## File: README.md

# Agent2Agent (A2A) Protocol

[](https://pypi.org/project/a2a-sdk)
[](LICENSE)
<a href="https://codewiki.google/github.com/a2aproject/a2a">
  
</a>


  
    🌐 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

[](https://goo.gle/dlai-a2a)

Join this short course on [A2A: The Agent2Agent Protocol](https://goo.gle/dlai-a2a), built in partnership with Google Cloud and IBM Research, and taught by [Holt Skinner](https://github.com/holtskinner), [Ivan Nardini](https://github.com/inardini), and [Sandi Besen](https://github.com/sandijean90).

**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?

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

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

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

## Contributing

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

- **Questions & Discussions:** Join our [GitHub Discussions](https://github.com/a2aproject/A2A/discussions).
- **Issues & Feedback:** Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
- **Contribution Guide:** See our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.
- **Private Feedback:** Use this [Google Form](https://goo.gle/a2a-feedback).
- **Partner Program:** Google Cloud customers can join our partner program via this [form](https://goo.gle/a2a-partner).

## What's next

### Protocol Enhancements

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

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

---

## File: docs/sdk/python/index.rst

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

# A2A SDK

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

| Language   | Repository                                               |
|------------|----------------------------------------------------------|
| Python     | [`a2a-python`](https://github.com/a2aproject/a2a-python) |
| Go         | [`a2a-go`](https://github.com/a2aproject/a2a-go)         |
| Java       | [`a2a-java`](https://github.com/a2aproject/a2a-java)     |
| JavaScript | [`a2a-js`](https://github.com/a2aproject/a2a-js)         |
| C#/.NET    | [`a2a-dotnet`](https://github.com/a2aproject/a2a-dotnet) |
| Rust       | [`a2a-rs`](https://github.com/a2aproject/a2a-rs)         |

The A2A project provides numerous samples across supported languages in the [a2a-samples repository](https://github.com/a2aproject/a2a-samples).

---

## File: docs/sdk/python.md

---
redirect: python/api/index.html
---

# Python SDK

Redirecting to [API reference](python/api/index.html)...

---

## File: docs/topics/a2a-and-mcp.md

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

---

## File: docs/topics/agent-discovery.md

# 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](../specification.md#8-agent-discovery-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

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

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

### 1. Well-Known URI

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](https://datatracker.ietf.org/doc/html/rfc8615).

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

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

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

Agent Cards include sensitive information, such as:

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

### Protection Mechanisms

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

- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#3111-get-extended-agent-card) 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

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

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

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](../specification.md#133-extended-agent-card-access-control).

For normative requirements, see [Section 8.6](../specification.md#86-caching) of the specification.

## Future Considerations

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

---

## File: docs/topics/enterprise-ready.md

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

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

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

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.

---

## File: docs/topics/extensions.md

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

!!! 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](extension-and-binding-governance.md#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](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.

---

## File: docs/topics/key-concepts.md

# 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

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

The following table describes the fundamental communication elements in A2A:

| Element | Description | Key Purpose |
| :------ | :---------- | :---------- |
| Agent Card | A JSON metadata document describing an agent's identity, capabilities, endpoint, skills, and authentication requirements. | Enables clients to discover agents and understand how to interact with them securely and effectively. |
| Task | A stateful unit of work initiated by an agent, with a unique ID and defined lifecycle. | Facilitates tracking of long-running operations and enables multi-turn interactions and collaboration. |
| Message | A single turn of communication between a client and an agent, containing content and a role ("user" or "agent"). | Conveys instructions, context, questions, answers, or status updates that are not necessarily formal artifacts. |
| Part | The fundamental content container used within Messages and Artifacts. A Part holds one of: text content, a file reference (URL or inline bytes), or structured data. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
| Artifact | A tangible output generated by an agent during a task (for example, a document, image, or structured data). | Delivers the concrete results of an agent's work, ensuring structured and retrievable outputs. |

## Interaction Mechanisms

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](./streaming-and-async.md) document.

## Agent Cards

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

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

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

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](./life-of-a-task.md).

## Other Important Concepts

- **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](./enterprise-ready.md).
- **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](./agent-discovery.md).
- **Extensions:** A2A allows agents to declare custom protocol extensions as part of their AgentCard. For more information, see [Extensions](./extensions.md).

---

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

# 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

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

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](https://discuss.google.dev/t/a2a-protocol-demystifying-tasks-vs-messages/255879).

## Task Refinements

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

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

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

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

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

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

1. Client sends a message to the agent:

    ```json
    {
      "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
    {
      "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
    {
      "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
    {
      "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"
                }
              ]
            }
          ]
        }
      }
    }
    ```