Skip to content

Commit b078419

Browse files
darrelmillermuscarielloholtskinnergemini-code-assist[bot]Tehsmash
authored
docs(spec): Large refactor of specification to separate application protocol definition from mapping to transports. (#1160)
Related to #1151 Fixes #998 Fixes #1091 Fixes #1072 Fixes #1058 Fixes #975 Fixes #1105 Fixes #989 Fixes #1189 Fixes #1187 Fixes #1177 Fixes #1180 Fixes #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>
1 parent 5f26091 commit b078419

32 files changed

Lines changed: 4328 additions & 7042 deletions

‎.devcontainer/README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# A2A Development Container
2+
3+
This devcontainer provides a fully configured development environment for the A2A project with all required dependencies pre-installed.
4+
5+
## What's Included
6+
7+
### Build Tools
8+
9+
- **protoc** (v28.3) - Protocol Buffers compiler
10+
- **protoc-gen-jsonschema** (bufbuild) - JSON Schema generator for protobuf
11+
- **jq** (latest) - JSON processor
12+
- **googleapis** - Google API proto definitions
13+
14+
### Development Tools
15+
16+
- **Python 3.12** with all documentation dependencies
17+
- **Go** (latest) - for protoc plugin compilation
18+
19+
### VS Code Extensions
20+
21+
- Python language support with Pylance
22+
- Buf for Protocol Buffers
23+
- Code Spell Checker
24+
25+
## Usage
26+
27+
### Opening in VS Code
28+
29+
1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
30+
2. Open this repository in VS Code
31+
3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container")
32+
4. Wait for the container to build and dependencies to install
33+
34+
### Building Documentation
35+
36+
Once inside the container:
37+
38+
```bash
39+
# Build all documentation
40+
./scripts/build_docs.sh
41+
42+
# Convert proto to JSON Schema only
43+
./scripts/proto_to_json_schema.sh specification/json/a2a.json
44+
```
45+
46+
### GitHub Codespaces
47+
48+
This devcontainer configuration also works with GitHub Codespaces:
49+
50+
1. Go to the repository on GitHub
51+
2. Click "Code" → "Codespaces" → "Create codespace on [branch]"
52+
3. Wait for the environment to be provisioned
53+
54+
## Benefits
55+
56+
- **Reproducible builds**: Everyone uses the same tool versions
57+
- **No local setup**: No need to install protoc, jq, etc. on your host machine
58+
- **Quick onboarding**: New contributors can start developing immediately
59+
- **CI/CD alignment**: Same environment as CI can use similar container
60+
61+
## Customization
62+
63+
To modify the environment:
64+
65+
- **Add tools**: Edit `.devcontainer/setup.sh`
66+
- **Change Python/Go versions**: Edit `features` in `devcontainer.json`
67+
- **Add VS Code extensions**: Edit `customizations.vscode.extensions` in `devcontainer.json`
68+
69+
## Troubleshooting
70+
71+
### Container build fails
72+
73+
```bash
74+
# Rebuild without cache
75+
Dev Containers: Rebuild Container (without cache)
76+
```
77+
78+
### Tools not found after setup
79+
80+
```bash
81+
# Re-run setup script manually
82+
bash .devcontainer/setup.sh
83+
```

‎.devcontainer/devcontainer.json‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"name": "A2A Development",
3+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
4+
"features": {
5+
"ghcr.io/devcontainers/features/python:1": {
6+
"version": "3.12"
7+
},
8+
"ghcr.io/devcontainers/features/go:1": {
9+
"version": "latest"
10+
},
11+
"ghcr.io/devcontainers/features/node:1": {
12+
"version": "lts"
13+
}
14+
},
15+
"postCreateCommand": "bash .devcontainer/setup.sh",
16+
"customizations": {
17+
"vscode": {
18+
"extensions": [
19+
"ms-python.python",
20+
"ms-python.vscode-pylance",
21+
"bufbuild.vscode-buf",
22+
"streetsidesoftware.code-spell-checker"
23+
],
24+
"settings": {
25+
"python.defaultInterpreterPath": "/usr/local/bin/python"
26+
}
27+
}
28+
},
29+
"forwardPorts": [
30+
8000
31+
],
32+
"remoteUser": "vscode"
33+
}

‎.devcontainer/setup.sh‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
#!/bin/bash
2+
set -euo pipefail
3+
4+
echo "==> Setting up A2A development environment..."
5+
6+
# Install system dependencies
7+
echo "→ Installing system packages..."
8+
sudo apt-get update
9+
sudo apt-get install -y \
10+
curl \
11+
git \
12+
jq \
13+
unzip
14+
15+
# Install Protocol Buffers compiler
16+
echo "→ Installing protoc..."
17+
PROTOC_VERSION="28.3"
18+
PROTOC_ZIP="protoc-${PROTOC_VERSION}-linux-x86_64.zip"
19+
curl -fsSL -o /tmp/protoc.zip "https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/${PROTOC_ZIP}"
20+
sudo unzip -q /tmp/protoc.zip -d /usr/local
21+
rm /tmp/protoc.zip
22+
23+
# Install protoc-gen-jsonschema (bufbuild)
24+
echo "→ Installing protoc-gen-jsonschema..."
25+
go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest
26+
go_bin_path="$(go env GOPATH)/bin/protoc-gen-jsonschema"
27+
if [ -f "$go_bin_path" ]; then
28+
sudo cp "$go_bin_path" /usr/local/bin/
29+
fi
30+
31+
# Install buf CLI
32+
echo "→ Installing buf..."
33+
go install github.com/bufbuild/buf/cmd/buf@latest
34+
go_bin_path="$(go env GOPATH)/bin/buf"
35+
if [ -f "$go_bin_path" ]; then
36+
sudo cp "$go_bin_path" /usr/local/bin/
37+
fi
38+
39+
# Install googleapis proto files to third_party
40+
echo "→ Installing googleapis..."
41+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
42+
WORKSPACE_DIR="$(dirname "$SCRIPT_DIR")"
43+
GOOGLEAPIS_DIR="$WORKSPACE_DIR/third_party/googleapis"
44+
if [ ! -d "$GOOGLEAPIS_DIR" ]; then
45+
mkdir -p "$WORKSPACE_DIR/third_party"
46+
cd "$WORKSPACE_DIR/third_party"
47+
git clone --depth 1 https://github.com/googleapis/googleapis.git
48+
cd "$WORKSPACE_DIR"
49+
fi
50+
51+
# Install Python dependencies for documentation
52+
echo "→ Installing Python packages..."
53+
pip install --no-cache-dir -r requirements-docs.txt
54+
55+
# Verify installations
56+
echo ""
57+
echo "==> Verifying installations..."
58+
echo "protoc: $(protoc --version)"
59+
echo "protoc-gen-jsonschema: $(which protoc-gen-jsonschema)"
60+
echo "buf: $(buf --version 2>/dev/null || echo 'not found')"
61+
echo "jq: $(jq --version)"
62+
echo "python: $(python --version)"
63+
echo "go: $(go version)"
64+
65+
echo ""
66+
echo "✓ Development environment ready!"
67+
echo ""
68+
echo "To build documentation:"
69+
echo " ./scripts/build_docs.sh"
70+
echo ""
71+
echo "To convert proto to JSON Schema:"
72+
echo " ./scripts/proto_to_json_schema.sh specification/json/a2a.json"

‎.gitattributes‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Documentation overrides
22
/docs/** linguist-documentation=true
33
/.mkdocs/** linguist-documentation=true
4-
/specification/json/a2a.json linguist-generated=true
4+
# Removed committed a2a.json; generated at build time.
55
noxfile.py linguist-vendored=true
66

77
# Merge and diff setting

‎.github/actions/spelling/allow.txt‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Cpzuhi
2929
DDo
3030
DGT
3131
DHDe
32+
Debian
3233
Djq
3334
Dotnet
3435
EBFF
@@ -49,6 +50,7 @@ GitVote
4950
HBz
5051
HKRMw
5152
HRA
53+
HSTS
5254
HXo
5355
Hackathon
5456
IFdvcmxk
@@ -59,6 +61,7 @@ Imh
5961
Imprd
6062
JFUz
6163
JHv
64+
JIUz
6265
JPY
6366
JWKS
6467
JWS
@@ -89,6 +92,7 @@ RPCs
8992
RUF
9093
SLAs
9194
SLF
95+
SSLv
9296
Solax
9397
TJS
9498
TMDB
@@ -103,6 +107,7 @@ WQi
103107
WVw
104108
Witteveen
105109
XBs
110+
XVCJ
106111
Xca
107112
YQGt
108113
YTAKFW
@@ -129,13 +134,15 @@ agentskill
129134
agntcy
130135
agp
131136
ainvoke
137+
aip
132138
airbnb
133139
aldridge
134140
alloydb
135141
amannn
136142
aparse
137143
aproject
138144
aprotocol
145+
argjson
139146
arxiv
140147
askmarvin
141148
asyncclick
@@ -149,6 +156,7 @@ beeai
149156
bufbuild
150157
bzr
151158
cae
159+
canceltask
152160
ccc
153161
cdn
154162
ceee
@@ -157,6 +165,7 @@ cls
157165
coc
158166
codegen
159167
codeowner
168+
codespace
160169
crewai
161170
datamodel
162171
datapart
@@ -181,9 +190,11 @@ euo
181190
evt
182191
excinfo
183192
faa
193+
faf
184194
fafd
185195
fdebd
186196
ffbb
197+
fff
187198
firewalls
188199
flightbook
189200
forbes
@@ -196,11 +207,13 @@ geneknit
196207
genkit
197208
genproto
198209
georoute
210+
gettask
199211
gettickets
200212
gitvote
201213
gle
202214
googleai
203215
googleapi
216+
googleapis
204217
googleblog
205218
gpt
206219
gstatic
@@ -216,6 +229,8 @@ inmemory
216229
ipynb
217230
iss
218231
jherr
232+
jku
233+
jqlang
219234
jti
220235
jwks
221236
konami
@@ -224,12 +239,16 @@ langgraph
224239
linenums
225240
linkedin
226241
linting
242+
listtasks
227243
llm
228244
llms
229245
lng
246+
logtostderr
230247
marvin
231248
mcp
249+
mcr
232250
mesop
251+
mikefarah
233252
mindsdb
234253
motherlode
235254
mozilla
@@ -248,6 +267,8 @@ oidc
248267
ollama
249268
oneof
250269
openapis
270+
openapiv
271+
openapiv2
251272
oreilly
252273
postgres
253274
postgresql
@@ -256,31 +277,36 @@ prefecthq
256277
protoc
257278
protolint
258279
pyguide
280+
pylance
259281
pymdownx
260282
pypa
261283
pypackages
262284
pytype
263285
pyupgrade
264286
qwq
265287
rcm
288+
regen
266289
repomapr
267290
reportgen
268291
reposted
269292
rst
270293
rvelicheti
271294
scm
272295
sllm
296+
sourced
273297
sourcing
274298
squidfunk
275299
srcs
276300
sse
301+
sss
277302
stateclass
278303
stephenh
279304
styleguide
280305
svn
281306
systemctl
282307
tagwords
283308
tasksget
309+
taskslist
284310
taskssend
285311
taskstate
286312
taskstatus
@@ -293,6 +319,7 @@ tracestate
293319
ugc
294320
undoc
295321
utm
322+
venv-docs
296323
versioned
297324
vnd
298325
voa
@@ -302,6 +329,7 @@ webform
302329
webpage
303330
whatwg
304331
wikipedia
332+
winget
305333
wsgi
306334
wwwwwwww
307335
xxxxx

‎.github/linters/.protolint.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
lint:
2+
rules:
3+
remove:
4+
- MAX_LINE_LENGTH

0 commit comments

Comments
 (0)