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:
- Securely exchange information to achieve user goals **without needing access to each other's internal state, memory, or tools.**
### 1.1. Key Goals of A2A
- **Interoperability:** Bridge the communication gap between disparate agentic systems.
- **Collaboration:** Enable agents to delegate tasks, exchange context, and work together on complex user requests.
- **Discovery:** Allow agents to dynamically find and understand the capabilities of other agents.
- **Flexibility:** Support various interaction modes including synchronous request/response, streaming for real-time updates, and asynchronous push notifications for long-running tasks.
- **Security:** Facilitate secure communication patterns suitable for enterprise environments, relying on standard web security practices.
- **Asynchronicity:** Natively support long-running tasks and interactions that may involve human-in-the-loop scenarios.
- **Enterprise Ready:** Address authentication, authorization, security, privacy, tracing, and monitoring by aligning with established enterprise practices.
- **Async First:** Designed for (potentially very) long-running tasks and human-in-the-loop interactions.
- **Modality Agnostic:** Support exchange of diverse content types including text, audio/video (via file references), structured data/forms, and potentially embedded UI components (e.g., iframes referenced in parts).
- **Opaque Execution:** Agents collaborate based on declared capabilities and exchanged information, without needing to share their internal thoughts, plans, or tool implementations.
For a broader understanding of A2A's purpose and benefits, see [What is A2A?](./topics/what-is-a2a.md).
**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:
- Core semantics remain consistent across all protocol bindings
- New protocol bindings can be added without changing the fundamental data model
- Developers can reason about A2A operations independently of binding concerns
- Interoperability is maintained through shared understanding of the canonical data model
### 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:**
- Introduction: When a proto message or field is renamed, the new name is added while existing published names remain available, but marked deprecated, until the next major release.
- Anchors: Legacy documentation anchors MUST be preserved (as hidden HTML anchors) to avoid breaking inbound links.
- SDK/Schema Aliases: SDKs and JSON Schemas SHOULD provide deprecated alias types/definitions to maintain backward compatibility.
- Removal: A deprecated name SHOULD NOT be removed earlier than the next major version after introduction of its replacement.
**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.
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](https://tools.ietf.org/html/rfc2119).
- **Agent Card:** A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements.
- **Push Notifications:** Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios.
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.
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)](#53-method-mapping-reference). For detailed protocol-specific implementation details, see:
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.
- [`ContentTypeNotSupportedError`](#332-error-handling): A Media Type provided in the request's message parts is not supported by the agent.
- [`UnsupportedOperationError`](#332-error-handling): Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages.
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`](#411-task) is returned.
- Initial response: [`Task`](#411-task) object OR [`Message`](#414-message) object
- Subsequent events following a `Task` MAY include stream of [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) and [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects
- [`UnsupportedOperationError`](#332-error-handling): Streaming is not supported by the agent (see [Capability Validation](#334-capability-validation)).
- [`UnsupportedOperationError`](#332-error-handling): Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages.
- [`ContentTypeNotSupportedError`](#332-error-handling): A Media Type provided in the request's message parts is not supported by the agent.
- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.
1.**Message-only stream:** If the agent returns a [`Message`](#414-message), the stream MUST contain exactly one `Message` object and then close immediately. No task tracking or updates are provided.
2.**Task lifecycle stream:** If the agent returns a [`Task`](#411-task), the stream MUST begin with the Task object, followed by zero or more [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) or [`TaskArtifactUpdateEvent`](#422-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.
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.
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.
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).
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.
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](#131-data-access-and-authorization-scoping) for detailed security requirements.
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).
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.
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).
- [`UnsupportedOperationError`](#332-error-handling): Streaming is not supported by the agent (see [Capability Validation](#334-capability-validation)).
- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.
- [`UnsupportedOperationError`](#332-error-handling): The operation is attempted on a task that is in a terminal state (`completed`, `failed`, `canceled`, or `rejected`).
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`.
- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).
- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.
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`](#323-stream-response) payloads (see [Push Notification Payload](#433-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.
- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).
- [`TaskNotFoundError`](#332-error-handling): The push notification configuration does not exist.
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.
- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).
- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.
The operation MUST return all active push notification configurations for the specified task and MAY support pagination for tasks with many configurations.
- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).
- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist.
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.
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`.
- [`UnsupportedOperationError`](#332-error-handling): The agent does not support authenticated extended cards (see [Capability Validation](#334-capability-validation)).
- [`ExtendedAgentCardNotConfiguredError`](#332-error-handling): The agent declares support but does not have an extended agent card configured.
- **Authentication**: The client MUST authenticate the request using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields.
- **Extended Information**: The operation MAY return different details based on client authentication level, including additional skills, capabilities, or configuration not available in the public Agent Card.
- **Card Replacement**: Clients retrieving this extended card SHOULD replace their cached public Agent Card with the content received from this endpoint for the duration of their authenticated session or until the card's version changes.
The `return_immediately` field in [`SendMessageConfiguration`](#322-sendmessageconfiguration) controls whether the operation returns immediately or waits for task completion. Operations are blocking by default:
- **Blocking (`return_immediately: false` or unset)**: 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 latest task state with all artifacts and status information. This is the default behavior.
- **Non-Blocking (`return_immediately: true`)**: 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](#313-get-task), subscribe via [Subscribe to Task](#316-subscribe-to-task), or receive updates via push notifications.
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:
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`](#46-extensions) can be used to strongly type metadata values for specific use cases.
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.
| `A2A-Extensions` | Comma-separated list of extension URIs that the client wants to use for the request | `https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1` |
| `A2A-Version` | The A2A protocol version that the client is using. If the version is not supported, the agent returns [`VersionNotSupportedError`](#332-error-handling) | `0.3` |
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-`.
- **Cancel Task** operations are idempotent - multiple cancellation requests have the same effect. A duplicate cancellation request MAY return `TaskNotFoundError` if the task has already been canceled and purged.
All operations may return errors in the following categories. Servers **MUST** return appropriate errors and **SHOULD** provide actionable information to help clients resolve issues.
- **System Errors**: Internal agent failures or temporary unavailability
- Servers **SHOULD** return appropriate error codes for temporary failures vs. permanent errors
- Servers **MAY** include retry guidance (e.g., Retry-After header in HTTP)
- Servers **SHOULD** log system errors for diagnostic purposes
- Example error codes: HTTP `500 Internal Server Error` or `503 Service Unavailable`, gRPC `INTERNAL` or `UNAVAILABLE`, JSON-RPC `-32603 Internal error`
- Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded
3.**Error Details** (optional): An array of objects providing additional structured information about the error. Each object in the array **MUST** include a `@type` key that identifies the object's type (using [ProtoJSON `Any` representation](https://protobuf.dev/programming-guides/json)). Well-known types from the [`google.rpc` error model](https://cloud.google.com/apis/design/errors#error_model) (e.g., `ErrorInfo`, `BadRequest`) **SHOULD** be used where applicable. Error details may be used for:
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](#95-error-handling), [gRPC Error Handling](#106-error-handling), and [HTTP/REST Error Handling](#116-error-handling).
| `TaskNotFoundError` | The specified task ID does not correspond to an existing or accessible task. It might be invalid, expired, or already completed and purged. |
| `TaskNotCancelableError` | An attempt was made to cancel a task that is not in a cancelable state (e.g., it has already reached a terminal state like `completed`, `failed`, or `canceled`). |
| `PushNotificationNotSupportedError` | Client attempted to use push notification features but the server agent does not support them (i.e., `AgentCard.capabilities.pushNotifications` is `false`). |
| `UnsupportedOperationError` | The requested operation or a specific aspect of it is not supported by this server agent implementation. |
| `ContentTypeNotSupportedError` | A Media Type provided in the request's message parts or implied for an artifact is not supported by the agent or the specific skill being invoked. |
| `InvalidAgentResponseError` | An agent returned a response that does not conform to the specification for the current method. |
| `ExtendedAgentCardNotConfiguredError` | The agent does not have an extended agent card configured when one is required for the requested operation. |
| `ExtensionSupportRequiredError` | Server requested use of an extension marked as `required: true` in the Agent Card but the client did not declare support for it in the request. |
| `VersionNotSupportedError` | The A2A protocol version specified in the request (via `A2A-Version` service parameter) is not supported by the agent. |
A2A operations are designed for asynchronous task execution. Operations return immediately with either [`Task`](#411-task) objects or [`Message`](#414-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](#35-task-update-delivery-mechanisms)). Agents MAY accept additional messages for tasks in non-terminal states to enable multi-turn interactions (see [Section 3.4](#34-multi-turn-interactions)).
Agents declare optional capabilities in their [`AgentCard`](#441-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:
- **Push Notifications**: If `AgentCard.capabilities.pushNotifications` is `false` or not present, operations related to push notification configuration (Create, Get, List, Delete) **MUST** return [`PushNotificationNotSupportedError`](#332-error-handling).
- **Streaming**: If `AgentCard.capabilities.streaming` is `false` or not present, attempts to use `SendStreamingMessage` or `SubscribeToTask` operations **MUST** return [`UnsupportedOperationError`](#332-error-handling).
- **Extended Agent Card**: If `AgentCard.capabilities.extendedAgentCard` is `false` or not present, attempts to call the Get Extended Agent Card operation **MUST** return [`UnsupportedOperationError`](#332-error-handling). If the agent declares support but has not configured an extended card, it **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling).
- **Extensions**: When a server requests use of an extension marked as `required: true` in the Agent Card but the client does not declare support for it, the agent **MUST** return [`ExtensionSupportRequiredError`](#332-error-handling).
The A2A protocol supports multi-turn conversations through context identifiers and task references, enabling agents to maintain conversational continuity across multiple interactions.
A `contextId` is an identifier that logically groups multiple related [`Task`](#411-task) and [`Message`](#414-message) objects, providing continuity across a series of interactions.
- Agents **MAY** generate a new `contextId` when processing a [`Message`](#414-message) that does not include a `contextId` field
- If an agent generates a new `contextId`, it **MUST** be included in the response (either [`Task`](#411-task) or [`Message`](#414-message))
- Agents **MAY** accept and preserve client-provided `contextId` values
- If an agent cannot accept a client-provided `contextId`, it **MUST** reject the request with an error and **MUST NOT** generate a new `contextId` for the response
- Clients **SHOULD NOT** provide a client-generated `contextId` to a server unless they understand how the server will process that `contextId`
- Server-generated `contextId` values **SHOULD** be treated as opaque identifiers by clients
- A `contextId` logically groups multiple [`Task`](#411-task) objects and [`Message`](#414-message) objects that are part of the same conversational context
- All tasks and messages with the same `contextId`**SHOULD** be treated as part of the same conversational session
- Agents **MAY** use the `contextId` to maintain internal state, conversational history, or LLM context across multiple interactions
- Agents **MAY** implement context expiration or cleanup policies and **SHOULD** document any such policies
- Agents **MUST** infer `contextId` from the task if only `taskId` is provided
- Agents **MUST** reject messages containing mismatching `contextId` and `taskId` (i.e., the provided `contextId` is different from that of the referenced [`Task`](#411-task)).
- Requires `AgentCard.capabilities.pushNotifications` to be `true`
- Regardless of the protocol binding being used by the agent, WebHook calls use plain HTTP and the JSON payloads as defined in the HTTP protocol binding
#### 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.
- Multiple team members monitoring the same long-running task
- A client reconnecting to a task after a network interruption by opening a new stream
- Different applications or dashboards displaying real-time updates for the same task
#### 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](#43-push-notification-objects).
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.
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.
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`](#332-error-handling).
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.
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:
- **Task Initiation**: Clients send Messages to agents to initiate new tasks.
- **Clarification Messages**: Agents may send Messages back to the client to request clarification prior to initiating a task.
- **Status Messages**: Agents attach Messages to status update events to inform clients about task progress, request additional input, or provide informational updates.
- **Task Interaction**: Clients send Messages to provide additional input or instructions for ongoing tasks.
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.
The A2A protocol defines a canonical data model using Protocol Buffers. All protocol bindings **MUST** provide functionally equivalent representations of these data structures.
When a task update occurs, the agent sends an HTTP POST request to the configured webhook URL. The payload uses the same [`StreamResponse`](#323-stream-response) format as streaming operations, allowing push notifications to deliver the same event types as real-time streams.
The agent MUST include authentication credentials in the request headers as specified in the [`PushNotificationConfig.authentication`](#432-authenticationinfo) field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.).
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.
Agents declare their supported extensions in the [`AgentCard`](#441-agentcard) using the `extensions` field, which contains an array of [`AgentExtension`](#444-agentextension) objects.
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.
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.
"relevantText": "Global temperatures have risen by 1.1°C"
}
]
}
}
}
```
#### 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**:
- **Identical Functionality**: Provide the same set of operations and capabilities
- **Consistent Behavior**: Return semantically equivalent results for the same requests
All A2A-specific errors defined in [Section 3.3.2](#332-error-handling) **MUST** be mapped to binding-specific error representations. The following table provides the canonical mappings for each standard protocol binding:
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:
- [JSON-RPC Error Handling](#95-error-handling)
- [gRPC Error Handling](#106-error-handling)
- [HTTP/REST Error Handling](#116-error-handling)
### 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.
- Enum values **MUST** be represented according to the [ProtoJSON specification](https://protobuf.dev/programming-guides/json/), which serializes enums as their string names **as defined in the Protocol Buffer definition** (typically SCREAMING_SNAKE_CASE).
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`](https://protobuf.dev/reference/protobuf/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:**
- **Format:** ISO 8601 combined date and time representation
- **Timezone:** UTC (denoted by 'Z' suffix)
- **Precision:** Millisecond precision **SHOULD** be used where available
- **Pattern:** `YYYY-MM-DDTHH:mm:ss.sssZ`
**Examples:**
```json
{
"timestamp": "2025-10-28T10:30:00.000Z",
"createdAt": "2025-10-28T14:25:33.142Z",
"lastModified": "2025-10-31T17:45:22.891Z"
}
```
**Implementation Notes:**
- Protocol Buffer's `google.protobuf.Timestamp` represents time as seconds since Unix epoch (January 1, 1970, 00:00:00 UTC) plus nanoseconds
- JSON serialization automatically converts this to ISO 8601 format when using standard Protocol Buffer JSON encoding
- Clients and servers **MUST** parse and generate ISO 8601 timestamps correctly
- When millisecond precision is not available, the fractional seconds portion **MAY** be omitted or zero-filled
- Timestamps **MUST NOT** include timezone offsets other than 'Z' (all times are UTC)
The Protocol Buffer definition in `specification/a2a.proto` uses [`google.api.field_behavior`](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) annotations to indicate whether fields are `REQUIRED`. These annotations serve as both documentation and validation hints for implementations.
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:
1.**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.
2.**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.
"text": "[{\"ticketNumber\":\"REQ12312\",\"description\":\"request for VPN access\"},{\"ticketNumber\":\"REQ23422\",\"description\":\"Add to DL - team-gcp-onboarding\"}]"
/* Extended skills available to authenticated users */
]
}
```
## 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](./topics/enterprise-ready.md).
### 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.
2.**Credential Acquisition (Out-of-Band):** The client obtains the necessary credentials through an out-of-band process specific to the required authentication scheme.
3.**Credential Transmission:** The client includes these credentials in protocol-appropriate headers or metadata for every A2A request.
### 7.4. Server Authentication Responsibilities
The A2A Server:
- **MUST** authenticate every incoming request based on the provided credentials and its declared authentication requirements.
- **SHOULD** use appropriate binding-specific error codes for authentication challenges or rejections.
- **SHOULD** provide relevant authentication challenge information with error responses.
Once authenticated, the A2A Server authorizes requests based on the authenticated identity and its own policies. Authorization logic is implementation-specific and **MAY** consider:
In the course of performing a task, an agent may require authorization to perform some action. Examples include:
- An agent requiring an OAuth access token to call an API or another agent
- An agent requiring human approval before a destructive action is taken
In the sections below, we refer to the object that represents the approved authorization as a credential.
Agents may have multiple means for retrieving this authorization, such as via directly sending messages to a human.
A2A provides the capability for agents to delegate the fulfillment of this authorization to the client via the `TASK_STATE_AUTH_REQUIRED` Task state. This provides agents a fallback path for requesting authorization by passing the responsibility to the client.
To request that a client fulfills an authorization request, the agent:
1. MUST use a Task to track the operation it is performing
2. MUST transition the TaskState to `TASK_STATE_AUTH_REQUIRED`
3. MUST include a TaskStatus message explaining the required authorization, unless the details of the authorization have been negotiated out-of-band or via an extension
Agents MUST arrange to receive credentials via an out-of-band means, unless an in-band mechanism has been negotiated out-of-band or via an extension.
If the credential is received out-of-band, the agent SHOULD maintain any active response streams with the client after setting the TaskState to `TASK_STATE_AUTH_REQUIRED`. The agent MAY immediately continue Task processing after receiving the credential, without a requirement that clients send a follow-up message.
Agents SHOULD support receiving messages directed to the Task while the Task remains in `TASK_STATE_AUTH_REQUIRED`. This enables clients to negotiate, correct, or reject an authorization request.
Upon receiving a Task in `TASK_STATE_AUTH_REQUIRED`, a client is expected to take action in some way to resolve the agent's request for authorization.
A client may:
- Send a response message to the Task to negotiate, correct, or reject the authorization request.
- Contact another human, agent, or service to fulfill the authorization request
- Directly fulfill the authorization request via an out-of-band or extension negotiated means
If the client is itself an A2A agent actively processing a Task, the client may further delegate the authorization request to its client by transitioning its own Task to `TASK_STATE_AUTH_REQUIRED`. The client SHOULD follow all [In-Task Authorization Agent Responsibilities](#761-in-task-authorization-agent-responsibilities). This enables forming a chain of Tasks in `TASK_STATE_AUTH_REQUIRED`.
Clients may not be aware of when the agent receives credentials out-of-band and subsequently continues Task processing. If a client does not have an active response stream open with the agent, the client risks missing Task updates. To avoid this, a client SHOULD perform one of the following:
- Subscribe to a stream of events for the Task using the [Subscribe to Task](#316-subscribe-to-task) operation
- Register a webhook to receive events, if supported by the agent, using the [Create Push Notification Config](#317-create-push-notification-config) operation
- Begin polling the Task using the [Get Task](#313-get-task) operation
Agents SHOULD receive credentials for in-task authorization requests out of band via a secure channel, such as HTTPS. This ensures that credentials are provided directly to the agent.
In-band credential exchange may be negotiated via out-of-band means or by using extensions. In-band credential exchange can allow credentials to be passed across chains of multiple A2A agents, exposing those credentials to each agent participating in the chain.
If using in-band credential exchange, we recommend adhering to the following security practices:
- Credentials SHOULD be bound to the agent which originated the request, such that only this agent is able to use the credentials. This ensures that credentials propagating through a chain of A2A requests are only usable by the requesting agent.
- Credentials containing sensitive information SHOULD be only readable by the agent which originated the request, such as by encrypting the credential.
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](./topics/agent-discovery.md).
Agent Cards **MAY** be digitally signed using JSON Web Signature (JWS) as defined in [RFC 7515](https://tools.ietf.org/html/rfc7515) 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](https://tools.ietf.org/html/rfc8785). This ensures consistent signature generation and verification across different JSON implementations.
**Canonicalization Rules:**
1.**Field Presence and Default Value Handling**: Before canonicalization, the JSON representation **MUST** respect Protocol Buffer field presence semantics as defined in [Section 5.7](#57-field-presence-and-optionality). 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:
- **Optional fields not explicitly set**: Fields marked with the `optional` keyword that were not explicitly set **MUST** be omitted from the JSON object
- **Optional fields explicitly set to defaults**: Fields marked with `optional` that were explicitly set to a value (even if that value matches a default) **MUST** be included in the JSON object
- **Required fields**: Fields marked with `REQUIRED`**MUST** always be present, even if the field value matches the default.
- **Default values**: Fields with default values **MUST** be omitted unless the field is marked as `REQUIRED` or has the `optional` keyword.
2.**RFC 8785 Compliance**: The Agent Card JSON **MUST** be canonicalized according to RFC 8785, which specifies:
- Predictable ordering of object properties (lexicographic by key)
- Consistent representation of numbers, strings, and other primitive values
- Removal of insignificant whitespace
3.**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:
```json
{
"name": "Example Agent",
"description": "",
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extensions": []
},
"skills": []
}
```
Applying the canonicalization rules:
-`name`: "Example Agent" - REQUIRED field → **include**
-`description`: "" - REQUIRED field → **include**
-`capabilities`: object - REQUIRED field → **include** (after processing children)
Signatures use the JSON Web Signature (JWS) format as defined in [RFC 7515](https://tools.ietf.org/html/rfc7515). The [`AgentCardSignature`](#447-agentcardsignature) object represents JWS components using three fields:
1. Extract the signature from the `signatures` array
2. Retrieve the public key using the `kid` and `jku` (or from a trusted key store)
3. Remove properties with default values from the received Agent Card
4. Exclude the `signatures` field
5. Canonicalize the resulting JSON using RFC 8785
6. Verify the signature against the canonicalized payload
**Security Considerations:**
- Clients **SHOULD** verify at least one signature before trusting an Agent Card
- Public keys **SHOULD** be retrieved over secure channels (HTTPS)
- Clients **MAY** maintain a trusted key store for known agent providers
- Expired or revoked keys **MUST NOT** be used for verification
- Multiple signatures **MAY** be present to support key rotation
### 8.5. Sample Agent Card
```json
{
"name": "GeoSpatial Route Planner Agent",
"description": "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.",
"description": "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
"description": "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.",
Agent Card content changes infrequently relative to the frequency at which clients may fetch it. Servers and clients **SHOULD** use standard HTTP caching mechanisms to reduce unnecessary network overhead.
#### 8.6.1. Server Requirements
- Agent Card HTTP endpoints **SHOULD** include a `Cache-Control` response header with a `max-age` directive appropriate for the agent's expected update frequency
- Agent Card HTTP endpoints **SHOULD** include an `ETag` response header derived from the Agent Card's `version` field or a hash of the card content
- Agent Card HTTP endpoints **MAY** include a `Last-Modified` response header
#### 8.6.2. Client Requirements
- Clients **SHOULD** honor HTTP caching semantics as defined in [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) when fetching Agent Cards
- When a cached Agent Card has expired, clients **SHOULD** use conditional requests (`If-None-Match` with the stored `ETag`, or `If-Modified-Since`) to avoid re-downloading unchanged cards
- When the server does not include caching headers, clients **MAY** apply an implementation-specific default cache duration
A2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using standard HTTP request headers, as JSON-RPC 2.0 operates over HTTP(S).
**Service Parameter Requirements:**
- Service parameter names **MUST** be transmitted as HTTP header fields
- Service parameter keys are case-insensitive per HTTP specification (RFC 7230)
- Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single header field
JSON-RPC error responses use the standard [JSON-RPC 2.0 error object](https://www.jsonrpc.org/specification#error_object) structure, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:
- **Error Code**: Mapped to `error.code` (numeric JSON-RPC error code)
- **Error Message**: Mapped to `error.message` (human-readable string)
| `-32700` | `JSONParseError` | "Invalid JSON payload" | The server received invalid JSON |
| `-32600` | `InvalidRequestError` | "Request payload validation error" | The JSON sent is not a valid Request object |
| `-32601` | `MethodNotFoundError` | "Method not found" | The requested method does not exist or is not available |
| `-32602` | `InvalidParamsError` | "Invalid parameters" | The method parameters are invalid |
| `-32603` | `InternalError` | "Internal error" | An internal error occurred on the server |
**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)](#54-error-code-mappings).
Each object in the `data` array **MUST** include a `@type` key that identifies the object's type. Implementations **SHOULD** use well-known types such as `google.rpc.ErrorInfo` to refine error reporting, or `google.rpc.BadRequest` to attach structured data to validation errors. Additional error context **MAY** be included as further objects in the `data` array.
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](https://google.aip.dev/general) to simplify gRPC to HTTP mapping.
**Response:** See [`AgentCard`](#441-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.
gRPC error responses use the standard [gRPC status](https://grpc.io/docs/guides/error/) structure with [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto), which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:
- **Error Code**: Mapped to `status.code` (gRPC status code enum)
- **Error Message**: Mapped to `status.message` (human-readable string)
- **Error Details**: Mapped to `status.details` (repeated google.protobuf.Any messages)
**A2A Error Representation:**
For A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `status.details` array with:
-`reason`: The A2A error type in UPPER_SNAKE_CASE without the "Error" suffix (e.g., `TASK_NOT_FOUND`)
-`domain`: Set to `"a2a-protocol.org"`
-`metadata`: Optional map of additional error context
For the complete mapping of A2A error types to gRPC status codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings).
**Error Response Example:**
```proto
// Standard gRPC invalid argument error
status {
code: INVALID_ARGUMENT
message: "Invalid request parameters"
details: [
{
type: "type.googleapis.com/google.rpc.BadRequest"
field_violations: [
{
field: "message.parts"
description: "At least one part is required"
}
]
}
]
}
```
**Example A2A-Specific Error Response:**
```proto
// A2A-specific task not found error
status {
code: NOT_FOUND
message: "Task with ID 'task-123' not found"
details: [
{
type: "type.googleapis.com/google.rpc.ErrorInfo"
reason: "TASK_NOT_FOUND"
domain: "a2a-protocol.org"
metadata: {
task_id: "task-123"
timestamp: "2025-11-09T10:30:00Z"
}
}
]
}
```
### 10.7. Streaming
gRPC streaming uses server streaming RPCs for real-time updates. The `StreamResponse` message provides a union of possible streaming events:
### 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:**
| Protocol Buffer Field | Query Parameter Name | Example Usage |
- **Strings**: Passed directly as query parameter values
- **Booleans**: Represented as lowercase strings (`true`, `false`)
- **Numbers**: Represented as decimal strings
- **Enums**: Represented using their string values (e.g., `status=working`)
- **Repeated Fields**: Multiple values **MAY** be passed by repeating the parameter name (e.g., `?tag=value1&tag=value2`) or as comma-separated values (e.g., `?tag=value1,value2`)
- **Nested Objects**: Not supported in query parameters; operations requiring nested objects **MUST** use POST with a request body
HTTP error responses use the [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) JSON representation, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:
- **Error Details**: Mapped to the `error.details` array (array of objects, each containing a `@type` key, using ProtoJSON `Any` representation)
**Error Detail Objects:**
Each object in the `details` array **MUST** include a `@type` key that identifies the object's type. Implementations **SHOULD** use well-known types such as `google.rpc.BadRequest` to attach structured data to validation errors. Additional error context **MAY** be included as further objects in the `details` array.
Since multiple A2A error types may map to the same HTTP status code (e.g., `TaskNotCancelableError` and `PushNotificationNotSupportedError` both map to `400 Bad Request`), implementations **MUST** include a `google.rpc.ErrorInfo` object in the `details` array for A2A-specific errors with:
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)](#5-protocol-binding-requirements-and-interoperability). This section provides additional guidelines specific to developing custom bindings.
### 12.1. Binding Requirements
Custom protocol bindings **MUST**:
1.**Implement All Core Operations**: Support all operations defined in [Section 3 (A2A Protocol Operations)](#3-a2a-protocol-operations)
2.**Preserve Data Model**: Use data structures functionally equivalent to those defined in [Section 4 (Protocol Data Model)](#4-protocol-data-model)
3.**Maintain Semantics**: Ensure operations behave consistently with the abstract operation definitions
4.**Document Completely**: Provide comprehensive documentation of the binding specification
### 12.2. Data Type Mappings
Custom bindings **MUST** provide clear mappings for:
- **Protocol Buffer Types**: Define how each Protocol Buffer message type is represented
- **Timestamps**: Follow the conventions in [Section 5.6.1 (Timestamps)](#561-timestamps)
- **Binary Data**: Specify encoding for binary content (e.g., base64 for text-based protocols)
- **Enumerations**: Define representation of enum values (e.g., strings, integers)
### 12.3. Service Parameter Transmission
As specified in [Section 3.2.6 (Service Parameters)](#326-service-parameters), custom protocol bindings **MUST** document how service parameters are transmitted. The binding specification **MUST** address:
1.**Transmission Mechanism**: The protocol-specific method for transmitting service parameter key-value pairs
2.**Value Constraints**: Any limitations on service parameter values (e.g., character encoding, size limits)
3.**Reserved Names**: Any service parameter names reserved by the binding itself
4.**Fallback Strategy**: What happens when the protocol lacks native header support (e.g., passing service parameters in metadata)
**Example Documentation Requirements:**
- **For native header support**: "Service parameters are transmitted using HTTP request headers. Service parameter keys are case-insensitive and must conform to RFC 7230. Service parameter values must be UTF-8 strings."
- **For protocols without headers**: "Service parameters are serialized as a JSON object and transmitted in the request metadata field `a2a-service-parameters`."
### 12.4. Error Mapping
Custom bindings **MUST**:
1.**Map Standard Errors**: Provide mappings for all A2A-specific error types defined in [Section 3.2.2 (Error Handling)](#332-error-handling)
2.**Preserve Error Information**: Ensure error details are accessible to clients
3.**Use Appropriate Codes**: Map to protocol-native error codes where applicable
4.**Document Error Format**: Specify the structure of error responses
### 12.5. Streaming Support
If the binding supports streaming operations:
1.**Define Stream Mechanism**: Document how streaming is implemented (e.g., WebSockets, long-polling, chunked encoding)
2.**Event Ordering**: Specify ordering guarantees for streaming events
3.**Reconnection**: Define behavior for connection interruption and resumption
4.**Stream Termination**: Specify how stream completion is signaled
If streaming is not supported, the binding **MUST** clearly document this limitation in the Agent Card.
### 12.6. Authentication and Authorization
Custom bindings **MUST**:
1.**Support Standard Schemes**: Implement authentication schemes declared in the Agent Card
2.**Document Integration**: Specify how credentials are transmitted in the protocol
3.**Handle Challenges**: Define how authentication challenges are communicated
4.**Maintain Security**: Follow security best practices for the transport protocol
### 12.7. Agent Card Declaration
Custom bindings **MUST** be declared in the Agent Card:
1.**Test Against Reference**: Verify behavior matches standard bindings
2.**Document Differences**: Clearly note any deviations from standard binding behavior
3.**Provide Examples**: Include sample requests and responses
4.**Test Edge Cases**: Verify handling of error conditions, large payloads, and long-running tasks
## 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](./topics/enterprise-ready.md).
### 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:**
- Servers **MUST** implement authorization checks on every [A2A Protocol Operations](#3-a2a-protocol-operations) request
- Implementations **MUST** scope results to the caller's authorized access boundaries as defined by the agent's authorization model
- Even when `contextId` or other filter parameters are not specified in requests, implementations **MUST** scope results to the caller's authorized access boundaries
- Authorization models are agent-defined and **MAY** be based on:
- User identity (user-based authorization)
- Organizational roles or groups (role-based authorization)
- Project or workspace membership (project-based authorization)
- Organizational or tenant boundaries (multi-tenant authorization)
- Custom authorization logic specific to the agent's domain
**Operations Requiring Scope Limitation:**
- [`List Tasks`](#314-list-tasks): **MUST** only return tasks visible to the authenticated client according to the agent's authorization model
- [`Get Task`](#313-get-task): **MUST** verify the authenticated client has access to the requested task according to the agent's authorization model
- Task-related operations (Cancel, Subscribe, Push Notification Config): **MUST** verify the client has appropriate access rights according to the agent's authorization model
**Implementation Requirements:**
- Authorization boundaries are defined by each agent's authorization model, not prescribed by the protocol
- Authorization checks **MUST** occur before any database queries or operations that could leak information about the existence of resources outside the caller's authorization scope
- Agents **SHOULD** document their authorization model and access control policies
See also: [Section 3.1.4 List Tasks (Security Note)](#314-list-tasks) 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:**
- Agents **MUST** include authentication credentials in webhook requests as specified in [`PushNotificationConfig.authentication`](#432-authenticationinfo)
- Reject private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
- Reject localhost and link-local addresses
- Implement URL allowlists where appropriate
**Client (Webhook Receiver) Requirements:**
- Clients **MUST** validate webhook authenticity using the provided authentication credentials
- Clients **SHOULD** verify the task ID in the payload matches an expected task they created
- Clients **MUST** respond with HTTP 2xx status codes to acknowledge successful receipt
- Clients **SHOULD** process notifications idempotently, as duplicate deliveries may occur
- Clients **SHOULD** implement rate limiting to prevent webhook flooding
- Clients **SHOULD** use HTTPS endpoints for webhook URLs to ensure confidentiality
**Configuration Security:**
- Webhook URLs **SHOULD** use HTTPS to protect payload confidentiality in transit
- Authentication tokens in [`PushNotificationConfig`](#431-pushnotificationconfig) **SHOULD** be treated as secrets and rotated periodically
- Agents **SHOULD** securely store push notification configurations and credentials
- Clients **SHOULD** use unique, single-purpose tokens for each push notification configuration
See also: [Section 4.3 Push Notification Objects](#43-push-notification-objects) and [Section 4.3.3 Push Notification Payload](#433-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:**
- The [`Get Extended Agent Card`](#3111-get-extended-agent-card) operation **MUST** require authentication
- Agents **MUST** authenticate requests using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields
- Agents **MAY** return different extended card content based on the authenticated client's identity or authorization level
- Agents **SHOULD** implement appropriate caching headers to control client-side caching of extended cards
**Capability-Based Access:**
- Extended cards **MAY** include additional skills not present in the public card
- Extended cards **MAY** expose more detailed capability information (e.g., rate limits, quotas)
- Extended cards **MAY** include organization-specific or user-specific configuration
- Agents **SHOULD** document which capabilities are available at different authentication levels
**Security Considerations:**
- Extended cards **SHOULD NOT** include sensitive information that could be exploited if leaked (e.g., internal service URLs, unmasked credentials)
- Agents **MUST** validate that clients have appropriate permissions before returning privileged information in extended cards
- Clients retrieving extended cards **SHOULD** replace their cached public Agent Card with the extended version for the duration of their authenticated session
- Agents **SHOULD** version extended cards appropriately and honor client cache invalidation
- When support is declared but no extended card is configured, the operation **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling)
See also: [Section 3.1.11 Get Extended Agent Card](#3111-get-extended-agent-card) and [Section 3.3.4 Capability Validation](#334-capability-validation).
### 13.4. General Security Best Practices
**Transport 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
- Agents **SHOULD** enforce HSTS (HTTP Strict Transport Security) headers when using HTTP-based bindings
- Implementations **SHOULD** disable support for deprecated SSL/TLS versions (SSLv3, TLS 1.0, TLS 1.1)
**Input Validation:**
- Agents **MUST** validate all input parameters before processing
- Agents **SHOULD** implement appropriate limits on message sizes, file sizes, and request complexity
- Agents **SHOULD** sanitize or validate file content types and reject unexpected media types
**Credential Management:**
- API keys, tokens, and other credentials **MUST** be treated as secrets
- Credentials **SHOULD** be rotated periodically
- Credentials **SHOULD** be transmitted only over encrypted connections
- Agents **SHOULD** provide audit trails for sensitive operations
- Logs **MUST NOT** include sensitive information (credentials, personal data) unless required and properly protected
**Rate Limiting and Abuse Prevention:**
- Agents **SHOULD** implement rate limiting on all operations
- Agents **SHOULD** return appropriate error responses when rate limits are exceeded
- Agents **MAY** implement different rate limits for different operations or user tiers
**Data Privacy:**
- Agents **MUST** comply with applicable data protection regulations
- Agents **SHOULD** provide mechanisms for users to request deletion of their data
- Agents **SHOULD** implement appropriate data retention policies
- Agents **SHOULD** minimize logging of sensitive or personal information
**Custom Binding Security:**
- Custom protocol bindings **MUST** address security considerations in their specification
- Custom bindings **SHOULD** follow the same security principles as standard bindings
- Custom bindings **MUST** document authentication integration and credential transmission
See also: [Section 12.6 Authentication and Authorization (Custom Bindings)](#126-authentication-and-authorization).
## 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:**
- None
**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:
- Content MUST be validated against the A2A protocol schema before processing
- Implementations MUST sanitize user-provided content to prevent injection attacks
- File references within A2A messages MUST be validated to prevent server-side request forgery (SSRF)
- Authentication and authorization MUST be enforced as specified in Section 7 of the A2A specification
- Sensitive information in task history and artifacts MUST be protected according to applicable data protection regulations
**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:**
- **Deprecated alias names for this type:** None
- **Magic number(s):** None
- **File extension(s):** .a2a.json
- **Macintosh file type code(s):** TEXT
**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](#326-service-parameters). 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:**
```text
A2A-Version: 0.3
```
#### 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.
**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:**
- The Agent Card MAY contain public information about an agent's capabilities and SHOULD NOT include sensitive credentials or internal implementation details
- Implementations SHOULD support HTTPS to ensure authenticity and integrity of the Agent Card
- Agent Cards MAY be signed using JSON Web Signatures (JWS) as specified in the AgentCardSignature object (Section 4.4.7)
- Clients SHOULD verify signatures when present to ensure the Agent Card has not been tampered with
- Extended Agent Cards retrieved via authenticated endpoints (Section 3.1.11) MAY contain additional information and MUST enforce appropriate access controls
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.
| Legacy Name | Current Name | Earliest Removal Version | Notes |
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:
- Prefer new names immediately for all new integrations.
- Implement dual-handling where schemas/types permit (e.g., union type or backward-compatible decoder).
- Log a warning when receiving legacy-named objects after the first deprecation announcement release.
Server Implementations MAY:
- Accept both legacy and current request message forms during the overlap period.
- Emit only current form in responses (recommended) while providing explicit upgrade notes.
**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:
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:
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:
- Reduces redundancy (no need for both a field name and a `kind` value)
- Aligns JSON-RPC and gRPC representations more closely
- Simplifies code generation from schema definitions
- Eliminates the need for representing inheritance structures in schema languages
- Improves type safety in strongly-typed languages
All optional features enabling specific operations (`streaming`, `pushNotifications`, `stateTransitionHistory`) reside in `AgentCapabilities`. Moving `extendedAgentCard` achieves:
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:
- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/):** Focuses on standardizing how AI models and agents connect to and interact with **tools, APIs, data sources, and other external resources.** It defines structured ways to describe tool capabilities (like function calling in LLMs), pass inputs, and receive structured outputs. Think of MCP as the "how-to" for an agent to *use* a specific capability or access a resource.
- **Agent2Agent Protocol (A2A):** Focuses on standardizing how independent, often opaque, **AI agents communicate and collaborate with each other as peers.** A2A provides an application-level protocol for agents to discover each other, negotiate interaction modalities, manage shared tasks, and exchange conversational context or complex results. It's about how agents *partner* or *delegate* work.
**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](./topics/a2a-and-mcp.md).