Protocol surfaces
A2A
Experimental A2A v1.0.0: Agent Card discovery and JSON-RPC SendMessage at /a2a.
ExperimentalA2A v1.0.0, off unless
protocols.a2a.enabled is true.| Binding | JSON-RPC 2.0 over HTTPS |
| Method | SendMessage (not the legacy message/send) |
| Version header | A2A-Version: 1.0, required |
| Agent Card | GET /.well-known/agent-card.json |
| Default mount | /a2a |
| Streaming, task persistence, push notifications | unsupported |
Agent Card
GET
/.well-known/agent-card.jsonpublicResources exposed with expose: [a2a] become skills: skill id = resource id; a paid skill is tagged paid and names its price. Core A2A v1.0 skills have no input schema field, so input schemas are not embedded — read them from GET /api/resources.
SendMessage
POST
/a2apayment{
"jsonrpc": "2.0",
"id": "1",
"method": "SendMessage",
"params": {
"message": {
"role": "ROLE_USER",
"messageId": "msg-1",
"parts": [
{
"data": { "resource": "market_report", "input": { "_payment": "<base64 x402 proof>" } },
"mediaType": "application/json"
}
]
}
}
}One message, one data part naming the resource and its input. Text, file, bytes and URL parts, multi-part messages, roles other than ROLE_USER, and task or context continuation are refused.
Results
| Outcome | Task state | Artifact data |
|---|---|---|
| delivered | TASK_STATE_COMPLETED | the merchant response (non-objects wrapped as { value }); delivery summary in agent-commerce/delivery metadata |
| payment required | TASK_STATE_FAILED | the payment envelope |
| domain failure | TASK_STATE_FAILED | the error envelope |
Payment required is terminal: there is no task store, so the buyer sends a new message carrying the proof.
JSON-RPC errors
Reserved for requests that are malformed or unsupported as A2A — never for commerce outcomes.
| Code | Meaning |
|---|---|
-32700 | bad JSON |
-32600 | bad request object |
-32601 | unknown method |
-32602 | bad params or envelope |
-32004 | unsupported operation, including a missing or unsupported A2A-Version |