a2a 0.1.0.pre → 0.2.0

data/.agent-docs/topics/a2a-and-mcp.md

@@ -0,0 +1,132 @@
+# 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.
+
+<div style="text-align: center; margin: 20px;" markdown>
+
+![Diagram showing A2A and MCP working together. A User interacts with Agent A using A2A. Agent A interacts with Agent B using A2A. Agent B uses MCP to interact with Tool 1 and Tool 2.](../assets/a2a-mcp.png){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._
+
+</div>
+
+### 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.

data/.agent-docs/topics/agent-discovery.md

@@ -0,0 +1,96 @@
+# 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#5-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#710-agentgetauthenticatedextendedcard) 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.
+
+## Future Considerations
+
+The A2A community explores standardizing registry interactions or advanced discovery protocols.

data/.agent-docs/topics/enterprise-ready.md

@@ -0,0 +1,139 @@
+# 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.

data/.agent-docs/topics/extensions.md

@@ -0,0 +1,260 @@
+# 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' sub-state 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.
+
+## 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.
+
+```ts { .no-copy }
+--8<-- "types/src/types.ts: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
+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
+    `X-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 `X-A2A-Extensions` header, listing all
+    extensions that were successfully activated for that request.
+
+![A2A Extension Flow Diagram](https://storage.googleapis.com/gweb-developer-goog-blog-assets/images/Screenshot_2025-09-04_at_13.03.31.original.png){ 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
+X-A2A-Extensions: https://example.com/ext/konami-code/v1
+Content-Length: 519
+{
+  "jsonrpc": "2.0",
+  "method": "message/send",
+  "id": "1",
+  "params": {
+    "message": {
+      "kind": "message",
+      "messageId": "1",
+      "role": "user",
+      "parts": [{"kind": "text", "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
+X-A2A-Extensions: https://example.com/ext/konami-code/v1
+Content-Length: 338
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "kind": "message",
+    "messageId": "2",
+    "role": "agent",
+    "parts": [{"kind": "text", "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 (Future)**: The A2A community might establish a
+        central registry for discovering and browsing available extensions in
+        the future.
+- **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.