Skip to main content

Agent-to-Agent (A2A) Protocol Overview

The Linux Foundation Agent-to-Agent Protocol (A2A v1.0) is an open, vendor-neutral specification governing autonomous multi-agent communication, collaborative task execution, and real-time event distribution.

GoRoute AI Gateway implements an enterprise-grade A2A router and messaging hub, enabling independent agent systems (e.g., LangChain agents, AutoGen swarms, Claude Code, and autonomous background bots) to coordinate tasks securely with enterprise auth, audit trails, and multi-tenant isolation.

Client Agents GoRoute AI Gateway Hub Target Agent Network HTTP POST or JSON-RPC Events GET :subscribe SSE HTTP Webhook Push Initiator Agent A Client Bot B Dual Ingress Binding(HTTP+JSON & JSON-RPC 2.0) A2A Task Router Service Subscribe-First SSE Engine(Monotonic Event Sequences) Transactional Outbox Worker(DLQ & Exponential Backoff) Autonomous Worker Agent C Webhook Subscriber D

1. Dual Protocol Binding: HTTP+JSON and JSON-RPC 2.0​

To ensure compatibility across different software ecosystems, GoRoute AI Gateway exposes identical agent capabilities over two transport bindings:

1. HTTP+JSON REST Binding​

Idiomatic REST APIs designed for standard HTTP microservices and web clients:

OperationMethod & RouteDescription
Send MessagePOST /a2a/v1/agents/{slug}/messagesSubmits a message to an agent, initializing or continuing a task.
Get TaskGET /a2a/v1/agents/{slug}/tasks/{taskID}Retrieves current task status, artifacts, and execution state.
List TasksGET /a2a/v1/agents/{slug}/tasksLists active and historical tasks for the caller.
Cancel TaskPOST /a2a/v1/agents/{slug}/tasks/{taskID}:cancelSignals cancellation to an in-flight agent task.
Subscribe StreamGET /a2a/v1/agents/{slug}/tasks/{taskID}:subscribeOpens a real-time SSE stream of task events.

2. JSON-RPC 2.0 Binding​

Standardized RPC interface accessible on a single URL (POST /a2a/v1/agents/{slug}):

curl -X POST "http://localhost:8080/a2a/v1/agents/risk-analyst" \
-H "Authorization: Bearer sk-gw-client-key" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 101,
"method": "sendMessage",
"params": {
"message": {
"role": "user",
"content": "Evaluate quarterly exposure to semiconductor supply shocks."
}
}
}'

Supported JSON-RPC methods: sendMessage, getTask, listTasks, cancelTask, createPushConfig, getPushConfig, deletePushConfig.


2. Subscribe-First SSE Real-Time Streaming​

A common vulnerability in distributed SSE streaming is the "race window": if a client queries the database for past events and then connects to the live stream, any event emitted between the database read and the socket connection is permanently lost.

GoRoute AI Gateway implements the Subscribe-First SSE Protocol (internal/a2a/streams.go):

1. GET /tasks/{id}:subscribe?after_seq=4 2. Subscribe(gw:a2a:events:{id}) 3. HTTP 200 text/event-stream 4. ListEvents(taskID, seq > 4) 5. Historical Events (seq 5, 6) 6. SSE id: 5, id: 6 7. Live Event (seq 8) [Gap: seq 7 missing] 8. Fetch Missing Gap (seq 7) 9. Event 7 Payload 10. SSE id: 7 11. SSE id: 8 1. Subscribe to Redis FIRST 2. Backfill Historical Events 3. Gap Detection & Backfill Subscriber Client Gateway SSE Handler Redis Pub/Sub PostgreSQL (a2a_events)

Key Stream Resiliency Features:​

  1. Subscribe-First Sequencing: Connects to the Redis event channel gw:a2a:events:{taskID} before fetching database snapshots, buffering live events in a channel.
  2. Monotonic Event Sequencing: Every task event is assigned an auto-incrementing 64-bit integer sequence number (id: 1, id: 2, id: 3).
  3. Resumption via Last-Event-ID: If a subscriber disconnects, it reconnects with standard Last-Event-ID: <seq> or ?after_seq=<seq>. The gateway replays all missed events seamlessly.
  4. Gap Detection & Deduplication: If a live buffered event skips a sequence number, the gateway queries PostgreSQL to backfill the missing gap before delivering live events. Duplicate events already delivered during backfill are discarded.
  5. Periodic Keep-Alive: Emits comment frames (: keepalive\n\n) every 15 seconds to prevent intermediate proxy timeout disconnects.

3. Transactional Outbox Pattern & Webhook Delivery​

For asynchronous event delivery to external systems, the gateway implements a Transactional Outbox Worker (internal/a2a/outbox_worker.go).

Background Outbox Worker Atomic Transaction Yes No (under 5 retries) No (max retries exceeded) Agent Task Mutation PostgreSQL1. Task Event2. a2a_outbox_events Status: SENT Exponential Backoff100ms * 2^attempt Status: DEAD_LETTER (DLQ) Claim Pending Batches (50 events) HTTP POST with Idempotency-Key Delivery Success?

Operational Guarantees:​

  • Zero-Loss Transactions: The task status mutation and the outbound webhook event are written within the same database transaction. Events can never be lost due to process crashes.
  • Idempotency & Attribution Headers: Outbound webhook POSTs carry strict idempotency and audit metadata:
    POST /webhooks/agent-events HTTP/1.1
    Host: client-service.acme.com
    Content-Type: application/json
    Idempotency-Key: evt_01928374-abcd-ef01
    X-Gateway-Event-Id: evt_01928374-abcd-ef01
    X-Gateway-Task-Id: task_98765432-feed-dead
    X-Gateway-Delivery-Attempt: 1
  • Exponential Backoff: Failed deliveries back off exponentially (100ms * 2^attempt).
  • Dead-Letter Queue (DLQ): After 5 consecutive failures (a2a.max_push_retries: 5), the event status transitions to dead_letter for operator inspection.
  • Emergency Kill-Switch: Webhook delivery can be deactivated instantly per agent or globally by deleting or toggling push notification configs.