If the flagged items are :exploding_head: false positives
\n\nIf items relate to a ...\n\n- binary file (or some other file you wouldn't want to check at all).\n\n Please add a file path to the `excludes.txt` file matching the containing file.\n\n File paths are Perl 5 Regular Expressions - you can [test](https://www.regexplanet.com/advanced/perl/) yours before committing to verify it will match your files.\n\n `^` refers to the file's path from the root of the repository, so `^README\\.md$` would exclude `README.md` (on whichever branch you're using).\n\n- well-formed pattern.\n\n If you can write a [pattern](https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-patterns) that would match it,\n try adding it to the `patterns.txt` file.\n\n Patterns are Perl 5 Regular Expressions - you can [test](https://www.regexplanet.com/advanced/perl/) yours before committing to verify it will match your lines.\n\n Note that patterns can't match multiline strings.\n\n![\"Ask](\"https://www.gstatic.com/_/boq-sdlc-agents-ui/_/r/Mvosg4klCA4.svg\")
\n\n\n\n \n
\n\n\n\n
\n\n**An open protocol enabling communication and interoperability between opaque agentic applications.**\n\nThe 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.\n\nWith A2A, agents can:\n\n- Discover each other's capabilities.\n- Negotiate interaction modalities (text, forms, media).\n- Securely collaborate on long-running tasks.\n- Operate without exposing their internal state, memory, or tools.\n\n## DeepLearning.AI Course\n\n[](https://goo.gle/dlai-a2a)\n\nJoin 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).\n\n**What you'll learn:**\n\n- **Make agents A2A-compliant:** Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.\n- **Connect agents:** Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.\n- **Orchestrate workflows:** Build sequential and hierarchical workflows of A2A-compliant agents.\n- **Multi-agent systems:** Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.\n- **A2A and MCP:** Learn how A2A complements MCP by enabling agents to collaborate with each other.\n\n## Why A2A?\n\nAs AI agents become more prevalent, their ability to interoperate is crucial for building complex, multi-functional applications. A2A aims to:\n\n- **Break Down Silos:** Connect agents across different ecosystems.\n- **Enable Complex Collaboration:** Allow specialized agents to work together on tasks that a single agent cannot handle alone.\n- **Promote Open Standards:** Foster a community-driven approach to agent communication, encouraging innovation and broad adoption.\n- **Preserve Opacity:** Allow agents to collaborate without needing to share internal memory, proprietary logic, or specific tool implementations, enhancing security and protecting intellectual property.\n\n### Key Features\n\n- **Standardized Communication:** JSON-RPC 2.0 over HTTP(S).\n- **Agent Discovery:** Via \"Agent Cards\" detailing capabilities and connection info.\n- **Flexible Interaction:** Supports synchronous request/response, streaming (SSE), and asynchronous push notifications.\n- **Rich Data Exchange:** Handles text, files, and structured JSON data.\n- **Enterprise-Ready:** Designed with security, authentication, and observability in mind.\n\n## Getting Started\n\n- 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://a2a-protocol.org) for a complete overview, the full protocol specification, tutorials, and guides.\n- 📝 **View the Specification:** [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/)\n- Use the SDKs:\n - [🐍 A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk`\n - [🐿️ A2A Go SDK](https://github.com/a2aproject/a2a-go) `go get github.com/a2aproject/a2a-go`\n - [🧑💻 A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk`\n - [☕️ A2A Java SDK](https://github.com/a2aproject/a2a-java) using maven\n - [🔷 A2A .NET SDK](https://github.com/a2aproject/a2a-dotnet) using [NuGet](https://www.nuget.org/packages/A2A) `dotnet add package A2A`\n- 🎬 Use our [samples](https://github.com/a2aproject/a2a-samples) to see A2A in action\n\n## Contributing\n\nWe welcome community contributions to enhance and evolve the A2A protocol!\n\n- **Questions & Discussions:** Join our [GitHub Discussions](https://github.com/a2aproject/A2A/discussions).\n- **Issues & Feedback:** Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).\n- **Contribution Guide:** See our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.\n- **Private Feedback:** Use this [Google Form](https://goo.gle/a2a-feedback).\n- **Partner Program:** Google Cloud customers can join our partner program via this [form](https://goo.gle/a2a-partner).\n\n## What's next\n\n### Protocol Enhancements\n\n- **Agent Discovery:**\n - Formalize inclusion of authorization schemes and optional credentials directly within the `AgentCard`.\n- **Agent Collaboration:**\n - Investigate a `QuerySkill()` method for dynamically checking unsupported or unanticipated skills.\n- **Task Lifecycle & UX:**\n - Support for dynamic UX negotiation _within_ a task (e.g., agent adding audio/video mid-conversation).\n- **Client Methods & Transport:**\n - Explore extending support to client-initiated methods (beyond task management).\n - Improvements to streaming reliability and push notification mechanisms.\n\n## About\n\nThe 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.\n"
},
{
"path": "SECURITY.md",
"content": "# Security Policy\n\nTo report a security issue, please use email \n ![\"Agent2Agent](\"docs/assets/a2a-logo-black.svg\")
\n
\n\n Agent2Agent (A2A) Protocol
\nA2A - Page Not Found
\nWe are attempting to redirect you to the latest version of this page.
\nIf you are not redirected automatically, please navigate to the A2A project homepage.
\n\n\n\n" }, { "path": "docs/README.md", "content": "# A2A Docs\n\nProtobuf
\n The normative A2A protocol definition in Protocol Buffers (proto3 syntax).\n This is the source of truth for the A2A protocol specification.\n\nDownload
\n\n You can download the proto file directly: [`a2a.proto`](spec/a2a.proto)\n\nDefinition
\n\n ```protobuf\n --8<-- \"docs/spec/a2a.proto\"\n ```\n\n=== \"JSON\"\nJSON
\n The A2A protocol JSON Schema definition (JSON Schema 2020-12 compliant).\n This schema is automatically generated from the protocol buffer definitions and bundled into a single file with all message definitions.\n\nDownload
\n\n You can download the schema file directly: [`a2a.json`](spec/a2a.json)\n\nDefinition
\n\n ```json\n --8<-- \"docs/spec/a2a.json\"\n ```\n" }, { "path": "docs/index.md", "content": "---\nhide:\n - toc\n---\n\n\n\n
\n\n## What is A2A Protocol?\n\nWelcome to the **official documentation** for the **Agent2Agent (A2A) Protocol**, an open standard designed to enable seamless communication and collaboration between AI agents.\n\nOriginally developed by Google and now donated to the Linux Foundation, A2A provides the definitive common language for agent interoperability in a world where agents are built using diverse frameworks and by different vendors.\n\n!!! abstract \"\"\n Build with\n **[{class=\"twemoji lg middle\"} ADK](https://google.github.io/adk-docs/)** _(or any framework)_,\n equip with **[{class=\"twemoji lg middle\"} MCP](https://modelcontextprotocol.io)** _(or any tool)_,\n and communicate with\n **{class=\"twemoji lg middle\"} A2A**,\n to remote agents, local agents, and humans.\n\n## Get started with A2A\n\n\n ![\"Agent2Agent](\"assets/a2a-logo-black.svg\")
\n
\n\n Agent2Agent (A2A) Protocol
\n\n\n- :material-play-circle:{ .lg .middle } **Video** Intro in <8 min\n\n \n\n- :material-play-circle:{ .lg .middle } **Course** [DeepLearning.AI](https://deeplearning.ai) - Intro to A2A\n\n [](https://goo.gle/dlai-a2a)\n\n- :material-book-open:{ .lg .middle } **Read the Introduction**\n\n Understand the core ideas behind A2A.\n\n [:octicons-arrow-right-24: What is A2A?](./topics/what-is-a2a.md)\n\n [:octicons-arrow-right-24: Key Concepts](./topics/key-concepts.md)\n\n- :material-file-document-outline:{ .lg .middle } **Dive into the Specification**\n\n Explore the detailed technical definition of the A2A protocol.\n\n [:octicons-arrow-right-24: Protocol Specification](./specification.md)\n\n- :material-application-cog-outline:{ .lg .middle } **Follow the Tutorials**\n\n Build your first A2A-compliant agent with our step-by-step Python quickstart.\n\n [:octicons-arrow-right-24: Python Tutorial](./tutorials/python/1-introduction.md)\n\n [:octicons-arrow-right-24: Walkthrough with AI Agent Frameworks](https://github.com/holtskinner/A2AWalkthrough)\n\n- :material-code-braces:{ .lg .middle } **Explore Code Samples**\n\n See A2A in action with sample clients, servers, and agent framework integrations.\n\n [:fontawesome-brands-github: GitHub Samples](https://github.com/a2aproject/a2a-samples)\n\n- :material-code-braces:{ .lg .middle } **Download the Official SDKs**\n\n [:fontawesome-brands-python: Python](https://github.com/a2aproject/a2a-python)\n\n [:fontawesome-brands-js: JavaScript](https://github.com/a2aproject/a2a-js)\n\n [:fontawesome-brands-java: Java](https://github.com/a2aproject/a2a-java)\n\n [:octicons-code-24: C#/.NET](https://github.com/a2aproject/a2a-dotnet)\n\n [:fontawesome-brands-golang: Golang](https://github.com/a2aproject/a2a-go)\n\n
\n\n## Why use the A2A Protocol\n\n\n\n```mermaid\ngraph LR\n User(🧑💻 User) <--> ClientAgent(🤖 Client Agent)\n ClientAgent --> A2A1(**↔️ A2A**) --> RemoteAgent1(🤖 Remote Agent 1)\n ClientAgent --> A2A2(**↔️ A2A**) --> RemoteAgent2(🤖 Remote Agent 2)\n\n style User fill:#fdebd0,stroke:#e67e22,stroke-width:2px\n style ClientAgent fill:#d6eaf8,stroke:#3498db,stroke-width:2px\n style RemoteAgent1 fill:#d6eaf8,stroke:#3498db,stroke-width:2px\n style RemoteAgent2 fill:#d6eaf8,stroke:#3498db,stroke-width:2px\n style A2A1 fill:#ebedef,stroke:#909497,stroke-width:2px\n style A2A2 fill:#ebedef,stroke:#909497,stroke-width:2px\n```\n\n
\n\n\n\n- :material-account-group-outline:{ .lg .middle } **Interoperability**\n\n Connect agents built on different platforms (LangGraph, CrewAI, Semantic Kernel, custom solutions) to create powerful, composite AI systems.\n\n- :material-lan-connect:{ .lg .middle } **Complex Workflows**\n\n Enable agents to delegate sub-tasks, exchange information, and coordinate actions to solve complex problems that a single agent cannot.\n\n- :material-shield-key-outline:{ .lg .middle } **Secure & Opaque**\n\n Agents interact without needing to share internal memory, tools, or proprietary logic, ensuring security and preserving intellectual property.\n\n
\n\n---\n\n## How does A2A work with MCP?\n\n{width=\"60%\"}\n{style=\"text-align: center; margin-bottom:1em; margin-top:1em;\"}\n\nA2A and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) are complementary standards for building robust agentic applications:\n\n- **Model Context Protocol (MCP)**: Provides [agent-to-tool communication](https://cloud.google.com/discover/what-is-model-context-protocol). It's a complementary standard that standardizes how an agent connects to its tools, APIs, and resources to get information.\n- **IBM ACP**: [Incorporated into the A2A Protocol](https://github.com/orgs/i-am-bee/discussions/5)\n- **Cisco agntcy**: A framework that provides components to the Internet of Agents with discovery, group communication, identity and observability and leverages A2A and MCP for agent communication and tool calling.\n- **A2A**: Provides agent-to-agent communication. As a universal, decentralized standard, A2A acts as the public internet that allows [ai agents](https://cloud.google.com/discover/what-are-ai-agents)—including those using MCP, or built with frameworks like agntcy—to interoperate, collaborate, and share their findings.\n"
},
{
"path": "docs/llms.txt",
"content": "# A2A (Agent2Agent) Protocol High-Level Summary\n\nThis project defines the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. It allows agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely without exposing internal state.\n\nThe repository contains:\n1. **Formal Specification:** Protobuf definitions (`specification/a2a.proto`) and JSON Schema (`specification/json/a2a.json`).\n2. **Core Concepts Documentation:** Guides on discovery, task lifecycle, streaming, and enterprise-readiness (`docs/topics/`).\n3. **SDKs:** Production-ready SDKs for Python, JS/TS, Java, Go, and .NET.\n4. **Sample Implementations:** Real-world examples integrated with various agent frameworks.\n\n## Key Files & Directories\n\n- `specification/a2a.proto`: The authoritative Protobuf definition of the protocol.\n- `docs/topics/`: Detailed conceptual guides (Discovery, Lifecycle, Security, etc.).\n- `docs/tutorials/`: Step-by-step guides for building A2A-compliant agents.\n- `scripts/`: Utility scripts for building documentation and formatting.\n\n# A2A (Agent2Agent) Protocol Reference\n\n## 1. Overview\n\n- **Purpose:** Open standard for agent-to-agent interoperability.\n- **Communication Bindings:** Supports JSON-RPC 2.0 (HTTP/SSE), gRPC, and HTTP/REST.\n- **Key Concepts:** Agent Cards for discovery, Task-based execution, Multi-turn Messages, and Artifact outputs.\n\n## 2. Core Data Objects\n\n### 2.1 AgentCard (`/.well-known/agent-card.json`)\nDescribes an agent's identity and capabilities.\n- `name`, `description`, `version`: Identity metadata.\n- `supported_interfaces`: List of `AgentInterface` (URL, protocol binding, tenant, protocol version).\n- `capabilities`: `streaming`, `push_notifications`, `extended_agent_card`, `extensions`.\n- `skills`: List of `AgentSkill` (id, name, description, tags, examples).\n- `security_schemes`, `security_requirements`: Authentication configuration (API Key, OAuth2, OIDC, mTLS, HTTP Auth).\n- `default_input_modes`, `default_output_modes`: Supported MIME types (e.g., `text/plain`, `application/json`).\n\n### 2.2 Task\nRepresents a stateful unit of work.\n- `id`, `context_id`: Identifiers for the task and its conversational context.\n- `status`: `TaskStatus` (state, message, timestamp).\n- `artifacts`: List of `Artifact` (outputs produced).\n- `history`: List of `Message` (conversation history).\n- `metadata`: Custom structured data.\n\n### 2.3 TaskState (Enum)\n- `SUBMITTED`, `WORKING`, `COMPLETED` (terminal), `FAILED` (terminal), `CANCELED` (terminal), `REJECTED` (terminal), `INPUT_REQUIRED` (interrupted), `AUTH_REQUIRED` (interrupted).\n\n### 2.4 Message & Part\n- `Message`: Contains `message_id`, `role` (USER/AGENT), `parts`, `context_id`, `task_id`, `reference_task_ids`.\n- `Part`: Union type containing `text`, `raw` (bytes), `url`, or `data` (JSON). Includes `media_type` and `filename`.\n\n### 2.5 Artifact\n- A tangible output from a task, containing one or more `Part`s and metadata.\n\n## 3. RPC Methods\n\n| Method | Request | Response | Description |\n| :--- | :--- | :--- | :--- |\n| `SendMessage` | `SendMessageRequest` | `SendMessageResponse` | Initiates or continues a task. |\n| `SendStreamingMessage` | `SendMessageRequest` | `stream StreamResponse` | Sends message and receives real-time SSE updates. |\n| `GetTask` | `GetTaskRequest` | `Task` | Retrieves current task state. |\n| `ListTasks` | `ListTasksRequest` | `ListTasksResponse` | Filter and paginate tasks. |\n| `CancelTask` | `CancelTaskRequest` | `Task` | Requests cancellation of a task. |\n| `SubscribeToTask` | `SubscribeToTaskRequest` | `stream StreamResponse` | Subscribes to updates for an existing task. |\n| `GetExtendedAgentCard` | `GetExtendedAgentCardRequest` | `AgentCard` | Fetches detailed metadata after authentication. |\n\n### 3.1 Streaming Events (`StreamResponse`)\nStreams return a payload containing one of:\n- `task`: Full task state.\n- `message`: A discrete message part.\n- `status_update`: `TaskStatusUpdateEvent` (taskId, contextId, status).\n- `artifact_update`: `TaskArtifactUpdateEvent` (taskId, artifact, append, last_chunk).\n\n## 4. Security & Authentication\n- **Transport:** HTTPS/TLS required for production.\n- **Authentication:** Declared in `AgentCard` via OpenAPI-style security schemes.\n- **Push Notifications:** Webhooks secured via authentication tokens/schemes configured per task.\n\n## 5. Implementation Status\n- **Official SDKs:** Python (`a2a-sdk`), JS/TS (`@a2a-js/sdk`), Java, Go, C#/.NET.\n- **Integrations:** LangGraph, CrewAI, Google ADK, Genkit, AG2, BeeAI, PydanticAI, and more.\n"
},
{
"path": "docs/partners.md",
"content": "# Partners\n\nBelow is a list of partners (and a link to their A2A announcement or blog post,\nif available) who are part of the A2A community and are helping build, codify,\nand adopt A2A as the standard protocol for AI agents to communicate and\ncollaborate effectively with each other and with users.\n\n- [A2A Net](https://a2anet.com)\n- [Accelirate Inc](https://www.accelirate.com)\n- [Accenture](https://www.accenture.com)\n- [Activeloop](https://www.activeloop.ai/)\n- [Adobe](https://www.adobe.com)\n- [AG2AI](https://ag2.ai)\n- [AgentTrust](https://agenttrust.ai/)\n- [AI21 Labs](https://www.ai21.com/)\n- [AI71](https://ai71.ai/)\n- [Aisera](https://aisera.com/)\n- [AliCloud](http://www.alibabacloud.com)\n- [Almawave.it](https://www.almawave.com/it/)\n- [AmikoNet](https://amikonet.ai)\n- [ArcBlock](http://www.arcblock.io)\n- [Arize](https://arize.com/blog/arize-ai-and-future-of-agent-interoperability-embracing-googles-a2a-protocol/)\n- [Articul8](https://www.articul8.ai/blog/unleashing-the-next-frontier-of-enterprise-ai-introducing-model-mesh-dock-and-inter-lock-and-our-a2-a-partnership-with-google)\n- [ask-ai.com](https://ask-ai.com)\n- [Atlassian](https://www.atlassian.com)\n- [Auth0](https://auth0.com/blog/auth0-google-a2a/)\n- [Autodesk](https://www.autodesk.com)\n- [AWS](https://aws.amazon.com/)\n- [Beekeeper](http://beekeeper.io)\n- [BCG](https://www.bcg.com)\n- [Block Inc](https://block.xyz/)\n- [Bloomberg LP](https://techatbloomberg.com/)\n- [BLUEISH Inc](https://www.blueish.co.jp/)\n- [BMC Software Inc](https://www.bmc.com/it-solutions/bmc-helix.html)\n- [Boomi](https://boomi.com/)\n- [Box](https://www.box.com)\n- [Bridge2Things Automation Process GmbH](http://bridge2things.at)\n- [Cafe 24](https://www.cafe24corp.com/en/company/about)\n- [C3 AI](https://c3.ai)\n- [Capgemini](https://www.capgemini.com)\n- [Chronosphere](https://chronosphere.io)\n- [Cisco](https://www.cisco.com/)\n- [Codimite PTE LTD](https://codimite.ai/)\n- [Cognigy](https://www.cognigy.com/)\n- [Cognizant](https://www.cognizant.com)\n- [Cohere](https://cohere.com)\n- [Collibra](https://www.collibra.com)\n- [Confluent](https://developer.confluent.io)\n- [Contextual](https://contextual.ai)\n- [Cotality](https://cotality.com) (fka Corelogic)\n- [Crubyt](https://www.crubyt.com)\n- [Cyderes](http://www.cyderes.com)\n- [Datadog](https://www.datadoghq.com)\n- [DataRobot](https://www.datarobot.com)\n- [DataStax](https://www.datastax.com)\n- [Decagon.ai](https://decagon.ai)\n- [Deloitte](https://www.prnewswire.com/news-releases/deloitte-expands-alliances-with-google-cloud-and-servicenow-to-accelerate-agentic-ai-adoption-in-the-enterprise-302423941.html)\n- [Devnagri](https://devnagri.com)\n- [Deutsche Telekom](https://www.telekom.com/en)\n- [Dexter Tech Labs](http://www.dextertechlabs.com)\n- [Distyl.ai](https://distyl.ai)\n- [Elastic](https://www.elastic.co)\n- [Ema.co](https://ema.co)\n- [EPAM](https://www.epam.com)\n- [Eviden (Atos Group)](https://atos.net/)\n- [fractal.ai](https://fractal.ai/new)\n- [GenAI Nebula9.ai Solutions Pvt Ltd](http://nebula9.ai)\n- [Glean](https://www.glean.com)\n- [Global Logic](https://www.globallogic.com/)\n- [Gravitee](https://www.gravitee.io/)\n- [GrowthLoop](https://growthloop.com)\n- [Guru](http://www.getguru.com)\n- [Harness](https://harness.io)\n- [HCLTech](https://www.hcltech.com)\n- [Headwaters](https://www.headwaters.co.jp)\n- [Hellotars](https://hellotars.com)\n- [Hexaware](https://hexaware.com/)\n- [HUMAN](https://www.humansecurity.com/)\n- [IBM Research](https://lfaidata.foundation/communityblog/2025/08/29/acp-joins-forces-with-a2a-under-the-linux-foundations-lf-ai-data/)\n- [Incorta](https://www.incorta.com)\n- [Infinitus](https://www.infinitus.ai/)\n- [InfoSys](https://www.infosys.com)\n- [Intuit](https://www.intuit.com)\n- [Iron Mountain](https://www.ironmountain.com/)\n- [JamJet](https://github.com/jamjet-labs/jamjet)\n- [JetBrains](https://www.jetbrains.com)\n- [JFrog](https://jfrog.com)\n- [Kakao](https://www.kakaocorp.com)\n- [King's College London](https://www.kcl.ac.uk/informatics)\n- [KPMG](https://kpmg.com/us/en/media/news/kpmg-google-cloud-alliance-expansion-agentspace-adoption.html)\n- [Kyndryl](http://www.kyndryl.com)\n- [LabelBox](https://labelbox.com)\n- [LangChain](https://www.langchain.com)\n- [LG CNS](http://www.lgcns.com)\n- [Livex.ai](https://livex.ai)\n- [LlamaIndex](https://x.com/llama_index/status/1912949446322852185)\n- [LTIMindTtree](https://www.ltimindtree.com)\n- [Lumeris](https://www.lumeris.com/)\n- [Lyzr.ai](https://lyzr.ai)\n- [Magyar Telekom](https://www.telekom.hu/)\n- [MasOrange](https://masorange.es/en/)\n- [Microsoft](https://www.microsoft.com/en-us/microsoft-cloud/blog/2025/05/07/empowering-multi-agent-apps-with-the-open-agent2agent-a2a-protocol/)\n- [MindsDB](https://mindsdb.com/blog/mindsdb-now-supports-the-agent2agent-(a2a)-protocol)\n- [McKinsey](https://www.mckinsey.com)\n- [MongoDB](https://www.mongodb.com)\n- [Monite](https://monite.com/)\n- [Neo4j](https://neo4j.com)\n- [New Relic](https://newrelic.com)\n- [Nisum](http://www.nisum.com)\n- [Noorle Inc](http://www.noorle.com)\n- [NTT DATA](https://www.nttdata.com)\n- [Optimizely Inc](https://www.optimizely.com/)\n- [Oracle / NetSuite](https://www.oracle.com/netsuite)\n- [Palo Alto Networks](https://www.paloaltonetworks.com/)\n- [PancakeAI](https://www.pancakeai.tech/)\n- [ParkourSC](https://www.parkoursc.com/)\n- [Pendo](https://www.pendo.io)\n- [PerfAI.ai](https://perfai.ai)\n- [Personal AI](https://personal.ai)\n- [Pinchwork](https://pinchwork.dev)\n- [Poppulo](https://www.poppulo.com/blog/poppulo-google-a2a-the-future-of-workplace-communication)\n- [Productive Edge](https://www.productiveedge.com/)\n- [Proofs](https://proofs.io)\n- [Publicis Sapient](https://www.publicissapient.com/)\n- [PWC](https://www.pwc.com)\n- [Quantiphi](https://www.quantiphi.com)\n- [Radix](https://radix.website/)\n- [RagaAI Inc](https://raga.ai/)\n- [Red Hat](https://www.redhat.com)\n- [Reltio Inc](http://www.reltio.com)\n- [S&P](https://www.spglobal.com)\n- [Sage](https://www.sage.com/en-us/)\n- [Salesforce](https://www.salesforce.com)\n- [SAP](https://news.sap.com/2025/04/sap-google-cloud-enterprise-ai-open-agent-collaboration-model-choice-multimodal-intelligence/)\n- [Sayone Technologies](https://www.sayonetech.com/)\n- [ServiceNow](https://www.servicenow.com)\n- [Siemens AG](https://siemens.com/)\n- [SoftBank Corp](https://www.softbank.jp/en//)\n- [Solace](https://solace.com/products/agent-mesh/)\n- [Solo.io](https://www.solo.io/)\n- [Stacklok, Inc](https://stacklok.com)\n- [Supertab](https://www.supertab.co/post/supertab-connect-partners-with-google-cloud-to-enable-ai-agents)\n- [Suzega](https://suzega.com/)\n- [TCS](https://www.tcs.com)\n- [Tech Mahindra](https://www.techmahindra.com/)\n- [Telefonica](https://www.telefonica.com/)\n- [Test Innovation Technology](https://www.test-it.com)\n- [the artinet project](https://artinet.io/)\n- [Think41](http://www.think41.com)\n- [Thoughtworks](https://www.thoughtworks.com/)\n- [Tredence](http://www.tredence.com)\n- [Two Tall Totems Ltd. DBA TTT Studios](https://ttt.studio)\n- [Typeface](https://typeface.ai)\n- [UKG](https://www.ukg.com)\n- [UiPath](https://www.uipath.com/newsroom/uipath-launches-first-enterprise-grade-platform-for-agentic-automation)\n- [Upwork, Inc.](https://www.upwork.com/)\n- [Ushur, Inc.](http://ushur.ai)\n- [Valle AI](http://www.valleai.com.br)\n- [Valtech](https://www.valtech.com/)\n- [Vervelo](https://www.vervelo.com/)\n- [VoltAgent](https://voltagent.dev/)\n- [Weights & Biases](https://wandb.ai/wandb_fc/product-announcements-fc/reports/Powering-Agent-Collaboration-Weights-Biases-Partners-with-Google-Cloud-on-Agent2Agent-Interoperability-Protocol---VmlldzoxMjE3NDg3OA)\n- [Wipro](https://www.wipro.com)\n- [Workday](https://www.workday.com)\n- [WritBase](https://github.com/Writbase/writbase)\n- [Writer](https://writer.com)\n- [Zenity](https://zenity.io)\n- [Zeotap](https://www.zeotap.com)\n- [Zocket Technologies , Inc.](https://zocket.ai)\n- [Zoom](https://www.zoom.us)\n- [zyprova](http://www.zyprova.com)\n"
},
{
"path": "docs/roadmap.md",
"content": "# A2A protocol roadmap\n\n**Last updated:** March 10, 2026\n\n## Near-term initiatives\n\n- Release `1.0` version of the protocol which represents significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.\n- [What's New in A2A Protocol v1.0](https://a2a-protocol.org/latest/whats-new-v1/) has further updates. \n- Continue to support additional [A2A extensions](topics/extensions.md) with SDK support. \n- Prioritize community-led development with standardized processes for contributing to the specification, SDKs and tooling.\n\nTo review recent protocol changes see [Release Notes](https://github.com/a2aproject/A2A/releases).\n\n## Longer term (3-6 month period) roadmap\n\n### Governance\n\nThe TSC looks to streamline opportunities for contribution through [A2A extensions](topics/extensions.md), [Samples](https://github.com/a2aproject/a2a-samples) and participation.\n\n\n### Validation\n\nAs the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).\n\n### SDKs\n\nA2A Project currently hosts SDKs in five languages (Python, Go, JS, Java, .NET).\n\n### Community best practices\n\nAs companies and individuals deploy A2A systems at an increasing pace, we are looking to accelerate the learning of the community by collecting and sharing the best practices and success stories that A2A enabled.\n"
},
{
"path": "docs/robots.txt",
"content": "# Allow all crawlers to access the entire site.\nUser-agent: *\nAllow: /\n\n# Generative AI and LLM crawlers\nUser-agent: GPTBot\nAllow: /\n\nUser-agent: ChatGPT-User\nAllow: /\n\nUser-agent: ClaudeBot\nAllow: /\n\nUser-agent: Claude-Web\nAllow: /\n\nUser-agent: PerplexityBot\nAllow: /\n\nUser-agent: FacebookBot\nAllow: /\n\nUser-agent: Applebot\nAllow: /\n\nUser-agent: PerplexityBot\nAllow: /\n\nUser-agent: Google-Extended\nAllow: /\n\nUser-agent: GoogleOther\nAllow: /\n\nUser-agent: DuckAssistBot\nAllow: /\n\nSitemap: https://a2a-protocol.org/latest/sitemap.xml\n"
},
{
"path": "docs/sdk/index.md",
"content": "# A2A SDK\n\nA2A currently hosts SDKs in five languages (Python, Go, JS, Java, .NET).\n\nThe following table lists the supported languages and their stability.\n\n| Language | Support |\n| :--------- | :------- |\n| Python | [Stable](https://github.com/a2aproject/a2a-python) |\n| Go | [Stable](https://github.com/a2aproject/a2a-go) |\n| Java | [Stable](https://github.com/a2aproject/a2a-java) |\n| JavaScript | [Stable](https://github.com/a2aproject/a2a-js) |\n| C#/.NET | [Stable](https://github.com/a2aproject/a2a-dotnet) |\n\nThe A2A project provides numerous samples across supported languages in the [a2a-samples repository](https://github.com/a2aproject/a2a-samples).\n"
},
{
"path": "docs/sdk/python.md",
"content": "---\nredirect: python/api/index.html\n---\n\n# Python SDK\n\nRedirecting to [API reference](python/api/index.html)...\n"
},
{
"path": "docs/specification.md",
"content": "# Agent2Agent (A2A) Protocol Specification\n\n??? note \"**Latest Released Version** [`1.0.0`](https://a2a-protocol.org/v1.0.0/specification)\"\n\n **Previous Versions**\n\n - [`0.3.0`](https://a2a-protocol.org/v0.3.0/specification)\n - [`0.2.6`](https://a2a-protocol.org/v0.2.6/specification)\n - [`0.1.0`](https://a2a-protocol.org/v0.1.0/specification)\n\nSee [Release Notes](https://github.com/a2aproject/A2A/releases) for changes made between versions.\n\n## 1. Introduction\n\nThe Agent2Agent (A2A) Protocol is an open standard designed to facilitate communication and interoperability between independent, potentially opaque AI agent systems. In an ecosystem where agents might be built using different frameworks, languages, or by different vendors, A2A provides a common language and interaction model.\n\nThis document provides the detailed technical specification for the A2A protocol. Its primary goal is to enable agents to:\n\n- Discover each other's capabilities.\n- Negotiate interaction modalities (text, files, structured data).\n- Manage collaborative tasks.\n- Securely exchange information to achieve user goals **without needing access to each other's internal state, memory, or tools.**\n\n### 1.1. Key Goals of A2A\n\n- **Interoperability:** Bridge the communication gap between disparate agentic systems.\n- **Collaboration:** Enable agents to delegate tasks, exchange context, and work together on complex user requests.\n- **Discovery:** Allow agents to dynamically find and understand the capabilities of other agents.\n- **Flexibility:** Support various interaction modes including synchronous request/response, streaming for real-time updates, and asynchronous push notifications for long-running tasks.\n- **Security:** Facilitate secure communication patterns suitable for enterprise environments, relying on standard web security practices.\n- **Asynchronicity:** Natively support long-running tasks and interactions that may involve human-in-the-loop scenarios.\n\n### 1.2. Guiding Principles\n\n- **Simple:** Reuse existing, well-understood standards (HTTP, JSON-RPC 2.0, Server-Sent Events).\n- **Enterprise Ready:** Address authentication, authorization, security, privacy, tracing, and monitoring by aligning with established enterprise practices.\n- **Async First:** Designed for (potentially very) long-running tasks and human-in-the-loop interactions.\n- **Modality Agnostic:** Support exchange of diverse content types including text, audio/video (via file references), structured data/forms, and potentially embedded UI components (e.g., iframes referenced in parts).\n- **Opaque Execution:** Agents collaborate based on declared capabilities and exchanged information, without needing to share their internal thoughts, plans, or tool implementations.\n\nFor a broader understanding of A2A's purpose and benefits, see [What is A2A?](./topics/what-is-a2a.md).\n\n### 1.3. Specification Structure\n\nThis specification is organized into three distinct layers that work together to provide a complete protocol definition:\n\n```mermaid\ngraph TB\n subgraph L1 [\"A2A Data Model\"]\n direction LR\n A[Task] ~~~ B[Message] ~~~ C[AgentCard] ~~~ D[Part] ~~~ E[Artifact] ~~~ F[Extension]\n end\n\n subgraph L2 [\"A2A Operations\"]\n direction LR\n G[Send Message] ~~~ H[Stream Message] ~~~ I[Get Task] ~~~ J[List Tasks] ~~~ K[Cancel Task] ~~~ L[Get Agent Card]\n end\n\n subgraph L3 [\"Protocol Bindings\"]\n direction LR\n M[JSON-RPC Methods] ~~~ N[gRPC RPCs] ~~~ O[HTTP/REST Endpoints] ~~~ P[Custom Bindings]\n end\n\n %% Dependencies between layers\n L1 --> L2\n L2 --> L3\n\n\n style A fill:#e1f5fe\n style B fill:#e1f5fe\n style C fill:#e1f5fe\n style D fill:#e1f5fe\n style E fill:#e1f5fe\n style F fill:#e1f5fe\n\n style G fill:#f3e5f5\n style H fill:#f3e5f5\n style I fill:#f3e5f5\n style J fill:#f3e5f5\n style K fill:#f3e5f5\n style L fill:#f3e5f5\n\n style M fill:#e8f5e8\n style N fill:#e8f5e8\n style O fill:#e8f5e8\n\n style L1 fill:#f0f8ff,stroke:#333,stroke-width:2px\n style L2 fill:#faf0ff,stroke:#333,stroke-width:2px\n style L3 fill:#f0fff0,stroke:#333,stroke-width:2px\n```\n\n**Layer 1: Canonical Data Model** defines the core data structures and message formats that all A2A implementations must understand. These are protocol agnostic definitions expressed as Protocol Buffer messages.\n\n**Layer 2: Abstract Operations** describes the fundamental capabilities and behaviors that A2A agents must support, independent of how they are exposed over specific protocols.\n\n**Layer 3: Protocol Bindings** provides concrete mappings of the abstract operations and data structures to specific protocol bindings (JSON-RPC, gRPC, HTTP/REST), including method names, endpoint patterns, and protocol-specific behaviors.\n\nThis layered approach ensures that:\n\n- Core semantics remain consistent across all protocol bindings\n- New protocol bindings can be added without changing the fundamental data model\n- Developers can reason about A2A operations independently of binding concerns\n- Interoperability is maintained through shared understanding of the canonical data model\n\n### 1.4 Normative Content\n\nIn addition to the protocol requirements defined in this document, the file `spec/a2a.proto` is the single authoritative normative definition of all protocol data objects and request/response messages. A generated JSON artifact (`spec/a2a.json`, produced at build time and not committed) MAY be published for convenience to tooling and the website, but it is a non-normative build artifact. SDK language bindings, schemas, and any other derived forms **MUST** be regenerated from the proto (directly or via code generation) rather than edited manually.\n\n**Change Control and Deprecation Lifecycle:**\n\n- Introduction: When a proto message or field is renamed, the new name is added while existing published names remain available, but marked deprecated, until the next major release.\n- Documentation: Migration guidance MUST be provided via an ancillary document when introducing major breaking changes.\n- Anchors: Legacy documentation anchors MUST be preserved (as hidden HTML anchors) to avoid breaking inbound links.\n- SDK/Schema Aliases: SDKs and JSON Schemas SHOULD provide deprecated alias types/definitions to maintain backward compatibility.\n- Removal: A deprecated name SHOULD NOT be removed earlier than the next major version after introduction of its replacement.\n\n**Automated Generation:**\n\nThe documentation build generates `specification/json/a2a.json` on-the-fly (the file is not tracked in source control). Future improvements may publish an OpenAPI v3 + JSON Schema bundle for enhanced tooling.\n\n**Rationale:**\n\nCentering the proto file as the normative source ensures protocol neutrality, reduces specification drift, and provides a deterministic evolution path for the ecosystem.\n\n## 2. Terminology\n\n### 2.1. Requirements Language\n\nThe keywords \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).\n\n### 2.2. Core Concepts\n\nA2A revolves around several key concepts. For detailed explanations, please refer to the [Key Concepts guide](./topics/key-concepts.md).\n\n- **A2A Client:** An application or agent that initiates requests to an A2A Server on behalf of a user or another system.\n- **A2A Server (Remote Agent):** An agent or agentic system that exposes an A2A-compliant endpoint, processing tasks and providing responses.\n- **Agent Card:** A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements.\n- **Message:** A communication turn between a client and a remote agent, having a `role` (\"user\" or \"agent\") and containing one or more `Parts`.\n- **Task:** The fundamental unit of work managed by A2A, identified by a unique ID. Tasks are stateful and progress through a defined lifecycle.\n- **Part:** The smallest unit of content within a Message or Artifact. Parts can contain text, file references, or structured data.\n- **Artifact:** An output (e.g., a document, image, structured data) generated by the agent as a result of a task, composed of `Parts`.\n- **Streaming:** Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via protocol-specific streaming mechanisms.\n- **Push Notifications:** Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios.\n- **Context:** An optional identifier to logically group related tasks and messages.\n- **Extension:** A mechanism for agents to provide additional functionality or data beyond the core A2A specification.\n\n## 3. A2A Protocol Operations\n\nThis section describes the core operations of the A2A protocol in a binding-independent manner. These operations define the fundamental capabilities that all A2A implementations must support, regardless of the underlying binding mechanism.\n\n### 3.1. Core Operations\n\nThe following operations define the fundamental capabilities that all A2A implementations must support, independent of the specific protocol binding used. For a quick reference mapping of these operations to protocol-specific method names and endpoints, see [Section 5.3 (Method Mapping Reference)](#53-method-mapping-reference). For detailed protocol-specific implementation details, see:\n\n- [Section 9: JSON-RPC Protocol Binding](#9-json-rpc-protocol-binding)\n- [Section 10: gRPC Protocol Binding](#10-grpc-protocol-binding)\n- [Section 11: HTTP+JSON/REST Protocol Binding](#11-httpjsonrest-protocol-binding)\n\n#### 3.1.1. Send Message\n\nThe primary operation for initiating agent interactions. Clients send a message to an agent and receive either a task that tracks the processing or a direct response message.\n\n**Inputs:**\n\n- [`SendMessageRequest`](#321-sendmessagerequest): Request object containing the message, configuration, and metadata\n\n**Outputs:**\n\n- [`Task`](#411-task): A task object representing the processing of the message, OR\n- [`Message`](#414-message): A direct response message (for simple interactions that don't require task tracking)\n\n**Errors:**\n\n- [`ContentTypeNotSupportedError`](#332-error-handling): A Media Type provided in the request's message parts is not supported by the agent.\n- [`UnsupportedOperationError`](#332-error-handling): Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages.\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n\n**Behavior:**\n\nThe agent MAY create a new `Task` to process the provided message asynchronously or MAY return a direct `Message` response for simple interactions. The operation MUST return immediately with either task information or response message. Task processing MAY continue asynchronously after the response when a [`Task`](#411-task) is returned.\n\n#### 3.1.2. Send Streaming Message\n\nSimilar to Send Message but with real-time streaming of updates during processing.\n\n**Inputs:**\n\n- [`SendMessageRequest`](#321-sendmessagerequest): Request object containing the message, configuration, and metadata\n\n**Outputs:**\n\n- [`Stream Response`](#323-stream-response) object containing:\n - Initial response: [`Task`](#411-task) object OR [`Message`](#414-message) object\n - Subsequent events following a `Task` MAY include stream of [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) and [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects\n- Final completion indicator\n\n**Errors:**\n\n- [`UnsupportedOperationError`](#332-error-handling): Streaming is not supported by the agent (see [Capability Validation](#334-capability-validation)).\n- [`UnsupportedOperationError`](#332-error-handling): Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages.\n- [`ContentTypeNotSupportedError`](#332-error-handling): A Media Type provided in the request's message parts is not supported by the agent.\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n\n**Behavior:**\n\nThe operation MUST establish a streaming connection for real-time updates. The stream MUST follow one of these patterns:\n\n1. **Message-only stream:** If the agent returns a [`Message`](#414-message), the stream MUST contain exactly one `Message` object and then close immediately. No task tracking or updates are provided.\n\n2. **Task lifecycle stream:** If the agent returns a [`Task`](#411-task), the stream MUST begin with the Task object, followed by zero or more [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) or [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects. The stream MUST close when the task reaches a terminal state (e.g. completed, failed, canceled, rejected).\n\nThe agent MAY return a `Task` for complex processing with status/artifact updates or MAY return a `Message` for direct streaming responses without task overhead. The implementation MUST provide immediate feedback on progress and intermediate results.\n\n#### 3.1.3. Get Task\n\nRetrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with message/send, or for fetching the final state of a task after being notified via a push notification or after a stream has ended.\n\n**Inputs:**\n\n{{ proto_to_table(\"GetTaskRequest\") }}\n\nSee [History Length Semantics](#324-history-length-semantics) for details about `historyLength`.\n\n**Outputs:**\n\n- [`Task`](#411-task): Current state and artifacts of the requested task\n\n**Errors:**\n\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n\n#### 3.1.4. List Tasks\n\nRetrieves a list of tasks with optional filtering and pagination capabilities. This method allows clients to discover and manage multiple tasks across different contexts or with specific status criteria.\n\n**Inputs:**\n\n{{ proto_to_table(\"ListTasksRequest\") }}\n\nWhen `includeArtifacts` is false (the default), the artifacts field MUST be omitted entirely from each Task object in the response. The field should not be present as an empty array or null value. When `includeArtifacts` is true, the artifacts field should be included with its actual content (which may be an empty array if the task has no artifacts).\n\n**Outputs:**\n\n{{ proto_to_table(\"ListTasksResponse\") }}\n\nNote on `nextPageToken`: The `nextPageToken` field MUST always be present in the response. When there are no more results to retrieve (i.e., this is the final page), the field MUST be set to an empty string (\"\"). Clients should check for an empty string to determine if more pages are available.\n\n**Errors:**\n\nNone specific to this operation beyond standard protocol errors.\n\n**Behavior:**\n\nThe operation MUST return only tasks visible to the authenticated client and MUST use cursor-based pagination for performance and consistency. Tasks MUST be sorted by last update time in descending order. Implementations MUST implement appropriate authorization scoping to ensure clients can only access authorized tasks. See [Section 13.1 Data Access and Authorization Scoping](#131-data-access-and-authorization-scoping) for detailed security requirements.\n\n***Pagination Strategy:***\n\nThis method uses cursor-based pagination (via `pageToken`/`nextPageToken`) rather than offset-based pagination for better performance and consistency, especially with large datasets. Cursor-based pagination avoids the \"deep pagination problem\" where skipping large numbers of records becomes inefficient for databases. This approach is consistent with the gRPC specification, which also uses cursor-based pagination (page_token/next_page_token).\n\n***Ordering:***\n\nImplementations MUST return tasks sorted by their status timestamp time in descending order (most recently updated tasks first). This ensures consistent pagination and allows clients to efficiently monitor recent task activity.\n\n#### 3.1.5. Cancel Task\n\nRequests the cancellation of an ongoing task. The server will attempt to cancel the task, but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage).\n\n**Inputs:**\n\n{{ proto_to_table(\"CancelTaskRequest\") }}\n\n**Outputs:**\n\n- Updated [`Task`](#411-task) with cancellation status\n\n**Errors:**\n\n- [`TaskNotCancelableError`](#332-error-handling): The task is not in a cancelable state (e.g., already completed, failed, or canceled).\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n\n**Behavior:**\n\nThe operation attempts to cancel the specified task and returns its updated state.\n\n#### 3.1.6. Subscribe to Task\n\n\n\nEstablishes a streaming connection to receive updates for an existing task.\n\n**Inputs:**\n\n{{ proto_to_table(\"SubscribeToTaskRequest\") }}\n\n**Outputs:**\n\n- [`Stream Response`](#323-stream-response) object containing:\n - Initial response: [`Task`](#411-task) object with current state\n - Stream of [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) and [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects\n\n**Errors:**\n\n- [`UnsupportedOperationError`](#332-error-handling): Streaming is not supported by the agent (see [Capability Validation](#334-capability-validation)).\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n- [`UnsupportedOperationError`](#332-error-handling): The operation is attempted on a task that is in a terminal state (`completed`, `failed`, `canceled`, or `rejected`).\n\n**Behavior:**\n\nThe operation enables real-time monitoring of task progress and can be used with any task that is not in a terminal state. The stream MUST terminate when the task reaches a terminal state (`completed`, `failed`, `canceled`, or `rejected`).\n\nThe operation MUST return a `Task` object as the first event in the stream, representing the current state of the task at the time of subscription. This prevents a potential loss of information between a call to `GetTask` and calling `SubscribeToTask`.\n\n#### 3.1.7. Create Push Notification Config\n\n\n\n\nCreates a push notification configuration for a task to receive asynchronous updates via webhook.\n\n**Inputs:**\n\n{{ proto_to_table(\"CreateTaskPushNotificationConfigRequest\") }}\n\n**Outputs:**\n\n- [`PushNotificationConfig`](#431-pushnotificationconfig): Created configuration with assigned ID\n\n**Errors:**\n\n- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n\n**Behavior:**\n\nThe operation MUST establish a webhook endpoint for task update notifications. When task updates occur, the agent will send HTTP POST requests to the configured webhook URL with [`StreamResponse`](#323-stream-response) payloads (see [Push Notification Payload](#433-push-notification-payload) for details). This operation is only available if the agent supports push notifications capability. The configuration MUST persist until task completion or explicit deletion.\n\n \n\n#### 3.1.8. Get Push Notification Config\n\n\n\nRetrieves an existing push notification configuration for a task.\n\n**Inputs:**\n\n{{ proto_to_table(\"GetTaskPushNotificationConfigRequest\") }}\n\n**Outputs:**\n\n- [`PushNotificationConfig`](#431-pushnotificationconfig): The requested configuration\n\n**Errors:**\n\n- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).\n- [`TaskNotFoundError`](#332-error-handling): The push notification configuration does not exist.\n\n**Behavior:**\n\nThe operation MUST return configuration details including webhook URL and notification settings. The operation MUST fail if the configuration does not exist or the client lacks access.\n\n#### 3.1.9. List Push Notification Configs\n\nRetrieves all push notification configurations for a task.\n\n**Inputs:**\n\n{{ proto_to_table(\"ListTaskPushNotificationConfigsRequest\") }}\n\n**Outputs:**\n\n{{ proto_to_table(\"ListTaskPushNotificationConfigsResponse\") }}\n\n**Errors:**\n\n- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible.\n\n**Behavior:**\n\nThe operation MUST return all active push notification configurations for the specified task and MAY support pagination for tasks with many configurations.\n\n#### 3.1.10. Delete Push Notification Config\n\nRemoves a push notification configuration for a task.\n\n**Inputs:**\n\n{{ proto_to_table(\"DeleteTaskPushNotificationConfigRequest\") }}\n\n**Outputs:**\n\n- Confirmation of deletion (implementation-specific)\n\n**Errors:**\n\n- [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)).\n- [`TaskNotFoundError`](#332-error-handling): The task ID does not exist.\n\n**Behavior:**\n\nThe operation MUST permanently remove the specified push notification configuration. No further notifications will be sent to the configured webhook after deletion. This operation MUST be idempotent - multiple deletions of the same config have the same effect.\n\n#### 3.1.11. Get Extended Agent Card\n\nRetrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.capabilities.extendedAgentCard` is `true`.\n\n**Inputs:**\n\n{{ proto_to_table(\"GetExtendedAgentCardRequest\") }}\n\n**Outputs:**\n\n- [`AgentCard`](#441-agentcard): A complete Agent Card object, which may contain additional details or skills not present in the public card\n\n**Errors:**\n\n- [`UnsupportedOperationError`](#332-error-handling): The agent does not support authenticated extended cards (see [Capability Validation](#334-capability-validation)).\n- [`ExtendedAgentCardNotConfiguredError`](#332-error-handling): The agent declares support but does not have an extended agent card configured.\n\n**Behavior:**\n\n- **Authentication**: The client MUST authenticate the request using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields.\n- **Extended Information**: The operation MAY return different details based on client authentication level, including additional skills, capabilities, or configuration not available in the public Agent Card.\n- **Card Replacement**: Clients retrieving this extended card SHOULD replace their cached public Agent Card with the content received from this endpoint for the duration of their authenticated session or until the card's version changes.\n- **Availability**: This operation is only available if the public Agent Card declares `capabilities.extendedAgentCard: true`.\n\nFor detailed security guidance on extended agent cards, see [Section 13.3 Extended Agent Card Access Control](#133-extended-agent-card-access-control).\n\n### 3.2. Operation Parameter Objects\n\nThis section defines common parameter objects used across multiple operations.\n\n#### 3.2.1. SendMessageRequest\n\n{{ proto_to_table(\"SendMessageRequest\") }}\n\n#### 3.2.2. SendMessageConfiguration\n\n{{ proto_to_table(\"SendMessageConfiguration\") }}\n\n**Execution Mode:**\n\nThe `return_immediately` field in [`SendMessageConfiguration`](#322-sendmessageconfiguration) controls whether the operation returns immediately or waits for task completion. Operations are blocking by default:\n\n- **Blocking (`return_immediately: false` or unset)**: The operation MUST wait until the task reaches a terminal state (`COMPLETED`, `FAILED`, `CANCELED`, `REJECTED`) or an interrupted state (`INPUT_REQUIRED`, `AUTH_REQUIRED`) before returning. The response MUST include the latest task state with all artifacts and status information. This is the default behavior.\n\n- **Non-Blocking (`return_immediately: true`)**: The operation MUST return immediately after creating the task, even if processing is still in progress. The returned task will have an in-progress state (e.g., `working`, `input_required`). It is the caller's responsibility to poll for updates using [Get Task](#313-get-task), subscribe via [Subscribe to Task](#316-subscribe-to-task), or receive updates via push notifications.\n\nThe `return_immediately` field has no effect:\n\n- when the operation returns a direct [`Message`](#414-message) response instead of a task.\n- for streaming operations, which always return updates in real-time.\n- on configured push notification configurations, which operates independently of execution mode.\n\n#### 3.2.3. Stream Response\n\n\n\n\n{{ proto_to_table(\"StreamResponse\") }}\n\nThis wrapper allows streaming endpoints to return different types of updates through a single response stream while maintaining type safety.\n\n#### 3.2.4. History Length Semantics\n\nThe `historyLength` parameter appears in multiple operations and controls how much task history is returned in responses. This parameter follows consistent semantics across all operations:\n\n- **Unset/undefined**: No limit imposed; server returns its default amount of history (implementation-defined, may be all history)\n- **0**: No history should be returned; the `history` field SHOULD be omitted\n- **> 0**: Return at most this many recent messages from the task's history\n\n#### 3.2.5. Metadata\n\nA flexible key-value map for passing additional context or parameters with operations. Metadata keys and are strings and values can be any valid value that can be represented in JSON. [`Extensions`](#46-extensions) can be used to strongly type metadata values for specific use cases.\n\n#### 3.2.6 Service Parameters\n\nA key-value map for passing horizontally applicable context or parameters with case-insensitive string keys and case-sensitive string values. The transmission mechanism for these service parameter key-value pairs is defined by the specific protocol binding (e.g., HTTP headers for HTTP-based bindings, gRPC metadata for gRPC bindings). Custom protocol bindings **MUST** specify how service parameters are transmitted in their binding specification.\n\n**Standard A2A Service Parameters:**\n\n| Name | Description | Example Value |\n| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |\n| `A2A-Extensions` | Comma-separated list of extension URIs that the client wants to use for the request | `https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1` |\n| `A2A-Version` | The A2A protocol version that the client is using. If the version is not supported, the agent returns [`VersionNotSupportedError`](#332-error-handling) | `0.3` |\n\nAs service parameter names MAY need to co-exist with other parameters defined by the underlying transport protocol or infrastructure, all service parameters defined by this specification will be prefixed with `a2a-`.\n\n### 3.3. Operation Semantics\n\n#### 3.3.1. Idempotency\n\n- **Get operations** (Get Task, List Tasks, Get Extended Agent Card) are naturally idempotent\n- **Send Message** operations MAY be idempotent. Agents may utilize the messageId to detect duplicate messages.\n- **Cancel Task** operations are idempotent - multiple cancellation requests have the same effect. A duplicate cancellation request MAY return `TaskNotFoundError` if the task has already been canceled and purged.\n\n#### 3.3.2. Error Handling\n\nAll operations may return errors in the following categories. Servers **MUST** return appropriate errors and **SHOULD** provide actionable information to help clients resolve issues.\n\n**Error Categories and Server Requirements:**\n\n- **Authentication Errors**: Invalid or missing credentials\n - Servers **MUST** reject requests with invalid or missing authentication credentials\n - Servers **SHOULD** include authentication challenge information in the error response\n - Servers **SHOULD** specify which authentication scheme is required\n - Example error codes: HTTP `401 Unauthorized`, gRPC `UNAUTHENTICATED`, JSON-RPC custom error\n - Example scenarios: Missing bearer token, expired API key, invalid OAuth token\n\n- **Authorization Errors**: Insufficient permissions for requested operation\n - Servers **MUST** return an authorization error when the authenticated client lacks required permissions\n - Servers **SHOULD** indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access)\n - Servers **MUST NOT** reveal the existence of resources the client is not authorized to access\n - Example error codes: HTTP `403 Forbidden`, gRPC `PERMISSION_DENIED`, JSON-RPC custom error\n - Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes\n\n- **Validation Errors**: Invalid input parameters or message format\n - Servers **MUST** validate all input parameters before processing\n - Servers **SHOULD** specify which parameter(s) failed validation and why\n - Servers **SHOULD** provide guidance on valid parameter values or formats\n - Example error codes: HTTP `400 Bad Request`, gRPC `INVALID_ARGUMENT`, JSON-RPC `-32602 Invalid params`\n - Example scenarios: Invalid task ID format, missing required message parts, unsupported content type\n\n- **Resource Errors**: Requested task not found or not accessible\n - Servers **MUST** return a not found error when a requested resource does not exist or is not accessible to the authenticated client\n - Servers **SHOULD NOT** distinguish between \"does not exist\" and \"not authorized\" to prevent information leakage\n - Example error codes: HTTP `404 Not Found`, gRPC `NOT_FOUND`, JSON-RPC custom error (see A2A-specific errors)\n - Example scenarios: Task ID does not exist, task has been deleted, configuration not found\n\n- **System Errors**: Internal agent failures or temporary unavailability\n - Servers **SHOULD** return appropriate error codes for temporary failures vs. permanent errors\n - Servers **MAY** include retry guidance (e.g., Retry-After header in HTTP)\n - Servers **SHOULD** log system errors for diagnostic purposes\n - Example error codes: HTTP `500 Internal Server Error` or `503 Service Unavailable`, gRPC `INTERNAL` or `UNAVAILABLE`, JSON-RPC `-32603 Internal error`\n - Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded\n\n**Error Payload Structure:**\n\nAll error responses in the A2A protocol, regardless of binding, **MUST** convey the following information:\n\n1. **Error Code**: A machine-readable identifier for the error type (e.g., string code, numeric code, or protocol-specific status)\n2. **Error Message**: A human-readable description of the error\n3. **Error Details** (optional): Additional structured information about the error, such as:\n - Affected fields or parameters\n - Contextual information (e.g., task ID, timestamp)\n - Suggestions for resolution\n\nProtocol bindings **MUST** map these elements to their native error representations while preserving semantic meaning. See binding-specific sections for concrete error format examples: [JSON-RPC Error Handling](#95-error-handling), [gRPC Error Handling](#106-error-handling), and [HTTP/REST Error Handling](#116-error-handling).\n\n**A2A-Specific Errors:**\n\n| Error Name | Description |\n| :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `TaskNotFoundError` | The specified task ID does not correspond to an existing or accessible task. It might be invalid, expired, or already completed and purged. |\n| `TaskNotCancelableError` | An attempt was made to cancel a task that is not in a cancelable state (e.g., it has already reached a terminal state like `completed`, `failed`, or `canceled`). |\n| `PushNotificationNotSupportedError` | Client attempted to use push notification features but the server agent does not support them (i.e., `AgentCard.capabilities.pushNotifications` is `false`). |\n| `UnsupportedOperationError` | The requested operation or a specific aspect of it is not supported by this server agent implementation. |\n| `ContentTypeNotSupportedError` | A Media Type provided in the request's message parts or implied for an artifact is not supported by the agent or the specific skill being invoked. |\n| `InvalidAgentResponseError` | An agent returned a response that does not conform to the specification for the current method. |\n| `ExtendedAgentCardNotConfiguredError` | The agent does not have an extended agent card configured when one is required for the requested operation. |\n| `ExtensionSupportRequiredError` | Server requested use of an extension marked as `required: true` in the Agent Card but the client did not declare support for it in the request. |\n| `VersionNotSupportedError` | The A2A protocol version specified in the request (via `A2A-Version` service parameter) is not supported by the agent. |\n\n#### 3.3.3. Asynchronous Processing\n\nA2A operations are designed for asynchronous task execution. Operations return immediately with either [`Task`](#411-task) objects or [`Message`](#414-message) objects, and when a Task is returned, processing continues in the background. Clients retrieve task updates through polling, streaming, or push notifications (see [Section 3.5](#35-task-update-delivery-mechanisms)). Agents MAY accept additional messages for tasks in non-terminal states to enable multi-turn interactions (see [Section 3.4](#34-multi-turn-interactions)).\n\n#### 3.3.4. Capability Validation\n\nAgents declare optional capabilities in their [`AgentCard`](#441-agentcard). When clients attempt to use operations or features that require capabilities not declared as supported in the Agent Card, the agent **MUST** return an appropriate error response:\n\n- **Push Notifications**: If `AgentCard.capabilities.pushNotifications` is `false` or not present, operations related to push notification configuration (Create, Get, List, Delete) **MUST** return [`PushNotificationNotSupportedError`](#332-error-handling).\n- **Streaming**: If `AgentCard.capabilities.streaming` is `false` or not present, attempts to use `SendStreamingMessage` or `SubscribeToTask` operations **MUST** return [`UnsupportedOperationError`](#332-error-handling).\n- **Extended Agent Card**: If `AgentCard.capabilities.extendedAgentCard` is `false` or not present, attempts to call the Get Extended Agent Card operation **MUST** return [`UnsupportedOperationError`](#332-error-handling). If the agent declares support but has not configured an extended card, it **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling).\n- **Extensions**: When a server requests use of an extension marked as `required: true` in the Agent Card but the client does not declare support for it, the agent **MUST** return [`ExtensionSupportRequiredError`](#332-error-handling).\n\nClients **SHOULD** validate capability support by examining the Agent Card before attempting operations that require optional capabilities.\n\n### 3.4. Multi-Turn Interactions\n\nThe A2A protocol supports multi-turn conversations through context identifiers and task references, enabling agents to maintain conversational continuity across multiple interactions.\n\n#### 3.4.1. Context Identifier Semantics\n\nA `contextId` is an identifier that logically groups multiple related [`Task`](#411-task) and [`Message`](#414-message) objects, providing continuity across a series of interactions.\n\n**Generation and Assignment:**\n\n- Agents **MAY** generate a new `contextId` when processing a [`Message`](#414-message) that does not include a `contextId` field\n- If an agent generates a new `contextId`, it **MUST** be included in the response (either [`Task`](#411-task) or [`Message`](#414-message))\n- Agents **MAY** accept and preserve client-provided `contextId` values\n- If an agent cannot accept a client-provided `contextId`, it **MUST** reject the request with an error and **MUST NOT** generate a new `contextId` for the response\n- Clients **SHOULD NOT** provide a client-generated `contextId` to a server unless they understand how the server will process that `contextId`\n- Server-generated `contextId` values **SHOULD** be treated as opaque identifiers by clients\n\n**Grouping and Scope:**\n\n- A `contextId` logically groups multiple [`Task`](#411-task) objects and [`Message`](#414-message) objects that are part of the same conversational context\n- All tasks and messages with the same `contextId` **SHOULD** be treated as part of the same conversational session\n- Agents **MAY** use the `contextId` to maintain internal state, conversational history, or LLM context across multiple interactions\n- Agents **MAY** implement context expiration or cleanup policies and **SHOULD** document any such policies\n\n#### 3.4.2. Task Identifier Semantics\n\nA `taskId` is a unique identifier for a [`Task`](#411-task) object, representing a stateful unit of work with a defined lifecycle.\n\n**Generation and Assignment:**\n\n- Task IDs are **server-generated** when a new task is created in response to a [`Message`](#414-message)\n- Agents **MUST** generate a unique `taskId` for each new task they create\n- The generated `taskId` **MUST** be included in the [`Task`](#411-task) object returned to the client\n- When a client includes a `taskId` in a [`Message`](#414-message), it **MUST** reference an existing task\n- Agents **MUST** return a [`TaskNotFoundError`](#332-error-handling) if the provided `taskId` does not correspond to an existing task\n- Client-provided `taskId` values for creating new tasks is **NOT** supported\n\n#### 3.4.3. Multi-Turn Conversation Patterns\n\nThe A2A protocol supports several patterns for multi-turn interactions:\n\n**Context Continuity:**\n\n- [`Task`](#411-task) objects maintain conversation context through the `contextId` field\n- Clients **MAY** include the `contextId` in subsequent messages to indicate continuation of a previous interaction\n- Clients **MAY** use `taskId` (with or without `contextId`) to continue or refine a specific task\n- Clients **MAY** use `contextId` without `taskId` to start a new task within an existing conversation context\n- Agents **MUST** infer `contextId` from the task if only `taskId` is provided\n- Agents **MUST** reject messages containing mismatching `contextId` and `taskId` (i.e., the provided `contextId` is different from that of the referenced [`Task`](#411-task)).\n\n**Input Required State:**\n\n- Agents can request additional input mid-processing by transitioning a task to the `input-required` state\n- The client continues the interaction by sending a new message with the same `taskId` and `contextId`\n\n**Follow-up Messages:**\n\n- Clients can send additional messages with `taskId` references to continue or refine existing tasks\n- Clients **SHOULD** use the `referenceTaskIds` field in [`Message`](#414-message) to explicitly reference related tasks\n- Agents **SHOULD** use referenced tasks to understand the context and intent of follow-up requests\n\n**Context Inheritance:**\n\n- New tasks created within the same `contextId` can inherit context from previous interactions\n- Agents **SHOULD** leverage the shared `contextId` to provide contextually relevant responses\n\n### 3.5. Task Update Delivery Mechanisms\n\nThe A2A protocol provides three complementary mechanisms for clients to receive updates about task progress and completion.\n\n#### 3.5.1. Overview of Update Mechanisms\n\n**Polling (Get Task):**\n\n- Client periodically calls Get Task ([Section 3.1.3](#313-get-task)) to check task status\n- Simple to implement, works with all protocol bindings\n- Higher latency, potential for unnecessary requests\n- Best for: Simple integrations, infrequent updates, clients behind restrictive firewalls\n\n**Streaming:**\n\n- Real-time delivery of events as they occur\n- Operations: Stream Message ([Section 3.1.2](#312-send-streaming-message)) and Subscribe to Task ([Section 3.1.6](#316-subscribe-to-task))\n- Low latency, efficient for frequent updates\n- Requires persistent connection support\n- Best for: Interactive applications, real-time dashboards, live progress monitoring\n- Requires `AgentCard.capabilities.streaming` to be `true`\n\n**Push Notifications (WebHooks):**\n\n- Agent sends HTTP POST requests to client-registered endpoints when task state changes\n- Client does not maintain persistent connection\n- Asynchronous delivery, client must be reachable via HTTP\n- Best for: Server-to-server integrations, long-running tasks, event-driven architectures\n- Operations: Create ([Section 3.1.7](#317-create-push-notification-config)), Get ([Section 3.1.8](#76-taskspushnotificationconfigget)), List ([Section 3.1.9](#319-list-push-notification-configs)), Delete ([Section 3.1.10](#3110-delete-push-notification-config))\n- Event types: TaskStatusUpdateEvent ([Section 4.2.1](#421-taskstatusupdateevent)), TaskArtifactUpdateEvent ([Section 4.2.2](#422-taskartifactupdateevent)), WebHook payloads ([Section 4.3](#43-push-notification-objects))\n- Requires `AgentCard.capabilities.pushNotifications` to be `true`\n- Regardless of the protocol binding being used by the agent, WebHook calls use plain HTTP and the JSON payloads as defined in the HTTP protocol binding\n\n#### 3.5.2. Streaming Event Delivery\n\n**Event Ordering:**\n\nAll implementations MUST deliver events in the order they were generated. Events MUST NOT be reordered during transmission, regardless of protocol binding.\n\n**Multiple Streams Per Task:**\n\nAn agent MAY serve multiple concurrent streams to one or more clients for the same task. This allows multiple clients (or the same client with multiple connections) to independently subscribe to and receive updates about a task's progress.\n\nWhen multiple streams are active for a task:\n\n- Events MUST be broadcast to all active streams for that task\n- Each stream MUST receive the same events in the same order\n- Closing one stream MUST NOT affect other active streams for the same task\n- The task lifecycle is independent of any individual stream's lifecycle\n\nThis capability enables scenarios such as:\n\n- Multiple team members monitoring the same long-running task\n- A client reconnecting to a task after a network interruption by opening a new stream\n- Different applications or dashboards displaying real-time updates for the same task\n\n#### 3.5.3. Push Notification Delivery\n\nPush notifications are delivered via HTTP POST to client-registered webhook endpoints. The delivery semantics and reliability guarantees are defined in [Section 4.3](#43-push-notification-objects).\n\n### 3.6 Versioning\n\nThe specific version of the A2A protocol in use is identified using the `Major.Minor` elements (e.g. `1.0`) of the corresponding A2A specification version. Patch version numbers used by the specification, do not affect protocol compatibility. Patch version numbers SHOULD NOT be used in requests, responses and Agent Cards, and MUST not be considered when clients and servers negotiate protocol versions.\n\n#### 3.6.1 Client Responsibilities\n\nClients MUST send the `A2A-Version` header with each request to maintain compatibility after an agent upgrades to a new version of the protocol (except for 0.3 Clients - 0.3 will be assumed for empty header). Sending the `A2A-Version` header also provides visibility to agents about version usage in the ecosystem, which can help inform the risks of inplace version upgrades.\n\n**Example of HTTP GET Request with Version Header:**\n\n```http\nGET /tasks/task-123 HTTP/1.1\nHost: agent.example.com\nA2A-Version: 1.0\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\nAccept: application/json\n```\n\nClients MAY provide the `A2A-Version` as a request parameter instead of a header.\n\n**Example of HTTP GET Request with Version request parameter:**\n\n```http\nGET /tasks/task-123?A2A-Version=1.0 HTTP/1.1\nHost: agent.example.com\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\nAccept: application/json\n```\n\n#### 3.6.2 Server Responsibilities\n\nAgents MUST process requests using the semantics of the requested `A2A-Version` (matching `Major.Minor`). If the version is not supported by the interface, agents MUST return a [`VersionNotSupportedError`](#332-error-handling).\n\nAgents MUST interpret empty value as 0.3 version.\n\nAgents CAN expose multiple interfaces for the same transport with different versions under the same or different URLs.\n\n#### 3.6.3 Tooling support\n\nTooling libraries and SDKs that implement the A2A protocol MUST provide mechanisms to help clients manage protocol versioning, such as negotiation of the transport and protocol version used. Client Agents that require the latest features of the protocol should be configured to request specific versions and avoid automatic fallback to older versions, to prevent silently losing functionality.\n\n### 3.7 Messages and Artifacts\n\nMessages and Artifacts serve distinct purposes within the A2A protocol. The core interaction model defined by A2A is for clients to send messages to initiate a task that produces one or more artifacts.\n\nMessages play several key roles:\n\n- **Task Initiation**: Clients send Messages to agents to initiate new tasks.\n- **Clarification Messages**: Agents may send Messages back to the client to request clarification prior to initiating a task.\n- **Status Messages**: Agents attach Messages to status update events to inform clients about task progress, request additional input, or provide informational updates.\n- **Task Interaction**: Clients send Messages to provide additional input or instructions for ongoing tasks.\n\nMessages SHOULD NOT be used to deliver task outputs. Results SHOULD BE returned using Artifacts associated with a Task. This separation allows for a clear distinction between communication (Messages) and data output (Artifacts).\n\nThe Task History field contains Messages exchanged during task execution. However, not all Messages are guaranteed to be persisted in the Task history; for example, transient informational messages may not be stored. Messages exchanged prior to task creation may not be stored in Task history. The agent is responsible to determine which Messages are persisted in the Task History.\n\nClients using streaming to retrieve task updates MAY not receive all status update messages if the client is disconnected and then reconnects. Messages MUST NOT be considered a reliable delivery mechanism for critical information.\n\nAgents MAY choose to persist all Messages that contain important information in the Task history to ensure clients can retrieve it later. However, clients MUST NOT rely on this behavior unless negotiated out-of-band.\n\n## 4. Protocol Data Model\n\nThe A2A protocol defines a canonical data model using Protocol Buffers. All protocol bindings **MUST** provide functionally equivalent representations of these data structures.\n\n### 4.1. Core Objects\n\n\n\n#### 4.1.1. Task\n\n{{ proto_to_table(\"Task\") }}\n\n\n\n#### 4.1.2. TaskStatus\n\n{{ proto_to_table(\"TaskStatus\") }}\n\n\n\n#### 4.1.3. TaskState\n\n{{ proto_enum_to_table(\"TaskState\") }}\n\n\n\n#### 4.1.4. Message\n\n{{ proto_to_table(\"Message\") }}\n\n\n\n#### 4.1.5. Role\n\n{{ proto_enum_to_table(\"Role\") }}\n\n\n\n#### 4.1.6. Part\n\n{{ proto_to_table(\"Part\") }}\n\n\n\n#### 4.1.7. Artifact\n\n{{ proto_to_table(\"Artifact\") }}\n\n### 4.2. Streaming Events\n\n\n\n#### 4.2.1. TaskStatusUpdateEvent\n\n{{ proto_to_table(\"TaskStatusUpdateEvent\") }}\n\n\n\n#### 4.2.2. TaskArtifactUpdateEvent\n\n{{ proto_to_table(\"TaskArtifactUpdateEvent\") }}\n\n### 4.3. Push Notification Objects\n\n\n\n#### 4.3.1. PushNotificationConfig\n\n{{ proto_to_table(\"PushNotificationConfig\") }}\n\n\n\n#### 4.3.2. AuthenticationInfo\n\n{{ proto_to_table(\"AuthenticationInfo\") }}\n\n#### 4.3.3. Push Notification Payload\n\nWhen a task update occurs, the agent sends an HTTP POST request to the configured webhook URL. The payload uses the same [`StreamResponse`](#323-stream-response) format as streaming operations, allowing push notifications to deliver the same event types as real-time streams.\n\n**Request Format:**\n\n```http\nPOST {webhook_url}\nAuthorization: {authentication_scheme} {credentials}\nContent-Type: application/json\n\n{\n /* StreamResponse object - one of: */\n \"task\": { /* Task object */ },\n \"message\": { /* Message object */ },\n \"statusUpdate\": { /* TaskStatusUpdateEvent object */ },\n \"artifactUpdate\": { /* TaskArtifactUpdateEvent object */ }\n}\n```\n\n**Payload Structure:**\n\nThe webhook payload is a [`StreamResponse`](#323-stream-response) object containing exactly one of the following:\n\n- **task**: A [`Task`](#411-task) object with the current task state\n- **message**: A [`Message`](#414-message) object containing a message response\n- **statusUpdate**: A [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) indicating a status change\n- **artifactUpdate**: A [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) indicating artifact updates\n\n**Authentication:**\n\nThe agent MUST include authentication credentials in the request headers as specified in the [`PushNotificationConfig.authentication`](#432-authenticationinfo) field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.).\n\n**Client Responsibilities:**\n\n- Clients MUST respond with HTTP 2xx status codes to acknowledge successful receipt\n- Clients SHOULD process notifications idempotently, as duplicate deliveries may occur\n- Clients MUST validate the task ID matches an expected task\n- Clients SHOULD implement appropriate security measures to verify the notification source\n\n**Server Guarantees:**\n\n- Agents MUST attempt delivery at least once for each configured webhook\n- Agents MAY implement retry logic with exponential backoff for failed deliveries\n- Agents SHOULD include a reasonable timeout for webhook requests (recommended: 10-30 seconds)\n- Agents MAY stop attempting delivery after a configured number of consecutive failures\n\nFor detailed security guidance on push notifications, see [Section 13.2 Push Notification Security](#132-push-notification-security).\n\n### 4.4. Agent Discovery Objects\n\n\n\n#### 4.4.1. AgentCard\n\n{{ proto_to_table(\"AgentCard\") }}\n\n\n\n#### 4.4.2. AgentProvider\n\n{{ proto_to_table(\"AgentProvider\") }}\n\n\n\n#### 4.4.3. AgentCapabilities\n\n{{ proto_to_table(\"AgentCapabilities\") }}\n\n\n\n#### 4.4.4. AgentExtension\n\n{{ proto_to_table(\"AgentExtension\") }}\n\n\n\n#### 4.4.5. AgentSkill\n\n{{ proto_to_table(\"AgentSkill\") }}\n\n\n\n#### 4.4.6. AgentInterface\n\n{{ proto_to_table(\"AgentInterface\") }}\n\n\n\n#### 4.4.7. AgentCardSignature\n\n{{ proto_to_table(\"AgentCardSignature\") }}\n\n### 4.5. Security Objects\n\n\n\n\n#### 4.5.1. SecurityScheme\n\n{{ proto_to_table(\"SecurityScheme\") }}\n\n\n\n#### 4.5.2. APIKeySecurityScheme\n\n{{ proto_to_table(\"APIKeySecurityScheme\") }}\n\n\n\n#### 4.5.3. HTTPAuthSecurityScheme\n\n{{ proto_to_table(\"HTTPAuthSecurityScheme\") }}\n\n\n\n#### 4.5.4. OAuth2SecurityScheme\n\n{{ proto_to_table(\"OAuth2SecurityScheme\") }}\n\n\n\n#### 4.5.5. OpenIdConnectSecurityScheme\n\n{{ proto_to_table(\"OpenIdConnectSecurityScheme\") }}\n\n\n\n#### 4.5.6. MutualTlsSecurityScheme\n\n{{ proto_to_table(\"MutualTlsSecurityScheme\") }}\n\n\n\n#### 4.5.7. OAuthFlows\n\n{{ proto_to_table(\"OAuthFlows\") }}\n\n\n\n#### 4.5.8. AuthorizationCodeOAuthFlow\n\n{{ proto_to_table(\"AuthorizationCodeOAuthFlow\") }}\n\n\n\n#### 4.5.9. ClientCredentialsOAuthFlow\n\n{{ proto_to_table(\"ClientCredentialsOAuthFlow\") }}\n\n\n\n#### 4.5.10. DeviceCodeOAuthFlow\n\n{{ proto_to_table(\"DeviceCodeOAuthFlow\") }}\n\n### 4.6. Extensions\n\nThe A2A protocol supports extensions to provide additional functionality or data beyond the core specification while maintaining backward compatibility and interoperability. Extensions allow agents to declare additional capabilities such as protocol enhancements or vendor-specific features, maintain compatibility with clients that don't support specific extensions, enable innovation through experimental or domain-specific features without modifying the core protocol, and facilitate standardization by providing a pathway for community-developed features to become part of the core specification.\n\n#### 4.6.1. Extension Declaration\n\nAgents declare their supported extensions in the [`AgentCard`](#441-agentcard) using the `extensions` field, which contains an array of [`AgentExtension`](#444-agentextension) objects.\n\n*Example: Agent declaring extension support in AgentCard:*\n\n```json\n{\n \"name\": \"Research Assistant Agent\",\n \"description\": \"AI agent for academic research and fact-checking\",\n \"supportedInterfaces\": [\n {\n \"url\": \"https://research-agent.example.com/a2a/v1\",\n \"protocolBinding\": \"HTTP+JSON\",\n \"protocolVersion\": \"0.3\",\n }\n ],\n \"capabilities\": {\n \"streaming\": false,\n \"pushNotifications\": false,\n \"extensions\": [\n {\n \"uri\": \"https://standards.org/extensions/citations/v1\",\n \"description\": \"Provides citation formatting and source verification\",\n \"required\": false\n },\n {\n \"uri\": \"https://example.com/extensions/geolocation/v1\",\n \"description\": \"Location-based search capabilities\",\n \"required\": false\n }\n ]\n },\n \"defaultInputModes\": [\"text/plain\"],\n \"defaultOutputModes\": [\"text/plain\"],\n \"skills\": [\n {\n \"id\": \"academic-research\",\n \"name\": \"Academic Research Assistant\",\n \"description\": \"Provides research assistance with citations and source verification\",\n \"tags\": [\"research\", \"citations\", \"academic\"],\n \"examples\": [\"Find peer-reviewed articles on climate change\"],\n \"inputModes\": [\"text/plain\"],\n \"outputModes\": [\"text/plain\"]\n }\n ]\n}\n```\n\nClients indicate their desire to opt into the use of specific extensions through binding-specific mechanisms such as HTTP headers, gRPC metadata, or JSON-RPC request parameters that identify the extension identifiers they wish to utilize during the interaction.\n\n*Example: HTTP client opting into extensions using headers:*\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/json\nAuthorization: Bearer token\nA2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Find restaurants near me\"}],\n \"extensions\": [\"https://example.com/extensions/geolocation/v1\"],\n \"metadata\": {\n \"https://example.com/extensions/geolocation/v1\": {\n \"latitude\": 37.7749,\n \"longitude\": -122.4194\n }\n }\n }\n}\n```\n\n#### 4.6.2. Extensions Points\n\nExtensions can be integrated into the A2A protocol at several well-defined extension points:\n\n**Message Extensions:**\n\nMessages can be extended to allow clients to provide additional strongly typed context or parameters relevant to the message being sent, or TaskStatus Messages to include extra information about the task's progress.\n\n*Example: A location extension using the extensions and metadata arrays:*\n\n```json\n{\n \"role\": \"ROLE_USER\",\n \"parts\": [\n {\"text\": \"Find restaurants near me\"}\n ],\n \"extensions\": [\"https://example.com/extensions/geolocation/v1\"],\n \"metadata\": {\n \"https://example.com/extensions/geolocation/v1\": {\n \"latitude\": 37.7749,\n \"longitude\": -122.4194,\n \"accuracy\": 10.0,\n \"timestamp\": \"2025-10-21T14:30:00Z\"\n }\n }\n}\n```\n\n**Artifact Extensions:**\n\nArtifacts can include extension data to provide strongly typed context or metadata about the generated content.\n\n*Example: An artifact with citation extension for research sources:*\n\n```json\n{\n \"artifactId\": \"research-summary-001\",\n \"name\": \"Climate Change Summary\",\n \"parts\": [\n {\n \"text\": \"Global temperatures have risen by 1.1°C since pre-industrial times, with significant impacts on weather patterns and sea levels.\"\n }\n ],\n \"extensions\": [\"https://standards.org/extensions/citations/v1\"],\n \"metadata\": {\n \"https://standards.org/extensions/citations/v1\": {\n \"sources\": [\n {\n \"title\": \"Global Temperature Anomalies - 2023 Report\",\n \"authors\": [\"Smith, J.\", \"Johnson, M.\"],\n \"url\": \"https://climate.gov/reports/2023-temperature\",\n \"accessDate\": \"2025-10-21\",\n \"relevantText\": \"Global temperatures have risen by 1.1°C\"\n }\n ]\n }\n }\n}\n```\n\n#### 4.6.3. Extension Versioning and Compatibility\n\nExtensions **SHOULD** include version information in their URI identifier. This allows clients and agents to negotiate compatible versions of extensions during interactions. A new URI **MUST** be created for breaking changes to an extension.\n\nIf a client requests a versions of an extension that the agent does not support, the agent **SHOULD** ignore the extension for that interaction and proceed without it, unless the extension is marked as `required` in the AgentCard, in which case the agent **MUST** return an error indicating unsupported extension. It **MUST NOT** fall back to a previous version of the extension automatically.\n\n## 5. Protocol Binding Requirements and Interoperability\n\n### 5.1. Functional Equivalence Requirements\n\nWhen an agent supports multiple protocols, all supported protocols **MUST**:\n\n- **Identical Functionality**: Provide the same set of operations and capabilities\n- **Consistent Behavior**: Return semantically equivalent results for the same requests\n- **Same Error Handling**: Map errors consistently using appropriate protocol-specific codes\n- **Equivalent Authentication**: Support the same authentication schemes declared in the AgentCard\n\n### 5.2. Protocol Selection and Negotiation\n\n- **Agent Declaration**: Agents **MUST** declare all supported protocols in their AgentCard\n- **Client Choice**: Clients **MAY** choose any protocol declared by the agent\n- **Fallback Behavior**: Clients **SHOULD** implement fallback logic for alternative protocols\n\n### 5.3. Method Mapping Reference\n\n| Functionality | JSON-RPC Method | gRPC Method | REST Endpoint |\n| :------------------------------ | :--------------------------------- | :--------------------------------- | :------------------------------------------------------ |\n| Send message | `SendMessage` | `SendMessage` | `POST /message:send` |\n| Stream message | `SendStreamingMessage` | `SendStreamingMessage` | `POST /message:stream` |\n| Get task | `GetTask` | `GetTask` | `GET /tasks/{id}` |\n| List tasks | `ListTasks` | `ListTasks` | `GET /tasks` |\n| Cancel task | `CancelTask` | `CancelTask` | `POST /tasks/{id}:cancel` |\n| Subscribe to task | `SubscribeToTask` | `SubscribeToTask` | `POST /tasks/{id}:subscribe` |\n| Create push notification config | `CreateTaskPushNotificationConfig` | `CreateTaskPushNotificationConfig` | `POST /tasks/{id}/pushNotificationConfigs` |\n| Get push notification config | `GetTaskPushNotificationConfig` | `GetTaskPushNotificationConfig` | `GET /tasks/{id}/pushNotificationConfigs/{configId}` |\n| List push notification configs | `ListTaskPushNotificationConfigs` | `ListTaskPushNotificationConfigs` | `GET /tasks/{id}/pushNotificationConfigs` |\n| Delete push notification config | `DeleteTaskPushNotificationConfig` | `DeleteTaskPushNotificationConfig` | `DELETE /tasks/{id}/pushNotificationConfigs/{configId}` |\n| Get extended Agent Card | `GetExtendedAgentCard` | `GetExtendedAgentCard` | `GET /extendedAgentCard` |\n\n### 5.4. Error Code Mappings\n\nAll A2A-specific errors defined in [Section 3.3.2](#332-error-handling) **MUST** be mapped to binding-specific error representations. The following table provides the canonical mappings for each standard protocol binding:\n\n| A2A Error Type | JSON-RPC Code | gRPC Status | HTTP Status |\n| :------------------------------------ | :------------ | :-------------------- | :--------------------------- |\n| `TaskNotFoundError` | `-32001` | `NOT_FOUND` | `404 Not Found` |\n| `TaskNotCancelableError` | `-32002` | `FAILED_PRECONDITION` | `409 Conflict` |\n| `PushNotificationNotSupportedError` | `-32003` | `UNIMPLEMENTED` | `400 Bad Request` |\n| `UnsupportedOperationError` | `-32004` | `UNIMPLEMENTED` | `400 Bad Request` |\n| `ContentTypeNotSupportedError` | `-32005` | `INVALID_ARGUMENT` | `415 Unsupported Media Type` |\n| `InvalidAgentResponseError` | `-32006` | `INTERNAL` | `502 Bad Gateway` |\n| `ExtendedAgentCardNotConfiguredError` | `-32007` | `FAILED_PRECONDITION` | `400 Bad Request` |\n| `ExtensionSupportRequiredError` | `-32008` | `FAILED_PRECONDITION` | `400 Bad Request` |\n| `VersionNotSupportedError` | `-32009` | `UNIMPLEMENTED` | `400 Bad Request` |\n\n**Custom Binding Requirements:**\n\nCustom protocol bindings **MUST** define equivalent error code mappings that preserve the semantic meaning of each A2A error type. The binding specification **SHOULD** provide a similar mapping table showing how each A2A error type is represented in the custom binding's native error format.\n\nFor binding-specific error structures and examples, see:\n\n- [JSON-RPC Error Handling](#95-error-handling)\n- [gRPC Error Handling](#106-error-handling)\n- [HTTP/REST Error Handling](#116-error-handling)\n\n### 5.5. JSON Field Naming Convention\n\nAll JSON serializations of the A2A protocol data model **MUST** use **camelCase** naming for field names, not the snake_case convention used in Protocol Buffer definitions.\n\n**Naming Convention:**\n\n- Protocol Buffer field: `protocol_version` → JSON field: `protocolVersion`\n- Protocol Buffer field: `context_id` → JSON field: `contextId`\n- Protocol Buffer field: `default_input_modes` → JSON field: `defaultInputModes`\n- Protocol Buffer field: `push_notification_config` → JSON field: `pushNotificationConfig`\n\n**Enum Values:**\n\n- Enum values **MUST** be represented according to the [ProtoJSON specification](https://protobuf.dev/programming-guides/json/), which serializes enums as their string names **as defined in the Protocol Buffer definition** (typically SCREAMING_SNAKE_CASE).\n\n**Examples:**\n\n- Protocol Buffer enum: `TASK_STATE_INPUT_REQUIRED` → JSON value: `\"TASK_STATE_INPUT_REQUIRED\"`\n- Protocol Buffer enum: `ROLE_USER` → JSON value: `\"ROLE_USER\"`\n\n**Note:** This follows the ProtoJSON specification as adopted in [ADR-001](../adrs/adr-001-protojson-serialization.md).\n\n### 5.6. Data Type Conventions\n\nThis section documents conventions for common data types used throughout the A2A protocol, particularly as they apply to protocol bindings.\n\n#### 5.6.1. Timestamps\n\nThe A2A protocol uses [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) for all timestamp fields in the Protocol Buffer definitions. When serialized to JSON (in JSON-RPC, HTTP/REST, or other JSON-based bindings), these timestamps **MUST** be represented as ISO 8601 formatted strings in UTC timezone.\n\n**Format Requirements:**\n\n- **Format:** ISO 8601 combined date and time representation\n- **Timezone:** UTC (denoted by 'Z' suffix)\n- **Precision:** Millisecond precision **SHOULD** be used where available\n- **Pattern:** `YYYY-MM-DDTHH:mm:ss.sssZ`\n\n**Examples:**\n\n```json\n{\n \"timestamp\": \"2025-10-28T10:30:00.000Z\",\n \"createdAt\": \"2025-10-28T14:25:33.142Z\",\n \"lastModified\": \"2025-10-31T17:45:22.891Z\"\n}\n```\n\n**Implementation Notes:**\n\n- Protocol Buffer's `google.protobuf.Timestamp` represents time as seconds since Unix epoch (January 1, 1970, 00:00:00 UTC) plus nanoseconds\n- JSON serialization automatically converts this to ISO 8601 format when using standard Protocol Buffer JSON encoding\n- Clients and servers **MUST** parse and generate ISO 8601 timestamps correctly\n- When millisecond precision is not available, the fractional seconds portion **MAY** be omitted or zero-filled\n- Timestamps **MUST NOT** include timezone offsets other than 'Z' (all times are UTC)\n\n### 5.7. Field Presence and Optionality\n\nThe Protocol Buffer definition in `specification/a2a.proto` uses [`google.api.field_behavior`](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) annotations to indicate whether fields are `REQUIRED`. These annotations serve as both documentation and validation hints for implementations.\n\n**Required Fields:**\n\nFields marked with `[(google.api.field_behavior) = REQUIRED]` indicate that the field **MUST** be present and set in valid messages. Implementations **SHOULD** validate these requirements and reject messages with missing required fields. Arrays marked as required **MUST** contain at least one element.\n\n**Optional Field Presence:**\n\nThe Protocol Buffer `optional` keyword is used to distinguish between a field being explicitly set versus omitted. This distinction is critical for two scenarios:\n\n1. **Explicit Default Values:** Some fields in the specification define default values that differ from Protocol Buffer's implicit defaults. Implementations should apply the default value when the field is not explicitly provided.\n\n2. **Agent Card Canonicalization:** When creating cryptographic signatures of Agent Cards, it is required to produce a canonical JSON representation. The `optional` keyword enables implementations to distinguish between fields that were explicitly set (and should be included in the canonical form) versus fields that were omitted (and should be excluded from canonicalization). This ensures Agent Cards can be reconstructed to accurately match their signature.\n\n**Unrecognized Fields:**\n\nImplementations **SHOULD** ignore unrecognized fields in messages, allowing for forward compatibility as the protocol evolves.\n\n## 6. Common Workflows & Examples\n\nThis section provides illustrative examples of common A2A interactions across different bindings.\n\n### 6.1. Basic Task Execution\n\n**Scenario:** Client asks a question and receives a completed task response.\n\n**Request:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"What is the weather today?\"}],\n \"messageId\": \"msg-uuid\"\n }\n}\n```\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"task\": {\n \"id\": \"task-uuid\",\n \"contextId\": \"context-uuid\",\n \"status\": {\"state\": \"TASK_STATE_COMPLETED\"},\n \"artifacts\": [{\n \"artifactId\": \"artifact-uuid\",\n \"name\": \"Weather Report\",\n \"parts\": [{\"text\": \"Today will be sunny with a high of 75°F\"}]\n }]\n }\n}\n```\n\n### 6.2. Streaming Task Execution\n\n**Scenario:** Client requests a long-running task with real-time updates.\n\n**Request:**\n\n```http\nPOST /message:stream HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Write a detailed report on climate change\"}],\n \"messageId\": \"msg-uuid\"\n }\n}\n```\n\n**SSE Response Stream:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: text/event-stream\n\ndata: {\"task\": {\"id\": \"task-uuid\", \"status\": {\"state\": \"TASK_STATE_WORKING\"}}}\n\ndata: {\"artifactUpdate\": {\"taskId\": \"task-uuid\", \"artifact\": {\"parts\": [{\"text\": \"# Climate Change Report\\n\\n\"}]}}}\n\ndata: {\"statusUpdate\": {\"taskId\": \"task-uuid\", \"status\": {\"state\": \"TASK_STATE_COMPLETED\"}}}\n```\n\n### 6.3. Multi-Turn Interaction\n\n**Scenario:** Agent requires additional input to complete a task.\n\n**Initial Request:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Book me a flight\"}],\n \"messageId\": \"msg-1\"\n }\n}\n```\n\n**Response (Input Required):**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"task\": {\n \"id\": \"task-uuid\",\n \"status\": {\n \"state\": \"TASK_STATE_INPUT_REQUIRED\",\n \"message\": {\n \"role\": \"ROLE_AGENT\",\n \"parts\": [{\"text\": \"I need more details. Where would you like to fly from and to?\"}]\n }\n }\n }\n}\n```\n\n**Follow-up Request:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"taskId\": \"task-uuid\",\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"From San Francisco to New York\"}],\n \"messageId\": \"msg-2\"\n }\n}\n```\n\n### 6.4. Version Negotiation Error\n\n**Scenario:** Client requests an unsupported protocol version.\n\n**Request:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\nA2A-Version: 0.5\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Hello\"}],\n \"messageId\": \"msg-uuid\"\n }\n}\n```\n\n**Response:**\n\n```http\nHTTP/1.1 400 Bad Request\nContent-Type: application/problem+json\n\n{\n \"type\": \"https://a2a-protocol.org/errors/version-not-supported\",\n \"title\": \"Protocol Version Not Supported\",\n \"status\": 400,\n \"detail\": \"The requested A2A protocol version 0.5 is not supported by this agent\",\n \"supportedVersions\": [\"0.3\"]\n}\n```\n\n### 6.5. Task Listing and Management\n\n**Scenario:** Client wants to see all tasks from a specific context or all tasks with a particular status.\n\n#### Request: All tasks from a specific context\n\n**Request:**\n\n```http\nGET /tasks?contextId=c295ea44-7543-4f78-b524-7a38915ad6e4&pageSize=10&historyLength=3 HTTP/1.1\nHost: agent.example.com\nAuthorization: Bearer token\n```\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"tasks\": [\n {\n \"id\": \"3f36680c-7f37-4a5f-945e-d78981fafd36\",\n \"contextId\": \"c295ea44-7543-4f78-b524-7a38915ad6e4\",\n \"status\": {\n \"state\": \"TASK_STATE_COMPLETED\",\n \"timestamp\": \"2024-03-15T10:15:00Z\"\n }\n }\n ],\n \"totalSize\": 5,\n \"pageSize\": 10,\n \"nextPageToken\": \"\"\n}\n```\n\n#### Request: All working tasks across all contexts\n\n**Request:**\n\n```http\nGET /tasks?status=TASK_STATE_WORKING&pageSize=20 HTTP/1.1\nHost: agent.example.com\nAuthorization: Bearer token\n```\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"tasks\": [\n {\n \"id\": \"789abc-def0-1234-5678-9abcdef01234\",\n \"contextId\": \"another-context-id\",\n \"status\": {\n \"state\": \"TASK_STATE_WORKING\",\n \"message\": {\n \"role\": \"ROLE_AGENT\",\n \"parts\": [\n {\n \"text\": \"Processing your document analysis...\"\n }\n ],\n \"messageId\": \"msg-status-update\"\n },\n \"timestamp\": \"2024-03-15T10:20:00Z\"\n }\n }\n ],\n \"totalSize\": 1,\n \"pageSize\": 20,\n \"nextPageToken\": \"\"\n}\n```\n\n#### Pagination Example\n\n**Request:**\n\n```http\nGET /tasks?contextId=c295ea44-7543-4f78-b524-7a38915ad6e4&pageSize=10&pageToken=base64-encoded-cursor-token HTTP/1.1\nHost: agent.example.com\nAuthorization: Bearer token\n```\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"tasks\": [\n /* ... additional tasks */\n ],\n \"totalSize\": 15,\n \"pageSize\": 10,\n \"nextPageToken\": \"base64-encoded-next-cursor-token\"\n}\n```\n\n#### Validation Error Example\n\n**Request:**\n\n```http\nGET /tasks?pageSize=150&historyLength=-5&status=TASK_STATE_RUNNING HTTP/1.1\nHost: agent.example.com\nAuthorization: Bearer token\n```\n\n**Response:**\n\n```http\nHTTP/1.1 400 Bad Request\nContent-Type: application/problem+json\n\n{\n \"status\": 400,\n \"detail\": \"Invalid parameters\",\n \"errors\": [\n {\n \"field\": \"pageSize\",\n \"message\": \"Must be between 1 and 100 inclusive, got 150\"\n },\n {\n \"field\": \"historyLength\",\n \"message\": \"Must be non-negative integer, got -5\"\n },\n {\n \"field\": \"status\",\n \"message\": \"Invalid status value 'running'. Must be one of: pending, working, completed, failed, canceled\"\n }\n ]\n}\n```\n\n### 6.6. Push Notification Setup and Usage\n\n**Scenario:** Client requests a long-running report generation and wants to be notified via webhook when it's done.\n\n**Initial Request with Push Notification Config:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [\n {\n \"text\": \"Generate the Q1 sales report. This usually takes a while. Notify me when it's ready.\"\n }\n ],\n \"messageId\": \"6dbc13b5-bd57-4c2b-b503-24e381b6c8d6\"\n },\n \"configuration\": {\n \"pushNotificationConfig\": {\n \"url\": \"https://client.example.com/webhook/a2a-notifications\",\n \"token\": \"secure-client-token-for-task-aaa\",\n \"authentication\": {\n \"schemes\": [\"Bearer\"]\n }\n }\n }\n}\n```\n\n**Response (Task Submitted):**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"task\": {\n \"id\": \"43667960-d455-4453-b0cf-1bae4955270d\",\n \"contextId\": \"c295ea44-7543-4f78-b524-7a38915ad6e4\",\n \"status\": {\n \"state\": \"submitted\",\n \"timestamp\": \"2024-03-15T11:00:00Z\"\n }\n }\n}\n```\n\n**Later: Server POSTs Notification to Webhook:**\n\n```http\nPOST /webhook/a2a-notifications HTTP/1.1\nHost: client.example.com\nAuthorization: Bearer server-generated-jwt\nContent-Type: application/a2a+json\nX-A2A-Notification-Token: secure-client-token-for-task-aaa\n\n{\n \"statusUpdate\": {\n \"taskId\": \"43667960-d455-4453-b0cf-1bae4955270d\",\n \"contextId\": \"c295ea44-7543-4f78-b524-7a38915ad6e4\",\n \"status\": {\n \"state\": \"TASK_STATE_COMPLETED\",\n \"timestamp\": \"2024-03-15T18:30:00Z\"\n }\n }\n}\n```\n\n### 6.7. File Exchange (Upload and Download)\n\n**Scenario:** Client sends an image for analysis, and the agent returns a modified image.\n\n**Request with File Upload:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [\n {\n \"text\": \"Analyze this image and highlight any faces.\"\n },\n {\n \"raw\": \"iVBORw0KGgoAAAANSUhEUgAAAAUA...\"\n \"filename\": \"input_image.png\",\n \"mediaType\": \"image/png\",\n }\n ],\n \"messageId\": \"6dbc13b5-bd57-4c2b-b503-24e381b6c8d6\"\n }\n}\n```\n\n**Response with File Reference:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"task\": {\n \"id\": \"43667960-d455-4453-b0cf-1bae4955270d\",\n \"contextId\": \"c295ea44-7543-4f78-b524-7a38915ad6e4\",\n \"status\": {\n \"state\": \"TASK_STATE_COMPLETED\",\n \"timestamp\": \"2024-03-15T12:05:00Z\"\n },\n \"artifacts\": [\n {\n \"artifactId\": \"9b6934dd-37e3-4eb1-8766-962efaab63a1\",\n \"name\": \"processed_image_with_faces.png\",\n \"parts\": [\n {\n \"url\": \"https://storage.example.com/processed/task-bbb/output.png?token=xyz\",\n \"filename\": \"output.png\",\n \"mediaType\": \"image/png\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### 6.8. Structured Data Exchange\n\n**Scenario:** Client asks for a list of open support tickets in a specific JSON format.\n\n**Request:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/a2a+json\nAuthorization: Bearer token\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [\n {\n \"text\": \"Show me a list of my open IT tickets\",\n \"metadata\": {\n \"mediaType\": \"application/json\",\n \"schema\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"ticketNumber\": { \"type\": \"string\" },\n \"description\": { \"type\": \"string\" }\n }\n }\n }\n }\n }\n ],\n \"messageId\": \"85b26db5-ffbb-4278-a5da-a7b09dea1b47\"\n }\n}\n```\n\n**Response with Structured Data:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"task\": {\n \"id\": \"d8c6243f-5f7a-4f6f-821d-957ce51e856c\",\n \"contextId\": \"c295ea44-7543-4f78-b524-7a38915ad6e4\",\n \"status\": {\n \"state\": \"TASK_STATE_COMPLETED\",\n \"timestamp\": \"2025-04-17T17:47:09.680794Z\"\n },\n \"artifacts\": [\n {\n \"artifactId\": \"c5e0382f-b57f-4da7-87d8-b85171fad17c\",\n \"parts\": [\n {\n \"text\": \"[{\\\"ticketNumber\\\":\\\"REQ12312\\\",\\\"description\\\":\\\"request for VPN access\\\"},{\\\"ticketNumber\\\":\\\"REQ23422\\\",\\\"description\\\":\\\"Add to DL - team-gcp-onboarding\\\"}]\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### 6.9. Fetching Authenticated Extended Agent Card\n\n**Scenario:** A client discovers a public Agent Card indicating support for an authenticated extended card and wants to retrieve the full details.\n\n**Step 1: Client fetches the public Agent Card:**\n\n```http\nGET /.well-known/agent-card.json HTTP/1.1\nHost: example.com\n```\n\n**Response includes:**\n\n```json\n{\n \"capabilities\": {\n \"extendedAgentCard\": true\n },\n \"securitySchemes\": {\n \"google\": {\n \"openIdConnectSecurityScheme\": {\n \"openIdConnectUrl\": \"https://accounts.google.com/.well-known/openid-configuration\"\n }\n }\n }\n}\n```\n\n### Step 2: Client obtains credentials (out-of-band OAuth 2.0 flow)\n\n### Step 3: Client fetches authenticated extended Agent Card\n\n```http\nGET /extendedAgentCard HTTP/1.1\nHost: agent.example.com\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/a2a+json\n\n{\n \"name\": \"Extended Agent with Additional Skills\",\n \"skills\": [\n /* Extended skills available to authenticated users */\n ]\n}\n```\n\n## 7. Authentication and Authorization\n\nA2A treats agents as standard enterprise applications, relying on established web security practices. Identity information is handled at the protocol layer, not within A2A semantics.\n\nFor a comprehensive guide on enterprise security aspects, see [Enterprise-Ready Features](./topics/enterprise-ready.md).\n\n### 7.1. Protocol Security\n\nProduction deployments **MUST** use encrypted communication (HTTPS for HTTP-based bindings, TLS for gRPC). Implementations **SHOULD** use modern TLS configurations (TLS 1.3+ recommended) with strong cipher suites.\n\n### 7.2. Server Identity Verification\n\nA2A Clients **SHOULD** verify the A2A Server's identity by validating its TLS certificate against trusted certificate authorities (CAs) during the TLS handshake.\n\n### 7.3. Client Authentication Process\n\n1. **Discovery of Requirements:** The client discovers the server's required authentication schemes via the `securitySchemes` field in the AgentCard.\n2. **Credential Acquisition (Out-of-Band):** The client obtains the necessary credentials through an out-of-band process specific to the required authentication scheme.\n3. **Credential Transmission:** The client includes these credentials in protocol-appropriate headers or metadata for every A2A request.\n\n### 7.4. Server Authentication Responsibilities\n\nThe A2A Server:\n\n- **MUST** authenticate every incoming request based on the provided credentials and its declared authentication requirements.\n- **SHOULD** use appropriate binding-specific error codes for authentication challenges or rejections.\n- **SHOULD** provide relevant authentication challenge information with error responses.\n\n### 7.5. Server Authorization Responsibilities\n\nOnce authenticated, the A2A Server authorizes requests based on the authenticated identity and its own policies. Authorization logic is implementation-specific and **MAY** consider:\n\n- Specific skills requested\n- Actions attempted within tasks\n- Data access policies\n- OAuth scopes (if applicable)\n\n### 7.6. In-Task Authorization\n\nIn the course of performing a task, an agent may require authorization to perform some action. Examples include:\n\n- An agent requiring an OAuth access token to call an API or another agent\n- An agent requiring human approval before a destructive action is taken\n\nIn the sections below, we refer to the object that represents the approved authorization as a credential.\n\nAgents may have multiple means for retrieving this authorization, such as via directly sending messages to a human.\n\nA2A provides the capability for agents to delegate the fulfillment of this authorization to the client via the `TASK_STATE_AUTH_REQUIRED` Task state. This provides agents a fallback path for requesting authorization by passing the responsibility to the client.\n\n#### 7.6.1 In-Task Authorization Agent Responsibilities\n\nTo request that a client fulfills an authorization request, the agent:\n\n1. MUST use a Task to track the operation it is performing\n2. MUST transition the TaskState to `TASK_STATE_AUTH_REQUIRED`\n3. MUST include a TaskStatus message explaining the required authorization, unless the details of the authorization have been negotiated out-of-band or via an extension\n\nAgents MUST arrange to receive credentials via an out-of-band means, unless an in-band mechanism has been negotiated out-of-band or via an extension.\n\nIf the credential is received out-of-band, the agent SHOULD maintain any active response streams with the client after setting the TaskState to `TASK_STATE_AUTH_REQUIRED`. The agent MAY immediately continue Task processing after receiving the credential, without a requirement that clients send a follow-up message.\n\nAgents SHOULD support receiving messages directed to the Task while the Task remains in `TASK_STATE_AUTH_REQUIRED`. This enables clients to negotiate, correct, or reject an authorization request.\n\n#### 7.6.2 In-Task Authorization Client Responsibilities\n\nUpon receiving a Task in `TASK_STATE_AUTH_REQUIRED`, a client is expected to take action in some way to resolve the agent's request for authorization.\n\nA client may:\n\n- Send a response message to the Task to negotiate, correct, or reject the authorization request.\n- Contact another human, agent, or service to fulfill the authorization request\n- Directly fulfill the authorization request via an out-of-band or extension negotiated means\n\nIf the client is itself an A2A agent actively processing a Task, the client may further delegate the authorization request to its client by transitioning its own Task to `TASK_STATE_AUTH_REQUIRED`. The client SHOULD follow all [In-Task Authorization Agent Responsibilities](#761-in-task-authorization-agent-responsibilities). This enables forming a chain of Tasks in `TASK_STATE_AUTH_REQUIRED`.\n\nClients may not be aware of when the agent receives credentials out-of-band and subsequently continues Task processing. If a client does not have an active response stream open with the agent, the client risks missing Task updates. To avoid this, a client SHOULD perform one of the following:\n\n- Subscribe to a stream of events for the Task using the [Subscribe to Task](#316-subscribe-to-task) operation\n- Register a webhook to receive events, if supported by the agent, using the [Create Push Notification Config](#317-create-push-notification-config) operation\n- Begin polling the Task using the [Get Task](#313-get-task) operation\n\n#### 7.6.3 In-Task Authorization Security Considerations\n\nAgents SHOULD receive credentials for in-task authorization requests out of band via a secure channel, such as HTTPS. This ensures that credentials are provided directly to the agent.\n\nIn-band credential exchange may be negotiated via out-of-band means or by using extensions. In-band credential exchange can allow credentials to be passed across chains of multiple A2A agents, exposing those credentials to each agent participating in the chain.\n\nIf using in-band credential exchange, we recommend adhering to the following security practices:\n\n- Credentials SHOULD be bound to the agent which originated the request, such that only this agent is able to use the credentials. This ensures that credentials propagating through a chain of A2A requests are only usable by the requesting agent.\n- Credentials containing sensitive information SHOULD be only readable by the agent which originated the request, such as by encrypting the credential.\n\n## 8. Agent Discovery: The Agent Card\n\n\n\n### 8.1. Purpose\n\nA2A Servers **MUST** make an Agent Card available. The Agent Card describes the server's identity, capabilities, skills, and interaction requirements. Clients use this information for discovering suitable agents and configuring interactions.\n\nFor more on discovery strategies, see the [Agent Discovery guide](./topics/agent-discovery.md).\n\n### 8.2. Discovery Mechanisms\n\nClients can find Agent Cards through:\n\n- **Well-Known URI:** Accessing `https://{server_domain}/.well-known/agent-card.json` (see [Section 8.6](#86-caching) for caching guidance)\n- **Registries/Catalogs:** Querying curated catalogs of agents\n- **Direct Configuration:** Pre-configured Agent Card URLs or content\n\n### 8.3. Protocol Declaration Requirements\n\nThe AgentCard **MUST** properly declare supported protocols:\n\n#### 8.3.1. Supported Interfaces Declaration\n\n- The `supportedInterfaces` field **SHOULD** declare all supported protocol combinations in preference order\n- The first entry in `supportedInterfaces` represents the preferred interface\n- Each interface **MUST** accurately declare its transport protocol and URL\n- URLs **MAY** be reused if multiple transports are available at the same endpoint\n\n#### 8.3.2. Client Protocol Selection\n\nClients **MUST** follow these rules:\n\n1. Parse `supportedInterfaces` if present, and select the first supported transport\n2. Prefer earlier entries in the ordered list when multiple options are supported\n3. Use the correct URL for the selected transport\n\n### 8.4. Agent Card Signing\n\nAgent Cards **MAY** be digitally signed using JSON Web Signature (JWS) as defined in [RFC 7515](https://tools.ietf.org/html/rfc7515) to ensure authenticity and integrity. Signatures allow clients to verify that an Agent Card has not been tampered with and originates from the claimed provider.\n\n#### 8.4.1. Canonicalization Requirements\n\nBefore signing, the Agent Card content **MUST** be canonicalized using the JSON Canonicalization Scheme (JCS) as defined in [RFC 8785](https://tools.ietf.org/html/rfc8785). This ensures consistent signature generation and verification across different JSON implementations.\n\n**Canonicalization Rules:**\n\n1. **Field Presence and Default Value Handling**: Before canonicalization, the JSON representation **MUST** respect Protocol Buffer field presence semantics as defined in [Section 5.7](#57-field-presence-and-optionality). This ensures that the canonical form accurately reflects which fields were explicitly provided versus which were omitted, enabling signature verification when Agent Cards are reconstructed:\n - **Optional fields not explicitly set**: Fields marked with the `optional` keyword that were not explicitly set **MUST** be omitted from the JSON object\n - **Optional fields explicitly set to defaults**: Fields marked with `optional` that were explicitly set to a value (even if that value matches a default) **MUST** be included in the JSON object\n - **Required fields**: Fields marked with `REQUIRED` **MUST** always be present, even if the field value matches the default.\n - **Default values**: Fields with default values **MUST** be omitted unless the field is marked as `REQUIRED` or has the `optional` keyword.\n\n2. **RFC 8785 Compliance**: The Agent Card JSON **MUST** be canonicalized according to RFC 8785, which specifies:\n - Predictable ordering of object properties (lexicographic by key)\n - Consistent representation of numbers, strings, and other primitive values\n - Removal of insignificant whitespace\n\n3. **Signature Field Exclusion**: The `signatures` field itself **MUST** be excluded from the content being signed to avoid circular dependencies.\n\n**Example of Default Value Removal:**\n\nOriginal Agent Card fragment:\n\n```json\n{\n \"name\": \"Example Agent\",\n \"description\": \"\",\n \"capabilities\": {\n \"streaming\": false,\n \"pushNotifications\": false,\n \"extensions\": []\n },\n \"skills\": []\n}\n```\n\nApplying the canonicalization rules:\n\n- `name`: \"Example Agent\" - REQUIRED field → **include**\n- `description`: \"\" - REQUIRED field → **include**\n- `capabilities`: object - REQUIRED field → **include** (after processing children)\n - `streaming`: false - optional field, present in JSON (explicitly set) → **include**\n - `pushNotifications`: false - optional field, present in JSON (explicitly set) → **include**\n - `extensions`: [] - repeated field (not REQUIRED) with empty array → **omit**\n- `skills`: [] - REQUIRED field → **include**\n\nAfter applying RFC 8785:\n\n```json\n{\"capabilities\":{\"pushNotifications\":false,\"streaming\":false},\"description\":\"\",\"name\":\"Example Agent\",\"skills\":[]}\n```\n\n#### 8.4.2. Signature Format\n\nSignatures use the JSON Web Signature (JWS) format as defined in [RFC 7515](https://tools.ietf.org/html/rfc7515). The [`AgentCardSignature`](#447-agentcardsignature) object represents JWS components using three fields:\n\n- **`protected`** (required, string): Base64url-encoded JSON object containing the JWS Protected Header\n- **`signature`** (required, string): Base64url-encoded signature value\n- **`header`** (optional, object): JWS Unprotected Header as a JSON object (not base64url-encoded)\n\n**JWS Protected Header Parameters:**\n\nThe protected header **MUST** include:\n\n- `alg`: Algorithm used for signing (e.g., \"ES256\", \"RS256\")\n- `typ`: **SHOULD** be set to \"JOSE\" for JWS\n- `kid`: Key ID for identifying the signing key\n\nThe protected header **MAY** include:\n\n- `jku`: URL to JSON Web Key Set (JWKS) containing the public key\n\n**Signature Generation Process:**\n\n1. **Prepare the payload:**\n - Remove properties with default values from the Agent Card\n - Exclude the `signatures` field\n - Canonicalize the resulting JSON using RFC 8785 to produce the canonical payload\n\n2. **Create the protected header:**\n - Construct a JSON object with the required header parameters (`alg`, `typ`, `kid`) and any optional parameters (`jku`)\n - Serialize the header to JSON\n - Base64url-encode the serialized header to produce the `protected` field value\n\n3. **Compute the signature:**\n - Construct the JWS Signing Input: `ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload))`\n - Sign the JWS Signing Input using the algorithm specified in the `alg` header parameter and the private key\n - Base64url-encode the resulting signature bytes to produce the `signature` field value\n\n4. **Assemble the AgentCardSignature:**\n - Set `protected` to the base64url-encoded protected header from step 2\n - Set `signature` to the base64url-encoded signature value from step 3\n - Optionally set `header` to a JSON object containing any unprotected header parameters.\n\n**Example:**\n\nGiven a canonical Agent Card payload and signing key, the signature generation produces:\n\n```json\n{\n \"protected\": \"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0\",\n \"signature\": \"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ\"\n}\n```\n\nWhere the `protected` value decodes to:\n\n```json\n{\"alg\":\"ES256\",\"typ\":\"JOSE\",\"kid\":\"key-1\",\"jku\":\"https://example.com/agent/jwks.json\"}\n```\n\n#### 8.4.3. Signature Verification\n\nClients verifying Agent Card signatures **MUST**:\n\n1. Extract the signature from the `signatures` array\n2. Retrieve the public key using the `kid` and `jku` (or from a trusted key store)\n3. Remove properties with default values from the received Agent Card\n4. Exclude the `signatures` field\n5. Canonicalize the resulting JSON using RFC 8785\n6. Verify the signature against the canonicalized payload\n\n**Security Considerations:**\n\n- Clients **SHOULD** verify at least one signature before trusting an Agent Card\n- Public keys **SHOULD** be retrieved over secure channels (HTTPS)\n- Clients **MAY** maintain a trusted key store for known agent providers\n- Expired or revoked keys **MUST NOT** be used for verification\n- Multiple signatures **MAY** be present to support key rotation\n\n### 8.5. Sample Agent Card\n\n```json\n{\n \"name\": \"GeoSpatial Route Planner Agent\",\n \"description\": \"Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.\",\n \"supportedInterfaces\": [\n {\"url\": \"https://georoute-agent.example.com/a2a/v1\", \"protocolBinding\": \"JSONRPC\", \"protocolVersion\": \"1.0\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/grpc\", \"protocolBinding\": \"GRPC\", \"protocolVersion\": \"1.0\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/json\", \"protocolBinding\": \"HTTP+JSON\", \"protocolVersion\": \"1.0\"}\n ],\n \"provider\": {\n \"organization\": \"Example Geo Services Inc.\",\n \"url\": \"https://www.examplegeoservices.com\"\n },\n \"iconUrl\": \"https://georoute-agent.example.com/icon.png\",\n \"version\": \"1.2.0\",\n \"documentationUrl\": \"https://docs.examplegeoservices.com/georoute-agent/api\",\n \"capabilities\": {\n \"streaming\": true,\n \"pushNotifications\": true,\n \"stateTransitionHistory\": false,\n \"extendedAgentCard\": true\n },\n \"securitySchemes\": {\n \"google\": {\n \"openIdConnectSecurityScheme\": {\n \"openIdConnectUrl\": \"https://accounts.google.com/.well-known/openid-configuration\"\n }\n }\n },\n \"security\": [{ \"google\": [\"openid\", \"profile\", \"email\"] }],\n \"defaultInputModes\": [\"application/json\", \"text/plain\"],\n \"defaultOutputModes\": [\"application/json\", \"image/png\"],\n \"skills\": [\n {\n \"id\": \"route-optimizer-traffic\",\n \"name\": \"Traffic-Aware Route Optimizer\",\n \"description\": \"Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).\",\n \"tags\": [\"maps\", \"routing\", \"navigation\", \"directions\", \"traffic\"],\n \"examples\": [\n \"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.\",\n \"{\\\"origin\\\": {\\\"lat\\\": 37.422, \\\"lng\\\": -122.084}, \\\"destination\\\": {\\\"lat\\\": 37.7749, \\\"lng\\\": -122.4194}, \\\"preferences\\\": [\\\"avoid_ferries\\\"]}\"\n ],\n \"inputModes\": [\"application/json\", \"text/plain\"],\n \"outputModes\": [\n \"application/json\",\n \"application/vnd.geo+json\",\n \"text/html\"\n ]\n },\n {\n \"id\": \"custom-map-generator\",\n \"name\": \"Personalized Map Generator\",\n \"description\": \"Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.\",\n \"tags\": [\"maps\", \"customization\", \"visualization\", \"cartography\"],\n \"examples\": [\n \"Generate a map of my upcoming road trip with all planned stops highlighted.\",\n \"Show me a map visualizing all coffee shops within a 1-mile radius of my current location.\"\n ],\n \"inputModes\": [\"application/json\"],\n \"outputModes\": [\n \"image/png\",\n \"image/jpeg\",\n \"application/json\",\n \"text/html\"\n ]\n }\n ],\n \"signatures\": [\n {\n \"protected\": \"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0\",\n \"signature\": \"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ\"\n }\n ]\n}\n```\n\n### 8.6. Caching\n\nAgent Card content changes infrequently relative to the frequency at which clients may fetch it. Servers and clients **SHOULD** use standard HTTP caching mechanisms to reduce unnecessary network overhead.\n\n#### 8.6.1. Server Requirements\n\n- Agent Card HTTP endpoints **SHOULD** include a `Cache-Control` response header with a `max-age` directive appropriate for the agent's expected update frequency\n- Agent Card HTTP endpoints **SHOULD** include an `ETag` response header derived from the Agent Card's `version` field or a hash of the card content\n- Agent Card HTTP endpoints **MAY** include a `Last-Modified` response header\n\n#### 8.6.2. Client Requirements\n\n- Clients **SHOULD** honor HTTP caching semantics as defined in [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) when fetching Agent Cards\n- When a cached Agent Card has expired, clients **SHOULD** use conditional requests (`If-None-Match` with the stored `ETag`, or `If-Modified-Since`) to avoid re-downloading unchanged cards\n- When the server does not include caching headers, clients **MAY** apply an implementation-specific default cache duration\n\n## 9. JSON-RPC Protocol Binding\n\nThe JSON-RPC protocol binding provides a simple, HTTP-based interface using JSON-RPC 2.0 for method calls and Server-Sent Events for streaming.\n\n### 9.1. Protocol Requirements\n\n- **Protocol:** JSON-RPC 2.0 over HTTP(S)\n- **Content-Type:** `application/json` for requests and responses\n- **Method Naming:** PascalCase method names matching gRPC conventions (e.g., `SendMessage`, `GetTask`)\n- **Streaming:** Server-Sent Events (`text/event-stream`)\n\n### 9.2. Service Parameter Transmission\n\nA2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using standard HTTP request headers, as JSON-RPC 2.0 operates over HTTP(S).\n\n**Service Parameter Requirements:**\n\n- Service parameter names **MUST** be transmitted as HTTP header fields\n- Service parameter keys are case-insensitive per HTTP specification (RFC 7230)\n- Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single header field\n\n**Example Request with A2A Service Parameters:**\n\n```http\nPOST /rpc HTTP/1.1\nHost: agent.example.com\nContent-Type: application/json\nAuthorization: Bearer token\nA2A-Version: 0.3\nA2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1\n\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"SendMessage\",\n \"params\": { /* SendMessageRequest */ }\n}\n```\n\n### 9.3. Base Request Structure\n\nAll JSON-RPC requests **MUST** follow the standard JSON-RPC 2.0 format:\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": \"unique-request-id\",\n \"method\": \"category/action\",\n \"params\": { /* method-specific parameters */ }\n}\n```\n\n### 9.4. Core Methods\n\n#### 9.4.1. `SendMessage`\n\nSends a message to initiate or continue a task.\n\n**Request:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"SendMessage\",\n \"params\": { /* SendMessageRequest object */ }\n}\n```\n\n**Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest), [`Message`](#414-message)\n\n**Response:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n /* SendMessageResponse object, contains one of:\n * \"task\": { Task object }\n * \"message\": { Message object }\n */\n }\n```\n\n**Referenced Objects:** [`Task`](#411-task), [`Message`](#414-message)\n\n#### 9.4.2. `SendStreamingMessage`\n\nSends a message and subscribes to real-time updates via Server-Sent Events.\n\n**Request:** Same as `SendMessage`\n\n**Response:** HTTP 200 with `Content-Type: text/event-stream`\n\n```text\ndata: {\"jsonrpc\": \"2.0\", \"id\": 1, \"result\": { /* StreamResponse object */ }}\n\ndata: {\"jsonrpc\": \"2.0\", \"id\": 1, \"result\": { /* StreamResponse object */ }}\n```\n\n**Referenced Objects:** [`StreamResponse`](#323-stream-response)\n\n#### 9.4.3. `GetTask`\n\nRetrieves the current state of a task.\n\n**Request:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"GetTask\",\n \"params\": {\n \"id\": \"task-uuid\",\n \"historyLength\": 10\n }\n}\n```\n\n#### 9.4.4. `ListTasks`\n\nLists tasks with optional filtering and pagination.\n\n**Request:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"method\": \"ListTasks\",\n \"params\": {\n \"contextId\": \"context-uuid\",\n \"status\": \"TASK_STATE_WORKING\",\n \"pageSize\": 50,\n \"pageToken\": \"cursor-token\"\n }\n}\n```\n\n#### 9.4.5. `CancelTask`\n\nCancels an ongoing task.\n\n**Request:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 4,\n \"method\": \"CancelTask\",\n \"params\": {\n \"id\": \"task-uuid\"\n }\n}\n```\n\n#### 9.4.6. `SubscribeToTask`\n\n\n\nSubscribes to a task stream for receiving updates on a task that is not in a terminal state.\n\n**Request:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 5,\n \"method\": \"SubscribeToTask\",\n \"params\": {\n \"id\": \"task-uuid\"\n }\n}\n```\n\n**Response:** SSE stream (same format as `SendStreamingMessage`)\n\n**Error:** Returns `UnsupportedOperationError` if the task is in a terminal state (`completed`, `failed`, `canceled`, or `rejected`).\n\n#### 9.4.7. Push Notification Configuration Methods\n\n- `CreateTaskPushNotificationConfig` - Create push notification configuration\n- `GetTaskPushNotificationConfig` - Get push notification configuration\n- `ListTaskPushNotificationConfigs` - List push notification configurations\n- `DeleteTaskPushNotificationConfig` - Delete push notification configuration\n\n#### 9.4.8. `GetExtendedAgentCard`\n\nRetrieves an extended Agent Card.\n\n**Request:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 6,\n \"method\": \"GetExtendedAgentCard\"\n}\n```\n\n### 9.5. Error Handling\n\nJSON-RPC error responses use the standard [JSON-RPC 2.0 error object](https://www.jsonrpc.org/specification#error_object) structure, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:\n\n- **Error Code**: Mapped to `error.code` (numeric JSON-RPC error code)\n- **Error Message**: Mapped to `error.message` (human-readable string)\n- **Error Details**: Mapped to `error.data` (array containing `google.protobuf.Any` messages, using ProtoJSON representation)\n\n**Standard JSON-RPC Error Codes:**\n\n| JSON-RPC Error Code | Error Name | Standard Message | Description |\n| :------------------ | :-------------------- | :--------------------------------- | :------------------------------------------------------ |\n| `-32700` | `JSONParseError` | \"Invalid JSON payload\" | The server received invalid JSON |\n| `-32600` | `InvalidRequestError` | \"Request payload validation error\" | The JSON sent is not a valid Request object |\n| `-32601` | `MethodNotFoundError` | \"Method not found\" | The requested method does not exist or is not available |\n| `-32602` | `InvalidParamsError` | \"Invalid parameters\" | The method parameters are invalid |\n| `-32603` | `InternalError` | \"Internal error\" | An internal error occurred on the server |\n\n**A2A-Specific Error Codes:**\n\nA2A-specific errors use codes in the range `-32001` to `-32099`. For the complete mapping of A2A error types to JSON-RPC error codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings).\n\n**A2A Error Representation:**\n\nFor A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `data` array with:\n\n- `@type`: Set to `\"type.googleapis.com/google.rpc.ErrorInfo\"`\n- `reason`: The A2A error type in UPPER_SNAKE_CASE without the \"Error\" suffix (e.g., `TASK_NOT_FOUND`)\n- `domain`: Set to `\"a2a-protocol.org\"`\n- `metadata`: Optional map of additional error context\n\nAdditional error context **MAY** be included in the `data` array.\n\n**Error Response Structure:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"error\": {\n \"code\": -32601,\n \"message\": \"Method not found\",\n \"data\": {\n \"method\": \"invalid/method\"\n }\n }\n}\n```\n\n**Example A2A-Specific Error Response:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"error\": {\n \"code\": -32001,\n \"message\": \"Task not found\",\n \"data\": [\n {\n \"@type\": \"type.googleapis.com/google.rpc.ErrorInfo\",\n \"reason\": \"TASK_NOT_FOUND\",\n \"domain\": \"a2a-protocol.org\",\n \"metadata\": {\n \"taskId\": \"nonexistent-task-id\",\n \"timestamp\": \"2025-11-09T10:30:00.000Z\"\n }\n }\n ]\n }\n}\n```\n\n## 10. gRPC Protocol Binding\n\nThe gRPC Protocol Binding provides a high-performance, strongly-typed interface using Protocol Buffers over HTTP/2. The gRPC Protocol Binding leverages the [API guidelines](https://google.aip.dev/general) to simplify gRPC to HTTP mapping.\n\n### 10.1. Protocol Requirements\n\n- **Protocol:** gRPC over HTTP/2 with TLS\n- **Definition:** Use the normative Protocol Buffers definition in `specification/a2a.proto`\n- **Serialization:** Protocol Buffers version 3\n- **Service:** Implement the `A2AService` gRPC service\n\n### 10.2. Service Parameter Transmission\n\nA2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using gRPC metadata (headers).\n\n**Service Parameter Requirements:**\n\n- Service parameter names **MUST** be transmitted as gRPC metadata keys\n- Metadata keys are case-insensitive and automatically converted to lowercase by gRPC\n- Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single metadata entry\n\n**Example gRPC Request with A2A Service Parameters:**\n\n```go\n// Go example using gRPC metadata\nmd := metadata.Pairs(\n \"authorization\", \"Bearer token\",\n \"a2a-version\", \"0.3\",\n \"a2a-extensions\", \"https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1\",\n)\nctx := metadata.NewOutgoingContext(context.Background(), md)\n\n// Make the RPC call with the context containing metadata\nresponse, err := client.SendMessage(ctx, request)\n```\n\n**Metadata Handling:**\n\n- Implementations **MUST** extract A2A service parameters from gRPC metadata for processing\n- Servers **SHOULD** validate required service parameters (e.g., `A2A-Version`) from metadata\n- Service parameter keys in metadata are normalized to lowercase per gRPC conventions\n\n### 10.3. Service Definition\n\n{{ proto_service_to_table(\"A2AService\") }}\n\n### 10.4. Core Methods\n\n#### 10.4.1. SendMessage\n\nSends a message to an agent.\n\n**Request:**\n\n{{ proto_to_table(\"SendMessageRequest\") }}\n\n**Response:**\n\n{{ proto_to_table(\"SendMessageResponse\") }}\n\n#### 10.4.2. SendStreamingMessage\n\nSends a message with streaming updates.\n\n**Request:**\n\n{{ proto_to_table(\"SendMessageRequest\") }}\n\n**Response:** Server streaming [`StreamResponse`](#stream-response) objects.\n\n#### 10.4.3. GetTask\n\nRetrieves task status.\n\n**Request:**\n\n{{ proto_to_table(\"GetTaskRequest\") }}\n\n**Response:** See [`Task`](#411-task) object definition.\n\n#### 10.4.4. ListTasks\n\nLists tasks with filtering.\n\n**Request:**\n\n{{ proto_to_table(\"ListTasksRequest\") }}\n\n**Response:**\n\n{{ proto_to_table(\"ListTasksResponse\") }}\n\n#### 10.4.5. CancelTask\n\nCancels a running task.\n\n**Request:**\n\n{{ proto_to_table(\"CancelTaskRequest\") }}\n\n**Response:** See [`Task`](#411-task) object definition.\n\n#### 10.4.6. SubscribeToTask\n\nSubscribe to task updates via streaming. Returns `UnsupportedOperationError` if the task is in a terminal state.\n\n**Request:**\n\n{{ proto_to_table(\"SubscribeToTaskRequest\") }}\n\n**Response:** Server streaming [`StreamResponse`](#stream-response) objects.\n\n#### 10.4.7. CreateTaskPushNotificationConfig\n\nCreates a push notification configuration for a task.\n\n**Request:**\n\n{{ proto_to_table(\"CreateTaskPushNotificationConfigRequest\") }}\n\n**Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition.\n\n#### 10.4.8. GetTaskPushNotificationConfig\n\nRetrieves an existing push notification configuration for a task.\n\n**Request:**\n\n{{ proto_to_table(\"GetTaskPushNotificationConfigRequest\") }}\n\n**Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition.\n\n#### 10.4.9. ListTaskPushNotificationConfigs\n\nLists all push notification configurations for a task.\n\n**Request:**\n\n{{ proto_to_table(\"ListTaskPushNotificationConfigsRequest\") }}\n\n**Response:**\n\n{{ proto_to_table(\"ListTaskPushNotificationConfigsResponse\") }}\n\n#### 10.4.10. DeleteTaskPushNotificationConfig\n\nRemoves a push notification configuration for a task.\n\n**Request:**\n\n{{ proto_to_table(\"DeleteTaskPushNotificationConfigRequest\") }}\n\n**Response:** `google.protobuf.Empty`\n\n#### 10.4.11. GetExtendedAgentCard\n\nRetrieves the agent's extended capability card after authentication.\n\n**Request:**\n\n{{ proto_to_table(\"GetExtendedAgentCardRequest\") }}\n\n**Response:** See [`AgentCard`](#441-agentcard) object definition.\n\n### 10.5. gRPC-Specific Data Types\n\n#### 10.5.1. TaskPushNotificationConfig\n\nResource wrapper for push notification configurations. This is a gRPC-specific type used in resource-oriented operations to provide the full resource name along with the configuration data.\n\n{{ proto_to_table(\"TaskPushNotificationConfig\") }}\n\n**Fields:**\n\n{{ proto_to_table(\"TaskPushNotificationConfig\") }}\n\n### 10.6. Error Handling\n\ngRPC error responses use the standard [gRPC status](https://grpc.io/docs/guides/error/) structure with [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto), which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:\n\n- **Error Code**: Mapped to `status.code` (gRPC status code enum)\n- **Error Message**: Mapped to `status.message` (human-readable string)\n- **Error Details**: Mapped to `status.details` (repeated google.protobuf.Any messages)\n\n**A2A Error Representation:**\n\nFor A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `status.details` array with:\n\n- `reason`: The A2A error type in UPPER_SNAKE_CASE without the \"Error\" suffix (e.g., `TASK_NOT_FOUND`)\n- `domain`: Set to `\"a2a-protocol.org\"`\n- `metadata`: Optional map of additional error context\n\nFor the complete mapping of A2A error types to gRPC status codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings).\n\n**Error Response Example:**\n\n```proto\n// Standard gRPC invalid argument error\nstatus {\n code: INVALID_ARGUMENT\n message: \"Invalid request parameters\"\n details: [\n {\n type: \"type.googleapis.com/google.rpc.BadRequest\"\n field_violations: [\n {\n field: \"message.parts\"\n description: \"At least one part is required\"\n }\n ]\n }\n ]\n}\n```\n\n**Example A2A-Specific Error Response:**\n\n```proto\n// A2A-specific task not found error\nstatus {\n code: NOT_FOUND\n message: \"Task with ID 'task-123' not found\"\n details: [\n {\n type: \"type.googleapis.com/google.rpc.ErrorInfo\"\n reason: \"TASK_NOT_FOUND\"\n domain: \"a2a-protocol.org\"\n metadata: {\n task_id: \"task-123\"\n timestamp: \"2025-11-09T10:30:00Z\"\n }\n }\n ]\n}\n```\n\n### 10.7. Streaming\n\ngRPC streaming uses server streaming RPCs for real-time updates. The `StreamResponse` message provides a union of possible streaming events:\n\n{{ proto_to_table(\"StreamResponse\") }}\n\n## 11. HTTP+JSON/REST Protocol Binding\n\nThe HTTP+JSON protocol binding provides a RESTful interface using standard HTTP methods and JSON payloads.\n\n### 11.1. Protocol Requirements\n\n- **Protocol:** HTTP(S) with JSON payloads\n- **Content-Type:** `application/json` for requests and responses\n- **Methods:** Standard HTTP verbs (GET, POST, PUT, DELETE)\n- **URL Patterns:** RESTful resource-based URLs\n- **Streaming:** Server-Sent Events for real-time updates\n\n### 11.2. Service Parameter Transmission\n\nA2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using standard HTTP request headers.\n\n**Service Parameter Requirements:**\n\n- Service parameter names **MUST** be transmitted as HTTP header fields\n- Service parameter keys are case-insensitive per HTTP specification (RFC 9110)\n- Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single header field\n\n**Example Request with A2A Service Parameters:**\n\n```http\nPOST /message:send HTTP/1.1\nHost: agent.example.com\nContent-Type: application/json\nAuthorization: Bearer token\nA2A-Version: 0.3\nA2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1\n\n{\n \"message\": {\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Find restaurants near me\"}]\n }\n}\n```\n\n### 11.3. URL Patterns and HTTP Methods\n\n#### 11.3.1. Message Operations\n\n- `POST /message:send` - Send message\n- `POST /message:stream` - Send message with streaming (SSE response)\n\n#### 11.3.2. Task Operations\n\n- `GET /tasks/{id}` - Get task status\n- `GET /tasks` - List tasks (with query parameters)\n- `POST /tasks/{id}:cancel` - Cancel task\n- `POST /tasks/{id}:subscribe` - Subscribe to task updates (SSE response, returns error for terminal tasks)\n\n#### 11.3.3. Push Notification Configuration\n\n- `POST /tasks/{id}/pushNotificationConfigs` - Create configuration\n- `GET /tasks/{id}/pushNotificationConfigs/{configId}` - Get configuration\n- `GET /tasks/{id}/pushNotificationConfigs` - List configurations\n- `DELETE /tasks/{id}/pushNotificationConfigs/{configId}` - Delete configuration\n\n#### 11.3.4. Agent Card\n\n- `GET /extendedAgentCard` - Get authenticated extended Agent Card\n\n### 11.4. Request/Response Format\n\nAll requests and responses use JSON objects structurally equivalent to the Protocol Buffer definitions.\n\n**Example Send Message:**\n\n```http\nPOST /message:send\nContent-Type: application/json\n\n{\n \"message\": {\n \"messageId\": \"uuid\",\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Hello\"}]\n },\n \"configuration\": {\n \"acceptedOutputModes\": [\"text/plain\"]\n }\n}\n```\n\n**Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest), [`Message`](#414-message)\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n \"task\": {\n \"id\": \"task-uuid\",\n \"contextId\": \"context-uuid\",\n \"status\": {\n \"state\": \"TASK_STATE_COMPLETED\"\n }\n }\n}\n```\n\n**Referenced Objects:** [`Task`](#411-task)\n\n### 11.5. Query Parameter Naming for Request Parameters\n\nHTTP methods that do not support request bodies (GET, DELETE) **MUST** transmit operation request parameters as path parameters or query parameters. This section defines how to map Protocol Buffer field names to query parameter names.\n\n**Naming Convention:**\n\nQuery parameter names **MUST** use `camelCase` to match the JSON serialization of Protocol Buffer field names. This ensures consistency with request bodies used in POST operations.\n\n**Example Mappings:**\n\n| Protocol Buffer Field | Query Parameter Name | Example Usage |\n| --------------------- | -------------------- | ------------------- |\n| `context_id` | `contextId` | `?contextId=uuid` |\n| `page_size` | `pageSize` | `?pageSize=50` |\n| `page_token` | `pageToken` | `?pageToken=cursor` |\n| `task_id` | `taskId` | `?taskId=uuid` |\n\n**Usage Examples:**\n\nList tasks with filtering:\n\n```http\nGET /tasks?contextId=uuid&status=working&pageSize=50&pageToken=cursor\n```\n\nGet task with history:\n\n```http\nGET /tasks/{id}?historyLength=10\n```\n\n**Field Type Handling:**\n\n- **Strings**: Passed directly as query parameter values\n- **Booleans**: Represented as lowercase strings (`true`, `false`)\n- **Numbers**: Represented as decimal strings\n- **Enums**: Represented using their string values (e.g., `status=working`)\n- **Repeated Fields**: Multiple values **MAY** be passed by repeating the parameter name (e.g., `?tag=value1&tag=value2`) or as comma-separated values (e.g., `?tag=value1,value2`)\n- **Nested Objects**: Not supported in query parameters; operations requiring nested objects **MUST** use POST with a request body\n- **Datetimes/Timestamps**: Represented as ISO 8601 strings (e.g., `2025-11-09T10:30:00Z`)\n\n**URL Encoding:**\n\nAll query parameter values **MUST** be properly URL-encoded per [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html).\n\n### 11.6. Error Handling\n\nHTTP error responses use the representation specified in [AIP-193](https://google.aip.dev/193#http11json-representation) which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:\n\n- **Error Code**: Mapped to the HTTP status code and the `error.code` field\n- **Error Message**: Mapped to the `error.message` field (human-readable string)\n- **Error Details**: Mapped to the `error.details` array (containing `google.protobuf.Any` messages)\n\n**A2A Error Representation:**\n\nFor A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `details` array with:\n\n- `@type`: Set to `\"type.googleapis.com/google.rpc.ErrorInfo\"`\n- `reason`: The A2A error type in UPPER_SNAKE_CASE without the \"Error\" suffix (e.g., `TASK_NOT_FOUND`)\n- `domain`: Set to `\"a2a-protocol.org\"`\n- `metadata`: Optional map of additional error context\n\nFor the complete mapping of A2A error types to HTTP status codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings). Additional error context **MAY** be included in the `details` array of the Status object.\n\n**Error Response Example:**\n\n```http\nHTTP/1.1 404 Not Found\nContent-Type: application/json\n\n{\n \"error\": {\n \"code\": 404,\n \"status\": \"NOT_FOUND\",\n \"message\": \"The specified task ID does not exist or is not accessible\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/google.rpc.ErrorInfo\",\n \"reason\": \"TASK_NOT_FOUND\",\n \"domain\": \"a2a-protocol.org\",\n \"metadata\": {\n \"taskId\": \"task-123\",\n \"timestamp\": \"2025-11-09T10:30:00.000Z\"\n }\n }\n ]\n }\n}\n```\n\nExtension fields like `taskId` and `timestamp` provide additional context to help diagnose the error.\n\n### 11.7. Streaming\n\n\n\nREST streaming uses Server-Sent Events with the `data` field containing JSON serializations of the protocol data objects:\n\n```http\nPOST /message:stream\nContent-Type: application/json\n\n{ /* SendMessageRequest object */ }\n```\n\n**Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest)\n\n**Response:**\n\n```http\nHTTP/1.1 200 OK\nContent-Type: text/event-stream\n\ndata: { /* StreamResponse object */ }\n\ndata: { /* StreamResponse object */ }\n```\n\n**Referenced Objects:** [`StreamResponse`](#323-stream-response)\nStreaming responses are simple, linearly ordered sequences: first a `Task` (or single `Message`), then zero or more status or artifact update events until the task reaches a terminal or interrupted state, at which point the stream closes. Implementations SHOULD avoid re-ordering events and MAY optionally resend a final `Task` snapshot before closing.\n\n## 12. Custom Binding Guidelines\n\nWhile the A2A protocol provides three standard bindings (JSON-RPC, gRPC, and HTTP+JSON/REST), implementers **MAY** create custom protocol bindings to support additional transport mechanisms or communication patterns. Custom bindings **MUST** comply with all requirements defined in [Section 5 (Protocol Binding Requirements and Interoperability)](#5-protocol-binding-requirements-and-interoperability). This section provides additional guidelines specific to developing custom bindings.\n\n### 12.1. Binding Requirements\n\nCustom protocol bindings **MUST**:\n\n1. **Implement All Core Operations**: Support all operations defined in [Section 3 (A2A Protocol Operations)](#3-a2a-protocol-operations)\n2. **Preserve Data Model**: Use data structures functionally equivalent to those defined in [Section 4 (Protocol Data Model)](#4-protocol-data-model)\n3. **Maintain Semantics**: Ensure operations behave consistently with the abstract operation definitions\n4. **Document Completely**: Provide comprehensive documentation of the binding specification\n\n### 12.2. Data Type Mappings\n\nCustom bindings **MUST** provide clear mappings for:\n\n- **Protocol Buffer Types**: Define how each Protocol Buffer message type is represented\n- **Timestamps**: Follow the conventions in [Section 5.6.1 (Timestamps)](#561-timestamps)\n- **Binary Data**: Specify encoding for binary content (e.g., base64 for text-based protocols)\n- **Enumerations**: Define representation of enum values (e.g., strings, integers)\n\n### 12.3. Service Parameter Transmission\n\nAs specified in [Section 3.2.6 (Service Parameters)](#326-service-parameters), custom protocol bindings **MUST** document how service parameters are transmitted. The binding specification **MUST** address:\n\n1. **Transmission Mechanism**: The protocol-specific method for transmitting service parameter key-value pairs\n2. **Value Constraints**: Any limitations on service parameter values (e.g., character encoding, size limits)\n3. **Reserved Names**: Any service parameter names reserved by the binding itself\n4. **Fallback Strategy**: What happens when the protocol lacks native header support (e.g., passing service parameters in metadata)\n\n**Example Documentation Requirements:**\n\n- **For native header support**: \"Service parameters are transmitted using HTTP request headers. Service parameter keys are case-insensitive and must conform to RFC 7230. Service parameter values must be UTF-8 strings.\"\n- **For protocols without headers**: \"Service parameters are serialized as a JSON object and transmitted in the request metadata field `a2a-service-parameters`.\"\n\n### 12.4. Error Mapping\n\nCustom bindings **MUST**:\n\n1. **Map Standard Errors**: Provide mappings for all A2A-specific error types defined in [Section 3.2.2 (Error Handling)](#332-error-handling)\n2. **Preserve Error Information**: Ensure error details are accessible to clients\n3. **Use Appropriate Codes**: Map to protocol-native error codes where applicable\n4. **Document Error Format**: Specify the structure of error responses\n\n### 12.5. Streaming Support\n\nIf the binding supports streaming operations:\n\n1. **Define Stream Mechanism**: Document how streaming is implemented (e.g., WebSockets, long-polling, chunked encoding)\n2. **Event Ordering**: Specify ordering guarantees for streaming events\n3. **Reconnection**: Define behavior for connection interruption and resumption\n4. **Stream Termination**: Specify how stream completion is signaled\n\nIf streaming is not supported, the binding **MUST** clearly document this limitation in the Agent Card.\n\n### 12.6. Authentication and Authorization\n\nCustom bindings **MUST**:\n\n1. **Support Standard Schemes**: Implement authentication schemes declared in the Agent Card\n2. **Document Integration**: Specify how credentials are transmitted in the protocol\n3. **Handle Challenges**: Define how authentication challenges are communicated\n4. **Maintain Security**: Follow security best practices for the transport protocol\n\n### 12.7. Agent Card Declaration\n\nCustom bindings **MUST** be declared in the Agent Card:\n\n1. **Transport Identifier**: Use a clear, descriptive transport name\n2. **Endpoint URL**: Provide the full URL where the binding is available\n3. **Documentation Link**: Include a URL to the complete binding specification\n\n**Example:**\n\n```json\n{\n \"supportedInterfaces\": [\n {\n \"url\": \"wss://agent.example.com/a2a/websocket\",\n \"protocolBinding\": \"WEBSOCKET\"\n }\n ]\n}\n```\n\n### 12.8. Interoperability Testing\n\nCustom binding implementers **SHOULD**:\n\n1. **Test Against Reference**: Verify behavior matches standard bindings\n2. **Document Differences**: Clearly note any deviations from standard binding behavior\n3. **Provide Examples**: Include sample requests and responses\n4. **Test Edge Cases**: Verify handling of error conditions, large payloads, and long-running tasks\n\n## 13. Security Considerations\n\nThis section consolidates security guidance and best practices for implementing and operating A2A agents. For additional enterprise security considerations, see [Enterprise-Ready Features](./topics/enterprise-ready.md).\n\n### 13.1. Data Access and Authorization Scoping\n\nImplementations **MUST** ensure appropriate scope limitation based on the authenticated caller's authorization boundaries. This applies to all operations that access or list tasks and other resources.\n\n**Authorization Principles:**\n\n- Servers **MUST** implement authorization checks on every [A2A Protocol Operations](#3-a2a-protocol-operations) request\n- Implementations **MUST** scope results to the caller's authorized access boundaries as defined by the agent's authorization model\n- Even when `contextId` or other filter parameters are not specified in requests, implementations **MUST** scope results to the caller's authorized access boundaries\n- Authorization models are agent-defined and **MAY** be based on:\n - User identity (user-based authorization)\n - Organizational roles or groups (role-based authorization)\n - Project or workspace membership (project-based authorization)\n - Organizational or tenant boundaries (multi-tenant authorization)\n - Custom authorization logic specific to the agent's domain\n\n**Operations Requiring Scope Limitation:**\n\n- [`List Tasks`](#314-list-tasks): **MUST** only return tasks visible to the authenticated client according to the agent's authorization model\n- [`Get Task`](#313-get-task): **MUST** verify the authenticated client has access to the requested task according to the agent's authorization model\n- Task-related operations (Cancel, Subscribe, Push Notification Config): **MUST** verify the client has appropriate access rights according to the agent's authorization model\n\n**Implementation Requirements:**\n\n- Authorization boundaries are defined by each agent's authorization model, not prescribed by the protocol\n- Authorization checks **MUST** occur before any database queries or operations that could leak information about the existence of resources outside the caller's authorization scope\n- Agents **SHOULD** document their authorization model and access control policies\n\nSee also: [Section 3.1.4 List Tasks (Security Note)](#314-list-tasks) for operation-specific requirements.\n\n### 13.2. Push Notification Security\n\nWhen implementing push notifications, both agents (as webhook callers) and clients (as webhook receivers) have security responsibilities.\n\n**Agent (Webhook Caller) Requirements:**\n\n- Agents **MUST** include authentication credentials in webhook requests as specified in [`PushNotificationConfig.authentication`](#432-authenticationinfo)\n- Agents **SHOULD** implement reasonable timeout values for webhook requests (recommended: 10-30 seconds)\n- Agents **SHOULD** implement retry logic with exponential backoff for failed deliveries\n- Agents **MAY** stop attempting delivery after a configured number of consecutive failures\n- Agents **SHOULD** validate webhook URLs to prevent SSRF (Server-Side Request Forgery) attacks:\n - Reject private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)\n - Reject localhost and link-local addresses\n - Implement URL allowlists where appropriate\n\n**Client (Webhook Receiver) Requirements:**\n\n- Clients **MUST** validate webhook authenticity using the provided authentication credentials\n- Clients **SHOULD** verify the task ID in the payload matches an expected task they created\n- Clients **MUST** respond with HTTP 2xx status codes to acknowledge successful receipt\n- Clients **SHOULD** process notifications idempotently, as duplicate deliveries may occur\n- Clients **SHOULD** implement rate limiting to prevent webhook flooding\n- Clients **SHOULD** use HTTPS endpoints for webhook URLs to ensure confidentiality\n\n**Configuration Security:**\n\n- Webhook URLs **SHOULD** use HTTPS to protect payload confidentiality in transit\n- Authentication tokens in [`PushNotificationConfig`](#431-pushnotificationconfig) **SHOULD** be treated as secrets and rotated periodically\n- Agents **SHOULD** securely store push notification configurations and credentials\n- Clients **SHOULD** use unique, single-purpose tokens for each push notification configuration\n\nSee also: [Section 4.3 Push Notification Objects](#43-push-notification-objects) and [Section 4.3.3 Push Notification Payload](#433-push-notification-payload).\n\n### 13.3. Extended Agent Card Access Control\n\nThe extended Agent Card feature allows agents to provide additional capabilities or information to authenticated clients beyond what is available in the public Agent Card.\n\n**Access Control Requirements:**\n\n- The [`Get Extended Agent Card`](#3111-get-extended-agent-card) operation **MUST** require authentication\n- Agents **MUST** authenticate requests using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields\n- Agents **MAY** return different extended card content based on the authenticated client's identity or authorization level\n- Agents **SHOULD** implement appropriate caching headers to control client-side caching of extended cards\n\n**Capability-Based Access:**\n\n- Extended cards **MAY** include additional skills not present in the public card\n- Extended cards **MAY** expose more detailed capability information (e.g., rate limits, quotas)\n- Extended cards **MAY** include organization-specific or user-specific configuration\n- Agents **SHOULD** document which capabilities are available at different authentication levels\n\n**Security Considerations:**\n\n- Extended cards **SHOULD NOT** include sensitive information that could be exploited if leaked (e.g., internal service URLs, unmasked credentials)\n- Agents **MUST** validate that clients have appropriate permissions before returning privileged information in extended cards\n- Clients retrieving extended cards **SHOULD** replace their cached public Agent Card with the extended version for the duration of their authenticated session\n- Agents **SHOULD** version extended cards appropriately and honor client cache invalidation\n\n**Availability Declaration:**\n\n- Agents declare extended card support via `AgentCard.capabilities.extendedAgentCard`\n- When `capabilities.extendedAgentCard` is `false` or not present, the operation **MUST** return [`UnsupportedOperationError`](#332-error-handling)\n- When support is declared but no extended card is configured, the operation **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling)\n\nSee also: [Section 3.1.11 Get Extended Agent Card](#3111-get-extended-agent-card) and [Section 3.3.4 Capability Validation](#334-capability-validation).\n\n### 13.4. General Security Best Practices\n\n**Transport Security:**\n\n- Production deployments **MUST** use encrypted communication (HTTPS for HTTP-based bindings, TLS for gRPC)\n- Implementations **SHOULD** use modern TLS configurations (TLS 1.3+ recommended) with strong cipher suites\n- Agents **SHOULD** enforce HSTS (HTTP Strict Transport Security) headers when using HTTP-based bindings\n- Implementations **SHOULD** disable support for deprecated SSL/TLS versions (SSLv3, TLS 1.0, TLS 1.1)\n\n**Input Validation:**\n\n- Agents **MUST** validate all input parameters before processing\n- Agents **SHOULD** implement appropriate limits on message sizes, file sizes, and request complexity\n- Agents **SHOULD** sanitize or validate file content types and reject unexpected media types\n\n**Credential Management:**\n\n- API keys, tokens, and other credentials **MUST** be treated as secrets\n- Credentials **SHOULD** be rotated periodically\n- Credentials **SHOULD** be transmitted only over encrypted connections\n- Agents **SHOULD** implement credential revocation mechanisms\n- Agents **SHOULD** log authentication failures and implement rate limiting to prevent brute-force attacks\n\n**Audit and Monitoring:**\n\n- Agents **SHOULD** log security-relevant events (authentication failures, authorization denials, suspicious requests)\n- Agents **SHOULD** implement monitoring for unusual patterns (rapid task creation, excessive cancellations)\n- Agents **SHOULD** provide audit trails for sensitive operations\n- Logs **MUST NOT** include sensitive information (credentials, personal data) unless required and properly protected\n\n**Rate Limiting and Abuse Prevention:**\n\n- Agents **SHOULD** implement rate limiting on all operations\n- Agents **SHOULD** return appropriate error responses when rate limits are exceeded\n- Agents **MAY** implement different rate limits for different operations or user tiers\n\n**Data Privacy:**\n\n- Agents **MUST** comply with applicable data protection regulations\n- Agents **SHOULD** provide mechanisms for users to request deletion of their data\n- Agents **SHOULD** implement appropriate data retention policies\n- Agents **SHOULD** minimize logging of sensitive or personal information\n\n**Custom Binding Security:**\n\n- Custom protocol bindings **MUST** address security considerations in their specification\n- Custom bindings **SHOULD** follow the same security principles as standard bindings\n- Custom bindings **MUST** document authentication integration and credential transmission\n\nSee also: [Section 12.6 Authentication and Authorization (Custom Bindings)](#126-authentication-and-authorization).\n\n## 14. IANA Considerations\n\nThis section provides registration templates for the A2A protocol's media type, HTTP headers, and well-known URI, intended for submission to the Internet Assigned Numbers Authority (IANA).\n\n### 14.1. Media Type Registration\n\n#### 14.1.1. application/a2a+json\n\n**Type name:** `application`\n\n**Subtype name:** `a2a+json`\n\n**Required parameters:** None\n\n**Optional parameters:**\n\n- None\n\n**Encoding considerations:** Binary (UTF-8 encoding MUST be used for JSON text)\n\n**Security considerations:**\nThis media type shares security considerations common to all JSON-based formats as described in RFC 8259, Section 12. Additionally:\n\n- Content MUST be validated against the A2A protocol schema before processing\n- Implementations MUST sanitize user-provided content to prevent injection attacks\n- File references within A2A messages MUST be validated to prevent server-side request forgery (SSRF)\n- Authentication and authorization MUST be enforced as specified in Section 7 of the A2A specification\n- Sensitive information in task history and artifacts MUST be protected according to applicable data protection regulations\n\n**Interoperability considerations:**\nThe A2A protocol supports multiple protocol bindings. This media type is intended for the HTTP+JSON/REST binding.\n\n**Published specification:**\nAgent2Agent (A2A) Protocol Specification, available at: \n\n{width=\"80%\"}\n\n_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._\n\n
\n\n### Example Scenario: The Auto Repair Shop\n\nConsider an auto repair shop staffed by autonomous AI agent \"mechanics\".\nThese mechanics use special-purpose tools, such as vehicle diagnostic scanners,\nrepair manuals, and platform lifts, to diagnose and repair problems. The repair\nprocess can involve extensive conversations, research, and interaction with part\nsuppliers.\n\n- **Customer Interaction (User-to-Agent using A2A)**: A customer (or their\n primary assistant agent) uses A2A to communicate with the \"Shop Manager\"\n agent.\n\n For example, the customer might say, \"My car is making a rattling noise\".\n\n- **Multi-turn Diagnostic Conversation (Agent-to-Agent using A2A)**: The Shop\n Manager agent uses A2A for a multi-turn diagnostic conversation.\n\n 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?\".\n\n- **Internal Tool Usage (Agent-to-Tool using MCP)**: The Mechanic agent,\n assigned the task by the Shop Manager, needs to diagnose the issue. The\n Mechanic agent uses MCP to interact with its specialized tools.\n\n For example:\n\n - MCP call to a \"Vehicle Diagnostic Scanner\" tool:\n `scan_vehicle_for_error_codes(vehicle_id='XYZ123')`\n - MCP call to a \"Repair Manual Database\" tool:\n `get_repair_procedure(error_code='P0300', vehicle_make='Toyota',\n vehicle_model='Camry')`\n - MCP call to a \"Platform Lift\" tool: `raise_platform(height_meters=2)`\n\n- **Supplier Interaction (Agent-to-Agent using A2A)**: The Mechanic agent\n determines that a specific part is needed. The Mechanic agent uses A2A to\n communicate with a \"Parts Supplier\" agent to order a part.\n For example, the\n Mechanic agent might ask, \"Do you have part #12345 in stock for a Toyota Camry 2018?\"\n\n- **Order processing (Agent-to-Agent using A2A)**: The Parts Supplier agent,\n which is also an A2A-compliant system, responds, potentially leading to an\n order.\n\nIn this example:\n\n- A2A facilitates the higher-level, conversational, and task-oriented\n interactions between the customer and the shop, and between the shop's\n agents and external supplier agents.\n- MCP enables the mechanic agent to use its specific, structured tools to\n perform its diagnostic and repair functions.\n\nAn A2A server could expose some of its skills as MCP-compatible resources.\nHowever, A2A's primary strength lies in its support for more flexible, stateful,\nand collaborative interactions. These interactions go beyond a typical tool\ninvocation. A2A focuses on agents partnering on tasks, whereas MCP focuses on\nagents using capabilities.\n\n## Representing A2A Agents as MCP Resources\n\nAn 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).\n\nHowever, 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.\n\nBy leveraging both A2A for inter-agent collaboration and MCP for tool integration, developers can build more powerful, flexible, and interoperable AI systems.\n"
},
{
"path": "docs/topics/agent-discovery.md",
"content": "# Agent Discovery in A2A\n\nTo 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.\n\n## The Role of the Agent Card\n\nThe 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:\n\n- **Identity:** Includes `name`, `description`, and `provider` information.\n- **Service Endpoint:** Specifies the `url` for the A2A service.\n- **A2A Capabilities:** Lists supported features such as `streaming` or `pushNotifications`.\n- **Authentication:** Details the required `schemes` (e.g., \"Bearer\", \"OAuth2\").\n- **Skills:** Describes the agent's tasks using `AgentSkill` objects, including `id`, `name`, `description`, `inputModes`, `outputModes`, and `examples`.\n\nClient agents use the Agent Card to determine an agent's suitability, structure requests, and ensure secure communication.\n\n## Discovery Strategies\n\nThe following sections detail common strategies used by client agents to discover remote Agent Cards:\n\n### 1. Well-Known URI\n\nThis approach is recommended for public agents or agents intended for broad discovery within a specific domain.\n\n- **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).\n\n- **Process:**\n 1. A client agent knows or programmatically discovers the domain of a potential A2A Server (e.g., `smart-thermostat.example.com`).\n 2. The client performs an HTTP GET request to `https://smart-thermostat.example.com/.well-known/agent-card.json`.\n 3. If the Agent Card exists and is accessible, the server returns it as a JSON response.\n\n- **Advantages:**\n - Ease of implementation\n - Adheres to standards\n - Facilitates automated discovery\n\n- **Considerations:**\n - Best suited for open or domain-controlled discovery scenarios.\n - Authentication is necessary at the endpoint serving the Agent Card if it contains sensitive details.\n\n### 2. Curated Registries (Catalog-Based Discovery)\n\nThis 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\".\n\n- **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).\n\n- **Process:**\n 1. A2A Servers publish their Agent Cards to the registry.\n 2. Client agents query the registry's API, and search by criteria such as \"specific skills\".\n 3. The registry returns matching Agent Cards or references.\n\n- **Advantages:**\n - Centralized management and governance.\n - Capability-based discovery (e.g., by skill).\n - Support for access controls and trust frameworks.\n - Applicable in both private and public marketplaces.\n- **Considerations:**\n - Requires deployment and maintenance of a registry service.\n - The current A2A specification does not prescribe a standard API for curated registries.\n\n### 3. Direct Configuration / Private Discovery\n\nThis approach is used for tightly coupled systems, private agents, or development purposes, where clients are directly configured with Agent Card information or URLs.\n\n- **Mechanism:** Client applications utilize hardcoded details, configuration files, environment variables, or proprietary APIs for discovery.\n- **Process:** The process is specific to the application's deployment and configuration strategy.\n- **Advantages:** This method is straightforward for establishing connections within known, static relationships.\n- **Considerations:**\n - Inflexible for dynamic discovery scenarios.\n - Changes to Agent Card information necessitate client reconfiguration.\n - Proprietary API-based discovery also lacks standardization.\n\n## Securing Agent Cards\n\nAgent Cards include sensitive information, such as:\n\n- URLs for internal or restricted agents.\n- Descriptions of sensitive skills.\n\n### Protection Mechanisms\n\nTo mitigate risks, the following protection mechanisms should be considered:\n\n- **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.\n- **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:\n - Mutual TLS (mTLS)\n - Network restrictions (e.g., IP ranges)\n - HTTP Authentication (e.g., OAuth 2.0)\n\n- **Registry Selective Disclosure:** Registries return different Agent Cards based on the client's identity and permissions.\n\nAny 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.\n\n## Caching Considerations\n\nAgent 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.\n\n### Server Guidance\n\nServers 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.\n\n### Client Guidance\n\nClients 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.\n\nFor Extended Agent Cards, clients should also follow the session-scoped caching guidance described in the [specification](../specification.md#133-extended-agent-card-access-control).\n\nFor normative requirements, see [Section 8.6](../specification.md#86-caching) of the specification.\n\n## Future Considerations\n\nThe A2A community explores standardizing registry interactions or advanced discovery protocols.\n"
},
{
"path": "docs/topics/enterprise-ready.md",
"content": "# Enterprise Implementation of A2A\n\nThe Agent2Agent (A2A) protocol is designed with enterprise requirements at its\ncore. Rather than inventing new, proprietary standards for security and\noperations, A2A aims to integrate seamlessly with existing enterprise\ninfrastructure and widely adopted best practices. This approach allows\norganizations to use their existing investments and expertise in security,\nmonitoring, governance, and identity management.\n\nA key principle of A2A is that agents are typically **opaque** because they don't\nshare internal memory, tools, or direct resource access with each other. This\nopacity naturally aligns with standard client-server security paradigms,\ntreating remote agents as standard HTTP-based enterprise applications.\n\n## Transport Level Security (TLS)\n\nEnsuring the confidentiality and integrity of data in transit is fundamental for\nany enterprise application.\n\n- **HTTPS Mandate**: All A2A communication in production environments must\n occur over `HTTPS`.\n- **Modern TLS Standards**: Implementations should use modern TLS versions.\n TLS 1.2 or higher is recommended. Strong, industry-standard cipher suites\n should be used to protect data from eavesdropping and tampering.\n- **Server Identity Verification**: A2A clients should verify the A2A server's\n identity by validating its TLS certificate against trusted certificate\n authorities during the TLS handshake. This prevents man-in-the-middle\n attacks.\n\n## Authentication\n\nA2A delegates authentication to standard web mechanisms. It primarily relies on\nHTTP headers and established standards like OAuth2 and OpenID Connect.\nAuthentication requirements are advertised by the A2A server in its Agent Card.\n\n- **No Identity in Payload**: A2A protocol payloads, such as `JSON-RPC`\n messages, don't carry user or client identity information directly. Identity\n is established at the transport/HTTP layer.\n- **Agent Card Declaration**: The A2A server's Agent Card describes the\n authentication schemes it supports in its `security` field and aligns with\n those defined in the OpenAPI Specification for authentication.\n- **Out-of-Band Credential Acquisition**: The A2A Client obtains the necessary credentials,\n 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.\n- **HTTP Header Transmission**: Credentials **must** be transmitted in standard\n HTTP headers as per the requirements of the chosen authentication scheme.\n Examples include `Authorization: Bearer **To make use of this agent in a multi-language, multi-agent system, check out the [weather_and_airbnb_planner sample](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/weather_and_airbnb_planner).** | Easy\n[Content Writer Agent](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/content_writer) | Build a content writer agent that generates engaging pieces of content from outlines.
**To make use of this agent in a content creation multi-language, multi-agent system, check out the [content_creation sample](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/content_creation).** | Easy\n[Content Editor Agent](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/content_editor) | Build a content editor agent that proof-reads and polishes content.
**To make use of this agent in a content creation multi-language, multi-agent system, check out the [content_creation sample](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/content_creation).** | Easy\n[Dice Agent (Multi-Transport)](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/dice_agent_multi_transport) | Build a multi-transport agent that rolls dice and checks for prime numbers. | Medium\n[Magic 8 Ball Agent (Security)](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/magic_8_ball_security) | Build a Magic 8 Ball agent to learn how to secure A2A servers with Keycloak using bearer token authentication and configure an A2A client to obtain and pass the required token. | Medium\n\n## JavaScript\n\nTutorial | Description\n:--------|:------------\n[Movie research agent using JavaScript](https://github.com/a2aproject/a2a-samples/tree/main/samples/js) | Build an A2A agent with Node.js that uses the TMDB (The Movie Database) API to handle movie searches and queries.\n\n## C#/.NET\n\nTutorial | Description\n:--------|:------------\n[All .NET samples](https://github.com/a2aproject/a2a-dotnet/tree/main/samples) | Repository of foundational samples showing how to build A2A clients and servers, including an Echo Agent, using the C#/.NET SDK.\n" }, { "path": "docs/tutorials/python/1-introduction.md", "content": "# Python Quickstart Tutorial: Building an A2A Agent\n\nWelcome to the Agent2Agent (A2A) Python Quickstart Tutorial!\n\nIn this tutorial, you will explore a simple \"echo\" A2A server using the Python SDK. This will introduce you to the fundamental concepts and components of an A2A server. You will then look at a more advanced example that integrates a Large Language Model (LLM).\n\nThis hands-on guide will help you understand:\n\n- The basic concepts behind the A2A protocol.\n- How to set up a Python environment for A2A development using the SDK.\n- How Agent Skills and Agent Cards describe an agent.\n- How an A2A server handles tasks.\n- How to interact with an A2A server using a client.\n- How streaming capabilities and multi-turn interactions work.\n- How an LLM can be integrated into an A2A agent.\n\nBy the end of this tutorial, you will have a functional understanding of A2A agents and a solid foundation for building or integrating A2A-compliant applications.\n\n## Tutorial Sections\n\nThe tutorial is broken down into the following steps:\n\n1. **[Introduction (This Page)](./1-introduction.md)**\n2. **[Setup](./2-setup.md)**: Prepare your Python environment and the A2A SDK.\n3. **[Agent Skills & Agent Card](./3-agent-skills-and-card.md)**: Define what your agent can do and how it describes itself.\n4. **[The Agent Executor](./4-agent-executor.md)**: Understand how the agent logic is implemented.\n5. **[Starting the Server](./5-start-server.md)**: Run the Helloworld A2A server.\n6. **[Interacting with the Server](./6-interact-with-server.md)**: Send requests to your agent.\n7. **[Streaming & Multi-Turn Interactions](./7-streaming-and-multiturn.md)**: Explore advanced capabilities with the LangGraph example.\n8. **[Next Steps](./8-next-steps.md)**: Explore further possibilities with A2A.\n\nLet's get started!\n" }, { "path": "docs/tutorials/python/2-setup.md", "content": "# 2. Setup Your Environment\n\n## Prerequisites\n\n- Python 3.10 or higher.\n- Access to a terminal or command prompt.\n- Git, for cloning the repository.\n- A code editor (e.g., Visual Studio Code) is recommended.\n\n## Clone the Repository\n\nIf you haven't already, clone the A2A Samples repository:\n\n```bash\ngit clone https://github.com/a2aproject/a2a-samples.git -b main --depth 1\ncd a2a-samples\n```\n\n## Python Environment & SDK Installation\n\nWe recommend using a virtual environment for Python projects. The A2A Python SDK uses `uv` for dependency management, but you can use `pip` with `venv` as well.\n\n1. **Create and activate a virtual environment:**\n\n Using `venv` (standard library):\n\n === \"Mac/Linux\"\n\n ```sh\n python -m venv .venv\n source .venv/bin/activate\n ```\n\n === \"Windows\"\n\n ```powershell\n python -m venv .venv\n .venv\\Scripts\\activate\n ```\n\n2. **Install needed Python dependencies along with the A2A SDK and its dependencies:**\n\n ```bash\n pip install -r samples/python/requirements.txt\n ```\n\n## Verify Installation\n\nAfter installation, you should be able to import the `a2a` package in a Python interpreter:\n\n```bash\npython -c \"import a2a; print('A2A SDK imported successfully')\"\n```\n\nIf this command runs without error and prints the success message, your environment is set up correctly.\n" }, { "path": "docs/tutorials/python/3-agent-skills-and-card.md", "content": "# 3. Agent Skills & Agent Card\n\nBefore an A2A agent can do anything, it needs to define what it _can_ do (its skills) and how other agents or clients can find out about these capabilities (its Agent Card).\n\nWe'll use the `helloworld` example located in [`a2a-samples/samples/python/agents/helloworld/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/helloworld).\n\n## Agent Skills\n\nAn **Agent Skill** describes a specific capability or function the agent can perform. It's a building block that tells clients what kinds of tasks the agent is good for.\n\nKey attributes of an `AgentSkill` (defined in `a2a.types`):\n\n- `id`: A unique identifier for the skill.\n- `name`: A human-readable name.\n- `description`: A more detailed explanation of what the skill does.\n- `tags`: Keywords for categorization and discovery.\n- `examples`: Sample prompts or use cases.\n- `inputModes` / `outputModes`: Supported Media Types for input and output (e.g., \"text/plain\", \"application/json\").\n\nIn `__main__.py`, you can see how a skill for the Helloworld agent is defined:\n\n```python { .no-copy }\n--8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentSkill\"\n```\n\nThis skill is very simple: it's named \"Returns hello world\" and primarily deals with text.\n\n## Agent Card\n\nThe **Agent Card** is a JSON document that an A2A Server makes available, typically at a `.well-known/agent-card.json` endpoint. It's like a digital business card for the agent.\n\nKey attributes of an `AgentCard` (defined in `a2a.types`):\n\n- `name`, `description`, `version`: Basic identity information.\n- `url`: The endpoint where the A2A service can be reached.\n- `capabilities`: Specifies supported A2A features like `streaming` or `pushNotifications`.\n- `defaultInputModes` / `defaultOutputModes`: Default Media Types for the agent.\n- `skills`: A list of `AgentSkill` objects that the agent offers.\n\nThe `helloworld` example defines its Agent Card like this:\n\n```python { .no-copy }\n--8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentCard\"\n```\n\nThis card tells us the agent is named \"Hello World Agent\", runs at `http://localhost:9999/`, supports text interactions, and has the `hello_world` skill. It also indicates public authentication, meaning no specific credentials are required.\n\nUnderstanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it.\n" }, { "path": "docs/tutorials/python/4-agent-executor.md", "content": "# 4. The Agent Executor\n\nThe core logic of how an A2A agent processes requests and generates responses/events is handled by an **Agent Executor**. The A2A Python SDK provides an abstract base class `a2a.server.agent_execution.AgentExecutor` that you implement.\n\n## `AgentExecutor` Interface\n\nThe `AgentExecutor` class defines two primary methods:\n\n- `async def execute(self, context: RequestContext, event_queue: EventQueue)`: Handles incoming requests that expect a response or a stream of events. It processes the user's input (available via `context`) and uses the `event_queue` to send back `Message`, `Task`, `TaskStatusUpdateEvent`, or `TaskArtifactUpdateEvent` objects.\n- `async def cancel(self, context: RequestContext, event_queue: EventQueue)`: Handles requests to cancel an ongoing task.\n\nThe `RequestContext` provides information about the incoming request, such as the user's message and any existing task details. The `EventQueue` is used by the executor to send events back to the client.\n\n## Helloworld Agent Executor\n\nLet's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.\n\n1. **The Agent (`HelloWorldAgent`)**:\n This is a simple helper class that encapsulates the actual \"business logic\".\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent\"\n ```\n\n It has a simple `invoke` method that returns the string \"Hello World\".\n\n2. **The Executor (`HelloWorldAgentExecutor`)**:\n This class implements the `AgentExecutor` interface.\n\n - **`__init__`**:\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_init\"\n ```\n\n It instantiates the `HelloWorldAgent`.\n\n - **`execute`**:\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute\"\n ```\n\n When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor):\n\n 1. It calls `self.agent.invoke()` to get the \"Hello World\" string.\n 2. It creates an A2A `Message` object using the `new_agent_text_message` utility function.\n 3. It enqueues this message onto the `event_queue`. The underlying `DefaultRequestHandler` will then process this queue to send the response(s) to the client. For a single message like this, it will result in a single response for `message/send` or a single event for `message/stream` before the stream closes.\n\n - **`cancel`**:\n The Hello World example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent.\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel\"\n ```\n\nThe `AgentExecutor` acts as the bridge between the A2A protocol (managed by the request handler and server application) and your agent's specific logic. It receives context about the request and uses an event queue to communicate results or updates back.\n" }, { "path": "docs/tutorials/python/5-start-server.md", "content": "# 5. Starting the Server\n\nNow that we have an Agent Card and an Agent Executor, we can set up and start the A2A server.\n\nThe A2A Python SDK provides an `A2AStarletteApplication` class that simplifies running an A2A-compliant HTTP server. It uses [Starlette](https://www.starlette.io/) for the web framework and is typically run with an ASGI server like [Uvicorn](https://www.uvicorn.org/).\n\n## Server Setup in Helloworld\n\nLet's look at `__main__.py` again to see how the server is initialized and started.\n\n```python { .no-copy }\n--8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py\"\n```\n\nLet's break this down:\n\n1. **`DefaultRequestHandler`**:\n\n - The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`).\n - It routes incoming A2A RPC calls to the appropriate methods on your executor (like `execute` or `cancel`).\n - The `TaskStore` is used by the `DefaultRequestHandler` to manage the lifecycle of tasks, especially for stateful interactions, streaming, and resubscription. Even if your agent executor is simple, the handler needs a task store.\n\n2. **`A2AStarletteApplication`**:\n\n - The `A2AStarletteApplication` class is instantiated with the `agent_card` and the `request_handler` (referred to as `http_handler` in its constructor).\n - The `agent_card` is crucial because the server will expose it at the `/.well-known/agent-card.json` endpoint (by default).\n - The `request_handler` is responsible for processing all incoming A2A method calls by interacting with your `AgentExecutor`.\n\n3. **`uvicorn.run(server_app_builder.build(), ...)`**:\n - The `A2AStarletteApplication` has a `build()` method that constructs the actual Starlette application.\n - This application is then run using `uvicorn.run()`, making your agent accessible over HTTP.\n - `host='0.0.0.0'` makes the server accessible on all network interfaces on your machine.\n - `port=9999` specifies the port to listen on. This matches the `url` in the `AgentCard`.\n\n## Running the Helloworld Server\n\nNavigate to the `a2a-samples` directory in your terminal (if you're not already there) and ensure your virtual environment is activated.\n\nTo run the Helloworld server:\n\n```bash\n# from the a2a-samples directory\npython samples/python/agents/helloworld/__main__.py\n```\n\nYou should see output similar to this, indicating the server is running:\n\n```console { .no-copy }\nINFO: Started server process [xxxxx]\nINFO: Waiting for application startup.\nINFO: Application startup complete.\nINFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)\n```\n\nYour A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it.\n" }, { "path": "docs/tutorials/python/6-interact-with-server.md", "content": "# 6. Interacting with the Server\n\nWith the Helloworld A2A server running, let's send some requests to it. The SDK includes a client (`A2AClient`) that simplifies these interactions.\n\n## The Helloworld Test Client\n\nThe `test_client.py` script demonstrates how to:\n\n1. Fetch the Agent Card from the server.\n2. Create an `A2AClient` instance.\n3. Send both non-streaming (`message/send`) and streaming (`message/stream`) requests.\n\nOpen a **new terminal window**, activate your virtual environment, and navigate to the `a2a-samples` directory.\n\nActivate virtual environment (Be sure to do this in the same directory where you created the virtual environment):\n\n=== \"Mac/Linux\"\n\n ```sh\n source .venv/bin/activate\n ```\n\n=== \"Windows\"\n\n ```powershell\n .venv\\Scripts\\activate\n ```\n\nRun the test client:\n\n```bash\n# from the a2a-samples directory\npython samples/python/agents/helloworld/test_client.py\n```\n\n## Understanding the Client Code\n\nLet's look at key parts of `test_client.py`:\n\n1. **Fetching the Agent Card & Initializing the Client**:\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver\"\n ```\n\n The `A2ACardResolver` class is a convenience. It first fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL) and then initializes the client with it.\n\n2. **Sending a Non-Streaming Message (`send_message`)**:\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message\"\n ```\n\n - The `send_message_payload` constructs the data for `MessageSendParams`.\n - This is wrapped in a `SendMessageRequest`.\n - It includes a `message` object with the `role` set to \"user\" and the content in `parts`.\n - The Helloworld agent's `execute` method will enqueue a single \"Hello World\" message. The `DefaultRequestHandler` will retrieve this and send it as the response.\n - The `response` will be a `SendMessageResponse` object, which contains either a `SendMessageSuccessResponse` (with the agent's `Message` as the result) or a `JSONRPCErrorResponse`.\n\n3. **Handling Task IDs (Illustrative Note for Helloworld)**:\n\n The Helloworld client (`test_client.py`) doesn't attempt `get_task` or `cancel_task` directly because the simple Helloworld agent's `execute` method, when called via `message/send`, results in the `DefaultRequestHandler` returning a direct `Message` response rather than a `Task` object. More complex agents that explicitly manage tasks (like the LangGraph example) would return a `Task` object from `message/send`, and its `id` could then be used for `get_task` or `cancel_task`.\n\n4. **Sending a Streaming Message (`send_message_streaming`)**:\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming\"\n ```\n\n - This method calls the agent's `message/stream` endpoint. The `DefaultRequestHandler` will invoke the `HelloWorldAgentExecutor.execute` method.\n - The `execute` method enqueues one \"Hello World\" message, and then the event queue is closed.\n - The client will receive this single message as one `SendStreamingMessageResponse` event, and then the stream will terminate.\n - The `stream_response` is an `AsyncGenerator`.\n\n## Expected Output\n\nWhen you run `test_client.py`, you'll see JSON outputs for:\n\n- The non-streaming response (a single \"Hello World\" message).\n- The streaming response (a single \"Hello World\" message as one chunk, after which the stream ends).\n\nThe `id` fields in the output will vary with each run.\n\n```console { .no-copy }\n// Non-streaming response\n{\"jsonrpc\":\"2.0\",\"id\":\"xxxxxxxx\",\"result\":{\"message\":{\"role\":\"ROLE_AGENT\",\"parts\":[{\"text\":\"Hello World\"}],\"messageId\":\"yyyyyyyy\"}}}\n// Streaming response (one chunk)\n{\"jsonrpc\":\"2.0\",\"id\":\"zzzzzzzz\",\"result\":{\"message\":{\"role\":\"ROLE_AGENT\",\"parts\":[{\"text\":\"Hello World\"}],\"messageId\":\"wwwwwwww\"}}}\n```\n\n_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww` will be different UUIDs/request IDs)_\n\nThis confirms your server is correctly handling basic A2A interactions with the updated SDK structure!\n\nNow you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.\n" }, { "path": "docs/tutorials/python/7-streaming-and-multiturn.md", "content": "# 7. Streaming & Multi-Turn Interactions (LangGraph Example)\n\nThe Hello World example demonstrates the basic mechanics of A2A. For more advanced features like robust streaming, task state management, and multi-turn conversations powered by an LLM, we'll turn to the LangGraph example located in [`a2a-samples/samples/python/agents/langgraph/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/langgraph).\n\nThis example features a \"Currency Agent\" that uses the Gemini model via LangChain and LangGraph to answer currency conversion questions.\n\n## Setting up the LangGraph Example\n\n1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one.\n\n2. **Environment Variable:**\n\n Create a `.env` file in the `a2a-samples/samples/python/agents/langgraph/` directory:\n\n ```bash\n echo \"GOOGLE_API_KEY=YOUR_API_KEY_HERE\" > .env\n ```\n\n Replace `YOUR_API_KEY_HERE` with your actual Gemini API key.\n\n3. **Install Dependencies (if not already covered):**\n\n The `langgraph` example has its own `pyproject.toml` which includes dependencies like `langchain-google-genai` and `langgraph`. When you installed the SDK from the `a2a-samples` root using `pip install -e .[dev]`, this should have also installed the dependencies for the workspace examples, including `langgraph-example`. If you encounter import errors, ensure your primary SDK installation from the root directory was successful.\n\n## Running the LangGraph Server\n\nNavigate to the `a2a-samples/samples/python/agents/langgraph/app` directory in your terminal and ensure your virtual environment (from the SDK root) is activated.\n\nStart the LangGraph agent server:\n\n```bash\npython __main__.py\n```\n\nThis will start the server, usually on `http://localhost:10000`.\n\n## Interacting with the LangGraph Agent\n\nOpen a **new terminal window**, activate your virtual environment, and navigate to `a2a-samples/samples/python/agents/langgraph/app`.\n\nRun its test client:\n\n```bash\npython test_client.py\n```\n\nNow, you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.\n\n## Key Features Demonstrated\n\nThe `langgraph` example showcases several important A2A concepts:\n\n1. **LLM Integration**:\n\n - `agent.py` defines `CurrencyAgent`. It uses `ChatGoogleGenerativeAI` and LangGraph's `create_react_agent` to process user queries.\n - This demonstrates how a real LLM can power the agent's logic.\n\n2. **Task State Management**:\n\n - `samples/langgraph/__main__.py` initializes a `DefaultRequestHandler` with an `InMemoryTaskStore`.\n\n ```python { .no-copy }\n --8<-- \"https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/langgraph/app/__main__.py:DefaultRequestHandler\"\n ```\n\n - The `CurrencyAgentExecutor` (in `samples/langgraph/agent_executor.py`), when its `execute` method is called by the `DefaultRequestHandler`, interacts with the `RequestContext` which contains the current task (if any).\n - For `message/send`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `message/send` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.\n - The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`.\n\n3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**:\n\n - The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`.\n - As the LangGraph agent processes the request (which might involve calling tools like `get_exchange_rate`), the `CurrencyAgentExecutor` enqueues different types of events onto the `EventQueue`:\n - `TaskStatusUpdateEvent`: For intermediate updates (e.g., \"Looking up exchange rates...\", \"Processing the exchange rates..\").\n - `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`.\n - A final `TaskStatusUpdateEvent` with `state=TaskState.completed` is sent to signify the end of the task, closing the stream.\n - The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server.\n\n4. **Multi-Turn Conversation (`TaskState.input_required`)**:\n\n - The `CurrencyAgent` can ask for clarification if a query is ambiguous (e.g., user asks \"how much is 100 USD?\").\n - When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., \"To which currency would you like to convert?\"). The stream closes after this event.\n - The `test_client.py`'s `run_multi_turn_test` function demonstrates this:\n - It sends an initial ambiguous query.\n - The agent responds (via the `DefaultRequestHandler` processing the enqueued events) with a `Task` whose status is `input_required`.\n - The client then sends a second message, including the `taskId` and `contextId` from the first turn's `Task` response, to provide the missing information (\"in GBP\"). This continues the same task.\n\n## Exploring the Code\n\nTake some time to look through these files:\n\n- `__main__.py`: Server setup using `A2AStarletteApplication` and `DefaultRequestHandler`. Note the `AgentCard` definition includes `capabilities.streaming=True`.\n- `agent.py`: The `CurrencyAgent` with LangGraph, LLM model, and tool definitions.\n- `agent_executor.py`: The `CurrencyAgentExecutor` implementing the `execute` (and `cancel`) method. It uses the `RequestContext` to understand the ongoing task and the `EventQueue` to send back various events (`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`, new `Task` object implicitly via the first event if no task exists).\n- `test_client.py`: Demonstrates various interaction patterns, including retrieving task IDs and using them for multi-turn conversations.\n\nThis example provides a much richer illustration of how A2A facilitates complex, stateful, and asynchronous interactions between agents.\n" }, { "path": "docs/tutorials/python/8-next-steps.md", "content": "# Next Steps\n\nCongratulations on completing the A2A Python SDK Tutorial! You've learned how to:\n\n- Set up your environment for A2A development.\n- Define Agent Skills and Agent Cards using the SDK's types.\n- Implement a basic HelloWorld A2A server and client.\n- Understand and implement streaming capabilities.\n- Integrate a more complex agent using LangGraph, demonstrating task state management and tool use.\n\nYou now have a solid foundation for building and integrating your own A2A-compliant agents.\n\n## Where to Go From Here?\n\nHere are some ideas and resources to continue your A2A journey:\n\n- **Explore Other Examples:**\n - Check out the other examples in the [a2a-samples GitHub repository](https://github.com/a2aproject/a2a-samples/tree/main/samples) for more complex agent integrations and features.\n- **Deepen Your Protocol Understanding:**\n - 📚 Read the complete [A2A Protocol Documentation site](https://a2a-protocol.org) for a comprehensive overview.\n - 📝 Review the detailed [A2A Protocol Specification](../../specification.md) to understand the nuances of all data structures and RPC methods.\n- **Review Key A2A Topics:**\n - [A2A and MCP](../../topics/a2a-and-mcp.md): Understand how A2A complements the Model Context Protocol for tool usage.\n - [Enterprise-Ready Features](../../topics/enterprise-ready.md): Learn about security, observability, and other enterprise considerations.\n - [Streaming & Asynchronous Operations](../../topics/streaming-and-async.md): Get more details on SSE and push notifications.\n - [Agent Discovery](../../topics/agent-discovery.md): Explore different ways agents can find each other.\n- **Build Your Own Agent:**\n - Try creating a new A2A agent using your favorite Python agent framework (like LangChain, CrewAI, AutoGen, Semantic Kernel, or a custom solution).\n - Implement the `a2a.server.AgentExecutor` interface to bridge your agent's logic with the A2A protocol.\n - Think about what unique skills your agent could offer and how its Agent Card would represent them.\n- **Experiment with Advanced Features:**\n - Implement robust task management with a persistent `TaskStore` if your agent handles long-running or multi-session tasks.\n - Explore implementing push notifications if your agent's tasks are very long-lived.\n - Consider more complex input and output modalities (e.g., handling file uploads/downloads via file Parts, or structured data via data Parts).\n- **Contribute to the A2A Community:**\n - Join the discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).\n - Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).\n - Consider contributing code, examples, or documentation. See the [CONTRIBUTING.md](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md) guide.\n\nThe A2A protocol aims to foster an ecosystem of interoperable AI agents. By building and sharing A2A-compliant agents, you can be a part of this exciting development!\n" }, { "path": "docs/whats-new-v1.md", "content": "# What's New in A2A Protocol v1.0\n\nThis document provides a comprehensive overview of changes from A2A Protocol v0.3.0 to v1.0. The v1.0 release represents a significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.\n\n## Overview of Major Themes\n\nThe v1.0 release focuses on four major themes:\n\n### 1. **Protocol Maturity and Standardization**\n\n- Elevate a2a.proto from being a gRPC-specific implementation file to the universal, normative source of truth\n- Leverage formal specification standards (RFC 8785, RFC 7515) and google.rpc.Status where possible\n- Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings\n- Enhanced versioning strategy with explicit backward compatibility rules\n- Comprehensive error taxonomy with protocol-specific mappings\n\n### 2. **Enhanced Type Safety and Clarity**\n\n- Removal of discriminator `kind` fields in favor of JSON member-based polymorphism\n- **Breaking:** Enum values changed from `kebab-case` to `SCREAMING_SNAKE_CASE` for compliance with the ProtoJSON specification\n- Stricter field naming conventions (`camelCase` for JSON)\n- More precise timestamp specifications (ISO 8601 with millisecond precision)\n- Better-defined data types with clearer Optional vs Required semantics\n\n### 3. **Improved Developer Experience**\n\n- Renamed operations for consistency and clarity\n- Reorganized Agent Card structure for better logical grouping\n- Enhanced extension mechanism with versioning and requirement declarations\n- More explicit service parameter handling (A2A-Version, A2A-Extensions headers)\n- **Simplified ID format** - Removed complex compound IDs (e.g., `tasks/{id}`) in favor of simple UUIDs\n- **Protocol versioning per interface** - Each AgentInterface specifies its own protocol version for better backward compatibility\n- **Multi-tenancy support** - Native tenant scoping in gRPC requests\n\n### 4. **Enterprise-Ready Features**\n\n- Agent Card signature verification using JWS and JSON Canonicalization\n- Formal specification of all three protocol bindings with equivalence guarantees\n- Enhanced security scheme declarations with mutual TLS support\n- **Modern OAuth 2.0 flows** - Added Device Code flow (RFC 8628), removed deprecated implicit/password flows\n- **PKCE support** - Added `pkce_required` field to Authorization Code flow for enhanced security\n- Cursor-based pagination for scalable task listing\n\n---\n\n## Behavioral Changes for Core Operations\n\n### Send Message (`message/send` → **`SendMessage`**)\n\n**v0.3.0 Behavior:**\n\n- Operation named `message/send`\n- Less formal specification of when `Task` vs `Message` is returned\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** Operation now **`SendMessage`**\n- **✅ CLARIFIED:** More precise specification of Task vs Message return semantics\n\n### Send Streaming Message (`message/stream` → **SendStreamingMessage**)\n\n**v0.3.0 Behavior:**\n\n- Operation named `message/stream`\n- Stream events had `kind` discriminator field\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** Operation now **`SendStreamingMessage`**\n- **✅ BREAKING:** Stream events no longer have `kind` field\n - Use JSON member names to discriminate between `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`\n- **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.\n- **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events\n\n### Get Task (`tasks/get` → **GetTask**)\n\n**v0.3.0 Behavior:**\n\n- Operation named `tasks/get`\n- Returns task with status, artifacts, and optionally history\n- Less formal specification of what \"include history\" means\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** Operation now **GetTask**\n- **✅ NEW:** `createdAt` and `lastModified` timestamp fields added to Task object\n- **✅ CLARIFIED:** More precise specification of history inclusion behavior\n- **✅ NEW:** Task object now includes `extensions[]` array in messages and artifacts\n- **✅ CLARIFIED:** Authentication/authorization scoping - servers MUST only return tasks visible to caller\n\n### List Tasks (`tasks/list` → **ListTasks**)\n\n**v0.3.0 Behavior:**\n\n- Operation unavailable.\n\n**v1.0 Changes:**\n\n- **✅ NEW:** New operation **ListTasks** with filtering capabilities\n- **✅ CLARIFIED:** Task visibility scoped to authenticated caller\n\n### Cancel Task (`tasks/cancel` → **CancelTask**)\n\n**v0.3.0 Behavior:**\n\n- Operation named `tasks/cancel`\n- Request with taskId, returns Task\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** Operation now **CancelTask**\n- **✅ CLARIFIED:** More precise specification of when cancellation is allowed\n- **✅ CLARIFIED:** Task state transitions for cancellation scenarios\n\n### Get Agent Card (Well-known URI and **GetExtendedAgentCard**)\n\n**v0.3.0 Behavior:**\n\n- Discovery via `/.well-known/agent-card.json`\n- Extended card via `agent/getAuthenticatedExtendedCard`\n- `supportsAuthenticatedExtendedCard` boolean at top level\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** `agent/getAuthenticatedExtendedCard` → **GetExtendedAgentCard**\n- **✅ BREAKING:** `supportsAuthenticatedExtendedCard` moved to `capabilities.extendedAgentCard`\n- **✅ NEW:** Canonicalization (RFC 8785) clarified for Agent Card signature\n- **✅ BREAKING:** `protocolVersion` moved from AgentCard to individual AgentInterface objects\n- **✅ BREAKING:** `preferredTransport` and `additionalInterfaces` consolidated into `supportedInterfaces[]`\n - Each interface has `url`, `protocolBinding`, and `protocolVersion`\n\n### Subscribe to task (`tasks/resubscribe` → **SubscribeToTask**)\n\n**v0.3.0 Behavior:**\n\n- Used `tasks/resubscribe` to reconnect interrupted SSE streams\n- Backfill behavior implementation-dependent\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** Operation now **SubscribeToTask**\n- **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle\n- **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state\n- **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task\n\n### Push Notification Operations\n\n**v0.3.0 Operations:**\n\n- `tasks/pushNotificationConfig/set`\n- `tasks/pushNotificationConfig/get`\n- `tasks/pushNotificationConfig/list`\n- `tasks/pushNotificationConfig/delete`\n\n**v1.0 Changes:**\n\n- **✅ RENAMED:** Operations now **CreateTaskPushNotificationConfig**, **GetTaskPushNotificationConfig**, **ListTaskPushNotificationConfigs**, **DeleteTaskPushNotificationConfig**\n- **✅ NEW:** `createdAt` timestamp field added to PushNotificationConfig\n- **✅ CLARIFIED:** Push notification payloads now use StreamResponse format\n- **✅ BREAKING:** model changed for all methods, with TaskPushNotificationConfig flattened\n\n### NEW: Multi-Tenancy Support\n\n**v0.3.0:**\n\n- No native multi-tenancy support in protocol\n- Tenants handled implicitly via authentication or URL paths\n\n**v1.0 Changes:**\n\n- **✅ NEW:** `tenant` field added to all request messages\n- **✅ NEW:** `tenant` field added to `AgentInterface` to specify default tenant\n- **✅ CLARIFIED:** Tenant provided per-request, inherited from AgentInterface\n- **✅ USE CASE:** Enables to serve multiple agents from a single endpoint\n\n### Protocol Simplifications\n\n#### ID Format Simplification (#1389)\n\n**v0.3.0:**\n\n- Some operations used complex compound IDs like `tasks/{taskId}`\n- Required clients/servers to construct/deconstruct resource names\n\n**v1.0 Changes:**\n\n- **✅ BREAKING:** All IDs are now simple literals\n- **✅ BREAKING:** Operations that previously used compound IDs now separate parent and resource ID\n - Example: `tasks/{taskId}/pushNotificationConfigs/{configId}` → separate `task_id` and `config_id` fields\n- **✅ BENEFIT:** Simpler to implement - IDs map directly to database keys\n\n#### HTTP URL Path Simplification (#1269)\n\n**v0.3.0:**\n\n- HTTP+JSON binding used `/v1/` prefix in URLs\n- Example: `POST /v1/message:send`\n\n**v1.0 Changes:**\n\n- **✅ BREAKING:** Removed `/v1` prefix from HTTP+JSON URL paths\n- **✅ NEW:** Examples: `POST /message:send`, `GET /tasks/{id}`\n- **✅ RATIONALE:** Version can be part of the base url if required by agent owner\n- **✅ BENEFIT:** Cleaner URLs, version management at interface level\n\n---\n\n## Structural Changes in Core Model Objects\n\n### TaskStatus Object\n\n**Modified Fields:**\n\n- ✅ `state`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix\n - v0.3.0: `\"submitted\"`, `\"working\"`, `\"completed\"`, `\"failed\"`, `\"canceled\"`, `\"rejected\"`, `\"input-required\"`, `\"auth-required\"`\n - v1.0: `\"TASK_STATE_SUBMITTED\"`, `\"TASK_STATE_WORKING\"`, `\"TASK_STATE_COMPLETED\"`, `\"TASK_STATE_FAILED\"`, `\"TASK_STATE_CANCELED\"`, `\"TASK_STATE_REJECTED\"`, `\"TASK_STATE_INPUT_REQUIRED\"`, `\"TASK_STATE_AUTH_REQUIRED\"`\n- ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)\n\n**Removed Fields:**\n\n- None\n\n**Example Migration:**\n\n```json\n// v0.3.0\n{\n \"status\": {\n \"state\": \"completed\",\n \"timestamp\": \"2024-03-15T10:15:00Z\"\n }\n}\n\n// v1.0\n{\n \"status\": {\n \"state\": \"TASK_STATE_COMPLETED\",\n \"timestamp\": \"2024-03-15T10:15:00.000Z\"\n }\n}\n```\n\n### Message Object\n\n**Added Fields:**\n\n- ✅ `extensions[]`: Array of extension URIs applicable to this message\n\n**Modified Fields:**\n\n- ✅ `role`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `ROLE_` prefix\n - v0.3.0: `\"user\"`, `\"agent\"`\n - v1.0: `\"ROLE_USER\"`, `\"ROLE_AGENT\"`\n\n**Example Migration:**\n\n```json\n// v0.3.0\n{\n \"role\": \"user\",\n \"parts\": [{\"kind\": \"text\", \"text\": \"Hello\"}]\n}\n\n// v1.0\n{\n \"role\": \"ROLE_USER\",\n \"parts\": [{\"text\": \"Hello\"}],\n}\n```\n\n**Behavior Changes:**\n\n- Parts array now uses member-based discrimination instead of `kind` field\n\n### Part Object\n\n**BREAKING CHANGE - Complete Redesign:**\n\nThe Part structure has been completely redesigned in v1.0. Instead of separate TextPart, FilePart, and DataPart message types, there is now a single unified `Part` message.\n\n**v0.3.0 Structure (Separate Types):**\n\n```json\n// Text example\n{\n \"kind\": \"text\",\n \"text\": \"Hello world\"\n}\n\n// File example\n{\n \"kind\": \"file\",\n \"file\": {\n \"fileWithUri\": \"https://example.com/doc.pdf\",\n \"mimeType\": \"application/pdf\"\n }\n}\n\n// Data example\n{\n \"kind\": \"data\",\n \"data\": {\"key\": \"value\"}\n}\n```\n\n**v1.0 Structure (Unified Part):**\n\n```json\n// Text example\n{\n \"text\": \"Hello world\",\n \"mediaType\": \"text/plain\"\n}\n\n// File with URL example\n{\n \"url\": \"https://example.com/doc.pdf\",\n \"filename\": \"doc.pdf\",\n \"mediaType\": \"application/pdf\"\n}\n\n// File with raw bytes example\n{\n \"raw\": \"base64encodedcontent==\",\n \"filename\": \"image.png\",\n \"mediaType\": \"image/png\"\n}\n\n// Data example\n{\n \"data\": {\"key\": \"value\"},\n \"mediaType\": \"application/json\"\n}\n```\n\n**Changes:**\n\n- ⛔ **REMOVED:** Separate `TextPart`, `FilePart`, and `DataPart` types\n- ⛔ **REMOVED:** `kind` discriminator field\n- ⛔ **REMOVED:** Nested `file` object structure\n- ✅ **NEW:** Single unified `Part` message with `oneof content` field\n- ✅ **NEW:** Content type determined by which field is present: `text`, `raw`, `url`, or `data`\n- ✅ **NEW:** `mediaType` field (replaces `mimeType`) - available for all part types\n- ✅ **NEW:** `filename` field - available for all part types (not just files)\n- ✅ **NEW:** `raw` field for inline binary content (base64 in JSON)\n- ✅ **NEW:** `url` field for file references (replaces `file.fileWithUri`)\n\n**Migration Examples:**\n\n```typescript\n// v0.3.0\nconst textPart = { kind: \"text\", text: \"Hello\" };\nconst filePart = { kind: \"file\", file: { fileWithUri: \"https://...\", mimeType: \"image/png\" } };\nconst dataPart = { kind: \"data\", data: { key: \"value\" } };\n\n// v1.0\nconst textPart = { text: \"Hello\", mediaType: \"text/plain\" };\nconst filePart = { url: \"https://...\", mediaType: \"image/png\", filename: \"image.png\" };\nconst dataPart = { data: { key: \"value\" }, mediaType: \"application/json\" };\n\n// Discrimination changed from kind field to member presence\nif (part.kind === \"text\") { ... } // v0.3.0\nif (\"text\" in part) { ... } // v1.0\n```\n\n### Artifact Object\n\n**Added Fields:**\n\n- ✅ `extensions[]`: Array of extension URIs\n\n**Modified Fields:**\n\n- ✅ `parts[]`: Now uses member-based Part discrimination (see Part changes above)\n\n### AgentCard Object\n\n**Added Fields:**\n\n- ✅ `supportedInterfaces[]`: Array of `AgentInterface` objects\n\n**Removed Fields:**\n\n- ⛔ `protocolVersion`: Removed from AgentCard (now in each AgentInterface)\n- ⛔ `preferredTransport`: Consolidated into `supportedInterfaces`\n- ⛔ `additionalInterfaces`: Consolidated into `supportedInterfaces`\n- ⛔ `supportsAuthenticatedExtendedCard`: Moved to `capabilities.extendedAgentCard`\n- ⛔ `url`: Primary endpoint now in `supportedInterfaces[0].url`\n\n**Structure Example:**\n\n**v0.3.0:**\n\n```json\n{\n \"protocolVersion\": \"0.3\",\n \"url\": \"https://agent.example.com/a2a\",\n \"preferredTransport\": \"JSONRPC\",\n \"supportsAuthenticatedExtendedCard\": true,\n \"additionalInterfaces\": [...]\n}\n```\n\n**v1.0:**\n\n```json\n{\n \"supportedInterfaces\": [\n {\n \"url\": \"https://agent.example.com/a2a\",\n \"protocolBinding\": \"JSONRPC\",\n \"protocolVersion\": \"1.0\"\n }\n ],\n \"capabilities\": {\n \"extendedAgentCard\": true\n },\n \"signatures\": [...]\n}\n```\n\n### AgentCapabilities Object\n\n**Modified Fields:**\n\n- ✅ `extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard` field\n\n### PushNotificationConfig Object\n\n**Added Fields:**\n\n- ✅ `configId`: Unique identifier for the configuration\n- ✅ `createdAt`: Timestamp - Configuration creation time\n\n**Modified Fields:**\n\n- ✅ `authentication`: Enhanced PushNotificationAuthenticationInfo structure\n\n### Stream Event Objects\n\n**TaskStatusUpdateEvent:**\n\n**v0.3.0:**\n\n```json\n{\n \"kind\": \"taskStatusUpdate\",\n \"taskId\": \"...\",\n \"contextId\": \"...\",\n \"status\": {...},\n \"final\": true\n}\n```\n\n**v1.0:**\n\n```json\n{\n \"taskStatusUpdate\": {\n \"taskId\": \"...\",\n \"contextId\": \"...\",\n \"status\": {...}\n }\n}\n```\n\n**Changes:**\n\n- ⛔ **REMOVED:** `kind` discriminator\n- ⛔ **REMOVED:** `final` boolean field (stream closure indicates completion instead)\n- ✅ **NEW PATTERN:** Event type determined by JSON member name (`taskStatusUpdate` or `taskArtifactUpdate`)\n- ✅ **CLARIFIED:** Terminal state indicated by protocol-specific stream closure mechanism\n\n**TaskArtifactUpdateEvent:**\n\n**v0.3.0:**\n\n```json\n{\n \"kind\": \"taskArtifactUpdate\",\n \"taskId\": \"...\",\n \"contextId\": \"...\",\n \"artifact\": {...}\n}\n```\n\n**v1.0:**\n\n```json\n{\n \"taskArtifactUpdate\": {\n \"taskId\": \"...\",\n \"contextId\": \"...\",\n \"artifact\": {...},\n \"index\": 0\n }\n}\n```\n\n**Changes:**\n\n- ⛔ **REMOVED:** `kind` discriminator\n- ✅ **NEW PATTERN:** Wrapped in `taskArtifactUpdate` object\n- ✅ **NEW:** `index` field indicates artifact position in task's artifacts array\n\n### OAuth 2.0 Security Updates (#1303)\n\nv1.0 modernizes OAuth 2.0 support in alignment with OAuth 2.0 Security Best Current Practice (BCP).\n\n**Removed Flows (Deprecated by OAuth BCP):**\n\n- ⛔ `ImplicitOAuthFlow` - Deprecated due to token leakage risks in browser history/logs\n- ⛔ `PasswordOAuthFlow` - Deprecated due to credential exposure risks\n\n**Added Flows:**\n\n- ✅ `DeviceCodeOAuthFlow` (RFC 8628) - For CLI tools, IoT devices, and input-constrained scenarios\n - Provides `device_authorization_url` endpoint\n - Supports `verification_uri`, `user_code` pattern\n - Ideal for headless environments\n\n**Enhanced Security:**\n\n- ✅ `pkce_required` field added to `AuthorizationCodeOAuthFlow` (RFC 7636)\n - Indicates whether PKCE (Proof Key for Code Exchange) is mandatory\n - Protects against authorization code interception attacks\n - Recommended for all OAuth clients, required for public clients\n\n**Migration Guide:**\n\n```typescript\n// v0.3.0 - Implicit Flow (now removed)\n{\n \"implicitFlow\": {\n \"authorizationUrl\": \"https://auth.example.com/authorize\",\n \"scopes\": {\"read\": \"Read access\"}\n }\n}\n\n// v1.0 - Use Authorization Code + PKCE instead\n{\n \"authorizationCodeFlow\": {\n \"authorizationUrl\": \"https://auth.example.com/authorize\",\n \"tokenUrl\": \"https://auth.example.com/token\",\n \"pkceRequired\": true,\n \"scopes\": {\"read\": \"Read access\"}\n }\n}\n```\n\n---\n\n## New Dependencies on Other Specifications\n\nv1.0 introduces several new formal dependencies on industry-standard specifications:\n\n### Added Specifications\n\n#### ✅ google.rpc.Status / google.rpc.ErrorInfo\n\n- **Purpose:** Standardized error response model with ProtoJSON representation\n- **Usage:** Error responses for HTTP+JSON and JSON-RPC bindings\n- **Impact:** Replaces RFC 9457 for HTTP errors. Enforces structured `ErrorInfo` with `reason` and `domain` for A2A-specific errors.\n\n#### ✅ RFC 8785 - JSON Canonicalization Scheme (JCS)\n\n- **Purpose:** Deterministic JSON serialization for signing\n- **Usage:** Agent Card signature verification\n- **Impact:** Enables cryptographic verification of Agent Card integrity\n- **Details:** Canonical form used before JWS signing (excludes `signatures` field)\n\n#### ✅ RFC 7515 - JSON Web Signature (JWS)\n\n- **Purpose:** Cryptographic signing standard\n- **Usage:** Agent Card signatures field\n- **Impact:** Industry-standard signature format for trust verification\n- **Details:** Supports detached signatures with public key retrieval via `jku` or trusted keystores\n\n#### ✅ Google API Design Guidelines\n\n- **Purpose:** gRPC best practices and conventions\n- **Usage:** gRPC binding design patterns\n- **Impact:** Better alignment with gRPC ecosystem expectations\n\n#### ✅ ISO 8601\n\n- **Purpose:** Timestamp format standard\n- **Usage:** All timestamp fields (createdAt, lastModified, timestamp)\n- **Impact:** Explicit format requirement: UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)\n\n### Existing Dependencies (Retained from v0.3.0)\n\n- JSON-RPC 2.0\n- gRPC / Protocol Buffers 3\n- HTTP/HTTPS (various RFCs)\n- Server-Sent Events (SSE) - W3C specification\n- RFC 8615 - Well-known URIs\n- OAuth 2.0, OpenID Connect (for authentication)\n- TLS (RFC 8446 recommended)\n\n### Complementary Protocol\n\n**Model Context Protocol (MCP):**\n\n- Relationship clarified: MCP handles tool/resource integration, A2A handles agent-to-agent coordination\n- Protocols are complementary, not competing\n- Agents may support both protocols for different use cases\n\n---\n\n## Impact on Developers\n\n### Breaking Changes Requiring Code Updates\n\n#### 1. Part Type Unification (CRITICAL IMPACT)\n\nThe most significant breaking change: TextPart, FilePart, and DataPart types have been removed and replaced with a single unified Part structure.\n\n**Before (v0.3.0):**\n\n```typescript\n// Separate types with kind discriminator\nif (part.kind === \"text\") {\n return part.text;\n} else if (part.kind === \"file\") {\n if (part.file.fileWithUri) {\n return fetchFile(part.file.fileWithUri);\n } else {\n return part.file.fileWithBytes;\n }\n} else if (part.kind === \"data\") {\n return part.data;\n}\n```\n\n**After (v1.0):**\n\n```typescript\n// Unified Part with oneof content\nif (\"text\" in part) {\n return part.text;\n} else if (\"url\" in part) {\n return fetchFile(part.url);\n} else if (\"raw\" in part) {\n return decodeBase64(part.raw);\n} else if (\"data\" in part) {\n return part.data;\n}\n```\n\n#### 2. Stream Event Discriminator Pattern (HIGH IMPACT)\n\nStream events changed from kind-based to wrapper-based discrimination:\n\n**Before (v0.3.0):**\n\n```typescript\nif (event.kind === \"taskStatusUpdate\") {\n handleStatusUpdate(event);\n} else if (event.kind === \"taskArtifactUpdate\") {\n handleArtifactUpdate(event);\n}\n```\n\n**After (v1.0):**\n\n```typescript\nif (\"taskStatusUpdate\" in event) {\n handleStatusUpdate(event.taskStatusUpdate);\n} else if (\"taskArtifactUpdate\" in event) {\n handleArtifactUpdate(event.taskArtifactUpdate);\n}\n```\n\n#### 3. Agent Card Structure (HIGH IMPACT)\n\nAgent discovery and capability checking requires updates:\n\n**Before (v0.3.0):**\n\n```typescript\nconst endpoint = agentCard.url;\nconst transport = agentCard.preferredTransport;\nconst supportsExtended = agentCard.supportsAuthenticatedExtendedCard;\n```\n\n**After (v1.0):**\n\n```typescript\nconst primaryInterface = agentCard.supportedInterfaces[0];\nconst endpoint = primaryInterface.url;\nconst transport = primaryInterface.protocolBinding;\nconst supportsExtended = agentCard.capabilities.extendedAgentCard;\n```\n\n#### 4. Pagination (MEDIUM IMPACT)\n\nList Tasks implementation must switch from page-based to cursor-based:\n\n**Before (v0.3.0):**\n\n```typescript\nconst response = await listTasks({ page: 1, perPage: 50 });\n```\n\n**After (v1.0):**\n\n```typescript\nlet cursor = undefined;\ndo {\n const response = await listTasks({ cursor, limit: 50 });\n // process response.tasks\n cursor = response.nextCursor;\n} while (cursor);\n```\n\n#### 5. Enum Value Changes (HIGH IMPACT)\n\nAll enum values now use SCREAMING_SNAKE_CASE with type prefixes:\n\n**TaskState:**\n\n```typescript\n// v0.3.0\nif (task.status.state === \"completed\") { ... }\nif (task.status.state === \"input-required\") { ... }\n\n// v1.0\nif (task.status.state === \"TASK_STATE_COMPLETED\") { ... }\nif (task.status.state === \"TASK_STATE_INPUT_REQUIRED\") { ... }\n```\n\n**MessageRole:**\n\n```typescript\n// v0.3.0\nconst message = { role: \"user\", parts: [...] };\n\n// v1.0\nconst message = { role: \"ROLE_USER\", parts: [...] };\n```\n\n**Complete Mapping:**\n\n- `\"submitted\"` → `\"TASK_STATE_SUBMITTED\"`\n- `\"working\"` → `\"TASK_STATE_WORKING\"`\n- `\"completed\"` → `\"TASK_STATE_COMPLETED\"`\n- `\"failed\"` → `\"TASK_STATE_FAILED\"`\n- `\"canceled\"` → `\"TASK_STATE_CANCELED\"`\n- `\"rejected\"` → `\"TASK_STATE_REJECTED\"`\n- `\"input-required\"` → `\"TASK_STATE_INPUT_REQUIRED\"`\n- `\"auth-required\"` → `\"TASK_STATE_AUTH_REQUIRED\"`\n- `\"user\"` → `\"ROLE_USER\"`\n- `\"agent\"` → `\"ROLE_AGENT\"`\n\n#### 6. Field Name Changes (LOW IMPACT)\n\n- `file.mimeType` → `mediaType`\n- Operation names (aliases provided during transition)\n\n#### 7. Standardized Error Handling via google.rpc.Status (HIGH IMPACT)\n\nHTTP+JSON error responses have been updated to use the ProtoJSON representation of `google.rpc.Status` instead of RFC 9457 (Problem Details). JSON-RPC and HTTP+JSON bindings now use `google.rpc.ErrorInfo` within the `data` / `details` array to provide A2A-specific error context.\n\n**Changes:**\n\n- **HTTP+JSON Content-Type:** Changed from `application/problem+json` to `application/json`.\n- **Error Model:** Uses `google.rpc.Status` fields (`code`, `message`, `details`).\n- **A2A Error Info:** MUST include a `google.rpc.ErrorInfo` object in `details` with `reason` (UPPER_SNAKE_CASE from A2A error types) and `domain: \"a2a-protocol.org\"`.\n\n**JSON-RPC Example Migration:**\n\n```json\n// v0.3.0\n\"error\": {\n \"code\": -32001,\n \"message\": \"Task not found\",\n \"data\": { \"taskId\": \"123\" }\n}\n\n// v1.0\n\"error\": {\n \"code\": -32001,\n \"message\": \"Task not found\",\n \"data\": [\n {\n \"@type\": \"type.googleapis.com/google.rpc.ErrorInfo\",\n \"reason\": \"TASK_NOT_FOUND\",\n \"domain\": \"a2a-protocol.org\",\n \"metadata\": { \"taskId\": \"123\" }\n }\n ]\n}\n```\n\n**HTTP+JSON Example Migration:**\n\n```http\n// v0.3.0 (Draft using RFC 9457)\nHTTP/1.1 404 Not Found\nContent-Type: application/problem+json\n\n{\n \"type\": \"https://a2a-protocol.org/errors/task-not-found\",\n \"title\": \"Task Not Found\",\n \"status\": 404,\n \"detail\": \"The specified task ID does not exist\"\n}\n\n// v1.0\nHTTP/1.1 404 Not Found\nContent-Type: application/json\n\n{\n \"error\": {\n \"code\": 404,\n \"status\": \"NOT_FOUND\",\n \"message\": \"The specified task ID does not exist\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/google.rpc.ErrorInfo\",\n \"reason\": \"TASK_NOT_FOUND\",\n \"domain\": \"a2a-protocol.org\"\n }\n ]\n }\n}\n```\n\n### New Capabilities to Leverage\n\n#### 1. Execution Mode Control\n\n```typescript\n// Wait for task completion (Default)\nconst result = await sendMessage(message, { returnImmediately: false });\n\n// Return immediately, poll later\nconst task = await sendMessage(message, { returnImmediately: true });\n```\n\n#### 2. Agent Card Signature Verification\n\n```typescript\nif (agentCard.signatures && agentCard.signatures.length > 0) {\n const verified = await verifyAgentCardSignature(agentCard);\n if (!verified) {\n throw new Error(\"Agent Card signature verification failed\");\n }\n}\n```\n\n#### 3. Extension Requirements\n\n```typescript\nconst requiredExtensions = agentCard.extensions\n .filter(ext => ext.required)\n .map(ext => ext.uri);\n\n// Check if client supports required extensions\nif (!clientSupportsAll(requiredExtensions)) {\n throw new Error(\"Missing required extension support\");\n}\n```\n\n#### 4. Enhanced Timestamp Tracking\n\n```typescript\nconst taskAge = Date.now() - new Date(task.createdAt).getTime();\nconst timeSinceUpdate = Date.now() - new Date(task.lastModified).getTime();\n```\n\n#### 5. Versioning Negotiation\n\n```typescript\n// Client sends A2A-Version header\nheaders[\"A2A-Version\"] = \"1.0\";\n\n// Server validates and rejects if unsupported\nif (!supportedVersions.includes(requestedVersion)) {\n throw new VersionNotSupportedError();\n}\n```\n\n### Migration Strategy Recommendations\n\n#### Phase 1: Compatibility Layer\n\n1. Add support for parsing both old and new discriminator patterns\n2. Implement version detection based on protocol version\n3. Support both Agent Card structures during transition\n\n#### Phase 2: Dual Support\n\n1. Update all APIs to emit v1.0 format\n2. Maintain backward compatibility readers for v0.3.0\n3. Add A2A-Version header handling\n4. Implement cursor-based pagination alongside legacy page-based\n\n#### Phase 3: v1.0 Only\n\n1. Deprecate v0.3.0 compatibility code\n2. Remove legacy discriminator parsing\n3. Remove page-based pagination\n4. Clean up dual-format support code\n\n#### Backward Compatibility Strategy (#1401)\n\nv1.0 introduces a formal approach to protocol versioning that enables SDK backward compatibility.\n\n**Protocol Version Per Interface:**\n\n- Each `AgentInterface` now specifies its own `protocolVersion` field\n- Agents can support multiple protocol versions simultaneously by exposing multiple interfaces\n- Clients negotiate version by selecting appropriate interface from Agent Card\n\n**SDK Implementation Pattern:**\n\n```typescript\n// SDK can support multiple protocol versions\nclass A2AClient {\n async connect(agentCardUrl: string) {\n const card = await this.getAgentCard(agentCardUrl);\n\n // Find best matching interface\n const interface = card.supportedInterfaces.find(i =>\n this.supportedVersions.includes(i.protocolVersion)\n );\n\n if (!interface) {\n throw new Error(\"No compatible protocol version\");\n }\n\n // Use version-specific adapter\n return this.createAdapter(interface.protocolVersion, interface);\n }\n}\n```\n\n**Benefits:**\n\n- SDKs can maintain support for multiple protocol versions\n- Agents can gradually migrate by supporting both old and new versions\n- Clients automatically select best compatible version\n- Enables graceful deprecation of old protocol versions\n\n### Testing Considerations\n\n- Test with both v0.3.0 and v1.0 formatted data\n- Validate Agent Card signature verification\n- Test cursor-based pagination edge cases (empty results, single page, etc.)\n- Verify proper handling of new error types\n- Test extension requirement validation\n\n### Recommended Priority\n\n#### Critical (Do Immediately)\n\n- Update Part and streaming event parsing (discriminator pattern)\n- Update Agent Card parsing (structure changes)\n- Add A2A-Version header to all requests\n\n#### High (Within 1 Month)\n\n- Implement cursor-based pagination\n- Update enum value handling (state field)\n- Add return_immediately parameter support\n\n#### Medium (Within 3 Months)\n\n- Implement Agent Card signature verification\n- Add extension requirement checking\n- Update timestamp handling to ISO 8601 format\n- Implement new error types\n\n#### Low (Nice to Have)\n\n- Add createdAt/lastModified timestamp tracking\n- Leverage enhanced metadata capabilities\n- Implement mutual TLS authentication support\n\n---\n\n## Conclusion\n\nA2A Protocol v1.0 represents a significant step forward in protocol maturity while maintaining the core architectural principles of v0.3.0. The changes focus on standardization, type safety, and enterprise readiness, requiring developers to update their implementations but providing clearer specifications and better developer experience in return.\n\nThe breaking changes, while requiring code updates, are straightforward to implement and improve code clarity. The new capabilities around versioning, signatures, and enhanced extensions provide a solid foundation for future protocol evolution within the v1.x line.\n\nDevelopers should plan for a phased migration approach, prioritizing the critical breaking changes while gradually adopting new capabilities over time.\n" }, { "path": "lychee.toml", "content": "exclude = [\n 'https://fonts.gstatic.com/',\n 'https://fonts.googleapis.com/',\n 'https://medium.com/',\n 'https://x.com/',\n 'http://localhost:12000/',\n 'http://localhost:10020/',\n 'https://goo.gle/',\n]\nexclude_path = [\n \".github/actions/spelling\",\n \"CHANGELOG.md\",\n \"docs/partners.md\",\n \"docs/robots.txt\",\n \"docs/llms.txt\",\n \"docs/spec/a2a.json\",\n \"docs/spec-proto.md\",\n \"docs/sdk/python.md\",\n]\n\naccept = [\"200..=299\", 403, 408, 429]\n\nmax_retries = 0\nskip_missing = true\n" }, { "path": "mkdocs.yml", "content": "# Project information\nsite_name: A2A Protocol\nsite_url: https://a2a-protocol.org/\nsite_description: >-\n The official documentation for the Agent2Agent (A2A) protocol. The A2A protocol is an open standard that allows different AI agents to securely communicate, collaborate, and solve complex problems together.\nsite_author: The Linux Foundation\nsite_dir: site\nedit_uri: edit/main/docs/\n\n# Exclude files from the docs directory\nexclude_docs: |\n README.md\n\nextra:\n a2a_version: !ENV [MIKE_VERSION, \"dev\"]\n analytics:\n provider: google\n property: G-RB39M83WHB\n\n# Navigation\nnav:\n - Home: index.md\n - 🆕 Announcing Version 1.0: announcing-1.0.md\n - Documentation:\n - What is A2A?: topics/what-is-a2a.md\n - Core Concepts: topics/key-concepts.md\n - Agent Discovery: topics/agent-discovery.md\n - Enterprise Features: topics/enterprise-ready.md\n - Life of a Task: topics/life-of-a-task.md\n - Extensions: topics/extensions.md\n - Streaming & Asynchronous Operations: topics/streaming-and-async.md\n - A2A and MCP: topics/a2a-and-mcp.md\n - Tutorials and Samples:\n - tutorials/index.md\n - Quickstart (Python):\n - Introduction: tutorials/python/1-introduction.md\n - Setup: tutorials/python/2-setup.md\n - Agent Skills & Agent Card: tutorials/python/3-agent-skills-and-card.md\n - Agent Executor: tutorials/python/4-agent-executor.md\n - Start Server: tutorials/python/5-start-server.md\n - Interact with Server: tutorials/python/6-interact-with-server.md\n - Streaming & Multiturn: tutorials/python/7-streaming-and-multiturn.md\n - Next Steps: tutorials/python/8-next-steps.md\n - DeepLearning.AI Course: https://goo.gle/dlai-a2a\n - Specification:\n - Overview: specification.md\n - What's New in v1.0: whats-new-v1.md\n - Protocol Definition: definitions.md\n - SDK Reference:\n - sdk/index.md\n - Python: sdk/python/api/index.html\n - Community: community.md\n - Partners: partners.md\n - Roadmap: roadmap.md\n\n# Repository\nrepo_name: a2aproject/A2A\nrepo_url: https://github.com/a2aproject/A2A\n\n# Copyright\ncopyright: Copyright 2026 The Linux Foundation. Licensed under the Apache License, Version 2.0.\n\n# Custom CSS\nextra_css:\n - stylesheets/custom.css\n\n# Configuration\ntheme:\n name: material\n custom_dir: .mkdocs/overrides\n font:\n text: Google Sans\n code: Roboto Mono\n logo: assets/a2a-logo-white.svg\n favicon: assets/a2a-logo-black.svg\n icon:\n repo: fontawesome/brands/github\n view: material/pencil-box-multiple\n admonition:\n note: fontawesome/solid/note-sticky\n abstract: fontawesome/solid/book\n info: fontawesome/solid/circle-info\n tip: fontawesome/solid/bullhorn\n success: fontawesome/solid/check\n question: fontawesome/solid/circle-question\n warning: fontawesome/solid/triangle-exclamation\n failure: fontawesome/solid/bomb\n danger: fontawesome/solid/skull\n bug: fontawesome/solid/robot\n example: fontawesome/solid/flask\n quote: fontawesome/solid/quote-left\n palette:\n - scheme: default\n primary: indigo\n accent: white\n features:\n - announce.dismiss\n - content.action.view\n - content.code.annotate\n - content.code.copy\n - content.code.select\n - content.tabs.link\n - navigation.footer\n - navigation.indexes\n - navigation.instant\n - navigation.instant.progress\n - navigation.path\n - navigation.top\n - navigation.tracking\n - toc.follow\n - versioning:\n provider: mike\n\n# Extensions\nmarkdown_extensions:\n - meta\n - footnotes\n - admonition\n - attr_list\n - md_in_html\n - pymdownx.details\n - pymdownx.emoji:\n emoji_index: !!python/name:material.extensions.emoji.twemoji\n emoji_generator: !!python/name:material.extensions.emoji.to_svg\n - pymdownx.highlight:\n anchor_linenums: true\n line_spans: __span\n pygments_lang_class: true\n - pymdownx.inlinehilite\n - pymdownx.snippets:\n base_path: .\n url_download: true\n dedent_subsections: true\n - pymdownx.superfences:\n custom_fences:\n - name: mermaid\n class: mermaid\n format: !!python/name:pymdownx.superfences.fence_code_format\n - pymdownx.tabbed:\n alternate_style: true\n slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n - toc:\n permalink: true\n\n# Plugins\nplugins:\n - search\n - macros:\n module_name: .mkdocs/macros\n - redirects:\n redirect_maps:\n \"specification/overview.md\": \"specification.md\"\n \"specification/agent-card.md\": \"specification.md#5-agent-discovery-the-agent-card\"\n \"specification/agent-to-agent-communication.md\": \"specification.md#6-protocol-data-objects\"\n \"specification/sample-messages.md\": \"specification.md#9-common-workflows-examples\"\n \"specification/details.md\": \"specification.md\"\n \"documentation.md\": \"topics/key-concepts.md\"\n \"resources.md\": \"index.md\"\n \"topics/push-notifications.md\": \"topics/streaming-and-async.md\"\n \"specification/topics/a2a_and_mcp.md\": \"topics/a2a-and-mcp.md\"\n \"specification/topics/agent_discovery.md\": \"topics/agent-discovery.md\"\n \"specification/topics/enterprise_ready.md\": \"topics/enterprise-ready.md\"\n \"specification/topics/push_notification.md\": \"topics/streaming-and-async.md\"\n \"specification/topics/push_notifications.md\": \"topics/streaming-and-async.md\"\n \"topics/index.md\": \"topics/what-is-a2a.md\"\n \"topics/roadmap.md\": \"roadmap.md\"\n # Tutorial\n \"tutorials/python/index.md\": \"tutorials/python/1-introduction.md\"\n \"tutorials/python/1_introduction.md\": \"tutorials/python/1-introduction.md\"\n \"tutorials/python/3-create-project.md\": \"tutorials/python/2-setup.md\"\n \"tutorials/python/4-agent-skills.md\": \"tutorials/python/3-agent-skills-and-card.md\"\n \"tutorials/python/5-add-agent-card.md\": \"tutorials/python/3-agent-skills-and-card.md\"\n \"tutorials/python/6-start-server.md\": \"tutorials/python/5-start-server.md\"\n \"tutorials/python/7-interact-with-server.md\": \"tutorials/python/6-interact-with-server.md\"\n \"tutorials/python/8-agent-capabilities.md\": \"tutorials/python/7-streaming-and-multiturn.md\"\n \"tutorials/python/9-ollama-agent.md\": \"tutorials/python/7-streaming-and-multiturn.md\"\n \"tutorials/python/10-next-steps.md\": \"tutorials/python/8-next-steps.md\"\n - mike:\n canonical_version: latest\n" }, { "path": "requirements-docs.txt", "content": "mkdocs-material\nmkdocs-redirects\na2a-sdk[all]\nmike\nmkdocs-macros-plugin\nsphinx\nfuro\nmyst-parser\nproto-schema-parser\ntabulate\n" }, { "path": "scripts/build_docs.sh", "content": "#!/bin/bash\nset -euo pipefail\n\n# Unified docs build script that ensures the non-normative JSON artifact is\n# regenerated (if stale) before invoking MkDocs. Uses pure shell.\n\nROOT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\n\nSCHEMA_JSON=\"$ROOT_DIR/specification/json/a2a.json\"\nPROTO_SRC=\"$ROOT_DIR/specification/a2a.proto\"\nSPEC_SITE_DIR=\"$ROOT_DIR/docs/spec\"\nSCHEMA_JSON_SITE_FILE=\"$SPEC_SITE_DIR/a2a.json\"\nPROTO_SITE_FILE=\"$SPEC_SITE_DIR/a2a.proto\"\nPROTO_TO_SCHEMA_SCRIPT=\"$ROOT_DIR/scripts/proto_to_json_schema.sh\"\n\nregen_needed() {\n if [ ! -f \"$SCHEMA_JSON\" ]; then return 0; fi\n\n local proto_mtime\n local schema_mtime\n if [[ \"$(uname)\" == \"Darwin\" ]]; then\n proto_mtime=$(stat -f %m \"$PROTO_SRC\")\n schema_mtime=$(stat -f %m \"$SCHEMA_JSON\")\n else\n proto_mtime=$(stat -c %Y \"$PROTO_SRC\")\n schema_mtime=$(stat -c %Y \"$SCHEMA_JSON\")\n fi\n [ \"$proto_mtime\" -gt \"$schema_mtime\" ]\n}\n\necho \"[build_docs] Checking schema freshness...\" >&2\nif regen_needed; then\n echo \"[build_docs] Regenerating a2a.json from proto\" >&2\n if [ -x \"$PROTO_TO_SCHEMA_SCRIPT\" ]; then\n bash \"$PROTO_TO_SCHEMA_SCRIPT\" \"$SCHEMA_JSON\" || {\n echo \"[build_docs] Warning: proto to JSON schema conversion failed\" >&2\n }\n else\n echo \"[build_docs] proto_to_json_schema.sh missing or not executable; skipping schema generation.\" >&2\n fi\nelse\n echo \"[build_docs] Schema is up-to-date, skipping regeneration\" >&2\nfi\n\n# Always ensure spec files are available in docs directory for MkDocs\nmkdir -p \"$SPEC_SITE_DIR\"\n\nif [ -f \"$SCHEMA_JSON\" ]; then\n cp \"$SCHEMA_JSON\" \"$SCHEMA_JSON_SITE_FILE\"\n echo \"[build_docs] Published schema to $SCHEMA_JSON_SITE_FILE\" >&2\nelse\n echo \"[build_docs] Warning: Schema file not found at $SCHEMA_JSON - MkDocs may fail\" >&2\nfi\n\nif [ -f \"$PROTO_SRC\" ]; then\n cp \"$PROTO_SRC\" \"$PROTO_SITE_FILE\"\n echo \"[build_docs] Published proto to $PROTO_SITE_FILE\" >&2\nelse\n echo \"[build_docs] Warning: Proto file not found at $PROTO_SRC\" >&2\nfi\n\n# Build SDK documentation\necho \"[build_docs] Building SDK documentation...\" >&2\nSDK_DOCS_SCRIPT=\"$ROOT_DIR/scripts/build_sdk_docs.sh\"\nif [ -x \"$SDK_DOCS_SCRIPT\" ]; then\n bash \"$SDK_DOCS_SCRIPT\" || echo \"[build_docs] Warning: SDK docs build failed\" >&2\nelse\n echo \"[build_docs] SDK docs script not found or not executable: $SDK_DOCS_SCRIPT\" >&2\nfi\n\n# Add venv bin to PATH to ensure mike finds mkdocs and plugins\nif [ -d \"$ROOT_DIR/.doc-venv/bin\" ]; then\n export PATH=\"$ROOT_DIR/.doc-venv/bin:$PATH\"\nfi\n\nif [ \"${1:-}\" = \"deploy\" ]; then\n shift\n echo \"[build_docs] Deploying with mike...\" >&2\n mike deploy \"$@\"\nelse\n echo \"[build_docs] Building MkDocs site...\" >&2\n mkdocs build \"$@\"\nfi\necho \"[build_docs] Done.\" >&2\n" }, { "path": "scripts/build_llms_full.sh", "content": "#!/bin/bash\nset -e\n\n# This script concatenates all documentation and specification files\n# into a single file for LLM consumption.\n\n# --- Configuration ---\nOUTPUT_FILE=\"docs/llms-full.txt\"\nDOCS_DIR=\"docs\"\nSPEC_DIR=\"specification\"\nSDK_DOCS_SCRIPT=\"scripts/build_sdk_docs.sh\"\nPROJECT_NAME=\"A2A (Agent2Agent) Protocol\"\n\necho \"--- Generating consolidated LLM file: ${OUTPUT_FILE} ---\"\n\n# --- Generate Python SDK Text Documentation ---\nif [ -f \"$SDK_DOCS_SCRIPT\" ]; then\n echo \"Generating Python SDK documentation...\"\n bash \"$SDK_DOCS_SCRIPT\"\nelse\n echo \"Warning: SDK docs script not found at $SDK_DOCS_SCRIPT\"\nfi\n\n# Clear the output file and add introduction\ncat <
\n
\n\nmacOS/Linux
\n\n### Prerequisites for macOS/Linux\n\n1. **Homebrew (macOS) or apt-get (Debian/Ubuntu)**\n - **macOS**: Install from [brew.sh](https://brew.sh/)\n - **Debian/Ubuntu**: `apt-get` is pre-installed.\n\n2. **Python with pip**\n\n ```bash\n # Verify installation:\n python3 --version\n pip3 --version\n ```\n\n3. **Core build tools (`protoc`, `go`, `jq`)**\n - **macOS**:\n\n ```bash\n brew install protobuf go jq\n ```\n\n - **Debian/Ubuntu**:\n\n ```bash\n sudo apt-get update && sudo apt-get install -y protobuf-compiler golang jq\n ```\n\n4. **protoc-gen-jsonschema plugin**\n\n ```bash\n # Install via Go (requires Go to be installed first):\n go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest\n ```\n\n5. **Clone googleapis repository**\n\n ```bash\n # Clone to a location like $HOME/googleapis\n git clone https://github.com/googleapis/googleapis.git $HOME/googleapis\n export GOOGLEAPIS_DIR=$HOME/googleapis\n\n # To persist this, add the export command to your shell profile (e.g., ~/.zshrc or ~/.bashrc)\n echo 'export GOOGLEAPIS_DIR=$HOME/googleapis' >> ~/.bashrc\n ```\n\n6. **Python documentation dependencies**\n\n ```bash\n # Create and activate virtual environment:\n python3 -m venv .venv-docs\n source .venv-docs/bin/activate\n\n # Install requirements:\n pip install -r requirements-docs.txt\n ```\n\n#### Building the A2A JSON Artifact on macOS/Linux\n\nOnce all prerequisites are installed:\n\n```bash\n# Run the build script:\n./scripts/build_docs.sh\n```\n\nThis script handles all necessary steps to generate the `a2a.json` artifact and build the documentation site.\n\n
\n\n#### Troubleshooting\n\n- **protoc errors**: Ensure both `protoc` and the googleapis directory are properly configured\n- **jq not found**: Ensure jq is installed and in your `PATH`\n- **Python import errors**: Activate the virtual environment and ensure all requirements are installed\n- **Missing schemas**: Check that `protoc-gen-jsonschema` is in your `PATH` (run `go env GOPATH` to find Go bin directory)\n\n## Future Work\n\nPlanned improvements include:\n\n- Optional OpenAPI v3 conversion and publishing a draft 2020-12 `components.schemas` bundle.\n- Automatic alias injection for deprecated names (anyOf wrapper) to ease migrations.\n- Validation step ensuring no generated artifacts are reintroduced into git.\n"
}
]