Source: A2A Protocol Specification v1.0
The Agent2Agent protocol specification: Agent Cards, Tasks, Messages, Parts, Artifacts, nine task states, three protocol bindings, streaming, push notifications and security.
Contents
- What: the normative A2A specification (latest = 1.0.x; earlier 0.3.0, 0.2.6, 0.1.0)
- Author/publisher: A2A project (a2a-protocol.org), originally contributed by Google
- Date: v1.0 line, read 2026-11-14
- Original: A2A Protocol Specification
Summary
A2A defines how a client agent discovers a remote agent and delegates work to it without seeing its internals. The remote agent publishes an Agent Card; the client sends Messages made of Parts; long-running work is tracked as a Task with a state machine and produces Artifacts. The same abstract operations are bound to JSON-RPC, gRPC and HTTP+JSON/REST.
Key claims
- Versioning is Major.Minor via the
A2A-Versionheader (or?A2A-Version=query parameter); a missing or empty value is treated as 0.3; unsupported versions returnVersionNotSupportedError. - Agent Card required fields include
name,description,version,defaultInputModes/defaultOutputModes,skills(each withid,name,description,tags; optionalexamples, input/output modes) and an orderedsupportedInterfaceslist (each:url,protocolBinding=JSONRPC|GRPC|HTTP+JSON,protocolVersion, optionaltenant). The first interface is preferred. - Capabilities flags:
streaming,pushNotifications,extendedAgentCard. Security viasecuritySchemes/security: API key, HTTP auth, OAuth 2.0 (auth code, client credentials, device code), OpenID Connect, mTLS. - Discovery:
https://{domain}/.well-known/agent-card.json, registries, or direct configuration. An authenticatedGetExtendedAgentCardcan return a richer card. - Agent Cards may be signed with JWS (RFC 7515) over RFC 8785 (JCS) canonical JSON, excluding the
signaturesfield; clients should verify a signature before trusting a card. - Task:
id,contextId,status,artifacts,history,metadata.contextIdgroups related tasks into one conversation; a contextId/taskId mismatch must be rejected. - Message:
messageId,contextId,taskId,role(user/agent),parts,referenceTaskIds,extensions. Part holds exactly one oftext,rawbytes,url, ordata(JSON), plus optionalmediaType,filename,metadata. Artifact:artifactId,parts, optional name/description. - Task states: SUBMITTED, WORKING; interrupted INPUT_REQUIRED, AUTH_REQUIRED; terminal COMPLETED, FAILED, CANCELED, REJECTED (plus UNSPECIFIED).
- Operations: SendMessage, SendStreamingMessage, GetTask, ListTasks (cursor-paginated), CancelTask, SubscribeToTask, push-notification config CRUD, GetExtendedAgentCard.
- Streams carry
StreamResponseobjects in order; a message-only stream has one Message, a task stream starts with the Task then status/artifact updates and closes at a terminal state. JSON-RPC and REST stream over SSE (text/event-stream). REST paths includePOST /message:send,POST /message:stream,GET /tasks/{id},POST /tasks/{id}:cancel. - Push notifications: the server POSTs StreamResponse payloads to a client webhook; configs persist until completion or deletion; webhooks must be authenticated; agents should use 10–30 s request timeouts and may retry with exponential backoff; receivers return 2xx and should be idempotent.
SendMessageConfiguration.returnImmediately(default false = blocking) returns as soon as the task is created.- In-task auth: agent sets AUTH_REQUIRED and explains; credentials should arrive out of band; the state itself grants nothing.
- Errors include TaskNotFound, TaskNotCancelable, PushNotificationNotSupported, UnsupportedOperation, ContentTypeNotSupported, InvalidAgentResponse, VersionNotSupported.
- Production must use TLS (1.3+ recommended).