HTTP+JSON binding

The HTTP+JSON binding is one of A2A’s three standard protocol bindings, and it maps each A2A operation to a resource URL and a standard HTTP method, with JSON bodies that mirror the Protocol Buffer definitions.

Declaring it. An Agent Card lists the binding in a supportedInterfaces entry with "protocolBinding": "HTTP+JSON". The specification also calls it the HTTP+JSON/REST binding.

Operations. The paths come from section 11.3 and the HTTP annotations in a2a.proto:

Operation	Request
Send message	POST /message:send
Send streaming message	POST /message:stream
Get task	GET /tasks/{id}
List tasks	GET /tasks
Cancel task	POST /tasks/{id}:cancel
Subscribe to task	POST /tasks/{id}:subscribe in section 11.3; the proto annotates it as GET
Push notification configs	POST, GET and DELETE on /tasks/{id}/pushNotificationConfigs
Extended Agent Card	GET /extendedAgentCard

GET and DELETE requests put parameters in the path or query string with camelCase names, for example GET /tasks?contextId=ctx-7&status=TASK_STATE_WORKING. Bodies should use the application/a2a+json media type and follow ProtoJSON. When an interface declares a tenant, the proto’s additional bindings put it as the first path segment.

Errors. Errors use the google.rpc.Status JSON shape. For A2A-specific errors the details array must include a google.rpc.ErrorInfo whose reason names the error and whose domain is a2a-protocol.org. The HTTP status comes from section 5.4: 404 for a missing task, 500 for an invalid agent response, and 400 for the other A2A errors. Based on the section 11.6 example:

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "The specified task ID does not exist or is not accessible",
    "details": [
      {"@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "TASK_NOT_FOUND", "domain": "a2a-protocol.org"}
    ]
  }
}

Streaming and headers. Streaming responses use Server-Sent Events, and each data: line holds one StreamResponse object. The A2A-Version and A2A-Extensions service parameters travel as HTTP headers.

Neighbouring terms. The JSON-RPC binding sends every operation as a named method to one URL, and the gRPC binding uses the proto service directly.