A2A/mkdocs.yml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

184 lines
6.5 KiB
YAML
Raw Permalink Normal View History

# Project information
site_name: A2A Protocol
site_url: https://a2a-protocol.org/
site_description: >-
2025-10-16 10:51:33 -05:00
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.
site_author: The Linux Foundation
site_dir: site
edit_uri: edit/main/docs/
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
# Exclude files from the docs directory
exclude_docs: |
README.md
extra:
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
a2a_version: !ENV [MIKE_VERSION, "dev"]
analytics:
provider: google
property: G-RB39M83WHB
# Navigation
nav:
- Home: index.md
- 🆕 Announcing Version 1.0: announcing-1.0.md
- Documentation:
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
- What is A2A?: topics/what-is-a2a.md
- Core Concepts: topics/key-concepts.md
- Agent Discovery: topics/agent-discovery.md
- Enterprise Features: topics/enterprise-ready.md
- Life of a Task: topics/life-of-a-task.md
- Extensions: topics/extensions.md
- Custom Protocol Bindings: topics/custom-protocol-bindings.md
- Extension & Binding Governance: topics/extension-and-binding-governance.md
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
- Streaming & Asynchronous Operations: topics/streaming-and-async.md
- A2A and MCP: topics/a2a-and-mcp.md
- Tutorials and Samples:
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
- tutorials/index.md
- Quickstart (Python):
- Introduction: tutorials/python/1-introduction.md
- Setup: tutorials/python/2-setup.md
- Agent Skills & Agent Card: tutorials/python/3-agent-skills-and-card.md
- Agent Executor: tutorials/python/4-agent-executor.md
- Start Server: tutorials/python/5-start-server.md
- Interact with Server: tutorials/python/6-interact-with-server.md
- Streaming & Multiturn: tutorials/python/7-streaming-and-multiturn.md
- Next Steps: tutorials/python/8-next-steps.md
- DeepLearning.AI Course: https://goo.gle/dlai-a2a
- Specification:
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
- Overview: specification.md
- What's New in v1.0: whats-new-v1.md
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
- Protocol Definition: definitions.md
- SDK Reference:
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
- sdk/index.md
- Python: sdk/python/api/index.html
- Community: community.md
- Partners: partners.md
- Roadmap: roadmap.md
# Repository
2025-06-23 21:34:48 +02:00
repo_name: a2aproject/A2A
repo_url: https://github.com/a2aproject/A2A
# Copyright
copyright: Copyright 2026 The Linux Foundation. Licensed under the Apache License, Version 2.0.
# Custom CSS
extra_css:
- stylesheets/custom.css
# Configuration
theme:
name: material
custom_dir: .mkdocs/overrides
font:
text: Google Sans
code: Roboto Mono
logo: assets/a2a-logo-white.svg
favicon: assets/a2a-logo-black.svg
icon:
repo: fontawesome/brands/github
view: material/pencil-box-multiple
admonition:
note: fontawesome/solid/note-sticky
abstract: fontawesome/solid/book
info: fontawesome/solid/circle-info
tip: fontawesome/solid/bullhorn
success: fontawesome/solid/check
question: fontawesome/solid/circle-question
warning: fontawesome/solid/triangle-exclamation
failure: fontawesome/solid/bomb
danger: fontawesome/solid/skull
bug: fontawesome/solid/robot
example: fontawesome/solid/flask
quote: fontawesome/solid/quote-left
palette:
- scheme: default
primary: indigo
accent: white
features:
- announce.dismiss
- content.action.view
- content.code.annotate
- content.code.copy
- content.code.select
- content.tabs.link
- navigation.footer
- navigation.indexes
- navigation.instant
- navigation.instant.progress
- navigation.path
- navigation.top
- navigation.tracking
- toc.follow
- versioning:
provider: mike
# Extensions
markdown_extensions:
2025-09-08 12:59:20 -05:00
- meta
- footnotes
- admonition
- attr_list
- md_in_html
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets:
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
base_path: .
url_download: true
dedent_subsections: true
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
- toc:
permalink: true
# Plugins
plugins:
- search
docs(spec): Updated specification to render data models as a table generated from the proto instead of a raw proto snippet (#1225) In the currently published specification the data model definitions include a proto snippet and then have a list of fields under the snippet. This creates duplicated information. To prevent this duplication while maintaining an easy to read presentation of the abstract data models, this PR uses a Python macro to convert the proto into a markdown table. Also took the opportunity to do an editorial pass on the comments in the a2a.proto before the field descriptions were removed from the specification.md. Some of this content came from the types.ts file that often had information that was not in a2a.proto. A preview of the changes can be seen here https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#41-core-objects # Proto to Markdown Table Conversion The macro system provides two main functions (`proto_to_table` and `proto_enum_to_table`) that convert Protocol Buffer definitions into formatted markdown tables: 1. **Locates Definitions**: Reads the `.proto` file and uses region markers (`--8<-- [start:Name]` and `--8<-- [end:Name]`) to extract specific message or enum definitions. 2. **Parses Structure**: Analyzes the proto content to separate three sections: - **Description**: Comments appearing before the message/enum declaration - **Fields/Values**: The actual field or enum value definitions with their inline comments - **Notes**: Comments appearing after the closing brace 3. **Extracts Field Details**: For each field, it captures: - Field name (converted from snake_case to camelCase, or using `json_name` annotation) - Type (mapped to readable formats like "string", "array of integer", "map of string") - Required status (based on `REQUIRED` annotation or `optional` keyword) - Description (from preceding comment lines) 4. **Generates Output**: Assembles the markdown output with: - Description text at the top - A formatted table with columns for Field/Type/Required/Description (or Value/Description for enums) - Special notes for `oneof` groups - Additional notes from comments after the definition The conversion automatically handles multi-line field definitions, map types, repeated fields, and filters out protolint directives and region markers from the output. --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-11-25 12:11:28 -05:00
- macros:
module_name: .mkdocs/macros
- redirects:
redirect_maps:
2025-07-08 11:36:31 -04:00
"specification/overview.md": "specification.md"
"specification/agent-card.md": "specification.md#5-agent-discovery-the-agent-card"
"specification/agent-to-agent-communication.md": "specification.md#6-protocol-data-objects"
"specification/sample-messages.md": "specification.md#9-common-workflows-examples"
"specification/details.md": "specification.md"
"documentation.md": "topics/key-concepts.md"
"resources.md": "index.md"
"topics/push-notifications.md": "topics/streaming-and-async.md"
"specification/topics/a2a_and_mcp.md": "topics/a2a-and-mcp.md"
"specification/topics/agent_discovery.md": "topics/agent-discovery.md"
"specification/topics/enterprise_ready.md": "topics/enterprise-ready.md"
"specification/topics/push_notification.md": "topics/streaming-and-async.md"
"specification/topics/push_notifications.md": "topics/streaming-and-async.md"
"topics/index.md": "topics/what-is-a2a.md"
"topics/roadmap.md": "roadmap.md"
# Tutorial
"tutorials/python/index.md": "tutorials/python/1-introduction.md"
"tutorials/python/1_introduction.md": "tutorials/python/1-introduction.md"
"tutorials/python/3-create-project.md": "tutorials/python/2-setup.md"
"tutorials/python/4-agent-skills.md": "tutorials/python/3-agent-skills-and-card.md"
"tutorials/python/5-add-agent-card.md": "tutorials/python/3-agent-skills-and-card.md"
"tutorials/python/6-start-server.md": "tutorials/python/5-start-server.md"
"tutorials/python/7-interact-with-server.md": "tutorials/python/6-interact-with-server.md"
"tutorials/python/8-agent-capabilities.md": "tutorials/python/7-streaming-and-multiturn.md"
"tutorials/python/9-ollama-agent.md": "tutorials/python/7-streaming-and-multiturn.md"
"tutorials/python/10-next-steps.md": "tutorials/python/8-next-steps.md"
- mike:
canonical_version: latest