Every field in the AGPEnvelope, every supported intent, and how signing and correlation actually work.
The A2A protocol, explained with envelopes
Every field in the AGPEnvelope, every supported intent, and how signing and correlation actually work.
A2A (Agent-to-Agent) is the wire format AGNT uses to let one agent talk to another. This is the deep dive: the exact envelope shape, the intents it supports, how signing works, and how two agents maintain conversational state across a short exchange.
Prerequisites
- Read the /guides/how-agnt-works overview first.
- Comfort with JSON, HMAC, and the idea of protocol versions.
A personal agent needs to ask a venue agent about availability, negotiate a time, and confirm. REST endpoints are a poor fit for that — the conversation has state, it is bidirectional, and it wants a stable shape so the receiver knows how to validate. Webhooks are one-way. A2A is the minimum protocol that covers a back-and-forth exchange between two agents with a clean retry and observability story.
Every A2A message is a single JSON object with eight fields. No more, no fewer.
json
{
"protocol": "agp/1",
"from_agent": "agnt_consumer_42",
"to": "agnt_venue_la_brisa",
"intent": "booking.search",
"payload": { "party_size": 4, "date": "2026-04-20", "time": "19:30" },
"agent_context": { "locale": "en", "tier": "pro" },
"ttl_ms": 15000,
"timestamp": "2026-04-11T10:22:03Z"
}protocol is the version string — the gateway rejects any envelope whose version it does not recognise. from_agent and to identify the sender and recipient. intent tells the gateway which handler to dispatch to. payload is the intent-specific body. agent_context is an optional block for stateful follow-ups — it is echoed back on responses so both sides can correlate. ttl_ms is the round-trip cap in milliseconds; the gateway enforces a hard 15-second ceiling. timestamp is ISO 8601.
In production the dispatch table contains four intents. network.ping is a health check with no side effects. venue.list asks a venue agent to enumerate bookable slots. booking.search looks for a specific date/time/party combination. booking.confirm creates a reservation on the network — it is the only metered intent on the Open Network.
The intent set is deliberately small. Adding a new intent is a three-step process: publish the extension spec, roll out server-side support, and announce the availability date. The gateway rejects any unknown intent with a typed error so clients never silently talk past the network.
Every envelope is signed with HMAC-SHA256 using the sender's signing key. The signature covers the concatenation of the canonical JSON body (keys sorted, no whitespace) and the timestamp. The receiver re-computes the HMAC and compares in constant time. Timestamps older than five minutes are rejected to prevent replay.
Signing keys are managed in the developer dashboard and can be rotated with a ten-minute overlap window — the same mechanism as webhook secrets.
A short exchange — search then confirm — correlates through the agent_context block. The initial envelope sets a context object; every response echoes it back. Both sides can also attach a correlation_id of their own choosing, which ClawPulse stamps into every log line for the exchange.
AGPEnvelopes are idempotent at the receiving side. Two envelopes with the same (from_agent, intent, timestamp) tuple are treated as a single event — safe to retry without duplicate effects.
A2A never exposes generic 500s. Every failure is a typed error: circuit_open, breaker_half_open_probe_failed, invalid_signature, unknown_intent, ttl_exceeded, venue_unreachable. The caller reads the error code and decides — retry, back off, or fall back to a public booking endpoint.
The gateway is responsible for making failures visible. Every envelope is logged with a request_id and a dispatch latency, and the global circuit-breaker state snapshot is attached to error responses so the caller knows why it failed without a dashboard round-trip.
Key terms
Next steps