Use the Rust SDK

The aip crate is the public Rust facade. It always re-exports the semantic core and exposes runtime, gateway, transport, profile, storage, conformance, and connector modules through explicit Cargo features.

Use the facade when embedding AIP in a Rust process. Use aipd when the protocol boundary should run as a separately deployed service.

Choose Features Deliberately

The default feature set contains the semantic model only. Enable the smallest surface your application needs. From a source checkout, use a workspace or path dependency:

[dependencies]
aip = { path = "../agent-interoperability-protocol/crates/aip", features = ["gateway"] }

Use a registry version only after the release is published to that registry. The local Git tag and workspace version do not by themselves prove that a public package exists.

full enables every workspace integration and is appropriate for examples and conformance, not as an automatic production default.

Common features include:

Feature	Adds
schema	Generated JSON Schema registry
auth	Authentication and authorization primitives
runtime	Durable lifecycle services and handlers
gateway	Native dispatch and connector/profile composition
storage-postgres	PostgreSQL runtime backend
mcp-server	AIP-backed MCP server
mcp-client	Outbound MCP bridge
transport-http	Native HTTP codec and status mapping
transport-nats	Native NATS request/reply
connector	Frozen connector SDK traits
testkit	Deterministic construction helpers for tests

Run the Minimal Embedded Example

cargo run -p aip --example minimal-agent --features full

The example creates an in-process gateway, registers one echo handler, sends a native action, and prints the response. Its implementation source is examples/minimal-agent/main.rs in the AIP workspace.

Build an Envelope

use aip::{
    Action, CapabilityId, Envelope, MessageBody, Principal, PrincipalId,
    PrincipalKind,
};
use serde_json::json;

fn build_envelope() -> Result<Envelope, Box<dyn std::error::Error>> {
    let action = Action::new(
        CapabilityId::parse("cap:example:echo")?,
        json!({ "message": "hello" }),
    );
    let mut envelope = Envelope::new(MessageBody::Action(Box::new(action)));
    envelope.from = Some(Principal::new(
        PrincipalId::parse("agent:example-client")?,
        PrincipalKind::Agent,
    ));
    Ok(envelope)
}

Treat Envelope.from as a claim until a trusted transport or signer binds it. Network code must use the gateway’s authenticated or verified entrypoints after transport authentication.

Embed a Gateway

The gateway needs an admitted manifest and a handler for every callable capability. Gateway::local_development_with_handlers is intended for local tests and examples. Production embedders should construct explicit gateway policy, runtime storage, identity resolvers, callback policy, and handlers.

Do not publish a capability before its handler and implementation-support matrix are admitted. Gateway construction fails closed on a manifest/handler mismatch.

Error Handling

Public fallible APIs return typed errors. At a protocol boundary, map failures to ProtocolError without exposing raw provider payloads or secrets. A ConnectorFailure retains retry safety, uncertain outcome, provider correlation, and operation context for the runtime.

Do not branch automation on rendered Display text. Use typed variants and stable protocol codes.

API Documentation

Build local Rust documentation with all features:

cargo doc -p aip --all-features --no-deps --open

Feature-gated modules are absent from Rustdoc unless their feature is enabled. For protocol behavior, Rustdoc supplements but does not replace the AIP 1.0 Specification.