Marona Rust SDK
Run Agents through one managed API, with structured output, local tools, Hub capabilities, streaming, realtime and A2A collaboration.
Install
Version 4.2.0. Package registry.
Rust 1.89+ with the bundled dependency lockfile. A2A servers require the a2a feature (enabled by default).
[]
= "4.2.0"
= { = "1", = ["macros", "rt-multi-thread"] }
= "1"
= "0.22"
Set MARONA_API_KEY in your backend environment. Never commit it, log it,
or embed a developer key in browser or mobile code. Use an exact accessible
marona/* model alias from Marona Platform.
Agent quickstart
Save as examples/agent_example.rs. Run without arguments for text, or with a real
PNG/JPEG path for document extraction. Use stable application user IDs and a
distinct session ID for each conversation.
use ;
use ;
use json;
async
Encode actual file bytes with standard Base64. Image and file blocks accept
raw Base64 in image_data / file_data, or complete matching data URLs.
Do not encode a path, encode twice, or send placeholder data. Remote URLs must
be reachable by the runtime. PDF, audio and realtime support depend on the
selected model; render PDF pages to images when native PDF is unavailable.
Structured output through Agent
The following fragment uses the authenticated client from the quickstart.
document_input is your text or document message input.
use ;
use json;
let agent = new
.model
.instructions
.output_schema.output_schema_strict;
let result = run.await?;
println!;
The explicit strict option asks the provider to enforce the supplied schema; the SDK also validates the final result before returning it. Strict mode requires a compatible model and schema. Declare every object property as required, use nullable values for optional fields, and set additionalProperties to false. Unsupported model capabilities or invalid output produce errors; they do not silently fall back to unstructured text. Input schemas, function tool schemas, guardrails, dynamic instructions and lifecycle hooks are also supported.
Apps and user connections
use AppsListOptions;
use json;
let page = marona.apps.list.await?;
let action = marona.apps.connect.await?;
// Complete any returned authorization_url before calling protected tools.
marona.apps.disconnect.await?;
Listing an App does not authorize its protected operations. Follow the returned
connection action for the end user. Use hub.connect to expose a scoped set of
App or Skill capabilities to an Agent; Apps authorization and Hub tool discovery
are separate operations.
A2A collaboration and serving
use ;
use json;
let peer = new?;
let agent = new.peer;
let server = from_agent?
.api_key?
.task_store;
let listener = bind.await?;
serve.await?;
Peers support Agent Card discovery, REST/JSON-RPC messages, task retrieval, cancellation, continuation and streamed task events. Servers persist task state. Use explicit credentials, restricted skills, HTTPS, and an appropriate durable task directory for production. Local JSON stores are for a single service instance; multi-instance deployments require coordinated task storage.
Serving requires the a2a feature and an application axum = "0.8" dependency for the shown hosting code.
Push notifications are not implemented.
Brain2Agent (B2A)
Native B2A v0.1 exchanges decoded semantic intent and agent responses. The
independent neural service owns signal decoding and feedback encoding, with
vendor-hosted MCP, HTTP or local plugin backends. Models and device drivers
are supplied by the interface provider. Configure Agent.protocols and connect with
Runner.connect, following the persistent realtime session lifecycle. These examples
read one captured signal file using your configured provider.
One configured protocol is selected automatically. With several configured protocols,
select by name (protocol="b2a" in Python, the corresponding option/overload in
other SDKs). Duplicate names and ambiguous selection are rejected. Implement
AgentProtocol to add another protocol without adding Agent properties. Existing
A2A peers and servers retain their agent-to-agent role; they are not automatically
converted into input protocols. Agent.b2a and B2ARunner remain compatibility APIs.
Save as examples/b2a_intent.rs:
use ;
use Value;
use Arc;
async
Single run with structured output
Save as examples/b2a_structured.rs. This opens a connection, decodes the signal, runs
the agent, validates the response, encodes feedback, and closes the connection.
use ;
use Deserialize;
use ;
use Arc;
async
Python returns the declared Pydantic model in result.output. Other SDKs validate
the declared JSON schema and expose their language's structured output representation.
Invalid output is rejected before encoding. Decoder abstention, required approval,
or failure does not become a successful typed result; use a persistent connection
for interactive clarification, approvals, and feedback delivery acknowledgments.
The SDK manages protocol messages, sequencing, event cursors, decoding and encoding.
Set B2A_CODEC_URL, B2A_NEURAL_TOKEN, B2A_OUTPUT_PROFILE, B2A_USER_ID and
B2A_SESSION_ID. Use B2A_CODEC_TRANSPORT=mcp or http. session_id identifies
an application conversation; each connection gets a separate native transport
session. The application authorizes processing before connecting; device and
protocol scope fields are supplied internally. Closing revokes those scopes.
Keep the session open to send more signals. Feedback events contain encoded
output; printing them does not deliver feedback. An interface driver acknowledges
presentation only after delivery. Failed or uncertain sends are never replayed
automatically. Native B2A supports server-hosted Hub tools and agent graphs;
SDK-local functions, callbacks and peer callbacks require server-hosted equivalents.
B2A connections automatically negotiate HTTP SSE with current runtimes. Sending a
signal returns when accepted; agent.delta events carry provisional text during
generation, followed by validated, encoded feedback. Keep consuming the session
stream for subsequent turns. The SDK handles transport and sequencing; no background
task or polling loop is required in application code. Heartbeats keep an active
stream alive without imposing a generation-wide timeout. Runner.run collects the
completed result and retains its configured run limit. Older runtimes fall back to
HTTP JSON and retained cursor events; the connection's streaming flag reports
whether live deltas are available.
See the repository's docs/b2a-protocol.md for the complete wire contract.
Neural provider connection options
B2ACodec supports optional overrides for provider tool names and HTTP paths.
Omit them when your provider uses the SDK defaults.
| Configuration | Applies to | SDK defaults |
|---|---|---|
decode_tool, encode_tool |
MCP tool names | decode, encode |
decode_path, encode_path |
HTTP endpoint paths | /v1/decode, /v1/encode |
For MCP, configure the provider's complete MCP endpoint URL and select the MCP transport. Tool names identify the provider's tools; HTTP path overrides do not affect MCP calls. These illustrative names must match your provider.
let neural_service = with_options?;
For HTTP, configure the provider base URL. Paths start with / and are appended
to that URL after removing its trailing slash. For example,
https://neural.example/api plus /neural/decode calls
https://neural.example/api/neural/decode. MCP tool names do not affect HTTP calls.
let neural_service = with_options?;
The SDK defaults to HTTP when transport is omitted; the B2A quickstarts above
explicitly select MCP. Pass the resulting service as the B2A provider in the same
Agent.protocols configuration. These options change routing only: request and
response schemas still follow the B2A provider contract. Implement B2AProvider
when a vendor needs payload translation. These are neural-service routes, separate
from Marona's /runtime/b2a/... endpoints.
Execution and errors
Use Runner::stream for streamed Agent events and
RealtimeRunner for a live session. Delegation and handoffs use explicit Agent
graphs. Set execution limits and validate permissions before tools with side
effects; cancellation cannot roll back an operation that has already executed.
Inspect the canonical error code, HTTP status, request ID and retry metadata. Correct invalid input and authorization errors before retrying. Use bounded retries for transient failures. Never include credentials or document content in error reports.
See Platform documentation for language
specific examples and migration guidance. These files are generated from
docs/client-sdk-guides.json; verify them with
python scripts/sync_client_sdk_docs.py --check.
Communication protocols are configured through protocols; Runner.connect opens persistent connections and Runner.run completes a single input. The 2.3 B2A entry points remain compatible.