A2A Gateway API

Use the A2A Gateway API when one agent needs to delegate work to a registered peer under workspace policy, approval, loop, identity, and audit controls.

Enterprise only

Not included in DVARA Open Source.

Choose an operation

Endpoint	Purpose
GET /a2a/{agentId}/.well-known/agent-card.json	Read the governed Agent Card
POST /a2a/{agentId}/message:send	Send a message and wait for the result
POST /a2a/{agentId}/message:stream	Send a message and stream task updates
POST /a2a/{agentId}/tasks:get	Read one task
POST /a2a/{agentId}/tasks:list	List tasks
POST /a2a/{agentId}/tasks:cancel	Cancel a task
POST /a2a/{agentId}/tasks:resubscribe	Resume task event streaming
POST /a2a/{agentId}/pushConfig:set	Create or replace push configuration
POST /a2a/{agentId}/pushConfig:get	Read push configuration
POST /a2a/{agentId}/pushConfig:list	List push configurations
POST /a2a/{agentId}/pushConfig:delete	Remove push configuration
POST /a2a/{agentId}/push:notify/{callback}	Receive a governed push notification from the peer

Every request uses the target's registered agentId. DVARA resolves the workspace from the bearer API key before it looks up the target.

The Gateway implements the A2A v0.3 JSON-RPC method names shown above. A v1.0-only peer uses different method names and is not compatible with this contract in 1.8.

Authenticate and scope the call

Workspace-facing A2A operations require a DVARA workspace API key:

Authorization: Bearer <your-api-key>

Scope	Operations
a2a:read	tasks:get, tasks:list, tasks:resubscribe, and push-configuration reads
a2a:send	message:send, message:stream, tasks:cancel, and push-configuration writes or deletion

An unscoped API key is unrestricted. Agent Card discovery still requires a valid workspace key, but it is not narrowed by an A2A scope in 1.8.

Send a governed message

Replace the host, target agent ID, and workspace API key:

curl --silent https://<dvara-host>/a2a/<agent-id>/message:send \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": "hop-1042",
    "method": "message/send",
    "params": {
      "metadata": {"skill": "summarize"},
      "message": {
        "role": "user",
        "parts": [
          {"kind": "text", "text": "Summarize claim CLM-1042 for review."}
        ]
      }
    }
  }'

A completed peer call returns an A2A message or task inside the JSON-RPC envelope:

{
  "jsonrpc": "2.0",
  "id": "hop-1042",
  "result": {
    "task": {
      "id": "task-7f12"
    }
  }
}

If policy denies the hop, DVARA returns 403 and does not call the peer.

Open Agents → A2A Hops to inspect the source, target, decision, status, and latency. The same hop writes intent and result or denial evidence to Governance → Audit, joined by its trace information.

Stream a message or resume a task

message:stream and tasks:resubscribe return Server-Sent Events. They use the same authentication and governance checks as their unary forms. Streaming is on by default; when a2a.streaming.enabled=false, either route returns one SSE error event with a2a_streaming_disabled.

A governance refusal or upstream failure is delivered as one SSE error event. If the peer fails or stalls after the stream opens, DVARA sends an error event and does not send [DONE]. Treat that event as the final outcome rather than a partial success.

Discover the governed Agent Card

GET /a2a/{agentId}/.well-known/agent-card.json returns the card JSON directly, not a JSON-RPC envelope. DVARA resolves the agent inside the caller's workspace, filters its skills with that workspace's allow-list, and serves the cached card until its discovery TTL expires.

Add ?refresh=true to fetch the peer again immediately. If the agent has a pinned public key, DVARA verifies the card signature and reports the trust state in x-dvara-signature-trust. A fetch failure uses a valid cached card when one is available; otherwise it returns 502 a2a_card_unavailable.

Govern push notifications

The pushConfig:* routes manage the peer's push-notification configuration. pushConfig:set validates the workspace webhook address and refuses loopback, private, cloud-metadata, and plain HTTP targets before contacting the peer.

When a2a.push.callback-base-url is configured, DVARA replaces the workspace webhook details sent to the peer with a sealed Gateway callback. The peer posts updates to:

POST /a2a/{agentId}/push:notify/{callback}
X-A2A-Notification-Token: <notification-token>

The peer callback takes no DVARA API key. The sealed path and notification token identify the expected agent and task; an agent with a pinned key must also send a signed bearer JWT. DVARA checks and PII-scans the notification, records it, and then sends it to the workspace webhook. Duplicate notifications are accepted without a second delivery.

If the Gateway has no public callback base URL, governed push configuration is refused with 503 a2a_push_not_available, unless the workspace explicitly uses direct delivery. Direct delivery sends the workspace webhook to the peer and does not put the Gateway on the notification path.

Apply the request and response limits

Boundary	Default	Failure
Text across an outbound message:send or message:stream message	50,000 characters	413 a2a_message_too_large
Whole peer answer, task response, or Agent Card	16 MiB	502 a2a_response_too_large; Agent Card discovery uses a2a_card_unavailable when no cached card can be served
message:stream or tasks:resubscribe stream	64 MiB	The stream ends with an SSE error event
Incoming governed push-notification body	1 MiB	413 a2a_push_too_large

The message limit runs before policy and PII scanning. Response limits cover the bytes DVARA reads from a peer. Operators can change the fleet defaults; the response limits can also be set per workspace.

Diagnose a failed call

A missing, expired, or revoked workspace key returns 401. A key without the required A2A scope returns 403. A target outside the caller's workspace is not exposed. A message or task refusal uses a JSON-RPC error envelope and includes the request trace ID. Streaming failures use the SSE form described above; Agent Card discovery returns an ordinary HTTP JSON error.

Peer discovery, signature, credential, policy, approval, loop, size, and transport failures use distinct error codes so you can separate configuration failures from governed denials. See Error handling for the status and code table.

For delegation chains, approval behavior, streaming, push callbacks, and Agent Card trust, continue with Govern agent-to-agent calls with the A2A Gateway.