A2A Documentation

File: README.md Copy Chapter

Agent2Agent (A2A) Protocol

🌐 Language

  
    [English](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=en)
    | [简体中文](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-CN)
    | [繁體中文](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-TW)
    | [日本語](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ja)
    | [한국어](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ko)
    | [हिन्दी](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=hi)
    | [ไทย](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=th)
    | [Français](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fr)
    | [Deutsch](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=de)
    | [Español](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=es)
    | [Italiano](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=it)
    | [Русский](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ru)
    | [Português](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=pt)
    | [Nederlands](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=nl)
    | [Polski](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=pl)
    | [العربية](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ar)
    | [فارسی](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fa)
    | [Türkçe](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=tr)
    | [Tiếng Việt](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=vi)
    | [Bahasa Indonesia](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=id)
    | [অসমীয়া](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=as)
  








<h1>Agent2Agent (A2A) Protocol</h1>

An open protocol enabling communication and interoperability between opaque agentic applications.

The Agent2Agent (A2A) protocol addresses a critical challenge in the AI landscape: enabling gen AI agents, built on diverse frameworks by different companies running on separate servers, to communicate and collaborate effectively - as agents, not just as tools. A2A aims to provide a common language for agents, fostering a more interconnected, powerful, and innovative AI ecosystem.

With A2A, agents can:

• Discover each other's capabilities.
• Negotiate interaction modalities (text, forms, media).
• Securely collaborate on long-running tasks.
• Operate without exposing their internal state, memory, or tools.

DeepLearning.AI Course Copy Chapter

Join this short course on A2A: The Agent2Agent Protocol, built in partnership with Google Cloud and IBM Research, and taught by Holt Skinner, Ivan Nardini, and Sandi Besen.

What you'll learn:

• Make agents A2A-compliant: Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.
• Connect agents: Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.
• Orchestrate workflows: Build sequential and hierarchical workflows of A2A-compliant agents.
• Multi-agent systems: Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.
• A2A and MCP: Learn how A2A complements MCP by enabling agents to collaborate with each other.

Why A2A? Copy Chapter

As AI agents become more prevalent, their ability to interoperate is crucial for building complex, multi-functional applications. A2A aims to:

• Break Down Silos: Connect agents across different ecosystems.
• Enable Complex Collaboration: Allow specialized agents to work together on tasks that a single agent cannot handle alone.
• Promote Open Standards: Foster a community-driven approach to agent communication, encouraging innovation and broad adoption.
• Preserve Opacity: Allow agents to collaborate without needing to share internal memory, proprietary logic, or specific tool implementations, enhancing security and protecting intellectual property.

Key Features Copy Section

• Standardized Communication: JSON-RPC 2.0 over HTTP(S).
• Agent Discovery: Via "Agent Cards" detailing capabilities and connection info.
• Flexible Interaction: Supports synchronous request/response, streaming (SSE), and asynchronous push notifications.
• Rich Data Exchange: Handles text, files, and structured JSON data.
• Enterprise-Ready: Designed with security, authentication, and observability in mind.

Getting Started Copy Chapter

• 📚 Explore the Documentation: Visit the Agent2Agent Protocol Documentation Site for a complete overview, the full protocol specification, tutorials, and guides.
• 📝 View the Specification: A2A Protocol Specification
• Use the SDKs:
  • 🐍 A2A Python SDK pip install a2a-sdk
  • 🐿️ A2A Go SDK go get github.com/a2aproject/a2a-go
  • 🧑‍💻 A2A JS SDK npm install @a2a-js/sdk
  • ☕️ A2A Java SDK using maven
  • 🔷 A2A .NET SDK using NuGet dotnet add package A2A
  • 🦀 A2A Rust SDK cargo add a2a-lf
• 🎬 Use our samples to see A2A in action

Contributing Copy Chapter

We welcome community contributions to enhance and evolve the A2A protocol!

• Questions & Discussions: Join our GitHub Discussions.
• Issues & Feedback: Report issues or suggest improvements via GitHub Issues.
• Contribution Guide: See our CONTRIBUTING.md for details on how to contribute.
• Private Feedback: Use this Google Form.
• Partner Program: Google Cloud customers can join our partner program via this form.

What's next Copy Chapter

Protocol Enhancements Copy Section

• Agent Discovery:
  • Formalize inclusion of authorization schemes and optional credentials directly within the AgentCard.
• Agent Collaboration:
  • Investigate a QuerySkill() method for dynamically checking unsupported or unanticipated skills.
• Task Lifecycle & UX:
  • Support for dynamic UX negotiation within a task (e.g., agent adding audio/video mid-conversation).
• Client Methods & Transport:
  • Explore extending support to client-initiated methods (beyond task management).
  • Improvements to streaming reliability and push notification mechanisms.

About Copy Chapter

The A2A Protocol is an open source project under the Linux Foundation, contributed by Google. It is licensed under the Apache License 2.0 and is open to contributions from the community.

File: docs/sdk/python/index.rst Copy Chapter

A2A Python SDK Reference

This page contains the SDK documentation for the a2a-sdk Python package.

.. code-block:: sh

pip install a2a-sdk

.. toctree::
:maxdepth: 4

modules

File: docs/sdk/index.md Copy Chapter

A2A SDK

The following table lists the supported languages for official A2A SDKs and their repositories.

The A2A project provides numerous samples across supported languages in the a2a-samples repository.

File: docs/sdk/python.md Copy Chapter

redirect: python/api/index.html Copy Chapter

Python SDK

Redirecting to API reference...

File: docs/topics/a2a-and-mcp.md Copy Chapter

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 (MCP) address these distinct but highly complementary needs.

Model Context Protocol Copy Chapter

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 Copy Chapter

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? Copy Chapter

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 Copy Chapter

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 Copy Section

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 Copy Chapter

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.

File: docs/topics/agent-discovery.md Copy Chapter

Agent Discovery in A2A

To collaborate using the Agent2Agent (A2A) protocol, AI agents need to first find each other and understand their capabilities. A2A standardizes agent self-descriptions through the Agent Card. However, discovery methods for these Agent Cards vary by environment and requirements. The Agent Card defines what an agent offers. Various strategies exist for a client agent to discover these cards. The choice of strategy depends on the deployment environment and security requirements.

The Role of the Agent Card Copy Chapter

The Agent Card is a JSON document that serves as a digital "business card" for an A2A Server (the remote agent). It is crucial for agent discovery and interaction. The key information included in an Agent Card is as follows:

• Identity: Includes name, description, and provider information.
• Service Endpoint: Specifies the url for the A2A service.
• A2A Capabilities: Lists supported features such as streaming or pushNotifications.
• Authentication: Details the required schemes (e.g., "Bearer", "OAuth2").
• Skills: Describes the agent's tasks using AgentSkill objects, including id, name, description, inputModes, outputModes, and examples.

Client agents use the Agent Card to determine an agent's suitability, structure requests, and ensure secure communication.

Discovery Strategies Copy Chapter

The following sections detail common strategies used by client agents to discover remote Agent Cards:

1. Well-Known URI Copy Section

This approach is recommended for public agents or agents intended for broad discovery within a specific domain.

• Mechanism: A2A Servers make their Agent Card discoverable by hosting it at a standardized, well-known URI on their domain. The standard path is https://{agent-server-domain}/.well-known/agent-card.json, following the principles of RFC 8615.

• Process:

  1. A client agent knows or programmatically discovers the domain of a potential A2A Server (e.g., smart-thermostat.example.com).
  2. The client performs an HTTP GET request to https://smart-thermostat.example.com/.well-known/agent-card.json.
  3. If the Agent Card exists and is accessible, the server returns it as a JSON response.

• Advantages:

  • Ease of implementation
  • Adheres to standards
  • Facilitates automated discovery

• Considerations:

  • Best suited for open or domain-controlled discovery scenarios.
  • Authentication is necessary at the endpoint serving the Agent Card if it contains sensitive details.

2. Curated Registries (Catalog-Based Discovery) Copy Section

This approach is employed in enterprise environments or public marketplaces, where Agent Cards are often managed by a central registry. The curated registry acts as a central repository, allowing clients to query and discover agents based on criteria like "skills" or "tags".

• Mechanism: An intermediary service (the registry) maintains a collection of Agent Cards. Clients query this registry to find agents based on various criteria (e.g., skills offered, tags, provider name, capabilities).

• Process:

  1. A2A Servers publish their Agent Cards to the registry.
  2. Client agents query the registry's API, and search by criteria such as "specific skills".
  3. The registry returns matching Agent Cards or references.

• Advantages:

  • Centralized management and governance.
  • Capability-based discovery (e.g., by skill).
  • Support for access controls and trust frameworks.
  • Applicable in both private and public marketplaces.

• Considerations:

  • Requires deployment and maintenance of a registry service.
  • The current A2A specification does not prescribe a standard API for curated registries.

3. Direct Configuration / Private Discovery Copy Section

This approach is used for tightly coupled systems, private agents, or development purposes, where clients are directly configured with Agent Card information or URLs.

• Mechanism: Client applications utilize hardcoded details, configuration files, environment variables, or proprietary APIs for discovery.
• Process: The process is specific to the application's deployment and configuration strategy.
• Advantages: This method is straightforward for establishing connections within known, static relationships.
• Considerations:
  • Inflexible for dynamic discovery scenarios.
  • Changes to Agent Card information necessitate client reconfiguration.
  • Proprietary API-based discovery also lacks standardization.

Securing Agent Cards Copy Chapter

Agent Cards include sensitive information, such as:

• URLs for internal or restricted agents.
• Descriptions of sensitive skills.

Protection Mechanisms Copy Section

To mitigate risks, the following protection mechanisms should be considered:

• Authenticated Agent Cards: We recommend the use of authenticated extended agent cards for sensitive information or for serving a more detailed version of the card.

• Secure Endpoints: Implement access controls on the HTTP endpoint serving the Agent Card (e.g., /.well-known/agent-card.json or registry API). The methods include:

  • Mutual TLS (mTLS)
  • Network restrictions (e.g., IP ranges)
  • HTTP Authentication (e.g., OAuth 2.0)

• Registry Selective Disclosure: Registries return different Agent Cards based on the client's identity and permissions.

Any Agent Card containing sensitive data must be protected with authentication and authorization mechanisms. The A2A specification strongly recommends the use of out-of-band dynamic credentials rather than embedding static secrets within the Agent Card.

Caching Considerations Copy Chapter

Agent Cards describe an agent's capabilities and typically change infrequently — for example, when skills are added or authentication requirements are updated. Applying standard HTTP caching practices to Agent Card endpoints reduces unnecessary network requests while ensuring clients eventually receive updated information.

Server Guidance Copy Section

Servers hosting Agent Card endpoints should include HTTP caching headers in their responses. The Cache-Control header with an appropriate max-age directive allows clients and intermediaries to cache the card for a specified duration. Including an ETag header — derived from the card's version field or a content hash — enables clients to make conditional requests and avoid re-downloading unchanged cards.

Client Guidance Copy Section

Clients fetching Agent Cards should honor standard HTTP caching semantics. When a cached card expires, clients should use conditional requests (for example, If-None-Match with the stored ETag or If-Modified-Since) rather than unconditionally re-fetching the full card. When the server does not provide caching headers, clients may apply a reasonable default cache duration.

For Extended Agent Cards, clients should also follow the session-scoped caching guidance described in the specification.

For normative requirements, see Section 8.6 of the specification.

Future Considerations Copy Chapter

The A2A community explores standardizing registry interactions or advanced discovery protocols.

File: docs/topics/enterprise-ready.md Copy Chapter

Enterprise Implementation of A2A

The Agent2Agent (A2A) protocol is designed with enterprise requirements at its
core. Rather than inventing new, proprietary standards for security and
operations, A2A aims to integrate seamlessly with existing enterprise
infrastructure and widely adopted best practices. This approach allows
organizations to use their existing investments and expertise in security,
monitoring, governance, and identity management.

A key principle of A2A is that agents are typically opaque because they don't
share internal memory, tools, or direct resource access with each other. This
opacity naturally aligns with standard client-server security paradigms,
treating remote agents as standard HTTP-based enterprise applications.

Transport Level Security (TLS) Copy Chapter

Ensuring the confidentiality and integrity of data in transit is fundamental for
any enterprise application.

• HTTPS Mandate: All A2A communication in production environments must
  occur over HTTPS.
• Modern TLS Standards: Implementations should use modern TLS versions.
  TLS 1.2 or higher is recommended. Strong, industry-standard cipher suites
  should be used to protect data from eavesdropping and tampering.
• Server Identity Verification: A2A clients should verify the A2A server's
  identity by validating its TLS certificate against trusted certificate
  authorities during the TLS handshake. This prevents man-in-the-middle
  attacks.

Authentication Copy Chapter

A2A delegates authentication to standard web mechanisms. It primarily relies on
HTTP headers and established standards like OAuth2 and OpenID Connect.
Authentication requirements are advertised by the A2A server in its Agent Card.

• No Identity in Payload: A2A protocol payloads, such as JSON-RPC
  messages, don't carry user or client identity information directly. Identity
  is established at the transport/HTTP layer.
• Agent Card Declaration: The A2A server's Agent Card describes the
  authentication schemes it supports in its security field and aligns with
  those defined in the OpenAPI Specification for authentication.
• Out-of-Band Credential Acquisition: The A2A Client obtains the necessary credentials,
  such as OAuth 2.0 tokens or API keys, through processes external to the A2A protocol itself. Examples include OAuth flows or secure key distribution.
• HTTP Header Transmission: Credentials must be transmitted in standard
  HTTP headers as per the requirements of the chosen authentication scheme.
  Examples include Authorization: Bearer <TOKEN> or API-Key: <KEY_VALUE>.
• 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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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.

File: docs/topics/extensions.md Copy Chapter

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 Copy Chapter

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 Copy Chapter

Extension Governance Copy Chapter

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-).

!!! note "URI Namespaces"
The https://a2a-protocol.org/extensions/ prefix is a canonical namespace
for globally unique extension identifiers used in Agent Cards and protocol
messages. Individual URIs under this prefix, such as
https://a2a-protocol.org/extensions/{name}/v1 identify a specific
extension and version. These URIs are identifiers, HTTP access is not
expected. See URI namespaces
in the governance documentation for details.

For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
Extension and Protocol Binding Governance
page.

Limitations Copy Chapter

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 Copy Chapter

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:

{
  "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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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:

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/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 Copy Chapter

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
    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 Copy

    --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 blog post.

File: docs/topics/key-concepts.md Copy Chapter

Core Concepts and Components in A2A

A2A uses a set of core concepts that define how agents interact.
Understand these core building blocks to develop or integrate with A2A-compliant
systems.

{ width="70%" style="margin:20px auto;display:block;" }

Core Actors in A2A Interactions Copy Chapter

• User: The end user, which can be a human operator or an automated
  service. The user initiates a request or defines a goal that requires
  assistance from one or more AI agents.
• A2A Client (Client Agent): An application, service, or another AI agent
  that acts on behalf of the user. The client initiates communication using the
  A2A protocol.
• A2A Server (Remote Agent): An AI agent or an agentic system that exposes
  an HTTP endpoint implementing the A2A protocol. It receives requests from
  clients, processes tasks, and returns results or status updates. From the client's perspective,
  the remote agent operates as an opaque (black-box) system, meaning its internal workings, memory, or tools are not exposed.

Fundamental Communication Elements Copy Chapter

The following table describes the fundamental communication elements in A2A:

Interaction Mechanisms Copy Chapter

The A2A Protocol supports various interaction patterns to accommodate different
needs for responsiveness and persistence. These mechanisms ensure that agents
can exchange information efficiently and reliably, regardless of the task's
complexity or duration:

• Request/Response (Polling): Clients send a request and the server
  responds. For long-running tasks, the client periodically polls the server
  for updates.
• Streaming with Server-Sent Events (SSE): Clients initiate a stream to
  receive real-time, incremental results or status updates from the server
  over an open HTTP connection.
• Push Notifications: For very long-running tasks or disconnected
  scenarios, the server can actively send asynchronous notifications to a
  client-provided webhook when significant task updates occur.

For a detailed exploration of streaming and push notifications, refer to the
Streaming & Asynchronous Operations document.

Agent Cards Copy Chapter

The Agent Card is a JSON document that serves as a digital business card for
initial discovery and interaction setup. It provides essential metadata about an
agent. Clients parse this information to determine if an agent is suitable for a
given task, how to structure requests, and how to communicate securely. Key
information includes identity, service endpoint (URL), A2A capabilities,
authentication requirements, and a list of skills.

Messages and Parts Copy Chapter

A message represents a single turn of communication between a client and an
agent. It includes a role ("user" or "agent") and a unique messageId. It
contains one or more Part objects, which are granular containers for the actual
content. This design allows A2A to be modality independent.

The Part object is a flexible container that can hold different types of content using a oneof field structure. A Part must contain exactly one of the following content fields:

• text: A string containing plain textual content.
• raw: A byte array containing binary file data (inline).
• url: A string URI referencing external file content.
• data: A structured JSON value (e.g., object, array) for machine-readable data.

Additionally, every Part can include:

• mediaType: The MIME type of the content (e.g., "text/plain", "image/png", "application/json").
• filename: An optional name for the file or content.
• metadata: A key-value map for additional context.

Artifacts Copy Chapter

An artifact represents a tangible output or a concrete result generated by a
remote agent during task processing. Unlike general messages, artifacts are the
actual deliverables. An artifact has a unique artifactId, a human-readable
name, and consists of one or more part objects. Artifacts are closely tied to the
task lifecycle and can be streamed incrementally to the client.

Agent Response: Task or Message Copy Chapter

The agent response can be a new Task (when the agent needs to perform a
long-running operation) or a Message (when the agent can respond immediately).

For more details, see Life of a Task.

Other Important Concepts Copy Chapter

• Context (contextId): A server-generated identifier that can be used to logically group multiple related Task objects, providing context across a series of interactions.
• Transport and Format: A2A communication occurs over HTTP(S). JSON-RPC 2.0 is used as the payload format for all requests and responses.
• Authentication & Authorization: A2A relies on standard web security practices. Authentication requirements are declared in the Agent Card, and credentials (e.g., OAuth tokens, API keys) are typically passed through HTTP headers, separate from the A2A protocol messages themselves. For more information, see Enterprise-Ready Features.
• Agent Discovery: The process by which clients find Agent Cards to learn about available A2A Servers and their capabilities. For more information, see Agent Discovery.
• Extensions: A2A allows agents to declare custom protocol extensions as part of their AgentCard. For more information, see Extensions.

File: docs/topics/life-of-a-task.md Copy Chapter

Life of a Task

In the Agent2Agent (A2A) Protocol, interactions can range from simple, stateless
exchanges to complex, long-running processes. When an agent receives a message
from a client, it can respond in one of two fundamental ways:

• Respond with a Stateless Message: This type of response is
  typically used for immediate, self-contained interactions that conclude
  without requiring further state management.
• Initiate a Stateful Task: If the response is a Task, the agent will
  process it through a defined lifecycle, communicating progress and requiring
  input as needed, until it reaches an interrupted state (e.g.,
  input-required, auth-required) or a terminal state (e.g., completed,
  canceled, rejected, failed).

Group Related Interactions Copy Chapter

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

• When a client sends a message for the first time, the agent responds
  with a new contextId. If a task is initiated, it will also have a taskId.
• Clients can send subsequent messages and include the same contextId to
  indicate that they are continuing their previous interaction within the same
  context.
• Clients optionally attach the taskId to a subsequent message to
  indicate that it continues that specific task.

The contextId enables collaboration towards a common goal or a shared
contextual session across multiple, potentially concurrent tasks. Internally, an
A2A agent (especially one using an LLM) uses the contextId to manage its internal
conversational state or its LLM context.

Agent Response: Message or Task Copy Chapter

The choice between responding with a Message or a Task depends on the
nature of the interaction and the agent's capabilities:

• Messages for Trivial Interactions: Message objects are suitable for
  transactional interactions that don't require long-running
  processing or complex state management. An agent might use messages to
  negotiate the acceptance or scope of a task before committing to a Task
  object.
• Tasks for Stateful Interactions: Once an agent maps the intent of an
  incoming message to a supported capability that requires substantial,
  trackable work over an extended period, the agent responds with a Task
  object.

Conceptually, agents operate at different levels of complexity:

• Message-only Agents: Always respond with Message objects. They
  typically don't manage complex state or long-running executions, and use
  contextId to tie messages together. These agents might directly wrap LLM
  invocations and simple tools.
• Task-generating Agents: Always respond with Task objects, even for
  responses, which are then modeled as completed tasks. Once a task is
  created, the agent will only return Task objects in response to messages
  sent, and once a task is complete, no more messages can be sent. This
  approach avoids deciding between Task versus Message, but creates completed task objects
  for even simple interactions.
• Hybrid Agents: Generate both Message and Task objects. These agents
  use messages to negotiate agent capability and the scope of work for a task,
  then send a Task object to track execution and manage states like
  input-required or error handling. Once a task is created, the agent will
  only return Task objects in response to messages sent, and once a task is
  complete, no more messages can be sent. A hybrid agent uses messages to
  negotiate the scope of a task, and then generates a task to track its
  execution.
  For more information about hybrid agents, see A2A protocol: Demystifying Tasks vs Messages.

Task Refinements Copy Chapter

Clients often need to send new requests based on task results or refine the
outputs of previous tasks. This is modeled by starting another interaction using
the same contextId as the original task. Clients further hint the agent by
providing references to the original task using referenceTaskIds in the
Message object. The agent then responds with either a new Task or a
Message.

Task Immutability Copy Chapter

Once a task reaches a terminal state (completed, canceled, rejected, or failed),
it cannot restart. Any subsequent interaction related to that task, such as a
refinement, must initiate a new task within the same contextId. This principle
offers several benefits:

• Task Immutability. Clients reliably reference tasks and their
  associated state, artifacts, and messages, providing a clean mapping of
  inputs to outputs. This is valuable for orchestration and traceability.
• Clear Unit of Work. Every new request, refinement, or follow-up becomes
  a distinct task. This simplifies bookkeeping, allows for granular tracking
  of an agent's work, and enables tracing each artifact to a specific unit of
  work.
• Easier Implementation. This removes ambiguity for agent developers
  regarding whether to create a new task or restart an existing one.

Parallel Follow-ups Copy Chapter

A2A supports parallel work by enabling agents to create distinct, parallel
tasks for each follow-up message sent within the same contextId. This allows
clients to track individual tasks and create new dependent tasks as soon as a
prerequisite task is complete.

For example:

• Task 1: Book a flight to Helsinki.
• Task 2: Based on Task 1, book a hotel.
• Task 3: Based on Task 1, book a snowmobile activity.
• Task 4: Based on Task 2, add a spa reservation to the hotel booking.

Referencing Previous Artifacts Copy Chapter

The serving agent infers the relevant artifact from a referenced task or from the
contextId. As the domain expert, the serving agent is best suited to resolve
ambiguity or identify missing information. If there is ambiguity, the agent asks
the client for clarification by returning an input-required state. The client
then specifies the artifact in its response, optionally populating artifact
references (artifactId, taskId) in Part metadata.

Tracking Artifact Mutation Copy Chapter

Follow-up or refinement tasks often lead to the creation of new artifacts based on older ones. Tracking these mutations is important to ensure that only the most recent version of an artifact is used in subsequent interactions. This could be conceptualized as a version history, where each new artifact is linked to its predecessor.

However, the client is in the best position to manage this artifact linkage. The client determines what constitutes an acceptable result and has the ability to accept or reject new versions. Therefore, the serving agent shouldn't be responsible for tracking artifact mutations, and this linkage is not part of the A2A protocol specification. Clients should maintain this version history on their end and present the latest acceptable version to the user.

To facilitate client-side tracking, serving agents should use a consistent artifact-name when generating a refined version of an existing artifact.

When initiating follow-up or refinement tasks, the client should explicitly reference the specific artifact they intend to refine, ideally the "latest" version from their perspective. If the artifact reference is not provided, the serving agent can:

• Attempt to infer the intended artifact based on the current contextId.
• If there is ambiguity or insufficient context, the agent should respond with an input-required task state to request clarification from the client.

Example Follow-up Scenario Copy Chapter

The following example illustrates a typical task flow with a follow-up:

1. Client sends a message to the agent:

   json Copy

   {
     "jsonrpc": "2.0",
     "id": "req-001",
     "method": "SendMessage",
     "params": {
       "message": {
         "role": "user",
         "parts": [
           {
             "text": "Generate an image of a sailboat on the ocean."
           }
         ],
         "messageId": "msg-user-001"
       }
     }
   }

2. Agent responds with a boat image (completed task):

   json Copy

   {
     "jsonrpc": "2.0",
     "id": "req-001",
     "result": {
       "task": {
         "id": "task-boat-gen-123",
         "contextId": "ctx-conversation-abc",
         "status": {
           "state": "TASK_STATE_COMPLETED"
         },
         "artifacts": [
           {
             "artifactId": "artifact-boat-v1-xyz",
             "name": "sailboat_image.png",
             "description": "A generated image of a sailboat on the ocean.",
             "parts": [
               {
                 "filename": "sailboat_image.png",
                 "mediaType": "image/png",
                 "raw": "base64_encoded_png_data_of_a_sailboat"
               }
             ]
           }
         ]
       }
     }
   }

3. Client asks to color the boat red. This refinement request refers to the
   previous taskId and uses the same contextId.

   json Copy

   {
     "jsonrpc": "2.0",
     "id": "req-002",
     "method": "SendMessage",
     "params": {
       "message": {
         "role": "user",
         "messageId": "msg-user-002",
         "contextId": "ctx-conversation-abc",
         "referenceTaskIds": [
           "task-boat-gen-123"
         ],
         "parts": [
           {
             "text": "Please modify the sailboat to be red."
           }
         ]
       }
     }
   }

4. Agent responds with a new image artifact (new task, same context, same
   artifact name): The agent creates a new task within the same contextId. The
   new boat image artifact retains the same name but has a new artifactId.

   json Copy

   {
     "jsonrpc": "2.0",
     "id": "req-002",
     "result": {
       "task": {
         "id": "task-boat-color-456",
         "contextId": "ctx-conversation-abc",
         "status": {
           "state": "TASK_STATE_COMPLETED"
         },
         "artifacts": [
           {
             "artifactId": "artifact-boat-v2-red-pqr",
             "name": "sailboat_image.png",
             "description": "A generated image of a red sailboat on the ocean.",
             "parts": [
               {
                 "filename": "sailboat_image.png",
                 "mediaType": "image/png",
                 "raw": "base64_encoded_png_data_of_a_RED_sailboat"
               }
             ]
           }
         ]
       }
     }
   }