# Agent2Agent (A2A) Protocol Specification (DRAFT v1.0) {% macro render_spec_tabs(region_tag) %} === "JSON-RPC" ```ts { .no-copy } --8<-- "types/src/types.ts:{{ region_tag }}" ``` === "gRPC" ```proto { .no-copy } --8<-- "specification/grpc/a2a.proto:{{ region_tag }}" ``` {% endmacro %} ??? note "**Latest Released Version** [`0.3.0`](https://a2a-protocol.org/v0.3.0/specification)" **Previous Versions** - [`0.2.6`](https://a2a-protocol.org/v0.2.6/specification) - [`0.2.5`](https://a2a-protocol.org/v0.2.5/specification) - [`0.2.4`](https://a2a-protocol.org/v0.2.4/specification) - [`0.2.0`](https://a2a-protocol.org/v0.2.0/specification) - [`0.1.0`](https://a2a-protocol.org/v0.1.0/specification) See [Release Notes](https://github.com/a2aproject/A2A/releases) 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: - Discover each other's capabilities. - Negotiate interaction modalities (text, files, structured data). - Manage collaborative tasks. - 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. ### 1.2. Guiding Principles - **Simple:** Reuse existing, well-understood standards (HTTP, JSON-RPC 2.0, Server-Sent Events). - **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). ### 1.3. Specification Structure This specification is organized into three distinct layers that work together to provide a complete protocol definition: ```mermaid graph TB subgraph L1 ["A2A Data Model"] direction LR A[Task] ~~~ B[Message] ~~~ C[AgentCard] ~~~ D[Part] ~~~ E[Artifact] ~~~ F[Extension] end subgraph L2 ["A2A Operations"] direction LR G[Send Message] ~~~ H[Stream Message] ~~~ I[Get Task] ~~~ J[List Tasks] ~~~ K[Cancel Task] ~~~ L[Get Agent Card] end subgraph L3 ["Protocol Bindings"] direction LR M[JSON-RPC Methods] ~~~ N[gRPC RPCs] ~~~ O[HTTP/REST Endpoints] ~~~ P[Custom Bindings] end %% Dependencies between layers L1 --> L2 L2 --> L3 style A fill:#e1f5fe style B fill:#e1f5fe style C fill:#e1f5fe style D fill:#e1f5fe style E fill:#e1f5fe style F fill:#e1f5fe style G fill:#f3e5f5 style H fill:#f3e5f5 style I fill:#f3e5f5 style J fill:#f3e5f5 style K fill:#f3e5f5 style L fill:#f3e5f5 style M fill:#e8f5e8 style N fill:#e8f5e8 style O fill:#e8f5e8 style L1 fill:#f0f8ff,stroke:#333,stroke-width:2px style L2 fill:#faf0ff,stroke:#333,stroke-width:2px style L3 fill:#f0fff0,stroke:#333,stroke-width:2px ``` **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. - Documentation: This specification MUST include a Migration Appendix (Appendix A) enumerating legacy→current name mappings with planned removal versions. - 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. ## 2. Terminology ### 2.1. Requirements Language The key words "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). ### 2.2. Core Concepts A2A revolves around several key concepts. For detailed explanations, please refer to the [Key Concepts guide](./topics/key-concepts.md). - **A2A Client:** An application or agent that initiates requests to an A2A Server on behalf of a user or another system. - **A2A Server (Remote Agent):** An agent or agentic system that exposes an A2A-compliant endpoint, processing tasks and providing responses. - **Agent Card:** A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements. - **Message:** A communication turn between a client and a remote agent, having a `role` ("user" or "agent") and containing one or more `Parts`. - **Task:** The fundamental unit of work managed by A2A, identified by a unique ID. Tasks are stateful and progress through a defined lifecycle. - **Part:** The smallest unit of content within a Message or Artifact (e.g., `TextPart`, `FilePart`, `DataPart`). - **Artifact:** An output (e.g., a document, image, structured data) generated by the agent as a result of a task, composed of `Parts`. - **Streaming:** Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via protocol-specific streaming mechanisms. - **Push Notifications:** Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios. - **Context:** An optional, server-generated identifier to logically group related tasks. - **Extension:** A mechanism for agents to provide additional functionality or data beyond the core A2A specification. ## 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)](#53-method-mapping-reference). For detailed protocol-specific implementation details, see: - [Section 9: JSON-RPC Protocol Binding](#9-json-rpc-protocol-binding) - [Section 10: gRPC Protocol Binding](#10-grpc-protocol-binding) - [Section 11: HTTP+JSON/REST Protocol Binding](#11-httpjsonrest-protocol-binding) #### 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:** - [`SendMessageRequest`](#321-sendmessagerequest): Request object containing the message, configuration, and metadata **Outputs:** - [`Task`](#411-task): A task object representing the processing of the message, OR - [`Message`](#414-message): A direct response message (for simple interactions that don't require task tracking) **Errors:** - [`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. **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`](#411-task) is returned. #### 3.1.2. Stream Message Similar to Send Message but with real-time streaming of updates during processing. **Inputs:** - [`SendMessageRequest`](#321-sendmessagerequest): Request object containing the message, configuration, and metadata **Outputs:** - 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 - Final completion indicator **Errors:** - [`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. **Behavior:** The operation MUST establish a streaming connection for real-time updates. The stream MUST follow one of these patterns: 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, cancelled, 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:** - `taskId`: Unique identifier of the task to retrieve - `historyLength` (optional): Number of recent messages to include in the task's history (see [History Length Semantics](#324-history-length-semantics) for details) **Outputs:** - [`Task`](#411-task): Current state and artifacts of the requested task **Errors:** - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. #### 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:** - `contextId` (optional): Filter tasks by context ID to get tasks from a specific conversation or session - `status` (optional): Filter tasks by their current status state - `pageSize` (optional): Maximum number of tasks to return (must be between 1 and 100, defaults to 50) - `pageToken` (optional): Token for pagination from a previous response - `historyLength` (optional): Number of recent messages to include in each task's history (see [History Length Semantics](#324-history-length-semantics) for details, defaults to 0) - `lastUpdatedAfter` (optional): Filter tasks updated after this timestamp (milliseconds since epoch) - `includeArtifacts` (optional): Whether to include artifacts in returned tasks (defaults to false) - [`metadata`](#325-metadata) (optional): Request-specific metadata for extensions or custom parameters 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:** - `tasks`: Array of [`Task`](#411-task) objects matching the specified criteria - `totalSize`: Total number of tasks available (before pagination) - `pageSize`: Maximum number of tasks returned in this response - `nextPageToken`: Token for retrieving the next page of results (empty if no more results) 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](#131-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 last update 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:** - `taskId`: Unique identifier of the task to cancel **Outputs:** - Updated [`Task`](#411-task) with cancellation status **Errors:** - [`TaskNotCancelableError`](#332-error-handling): The task is not in a cancelable state (e.g., already completed, failed, or canceled). - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. **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:** - `taskId`: Unique identifier of the task to monitor **Outputs:** - [Stream Response](#323-stream-response) object containing: - Initial response: [`Task`](#411-task) object with current state - Stream of [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) and [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects **Errors:** - [`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`, `cancelled`, or `rejected`). **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`, `cancelled`, 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. Set or Update Push Notification Config Creates or updates a push notification configuration for a task to receive asynchronous updates via webhook. **Inputs:** - `taskId`: Unique identifier of the task to configure notifications for - [`PushNotificationConfig`](#431-pushnotificationconfig): Configuration specifying webhook URL and notification preferences **Outputs:** - [`PushNotificationConfig`](#431-pushnotificationconfig): Created configuration with assigned ID **Errors:** - [`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. **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`](#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. #### 3.1.8. Get Push Notification Config Retrieves an existing push notification configuration for a task. **Inputs:** - `taskId`: Unique identifier of the task - `configId`: Unique identifier of the push notification configuration **Outputs:** - [`PushNotificationConfig`](#431-pushnotificationconfig): The requested configuration **Errors:** - [`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. **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:** - `taskId`: Unique identifier of the task **Outputs:** - Array of [`PushNotificationConfig`](#431-pushnotificationconfig) objects **Errors:** - [`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. **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:** - `taskId`: Unique identifier of the task - `configId`: Unique identifier of the push notification configuration to delete **Outputs:** - Confirmation of deletion (implementation-specific) **Errors:** - [`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. **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.supportsAuthenticatedExtendedCard` is `true`. **Inputs:** - None (no parameters required) **Outputs:** - [`AgentCard`](#441-agentcard): A complete Agent Card object, which may contain additional details or skills not present in the public card **Errors:** - [`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. **Behavior:** - **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. - **Availability**: This operation is only available if the public Agent Card declares `supportsAuthenticatedExtendedCard: true`. For detailed security guidance on extended agent cards, see [Section 13.3 Extended Agent Card Access Control](#133-extended-agent-card-access-control). ### 3.2. Operation Parameter Objects This section defines common parameter objects used across multiple operations. #### 3.2.1. SendMessageRequest Request object for sending messages to an agent. ```proto --8<-- "specification/grpc/a2a.proto:SendMessageRequest" ``` **Fields:** - **`request`** (required): The [`Message`](#414-message) object to send to the agent. - **`configuration`** (optional): [`SendMessageConfiguration`](#322-sendmessageconfiguration) object containing options for this request. - **`metadata`** (optional): A flexible key-value map for passing additional context or parameters. See [Metadata](#325-metadata) for details. #### 3.2.2. SendMessageConfiguration Configuration options for message sending operations. ```proto --8<-- "specification/grpc/a2a.proto:SendMessageConfiguration" ``` **Fields:** - **`acceptedOutputModes`** (optional): A list of media types the client is prepared to accept in the response. Agents SHOULD use this to tailor their output format. - **`historyLength`** (optional): Number of recent messages from the task's history to include in the response. See [History Length Semantics](#324-history-length-semantics) for details. - **`pushNotificationConfig`** (optional): Configuration for the agent to send push notifications for task updates. See [PushNotificationConfig](#431-pushnotificationconfig) for details. - **`blocking`** (optional): If `true`, the operation waits until the task reaches a terminal state before returning. Default is `false`. **Blocking vs Non-Blocking Execution:** The `blocking` field in [`SendMessageConfiguration`](#322-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, cancelled, rejected) before returning. The response MUST include the final 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](#313-get-task), subscribe via [Subscribe to Task](#316-subscribe-to-task), or receive updates via push notifications. The `blocking` field has no effect: - when the operation returns a direct [`Message`](#414-message) response instead of a task. - for streaming operations, which always return updates in real-time. - on configured push notification configurations, which operates independently of blocking mode. #### 3.2.3. Stream Response A wrapper object used in streaming operations to encapsulate different types of response data. ```proto --8<-- "specification/grpc/a2a.proto:StreamResponse" ``` **Fields (exactly one of the following):** - **task**: A [`Task`](#411-task) object containing the current state of the task - **message**: A [`Message`](#414-message) object containing a message in the conversation - **taskStatusUpdateEvent**: A [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) object indicating a change in task status - **taskArtifactUpdateEvent**: A [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) object indicating updates to task artifacts 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: - **Unset/undefined**: No limit imposed; server returns its default amount of history (implementation-defined, may be all history) - **0**: No history should be returned; the `history` field SHOULD be omitted - **> 0**: Return at most this many recent messages from the task's history #### 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`](#46-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:** | Header Name | Description | Example Value | | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- | | `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-`. ### 3.3. Operation Semantics #### 3.3.1. Idempotency - **Get operations** (Get Task, List Tasks, Get Extended Agent Card) are naturally idempotent - **Send Message** operations MAY be idempotent. Agents may utilize the messageId to detect duplicate messages. - **Cancel Task** operations are idempotent - multiple cancellation requests have the same effect. A duplicate cancellation request MAY return `TaskNotFoundError` if a the task has already been canceled and purged. #### 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 - Servers **MUST** reject requests with invalid or missing authentication credentials - Servers **SHOULD** include authentication challenge information in the error response - Servers **SHOULD** specify which authentication scheme is required - Example error codes: HTTP `401 Unauthorized`, gRPC `UNAUTHENTICATED`, JSON-RPC custom error - Example scenarios: Missing bearer token, expired API key, invalid OAuth token - **Authorization Errors**: Insufficient permissions for requested operation - Servers **MUST** return an authorization error when the authenticated client lacks required permissions - Servers **SHOULD** indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access) - Servers **MUST NOT** reveal the existence of resources the client is not authorized to access - Example error codes: HTTP `403 Forbidden`, gRPC `PERMISSION_DENIED`, JSON-RPC custom error - Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes - **Validation Errors**: Invalid input parameters or message format - Servers **MUST** validate all input parameters before processing - Servers **SHOULD** specify which parameter(s) failed validation and why - Servers **SHOULD** provide guidance on valid parameter values or formats - Example error codes: HTTP `400 Bad Request`, gRPC `INVALID_ARGUMENT`, JSON-RPC `-32602 Invalid params` - Example scenarios: Invalid task ID format, missing required message parts, unsupported content type - **Resource Errors**: Requested task not found or not accessible - Servers **MUST** return a not found error when a requested resource does not exist or is not accessible to the authenticated client - Servers **SHOULD NOT** distinguish between "does not exist" and "not authorized" to prevent information leakage - Example error codes: HTTP `404 Not Found`, gRPC `NOT_FOUND`, JSON-RPC custom error (see A2A-specific errors) - Example scenarios: Task ID does not exist, task has been deleted, configuration not found - **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 **Error Payload Structure:** All error responses in the A2A protocol, regardless of binding, **MUST** convey the following information: 1. **Error Code**: A machine-readable identifier for the error type (e.g., string code, numeric code, or protocol-specific status) 2. **Error Message**: A human-readable description of the error 3. **Error Details** (optional): Additional structured information about the error, such as: - Affected fields or parameters - Contextual information (e.g., task ID, timestamp) - Suggestions for resolution 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). **A2A-Specific Errors:** | Error Name | Description | | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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` | Client 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. | #### 3.3.3. Asynchronous Processing 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)). #### 3.3.4. Capability Validation 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 (Set, 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.supportsAuthenticatedExtendedCard` 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 client 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). 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`](#411-task) and [`Message`](#414-message) objects, providing continuity across a series of interactions. **Generation and Assignment:** - Agents **MUST** generate a new `contextId` when processing a [`Message`](#414-message) that does not include a `contextId` field - The generated `contextId` **MUST** be included in the response (either [`Task`](#411-task) or [`Message`](#414-message)) - Agents **MUST** accept and preserve client-provided `contextId` values in subsequent messages within the same conversation - `contextId` values **SHOULD** be treated as opaque identifiers by clients **Grouping and Scope:** - 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 #### 3.4.2. Multi-Turn Conversation Patterns The A2A protocol supports several patterns for multi-turn interactions: **Context Continuity:** - [`Task`](#411-task) objects maintain conversation context through the `contextId` field - Clients **MAY** include the `contextId` in subsequent messages to indicate continuation of a previous interaction - Clients **MAY** combine `contextId` with `taskId` references to continue or refine a specific task - Clients **MAY** use `contextId` without `taskId` to start a new task within an existing conversation context **Input Required State:** - Agents can request additional input mid-processing by transitioning a task to the `input-required` state - The client continues the interaction by sending a new message with the same `taskId` and `contextId` **Follow-up Messages:** - Clients can send additional messages with `taskId` references to continue or refine existing tasks - Clients **SHOULD** use the `referenceTaskIds` field in [`Message`](#414-message) to explicitly reference related tasks - Agents **SHOULD** use referenced tasks to understand the context and intent of follow-up requests **Context Inheritance:** - New tasks created within the same `contextId` can inherit context from previous interactions - Agents **SHOULD** leverage the shared `contextId` to provide contextually relevant responses ### 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):** - Client periodically calls Get Task ([Section 3.1.3](#313-get-task)) to check task status - Simple to implement, works with all protocol bindings - Higher latency, potential for unnecessary requests - Best for: Simple integrations, infrequent updates, clients behind restrictive firewalls **Streaming:** - Real-time delivery of events as they occur - Operations: Stream Message ([Section 3.1.2](#312-stream-message)) and Subscribe to Task ([Section 3.1.6](#316-subscribe-to-task)) - Low latency, efficient for frequent updates - Requires persistent connection support - Best for: Interactive applications, real-time dashboards, live progress monitoring - Requires `AgentCard.capabilities.streaming` to be `true` **Push Notifications (WebHooks):** - Agent sends HTTP POST requests to client-registered endpoints when task state changes - Client does not maintain persistent connection - Asynchronous delivery, client must be reachable via HTTP - Best for: Server-to-server integrations, long-running tasks, event-driven architectures - Operations: Set ([Section 3.1.7](#75-taskspushnotificationconfigset)), Get ([Section 3.1.8](#76-taskspushnotificationconfigget)), List ([Section 3.1.9](#319-list-push-notification-configs)), Delete ([Section 3.1.10](#3110-delete-push-notification-config)) - Event types: TaskStatusUpdateEvent ([Section 4.2.1](#421-taskstatusupdateevent)), TaskArtifactUpdateEvent ([Section 4.2.2](#422-taskartifactupdateevent)), WebHook payloads ([Section 4.3](#43-push-notification-objects)) - 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. When multiple streams are active for a task: - Events MUST be broadcast to all active streams for that task - Each stream MUST receive the same events in the same order - Closing one stream MUST NOT affect other active streams for the same task - The task lifecycle is independent of any individual stream's lifecycle This capability enables scenarios such as: - 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). ### 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 do not affect protocol compatibility, SHOULD NOT be included in requests and responses, and MUST not be considered when clients and servers negotiate protocol versions. Agents declare support for latest supported protocol version in the `protocolVersion` field in the Agent Card. Agents MAY also support earlier protocol versions. Clients SHOULD specify the desired protocol version in requests using the `A2A-Version` header. If the requested version is not supported by the agent, the agent MUST return a `VersionNotSupportedError`. It is RECOMMENDED that clients send the `A2A-Version` header with each request to reduce the chances of being broken if an agent upgrades to a new version of the protocol. Sending the `A2A-Version` header provides visibility to agents about version usage in the ecosystem, which can help inform the risks of inplace version upgrades. ## 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 Represents the stateful unit of work being processed by the A2A Server for an A2A Client. ```proto --8<-- "specification/grpc/a2a.proto:Task" ``` **Fields:** - **`id`** (required, string): Unique identifier (e.g. UUID) for the task, generated by the server for a new task. - **`contextId`** (required, string): Unique identifier (e.g. UUID) for the contextual collection of interactions (tasks and messages). Created by the A2A server. - **`status`** (required, [`TaskStatus`](#412-taskstatus)): The current status of a Task, including state and an optional message. - **`artifacts`** (optional, array of [`Artifact`](#419-artifact)): A set of output artifacts for a Task. - **`history`** (optional, array of [`Message`](#414-message)): The history of interactions from a task. - **`metadata`** (optional, object): A key/value object to store custom metadata about a task. #### 4.1.2. TaskStatus Represents the current state and associated context of a Task. ```proto --8<-- "specification/grpc/a2a.proto:TaskStatus" ``` **Fields:** - **`state`** (required, [`TaskState`](#413-taskstate)): The current state of this task. - **`message`** (optional, [`Message`](#414-message)): A message associated with the status, providing context or updates about the current state. - **`timestamp`** (optional, string): Timestamp when the status was recorded, in ISO 8601 format (e.g., "2025-10-28T10:30:00Z"). #### 4.1.3. TaskState Defines the possible lifecycle states of a Task. ```proto --8<-- "specification/grpc/a2a.proto:TaskState" ``` **JSON Values:** - **`submitted`**: Represents the status that acknowledges a task is created. - **`working`**: Represents the status that a task is actively being processed. - **`completed`**: Represents the status that a task is finished. This is a terminal state. - **`failed`**: Represents the status that a task is done but failed. This is a terminal state. - **`cancelled`**: Represents the status that a task was cancelled before it finished. This is a terminal state. - **`input-required`**: Represents the status that the task requires information to complete. This is an interrupted state. - **`rejected`**: Represents the status that the agent has decided to not perform the task. This may be done during initial task creation or later once an agent has determined it can't or won't proceed. This is a terminal state. - **`auth-required`**: Represents the state that some authentication is needed from the upstream client. Authentication is expected to come out-of-band thus this is not an interrupted or terminal state. #### 4.1.4. Message Represents a single communication turn between a client and an agent. ```proto --8<-- "specification/grpc/a2a.proto:Message" ``` **Fields:** - **`messageId`** (required, string): The unique identifier (e.g. UUID) of the message. This is created by the message creator. - **`contextId`** (optional, string): The context id of the message. If set, the message will be associated with the given context. - **`taskId`** (optional, string): The task id of the message. If set, the message will be associated with the given task. - **`role`** (required, [`Role`](#415-role)): The role of the message sender (user or agent). - **`parts`** (required, array of [`Part`](#416-part)): The container of the message content. Must contain at least one part. - **`metadata`** (optional, object): Any optional metadata to provide along with the message. - **`extensions`** (optional, array of strings): The URIs of extensions that are present or contributed to this Message. - **`referenceTaskIds`** (optional, array of strings): A list of task IDs that this message references for additional context. #### 4.1.5. Role Defines the sender of a message in the A2A protocol communication. ```proto --8<-- "specification/grpc/a2a.proto:Role" ``` **JSON Values:** - **`user`**: Indicates communication from the client to the server. - **`agent`**: Indicates communication from the server to the client. #### 4.1.6. Part Represents a distinct piece of content within a Message or Artifact. ```proto --8<-- "specification/grpc/a2a.proto:Part" ``` **Fields:** A Part contains exactly one of the following content types: - **`text`** (string): Plain text content. - **`file`** ([`FilePart`](#417-filepart)): File-based content (image, document, etc.). - **`data`** ([`DataPart`](#418-datapart)): Structured JSON data. Additionally: - **`metadata`** (optional, object): Optional metadata associated with this part. #### 4.1.7. FilePart Represents file-based content within a Part. ```proto --8<-- "specification/grpc/a2a.proto:FilePart" ``` **Fields:** A FilePart contains exactly one of the following: - **`fileWithUri`** (string): URI reference to the file location. - **`fileWithBytes`** (bytes): The file content as base64-encoded bytes. Additionally: - **`mediaType`** (optional, string): The media type of the file (e.g., "application/pdf", "image/png"). - **`name`** (optional, string): The filename. #### 4.1.8. DataPart Represents structured JSON data within a Part. ```proto --8<-- "specification/grpc/a2a.proto:DataPart" ``` **Fields:** - **`data`** (required, object): A structured JSON object containing arbitrary data. #### 4.1.9. Artifact Represents a tangible output generated by the agent during a task. ```proto --8<-- "specification/grpc/a2a.proto:Artifact" ``` **Fields:** - **`artifactId`** (required, string): Unique identifier (e.g. UUID) for the artifact. It must be at least unique within a task. - **`name`** (optional, string): A human readable name for the artifact. - **`description`** (optional, string): A human readable description of the artifact. - **`parts`** (required, array of [`Part`](#416-part)): The content of the artifact. Must contain at least one part. - **`metadata`** (optional, object): Optional metadata included with the artifact. - **`extensions`** (optional, array of strings): The URIs of extensions that are present or contributed to this Artifact. ### 4.2. Streaming Events #### 4.2.1. TaskStatusUpdateEvent Carries information about a change in task status during streaming. ```proto --8<-- "specification/grpc/a2a.proto:TaskStatusUpdateEvent" ``` **Fields:** - **`taskId`** (required, string): The id of the task that is changed. - **`contextId`** (required, string): The id of the context that the task belongs to. - **`status`** (required, [`TaskStatus`](#412-taskstatus)): The new status of the task. - **`final`** (required, boolean): Whether this is the last status update expected for this task. - **`metadata`** (optional, object): Optional metadata to associate with the task update. #### 4.2.2. TaskArtifactUpdateEvent Carries a new or updated artifact generated during streaming. ```proto --8<-- "specification/grpc/a2a.proto:TaskArtifactUpdateEvent" ``` **Fields:** - **`taskId`** (required, string): The id of the task for this artifact. - **`contextId`** (required, string): The id of the context that this task belongs to. - **`artifact`** (required, [`Artifact`](#419-artifact)): The artifact itself. - **`append`** (optional, boolean): Whether this should be appended to a prior artifact produced. - **`lastChunk`** (optional, boolean): Whether this represents the last part of an artifact. - **`metadata`** (optional, object): Optional metadata associated with the artifact update. ### 4.3. Push Notification Objects #### 4.3.1. PushNotificationConfig Configuration for setting up push notifications for task updates. ```proto --8<-- "specification/grpc/a2a.proto:PushNotificationConfig" ``` **Fields:** - **`id`** (optional, string): A unique identifier (e.g. UUID) for this push notification. - **`url`** (required, string): URL to send the notification to. - **`token`** (optional, string): Token unique for this task/session. - **`authentication`** (optional, [`AuthenticationInfo`](#432-authenticationinfo)): Information about the authentication to send with the notification. #### 4.3.2. AuthenticationInfo Defines authentication details for push notifications. ```proto --8<-- "specification/grpc/a2a.proto:PushNotificationAuthenticationInfo" ``` **Fields:** - **`schemes`** (required, array of strings): Supported authentication schemes (e.g., "Basic", "Bearer"). - **`credentials`** (optional, string): Optional credentials string. #### 4.3.3. Push Notification Payload update-push-notification-payload-section-number 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. **Request Format:** ```http POST {webhook_url} Authorization: {authentication_scheme} {credentials} Content-Type: application/json { /* StreamResponse object - one of: */ "task": { /* Task object */ }, "message": { /* Message object */ }, "statusUpdate": { /* TaskStatusUpdateEvent object */ }, "artifactUpdate": { /* TaskArtifactUpdateEvent object */ } } ``` **Payload Structure:** The webhook payload is a [`StreamResponse`](#323-stream-response) object containing exactly one of the following: - **task**: A [`Task`](#411-task) object with the current task state - **message**: A [`Message`](#414-message) object containing a message response - **statusUpdate**: A [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) indicating a status change - **artifactUpdate**: A [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) indicating artifact updates **Authentication:** 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.). **Client Responsibilities:** - Clients MUST respond with HTTP 2xx status codes to acknowledge successful receipt - Clients SHOULD process notifications idempotently, as duplicate deliveries may occur - Clients MUST validate the task ID matches an expected task - Clients SHOULD implement appropriate security measures to verify the notification source **Server Guarantees:** - Agents MUST attempt delivery at least once for each configured webhook - Agents MAY implement retry logic with exponential backoff for failed deliveries - Agents SHOULD include a reasonable timeout for webhook requests (recommended: 10-30 seconds) - Agents MAY stop attempting delivery after a configured number of consecutive failures For detailed security guidance on push notifications, see [Section 13.2 Push Notification Security](#132-push-notification-security). ### 4.4. Agent Discovery Objects #### 4.4.1. AgentCard The primary metadata document describing an agent's capabilities and interface. ```proto --8<-- "specification/grpc/a2a.proto:AgentCard" ``` **Fields:** - **`protocolVersion`** (required, string): The version of the A2A protocol this agent supports (e.g., "1.0"). Defaults to "1.0". - **`name`** (required, string): A human readable name for the agent. - **`description`** (required, string): A human-readable description of the agent, assisting users and other agents in understanding its purpose. - **`supportedInterfaces`** (optional, array of [`AgentInterface`](#446-agentinterface)): An ordered list of supported interfaces (protocol binding and URL combinations). The first item in the list is the preferred interface that clients should use when possible. Clients can select any interface from this list based on their preferences, but SHOULD prefer earlier entries when multiple options are supported. - **`provider`** (optional, [`AgentProvider`](#442-agentprovider)): The service provider of the agent. - **`version`** (required, string): The version of the agent (e.g., "1.0.0"). - **`documentationUrl`** (optional, string): A URL to provide additional documentation about the agent. - **`capabilities`** (required, [`AgentCapabilities`](#443-agentcapabilities)): A2A capability set supported by the agent. - **`securitySchemes`** (optional, map of string to [`SecurityScheme`](#451-securityscheme)): The security scheme details used for authenticating with this agent. - **`security`** (optional, array of Security): Security requirements for contacting the agent. - **`defaultInputModes`** (required, array of strings): The set of interaction modes that the agent supports across all skills, defined as media types. - **`defaultOutputModes`** (required, array of strings): The media types supported as outputs from this agent. - **`skills`** (required, array of [`AgentSkill`](#445-agentskill)): Skills represent units of ability an agent can perform. - **`supportsAuthenticatedExtendedCard`** (optional, boolean): Whether the agent supports providing an extended agent card when authenticated. - **`signatures`** (optional, array of [`AgentCardSignature`](#447-agentcardsignature)): JSON Web Signatures computed for this AgentCard. - **`iconUrl`** (optional, string): An optional URL to an icon for the agent. #### 4.4.2. AgentProvider Information about the organization providing the agent. ```proto --8<-- "specification/grpc/a2a.proto:AgentProvider" ``` **Fields:** - **`url`** (required, string): A URL for the agent provider's website or relevant documentation. - **`organization`** (required, string): The name of the agent provider's organization. #### 4.4.3. AgentCapabilities Defines optional A2A protocol features supported by the agent. ```proto --8<-- "specification/grpc/a2a.proto:AgentCapabilities" ``` **Fields:** - **`streaming`** (optional, boolean): Indicates if the agent supports streaming responses. - **`pushNotifications`** (optional, boolean): Indicates if the agent supports sending push notifications for asynchronous task updates. - **`extensions`** (optional, array of [`AgentExtension`](#444-agentextension)): A list of protocol extensions supported by the agent. - **`stateTransitionHistory`** (optional, boolean): Indicates if the agent provides a history of state transitions for a task. #### 4.4.4. AgentExtension Specifies a protocol extension supported by the agent. ```proto --8<-- "specification/grpc/a2a.proto:AgentExtension" ``` **Fields:** - **`uri`** (optional, string): The unique URI identifying the extension. - **`description`** (optional, string): A human-readable description of how this agent uses the extension. - **`required`** (optional, boolean): If true, the client must understand and comply with the extension's requirements. - **`params`** (optional, object): Optional, extension-specific configuration parameters. #### 4.4.5. AgentSkill Describes a specific capability or area of expertise the agent can perform. ```proto --8<-- "specification/grpc/a2a.proto:AgentSkill" ``` **Fields:** - **`id`** (required, string): A unique identifier for the agent's skill. - **`name`** (required, string): A human-readable name for the skill. - **`description`** (required, string): A detailed description of the skill. - **`tags`** (required, array of strings): A set of keywords describing the skill's capabilities. - **`examples`** (optional, array of strings): Example prompts or scenarios that this skill can handle. - **`inputModes`** (optional, array of strings): The set of supported input media types for this skill, overriding the agent's defaults. - **`outputModes`** (optional, array of strings): The set of supported output media types for this skill, overriding the agent's defaults. - **`security`** (optional, array of Security): Security schemes necessary for this skill. #### 4.4.6. AgentInterface Declares additional protocols supported by the agent. ```proto --8<-- "specification/grpc/a2a.proto:AgentInterface" ``` **Fields:** - **`url`** (required, string): The URL where this interface is available. Must be a valid absolute HTTPS URL in production. - **`protocolBinding`** (required, string): The protocol binding supported at this URL. Examples: "JSONRPC", "GRPC", "HTTP+JSON". #### 4.4.7. AgentCardSignature Represents a JSON Web Signature for Agent Card verification. ```proto --8<-- "specification/grpc/a2a.proto:AgentCardSignature" ``` **Fields:** - **`protected`** (required, string): The protected JWS header for the signature. This is always a base64url-encoded JSON object. - **`signature`** (required, string): The computed signature, base64url-encoded. - **`header`** (optional, object): The unprotected JWS header values. ### 4.5. Security Objects #### 4.5.1. SecurityScheme Base security scheme definition supporting multiple authentication types. ```proto --8<-- "specification/grpc/a2a.proto:SecurityScheme" ``` **Fields:** A SecurityScheme contains exactly one of the following authentication types: - **`apiKeySecurityScheme`** ([`APIKeySecurityScheme`](#452-apikeysecurityscheme)): API key-based authentication. - **`httpAuthSecurityScheme`** ([`HTTPAuthSecurityScheme`](#453-httpauthsecurityscheme)): HTTP authentication (Basic, Bearer, etc.). - **`oauth2SecurityScheme`** ([`OAuth2SecurityScheme`](#454-oauth2securityscheme)): OAuth 2.0 authentication. - **`openIdConnectSecurityScheme`** ([`OpenIdConnectSecurityScheme`](#455-openidconnectsecurityscheme)): OpenID Connect authentication. - **`mtlsSecurityScheme`** ([`MutualTLSSecurityScheme`](#456-mutualtlssecurityscheme)): Mutual TLS authentication. #### 4.5.2. APIKeySecurityScheme API key-based authentication scheme. ```proto --8<-- "specification/grpc/a2a.proto:APIKeySecurityScheme" ``` **Fields:** - **`description`** (optional, string): An optional description for the security scheme. - **`location`** (required, string): The location of the API key. Valid values are "query", "header", or "cookie". - **`name`** (required, string): The name of the header, query, or cookie parameter to be used. #### 4.5.3. HTTPAuthSecurityScheme HTTP authentication scheme (Basic, Bearer, etc.). ```proto --8<-- "specification/grpc/a2a.proto:HTTPAuthSecurityScheme" ``` **Fields:** - **`description`** (optional, string): An optional description for the security scheme. - **`scheme`** (required, string): The name of the HTTP Authentication scheme to be used in the Authorization header, as defined in RFC7235 (e.g., "Bearer"). This value should be registered in the IANA Authentication Scheme registry. - **`bearerFormat`** (optional, string): A hint to the client to identify how the bearer token is formatted (e.g., "JWT"). This is primarily for documentation purposes. #### 4.5.4. OAuth2SecurityScheme OAuth 2.0 authentication scheme. ```proto --8<-- "specification/grpc/a2a.proto:OAuth2SecurityScheme" ``` **Fields:** - **`description`** (optional, string): An optional description for the security scheme. - **`flows`** (required, OAuthFlows): An object containing configuration information for the supported OAuth 2.0 flows. - **`oauth2MetadataUrl`** (optional, string): URL to the OAuth2 authorization server metadata per RFC8414. TLS is required. #### 4.5.5. OpenIdConnectSecurityScheme OpenID Connect authentication scheme. ```proto --8<-- "specification/grpc/a2a.proto:OpenIdConnectSecurityScheme" ``` **Fields:** - **`description`** (optional, string): An optional description for the security scheme. - **`openIdConnectUrl`** (required, string): The OpenID Connect Discovery URL for the OIDC provider's metadata. #### 4.5.6. MutualTLSSecurityScheme Mutual TLS authentication scheme. ```proto --8<-- "specification/grpc/a2a.proto:MutualTLSSecurityScheme" ``` **Fields:** - **`description`** (optional, string): An optional description for the security scheme. ### 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`](#441-agentcard) using the `extensions` field, which contains an array of [`AgentExtension`](#444-agentextension) objects. *Example: Agent declaring extension support in AgentCard:* ```json { "protocolVersion": "0.3.0", "name": "Research Assistant Agent", "description": "AI agent for academic research and fact-checking", "supportedInterfaces": [ { "url": "https://research-agent.example.com/a2a/v1", "protocolBinding": "HTTP+JSON" } ], "capabilities": { "streaming": false, "pushNotifications": false, "extensions": [ { "uri": "https://standards.org/extensions/citations/v1", "description": "Provides citation formatting and source verification", "required": false }, { "uri": "https://example.com/extensions/geolocation/v1", "description": "Location-based search capabilities", "required": false } ] }, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [ { "id": "academic-research", "name": "Academic Research Assistant", "description": "Provides research assistance with citations and source verification", "tags": ["research", "citations", "academic"], "examples": ["Find peer-reviewed articles on climate change"], "inputModes": ["text/plain"], "outputModes": ["text/plain"] } ] } ``` 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:* ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/json Authorization: Bearer token A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 { "message": { "role": "user", "parts": [{"text": "Find restaurants near me"}], "extensions": ["https://example.com/extensions/geolocation/v1"], "metadata": { "https://example.com/extensions/geolocation/v1": { "latitude": 37.7749, "longitude": -122.4194 } } } } ``` #### 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:* ```json { "role": "user", "parts": [ {"text": "Find restaurants near me"} ], "extensions": ["https://example.com/extensions/geolocation/v1"], "metadata": { "https://example.com/extensions/geolocation/v1": { "latitude": 37.7749, "longitude": -122.4194, "accuracy": 10.0, "timestamp": "2025-10-21T14:30:00Z" } } } ``` **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:* ```json { "artifactId": "research-summary-001", "name": "Climate Change Summary", "parts": [ { "text": "Global temperatures have risen by 1.1°C since pre-industrial times, with significant impacts on weather patterns and sea levels." } ], "extensions": ["https://standards.org/extensions/citations/v1"], "metadata": { "https://standards.org/extensions/citations/v1": { "sources": [ { "title": "Global Temperature Anomalies - 2023 Report", "authors": ["Smith, J.", "Johnson, M."], "url": "https://climate.gov/reports/2023-temperature", "accessDate": "2025-10-21", "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 - **Same Error Handling**: Map errors consistently using appropriate protocol-specific codes - **Equivalent Authentication**: Support the same authentication schemes declared in the AgentCard ### 5.2. Protocol Selection and Negotiation - **Agent Declaration**: Agents **MUST** declare all supported protocols in their AgentCard - **Client Choice**: Clients **MAY** choose any protocol declared by the agent - **No Dynamic Negotiation**: A2A does not define runtime protocol negotiation - **Fallback Behavior**: Clients **SHOULD** implement fallback logic for alternative protocols ### 5.3. Method Mapping Reference | Functionality | JSON-RPC Method | gRPC Method | REST Endpoint | | :------------------------------ | :--------------------------------- | :--------------------------------- | :--------------------------------------------------------- | | Send message | `SendMessage` | `SendMessage` | `POST /v1/message:send` | | Stream message | `SendStreamingMessage` | `SendStreamingMessage` | `POST /v1/message:stream` | | Get task | `GetTask` | `GetTask` | `GET /v1/tasks/{id}` | | List tasks | `ListTasks` | `ListTasks` | `GET /v1/tasks` | | Cancel task | `CancelTask` | `CancelTask` | `POST /v1/tasks/{id}:cancel` | | Subscribe to task | `SubscribeToTask` | `SubscribeToTask` | `POST /v1/tasks/{id}:subscribe` | | Set push notification config | `SetTaskPushNotificationConfig` | `SetTaskPushNotificationConfig` | `POST /v1/tasks/{id}/pushNotificationConfigs` | | Get push notification config | `GetTaskPushNotificationConfig` | `GetTaskPushNotificationConfig` | `GET /v1/tasks/{id}/pushNotificationConfigs/{configId}` | | List push notification configs | `ListTaskPushNotificationConfig` | `ListTaskPushNotificationConfig` | `GET /v1/tasks/{id}/pushNotificationConfigs` | | Delete push notification config | `DeleteTaskPushNotificationConfig` | `DeleteTaskPushNotificationConfig` | `DELETE /v1/tasks/{id}/pushNotificationConfigs/{configId}` | | Get extended Agent Card | `GetExtendedAgentCard` | `GetExtendedAgentCard` | `GET /v1/extendedAgentCard` | ### 5.4. Error Code Mappings 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: | A2A Error Type | JSON-RPC Code | gRPC Status | HTTP Status | HTTP Type URI | | :------------------------------------ | :------------ | :-------------------- | :--------------------------- | :------------------------------------------------------------------- | | `TaskNotFoundError` | `-32001` | `NOT_FOUND` | `404 Not Found` | `https://a2a-protocol.org/errors/task-not-found` | | `TaskNotCancelableError` | `-32002` | `FAILED_PRECONDITION` | `409 Conflict` | `https://a2a-protocol.org/errors/task-not-cancelable` | | `PushNotificationNotSupportedError` | `-32003` | `UNIMPLEMENTED` | `400 Bad Request` | `https://a2a-protocol.org/errors/push-notification-not-supported` | | `UnsupportedOperationError` | `-32004` | `UNIMPLEMENTED` | `400 Bad Request` | `https://a2a-protocol.org/errors/unsupported-operation` | | `ContentTypeNotSupportedError` | `-32005` | `INVALID_ARGUMENT` | `415 Unsupported Media Type` | `https://a2a-protocol.org/errors/content-type-not-supported` | | `InvalidAgentResponseError` | `-32006` | `INTERNAL` | `502 Bad Gateway` | `https://a2a-protocol.org/errors/invalid-agent-response` | | `ExtendedAgentCardNotConfiguredError` | `-32007` | `FAILED_PRECONDITION` | `400 Bad Request` | `https://a2a-protocol.org/errors/extended-agent-card-not-configured` | | `ExtensionSupportRequiredError` | `-32008` | `FAILED_PRECONDITION` | `400 Bad Request` | `https://a2a-protocol.org/errors/extension-support-required` | | `VersionNotSupportedError` | `-32009` | `UNIMPLEMENTED` | `400 Bad Request` | `https://a2a-protocol.org/errors/version-not-supported` | **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: - [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. **Naming Convention:** - Protocol Buffer field: `protocol_version` → JSON field: `protocolVersion` - Protocol Buffer field: `context_id` → JSON field: `contextId` - Protocol Buffer field: `default_input_modes` → JSON field: `defaultInputModes` - Protocol Buffer field: `push_notification_config` → JSON field: `pushNotificationConfig` **Enum Values:** - Enum values **MUST** be represented as their string names in JSON, using lower [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) after removing any type name prefixes. **Examples:** - Protocol Buffer enum: `TASK_STATE_INPUT_REQUIRED` → JSON value: `input-required` - Protocol Buffer enum: `ROLE_USER` → JSON value: `user` ### 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`](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) ### 5.7. Field Presence and Optionality The Protocol Buffer definition in `specification/grpc/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. **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: 1. **Explicit Default Values:** Some fields in the specification define default values that differ from Protocol Buffer's implicit defaults (e.g., `protocolVersion` defaults to `"1.0"` rather than empty string). The `optional` keyword allows implementations to detect whether a value was explicitly provided or should use the specified default. 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. ## 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:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "user", "parts": [{"text": "What is the weather today?"}], "messageId": "msg-uuid" } } ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "task-uuid", "contextId": "context-uuid", "status": {"state": "completed"}, "artifacts": [{ "artifactId": "artifact-uuid", "name": "Weather Report", "parts": [{"text": "Today will be sunny with a high of 75°F"}] }] } } ``` ### 6.2. Streaming Task Execution **Scenario:** Client requests a long-running task with real-time updates. **Request:** ```http POST /v1/message:stream HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "user", "parts": [{"text": "Write a detailed report on climate change"}], "messageId": "msg-uuid" } } ``` **SSE Response Stream:** ```http HTTP/1.1 200 OK Content-Type: text/event-stream data: {"task": {"id": "task-uuid", "status": {"state": "working"}}} data: {"artifactUpdate": {"taskId": "task-uuid", "artifact": {"parts": [{"text": "# Climate Change Report\n\n"}]}}} data: {"statusUpdate": {"taskId": "task-uuid", "status": {"state": "completed"}, "final": true}} ``` ### 6.3. Multi-Turn Interaction **Scenario:** Agent requires additional input to complete a task. **Initial Request:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "user", "parts": [{"text": "Book me a flight"}], "messageId": "msg-1" } } ``` **Response (Input Required):** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "task-uuid", "status": { "state": "input-required", "message": { "role": "agent", "parts": [{"text": "I need more details. Where would you like to fly from and to?"}] } } } } ``` **Follow-up Request:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "taskId": "task-uuid", "role": "user", "parts": [{"text": "From San Francisco to New York"}], "messageId": "msg-2" } } ``` ### 6.4. Version Negotiation Error **Scenario:** Client requests an unsupported protocol version. **Request:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token A2A-Version: 0.5 { "message": { "role": "user", "parts": [{"text": "Hello"}], "messageId": "msg-uuid" } } ``` **Response:** ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json { "type": "https://a2a-protocol.org/errors/version-not-supported", "title": "Protocol Version Not Supported", "status": 400, "detail": "The requested A2A protocol version 0.5 is not supported by this agent", "supportedVersions": ["0.3"] } ``` ### 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:** ```http POST /v1/tasks/list HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "pageSize": 10, "historyLength": 3 } ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "tasks": [ { "id": "3f36680c-7f37-4a5f-945e-d78981fafd36", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "completed", "timestamp": "2024-03-15T10:15:00Z" } } ], "totalSize": 5, "pageSize": 10, "nextPageToken": "" } ``` #### Request: All working tasks across all contexts **Request:** ```http POST /v1/tasks/list HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "status": "working", "pageSize": 20 } ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "tasks": [ { "id": "789abc-def0-1234-5678-9abcdef01234", "contextId": "another-context-id", "status": { "state": "working", "message": { "role": "agent", "parts": [ { "text": "Processing your document analysis..." } ], "messageId": "msg-status-update" }, "timestamp": "2024-03-15T10:20:00Z" } } ], "totalSize": 1, "pageSize": 20, "nextPageToken": "" } ``` #### Pagination Example **Request:** ```http POST /v1/tasks/list HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "pageSize": 10, "pageToken": "base64-encoded-cursor-token" } ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "tasks": [ /* ... additional tasks */ ], "totalSize": 15, "pageSize": 10, "nextPageToken": "base64-encoded-next-cursor-token" } ``` #### Validation Error Example **Request:** ```http POST /v1/tasks/list HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "pageSize": 150, "historyLength": -5, "status": "running" } ``` **Response:** ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json { "status": 400, "detail": "Invalid parameters", "errors": [ { "field": "pageSize", "message": "Must be between 1 and 100 inclusive, got 150" }, { "field": "historyLength", "message": "Must be non-negative integer, got -5" }, { "field": "status", "message": "Invalid status value 'running'. Must be one of: pending, working, completed, failed, canceled" } ] } ``` ### 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:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "user", "parts": [ { "text": "Generate the Q1 sales report. This usually takes a while. Notify me when it's ready." } ], "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6" }, "configuration": { "pushNotificationConfig": { "url": "https://client.example.com/webhook/a2a-notifications", "token": "secure-client-token-for-task-aaa", "authentication": { "schemes": ["Bearer"] } } } } ``` **Response (Task Submitted):** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "43667960-d455-4453-b0cf-1bae4955270d", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "submitted", "timestamp": "2024-03-15T11:00:00Z" } } } ``` **Later: Server POSTs Notification to Webhook:** ```http POST /webhook/a2a-notifications HTTP/1.1 Host: client.example.com Authorization: Bearer server-generated-jwt Content-Type: application/a2a+json X-A2A-Notification-Token: secure-client-token-for-task-aaa { "statusUpdate": { "taskId": "43667960-d455-4453-b0cf-1bae4955270d", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "completed", "timestamp": "2024-03-15T18:30:00Z" }, "final": true } } ``` ### 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:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "user", "parts": [ { "text": "Analyze this image and highlight any faces." }, { "file": { "name": "input_image.png", "mediaType": "image/png", "fileWithBytes": "iVBORw0KGgoAAAANSUhEUgAAAAUA..." } } ], "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6" } } ``` **Response with File Reference:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "43667960-d455-4453-b0cf-1bae4955270d", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "completed", "timestamp": "2024-03-15T12:05:00Z" }, "artifacts": [ { "artifactId": "9b6934dd-37e3-4eb1-8766-962efaab63a1", "name": "processed_image_with_faces.png", "parts": [ { "file": { "name": "output.png", "mediaType": "image/png", "fileWithUri": "https://storage.example.com/processed/task-bbb/output.png?token=xyz" } } ] } ] } } ``` ### 6.8. Structured Data Exchange **Scenario:** Client asks for a list of open support tickets in a specific JSON format. **Request:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "user", "parts": [ { "text": "Show me a list of my open IT tickets", "metadata": { "mediaType": "application/json", "schema": { "type": "array", "items": { "type": "object", "properties": { "ticketNumber": { "type": "string" }, "description": { "type": "string" } } } } } } ], "messageId": "85b26db5-ffbb-4278-a5da-a7b09dea1b47" } } ``` **Response with Structured Data:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "d8c6243f-5f7a-4f6f-821d-957ce51e856c", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "completed", "timestamp": "2025-04-17T17:47:09.680794Z" }, "artifacts": [ { "artifactId": "c5e0382f-b57f-4da7-87d8-b85171fad17c", "parts": [ { "text": "[{\"ticketNumber\":\"REQ12312\",\"description\":\"request for VPN access\"},{\"ticketNumber\":\"REQ23422\",\"description\":\"Add to DL - team-gcp-onboarding\"}]" } ] } ] } } ``` ### 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:** ```http GET /.well-known/agent-card.json HTTP/1.1 Host: example.com ``` **Response includes:** ```json { "supportsAuthenticatedExtendedCard": true, "securitySchemes": { "google": { "openIdConnectSecurityScheme": { "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration" } } } } ``` ### Step 2: Client obtains credentials (out-of-band OAuth 2.0 flow) ### Step 3: Client fetches authenticated extended Agent Card ```http GET /v1/extendedAgentCard HTTP/1.1 Host: agent.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "protocolVersion": "0.3.0", "name": "Extended Agent with Additional Skills", "skills": [ /* 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. ### 7.3. Client Authentication Process 1. **Discovery of Requirements:** The client discovers the server's required authentication schemes via the `security_schemes` field in the AgentCard. 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. ### 7.5. In-Task Authentication (Secondary Credentials) If an agent requires additional credentials during task execution: 1. It **SHOULD** transition the A2A task to the `TASK_STATE_AUTH_REQUIRED` state. 2. The accompanying `TaskStatus.update` **SHOULD** provide details about the required secondary authentication. 3. The A2A Client obtains these credentials out-of-band and provides them in a subsequent message request. ### 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: - Specific skills requested - Actions attempted within tasks - Data access policies - OAuth scopes (if applicable) ## 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](./topics/agent-discovery.md). ### 8.2. Discovery Mechanisms Clients can find Agent Cards through: - **Well-Known URI:** Accessing `https://{server_domain}/.well-known/agent-card.json` - **Registries/Catalogs:** Querying curated catalogs of agents - **Direct Configuration:** Pre-configured Agent Card URLs or content ### 8.3. Protocol Declaration Requirements The AgentCard **MUST** properly declare supported protocols: #### 8.3.1. Supported Interfaces Declaration - The `supportedInterfaces` field **SHOULD** declare all supported protocol combinations in preference order - The first entry in `supportedInterfaces` represents the preferred interface - Each interface **MUST** accurately declare its transport protocol and URL - URLs **MAY** be reused if multiple transports are available at the same endpoint **Backward Compatibility:** For backward compatibility, agents **MAY** continue to populate the deprecated fields (`url`, `preferredTransport`, `additionalInterfaces`) alongside `supportedInterfaces`: - The `url` field **SHOULD** match the URL of the first entry in `supportedInterfaces` - The `preferredTransport` field **SHOULD** match the transport of the first entry in `supportedInterfaces` - The `additionalInterfaces` field **SHOULD** contain all entries from `supportedInterfaces` #### 8.3.2. Client Protocol Selection Clients **MUST** follow these rules: 1. **Modern Clients**: Parse `supportedInterfaces` if present, and select the first supported transport 2. **Legacy Clients**: Parse `url`/`preferredTransport` and `additionalInterfaces` for backward compatibility 3. Prefer earlier entries in the ordered list when multiple options are supported 4. Use the correct URL for the selected transport ### 8.4. Agent Card Signing 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) - `streaming`: false - optional field, present in JSON (explicitly set) → **include** - `pushNotifications`: false - optional field, present in JSON (explicitly set) → **include** - `extensions`: [] - repeated field (not REQUIRED) with empty array → **omit** - `skills`: [] - REQUIRED field → **include** After applying RFC 8785: ```json {"capabilities":{"pushNotifications":false,"streaming":false},"description":"","name":"Example Agent","skills":[]} ``` #### 8.4.2. Signature Format 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: - **`protected`** (required, string): Base64url-encoded JSON object containing the JWS Protected Header - **`signature`** (required, string): Base64url-encoded signature value - **`header`** (optional, object): JWS Unprotected Header as a JSON object (not base64url-encoded) **JWS Protected Header Parameters:** The protected header **MUST** include: - `alg`: Algorithm used for signing (e.g., "ES256", "RS256") - `typ`: **SHOULD** be set to "JOSE" for JWS - `kid`: Key ID for identifying the signing key The protected header **MAY** include: - `jku`: URL to JSON Web Key Set (JWKS) containing the public key **Signature Generation Process:** 1. **Prepare the payload:** - Remove properties with default values from the Agent Card - Exclude the `signatures` field - Canonicalize the resulting JSON using RFC 8785 to produce the canonical payload 2. **Create the protected header:** - Construct a JSON object with the required header parameters (`alg`, `typ`, `kid`) and any optional parameters (`jku`) - Serialize the header to JSON - Base64url-encode the serialized header to produce the `protected` field value 3. **Compute the signature:** - Construct the JWS Signing Input: `ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload))` - Sign the JWS Signing Input using the algorithm specified in the `alg` header parameter and the private key - Base64url-encode the resulting signature bytes to produce the `signature` field value 4. **Assemble the AgentCardSignature:** - Set `protected` to the base64url-encoded protected header from step 2 - Set `signature` to the base64url-encoded signature value from step 3 - Optionally set `header` to a JSON object containing any unprotected header parameters. **Example:** Given a canonical Agent Card payload and signing key, the signature generation produces: ```json { "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0", "signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ" } ``` Where the `protected` value decodes to: ```json {"alg":"ES256","typ":"JOSE","kid":"key-1","jku":"https://example.com/agent/jwks.json"} ``` #### 8.4.3. Signature Verification Clients verifying Agent Card signatures **MUST**: 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 { "protocolVersion": "0.3.0", "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.", "supportedInterfaces": [ {"url": "https://georoute-agent.example.com/a2a/v1", "protocolBinding": "JSONRPC"}, {"url": "https://georoute-agent.example.com/a2a/grpc", "protocolBinding": "GRPC"}, {"url": "https://georoute-agent.example.com/a2a/json", "protocolBinding": "HTTP+JSON"} ], "provider": { "organization": "Example Geo Services Inc.", "url": "https://www.examplegeoservices.com" }, "iconUrl": "https://georoute-agent.example.com/icon.png", "version": "1.2.0", "documentationUrl": "https://docs.examplegeoservices.com/georoute-agent/api", "capabilities": { "streaming": true, "pushNotifications": true, "stateTransitionHistory": false }, "securitySchemes": { "google": { "type": "openIdConnect", "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration" } }, "security": [{ "google": ["openid", "profile", "email"] }], "defaultInputModes": ["application/json", "text/plain"], "defaultOutputModes": ["application/json", "image/png"], "skills": [ { "id": "route-optimizer-traffic", "name": "Traffic-Aware Route Optimizer", "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).", "tags": ["maps", "routing", "navigation", "directions", "traffic"], "examples": [ "Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.", "{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}" ], "inputModes": ["application/json", "text/plain"], "outputModes": [ "application/json", "application/vnd.geo+json", "text/html" ] }, { "id": "custom-map-generator", "name": "Personalized Map Generator", "description": "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.", "tags": ["maps", "customization", "visualization", "cartography"], "examples": [ "Generate a map of my upcoming road trip with all planned stops highlighted.", "Show me a map visualizing all coffee shops within a 1-mile radius of my current location." ], "inputModes": ["application/json"], "outputModes": [ "image/png", "image/jpeg", "application/json", "text/html" ] } ], "supportsAuthenticatedExtendedCard": true, "signatures": [ { "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0", "signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ" } ] } ``` ## 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 - **Protocol:** JSON-RPC 2.0 over HTTP(S) - **Content-Type:** `application/json` for requests and responses - **Method Naming:** PascalCase method names matching gRPC conventions (e.g., `SendMessage`, `GetTask`) - **Streaming:** Server-Sent Events (`text/event-stream`) ### 9.2. Service Parameter Transmission 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 **Example Request with A2A Service Parameters:** ```http POST /rpc HTTP/1.1 Host: agent.example.com Content-Type: application/json Authorization: Bearer token A2A-Version: 0.3 A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 { "jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": { /* SendMessageRequest */ } } ``` ### 9.3. Base Request Structure All JSON-RPC requests **MUST** follow the standard JSON-RPC 2.0 format: ```json { "jsonrpc": "2.0", "id": "unique-request-id", "method": "category/action", "params": { /* method-specific parameters */ } } ``` ### 9.4. Core Methods #### 9.4.1. `SendMessage` Sends a message to initiate or continue a task. **Request:** ```json { "jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": { /* SendMessageRequest object */ } } ``` **Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest), [`Message`](#414-message) **Response:** ```json { "jsonrpc": "2.0", "id": 1, "result": { /* Task or Message object */ } } ``` **Referenced Objects:** [`Task`](#411-task), [`Message`](#414-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` ```text data: {"jsonrpc": "2.0", "id": 1, "result": { /* Task | Message | TaskArtifactUpdateEvent | TaskStatusUpdateEvent */ }} data: {"jsonrpc": "2.0", "id": 1, "result": { /* Task | Message | TaskArtifactUpdateEvent | TaskStatusUpdateEvent */ }} ``` Referenced Objects: [`Task`](#411-task), [`Message`](#414-message), [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent), [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) #### 9.4.3. `GetTask` Retrieves the current state of a task. **Request:** ```json { "jsonrpc": "2.0", "id": 2, "method": "GetTask", "params": { "id": "task-uuid", "historyLength": 10 } } ``` #### 9.4.4. `ListTasks` Lists tasks with optional filtering and pagination. **Request:** ```json { "jsonrpc": "2.0", "id": 3, "method": "ListTasks", "params": { "contextId": "context-uuid", "status": "working", "pageSize": 50, "pageToken": "cursor-token" } } ``` #### 9.4.5. `CancelTask` Cancels an ongoing task. **Request:** ```json { "jsonrpc": "2.0", "id": 4, "method": "CancelTask", "params": { "id": "task-uuid" } } ``` #### 9.4.6. `SubscribeToTask` Subscribes to a task stream for receiving updates on a task that is not in a terminal state. **Request:** ```json { "jsonrpc": "2.0", "id": 5, "method": "SubscribeToTask", "params": { "id": "task-uuid" } } ``` **Response:** SSE stream (same format as `SendStreamingMessage`) **Error:** Returns `UnsupportedOperationError` if the task is in a terminal state (`completed`, `failed`, `cancelled`, or `rejected`). #### 9.4.7. Push Notification Configuration Methods - `SetTaskPushNotificationConfig` - Set push notification configuration - `GetTaskPushNotificationConfig` - Get push notification configuration - `ListTaskPushNotificationConfig` - List push notification configurations - `DeleteTaskPushNotificationConfig` - Delete push notification configuration #### 9.4.8. `GetExtendedAgentCard` Retrieves an extended Agent Card. **Request:** ```json { "jsonrpc": "2.0", "id": 6, "method": "GetExtendedAgentCard" } ``` ### 9.5. Error Handling 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) - **Error Details**: Mapped to `error.data` (optional structured object) **Standard JSON-RPC Error Codes:** | JSON-RPC Error Code | Error Name | Standard Message | Description | | :------------------ | :-------------------- | :--------------------------------- | :------------------------------------------------------ | | `-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). **Error Response Structure:** ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found", "data": { "method": "invalid/method" } } } ``` **Example A2A-Specific Error Response:** ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": -32001, "message": "Task not found", "data": { "taskId": "nonexistent-task-id", "timestamp": "2025-11-09T10:30:00.000Z" } } } ``` 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](https://google.aip.dev/general) to simplify gRPC to HTTP mapping. ### 10.1. Protocol Requirements - **Protocol:** gRPC over HTTP/2 with TLS - **Definition:** Use the normative Protocol Buffers definition in `specification/grpc/a2a.proto` - **Serialization:** Protocol Buffers version 3 - **Service:** Implement the `A2AService` gRPC service ### 10.2. Service Parameter Transmission A2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using gRPC metadata (headers). **Service Parameter Requirements:** - Service parameter names **MUST** be transmitted as gRPC metadata keys - Metadata keys are case-insensitive and automatically converted to lowercase by gRPC - Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single metadata entry **Example gRPC Request with A2A Service Parameters:** ```go // Go example using gRPC metadata md := metadata.Pairs( "authorization", "Bearer token", "a2a-version", "0.3", "a2a-extensions", "https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1", ) ctx := metadata.NewOutgoingContext(context.Background(), md) // Make the RPC call with the context containing metadata response, err := client.SendMessage(ctx, request) ``` **Metadata Handling:** - Implementations **MUST** extract A2A service parameters from gRPC metadata for processing - Servers **SHOULD** validate required service parameters (e.g., `A2A-Version`) from metadata - Service parameter keys in metadata are normalized to lowercase per gRPC conventions ### 10.3. Service Definition ```proto service A2AService { rpc SendMessage(SendMessageRequest) returns (SendMessageResponse); rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse); rpc GetTask(GetTaskRequest) returns (Task); rpc ListTasks(ListTasksRequest) returns (ListTasksResponse); rpc CancelTask(CancelTaskRequest) returns (Task); rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse); rpc SetTaskPushNotificationConfig(SetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig); rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig); rpc ListTaskPushNotificationConfig(ListTaskPushNotificationConfigRequest) returns (ListTaskPushNotificationConfigResponse); rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (google.protobuf.Empty); rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard); } ``` ### 10.4. Core Methods #### 10.4.1. SendMessage Sends a message to an agent. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:SendMessageRequest" ``` **Response:** ```proto --8<-- "specification/grpc/a2a.proto:SendMessageResponse" ``` #### 10.4.2. SendStreamingMessage Sends a message with streaming updates. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:SendMessageRequest" ``` **Response:** Server streaming [`StreamResponse`](#stream-response) objects. #### 10.4.3. GetTask Retrieves task status. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:GetTaskRequest" ``` **Response:** See [`Task`](#411-task) object definition. #### 10.4.4. ListTasks Lists tasks with filtering. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:ListTasksRequest" ``` **Response:** ```proto --8<-- "specification/grpc/a2a.proto:ListTasksResponse" ``` #### 10.4.5. CancelTask Cancels a running task. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:CancelTaskRequest" ``` **Response:** See [`Task`](#411-task) object definition. #### 10.4.6. SubscribeToTask Subscribe to task updates via streaming. Returns `UnsupportedOperationError` if the task is in a terminal state. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:SubscribeToTaskRequest" ``` **Response:** Server streaming [`StreamResponse`](#stream-response) objects. #### 10.4.7. SetTaskPushNotificationConfig Creates a push notification configuration for a task. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:SetTaskPushNotificationConfigRequest" ``` **Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition. #### 10.4.8. GetTaskPushNotificationConfig Retrieves an existing push notification configuration for a task. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:GetTaskPushNotificationConfigRequest" ``` **Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition. #### 10.4.9. ListTaskPushNotificationConfig Lists all push notification configurations for a task. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:ListTaskPushNotificationConfigRequest" ``` **Response:** ```proto --8<-- "specification/grpc/a2a.proto:ListTaskPushNotificationConfigResponse" ``` #### 10.4.10. DeleteTaskPushNotificationConfig Removes a push notification configuration for a task. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:DeleteTaskPushNotificationConfigRequest" ``` **Response:** `google.protobuf.Empty` #### 10.4.11. GetExtendedAgentCard Retrieves the agent's extended capability card after authentication. **Request:** ```proto --8<-- "specification/grpc/a2a.proto:GetExtendedAgentCardRequest" ``` **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. ```proto --8<-- "specification/grpc/a2a.proto:TaskPushNotificationConfig" ``` **Fields:** - **`name`** (required, string): Resource name in the format "tasks/{taskId}/pushNotificationConfigs/{configId}". - **`pushNotificationConfig`** (required, [`PushNotificationConfig`](#431-pushnotificationconfig)): The push notification configuration. ### 10.6. Error Handling 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: ```proto --8<-- "specification/grpc/a2a.proto:StreamResponse" ``` ## 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 - **Protocol:** HTTP(S) with JSON payloads - **Content-Type:** `application/json` for requests and responses - **Methods:** Standard HTTP verbs (GET, POST, PUT, DELETE) - **URL Patterns:** RESTful resource-based URLs - **Streaming:** Server-Sent Events for real-time updates ### 11.2. Service Parameter Transmission A2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using standard HTTP request headers. **Service Parameter Requirements:** - Service parameter names **MUST** be transmitted as HTTP header fields - Service parameter keys are case-insensitive per HTTP specification (RFC 9110) - Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single header field **Example Request with A2A Service Parameters:** ```http POST /v1/message:send HTTP/1.1 Host: agent.example.com Content-Type: application/json Authorization: Bearer token A2A-Version: 0.3 A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 { "message": { "role": "user", "parts": [{"text": "Find restaurants near me"}] } } ``` ### 11.3. URL Patterns and HTTP Methods #### 11.3.1. Message Operations - `POST /v1/message:send` - Send message - `POST /v1/message:stream` - Send message with streaming (SSE response) #### 11.3.2. Task Operations - `GET /v1/tasks/{id}` - Get task status - `GET /v1/tasks` - List tasks (with query parameters) - `POST /v1/tasks/{id}:cancel` - Cancel task - `POST /v1/tasks/{id}:subscribe` - Subscribe to task updates (SSE response, returns error for terminal tasks) #### 11.3.3. Push Notification Configuration - `POST /v1/tasks/{id}/pushNotificationConfigs` - Create configuration - `GET /v1/tasks/{id}/pushNotificationConfigs/{configId}` - Get configuration - `GET /v1/tasks/{id}/pushNotificationConfigs` - List configurations - `DELETE /v1/tasks/{id}/pushNotificationConfigs/{configId}` - Delete configuration #### 11.3.4. Agent Card - `GET /v1/extendedAgentCard` - Get authenticated extended Agent Card ### 11.4. Request/Response Format All requests and responses use JSON objects structurally equivalent to the Protocol Buffer definitions. **Example Send Message:** ```http POST /v1/message:send Content-Type: application/json { "message": { "messageId": "uuid", "role": "user", "parts": [{"text": "Hello"}] }, "configuration": { "acceptedOutputModes": ["text/plain"] } } ``` **Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest), [`Message`](#414-message) **Response:** ```http HTTP/1.1 200 OK Content-Type: application/json { "task": { "id": "task-uuid", "contextId": "context-uuid", "status": { "state": "completed" } } } ``` **Referenced Objects:** [`Task`](#411-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:** | Protocol Buffer Field | Query Parameter Name | Example Usage | | --------------------- | -------------------- | ------------------- | | `context_id` | `contextId` | `?contextId=uuid` | | `page_size` | `pageSize` | `?pageSize=50` | | `page_token` | `pageToken` | `?pageToken=cursor` | | `task_id` | `taskId` | `?taskId=uuid` | **Usage Examples:** List tasks with filtering: ```http GET /v1/tasks?contextId=uuid&status=working&pageSize=50&pageToken=cursor ``` Get task with history: ```http GET /v1/tasks/{id}?historyLength=10 ``` **Field Type Handling:** - **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 **URL Encoding:** All query parameter values **MUST** be properly URL-encoded per [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html). ### 11.6. Error Handling HTTP error responses use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) format with `Content-Type: application/problem+json`, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows: - **Error Code**: Mapped to `status` (HTTP status code) and `type` (URI identifier) - **Error Message**: Mapped to `detail` (human-readable string) - **Error Details**: Mapped to extension fields in the problem details object **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)](#54-error-code-mappings). Additional error context **MAY** be included as extension fields in the problem details object. **Error Response Example:** ```http HTTP/1.1 404 Not Found Content-Type: application/problem+json { "type": "https://a2a-protocol.org/errors/task-not-found", "title": "Task Not Found", "status": 404, "detail": "The specified task ID does not exist or is not accessible", "taskId": "task-123", "timestamp": "2025-11-09T10:30:00.000Z" } ``` 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: ```http POST /v1/message:stream Content-Type: application/json { /* SendMessageRequest object */ } ``` **Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest) **Response:** ```http HTTP/1.1 200 OK Content-Type: text/event-stream data: {"task": { /* Task object */ }} data: {"artifactUpdate": { /* TaskArtifactUpdateEvent */ }} data: {"statusUpdate": { /* TaskStatusUpdateEvent */ }} ``` **Referenced Objects:** [`Task`](#411-task), [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent), [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) 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. **Transport Identifier**: Use a clear, descriptive transport name 2. **Endpoint URL**: Provide the full URL where the binding is available 3. **Documentation Link**: Include a URL to the complete binding specification **Example:** ```json { "supportedInterfaces": [ { "url": "wss://agent.example.com/a2a/websocket", "protocolBinding": "WEBSOCKET" } ] } ``` ### 12.8. Interoperability Testing Custom binding implementers **SHOULD**: 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) - Agents **SHOULD** implement reasonable timeout values for webhook requests (recommended: 10-30 seconds) - Agents **SHOULD** implement retry logic with exponential backoff for failed deliveries - Agents **MAY** stop attempting delivery after a configured number of consecutive failures - Agents **SHOULD** validate webhook URLs to prevent SSRF (Server-Side Request Forgery) attacks: - 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 **Availability Declaration:** - Agents declare extended card support via `AgentCard.supportsAuthenticatedExtendedCard` - When `supportsAuthenticatedExtendedCard` is `false` or not present, the operation **MUST** return [`UnsupportedOperationError`](#332-error-handling) - 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** implement credential revocation mechanisms - Agents **SHOULD** log authentication failures and implement rate limiting to prevent brute-force attacks **Audit and Monitoring:** - Agents **SHOULD** log security-relevant events (authentication failures, authorization denials, suspicious requests) - Agents **SHOULD** implement monitoring for unusual patterns (rapid task creation, excessive cancellations) - 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: **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, **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. **Example:** ```text A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 ``` ### 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:** - 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 **Example:** ```text https://agent.example.com/.well-known/agent-card.json ``` --- ## 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. | Legacy Name | Current Name | Earliest Removal Version | Notes | | ----------------------------------------------- | ----------------------------------------- | ------------------------ | ------------------------------------------------------ | | `MessageSendParams` | `SendMessageRequest` | >= 0.5.0 | Request payload rename for clarity (request vs params) | | `SendMessageSuccessResponse` | `SendMessageResponse` | >= 0.5.0 | Unified success response naming | | `SendStreamingMessageSuccessResponse` | `StreamResponse` | >= 0.5.0 | Shorter, binding-agnostic streaming response | | `SetTaskPushNotificationConfigRequest` | `CreateTaskPushNotificationConfigRequest` | >= 0.5.0 | Explicit creation intent | | `ListTaskPushNotificationConfigSuccessResponse` | `ListTaskPushNotificationConfigResponse` | >= 0.5.0 | Consistent response suffix removal | | `GetAuthenticatedExtendedCardRequest` | `GetExtendedAgentCardRequest` | >= 0.5.0 | Removed "Authenticated" from naming | Planned Lifecycle (example timeline; adjust per release strategy): 1. 0.3.x: New names introduced; legacy names documented; aliases added. 2. 0.4.x: Legacy names marked "deprecated" in SDKs and schemas; warning notes added. 3. ≥0.5.0: Legacy names eligible for removal after review; migration appendix updated. ### 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: - 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. #### 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:** ```json { "kind": "TextPart", "text": "Hello, world!" } ``` **Example 2 - FilePart:** ```json { "kind": "FilePart", "mimeType": "image/png", "name": "diagram.png", "fileWithBytes": "iVBORw0KGgo..." } ``` **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:** ```json { "text": "Hello, world!" } ``` **Example 2 - FilePart:** ```json { "file": { "mediaType": "image/png", "name": "diagram.png", "fileWithBytes": "iVBORw0KGgo..." } } ``` **Affected Types:** 1. **Part Union Types**: - **TextPart**: - **Legacy:** `{ "kind": "TextPart", "text": "..." }` - **Current:** `{ "text": "..." }` (direct string value) - **FilePart**: - **Legacy:** `{ "kind": "FilePart", "mimeType": "...", "name": "...", "fileWithBytes": "..." }` - **Current:** `{ "file": { "mediaType": "...", "name": "...", "fileWithBytes": "..." } }` - **DataPart**: - **Legacy:** `{ "kind": "DataPart", "data": {...} }` - **Current:** `{ "data": { "data": {...} } }` 2. **Streaming Event Types**: - **TaskStatusUpdateEvent**: - **Legacy:** `{ "kind": "TaskStatusUpdateEvent", "taskId": "...", "status": {...} }` - **Current:** `{ "statusUpdate": { "taskId": "...", "status": {...} } }` - **TaskArtifactUpdateEvent**: - **Legacy:** `{ "kind": "TaskArtifactUpdateEvent", "taskId": "...", "artifact": {...} }` - **Current:** `{ "artifactUpdate": { "taskId": "...", "artifact": {...} } }` **Migration Strategy:** For **Clients** upgrading from pre-0.3.x: 1. Update parsers to expect wrapper objects with member names as discriminators 2. When constructing requests, use the new wrapper format 3. Implement version detection based on the agent's `protocolVersion` in the `AgentCard` 4. Consider maintaining backward compatibility by detecting and handling both formats during a transition period For **Servers** upgrading from pre-0.3.x: 1. Update serialization logic to emit wrapper objects 2. **Breaking:** The `kind` field is no longer part of the protocol and should not be emitted 3. Update deserialization to expect wrapper objects with member names 4. Ensure the `AgentCard` declares the correct `protocolVersion` (1.0 or later) **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: - 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 ### 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: - **[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). ---