Overview - A2A Protocol

Agent2Agent (A2A) Protocol Specification (Release Candidate v1.0)¶

Previous Versions

See Release Notes for changes made between versions.

1. Introduction¶

The Agent2Agent (A2A) Protocol is an open standard designed to facilitate communication and interoperability between independent, potentially opaque AI agent systems. In an ecosystem where agents might be built using different frameworks, languages, or by different vendors, A2A provides a common language and interaction model.

This document provides the detailed technical specification for the A2A protocol. Its primary goal is to enable agents to:

1.1. Key Goals of A2A¶

1.2. Guiding Principles¶

For a broader understanding of A2A's purpose and benefits, see What is A2A?.

1.3. Specification Structure¶

This specification is organized into three distinct layers that work together to provide a complete protocol definition:

Layer 1: Canonical Data Model defines the core data structures and message formats that all A2A implementations must understand. These are protocol agnostic definitions expressed as Protocol Buffer messages.

Layer 2: Abstract Operations describes the fundamental capabilities and behaviors that A2A agents must support, independent of how they are exposed over specific protocols.

Layer 3: Protocol Bindings provides concrete mappings of the abstract operations and data structures to specific protocol bindings (JSON-RPC, gRPC, HTTP/REST), including method names, endpoint patterns, and protocol-specific behaviors.

This layered approach ensures that:

1.4 Normative Content¶

In addition to the protocol requirements defined in this document, the file spec/a2a.proto is the single authoritative normative definition of all protocol data objects and request/response messages. A generated JSON artifact (spec/a2a.json, produced at build time and not committed) MAY be published for convenience to tooling and the website, but it is a non-normative build artifact. SDK language bindings, schemas, and any other derived forms MUST be regenerated from the proto (directly or via code generation) rather than edited manually.

Change Control and Deprecation Lifecycle:

Automated Generation:

The documentation build generates specification/json/a2a.json on-the-fly (the file is not tracked in source control). Future improvements may publish an OpenAPI v3 + JSON Schema bundle for enhanced tooling.

Rationale:

Centering the proto file as the normative source ensures protocol neutrality, reduces specification drift, and provides a deterministic evolution path for the ecosystem.

2. Terminology¶

2.1. Requirements Language¶

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2.2. Core Concepts¶

A2A revolves around several key concepts. For detailed explanations, please refer to the Key Concepts guide.

3. A2A Protocol Operations¶

This section describes the core operations of the A2A protocol in a binding-independent manner. These operations define the fundamental capabilities that all A2A implementations must support, regardless of the underlying binding mechanism.

3.1. Core Operations¶

The following operations define the fundamental capabilities that all A2A implementations must support, independent of the specific protocol binding used. For a quick reference mapping of these operations to protocol-specific method names and endpoints, see Section 5.3 (Method Mapping Reference). For detailed protocol-specific implementation details, see:

3.1.1. Send Message¶

The primary operation for initiating agent interactions. Clients send a message to an agent and receive either a task that tracks the processing or a direct response message.

Inputs:

Outputs:

Errors:

Behavior:

The agent MAY create a new Task to process the provided message asynchronously or MAY return a direct Message response for simple interactions. The operation MUST return immediately with either task information or response message. Task processing MAY continue asynchronously after the response when a Task is returned.

3.1.2. Send Streaming Message¶

Similar to Send Message but with real-time streaming of updates during processing.

Inputs:

Outputs:

Errors:

Behavior:

The operation MUST establish a streaming connection for real-time updates. The stream MUST follow one of these patterns:

Message-only stream: If the agent returns a Message, the stream MUST contain exactly one Message object and then close immediately. No task tracking or updates are provided.

Task lifecycle stream: If the agent returns a Task, the stream MUST begin with the Task object, followed by zero or more TaskStatusUpdateEvent or TaskArtifactUpdateEvent objects. The stream MUST close when the task reaches a terminal state (e.g. completed, failed, canceled, rejected).

The agent MAY return a Task for complex processing with status/artifact updates or MAY return a Message for direct streaming responses without task overhead. The implementation MUST provide immediate feedback on progress and intermediate results.

3.1.3. Get Task¶

Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with message/send, or for fetching the final state of a task after being notified via a push notification or after a stream has ended.

Inputs:

Represents a request for the GetTask method.

See History Length Semantics for details about historyLength.

Outputs:

Errors:

3.1.4. List Tasks¶

Retrieves a list of tasks with optional filtering and pagination capabilities. This method allows clients to discover and manage multiple tasks across different contexts or with specific status criteria.

Inputs:

Parameters for listing tasks with optional filtering criteria.

When includeArtifacts is false (the default), the artifacts field MUST be omitted entirely from each Task object in the response. The field should not be present as an empty array or null value. When includeArtifacts is true, the artifacts field should be included with its actual content (which may be an empty array if the task has no artifacts).

Outputs:

Result object for ListTasks method containing an array of tasks and pagination information.

Note on nextPageToken: The nextPageToken field MUST always be present in the response. When there are no more results to retrieve (i.e., this is the final page), the field MUST be set to an empty string (""). Clients should check for an empty string to determine if more pages are available.

Errors:

None specific to this operation beyond standard protocol errors.

Behavior:

The operation MUST return only tasks visible to the authenticated client and MUST use cursor-based pagination for performance and consistency. Tasks MUST be sorted by last update time in descending order. Implementations MUST implement appropriate authorization scoping to ensure clients can only access authorized tasks. See Section 13.1 Data Access and Authorization Scoping for detailed security requirements.

Pagination Strategy:

This method uses cursor-based pagination (via pageToken/nextPageToken) rather than offset-based pagination for better performance and consistency, especially with large datasets. Cursor-based pagination avoids the "deep pagination problem" where skipping large numbers of records becomes inefficient for databases. This approach is consistent with the gRPC specification, which also uses cursor-based pagination (page_token/next_page_token).

Ordering:

Implementations MUST return tasks sorted by their status timestamp time in descending order (most recently updated tasks first). This ensures consistent pagination and allows clients to efficiently monitor recent task activity.

3.1.5. Cancel Task¶

Requests the cancellation of an ongoing task. The server will attempt to cancel the task, but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage).

Inputs:

Represents a request for the CancelTask method.

Outputs:

Errors:

Behavior:

The operation attempts to cancel the specified task and returns its updated state.

3.1.6. Subscribe to Task¶

Establishes a streaming connection to receive updates for an existing task.

Inputs:

Outputs:

Errors:

Behavior:

The operation enables real-time monitoring of task progress and can be used with any task that is not in a terminal state. The stream MUST terminate when the task reaches a terminal state (completed, failed, canceled, or rejected).

The operation MUST return a Task object as the first event in the stream, representing the current state of the task at the time of subscription. This prevents a potential loss of information between a call to GetTask and calling SubscribeToTask.

3.1.7. Create Push Notification Config¶

Creates a push notification configuration for a task to receive asynchronous updates via webhook.

Inputs:

Represents a request for the CreateTaskPushNotificationConfig method.

Outputs:

Errors:

Behavior:

The operation MUST establish a webhook endpoint for task update notifications. When task updates occur, the agent will send HTTP POST requests to the configured webhook URL with StreamResponse payloads (see Push Notification Payload for details). This operation is only available if the agent supports push notifications capability. The configuration MUST persist until task completion or explicit deletion.

3.1.8. Get Push Notification Config¶

Retrieves an existing push notification configuration for a task.

Inputs:

Outputs:

Errors:

Behavior:

The operation MUST return configuration details including webhook URL and notification settings. The operation MUST fail if the configuration does not exist or the client lacks access.

3.1.9. List Push Notification Configs¶

Retrieves all push notification configurations for a task.

Inputs:

Outputs:

Represents a successful response for the ListTaskPushNotificationConfig method.

Errors:

Behavior:

The operation MUST return all active push notification configurations for the specified task and MAY support pagination for tasks with many configurations.

3.1.10. Delete Push Notification Config¶

Removes a push notification configuration for a task.

Inputs:

Represents a request for the DeleteTaskPushNotificationConfig method.

Outputs:

Errors:

Behavior:

The operation MUST permanently remove the specified push notification configuration. No further notifications will be sent to the configured webhook after deletion. This operation MUST be idempotent - multiple deletions of the same config have the same effect.

3.1.11. Get Extended Agent Card¶

Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if AgentCard.capabilities.extendedAgentCard is true.

Inputs:

Outputs:

Errors:

Behavior:

For detailed security guidance on extended agent cards, see Section 13.3 Extended Agent Card Access Control.

3.2. Operation Parameter Objects¶

This section defines common parameter objects used across multiple operations.

3.2.1. SendMessageRequest¶

Represents a request for the SendMessage method.

3.2.2. SendMessageConfiguration¶

Configuration of a send message request.

Blocking vs Non-Blocking Execution:

The blocking field in SendMessageConfiguration controls whether the operation waits for task completion:

Blocking (blocking: true): The operation MUST wait until the task reaches a terminal state (completed, failed, canceled, rejected) or an interrupted state (input_required, auth_required) before returning. The response MUST include the current task state with all artifacts and status information.

Non-Blocking (blocking: false): The operation MUST return immediately after creating the task, even if processing is still in progress. The returned task will have an in-progress state (e.g., working, input_required). It is the caller's responsibility to poll for updates using Get Task, subscribe via Subscribe to Task, or receive updates via push notifications.

The blocking field has no effect:

3.2.3. Stream Response¶

A wrapper object used in streaming operations to encapsulate different types of response data.

Note: A StreamResponse MUST contain exactly one of the following: task, message, statusUpdate, artifactUpdate

This wrapper allows streaming endpoints to return different types of updates through a single response stream while maintaining type safety.

3.2.4. History Length Semantics¶

The historyLength parameter appears in multiple operations and controls how much task history is returned in responses. This parameter follows consistent semantics across all operations:

3.2.5. Metadata¶

A flexible key-value map for passing additional context or parameters with operations. Metadata keys and are strings and values can be any valid value that can be represented in JSON. Extensions can be used to strongly type metadata values for specific use cases.

3.2.6 Service Parameters¶

A key-value map for passing horizontally applicable context or parameters with case-insensitive string keys and case-sensitive string values. The transmission mechanism for these service parameter key-value pairs is defined by the specific protocol binding (e.g., HTTP headers for HTTP-based bindings, gRPC metadata for gRPC bindings). Custom protocol bindings MUST specify how service parameters are transmitted in their binding specification.

Standard A2A Service Parameters:

As service parameter names MAY need to co-exist with other parameters defined by the underlying transport protocol or infrastructure, all service parameters defined by this specification will be prefixed with a2a-.

3.3. Operation Semantics¶

3.3.1. Idempotency¶

3.3.2. Error Handling¶

All operations may return errors in the following categories. Servers MUST return appropriate errors and SHOULD provide actionable information to help clients resolve issues.

Error Categories and Server Requirements:

Authentication Errors: Invalid or missing credentials

Authorization Errors: Insufficient permissions for requested operation

Validation Errors: Invalid input parameters or message format

Resource Errors: Requested task not found or not accessible

System Errors: Internal agent failures or temporary unavailability

Error Payload Structure:

All error responses in the A2A protocol, regardless of binding, MUST convey the following information:

Protocol bindings MUST map these elements to their native error representations while preserving semantic meaning. See binding-specific sections for concrete error format examples: JSON-RPC Error Handling, gRPC Error Handling, and HTTP/REST Error Handling.

A2A-Specific Errors:

3.3.3. Asynchronous Processing¶

A2A operations are designed for asynchronous task execution. Operations return immediately with either Task objects or Message objects, and when a Task is returned, processing continues in the background. Clients retrieve task updates through polling, streaming, or push notifications (see Section 3.5). Agents MAY accept additional messages for tasks in non-terminal states to enable multi-turn interactions (see Section 3.4).

3.3.4. Capability Validation¶

Agents declare optional capabilities in their AgentCard. When clients attempt to use operations or features that require capabilities not declared as supported in the Agent Card, the agent MUST return an appropriate error response:

Clients SHOULD validate capability support by examining the Agent Card before attempting operations that require optional capabilities.

3.4. Multi-Turn Interactions¶

The A2A protocol supports multi-turn conversations through context identifiers and task references, enabling agents to maintain conversational continuity across multiple interactions.

3.4.1. Context Identifier Semantics¶

A contextId is an identifier that logically groups multiple related Task and Message objects, providing continuity across a series of interactions.

Generation and Assignment:

Grouping and Scope:

3.4.2. Task Identifier Semantics¶

A taskId is a unique identifier for a Task object, representing a stateful unit of work with a defined lifecycle.

Generation and Assignment:

3.4.3. Multi-Turn Conversation Patterns¶

The A2A protocol supports several patterns for multi-turn interactions:

Context Continuity:

Input Required State:

Follow-up Messages:

Context Inheritance:

3.5. Task Update Delivery Mechanisms¶

The A2A protocol provides three complementary mechanisms for clients to receive updates about task progress and completion.

3.5.1. Overview of Update Mechanisms¶

Polling (Get Task):

Streaming:

Push Notifications (WebHooks):

3.5.2. Streaming Event Delivery¶

Event Ordering:

All implementations MUST deliver events in the order they were generated. Events MUST NOT be reordered during transmission, regardless of protocol binding.

Multiple Streams Per Task:

An agent MAY serve multiple concurrent streams to one or more clients for the same task. This allows multiple clients (or the same client with multiple connections) to independently subscribe to and receive updates about a task's progress.

When multiple streams are active for a task:

This capability enables scenarios such as:

3.5.3. Push Notification Delivery¶

Push notifications are delivered via HTTP POST to client-registered webhook endpoints. The delivery semantics and reliability guarantees are defined in Section 4.3.

3.6 Versioning¶

The specific version of the A2A protocol in use is identified using the Major.Minor elements (e.g. 1.0) of the corresponding A2A specification version. Patch version numbers used by the specification, do not affect protocol compatibility. Patch version numbers SHOULD NOT be used in requests, responses and Agent Cards, and MUST not be considered when clients and servers negotiate protocol versions.

3.6.1 Client Responsibilities¶

Clients MUST send the A2A-Version header with each request to maintain compatibility after an agent upgrades to a new version of the protocol (except for 0.3 Clients - 0.3 will be assumed for empty header). Sending the A2A-Version header also provides visibility to agents about version usage in the ecosystem, which can help inform the risks of inplace version upgrades.

Example of HTTP GET Request with Version Header:

Clients MAY provide the A2A-Version as a request parameter instead of a header.

Example of HTTP GET Request with Version request parameter:

3.6.2 Server Responsibilities¶

Agents MUST process requests using the semantics of the requested A2A-Version (matching Major.Minor). If the version is not supported by the interface, agents MUST return a VersionNotSupportedError.

Agents MUST interpret empty value as 0.3 version.

Agents CAN expose multiple interfaces for the same transport with different versions under the same or different URLs.

3.6.3 Tooling support¶

Tooling libraries and SDKs that implement the A2A protocol MUST provide mechanisms to help clients manage protocol versioning, such as negotiation of the transport and protocol version used. Client Agents that require the latest features of the protocol should be configured to request specific versions and avoid automatic fallback to older versions, to prevent silently losing functionality.

3.7 Messages and Artifacts¶

Messages and Artifacts serve distinct purposes within the A2A protocol. The core interaction model defined by A2A is for clients to send messages to initiate a task that produces one or more artifacts.

Messages play several key roles:

Messages SHOULD NOT be used to deliver task outputs. Results SHOULD BE returned using Artifacts associated with a Task. This separation allows for a clear distinction between communication (Messages) and data output (Artifacts).

The Task History field contains Messages exchanged during task execution. However, not all Messages are guaranteed to be persisted in the Task history; for example, transient informational messages may not be stored. Messages exchanged prior to task creation may not be stored in Task history. The agent is responsible to determine which Messages are persisted in the Task History.

Clients using streaming to retrieve task updates MAY not receive all status update messages if the client is disconnected and then reconnects. Messages MUST NOT be considered a reliable delivery mechanism for critical information.

Agents MAY choose to persist all Messages that contain important information in the Task history to ensure clients can retrieve it later. However, clients MUST NOT rely on this behavior unless negotiated out-of-band.

4. Protocol Data Model¶

The A2A protocol defines a canonical data model using Protocol Buffers. All protocol bindings MUST provide functionally equivalent representations of these data structures.

4.1. Core Objects¶

4.1.1. Task¶

Task is the core unit of action for A2A. It has a current status and when results are created for the task they are stored in the artifact. If there are multiple turns for a task, these are stored in history.

4.1.2. TaskStatus¶

A container for the status of a task

4.1.3. TaskState¶

Defines the possible lifecycle states of a Task.

4.1.4. Message¶

Message is one unit of communication between client and server. It can be associated with a context and/or a task. For server messages, context_id must be provided, and task_id only if a task was created. For client messages, both fields are optional, with the caveat that if both are provided, they have to match (the context_id has to be the one that is set on the task). If only task_id is provided, the server will infer context_id from it.

4.1.5. Role¶

Defines the sender of a message in A2A protocol communication.

4.1.6. Part¶

Part represents a container for a section of communication content. Parts can be purely textual, some sort of file (image, video, etc) or a structured data blob (i.e. JSON).

Note: A Part MUST contain exactly one of the following: text, raw, url, data

4.1.7. Artifact¶

Artifacts represent task outputs.

4.2. Streaming Events¶

4.2.1. TaskStatusUpdateEvent¶

An event sent by the agent to notify the client of a change in a task's status.

4.2.2. TaskArtifactUpdateEvent¶

A task delta where an artifact has been generated.

4.3. Push Notification Objects¶

4.3.1. PushNotificationConfig¶

Configuration for setting up push notifications for task updates.

4.3.2. AuthenticationInfo¶

Defines authentication details, used for push notifications.

4.3.3. Push Notification Payload¶

When a task update occurs, the agent sends an HTTP POST request to the configured webhook URL. The payload uses the same StreamResponse format as streaming operations, allowing push notifications to deliver the same event types as real-time streams.

Request Format:

Payload Structure:

The webhook payload is a StreamResponse object containing exactly one of the following:

Authentication:

The agent MUST include authentication credentials in the request headers as specified in the PushNotificationConfig.authentication field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.).

Client Responsibilities:

Server Guarantees:

For detailed security guidance on push notifications, see Section 13.2 Push Notification Security.

4.4. Agent Discovery Objects¶

4.4.1. AgentCard¶

A self-describing manifest for an agent. It provides essential metadata including the agent's identity, capabilities, skills, supported communication methods, and security requirements.

4.4.2. AgentProvider¶

Represents the service provider of an agent.

4.4.3. AgentCapabilities¶

Defines optional capabilities supported by an agent.

4.4.4. AgentExtension¶

A declaration of a protocol extension supported by an Agent.

4.4.5. AgentSkill¶

Represents a distinct capability or function that an agent can perform.

4.4.6. AgentInterface¶

Declares a combination of a target URL, transport and protocol version for interacting with the agent. This allows agents to expose the same functionality over multiple protocol binding mechanisms.

4.4.7. AgentCardSignature¶

AgentCardSignature represents a JWS signature of an AgentCard. This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).

4.5. Security Objects¶

4.5.1. SecurityScheme¶

Defines a security scheme that can be used to secure an agent's endpoints. This is a discriminated union type based on the OpenAPI 3.2 Security Scheme Object. See: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object

Note: A SecurityScheme MUST contain exactly one of the following: apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme

4.5.2. APIKeySecurityScheme¶

Defines a security scheme using an API key.

4.5.3. HTTPAuthSecurityScheme¶

Defines a security scheme using HTTP authentication.

4.5.4. OAuth2SecurityScheme¶

Defines a security scheme using OAuth 2.0.

4.5.5. OpenIdConnectSecurityScheme¶

Defines a security scheme using OpenID Connect.

4.5.6. MutualTlsSecurityScheme¶

Defines a security scheme using mTLS authentication.

4.5.7. OAuthFlows¶

Defines the configuration for the supported OAuth 2.0 flows.

Note: A OAuthFlows MUST contain exactly one of the following: authorizationCode, clientCredentials, implicit, password, deviceCode

4.5.8. AuthorizationCodeOAuthFlow¶

Defines configuration details for the OAuth 2.0 Authorization Code flow.

4.5.9. ClientCredentialsOAuthFlow¶

Defines configuration details for the OAuth 2.0 Client Credentials flow.

4.5.10. DeviceCodeOAuthFlow¶

Defines configuration details for the OAuth 2.0 Device Code flow (RFC 8628). This flow is designed for input-constrained devices such as IoT devices, and CLI tools where the user authenticates on a separate device.

4.6. Extensions¶

The A2A protocol supports extensions to provide additional functionality or data beyond the core specification while maintaining backward compatibility and interoperability. Extensions allow agents to declare additional capabilities such as protocol enhancements or vendor-specific features, maintain compatibility with clients that don't support specific extensions, enable innovation through experimental or domain-specific features without modifying the core protocol, and facilitate standardization by providing a pathway for community-developed features to become part of the core specification.

4.6.1. Extension Declaration¶

Agents declare their supported extensions in the AgentCard using the extensions field, which contains an array of AgentExtension objects.

Example: Agent declaring extension support in AgentCard:

Clients indicate their desire to opt into the use of specific extensions through binding-specific mechanisms such as HTTP headers, gRPC metadata, or JSON-RPC request parameters that identify the extension identifiers they wish to utilize during the interaction.

Example: HTTP client opting into extensions using headers:

4.6.2. Extensions Points¶

Extensions can be integrated into the A2A protocol at several well-defined extension points:

Message Extensions:

Messages can be extended to allow clients to provide additional strongly typed context or parameters relevant to the message being sent, or TaskStatus Messages to include extra information about the task's progress.

Example: A location extension using the extensions and metadata arrays:

Artifact Extensions:

Artifacts can include extension data to provide strongly typed context or metadata about the generated content.

Example: An artifact with citation extension for research sources:

4.6.3. Extension Versioning and Compatibility¶

Extensions SHOULD include version information in their URI identifier. This allows clients and agents to negotiate compatible versions of extensions during interactions. A new URI MUST be created for breaking changes to an extension.

If a client requests a versions of an extension that the agent does not support, the agent SHOULD ignore the extension for that interaction and proceed without it, unless the extension is marked as required in the AgentCard, in which case the agent MUST return an error indicating unsupported extension. It MUST NOT fall back to a previous version of the extension automatically.

5. Protocol Binding Requirements and Interoperability¶

5.1. Functional Equivalence Requirements¶

When an agent supports multiple protocols, all supported protocols MUST:

5.2. Protocol Selection and Negotiation¶

5.3. Method Mapping Reference¶

5.4. Error Code Mappings¶

All A2A-specific errors defined in Section 3.3.2 MUST be mapped to binding-specific error representations. The following table provides the canonical mappings for each standard protocol binding:

Custom Binding Requirements:

Custom protocol bindings MUST define equivalent error code mappings that preserve the semantic meaning of each A2A error type. The binding specification SHOULD provide a similar mapping table showing how each A2A error type is represented in the custom binding's native error format.

For binding-specific error structures and examples, see:

5.5. JSON Field Naming Convention¶

All JSON serializations of the A2A protocol data model MUST use camelCase naming for field names, not the snake_case convention used in Protocol Buffer definitions.

Naming Convention:

Enum Values:

Examples:

Note: This follows the ProtoJSON specification as adopted in ADR-001.

5.6. Data Type Conventions¶

This section documents conventions for common data types used throughout the A2A protocol, particularly as they apply to protocol bindings.

5.6.1. Timestamps¶

The A2A protocol uses google.protobuf.Timestamp for all timestamp fields in the Protocol Buffer definitions. When serialized to JSON (in JSON-RPC, HTTP/REST, or other JSON-based bindings), these timestamps MUST be represented as ISO 8601 formatted strings in UTC timezone.

Format Requirements:

Examples:

Implementation Notes:

5.7. Field Presence and Optionality¶

The Protocol Buffer definition in specification/a2a.proto uses google.api.field_behavior annotations to indicate whether fields are REQUIRED. These annotations serve as both documentation and validation hints for implementations.

Required Fields:

Fields marked with [(google.api.field_behavior) = REQUIRED] indicate that the field MUST be present and set in valid messages. Implementations SHOULD validate these requirements and reject messages with missing required fields. Arrays marked as required MUST contain at least one element.

Optional Field Presence:

The Protocol Buffer optional keyword is used to distinguish between a field being explicitly set versus omitted. This distinction is critical for two scenarios:

Explicit Default Values: Some fields in the specification define default values that differ from Protocol Buffer's implicit defaults. Implementations should apply the default value when the field is not explicitly provided.

Agent Card Canonicalization: When creating cryptographic signatures of Agent Cards, it is required to produce a canonical JSON representation. The optional keyword enables implementations to distinguish between fields that were explicitly set (and should be included in the canonical form) versus fields that were omitted (and should be excluded from canonicalization). This ensures Agent Cards can be reconstructed to accurately match their signature.

Unrecognized Fields:

Implementations SHOULD ignore unrecognized fields in messages, allowing for forward compatibility as the protocol evolves.

6. Common Workflows & Examples¶

This section provides illustrative examples of common A2A interactions across different bindings.

6.1. Basic Task Execution¶

Scenario: Client asks a question and receives a completed task response.

Request:

Response:

6.2. Streaming Task Execution¶

Scenario: Client requests a long-running task with real-time updates.

Request:

SSE Response Stream:

6.3. Multi-Turn Interaction¶

Scenario: Agent requires additional input to complete a task.

Initial Request:

Response (Input Required):

Follow-up Request:

6.4. Version Negotiation Error¶

Scenario: Client requests an unsupported protocol version.

Request:

Response:

6.5. Task Listing and Management¶

Scenario: Client wants to see all tasks from a specific context or all tasks with a particular status.

Request: All tasks from a specific context¶

Request:

Response:

Request: All working tasks across all contexts¶

Request:

Response:

Pagination Example¶

Request:

Response:

Validation Error Example¶

Request:

Response:

6.6. Push Notification Setup and Usage¶

Scenario: Client requests a long-running report generation and wants to be notified via webhook when it's done.

Initial Request with Push Notification Config:

Response (Task Submitted):

Later: Server POSTs Notification to Webhook:

6.7. File Exchange (Upload and Download)¶

Scenario: Client sends an image for analysis, and the agent returns a modified image.

Request with File Upload:

Response with File Reference:

6.8. Structured Data Exchange¶

Scenario: Client asks for a list of open support tickets in a specific JSON format.

Request:

Response with Structured Data:

6.9. Fetching Authenticated Extended Agent Card¶

Scenario: A client discovers a public Agent Card indicating support for an authenticated extended card and wants to retrieve the full details.

Step 1: Client fetches the public Agent Card:

Response includes:

Step 2: Client obtains credentials (out-of-band OAuth 2.0 flow)¶

Step 3: Client fetches authenticated extended Agent Card¶

Response:

7. Authentication and Authorization¶

A2A treats agents as standard enterprise applications, relying on established web security practices. Identity information is handled at the protocol layer, not within A2A semantics.

For a comprehensive guide on enterprise security aspects, see Enterprise-Ready Features.

7.1. Protocol Security¶

Production deployments MUST use encrypted communication (HTTPS for HTTP-based bindings, TLS for gRPC). Implementations SHOULD use modern TLS configurations (TLS 1.3+ recommended) with strong cipher suites.

7.2. Server Identity Verification¶

A2A Clients SHOULD verify the A2A Server's identity by validating its TLS certificate against trusted certificate authorities (CAs) during the TLS handshake.

7.3. Client Authentication Process¶

7.4. Server Authentication Responsibilities¶

The A2A Server:

7.5. In-Task Authentication (Secondary Credentials)¶

If an agent requires additional credentials during task execution:

7.6. Authorization¶

Once authenticated, the A2A Server authorizes requests based on the authenticated identity and its own policies. Authorization logic is implementation-specific and MAY consider:

8. Agent Discovery: The Agent Card¶

8.1. Purpose¶

A2A Servers MUST make an Agent Card available. The Agent Card describes the server's identity, capabilities, skills, and interaction requirements. Clients use this information for discovering suitable agents and configuring interactions.

For more on discovery strategies, see the Agent Discovery guide.

8.2. Discovery Mechanisms¶

Clients can find Agent Cards through:

8.3. Protocol Declaration Requirements¶

The AgentCard MUST properly declare supported protocols:

8.3.1. Supported Interfaces Declaration¶

8.3.2. Client Protocol Selection¶

Clients MUST follow these rules:

8.4. Agent Card Signing¶

Agent Cards MAY be digitally signed using JSON Web Signature (JWS) as defined in RFC 7515 to ensure authenticity and integrity. Signatures allow clients to verify that an Agent Card has not been tampered with and originates from the claimed provider.

8.4.1. Canonicalization Requirements¶

Before signing, the Agent Card content MUST be canonicalized using the JSON Canonicalization Scheme (JCS) as defined in RFC 8785. This ensures consistent signature generation and verification across different JSON implementations.

Canonicalization Rules:

Field Presence and Default Value Handling: Before canonicalization, the JSON representation MUST respect Protocol Buffer field presence semantics as defined in Section 5.7. This ensures that the canonical form accurately reflects which fields were explicitly provided versus which were omitted, enabling signature verification when Agent Cards are reconstructed:

RFC 8785 Compliance: The Agent Card JSON MUST be canonicalized according to RFC 8785, which specifies:

Signature Field Exclusion: The signatures field itself MUST be excluded from the content being signed to avoid circular dependencies.

Example of Default Value Removal:

Original Agent Card fragment:

Applying the canonicalization rules:

After applying RFC 8785:

8.4.2. Signature Format¶

Signatures use the JSON Web Signature (JWS) format as defined in RFC 7515. The AgentCardSignature object represents JWS components using three fields:

JWS Protected Header Parameters:

The protected header MUST include:

The protected header MAY include:

Signature Generation Process:

Prepare the payload:

Create the protected header:

Compute the signature:

Assemble the AgentCardSignature:

Example:

Given a canonical Agent Card payload and signing key, the signature generation produces:

Where the protected value decodes to:

8.4.3. Signature Verification¶

Clients verifying Agent Card signatures MUST:

Security Considerations:

8.5. Sample Agent Card¶

9. JSON-RPC Protocol Binding¶

The JSON-RPC protocol binding provides a simple, HTTP-based interface using JSON-RPC 2.0 for method calls and Server-Sent Events for streaming.

9.1. Protocol Requirements¶

9.2. Service Parameter Transmission¶

A2A service parameters defined in Section 3.2.6 MUST be transmitted using standard HTTP request headers, as JSON-RPC 2.0 operates over HTTP(S).

Service Parameter Requirements:

Example Request with A2A Service Parameters:

9.3. Base Request Structure¶

All JSON-RPC requests MUST follow the standard JSON-RPC 2.0 format:

9.4. Core Methods¶

9.4.1. SendMessage¶

Sends a message to initiate or continue a task.

Request:

Referenced Objects: SendMessageRequest, Message

Response:

Referenced Objects: Task, Message

9.4.2. SendStreamingMessage¶

Sends a message and subscribes to real-time updates via Server-Sent Events.

Request: Same as SendMessage

Response: HTTP 200 with Content-Type: text/event-stream

Referenced Objects: StreamResponse

9.4.3. GetTask¶

Retrieves the current state of a task.

Request:

9.4.4. ListTasks¶

Lists tasks with optional filtering and pagination.

Request:

9.4.5. CancelTask¶

Cancels an ongoing task.

Request:

9.4.6. SubscribeToTask¶

Subscribes to a task stream for receiving updates on a task that is not in a terminal state.

Request:

Response: SSE stream (same format as SendStreamingMessage)

Error: Returns UnsupportedOperationError if the task is in a terminal state (completed, failed, canceled, or rejected).

9.4.7. Push Notification Configuration Methods¶

9.4.8. GetExtendedAgentCard¶

Retrieves an extended Agent Card.

Request:

9.5. Error Handling¶

JSON-RPC error responses use the standard JSON-RPC 2.0 error object structure, which maps to the generic A2A error model defined in Section 3.3.2 as follows:

Standard JSON-RPC Error Codes:

A2A-Specific Error Codes:

A2A-specific errors use codes in the range -32001 to -32099. For the complete mapping of A2A error types to JSON-RPC error codes, see Section 5.4 (Error Code Mappings).

Error Response Structure:

Example A2A-Specific Error Response:

The data field MAY include additional context-specific information to help clients diagnose and resolve the error.

10. gRPC Protocol Binding¶

The gRPC Protocol Binding provides a high-performance, strongly-typed interface using Protocol Buffers over HTTP/2. The gRPC Protocol Binding leverages the API guidelines to simplify gRPC to HTTP mapping.

10.1. Protocol Requirements¶

10.2. Service Parameter Transmission¶

A2A service parameters defined in Section 3.2.6 MUST be transmitted using gRPC metadata (headers).

Service Parameter Requirements:

Example gRPC Request with A2A Service Parameters:

Metadata Handling:

10.3. Service Definition¶

10.4. Core Methods¶

10.4.1. SendMessage¶

Sends a message to an agent.

Request:

Represents a request for the SendMessage method.

Response:

Note: A SendMessageResponse MUST contain exactly one of the following: task, message

10.4.2. SendStreamingMessage¶

Sends a message with streaming updates.

Request:

Represents a request for the SendMessage method.

Response: Server streaming StreamResponse objects.

10.4.3. GetTask¶

Retrieves task status.

Request:

Represents a request for the GetTask method.

Response: See Task object definition.

10.4.4. ListTasks¶

Lists tasks with filtering.

Request:

Parameters for listing tasks with optional filtering criteria.

Response:

Result object for ListTasks method containing an array of tasks and pagination information.

10.4.5. CancelTask¶

Cancels a running task.

Request:

Represents a request for the CancelTask method.

Response: See Task object definition.

10.4.6. SubscribeToTask¶

Subscribe to task updates via streaming. Returns UnsupportedOperationError if the task is in a terminal state.

Request:

Response: Server streaming StreamResponse objects.

10.4.7. CreateTaskPushNotificationConfig¶

Creates a push notification configuration for a task.

Request:

Represents a request for the CreateTaskPushNotificationConfig method.

Response: See PushNotificationConfig object definition.

10.4.8. GetTaskPushNotificationConfig¶

Retrieves an existing push notification configuration for a task.

Request:

Response: See PushNotificationConfig object definition.

10.4.9. ListTaskPushNotificationConfig¶

Lists all push notification configurations for a task.

Request:

Response:

Represents a successful response for the ListTaskPushNotificationConfig method.

10.4.10. DeleteTaskPushNotificationConfig¶

Removes a push notification configuration for a task.

Request:

Represents a request for the DeleteTaskPushNotificationConfig method.

Response: google.protobuf.Empty

10.4.11. GetExtendedAgentCard¶

Retrieves the agent's extended capability card after authentication.

Request:

Response: See AgentCard object definition.

10.5. gRPC-Specific Data Types¶

10.5.1. TaskPushNotificationConfig¶

Resource wrapper for push notification configurations. This is a gRPC-specific type used in resource-oriented operations to provide the full resource name along with the configuration data.

A container associating a push notification configuration with a specific task.

Fields:

A container associating a push notification configuration with a specific task.

10.6. Error Handling¶

gRPC error responses use the standard gRPC status structure with google.rpc.Status, which maps to the generic A2A error model defined in Section 3.3.2 as follows:

A2A Error Representation:

For A2A-specific errors, implementations MUST include a google.rpc.ErrorInfo message in the status.details array with:

For the complete mapping of A2A error types to gRPC status codes, see Section 5.4 (Error Code Mappings).

Error Response Example:

Example A2A-Specific Error Response:

10.7. Streaming¶

gRPC streaming uses server streaming RPCs for real-time updates. The StreamResponse message provides a union of possible streaming events:

A wrapper object used in streaming operations to encapsulate different types of response data.

Note: A StreamResponse MUST contain exactly one of the following: task, message, statusUpdate, artifactUpdate

11. HTTP+JSON/REST Protocol Binding¶

The HTTP+JSON protocol binding provides a RESTful interface using standard HTTP methods and JSON payloads.

11.1. Protocol Requirements¶

11.2. Service Parameter Transmission¶

A2A service parameters defined in Section 3.2.6 MUST be transmitted using standard HTTP request headers.

Service Parameter Requirements:

Example Request with A2A Service Parameters:

11.3. URL Patterns and HTTP Methods¶

11.3.1. Message Operations¶

11.3.2. Task Operations¶

11.3.3. Push Notification Configuration¶

11.3.4. Agent Card¶

11.4. Request/Response Format¶

All requests and responses use JSON objects structurally equivalent to the Protocol Buffer definitions.

Example Send Message:

Referenced Objects: SendMessageRequest, Message

Response:

Referenced Objects: Task

11.5. Query Parameter Naming for Request Parameters¶

HTTP methods that do not support request bodies (GET, DELETE) MUST transmit operation request parameters as path parameters or query parameters. This section defines how to map Protocol Buffer field names to query parameter names.

Naming Convention:

Query parameter names MUST use camelCase to match the JSON serialization of Protocol Buffer field names. This ensures consistency with request bodies used in POST operations.

Example Mappings:

Usage Examples:

List tasks with filtering:

Get task with history:

Field Type Handling:

URL Encoding:

All query parameter values MUST be properly URL-encoded per RFC 3986.

11.6. Error Handling¶

HTTP error responses use RFC 9457 Problem Details format with Content-Type: application/problem+json, which maps to the generic A2A error model defined in Section 3.3.2 as follows:

A2A Error Representation:

For A2A-specific errors, the type field MUST use the URI from the mapping table in Section 5.4 (Error Code Mappings). Additional error context MAY be included as extension fields in the problem details object.

Error Response Example:

Extension fields like taskId and timestamp provide additional context to help diagnose the error.

11.7. Streaming¶

REST streaming uses Server-Sent Events with the data field containing JSON serializations of the protocol data objects:

Referenced Objects: SendMessageRequest

Response:

Referenced Objects: StreamResponse
Streaming responses are simple, linearly ordered sequences: first a Task (or single Message), then zero or more status or artifact update events until the task reaches a terminal or interrupted state, at which point the stream closes. Implementations SHOULD avoid re-ordering events and MAY optionally resend a final Task snapshot before closing.

12. Custom Binding Guidelines¶

While the A2A protocol provides three standard bindings (JSON-RPC, gRPC, and HTTP+JSON/REST), implementers MAY create custom protocol bindings to support additional transport mechanisms or communication patterns. Custom bindings MUST comply with all requirements defined in Section 5 (Protocol Binding Requirements and Interoperability). This section provides additional guidelines specific to developing custom bindings.

12.1. Binding Requirements¶

Custom protocol bindings MUST:

12.2. Data Type Mappings¶

Custom bindings MUST provide clear mappings for:

12.3. Service Parameter Transmission¶

As specified in Section 3.2.6 (Service Parameters), custom protocol bindings MUST document how service parameters are transmitted. The binding specification MUST address:

Example Documentation Requirements:

12.4. Error Mapping¶

Custom bindings MUST:

12.5. Streaming Support¶

If the binding supports streaming operations:

If streaming is not supported, the binding MUST clearly document this limitation in the Agent Card.

12.6. Authentication and Authorization¶

Custom bindings MUST:

12.7. Agent Card Declaration¶

Custom bindings MUST be declared in the Agent Card:

Example:

12.8. Interoperability Testing¶

Custom binding implementers SHOULD:

13. Security Considerations¶

This section consolidates security guidance and best practices for implementing and operating A2A agents. For additional enterprise security considerations, see Enterprise-Ready Features.

13.1. Data Access and Authorization Scoping¶

Implementations MUST ensure appropriate scope limitation based on the authenticated caller's authorization boundaries. This applies to all operations that access or list tasks and other resources.

Authorization Principles:

Operations Requiring Scope Limitation:

Implementation Requirements:

See also: Section 3.1.4 List Tasks (Security Note) for operation-specific requirements.

13.2. Push Notification Security¶

When implementing push notifications, both agents (as webhook callers) and clients (as webhook receivers) have security responsibilities.

Agent (Webhook Caller) Requirements:

Client (Webhook Receiver) Requirements:

Configuration Security:

See also: Section 4.3 Push Notification Objects and Section 4.3.3 Push Notification Payload.

13.3. Extended Agent Card Access Control¶

The extended Agent Card feature allows agents to provide additional capabilities or information to authenticated clients beyond what is available in the public Agent Card.

Access Control Requirements:

Capability-Based Access:

Security Considerations:

Availability Declaration:

See also: Section 3.1.11 Get Extended Agent Card and Section 3.3.4 Capability Validation.

13.4. General Security Best Practices¶

Transport Security:

Input Validation:

Credential Management:

Audit and Monitoring:

Rate Limiting and Abuse Prevention:

Data Privacy:

Custom Binding Security:

See also: Section 12.6 Authentication and Authorization (Custom Bindings).

14. IANA Considerations¶

This section provides registration templates for the A2A protocol's media type, HTTP headers, and well-known URI, intended for submission to the Internet Assigned Numbers Authority (IANA).

14.1. Media Type Registration¶

14.1.1. application/a2a+json¶

Type name: application

Subtype name: a2a+json

Required parameters: None

Optional parameters:

Encoding considerations: Binary (UTF-8 encoding MUST be used for JSON text)

Security considerations:
This media type shares security considerations common to all JSON-based formats as described in RFC 8259, Section 12. Additionally:

Interoperability considerations:
The A2A protocol supports multiple protocol bindings. This media type is intended for the HTTP+JSON/REST binding.

Published specification:
Agent2Agent (A2A) Protocol Specification, available at: https://a2a-protocol.org/latest/specification

Applications that use this media type:
AI agent platforms, agentic workflow systems, multi-agent collaboration tools, and enterprise automation systems that implement the A2A protocol for agent-to-agent communication.

Fragment identifier considerations: None

Additional information:

Person & email address to contact for further information:
A2A Protocol Working Group, a2a-protocol@example.org

Intended usage: COMMON

Restrictions on usage: None

Author: A2A Protocol Working Group

Change controller: A2A Protocol Working Group

Provisional registration: No

14.2. HTTP Header Field Registrations¶

Note: The following HTTP headers represent the HTTP-based protocol binding implementation of the abstract A2A service parameters defined in Section 3.2.6. These registrations are specific to HTTP/HTTPS transports.

14.2.1. A2A-Version Header¶

Header field name: A2A-Version

Applicable protocol: HTTP

Status: Standard

Author/Change controller: A2A Protocol Working Group

Specification document: Section 3.2.5 of the A2A Protocol Specification

Related information:
The A2A-Version header field indicates the A2A protocol version that the client is using. The value MUST be in the format Major.Minor (e.g., "0.3"). If the version is not supported by the agent, the agent returns a VersionNotSupportedError.

Example:

14.2.2. A2A-Extensions Header¶

Header field name: A2A-Extensions

Applicable protocol: HTTP

Status: Standard

Author/Change controller: A2A Protocol Working Group

Specification document: Section 3.2.5 of the A2A Protocol Specification

Related information:
The A2A-Extensions header field contains a comma-separated list of extension URIs that the client wants to use for the request. Extensions allow agents to provide additional functionality beyond the core A2A specification while maintaining backward compatibility.

Example:

14.3. Well-Known URI Registration¶

URI suffix: agent-card.json

Change controller: A2A Protocol Working Group

Specification document: Section 8.2 of the A2A Protocol Specification

Related information:
The .well-known/agent-card.json URI provides a standardized location for discovering an A2A agent's capabilities, supported protocols, authentication requirements, and available skills. The resource at this URI MUST return an AgentCard object as defined in Section 4.4.1 of the A2A specification.

Status: Permanent

Security considerations:

Example:

Appendix A. Migration & Legacy Compatibility¶

This appendix catalogs renamed protocol messages and objects, their legacy identifiers, and the planned deprecation/removal schedule. All legacy names and anchors MUST remain resolvable until the stated earliest removal version.

Planned Lifecycle (example timeline; adjust per release strategy):

A.1 Legacy Documentation Anchors¶

Hidden anchor spans preserve old inbound links:

Each legacy span SHOULD be placed adjacent to the current object's heading (to be inserted during detailed object section edits). If an exact numeric-prefixed anchor existed (e.g., #414-message), add an additional span matching that historical form if known.

A.2 Migration Guidance¶

Client Implementations SHOULD:

Server Implementations MAY:

A.2.1 Breaking Change: Kind Discriminator Removed¶

Version 1.0 introduces a breaking change in how polymorphic objects are represented in the protocol. This affects Part types and streaming event types.

Legacy Pattern (v0.3.x):
Objects used an inline kind field as a discriminator to identify the object type:

Example 1 - TextPart:

Example 2 - FilePart:

Current Pattern (v1.0):
Objects now use the JSON member name itself to identify the type. The member name acts as the discriminator, and the value structure depends on the specific type:

Example 1 - TextPart:

Example 2 - FilePart:

Affected Types:

DataPart:

Streaming Event Types:

Migration Strategy:

For Clients upgrading from pre-0.3.x:

For Servers upgrading from pre-0.3.x:

Rationale:

This change aligns with modern API design practices and Protocol Buffers' oneof semantics, where the field name itself serves as the type discriminator. This approach:

A.2.2 Breaking Change: Extended Agent Card Field Relocated¶

Version 1.0 relocates the extended agent card capability from a top-level field to the capabilities object for architectural consistency.

Legacy Structure (pre-1.0):

Current Structure (1.0+):

Proto Changes:

Migration Steps:

For Agent Implementations:

For Client Implementations:

For SDK Developers:

Rationale:

All optional features enabling specific operations (streaming, pushNotifications, stateTransitionHistory) reside in AgentCapabilities. Moving extendedAgentCard achieves:

A.3 Future Automation¶

Once the proto→schema generation pipeline lands, this appendix will be partially auto-generated (legacy mapping table sourced from a maintained manifest). Until then, edits MUST be manual and reviewed in PRs affecting a2a.proto.

Appendix B. Relationship to MCP (Model Context Protocol)¶

A2A and MCP are complementary protocols designed for different aspects of agentic systems:

How they work together:
An A2A Client agent might request an A2A Server agent to perform a complex task. The Server agent, in turn, might use MCP to interact with several underlying tools, APIs, or data sources to gather information or perform actions necessary to fulfill the A2A task.

For a more detailed comparison, see the A2A and MCP guide.