# 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:

```toml
[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

```sh
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

```rust
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:

```sh
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](../spec/AIP-1.0.md).