A2A/docs/index.md
Darrel b078419954
docs(spec): Large refactor of specification to separate application protocol definition from mapping to transports. (#1160)
Related to #1151 

Fixes https://github.com/a2aproject/A2A/issues/998
Fixes https://github.com/a2aproject/A2A/issues/1091
Fixes https://github.com/a2aproject/A2A/issues/1072
Fixes https://github.com/a2aproject/A2A/issues/1058
Fixes https://github.com/a2aproject/A2A/issues/975
Fixes https://github.com/a2aproject/A2A/issues/1105
Fixes https://github.com/a2aproject/A2A/issues/989
Fixes https://github.com/a2aproject/A2A/issues/1189
Fixes https://github.com/a2aproject/A2A/issues/1187
Fixes https://github.com/a2aproject/A2A/issues/1177
Fixes https://github.com/a2aproject/A2A/issues/1180
Fixes https://github.com/a2aproject/A2A/issues/1172



In order to more effectively describe the A2A protocol in a consistent
way across different protocols, this PR refactors the specification to
describe the application protocol in a transport agnostic way, and then
have separate sections that describe how each of the transports map to
the abstract application protocol. To see a preview of what it looks
like you can go here
https://purple-moss-0838db51e.3.azurestaticapps.net/specification/

The goal of the TSC is to use the changes in this PR as the baseline for
a v1.0 Release Candidate. This will give SDK maintainers an stable
document to validate the changes in the specification through
implementations before v1.0 release.

There are many pending feature requests for the A2A specifications that
the TSC are supportive of. However, getting a stable, consistent,
unambiguous, multi-protocol specification is necessary before additional
features can be added safely.

## Document Restructuring 

- [A2A
Operations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#3-a2a-protocol-operations)
are described independent of wire protocol
- [Protocol Data
Model](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#4-protocol-data-model)
is described using protobuf as source of truth. All other serializations
are derived from that.
- Protocol bindings (formerly described as transports) are now described
in their own sections
-
[JSON-RPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#9-json-rpc-protocol-binding)
-
[gRPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#10-grpc-protocol-binding)
-
[HTTP](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#11-httpjsonrest-protocol-binding)
- [Operation Parameters
](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#32-operation-parameter-objects)
describe structures reused across different operations
- [Operation
Semantics](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#33-operation-semantics)
describe common behavior patterns across operations

## New Sections

- [Requirements
Language](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#21-requirements-language)
- [Capability
Validation](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#334-capability-validation)
- [Abstract description of error
handling](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#332-error-handling)
- [Abstract description of
"headers"](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#325-headers)
-
[Extensions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#46-extensions)
-
[Versioning](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#36-versioning)
- [Custom Binding
Guidelines](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#12-custom-binding-guidelines)
- [JSON Field Naming
Conventions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#54-json-field-naming-convention)
- [Data Type
Conventions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#55-data-type-conventions)
- [Security
Considerations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#77-security-considerations)
- [Agent Card
Signing](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#84-agent-card-signing)
- [IANA
Considerations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#13-iana-considerations)

## Protocol Clarifications

- Defining order for events returned from [Stream
Message](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#312-stream-message)
- [JSON
Examples](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#416-filepart)
provided for protobuf definitions of data model objects that previously
used discriminators
- Clarification of returned errors where multiple are applicable. e.g.
[Cancel
Task](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#315-cancel-task)
- Defined returned events and usage scenarios for
[Resubscribe](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#316-resubscribe-to-task)
- Defined protocol binding for errors using protocol native capabilities
for all bindings
-
[JSON-RPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#94-error-handling)
-
[gRPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#104-error-handling)
-
[HTTP](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#115-error-handling)
  
## Artifact Generation

The scripts have been changed to enable a2a.json to be generated from
the a2a.proto so that a2a.proto and specification.md are the only
normative source. Additional work is required to align the generated
a2a.json with the original one.

Release-As: 1.0

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Signed-off-by: Luca Muscariello <lumuscar@cisco.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2025-11-20 14:52:09 -05:00

5.6 KiB

hide
hide
toc
Agent2Agent Protocol Logo

Agent2Agent (A2A) Protocol

What is A2A Protocol?

Welcome to the official documentation for the Agent2Agent (A2A) Protocol, an open standard designed to enable seamless communication and collaboration between AI agents.

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

!!! abstract "" Build with ADK Logo{class="twemoji lg middle"} ADK (or any framework), equip with MCP Logo{class="twemoji lg middle"} MCP (or any tool), and communicate with A2A Logo{class="twemoji lg middle"} A2A, to remote agents, local agents, and humans.

Get started with A2A

Why use the A2A Protocol

graph LR
    User(🧑‍💻 User) <--> ClientAgent(🤖 Client Agent)
    ClientAgent --> A2A1(**↔️ A2A**) --> RemoteAgent1(🤖 Remote Agent 1)
    ClientAgent --> A2A2(**↔️ A2A**) --> RemoteAgent2(🤖 Remote Agent 2)

    style User fill:#fdebd0,stroke:#e67e22,stroke-width:2px
    style ClientAgent fill:#d6eaf8,stroke:#3498db,stroke-width:2px
    style RemoteAgent1 fill:#d6eaf8,stroke:#3498db,stroke-width:2px
    style RemoteAgent2 fill:#d6eaf8,stroke:#3498db,stroke-width:2px
    style A2A1 fill:#ebedef,stroke:#909497,stroke-width:2px
    style A2A2 fill:#ebedef,stroke:#909497,stroke-width:2px
  • :material-account-group-outline:{ .lg .middle } Interoperability

    Connect agents built on different platforms (LangGraph, CrewAI, Semantic Kernel, custom solutions) to create powerful, composite AI systems.

  • :material-lan-connect:{ .lg .middle } Complex Workflows

    Enable agents to delegate sub-tasks, exchange information, and coordinate actions to solve complex problems that a single agent cannot.

  • :material-shield-key-outline:{ .lg .middle } Secure & Opaque

    Agents interact without needing to share internal memory, tools, or proprietary logic, ensuring security and preserving intellectual property.


How does A2A work with MCP?

A2A MCP Graphic{width="60%"} {style="text-align: center; margin-bottom:1em; margin-top:1em;"}

A2A and Model Context Protocol (MCP) are complementary standards for building robust agentic applications:

  • Model Context Protocol (MCP): Provides agent-to-tool communication. It's a complementary standard that standardizes how an agent connects to its tools, APIs, and resources to get information.
  • IBM ACP: Incorporated into the A2A Protocol
  • 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.
  • A2A: Provides agent-to-agent communication. As a universal, decentralized standard, A2A acts as the public internet that allows ai agents—including those using MCP, or built with frameworks like agntcy—to interoperate, collaborate, and share their findings.