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>
A2A JSON Artifact
a2a.json is a non-normative build artifact derived from the canonical proto definition at specification/grpc/a2a.proto. It is generated during builds and intentionally not committed to source control.
Generation pipeline:
scripts/proto_to_json_schema.shconverts proto directly to JSON Schema using bufbuild'sprotoc-gen-jsonschemaplugin.- The resulting
a2a.json(JSON Schema 2020-12 bundle) is copied todocs/spec-json/a2a.jsonfor site publishing.
The build uses protoc with protoc-gen-jsonschema plugin and jq for bundling. Only source (a2a.proto) and scripts remain under version control.
The artifact is generated automatically in:
- Local docs builds (
scripts/build_docs.sh) - CI workflow (
.github/workflows/generate-a2a-json.yml) on proto changes
Do Not Edit
Do NOT edit a2a.json manually. Update the proto instead. The file is transient and will be regenerated.
Building the A2A JSON Artifact Locally
To build the a2a.json artifact locally, you'll need several dependencies depending on your operating system. This is useful for contributors who want to preview changes before submitting pull requests.
macOS/Linux
Prerequisites for macOS/Linux
-
Homebrew (macOS) or apt-get (Debian/Ubuntu)
- macOS: Install from brew.sh
- Debian/Ubuntu:
apt-getis pre-installed.
-
Python with pip
# Verify installation: python3 --version pip3 --version -
Core build tools (
protoc,go,jq)-
macOS:
brew install protobuf go jq -
Debian/Ubuntu:
sudo apt-get update && sudo apt-get install -y protobuf-compiler golang jq
-
-
protoc-gen-jsonschema plugin
# Install via Go (requires Go to be installed first): go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest -
Clone googleapis repository
# Clone to a location like $HOME/googleapis git clone https://github.com/googleapis/googleapis.git $HOME/googleapis export GOOGLEAPIS_DIR=$HOME/googleapis # To persist this, add the export command to your shell profile (e.g., ~/.zshrc or ~/.bashrc) echo 'export GOOGLEAPIS_DIR=$HOME/googleapis' >> ~/.bashrc -
Python documentation dependencies
# Create and activate virtual environment: python3 -m venv .venv-docs source .venv-docs/bin/activate # Install requirements: pip install -r requirements-docs.txt
Building the A2A JSON Artifact on macOS/Linux
Once all prerequisites are installed:
# Run the build script:
./scripts/build_docs.sh
This script handles all necessary steps to generate the a2a.json artifact and build the documentation site.
Windows
Windows Prerequisites
-
Python with pip (for MkDocs)
# Install Python from python.org or via Microsoft Store # Verify installation: python --version pip --version -
Protocol Buffers compiler (protoc)
# Install via WinGet (recommended): winget install Google.Protobuf # Verify installation: protoc --version -
Go programming language (for protoc-gen-jsonschema plugin)
# Install via WinGet: winget install GoLang.Go # Or download from https://golang.org/dl/ # Verify installation: go version -
protoc-gen-jsonschema plugin
# Install via Go (requires Go to be installed first): go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest # Verify installation (should be in your Go bin directory): protoc-gen-jsonschema --version -
jq (JSON processor)
# Install via WinGet: winget install jqlang.jq # Verify installation: jq --version -
Clone googleapis repository
# Clone to any location and set environment variable: git clone https://github.com/googleapis/googleapis.git C:\path\to\googleapis $env:GOOGLEAPIS_DIR = "C:\path\to\googleapis" # To persist this setting, add the following line to your PowerShell profile. # You can open your profile for editing by running: notepad $PROFILE $env:GOOGLEAPIS_DIR = "C:\path\to\googleapis" -
Python documentation dependencies
# Create and activate virtual environment: python -m venv .venv-docs .\.venv-docs\Scripts\Activate.ps1 # Install requirements: pip install -r requirements-docs.txt
Building the A2A JSON Artifact on Windows
Once all prerequisites are installed:
# Run the build script:
.\scripts\build_docs.ps1
# The documentation will be generated in the ./site directory
# Open site/index.html in your browser to view locally
The build script will:
- Generate JSON Schema from Protocol Buffer definitions
- Build the MkDocs site with all content
Troubleshooting
- protoc errors: Ensure both
protocand the googleapis directory are properly configured - jq not found: Ensure jq is installed and in your
PATH - Python import errors: Activate the virtual environment and ensure all requirements are installed
- Missing schemas: Check that
protoc-gen-jsonschemais in yourPATH(rungo env GOPATHto find Go bin directory)
Future Work
Planned improvements include:
- Optional OpenAPI v3 conversion and publishing a draft 2020-12
components.schemasbundle. - Automatic alias injection for deprecated names (anyOf wrapper) to ease migrations.
- Validation step ensuring no generated artifacts are reintroduced into git.