`.
- **Server-Side Validation**: The A2A server **must** authenticate every
incoming request using the credentials provided in the HTTP headers.
- If authentication fails or credentials are missing, the server **should**
respond with a standard HTTP status code:
- `401 Unauthorized`: If the credentials are missing or invalid. This
response **should** include a `WWW-Authenticate` header to inform
the client about the supported authentication methods.
- `403 Forbidden`: If the credentials are valid, but the authenticated
client does not have permission to perform the requested action.
- **In-Task Authentication (Secondary Credentials)**: If an agent needs
additional credentials to access a different system or service during a
task (for example, to use a specific tool on the user's behalf), the A2A server
indicates to the client that more information is needed. The client
is then responsible for obtaining these secondary credentials through a
process outside of the A2A protocol itself (for example, an OAuth flow) and
providing them back to the A2A server to continue the task.
## Authorization
Once a client is authenticated, the A2A server is responsible for authorizing
the request. Authorization logic is specific to the agent's implementation,
the data it handles, and applicable enterprise policies.
- **Granular Control**: Authorization **should** be applied based on the
authenticated identity, which could represent an end user, a client
application, or both.
- **Skill-Based Authorization**: Access can be controlled on a per-skill
basis, as advertised in the Agent Card. For example, specific OAuth scopes
**should** grant an authenticated client access to invoke certain skills but
not others.
- **Data and Action-Level Authorization**: Agents that interact with backend
systems, databases, or tools **must** enforce appropriate authorization before
performing sensitive actions or accessing sensitive data through those
underlying resources. The agent acts as a gatekeeper.
- **Principle of Least Privilege**: Agents **must** grant only the necessary
permissions required for a client or user to perform their intended
operations through the A2A interface.
## Data Privacy and Confidentiality
Protecting sensitive data exchanged between agents is paramount, requiring
strict adherence to privacy regulations and best practices.
- **Sensitivity Awareness**: Implementers must be acutely aware of the
sensitivity of data exchanged in Message and Artifact parts of A2A
interactions.
- **Compliance**: Ensure compliance with relevant data privacy regulations
such as GDPR, CCPA, and HIPAA, based on the domain and data involved.
- **Data Minimization**: Avoid including or requesting unnecessarily sensitive
information in A2A exchanges.
- **Secure Handling**: Protect data both in transit, using TLS as mandated,
and at rest if persisted by agents, according to enterprise data security
policies and regulatory requirements.
## Tracing, Observability, and Monitoring
A2A's reliance on HTTP allows for straightforward integration with standard
enterprise tracing, logging, and monitoring tools, providing critical visibility
into inter-agent workflows.
- **Distributed Tracing**: A2A Clients and Servers **should** participate in
distributed tracing systems. For example, use OpenTelemetry to propagate
trace context, including trace IDs and span IDs, through standard HTTP
headers, such as W3C Trace Context headers. This enables end-to-end
visibility for debugging and performance analysis.
- **Comprehensive Logging**: Log details on both client and server, including
taskId, sessionId, correlation IDs, and trace context for troubleshooting
and auditing.
- **Metrics**: A2A servers should expose key operational metrics, such as
request rates, error rates, task processing latency, and resource
utilization, to enable performance monitoring, alerting, and capacity
planning.
- **Auditing**: Audit significant events, such as task creation, critical
state changes, and agent actions, especially when involving sensitive data
or high-impact operations.
## API Management and Governance
For A2A servers exposed externally, across organizational boundaries, or even within
large enterprises, integration with API Management solutions is highly recommended,
as this provides:
- **Centralized Policy Enforcement**: Consistent application of security
policies such as authentication and authorization, rate limiting, and quotas.
- **Traffic Management**: Load balancing, routing, and mediation.
- **Analytics and Reporting**: Insights into agent usage, performance, and
trends.
- **Developer Portals**: Facilitate discovery of A2A-enabled agents, provide
documentation such as Agent Cards, and streamline onboarding for client developers.
By adhering to these enterprise-grade practices, A2A implementations can be
deployed securely, reliably, and manageably within complex organizational
environments. This fosters trust and enables scalable inter-agent collaboration.
# A2A and MCP: Detailed Comparison
In AI agent development, two key protocol types emerge to facilitate
interoperability. One connects agents to tools and resources. The other enables
agent-to-agent collaboration. The Agent2Agent (A2A) Protocol and the
[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) address these distinct but highly complementary needs.
## Model Context Protocol
The Model Context Protocol (MCP) defines how an AI agent interacts with and utilizes individual tools and resources, such as a database or an API.
This protocol offers the following capabilities:
- Standardizes how AI models and agents connect to and interact with tools,
APIs, and other external resources.
- Defines a structured way to describe tool capabilities, similar to function
calling in Large Language Models.
- Passes inputs to tools and receives structured outputs.
- Supports common use cases, such as an LLM calling an external API, an agent
querying a database, or an agent connecting to predefined functions.
## Agent2Agent Protocol
The Agent2Agent Protocol focuses on enabling different agents to collaborate with one another to achieve a common goal.
This protocol offers the following capabilities:
- Standardizes how independent, often opaque, AI agents communicate and
collaborate as peers.
- Provides an application-level protocol for agents to discover each other,
negotiate interactions, manage shared tasks, and exchange conversational
context and complex data.
- Supports typical use cases, including a customer service agent delegating an
inquiry to a billing agent, or a travel agent coordinating with flight,
hotel, and activity agents.
## Why Different Protocols?
Both the MCP and A2A protocols are essential for building complex AI systems, and they address distinct but highly complementary needs. The distinction between A2A and MCP depends on what an agent interacts with.
- **Tools and Resources (MCP Domain)**:
- **Characteristics:** These are typically primitives with well-defined,
structured inputs and outputs. They perform specific, often stateless,
functions. Examples include a calculator, a database query API, or a
weather lookup service.
- **Purpose:** Agents use tools to gather information and perform discrete
functions.
- **Agents (A2A domain)**:
- **Characteristics:** These are more autonomous systems. They reason,
plan, use multiple tools, maintain state over longer interactions, and
engage in complex, often multi-turn dialogues to achieve novel or
evolving tasks.
- **Purpose:** Agents collaborate with other agents to tackle broader, more
complex goals.
## A2A ❤️ MCP: Complementary Protocols for Agentic Systems
An agentic application might primarily use A2A to communicate with other agents.
Each individual agent internally uses MCP to interact with its specific tools
and resources.
{width="80%"}
_An agentic application might use A2A to communicate with other agents, while each agent internally uses MCP to interact with its specific tools and resources._
### Example Scenario: The Auto Repair Shop
Consider an auto repair shop staffed by autonomous AI agent "mechanics".
These mechanics use special-purpose tools, such as vehicle diagnostic scanners,
repair manuals, and platform lifts, to diagnose and repair problems. The repair
process can involve extensive conversations, research, and interaction with part
suppliers.
- **Customer Interaction (User-to-Agent using A2A)**: A customer (or their
primary assistant agent) uses A2A to communicate with the "Shop Manager"
agent.
For example, the customer might say, "My car is making a rattling noise".
- **Multi-turn Diagnostic Conversation (Agent-to-Agent using A2A)**: The Shop
Manager agent uses A2A for a multi-turn diagnostic conversation.
For example, the Manager might ask, "Can you send a video of the noise?" or "I see some fluid leaking. How long has this been happening?".
- **Internal Tool Usage (Agent-to-Tool using MCP)**: The Mechanic agent,
assigned the task by the Shop Manager, needs to diagnose the issue. The
Mechanic agent uses MCP to interact with its specialized tools.
For example:
- MCP call to a "Vehicle Diagnostic Scanner" tool:
`scan_vehicle_for_error_codes(vehicle_id='XYZ123')`
- MCP call to a "Repair Manual Database" tool:
`get_repair_procedure(error_code='P0300', vehicle_make='Toyota',
vehicle_model='Camry')`
- MCP call to a "Platform Lift" tool: `raise_platform(height_meters=2)`
- **Supplier Interaction (Agent-to-Agent using A2A)**: The Mechanic agent
determines that a specific part is needed. The Mechanic agent uses A2A to
communicate with a "Parts Supplier" agent to order a part.
For example, the
Mechanic agent might ask, "Do you have part #12345 in stock for a Toyota Camry 2018?"
- **Order processing (Agent-to-Agent using A2A)**: The Parts Supplier agent,
which is also an A2A-compliant system, responds, potentially leading to an
order.
In this example:
- A2A facilitates the higher-level, conversational, and task-oriented
interactions between the customer and the shop, and between the shop's
agents and external supplier agents.
- MCP enables the mechanic agent to use its specific, structured tools to
perform its diagnostic and repair functions.
An A2A server could expose some of its skills as MCP-compatible resources.
However, A2A's primary strength lies in its support for more flexible, stateful,
and collaborative interactions. These interactions go beyond a typical tool
invocation. A2A focuses on agents partnering on tasks, whereas MCP focuses on
agents using capabilities.
## Representing A2A Agents as MCP Resources
An A2A Server (a remote agent) could expose some of its skills as MCP-compatible resources, especially if those skills are well-defined and can be invoked in a more tool-like, stateless manner. In such a case, another agent might "discover" this A2A agent's specific skill through an MCP-style tool description (perhaps derived from its Agent Card).
However, the primary strength of A2A lies in its support for more flexible, stateful, and collaborative interactions that go beyond typical tool invocation. A2A is about agents _partnering_ on tasks, while MCP is more about agents _using_ capabilities.
By leveraging both A2A for inter-agent collaboration and MCP for tool integration, developers can build more powerful, flexible, and interoperable AI systems.
# Extensions in A2A
The Agent2Agent (A2A) protocol provides a strong foundation for inter-agent
communication. However, specific domains or advanced use cases often require
additional structure, custom data, or new interaction patterns beyond the
generic methods. Extensions are A2A's powerful mechanism for layering new capabilities onto the
base protocol.
Extensions allow for extending the A2A protocol with new data, requirements,
RPC methods, and state machines. Agents declare their support for specific
extensions in their Agent Card, and clients can then opt in to the behavior
offered by an extension as part of requests they make to the agent. Extensions
are identified by a URI and defined by their own specification. Anyone is able to define, publish, and implement an extension.
The flexibility of extensions allows for customizing A2A without fragmenting
the core standard, fostering innovation and domain-specific optimizations.
## Scope of Extensions
The exact set of possible ways to use extensions is intentionally broad,
facilitating the ability to expand A2A beyond known use cases.
However, some foreseeable applications include:
- **Data-only Extensions**: Exposing new, structured information in the Agent
Card that doesn't impact the request-response flow. For example, an
extension could add structured data about an agent's GDPR compliance.
- **Profile Extensions**: Overlaying additional structure and state change
requirements on the core request-response messages. This type effectively
acts as a profile on the core A2A protocol, narrowing the space of allowed
values (for example, requiring all messages to use `DataParts` adhering to
a specific schema). This can also include augmenting existing states in the
task state machine by using metadata. For example, an extension could define
a 'generating-image' substate when `TaskStatus.state` is 'working' and
`TaskStatus.message.metadata["generating-image"]` is true.
- **Method Extensions (Extended Skills)**: Adding entirely new RPC methods
beyond the core set defined by the protocol. An Extended Skill refers to a
capability or function an agent gains or exposes specifically through the
implementation of an extension that defines new RPC methods. For example, a
`task-history` extension might add a `tasks/search` RPC method to retrieve
a list of previous tasks, effectively providing the agent with a new,
extended skill.
- **State Machine Extensions**: Adding new states or transitions to the task
state machine.
## List of Example Extensions
| Extension | Description |
| :-------- | :------------ |
| [Secure Passport Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/secure-passport) | Adds a trusted, contextual layer for immediate personalization and reduced overhead (v1). |
| [Hello World or Timestamp Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/timestamp) | A simple extension demonstrating how to augment base A2A types by adding timestamps to the `metadata` field of `Message` and `Artifact` objects (v1). |
| [Traceability Extension](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/extensions/traceability) | Explore the Python implementation and basic usage of the Traceability Extension (v1). |
| [Agent Gateway Protocol (AGP) Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/agp) | A Core Protocol Layer or Routing Extension that introduces Autonomous Squads (ASq) and routes Intent payloads based on declared Capabilities, enhancing scalability (v1). |
## Extension Governance
The A2A organization uses a formal governance framework for how extensions are
proposed, developed, promoted, and maintained. Official extensions use the
`https://a2a-protocol.org/extensions/` URI prefix and are hosted under the
`a2aproject` organization with the `ext-` repository prefix (experimental
extensions use `experimental-ext-`).
For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
page.
## Limitations
There are some changes to the protocol that extensions don't allow, primarily
to prevent breaking core type validations:
- **Changing the Definition of Core Data Structures**: For example, adding new
fields or removing required fields to protocol-defined data structures.
Extensions should place custom attributes in the `metadata` map present on
core data structures.
- **Adding New Values to Enum Types**: Extensions should use existing enum values
and annotate additional semantic meaning in the `metadata` field.
## Extension Declaration
Agents declare their support for extensions in their Agent Card by including
`AgentExtension` objects within their `AgentCapabilities` object.
{{ proto_to_table("AgentExtension") }}
The following is an example of an Agent Card with an extension:
```json
{
"name": "Magic 8-ball",
"description": "An agent that can tell your future... maybe.",
"version": "0.1.0",
"url": "https://example.com/agents/eightball",
"capabilities": {
"streaming": true,
"extensions": [
{
"uri": "https://example.com/ext/konami-code/v1",
"description": "Provide cheat codes to unlock new fortunes",
"required": false,
"params": {
"hints": [
"When your sims need extra cash fast",
"You might deny it, but we've seen the evidence of those cows."
]
}
}
]
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"],
"skills": [
{
"id": "fortune",
"name": "Fortune teller",
"description": "Seek advice from the mystical magic 8-ball",
"tags": ["mystical", "untrustworthy"]
}
]
}
```
## Required Extensions
While extensions generally offer optional functionality, some agents may have
stricter requirements. When an Agent Card declares an extension as
`required: true`, it signals to clients that some aspect of the extension impacts how
requests are structured or processed, and that the client must abide by it.
Agents shouldn't mark data-only extensions as required. If a client does not
request activation of a required extension, or fails to follow its protocol,
the agent should reject the incoming request with an appropriate error.
## Extension Specification
The detailed behavior and structure of an extension are defined by its
**specification**. While the exact format is not mandated, it should contain at
least:
- The specific URI(s) that identify the extension.
- The schema and meaning of objects specified in the `params` field of the
`AgentExtension` object.
- Schemas of any additional data structures communicated between client and
agent.
- Details of new request-response flows, additional endpoints, or any other
logic required to implement the extension.
## Extension Dependencies
Extensions might depend on other extensions. This can be a required dependency
(where the extension cannot function without the dependent) or an optional one
(where additional functionality is enabled if another extension is present).
Extension specifications should document these dependencies. It is the client's
responsibility to activate an extension and all its required dependencies as
listed in the extension's specification.
## Extension Activation
Extensions default to being inactive, providing a baseline
experience for extension-unaware clients. Clients and agents perform
negotiation to determine which extensions are active for a specific request.
1. **Client Request**: A client requests extension activation by including the
`A2A-Extensions` header in the HTTP request to the agent. The value is a
comma-separated list of extension URIs the client intends to activate.
2. **Agent Processing**: Agents are responsible for identifying supported
extensions in the request and performing the activation. Any requested
extensions not supported by the agent can be ignored.
3. **Response**: Once the agent has identified all activated extensions, the
response SHOULD include the `A2A-Extensions` header, listing all
extensions that were successfully activated for that request.
{ width="70%" style="margin:20px auto;display:block;" }
**Example request showing extension activation:**
```http
POST /agents/eightball HTTP/1.1
Host: example.com
Content-Type: application/json
A2A-Extensions: https://example.com/ext/konami-code/v1
Content-Length: 519
{
"jsonrpc": "2.0",
"method": "SendMessage",
"id": "1",
"params": {
"message": {
"messageId": "1",
"role": "ROLE_USER",
"parts": [{"text": "Oh magic 8-ball, will it rain today?"}]
},
"metadata": {
"https://example.com/ext/konami-code/v1/code": "motherlode"
}
}
}
```
**Corresponding response echoing activated extensions:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
A2A-Extensions: https://example.com/ext/konami-code/v1
Content-Length: 338
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"message": {
"messageId": "2",
"role": "ROLE_AGENT",
"parts": [{"text": "That's a bingo!"}]
}
}
}
```
## Implementation Considerations
While the A2A protocol defines the functionality of extensions, this section
provides guidance on their implementation—best practices for authoring,
versioning, and distributing extension implementations.
- **Versioning**: Extension specifications evolve. It is
crucial to have a clear versioning strategy to ensure that clients and
agents can negotiate compatible implementations.
- **Recommendation**: Use the extension's URI as the primary version
identifier, ideally including a version number (for example,
`https://example.com/ext/my-extension/v1`).
- **Breaking Changes**: A new URI MUST be used when introducing a breaking
change to an extension's logic, data structures, or required parameters.
- Handling Mismatches: If a client requests a version not supported by
the agent, the agent SHOULD ignore the activation request for that
extension; it MUST NOT fall back to a different version.
- **Discoverability and Publication**:
- **Specification Hosting**: The extension specification document **should** be
hosted at the extension's URI.
- **Permanent Identifiers**: Authors are encouraged to use a permanent
identifier service, such as `w3id.org`, for their extension URIs to
prevent broken links.
- **Community Registry**: The A2A [Extension Governance](#extension-governance)
framework defines a tiered system for official and experimental
extensions hosted under the `a2aproject` organization, including a
lifecycle for proposing and promoting extensions.
- **Packaging and Reusability (A2A SDKs and Libraries)**:
To promote adoption, extension logic should be packaged into reusable
libraries that can be integrated into existing A2A client and
server applications.
- An extension implementation should be distributed as a
standard package for its language ecosystem (for example, a PyPI package
for Python, an npm package for TypeScript/JavaScript).
- The objective is to provide a streamlined integration experience for
developers. A well-designed extension package should allow a developer
to add it to their server with minimal code, for example:
```python
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/adk_expense_reimbursement/__main__.py"
```
This example showcases how A2A SDKs or libraries such as `a2a.server` in
Python facilitate the implementation of A2A agents and extensions.
- **Security**: Extensions modify the core behavior of the A2A protocol, and therefore
introduce new security considerations:
- **Input Validation**: Any new data fields, parameters, or methods
introduced by an extension MUST be rigorously validated. Treat all
extension-related data from an external party as untrusted input.
- **Scope of Required Extensions**: Be mindful when marking an extension as
`required: true` in an Agent Card. This creates a hard dependency for
all clients and should only be used for extensions fundamental to the
agent's core function and security (for example, a message signing
extension).
- **Authentication and Authorization**: If an extension adds new methods,
the implementation MUST ensure these methods are subject to the same
authentication and authorization checks as the core A2A methods. An
extension MUST NOT provide a way to bypass the agent's primary security
controls.
For more information, see the [A2A Extensions: Empowering Custom Agent Functionality](https://developers.googleblog.com/en/a2a-extensions-empowering-custom-agent-functionality/) blog post.
# What's New in A2A Protocol v1.0
This document provides a comprehensive overview of changes from A2A Protocol v0.3.0 to v1.0. The v1.0 release represents a significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
## Overview of Major Themes
The v1.0 release focuses on four major themes:
### 1. **Protocol Maturity and Standardization**
- Elevate a2a.proto from being a gRPC-specific implementation file to the universal, normative source of truth
- Leverage formal specification standards (RFC 8785, RFC 7515) and google.rpc.Status where possible
- Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings
- Enhanced versioning strategy with explicit backward compatibility rules
- Comprehensive error taxonomy with protocol-specific mappings
### 2. **Enhanced Type Safety and Clarity**
- Removal of discriminator `kind` fields in favor of JSON member-based polymorphism
- **Breaking:** Enum values changed from `kebab-case` to `SCREAMING_SNAKE_CASE` for compliance with the ProtoJSON specification
- Stricter field naming conventions (`camelCase` for JSON)
- More precise timestamp specifications (ISO 8601 with millisecond precision)
- Better-defined data types with clearer Optional vs Required semantics
### 3. **Improved Developer Experience**
- Renamed operations for consistency and clarity
- Reorganized Agent Card structure for better logical grouping
- Enhanced extension mechanism with versioning and requirement declarations
- More explicit service parameter handling (A2A-Version, A2A-Extensions headers)
- **Simplified ID format** - Removed complex compound IDs (e.g., `tasks/{id}`) in favor of simple UUIDs
- **Protocol versioning per interface** - Each AgentInterface specifies its own protocol version for better backward compatibility
- **Multi-tenancy support** - Native tenant scoping in gRPC requests
### 4. **Enterprise-Ready Features**
- Agent Card signature verification using JWS and JSON Canonicalization
- Formal specification of all three protocol bindings with equivalence guarantees
- Enhanced security scheme declarations with mutual TLS support
- **Modern OAuth 2.0 flows** - Added Device Code flow (RFC 8628), removed deprecated implicit/password flows
- **PKCE support** - Added `pkce_required` field to Authorization Code flow for enhanced security
- Cursor-based pagination for scalable task listing
---
## Behavioral Changes for Core Operations
### Send Message (`message/send` → **`SendMessage`**)
**v0.3.0 Behavior:**
- Operation named `message/send`
- Less formal specification of when `Task` vs `Message` is returned
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **`SendMessage`**
- **✅ CLARIFIED:** More precise specification of Task vs Message return semantics
### Send Streaming Message (`message/stream` → **SendStreamingMessage**)
**v0.3.0 Behavior:**
- Operation named `message/stream`
- Stream events had `kind` discriminator field
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **`SendStreamingMessage`**
- **✅ BREAKING:** Stream events no longer have `kind` field
- Use JSON member names to discriminate between `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`
- **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.
- **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events
### Get Task (`tasks/get` → **GetTask**)
**v0.3.0 Behavior:**
- Operation named `tasks/get`
- Returns task with status, artifacts, and optionally history
- Less formal specification of what "include history" means
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **GetTask**
- **✅ NEW:** `createdAt` and `lastModified` timestamp fields added to Task object
- **✅ CLARIFIED:** More precise specification of history inclusion behavior
- **✅ NEW:** Task object now includes `extensions[]` array in messages and artifacts
- **✅ CLARIFIED:** Authentication/authorization scoping - servers MUST only return tasks visible to caller
### List Tasks (`tasks/list` → **ListTasks**)
**v0.3.0 Behavior:**
- Operation unavailable.
**v1.0 Changes:**
- **✅ NEW:** New operation **ListTasks** with filtering capabilities
- **✅ CLARIFIED:** Task visibility scoped to authenticated caller
### Cancel Task (`tasks/cancel` → **CancelTask**)
**v0.3.0 Behavior:**
- Operation named `tasks/cancel`
- Request with taskId, returns Task
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **CancelTask**
- **✅ CLARIFIED:** More precise specification of when cancellation is allowed
- **✅ CLARIFIED:** Task state transitions for cancellation scenarios
### Get Agent Card (Well-known URI and **GetExtendedAgentCard**)
**v0.3.0 Behavior:**
- Discovery via `/.well-known/agent-card.json`
- Extended card via `agent/getAuthenticatedExtendedCard`
- `supportsAuthenticatedExtendedCard` boolean at top level
**v1.0 Changes:**
- **✅ RENAMED:** `agent/getAuthenticatedExtendedCard` → **GetExtendedAgentCard**
- **✅ BREAKING:** `supportsAuthenticatedExtendedCard` moved to `capabilities.extendedAgentCard`
- **✅ NEW:** Canonicalization (RFC 8785) clarified for Agent Card signature
- **✅ BREAKING:** `protocolVersion` moved from AgentCard to individual AgentInterface objects
- **✅ BREAKING:** `preferredTransport` and `additionalInterfaces` consolidated into `supportedInterfaces[]`
- Each interface has `url`, `protocolBinding`, and `protocolVersion`
### Subscribe to task (`tasks/resubscribe` → **SubscribeToTask**)
**v0.3.0 Behavior:**
- Used `tasks/resubscribe` to reconnect interrupted SSE streams
- Backfill behavior implementation-dependent
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **SubscribeToTask**
- **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle
- **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state
- **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task
### Push Notification Operations
**v0.3.0 Operations:**
- `tasks/pushNotificationConfig/set`
- `tasks/pushNotificationConfig/get`
- `tasks/pushNotificationConfig/list`
- `tasks/pushNotificationConfig/delete`
**v1.0 Changes:**
- **✅ RENAMED:** Operations now **CreateTaskPushNotificationConfig**, **GetTaskPushNotificationConfig**, **ListTaskPushNotificationConfigs**, **DeleteTaskPushNotificationConfig**
- **✅ NEW:** `createdAt` timestamp field added to PushNotificationConfig
- **✅ CLARIFIED:** Push notification payloads now use StreamResponse format
- **✅ BREAKING:** model changed for all methods, with TaskPushNotificationConfig flattened
### NEW: Multi-Tenancy Support
**v0.3.0:**
- No native multi-tenancy support in protocol
- Tenants handled implicitly via authentication or URL paths
**v1.0 Changes:**
- **✅ NEW:** `tenant` field added to all request messages
- **✅ NEW:** `tenant` field added to `AgentInterface` to specify default tenant
- **✅ CLARIFIED:** Tenant provided per-request, inherited from AgentInterface
- **✅ USE CASE:** Enables to serve multiple agents from a single endpoint
### Protocol Simplifications
#### ID Format Simplification (#1389)
**v0.3.0:**
- Some operations used complex compound IDs like `tasks/{taskId}`
- Required clients/servers to construct/deconstruct resource names
**v1.0 Changes:**
- **✅ BREAKING:** All IDs are now simple literals
- **✅ BREAKING:** Operations that previously used compound IDs now separate parent and resource ID
- Example: `tasks/{taskId}/pushNotificationConfigs/{configId}` → separate `task_id` and `config_id` fields
- **✅ BENEFIT:** Simpler to implement - IDs map directly to database keys
#### HTTP URL Path Simplification (#1269)
**v0.3.0:**
- HTTP+JSON binding used `/v1/` prefix in URLs
- Example: `POST /v1/message:send`
**v1.0 Changes:**
- **✅ BREAKING:** Removed `/v1` prefix from HTTP+JSON URL paths
- **✅ NEW:** Examples: `POST /message:send`, `GET /tasks/{id}`
- **✅ RATIONALE:** Version can be part of the base url if required by agent owner
- **✅ BENEFIT:** Cleaner URLs, version management at interface level
---
## Structural Changes in Core Model Objects
### TaskStatus Object
**Modified Fields:**
- ✅ `state`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
- v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"canceled"`, `"rejected"`, `"input-required"`, `"auth-required"`
- v1.0: `"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_AUTH_REQUIRED"`
- ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
**Removed Fields:**
- None
**Example Migration:**
```json
// v0.3.0
{
"status": {
"state": "completed",
"timestamp": "2024-03-15T10:15:00Z"
}
}
// v1.0
{
"status": {
"state": "TASK_STATE_COMPLETED",
"timestamp": "2024-03-15T10:15:00.000Z"
}
}
```
### Message Object
**Added Fields:**
- ✅ `extensions[]`: Array of extension URIs applicable to this message
**Modified Fields:**
- ✅ `role`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `ROLE_` prefix
- v0.3.0: `"user"`, `"agent"`
- v1.0: `"ROLE_USER"`, `"ROLE_AGENT"`
**Example Migration:**
```json
// v0.3.0
{
"role": "user",
"parts": [{"kind": "text", "text": "Hello"}]
}
// v1.0
{
"role": "ROLE_USER",
"parts": [{"text": "Hello"}],
}
```
**Behavior Changes:**
- Parts array now uses member-based discrimination instead of `kind` field
### Part Object
**BREAKING CHANGE - Complete Redesign:**
The Part structure has been completely redesigned in v1.0. Instead of separate TextPart, FilePart, and DataPart message types, there is now a single unified `Part` message.
**v0.3.0 Structure (Separate Types):**
```json
// Text example
{
"kind": "text",
"text": "Hello world"
}
// File example
{
"kind": "file",
"file": {
"fileWithUri": "https://example.com/doc.pdf",
"mimeType": "application/pdf"
}
}
// Data example
{
"kind": "data",
"data": {"key": "value"}
}
```
**v1.0 Structure (Unified Part):**
```json
// Text example
{
"text": "Hello world",
"mediaType": "text/plain"
}
// File with URL example
{
"url": "https://example.com/doc.pdf",
"filename": "doc.pdf",
"mediaType": "application/pdf"
}
// File with raw bytes example
{
"raw": "base64encodedcontent==",
"filename": "image.png",
"mediaType": "image/png"
}
// Data example
{
"data": {"key": "value"},
"mediaType": "application/json"
}
```
**Changes:**
- ⛔ **REMOVED:** Separate `TextPart`, `FilePart`, and `DataPart` types
- ⛔ **REMOVED:** `kind` discriminator field
- ⛔ **REMOVED:** Nested `file` object structure
- ✅ **NEW:** Single unified `Part` message with `oneof content` field
- ✅ **NEW:** Content type determined by which field is present: `text`, `raw`, `url`, or `data`
- ✅ **NEW:** `mediaType` field (replaces `mimeType`) - available for all part types
- ✅ **NEW:** `filename` field - available for all part types (not just files)
- ✅ **NEW:** `raw` field for inline binary content (base64 in JSON)
- ✅ **NEW:** `url` field for file references (replaces `file.fileWithUri`)
**Migration Examples:**
```typescript
// v0.3.0
const textPart = { kind: "text", text: "Hello" };
const filePart = { kind: "file", file: { fileWithUri: "https://...", mimeType: "image/png" } };
const dataPart = { kind: "data", data: { key: "value" } };
// v1.0
const textPart = { text: "Hello", mediaType: "text/plain" };
const filePart = { url: "https://...", mediaType: "image/png", filename: "image.png" };
const dataPart = { data: { key: "value" }, mediaType: "application/json" };
// Discrimination changed from kind field to member presence
if (part.kind === "text") { ... } // v0.3.0
if ("text" in part) { ... } // v1.0
```
### Artifact Object
**Added Fields:**
- ✅ `extensions[]`: Array of extension URIs
**Modified Fields:**
- ✅ `parts[]`: Now uses member-based Part discrimination (see Part changes above)
### AgentCard Object
**Added Fields:**
- ✅ `supportedInterfaces[]`: Array of `AgentInterface` objects
**Removed Fields:**
- ⛔ `protocolVersion`: Removed from AgentCard (now in each AgentInterface)
- ⛔ `preferredTransport`: Consolidated into `supportedInterfaces`
- ⛔ `additionalInterfaces`: Consolidated into `supportedInterfaces`
- ⛔ `supportsAuthenticatedExtendedCard`: Moved to `capabilities.extendedAgentCard`
- ⛔ `url`: Primary endpoint now in `supportedInterfaces[0].url`
**Structure Example:**
**v0.3.0:**
```json
{
"protocolVersion": "0.3",
"url": "https://agent.example.com/a2a",
"preferredTransport": "JSONRPC",
"supportsAuthenticatedExtendedCard": true,
"additionalInterfaces": [...]
}
```
**v1.0:**
```json
{
"supportedInterfaces": [
{
"url": "https://agent.example.com/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"capabilities": {
"extendedAgentCard": true
},
"signatures": [...]
}
```
### AgentCapabilities Object
**Modified Fields:**
- ✅ `extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard` field
### PushNotificationConfig Object
**Added Fields:**
- ✅ `configId`: Unique identifier for the configuration
- ✅ `createdAt`: Timestamp - Configuration creation time
**Modified Fields:**
- ✅ `authentication`: Enhanced PushNotificationAuthenticationInfo structure
### Stream Event Objects
**TaskStatusUpdateEvent:**
**v0.3.0:**
```json
{
"kind": "taskStatusUpdate",
"taskId": "...",
"contextId": "...",
"status": {...},
"final": true
}
```
**v1.0:**
```json
{
"taskStatusUpdate": {
"taskId": "...",
"contextId": "...",
"status": {...}
}
}
```
**Changes:**
- ⛔ **REMOVED:** `kind` discriminator
- ⛔ **REMOVED:** `final` boolean field (stream closure indicates completion instead)
- ✅ **NEW PATTERN:** Event type determined by JSON member name (`taskStatusUpdate` or `taskArtifactUpdate`)
- ✅ **CLARIFIED:** Terminal state indicated by protocol-specific stream closure mechanism
**TaskArtifactUpdateEvent:**
**v0.3.0:**
```json
{
"kind": "taskArtifactUpdate",
"taskId": "...",
"contextId": "...",
"artifact": {...}
}
```
**v1.0:**
```json
{
"taskArtifactUpdate": {
"taskId": "...",
"contextId": "...",
"artifact": {...},
"index": 0
}
}
```
**Changes:**
- ⛔ **REMOVED:** `kind` discriminator
- ✅ **NEW PATTERN:** Wrapped in `taskArtifactUpdate` object
- ✅ **NEW:** `index` field indicates artifact position in task's artifacts array
### OAuth 2.0 Security Updates (#1303)
v1.0 modernizes OAuth 2.0 support in alignment with OAuth 2.0 Security Best Current Practice (BCP).
**Removed Flows (Deprecated by OAuth BCP):**
- ⛔ `ImplicitOAuthFlow` - Deprecated due to token leakage risks in browser history/logs
- ⛔ `PasswordOAuthFlow` - Deprecated due to credential exposure risks
**Added Flows:**
- ✅ `DeviceCodeOAuthFlow` (RFC 8628) - For CLI tools, IoT devices, and input-constrained scenarios
- Provides `device_authorization_url` endpoint
- Supports `verification_uri`, `user_code` pattern
- Ideal for headless environments
**Enhanced Security:**
- ✅ `pkce_required` field added to `AuthorizationCodeOAuthFlow` (RFC 7636)
- Indicates whether PKCE (Proof Key for Code Exchange) is mandatory
- Protects against authorization code interception attacks
- Recommended for all OAuth clients, required for public clients
**Migration Guide:**
```typescript
// v0.3.0 - Implicit Flow (now removed)
{
"implicitFlow": {
"authorizationUrl": "https://auth.example.com/authorize",
"scopes": {"read": "Read access"}
}
}
// v1.0 - Use Authorization Code + PKCE instead
{
"authorizationCodeFlow": {
"authorizationUrl": "https://auth.example.com/authorize",
"tokenUrl": "https://auth.example.com/token",
"pkceRequired": true,
"scopes": {"read": "Read access"}
}
}
```
---
## New Dependencies on Other Specifications
v1.0 introduces several new formal dependencies on industry-standard specifications:
### Added Specifications
#### ✅ google.rpc.Status / google.rpc.ErrorInfo
- **Purpose:** Standardized error response model with ProtoJSON representation
- **Usage:** Error responses for HTTP+JSON and JSON-RPC bindings
- **Impact:** Replaces RFC 9457 for HTTP errors. Enforces structured `ErrorInfo` with `reason` and `domain` for A2A-specific errors.
#### ✅ RFC 8785 - JSON Canonicalization Scheme (JCS)
- **Purpose:** Deterministic JSON serialization for signing
- **Usage:** Agent Card signature verification
- **Impact:** Enables cryptographic verification of Agent Card integrity
- **Details:** Canonical form used before JWS signing (excludes `signatures` field)
#### ✅ RFC 7515 - JSON Web Signature (JWS)
- **Purpose:** Cryptographic signing standard
- **Usage:** Agent Card signatures field
- **Impact:** Industry-standard signature format for trust verification
- **Details:** Supports detached signatures with public key retrieval via `jku` or trusted keystores
#### ✅ Google API Design Guidelines
- **Purpose:** gRPC best practices and conventions
- **Usage:** gRPC binding design patterns
- **Impact:** Better alignment with gRPC ecosystem expectations
#### ✅ ISO 8601
- **Purpose:** Timestamp format standard
- **Usage:** All timestamp fields (createdAt, lastModified, timestamp)
- **Impact:** Explicit format requirement: UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
### Existing Dependencies (Retained from v0.3.0)
- JSON-RPC 2.0
- gRPC / Protocol Buffers 3
- HTTP/HTTPS (various RFCs)
- Server-Sent Events (SSE) - W3C specification
- RFC 8615 - Well-known URIs
- OAuth 2.0, OpenID Connect (for authentication)
- TLS (RFC 8446 recommended)
### Complementary Protocol
**Model Context Protocol (MCP):**
- Relationship clarified: MCP handles tool/resource integration, A2A handles agent-to-agent coordination
- Protocols are complementary, not competing
- Agents may support both protocols for different use cases
---
## Impact on Developers
### Breaking Changes Requiring Code Updates
#### 1. Part Type Unification (CRITICAL IMPACT)
The most significant breaking change: TextPart, FilePart, and DataPart types have been removed and replaced with a single unified Part structure.
**Before (v0.3.0):**
```typescript
// Separate types with kind discriminator
if (part.kind === "text") {
return part.text;
} else if (part.kind === "file") {
if (part.file.fileWithUri) {
return fetchFile(part.file.fileWithUri);
} else {
return part.file.fileWithBytes;
}
} else if (part.kind === "data") {
return part.data;
}
```
**After (v1.0):**
```typescript
// Unified Part with oneof content
if ("text" in part) {
return part.text;
} else if ("url" in part) {
return fetchFile(part.url);
} else if ("raw" in part) {
return decodeBase64(part.raw);
} else if ("data" in part) {
return part.data;
}
```
#### 2. Stream Event Discriminator Pattern (HIGH IMPACT)
Stream events changed from kind-based to wrapper-based discrimination:
**Before (v0.3.0):**
```typescript
if (event.kind === "taskStatusUpdate") {
handleStatusUpdate(event);
} else if (event.kind === "taskArtifactUpdate") {
handleArtifactUpdate(event);
}
```
**After (v1.0):**
```typescript
if ("taskStatusUpdate" in event) {
handleStatusUpdate(event.taskStatusUpdate);
} else if ("taskArtifactUpdate" in event) {
handleArtifactUpdate(event.taskArtifactUpdate);
}
```
#### 3. Agent Card Structure (HIGH IMPACT)
Agent discovery and capability checking requires updates:
**Before (v0.3.0):**
```typescript
const endpoint = agentCard.url;
const transport = agentCard.preferredTransport;
const supportsExtended = agentCard.supportsAuthenticatedExtendedCard;
```
**After (v1.0):**
```typescript
const primaryInterface = agentCard.supportedInterfaces[0];
const endpoint = primaryInterface.url;
const transport = primaryInterface.protocolBinding;
const supportsExtended = agentCard.capabilities.extendedAgentCard;
```
#### 4. Pagination (MEDIUM IMPACT)
List Tasks implementation must switch from page-based to cursor-based:
**Before (v0.3.0):**
```typescript
const response = await listTasks({ page: 1, perPage: 50 });
```
**After (v1.0):**
```typescript
let cursor = undefined;
do {
const response = await listTasks({ cursor, limit: 50 });
// process response.tasks
cursor = response.nextCursor;
} while (cursor);
```
#### 5. Enum Value Changes (HIGH IMPACT)
All enum values now use SCREAMING_SNAKE_CASE with type prefixes:
**TaskState:**
```typescript
// v0.3.0
if (task.status.state === "completed") { ... }
if (task.status.state === "input-required") { ... }
// v1.0
if (task.status.state === "TASK_STATE_COMPLETED") { ... }
if (task.status.state === "TASK_STATE_INPUT_REQUIRED") { ... }
```
**MessageRole:**
```typescript
// v0.3.0
const message = { role: "user", parts: [...] };
// v1.0
const message = { role: "ROLE_USER", parts: [...] };
```
**Complete Mapping:**
- `"submitted"` → `"TASK_STATE_SUBMITTED"`
- `"working"` → `"TASK_STATE_WORKING"`
- `"completed"` → `"TASK_STATE_COMPLETED"`
- `"failed"` → `"TASK_STATE_FAILED"`
- `"canceled"` → `"TASK_STATE_CANCELED"`
- `"rejected"` → `"TASK_STATE_REJECTED"`
- `"input-required"` → `"TASK_STATE_INPUT_REQUIRED"`
- `"auth-required"` → `"TASK_STATE_AUTH_REQUIRED"`
- `"user"` → `"ROLE_USER"`
- `"agent"` → `"ROLE_AGENT"`
#### 6. Field Name Changes (LOW IMPACT)
- `file.mimeType` → `mediaType`
- Operation names (aliases provided during transition)
#### 7. Standardized Error Handling via google.rpc.Status (HIGH IMPACT)
HTTP+JSON error responses have been updated to use the ProtoJSON representation of `google.rpc.Status` instead of RFC 9457 (Problem Details). JSON-RPC and HTTP+JSON bindings now use `google.rpc.ErrorInfo` within the `data` / `details` array to provide A2A-specific error context.
**Changes:**
- **HTTP+JSON Content-Type:** Changed from `application/problem+json` to `application/json`.
- **Error Model:** Uses `google.rpc.Status` fields (`code`, `message`, `details`).
- **A2A Error Info:** MUST include a `google.rpc.ErrorInfo` object in `details` with `reason` (UPPER_SNAKE_CASE from A2A error types) and `domain: "a2a-protocol.org"`.
**JSON-RPC Example Migration:**
```json
// v0.3.0
"error": {
"code": -32001,
"message": "Task not found",
"data": { "taskId": "123" }
}
// v1.0
"error": {
"code": -32001,
"message": "Task not found",
"data": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org",
"metadata": { "taskId": "123" }
}
]
}
```
**HTTP+JSON Example Migration:**
```http
// v0.3.0 (Draft using RFC 9457)
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"
}
// v1.0
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error": {
"code": 404,
"status": "NOT_FOUND",
"message": "The specified task ID does not exist",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org"
}
]
}
}
```
### New Capabilities to Leverage
#### 1. Execution Mode Control
```typescript
// Wait for task completion (Default)
const result = await sendMessage(message, { returnImmediately: false });
// Return immediately, poll later
const task = await sendMessage(message, { returnImmediately: true });
```
#### 2. Agent Card Signature Verification
```typescript
if (agentCard.signatures && agentCard.signatures.length > 0) {
const verified = await verifyAgentCardSignature(agentCard);
if (!verified) {
throw new Error("Agent Card signature verification failed");
}
}
```
#### 3. Extension Requirements
```typescript
const requiredExtensions = agentCard.extensions
.filter(ext => ext.required)
.map(ext => ext.uri);
// Check if client supports required extensions
if (!clientSupportsAll(requiredExtensions)) {
throw new Error("Missing required extension support");
}
```
#### 4. Enhanced Timestamp Tracking
```typescript
const taskAge = Date.now() - new Date(task.createdAt).getTime();
const timeSinceUpdate = Date.now() - new Date(task.lastModified).getTime();
```
#### 5. Versioning Negotiation
```typescript
// Client sends A2A-Version header
headers["A2A-Version"] = "1.0";
// Server validates and rejects if unsupported
if (!supportedVersions.includes(requestedVersion)) {
throw new VersionNotSupportedError();
}
```
### Migration Strategy Recommendations
#### Phase 1: Compatibility Layer
1. Add support for parsing both old and new discriminator patterns
2. Implement version detection based on protocol version
3. Support both Agent Card structures during transition
#### Phase 2: Dual Support
1. Update all APIs to emit v1.0 format
2. Maintain backward compatibility readers for v0.3.0
3. Add A2A-Version header handling
4. Implement cursor-based pagination alongside legacy page-based
#### Phase 3: v1.0 Only
1. Deprecate v0.3.0 compatibility code
2. Remove legacy discriminator parsing
3. Remove page-based pagination
4. Clean up dual-format support code
#### Backward Compatibility Strategy (#1401)
v1.0 introduces a formal approach to protocol versioning that enables SDK backward compatibility.
**Protocol Version Per Interface:**
- Each `AgentInterface` now specifies its own `protocolVersion` field
- Agents can support multiple protocol versions simultaneously by exposing multiple interfaces
- Clients negotiate version by selecting appropriate interface from Agent Card
**SDK Implementation Pattern:**
```typescript
// SDK can support multiple protocol versions
class A2AClient {
async connect(agentCardUrl: string) {
const card = await this.getAgentCard(agentCardUrl);
// Find best matching interface
const interface = card.supportedInterfaces.find(i =>
this.supportedVersions.includes(i.protocolVersion)
);
if (!interface) {
throw new Error("No compatible protocol version");
}
// Use version-specific adapter
return this.createAdapter(interface.protocolVersion, interface);
}
}
```
**Benefits:**
- SDKs can maintain support for multiple protocol versions
- Agents can gradually migrate by supporting both old and new versions
- Clients automatically select best compatible version
- Enables graceful deprecation of old protocol versions
### Testing Considerations
- Test with both v0.3.0 and v1.0 formatted data
- Validate Agent Card signature verification
- Test cursor-based pagination edge cases (empty results, single page, etc.)
- Verify proper handling of new error types
- Test extension requirement validation
### Recommended Priority
#### Critical (Do Immediately)
- Update Part and streaming event parsing (discriminator pattern)
- Update Agent Card parsing (structure changes)
- Add A2A-Version header to all requests
#### High (Within 1 Month)
- Implement cursor-based pagination
- Update enum value handling (state field)
- Add return_immediately parameter support
#### Medium (Within 3 Months)
- Implement Agent Card signature verification
- Add extension requirement checking
- Update timestamp handling to ISO 8601 format
- Implement new error types
#### Low (Nice to Have)
- Add createdAt/lastModified timestamp tracking
- Leverage enhanced metadata capabilities
- Implement mutual TLS authentication support
---
## Conclusion
A2A Protocol v1.0 represents a significant step forward in protocol maturity while maintaining the core architectural principles of v0.3.0. The changes focus on standardization, type safety, and enterprise readiness, requiring developers to update their implementations but providing clearer specifications and better developer experience in return.
The breaking changes, while requiring code updates, are straightforward to implement and improve code clarity. The new capabilities around versioning, signatures, and enhanced extensions provide a solid foundation for future protocol evolution within the v1.x line.
Developers should plan for a phased migration approach, prioritizing the critical breaking changes while gradually adopting new capabilities over time.
# A2A Protocol Ships v1.0: Production-Ready Standard for Agent-to-Agent Communication
The A2A Protocol community today are announcing the release of A2A Protocol v1.0, marking the first stable, production-ready version of the open standard for communication between AI agents. The protocol is guided by a technical steering committee with representatives from eight major technology companies.
As organizations build increasingly sophisticated multi-agent systems, interoperability has become the defining challenge. Teams can coordinate agents effectively within a single platform, but connecting those systems across technology stacks and organizational boundaries remains difficult. A2A addresses that challenge by combining support for multiple protocol bindings, seamless version negotiation, and a common semantic model so agents can interoperate across systems with predictable behavior.
The v1.0 release emphasizes maturity rather than reinvention: the core ideas remain intact, while rough edges have been removed, ambiguous areas clarified, and enterprise deployment requirements addressed more directly. The official SDKs ensure v1.0 A2A agents work seamlessly with older versions.
## Delivering on enterprise requirements
The v1.0 release introduces several capabilities aimed at production environments where trust, scale, and operational control are non-negotiable.
- **Heterogeneous environment support** enables interoperability across diverse technology stacks through multi-protocol bindings and version negotiation, so enterprises are not tied to a single vendor or platform.
- **Multi-tenancy support** allows a single endpoint to securely host many agents.
- **Signed Agent Cards** provide cryptographic verification of agent identity and metadata, establishing trust before interaction across organizational boundaries.
- **Improved security posture** modernizes security flows and removes legacy patterns that are no longer aligned with current best practices.
Together, these changes move A2A from early adopter implementations toward broader enterprise confidence, especially in regulated or multi-party scenarios.
## Web-aligned architecture for scale
A2A v1.0 aligns with core architectural principles of the web: stateless, layered architecture, standard protocol bindings, and infrastructure-friendly communication patterns. That alignment matters operationally because organizations can scale agent interactions with the same proven load balancing, gateway, security and observability patterns they already use for web systems.
The standard builds on industry-proven protocols, including JSON+HTTP, gRPC, and JSON-RPC. It also keeps the barrier to entry low: in its simplest form, an A2A interaction can begin with a single HTTP request.
A2A also gives consumers flexibility in how they receive results. Depending on workload and operational needs, clients can use polling, streaming, or webhooks to consume task updates and responses.
## Complementary to MCP, not a replacement
The release also reinforces A2A's relationship with the Model Context Protocol (MCP), a point that has generated confusion in early ecosystem discussions.
MCP and A2A solve different layers of the problem. MCP is commonly used for tool and context integration at the individual agent level. A2A focuses on communication and coordination between agents. In practice, many systems will use both: MCP inside agents, A2A between agents.
## Smooth migration from earlier versions
The v1.0 release tightens specification behavior, which includes breaking changes in the interaction protocol. AgentCard, however, has evolved in a backward-compatible way and now allows agents to advertise support for both existing v0.3 protocol behavior and v1.0 simultaneously. This enables clients to migrate progressively rather than through a single cutover.
That approach is intended to protect current investments while still delivering the benefits of a cleaner, more durable standard.
## Why this release matters now
AI agents are increasingly deployed across departments, products, and partner ecosystems. At that scale, the key question is no longer whether agents can coordinate within one stack, but whether they can collaborate reliably across organizational and platform boundaries. Open protocols determine whether organizations can compose best-of-breed systems or become locked into isolated stacks.
A2A v1.0 gives the market a stronger foundation for open multi-agent collaboration. The community is now focused on delivering multi-language v1.0 SDK support to help developers build conformant solutions with ease.
The complete v1.0 materials, including specification and migration documentation, are available at [a2a-protocol.org](https://a2a-protocol.org) and on [GitHub](https://github.com/a2aproject/A2A).
---
**About A2A Protocol**
The Agent-to-Agent (A2A) Protocol is an open standard that enables AI agents to discover capabilities, communicate, and delegate tasks across teams, products, and organizations. The A2A Technical Steering Committee includes representatives from AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow.
**Media Contact**
A2A Protocol Community
[https://a2a-protocol.org](https://a2a-protocol.org)
# Multi-Tenancy and Multi-Agent Routing
A single A2A endpoint can serve multiple agents or tenants. The A2A protocol
does not prescribe a specific routing implementation — operators are free to
choose the approach that best fits their infrastructure. This document describes
the routing mechanisms the protocol supports and the rules clients must follow
when a routing identifier is advertised in an Agent Card.
## Overview
A common deployment pattern is to place several agents behind a single host or
reverse-proxy. From the outside the agents are reachable at the same domain,
but each individual agent needs to be distinguished so that requests are
delivered to the right backend.
Three complementary approaches are available:
### 1. URL-Based Routing (Sub-Path)
Each agent is assigned a distinct URL prefix. The Agent Card for each agent
advertises its own `url` in `supportedInterfaces`, so clients automatically
send requests to the correct path.
Agent Card for the "billing" agent:
```json
{
"name": "Billing Agent",
"supportedInterfaces": [
{
"url": "https://agents.example.com/billing",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
]
}
```
Agent Card for the "support" agent:
```json
{
"name": "Support Agent",
"supportedInterfaces": [
{
"url": "https://agents.example.com/support",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
]
}
```
The gateway or reverse-proxy routes `/billing/*` and `/support/*` to the
appropriate backend. This is the simplest approach and requires no special
client awareness beyond reading the Agent Card.
### 2. Authentication Header-Based Routing
When multiple agents share the same URL, a gateway can use the authentication
credentials already present in the request to determine which agent to route to.
Authentication requirements are declared in the Agent Card's `securitySchemes`
and `security` fields, making this approach fully discoverable by clients.
Examples:
- A bearer token whose claims (such as audience or scope) identify the target agent.
- An API key that maps to a particular agent in the gateway's configuration.
The gateway inspects the credential and forwards the request to the appropriate
backend without any changes to the A2A protocol messages themselves.
### 3. Body-Based Routing Using the `tenant` Field
Every A2A request message contains an optional `tenant` field. This is an
**opaque string** whose value is defined entirely by the server operator; the
protocol does not impose any format or semantics on it. A gateway or agent
implementation can inspect this field and forward the request to the appropriate
backend.
The `tenant` value that a client should use for a particular agent is advertised
in the `AgentInterface` entry inside `supportedInterfaces`:
```json
{
"name": "Billing Agent",
"supportedInterfaces": [
{
"url": "https://agents.example.com/a2a",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0",
"tenant": "billing"
}
]
}
```
**Client requirement**: The client **MUST** always echo the `tenant` value
from the selected `AgentInterface` entry back in every request message. If
the `AgentInterface` does not set `tenant`, the field **MUST** be omitted
from the request. See
[Section 8.3.2](../specification.md#832-client-protocol-selection) of the
specification for the normative rule.
A server MAY use the `tenant` field to represent any routing key that suits its
deployment — agent identifiers, workspace slugs, organization IDs, or any other
opaque discriminator.
## Combining Approaches
The three approaches are not mutually exclusive. For example, a deployment could
use URL-based routing to distinguish between major product lines and rely on the
`tenant` field to distinguish individual customers within each product line. The
appropriate combination depends on the operator's architecture and the
capabilities of the gateway in use.
## Discovering Multiple Agents
When multiple agents are deployed behind a shared domain, each agent **SHOULD**
have its own Agent Card published at an appropriate location (see
[Agent Discovery](./agent-discovery.md)). Clients retrieve each agent's card
independently and use the `supportedInterfaces` information it contains — including
any `tenant` value — to communicate with the correct agent.
# Custom Protocol Bindings
The A2A protocol ships with three standard bindings (JSON-RPC, gRPC, and
HTTP+JSON/REST) that cover the majority of deployment scenarios. Custom protocol
bindings let implementers expose A2A operations over additional transport
mechanisms not covered by the standard set.
Custom protocol bindings are a complementary but distinct concept to
[Extensions](extensions.md). Extensions modify the *behavior* of protocol
interactions by adding new data, methods, or state transitions on top of an
existing transport. Custom protocol bindings change the *transport layer*
itself—for example, exposing A2A over WebSockets for low-latency bidirectional
communication, or over MQTT for IoT environments with constrained connectivity.
## Declaration in the Agent Card
Custom protocol bindings are declared in the Agent Card's `supportedInterfaces`
list. Each entry identifies the transport by URI, the endpoint URL, and the A2A
protocol version it implements. The `protocolBinding` field should be a URI that uniquely identifies the
binding (see [Section 5.8 of the specification](../specification.md#58-custom-binding-identification)
for the normative requirement and versioning guidance).
```json
{
"supportedInterfaces": [
{
"url": "wss://agent.example.com/a2a/websocket",
"protocolBinding": "https://a2a-protocol.org/bindings/websocket",
"protocolVersion": "1.0"
}
]
}
```
Agents that support multiple bindings list all of them. Clients parse
`supportedInterfaces` in order and select the first transport they support, so
entries should be listed in preference order.
## Requirements
Custom protocol bindings must comply with all requirements in the
[Protocol Binding Requirements and Interoperability](../specification.md#5-protocol-binding-requirements-and-interoperability)
section of the specification. In particular:
- **All core operations must be supported.** The binding must expose every
operation defined in the abstract operations layer (send message, get task,
cancel task, streaming, push notifications, etc.).
- **The data model must be preserved.** All data structures must be
functionally equivalent to the canonical Protocol Buffer definitions. JSON
serializations must use camelCase field names, and timestamps must be
ISO 8601 strings in UTC.
- **Behavior must be consistent.** Semantically equivalent requests must
produce semantically equivalent results regardless of which binding is used.
## Key Areas to Specify
A custom binding specification must address each of the following areas.
### Data Type Mappings
Document how each Protocol Buffer type is represented in the custom transport,
including:
- Binary data encoding (e.g., base64 for text-based transports)
- Enum representation (strings, integers, or named constants)
- Timestamp format (ISO 8601 strings in UTC per the core convention)
### Service Parameters
Service parameters are key-value pairs used to carry horizontally applicable
context such as tracing identifiers or authentication hints. The binding
specification must state:
- The mechanism used to carry service parameters (e.g., custom message headers,
a top-level metadata field)
- Any character encoding or size constraints on keys and values
- Any names reserved by the binding itself
For transports that lack native header support, a common pattern is to embed
service parameters as a JSON object in a dedicated metadata field, for example
`a2a-service-parameters`.
### Error Mapping
The binding must map all A2A error types to transport-native error
representations while preserving their semantic meaning. Provide a mapping
table equivalent to the one in the specification's
[Error Code Mappings](../specification.md#54-error-code-mappings) section, showing
how each A2A error type (e.g., `TaskNotFoundError`, `UnsupportedOperationError`) is expressed in the custom binding's native error format.
### Streaming
If the transport supports streaming, document:
- The stream mechanism (e.g., WebSocket frames, chunked encoding, long polling)
- Ordering guarantees (events must be delivered in the order they were
generated)
- Reconnection behavior when a connection is interrupted
- How stream completion or termination is signaled to the client
If the transport does not support streaming, state this limitation clearly in
the Agent Card so clients can fall back to polling.
### Authentication and Authorization
Document how authentication credentials declared in the Agent Card are
transmitted using the custom transport. Define how authentication challenges are
communicated to clients and ensure the custom binding does not inadvertently
bypass the agent's primary security controls.
## Interoperability Testing
Before publishing a custom binding, verify that:
- All operations behave identically to the standard bindings for the same
logical requests
- Error conditions, large payloads, and long-running tasks are handled correctly
- Any intentional deviations from standard binding behavior are clearly
documented
- Sample requests and responses are included in the specification to help
implementers
## Governance
The A2A organization uses a formal governance framework for how custom protocol
bindings are proposed, developed, promoted, and maintained. Official bindings
use the `https://a2a-protocol.org/bindings/` URI prefix and are hosted under
the `a2aproject` organization with the `cpb-` repository prefix (experimental
bindings use `experimental-cpb-`). A2A SDKs SHOULD implement official custom
protocol bindings.
For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
page.
# Extension and Protocol Binding Governance
The A2A organization uses a unified governance framework for both
[Extensions](extensions.md) and [Custom Protocol Bindings](custom-protocol-bindings.md).
This document defines the formal process for proposing, developing, promoting,
and maintaining these artifacts within the A2A organization.
Anyone may develop and publish extensions or custom protocol bindings
independently. The tiers and lifecycle described here apply specifically to
those hosted under the `a2aproject` GitHub organization.
## Tiers
Both extensions and custom protocol bindings use a two-tier system within the
`a2aproject` organization. Repository naming and URI prefixes differ by type:
| | Extensions | Custom Protocol Bindings |
| :----------------------- | :---------------------------------------------- | :--------------------------------------------- |
| Official repo prefix | `ext-{name}` | `cpb-{name}` |
| Experimental repo prefix | `experimental-ext-{name}` | `experimental-cpb-{name}` |
| Official URI prefix | `https://a2a-protocol.org/extensions/` | `https://a2a-protocol.org/bindings/` |
### Official
Official artifacts are developed and maintained under the `a2aproject` GitHub
organization, officially recommended by the TSC. Each repository has designated
maintainers identified in `MAINTAINERS.md`.
**Requirements:**
- Specifications MUST use the same language as the core specification
([RFC 2119](https://tools.ietf.org/html/rfc2119))
- MUST be licensed under Apache 2.0
- MUST have at least one reference implementation
- SHOULD have associated documentation on the A2A website
### Experimental
Experimental artifacts provide an incubation pathway for community contributors
to prototype and collaborate on ideas before graduation to official status.
**Creation Requirements:**
- An experimental repository can ONLY be created with sponsorship from an A2A
Maintainer
- The sponsoring Maintainer is responsible for initial oversight of the
experimental artifact
- Experimental repositories MUST clearly indicate their experimental/non-official
status in the README
- Any published packages MUST use naming that clearly indicates experimental
status
- The TSC retains oversight, including the ability to archive or remove
experimental repositories
## Lifecycle
Extensions and custom protocol bindings progress through the following phases.
### Proposal Phase
Any community member may propose an extension or custom protocol binding:
1. **Open an Issue**: Create an issue in the main `a2aproject/A2A` repository
describing:
- An abstract describing the extension's purpose or the binding's transport
and use case
- Motivation explaining why this cannot be achieved with the core protocol
or existing standard bindings
- An initial technical approach or specification draft
2. **Community Discussion**: The proposal is open for community feedback and
refinement
### Maintainer Sponsorship
For a proposal to proceed to experimental status:
1. **Secure a Sponsor**: An A2A Maintainer must agree to sponsor the proposal
2. **Repository Creation**: The sponsoring Maintainer creates the
`experimental-ext-*` or `experimental-cpb-*` repository under `a2aproject`
3. **Oversight**: The sponsoring Maintainer provides initial oversight and
ensures alignment with A2A design principles
### Experimental Development
While in experimental status:
- Contributors iterate on the specification and reference implementations
- The experimental artifact MAY be used by early adopters with the
understanding that breaking changes are expected
- Community feedback is gathered and incorporated
- The experimental repository MUST clearly indicate its non-official status
### Graduation to Official Status
To graduate an experimental extension or binding to official status:
1. **Maturity Requirements**:
- At least one production-quality reference implementation
- Documentation meeting A2A standards
- Evidence of community adoption or interest
- Clear maintainer commitment for ongoing maintenance
2. **Graduation Proposal**: Open an issue in `a2aproject/A2A` with:
- Reference to the experimental repository and its implementations
- Summary of community feedback and adoption
- Proposed maintainers for the official artifact
3. **TSC Vote**:
- The proposal is added to the TSC meeting agenda
- **Quorum Requirement**: At least 50% of TSC voting members must be
present
- **Approval**: Requires majority vote of those in attendance (per A2A
governance)
- The TSC may request revisions before a final vote
4. **Acceptance**:
- (Extensions) The repository is renamed from `experimental-ext-*` to
`ext-*`; documentation is added to the A2A website's extensions page
- (Custom Protocol Bindings) The repository is renamed from
`experimental-cpb-*` to `cpb-*`; documentation is added to the A2A
website's custom protocol bindings page
### Official Iteration
Once official, extensions and bindings may be iterated on:
- Repository maintainers are responsible for day-to-day governance
- Changes SHOULD be coordinated via the relevant working group if one exists
- Breaking changes require a new identifier
- Breaking changes require TSC review
- Maintainers SHOULD coordinate with SDK maintainers for implementation updates
### Promotion to Core Protocol
Some extensions may eventually transition to core protocol features, and some
custom protocol bindings may transition to core bindings. This is governed
through the existing A2A specification enhancement process:
- A proposal is submitted following the standard specification change process
- The proposal references the official extension or binding and its adoption
- TSC vote with standard quorum and majority requirements applies
- Not all extensions or bindings are suitable for core inclusion; many will
remain as extensions or custom bindings indefinitely
## SDK Support
SDK support requirements differ between extensions and official custom protocol
bindings, reflecting their different roles in the protocol ecosystem.
**Extensions**: A2A SDKs MAY implement extensions. Where implemented:
- Extensions MUST be disabled by default and require explicit opt-in
- SDK documentation SHOULD list supported extensions
- SDK maintainers have full autonomy over extension support decisions
- Extension support is not required for protocol conformance
**Official Custom Protocol Bindings**: A2A SDKs SHOULD implement official
custom protocol bindings. Where implemented:
- Custom protocol bindings MUST be disabled by default and require explicit
opt-in
- SDK documentation SHOULD list supported custom protocol bindings
- SDK maintainers have full autonomy over binding support decisions
- Custom protocol binding support is not required for protocol conformance
## Legal Requirements
### Licensing
Official extensions and custom protocol bindings MUST be available under the
Apache 2.0 license, consistent with the core A2A project.
### Contributor License Grant
By submitting a contribution to an official A2A extension or custom protocol
binding repository, contributors represent that:
1. They have the legal authority to grant the rights
2. The contribution is original work or they have sufficient rights to submit it
3. They grant to the Linux Foundation and recipients a perpetual, worldwide,
non-exclusive, royalty-free license to use, reproduce, modify, and
distribute the contribution
### Antitrust
Extension and custom protocol binding developers acknowledge that:
- They may compete with other participants
- They have no obligation to implement any extension or binding
- They are free to develop competing extensions or bindings
- Status as an official extension or binding does not create an exclusive
relationship
