Rust SDK

The akshi-sdk crate is the primary interface for agents running inside the Akshi WASM sandbox. Add it to your agent’s Cargo.toml:

[dependencies]
akshi-sdk = "0.1"

Buffer safety: Many SDK functions return &'static str slices backed by a shared 1 MB host buffer. The data is only valid until the next SDK call. If you need to store a value, copy it immediately with .to_string().

All fallible functions return Result<T, akshi_sdk::Error> where Error is:

#![allow(unused)]
fn main() {
pub enum Error {
    HostUnavailable, // host function not available
    CallFailed,      // host call returned an error
}
}

Database

db_query

#![allow(unused)]
fn main() {
pub fn db_query(sql: &str) -> Result<&'static str, Error>
}

Execute a read-only SQL query against the agent’s sandboxed SQLite database. Returns the result set as a JSON array string.

#![allow(unused)]
fn main() {
let rows = akshi_sdk::db_query("SELECT * FROM events LIMIT 10")?;
}

db_exec

#![allow(unused)]
fn main() {
pub fn db_exec(sql: &str) -> Result<(), Error>
}

Execute a write SQL statement (INSERT, UPDATE, DELETE, CREATE TABLE, etc.).

#![allow(unused)]
fn main() {
akshi_sdk::db_exec("INSERT INTO events (msg) VALUES ('hello')")?;
}

Journal

journal_insert

#![allow(unused)]
fn main() {
pub fn journal_insert(content: &str, embedding_json: &str) -> Result<i64, Error>
}

Insert one memory entry into the agent journal. embedding_json must be a JSON float array (e.g., "[0.1,0.2,0.3]"). Returns the inserted row ID.

#![allow(unused)]
fn main() {
let row_id = akshi_sdk::journal_insert(
    "scan complete: 3 findings",
    "[0.12, -0.34, 0.56]",
)?;
}

journal_insert_with_provenance

#![allow(unused)]
fn main() {
pub fn journal_insert_with_provenance(
    content: &str,
    embedding_json: &str,
    provenance: JournalProvenance<'_>,
) -> Result<i64, Error>
}

Insert a journal entry with additive provenance fields for research flows.

#![allow(unused)]
fn main() {
use akshi_sdk::JournalProvenance;

let prov = JournalProvenance {
    source_url: "https://example.com/article",
    fetcher_did: "did:key:z6Mk...",
    source_hash: "sha256:abc123",
};
let row_id = akshi_sdk::journal_insert_with_provenance(
    "Article summary...",
    "[0.1, 0.2]",
    prov,
)?;
}

journal_search

#![allow(unused)]
fn main() {
pub fn journal_search(embedding_json: &str, limit: u32) -> Result<&'static str, Error>
}

Search journal memories by vector similarity. Returns a JSON array of rows sorted by ascending distance.

#![allow(unused)]
fn main() {
let results = akshi_sdk::journal_search("[0.12, -0.34, 0.56]", 5)?;
}

journal_search_hybrid

#![allow(unused)]
fn main() {
pub fn journal_search_hybrid(
    query_text: &str,
    embedding_json: &str,
    limit: u32,
) -> Result<&'static str, Error>
}

Search journal memories with hybrid fusion (FTS + vector + decay/importance controls).

#![allow(unused)]
fn main() {
let results = akshi_sdk::journal_search_hybrid(
    "security findings",
    "[0.12, -0.34, 0.56]",
    10,
)?;
}

Memory

memory_query

#![allow(unused)]
fn main() {
pub fn memory_query(query: &str, top_k: u32) -> Result<&'static str, Error>
}

Semantic memory query: search journal entries by meaning. Automatically generates embeddings from the query text and returns the top-k most relevant entries as a JSON array sorted by relevance.

#![allow(unused)]
fn main() {
let entries = akshi_sdk::memory_query("recent security incidents", 5)?;
}

MCP (Model Context Protocol)

mcp_call

#![allow(unused)]
fn main() {
pub fn mcp_call(tool: &str, args_json: &str) -> Result<&'static str, Error>
}

Invoke an MCP tool by name with a JSON arguments string. The runtime routes the call to the appropriate connected MCP server.

#![allow(unused)]
fn main() {
let result = akshi_sdk::mcp_call(
    "read_file",
    r#"{"path":"/tmp/data.txt"}"#,
)?;
}

HTTP

http_fetch

#![allow(unused)]
fn main() {
pub fn http_fetch(url: &str, body: &str) -> Result<&'static str, Error>
}

Fetch a URL through the secrets broker. The URL must be on the agent’s endpoint allowlist. Pass an empty string for body on GET requests.

#![allow(unused)]
fn main() {
let resp = akshi_sdk::http_fetch("https://api.example.com/data", "")?;
}

http_fetch_with_intent

#![allow(unused)]
fn main() {
pub fn http_fetch_with_intent(url: &str, body: &str, intent: &str) -> Result<&'static str, Error>
}

Fetch a URL with an explicit declared intent. Required when the agent has an intent_policy.outbound_http configured.

#![allow(unused)]
fn main() {
let resp = akshi_sdk::http_fetch_with_intent(
    "https://api.example.com/data",
    "",
    "read_public_api",
)?;
}

Inference

infer

#![allow(unused)]
fn main() {
pub fn infer(prompt: &str) -> Result<&'static str, Error>
}

Send a prompt through the inference router (local Ollama / cloud fallback). The router selects the model based on the active route profile.

#![allow(unused)]
fn main() {
let answer = akshi_sdk::infer("Summarize these findings.")?;
}

parse_llm_response

#![allow(unused)]
fn main() {
pub fn parse_llm_response(json: &str) -> &str
}

Extract text content from an LLM JSON response. Supports Ollama ("response":"...") and OpenAI/OpenRouter ("content":"...") formats. Falls back to the raw input if parsing fails.

#![allow(unused)]
fn main() {
let raw = akshi_sdk::infer("Hello")?;
let text = akshi_sdk::parse_llm_response(raw);
}

Config

get_config

#![allow(unused)]
fn main() {
pub fn get_config(key: &str) -> Result<&'static str, Error>
}

Read a value by key from the agent’s TOML configuration section (the extra fields in the [[agents]] entry).

#![allow(unused)]
fn main() {
let interval = akshi_sdk::get_config("scan_interval")?;
}

Scraping

scrape_to_markdown

#![allow(unused)]
fn main() {
pub fn scrape_to_markdown(html: &str) -> Result<&'static str, Error>
}

Reduce raw HTML into cleaner markdown on the host side.

#![allow(unused)]
fn main() {
let md = akshi_sdk::scrape_to_markdown("<h1>Title</h1><p>Content</p>")?;
}

A2A (Agent-to-Agent)

a2a_send

#![allow(unused)]
fn main() {
pub fn a2a_send(target_agent: &str, payload_json: &str) -> Result<&'static str, Error>
}

Send a task to another agent by name via the local A2A protocol. Returns the created task ID.

#![allow(unused)]
fn main() {
let task_id = akshi_sdk::a2a_send("analyzer", r#"{"action":"scan"}"#)?;
}

a2a_recv

#![allow(unused)]
fn main() {
pub fn a2a_recv() -> Result<Option<&'static str>, Error>
}

Receive one inbound A2A task for the current agent. Returns Ok(None) when no task is available.

#![allow(unused)]
fn main() {
if let Some(task_json) = akshi_sdk::a2a_recv()? {
    // process task
}
}

WebSocket

WebSocket connections use an opaque handle (WsHandle = i64) returned by ws_connect. All WebSocket URLs must be on the agent’s endpoint allowlist.

ws_connect

#![allow(unused)]
fn main() {
pub fn ws_connect(url: &str) -> Result<WsHandle, Error>
}

Open a WebSocket connection. Returns a handle for subsequent calls.

#![allow(unused)]
fn main() {
let handle = akshi_sdk::ws_connect("wss://stream.example.com/ws")?;
}

ws_send

#![allow(unused)]
fn main() {
pub fn ws_send(handle: WsHandle, data: &str) -> Result<(), Error>
}

Send a text frame on an open WebSocket connection.

#![allow(unused)]
fn main() {
akshi_sdk::ws_send(handle, r#"{"subscribe":"events"}"#)?;
}

ws_recv

#![allow(unused)]
fn main() {
pub fn ws_recv(handle: WsHandle) -> Result<Option<&'static str>, Error>
}

Non-blocking receive: returns the next buffered frame or None.

#![allow(unused)]
fn main() {
if let Some(msg) = akshi_sdk::ws_recv(handle)? {
    // process message
}
}

ws_close

#![allow(unused)]
fn main() {
pub fn ws_close(handle: WsHandle) -> Result<(), Error>
}

Close a WebSocket connection and release the handle.

#![allow(unused)]
fn main() {
akshi_sdk::ws_close(handle)?;
}

Utility

log

#![allow(unused)]
fn main() {
pub fn log(msg: &str)
}

Log a message to stdout (visible in terminal and dashboard event stream).

#![allow(unused)]
fn main() {
akshi_sdk::log("Agent started successfully");
}

fuel_remaining

#![allow(unused)]
fn main() {
pub fn fuel_remaining() -> Option<u64>
}

Query the remaining fuel budget for this agent execution. Returns None if fuel metering is unavailable.

#![allow(unused)]
fn main() {
if let Some(fuel) = akshi_sdk::fuel_remaining() {
    akshi_sdk::log(&format!("Fuel remaining: {fuel}"));
}
}