Transport Bindings

Transport bindings move AIP messages without changing their semantic meaning. The action id, authenticated principal, policy decision, lifecycle, and error contract remain the same across HTTP, NATS, SSE, and WebSocket.

Choose a Binding

Binding	Direction	Best fit	Durable source of truth
Native HTTP	Request/reply	Service APIs and operational queries	Runtime store
SSE	Server to client	Ordered event and stream following	Runtime event log
WebSocket	Bidirectional	Low-latency multiplexed native envelopes	Runtime store and event log
Native NATS	Request/reply and publish	Brokered service routing and queue groups	Runtime store; broker durability is deployment-owned

Use a compatibility transport only when the client speaks that profile. MCP Streamable HTTP and A2A streaming have their own version and session rules even though they reuse HTTP and SSE primitives.

Native HTTP

The generic endpoint is POST /aip/v1/messages. Complete envelopes use the normative application/aip+json media type. Operational routes under /aip/v1 provide typed reads and commands for clients that do not need to construct every envelope manually.

The current daemon returns application/json from its Axum JSON routes. This known media-type conformance difference is tracked in Implementation Status.

See Native HTTP API for the complete route and query reference.

Server-Sent Events

Set follow=true on an event endpoint to receive text/event-stream:

curl --no-buffer --fail-with-body \
  -H "Authorization: Bearer $AIP_TOKEN" \
  "$AIP_URL/aip/v1/actions/$ACTION_ID/events?include_chunks=true&follow=true"

Native follow endpoints include:

• /aip/v1/events;
• /aip/v1/actions/{action_id}/events;
• /aip/v1/actions/{action_id}/chunks.

Each retained event has an id. Persist the last processed id and send it as Last-Event-ID after reconnect. An explicit query cursor takes precedence over the header. Consumers must tolerate replay and deduplicate by stable event identity.

SSE is delivery, not storage. Retention and replay depend on the configured runtime backend and policy.

Native WebSocket

Connect an authenticated WebSocket client to /aip/v1/ws. Each text frame contains exactly one JSON-encoded AIP envelope. Binary application frames are not part of the native profile.

The binding supports ping/pong liveness and session-aware multiplexing. A client must still persist action ids and recover through operational APIs after a disconnect. Receiving a terminal frame does not replace durable action and receipt reads when business settlement matters.

Apply the same native authentication and authorization policy used by HTTP. Bound frame size, connection count, idle time, and outbound buffering at the deployment edge.

Native NATS

The native NATS profile id is aip.native.nats.v1. Canonical request subjects use:

aip.v1.{trust_domain}.{service}.{version}.{message_type}

The service listener subscribes to the corresponding wildcard ending in >. Streaming subjects use:

aip.v1.{trust_domain}.{service}.{version}.stream.{correlation_id}

Payloads are JSON TransportMessage objects containing the native envelope and transport metadata. The daemon also accepts a raw native envelope for compatibility at this boundary and responds with a TransportMessage.

Enable the listener with:

cargo run -p aipd -- \
  --service-id agent:aipd:nats \
  --nats-url nats://nats.example.com:4222 \
  --nats-username aipd \
  --nats-password-file /run/secrets/nats-password \
  --nats-trust-domain production \
  --nats-service orchestration \
  --nats-version v1 \
  --nats-queue-group aipd-workers \
  --postgres-url "$AIP_POSTGRES_URL"

NATS account isolation, TLS, subject ACLs, JetStream policy, broker retention, and availability remain deployment responsibilities. Queue groups distribute requests; they do not replace AIP action leases or idempotency fencing.

Authentication Is Not Authorization

Every binding must establish a trusted principal before dispatch. Network reachability, a WebSocket upgrade, or permission to publish to a NATS subject does not authorize a capability. The gateway must still enforce scopes, tenant, delegation, approval, and transaction policy.

Do not derive identity from an untrusted envelope from field or caller-owned transport metadata.

Delivery and Retry Rules

• Retry only when the capability contract and error category permit it.
• Reuse the same idempotency key for an exact replay.
• Never replay an uncertain mutation merely because a transport timed out.
• Resume streams from retained cursors and accept duplicate delivery.
• Read the durable action or transaction after a transport interruption.

See Errors and Retry Decisions and Actions and Sessions.