Compare commits
133 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ae6a562d5d | ||
|
|
434d1fecbb | ||
|
|
c5104cec72 | ||
|
|
7ff1004159 | ||
|
|
757f0ec6d0 | ||
|
|
3947dacff8 | ||
|
|
8dda73b3b4 | ||
|
|
b9f03d4c96 | ||
|
|
f1b45c522a | ||
|
|
a40261c464 | ||
|
|
43bddf8cc1 | ||
|
|
3c0e23e996 | ||
|
|
66df070988 | ||
|
|
74c7c62286 | ||
|
|
c1169f4572 | ||
|
|
f991a08f2c | ||
|
|
5ac9d2c7d7 | ||
|
|
72d1459ddb | ||
|
|
32a7d3a0bd | ||
|
|
7b900e77be | ||
|
|
3c1a5ff473 | ||
|
|
7df7685561 | ||
|
|
b750332f4c | ||
|
|
625146ede8 | ||
|
|
f86c799f09 | ||
|
|
4f77f1bdd0 | ||
|
|
ee335737c9 | ||
|
|
6845a87b50 | ||
|
|
1736957556 | ||
|
|
087604615d | ||
|
|
727168fe1f | ||
|
|
149cb82d38 | ||
|
|
7415773696 | ||
|
|
5fed760884 | ||
|
|
0833a5f5fd | ||
|
|
e2eb7d2b4b | ||
|
|
2c9bc7ecd9 | ||
|
|
477a0ee304 | ||
|
|
601c408aec | ||
|
|
aca981cee3 | ||
|
|
dec790aa06 | ||
|
|
010b9cc936 | ||
|
|
d1ed0da587 | ||
|
|
dbb1bf8e60 | ||
|
|
789bc73d8b | ||
|
|
4890b77d6f | ||
|
|
a3e2e1f8c6 | ||
|
|
629190aea9 | ||
|
|
8bf133addc | ||
|
|
7245512250 | ||
|
|
1997c9d630 | ||
|
|
b2daedcadf | ||
|
|
857a995a3d | ||
|
|
393898dfee | ||
|
|
cf735cb870 | ||
|
|
c441b910b6 | ||
|
|
a54e80904a | ||
|
|
73d5f59a32 | ||
|
|
a9cffef493 | ||
|
|
fde2bd8da8 | ||
|
|
cd16c5276b | ||
|
|
05603f973f | ||
|
|
f63f6551c5 | ||
|
|
68727dcb35 | ||
|
|
7cf67271cf | ||
|
|
a3d78dcad3 | ||
|
|
c24b1151d1 | ||
|
|
3f6ad2d9d6 | ||
|
|
741ccaa3af | ||
|
|
8c17173de3 | ||
|
|
ed97dea512 | ||
|
|
ce73987171 | ||
|
|
47eda410c3 | ||
|
|
d22ee06d36 | ||
|
|
6292104e35 | ||
|
|
b86d8bb2ed | ||
|
|
b03d141aea | ||
|
|
2596c1c5e0 | ||
|
|
227e2493c3 | ||
|
|
f6129cafa1 | ||
|
|
59ea3f614c | ||
|
|
f6e786c652 | ||
|
|
871924e804 | ||
|
|
4dd980f6ff | ||
|
|
0655ff324a | ||
|
|
bfae8f7791 | ||
|
|
810eaa1c6e | ||
|
|
3e6c7db907 | ||
|
|
5b101cce0f | ||
|
|
19e2059852 | ||
|
|
229d005bff | ||
|
|
bb527d4299 | ||
|
|
d14f410711 | ||
|
|
c768a44da0 | ||
|
|
92e6fb712e | ||
|
|
057295311b | ||
|
|
4befaeacaf | ||
|
|
f9a8f5b85d | ||
|
|
ca615d78e5 | ||
|
|
40d6286fbe | ||
|
|
0e204bf878 | ||
|
|
525ff38e5f | ||
|
|
e6c5699c55 | ||
|
|
a4afeea788 | ||
|
|
1e5f462064 | ||
|
|
e8c0f0fd61 | ||
|
|
cc8e67ebea | ||
|
|
48f58461c2 | ||
|
|
60f83c3faa | ||
|
|
a336a5a484 | ||
|
|
d803564477 | ||
|
|
1a2d580a3e | ||
|
|
33f065d3da | ||
|
|
dec450b3c4 | ||
|
|
290c87f0c2 | ||
|
|
1004abcafc | ||
|
|
22d15cd172 | ||
|
|
6e65c7fbaf | ||
|
|
f74fe490a8 | ||
|
|
c56ea72d5b | ||
|
|
c42ef44805 | ||
|
|
c196824396 | ||
|
|
8704c88a72 | ||
|
|
1bd263f537 | ||
|
|
cfbce32cb0 | ||
|
|
b6ef9eec55 | ||
|
|
d381cea9d0 | ||
|
|
5792804372 | ||
|
|
18ca2533bf | ||
|
|
d8dd640d2b | ||
|
|
498d3ab398 | ||
|
|
61d1e3a6f9 | ||
|
|
b078419954 |
83
.devcontainer/README.md
Normal file
@ -0,0 +1,83 @@
|
||||
# A2A Development Container
|
||||
|
||||
This devcontainer provides a fully configured development environment for the A2A project with all required dependencies pre-installed.
|
||||
|
||||
## What's Included
|
||||
|
||||
### Build Tools
|
||||
|
||||
- **protoc** (v28.3) - Protocol Buffers compiler
|
||||
- **protoc-gen-jsonschema** (bufbuild) - JSON Schema generator for protobuf
|
||||
- **jq** (latest) - JSON processor
|
||||
- **googleapis** - Google API proto definitions
|
||||
|
||||
### Development Tools
|
||||
|
||||
- **Python 3.12** with all documentation dependencies
|
||||
- **Go** (latest) - for protoc plugin compilation
|
||||
|
||||
### VS Code Extensions
|
||||
|
||||
- Python language support with Pylance
|
||||
- Buf for Protocol Buffers
|
||||
- Code Spell Checker
|
||||
|
||||
## Usage
|
||||
|
||||
### Opening in VS Code
|
||||
|
||||
1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
|
||||
2. Open this repository in VS Code
|
||||
3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container")
|
||||
4. Wait for the container to build and dependencies to install
|
||||
|
||||
### Building Documentation
|
||||
|
||||
Once inside the container:
|
||||
|
||||
```bash
|
||||
# Build all documentation
|
||||
./scripts/build_docs.sh
|
||||
|
||||
# Convert proto to JSON Schema only
|
||||
./scripts/proto_to_json_schema.sh specification/json/a2a.json
|
||||
```
|
||||
|
||||
### GitHub Codespaces
|
||||
|
||||
This devcontainer configuration also works with GitHub Codespaces:
|
||||
|
||||
1. Go to the repository on GitHub
|
||||
2. Click "Code" → "Codespaces" → "Create codespace on [branch]"
|
||||
3. Wait for the environment to be provisioned
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Reproducible builds**: Everyone uses the same tool versions
|
||||
- **No local setup**: No need to install protoc, jq, etc. on your host machine
|
||||
- **Quick onboarding**: New contributors can start developing immediately
|
||||
- **CI/CD alignment**: Same environment as CI can use similar container
|
||||
|
||||
## Customization
|
||||
|
||||
To modify the environment:
|
||||
|
||||
- **Add tools**: Edit `.devcontainer/setup.sh`
|
||||
- **Change Python/Go versions**: Edit `features` in `devcontainer.json`
|
||||
- **Add VS Code extensions**: Edit `customizations.vscode.extensions` in `devcontainer.json`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container build fails
|
||||
|
||||
```bash
|
||||
# Rebuild without cache
|
||||
Dev Containers: Rebuild Container (without cache)
|
||||
```
|
||||
|
||||
### Tools not found after setup
|
||||
|
||||
```bash
|
||||
# Re-run setup script manually
|
||||
bash .devcontainer/setup.sh
|
||||
```
|
||||
33
.devcontainer/devcontainer.json
Normal file
@ -0,0 +1,33 @@
|
||||
{
|
||||
"name": "A2A Development",
|
||||
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
||||
"features": {
|
||||
"ghcr.io/devcontainers/features/python:1": {
|
||||
"version": "3.12"
|
||||
},
|
||||
"ghcr.io/devcontainers/features/go:1": {
|
||||
"version": "latest"
|
||||
},
|
||||
"ghcr.io/devcontainers/features/node:1": {
|
||||
"version": "lts"
|
||||
}
|
||||
},
|
||||
"postCreateCommand": "bash .devcontainer/setup.sh",
|
||||
"customizations": {
|
||||
"vscode": {
|
||||
"extensions": [
|
||||
"ms-python.python",
|
||||
"ms-python.vscode-pylance",
|
||||
"bufbuild.vscode-buf",
|
||||
"streetsidesoftware.code-spell-checker"
|
||||
],
|
||||
"settings": {
|
||||
"python.defaultInterpreterPath": "/usr/local/bin/python"
|
||||
}
|
||||
}
|
||||
},
|
||||
"forwardPorts": [
|
||||
8000
|
||||
],
|
||||
"remoteUser": "vscode"
|
||||
}
|
||||
72
.devcontainer/setup.sh
Executable file
@ -0,0 +1,72 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
echo "==> Setting up A2A development environment..."
|
||||
|
||||
# Install system dependencies
|
||||
echo "→ Installing system packages..."
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y \
|
||||
curl \
|
||||
git \
|
||||
jq \
|
||||
unzip
|
||||
|
||||
# Install Protocol Buffers compiler
|
||||
echo "→ Installing protoc..."
|
||||
PROTOC_VERSION="28.3"
|
||||
PROTOC_ZIP="protoc-${PROTOC_VERSION}-linux-x86_64.zip"
|
||||
curl -fsSL -o /tmp/protoc.zip "https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/${PROTOC_ZIP}"
|
||||
sudo unzip -q /tmp/protoc.zip -d /usr/local
|
||||
rm /tmp/protoc.zip
|
||||
|
||||
# Install protoc-gen-jsonschema (bufbuild)
|
||||
echo "→ Installing protoc-gen-jsonschema..."
|
||||
go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest
|
||||
go_bin_path="$(go env GOPATH)/bin/protoc-gen-jsonschema"
|
||||
if [ -f "$go_bin_path" ]; then
|
||||
sudo cp "$go_bin_path" /usr/local/bin/
|
||||
fi
|
||||
|
||||
# Install buf CLI
|
||||
echo "→ Installing buf..."
|
||||
go install github.com/bufbuild/buf/cmd/buf@latest
|
||||
go_bin_path="$(go env GOPATH)/bin/buf"
|
||||
if [ -f "$go_bin_path" ]; then
|
||||
sudo cp "$go_bin_path" /usr/local/bin/
|
||||
fi
|
||||
|
||||
# Install googleapis proto files to third_party
|
||||
echo "→ Installing googleapis..."
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
WORKSPACE_DIR="$(dirname "$SCRIPT_DIR")"
|
||||
GOOGLEAPIS_DIR="$WORKSPACE_DIR/third_party/googleapis"
|
||||
if [ ! -d "$GOOGLEAPIS_DIR" ]; then
|
||||
mkdir -p "$WORKSPACE_DIR/third_party"
|
||||
cd "$WORKSPACE_DIR/third_party"
|
||||
git clone --depth 1 https://github.com/googleapis/googleapis.git
|
||||
cd "$WORKSPACE_DIR"
|
||||
fi
|
||||
|
||||
# Install Python dependencies for documentation
|
||||
echo "→ Installing Python packages..."
|
||||
pip install --no-cache-dir -r requirements-docs.txt
|
||||
|
||||
# Verify installations
|
||||
echo ""
|
||||
echo "==> Verifying installations..."
|
||||
echo "protoc: $(protoc --version)"
|
||||
echo "protoc-gen-jsonschema: $(which protoc-gen-jsonschema)"
|
||||
echo "buf: $(buf --version 2>/dev/null || echo 'not found')"
|
||||
echo "jq: $(jq --version)"
|
||||
echo "python: $(python --version)"
|
||||
echo "go: $(go version)"
|
||||
|
||||
echo ""
|
||||
echo "✓ Development environment ready!"
|
||||
echo ""
|
||||
echo "To build documentation:"
|
||||
echo " ./scripts/build_docs.sh"
|
||||
echo ""
|
||||
echo "To convert proto to JSON Schema:"
|
||||
echo " ./scripts/proto_to_json_schema.sh specification/json/a2a.json"
|
||||
2
.gitattributes
vendored
@ -1,7 +1,7 @@
|
||||
# Documentation overrides
|
||||
/docs/** linguist-documentation=true
|
||||
/.mkdocs/** linguist-documentation=true
|
||||
/specification/json/a2a.json linguist-generated=true
|
||||
# Removed committed a2a.json; generated at build time.
|
||||
noxfile.py linguist-vendored=true
|
||||
|
||||
# Merge and diff setting
|
||||
|
||||
12
.github/CODEOWNERS
vendored
@ -5,10 +5,14 @@
|
||||
# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax
|
||||
|
||||
* @a2aproject/a2a-tsc
|
||||
docs/ @a2aproject/tech-writing
|
||||
docs/ @a2aproject/a2a-tsc
|
||||
scripts/ @a2aproject/a2a-tsc
|
||||
specification/ @a2aproject/a2a-tsc
|
||||
types/ @a2aproject/a2a-tsc
|
||||
docs/specification.md @a2aproject/a2a-tsc
|
||||
GOVERNANCE.md @a2aproject/a2a-tsc
|
||||
.mkdocs.yml @a2aproject/tech-writing
|
||||
|
||||
.mkdocs/ @a2aproject/a2a-tsc
|
||||
.mkdocs.yml @a2aproject/a2a-tsc
|
||||
README.md @a2aproject/a2a-tsc
|
||||
.gemini/ @a2aproject/a2a-tsc
|
||||
.mkdocs/ @a2aproject/a2a-tsc
|
||||
.github/ @a2aproject/a2a-tsc
|
||||
|
||||
74
.github/actions/spelling/allow.txt
vendored
@ -6,6 +6,7 @@ ACard
|
||||
AClient
|
||||
ACo
|
||||
ADK
|
||||
ADR
|
||||
AError
|
||||
AExecutor
|
||||
AGP
|
||||
@ -18,8 +19,12 @@ AService
|
||||
ASq
|
||||
AStarlette
|
||||
AUTOCOMMIT
|
||||
Abhimanyu
|
||||
Agentspace
|
||||
Agno
|
||||
Autogen
|
||||
Bahasa
|
||||
Besen
|
||||
Blogs
|
||||
CAs
|
||||
CLIs
|
||||
@ -29,11 +34,14 @@ Cpzuhi
|
||||
DDo
|
||||
DGT
|
||||
DHDe
|
||||
Datetimes
|
||||
Debian
|
||||
Djq
|
||||
Dotnet
|
||||
EBFF
|
||||
EUR
|
||||
EUg
|
||||
Espa
|
||||
FBT
|
||||
FHIR
|
||||
Fbr
|
||||
@ -49,6 +57,7 @@ GitVote
|
||||
HBz
|
||||
HKRMw
|
||||
HRA
|
||||
HSTS
|
||||
HXo
|
||||
Hackathon
|
||||
IFdvcmxk
|
||||
@ -59,6 +68,7 @@ Imh
|
||||
Imprd
|
||||
JFUz
|
||||
JHv
|
||||
JIUz
|
||||
JPY
|
||||
JWKS
|
||||
JWS
|
||||
@ -67,28 +77,39 @@ Jhb
|
||||
Jra
|
||||
KGgo
|
||||
KRW
|
||||
LFX
|
||||
LHR
|
||||
LJcvt
|
||||
LLM
|
||||
LLMs
|
||||
Lindfors
|
||||
Lix
|
||||
MSIs
|
||||
MWpm
|
||||
Mapr
|
||||
Mvosg
|
||||
Nszl
|
||||
OIDC
|
||||
OOa
|
||||
OTP
|
||||
Ollama
|
||||
PLE
|
||||
PLW
|
||||
PMEEi
|
||||
PTH
|
||||
Petschulat
|
||||
Polski
|
||||
Portugu
|
||||
QFdk
|
||||
Qvandrcy
|
||||
RFCs
|
||||
RPCs
|
||||
RUF
|
||||
SFDC
|
||||
SLAs
|
||||
SLF
|
||||
SSLv
|
||||
Siwach
|
||||
Solax
|
||||
TJS
|
||||
TMDB
|
||||
@ -97,12 +118,14 @@ URLTo
|
||||
Upserting
|
||||
Urke
|
||||
VBORw
|
||||
VHc
|
||||
Vsb
|
||||
WHB
|
||||
WQi
|
||||
WVw
|
||||
Witteveen
|
||||
XBs
|
||||
XVCJ
|
||||
Xca
|
||||
YQGt
|
||||
YTAKFW
|
||||
@ -120,15 +143,20 @@ aacacac
|
||||
aboutasha
|
||||
achat
|
||||
aconnect
|
||||
actioncard
|
||||
adk
|
||||
adr
|
||||
adrs
|
||||
afet
|
||||
affef
|
||||
agentcard
|
||||
agentic
|
||||
agentskill
|
||||
agno
|
||||
agntcy
|
||||
agp
|
||||
ainvoke
|
||||
aip
|
||||
airbnb
|
||||
aldridge
|
||||
alloydb
|
||||
@ -136,6 +164,7 @@ amannn
|
||||
aparse
|
||||
aproject
|
||||
aprotocol
|
||||
argjson
|
||||
arxiv
|
||||
askmarvin
|
||||
asyncclick
|
||||
@ -146,17 +175,23 @@ backstory
|
||||
backticks
|
||||
bbb
|
||||
beeai
|
||||
boq
|
||||
bufbuild
|
||||
bzr
|
||||
cae
|
||||
canceltask
|
||||
ccc
|
||||
cdn
|
||||
ceee
|
||||
cfe
|
||||
chrusty
|
||||
cls
|
||||
coc
|
||||
codegen
|
||||
codeowner
|
||||
codespace
|
||||
codewiki
|
||||
cpb
|
||||
crewai
|
||||
datamodel
|
||||
datapart
|
||||
@ -166,6 +201,7 @@ dcfa
|
||||
dde
|
||||
deepwiki
|
||||
direnv
|
||||
dlai
|
||||
docstrings
|
||||
documentai
|
||||
dotnet
|
||||
@ -181,9 +217,11 @@ euo
|
||||
evt
|
||||
excinfo
|
||||
faa
|
||||
faf
|
||||
fafd
|
||||
fdebd
|
||||
ffbb
|
||||
fff
|
||||
firewalls
|
||||
flightbook
|
||||
forbes
|
||||
@ -196,41 +234,59 @@ geneknit
|
||||
genkit
|
||||
genproto
|
||||
georoute
|
||||
gettask
|
||||
gettickets
|
||||
gitleaks
|
||||
gitvote
|
||||
gle
|
||||
googleai
|
||||
googleapi
|
||||
googleapis
|
||||
googleblog
|
||||
gpt
|
||||
gstatic
|
||||
gweb
|
||||
hackathon
|
||||
hackathons
|
||||
hexpm
|
||||
hqdefault
|
||||
hughesthe
|
||||
iana
|
||||
iat
|
||||
ietf
|
||||
inardini
|
||||
inbox
|
||||
inmemory
|
||||
ipynb
|
||||
iss
|
||||
jherr
|
||||
jku
|
||||
jqlang
|
||||
jti
|
||||
jwks
|
||||
kadirpekel
|
||||
keystores
|
||||
konami
|
||||
kty
|
||||
langgraph
|
||||
lerhaupt
|
||||
lfx
|
||||
linenums
|
||||
linkedin
|
||||
linting
|
||||
listtasks
|
||||
litellm
|
||||
llm
|
||||
llms
|
||||
lng
|
||||
logtostderr
|
||||
marvin
|
||||
mcp
|
||||
mcr
|
||||
mesop
|
||||
mikefarah
|
||||
mindsdb
|
||||
mintlify
|
||||
motherlode
|
||||
mozilla
|
||||
msword
|
||||
@ -247,15 +303,20 @@ octicons
|
||||
oidc
|
||||
ollama
|
||||
oneof
|
||||
openaitx
|
||||
openapis
|
||||
openapiv
|
||||
openapiv2
|
||||
oreilly
|
||||
postgres
|
||||
postgresql
|
||||
pqr
|
||||
prefecthq
|
||||
protoc
|
||||
protojson
|
||||
protolint
|
||||
pyguide
|
||||
pylance
|
||||
pymdownx
|
||||
pypa
|
||||
pypackages
|
||||
@ -263,45 +324,58 @@ pytype
|
||||
pyupgrade
|
||||
qwq
|
||||
rcm
|
||||
regen
|
||||
repomapr
|
||||
reportgen
|
||||
reposted
|
||||
rst
|
||||
rvelicheti
|
||||
sandijean
|
||||
scm
|
||||
siwachabhi
|
||||
sllm
|
||||
sourced
|
||||
sourcing
|
||||
squidfunk
|
||||
srcs
|
||||
sse
|
||||
sss
|
||||
stateclass
|
||||
stephenh
|
||||
styleguide
|
||||
svn
|
||||
systemctl
|
||||
tablefmt
|
||||
tagwords
|
||||
tasksget
|
||||
taskslist
|
||||
taskssend
|
||||
taskstate
|
||||
taskstatus
|
||||
textpart
|
||||
threadsafe
|
||||
tiangolo
|
||||
toctree
|
||||
tok
|
||||
tolgaki
|
||||
tomtom
|
||||
toolkits
|
||||
tracestate
|
||||
ugc
|
||||
undoc
|
||||
utm
|
||||
venv-docs
|
||||
versioned
|
||||
vnd
|
||||
voa
|
||||
vscode
|
||||
vvvvvvvv
|
||||
weavehacks
|
||||
webform
|
||||
webpage
|
||||
whatwg
|
||||
wikipedia
|
||||
winget
|
||||
wsgi
|
||||
wwwwwwww
|
||||
xxxxx
|
||||
|
||||
6
.github/actions/spelling/expect.txt
vendored
Normal file
@ -0,0 +1,6 @@
|
||||
Abhimanyu
|
||||
lfx
|
||||
Petschulat
|
||||
SFDC
|
||||
Siwach
|
||||
siwachabhi
|
||||
@ -59,11 +59,6 @@
|
||||
# Should be `in front of`
|
||||
\bin from of\b
|
||||
|
||||
# Should be `into`
|
||||
# when not phrasal and when `in order to` would be wrong:
|
||||
# https://thewritepractice.com/into-vs-in-to/
|
||||
\sin to\s(?!if\b)
|
||||
|
||||
# Should be `use`
|
||||
\sin used by\b
|
||||
|
||||
@ -79,9 +74,6 @@
|
||||
# Should be `perform its`
|
||||
\bperform it's\b
|
||||
|
||||
# Should be `opt-in`
|
||||
(?<!\sfor)\sopt in\s
|
||||
|
||||
# Should be `less than`
|
||||
\bless then\b
|
||||
|
||||
|
||||
3
.github/linters/.jscpd.json
vendored
@ -5,7 +5,8 @@
|
||||
"**/images/**",
|
||||
"**/samples/**",
|
||||
"**/tests/**",
|
||||
"**/.git/**"
|
||||
"**/.git/**",
|
||||
"**/a2a_logo/**"
|
||||
],
|
||||
"threshold": 3,
|
||||
"reporters": ["html", "markdown"]
|
||||
|
||||
4
.github/linters/.protolint.yaml
vendored
Normal file
@ -0,0 +1,4 @@
|
||||
lint:
|
||||
rules:
|
||||
remove:
|
||||
- MAX_LINE_LENGTH
|
||||
22
.github/super-linter.env
vendored
Normal file
@ -0,0 +1,22 @@
|
||||
SHELLCHECK_OPTS=-e SC1091 -e SC2086
|
||||
VALIDATE_ALL_CODEBASE=false
|
||||
FILTER_REGEX_EXCLUDE=^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|MAINTAINERS.md
|
||||
VALIDATE_BASH=true
|
||||
VALIDATE_BASH_EXEC=true
|
||||
VALIDATE_CSS=true
|
||||
VALIDATE_EDITORCONFIG=true
|
||||
VALIDATE_GIT_MERGE_CONFLICT_MARKERS=true
|
||||
VALIDATE_GITHUB_ACTIONS=true
|
||||
VALIDATE_GITLEAKS=true
|
||||
VALIDATE_JSCPD=true
|
||||
VALIDATE_JSON=true
|
||||
VALIDATE_MARKDOWN=true
|
||||
VALIDATE_PROTOBUF=true
|
||||
VALIDATE_PYTHON_RUFF=true
|
||||
VALIDATE_SHELL_SHFMT=true
|
||||
VALIDATE_TOML=true
|
||||
VALIDATE_TYPESCRIPT_ES=true
|
||||
VALIDATE_YAML=true
|
||||
TYPESCRIPT_ES_CONFIG_FILE=.eslintrc.js
|
||||
MARKDOWN_CONFIG_FILE=.markdownlint.json
|
||||
PROTOBUF_CONFIG_FILE=.protolint.yaml
|
||||
2
.github/workflows/dispatch-a2a-update.yml
vendored
@ -10,6 +10,8 @@ on:
|
||||
jobs:
|
||||
dispatch:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.repository_owner == 'a2aproject'
|
||||
|
||||
steps:
|
||||
- name: Dispatch repository_dispatch to a2a-python
|
||||
uses: peter-evans/repository-dispatch@v4
|
||||
|
||||
58
.github/workflows/docs.yml
vendored
@ -23,6 +23,11 @@ on:
|
||||
types:
|
||||
- published
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: 'Version to deploy to (e.g., v1.0.0)'
|
||||
required: true
|
||||
default: 'dev'
|
||||
|
||||
jobs:
|
||||
build_and_deploy:
|
||||
@ -35,7 +40,7 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v5
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
fetch-depth: 0
|
||||
@ -50,8 +55,11 @@ jobs:
|
||||
with:
|
||||
python-version: 3.13
|
||||
|
||||
- name: Setup uv
|
||||
uses: astral-sh/setup-uv@v7
|
||||
|
||||
- name: Restore pip cache
|
||||
uses: actions/cache@v4
|
||||
uses: actions/cache@v5
|
||||
with:
|
||||
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements-docs.txt') }}
|
||||
path: ~/.cache/pip
|
||||
@ -61,17 +69,36 @@ jobs:
|
||||
- name: Install documentation dependencies
|
||||
run: pip install --upgrade -r requirements-docs.txt
|
||||
|
||||
- name: Generate and Build Python SDK Docs
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '1.25'
|
||||
|
||||
- name: Install build tools
|
||||
run: |
|
||||
# Find the path to the installed package
|
||||
PACKAGE_PATH=$(python -c "import a2a, os; print(os.path.dirname(a2a.__file__))")
|
||||
echo "Found 'a2a' package at: ${PACKAGE_PATH}"
|
||||
# Install protoc
|
||||
PROTOC_VERSION="28.3"
|
||||
PROTOC_ZIP="protoc-${PROTOC_VERSION}-linux-x86_64.zip"
|
||||
curl -fsSL -o /tmp/protoc.zip "https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/${PROTOC_ZIP}"
|
||||
sudo unzip -q /tmp/protoc.zip -d /usr/local
|
||||
rm /tmp/protoc.zip
|
||||
|
||||
# Generate RST source files from the installed package
|
||||
sphinx-apidoc -f -o docs/sdk/python "${PACKAGE_PATH}"
|
||||
# Install protoc-gen-jsonschema
|
||||
go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest
|
||||
sudo cp "$(go env GOPATH)/bin/protoc-gen-jsonschema" /usr/local/bin/
|
||||
|
||||
# Build the HTML from the generated RST files
|
||||
sphinx-build -b html docs/sdk/python docs/sdk/python/api
|
||||
# Install buf CLI
|
||||
go install github.com/bufbuild/buf/cmd/buf@latest
|
||||
sudo cp "$(go env GOPATH)/bin/buf" /usr/local/bin/
|
||||
|
||||
# Clone googleapis
|
||||
mkdir -p third_party
|
||||
cd third_party
|
||||
git clone --depth 1 https://github.com/googleapis/googleapis.git
|
||||
cd ..
|
||||
|
||||
- name: Generate protocol specification files
|
||||
run: ./scripts/build_docs.sh
|
||||
|
||||
- name: Generate consolidated llms-full.txt file
|
||||
run: bash scripts/build_llms_full.sh
|
||||
@ -106,3 +133,14 @@ jobs:
|
||||
bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}
|
||||
env:
|
||||
GITHUB_EVENT_RELEASE_TAG_NAME: ${{ github.event.release.tag_name }}
|
||||
|
||||
- name: Manually deploy specific version from main
|
||||
if: github.event_name == 'workflow_dispatch'
|
||||
run: |
|
||||
mike deploy --push --update-aliases ${{ github.event.inputs.version }} latest
|
||||
|
||||
echo "Setting 'latest' as the default version for the site..."
|
||||
mike set-default --push latest
|
||||
|
||||
# Re-deploy 404 page
|
||||
bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
69
.github/workflows/generate-a2a-json.yml
vendored
@ -1,69 +0,0 @@
|
||||
name: Auto-generate A2A JSON Schema
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- "types/**"
|
||||
types:
|
||||
- opened
|
||||
- synchronize
|
||||
- reopened
|
||||
|
||||
jobs:
|
||||
generate_json:
|
||||
name: Generate JSON Schema
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v5
|
||||
with:
|
||||
fetch-depth: 0
|
||||
ref: ${{ github.event.pull_request.head.ref }}
|
||||
repository: ${{ github.event.pull_request.head.repo.full_name }}
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v5
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Install dependencies and generate a2a.json
|
||||
working-directory: types
|
||||
run: |
|
||||
npm install
|
||||
npm run generate
|
||||
id: generate_schema
|
||||
|
||||
- name: Configure Git for Bot
|
||||
if: github.event.pull_request.head.repo.full_name == github.repository
|
||||
run: |
|
||||
git config user.name "a2a-bot"
|
||||
git config user.email "a2a-bot@google.com"
|
||||
|
||||
- name: Check for Changes
|
||||
id: git_status
|
||||
run: |
|
||||
git add specification/json/a2a.json
|
||||
if ! git diff --cached --quiet --exit-code; then
|
||||
echo "changes_detected=true" >> "$GITHUB_OUTPUT"
|
||||
echo "a2a.json is not up-to-date with types.ts"
|
||||
else
|
||||
echo "a2a.json is up-to-date."
|
||||
fi
|
||||
|
||||
- name: Commit and Push Changes (if on base repository)
|
||||
if: steps.git_status.outputs.changes_detected == 'true' && github.event.pull_request.head.repo.full_name == github.repository
|
||||
run: |
|
||||
git commit -m "chore: Auto-generate a2a.json from types.ts changes"
|
||||
git push
|
||||
|
||||
- name: Fail on Fork PR if Changes Required
|
||||
if: steps.git_status.outputs.changes_detected == 'true' && github.event.pull_request.head.repo.full_name != github.repository
|
||||
run: |
|
||||
echo "::error::a2a.json is out of date."
|
||||
echo "Please run 'npm install' then 'npm run generate' in the 'types' directory of your branch and commit the updated 'specification/json/a2a.json' file."
|
||||
exit 1 # Exit with a non-zero code to fail the workflow
|
||||
2
.github/workflows/issue-metrics.yml
vendored
@ -29,7 +29,7 @@ jobs:
|
||||
echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Run issue-metrics tool
|
||||
uses: github/issue-metrics@v3
|
||||
uses: github-community-projects/issue-metrics@v4
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
SEARCH_QUERY: 'repo:a2aproject/A2A is:issue created:${{ env.last_month }} -reason:"not planned"'
|
||||
|
||||
2
.github/workflows/links.yaml
vendored
@ -16,7 +16,7 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout Repository
|
||||
uses: actions/checkout@v5
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Get relevant changed files
|
||||
id: changed-files
|
||||
|
||||
61
.github/workflows/linter.yaml
vendored
@ -15,32 +15,49 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v5
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Load Super Linter Environment Variables into GITHUB_ENV
|
||||
run: |
|
||||
grep -v '^\\(#.*\\|\\s\\?\\)$' .github/super-linter.env >> "${GITHUB_ENV}"
|
||||
|
||||
- name: GitHub Super Linter
|
||||
uses: super-linter/super-linter/slim@v8
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
SHELLCHECK_OPTS: -e SC1091 -e 2086
|
||||
VALIDATE_ALL_CODEBASE: false
|
||||
FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|MAINTAINERS.md"
|
||||
VALIDATE_BASH: true
|
||||
VALIDATE_BASH_EXEC: true
|
||||
VALIDATE_CSS: true
|
||||
VALIDATE_EDITORCONFIG: true
|
||||
VALIDATE_GIT_MERGE_CONFLICT_MARKERS: true
|
||||
VALIDATE_GITHUB_ACTIONS: true
|
||||
VALIDATE_GITLEAKS: true
|
||||
VALIDATE_JSCPD: true
|
||||
VALIDATE_JSON: true
|
||||
VALIDATE_MARKDOWN: true
|
||||
VALIDATE_PROTOBUF: true
|
||||
VALIDATE_PYTHON_RUFF: true
|
||||
VALIDATE_SHELL_SHFMT: true
|
||||
VALIDATE_TOML: true
|
||||
VALIDATE_TYPESCRIPT_ES: true
|
||||
VALIDATE_YAML: true
|
||||
TYPESCRIPT_ES_CONFIG_FILE: ".eslintrc.js"
|
||||
MARKDOWN_CONFIG_FILE: ".markdownlint.json"
|
||||
|
||||
api-linter:
|
||||
name: API Linter
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Install buf
|
||||
run: |
|
||||
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64" -o buf
|
||||
sudo mv buf /usr/local/bin/buf
|
||||
sudo chmod +x /usr/local/bin/buf
|
||||
|
||||
- name: Download proto dependencies
|
||||
working-directory: specification
|
||||
run: |
|
||||
buf dep update
|
||||
buf export buf.build/googleapis/googleapis --output=.googleapis
|
||||
|
||||
- name: Install api-linter
|
||||
run: |
|
||||
curl -L https://github.com/googleapis/api-linter/releases/download/v1.67.6/api-linter-1.67.6-linux-amd64.tar.gz -o api-linter.tar.gz
|
||||
tar -xzf api-linter.tar.gz
|
||||
sudo mv api-linter /usr/local/bin/
|
||||
sudo chmod +x /usr/local/bin/api-linter
|
||||
|
||||
- name: Run API Linter
|
||||
run: |
|
||||
# Run api-linter with exported googleapis protos
|
||||
api-linter --config specification/.api-linter.yaml --output-format github --set-exit-status --proto-path specification --proto-path specification/.googleapis specification/a2a.proto
|
||||
|
||||
2
.github/workflows/release-please.yml
vendored
@ -12,6 +12,8 @@ name: release-please
|
||||
jobs:
|
||||
release-please:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.repository_owner == 'a2aproject'
|
||||
|
||||
steps:
|
||||
- uses: googleapis/release-please-action@v4
|
||||
with:
|
||||
|
||||
@ -18,7 +18,7 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v5
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
repository: ${{ github.event.pull_request.head.repo.full_name }}
|
||||
ref: ${{ github.event.pull_request.head.ref }}
|
||||
|
||||
2
.github/workflows/spelling.yaml
vendored
@ -27,7 +27,7 @@ jobs:
|
||||
steps:
|
||||
- name: check-spelling
|
||||
id: spelling
|
||||
uses: check-spelling/check-spelling@main
|
||||
uses: check-spelling/check-spelling@v0.0.26
|
||||
with:
|
||||
suppress_push_for_open_pull_request: ${{ github.actor != 'dependabot[bot]' && 1 }}
|
||||
checkout: true
|
||||
|
||||
2
.github/workflows/stale.yaml
vendored
@ -7,7 +7,7 @@ name: Mark stale issues and pull requests
|
||||
|
||||
on:
|
||||
schedule:
|
||||
# Scheduled to run at 10.30PM UTC everyday (1530PDT/1430PST)
|
||||
# Scheduled to run at 10.30PM UTC every day (1530PDT/1430PST)
|
||||
- cron: "30 22 * * *"
|
||||
workflow_dispatch:
|
||||
|
||||
|
||||
27
.gitignore
vendored
@ -1,3 +1,28 @@
|
||||
# Added: ignore local documentation virtualenv and generated proto-derived artifacts
|
||||
venv-docs/
|
||||
.venv/
|
||||
venv/
|
||||
ENV/
|
||||
.doc-venv
|
||||
|
||||
# Ephemeral schema artifacts (never commit)
|
||||
specification/json/a2a.json
|
||||
specification/json/*.json
|
||||
!specification/json/README.md
|
||||
docs/spec/
|
||||
|
||||
# Generated SDK docs
|
||||
docs/sdk/*
|
||||
!docs/sdk/index.md
|
||||
!docs/sdk/python.md
|
||||
!docs/sdk/python/
|
||||
docs/sdk/python/*
|
||||
!docs/sdk/python/conf.py
|
||||
!docs/sdk/python/index.rst
|
||||
|
||||
# Third-party dependencies (generated by setup)
|
||||
third_party/
|
||||
|
||||
# Byte-compiled / optimized / DLL files
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
@ -185,3 +210,5 @@ Thumbs.db
|
||||
docs/sdk/python/_build/
|
||||
docs/sdk/python/api/
|
||||
docs/sdk/python/generated/
|
||||
|
||||
specification/.googleapis/
|
||||
|
||||
@ -26,7 +26,7 @@
|
||||
# profile: default
|
||||
profiles:
|
||||
default:
|
||||
duration: 1w
|
||||
duration: 52w
|
||||
pass_threshold: 51
|
||||
periodic_status_check: "1 day"
|
||||
allowed_voters:
|
||||
|
||||
325
.mkdocs/macros.py
Normal file
@ -0,0 +1,325 @@
|
||||
"""Custom MkDocs macros for A2A documentation.
|
||||
|
||||
This module provides macros for rendering Protocol Buffer definitions
|
||||
as markdown tables.
|
||||
"""
|
||||
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from proto_schema_parser.ast import (
|
||||
Comment,
|
||||
Enum,
|
||||
EnumValue,
|
||||
Field,
|
||||
MapField,
|
||||
Message,
|
||||
Method,
|
||||
OneOf,
|
||||
Service,
|
||||
)
|
||||
from proto_schema_parser.parser import Parser
|
||||
from tabulate import tabulate
|
||||
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Configuration & Helpers
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
TYPE_MAP = {
|
||||
'string': 'string',
|
||||
'int32': 'integer',
|
||||
'int64': 'integer',
|
||||
'bool': 'boolean',
|
||||
'bytes': 'bytes',
|
||||
'double': 'float',
|
||||
'float': 'float',
|
||||
'google.protobuf.Struct': 'object',
|
||||
'google.protobuf.Timestamp': 'timestamp',
|
||||
'google.protobuf.Value': 'any',
|
||||
'google.protobuf.Empty': 'empty',
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Main Macros
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
|
||||
def define_env(env):
|
||||
"""Define custom macros for MkDocs."""
|
||||
|
||||
def _parse_proto(file_path: str):
|
||||
"""Parses a .proto file and returns the AST with comments attached."""
|
||||
full_path = Path(env.conf['docs_dir']).parent / file_path
|
||||
if not full_path.exists():
|
||||
raise FileNotFoundError(f'Proto not found: {file_path}')
|
||||
ast = Parser().parse(full_path.read_text(encoding='utf-8'))
|
||||
_attach_comments(ast.file_elements)
|
||||
return ast.file_elements
|
||||
|
||||
@env.macro
|
||||
def proto_to_table(
|
||||
message_name: str, proto_file: str = 'specification/a2a.proto'
|
||||
) -> str:
|
||||
"""Parses a .proto file and renders a message table."""
|
||||
try:
|
||||
elements = _parse_proto(proto_file)
|
||||
except FileNotFoundError as e:
|
||||
return f'**Error:** {e}'
|
||||
|
||||
# Find the specific message object
|
||||
target_message = _find_type(elements, message_name, Message)
|
||||
if not target_message:
|
||||
return f'**Error:** Message `{message_name}` not found.'
|
||||
|
||||
# Extract data
|
||||
rows = []
|
||||
oneof_groups = {} # Map[oneof_name] -> List[field_names]
|
||||
|
||||
# Iterate over elements inside the message
|
||||
# elements can be Field, MapField, OneOf, Enum, Message, etc.
|
||||
for el in target_message.elements:
|
||||
# Handle Standard/Map Fields
|
||||
if isinstance(el, Field | MapField):
|
||||
rows.append(_process_field(el))
|
||||
elif isinstance(el, OneOf):
|
||||
for oneof_el in el.elements:
|
||||
if isinstance(oneof_el, Field):
|
||||
# Process field normally
|
||||
row = _process_field(oneof_el, is_oneof=True)
|
||||
rows.append(row)
|
||||
# Add display name to group tracker
|
||||
oneof_groups.setdefault(el.name, []).append(
|
||||
row[0].strip('`') # Remove code ticks for the note
|
||||
)
|
||||
|
||||
if not rows:
|
||||
return 'None'
|
||||
|
||||
# Generate Output
|
||||
output = []
|
||||
|
||||
# Message Description
|
||||
msg_desc = _extract_comments(target_message)
|
||||
if msg_desc:
|
||||
output.append(msg_desc)
|
||||
output.append('')
|
||||
|
||||
# Render Table
|
||||
headers = ['Field', 'Type', 'Required', 'Description']
|
||||
output.append(tabulate(rows, headers, tablefmt='github'))
|
||||
|
||||
# Add OneOf Notes
|
||||
if oneof_groups:
|
||||
output.append('')
|
||||
for _, fields in oneof_groups.items():
|
||||
if len(fields) > 1:
|
||||
field_list = ', '.join(f'`{f}`' for f in fields)
|
||||
output.append(
|
||||
f'**Note:** A `{message_name}` MUST contain exactly one of the following: {field_list}'
|
||||
)
|
||||
|
||||
return '\n'.join(output)
|
||||
|
||||
@env.macro
|
||||
def proto_enum_to_table(
|
||||
enum_name: str, proto_file: str = 'specification/a2a.proto'
|
||||
):
|
||||
"""Parses a .proto file and renders an Enum table."""
|
||||
try:
|
||||
elements = _parse_proto(proto_file)
|
||||
el = _find_type(elements, enum_name, Enum)
|
||||
if not el:
|
||||
return f'**Error:** Enum `{enum_name}` not found.'
|
||||
|
||||
rows = [
|
||||
[f'`{e.name}`', _extract_comments(e)]
|
||||
for e in el.elements
|
||||
if isinstance(e, EnumValue)
|
||||
]
|
||||
return f'{_extract_comments(el)}\n\n' + tabulate(
|
||||
rows, ['Value', 'Description'], tablefmt='github'
|
||||
)
|
||||
except Exception as e:
|
||||
return f'**Error:** {e}'
|
||||
|
||||
@env.macro
|
||||
def proto_service_to_table(
|
||||
service_name: str, proto_file: str = 'specification/a2a.proto'
|
||||
) -> str:
|
||||
"""Parses a .proto file and renders a Service table."""
|
||||
try:
|
||||
elements = _parse_proto(proto_file)
|
||||
service = _find_type(elements, service_name, Service)
|
||||
if not service:
|
||||
return f'**Error:** Service `{service_name}` not found.'
|
||||
|
||||
rows = []
|
||||
for el in service.elements:
|
||||
if isinstance(el, Method):
|
||||
# Request Type
|
||||
# input_type is a MessageType(type='...', stream=True/False)
|
||||
req_str = _format_type_for_docs(el.input_type.type)
|
||||
if el.input_type.stream:
|
||||
req_str = f'stream {req_str}'
|
||||
|
||||
# Response Type
|
||||
res_str = _format_type_for_docs(el.output_type.type)
|
||||
if el.output_type.stream:
|
||||
res_str = f'stream {res_str}'
|
||||
|
||||
rows.append(
|
||||
[
|
||||
f'`{el.name}`',
|
||||
req_str,
|
||||
res_str,
|
||||
_extract_comments(el),
|
||||
]
|
||||
)
|
||||
|
||||
if not rows:
|
||||
return 'None'
|
||||
|
||||
headers = ['Method', 'Request', 'Response', 'Description']
|
||||
return tabulate(rows, headers, tablefmt='github')
|
||||
|
||||
except Exception as e:
|
||||
return f'**Error:** {e}'
|
||||
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Helper Functions
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _extract_comments(element: Any) -> str:
|
||||
"""Clean and combine comments from an AST element."""
|
||||
cleaned_parts = []
|
||||
raw_comments = getattr(element, 'comments', [])
|
||||
|
||||
for comment in raw_comments:
|
||||
text = (
|
||||
comment.strip()
|
||||
.removeprefix('//')
|
||||
.removeprefix('/*')
|
||||
.removesuffix('*/')
|
||||
)
|
||||
lines = (
|
||||
line.strip().removeprefix('*').strip() for line in text.splitlines()
|
||||
)
|
||||
combined = ' '.join(filter(None, lines))
|
||||
|
||||
if combined and not combined.startswith(
|
||||
(
|
||||
'protolint:',
|
||||
'--8<--',
|
||||
'Next ID:',
|
||||
'(-- api-linter',
|
||||
'api-linter',
|
||||
'aip.dev/not-precedent',
|
||||
)
|
||||
):
|
||||
cleaned_parts.append(combined)
|
||||
|
||||
return ' '.join(cleaned_parts)
|
||||
|
||||
|
||||
def _attach_comments(elements: list[Any]) -> None:
|
||||
"""Recursively attach preceding comments to each non-comment element."""
|
||||
buffer = []
|
||||
for el in elements:
|
||||
if isinstance(el, Comment):
|
||||
buffer.append(el.text)
|
||||
else:
|
||||
# Attach collected comments to this element
|
||||
el.comments = buffer
|
||||
buffer = []
|
||||
# Recursively handle nested elements (e.g. inside Message or OneOf)
|
||||
if hasattr(el, 'elements'):
|
||||
_attach_comments(el.elements)
|
||||
|
||||
|
||||
def _format_type_for_docs(
|
||||
proto_type: str, is_repeated: bool = False, map_key: str | None = None
|
||||
) -> str:
|
||||
"""Formats the type name with Markdown links for non-primitive types."""
|
||||
# Handle fully qualified names by taking only the last part for the link label,
|
||||
# but keep it if it's a known google.protobuf type we mapped.
|
||||
display_name = TYPE_MAP.get(proto_type, proto_type.split('.')[-1])
|
||||
is_primitive = proto_type in TYPE_MAP or proto_type.startswith(
|
||||
'google.protobuf'
|
||||
)
|
||||
|
||||
# Create a slug for the link. Messages are usually CamelCase, so lowercase it.
|
||||
label = f'`{display_name}`'
|
||||
if not is_primitive:
|
||||
label = f'[{label}](#{display_name.lower()})'
|
||||
|
||||
if map_key:
|
||||
key_label = TYPE_MAP.get(map_key, map_key)
|
||||
return f'map of {key_label} to {label}'
|
||||
|
||||
if is_repeated:
|
||||
return f'array of {label}'
|
||||
|
||||
return label
|
||||
|
||||
|
||||
def _find_type(elements: list[Any], name: str, target_cls: type) -> Any | None:
|
||||
"""Recursively searches for a Message or Enum by name."""
|
||||
for el in elements:
|
||||
if getattr(el, 'name', None) == name and isinstance(el, target_cls):
|
||||
return el
|
||||
if isinstance(el, Message):
|
||||
found = _find_type(el.elements, name, target_cls)
|
||||
if found:
|
||||
return found
|
||||
return None
|
||||
|
||||
|
||||
def _process_field(field: Field, is_oneof: bool = False) -> list[str]:
|
||||
"""Converts a Field or MapField object into a table row."""
|
||||
options = getattr(field, 'options', [])
|
||||
cardinality_obj = getattr(field, 'cardinality', None)
|
||||
cardinality = (
|
||||
getattr(cardinality_obj, 'value', None) if cardinality_obj else None
|
||||
)
|
||||
|
||||
# Determine Display Name (json_name vs snake_case)
|
||||
json_name = next(
|
||||
(o.value.strip('"') for o in options if o.name == 'json_name'), None
|
||||
)
|
||||
display_name = json_name or _snake_to_camel_case(field.name)
|
||||
|
||||
# Determine Type
|
||||
is_map = isinstance(field, MapField)
|
||||
is_repeated = cardinality == 'REPEATED'
|
||||
|
||||
type_to_format = field.value_type if is_map else field.type
|
||||
map_key = getattr(field, 'key_type', None)
|
||||
|
||||
type_str = _format_type_for_docs(type_to_format, is_repeated, map_key)
|
||||
|
||||
# Determine Required/Optional
|
||||
has_required_behavior = any(
|
||||
'REQUIRED' in str(opt.value)
|
||||
for opt in options
|
||||
if 'field_behavior' in opt.name
|
||||
)
|
||||
|
||||
if is_oneof:
|
||||
req_val = 'Optional (OneOf)'
|
||||
elif cardinality == 'REQUIRED' or has_required_behavior:
|
||||
req_val = 'Yes'
|
||||
else:
|
||||
req_val = 'No'
|
||||
|
||||
desc = _extract_comments(field)
|
||||
|
||||
return [f'`{display_name}`', type_str, req_val, desc]
|
||||
|
||||
|
||||
def _snake_to_camel_case(snake_str: str) -> str:
|
||||
"""Convert snake_case to camelCase."""
|
||||
components = snake_str.split('_')
|
||||
return components[0] + ''.join(x.title() for x in components[1:])
|
||||
@ -1,3 +1,8 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block announce %}{% endblock %}
|
||||
{% block announce %}
|
||||
Join the new DeepLearning.AI short course: <strong>A2A: The Agent2Agent Protocol</strong>!
|
||||
<a href="https://goo.gle/dlai-a2a" class="md-button">
|
||||
Enroll for free
|
||||
</a>
|
||||
{% endblock %}
|
||||
|
||||
3
.vscode/settings.json
vendored
@ -14,5 +14,6 @@
|
||||
"editor.formatOnSave": true
|
||||
},
|
||||
"files.trimTrailingWhitespace": true,
|
||||
"files.insertFinalNewline": true
|
||||
"files.insertFinalNewline": true,
|
||||
"codeQL.githubDatabase.download": "never"
|
||||
}
|
||||
|
||||
84
CHANGELOG.md
@ -1,10 +1,88 @@
|
||||
# Changelog
|
||||
|
||||
## [0.4.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v0.4.0) (2025-09-15)
|
||||
## [1.0.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v1.0.0) (2026-03-12)
|
||||
|
||||
|
||||
### ⚠ BREAKING CHANGES
|
||||
|
||||
* **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](https://github.com/a2aproject/A2A/issues/1500))
|
||||
* **spec:** remove duplicated ID from the create task push config request ([#1487](https://github.com/a2aproject/A2A/issues/1487))
|
||||
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](https://github.com/a2aproject/A2A/issues/1486))
|
||||
* **spec:** Add LF prefix to the package. ([#1474](https://github.com/a2aproject/A2A/issues/1474))
|
||||
* **spec:** Switch to non-complex IDs in requests ([#1389](https://github.com/a2aproject/A2A/issues/1389))
|
||||
* **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283))
|
||||
* **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](https://github.com/a2aproject/A2A/issues/1384))
|
||||
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](https://github.com/a2aproject/A2A/issues/1308))
|
||||
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](https://github.com/a2aproject/A2A/issues/1307))
|
||||
* **spec:** Fixes for the last_updated_after field ([#1358](https://github.com/a2aproject/A2A/issues/1358))
|
||||
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](https://github.com/a2aproject/A2A/issues/1303))
|
||||
* **spec:** Make "message" field name consistent between protocol bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302))
|
||||
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](https://github.com/a2aproject/A2A/issues/1301))
|
||||
* **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](https://github.com/a2aproject/A2A/issues/1222))
|
||||
* **spec:** Remove v1s from a2a url http bindings
|
||||
* **spec:** Large refactor of specification to separate application protocol definition from mapping to transports
|
||||
|
||||
### Features
|
||||
|
||||
* **spec:** Add `tasks/list` method for retrieving and filtering tasks with pagination
|
||||
* **spec:** Add `tasks/list` method with filtering and pagination to the specification ([0a9f629](https://github.com/a2aproject/A2A/commit/0a9f629e801d4ae89f94991fc28afe9429c91cbc))
|
||||
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](https://github.com/a2aproject/A2A/issues/1303)) ([525ff38](https://github.com/a2aproject/A2A/commit/525ff38e5fe2a118f5be5d25189708b590616dd4))
|
||||
* **spec:** Natively Support Multi-tenancy on gRPC through an additional scope field on the request. ([#1195](https://github.com/a2aproject/A2A/issues/1195)) ([cfbce32](https://github.com/a2aproject/A2A/commit/cfbce32cb0ac2a630597eb8b771691cac5b20a4b)), closes [#1148](https://github.com/a2aproject/A2A/issues/1148)
|
||||
* **spec:** Provide ability for SDKs to be backwards compatible. ([#1401](https://github.com/a2aproject/A2A/issues/1401)) ([227e249](https://github.com/a2aproject/A2A/commit/227e2493c317004b7e6f7ef4a484e220ffd0b77e))
|
||||
* **spec:** Remove v1s from a2a url http bindings ([1bd263f](https://github.com/a2aproject/A2A/commit/1bd263f5373fdc8fa7c17ec8bdb24088996b6828))
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* Add missing metadata field to Part message in gRPC specification ([#1019](https://github.com/a2aproject/A2A/issues/1019)) ([b3b266d](https://github.com/a2aproject/A2A/commit/b3b266d127dde3d1000ec103b252d1de81289e83)), closes [#1005](https://github.com/a2aproject/A2A/issues/1005)
|
||||
* Add name field to FilePart protobuf message ([#983](https://github.com/a2aproject/A2A/issues/983)) ([2b7cb6f](https://github.com/a2aproject/A2A/commit/2b7cb6f8408e6324c48fb82c71839c67a18f1fab)), closes [#984](https://github.com/a2aproject/A2A/issues/984)
|
||||
* Clarify blocking calls return on interrupted states ([#1403](https://github.com/a2aproject/A2A/issues/1403)) ([0655ff3](https://github.com/a2aproject/A2A/commit/0655ff324a93b7e0eaebc108666e6703998b4a9c))
|
||||
* **doc:** Makes JSON-RPC SendMessage response clearer ([#1241](https://github.com/a2aproject/A2A/issues/1241)) ([5792804](https://github.com/a2aproject/A2A/commit/57928043727e5e002a1395dadfb5f699d0626b1c))
|
||||
* **docs:** Clearer wording around context id. ([#1588](https://github.com/a2aproject/A2A/issues/1588)) ([dec790a](https://github.com/a2aproject/A2A/commit/dec790aa063943e3ac70e972f9da513c25ab420c))
|
||||
* **grpc:** Fix inconsistent property name between gRPC and JSON-RPC in Message object ([#1100](https://github.com/a2aproject/A2A/issues/1100)) ([2a1f819](https://github.com/a2aproject/A2A/commit/2a1f819aaa2540602ee81498e159ebe0192be818))
|
||||
* **grpc:** missing field in gRPC spec - state_transition_history ([#1138](https://github.com/a2aproject/A2A/issues/1138)) ([a2de798](https://github.com/a2aproject/A2A/commit/a2de7981cadeaa5197bee56cbd6ab7b2c5da2541)), closes [#1139](https://github.com/a2aproject/A2A/issues/1139)
|
||||
* **grpc:** Update `CreateTaskPushNotificationConfig` endpoint to `/v1/{parent=tasks/*/pushNotificationConfigs}` ([#979](https://github.com/a2aproject/A2A/issues/979)) ([911f9b0](https://github.com/a2aproject/A2A/commit/911f9b059c52dd65497b76ccf63d196ca84c7f0e))
|
||||
* **proto:** Add icon_url to a2a.proto ([#986](https://github.com/a2aproject/A2A/issues/986)) ([17e7f62](https://github.com/a2aproject/A2A/commit/17e7f62df9a3e4ca0768ab8d4f0bb7573b3d73e1))
|
||||
* **proto:** Adds metadata field to A2A DataPart proto ([#1004](https://github.com/a2aproject/A2A/issues/1004)) ([a8b45dc](https://github.com/a2aproject/A2A/commit/a8b45dcc429a5571ef8a24c36336bf84b89bbd7f))
|
||||
* Remove unimplemented state_transition_history capability field ([#1396](https://github.com/a2aproject/A2A/issues/1396)) ([c768a44](https://github.com/a2aproject/A2A/commit/c768a44da0f719595e375636f3cab9898ff6df75)), closes [#1228](https://github.com/a2aproject/A2A/issues/1228)
|
||||
* Restore CreateTaskPushNotificationConfig method naming ([#1402](https://github.com/a2aproject/A2A/issues/1402)) ([d14f410](https://github.com/a2aproject/A2A/commit/d14f4107119bf0fe0dff9e2c577eb4ab70b51793))
|
||||
* Revert "chore(gRPC): Update a2a.proto to include metadata on GetTaskRequest" ([#1000](https://github.com/a2aproject/A2A/issues/1000)) ([e6b8c65](https://github.com/a2aproject/A2A/commit/e6b8c654a86a6ee461bb5c7be5d5b81004b80a92))
|
||||
* Simplify Part message structure by flattening FilePart and DataPart ([#1411](https://github.com/a2aproject/A2A/issues/1411)) ([bfae8f7](https://github.com/a2aproject/A2A/commit/bfae8f7791e019f21f6662dd73fce0b3ab261cd6))
|
||||
* **spec:** Add LF prefix to the package. ([#1474](https://github.com/a2aproject/A2A/issues/1474)) ([a54e809](https://github.com/a2aproject/A2A/commit/a54e80904aa32c74a14bc2c3d21bf82936ccbbdd))
|
||||
* **spec:** add metadata to `CancelTaskRequest` ([#1485](https://github.com/a2aproject/A2A/issues/1485)) ([c441b91](https://github.com/a2aproject/A2A/commit/c441b910b64d45514ae929a42e7367c2a9a2f6c3)), closes [#1484](https://github.com/a2aproject/A2A/issues/1484)
|
||||
* **spec:** Added clarification on timestamps in HTTP query params ([#1425](https://github.com/a2aproject/A2A/issues/1425)) ([6292104](https://github.com/a2aproject/A2A/commit/6292104e359efca05bd8703174517b6f961ae4e1))
|
||||
* **spec:** Added clarifying text around messages and artifacts ([#1424](https://github.com/a2aproject/A2A/issues/1424)) ([b03d141](https://github.com/a2aproject/A2A/commit/b03d141aeab6abd71a229e85c81f7e4c00b537ec))
|
||||
* **spec:** Adjust field number for `ListTasksRequest.tenant` to prevent missing number ([#1470](https://github.com/a2aproject/A2A/issues/1470)) ([cd16c52](https://github.com/a2aproject/A2A/commit/cd16c5276b4c662ca1823678d07487a624cad606))
|
||||
* **spec:** Clarify contextId behavior when message is sent with taskId but without contextId ([#1309](https://github.com/a2aproject/A2A/issues/1309)) ([a336a5a](https://github.com/a2aproject/A2A/commit/a336a5a4846fdf85079d4e310339ea0128922ee7))
|
||||
* **spec:** Clarify versioning strategy and client responsibilities in protocol specification ([#1259](https://github.com/a2aproject/A2A/issues/1259)) ([a4afeea](https://github.com/a2aproject/A2A/commit/a4afeea788b3877101f7a63c2e50091709490058))
|
||||
* **spec:** Fix/1251 clarify authentication scheme ([#1256](https://github.com/a2aproject/A2A/issues/1256)) ([3e6c7db](https://github.com/a2aproject/A2A/commit/3e6c7db90790c2d05dad3ab1a313de26debe5cb7))
|
||||
* **spec:** Fixes for the last_updated_after field ([#1358](https://github.com/a2aproject/A2A/issues/1358)) ([0e204bf](https://github.com/a2aproject/A2A/commit/0e204bf878eb63619e205d3419ebc48d4cd35849))
|
||||
* **spec:** Make "message" field name consistent between protocol bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302)) ([1e5f462](https://github.com/a2aproject/A2A/commit/1e5f46206403982cc629a0dad535856b28c269aa)), closes [#1230](https://github.com/a2aproject/A2A/issues/1230)
|
||||
* **spec:** make `history_length` optional ([#1071](https://github.com/a2aproject/A2A/issues/1071)) ([0572953](https://github.com/a2aproject/A2A/commit/057295311b8ddda63bdda56c82a694c76d307e37))
|
||||
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](https://github.com/a2aproject/A2A/issues/1486)) ([cf735cb](https://github.com/a2aproject/A2A/commit/cf735cb87056ff6d62abd21a1a66ccb14a23c38e))
|
||||
* **spec:** Remove config from binding. ([#1587](https://github.com/a2aproject/A2A/issues/1587)) ([010b9cc](https://github.com/a2aproject/A2A/commit/010b9cc936fbafd66610282ad66070da2cb28855))
|
||||
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](https://github.com/a2aproject/A2A/issues/1301)) ([60f83c3](https://github.com/a2aproject/A2A/commit/60f83c3faac4770b231f038406c9e02282887a25)), closes [#1227](https://github.com/a2aproject/A2A/issues/1227)
|
||||
* **spec:** remove duplicated ID from the create task push config request ([#1487](https://github.com/a2aproject/A2A/issues/1487)) ([393898d](https://github.com/a2aproject/A2A/commit/393898dfeefa37186aced5b61733c5d2c0d9c34a))
|
||||
* **spec:** Remove metadata field from ListTasksRequest ([#1235](https://github.com/a2aproject/A2A/issues/1235)) ([b6ef9ee](https://github.com/a2aproject/A2A/commit/b6ef9eec558c877fb69024df090a8bb63c542a1c))
|
||||
* **spec:** Remove reserved and fix tags ordering ([#1494](https://github.com/a2aproject/A2A/issues/1494)) ([1997c9d](https://github.com/a2aproject/A2A/commit/1997c9d63058ca0b89361a7d6e508f4641a6f68b))
|
||||
* **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](https://github.com/a2aproject/A2A/issues/1222)) ([c196824](https://github.com/a2aproject/A2A/commit/c196824396bb4af4c595f30e2c503a5ab1dbac4b)), closes [#1215](https://github.com/a2aproject/A2A/issues/1215)
|
||||
* **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283)) ([4dd980f](https://github.com/a2aproject/A2A/commit/4dd980f6ff1989177faffa631a695aba811c56ad))
|
||||
* **spec:** Suggest Unique Identifier fields to be UUID ([#966](https://github.com/a2aproject/A2A/issues/966)) ([00cf76e](https://github.com/a2aproject/A2A/commit/00cf76e7bbc752842ef254f3d4136ed1b5751f6e))
|
||||
* **spec:** Switch to non-complex IDs in requests ([#1389](https://github.com/a2aproject/A2A/issues/1389)) ([2596c1c](https://github.com/a2aproject/A2A/commit/2596c1c5e0effd941880e8487d38d78b74b9c0bf)), closes [#1390](https://github.com/a2aproject/A2A/issues/1390)
|
||||
* **spec:** Update security schemes example ([#1364](https://github.com/a2aproject/A2A/issues/1364)) ([f9a8f5b](https://github.com/a2aproject/A2A/commit/f9a8f5b85d5b07824c52d55d63f7d71ccc6303c5))
|
||||
* Update the Java tutorials and descriptions ([#1181](https://github.com/a2aproject/A2A/issues/1181)) ([202aa06](https://github.com/a2aproject/A2A/commit/202aa069e66f701bacf2156d42d8916fc96a5188))
|
||||
|
||||
|
||||
### Documentation
|
||||
|
||||
* **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](https://github.com/a2aproject/A2A/issues/1384)) ([810eaa1](https://github.com/a2aproject/A2A/commit/810eaa1c6e6462f845a00774f8622b998272116e)), closes [#1344](https://github.com/a2aproject/A2A/issues/1344)
|
||||
|
||||
|
||||
### Code Refactoring
|
||||
|
||||
* **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](https://github.com/a2aproject/A2A/issues/1500)) ([d1ed0da](https://github.com/a2aproject/A2A/commit/d1ed0da587d2d634ba0b81a40d082cee0850b81b))
|
||||
* **spec:** Large refactor of specification to separate application protocol definition from mapping to transports ([b078419](https://github.com/a2aproject/A2A/commit/b0784199543eebf2e95dcb02e9336cb213923506))
|
||||
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](https://github.com/a2aproject/A2A/issues/1307)) ([40d6286](https://github.com/a2aproject/A2A/commit/40d6286fbe29fb083d416b77e84122df8d70ae9d))
|
||||
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](https://github.com/a2aproject/A2A/issues/1308)) ([5b101cc](https://github.com/a2aproject/A2A/commit/5b101cce0fff449c1120ad50ce360acf7c90bac3))
|
||||
|
||||
## [0.3.0](https://github.com/a2aproject/A2A/compare/v0.2.6...v0.3.0) (2025-07-30)
|
||||
|
||||
@ -89,7 +167,7 @@
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* Protocol should released as 0.2.2 ([22e7541](https://github.com/a2aproject/A2A/commit/22e7541be082c4f0845ff7fa044992cda05b437e))
|
||||
* Protocol should be released as 0.2.2 ([22e7541](https://github.com/a2aproject/A2A/commit/22e7541be082c4f0845ff7fa044992cda05b437e))
|
||||
* Resolve spec inconsistencies with JSON-RPC 2.0 ([628380e](https://github.com/a2aproject/A2A/commit/628380e7e392bc8f1778ae991d4719bd787c17a9))
|
||||
|
||||
## [0.2.1](https://github.com/a2aproject/A2A/compare/v0.2.0...v0.2.1) (2025-05-27)
|
||||
|
||||
@ -72,7 +72,7 @@ an environment where participants feel welcome and safe.
|
||||
Reports should be directed to [a2a-coc@googlegroups.com](mailto:a2a-coc@googlegroups.com), the
|
||||
Project Steward(s) for A2A. It is the Project Steward’s duty to
|
||||
receive and address reported violations of the code of conduct. They will then
|
||||
work with a committee consisting of representatives from the A2A project and leadership.
|
||||
work with a committee consisting of representatives from the A2A project and leadership.
|
||||
|
||||
We will investigate every complaint, but you may not receive a direct response.
|
||||
We will use our discretion in determining when and how to follow up on reported
|
||||
@ -87,4 +87,4 @@ harassment or threats to anyone's safety, we may take action without notice.
|
||||
|
||||
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
|
||||
available at
|
||||
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
|
||||
https://www.contributor-covenant.org/version/1/4/code-of-conduct/
|
||||
|
||||
@ -2,7 +2,84 @@
|
||||
|
||||
We'd love to accept your patches and contributions to this project.
|
||||
|
||||
## Contribution process
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
To contribute to this project, you will need the following tools installed:
|
||||
|
||||
- [Python 3.10+](https://www.python.org/downloads/)
|
||||
- [uv](https://docs.astral.sh/uv/getting-started/installation/) - Fast Python package installer and resolver.
|
||||
- [Node.js & npm](https://nodejs.org/en/download/) - For markdown formatting tools.
|
||||
- [Docker](https://www.docker.com/get-started) - Required for running the local linter.
|
||||
|
||||
## Working with Documentation
|
||||
|
||||
The A2A documentation is built using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/).
|
||||
|
||||
### Local Setup
|
||||
|
||||
1. **Create a virtual environment:**
|
||||
|
||||
```bash
|
||||
uv venv .doc-venv
|
||||
```
|
||||
|
||||
2. **Activate the virtual environment:**
|
||||
|
||||
```bash
|
||||
source .doc-venv/bin/activate # Unix/macOS
|
||||
# .doc-venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
3. **Install dependencies:**
|
||||
|
||||
```bash
|
||||
uv pip install -r requirements-docs.txt
|
||||
```
|
||||
|
||||
### Build and Serve
|
||||
|
||||
1. **Build the documentation:**
|
||||
This script regenerates the JSON schema from the protocol definition, builds the SDK documentation, and then builds the MkDocs site.
|
||||
|
||||
```bash
|
||||
./scripts/build_docs.sh
|
||||
```
|
||||
|
||||
2. **Serve the documentation locally:**
|
||||
Run the following command to start a local server with live reloading:
|
||||
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
3. **View the documentation:**
|
||||
Open [http://localhost:8000](http://localhost:8000) in your browser.
|
||||
|
||||
## Code Standards
|
||||
|
||||
### Linting
|
||||
|
||||
We use [Super Linter](https://github.com/super-linter/super-linter) to ensure code quality across the repository. You can run the linter locally using Docker:
|
||||
|
||||
```bash
|
||||
./scripts/lint.sh
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
We use [markdownlint](https://github.com/igorshubovych/markdownlint-cli) for formatting markdown files. You can fix most formatting issues automatically by running:
|
||||
|
||||
```bash
|
||||
./scripts/format.sh
|
||||
```
|
||||
|
||||
### Conventional Commits
|
||||
|
||||
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for our commit messages. This helps us automate our release process and maintain a clear changelog.
|
||||
|
||||
## Contribution Process
|
||||
|
||||
### Code reviews
|
||||
|
||||
@ -11,18 +88,17 @@ use GitHub pull requests for this purpose. Consult
|
||||
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
|
||||
information on using pull requests.
|
||||
|
||||
### Contributor Guide
|
||||
### Workflow
|
||||
|
||||
You may follow these steps to contribute:
|
||||
|
||||
1. **Fork the official repository.** This will create a copy of the official repository in your own account.
|
||||
2. **Sync the branches.** This will ensure that your copy of the repository is up-to-date with the latest changes from the official repository.
|
||||
3. **Work on your forked repository's feature branch.** This is where you will make your changes to the code.
|
||||
4. **Commit your updates on your forked repository's feature branch.** This will save your changes to your copy of the repository.
|
||||
5. **Submit a pull request to the official repository's main branch.** This will request that your changes be merged into the official repository.
|
||||
6. **Resolve any linting errors.** This will ensure that your changes are formatted correctly.
|
||||
4. **Test your changes.** Build and preview the documentation locally to ensure everything looks correct.
|
||||
5. Format and lint your code. Run ./scripts/format.sh and ./scripts/lint.sh to ensure your changes meet our standards.
|
||||
6. **Commit your updates.** Use conventional commit messages on your feature branch.
|
||||
7. **Submit a pull request.** Submit a PR from your fork's feature branch to the official repository's `main` branch.
|
||||
8. **Resolve any feedback.** Work with reviewers to address any comments or requested changes.
|
||||
|
||||
Here are some additional things to keep in mind during the process:
|
||||
|
||||
- **Test your changes.** Before you submit a pull request, make sure that your changes work as expected.
|
||||
- **Be patient.** It may take some time for your pull request to be reviewed and merged.
|
||||
Be patient! It may take some time for your pull request to be reviewed and merged.
|
||||
|
||||
@ -6,9 +6,9 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Google** | Todd Segal | Principal Engineer | [@ToddSegal](https://github.com/ToddSegal) |
|
||||
| **Microsoft** | Darrel Miller | Partner API Architect | [@darrelmiller](https://github.com/darrelmiller) |
|
||||
| **Cisco** | Luca Muscariello | Principal Engineer | [@muscariello](https://github.com/muscariello) |
|
||||
| **Amazon Web Services** | Nicholas Aldridge | Principal Engineer | [@000-000-000-000-000](https://github.com/000-000-000-000-000) |
|
||||
| **Salesforce** | Gary Lerhaupt | VP, Product Architecture | [@lerhaupt](https://github.com/lerhaupt) |
|
||||
| **Cisco** | Luca Muscariello | Distinguished Engineer | [@muscariello](https://github.com/muscariello) |
|
||||
| **Amazon Web Services** | Abhimanyu Siwach | Senior Software Engineer | [@siwachabhi](https://github.com/siwachabhi) |
|
||||
| **Salesforce** | Stephen Petschulat | Principal Architect | [@spetschulatSFDC](https://github.com/spetschulatSFDC) |
|
||||
| **ServiceNow** | Sean Hughes | Director of Open Science | [@hughesthe1st](https://github.com/hughesthe1st) |
|
||||
| **SAP** | Sivakumar N. | Vice President | [@SivaNSAP](https://github.com/SivaNSAP) |
|
||||
| **IBM Research** | Kate Blair | Director of Incubation | [@geneknit](https://github.com/geneknit) |
|
||||
@ -32,7 +32,9 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
|
||||
|
||||
a. **"Startup Phase."** At the inception of the Project, each organization listed in the [`GOVERNANCE`](GOVERNANCE.md) file in the governance repository of the Project will have the right to appoint (and remove and replace) one employee to serve as a voting member of the TSC.
|
||||
|
||||
b. **"Steady State."** The TSC will decide upon a "steady state" composition of the TSC (whether by election, sub-project technical leads, or other method as determined by the TSC) for composition of the TSC from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC.
|
||||
Adding new organizations to the GOVERNANCE file will be determined through a proposal to the TSC GOVERNANCE.md file. Any new organization will be added through a majority vote of the TSC, and an employee of that organization will serve as a voting member of the TSC.
|
||||
|
||||
b. **"Steady State."** The TSC will decide upon a "steady state" composition of the TSC (whether by election, subproject technical leads, or other method as determined by the TSC), to take effect from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC.
|
||||
|
||||
c. The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file. Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person.
|
||||
|
||||
@ -52,9 +54,9 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
|
||||
5. The TSC may elect a TSC Chair, who will preside over meetings of the TSC and will serve until their resignation or replacement by the TSC.
|
||||
6. **Responsibilities:** The TSC will be responsible for all aspects of oversight relating to the Project, which may include:
|
||||
1. coordinating the technical direction of the Project;
|
||||
2. approving project or system proposals (including, but not limited to, incubation, deprecation, and changes to a sub-project's scope);
|
||||
3. organizing sub-projects and removing sub-projects;
|
||||
4. creating sub-committees or working groups to focus on cross-project technical issues and requirements;
|
||||
2. approving project or system proposals (including, but not limited to, incubation, deprecation, and changes to a subproject's scope);
|
||||
3. organizing subprojects and removing subprojects;
|
||||
4. creating subcommittees or working groups to focus on cross-project technical issues and requirements;
|
||||
5. appointing representatives to work with other open source or open standards communities;
|
||||
6. establishing community norms, workflows, issuing releases, and security issue reporting policies;
|
||||
7. approving and implementing policies and processes for contributing (to be published in the [`CONTRIBUTING`](CONTRIBUTING.md) file) and coordinating with the series manager of the Project (as provided for in the Series Agreement, the "Series Manager") to resolve matters or concerns that may arise as set forth in Section 7 of this Charter;
|
||||
@ -63,13 +65,15 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
|
||||
|
||||
### TSC Voting
|
||||
|
||||
While the Project aims to operate as a consensus-based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis.
|
||||
While the Project aims to operate as a consensus-based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis.
|
||||
|
||||
Quorum for TSC meetings requires at least fifty percent of all voting members of the TSC to be present. The TSC may continue to meet if quorum is not met but will be prevented from making any decisions at the meeting. Except as provided in Section 7.c. and 8.a, decisions by vote at a meeting require a majority vote of those in attendance, provided quorum is met. Decisions made by electronic vote without a meeting require a majority vote of all voting members of the TSC.
|
||||
|
||||
### TSC Meetings
|
||||
A voting member who has not attended a meeting of the TSC within the last six weeks (as measured by the LFX attendance tracking) shall be determined to be an inactive voting member. They will not be included in active votes, which means that they will not be counted for quorum, and the sponsoring organization may choose to replace the named TSC member within a reasonable timeframe.
|
||||
|
||||
Our hope is that the first TSC meeting will be held in August 2025. Once the TSC representatives are finalized, scheduling will begin. In the interim we have drafted a [working doc for TSC Meeting Agendas](https://docs.google.com/document/d/1Dx6qYfCjSChHKRMwLJcvtDjq6igYTAKFW9Vg1IMPCUk/view).
|
||||
### TSC Meetings
|
||||
TSC Meetings are held on the Linux Foundation's meeting platform. [https://zoom-lfx.platform.linuxfoundation.org/meetings/agent2agent](https://zoom-lfx.platform.linuxfoundation.org/meetings/agent2agent) has meeting details and recordings of past meetings.
|
||||
Our [working doc for TSC Meeting Agendas](https://docs.google.com/document/d/1Dx6qYfCjSChHKRMwLJcvtDjq6igYTAKFW9Vg1IMPCUk/view) is in Google Docs.
|
||||
|
||||
## Project Communications
|
||||
|
||||
|
||||
49
README.md
@ -6,6 +6,37 @@
|
||||
<img src="https://www.gstatic.com/_/boq-sdlc-agents-ui/_/r/Mvosg4klCA4.svg" alt="Ask Code Wiki" height="20">
|
||||
</a>
|
||||
|
||||
<div style="text-align: left;">
|
||||
<details>
|
||||
<summary>🌐 Language</summary>
|
||||
<div>
|
||||
<div style="text-align: center;">
|
||||
<a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=en">English</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-CN">简体中文</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-TW">繁體中文</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ja">日本語</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ko">한국어</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=hi">हिन्दी</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=th">ไทย</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fr">Français</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=de">Deutsch</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=es">Español</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=it">Italiano</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ru">Русский</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=pt">Português</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=nl">Nederlands</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=pl">Polski</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ar">العربية</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fa">فارسی</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=tr">Türkçe</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=vi">Tiếng Việt</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=id">Bahasa Indonesia</a>
|
||||
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=as">অসমীয়া</a>
|
||||
</div>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
|
||||
<!-- markdownlint-disable MD041 -->
|
||||
<div style="text-align: center;">
|
||||
<div class="centered-logo-text-group">
|
||||
@ -22,12 +53,22 @@ With A2A, agents can:
|
||||
|
||||
- Discover each other's capabilities.
|
||||
- Negotiate interaction modalities (text, forms, media).
|
||||
- Securely collaborate on long running tasks.
|
||||
- Securely collaborate on long-running tasks.
|
||||
- Operate without exposing their internal state, memory, or tools.
|
||||
|
||||
## Intro to A2A Video
|
||||
## DeepLearning.AI Course
|
||||
|
||||
[](https://goo.gle/a2a-video)
|
||||
[](https://goo.gle/dlai-a2a)
|
||||
|
||||
Join this short course on [A2A: The Agent2Agent Protocol](https://goo.gle/dlai-a2a), built in partnership with Google Cloud and IBM Research, and taught by [Holt Skinner](https://github.com/holtskinner), [Ivan Nardini](https://github.com/inardini), and [Sandi Besen](https://github.com/sandijean90).
|
||||
|
||||
**What you'll learn:**
|
||||
|
||||
- **Make agents A2A-compliant:** Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.
|
||||
- **Connect agents:** Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.
|
||||
- **Orchestrate workflows:** Build sequential and hierarchical workflows of A2A-compliant agents.
|
||||
- **Multi-agent systems:** Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.
|
||||
- **A2A and MCP:** Learn how A2A complements MCP by enabling agents to collaborate with each other.
|
||||
|
||||
## Why A2A?
|
||||
|
||||
@ -84,4 +125,4 @@ We welcome community contributions to enhance and evolve the A2A protocol!
|
||||
|
||||
## About
|
||||
|
||||
The A2A Protocol is an open-source project by Google LLC, under the [Apache License 2.0](LICENSE), and is open to contributions from the community.
|
||||
The A2A Protocol is an open source project under the Linux Foundation, contributed by Google. It is licensed under the [Apache License 2.0](LICENSE) and is open to contributions from the community.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
# Security Policy
|
||||
|
||||
To report a security issue, please use email security@lists.a2aproject.org.
|
||||
To report a security issue, please use email <security@lists.a2aproject.org>.
|
||||
|
||||
We use a mailing list for our intake, and do coordination and disclosure here using GitHub Security Advisory to privately discuss and fix the issue.
|
||||
|
||||
73
adrs/adr-001-protojson-serialization.md
Normal file
@ -0,0 +1,73 @@
|
||||
# ADR-001: Leverage ProtoJSON Specification for JSON Serialization
|
||||
|
||||
**Status:** Accepted
|
||||
|
||||
**Date:** 2025-11-18
|
||||
|
||||
**Decision Makers:** Technical Steering Committee (TSC)
|
||||
|
||||
**Technical Story:** JSON serialization approach for A2A specification
|
||||
|
||||
## Context
|
||||
|
||||
The A2A specification defines message structures using Protocol Buffers (proto definitions) but also needs to support JSON serialization for HTTP/REST-based communication and JSONRPC payloads. We needed to establish a normative approach for how JSON payloads should be serialized based on the proto definitions referenced by the specification.
|
||||
|
||||
Without a clearly specified approach to JSON serialization from proto definitions, implementers could create incompatible JSON representations, leading to interoperability issues across different A2A implementations.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
* Need for a standardized, well-documented approach to JSON serialization
|
||||
* Ability to leverage existing Protocol Buffer tooling
|
||||
* Clear specification for handling edge cases and type mappings
|
||||
* Idiomatic use of JSON conventions
|
||||
* Coupling of specification to tool chain
|
||||
|
||||
## Considered Options
|
||||
|
||||
* ProtoJSON (canonical JSON encoding for Protocol Buffers)
|
||||
* Explicit transformation rules defined in the A2A specification
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
**Chosen option:** "ProtoJSON specification"
|
||||
|
||||
The TSC has decided to leverage the ProtoJSON specification as the normative approach to serializing JSON based on the proto definition referenced by the specification. This provides a well-defined, standardized way to convert Protocol Buffer messages to JSON format.
|
||||
|
||||
This decision was made with some reservation due to the dependency on ProtoJSON mechanisms and potential impact on protocol bindings unrelated to protobuf and gRPC. However, the decision is reversible if we identify significant issues during implementation, at which point we can duplicate the ProtoJSON conventions in the A2A specification where applicable and describe differences as needed.
|
||||
|
||||
### Consequences
|
||||
|
||||
#### Positive
|
||||
|
||||
* Standardized approach with clear documentation and specification
|
||||
* Wide ecosystem support with mature libraries across multiple languages
|
||||
* Consistent behavior across different implementations
|
||||
* Reduced ambiguity in JSON representation
|
||||
* Built-in handling for proto3 types and conventions
|
||||
* Provides well-defined rules for wire-unsafe changes
|
||||
* Removes the need to define data type handling rules for dates and numbers in the A2A specification
|
||||
|
||||
#### Negative
|
||||
|
||||
* **Breaking change**: This decision will result in breaking changes to existing JSON payloads, specifically relating to the casing of enum values (ProtoJSON uses SCREAMING_SNAKE_CASE for enums)
|
||||
* **Loss of roundtrip capability**: We will not be able to roundtrip unknown values because ProtoJSON doesn't support preserving unknown fields in the JSON representation
|
||||
* Migration effort required for existing implementations
|
||||
* **Ugly enums** Developers are not used to seeing enum values in SCREAMING_SNAKE_CASE in JSON, which may lead to confusion or errors during implementation
|
||||
* Changes to the ProtoJSON specification for the benefit of gRPC could have an impact on other protocol bindings.
|
||||
* Enums require a "unspecified" value even when they are only used for required fields to meet Proto best practices.
|
||||
* Certain field names need to have less than optimal names to avoid conflicts with proto keywords. e.g. message.
|
||||
|
||||
#### Neutral
|
||||
|
||||
* Implementations must follow ProtoJSON specification strictly
|
||||
* Documentation must clearly communicate the breaking changes
|
||||
|
||||
## References
|
||||
|
||||
* [ProtoJSON format](https://protobuf.dev/programming-guides/json/)
|
||||
|
||||
## Notes
|
||||
|
||||
This decision was made to ensure long-term interoperability and maintainability of the A2A specification. While it introduces breaking changes in the short term, the benefits of standardization and ecosystem alignment outweigh the migration costs.
|
||||
|
||||
Implementers should be aware that the enum casing change is the most visible breaking change and should plan accordingly for version transitions.
|
||||
113
adrs/adr-template.md
Normal file
@ -0,0 +1,113 @@
|
||||
# ADR-[number]: [Title]
|
||||
|
||||
**Status:** [Proposed | Accepted | Deprecated | Superseded]
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
|
||||
**Decision Makers:** [List of people involved in the decision]
|
||||
|
||||
**Technical Story:** [Optional: Link to related issue/story]
|
||||
|
||||
## Context
|
||||
|
||||
[Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?]
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
* [Driver 1: e.g., performance requirements]
|
||||
* [Driver 2: e.g., maintainability concerns]
|
||||
* [Driver 3: e.g., team expertise]
|
||||
* [Driver 4: e.g., cost considerations]
|
||||
|
||||
## Considered Options
|
||||
|
||||
* [Option 1]
|
||||
* [Option 2]
|
||||
* [Option 3]
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
**Chosen option:** "[Option X]"
|
||||
|
||||
[Describe why this option was selected. What are the expected positive outcomes?]
|
||||
|
||||
### Consequences
|
||||
|
||||
#### Positive
|
||||
|
||||
* [Positive consequence 1]
|
||||
* [Positive consequence 2]
|
||||
|
||||
#### Negative
|
||||
|
||||
* [Negative consequence 1]
|
||||
* [Negative consequence 2]
|
||||
|
||||
#### Neutral
|
||||
|
||||
* [Neutral consequence 1]
|
||||
|
||||
## [Optional] Pros and Cons of the Options
|
||||
|
||||
### [Option 1]
|
||||
|
||||
[Brief description of option 1]
|
||||
|
||||
**Pros:**
|
||||
|
||||
* [Advantage 1]
|
||||
* [Advantage 2]
|
||||
|
||||
**Cons:**
|
||||
|
||||
* [Disadvantage 1]
|
||||
* [Disadvantage 2]
|
||||
|
||||
### [Option 2]
|
||||
|
||||
[Brief description of option 2]
|
||||
|
||||
**Pros:**
|
||||
|
||||
* [Advantage 1]
|
||||
* [Advantage 2]
|
||||
* [Advantage 2]
|
||||
|
||||
**Cons:**
|
||||
|
||||
* [Disadvantage 1]
|
||||
* [Disadvantage 2]
|
||||
|
||||
### [Option 3]
|
||||
|
||||
[Brief description of option 3]
|
||||
|
||||
**Pros:**
|
||||
|
||||
* [Advantage 1]
|
||||
* [Advantage 2]
|
||||
* [Advantage 2]
|
||||
|
||||
**Cons:**
|
||||
|
||||
* [Disadvantage 1]
|
||||
* [Disadvantage 2]
|
||||
|
||||
## Implementation
|
||||
|
||||
[Optional: Describe the implementation plan, timeline, and any specific technical details]
|
||||
|
||||
## Related Decisions
|
||||
|
||||
* [Link to related ADR 1]
|
||||
* [Link to related ADR 2]
|
||||
|
||||
## References
|
||||
|
||||
* [Link to resource 1]
|
||||
* [Link to resource 2]
|
||||
* [Link to resource 3]
|
||||
|
||||
## Notes
|
||||
|
||||
[Any additional notes, follow-up items, or context that doesn't fit elsewhere]
|
||||
55
docs/announcing-1.0.md
Normal file
@ -0,0 +1,55 @@
|
||||
# A2A Protocol Ships v1.0: Production-Ready Standard for Agent-to-Agent Communication
|
||||
|
||||
The A2A Protocol community today are announcing the release of A2A Protocol v1.0, marking the first stable, production-ready version of the open standard for communication between AI agents. The protocol is guided by a technical steering committee with representatives from eight major technology companies.
|
||||
|
||||
As organizations build increasingly sophisticated multi-agent systems, interoperability has become the defining challenge. Teams can coordinate agents effectively within a single platform, but connecting those systems across technology stacks and organizational boundaries remains difficult. A2A addresses that challenge by combining support for multiple protocol bindings, seamless version negotiation, and a common semantic model so agents can interoperate across systems with predictable behavior.
|
||||
|
||||
The v1.0 release emphasizes maturity rather than reinvention: the core ideas remain intact, while rough edges have been removed, ambiguous areas clarified, and enterprise deployment requirements addressed more directly. The official SDKs ensure v1.0 A2A agents work seamlessly with older versions.
|
||||
|
||||
## Delivering on enterprise requirements
|
||||
|
||||
The v1.0 release introduces several capabilities aimed at production environments where trust, scale, and operational control are non-negotiable.
|
||||
|
||||
- **Heterogeneous environment support** enables interoperability across diverse technology stacks through multi-protocol bindings and version negotiation, so enterprises are not tied to a single vendor or platform.
|
||||
- **Multi-tenancy support** allows a single endpoint to securely host many agents.
|
||||
- **Signed Agent Cards** provide cryptographic verification of agent identity and metadata, establishing trust before interaction across organizational boundaries.
|
||||
- **Improved security posture** modernizes security flows and removes legacy patterns that are no longer aligned with current best practices.
|
||||
|
||||
Together, these changes move A2A from early adopter implementations toward broader enterprise confidence, especially in regulated or multi-party scenarios.
|
||||
|
||||
## Web-aligned architecture for scale
|
||||
|
||||
A2A v1.0 aligns with core architectural principles of the web: stateless, layered architecture, standard protocol bindings, and infrastructure-friendly communication patterns. That alignment matters operationally because organizations can scale agent interactions with the same proven load balancing, gateway, security and observability patterns they already use for web systems.
|
||||
|
||||
The standard builds on industry-proven protocols, including JSON+HTTP, gRPC, and JSON-RPC. It also keeps the barrier to entry low: in its simplest form, an A2A interaction can begin with a single HTTP request.
|
||||
|
||||
A2A also gives consumers flexibility in how they receive results. Depending on workload and operational needs, clients can use polling, streaming, or webhooks to consume task updates and responses.
|
||||
|
||||
## Complementary to MCP, not a replacement
|
||||
|
||||
The release also reinforces A2A's relationship with the Model Context Protocol (MCP), a point that has generated confusion in early ecosystem discussions.
|
||||
|
||||
MCP and A2A solve different layers of the problem. MCP is commonly used for tool and context integration at the individual agent level. A2A focuses on communication and coordination between agents. In practice, many systems will use both: MCP inside agents, A2A between agents.
|
||||
|
||||
## Smooth migration from earlier versions
|
||||
|
||||
The v1.0 release tightens specification behavior, which includes breaking changes in the interaction protocol. AgentCard, however, has evolved in a backward-compatible way and now allows agents to advertise support for both existing v0.3 protocol behavior and v1.0 simultaneously. This enables clients to migrate progressively rather than through a single cutover.
|
||||
|
||||
That approach is intended to protect current investments while still delivering the benefits of a cleaner, more durable standard.
|
||||
|
||||
## Why this release matters now
|
||||
|
||||
AI agents are increasingly deployed across departments, products, and partner ecosystems. At that scale, the key question is no longer whether agents can coordinate within one stack, but whether they can collaborate reliably across organizational and platform boundaries. Open protocols determine whether organizations can compose best-of-breed systems or become locked into isolated stacks.
|
||||
|
||||
A2A v1.0 gives the market a stronger foundation for open multi-agent collaboration. The community is now focused on delivering multi-language v1.0 SDK support to help developers build conformant solutions with ease.
|
||||
|
||||
The complete v1.0 materials, including specification and migration documentation, are available at [a2a-protocol.org](https://a2a-protocol.org) and on [GitHub](https://github.com/a2aproject/A2A).
|
||||
|
||||
---
|
||||
|
||||
**About A2A Protocol**
|
||||
The Agent-to-Agent (A2A) Protocol is an open standard that enables AI agents to discover capabilities, communicate, and delegate tasks across teams, products, and organizations. The A2A Technical Steering Committee includes representatives from AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow.
|
||||
|
||||
**Media Contact**
|
||||
A2A Protocol Community
|
||||
[https://a2a-protocol.org](https://a2a-protocol.org)
|
||||
BIN
docs/assets/a2a_logo/black/PNG/a2a_black.png
Normal file
|
After Width: | Height: | Size: 30 KiB |
616
docs/assets/a2a_logo/black/SVG/a2a_black.svg
Normal file
|
After Width: | Height: | Size: 51 KiB |
BIN
docs/assets/a2a_logo/color/PNG/a2a_color.png
Normal file
|
After Width: | Height: | Size: 31 KiB |
616
docs/assets/a2a_logo/color/SVG/a2a_color.svg
Normal file
|
After Width: | Height: | Size: 51 KiB |
BIN
docs/assets/a2a_logo/icon/black/PNG/a2a_icon_black.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
601
docs/assets/a2a_logo/icon/black/SVG/a2a_icon_black.svg
Normal file
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/assets/a2a_logo/icon/color/PNG/a2a_icon_color.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
601
docs/assets/a2a_logo/icon/color/SVG/a2a_icon_color.svg
Normal file
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/assets/a2a_logo/icon/white/PNG/a2a_icon_white.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
601
docs/assets/a2a_logo/icon/white/SVG/a2a_icon_white.svg
Normal file
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/assets/a2a_logo/mascot/PNG/a2a_ada.png
Normal file
|
After Width: | Height: | Size: 226 KiB |
725
docs/assets/a2a_logo/mascot/SVG/a2a_ada.svg
Normal file
|
After Width: | Height: | Size: 125 KiB |
BIN
docs/assets/a2a_logo/white/PNG/a2a_white.png
Normal file
|
After Width: | Height: | Size: 28 KiB |
616
docs/assets/a2a_logo/white/SVG/a2a_white.svg
Normal file
|
After Width: | Height: | Size: 51 KiB |
@ -16,28 +16,6 @@ Stay up-to-date with the latest announcements, tutorials, and insights from the
|
||||
|
||||
---
|
||||
|
||||
## Upcoming Events
|
||||
|
||||
Connect with us at these upcoming events to learn more about A2A, see live demos, and participate in hands-on hackathons.
|
||||
|
||||
- **University of Florida Hackathon**
|
||||
- *October (Date TBD)*
|
||||
- Join us for a hackathon focused on building innovative solutions with A2A.
|
||||
|
||||
- **São Paulo Summit**
|
||||
- *September 10-11*
|
||||
- Featuring key announcements, including the new Agent Payments Protocol.
|
||||
|
||||
- **Mexico City Summit**
|
||||
- *September 3-4*
|
||||
- Explore the latest content and use cases for A2A.
|
||||
|
||||
- **Tokyo Summit**
|
||||
- *August 4*
|
||||
- Discover how A2A is being used to power the next generation of AI agents.
|
||||
|
||||
---
|
||||
|
||||
## Use Case Highlights
|
||||
|
||||
A2A unlocks powerful new ways for AI agents to collaborate and solve complex problems. Here are a few examples of what's possible:
|
||||
@ -77,10 +55,50 @@ The launch of A2A has sparked lively discussions and positive reactions across v
|
||||
These agentic frameworks have built-in A2A integration, making it easy to get started:
|
||||
|
||||
- [Agent Development Kit (ADK)](https://google.github.io/adk-docs/a2a/)
|
||||
- [Agno](https://docs.agno.com/agent-os/interfaces/a2a/introduction)
|
||||
- [AG2](https://docs.ag2.ai/latest/docs/user-guide/a2a/)
|
||||
- [BeeAI Framework](https://framework.beeai.dev/integrations/a2a)
|
||||
- [LangGraph](https://docs.langchain.com/langgraph-platform/server-a2a)
|
||||
- [CrewAI](https://docs.crewai.com/en/learn/a2a-agent-delegation)
|
||||
- [Hector](https://github.com/kadirpekel/hector)
|
||||
- [LangGraph](https://docs.langchain.com/langsmith/server-a2a)
|
||||
- [LiteLLM](https://docs.litellm.ai/docs/a2a)
|
||||
- [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-types/a2a-agent)
|
||||
- [Pydantic AI](https://ai.pydantic.dev/a2a/)
|
||||
- [Slide (Tyler)](https://slide.mintlify.app/guides/a2a-integration)
|
||||
- [Strands Agents](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/multi-agent/agent-to-agent/)
|
||||
|
||||
## Community SDKs
|
||||
|
||||
Building an A2A agent in a language not covered by the [official SDKs](./sdk/index.md)? These community-maintained implementations have you covered.
|
||||
|
||||
### 🦀 Rust — a2a-rust
|
||||
|
||||
 [](https://crates.io/crates/a2a-protocol-sdk)
|
||||
|
||||
[tomtom215/a2a-rust](https://github.com/tomtom215/a2a-rust) · A2A spec v1.0.0 · Full SDK with JSON-RPC, REST, WebSocket, and gRPC transports.
|
||||
|
||||
### 🦀 Rust — a2a-rs
|
||||
|
||||
 [](https://crates.io/crates/a2a-rs)
|
||||
|
||||
[EmilLindfors/a2a-rs](https://github.com/EmilLindfors/a2a-rs) · A2A spec v0.3.0 · Modular workspace with core protocol, AP2 extension, and agent framework.
|
||||
|
||||
### 🍎 Swift — A2AClient
|
||||
|
||||

|
||||
|
||||
[tolgaki/a2a-client-swift](https://github.com/tolgaki/a2a-client-swift) · A2A spec v1.0.0 · Swift Package Manager. iOS 15+, macOS 12+, watchOS 8+, tvOS 15+.
|
||||
|
||||
### 💧 Elixir — a2a
|
||||
|
||||
 [](https://hex.pm/packages/a2a)
|
||||
|
||||
[actioncard/a2a-elixir](https://github.com/actioncard/a2a-elixir) · A2A spec v0.2.0 · OTP-native with Agent behaviour, TaskStore, and supervision tree.
|
||||
|
||||
!!! tip "Want to add your SDK?"
|
||||
Open an issue on [a2aproject/A2A](https://github.com/a2aproject/A2A/issues/new?title=Community%20SDK%20Submission) with a link to your repository and published package.
|
||||
|
||||
**Requirements:** Spec compliance, published package on standard registry, documentation, tests with CI, Apache 2.0 license, and active maintenance.
|
||||
|
||||
## The Future is Interoperable
|
||||
|
||||
|
||||
31
docs/definitions.md
Normal file
@ -0,0 +1,31 @@
|
||||
# A2A Definition/Schema
|
||||
|
||||
=== "Protobuf"
|
||||
<h3>Protobuf</h3>
|
||||
The normative A2A protocol definition in Protocol Buffers (proto3 syntax).
|
||||
This is the source of truth for the A2A protocol specification.
|
||||
|
||||
<h3>Download</h3>
|
||||
|
||||
You can download the proto file directly: [`a2a.proto`](spec/a2a.proto)
|
||||
|
||||
<h3>Definition</h3>
|
||||
|
||||
```protobuf
|
||||
--8<-- "docs/spec/a2a.proto"
|
||||
```
|
||||
|
||||
=== "JSON"
|
||||
<h3>JSON</h3>
|
||||
The A2A protocol JSON Schema definition (JSON Schema 2020-12 compliant).
|
||||
This schema is automatically generated from the protocol buffer definitions and bundled into a single file with all message definitions.
|
||||
|
||||
<h3>Download</h3>
|
||||
|
||||
You can download the schema file directly: [`a2a.json`](spec/a2a.json)
|
||||
|
||||
<h3>Definition</h3>
|
||||
|
||||
```json
|
||||
--8<-- "docs/spec/a2a.json"
|
||||
```
|
||||
@ -31,7 +31,11 @@ Originally developed by Google and now donated to the Linux Foundation, A2A prov
|
||||
|
||||
- :material-play-circle:{ .lg .middle } **Video** Intro in <8 min
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/Fbr_Solax1w?si=QxPMEEiO5kLr5_0F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
<iframe class="video-container" src="https://www.youtube.com/embed/Fbr_Solax1w?si=QxPMEEiO5kLr5_0F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
|
||||
- :material-play-circle:{ .lg .middle } **Course** [DeepLearning.AI](https://deeplearning.ai) - Intro to A2A
|
||||
|
||||
[](https://goo.gle/dlai-a2a)
|
||||
|
||||
- :material-book-open:{ .lg .middle } **Read the Introduction**
|
||||
|
||||
@ -53,6 +57,8 @@ Originally developed by Google and now donated to the Linux Foundation, A2A prov
|
||||
|
||||
[:octicons-arrow-right-24: Python Tutorial](./tutorials/python/1-introduction.md)
|
||||
|
||||
[:octicons-arrow-right-24: Walkthrough with AI Agent Frameworks](https://github.com/holtskinner/A2AWalkthrough)
|
||||
|
||||
- :material-code-braces:{ .lg .middle } **Explore Code Samples**
|
||||
|
||||
See A2A in action with sample clients, servers, and agent framework integrations.
|
||||
@ -120,5 +126,5 @@ A2A and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) are com
|
||||
|
||||
- **Model Context Protocol (MCP)**: Provides [agent-to-tool communication](https://cloud.google.com/discover/what-is-model-context-protocol). It's a complementary standard that standardizes how an agent connects to its tools, APIs, and resources to get information.
|
||||
- **IBM ACP**: [Incorporated into the A2A Protocol](https://github.com/orgs/i-am-bee/discussions/5)
|
||||
- **Cisco agntcy**: A framework for building the internal logic of a single, complex agent system, often with a supervisor/expert structure.
|
||||
- **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](https://cloud.google.com/discover/what-are-ai-agents)—including those using MCP, or built with frameworks like agntcy—to interoperate, collaborate, and share their findings.
|
||||
|
||||
251
docs/llms.txt
@ -1,210 +1,81 @@
|
||||
# A2A (Agent2Agent) Protocol High-Level Summary
|
||||
|
||||
This project defines and demonstrates the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. The core goal is to allow agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) or by different vendors to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely.
|
||||
This project defines the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. It allows agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely without exposing internal state.
|
||||
|
||||
The repository provides:
|
||||
The repository contains:
|
||||
1. **Formal Specification:** Protobuf definitions (`specification/a2a.proto`) and JSON Schema (`specification/json/a2a.json`).
|
||||
2. **Core Concepts Documentation:** Guides on discovery, task lifecycle, streaming, and enterprise-readiness (`docs/topics/`).
|
||||
3. **SDKs:** Production-ready SDKs for Python, JS/TS, Java, Go, and .NET.
|
||||
4. **Sample Implementations:** Real-world examples integrated with various agent frameworks.
|
||||
|
||||
1. **Formal Specification:** A detailed JSON Schema (`specification/json/a2a.json`) and Protobuf definitions (`specification/grpc/a2a.proto`) that define the structure of A2A messages, including requests, responses, tasks, artifacts, and agent metadata (Agent Cards).
|
||||
2. **Core Concepts Documentation:** A comprehensive set of documents in the `docs/topics/` directory covering agent discovery, task lifecycle, streaming, push notifications, and enterprise-readiness.
|
||||
3. **SDKs and Sample Implementations:**
|
||||
* **SDKs:** Production-ready SDKs for Python, Java, JavaScript, and C#/.NET, with more in development.
|
||||
* **Example Agents:** Demonstrations of integrating A2A into various agent frameworks:
|
||||
* **Python:** LangGraph (currency conversion, streaming), CrewAI (image generation, file artifacts), Google ADK (expense reports, form handling).
|
||||
* **JavaScript/TypeScript:** Genkit (movie info via API, code generation with file artifacts).
|
||||
* **Example Hosts:** Applications that consume A2A services, including CLIs for direct interaction and a Python-based multi-agent orchestrator.
|
||||
4. **Demo Web Application:** A web UI demonstrating multi-agent interactions facilitated by the A2A protocol, including visualization of conversations, tasks, events, and agent discovery.
|
||||
## Key Files & Directories
|
||||
|
||||
Key features of the A2A protocol include: agent discovery via Agent Cards, standardized task management (`send`, `get`, `cancel`), support for rich content types (text, files, structured data), real-time streaming updates for long-running tasks, and mechanisms for asynchronous push notifications. The project is open-source and encourages community contribution.
|
||||
- `specification/a2a.proto`: The authoritative Protobuf definition of the protocol.
|
||||
- `docs/topics/`: Detailed conceptual guides (Discovery, Lifecycle, Security, etc.).
|
||||
- `docs/tutorials/`: Step-by-step guides for building A2A-compliant agents.
|
||||
- `scripts/`: Utility scripts for building documentation and formatting.
|
||||
|
||||
# A2A (Agent2Agent) Protocol
|
||||
# A2A (Agent2Agent) Protocol Reference
|
||||
|
||||
## 1. Overview
|
||||
|
||||
- **Project Name:** Agent2Agent (A2A) Protocol
|
||||
- **Purpose:** An open protocol enabling communication and interoperability between AI agents built on different frameworks or by different vendors.
|
||||
- **Core Goal:** Allow agents to discover capabilities, negotiate interaction, and collaborate securely on tasks.
|
||||
- **Communication:** Uses JSON-RPC 2.0 over HTTP(S). Supports standard request/response and Server-Sent Events (SSE) for streaming. Also includes a gRPC specification.
|
||||
- **Key Components:** Formal Specification (JSON Schema, Protobuf), SDKs (Python, JS, Java, .NET), Sample Implementations, and Core Documentation.
|
||||
- **Purpose:** Open standard for agent-to-agent interoperability.
|
||||
- **Communication Bindings:** Supports JSON-RPC 2.0 (HTTP/SSE), gRPC, and HTTP/REST.
|
||||
- **Key Concepts:** Agent Cards for discovery, Task-based execution, Multi-turn Messages, and Artifact outputs.
|
||||
|
||||
## 2. Protocol Specification (`specification/json/a2a.json`)
|
||||
## 2. Core Data Objects
|
||||
|
||||
### 2.1. Core JSON-RPC Structures
|
||||
### 2.1 AgentCard (`/.well-known/agent-card.json`)
|
||||
Describes an agent's identity and capabilities.
|
||||
- `name`, `description`, `version`: Identity metadata.
|
||||
- `supported_interfaces`: List of `AgentInterface` (URL, protocol binding, tenant, protocol version).
|
||||
- `capabilities`: `streaming`, `push_notifications`, `extended_agent_card`, `extensions`.
|
||||
- `skills`: List of `AgentSkill` (id, name, description, tags, examples).
|
||||
- `security_schemes`, `security_requirements`: Authentication configuration (API Key, OAuth2, OIDC, mTLS, HTTP Auth).
|
||||
- `default_input_modes`, `default_output_modes`: Supported MIME types (e.g., `text/plain`, `application/json`).
|
||||
|
||||
- **`JSONRPCMessage`:** Base for requests/responses. Contains `jsonrpc: "2.0"` and optional `id`.
|
||||
- **`JSONRPCRequest`:** Represents a request with `method`, `params`, and `id`.
|
||||
- **`JSONRPCResponse`:** Represents a response with either `result` or `error`, and a matching `id`.
|
||||
- **`JSONRPCError`:** Represents an error with `code`, `message`, and optional `data`.
|
||||
### 2.2 Task
|
||||
Represents a stateful unit of work.
|
||||
- `id`, `context_id`: Identifiers for the task and its conversational context.
|
||||
- `status`: `TaskStatus` (state, message, timestamp).
|
||||
- `artifacts`: List of `Artifact` (outputs produced).
|
||||
- `history`: List of `Message` (conversation history).
|
||||
- `metadata`: Custom structured data.
|
||||
|
||||
### 2.2. Key A2A Data Objects
|
||||
### 2.3 TaskState (Enum)
|
||||
- `SUBMITTED`, `WORKING`, `COMPLETED` (terminal), `FAILED` (terminal), `CANCELED` (terminal), `REJECTED` (terminal), `INPUT_REQUIRED` (interrupted), `AUTH_REQUIRED` (interrupted).
|
||||
|
||||
- **`AgentCard`:** Metadata describing an agent, typically found at `/.well-known/agent-card.json`.
|
||||
- `protocolVersion`: (string) The version of the A2A protocol supported.
|
||||
- `name`, `description`, `version`: (string) Agent's identity.
|
||||
- `url`: (string) The preferred endpoint URL for the agent's A2A service.
|
||||
- `provider`: (`AgentProvider`) Organization details.
|
||||
- `capabilities`: (`AgentCapabilities`) Features supported (streaming, push notifications, extensions).
|
||||
- `securitySchemes`, `security`: (object, array) Authentication and authorization requirements, following OpenAPI specifications.
|
||||
- `defaultInputModes`, `defaultOutputModes`: (string[]) Default supported MIME types.
|
||||
- `skills`: (`AgentSkill[]`) List of specific capabilities.
|
||||
- `supportsAuthenticatedExtendedCard`: (boolean) Indicates if a more detailed card is available post-authentication.
|
||||
- `signatures`: (`AgentCardSignature[]`) JWS signatures for verifying the card's integrity.
|
||||
- **`AgentSkill`:** A specific capability of an agent, with `id`, `name`, `description`, `tags`, and `examples`.
|
||||
- **`Task`:** Represents a stateful unit of work.
|
||||
- `id`, `contextId`: (string) Unique identifiers for the task and its conversational context.
|
||||
- `status`: (`TaskStatus`) Current state information.
|
||||
- `artifacts`: (`Artifact[]`) Outputs produced by the agent.
|
||||
- `history`: (`Message[]`) The conversation history associated with the task (if enabled by `stateTransitionHistory` capability).
|
||||
- `metadata`: (object) Custom key-value data.
|
||||
- `kind`: ("task") Type discriminator.
|
||||
- **`TaskStatus`:**
|
||||
- `state`: (`TaskState`) Current lifecycle state (e.g., "working", "completed").
|
||||
- `message`: (`Message`) An optional, human-readable message from the agent providing status details.
|
||||
- `timestamp`: (string) ISO-8601 timestamp.
|
||||
- **`TaskState`:** (enum) `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`, `rejected`, `auth-required`, `unknown`.
|
||||
- **`Message`:** A single unit of communication.
|
||||
- `role`: ("user" | "agent") Sender's role.
|
||||
- `parts`: (`Part[]`) The content of the message.
|
||||
- `messageId`, `taskId`, `contextId`: (string) Identifiers linking the message.
|
||||
- `referenceTaskIds`: (string[]) List of prior tasks for context.
|
||||
- **`Part` (Union Type):** A segment of content within a `Message` or `Artifact`.
|
||||
- **`TextPart`:** Plain text content.
|
||||
- **`FilePart`:** A file, referenced by URI or with inline base64-encoded bytes.
|
||||
- **`DataPart`:** Structured JSON data.
|
||||
- **`Artifact`:** A tangible output generated by a task, composed of one or more `Part`s.
|
||||
- **`PushNotificationConfig`:** Configuration for receiving asynchronous updates via a webhook URL.
|
||||
- **`agent/getAuthenticatedExtendedCard`:** An RPC method to retrieve a more detailed `AgentCard` after authentication.
|
||||
### 2.4 Message & Part
|
||||
- `Message`: Contains `message_id`, `role` (USER/AGENT), `parts`, `context_id`, `task_id`, `reference_task_ids`.
|
||||
- `Part`: Union type containing `text`, `raw` (bytes), `url`, or `data` (JSON). Includes `media_type` and `filename`.
|
||||
|
||||
### 2.3. A2A RPC Methods
|
||||
### 2.5 Artifact
|
||||
- A tangible output from a task, containing one or more `Part`s and metadata.
|
||||
|
||||
- **`message/send`:** (Request/Response)
|
||||
- Sends a message to initiate or continue a task.
|
||||
- `params`: `MessageSendParams` (includes `taskId`, `contextId`, `message`, optionally `configuration`).
|
||||
- `result`: `Task` (final state after synchronous processing).
|
||||
- **`message/stream`:** (Request/Stream)
|
||||
- Sends a message and subscribes to real-time updates via Server-Sent Events (SSE).
|
||||
- `params`: `MessageSendParams`.
|
||||
- `result` (stream events): `SendStreamingMessageResponse` containing one of: `MessageEvent`, `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`. Final event has `final: true`.
|
||||
- **`tasks/get`:** (Request/Response)
|
||||
- Retrieves the current state of a task.
|
||||
- `params`: `TaskQueryParams` (includes `id`, optionally `historyLength`).
|
||||
- `result`: `Task`.
|
||||
- **`tasks/list`:** (Request/Response)
|
||||
- Retrieves a list of tasks with optional filtering and pagination.
|
||||
- `params`: `ListTasksParams` (optional: `contextId`, `status`, `pageSize`, `pageToken`, `historyLength`, `lastUpdatedAfter`, `includeArtifacts`, `metadata`).
|
||||
- `result`: `ListTasksResult` (includes `tasks[]`, `totalSize`, `pageSize`, `nextPageToken`).
|
||||
- **`tasks/cancel`:** (Request/Response)
|
||||
- Requests cancellation of a running task.
|
||||
- `params`: `TaskIdParams` (includes `id`).
|
||||
- `result`: `Task` (updated state, likely 'canceled') or error if not cancelable.
|
||||
- **`tasks/pushNotificationConfig/set`:** (Request/Response)
|
||||
- Sets or updates the push notification configuration for a task.
|
||||
- `params`: `TaskPushNotificationConfig`.
|
||||
- `result`: `TaskPushNotificationConfig` (confirmed configuration).
|
||||
- **`tasks/pushNotificationConfig/get`:** (Request/Response)
|
||||
- Retrieves the current push notification configuration for a task.
|
||||
- `params`: `TaskIdParams` (includes `taskId`).
|
||||
- `result`: `TaskPushNotificationConfig`.
|
||||
- **`tasks/resubscribe`:** (Request/Stream)
|
||||
- Resubscribes to task updates after a connection interruption (SSE).
|
||||
- `params`: `TaskQueryParams`.
|
||||
- `result` (stream events): `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent`.
|
||||
## 3. RPC Methods
|
||||
|
||||
### 2.4. Streaming Update Events (Result of `message/stream` or `tasks/resubscribe`)
|
||||
| Method | Request | Response | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `SendMessage` | `SendMessageRequest` | `SendMessageResponse` | Initiates or continues a task. |
|
||||
| `SendStreamingMessage` | `SendMessageRequest` | `stream StreamResponse` | Sends message and receives real-time SSE updates. |
|
||||
| `GetTask` | `GetTaskRequest` | `Task` | Retrieves current task state. |
|
||||
| `ListTasks` | `ListTasksRequest` | `ListTasksResponse` | Filter and paginate tasks. |
|
||||
| `CancelTask` | `CancelTaskRequest` | `Task` | Requests cancellation of a task. |
|
||||
| `SubscribeToTask` | `SubscribeToTaskRequest` | `stream StreamResponse` | Subscribes to updates for an existing task. |
|
||||
| `GetExtendedAgentCard` | `GetExtendedAgentCardRequest` | `AgentCard` | Fetches detailed metadata after authentication. |
|
||||
|
||||
- **`SendStreamingMessageResponse`:** Contains a message from the agent.
|
||||
- `type`: "message"
|
||||
- `message`: (`Message`) The message content.
|
||||
- `contextId`: (string) Context identifier the message is associated with.
|
||||
- `kind`: ("streaming-response") Type discriminator.
|
||||
- `final`: (boolean) True if this is the final message for the task.
|
||||
- **`TaskStatusUpdateEvent`:** Signals a change in task status.
|
||||
- `type`: "task-status"
|
||||
- `taskId`: (string) Task ID.
|
||||
- `contextId`: (string) Context identifier the task is associated with.
|
||||
- `kind`: ("status-update") Type discriminator.
|
||||
- `status`: (`TaskStatus`) The new status object.
|
||||
- `final`: (boolean) True if this is the terminal update for the task.
|
||||
- **`TaskArtifactUpdateEvent`:** Signals a new or updated artifact.
|
||||
- `type`: "task-artifact"
|
||||
- `taskId`: (string) Task ID.
|
||||
- `artifact`: (`Artifact`) The artifact data.
|
||||
- `append`: (boolean) If true, append parts to artifact; if false (default), replace.
|
||||
- `lastChunk`: (boolean) If true, indicates this is the final update for the artifact.
|
||||
- `final`: (boolean) Usually false for artifacts, can signal end concurrently with status.
|
||||
### 3.1 Streaming Events (`StreamResponse`)
|
||||
Streams return a payload containing one of:
|
||||
- `task`: Full task state.
|
||||
- `message`: A discrete message part.
|
||||
- `status_update`: `TaskStatusUpdateEvent` (taskId, contextId, status).
|
||||
- `artifact_update`: `TaskArtifactUpdateEvent` (taskId, artifact, append, last_chunk).
|
||||
|
||||
### 2.5. Standard Error Codes
|
||||
## 4. Security & Authentication
|
||||
- **Transport:** HTTPS/TLS required for production.
|
||||
- **Authentication:** Declared in `AgentCard` via OpenAPI-style security schemes.
|
||||
- **Push Notifications:** Webhooks secured via authentication tokens/schemes configured per task.
|
||||
|
||||
- `-32700`: `JSONParseError`
|
||||
- `-32600`: `InvalidRequestError`
|
||||
- `-32601`: `MethodNotFoundError`
|
||||
- `-32602`: `InvalidParamsError`
|
||||
- `-32603`: `InternalError`
|
||||
|
||||
### 2.6. A2A Specific Error Codes
|
||||
|
||||
- `-32001`: `TaskNotFoundError`
|
||||
- `-32002`: `TaskNotCancelableError`
|
||||
- `-32003`: `PushNotificationNotSupportedError`
|
||||
- `-32004`: `UnsupportedOperationError`
|
||||
- `-32005`: `ContentTypeNotSupportedError`
|
||||
- `-32006`: `InvalidAgentResponseError`
|
||||
- `-32007`: `AuthenticatedExtendedCardNotConfiguredError`
|
||||
|
||||
## 3. Core Concepts
|
||||
|
||||
- **Agent Discovery:** Clients find agents by fetching their `AgentCard` JSON, typically from a `/.well-known/agent-card.json` URI or a curated registry.
|
||||
- **Task Lifecycle:** Tasks progress through defined states (`submitted` -> `working` -> `completed`/`failed`, etc.), enabling tracking of long-running operations.
|
||||
- **Communication:** Interactions use `Message` objects containing `Part`s (text, file, data). Task outputs are delivered as `Artifact`s.
|
||||
- **Streaming:** Long-running tasks provide real-time updates via SSE using the `message/stream` method. Updates can be `Task`, `Message`, `TaskStatusUpdateEvent`, or `TaskArtifactUpdateEvent` objects.
|
||||
- **Push Notifications:** For disconnected clients, agents can send updates to a webhook URL configured via `tasks/pushNotificationConfig/set`.
|
||||
- **Authentication:** A2A leverages standard web security (e.g., OAuth, API keys), declared in the `AgentCard`. Credentials are sent via HTTP headers, not in the A2A payload.
|
||||
|
||||
## 4. Security Considerations
|
||||
|
||||
- **Transport Security:** Production environments MUST use HTTPS with modern TLS.
|
||||
- **Authentication:** Servers MUST authenticate every request based on schemes declared in the `AgentCard`.
|
||||
- **Authorization:** Authorization logic is implementation-specific and MUST enforce the principle of least privilege, potentially on a per-skill basis.
|
||||
- **Push Notification Security:** Both the server (validating webhook URLs to prevent SSRF) and the client (verifying incoming notifications) have critical security responsibilities.
|
||||
- **Input Validation:** Servers MUST rigorously validate all RPC parameters and message content.
|
||||
|
||||
## 5. Implementations & Samples
|
||||
|
||||
### 5.1. SDKs
|
||||
- **Python:** `a2a-sdk` on PyPI.
|
||||
- **JavaScript/TypeScript:** `@a2a-js/sdk` on npm.
|
||||
- **Java:** `a2a-java` on Maven.
|
||||
- **C#/.NET:** `A2A` on NuGet.
|
||||
|
||||
### 5.2. Python Samples
|
||||
- **Location:** `a2a-samples/samples/python/`
|
||||
- **Agents:**
|
||||
- **LangGraph:** Currency conversion agent demonstrating tool use, multi-turn conversation (`input-required`), and streaming via `message/stream`.
|
||||
- **CrewAI:** Image generation agent demonstrating file artifact handling.
|
||||
- **Google ADK:** Expense report agent demonstrating structured data/forms.
|
||||
- **Hosts:**
|
||||
- **CLI:** Command-line client for interacting with any A2A agent.
|
||||
- **Multi-Agent Orchestrator:** An ADK-based agent that delegates tasks to other A2A agents.
|
||||
|
||||
### 5.3. JavaScript/TypeScript Samples
|
||||
- **Location:** `a2a-samples/samples/js/`
|
||||
- **Framework:** Genkit
|
||||
- **Agents:**
|
||||
- **Movie Agent:** Uses an external API to answer questions.
|
||||
- **Coder Agent:** Generates code and demonstrates file artifact creation.
|
||||
|
||||
### 5.4. Demo Application
|
||||
- **Location:** `a2a-samples/demo/`
|
||||
- A web application built with Mesop that visualizes multi-agent conversations orchestrated by a host agent, rendering text, images, and forms.
|
||||
|
||||
## 6. Development & Setup
|
||||
|
||||
- **Prerequisites:** Python (>=3.10), Node.js (>=18).
|
||||
- **API Keys:** LLM access requires API keys (e.g., `GOOGLE_API_KEY`), typically set via `.env` files.
|
||||
- **Running Samples:** Involves starting an agent server and then running a host/client application to interact with it.
|
||||
|
||||
## 7. Contribution
|
||||
|
||||
- See `CONTRIBUTING.md` for guidelines.
|
||||
- Join discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
|
||||
- Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
|
||||
- Provide private feedback via this [Google Form](https://goo.gle/a2a-feedback).
|
||||
## 5. Implementation Status
|
||||
- **Official SDKs:** Python (`a2a-sdk`), JS/TS (`@a2a-js/sdk`), Java, Go, C#/.NET.
|
||||
- **Integrations:** LangGraph, CrewAI, Google ADK, Genkit, AG2, BeeAI, PydanticAI, and more.
|
||||
|
||||
@ -11,11 +11,13 @@ collaborate effectively with each other and with users.
|
||||
- [Activeloop](https://www.activeloop.ai/)
|
||||
- [Adobe](https://www.adobe.com)
|
||||
- [AG2AI](https://ag2.ai)
|
||||
- [AgentTrust](https://agenttrust.ai/)
|
||||
- [AI21 Labs](https://www.ai21.com/)
|
||||
- [AI71](https://ai71.ai/)
|
||||
- [Aisera](https://aisera.com/)
|
||||
- [Almawave.it](https://www.almawave.com/it/)
|
||||
- [AliCloud](http://www.alibabacloud.com)
|
||||
- [Almawave.it](https://www.almawave.com/it/)
|
||||
- [AmikoNet](https://amikonet.ai)
|
||||
- [ArcBlock](http://www.arcblock.io)
|
||||
- [Arize](https://arize.com/blog/arize-ai-and-future-of-agent-interoperability-embracing-googles-a2a-protocol/)
|
||||
- [Articul8](https://www.articul8.ai/blog/unleashing-the-next-frontier-of-enterprise-ai-introducing-model-mesh-dock-and-inter-lock-and-our-a2-a-partnership-with-google)
|
||||
@ -80,6 +82,7 @@ collaborate effectively with each other and with users.
|
||||
- [InfoSys](https://www.infosys.com)
|
||||
- [Intuit](https://www.intuit.com)
|
||||
- [Iron Mountain](https://www.ironmountain.com/)
|
||||
- [JamJet](https://github.com/jamjet-labs/jamjet)
|
||||
- [JetBrains](https://www.jetbrains.com)
|
||||
- [JFrog](https://jfrog.com)
|
||||
- [Kakao](https://www.kakaocorp.com)
|
||||
@ -95,6 +98,7 @@ collaborate effectively with each other and with users.
|
||||
- [Lumeris](https://www.lumeris.com/)
|
||||
- [Lyzr.ai](https://lyzr.ai)
|
||||
- [Magyar Telekom](https://www.telekom.hu/)
|
||||
- [MasOrange](https://masorange.es/en/)
|
||||
- [Microsoft](https://www.microsoft.com/en-us/microsoft-cloud/blog/2025/05/07/empowering-multi-agent-apps-with-the-open-agent2agent-a2a-protocol/)
|
||||
- [MindsDB](https://mindsdb.com/blog/mindsdb-now-supports-the-agent2agent-(a2a)-protocol)
|
||||
- [McKinsey](https://www.mckinsey.com)
|
||||
@ -105,6 +109,7 @@ collaborate effectively with each other and with users.
|
||||
- [Nisum](http://www.nisum.com)
|
||||
- [Noorle Inc](http://www.noorle.com)
|
||||
- [NTT DATA](https://www.nttdata.com)
|
||||
- [OIXA Protocol](https://oixa.io)
|
||||
- [Optimizely Inc](https://www.optimizely.com/)
|
||||
- [Oracle / NetSuite](https://www.oracle.com/netsuite)
|
||||
- [Palo Alto Networks](https://www.paloaltonetworks.com/)
|
||||
@ -113,6 +118,7 @@ collaborate effectively with each other and with users.
|
||||
- [Pendo](https://www.pendo.io)
|
||||
- [PerfAI.ai](https://perfai.ai)
|
||||
- [Personal AI](https://personal.ai)
|
||||
- [Pinchwork](https://pinchwork.dev)
|
||||
- [Poppulo](https://www.poppulo.com/blog/poppulo-google-a2a-the-future-of-workplace-communication)
|
||||
- [Productive Edge](https://www.productiveedge.com/)
|
||||
- [Proofs](https://proofs.io)
|
||||
@ -134,6 +140,7 @@ collaborate effectively with each other and with users.
|
||||
- [Solace](https://solace.com/products/agent-mesh/)
|
||||
- [Solo.io](https://www.solo.io/)
|
||||
- [Stacklok, Inc](https://stacklok.com)
|
||||
- [Strale](https://strale.dev)
|
||||
- [Supertab](https://www.supertab.co/post/supertab-connect-partners-with-google-cloud-to-enable-ai-agents)
|
||||
- [Suzega](https://suzega.com/)
|
||||
- [TCS](https://www.tcs.com)
|
||||
@ -157,6 +164,7 @@ collaborate effectively with each other and with users.
|
||||
- [Weights & Biases](https://wandb.ai/wandb_fc/product-announcements-fc/reports/Powering-Agent-Collaboration-Weights-Biases-Partners-with-Google-Cloud-on-Agent2Agent-Interoperability-Protocol---VmlldzoxMjE3NDg3OA)
|
||||
- [Wipro](https://www.wipro.com)
|
||||
- [Workday](https://www.workday.com)
|
||||
- [WritBase](https://github.com/Writbase/writbase)
|
||||
- [Writer](https://writer.com)
|
||||
- [Zenity](https://zenity.io)
|
||||
- [Zeotap](https://www.zeotap.com)
|
||||
|
||||
@ -1,15 +1,13 @@
|
||||
# A2A protocol roadmap
|
||||
|
||||
**Last updated:** Jul 16, 2025
|
||||
**Last updated:** March 10, 2026
|
||||
|
||||
## Near-term initiatives
|
||||
|
||||
- Release `0.3` version of the protocol which we intend to keep supported and without breaking changes for a significant amount of time with backward compatibility of the SDKs starting at version `0.3`. As part of this release there are a few known breaking changes including:
|
||||
- Update the `/.well-known/agent.json` path for hosting Agent Cards to `/.well-known/agent-card.json` based on feedback from IANA.
|
||||
- Refactor class fields to be more Pythonic and adopt `snake_case`. [PR 199](https://github.com/a2aproject/a2a-python/pull/199)
|
||||
- Solidify the support for [A2A extensions](topics/extensions.md) with SDK support (starting with the Python SDK) and publishing sample extensions.
|
||||
- Introduce support for signed Agent Cards [Discussion 199](https://github.com/a2aproject/A2A/discussions/199#discussioncomment-13770576) to allow verifying the integrity of Agent Card content.
|
||||
- Enhance the client side support in SDK (starting with Python) to expose ready-to-use A2A clients, streamlined auth handling and improved handling of tasks.
|
||||
- Release `1.0` version of the protocol which represents significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
|
||||
- [What's New in A2A Protocol v1.0](https://a2a-protocol.org/latest/whats-new-v1/) has further updates.
|
||||
- Continue to support additional [A2A extensions](topics/extensions.md) with SDK support.
|
||||
- Prioritize community-led development with standardized processes for contributing to the specification, SDKs and tooling.
|
||||
|
||||
To review recent protocol changes see [Release Notes](https://github.com/a2aproject/A2A/releases).
|
||||
|
||||
@ -17,15 +15,12 @@ To review recent protocol changes see [Release Notes](https://github.com/a2aproj
|
||||
|
||||
### Governance
|
||||
|
||||
The protocol has been [donated](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents) to the Linux Foundation. The TSC is working on implementing a governance structure that prioritizes community-led development with standardized processes for contributing to the specification, SDKs and tooling. As part of the effort there will be dedicated working groups created for specific areas of the protocol.
|
||||
The TSC looks to streamline opportunities for contribution through [A2A extensions](topics/extensions.md), [Samples](https://github.com/a2aproject/a2a-samples) and participation.
|
||||
|
||||
### Agent Registry
|
||||
|
||||
Agent Registry enables the discovery of agents and is a critical component of a multi-agent system. There is an active and ongoing discussion in the community around the latest [Discussion 741](https://github.com/a2aproject/A2A/discussions/741).
|
||||
|
||||
### Validation
|
||||
|
||||
As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation which the group will continue to enhance in the coming months. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).
|
||||
As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).
|
||||
|
||||
### SDKs
|
||||
|
||||
|
||||
@ -1,15 +1,14 @@
|
||||
# A2A SDK
|
||||
|
||||
A2A currently hosts SDKs in five languages (Python, Go, JS, Java, .NET).
|
||||
The following table lists the supported languages for official A2A SDKs and their repositories.
|
||||
|
||||
The following table lists the supported languages and their stability.
|
||||
|
||||
| Language | Support |
|
||||
| :--------- | :------- |
|
||||
| Python | [Stable](https://github.com/a2aproject/a2a-python) |
|
||||
| Go | [Stable](https://github.com/a2aproject/a2a-go) |
|
||||
| Java | [Stable](https://github.com/a2aproject/a2a-java) |
|
||||
| JavaScript | [Stable](https://github.com/a2aproject/a2a-js) |
|
||||
| C#/.NET | [Stable](https://github.com/a2aproject/a2a-dotnet) |
|
||||
| Language | Repository |
|
||||
|------------|----------------------------------------------------------|
|
||||
| Python | [`a2a-python`](https://github.com/a2aproject/a2a-python) |
|
||||
| Go | [`a2a-go`](https://github.com/a2aproject/a2a-go) |
|
||||
| Java | [`a2a-java`](https://github.com/a2aproject/a2a-java) |
|
||||
| JavaScript | [`a2a-js`](https://github.com/a2aproject/a2a-js) |
|
||||
| C#/.NET | [`a2a-dotnet`](https://github.com/a2aproject/a2a-dotnet) |
|
||||
| Rust | [`a2a-rs`](https://github.com/a2aproject/a2a-rs) |
|
||||
|
||||
The A2A project provides numerous samples across supported languages in the [a2a-samples repository](https://github.com/a2aproject/a2a-samples).
|
||||
|
||||
7
docs/sdk/python.md
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
redirect: python/api/index.html
|
||||
---
|
||||
|
||||
# Python SDK
|
||||
|
||||
Redirecting to [API reference](python/api/index.html)...
|
||||
@ -1,8 +1,8 @@
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'a2a-sdk'
|
||||
copyright = '2025, Google LLC'
|
||||
author = 'Google LLC'
|
||||
copyright = '2026, The Linux Foundation'
|
||||
author = 'The Linux Foundation'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
@ -16,6 +16,13 @@ extensions = [
|
||||
# Tell autosummary to generate stub files
|
||||
autosummary_generate = True
|
||||
|
||||
# Suppress warnings from external SDK package
|
||||
suppress_warnings = [
|
||||
'ref.python', # Suppress "more than one target found for cross-reference"
|
||||
'ref.ref', # Suppress "undefined label"
|
||||
'toc.not_included', # Suppress "document isn't included in any toctree"
|
||||
]
|
||||
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
@ -10,4 +10,4 @@ This page contains the SDK documentation for the ``a2a-sdk`` Python package.
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
a2a
|
||||
modules
|
||||
|
||||
@ -91,3 +91,10 @@ figure.hero figcaption {
|
||||
margin-bottom: 0;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
iframe.video-container {
|
||||
width: 100%;
|
||||
aspect-ratio: 16 / 9;
|
||||
height: auto;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
@ -81,7 +81,7 @@ Agent Cards include sensitive information, such as:
|
||||
|
||||
To mitigate risks, the following protection mechanisms should be considered:
|
||||
|
||||
- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#710-agentgetauthenticatedextendedcard) for sensitive information or for serving a more detailed version of the card.
|
||||
- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#3111-get-extended-agent-card) for sensitive information or for serving a more detailed version of the card.
|
||||
- **Secure Endpoints:** Implement access controls on the HTTP endpoint serving the Agent Card (e.g., `/.well-known/agent-card.json` or registry API). The methods include:
|
||||
- Mutual TLS (mTLS)
|
||||
- Network restrictions (e.g., IP ranges)
|
||||
@ -91,6 +91,22 @@ To mitigate risks, the following protection mechanisms should be considered:
|
||||
|
||||
Any Agent Card containing sensitive data must be protected with authentication and authorization mechanisms. The A2A specification strongly recommends the use of out-of-band dynamic credentials rather than embedding static secrets within the Agent Card.
|
||||
|
||||
## Caching Considerations
|
||||
|
||||
Agent Cards describe an agent's capabilities and typically change infrequently — for example, when skills are added or authentication requirements are updated. Applying standard HTTP caching practices to Agent Card endpoints reduces unnecessary network requests while ensuring clients eventually receive updated information.
|
||||
|
||||
### Server Guidance
|
||||
|
||||
Servers hosting Agent Card endpoints should include HTTP caching headers in their responses. The `Cache-Control` header with an appropriate `max-age` directive allows clients and intermediaries to cache the card for a specified duration. Including an `ETag` header — derived from the card's `version` field or a content hash — enables clients to make conditional requests and avoid re-downloading unchanged cards.
|
||||
|
||||
### Client Guidance
|
||||
|
||||
Clients fetching Agent Cards should honor standard HTTP caching semantics. When a cached card expires, clients should use conditional requests (for example, `If-None-Match` with the stored `ETag` or `If-Modified-Since`) rather than unconditionally re-fetching the full card. When the server does not provide caching headers, clients may apply a reasonable default cache duration.
|
||||
|
||||
For Extended Agent Cards, clients should also follow the session-scoped caching guidance described in the [specification](../specification.md#133-extended-agent-card-access-control).
|
||||
|
||||
For normative requirements, see [Section 8.6](../specification.md#86-caching) of the specification.
|
||||
|
||||
## Future Considerations
|
||||
|
||||
The A2A community explores standardizing registry interactions or advanced discovery protocols.
|
||||
|
||||
135
docs/topics/custom-protocol-bindings.md
Normal file
@ -0,0 +1,135 @@
|
||||
# Custom Protocol Bindings
|
||||
|
||||
The A2A protocol ships with three standard bindings (JSON-RPC, gRPC, and
|
||||
HTTP+JSON/REST) that cover the majority of deployment scenarios. Custom protocol
|
||||
bindings let implementers expose A2A operations over additional transport
|
||||
mechanisms not covered by the standard set.
|
||||
|
||||
Custom protocol bindings are a complementary but distinct concept to
|
||||
[Extensions](extensions.md). Extensions modify the *behavior* of protocol
|
||||
interactions by adding new data, methods, or state transitions on top of an
|
||||
existing transport. Custom protocol bindings change the *transport layer*
|
||||
itself—for example, exposing A2A over WebSockets for low-latency bidirectional
|
||||
communication, or over MQTT for IoT environments with constrained connectivity.
|
||||
|
||||
## Declaration in the Agent Card
|
||||
|
||||
Custom protocol bindings are declared in the Agent Card's `supportedInterfaces`
|
||||
list. Each entry identifies the transport by URI, the endpoint URL, and the A2A
|
||||
protocol version it implements. The `protocolBinding` field should be a URI that uniquely identifies the
|
||||
binding (see [Section 5.8 of the specification](../specification.md#58-custom-binding-identification)
|
||||
for the normative requirement and versioning guidance).
|
||||
|
||||
```json
|
||||
{
|
||||
"supportedInterfaces": [
|
||||
{
|
||||
"url": "wss://agent.example.com/a2a/websocket",
|
||||
"protocolBinding": "https://a2a-protocol.org/bindings/websocket",
|
||||
"protocolVersion": "1.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Agents that support multiple bindings list all of them. Clients parse
|
||||
`supportedInterfaces` in order and select the first transport they support, so
|
||||
entries should be listed in preference order.
|
||||
|
||||
## Requirements
|
||||
|
||||
Custom protocol bindings must comply with all requirements in the
|
||||
[Protocol Binding Requirements and Interoperability](../specification.md#5-protocol-binding-requirements-and-interoperability)
|
||||
section of the specification. In particular:
|
||||
|
||||
- **All core operations must be supported.** The binding must expose every
|
||||
operation defined in the abstract operations layer (send message, get task,
|
||||
cancel task, streaming, push notifications, etc.).
|
||||
- **The data model must be preserved.** All data structures must be
|
||||
functionally equivalent to the canonical Protocol Buffer definitions. JSON
|
||||
serializations must use camelCase field names, and timestamps must be
|
||||
ISO 8601 strings in UTC.
|
||||
- **Behavior must be consistent.** Semantically equivalent requests must
|
||||
produce semantically equivalent results regardless of which binding is used.
|
||||
|
||||
## Key Areas to Specify
|
||||
|
||||
A custom binding specification must address each of the following areas.
|
||||
|
||||
### Data Type Mappings
|
||||
|
||||
Document how each Protocol Buffer type is represented in the custom transport,
|
||||
including:
|
||||
|
||||
- Binary data encoding (e.g., base64 for text-based transports)
|
||||
- Enum representation (strings, integers, or named constants)
|
||||
- Timestamp format (ISO 8601 strings in UTC per the core convention)
|
||||
|
||||
### Service Parameters
|
||||
|
||||
Service parameters are key-value pairs used to carry horizontally applicable
|
||||
context such as tracing identifiers or authentication hints. The binding
|
||||
specification must state:
|
||||
|
||||
- The mechanism used to carry service parameters (e.g., custom message headers,
|
||||
a top-level metadata field)
|
||||
- Any character encoding or size constraints on keys and values
|
||||
- Any names reserved by the binding itself
|
||||
|
||||
For transports that lack native header support, a common pattern is to embed
|
||||
service parameters as a JSON object in a dedicated metadata field, for example
|
||||
`a2a-service-parameters`.
|
||||
|
||||
### Error Mapping
|
||||
|
||||
The binding must map all A2A error types to transport-native error
|
||||
representations while preserving their semantic meaning. Provide a mapping
|
||||
table equivalent to the one in the specification's
|
||||
[Error Code Mappings](../specification.md#54-error-code-mappings) section, showing
|
||||
how each A2A error type (e.g., `TaskNotFoundError`, `UnsupportedOperationError`) is expressed in the custom binding's native error format.
|
||||
|
||||
### Streaming
|
||||
|
||||
If the transport supports streaming, document:
|
||||
|
||||
- The stream mechanism (e.g., WebSocket frames, chunked encoding, long polling)
|
||||
- Ordering guarantees (events must be delivered in the order they were
|
||||
generated)
|
||||
- Reconnection behavior when a connection is interrupted
|
||||
- How stream completion or termination is signaled to the client
|
||||
|
||||
If the transport does not support streaming, state this limitation clearly in
|
||||
the Agent Card so clients can fall back to polling.
|
||||
|
||||
### Authentication and Authorization
|
||||
|
||||
Document how authentication credentials declared in the Agent Card are
|
||||
transmitted using the custom transport. Define how authentication challenges are
|
||||
communicated to clients and ensure the custom binding does not inadvertently
|
||||
bypass the agent's primary security controls.
|
||||
|
||||
## Interoperability Testing
|
||||
|
||||
Before publishing a custom binding, verify that:
|
||||
|
||||
- All operations behave identically to the standard bindings for the same
|
||||
logical requests
|
||||
- Error conditions, large payloads, and long-running tasks are handled correctly
|
||||
- Any intentional deviations from standard binding behavior are clearly
|
||||
documented
|
||||
- Sample requests and responses are included in the specification to help
|
||||
implementers
|
||||
|
||||
## Governance
|
||||
|
||||
The A2A organization uses a formal governance framework for how custom protocol
|
||||
bindings are proposed, developed, promoted, and maintained. Official bindings
|
||||
use the `https://a2a-protocol.org/bindings/` URI prefix and are hosted under
|
||||
the `a2aproject` organization with the `cpb-` repository prefix (experimental
|
||||
bindings use `experimental-cpb-`). A2A SDKs SHOULD implement official custom
|
||||
protocol bindings.
|
||||
|
||||
For the full governance process—including tiers, lifecycle, SDK support, and
|
||||
legal requirements—see the
|
||||
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
|
||||
page.
|
||||
189
docs/topics/extension-and-binding-governance.md
Normal file
@ -0,0 +1,189 @@
|
||||
# Extension and Protocol Binding Governance
|
||||
|
||||
The A2A organization uses a unified governance framework for both
|
||||
[Extensions](extensions.md) and [Custom Protocol Bindings](custom-protocol-bindings.md).
|
||||
This document defines the formal process for proposing, developing, promoting,
|
||||
and maintaining these artifacts within the A2A organization.
|
||||
|
||||
Anyone may develop and publish extensions or custom protocol bindings
|
||||
independently. The tiers and lifecycle described here apply specifically to
|
||||
those hosted under the `a2aproject` GitHub organization.
|
||||
|
||||
## Tiers
|
||||
|
||||
Both extensions and custom protocol bindings use a two-tier system within the
|
||||
`a2aproject` organization. Repository naming and URI prefixes differ by type:
|
||||
|
||||
| | Extensions | Custom Protocol Bindings |
|
||||
| :----------------------- | :---------------------------------------------- | :--------------------------------------------- |
|
||||
| Official repo prefix | `ext-{name}` | `cpb-{name}` |
|
||||
| Experimental repo prefix | `experimental-ext-{name}` | `experimental-cpb-{name}` |
|
||||
| Official URI prefix | `https://a2a-protocol.org/extensions/` | `https://a2a-protocol.org/bindings/` |
|
||||
|
||||
### Official
|
||||
|
||||
Official artifacts are developed and maintained under the `a2aproject` GitHub
|
||||
organization, officially recommended by the TSC. Each repository has designated
|
||||
maintainers identified in `MAINTAINERS.md`.
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- Specifications MUST use the same language as the core specification
|
||||
([RFC 2119](https://tools.ietf.org/html/rfc2119))
|
||||
- MUST be licensed under Apache 2.0
|
||||
- MUST have at least one reference implementation
|
||||
- SHOULD have associated documentation on the A2A website
|
||||
|
||||
### Experimental
|
||||
|
||||
Experimental artifacts provide an incubation pathway for community contributors
|
||||
to prototype and collaborate on ideas before graduation to official status.
|
||||
|
||||
**Creation Requirements:**
|
||||
|
||||
- An experimental repository can ONLY be created with sponsorship from an A2A
|
||||
Maintainer
|
||||
- The sponsoring Maintainer is responsible for initial oversight of the
|
||||
experimental artifact
|
||||
- Experimental repositories MUST clearly indicate their experimental/non-official
|
||||
status in the README
|
||||
- Any published packages MUST use naming that clearly indicates experimental
|
||||
status
|
||||
- The TSC retains oversight, including the ability to archive or remove
|
||||
experimental repositories
|
||||
|
||||
## Lifecycle
|
||||
|
||||
Extensions and custom protocol bindings progress through the following phases.
|
||||
|
||||
### Proposal Phase
|
||||
|
||||
Any community member may propose an extension or custom protocol binding:
|
||||
|
||||
1. **Open an Issue**: Create an issue in the main `a2aproject/A2A` repository
|
||||
describing:
|
||||
- An abstract describing the extension's purpose or the binding's transport
|
||||
and use case
|
||||
- Motivation explaining why this cannot be achieved with the core protocol
|
||||
or existing standard bindings
|
||||
- An initial technical approach or specification draft
|
||||
2. **Community Discussion**: The proposal is open for community feedback and
|
||||
refinement
|
||||
|
||||
### Maintainer Sponsorship
|
||||
|
||||
For a proposal to proceed to experimental status:
|
||||
|
||||
1. **Secure a Sponsor**: An A2A Maintainer must agree to sponsor the proposal
|
||||
2. **Repository Creation**: The sponsoring Maintainer creates the
|
||||
`experimental-ext-*` or `experimental-cpb-*` repository under `a2aproject`
|
||||
3. **Oversight**: The sponsoring Maintainer provides initial oversight and
|
||||
ensures alignment with A2A design principles
|
||||
|
||||
### Experimental Development
|
||||
|
||||
While in experimental status:
|
||||
|
||||
- Contributors iterate on the specification and reference implementations
|
||||
- The experimental artifact MAY be used by early adopters with the
|
||||
understanding that breaking changes are expected
|
||||
- Community feedback is gathered and incorporated
|
||||
- The experimental repository MUST clearly indicate its non-official status
|
||||
|
||||
### Graduation to Official Status
|
||||
|
||||
To graduate an experimental extension or binding to official status:
|
||||
|
||||
1. **Maturity Requirements**:
|
||||
- At least one production-quality reference implementation
|
||||
- Documentation meeting A2A standards
|
||||
- Evidence of community adoption or interest
|
||||
- Clear maintainer commitment for ongoing maintenance
|
||||
2. **Graduation Proposal**: Open an issue in `a2aproject/A2A` with:
|
||||
- Reference to the experimental repository and its implementations
|
||||
- Summary of community feedback and adoption
|
||||
- Proposed maintainers for the official artifact
|
||||
3. **TSC Vote**:
|
||||
- The proposal is added to the TSC meeting agenda
|
||||
- **Quorum Requirement**: At least 50% of TSC voting members must be
|
||||
present
|
||||
- **Approval**: Requires majority vote of those in attendance (per A2A
|
||||
governance)
|
||||
- The TSC may request revisions before a final vote
|
||||
4. **Acceptance**:
|
||||
- (Extensions) The repository is renamed from `experimental-ext-*` to
|
||||
`ext-*`; documentation is added to the A2A website's extensions page
|
||||
- (Custom Protocol Bindings) The repository is renamed from
|
||||
`experimental-cpb-*` to `cpb-*`; documentation is added to the A2A
|
||||
website's custom protocol bindings page
|
||||
|
||||
### Official Iteration
|
||||
|
||||
Once official, extensions and bindings may be iterated on:
|
||||
|
||||
- Repository maintainers are responsible for day-to-day governance
|
||||
- Changes SHOULD be coordinated via the relevant working group if one exists
|
||||
- Breaking changes require a new identifier
|
||||
- Breaking changes require TSC review
|
||||
- Maintainers SHOULD coordinate with SDK maintainers for implementation updates
|
||||
|
||||
### Promotion to Core Protocol
|
||||
|
||||
Some extensions may eventually transition to core protocol features, and some
|
||||
custom protocol bindings may transition to core bindings. This is governed
|
||||
through the existing A2A specification enhancement process:
|
||||
|
||||
- A proposal is submitted following the standard specification change process
|
||||
- The proposal references the official extension or binding and its adoption
|
||||
- TSC vote with standard quorum and majority requirements applies
|
||||
- Not all extensions or bindings are suitable for core inclusion; many will
|
||||
remain as extensions or custom bindings indefinitely
|
||||
|
||||
## SDK Support
|
||||
|
||||
SDK support requirements differ between extensions and official custom protocol
|
||||
bindings, reflecting their different roles in the protocol ecosystem.
|
||||
|
||||
**Extensions**: A2A SDKs MAY implement extensions. Where implemented:
|
||||
|
||||
- Extensions MUST be disabled by default and require explicit opt-in
|
||||
- SDK documentation SHOULD list supported extensions
|
||||
- SDK maintainers have full autonomy over extension support decisions
|
||||
- Extension support is not required for protocol conformance
|
||||
|
||||
**Official Custom Protocol Bindings**: A2A SDKs SHOULD implement official
|
||||
custom protocol bindings. Where implemented:
|
||||
|
||||
- Custom protocol bindings MUST be disabled by default and require explicit
|
||||
opt-in
|
||||
- SDK documentation SHOULD list supported custom protocol bindings
|
||||
- SDK maintainers have full autonomy over binding support decisions
|
||||
- Custom protocol binding support is not required for protocol conformance
|
||||
|
||||
## Legal Requirements
|
||||
|
||||
### Licensing
|
||||
|
||||
Official extensions and custom protocol bindings MUST be available under the
|
||||
Apache 2.0 license, consistent with the core A2A project.
|
||||
|
||||
### Contributor License Grant
|
||||
|
||||
By submitting a contribution to an official A2A extension or custom protocol
|
||||
binding repository, contributors represent that:
|
||||
|
||||
1. They have the legal authority to grant the rights
|
||||
2. The contribution is original work or they have sufficient rights to submit it
|
||||
3. They grant to the Linux Foundation and recipients a perpetual, worldwide,
|
||||
non-exclusive, royalty-free license to use, reproduce, modify, and
|
||||
distribute the contribution
|
||||
|
||||
### Antitrust
|
||||
|
||||
Extension and custom protocol binding developers acknowledge that:
|
||||
|
||||
- They may compete with other participants
|
||||
- They have no obligation to implement any extension or binding
|
||||
- They are free to develop competing extensions or bindings
|
||||
- Status as an official extension or binding does not create an exclusive
|
||||
relationship
|
||||
@ -8,7 +8,7 @@ base protocol.
|
||||
|
||||
Extensions allow for extending the A2A protocol with new data, requirements,
|
||||
RPC methods, and state machines. Agents declare their support for specific
|
||||
extensions in their Agent Card, and clients can then opt-in to the behavior
|
||||
extensions in their Agent Card, and clients can then opt in to the behavior
|
||||
offered by an extension as part of requests they make to the agent. Extensions
|
||||
are identified by a URI and defined by their own specification. Anyone is able to define, publish, and implement an extension.
|
||||
|
||||
@ -30,7 +30,7 @@ However, some foreseeable applications include:
|
||||
values (for example, requiring all messages to use `DataParts` adhering to
|
||||
a specific schema). This can also include augmenting existing states in the
|
||||
task state machine by using metadata. For example, an extension could define
|
||||
a 'generating-image' sub-state when `TaskStatus.state` is 'working' and
|
||||
a 'generating-image' substate when `TaskStatus.state` is 'working' and
|
||||
`TaskStatus.message.metadata["generating-image"]` is true.
|
||||
- **Method Extensions (Extended Skills)**: Adding entirely new RPC methods
|
||||
beyond the core set defined by the protocol. An Extended Skill refers to a
|
||||
@ -51,13 +51,26 @@ However, some foreseeable applications include:
|
||||
| [Traceability Extension](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/extensions/traceability) | Explore the Python implementation and basic usage of the Traceability Extension (v1). |
|
||||
| [Agent Gateway Protocol (AGP) Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/agp) | A Core Protocol Layer or Routing Extension that introduces Autonomous Squads (ASq) and routes Intent payloads based on declared Capabilities, enhancing scalability (v1). |
|
||||
|
||||
## Extension Governance
|
||||
|
||||
The A2A organization uses a formal governance framework for how extensions are
|
||||
proposed, developed, promoted, and maintained. Official extensions use the
|
||||
`https://a2a-protocol.org/extensions/` URI prefix and are hosted under the
|
||||
`a2aproject` organization with the `ext-` repository prefix (experimental
|
||||
extensions use `experimental-ext-`).
|
||||
|
||||
For the full governance process—including tiers, lifecycle, SDK support, and
|
||||
legal requirements—see the
|
||||
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
|
||||
page.
|
||||
|
||||
## Limitations
|
||||
|
||||
There are some changes to the protocol that extensions don't allow, primarily
|
||||
to prevent breaking core type validations:
|
||||
|
||||
- **Changing the Definition of Core Data Structures**: For example, adding new
|
||||
fields or removing required fields to protocol-defined data structures).
|
||||
fields or removing required fields to protocol-defined data structures.
|
||||
Extensions should place custom attributes in the `metadata` map present on
|
||||
core data structures.
|
||||
- **Adding New Values to Enum Types**: Extensions should use existing enum values
|
||||
@ -68,9 +81,7 @@ to prevent breaking core type validations:
|
||||
Agents declare their support for extensions in their Agent Card by including
|
||||
`AgentExtension` objects within their `AgentCapabilities` object.
|
||||
|
||||
```ts { .no-copy }
|
||||
--8<-- "types/src/types.ts:AgentExtension"
|
||||
```
|
||||
{{ proto_to_table("AgentExtension") }}
|
||||
|
||||
The following is an example of an Agent Card with an extension:
|
||||
|
||||
@ -123,7 +134,7 @@ the agent should reject the incoming request with an appropriate error.
|
||||
|
||||
The detailed behavior and structure of an extension are defined by its
|
||||
**specification**. While the exact format is not mandated, it should contain at
|
||||
at least:
|
||||
least:
|
||||
|
||||
- The specific URI(s) that identify the extension.
|
||||
- The schema and meaning of objects specified in the `params` field of the
|
||||
@ -149,13 +160,13 @@ experience for extension-unaware clients. Clients and agents perform
|
||||
negotiation to determine which extensions are active for a specific request.
|
||||
|
||||
1. **Client Request**: A client requests extension activation by including the
|
||||
`X-A2A-Extensions` header in the HTTP request to the agent. The value is a
|
||||
`A2A-Extensions` header in the HTTP request to the agent. The value is a
|
||||
comma-separated list of extension URIs the client intends to activate.
|
||||
2. **Agent Processing**: Agents are responsible for identifying supported
|
||||
extensions in the request and performing the activation. Any requested
|
||||
extensions not supported by the agent can be ignored.
|
||||
3. **Response**: Once the agent has identified all activated extensions, the
|
||||
response SHOULD include the `X-A2A-Extensions` header, listing all
|
||||
response SHOULD include the `A2A-Extensions` header, listing all
|
||||
extensions that were successfully activated for that request.
|
||||
|
||||
{ width="70%" style="margin:20px auto;display:block;" }
|
||||
@ -166,18 +177,17 @@ negotiation to determine which extensions are active for a specific request.
|
||||
POST /agents/eightball HTTP/1.1
|
||||
Host: example.com
|
||||
Content-Type: application/json
|
||||
X-A2A-Extensions: https://example.com/ext/konami-code/v1
|
||||
A2A-Extensions: https://example.com/ext/konami-code/v1
|
||||
Content-Length: 519
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "message/send",
|
||||
"method": "SendMessage",
|
||||
"id": "1",
|
||||
"params": {
|
||||
"message": {
|
||||
"kind": "message",
|
||||
"messageId": "1",
|
||||
"role": "user",
|
||||
"parts": [{"kind": "text", "text": "Oh magic 8-ball, will it rain today?"}]
|
||||
"role": "ROLE_USER",
|
||||
"parts": [{"text": "Oh magic 8-ball, will it rain today?"}]
|
||||
},
|
||||
"metadata": {
|
||||
"https://example.com/ext/konami-code/v1/code": "motherlode"
|
||||
@ -191,16 +201,17 @@ Content-Length: 519
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
X-A2A-Extensions: https://example.com/ext/konami-code/v1
|
||||
A2A-Extensions: https://example.com/ext/konami-code/v1
|
||||
Content-Length: 338
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "1",
|
||||
"result": {
|
||||
"kind": "message",
|
||||
"messageId": "2",
|
||||
"role": "agent",
|
||||
"parts": [{"kind": "text", "text": "That's a bingo!"}]
|
||||
"message": {
|
||||
"messageId": "2",
|
||||
"role": "ROLE_AGENT",
|
||||
"parts": [{"text": "That's a bingo!"}]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -228,9 +239,10 @@ versioning, and distributing extension implementations.
|
||||
- **Permanent Identifiers**: Authors are encouraged to use a permanent
|
||||
identifier service, such as `w3id.org`, for their extension URIs to
|
||||
prevent broken links.
|
||||
- **Community Registry (Future)**: The A2A community might establish a
|
||||
central registry for discovering and browsing available extensions in
|
||||
the future.
|
||||
- **Community Registry**: The A2A [Extension Governance](#extension-governance)
|
||||
framework defines a tiered system for official and experimental
|
||||
extensions hosted under the `a2aproject` organization, including a
|
||||
lifecycle for proposing and promoting extensions.
|
||||
- **Packaging and Reusability (A2A SDKs and Libraries)**:
|
||||
To promote adoption, extension logic should be packaged into reusable
|
||||
libraries that can be integrated into existing A2A client and
|
||||
|
||||
@ -28,7 +28,7 @@ The following table describes the fundamental communication elements in A2A:
|
||||
| Agent Card | A JSON metadata document describing an agent's identity, capabilities, endpoint, skills, and authentication requirements. | Enables clients to discover agents and understand how to interact with them securely and effectively. |
|
||||
| Task | A stateful unit of work initiated by an agent, with a unique ID and defined lifecycle. | Facilitates tracking of long-running operations and enables multi-turn interactions and collaboration. |
|
||||
| Message | A single turn of communication between a client and an agent, containing content and a role ("user" or "agent"). | Conveys instructions, context, questions, answers, or status updates that are not necessarily formal artifacts. |
|
||||
| Part | The fundamental content container (for example, TextPart, FilePart, DataPart) used within Messages and Artifacts. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
|
||||
| Part | The fundamental content container used within Messages and Artifacts. A Part holds one of: text content, a file reference (URL or inline bytes), or structured data. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
|
||||
| Artifact | A tangible output generated by an agent during a task (for example, a document, image, or structured data). | Delivers the concrete results of an agent's work, ensuring structured and retrievable outputs. |
|
||||
|
||||
## Interaction Mechanisms
|
||||
@ -67,13 +67,18 @@ agent. It includes a role ("user" or "agent") and a unique `messageId`. It
|
||||
contains one or more Part objects, which are granular containers for the actual
|
||||
content. This design allows A2A to be modality independent.
|
||||
|
||||
The primary part kinds are:
|
||||
The `Part` object is a flexible container that can hold different types of content using a `oneof` field structure. A Part must contain exactly one of the following content fields:
|
||||
|
||||
- `TextPart`: Contains plain textual content.
|
||||
- `FilePart`: Represents a file. It can be transmitted either inline (Base64
|
||||
encoded) or through a URI. It includes metadata like "name" and "mimeType".
|
||||
- `DataPart`: Carries structured JSON data. This is useful for forms,
|
||||
parameters, or any machine-readable information.
|
||||
- `text`: A string containing plain textual content.
|
||||
- `raw`: A byte array containing binary file data (inline).
|
||||
- `url`: A string URI referencing external file content.
|
||||
- `data`: A structured JSON value (e.g., object, array) for machine-readable data.
|
||||
|
||||
Additionally, every `Part` can include:
|
||||
|
||||
- `mediaType`: The MIME type of the content (e.g., `"text/plain"`, `"image/png"`, `"application/json"`).
|
||||
- `filename`: An optional name for the file or content.
|
||||
- `metadata`: A key-value map for additional context.
|
||||
|
||||
## Artifacts
|
||||
|
||||
|
||||
@ -141,16 +141,15 @@ The following example illustrates a typical task flow with a follow-up:
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "message.send",
|
||||
"method": "SendMessage",
|
||||
"params": {
|
||||
"message": {
|
||||
"role": "user",
|
||||
"parts": [
|
||||
{
|
||||
"kind": "text",
|
||||
"text": "Generate an image of a sailboat on the ocean."
|
||||
}
|
||||
]
|
||||
],
|
||||
"messageId": "msg-user-001"
|
||||
}
|
||||
}
|
||||
@ -164,29 +163,27 @@ The following example illustrates a typical task flow with a follow-up:
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"result": {
|
||||
"id": "task-boat-gen-123",
|
||||
"contextId": "ctx-conversation-abc",
|
||||
"status": {
|
||||
"state": "completed"
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"artifactId": "artifact-boat-v1-xyz",
|
||||
"name": "sailboat_image.png",
|
||||
"description": "A generated image of a sailboat on the ocean.",
|
||||
"parts": [
|
||||
{
|
||||
"kind": "file",
|
||||
"file": {
|
||||
"name": "sailboat_image.png",
|
||||
"mimeType": "image/png",
|
||||
"bytes": "base64_encoded_png_data_of_a_sailboat"
|
||||
"task": {
|
||||
"id": "task-boat-gen-123",
|
||||
"contextId": "ctx-conversation-abc",
|
||||
"status": {
|
||||
"state": "TASK_STATE_COMPLETED"
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"artifactId": "artifact-boat-v1-xyz",
|
||||
"name": "sailboat_image.png",
|
||||
"description": "A generated image of a sailboat on the ocean.",
|
||||
"parts": [
|
||||
{
|
||||
"filename": "sailboat_image.png",
|
||||
"mediaType": "image/png",
|
||||
"raw": "base64_encoded_png_data_of_a_sailboat"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"kind": "task"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -198,7 +195,7 @@ The following example illustrates a typical task flow with a follow-up:
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-002",
|
||||
"method": "message.send",
|
||||
"method": "SendMessage",
|
||||
"params": {
|
||||
"message": {
|
||||
"role": "user",
|
||||
@ -209,7 +206,6 @@ The following example illustrates a typical task flow with a follow-up:
|
||||
],
|
||||
"parts": [
|
||||
{
|
||||
"kind": "text",
|
||||
"text": "Please modify the sailboat to be red."
|
||||
}
|
||||
]
|
||||
@ -218,7 +214,7 @@ The following example illustrates a typical task flow with a follow-up:
|
||||
}
|
||||
```
|
||||
|
||||
4. Agent responds with a new image artifact (new task, same context, updated
|
||||
4. Agent responds with a new image artifact (new task, same context, same
|
||||
artifact name): The agent creates a new task within the same `contextId`. The
|
||||
new boat image artifact retains the same name but has a new `artifactId`.
|
||||
|
||||
@ -227,29 +223,27 @@ The following example illustrates a typical task flow with a follow-up:
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-002",
|
||||
"result": {
|
||||
"id": "task-boat-color-456",
|
||||
"contextId": "ctx-conversation-abc",
|
||||
"status": {
|
||||
"state": "completed"
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"artifactId": "artifact-boat-v2-red-pqr",
|
||||
"name": "sailboat_image.png",
|
||||
"description": "A generated image of a red sailboat on the ocean.",
|
||||
"parts": [
|
||||
{
|
||||
"kind": "file",
|
||||
"file": {
|
||||
"name": "sailboat_image.png",
|
||||
"mimeType": "image/png",
|
||||
"bytes": "base64_encoded_png_data_of_a_RED_sailboat"
|
||||
"task": {
|
||||
"id": "task-boat-color-456",
|
||||
"contextId": "ctx-conversation-abc",
|
||||
"status": {
|
||||
"state": "TASK_STATE_COMPLETED"
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"artifactId": "artifact-boat-v2-red-pqr",
|
||||
"name": "sailboat_image.png",
|
||||
"description": "A generated image of a red sailboat on the ocean.",
|
||||
"parts": [
|
||||
{
|
||||
"filename": "sailboat_image.png",
|
||||
"mediaType": "image/png",
|
||||
"raw": "base64_encoded_png_data_of_a_RED_sailboat"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"kind": "task"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@ -10,19 +10,19 @@ The following key features detail how SSE streaming is implemented and managed w
|
||||
|
||||
- **Server Capability:** The A2A Server must indicate its support for streaming by setting `capabilities.streaming: true` in its Agent Card.
|
||||
|
||||
- **Initiating a Stream:** The client uses the `message/stream` RPC method to send an initial message (for example, a prompt or command) and simultaneously subscribe to updates for that task.
|
||||
- **Initiating a Stream:** The client uses the `SendStreamingMessage` RPC method to send an initial message (for example, a prompt or command) and simultaneously subscribe to updates for that task.
|
||||
|
||||
- **Server Response and Connection:** If the subscription is successful, the server responds with an HTTP 200 OK status and a `Content-Type: text/event-stream`. This HTTP connection remains open for the server to push events to the client.
|
||||
|
||||
- **Event Structure and Types:** The server sends events over this stream. Each event's `data` field contains a JSON-RPC 2.0 Response object, typically a `SendStreamingMessageResponse`. The `result` field of the `SendStreamingMessageResponse` contains:
|
||||
|
||||
- [`Task`](../specification.md#61-task-object): Represents the current state of the work.
|
||||
- [`TaskStatusUpdateEvent`](../specification.md#722-taskstatusupdateevent-object): Communicates changes in the task's lifecycle state (for example, from `working` to `input-required` or `completed`). It also provides intermediate messages from the agent.
|
||||
- [`TaskArtifactUpdateEvent`](../specification.md#723-taskartifactupdateevent-object): Delivers new or updated Artifacts generated by the task. This is used to stream large files or data structures in chunks, with fields like `append` and `lastChunk` to help reassemble.
|
||||
- [`TaskStatusUpdateEvent`](../specification.md#taskstatusupdateevent): Communicates changes in the task's lifecycle state (for example, from `working` to `input-required` or `completed`). It also provides intermediate messages from the agent.
|
||||
- [`TaskArtifactUpdateEvent`](../specification.md#taskartifactupdateevent): Delivers new or updated Artifacts generated by the task. This is used to stream large files or data structures in chunks, with fields like `append` and `lastChunk` to help reassemble.
|
||||
|
||||
- **Stream Termination:** The server signals the end of updates for a cycle by setting `final: true` in a `TaskStatusUpdateEvent`. This typically occurs when the task reaches a terminal state. After this, the server usually closes the SSE connection.
|
||||
- **Stream Termination:** When a task reaches a terminal or interrupted state (e.g., `COMPLETED`, `FAILED`, `CANCELED`, `REJECTED`, or `INPUT_REQUIRED`), the server closes the stream and sends no further updates.
|
||||
|
||||
- **Resubscription:** If a client's SSE connection breaks prematurely while a task is still active, the client is able to attempt to reconnect to the stream using the `tasks/resubscribe` RPC method.
|
||||
- **Resubscription:** If a client's SSE connection breaks prematurely while a task is still active, the client is able to attempt to reconnect to the stream using the `SubscribeToTask` RPC method.
|
||||
|
||||
### When to Use Streaming
|
||||
|
||||
@ -37,8 +37,8 @@ Streaming with SSE is best suited for:
|
||||
|
||||
Refer to the Protocol Specification for detailed structures:
|
||||
|
||||
- [`message/stream`](../specification.md#72-messagestream)
|
||||
- [`tasks/resubscribe`](../specification.md#79-tasksresubscribe)
|
||||
- [`SendStreamingMessage`](../specification.md#72-messagestream)
|
||||
- [`SubscribeToTask`](../specification.md#79-taskssubscribe)
|
||||
|
||||
## Push Notifications for Disconnected Scenarios
|
||||
|
||||
@ -47,13 +47,13 @@ For very long-running tasks (for example, lasting minutes, hours, or even days)
|
||||
The following key features detail how push notifications are implemented and managed within the A2A protocol:
|
||||
|
||||
- **Server Capability:** The A2A Server must indicate its support for this feature by setting `capabilities.pushNotifications: true` in its Agent Card.
|
||||
- **Configuration:** The client provides a [`PushNotificationConfig`](../specification.md#68-pushnotificationconfig-object) to the server. This configuration is supplied:
|
||||
- Within the initial `message/send` or `message/stream` request, or
|
||||
- Separately, using the `tasks/pushNotificationConfig/set` RPC method for an existing task.
|
||||
- **Configuration:** The client provides a [`PushNotificationConfig`](../specification.md#pushnotificationconfig) to the server. This configuration is supplied:
|
||||
- Within the initial `SendMessage` or `SendStreamingMessage` request, or
|
||||
- Separately, using the `CreateTaskPushNotificationConfig` RPC method for an existing task.
|
||||
The `PushNotificationConfig` includes a `url` (the HTTPS webhook URL), an optional `token` (for client-side validation), and optional `authentication` details (for the A2A Server to authenticate to the webhook).
|
||||
- **Notification Trigger:** The A2A Server decides when to send a push notification, typically when a task reaches a significant state change (for example, terminal state, `input-required`, or `auth-required`).
|
||||
- **Notification Payload:** The A2A protocol does not strictly define the HTTP body payload, but it SHOULD contain sufficient information for the client to identify the Task ID and understand the general nature of the update (for example, the new `TaskState`).
|
||||
- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `tasks/get` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.
|
||||
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#323-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#pushnotificationpayload) for detailed structure.
|
||||
- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `GetTask` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.
|
||||
|
||||
### When to Use Push Notifications
|
||||
|
||||
@ -67,8 +67,8 @@ Push notifications are ideal for:
|
||||
|
||||
Refer to the Protocol Specification for detailed structures:
|
||||
|
||||
- [`tasks/pushNotificationConfig/set`](../specification.md#75-taskspushnotificationconfigset)
|
||||
- [`tasks/get`](../specification.md#76-taskspushnotificationconfigget)
|
||||
- [`CreateTaskPushNotificationConfig`](../specification.md#317-create-push-notification-config)
|
||||
- [`GetTask`](../specification.md#76-taskspushnotificationconfigget)
|
||||
|
||||
### Client-Side Push Notification Service
|
||||
|
||||
@ -82,7 +82,7 @@ Security is paramount for push notifications due to their asynchronous and serve
|
||||
|
||||
- **Webhook URL Validation:** Servers SHOULD NOT blindly trust and send POST requests to any URL provided by a client. Malicious clients could provide URLs pointing to internal services or unrelated third-party systems, leading to Server-Side Request Forgery (SSRF) attacks or acting as Distributed Denial of Service (DDoS) amplifiers.
|
||||
- **Mitigation strategies:** Allowlisting of trusted domains, ownership verification (for example, challenge-response mechanisms), and network controls (e.g., egress firewalls).
|
||||
- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme(s) specified in `PushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).
|
||||
- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme specified in `PushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).
|
||||
|
||||
#### Client Webhook Receiver Security (when receiving notifications from A2A server)
|
||||
|
||||
@ -95,7 +95,7 @@ Security is paramount for push notifications due to their asynchronous and serve
|
||||
|
||||
#### Example Asymmetric Key Flow (JWT + JWKS)
|
||||
|
||||
1. Client sets `PushNotificationConfig` specifying `authentication.schemes: ["Bearer"]` and possibly an expected `issuer` or `audience` for the JWT.
|
||||
1. Client creates a `PushNotificationConfig` specifying `authentication.scheme: "Bearer"` and possibly an expected `issuer` or `audience` for the JWT.
|
||||
2. A2A Server, when sending a notification:
|
||||
- Generates a JWT, signing it with its private key. The JWT includes claims like `iss` (issuer), `aud` (audience), `iat` (issued at), `exp` (expires), `jti` (JWT ID), and `taskId`.
|
||||
- The JWT header indicates the signing algorithm and key ID (`kid`).
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# 2. Setup Your Environment
|
||||
# 2. Set Up Your Environment
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@ -38,7 +38,7 @@ We recommend using a virtual environment for Python projects. The A2A Python SDK
|
||||
.venv\Scripts\activate
|
||||
```
|
||||
|
||||
2. **Install needed Python dependencies along with the A2A SDK and its dependencies:**
|
||||
2. **Install the A2A SDK and its required Python dependencies:**
|
||||
|
||||
```bash
|
||||
pip install -r samples/python/requirements.txt
|
||||
|
||||
@ -8,14 +8,15 @@ We'll use the `helloworld` example located in [`a2a-samples/samples/python/agent
|
||||
|
||||
An **Agent Skill** describes a specific capability or function the agent can perform. It's a building block that tells clients what kinds of tasks the agent is good for.
|
||||
|
||||
Key attributes of an `AgentSkill` (defined in `a2a.types`):
|
||||
Attributes of an `AgentSkill` (defined in `a2a.types`):
|
||||
|
||||
- `id`: A unique identifier for the skill.
|
||||
- `name`: A human-readable name.
|
||||
- `description`: A more detailed explanation of what the skill does.
|
||||
- `tags`: Keywords for categorization and discovery.
|
||||
- `examples`: Sample prompts or use cases.
|
||||
- `inputModes` / `outputModes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
|
||||
- `input_modes` / `output_modes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
|
||||
- `security_requirements`: Security schemes necessary for this skill.
|
||||
|
||||
In `__main__.py`, you can see how a skill for the Helloworld agent is defined:
|
||||
|
||||
@ -32,9 +33,9 @@ The **Agent Card** is a JSON document that an A2A Server makes available, typica
|
||||
Key attributes of an `AgentCard` (defined in `a2a.types`):
|
||||
|
||||
- `name`, `description`, `version`: Basic identity information.
|
||||
- `url`: The endpoint where the A2A service can be reached.
|
||||
- `capabilities`: Specifies supported A2A features like `streaming` or `pushNotifications`.
|
||||
- `defaultInputModes` / `defaultOutputModes`: Default Media Types for the agent.
|
||||
- `supported_interfaces`: Ordered list of endpoints and protocols where the A2A service can be reached.
|
||||
- `capabilities`: Supported A2A features like `streaming` or `extended_agent_card`.
|
||||
- `default_input_modes` / `default_output_modes`: Default Media Types for the agent.
|
||||
- `skills`: A list of `AgentSkill` objects that the agent offers.
|
||||
|
||||
The `helloworld` example defines its Agent Card like this:
|
||||
@ -43,6 +44,4 @@ The `helloworld` example defines its Agent Card like this:
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentCard"
|
||||
```
|
||||
|
||||
This card tells us the agent is named "Hello World Agent", runs at `http://localhost:9999/`, supports text interactions, and has the `hello_world` skill. It also indicates public authentication, meaning no specific credentials are required.
|
||||
|
||||
Understanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it.
|
||||
This card tells us the agent is named "Hello World Agent", can be run at `http://127.0.0.1:9999/`, supports text interactions, and has the `hello_world` skill.
|
||||
|
||||
@ -22,7 +22,7 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent"
|
||||
```
|
||||
|
||||
It has a simple `invoke` method that returns the string "Hello World".
|
||||
It has a simple `invoke` method that returns the string "Hello, World!".
|
||||
|
||||
2. **The Executor (`HelloWorldAgentExecutor`)**:
|
||||
This class implements the `AgentExecutor` interface.
|
||||
@ -41,17 +41,16 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute"
|
||||
```
|
||||
|
||||
When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor):
|
||||
When a `Send Message` or `Send Streaming Message` request comes in (both are handled by `execute` in this simplified executor), the following steps occur:
|
||||
|
||||
1. It calls `self.agent.invoke()` to get the "Hello World" string.
|
||||
2. It creates an A2A `Message` object using the `new_agent_text_message` utility function.
|
||||
3. It enqueues this message onto the `event_queue`. The underlying `DefaultRequestHandler` will then process this queue to send the response(s) to the client. For a single message like this, it will result in a single response for `message/send` or a single event for `message/stream` before the stream closes.
|
||||
**Step 1.** The `A2A instance` (server) retrieves the current task from the context. If there is no task in context, then it creates a new task and adds it to the `EventQueue`.
|
||||
|
||||
- **`cancel`**:
|
||||
The Helloworld example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent.
|
||||
**Step 2.** It enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_WORKING` to indicate the agent has begun processing.
|
||||
|
||||
```python { .no-copy }
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel"
|
||||
```
|
||||
**Step 3.** It calls `self.agent.invoke()` to execute the actual business logic (which simply returns "Hello, World!").
|
||||
|
||||
**Step 4.** It enqueues a `TaskArtifactUpdateEvent` containing the result text from the agent.
|
||||
|
||||
**Step 5.** Finally, it enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_COMPLETED` to conclude the task.
|
||||
|
||||
The `AgentExecutor` acts as the bridge between the A2A protocol (managed by the request handler and server application) and your agent's specific logic. It receives context about the request and uses an event queue to communicate results or updates back.
|
||||
|
||||
@ -2,7 +2,9 @@
|
||||
|
||||
Now that we have an Agent Card and an Agent Executor, we can set up and start the A2A server.
|
||||
|
||||
The A2A Python SDK provides an `A2AStarletteApplication` class that simplifies running an A2A-compliant HTTP server. It uses [Starlette](https://www.starlette.io/) for the web framework and is typically run with an ASGI server like [Uvicorn](https://www.uvicorn.org/).
|
||||
To set up an A2A server, the Python SDK provides a route factory and helper functions (`create_agent_card_routes`, `create_jsonrpc_routes`, `create_rest_routes`). Use the route factory to create routes for the A2A server's services. These routes can be attached natively to popular frameworks like [Starlette](https://www.starlette.io/) and [FastAPI](https://fastapi.tiangolo.com/), which give you better control over authentication, logging, and other features.
|
||||
|
||||
In this tutorial, we will use Starlette with [Uvicorn](https://www.uvicorn.org/).
|
||||
|
||||
## Server Setup in Helloworld
|
||||
|
||||
@ -16,21 +18,22 @@ Let's break this down:
|
||||
|
||||
1. **`DefaultRequestHandler`**:
|
||||
|
||||
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`).
|
||||
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (`HelloWorldAgentExecutor`), a `TaskStore` (`InMemoryTaskStore`), and the public and extended `AgentCard` objects.
|
||||
- It routes incoming A2A RPC calls to the appropriate methods on your executor (like `execute` or `cancel`).
|
||||
- The `TaskStore` is used by the `DefaultRequestHandler` to manage the lifecycle of tasks, especially for stateful interactions, streaming, and resubscription. Even if your agent executor is simple, the handler needs a task store.
|
||||
- `agent_card` is passed to the handler so it can verify the agent's declared capabilities when processing incoming requests. For example, it checks whether streaming or push notifications are supported before handling those request types.
|
||||
- `extended_agent_card` is passed so the handler can serve it via the `GetExtendedAgentCard` RPC method to authenticated clients.
|
||||
|
||||
2. **`A2AStarletteApplication`**:
|
||||
2. **`create_agent_card_routes` and `create_jsonrpc_routes`**:
|
||||
|
||||
- The `A2AStarletteApplication` class is instantiated with the `agent_card` and the `request_handler` (referred to as `http_handler` in its constructor).
|
||||
- The `agent_card` is crucial because the server will expose it at the `/.well-known/agent-card.json` endpoint (by default).
|
||||
- The `request_handler` is responsible for processing all incoming A2A method calls by interacting with your `AgentExecutor`.
|
||||
- `create_agent_card_routes(public_agent_card)` returns Starlette routes that expose the Agent Card at the `/.well-known/agent-card.json` endpoint for public discovery.
|
||||
- `create_jsonrpc_routes(request_handler, '/')` returns Starlette routes that handle all incoming A2A JSON-RPC method calls by delegating to the `request_handler`.
|
||||
- These route lists are combined and passed to a standard `Starlette` application.
|
||||
|
||||
3. **`uvicorn.run(server_app_builder.build(), ...)`**:
|
||||
- The `A2AStarletteApplication` has a `build()` method that constructs the actual Starlette application.
|
||||
- This application is then run using `uvicorn.run()`, making your agent accessible over HTTP.
|
||||
- `host='0.0.0.0'` makes the server accessible on all network interfaces on your machine.
|
||||
- `port=9999` specifies the port to listen on. This matches the `url` in the `AgentCard`.
|
||||
3. **`uvicorn.run(app, ...)`**:
|
||||
- The constructed `Starlette` app is run using `uvicorn.run()`, making your agent accessible over HTTP.
|
||||
- `host='127.0.0.1'` makes the server accessible only from your local machine.
|
||||
- `port=9999` specifies the port to listen on. This matches the endpoints defined in the `AgentCard`'s `supported_interfaces`.
|
||||
|
||||
## Running the Helloworld Server
|
||||
|
||||
@ -49,7 +52,7 @@ You should see output similar to this, indicating the server is running:
|
||||
INFO: Started server process [xxxxx]
|
||||
INFO: Waiting for application startup.
|
||||
INFO: Application startup complete.
|
||||
INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)
|
||||
INFO: Uvicorn running on http://127.0.0.1:9999 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
Your A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it.
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
# 6. Interacting with the Server
|
||||
|
||||
With the Helloworld A2A server running, let's send some requests to it. The SDK includes a client (`A2AClient`) that simplifies these interactions.
|
||||
With the Helloworld A2A server running, let's send some requests to it.
|
||||
|
||||
## The Helloworld Test Client
|
||||
|
||||
The `test_client.py` script demonstrates how to:
|
||||
|
||||
1. Fetch the Agent Card from the server.
|
||||
2. Create an `A2AClient` instance.
|
||||
3. Send both non-streaming (`message/send`) and streaming (`message/stream`) requests.
|
||||
2. Create a client using `create_client`.
|
||||
3. Send both `Send Message` and `Send Streaming Message` requests.
|
||||
|
||||
Open a **new terminal window**, activate your virtual environment, and navigate to the `a2a-samples` directory.
|
||||
|
||||
Activate virtual environment (Be sure to do this in the same directory where you created the virtual environment):
|
||||
Activate the virtual environment (be sure to do this in the same directory where you created it):
|
||||
|
||||
=== "Mac/Linux"
|
||||
|
||||
@ -37,59 +37,201 @@ python samples/python/agents/helloworld/test_client.py
|
||||
|
||||
Let's look at key parts of `test_client.py`:
|
||||
|
||||
1. **Fetching the Agent Card & Initializing the Client**:
|
||||
1. **Fetching the Agent Card**:
|
||||
|
||||
```python { .no-copy }
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver"
|
||||
```
|
||||
|
||||
The `A2ACardResolver` class is a convenience. It first fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL) and then initializes the client with it.
|
||||
The `A2ACardResolver` class is a convenience. When `get_agent_card()` is called, it fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL), which is then used to initialize the client.
|
||||
|
||||
2. **Sending a Non-Streaming Message (`send_message`)**:
|
||||
2. **Initializing the Client & Sending a Non-Streaming Message**:
|
||||
|
||||
```python { .no-copy }
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message"
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_send"
|
||||
```
|
||||
|
||||
- The `send_message_payload` constructs the data for `MessageSendParams`.
|
||||
- This is wrapped in a `SendMessageRequest`.
|
||||
- It includes a `message` object with the `role` set to "user" and the content in `parts`.
|
||||
- The Helloworld agent's `execute` method will enqueue a single "Hello World" message. The `DefaultRequestHandler` will retrieve this and send it as the response.
|
||||
- The `response` will be a `SendMessageResponse` object, which contains either a `SendMessageSuccessResponse` (with the agent's `Message` as the result) or a `JSONRPCErrorResponse`.
|
||||
- The `create_client` function creates a `Client` based on the information provided by the `AgentCard` and a `ClientConfig`.
|
||||
- We construct a `Message` using the `new_text_message` helper (passing `role=Role.ROLE_USER`), then wrap it in a `SendMessageRequest`.
|
||||
- The client's `send_message` method returns an async iterator that yields a single final `Task` or `Message` response from the agent. In this example, it is a `Task`.
|
||||
|
||||
3. **Handling Task IDs (Illustrative Note for Helloworld)**:
|
||||
|
||||
The Helloworld client (`test_client.py`) doesn't attempt `get_task` or `cancel_task` directly because the simple Helloworld agent's `execute` method, when called via `message/send`, results in the `DefaultRequestHandler` returning a direct `Message` response rather than a `Task` object. More complex agents that explicitly manage tasks (like the LangGraph example) would return a `Task` object from `message/send`, and its `id` could then be used for `get_task` or `cancel_task`.
|
||||
|
||||
4. **Sending a Streaming Message (`send_message_streaming`)**:
|
||||
3. **Initializing the Client & Sending a Streaming Message**:
|
||||
|
||||
```python { .no-copy }
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming"
|
||||
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_stream"
|
||||
```
|
||||
|
||||
- This method calls the agent's `message/stream` endpoint. The `DefaultRequestHandler` will invoke the `HelloWorldAgentExecutor.execute` method.
|
||||
- The `execute` method enqueues one "Hello World" message, and then the event queue is closed.
|
||||
- The client will receive this single message as one `SendStreamingMessageResponse` event, and then the stream will terminate.
|
||||
- The `stream_response` is an `AsyncGenerator`.
|
||||
- A separate streaming client is created via `create_client` with `streaming=True` in its `ClientConfig`.
|
||||
- We again call `send_message`, which now streams events: each iteration of the loop prints a discrete chunk as it arrives over the network.
|
||||
- Call `await streaming_client.close()` after the loop to release the underlying HTTP connection.
|
||||
|
||||
## Expected Output
|
||||
|
||||
When you run `test_client.py`, you'll see JSON outputs for:
|
||||
When you run `test_client.py`, you'll see output for:
|
||||
|
||||
- The non-streaming response (a single "Hello World" message).
|
||||
- The streaming response (a single "Hello World" message as one chunk, after which the stream ends).
|
||||
- The public agent card, displayed in a formatted summary.
|
||||
- The non-streaming response: a single `task` in protobuf text format containing the completed status, the generated artifact with "Hello, World!", and the agent's intermediate status message in history.
|
||||
- The streaming response: four chunks — the initial `task`, a `status_update` for WORKING, an `artifact_update` with the result, and a final `status_update` for COMPLETED.
|
||||
- The extended agent card, displayed in a formatted summary (with an additional `super_hello_world` skill).
|
||||
|
||||
The `id` fields in the output will vary with each run.
|
||||
|
||||
```console { .no-copy }
|
||||
AgentCard
|
||||
--- General ---
|
||||
Name : Hello World Agent
|
||||
Description : Just a hello world agent
|
||||
Version : 0.0.1
|
||||
|
||||
--- Interfaces ---
|
||||
[0] http://127.0.0.1:9999 (JSONRPC)
|
||||
|
||||
--- Capabilities ---
|
||||
Streaming : True
|
||||
Push notifications : False
|
||||
Extended agent card : True
|
||||
|
||||
--- I/O Modes ---
|
||||
Input : text/plain
|
||||
Output : text/plain
|
||||
|
||||
--- Skills ---
|
||||
----------------------------------------------------
|
||||
ID : hello_world
|
||||
Name : Returns hello world
|
||||
Description : just returns hello world
|
||||
Tags : hello world
|
||||
Example : hi
|
||||
Example : hello world
|
||||
|
||||
--- Non-Streaming Call ---
|
||||
|
||||
Non-streaming Client initialized.
|
||||
Response:
|
||||
// Non-streaming response
|
||||
{"jsonrpc":"2.0","id":"xxxxxxxx","result":{"type":"message","role":"agent","parts":[{"type":"text","text":"Hello World"}],"messageId":"yyyyyyyy"}}
|
||||
// Streaming response (one chunk)
|
||||
{"jsonrpc":"2.0","id":"zzzzzzzz","result":{"type":"message","role":"agent","parts":[{"type":"text","text":"Hello World"}],"messageId":"wwwwwwww","final":true}}
|
||||
task {
|
||||
id: "xxxxxxxx"
|
||||
context_id: "yyyyyyyy"
|
||||
status {
|
||||
state: TASK_STATE_COMPLETED
|
||||
}
|
||||
artifacts {
|
||||
artifact_id: "zzzzzzzz"
|
||||
name: "result"
|
||||
parts {
|
||||
text: "Hello, World!"
|
||||
}
|
||||
}
|
||||
history {
|
||||
message_id: "vvvvvvvv"
|
||||
context_id: "yyyyyyyy"
|
||||
task_id: "xxxxxxxx"
|
||||
role: ROLE_USER
|
||||
parts {
|
||||
text: "Say hello."
|
||||
}
|
||||
}
|
||||
history {
|
||||
message_id: "wwwwwwww"
|
||||
role: ROLE_AGENT
|
||||
parts {
|
||||
text: "Processing request..."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Streaming response
|
||||
task {
|
||||
id: "xxxxxxxx-s"
|
||||
context_id: "yyyyyyyy-s"
|
||||
status {
|
||||
state: TASK_STATE_SUBMITTED
|
||||
}
|
||||
history {
|
||||
message_id: "vvvvvvvv"
|
||||
context_id: "yyyyyyyy-s"
|
||||
task_id: "xxxxxxxx-s"
|
||||
role: ROLE_USER
|
||||
parts {
|
||||
text: "Say hello."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Response chunk:
|
||||
status_update {
|
||||
task_id: "xxxxxxxx-s"
|
||||
context_id: "yyyyyyyy-s"
|
||||
status {
|
||||
state: TASK_STATE_WORKING
|
||||
message {
|
||||
message_id: "zzzzzzzz-s"
|
||||
role: ROLE_AGENT
|
||||
parts {
|
||||
text: "Processing request..."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Response chunk:
|
||||
artifact_update {
|
||||
task_id: "xxxxxxxx-s"
|
||||
context_id: "yyyyyyyy-s"
|
||||
artifact {
|
||||
artifact_id: "wwwwwwww-s"
|
||||
name: "result"
|
||||
parts {
|
||||
text: "Hello, World!"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Response chunk:
|
||||
status_update {
|
||||
task_id: "xxxxxxxx-s"
|
||||
context_id: "yyyyyyyy-s"
|
||||
status {
|
||||
state: TASK_STATE_COMPLETED
|
||||
}
|
||||
}
|
||||
AgentCard
|
||||
--- General ---
|
||||
Name : Hello World Agent - Extended Edition
|
||||
Description : The full-featured hello world agent for authenticated users.
|
||||
Version : 0.0.2
|
||||
|
||||
--- Interfaces ---
|
||||
[0] http://127.0.0.1:9999 (JSONRPC)
|
||||
|
||||
--- Capabilities ---
|
||||
Streaming : True
|
||||
Push notifications : False
|
||||
Extended agent card : True
|
||||
|
||||
--- I/O Modes ---
|
||||
Input : text/plain
|
||||
Output : text/plain
|
||||
|
||||
--- Skills ---
|
||||
----------------------------------------------------
|
||||
ID : hello_world
|
||||
Name : Returns hello world
|
||||
Description : just returns hello world
|
||||
Tags : hello world
|
||||
Example : hi
|
||||
Example : hello world
|
||||
----------------------------------------------------
|
||||
ID : super_hello_world
|
||||
Name : Returns a SUPER Hello World
|
||||
Description : A more enthusiastic greeting, only for authenticated users.
|
||||
Tags : hello world, super, extended
|
||||
Example : super hi
|
||||
Example : give me a super hello
|
||||
```
|
||||
|
||||
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww` will be different UUIDs/request IDs)_
|
||||
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww`, and `vvvvvvvv` will be different UUIDs in each run.)_
|
||||
|
||||
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure!
|
||||
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure.
|
||||
|
||||
Now you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.
|
||||
You can now shut down the server by pressing Ctrl+C in the terminal window where `__main__.py` is running.
|
||||
|
||||
@ -1,12 +1,12 @@
|
||||
# 7. Streaming & Multi-Turn Interactions (LangGraph Example)
|
||||
|
||||
The Helloworld example demonstrates the basic mechanics of A2A. For more advanced features like robust streaming, task state management, and multi-turn conversations powered by an LLM, we'll turn to the LangGraph example located in [`a2a-samples/samples/python/agents/langgraph/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/langgraph).
|
||||
The Hello World example demonstrates the basic mechanics of A2A. For more advanced features like robust streaming, task state management, and multi-turn conversations powered by an LLM, we'll turn to the LangGraph example located in [`a2a-samples/samples/python/agents/langgraph/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/langgraph).
|
||||
|
||||
This example features a "Currency Agent" that uses the Gemini model via LangChain and LangGraph to answer currency conversion questions.
|
||||
|
||||
## Setting up the LangGraph Example
|
||||
|
||||
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one.
|
||||
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key) if you don't already have one.
|
||||
|
||||
2. **Environment Variable:**
|
||||
|
||||
@ -64,22 +64,22 @@ The `langgraph` example showcases several important A2A concepts:
|
||||
```
|
||||
|
||||
- The `CurrencyAgentExecutor` (in `samples/langgraph/agent_executor.py`), when its `execute` method is called by the `DefaultRequestHandler`, interacts with the `RequestContext` which contains the current task (if any).
|
||||
- For `message/send`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `message/send` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
|
||||
- For `Send Message`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `Send Message` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
|
||||
- The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`.
|
||||
|
||||
3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**:
|
||||
|
||||
- The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`.
|
||||
- As the LangGraph agent processes the request (which might involve calling tools like `get_exchange_rate`), the `CurrencyAgentExecutor` enqueues different types of events onto the `EventQueue`:
|
||||
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates.."). The `final` flag on these events is `False`.
|
||||
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates...").
|
||||
- `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`.
|
||||
- A final `TaskStatusUpdateEvent` with `state=TaskState.completed` and `final=True` is sent to signify the end of the task for streaming.
|
||||
- A final `TaskStatusUpdateEvent` with `state=TaskState.completed` is sent to signify the end of the task, closing the stream.
|
||||
- The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server.
|
||||
|
||||
4. **Multi-Turn Conversation (`TaskState.input_required`)**:
|
||||
|
||||
- The `CurrencyAgent` can ask for clarification if a query is ambiguous (e.g., user asks "how much is 100 USD?").
|
||||
- When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., "To which currency would you like to convert?"). This event will have `final=True` for the current interaction stream.
|
||||
- When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., "To which currency would you like to convert?"). The stream closes after this event.
|
||||
- The `test_client.py`'s `run_multi_turn_test` function demonstrates this:
|
||||
- It sends an initial ambiguous query.
|
||||
- The agent responds (via the `DefaultRequestHandler` processing the enqueued events) with a `Task` whose status is `input_required`.
|
||||
|
||||
@ -31,7 +31,7 @@ Here are some ideas and resources to continue your A2A journey:
|
||||
- **Experiment with Advanced Features:**
|
||||
- Implement robust task management with a persistent `TaskStore` if your agent handles long-running or multi-session tasks.
|
||||
- Explore implementing push notifications if your agent's tasks are very long-lived.
|
||||
- Consider more complex input and output modalities (e.g., handling file uploads/downloads, or structured data via `DataPart`).
|
||||
- Consider more complex input and output modalities (e.g., handling file uploads/downloads via file Parts, or structured data via data Parts).
|
||||
- **Contribute to the A2A Community:**
|
||||
- Join the discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
|
||||
- Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
|
||||
|
||||
990
docs/whats-new-v1.md
Normal file
@ -0,0 +1,990 @@
|
||||
# What's New in A2A Protocol v1.0
|
||||
|
||||
This document provides a comprehensive overview of changes from A2A Protocol v0.3.0 to v1.0. The v1.0 release represents a significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
|
||||
|
||||
## Overview of Major Themes
|
||||
|
||||
The v1.0 release focuses on four major themes:
|
||||
|
||||
### 1. **Protocol Maturity and Standardization**
|
||||
|
||||
- Elevate a2a.proto from being a gRPC-specific implementation file to the universal, normative source of truth
|
||||
- Leverage formal specification standards (RFC 8785, RFC 7515) and google.rpc.Status where possible
|
||||
- Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings
|
||||
- Enhanced versioning strategy with explicit backward compatibility rules
|
||||
- Comprehensive error taxonomy with protocol-specific mappings
|
||||
|
||||
### 2. **Enhanced Type Safety and Clarity**
|
||||
|
||||
- Removal of discriminator `kind` fields in favor of JSON member-based polymorphism
|
||||
- **Breaking:** Enum values changed from `kebab-case` to `SCREAMING_SNAKE_CASE` for compliance with the ProtoJSON specification
|
||||
- Stricter field naming conventions (`camelCase` for JSON)
|
||||
- More precise timestamp specifications (ISO 8601 with millisecond precision)
|
||||
- Better-defined data types with clearer Optional vs Required semantics
|
||||
|
||||
### 3. **Improved Developer Experience**
|
||||
|
||||
- Renamed operations for consistency and clarity
|
||||
- Reorganized Agent Card structure for better logical grouping
|
||||
- Enhanced extension mechanism with versioning and requirement declarations
|
||||
- More explicit service parameter handling (A2A-Version, A2A-Extensions headers)
|
||||
- **Simplified ID format** - Removed complex compound IDs (e.g., `tasks/{id}`) in favor of simple UUIDs
|
||||
- **Protocol versioning per interface** - Each AgentInterface specifies its own protocol version for better backward compatibility
|
||||
- **Multi-tenancy support** - Native tenant scoping in gRPC requests
|
||||
|
||||
### 4. **Enterprise-Ready Features**
|
||||
|
||||
- Agent Card signature verification using JWS and JSON Canonicalization
|
||||
- Formal specification of all three protocol bindings with equivalence guarantees
|
||||
- Enhanced security scheme declarations with mutual TLS support
|
||||
- **Modern OAuth 2.0 flows** - Added Device Code flow (RFC 8628), removed deprecated implicit/password flows
|
||||
- **PKCE support** - Added `pkce_required` field to Authorization Code flow for enhanced security
|
||||
- Cursor-based pagination for scalable task listing
|
||||
|
||||
---
|
||||
|
||||
## Behavioral Changes for Core Operations
|
||||
|
||||
### Send Message (`message/send` → **`SendMessage`**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Operation named `message/send`
|
||||
- Less formal specification of when `Task` vs `Message` is returned
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** Operation now **`SendMessage`**
|
||||
- **✅ CLARIFIED:** More precise specification of Task vs Message return semantics
|
||||
|
||||
### Send Streaming Message (`message/stream` → **SendStreamingMessage**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Operation named `message/stream`
|
||||
- Stream events had `kind` discriminator field
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** Operation now **`SendStreamingMessage`**
|
||||
- **✅ BREAKING:** Stream events no longer have `kind` field
|
||||
- Use JSON member names to discriminate between `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`
|
||||
- **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.
|
||||
- **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events
|
||||
|
||||
### Get Task (`tasks/get` → **GetTask**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Operation named `tasks/get`
|
||||
- Returns task with status, artifacts, and optionally history
|
||||
- Less formal specification of what "include history" means
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** Operation now **GetTask**
|
||||
- **✅ NEW:** `createdAt` and `lastModified` timestamp fields added to Task object
|
||||
- **✅ CLARIFIED:** More precise specification of history inclusion behavior
|
||||
- **✅ NEW:** Task object now includes `extensions[]` array in messages and artifacts
|
||||
- **✅ CLARIFIED:** Authentication/authorization scoping - servers MUST only return tasks visible to caller
|
||||
|
||||
### List Tasks (`tasks/list` → **ListTasks**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Operation unavailable.
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ NEW:** New operation **ListTasks** with filtering capabilities
|
||||
- **✅ CLARIFIED:** Task visibility scoped to authenticated caller
|
||||
|
||||
### Cancel Task (`tasks/cancel` → **CancelTask**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Operation named `tasks/cancel`
|
||||
- Request with taskId, returns Task
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** Operation now **CancelTask**
|
||||
- **✅ CLARIFIED:** More precise specification of when cancellation is allowed
|
||||
- **✅ CLARIFIED:** Task state transitions for cancellation scenarios
|
||||
|
||||
### Get Agent Card (Well-known URI and **GetExtendedAgentCard**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Discovery via `/.well-known/agent-card.json`
|
||||
- Extended card via `agent/getAuthenticatedExtendedCard`
|
||||
- `supportsAuthenticatedExtendedCard` boolean at top level
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** `agent/getAuthenticatedExtendedCard` → **GetExtendedAgentCard**
|
||||
- **✅ BREAKING:** `supportsAuthenticatedExtendedCard` moved to `capabilities.extendedAgentCard`
|
||||
- **✅ NEW:** Canonicalization (RFC 8785) clarified for Agent Card signature
|
||||
- **✅ BREAKING:** `protocolVersion` moved from AgentCard to individual AgentInterface objects
|
||||
- **✅ BREAKING:** `preferredTransport` and `additionalInterfaces` consolidated into `supportedInterfaces[]`
|
||||
- Each interface has `url`, `protocolBinding`, and `protocolVersion`
|
||||
|
||||
### Subscribe to task (`tasks/resubscribe` → **SubscribeToTask**)
|
||||
|
||||
**v0.3.0 Behavior:**
|
||||
|
||||
- Used `tasks/resubscribe` to reconnect interrupted SSE streams
|
||||
- Backfill behavior implementation-dependent
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** Operation now **SubscribeToTask**
|
||||
- **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle
|
||||
- **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state
|
||||
- **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task
|
||||
|
||||
### Push Notification Operations
|
||||
|
||||
**v0.3.0 Operations:**
|
||||
|
||||
- `tasks/pushNotificationConfig/set`
|
||||
- `tasks/pushNotificationConfig/get`
|
||||
- `tasks/pushNotificationConfig/list`
|
||||
- `tasks/pushNotificationConfig/delete`
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ RENAMED:** Operations now **CreateTaskPushNotificationConfig**, **GetTaskPushNotificationConfig**, **ListTaskPushNotificationConfigs**, **DeleteTaskPushNotificationConfig**
|
||||
- **✅ NEW:** `createdAt` timestamp field added to PushNotificationConfig
|
||||
- **✅ CLARIFIED:** Push notification payloads now use StreamResponse format
|
||||
- **✅ BREAKING:** model changed for all methods, with TaskPushNotificationConfig flattened
|
||||
|
||||
### NEW: Multi-Tenancy Support
|
||||
|
||||
**v0.3.0:**
|
||||
|
||||
- No native multi-tenancy support in protocol
|
||||
- Tenants handled implicitly via authentication or URL paths
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ NEW:** `tenant` field added to all request messages
|
||||
- **✅ NEW:** `tenant` field added to `AgentInterface` to specify default tenant
|
||||
- **✅ CLARIFIED:** Tenant provided per-request, inherited from AgentInterface
|
||||
- **✅ USE CASE:** Enables to serve multiple agents from a single endpoint
|
||||
|
||||
### Protocol Simplifications
|
||||
|
||||
#### ID Format Simplification (#1389)
|
||||
|
||||
**v0.3.0:**
|
||||
|
||||
- Some operations used complex compound IDs like `tasks/{taskId}`
|
||||
- Required clients/servers to construct/deconstruct resource names
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ BREAKING:** All IDs are now simple literals
|
||||
- **✅ BREAKING:** Operations that previously used compound IDs now separate parent and resource ID
|
||||
- Example: `tasks/{taskId}/pushNotificationConfigs/{configId}` → separate `task_id` and `config_id` fields
|
||||
- **✅ BENEFIT:** Simpler to implement - IDs map directly to database keys
|
||||
|
||||
#### HTTP URL Path Simplification (#1269)
|
||||
|
||||
**v0.3.0:**
|
||||
|
||||
- HTTP+JSON binding used `/v1/` prefix in URLs
|
||||
- Example: `POST /v1/message:send`
|
||||
|
||||
**v1.0 Changes:**
|
||||
|
||||
- **✅ BREAKING:** Removed `/v1` prefix from HTTP+JSON URL paths
|
||||
- **✅ NEW:** Examples: `POST /message:send`, `GET /tasks/{id}`
|
||||
- **✅ RATIONALE:** Version can be part of the base url if required by agent owner
|
||||
- **✅ BENEFIT:** Cleaner URLs, version management at interface level
|
||||
|
||||
---
|
||||
|
||||
## Structural Changes in Core Model Objects
|
||||
|
||||
### TaskStatus Object
|
||||
|
||||
**Modified Fields:**
|
||||
|
||||
- ✅ `state`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
|
||||
- v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"canceled"`, `"rejected"`, `"input-required"`, `"auth-required"`
|
||||
- v1.0: `"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_AUTH_REQUIRED"`
|
||||
- ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
|
||||
|
||||
**Removed Fields:**
|
||||
|
||||
- None
|
||||
|
||||
**Example Migration:**
|
||||
|
||||
```json
|
||||
// v0.3.0
|
||||
{
|
||||
"status": {
|
||||
"state": "completed",
|
||||
"timestamp": "2024-03-15T10:15:00Z"
|
||||
}
|
||||
}
|
||||
|
||||
// v1.0
|
||||
{
|
||||
"status": {
|
||||
"state": "TASK_STATE_COMPLETED",
|
||||
"timestamp": "2024-03-15T10:15:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Message Object
|
||||
|
||||
**Added Fields:**
|
||||
|
||||
- ✅ `extensions[]`: Array of extension URIs applicable to this message
|
||||
|
||||
**Modified Fields:**
|
||||
|
||||
- ✅ `role`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `ROLE_` prefix
|
||||
- v0.3.0: `"user"`, `"agent"`
|
||||
- v1.0: `"ROLE_USER"`, `"ROLE_AGENT"`
|
||||
|
||||
**Example Migration:**
|
||||
|
||||
```json
|
||||
// v0.3.0
|
||||
{
|
||||
"role": "user",
|
||||
"parts": [{"kind": "text", "text": "Hello"}]
|
||||
}
|
||||
|
||||
// v1.0
|
||||
{
|
||||
"role": "ROLE_USER",
|
||||
"parts": [{"text": "Hello"}],
|
||||
}
|
||||
```
|
||||
|
||||
**Behavior Changes:**
|
||||
|
||||
- Parts array now uses member-based discrimination instead of `kind` field
|
||||
|
||||
### Part Object
|
||||
|
||||
**BREAKING CHANGE - Complete Redesign:**
|
||||
|
||||
The Part structure has been completely redesigned in v1.0. Instead of separate TextPart, FilePart, and DataPart message types, there is now a single unified `Part` message.
|
||||
|
||||
**v0.3.0 Structure (Separate Types):**
|
||||
|
||||
```json
|
||||
// Text example
|
||||
{
|
||||
"kind": "text",
|
||||
"text": "Hello world"
|
||||
}
|
||||
|
||||
// File example
|
||||
{
|
||||
"kind": "file",
|
||||
"file": {
|
||||
"fileWithUri": "https://example.com/doc.pdf",
|
||||
"mimeType": "application/pdf"
|
||||
}
|
||||
}
|
||||
|
||||
// Data example
|
||||
{
|
||||
"kind": "data",
|
||||
"data": {"key": "value"}
|
||||
}
|
||||
```
|
||||
|
||||
**v1.0 Structure (Unified Part):**
|
||||
|
||||
```json
|
||||
// Text example
|
||||
{
|
||||
"text": "Hello world",
|
||||
"mediaType": "text/plain"
|
||||
}
|
||||
|
||||
// File with URL example
|
||||
{
|
||||
"url": "https://example.com/doc.pdf",
|
||||
"filename": "doc.pdf",
|
||||
"mediaType": "application/pdf"
|
||||
}
|
||||
|
||||
// File with raw bytes example
|
||||
{
|
||||
"raw": "base64encodedcontent==",
|
||||
"filename": "image.png",
|
||||
"mediaType": "image/png"
|
||||
}
|
||||
|
||||
// Data example
|
||||
{
|
||||
"data": {"key": "value"},
|
||||
"mediaType": "application/json"
|
||||
}
|
||||
```
|
||||
|
||||
**Changes:**
|
||||
|
||||
- ⛔ **REMOVED:** Separate `TextPart`, `FilePart`, and `DataPart` types
|
||||
- ⛔ **REMOVED:** `kind` discriminator field
|
||||
- ⛔ **REMOVED:** Nested `file` object structure
|
||||
- ✅ **NEW:** Single unified `Part` message with `oneof content` field
|
||||
- ✅ **NEW:** Content type determined by which field is present: `text`, `raw`, `url`, or `data`
|
||||
- ✅ **NEW:** `mediaType` field (replaces `mimeType`) - available for all part types
|
||||
- ✅ **NEW:** `filename` field - available for all part types (not just files)
|
||||
- ✅ **NEW:** `raw` field for inline binary content (base64 in JSON)
|
||||
- ✅ **NEW:** `url` field for file references (replaces `file.fileWithUri`)
|
||||
|
||||
**Migration Examples:**
|
||||
|
||||
```typescript
|
||||
// v0.3.0
|
||||
const textPart = { kind: "text", text: "Hello" };
|
||||
const filePart = { kind: "file", file: { fileWithUri: "https://...", mimeType: "image/png" } };
|
||||
const dataPart = { kind: "data", data: { key: "value" } };
|
||||
|
||||
// v1.0
|
||||
const textPart = { text: "Hello", mediaType: "text/plain" };
|
||||
const filePart = { url: "https://...", mediaType: "image/png", filename: "image.png" };
|
||||
const dataPart = { data: { key: "value" }, mediaType: "application/json" };
|
||||
|
||||
// Discrimination changed from kind field to member presence
|
||||
if (part.kind === "text") { ... } // v0.3.0
|
||||
if ("text" in part) { ... } // v1.0
|
||||
```
|
||||
|
||||
### Artifact Object
|
||||
|
||||
**Added Fields:**
|
||||
|
||||
- ✅ `extensions[]`: Array of extension URIs
|
||||
|
||||
**Modified Fields:**
|
||||
|
||||
- ✅ `parts[]`: Now uses member-based Part discrimination (see Part changes above)
|
||||
|
||||
### AgentCard Object
|
||||
|
||||
**Added Fields:**
|
||||
|
||||
- ✅ `supportedInterfaces[]`: Array of `AgentInterface` objects
|
||||
|
||||
**Removed Fields:**
|
||||
|
||||
- ⛔ `protocolVersion`: Removed from AgentCard (now in each AgentInterface)
|
||||
- ⛔ `preferredTransport`: Consolidated into `supportedInterfaces`
|
||||
- ⛔ `additionalInterfaces`: Consolidated into `supportedInterfaces`
|
||||
- ⛔ `supportsAuthenticatedExtendedCard`: Moved to `capabilities.extendedAgentCard`
|
||||
- ⛔ `url`: Primary endpoint now in `supportedInterfaces[0].url`
|
||||
|
||||
**Structure Example:**
|
||||
|
||||
**v0.3.0:**
|
||||
|
||||
```json
|
||||
{
|
||||
"protocolVersion": "0.3",
|
||||
"url": "https://agent.example.com/a2a",
|
||||
"preferredTransport": "JSONRPC",
|
||||
"supportsAuthenticatedExtendedCard": true,
|
||||
"additionalInterfaces": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**v1.0:**
|
||||
|
||||
```json
|
||||
{
|
||||
"supportedInterfaces": [
|
||||
{
|
||||
"url": "https://agent.example.com/a2a",
|
||||
"protocolBinding": "JSONRPC",
|
||||
"protocolVersion": "1.0"
|
||||
}
|
||||
],
|
||||
"capabilities": {
|
||||
"extendedAgentCard": true
|
||||
},
|
||||
"signatures": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### AgentCapabilities Object
|
||||
|
||||
**Modified Fields:**
|
||||
|
||||
- ✅ `extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard` field
|
||||
|
||||
### PushNotificationConfig Object
|
||||
|
||||
**Added Fields:**
|
||||
|
||||
- ✅ `configId`: Unique identifier for the configuration
|
||||
- ✅ `createdAt`: Timestamp - Configuration creation time
|
||||
|
||||
**Modified Fields:**
|
||||
|
||||
- ✅ `authentication`: Enhanced PushNotificationAuthenticationInfo structure
|
||||
|
||||
### Stream Event Objects
|
||||
|
||||
**TaskStatusUpdateEvent:**
|
||||
|
||||
**v0.3.0:**
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "taskStatusUpdate",
|
||||
"taskId": "...",
|
||||
"contextId": "...",
|
||||
"status": {...},
|
||||
"final": true
|
||||
}
|
||||
```
|
||||
|
||||
**v1.0:**
|
||||
|
||||
```json
|
||||
{
|
||||
"taskStatusUpdate": {
|
||||
"taskId": "...",
|
||||
"contextId": "...",
|
||||
"status": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Changes:**
|
||||
|
||||
- ⛔ **REMOVED:** `kind` discriminator
|
||||
- ⛔ **REMOVED:** `final` boolean field (stream closure indicates completion instead)
|
||||
- ✅ **NEW PATTERN:** Event type determined by JSON member name (`taskStatusUpdate` or `taskArtifactUpdate`)
|
||||
- ✅ **CLARIFIED:** Terminal state indicated by protocol-specific stream closure mechanism
|
||||
|
||||
**TaskArtifactUpdateEvent:**
|
||||
|
||||
**v0.3.0:**
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "taskArtifactUpdate",
|
||||
"taskId": "...",
|
||||
"contextId": "...",
|
||||
"artifact": {...}
|
||||
}
|
||||
```
|
||||
|
||||
**v1.0:**
|
||||
|
||||
```json
|
||||
{
|
||||
"taskArtifactUpdate": {
|
||||
"taskId": "...",
|
||||
"contextId": "...",
|
||||
"artifact": {...},
|
||||
"index": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Changes:**
|
||||
|
||||
- ⛔ **REMOVED:** `kind` discriminator
|
||||
- ✅ **NEW PATTERN:** Wrapped in `taskArtifactUpdate` object
|
||||
- ✅ **NEW:** `index` field indicates artifact position in task's artifacts array
|
||||
|
||||
### OAuth 2.0 Security Updates (#1303)
|
||||
|
||||
v1.0 modernizes OAuth 2.0 support in alignment with OAuth 2.0 Security Best Current Practice (BCP).
|
||||
|
||||
**Removed Flows (Deprecated by OAuth BCP):**
|
||||
|
||||
- ⛔ `ImplicitOAuthFlow` - Deprecated due to token leakage risks in browser history/logs
|
||||
- ⛔ `PasswordOAuthFlow` - Deprecated due to credential exposure risks
|
||||
|
||||
**Added Flows:**
|
||||
|
||||
- ✅ `DeviceCodeOAuthFlow` (RFC 8628) - For CLI tools, IoT devices, and input-constrained scenarios
|
||||
- Provides `device_authorization_url` endpoint
|
||||
- Supports `verification_uri`, `user_code` pattern
|
||||
- Ideal for headless environments
|
||||
|
||||
**Enhanced Security:**
|
||||
|
||||
- ✅ `pkce_required` field added to `AuthorizationCodeOAuthFlow` (RFC 7636)
|
||||
- Indicates whether PKCE (Proof Key for Code Exchange) is mandatory
|
||||
- Protects against authorization code interception attacks
|
||||
- Recommended for all OAuth clients, required for public clients
|
||||
|
||||
**Migration Guide:**
|
||||
|
||||
```typescript
|
||||
// v0.3.0 - Implicit Flow (now removed)
|
||||
{
|
||||
"implicitFlow": {
|
||||
"authorizationUrl": "https://auth.example.com/authorize",
|
||||
"scopes": {"read": "Read access"}
|
||||
}
|
||||
}
|
||||
|
||||
// v1.0 - Use Authorization Code + PKCE instead
|
||||
{
|
||||
"authorizationCodeFlow": {
|
||||
"authorizationUrl": "https://auth.example.com/authorize",
|
||||
"tokenUrl": "https://auth.example.com/token",
|
||||
"pkceRequired": true,
|
||||
"scopes": {"read": "Read access"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New Dependencies on Other Specifications
|
||||
|
||||
v1.0 introduces several new formal dependencies on industry-standard specifications:
|
||||
|
||||
### Added Specifications
|
||||
|
||||
#### ✅ google.rpc.Status / google.rpc.ErrorInfo
|
||||
|
||||
- **Purpose:** Standardized error response model with ProtoJSON representation
|
||||
- **Usage:** Error responses for HTTP+JSON and JSON-RPC bindings
|
||||
- **Impact:** Replaces RFC 9457 for HTTP errors. Enforces structured `ErrorInfo` with `reason` and `domain` for A2A-specific errors.
|
||||
|
||||
#### ✅ RFC 8785 - JSON Canonicalization Scheme (JCS)
|
||||
|
||||
- **Purpose:** Deterministic JSON serialization for signing
|
||||
- **Usage:** Agent Card signature verification
|
||||
- **Impact:** Enables cryptographic verification of Agent Card integrity
|
||||
- **Details:** Canonical form used before JWS signing (excludes `signatures` field)
|
||||
|
||||
#### ✅ RFC 7515 - JSON Web Signature (JWS)
|
||||
|
||||
- **Purpose:** Cryptographic signing standard
|
||||
- **Usage:** Agent Card signatures field
|
||||
- **Impact:** Industry-standard signature format for trust verification
|
||||
- **Details:** Supports detached signatures with public key retrieval via `jku` or trusted keystores
|
||||
|
||||
#### ✅ Google API Design Guidelines
|
||||
|
||||
- **Purpose:** gRPC best practices and conventions
|
||||
- **Usage:** gRPC binding design patterns
|
||||
- **Impact:** Better alignment with gRPC ecosystem expectations
|
||||
|
||||
#### ✅ ISO 8601
|
||||
|
||||
- **Purpose:** Timestamp format standard
|
||||
- **Usage:** All timestamp fields (createdAt, lastModified, timestamp)
|
||||
- **Impact:** Explicit format requirement: UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
|
||||
|
||||
### Existing Dependencies (Retained from v0.3.0)
|
||||
|
||||
- JSON-RPC 2.0
|
||||
- gRPC / Protocol Buffers 3
|
||||
- HTTP/HTTPS (various RFCs)
|
||||
- Server-Sent Events (SSE) - W3C specification
|
||||
- RFC 8615 - Well-known URIs
|
||||
- OAuth 2.0, OpenID Connect (for authentication)
|
||||
- TLS (RFC 8446 recommended)
|
||||
|
||||
### Complementary Protocol
|
||||
|
||||
**Model Context Protocol (MCP):**
|
||||
|
||||
- Relationship clarified: MCP handles tool/resource integration, A2A handles agent-to-agent coordination
|
||||
- Protocols are complementary, not competing
|
||||
- Agents may support both protocols for different use cases
|
||||
|
||||
---
|
||||
|
||||
## Impact on Developers
|
||||
|
||||
### Breaking Changes Requiring Code Updates
|
||||
|
||||
#### 1. Part Type Unification (CRITICAL IMPACT)
|
||||
|
||||
The most significant breaking change: TextPart, FilePart, and DataPart types have been removed and replaced with a single unified Part structure.
|
||||
|
||||
**Before (v0.3.0):**
|
||||
|
||||
```typescript
|
||||
// Separate types with kind discriminator
|
||||
if (part.kind === "text") {
|
||||
return part.text;
|
||||
} else if (part.kind === "file") {
|
||||
if (part.file.fileWithUri) {
|
||||
return fetchFile(part.file.fileWithUri);
|
||||
} else {
|
||||
return part.file.fileWithBytes;
|
||||
}
|
||||
} else if (part.kind === "data") {
|
||||
return part.data;
|
||||
}
|
||||
```
|
||||
|
||||
**After (v1.0):**
|
||||
|
||||
```typescript
|
||||
// Unified Part with oneof content
|
||||
if ("text" in part) {
|
||||
return part.text;
|
||||
} else if ("url" in part) {
|
||||
return fetchFile(part.url);
|
||||
} else if ("raw" in part) {
|
||||
return decodeBase64(part.raw);
|
||||
} else if ("data" in part) {
|
||||
return part.data;
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Stream Event Discriminator Pattern (HIGH IMPACT)
|
||||
|
||||
Stream events changed from kind-based to wrapper-based discrimination:
|
||||
|
||||
**Before (v0.3.0):**
|
||||
|
||||
```typescript
|
||||
if (event.kind === "taskStatusUpdate") {
|
||||
handleStatusUpdate(event);
|
||||
} else if (event.kind === "taskArtifactUpdate") {
|
||||
handleArtifactUpdate(event);
|
||||
}
|
||||
```
|
||||
|
||||
**After (v1.0):**
|
||||
|
||||
```typescript
|
||||
if ("taskStatusUpdate" in event) {
|
||||
handleStatusUpdate(event.taskStatusUpdate);
|
||||
} else if ("taskArtifactUpdate" in event) {
|
||||
handleArtifactUpdate(event.taskArtifactUpdate);
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Agent Card Structure (HIGH IMPACT)
|
||||
|
||||
Agent discovery and capability checking requires updates:
|
||||
|
||||
**Before (v0.3.0):**
|
||||
|
||||
```typescript
|
||||
const endpoint = agentCard.url;
|
||||
const transport = agentCard.preferredTransport;
|
||||
const supportsExtended = agentCard.supportsAuthenticatedExtendedCard;
|
||||
```
|
||||
|
||||
**After (v1.0):**
|
||||
|
||||
```typescript
|
||||
const primaryInterface = agentCard.supportedInterfaces[0];
|
||||
const endpoint = primaryInterface.url;
|
||||
const transport = primaryInterface.protocolBinding;
|
||||
const supportsExtended = agentCard.capabilities.extendedAgentCard;
|
||||
```
|
||||
|
||||
#### 4. Pagination (MEDIUM IMPACT)
|
||||
|
||||
List Tasks implementation must switch from page-based to cursor-based:
|
||||
|
||||
**Before (v0.3.0):**
|
||||
|
||||
```typescript
|
||||
const response = await listTasks({ page: 1, perPage: 50 });
|
||||
```
|
||||
|
||||
**After (v1.0):**
|
||||
|
||||
```typescript
|
||||
let cursor = undefined;
|
||||
do {
|
||||
const response = await listTasks({ cursor, limit: 50 });
|
||||
// process response.tasks
|
||||
cursor = response.nextCursor;
|
||||
} while (cursor);
|
||||
```
|
||||
|
||||
#### 5. Enum Value Changes (HIGH IMPACT)
|
||||
|
||||
All enum values now use SCREAMING_SNAKE_CASE with type prefixes:
|
||||
|
||||
**TaskState:**
|
||||
|
||||
```typescript
|
||||
// v0.3.0
|
||||
if (task.status.state === "completed") { ... }
|
||||
if (task.status.state === "input-required") { ... }
|
||||
|
||||
// v1.0
|
||||
if (task.status.state === "TASK_STATE_COMPLETED") { ... }
|
||||
if (task.status.state === "TASK_STATE_INPUT_REQUIRED") { ... }
|
||||
```
|
||||
|
||||
**MessageRole:**
|
||||
|
||||
```typescript
|
||||
// v0.3.0
|
||||
const message = { role: "user", parts: [...] };
|
||||
|
||||
// v1.0
|
||||
const message = { role: "ROLE_USER", parts: [...] };
|
||||
```
|
||||
|
||||
**Complete Mapping:**
|
||||
|
||||
- `"submitted"` → `"TASK_STATE_SUBMITTED"`
|
||||
- `"working"` → `"TASK_STATE_WORKING"`
|
||||
- `"completed"` → `"TASK_STATE_COMPLETED"`
|
||||
- `"failed"` → `"TASK_STATE_FAILED"`
|
||||
- `"canceled"` → `"TASK_STATE_CANCELED"`
|
||||
- `"rejected"` → `"TASK_STATE_REJECTED"`
|
||||
- `"input-required"` → `"TASK_STATE_INPUT_REQUIRED"`
|
||||
- `"auth-required"` → `"TASK_STATE_AUTH_REQUIRED"`
|
||||
- `"user"` → `"ROLE_USER"`
|
||||
- `"agent"` → `"ROLE_AGENT"`
|
||||
|
||||
#### 6. Field Name Changes (LOW IMPACT)
|
||||
|
||||
- `file.mimeType` → `mediaType`
|
||||
- Operation names (aliases provided during transition)
|
||||
|
||||
#### 7. Standardized Error Handling via google.rpc.Status (HIGH IMPACT)
|
||||
|
||||
HTTP+JSON error responses have been updated to use the ProtoJSON representation of `google.rpc.Status` instead of RFC 9457 (Problem Details). JSON-RPC and HTTP+JSON bindings now use `google.rpc.ErrorInfo` within the `data` / `details` array to provide A2A-specific error context.
|
||||
|
||||
**Changes:**
|
||||
|
||||
- **HTTP+JSON Content-Type:** Changed from `application/problem+json` to `application/json`.
|
||||
- **Error Model:** Uses `google.rpc.Status` fields (`code`, `message`, `details`).
|
||||
- **A2A Error Info:** MUST include a `google.rpc.ErrorInfo` object in `details` with `reason` (UPPER_SNAKE_CASE from A2A error types) and `domain: "a2a-protocol.org"`.
|
||||
|
||||
**JSON-RPC Example Migration:**
|
||||
|
||||
```json
|
||||
// v0.3.0
|
||||
"error": {
|
||||
"code": -32001,
|
||||
"message": "Task not found",
|
||||
"data": { "taskId": "123" }
|
||||
}
|
||||
|
||||
// v1.0
|
||||
"error": {
|
||||
"code": -32001,
|
||||
"message": "Task not found",
|
||||
"data": [
|
||||
{
|
||||
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
|
||||
"reason": "TASK_NOT_FOUND",
|
||||
"domain": "a2a-protocol.org",
|
||||
"metadata": { "taskId": "123" }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**HTTP+JSON Example Migration:**
|
||||
|
||||
```http
|
||||
// v0.3.0 (Draft using RFC 9457)
|
||||
HTTP/1.1 404 Not Found
|
||||
Content-Type: application/problem+json
|
||||
|
||||
{
|
||||
"type": "https://a2a-protocol.org/errors/task-not-found",
|
||||
"title": "Task Not Found",
|
||||
"status": 404,
|
||||
"detail": "The specified task ID does not exist"
|
||||
}
|
||||
|
||||
// v1.0
|
||||
HTTP/1.1 404 Not Found
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"error": {
|
||||
"code": 404,
|
||||
"status": "NOT_FOUND",
|
||||
"message": "The specified task ID does not exist",
|
||||
"details": [
|
||||
{
|
||||
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
|
||||
"reason": "TASK_NOT_FOUND",
|
||||
"domain": "a2a-protocol.org"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### New Capabilities to Leverage
|
||||
|
||||
#### 1. Execution Mode Control
|
||||
|
||||
```typescript
|
||||
// Wait for task completion (Default)
|
||||
const result = await sendMessage(message, { returnImmediately: false });
|
||||
|
||||
// Return immediately, poll later
|
||||
const task = await sendMessage(message, { returnImmediately: true });
|
||||
```
|
||||
|
||||
#### 2. Agent Card Signature Verification
|
||||
|
||||
```typescript
|
||||
if (agentCard.signatures && agentCard.signatures.length > 0) {
|
||||
const verified = await verifyAgentCardSignature(agentCard);
|
||||
if (!verified) {
|
||||
throw new Error("Agent Card signature verification failed");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Extension Requirements
|
||||
|
||||
```typescript
|
||||
const requiredExtensions = agentCard.extensions
|
||||
.filter(ext => ext.required)
|
||||
.map(ext => ext.uri);
|
||||
|
||||
// Check if client supports required extensions
|
||||
if (!clientSupportsAll(requiredExtensions)) {
|
||||
throw new Error("Missing required extension support");
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Enhanced Timestamp Tracking
|
||||
|
||||
```typescript
|
||||
const taskAge = Date.now() - new Date(task.createdAt).getTime();
|
||||
const timeSinceUpdate = Date.now() - new Date(task.lastModified).getTime();
|
||||
```
|
||||
|
||||
#### 5. Versioning Negotiation
|
||||
|
||||
```typescript
|
||||
// Client sends A2A-Version header
|
||||
headers["A2A-Version"] = "1.0";
|
||||
|
||||
// Server validates and rejects if unsupported
|
||||
if (!supportedVersions.includes(requestedVersion)) {
|
||||
throw new VersionNotSupportedError();
|
||||
}
|
||||
```
|
||||
|
||||
### Migration Strategy Recommendations
|
||||
|
||||
#### Phase 1: Compatibility Layer
|
||||
|
||||
1. Add support for parsing both old and new discriminator patterns
|
||||
2. Implement version detection based on protocol version
|
||||
3. Support both Agent Card structures during transition
|
||||
|
||||
#### Phase 2: Dual Support
|
||||
|
||||
1. Update all APIs to emit v1.0 format
|
||||
2. Maintain backward compatibility readers for v0.3.0
|
||||
3. Add A2A-Version header handling
|
||||
4. Implement cursor-based pagination alongside legacy page-based
|
||||
|
||||
#### Phase 3: v1.0 Only
|
||||
|
||||
1. Deprecate v0.3.0 compatibility code
|
||||
2. Remove legacy discriminator parsing
|
||||
3. Remove page-based pagination
|
||||
4. Clean up dual-format support code
|
||||
|
||||
#### Backward Compatibility Strategy (#1401)
|
||||
|
||||
v1.0 introduces a formal approach to protocol versioning that enables SDK backward compatibility.
|
||||
|
||||
**Protocol Version Per Interface:**
|
||||
|
||||
- Each `AgentInterface` now specifies its own `protocolVersion` field
|
||||
- Agents can support multiple protocol versions simultaneously by exposing multiple interfaces
|
||||
- Clients negotiate version by selecting appropriate interface from Agent Card
|
||||
|
||||
**SDK Implementation Pattern:**
|
||||
|
||||
```typescript
|
||||
// SDK can support multiple protocol versions
|
||||
class A2AClient {
|
||||
async connect(agentCardUrl: string) {
|
||||
const card = await this.getAgentCard(agentCardUrl);
|
||||
|
||||
// Find best matching interface
|
||||
const interface = card.supportedInterfaces.find(i =>
|
||||
this.supportedVersions.includes(i.protocolVersion)
|
||||
);
|
||||
|
||||
if (!interface) {
|
||||
throw new Error("No compatible protocol version");
|
||||
}
|
||||
|
||||
// Use version-specific adapter
|
||||
return this.createAdapter(interface.protocolVersion, interface);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- SDKs can maintain support for multiple protocol versions
|
||||
- Agents can gradually migrate by supporting both old and new versions
|
||||
- Clients automatically select best compatible version
|
||||
- Enables graceful deprecation of old protocol versions
|
||||
|
||||
### Testing Considerations
|
||||
|
||||
- Test with both v0.3.0 and v1.0 formatted data
|
||||
- Validate Agent Card signature verification
|
||||
- Test cursor-based pagination edge cases (empty results, single page, etc.)
|
||||
- Verify proper handling of new error types
|
||||
- Test extension requirement validation
|
||||
|
||||
### Recommended Priority
|
||||
|
||||
#### Critical (Do Immediately)
|
||||
|
||||
- Update Part and streaming event parsing (discriminator pattern)
|
||||
- Update Agent Card parsing (structure changes)
|
||||
- Add A2A-Version header to all requests
|
||||
|
||||
#### High (Within 1 Month)
|
||||
|
||||
- Implement cursor-based pagination
|
||||
- Update enum value handling (state field)
|
||||
- Add return_immediately parameter support
|
||||
|
||||
#### Medium (Within 3 Months)
|
||||
|
||||
- Implement Agent Card signature verification
|
||||
- Add extension requirement checking
|
||||
- Update timestamp handling to ISO 8601 format
|
||||
- Implement new error types
|
||||
|
||||
#### Low (Nice to Have)
|
||||
|
||||
- Add createdAt/lastModified timestamp tracking
|
||||
- Leverage enhanced metadata capabilities
|
||||
- Implement mutual TLS authentication support
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
A2A Protocol v1.0 represents a significant step forward in protocol maturity while maintaining the core architectural principles of v0.3.0. The changes focus on standardization, type safety, and enterprise readiness, requiring developers to update their implementations but providing clearer specifications and better developer experience in return.
|
||||
|
||||
The breaking changes, while requiring code updates, are straightforward to implement and improve code clarity. The new capabilities around versioning, signatures, and enhanced extensions provide a solid foundation for future protocol evolution within the v1.x line.
|
||||
|
||||
Developers should plan for a phased migration approach, prioritizing the critical breaking changes while gradually adopting new capabilities over time.
|
||||
@ -1,12 +1,11 @@
|
||||
exclude = [
|
||||
'https://fonts.gstatic.com/',
|
||||
'https://fonts.googleapis.com/',
|
||||
'http://go/github',
|
||||
'http://go/github-googlecloudplatform',
|
||||
'https://medium.com/',
|
||||
'https://x.com/',
|
||||
'http://localhost:12000/',
|
||||
'http://localhost:10020/',
|
||||
'https://goo.gle/',
|
||||
]
|
||||
exclude_path = [
|
||||
".github/actions/spelling",
|
||||
@ -14,6 +13,9 @@ exclude_path = [
|
||||
"docs/partners.md",
|
||||
"docs/robots.txt",
|
||||
"docs/llms.txt",
|
||||
"docs/spec/a2a.json",
|
||||
"docs/spec-proto.md",
|
||||
"docs/sdk/python.md",
|
||||
]
|
||||
|
||||
accept = ["200..=299", 403, 408, 429]
|
||||
|
||||
63
mkdocs.yml
@ -7,8 +7,12 @@ site_author: The Linux Foundation
|
||||
site_dir: site
|
||||
edit_uri: edit/main/docs/
|
||||
|
||||
# Exclude files from the docs directory
|
||||
exclude_docs: |
|
||||
README.md
|
||||
|
||||
extra:
|
||||
a2a_version: !ENV [MIKE_VERSION, 'dev']
|
||||
a2a_version: !ENV [MIKE_VERSION, "dev"]
|
||||
analytics:
|
||||
provider: google
|
||||
property: G-RB39M83WHB
|
||||
@ -16,30 +20,37 @@ extra:
|
||||
# Navigation
|
||||
nav:
|
||||
- Home: index.md
|
||||
- 🆕 Announcing Version 1.0: announcing-1.0.md
|
||||
- Documentation:
|
||||
- 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
|
||||
- Streaming & Asynchronous Operations: topics/streaming-and-async.md
|
||||
- A2A and MCP: topics/a2a-and-mcp.md
|
||||
- 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
|
||||
- Streaming & Asynchronous Operations: topics/streaming-and-async.md
|
||||
- A2A and MCP: topics/a2a-and-mcp.md
|
||||
- Tutorials and Samples:
|
||||
- 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
|
||||
- Specification: specification.md
|
||||
- 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:
|
||||
- Overview: specification.md
|
||||
- What's New in v1.0: whats-new-v1.md
|
||||
- Protocol Definition: definitions.md
|
||||
- SDK Reference:
|
||||
- sdk/index.md
|
||||
- Python: sdk/python/api/index.html
|
||||
- sdk/index.md
|
||||
- Python: sdk/python/api/index.html
|
||||
- Community: community.md
|
||||
- Partners: partners.md
|
||||
- Roadmap: roadmap.md
|
||||
@ -49,7 +60,7 @@ repo_name: a2aproject/A2A
|
||||
repo_url: https://github.com/a2aproject/A2A
|
||||
|
||||
# Copyright
|
||||
copyright: Copyright 2025 The Linux Foundation. Licensed under the Apache License, Version 2.0.
|
||||
copyright: Copyright 2026 The Linux Foundation. Licensed under the Apache License, Version 2.0.
|
||||
|
||||
# Custom CSS
|
||||
extra_css:
|
||||
@ -119,6 +130,7 @@ markdown_extensions:
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets:
|
||||
base_path: .
|
||||
url_download: true
|
||||
dedent_subsections: true
|
||||
- pymdownx.superfences:
|
||||
@ -137,10 +149,10 @@ markdown_extensions:
|
||||
# Plugins
|
||||
plugins:
|
||||
- search
|
||||
- macros
|
||||
- macros:
|
||||
module_name: .mkdocs/macros
|
||||
- redirects:
|
||||
redirect_maps:
|
||||
"spec-json.md": https://raw.githubusercontent.com/a2aproject/A2A/refs/heads/main/specification/json/a2a.json
|
||||
"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"
|
||||
@ -167,6 +179,5 @@ plugins:
|
||||
"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"
|
||||
"sdk/python/": "sdk/python/api/index.html"
|
||||
- mike:
|
||||
canonical_version: latest
|
||||
|
||||
@ -6,3 +6,5 @@ mkdocs-macros-plugin
|
||||
sphinx
|
||||
furo
|
||||
myst-parser
|
||||
proto-schema-parser
|
||||
tabulate
|
||||
|
||||
84
scripts/build_docs.sh
Executable file
@ -0,0 +1,84 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Unified docs build script that ensures the non-normative JSON artifact is
|
||||
# regenerated (if stale) before invoking MkDocs. Uses pure shell.
|
||||
|
||||
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
SCHEMA_JSON="$ROOT_DIR/specification/json/a2a.json"
|
||||
PROTO_SRC="$ROOT_DIR/specification/a2a.proto"
|
||||
SPEC_SITE_DIR="$ROOT_DIR/docs/spec"
|
||||
SCHEMA_JSON_SITE_FILE="$SPEC_SITE_DIR/a2a.json"
|
||||
PROTO_SITE_FILE="$SPEC_SITE_DIR/a2a.proto"
|
||||
PROTO_TO_SCHEMA_SCRIPT="$ROOT_DIR/scripts/proto_to_json_schema.sh"
|
||||
|
||||
regen_needed() {
|
||||
if [ ! -f "$SCHEMA_JSON" ]; then return 0; fi
|
||||
|
||||
local proto_mtime
|
||||
local schema_mtime
|
||||
if [[ "$(uname)" == "Darwin" ]]; then
|
||||
proto_mtime=$(stat -f %m "$PROTO_SRC")
|
||||
schema_mtime=$(stat -f %m "$SCHEMA_JSON")
|
||||
else
|
||||
proto_mtime=$(stat -c %Y "$PROTO_SRC")
|
||||
schema_mtime=$(stat -c %Y "$SCHEMA_JSON")
|
||||
fi
|
||||
[ "$proto_mtime" -gt "$schema_mtime" ]
|
||||
}
|
||||
|
||||
echo "[build_docs] Checking schema freshness..." >&2
|
||||
if regen_needed; then
|
||||
echo "[build_docs] Regenerating a2a.json from proto" >&2
|
||||
if [ -x "$PROTO_TO_SCHEMA_SCRIPT" ]; then
|
||||
bash "$PROTO_TO_SCHEMA_SCRIPT" "$SCHEMA_JSON" || {
|
||||
echo "[build_docs] Warning: proto to JSON schema conversion failed" >&2
|
||||
}
|
||||
else
|
||||
echo "[build_docs] proto_to_json_schema.sh missing or not executable; skipping schema generation." >&2
|
||||
fi
|
||||
else
|
||||
echo "[build_docs] Schema is up-to-date, skipping regeneration" >&2
|
||||
fi
|
||||
|
||||
# Always ensure spec files are available in docs directory for MkDocs
|
||||
mkdir -p "$SPEC_SITE_DIR"
|
||||
|
||||
if [ -f "$SCHEMA_JSON" ]; then
|
||||
cp "$SCHEMA_JSON" "$SCHEMA_JSON_SITE_FILE"
|
||||
echo "[build_docs] Published schema to $SCHEMA_JSON_SITE_FILE" >&2
|
||||
else
|
||||
echo "[build_docs] Warning: Schema file not found at $SCHEMA_JSON - MkDocs may fail" >&2
|
||||
fi
|
||||
|
||||
if [ -f "$PROTO_SRC" ]; then
|
||||
cp "$PROTO_SRC" "$PROTO_SITE_FILE"
|
||||
echo "[build_docs] Published proto to $PROTO_SITE_FILE" >&2
|
||||
else
|
||||
echo "[build_docs] Warning: Proto file not found at $PROTO_SRC" >&2
|
||||
fi
|
||||
|
||||
# Build SDK documentation
|
||||
echo "[build_docs] Building SDK documentation..." >&2
|
||||
SDK_DOCS_SCRIPT="$ROOT_DIR/scripts/build_sdk_docs.sh"
|
||||
if [ -x "$SDK_DOCS_SCRIPT" ]; then
|
||||
bash "$SDK_DOCS_SCRIPT" || echo "[build_docs] Warning: SDK docs build failed" >&2
|
||||
else
|
||||
echo "[build_docs] SDK docs script not found or not executable: $SDK_DOCS_SCRIPT" >&2
|
||||
fi
|
||||
|
||||
# Add venv bin to PATH to ensure mike finds mkdocs and plugins
|
||||
if [ -d "$ROOT_DIR/.doc-venv/bin" ]; then
|
||||
export PATH="$ROOT_DIR/.doc-venv/bin:$PATH"
|
||||
fi
|
||||
|
||||
if [ "${1:-}" = "deploy" ]; then
|
||||
shift
|
||||
echo "[build_docs] Deploying with mike..." >&2
|
||||
mike deploy "$@"
|
||||
else
|
||||
echo "[build_docs] Building MkDocs site..." >&2
|
||||
mkdocs build "$@"
|
||||
fi
|
||||
echo "[build_docs] Done." >&2
|
||||
@ -8,24 +8,51 @@ set -e
|
||||
OUTPUT_FILE="docs/llms-full.txt"
|
||||
DOCS_DIR="docs"
|
||||
SPEC_DIR="specification"
|
||||
TYPES_DIR="types"
|
||||
SDK_DOCS_SCRIPT="scripts/build_sdk_docs.sh"
|
||||
PROJECT_NAME="A2A (Agent2Agent) Protocol"
|
||||
|
||||
echo "--- Generating consolidated LLM file: ${OUTPUT_FILE} ---"
|
||||
|
||||
# Clear the output file to start fresh
|
||||
>"${OUTPUT_FILE}"
|
||||
# --- Generate Python SDK Text Documentation ---
|
||||
if [ -f "$SDK_DOCS_SCRIPT" ]; then
|
||||
echo "Generating Python SDK documentation..."
|
||||
bash "$SDK_DOCS_SCRIPT"
|
||||
else
|
||||
echo "Warning: SDK docs script not found at $SDK_DOCS_SCRIPT"
|
||||
fi
|
||||
|
||||
# --- Helper function to append file content with a header ---
|
||||
# Clear the output file and add introduction
|
||||
cat <<EOF >"${OUTPUT_FILE}"
|
||||
# ${PROJECT_NAME} - Full Documentation
|
||||
|
||||
This file is a consolidated version of all documentation, specifications, and API references
|
||||
for the ${PROJECT_NAME} project, optimized for LLM consumption.
|
||||
|
||||
EOF
|
||||
|
||||
# Include llms.txt as the core summary if it exists
|
||||
if [ -f "${DOCS_DIR}/llms.txt" ]; then
|
||||
echo "Including summary from ${DOCS_DIR}/llms.txt"
|
||||
{
|
||||
echo "## Project Summary"
|
||||
echo
|
||||
cat "${DOCS_DIR}/llms.txt"
|
||||
echo
|
||||
echo "---"
|
||||
echo
|
||||
} >>"${OUTPUT_FILE}"
|
||||
fi
|
||||
|
||||
# --- Helper function to append file content with XML-style tags ---
|
||||
append_file() {
|
||||
local file_path="$1"
|
||||
local display_path="${2:-$file_path}"
|
||||
if [ -f "$file_path" ]; then
|
||||
echo "Appending: $file_path"
|
||||
{
|
||||
echo "--- START OF FILE ${file_path} ---"
|
||||
echo
|
||||
echo "<file path=\"${display_path}\">"
|
||||
cat "$file_path"
|
||||
echo
|
||||
echo "================================================="
|
||||
echo "</file>"
|
||||
echo
|
||||
} >>"${OUTPUT_FILE}"
|
||||
else
|
||||
@ -33,16 +60,59 @@ append_file() {
|
||||
fi
|
||||
}
|
||||
|
||||
# --- Process Documentation Files ---
|
||||
# Find all markdown and rst files in the docs directory, sort them for consistent output,
|
||||
# and append each one.
|
||||
find "${DOCS_DIR}" -type f \( -name "*.md" -o -name "*.rst" \) | sort | while read -r doc_file; do
|
||||
append_file "$doc_file"
|
||||
# --- Build File List ---
|
||||
echo "## File Index" >>"${OUTPUT_FILE}"
|
||||
echo >>"${OUTPUT_FILE}"
|
||||
|
||||
# Collect all files we intend to include
|
||||
FILES_TO_INCLUDE=()
|
||||
FILES_TO_INCLUDE+=("README.md")
|
||||
|
||||
# Doc files
|
||||
while IFS= read -r doc_file; do
|
||||
FILES_TO_INCLUDE+=("$doc_file")
|
||||
done < <(find "${DOCS_DIR}" -type f \( -name "*.md" -o -name "*.rst" \) \
|
||||
-not -path "docs/sdk/python/*" \
|
||||
-not -path "docs/README.md" \
|
||||
-not -path "docs/sdk/python.md" \
|
||||
-not -path "docs/llms-full.txt" | sort)
|
||||
|
||||
# SDK text files
|
||||
SDK_TEXT_DIR="docs/sdk/python/_build/text"
|
||||
if [ -d "$SDK_TEXT_DIR" ]; then
|
||||
while IFS= read -r sdk_file; do
|
||||
FILES_TO_INCLUDE+=("$sdk_file")
|
||||
done < <(find "$SDK_TEXT_DIR" -type f -name "*.txt" | sort)
|
||||
fi
|
||||
|
||||
# Specification
|
||||
if [ -f "${SPEC_DIR}/a2a.proto" ]; then
|
||||
FILES_TO_INCLUDE+=("${SPEC_DIR}/a2a.proto")
|
||||
fi
|
||||
|
||||
# Write the index to the output file
|
||||
for f in "${FILES_TO_INCLUDE[@]}"; do
|
||||
display_name="$f"
|
||||
# Clean up display name for SDK files
|
||||
if [[ "$f" == "$SDK_TEXT_DIR"* ]]; then
|
||||
display_name="sdk/python/${f#"$SDK_TEXT_DIR"/}"
|
||||
fi
|
||||
echo "- ${display_name}" >>"${OUTPUT_FILE}"
|
||||
done
|
||||
|
||||
# --- Process Specification Files ---
|
||||
append_file "${SPEC_DIR}/grpc/a2a.proto"
|
||||
append_file "${SPEC_DIR}/json/a2a.json"
|
||||
append_file "${TYPES_DIR}/src/types.ts"
|
||||
{
|
||||
echo
|
||||
echo "---"
|
||||
echo
|
||||
} >>"${OUTPUT_FILE}"
|
||||
|
||||
# --- Append file contents ---
|
||||
for f in "${FILES_TO_INCLUDE[@]}"; do
|
||||
display_name="$f"
|
||||
if [[ "$f" == "$SDK_TEXT_DIR"* ]]; then
|
||||
display_name="sdk/python/${f#"$SDK_TEXT_DIR"/}"
|
||||
fi
|
||||
append_file "$f" "$display_name"
|
||||
done
|
||||
|
||||
echo "✅ Consolidated LLM file generated successfully at ${OUTPUT_FILE}"
|
||||
|
||||
@ -14,17 +14,16 @@ echo "--- Setting up documentation build environment ---"
|
||||
if [ -d "$VENV_DIR" ]; then
|
||||
rm -rf "$VENV_DIR"
|
||||
fi
|
||||
python3 -m venv "$VENV_DIR"
|
||||
uv venv "$VENV_DIR"
|
||||
source "$VENV_DIR/bin/activate"
|
||||
|
||||
echo "--- Installing package and dependencies ---"
|
||||
|
||||
# Upgrade pip and install documentation requirements
|
||||
pip install -U pip
|
||||
pip install -r "requirements-docs.txt"
|
||||
# Install documentation requirements
|
||||
uv pip install -r "requirements-docs.txt"
|
||||
|
||||
# Install the package itself
|
||||
pip install "${PYPI_PACKAGE_NAME}"
|
||||
uv pip install "${PYPI_PACKAGE_NAME}"
|
||||
|
||||
echo "--- Finding installed package path ---"
|
||||
|
||||
@ -44,9 +43,26 @@ echo "--- Building HTML documentation ---"
|
||||
# Build the HTML documentation
|
||||
sphinx-build -b html "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/html"
|
||||
|
||||
echo "--- Building Text documentation ---"
|
||||
|
||||
# Build the Text documentation
|
||||
sphinx-build -b text "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/text"
|
||||
|
||||
echo "--- Copying SDK docs to MkDocs integration path ---"
|
||||
|
||||
# Copy SDK docs to where MkDocs expects them (docs/sdk/python/api/)
|
||||
SDK_API_DIR="${DOCS_SOURCE_DIR}/api"
|
||||
if [ -d "${DOCS_BUILD_DIR}/html" ]; then
|
||||
rm -rf "${SDK_API_DIR}"
|
||||
cp -r "${DOCS_BUILD_DIR}/html" "${SDK_API_DIR}"
|
||||
echo "SDK docs copied to: ${SDK_API_DIR}"
|
||||
else
|
||||
echo "Warning: SDK docs build directory not found at ${DOCS_BUILD_DIR}/html"
|
||||
fi
|
||||
|
||||
# Deactivate the virtual environment
|
||||
deactivate
|
||||
|
||||
echo ""
|
||||
echo "✅ Documentation build complete!"
|
||||
echo "View the docs by opening: ${DOCS_BUILD_DIR}/html/index.html"
|
||||
echo "View the docs by opening: ${SDK_API_DIR}/index.html"
|
||||
|
||||
25
scripts/lint.sh
Executable file
@ -0,0 +1,25 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Exit on error (-e), undefined variable usage (-u), or failed pipe command (-o pipefail).
|
||||
set -euo pipefail
|
||||
|
||||
# Determine the repository root directory based on the script's location.
|
||||
SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
|
||||
REPO_ROOT=$(cd -- "${SCRIPT_DIR}/.." &>/dev/null && pwd)
|
||||
# Absolute path to the Super Linter configuration file.
|
||||
SUPER_LINTER_ENV="${REPO_ROOT}/.github/super-linter.env"
|
||||
# Detect the default branch from the remote repository.
|
||||
DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
|
||||
|
||||
# Run Super Linter locally using Docker.
|
||||
# This mirrors the configuration used in GitHub Actions to provide consistent linting behavior.
|
||||
docker run \
|
||||
--rm -t \
|
||||
--platform linux/x86_64 \
|
||||
-v "${REPO_ROOT}":/tmp/lint \
|
||||
-e SHELL=/bin/bash \
|
||||
-e DEFAULT_BRANCH="${DEFAULT_BRANCH}" \
|
||||
-e RUN_LOCAL=true \
|
||||
-e LOG_LEVEL=INFO \
|
||||
--env-file "${SUPER_LINTER_ENV}" \
|
||||
ghcr.io/super-linter/super-linter:slim-v8
|
||||
126
scripts/proto_to_json_schema.sh
Executable file
@ -0,0 +1,126 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
# Convert proto files to JSON Schema in a single operation.
|
||||
# Usage: proto_to_json_schema.sh <output_json_schema>
|
||||
|
||||
OUTPUT=${1:-}
|
||||
if [[ -z "$OUTPUT" ]]; then
|
||||
echo "Usage: $0 <output.json>" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
PROTO_DIR="$ROOT_DIR/specification"
|
||||
PROTO_FILE="$PROTO_DIR/a2a.proto"
|
||||
GOOGLEAPIS_DIR="${GOOGLEAPIS_DIR:-}"
|
||||
|
||||
check_command() {
|
||||
if ! command -v "$1" >/dev/null 2>&1; then
|
||||
echo "Error: $1 not found on PATH" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Check dependencies
|
||||
check_command "protoc"
|
||||
check_command "protoc-gen-jsonschema"
|
||||
check_command "jq"
|
||||
|
||||
# Verify protoc-gen-jsonschema is the correct implementation (bufbuild/protoschema-plugins)
|
||||
# The bufbuild implementation outputs a version string starting with "v" (e.g., "v0.5.2")
|
||||
# Other implementations (like chrusty/protoc-gen-jsonschema) typically output "protoc-gen-jsonschema version X.Y.Z"
|
||||
PLUGIN_VERSION=$(protoc-gen-jsonschema --version 2>&1 || true)
|
||||
if [[ ! "$PLUGIN_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||
echo "Error: Incorrect protoc-gen-jsonschema plugin detected." >&2
|
||||
echo "Current version output: '$PLUGIN_VERSION'" >&2
|
||||
echo "This script requires the plugin from github.com/bufbuild/protoschema-plugins" >&2
|
||||
echo "Please install it with:" >&2
|
||||
echo " go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Create temporary directory for intermediate files
|
||||
TEMP_DIR=$(mktemp -d)
|
||||
trap 'rm -rf "$TEMP_DIR"' EXIT
|
||||
|
||||
# Setup include paths for googleapis
|
||||
INCLUDE_FLAGS=("-I$PROTO_DIR")
|
||||
if [ -n "$GOOGLEAPIS_DIR" ]; then
|
||||
INCLUDE_FLAGS+=("-I$GOOGLEAPIS_DIR")
|
||||
elif [ -d "$ROOT_DIR/third_party/googleapis" ]; then
|
||||
INCLUDE_FLAGS+=("-I$ROOT_DIR/third_party/googleapis")
|
||||
elif [ -d "/usr/local/include/google/api" ]; then
|
||||
INCLUDE_FLAGS+=("-I/usr/local/include")
|
||||
fi
|
||||
|
||||
# Verify googleapis annotations are available
|
||||
ANNOTATIONS_FOUND=false
|
||||
for inc in "${INCLUDE_FLAGS[@]}"; do
|
||||
dir="${inc#-I}"
|
||||
if [ -f "$dir/google/api/annotations.proto" ]; then
|
||||
ANNOTATIONS_FOUND=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
if [ "$ANNOTATIONS_FOUND" != true ]; then
|
||||
echo "Error: google/api/annotations.proto not found in include paths" >&2
|
||||
echo "Set GOOGLEAPIS_DIR env var or ensure third_party/googleapis exists" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Step 0: Pre-process proto
|
||||
echo "→ Cleaning proto comments..." >&2
|
||||
|
||||
# Define path for the cleaned proto in the temp directory
|
||||
CLEAN_PROTO_FILE="$TEMP_DIR/$(basename "$PROTO_FILE")"
|
||||
|
||||
# Use grep to remove lines containing specific patterns:
|
||||
# 1. matches "// --8<--"
|
||||
# 2. matches "// protolint:"
|
||||
grep -v -e "// --8<--" -e "// protolint:" "$PROTO_FILE" >"$CLEAN_PROTO_FILE"
|
||||
|
||||
# Add the temp dir to the include path so protoc finds the clean file context
|
||||
# We prepend it so it takes precedence over the original file
|
||||
INCLUDE_FLAGS=("-I$TEMP_DIR" "${INCLUDE_FLAGS[@]}")
|
||||
|
||||
# Step 1: Generate individual JSON Schema files with JSON field names (camelCase)
|
||||
echo "→ Generating JSON Schema from proto..." >&2
|
||||
if ! protoc "${INCLUDE_FLAGS[@]}" \
|
||||
--jsonschema_out="$TEMP_DIR" \
|
||||
--jsonschema_opt=target=json \
|
||||
"$CLEAN_PROTO_FILE" 2>&1; then
|
||||
echo "Error: protoc generation failed" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Step 2: Bundle all schemas into a single file with cleaned names
|
||||
echo "→ Creating JSON Schema bundle..." >&2
|
||||
|
||||
# Check if any JSON files were generated
|
||||
JSON_FILES=("$TEMP_DIR"/*.json)
|
||||
if [ ! -f "${JSON_FILES[0]}" ]; then
|
||||
echo "Error: No JSON schema files generated" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
jq -s '
|
||||
(if .[0]."$schema" then .[0]."$schema" else "http://json-schema.org/draft-07/schema#" end) as $schema |
|
||||
(reduce .[] as $item ({};
|
||||
if $item.title then
|
||||
. + {($item.title): ($item | del(."$id"))}
|
||||
else
|
||||
.
|
||||
end
|
||||
)) as $defs |
|
||||
{
|
||||
"$schema": $schema,
|
||||
title: "A2A Protocol Schemas",
|
||||
description: "Non-normative JSON Schema bundle extracted from proto definitions.",
|
||||
version: "v1",
|
||||
definitions: $defs
|
||||
}
|
||||
' "$TEMP_DIR"/*.json >"$OUTPUT"
|
||||
|
||||
# Count definitions
|
||||
DEF_COUNT=$(jq '.definitions | length' "$OUTPUT")
|
||||
echo "✓ Generated $OUTPUT with $DEF_COUNT definitions" >&2
|
||||
58
specification/.api-linter.yaml
Normal file
@ -0,0 +1,58 @@
|
||||
# API Linter Configuration
|
||||
# https://linter.aip.dev/
|
||||
|
||||
- included_paths:
|
||||
- "**/*.proto"
|
||||
disabled_rules:
|
||||
- "core::0140::abbreviations"
|
||||
- "core::0191::java-multiple-files"
|
||||
- "core::0191::java-outer-classname"
|
||||
- "core::0191::java-package"
|
||||
- "core::0191::proto-package"
|
||||
- "core::0123::resource-annotation"
|
||||
- "core::0203::optional"
|
||||
- "core::0203::required"
|
||||
- "core::0127::http-annotation"
|
||||
- "core::0131::request-message-name"
|
||||
- "core::0132::response-message-name"
|
||||
- "core::0158::request-required-fields"
|
||||
- "core::0203::input-only"
|
||||
- "core::0203::output-only"
|
||||
- "core::0203::immutable"
|
||||
|
||||
# TODO: Evaluate if the following should be enabled due to breaking changes
|
||||
- "core::0131::method-signature"
|
||||
- "core::0131::http-uri-name"
|
||||
- "core::0127::resource-name-extraction"
|
||||
- "core::0131::request-name-required"
|
||||
- "core::0131::request-required-fields"
|
||||
- "core::0131::response-message-name"
|
||||
- "core::0131::request-unknown-fields"
|
||||
- "core::0132::request-required-fields"
|
||||
- "core::0132::request-unknown-fields"
|
||||
- "core::0132::request-parent-required"
|
||||
- "core::0132::response-unknown-fields"
|
||||
- "core::0133::http-body"
|
||||
- "core::0133::request-required-fields"
|
||||
- "core::0133::request-unknown-fields"
|
||||
- "core::0133::request-parent-required"
|
||||
- "core::0133::request-resource-field"
|
||||
- "core::0133::request-id-field"
|
||||
- "core::0133::http-uri-parent"
|
||||
- "core::0135::http-uri-name"
|
||||
- "core::0135::request-name-required"
|
||||
- "core::0135::method-signature"
|
||||
- "core::0135::request-unknown-fields"
|
||||
- "core::0135::request-required-fields"
|
||||
- "core::0136::http-uri-suffix"
|
||||
- "core::0136::prepositions"
|
||||
- "core::0136::request-message-name"
|
||||
- "core::0136::response-message-name"
|
||||
- "core::0140::uri"
|
||||
- "core::0140::base64"
|
||||
- "core::0140::prepositions"
|
||||
- "core::0142::time-field-names"
|
||||
- "core::0191::file-layout"
|
||||
- "core::0203::field-behavior-required"
|
||||
- "core::0216::state-field-output-only"
|
||||
- "core::0216::nesting"
|
||||
796
specification/a2a.proto
Normal file
@ -0,0 +1,796 @@
|
||||
// Older protoc compilers don't understand edition yet.
|
||||
syntax = "proto3";
|
||||
package lf.a2a.v1;
|
||||
|
||||
import "google/api/annotations.proto";
|
||||
import "google/api/client.proto";
|
||||
import "google/api/field_behavior.proto";
|
||||
import "google/protobuf/empty.proto";
|
||||
import "google/protobuf/struct.proto";
|
||||
import "google/protobuf/timestamp.proto";
|
||||
|
||||
option csharp_namespace = "Lf.A2a.V1";
|
||||
option go_package = "google.golang.org/lf/a2a/v1";
|
||||
option java_multiple_files = true;
|
||||
option java_outer_classname = "A2A";
|
||||
option java_package = "com.google.lf.a2a.v1";
|
||||
|
||||
// Provides operations for interacting with agents using the A2A protocol.
|
||||
service A2AService {
|
||||
// Sends a message to an agent.
|
||||
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {
|
||||
option (google.api.http) = {
|
||||
post: "/message:send"
|
||||
body: "*"
|
||||
additional_bindings: {
|
||||
post: "/{tenant}/message:send"
|
||||
body: "*"
|
||||
}
|
||||
};
|
||||
}
|
||||
// Sends a streaming message to an agent, allowing for real-time interaction and status updates.
|
||||
// Streaming version of `SendMessage`
|
||||
rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse) {
|
||||
option (google.api.http) = {
|
||||
post: "/message:stream"
|
||||
body: "*"
|
||||
additional_bindings: {
|
||||
post: "/{tenant}/message:stream"
|
||||
body: "*"
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Gets the latest state of a task.
|
||||
rpc GetTask(GetTaskRequest) returns (Task) {
|
||||
option (google.api.http) = {
|
||||
get: "/tasks/{id=*}"
|
||||
additional_bindings: {
|
||||
get: "/{tenant}/tasks/{id=*}"
|
||||
}
|
||||
};
|
||||
option (google.api.method_signature) = "id";
|
||||
}
|
||||
// Lists tasks that match the specified filter.
|
||||
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
|
||||
option (google.api.http) = {
|
||||
get: "/tasks"
|
||||
additional_bindings: {
|
||||
get: "/{tenant}/tasks"
|
||||
}
|
||||
};
|
||||
}
|
||||
// Cancels a task in progress.
|
||||
rpc CancelTask(CancelTaskRequest) returns (Task) {
|
||||
option (google.api.http) = {
|
||||
post: "/tasks/{id=*}:cancel"
|
||||
body: "*"
|
||||
additional_bindings: {
|
||||
post: "/{tenant}/tasks/{id=*}:cancel"
|
||||
body: "*"
|
||||
}
|
||||
};
|
||||
}
|
||||
// Subscribes to task updates for tasks not in a terminal state.
|
||||
// Returns `UnsupportedOperationError` if the task is already in a terminal state (completed, failed, canceled, rejected).
|
||||
rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse) {
|
||||
option (google.api.http) = {
|
||||
get: "/tasks/{id=*}:subscribe"
|
||||
additional_bindings: {
|
||||
get: "/{tenant}/tasks/{id=*}:subscribe"
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// (-- api-linter: client-libraries::4232::required-fields=disabled
|
||||
// api-linter: core::0133::method-signature=disabled
|
||||
// api-linter: core::0133::request-message-name=disabled
|
||||
// aip.dev/not-precedent: method_signature preserved for backwards compatibility --)
|
||||
// Creates a push notification config for a task.
|
||||
rpc CreateTaskPushNotificationConfig(TaskPushNotificationConfig) returns (TaskPushNotificationConfig) {
|
||||
option (google.api.http) = {
|
||||
post: "/tasks/{task_id=*}/pushNotificationConfigs"
|
||||
body: "*"
|
||||
additional_bindings: {
|
||||
post: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs"
|
||||
body: "*"
|
||||
}
|
||||
};
|
||||
option (google.api.method_signature) = "task_id,config";
|
||||
}
|
||||
// Gets a push notification config for a task.
|
||||
rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) {
|
||||
option (google.api.http) = {
|
||||
get: "/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
|
||||
additional_bindings: {
|
||||
get: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
|
||||
}
|
||||
};
|
||||
option (google.api.method_signature) = "task_id,id";
|
||||
}
|
||||
// Get a list of push notifications configured for a task.
|
||||
rpc ListTaskPushNotificationConfigs(ListTaskPushNotificationConfigsRequest) returns (ListTaskPushNotificationConfigsResponse) {
|
||||
option (google.api.http) = {
|
||||
get: "/tasks/{task_id=*}/pushNotificationConfigs"
|
||||
additional_bindings: {
|
||||
get: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs"
|
||||
}
|
||||
};
|
||||
option (google.api.method_signature) = "task_id";
|
||||
}
|
||||
// Gets the extended agent card for the authenticated agent.
|
||||
rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard) {
|
||||
option (google.api.http) = {
|
||||
get: "/extendedAgentCard"
|
||||
additional_bindings: {
|
||||
get: "/{tenant}/extendedAgentCard"
|
||||
}
|
||||
};
|
||||
}
|
||||
// Deletes a push notification config for a task.
|
||||
rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (google.protobuf.Empty) {
|
||||
option (google.api.http) = {
|
||||
delete: "/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
|
||||
additional_bindings: {
|
||||
delete: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
|
||||
}
|
||||
};
|
||||
option (google.api.method_signature) = "task_id,id";
|
||||
}
|
||||
}
|
||||
|
||||
// Configuration of a send message request.
|
||||
message SendMessageConfiguration {
|
||||
// A list of media types the client is prepared to accept for response parts.
|
||||
// Agents SHOULD use this to tailor their output.
|
||||
repeated string accepted_output_modes = 1;
|
||||
// Configuration for the agent to send push notifications for task updates.
|
||||
// Task id should be empty when sending this configuration in a `SendMessage` request.
|
||||
TaskPushNotificationConfig task_push_notification_config = 2;
|
||||
// The maximum number of most recent messages from the task's history to retrieve in
|
||||
// the response. An unset value means the client does not impose any limit. A
|
||||
// value of zero is a request to not include any messages. The server MUST NOT
|
||||
// return more messages than the provided value, but MAY apply a lower limit.
|
||||
optional int32 history_length = 3;
|
||||
// If `true`, the operation returns immediately after creating the task,
|
||||
// even if processing is still in progress.
|
||||
// If `false` (default), the operation MUST wait until the task reaches a
|
||||
// terminal (`COMPLETED`, `FAILED`, `CANCELED`, `REJECTED`) or interrupted
|
||||
// (`INPUT_REQUIRED`, `AUTH_REQUIRED`) state before returning.
|
||||
bool return_immediately = 4;
|
||||
}
|
||||
|
||||
// `Task` is the core unit of action for A2A. It has a current status
|
||||
// and when results are created for the task they are stored in the
|
||||
// artifact. If there are multiple turns for a task, these are stored in
|
||||
// history.
|
||||
message Task {
|
||||
// Unique identifier (e.g. UUID) for the task, generated by the server for a
|
||||
// new task.
|
||||
string id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// Unique identifier (e.g. UUID) for the contextual collection of interactions
|
||||
// (tasks and messages).
|
||||
string context_id = 2;
|
||||
// The current status of a `Task`, including `state` and a `message`.
|
||||
TaskStatus status = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
// A set of output artifacts for a `Task`.
|
||||
repeated Artifact artifacts = 4;
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// The history of interactions from a `Task`.
|
||||
repeated Message history = 5;
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// A key/value object to store custom metadata about a task.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
}
|
||||
|
||||
// Defines the possible lifecycle states of a `Task`.
|
||||
enum TaskState {
|
||||
// The task is in an unknown or indeterminate state.
|
||||
TASK_STATE_UNSPECIFIED = 0;
|
||||
// Indicates that a task has been successfully submitted and acknowledged.
|
||||
TASK_STATE_SUBMITTED = 1;
|
||||
// Indicates that a task is actively being processed by the agent.
|
||||
TASK_STATE_WORKING = 2;
|
||||
// Indicates that a task has finished successfully. This is a terminal state.
|
||||
TASK_STATE_COMPLETED = 3;
|
||||
// Indicates that a task has finished with an error. This is a terminal state.
|
||||
TASK_STATE_FAILED = 4;
|
||||
// Indicates that a task was canceled before completion. This is a terminal state.
|
||||
TASK_STATE_CANCELED = 5;
|
||||
// Indicates that the agent requires additional user input to proceed. This is an interrupted state.
|
||||
TASK_STATE_INPUT_REQUIRED = 6;
|
||||
// Indicates that the agent has decided to not perform the task.
|
||||
// This may be done during initial task creation or later once an agent
|
||||
// has determined it can't or won't proceed. This is a terminal state.
|
||||
TASK_STATE_REJECTED = 7;
|
||||
// Indicates that authentication is required to proceed. This is an interrupted state.
|
||||
TASK_STATE_AUTH_REQUIRED = 8;
|
||||
}
|
||||
|
||||
// A container for the status of a task
|
||||
message TaskStatus {
|
||||
// The current state of this task.
|
||||
TaskState state = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// A message associated with the status.
|
||||
Message message = 2;
|
||||
// ISO 8601 Timestamp when the status was recorded.
|
||||
// Example: "2023-10-27T10:00:00Z"
|
||||
google.protobuf.Timestamp timestamp = 3;
|
||||
}
|
||||
|
||||
// `Part` represents a container for a section of communication content.
|
||||
// Parts can be purely textual, some sort of file (image, video, etc) or
|
||||
// a structured data blob (i.e. JSON).
|
||||
message Part {
|
||||
oneof content {
|
||||
// The string content of the `text` part.
|
||||
string text = 1;
|
||||
// The `raw` byte content of a file. In JSON serialization, this is encoded as a base64 string.
|
||||
bytes raw = 2;
|
||||
// A `url` pointing to the file's content.
|
||||
string url = 3;
|
||||
// Arbitrary structured `data` as a JSON value (object, array, string, number, boolean, or null).
|
||||
google.protobuf.Value data = 4;
|
||||
}
|
||||
// Optional. metadata associated with this part.
|
||||
google.protobuf.Struct metadata = 5;
|
||||
// An optional `filename` for the file (e.g., "document.pdf").
|
||||
string filename = 6;
|
||||
// The `media_type` (MIME type) of the part content (e.g., "text/plain", "application/json", "image/png").
|
||||
// This field is available for all part types.
|
||||
string media_type = 7;
|
||||
}
|
||||
|
||||
// Defines the sender of a message in A2A protocol communication.
|
||||
enum Role {
|
||||
// The role is unspecified.
|
||||
ROLE_UNSPECIFIED = 0;
|
||||
// The message is from the client to the server.
|
||||
ROLE_USER = 1;
|
||||
// The message is from the server to the client.
|
||||
ROLE_AGENT = 2;
|
||||
}
|
||||
|
||||
// `Message` is one unit of communication between client and server. It can be
|
||||
// associated with a context and/or a task. For server messages, `context_id` must
|
||||
// be provided, and `task_id` only if a task was created. For client messages, both
|
||||
// fields are optional, with the caveat that if both are provided, they have to
|
||||
// match (the `context_id` has to be the one that is set on the task). If only
|
||||
// `task_id` is provided, the server will infer `context_id` from it.
|
||||
message Message {
|
||||
// The unique identifier (e.g. UUID) of the message. This is created by the message creator.
|
||||
string message_id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// Optional. The context id of the message. If set, the message will be associated with the given context.
|
||||
string context_id = 2;
|
||||
// Optional. The task id of the message. If set, the message will be associated with the given task.
|
||||
string task_id = 3;
|
||||
// Identifies the sender of the message.
|
||||
Role role = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
// Parts is the container of the message content.
|
||||
repeated Part parts = 5 [(google.api.field_behavior) = REQUIRED];
|
||||
// Optional. Any metadata to provide along with the message.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
// The URIs of extensions that are present or contributed to this Message.
|
||||
repeated string extensions = 7;
|
||||
// A list of task IDs that this message references for additional context.
|
||||
repeated string reference_task_ids = 8;
|
||||
}
|
||||
|
||||
// Artifacts represent task outputs.
|
||||
message Artifact {
|
||||
// Unique identifier (e.g. UUID) for the artifact. It must be unique within a task.
|
||||
string artifact_id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// A human readable name for the artifact.
|
||||
string name = 2;
|
||||
// Optional. A human readable description of the artifact.
|
||||
string description = 3;
|
||||
// The content of the artifact. Must contain at least one part.
|
||||
repeated Part parts = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
// Optional. Metadata included with the artifact.
|
||||
google.protobuf.Struct metadata = 5;
|
||||
// The URIs of extensions that are present or contributed to this Artifact.
|
||||
repeated string extensions = 6;
|
||||
}
|
||||
|
||||
// An event sent by the agent to notify the client of a change in a task's status.
|
||||
message TaskStatusUpdateEvent {
|
||||
// The ID of the task that has changed.
|
||||
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The ID of the context that the task belongs to.
|
||||
string context_id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The new status of the task.
|
||||
TaskStatus status = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
// Optional. Metadata associated with the task update.
|
||||
google.protobuf.Struct metadata = 4;
|
||||
}
|
||||
|
||||
// A task delta where an artifact has been generated.
|
||||
message TaskArtifactUpdateEvent {
|
||||
// The ID of the task for this artifact.
|
||||
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The ID of the context that this task belongs to.
|
||||
string context_id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The artifact that was generated or updated.
|
||||
Artifact artifact = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
// If true, the content of this artifact should be appended to a previously
|
||||
// sent artifact with the same ID.
|
||||
bool append = 4;
|
||||
// If true, this is the final chunk of the artifact.
|
||||
bool last_chunk = 5;
|
||||
// Optional. Metadata associated with the artifact update.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
}
|
||||
|
||||
// Defines authentication details, used for push notifications.
|
||||
message AuthenticationInfo {
|
||||
// HTTP Authentication Scheme from the [IANA registry](https://www.iana.org/assignments/http-authschemes/).
|
||||
// Examples: `Bearer`, `Basic`, `Digest`.
|
||||
// Scheme names are case-insensitive per [RFC 9110 Section 11.1](https://www.rfc-editor.org/rfc/rfc9110#section-11.1).
|
||||
string scheme = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// Push Notification credentials. Format depends on the scheme (e.g., token for Bearer).
|
||||
string credentials = 2;
|
||||
}
|
||||
|
||||
// Declares a combination of a target URL, transport and protocol version for interacting with the agent.
|
||||
// This allows agents to expose the same functionality over multiple protocol binding mechanisms.
|
||||
message AgentInterface {
|
||||
// The URL where this interface is available. Must be a valid absolute HTTPS URL in production.
|
||||
// Example: "https://api.example.com/a2a/v1", "https://grpc.example.com/a2a"
|
||||
string url = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The protocol binding supported at this URL. This is an open form string, to be
|
||||
// easily extended for other protocol bindings. The core ones officially
|
||||
// supported are `JSONRPC`, `GRPC` and `HTTP+JSON`.
|
||||
string protocol_binding = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// Tenant ID to be used in the request when calling the agent.
|
||||
string tenant = 3;
|
||||
// The version of the A2A protocol this interface exposes.
|
||||
// Use the latest supported minor version per major version.
|
||||
// Examples: "0.3", "1.0"
|
||||
string protocol_version = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// A self-describing manifest for an agent. It provides essential
|
||||
// metadata including the agent's identity, capabilities, skills, supported
|
||||
// communication methods, and security requirements.
|
||||
// Next ID: 20
|
||||
message AgentCard {
|
||||
// A human readable name for the agent.
|
||||
// Example: "Recipe Agent"
|
||||
string name = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// A human-readable description of the agent, assisting users and other agents
|
||||
// in understanding its purpose.
|
||||
// Example: "Agent that helps users with recipes and cooking."
|
||||
string description = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// Ordered list of supported interfaces. The first entry is preferred.
|
||||
repeated AgentInterface supported_interfaces = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
// The service provider of the agent.
|
||||
AgentProvider provider = 4;
|
||||
// The version of the agent.
|
||||
// Example: "1.0.0"
|
||||
string version = 5 [(google.api.field_behavior) = REQUIRED];
|
||||
// A URL providing additional documentation about the agent.
|
||||
optional string documentation_url = 6;
|
||||
// A2A Capability set supported by the agent.
|
||||
AgentCapabilities capabilities = 7 [(google.api.field_behavior) = REQUIRED];
|
||||
// The security scheme details used for authenticating with this agent.
|
||||
map<string, SecurityScheme> security_schemes = 8;
|
||||
// Security requirements for contacting the agent.
|
||||
repeated SecurityRequirement security_requirements = 9;
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// The set of interaction modes that the agent supports across all skills.
|
||||
// This can be overridden per skill. Defined as media types.
|
||||
repeated string default_input_modes = 10 [(google.api.field_behavior) = REQUIRED];
|
||||
// The media types supported as outputs from this agent.
|
||||
repeated string default_output_modes = 11 [(google.api.field_behavior) = REQUIRED];
|
||||
// Skills represent the abilities of an agent.
|
||||
// It is largely a descriptive concept but represents a more focused set of behaviors that the
|
||||
// agent is likely to succeed at.
|
||||
repeated AgentSkill skills = 12 [(google.api.field_behavior) = REQUIRED];
|
||||
// JSON Web Signatures computed for this `AgentCard`.
|
||||
repeated AgentCardSignature signatures = 13;
|
||||
// Optional. A URL to an icon for the agent.
|
||||
optional string icon_url = 14;
|
||||
}
|
||||
|
||||
// Represents the service provider of an agent.
|
||||
message AgentProvider {
|
||||
// A URL for the agent provider's website or relevant documentation.
|
||||
// Example: "https://ai.google.dev"
|
||||
string url = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The name of the agent provider's organization.
|
||||
// Example: "Google"
|
||||
string organization = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Defines optional capabilities supported by an agent.
|
||||
message AgentCapabilities {
|
||||
// Indicates if the agent supports streaming responses.
|
||||
optional bool streaming = 1;
|
||||
// Indicates if the agent supports sending push notifications for asynchronous task updates.
|
||||
optional bool push_notifications = 2;
|
||||
// A list of protocol extensions supported by the agent.
|
||||
repeated AgentExtension extensions = 3;
|
||||
// Indicates if the agent supports providing an extended agent card when authenticated.
|
||||
optional bool extended_agent_card = 4;
|
||||
}
|
||||
|
||||
// A declaration of a protocol extension supported by an Agent.
|
||||
message AgentExtension {
|
||||
// The unique URI identifying the extension.
|
||||
string uri = 1;
|
||||
// A human-readable description of how this agent uses the extension.
|
||||
string description = 2;
|
||||
// If true, the client must understand and comply with the extension's requirements.
|
||||
bool required = 3;
|
||||
// Optional. Extension-specific configuration parameters.
|
||||
google.protobuf.Struct params = 4;
|
||||
}
|
||||
|
||||
// Represents a distinct capability or function that an agent can perform.
|
||||
message AgentSkill {
|
||||
// A unique identifier for the agent's skill.
|
||||
string id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// A human-readable name for the skill.
|
||||
string name = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// A detailed description of the skill.
|
||||
string description = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
// A set of keywords describing the skill's capabilities.
|
||||
repeated string tags = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
// Example prompts or scenarios that this skill can handle.
|
||||
repeated string examples = 5;
|
||||
// The set of supported input media types for this skill, overriding the agent's defaults.
|
||||
repeated string input_modes = 6;
|
||||
// The set of supported output media types for this skill, overriding the agent's defaults.
|
||||
repeated string output_modes = 7;
|
||||
// Security schemes necessary for this skill.
|
||||
repeated SecurityRequirement security_requirements = 8;
|
||||
}
|
||||
|
||||
// AgentCardSignature represents a JWS signature of an AgentCard.
|
||||
// This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).
|
||||
message AgentCardSignature {
|
||||
// (-- api-linter: core::0140::reserved-words=disabled
|
||||
// aip.dev/not-precedent: Backwards compatibility --)
|
||||
// Required. The protected JWS header for the signature. This is always a
|
||||
// base64url-encoded JSON object.
|
||||
string protected = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// Required. The computed signature, base64url-encoded.
|
||||
string signature = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The unprotected JWS header values.
|
||||
google.protobuf.Struct header = 3;
|
||||
}
|
||||
|
||||
// A container associating a push notification configuration with a specific task.
|
||||
message TaskPushNotificationConfig {
|
||||
// Optional. Tenant ID.
|
||||
string tenant = 1;
|
||||
// The push notification configuration details.
|
||||
// A unique identifier (e.g. UUID) for this push notification configuration.
|
||||
string id = 2;
|
||||
// The ID of the task this configuration is associated with.
|
||||
string task_id = 3;
|
||||
// The URL where the notification should be sent.
|
||||
string url = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
// A token unique for this task or session.
|
||||
string token = 5;
|
||||
// Authentication information required to send the notification.
|
||||
AuthenticationInfo authentication = 6;
|
||||
}
|
||||
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// A list of strings.
|
||||
message StringList {
|
||||
// The individual string values.
|
||||
repeated string list = 1;
|
||||
}
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
|
||||
// Defines the security requirements for an agent.
|
||||
message SecurityRequirement {
|
||||
// A map of security schemes to the required scopes.
|
||||
map<string, StringList> schemes = 1;
|
||||
}
|
||||
|
||||
// Defines a security scheme that can be used to secure an agent's endpoints.
|
||||
// This is a discriminated union type based on the OpenAPI 3.2 Security Scheme Object.
|
||||
// See: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object
|
||||
message SecurityScheme {
|
||||
oneof scheme {
|
||||
// API key-based authentication.
|
||||
APIKeySecurityScheme api_key_security_scheme = 1;
|
||||
// HTTP authentication (Basic, Bearer, etc.).
|
||||
HTTPAuthSecurityScheme http_auth_security_scheme = 2;
|
||||
// OAuth 2.0 authentication.
|
||||
OAuth2SecurityScheme oauth2_security_scheme = 3;
|
||||
// OpenID Connect authentication.
|
||||
OpenIdConnectSecurityScheme open_id_connect_security_scheme = 4;
|
||||
// Mutual TLS authentication.
|
||||
MutualTlsSecurityScheme mtls_security_scheme = 5;
|
||||
}
|
||||
}
|
||||
|
||||
// Defines a security scheme using an API key.
|
||||
message APIKeySecurityScheme {
|
||||
// An optional description for the security scheme.
|
||||
string description = 1;
|
||||
// The location of the API key. Valid values are "query", "header", or "cookie".
|
||||
string location = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The name of the header, query, or cookie parameter to be used.
|
||||
string name = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Defines a security scheme using HTTP authentication.
|
||||
message HTTPAuthSecurityScheme {
|
||||
// An optional description for the security scheme.
|
||||
string description = 1;
|
||||
// The name of the HTTP Authentication scheme to be used in the Authorization header,
|
||||
// as defined in RFC7235 (e.g., "Bearer").
|
||||
// This value should be registered in the IANA Authentication Scheme registry.
|
||||
string scheme = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// A hint to the client to identify how the bearer token is formatted (e.g., "JWT").
|
||||
// Primarily for documentation purposes.
|
||||
string bearer_format = 3;
|
||||
}
|
||||
|
||||
// Defines a security scheme using OAuth 2.0.
|
||||
message OAuth2SecurityScheme {
|
||||
// An optional description for the security scheme.
|
||||
string description = 1;
|
||||
// An object containing configuration information for the supported OAuth 2.0 flows.
|
||||
OAuthFlows flows = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// URL to the OAuth2 authorization server metadata [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
|
||||
// TLS is required.
|
||||
string oauth2_metadata_url = 3;
|
||||
}
|
||||
|
||||
// Defines a security scheme using OpenID Connect.
|
||||
message OpenIdConnectSecurityScheme {
|
||||
// An optional description for the security scheme.
|
||||
string description = 1;
|
||||
// The [OpenID Connect Discovery URL](https://openid.net/specs/openid-connect-discovery-1_0.html) for the OIDC provider's metadata.
|
||||
string open_id_connect_url = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Defines a security scheme using mTLS authentication.
|
||||
message MutualTlsSecurityScheme {
|
||||
// An optional description for the security scheme.
|
||||
string description = 1;
|
||||
}
|
||||
|
||||
// Defines the configuration for the supported OAuth 2.0 flows.
|
||||
message OAuthFlows {
|
||||
oneof flow {
|
||||
// Configuration for the OAuth Authorization Code flow.
|
||||
AuthorizationCodeOAuthFlow authorization_code = 1;
|
||||
// Configuration for the OAuth Client Credentials flow.
|
||||
ClientCredentialsOAuthFlow client_credentials = 2;
|
||||
// Deprecated: Use Authorization Code + PKCE instead.
|
||||
ImplicitOAuthFlow implicit = 3 [deprecated = true];
|
||||
// Deprecated: Use Authorization Code + PKCE or Device Code.
|
||||
PasswordOAuthFlow password = 4 [deprecated = true];
|
||||
// Configuration for the OAuth Device Code flow.
|
||||
DeviceCodeOAuthFlow device_code = 5;
|
||||
}
|
||||
}
|
||||
|
||||
// Defines configuration details for the OAuth 2.0 Authorization Code flow.
|
||||
message AuthorizationCodeOAuthFlow {
|
||||
// The authorization URL to be used for this flow.
|
||||
string authorization_url = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The token URL to be used for this flow.
|
||||
string token_url = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The URL to be used for obtaining refresh tokens.
|
||||
string refresh_url = 3;
|
||||
// The available scopes for the OAuth2 security scheme.
|
||||
map<string, string> scopes = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
// Indicates if PKCE (RFC 7636) is required for this flow.
|
||||
// PKCE should always be used for public clients and is recommended for all clients.
|
||||
bool pkce_required = 5;
|
||||
}
|
||||
|
||||
// Defines configuration details for the OAuth 2.0 Client Credentials flow.
|
||||
message ClientCredentialsOAuthFlow {
|
||||
// The token URL to be used for this flow.
|
||||
string token_url = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The URL to be used for obtaining refresh tokens.
|
||||
string refresh_url = 2;
|
||||
// The available scopes for the OAuth2 security scheme.
|
||||
map<string, string> scopes = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Deprecated: Use Authorization Code + PKCE instead.
|
||||
message ImplicitOAuthFlow {
|
||||
// The authorization URL to be used for this flow. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS
|
||||
string authorization_url = 1;
|
||||
// The URL to be used for obtaining refresh tokens. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS.
|
||||
string refresh_url = 2;
|
||||
// The available scopes for the OAuth2 security scheme. A map between the
|
||||
// scope name and a short description for it. The map MAY be empty.
|
||||
map<string, string> scopes = 3;
|
||||
}
|
||||
|
||||
// Deprecated: Use Authorization Code + PKCE or Device Code.
|
||||
message PasswordOAuthFlow {
|
||||
// The token URL to be used for this flow. This MUST be in the form of a URL.
|
||||
// The OAuth2 standard requires the use of TLS.
|
||||
string token_url = 1;
|
||||
// The URL to be used for obtaining refresh tokens. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS.
|
||||
string refresh_url = 2;
|
||||
// The available scopes for the OAuth2 security scheme. A map between the
|
||||
// scope name and a short description for it. The map MAY be empty.
|
||||
map<string, string> scopes = 3;
|
||||
}
|
||||
|
||||
// Defines configuration details for the OAuth 2.0 Device Code flow (RFC 8628).
|
||||
// This flow is designed for input-constrained devices such as IoT devices,
|
||||
// and CLI tools where the user authenticates on a separate device.
|
||||
message DeviceCodeOAuthFlow {
|
||||
// The device authorization endpoint URL.
|
||||
string device_authorization_url = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The token URL to be used for this flow.
|
||||
string token_url = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The URL to be used for obtaining refresh tokens.
|
||||
string refresh_url = 3;
|
||||
// The available scopes for the OAuth2 security scheme.
|
||||
map<string, string> scopes = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Represents a request for the `SendMessage` method.
|
||||
message SendMessageRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// The message to send to the agent.
|
||||
Message message = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// Configuration for the send request.
|
||||
SendMessageConfiguration configuration = 3;
|
||||
// A flexible key-value map for passing additional context or parameters.
|
||||
google.protobuf.Struct metadata = 4;
|
||||
}
|
||||
|
||||
// Represents a request for the `GetTask` method.
|
||||
message GetTaskRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// The resource ID of the task to retrieve.
|
||||
string id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The maximum number of most recent messages from the task's history to retrieve. An
|
||||
// unset value means the client does not impose any limit. A value of zero is
|
||||
// a request to not include any messages. The server MUST NOT return more
|
||||
// messages than the provided value, but MAY apply a lower limit.
|
||||
optional int32 history_length = 3;
|
||||
}
|
||||
|
||||
// Parameters for listing tasks with optional filtering criteria.
|
||||
message ListTasksRequest {
|
||||
// Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// Filter tasks by context ID to get tasks from a specific conversation or session.
|
||||
string context_id = 2;
|
||||
// Filter tasks by their current status state.
|
||||
TaskState status = 3;
|
||||
// The maximum number of tasks to return. The service may return fewer than this value.
|
||||
// If unspecified, at most 50 tasks will be returned.
|
||||
// The minimum value is 1.
|
||||
// The maximum value is 100.
|
||||
optional int32 page_size = 4;
|
||||
// A page token, received from a previous `ListTasks` call.
|
||||
// `ListTasksResponse.next_page_token`.
|
||||
// Provide this to retrieve the subsequent page.
|
||||
string page_token = 5;
|
||||
// The maximum number of messages to include in each task's history.
|
||||
optional int32 history_length = 6;
|
||||
// Filter tasks which have a status updated after the provided timestamp in ISO 8601 format (e.g., "2023-10-27T10:00:00Z").
|
||||
// Only tasks with a status timestamp time greater than or equal to this value will be returned.
|
||||
google.protobuf.Timestamp status_timestamp_after = 7;
|
||||
// Whether to include artifacts in the returned tasks.
|
||||
// Defaults to false to reduce payload size.
|
||||
optional bool include_artifacts = 8;
|
||||
}
|
||||
|
||||
// Result object for `ListTasks` method containing an array of tasks and pagination information.
|
||||
message ListTasksResponse {
|
||||
// Array of tasks matching the specified criteria.
|
||||
repeated Task tasks = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// A token to retrieve the next page of results, or empty if there are no more results in the list.
|
||||
string next_page_token = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The page size used for this response.
|
||||
int32 page_size = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
// Total number of tasks available (before pagination).
|
||||
int32 total_size = 4 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Represents a request for the `CancelTask` method.
|
||||
message CancelTaskRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// The resource ID of the task to cancel.
|
||||
string id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// A flexible key-value map for passing additional context or parameters.
|
||||
google.protobuf.Struct metadata = 3;
|
||||
}
|
||||
|
||||
// Represents a request for the `GetTaskPushNotificationConfig` method.
|
||||
message GetTaskPushNotificationConfigRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// The parent task resource ID.
|
||||
string task_id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The resource ID of the configuration to retrieve.
|
||||
string id = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Represents a request for the `DeleteTaskPushNotificationConfig` method.
|
||||
message DeleteTaskPushNotificationConfigRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// The parent task resource ID.
|
||||
string task_id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The resource ID of the configuration to delete.
|
||||
string id = 3 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Represents a request for the `SubscribeToTask` method.
|
||||
message SubscribeToTaskRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
// The resource ID of the task to subscribe to.
|
||||
string id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
|
||||
// Represents a request for the `ListTaskPushNotificationConfigs` method.
|
||||
message ListTaskPushNotificationConfigsRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 4;
|
||||
// The parent task resource ID.
|
||||
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
|
||||
// The maximum number of configurations to return.
|
||||
int32 page_size = 2;
|
||||
|
||||
// A page token received from a previous `ListTaskPushNotificationConfigsRequest` call.
|
||||
string page_token = 3;
|
||||
}
|
||||
|
||||
// Represents a request for the `GetExtendedAgentCard` method.
|
||||
message GetExtendedAgentCardRequest {
|
||||
// Optional. Tenant ID, provided as a path parameter.
|
||||
string tenant = 1;
|
||||
}
|
||||
|
||||
// Represents the response for the `SendMessage` method.
|
||||
message SendMessageResponse {
|
||||
// The payload of the response.
|
||||
oneof payload {
|
||||
// The task created or updated by the message.
|
||||
Task task = 1;
|
||||
// A message from the agent.
|
||||
Message message = 2;
|
||||
}
|
||||
}
|
||||
|
||||
// A wrapper object used in streaming operations to encapsulate different types of response data.
|
||||
message StreamResponse {
|
||||
// The payload of the stream response.
|
||||
oneof payload {
|
||||
// A Task object containing the current state of the task.
|
||||
Task task = 1;
|
||||
// A Message object containing a message from the agent.
|
||||
Message message = 2;
|
||||
// An event indicating a task status update.
|
||||
TaskStatusUpdateEvent status_update = 3;
|
||||
// An event indicating a task artifact update.
|
||||
TaskArtifactUpdateEvent artifact_update = 4;
|
||||
}
|
||||
}
|
||||
|
||||
// Represents a successful response for the `ListTaskPushNotificationConfigs`
|
||||
// method.
|
||||
message ListTaskPushNotificationConfigsResponse {
|
||||
// The list of push notification configurations.
|
||||
repeated TaskPushNotificationConfig configs = 1;
|
||||
// A token to retrieve the next page of results, or empty if there are no more results in the list.
|
||||
string next_page_token = 2;
|
||||
}
|
||||
6
specification/buf.lock
Normal file
@ -0,0 +1,6 @@
|
||||
# Generated by buf. DO NOT EDIT.
|
||||
version: v2
|
||||
deps:
|
||||
- name: buf.build/googleapis/googleapis
|
||||
commit: 004180b77378443887d3b55cabc00384
|
||||
digest: b5:e8f475fe3330f31f5fd86ac689093bcd274e19611a09db91f41d637cb9197881ce89882b94d13a58738e53c91c6e4bae7dc1feba85f590164c975a89e25115dc
|
||||
@ -7,6 +7,7 @@ lint:
|
||||
# Indicates that all the default rules should be used.
|
||||
# See https://buf.build/docs/lint/rules for more details.
|
||||
- STANDARD
|
||||
- COMMENTS
|
||||
except:
|
||||
- PACKAGE_DIRECTORY_MATCH
|
||||
- RPC_REQUEST_RESPONSE_UNIQUE
|
||||
@ -1,69 +0,0 @@
|
||||
# Protocol Buffer Definitions
|
||||
|
||||
This folder contains the a2a specification in Protocol Buffer (protobuf) format
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you can validate or generate code from these protobuf definitions, you need to install `buf`.
|
||||
|
||||
Follow the installation instructions on the official `buf` GitHub repository:
|
||||
<https://github.com/bufbuild/buf/>
|
||||
|
||||
## Validation
|
||||
|
||||
To validate your protobuf definitions and ensure they adhere to linting rules, run the following command from the root of this folder:
|
||||
|
||||
```sh
|
||||
buf lint
|
||||
```
|
||||
|
||||
## Code Generation
|
||||
|
||||
`buf.gen.yaml` is configured to generate code for the following languages:
|
||||
|
||||
- Go
|
||||
- Java
|
||||
- Python
|
||||
- TypeScript
|
||||
|
||||
To generate code for all configured languages, run the following command from the root of this folder:
|
||||
|
||||
```sh
|
||||
buf generate
|
||||
```
|
||||
|
||||
`buf.gen.yaml` uses remote plugins for generation, if you wish to use local plugins change remote to local
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
- local: protoc-gen-java
|
||||
out: src/java
|
||||
- local: protoc-gen-grpc-java
|
||||
out: src/java
|
||||
```
|
||||
|
||||
Alternatively use `protoc` commandline for code generation
|
||||
|
||||
```bash
|
||||
protoc --java_out=./src/java --grpc-java_out=./src/java -I. a2a.proto
|
||||
```
|
||||
|
||||
### Generating for Specific Languages
|
||||
|
||||
If you do not need to generate code for all the languages listed above, you can comment out the unwanted language sections in your `buf.gen.yaml` file.
|
||||
|
||||
For example, if you only want to generate Java exclude the rest, your `buf.gen.yaml` might look something like this (ensure you adapt this to your actual `buf.gen.yaml` structure):
|
||||
|
||||
```yaml
|
||||
# buf.gen.yaml
|
||||
version: v2
|
||||
plugins:
|
||||
# - plugin: buf.build/protocolbuffers/go
|
||||
# out: src/go
|
||||
# - plugin: buf.build/protocolbuffers/python
|
||||
# out: src/python
|
||||
- plugin: buf.build/protocolbuffers/java
|
||||
out: src/java
|
||||
# - plugin: buf.build/grpc/typescript
|
||||
# out: src/ts
|
||||
```
|
||||
@ -1,868 +0,0 @@
|
||||
// Older protoc compilers don't understand edition yet.
|
||||
syntax = "proto3";
|
||||
package a2a.v1;
|
||||
|
||||
import "google/api/annotations.proto";
|
||||
import "google/api/client.proto";
|
||||
import "google/api/field_behavior.proto";
|
||||
import "google/protobuf/empty.proto";
|
||||
import "google/protobuf/struct.proto";
|
||||
import "google/protobuf/timestamp.proto";
|
||||
|
||||
option csharp_namespace = "A2a.V1";
|
||||
option go_package = "google.golang.org/a2a/v1";
|
||||
option java_multiple_files = true;
|
||||
option java_outer_classname = "A2A";
|
||||
option java_package = "com.google.a2a.v1";
|
||||
|
||||
// A2AService defines the gRPC version of the A2A protocol. This has a slightly
|
||||
// different shape than the JSONRPC version to better conform to AIP-127,
|
||||
// where appropriate. The nouns are AgentCard, Message, Task and
|
||||
// TaskPushNotificationConfig.
|
||||
// - Messages are not a standard resource so there is no get/delete/update/list
|
||||
// interface, only a send and stream custom methods.
|
||||
// - Tasks have a get interface and custom cancel and subscribe methods.
|
||||
// - TaskPushNotificationConfig are a resource whose parent is a task.
|
||||
// They have get, list and create methods.
|
||||
// - AgentCard is a static resource with only a get method.
|
||||
service A2AService {
|
||||
// Send a message to the agent. This is a blocking call that will return the
|
||||
// task once it is completed, or a LRO if requested.
|
||||
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {
|
||||
option (google.api.http) = {
|
||||
post: "/v1/message:send"
|
||||
body: "*"
|
||||
};
|
||||
}
|
||||
// SendStreamingMessage is a streaming call that will return a stream of
|
||||
// task update events until the Task is in an interrupted or terminal state.
|
||||
rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse) {
|
||||
option (google.api.http) = {
|
||||
post: "/v1/message:stream"
|
||||
body: "*"
|
||||
};
|
||||
}
|
||||
|
||||
// Get the current state of a task from the agent.
|
||||
rpc GetTask(GetTaskRequest) returns (Task) {
|
||||
option (google.api.http) = {
|
||||
get: "/v1/{name=tasks/*}"
|
||||
};
|
||||
option (google.api.method_signature) = "name";
|
||||
}
|
||||
// List tasks with optional filtering and pagination.
|
||||
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
|
||||
option (google.api.http) = {
|
||||
get: "/v1/tasks"
|
||||
};
|
||||
}
|
||||
// Cancel a task from the agent. If supported one should expect no
|
||||
// more task updates for the task.
|
||||
rpc CancelTask(CancelTaskRequest) returns (Task) {
|
||||
option (google.api.http) = {
|
||||
post: "/v1/{name=tasks/*}:cancel"
|
||||
body: "*"
|
||||
};
|
||||
}
|
||||
// TaskSubscription is a streaming call that will return a stream of task
|
||||
// update events. This attaches the stream to an existing in process task.
|
||||
// If the task is complete the stream will return the completed task (like
|
||||
// GetTask) and close the stream.
|
||||
rpc TaskSubscription(TaskSubscriptionRequest)
|
||||
returns (stream StreamResponse) {
|
||||
option (google.api.http) = {
|
||||
get: "/v1/{name=tasks/*}:subscribe"
|
||||
};
|
||||
}
|
||||
|
||||
// Set a push notification config for a task.
|
||||
rpc CreateTaskPushNotificationConfig(CreateTaskPushNotificationConfigRequest)
|
||||
returns (TaskPushNotificationConfig) {
|
||||
option (google.api.http) = {
|
||||
post: "/v1/{parent=tasks/*/pushNotificationConfigs}"
|
||||
body: "config"
|
||||
};
|
||||
option (google.api.method_signature) = "parent,config";
|
||||
}
|
||||
// Get a push notification config for a task.
|
||||
rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest)
|
||||
returns (TaskPushNotificationConfig) {
|
||||
option (google.api.http) = {
|
||||
get: "/v1/{name=tasks/*/pushNotificationConfigs/*}"
|
||||
};
|
||||
option (google.api.method_signature) = "name";
|
||||
}
|
||||
// Get a list of push notifications configured for a task.
|
||||
rpc ListTaskPushNotificationConfig(ListTaskPushNotificationConfigRequest)
|
||||
returns (ListTaskPushNotificationConfigResponse) {
|
||||
option (google.api.http) = {
|
||||
get: "/v1/{parent=tasks/*}/pushNotificationConfigs"
|
||||
};
|
||||
option (google.api.method_signature) = "parent";
|
||||
}
|
||||
// GetAgentCard returns the agent card for the agent.
|
||||
rpc GetAgentCard(GetAgentCardRequest) returns (AgentCard) {
|
||||
option (google.api.http) = {
|
||||
get: "/v1/card"
|
||||
};
|
||||
}
|
||||
// Delete a push notification config for a task.
|
||||
rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest)
|
||||
returns (google.protobuf.Empty) {
|
||||
option (google.api.http) = {
|
||||
delete: "/v1/{name=tasks/*/pushNotificationConfigs/*}"
|
||||
};
|
||||
option (google.api.method_signature) = "name";
|
||||
}
|
||||
}
|
||||
|
||||
///////// Data Model ////////////
|
||||
|
||||
// --8<-- [start:MessageSendConfiguration]
|
||||
// Configuration of a send message request.
|
||||
message SendMessageConfiguration {
|
||||
// The output modes that the agent is expected to respond with.
|
||||
repeated string accepted_output_modes = 1;
|
||||
// A configuration of a webhook that can be used to receive updates
|
||||
PushNotificationConfig push_notification = 2;
|
||||
// The maximum number of messages to include in the history. if 0, the
|
||||
// history will be unlimited.
|
||||
int32 history_length = 3;
|
||||
// If true, the message will be blocking until the task is completed. If
|
||||
// false, the message will be non-blocking and the task will be returned
|
||||
// immediately. It is the caller's responsibility to check for any task
|
||||
// updates.
|
||||
bool blocking = 4;
|
||||
}
|
||||
// --8<-- [end:MessageSendConfiguration]
|
||||
|
||||
// --8<-- [start:Task]
|
||||
// Task is the core unit of action for A2A. It has a current status
|
||||
// and when results are created for the task they are stored in the
|
||||
// artifact. If there are multiple turns for a task, these are stored in
|
||||
// history.
|
||||
message Task {
|
||||
// Unique identifier (e.g. UUID) for the task, generated by the server for a
|
||||
// new task.
|
||||
string id = 1;
|
||||
// Unique identifier (e.g. UUID) for the contextual collection of interactions
|
||||
// (tasks and messages). Created by the A2A server.
|
||||
string context_id = 2;
|
||||
// The current status of a Task, including state and a message.
|
||||
TaskStatus status = 3;
|
||||
// A set of output artifacts for a Task.
|
||||
repeated Artifact artifacts = 4;
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// The history of interactions from a task.
|
||||
repeated Message history = 5;
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// A key/value object to store custom metadata about a task.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
}
|
||||
// --8<-- [end:Task]
|
||||
|
||||
// --8<-- [start:TaskState]
|
||||
// The set of states a Task can be in.
|
||||
enum TaskState {
|
||||
TASK_STATE_UNSPECIFIED = 0;
|
||||
// Represents the status that acknowledges a task is created
|
||||
TASK_STATE_SUBMITTED = 1;
|
||||
// Represents the status that a task is actively being processed
|
||||
TASK_STATE_WORKING = 2;
|
||||
// Represents the status a task is finished. This is a terminal state
|
||||
TASK_STATE_COMPLETED = 3;
|
||||
// Represents the status a task is done but failed. This is a terminal state
|
||||
TASK_STATE_FAILED = 4;
|
||||
// Represents the status a task was cancelled before it finished.
|
||||
// This is a terminal state.
|
||||
TASK_STATE_CANCELLED = 5;
|
||||
// Represents the status that the task requires information to complete.
|
||||
// This is an interrupted state.
|
||||
TASK_STATE_INPUT_REQUIRED = 6;
|
||||
// Represents the status that the agent has decided to not perform the task.
|
||||
// This may be done during initial task creation or later once an agent
|
||||
// has determined it can't or won't proceed. This is a terminal state.
|
||||
TASK_STATE_REJECTED = 7;
|
||||
// Represents the state that some authentication is needed from the upstream
|
||||
// client. Authentication is expected to come out-of-band thus this is not
|
||||
// an interrupted or terminal state.
|
||||
TASK_STATE_AUTH_REQUIRED = 8;
|
||||
}
|
||||
// --8<-- [end:TaskState]
|
||||
|
||||
// --8<-- [start:TaskStatus]
|
||||
// A container for the status of a task
|
||||
message TaskStatus {
|
||||
// The current state of this task
|
||||
TaskState state = 1;
|
||||
// A message associated with the status.
|
||||
Message update = 2 [json_name = "message"];
|
||||
// Timestamp when the status was recorded.
|
||||
// Example: "2023-10-27T10:00:00Z"
|
||||
google.protobuf.Timestamp timestamp = 3;
|
||||
}
|
||||
// --8<-- [end:TaskStatus]
|
||||
|
||||
// --8<-- [start:Part]
|
||||
// Part represents a container for a section of communication content.
|
||||
// Parts can be purely textual, some sort of file (image, video, etc) or
|
||||
// a structured data blob (i.e. JSON).
|
||||
message Part {
|
||||
oneof part {
|
||||
string text = 1;
|
||||
FilePart file = 2;
|
||||
DataPart data = 3;
|
||||
}
|
||||
// Optional metadata associated with this part.
|
||||
google.protobuf.Struct metadata = 4;
|
||||
}
|
||||
// --8<-- [end:Part]
|
||||
|
||||
// --8<-- [start:FilePart]
|
||||
// FilePart represents the different ways files can be provided. If files are
|
||||
// small, directly feeding the bytes is supported via file_with_bytes. If the
|
||||
// file is large, the agent should read the content as appropriate directly
|
||||
// from the file_with_uri source.
|
||||
message FilePart {
|
||||
oneof file {
|
||||
string file_with_uri = 1;
|
||||
bytes file_with_bytes = 2;
|
||||
}
|
||||
string mime_type = 3;
|
||||
string name = 4;
|
||||
}
|
||||
// --8<-- [end:FilePart]
|
||||
|
||||
// --8<-- [start:DataPart]
|
||||
// DataPart represents a structured blob. This is most commonly a JSON payload.
|
||||
message DataPart {
|
||||
google.protobuf.Struct data = 1;
|
||||
}
|
||||
// --8<-- [end:DataPart]
|
||||
|
||||
enum Role {
|
||||
ROLE_UNSPECIFIED = 0;
|
||||
// USER role refers to communication from the client to the server.
|
||||
ROLE_USER = 1;
|
||||
// AGENT role refers to communication from the server to the client.
|
||||
ROLE_AGENT = 2;
|
||||
}
|
||||
|
||||
// --8<-- [start:Message]
|
||||
// Message is one unit of communication between client and server. It is
|
||||
// associated with a context and optionally a task. Since the server is
|
||||
// responsible for the context definition, it must always provide a context_id
|
||||
// in its messages. The client can optionally provide the context_id if it
|
||||
// knows the context to associate the message to. Similarly for task_id,
|
||||
// except the server decides if a task is created and whether to include the
|
||||
// task_id.
|
||||
message Message {
|
||||
// The unique identifier (e.g. UUID)of the message. This is required and
|
||||
// created by the message creator.
|
||||
string message_id = 1;
|
||||
// The context id of the message. This is optional and if set, the message
|
||||
// will be associated with the given context.
|
||||
string context_id = 2;
|
||||
// The task id of the message. This is optional and if set, the message
|
||||
// will be associated with the given task.
|
||||
string task_id = 3;
|
||||
// A role for the message.
|
||||
Role role = 4;
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// Parts is the container of the message content.
|
||||
repeated Part parts = 5;
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// Any optional metadata to provide along with the message.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
// The URIs of extensions that are present or contributed to this Message.
|
||||
repeated string extensions = 7;
|
||||
// A list of task IDs that this message references for additional context.
|
||||
repeated string reference_task_ids = 8;
|
||||
}
|
||||
// --8<-- [end:Message]
|
||||
|
||||
// --8<-- [start:Artifact]
|
||||
// Artifacts are the container for task completed results. These are similar
|
||||
// to Messages but are intended to be the product of a task, as opposed to
|
||||
// point-to-point communication.
|
||||
message Artifact {
|
||||
// Unique identifier (e.g. UUID) for the artifact. It must be at least unique
|
||||
// within a task.
|
||||
string artifact_id = 1;
|
||||
// A human readable name for the artifact.
|
||||
string name = 3;
|
||||
// A human readable description of the artifact, optional.
|
||||
string description = 4;
|
||||
// The content of the artifact.
|
||||
repeated Part parts = 5;
|
||||
// Optional metadata included with the artifact.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
// The URIs of extensions that are present or contributed to this Artifact.
|
||||
repeated string extensions = 7;
|
||||
}
|
||||
// --8<-- [end:Artifact]
|
||||
|
||||
// --8<-- [start:TaskStatusUpdateEvent]
|
||||
// TaskStatusUpdateEvent is a delta even on a task indicating that a task
|
||||
// has changed.
|
||||
message TaskStatusUpdateEvent {
|
||||
// The id of the task that is changed
|
||||
string task_id = 1;
|
||||
// The id of the context that the task belongs to
|
||||
string context_id = 2;
|
||||
// The new status of the task.
|
||||
TaskStatus status = 3;
|
||||
// Whether this is the last status update expected for this task.
|
||||
bool final = 4;
|
||||
// Optional metadata to associate with the task update.
|
||||
google.protobuf.Struct metadata = 5;
|
||||
}
|
||||
// --8<-- [end:TaskStatusUpdateEvent]
|
||||
|
||||
// --8<-- [start:TaskArtifactUpdateEvent]
|
||||
// TaskArtifactUpdateEvent represents a task delta where an artifact has
|
||||
// been generated.
|
||||
message TaskArtifactUpdateEvent {
|
||||
// The id of the task for this artifact
|
||||
string task_id = 1;
|
||||
// The id of the context that this task belongs too
|
||||
string context_id = 2;
|
||||
// The artifact itself
|
||||
Artifact artifact = 3;
|
||||
// Whether this should be appended to a prior one produced
|
||||
bool append = 4;
|
||||
// Whether this represents the last part of an artifact
|
||||
bool last_chunk = 5;
|
||||
// Optional metadata associated with the artifact update.
|
||||
google.protobuf.Struct metadata = 6;
|
||||
}
|
||||
// --8<-- [end:TaskArtifactUpdateEvent]
|
||||
|
||||
// --8<-- [start:PushNotificationConfig]
|
||||
// Configuration for setting up push notifications for task updates.
|
||||
message PushNotificationConfig {
|
||||
// A unique identifier (e.g. UUID) for this push notification.
|
||||
string id = 1;
|
||||
// Url to send the notification too
|
||||
string url = 2;
|
||||
// Token unique for this task/session
|
||||
string token = 3;
|
||||
// Information about the authentication to sent with the notification
|
||||
AuthenticationInfo authentication = 4;
|
||||
}
|
||||
// --8<-- [end:PushNotificationConfig]
|
||||
|
||||
// --8<-- [start:PushNotificationAuthenticationInfo]
|
||||
// Defines authentication details, used for push notifications.
|
||||
message AuthenticationInfo {
|
||||
// Supported authentication schemes - e.g. Basic, Bearer, etc
|
||||
repeated string schemes = 1;
|
||||
// Optional credentials
|
||||
string credentials = 2;
|
||||
}
|
||||
// --8<-- [end:PushNotificationAuthenticationInfo]
|
||||
|
||||
// --8<-- [start:AgentInterface]
|
||||
// Defines additional transport information for the agent.
|
||||
message AgentInterface {
|
||||
// The url this interface is found at.
|
||||
string url = 1;
|
||||
// The transport supported this url. This is an open form string, to be
|
||||
// easily extended for many transport protocols. The core ones officially
|
||||
// supported are JSONRPC, GRPC and HTTP+JSON.
|
||||
string transport = 2;
|
||||
}
|
||||
// --8<-- [end:AgentInterface]
|
||||
|
||||
// --8<-- [start:AgentCard]
|
||||
// AgentCard conveys key information:
|
||||
// - Overall details (version, name, description, uses)
|
||||
// - Skills; a set of actions/solutions the agent can perform
|
||||
// - Default modalities/content types supported by the agent.
|
||||
// - Authentication requirements
|
||||
// Next ID: 19
|
||||
message AgentCard {
|
||||
// The version of the A2A protocol this agent supports.
|
||||
string protocol_version = 16;
|
||||
// A human readable name for the agent.
|
||||
// Example: "Recipe Agent"
|
||||
string name = 1;
|
||||
// A description of the agent's domain of action/solution space.
|
||||
// Example: "Agent that helps users with recipes and cooking."
|
||||
string description = 2;
|
||||
// A URL to the address the agent is hosted at. This represents the
|
||||
// preferred endpoint as declared by the agent.
|
||||
string url = 3;
|
||||
// The transport of the preferred endpoint. If empty, defaults to JSONRPC.
|
||||
string preferred_transport = 14;
|
||||
// Announcement of additional supported transports. Client can use any of
|
||||
// the supported transports.
|
||||
repeated AgentInterface additional_interfaces = 15;
|
||||
// The service provider of the agent.
|
||||
AgentProvider provider = 4;
|
||||
// The version of the agent.
|
||||
// Example: "1.0.0"
|
||||
string version = 5;
|
||||
// A url to provide additional documentation about the agent.
|
||||
string documentation_url = 6;
|
||||
// A2A Capability set supported by the agent.
|
||||
AgentCapabilities capabilities = 7;
|
||||
// The security scheme details used for authenticating with this agent.
|
||||
map<string, SecurityScheme> security_schemes = 8;
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// Security requirements for contacting the agent.
|
||||
// This list can be seen as an OR of ANDs. Each object in the list describes
|
||||
// one possible set of security requirements that must be present on a
|
||||
// request. This allows specifying, for example, "callers must either use
|
||||
// OAuth OR an API Key AND mTLS."
|
||||
// Example:
|
||||
// security {
|
||||
// schemes { key: "oauth" value { list: ["read"] } }
|
||||
// }
|
||||
// security {
|
||||
// schemes { key: "api-key" }
|
||||
// schemes { key: "mtls" }
|
||||
// }
|
||||
repeated Security security = 9;
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// The set of interaction modes that the agent supports across all skills.
|
||||
// This can be overridden per skill. Defined as mime types.
|
||||
repeated string default_input_modes = 10;
|
||||
// The mime types supported as outputs from this agent.
|
||||
repeated string default_output_modes = 11;
|
||||
// Skills represent a unit of ability an agent can perform. This may
|
||||
// somewhat abstract but represents a more focused set of actions that the
|
||||
// agent is highly likely to succeed at.
|
||||
repeated AgentSkill skills = 12;
|
||||
// Whether the agent supports providing an extended agent card when
|
||||
// the user is authenticated, i.e. is the card from .well-known
|
||||
// different than the card from GetAgentCard.
|
||||
bool supports_authenticated_extended_card = 13;
|
||||
// JSON Web Signatures computed for this AgentCard.
|
||||
repeated AgentCardSignature signatures = 17;
|
||||
// An optional URL to an icon for the agent.
|
||||
string icon_url = 18;
|
||||
}
|
||||
// --8<-- [end:AgentCard]
|
||||
|
||||
// --8<-- [start:AgentProvider]
|
||||
// Represents information about the service provider of an agent.
|
||||
message AgentProvider {
|
||||
// The providers reference url
|
||||
// Example: "https://ai.google.dev"
|
||||
string url = 1;
|
||||
// The providers organization name
|
||||
// Example: "Google"
|
||||
string organization = 2;
|
||||
}
|
||||
// --8<-- [end:AgentProvider]
|
||||
|
||||
// --8<-- [start:AgentCapabilities]
|
||||
// Defines the A2A feature set supported by the agent
|
||||
message AgentCapabilities {
|
||||
// If the agent will support streaming responses
|
||||
bool streaming = 1;
|
||||
// If the agent can send push notifications to the clients webhook
|
||||
bool push_notifications = 2;
|
||||
// Extensions supported by this agent.
|
||||
repeated AgentExtension extensions = 3;
|
||||
// If the agent provides a history of state transitions for a task.
|
||||
bool state_transition_history = 4;
|
||||
}
|
||||
// --8<-- [end:AgentCapabilities]
|
||||
|
||||
// --8<-- [start:AgentExtension]
|
||||
// A declaration of an extension supported by an Agent.
|
||||
message AgentExtension {
|
||||
// The URI of the extension.
|
||||
// Example: "https://developers.google.com/identity/protocols/oauth2"
|
||||
string uri = 1;
|
||||
// A description of how this agent uses this extension.
|
||||
// Example: "Google OAuth 2.0 authentication"
|
||||
string description = 2;
|
||||
// Whether the client must follow specific requirements of the extension.
|
||||
// Example: false
|
||||
bool required = 3;
|
||||
// Optional configuration for the extension.
|
||||
google.protobuf.Struct params = 4;
|
||||
}
|
||||
// --8<-- [end:AgentExtension]
|
||||
|
||||
// --8<-- [start:AgentSkill]
|
||||
// AgentSkill represents a unit of action/solution that the agent can perform.
|
||||
// One can think of this as a type of highly reliable solution that an agent
|
||||
// can be tasked to provide. Agents have the autonomy to choose how and when
|
||||
// to use specific skills, but clients should have confidence that if the
|
||||
// skill is defined that unit of action can be reliably performed.
|
||||
message AgentSkill {
|
||||
// Unique identifier of the skill within this agent.
|
||||
string id = 1;
|
||||
// A human readable name for the skill.
|
||||
string name = 2;
|
||||
// A human (or llm) readable description of the skill
|
||||
// details and behaviors.
|
||||
string description = 3;
|
||||
// A set of tags for the skill to enhance categorization/utilization.
|
||||
// Example: ["cooking", "customer support", "billing"]
|
||||
repeated string tags = 4;
|
||||
// A set of example queries that this skill is designed to address.
|
||||
// These examples should help the caller to understand how to craft requests
|
||||
// to the agent to achieve specific goals.
|
||||
// Example: ["I need a recipe for bread"]
|
||||
repeated string examples = 5;
|
||||
// Possible input modalities supported.
|
||||
repeated string input_modes = 6;
|
||||
// Possible output modalities produced
|
||||
repeated string output_modes = 7;
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
// Security schemes necessary for the agent to leverage this skill.
|
||||
// As in the overall AgentCard.security, this list represents a logical OR of
|
||||
// security requirement objects. Each object is a set of security schemes
|
||||
// that must be used together (a logical AND).
|
||||
repeated Security security = 8;
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
}
|
||||
// --8<-- [end:AgentSkill]
|
||||
|
||||
// --8<-- [start:AgentCardSignature]
|
||||
// AgentCardSignature represents a JWS signature of an AgentCard.
|
||||
// This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).
|
||||
message AgentCardSignature {
|
||||
// The protected JWS header for the signature. This is always a
|
||||
// base64url-encoded JSON object. Required.
|
||||
string protected = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The computed signature, base64url-encoded. Required.
|
||||
string signature = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The unprotected JWS header values.
|
||||
google.protobuf.Struct header = 3;
|
||||
}
|
||||
// --8<-- [end:AgentCardSignature]
|
||||
|
||||
// --8<-- [start:TaskPushNotificationConfig]
|
||||
message TaskPushNotificationConfig {
|
||||
// The resource name of the config.
|
||||
// Format: tasks/{task_id}/pushNotificationConfigs/{config_id}
|
||||
string name = 1;
|
||||
// The push notification configuration details.
|
||||
PushNotificationConfig push_notification_config = 2;
|
||||
}
|
||||
// --8<-- [end:TaskPushNotificationConfig]
|
||||
|
||||
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
message StringList {
|
||||
repeated string list = 1;
|
||||
}
|
||||
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
|
||||
|
||||
message Security {
|
||||
map<string, StringList> schemes = 1;
|
||||
}
|
||||
|
||||
// --8<-- [start:SecurityScheme]
|
||||
message SecurityScheme {
|
||||
oneof scheme {
|
||||
APIKeySecurityScheme api_key_security_scheme = 1;
|
||||
HTTPAuthSecurityScheme http_auth_security_scheme = 2;
|
||||
OAuth2SecurityScheme oauth2_security_scheme = 3;
|
||||
OpenIdConnectSecurityScheme open_id_connect_security_scheme = 4;
|
||||
MutualTlsSecurityScheme mtls_security_scheme = 5;
|
||||
}
|
||||
}
|
||||
// --8<-- [end:SecurityScheme]
|
||||
|
||||
// --8<-- [start:APIKeySecurityScheme]
|
||||
message APIKeySecurityScheme {
|
||||
// Description of this security scheme.
|
||||
string description = 1;
|
||||
// Location of the API key, valid values are "query", "header", or "cookie"
|
||||
string location = 2;
|
||||
// Name of the header, query or cookie parameter to be used.
|
||||
string name = 3;
|
||||
}
|
||||
// --8<-- [end:APIKeySecurityScheme]
|
||||
|
||||
// --8<-- [start:HTTPAuthSecurityScheme]
|
||||
message HTTPAuthSecurityScheme {
|
||||
// Description of this security scheme.
|
||||
string description = 1;
|
||||
// The name of the HTTP Authentication scheme to be used in the
|
||||
// Authorization header as defined in RFC7235. The values used SHOULD be
|
||||
// registered in the IANA Authentication Scheme registry.
|
||||
// The value is case-insensitive, as defined in RFC7235.
|
||||
string scheme = 2;
|
||||
// A hint to the client to identify how the bearer token is formatted.
|
||||
// Bearer tokens are usually generated by an authorization server, so
|
||||
// this information is primarily for documentation purposes.
|
||||
string bearer_format = 3;
|
||||
}
|
||||
// --8<-- [end:HTTPAuthSecurityScheme]
|
||||
|
||||
// --8<-- [start:OAuth2SecurityScheme]
|
||||
message OAuth2SecurityScheme {
|
||||
// Description of this security scheme.
|
||||
string description = 1;
|
||||
// An object containing configuration information for the flow types supported
|
||||
OAuthFlows flows = 2;
|
||||
// URL to the oauth2 authorization server metadata
|
||||
// [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
|
||||
string oauth2_metadata_url = 3;
|
||||
}
|
||||
// --8<-- [end:OAuth2SecurityScheme]
|
||||
|
||||
// --8<-- [start:OpenIdConnectSecurityScheme]
|
||||
message OpenIdConnectSecurityScheme {
|
||||
// Description of this security scheme.
|
||||
string description = 1;
|
||||
// Well-known URL to discover the [[OpenID-Connect-Discovery]] provider
|
||||
// metadata.
|
||||
string open_id_connect_url = 2;
|
||||
}
|
||||
// --8<-- [end:OpenIdConnectSecurityScheme]
|
||||
|
||||
// --8<-- [start:MutualTLSSecurityScheme]
|
||||
message MutualTlsSecurityScheme {
|
||||
// Description of this security scheme.
|
||||
string description = 1;
|
||||
}
|
||||
// --8<-- [end:MutualTLSSecurityScheme]
|
||||
|
||||
// --8<-- [start:OAuthFlows]
|
||||
message OAuthFlows {
|
||||
oneof flow {
|
||||
AuthorizationCodeOAuthFlow authorization_code = 1;
|
||||
ClientCredentialsOAuthFlow client_credentials = 2;
|
||||
ImplicitOAuthFlow implicit = 3;
|
||||
PasswordOAuthFlow password = 4;
|
||||
}
|
||||
}
|
||||
// --8<-- [end:OAuthFlows]
|
||||
|
||||
// --8<-- [start:AuthorizationCodeOAuthFlow]
|
||||
message AuthorizationCodeOAuthFlow {
|
||||
// The authorization URL to be used for this flow. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS
|
||||
string authorization_url = 1;
|
||||
// The token URL to be used for this flow. This MUST be in the form of a URL.
|
||||
// The OAuth2 standard requires the use of TLS.
|
||||
string token_url = 2;
|
||||
// The URL to be used for obtaining refresh tokens. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS.
|
||||
string refresh_url = 3;
|
||||
// The available scopes for the OAuth2 security scheme. A map between the
|
||||
// scope name and a short description for it. The map MAY be empty.
|
||||
map<string, string> scopes = 4;
|
||||
}
|
||||
// --8<-- [end:AuthorizationCodeOAuthFlow]
|
||||
|
||||
// --8<-- [start:ClientCredentialsOAuthFlow]
|
||||
message ClientCredentialsOAuthFlow {
|
||||
// The token URL to be used for this flow. This MUST be in the form of a URL.
|
||||
// The OAuth2 standard requires the use of TLS.
|
||||
string token_url = 1;
|
||||
// The URL to be used for obtaining refresh tokens. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS.
|
||||
string refresh_url = 2;
|
||||
// The available scopes for the OAuth2 security scheme. A map between the
|
||||
// scope name and a short description for it. The map MAY be empty.
|
||||
map<string, string> scopes = 3;
|
||||
}
|
||||
// --8<-- [end:ClientCredentialsOAuthFlow]
|
||||
|
||||
// --8<-- [start:ImplicitOAuthFlow]
|
||||
message ImplicitOAuthFlow {
|
||||
// The authorization URL to be used for this flow. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS
|
||||
string authorization_url = 1;
|
||||
// The URL to be used for obtaining refresh tokens. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS.
|
||||
string refresh_url = 2;
|
||||
// The available scopes for the OAuth2 security scheme. A map between the
|
||||
// scope name and a short description for it. The map MAY be empty.
|
||||
map<string, string> scopes = 3;
|
||||
}
|
||||
// --8<-- [end:ImplicitOAuthFlow]
|
||||
|
||||
// --8<-- [start:PasswordOAuthFlow]
|
||||
message PasswordOAuthFlow {
|
||||
// The token URL to be used for this flow. This MUST be in the form of a URL.
|
||||
// The OAuth2 standard requires the use of TLS.
|
||||
string token_url = 1;
|
||||
// The URL to be used for obtaining refresh tokens. This MUST be in the
|
||||
// form of a URL. The OAuth2 standard requires the use of TLS.
|
||||
string refresh_url = 2;
|
||||
// The available scopes for the OAuth2 security scheme. A map between the
|
||||
// scope name and a short description for it. The map MAY be empty.
|
||||
map<string, string> scopes = 3;
|
||||
}
|
||||
// --8<-- [end:PasswordOAuthFlow]
|
||||
|
||||
///////////// Request Messages ///////////
|
||||
// --8<-- [start:MessageSendParams]
|
||||
message SendMessageRequest {
|
||||
// The message to send to the agent.
|
||||
Message request = 1
|
||||
[(google.api.field_behavior) = REQUIRED, json_name = "message"];
|
||||
// Configuration for the send request.
|
||||
SendMessageConfiguration configuration = 2;
|
||||
// Optional metadata for the request.
|
||||
google.protobuf.Struct metadata = 3;
|
||||
}
|
||||
// --8<-- [end:MessageSendParams]
|
||||
|
||||
// --8<-- [start:GetTaskRequest]
|
||||
message GetTaskRequest {
|
||||
// The resource name of the task.
|
||||
// Format: tasks/{task_id}
|
||||
string name = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The number of most recent messages from the task's history to retrieve.
|
||||
int32 history_length = 2;
|
||||
}
|
||||
// --8<-- [end:GetTaskRequest]
|
||||
|
||||
// --8<-- [start:ListTasksRequest]
|
||||
message ListTasksRequest {
|
||||
// Filter tasks by context ID to get tasks from a specific conversation
|
||||
// or session.
|
||||
string context_id = 1;
|
||||
// Filter tasks by their current status state.
|
||||
TaskState status = 2;
|
||||
// Maximum number of tasks to return. Must be between 1 and 100.
|
||||
// Defaults to 50 if not specified.
|
||||
int32 page_size = 3;
|
||||
// Token for pagination. Use the next_page_token from a previous
|
||||
// ListTasksResponse.
|
||||
string page_token = 4;
|
||||
// Number of recent messages to include in each task's history.
|
||||
// Must be non-negative. Defaults to 0 if not specified.
|
||||
int32 history_length = 5;
|
||||
// Filter tasks updated after this timestamp. Only tasks with a last
|
||||
// updated time greater than or equal to this value will be returned.
|
||||
google.protobuf.Timestamp last_updated_time = 6;
|
||||
// Whether to include artifacts in the returned tasks.
|
||||
// Defaults to false to reduce payload size.
|
||||
bool include_artifacts = 7;
|
||||
}
|
||||
// --8<-- [end:ListTasksRequest]
|
||||
|
||||
// --8<-- [start:ListTasksResponse]
|
||||
message ListTasksResponse {
|
||||
// Array of tasks matching the specified criteria.
|
||||
repeated Task tasks = 1;
|
||||
// Token for retrieving the next page of results.
|
||||
// Empty string if no more results.
|
||||
string next_page_token = 2;
|
||||
// Total number of tasks available (before pagination).
|
||||
int32 total_size = 3;
|
||||
}
|
||||
// --8<-- [end:ListTasksResponse]
|
||||
|
||||
// --8<-- [start:CancelTaskRequest]
|
||||
message CancelTaskRequest {
|
||||
// The resource name of the task to cancel.
|
||||
// Format: tasks/{task_id}
|
||||
string name = 1;
|
||||
}
|
||||
// --8<-- [end:CancelTaskRequest]
|
||||
|
||||
// --8<-- [start:GetTaskPushNotificationConfigRequest]
|
||||
message GetTaskPushNotificationConfigRequest {
|
||||
// The resource name of the config to retrieve.
|
||||
// Format: tasks/{task_id}/pushNotificationConfigs/{config_id}
|
||||
string name = 1;
|
||||
}
|
||||
// --8<-- [end:GetTaskPushNotificationConfigRequest]
|
||||
|
||||
// --8<-- [start:DeleteTaskPushNotificationConfigRequest]
|
||||
message DeleteTaskPushNotificationConfigRequest {
|
||||
// The resource name of the config to delete.
|
||||
// Format: tasks/{task_id}/pushNotificationConfigs/{config_id}
|
||||
string name = 1;
|
||||
}
|
||||
// --8<-- [end:DeleteTaskPushNotificationConfigRequest]
|
||||
|
||||
// --8<-- [start:SetTaskPushNotificationConfigRequest]
|
||||
message CreateTaskPushNotificationConfigRequest {
|
||||
// The parent task resource for this config.
|
||||
// Format: tasks/{task_id}
|
||||
string parent = 1 [(google.api.field_behavior) = REQUIRED];
|
||||
// The ID for the new config.
|
||||
string config_id = 2 [(google.api.field_behavior) = REQUIRED];
|
||||
// The configuration to create.
|
||||
TaskPushNotificationConfig config = 3
|
||||
[(google.api.field_behavior) = REQUIRED];
|
||||
}
|
||||
// --8<-- [end:SetTaskPushNotificationConfigRequest]
|
||||
|
||||
// --8<-- [start:TaskResubscriptionRequest]
|
||||
message TaskSubscriptionRequest {
|
||||
// The resource name of the task to subscribe to.
|
||||
// Format: tasks/{task_id}
|
||||
string name = 1;
|
||||
}
|
||||
// --8<-- [end:TaskResubscriptionRequest]
|
||||
|
||||
// --8<-- [start:ListTaskPushNotificationConfigRequest]
|
||||
message ListTaskPushNotificationConfigRequest {
|
||||
// The parent task resource.
|
||||
// Format: tasks/{task_id}
|
||||
string parent = 1;
|
||||
// For AIP-158 these fields are present. Usually not used/needed.
|
||||
// The maximum number of configurations to return.
|
||||
// If unspecified, all configs will be returned.
|
||||
int32 page_size = 2;
|
||||
|
||||
// A page token received from a previous
|
||||
// ListTaskPushNotificationConfigRequest call.
|
||||
// Provide this to retrieve the subsequent page.
|
||||
// When paginating, all other parameters provided to
|
||||
// `ListTaskPushNotificationConfigRequest` must match the call that provided
|
||||
// the page token.
|
||||
string page_token = 3;
|
||||
}
|
||||
// --8<-- [end:ListTaskPushNotificationConfigRequest]
|
||||
|
||||
// --8<-- [start:GetAuthenticatedExtendedCardRequest]
|
||||
message GetAgentCardRequest {
|
||||
// Empty. Added to fix linter violation.
|
||||
}
|
||||
// --8<-- [end:GetAuthenticatedExtendedCardRequest]
|
||||
|
||||
//////// Response Messages ///////////
|
||||
// --8<-- [start:SendMessageSuccessResponse]
|
||||
message SendMessageResponse {
|
||||
oneof payload {
|
||||
Task task = 1;
|
||||
Message msg = 2 [json_name = "message"];
|
||||
}
|
||||
}
|
||||
// --8<-- [end:SendMessageSuccessResponse]
|
||||
|
||||
// --8<-- [start:SendStreamingMessageSuccessResponse]
|
||||
// The stream response for a message. The stream should be one of the following
|
||||
// sequences:
|
||||
// If the response is a message, the stream should contain one, and only one,
|
||||
// message and then close
|
||||
// If the response is a task lifecycle, the first response should be a Task
|
||||
// object followed by zero or more TaskStatusUpdateEvents and
|
||||
// TaskArtifactUpdateEvents. The stream should complete when the Task
|
||||
// if in an interrupted or terminal state. A stream that ends before these
|
||||
// conditions are met are
|
||||
message StreamResponse {
|
||||
oneof payload {
|
||||
Task task = 1;
|
||||
Message msg = 2 [json_name = "message"];
|
||||
TaskStatusUpdateEvent status_update = 3;
|
||||
TaskArtifactUpdateEvent artifact_update = 4;
|
||||
}
|
||||
}
|
||||
// --8<-- [end:SendStreamingMessageSuccessResponse]
|
||||
|
||||
// --8<-- [start:ListTaskPushNotificationConfigSuccessResponse]
|
||||
message ListTaskPushNotificationConfigResponse {
|
||||
// The list of push notification configurations.
|
||||
repeated TaskPushNotificationConfig configs = 1;
|
||||
// A token, which can be sent as `page_token` to retrieve the next page.
|
||||
// If this field is omitted, there are no subsequent pages.
|
||||
string next_page_token = 2;
|
||||
}
|
||||
// --8<-- [end:ListTaskPushNotificationConfigSuccessResponse]
|
||||
@ -1,6 +0,0 @@
|
||||
# Generated by buf. DO NOT EDIT.
|
||||
version: v2
|
||||
deps:
|
||||
- name: buf.build/googleapis/googleapis
|
||||
commit: 61b203b9a9164be9a834f58c37be6f62
|
||||
digest: b5:7811a98b35bd2e4ae5c3ac73c8b3d9ae429f3a790da15de188dc98fc2b77d6bb10e45711f14903af9553fa9821dff256054f2e4b7795789265bc476bec2f088c
|
||||
@ -1,5 +1,205 @@
|
||||
# A2A Specification JSON
|
||||
# A2A JSON Artifact
|
||||
|
||||
DO NOT EDIT `a2a.json` directly.
|
||||
`a2a.json` is a **non-normative build artifact** derived from the canonical proto definition at `specification/a2a.proto`. It is generated during builds and intentionally **not** committed to source control.
|
||||
|
||||
Make all edits in [`types/src/types.ts`](https://github.com/a2aproject/A2A/blob/main/types/src/types.ts) and follow the directions in [`types/README.md`](https://github.com/a2aproject/A2A/blob/main/types/README.md)
|
||||
Generation pipeline:
|
||||
|
||||
1. `scripts/proto_to_json_schema.sh` converts proto directly to JSON Schema using bufbuild's `protoc-gen-jsonschema` plugin.
|
||||
2. The resulting `a2a.json` (JSON Schema 2020-12 bundle) is copied to `docs/spec/a2a.json` for 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`)
|
||||
|
||||
## 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.
|
||||
|
||||
<details>
|
||||
<summary>macOS/Linux</summary>
|
||||
|
||||
### Prerequisites for macOS/Linux
|
||||
|
||||
1. **Homebrew (macOS) or apt-get (Debian/Ubuntu)**
|
||||
- **macOS**: Install from [brew.sh](https://brew.sh/)
|
||||
- **Debian/Ubuntu**: `apt-get` is pre-installed.
|
||||
|
||||
2. **Python with pip**
|
||||
|
||||
```bash
|
||||
# Verify installation:
|
||||
python3 --version
|
||||
pip3 --version
|
||||
```
|
||||
|
||||
3. **Core build tools (`protoc`, `go`, `jq`)**
|
||||
- **macOS**:
|
||||
|
||||
```bash
|
||||
brew install protobuf go jq
|
||||
```
|
||||
|
||||
- **Debian/Ubuntu**:
|
||||
|
||||
```bash
|
||||
sudo apt-get update && sudo apt-get install -y protobuf-compiler golang jq
|
||||
```
|
||||
|
||||
4. **protoc-gen-jsonschema plugin**
|
||||
|
||||
```bash
|
||||
# Install via Go (requires Go to be installed first):
|
||||
go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest
|
||||
```
|
||||
|
||||
5. **Clone googleapis repository**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
6. **Python documentation dependencies**
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Windows</summary>
|
||||
|
||||
#### Windows Prerequisites
|
||||
|
||||
1. **Python with pip** (for MkDocs)
|
||||
|
||||
```powershell
|
||||
# Install Python from python.org or via Microsoft Store
|
||||
# Verify installation:
|
||||
python --version
|
||||
pip --version
|
||||
```
|
||||
|
||||
2. **Protocol Buffers compiler (protoc)**
|
||||
|
||||
```powershell
|
||||
# Install via WinGet (recommended):
|
||||
winget install Google.Protobuf
|
||||
|
||||
# Verify installation:
|
||||
protoc --version
|
||||
```
|
||||
|
||||
3. **Go programming language** (for protoc-gen-jsonschema plugin)
|
||||
|
||||
```powershell
|
||||
# Install via WinGet:
|
||||
winget install GoLang.Go
|
||||
|
||||
# Or download from https://golang.org/dl/
|
||||
# Verify installation:
|
||||
go version
|
||||
```
|
||||
|
||||
4. **protoc-gen-jsonschema plugin**
|
||||
|
||||
```powershell
|
||||
# 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
|
||||
```
|
||||
|
||||
5. **jq (JSON processor)**
|
||||
|
||||
```powershell
|
||||
# Install via WinGet:
|
||||
winget install jqlang.jq
|
||||
|
||||
# Verify installation:
|
||||
jq --version
|
||||
```
|
||||
|
||||
6. **Clone googleapis repository**
|
||||
|
||||
```powershell
|
||||
# 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"
|
||||
```
|
||||
|
||||
7. **Python documentation dependencies**
|
||||
|
||||
```powershell
|
||||
# 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:
|
||||
|
||||
```powershell
|
||||
# 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
|
||||
|
||||
</details>
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
- **protoc errors**: Ensure both `protoc` and 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-jsonschema` is in your `PATH` (run `go env GOPATH` to find Go bin directory)
|
||||
|
||||
## Future Work
|
||||
|
||||
Planned improvements include:
|
||||
|
||||
- Optional OpenAPI v3 conversion and publishing a draft 2020-12 `components.schemas` bundle.
|
||||
- Automatic alias injection for deprecated names (anyOf wrapper) to ease migrations.
|
||||
- Validation step ensuring no generated artifacts are reintroduced into git.
|
||||
|
||||
2
types/.gitignore
vendored
@ -1,2 +0,0 @@
|
||||
.DS_Store
|
||||
node_modules/
|
||||
@ -1,13 +0,0 @@
|
||||
# A2A Types
|
||||
|
||||
Core objects and method types for A2A Protocol
|
||||
|
||||
## Steps to update
|
||||
|
||||
1. Clone this repository.
|
||||
2. Run `npm install`
|
||||
3. Update `types.ts` with required changes
|
||||
4. Run `npm run generate`, this will update `a2a.json`.
|
||||
5. Verify the updates and push to the repository.
|
||||
|
||||
**DO NOT DIRECTLY CHANGE `a2a.json` file. THIS MUST BE GENERATED USING `npm run generate`**
|
||||
565
types/package-lock.json
generated
@ -1,565 +0,0 @@
|
||||
{
|
||||
"name": "types",
|
||||
"version": "1.0.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "types",
|
||||
"version": "1.0.0",
|
||||
"dependencies": {
|
||||
"typescript-json-schema": "^0.65.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"prettier": "^3.6.2",
|
||||
"typescript": "^5.9.3"
|
||||
}
|
||||
},
|
||||
"node_modules/@cspotcode/source-map-support": {
|
||||
"version": "0.8.1",
|
||||
"resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
|
||||
"integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@jridgewell/trace-mapping": "0.3.9"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/@jridgewell/resolve-uri": {
|
||||
"version": "3.1.2",
|
||||
"resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
|
||||
"integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=6.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@jridgewell/sourcemap-codec": {
|
||||
"version": "1.5.3",
|
||||
"resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.3.tgz",
|
||||
"integrity": "sha512-AiR5uKpFxP3PjO4R19kQGIMwxyRyPuXmKEEy301V1C0+1rVjS94EZQXf1QKZYN8Q0YM+estSPhmx5JwNftv6nw==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@jridgewell/trace-mapping": {
|
||||
"version": "0.3.9",
|
||||
"resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
|
||||
"integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@jridgewell/resolve-uri": "^3.0.3",
|
||||
"@jridgewell/sourcemap-codec": "^1.4.10"
|
||||
}
|
||||
},
|
||||
"node_modules/@tsconfig/node10": {
|
||||
"version": "1.0.11",
|
||||
"resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.11.tgz",
|
||||
"integrity": "sha512-DcRjDCujK/kCk/cUe8Xz8ZSpm8mS3mNNpta+jGCA6USEDfktlNvm1+IuZ9eTcDbNk41BHwpHHeW+N1lKCz4zOw==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@tsconfig/node12": {
|
||||
"version": "1.0.11",
|
||||
"resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz",
|
||||
"integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@tsconfig/node14": {
|
||||
"version": "1.0.3",
|
||||
"resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz",
|
||||
"integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@tsconfig/node16": {
|
||||
"version": "1.0.4",
|
||||
"resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz",
|
||||
"integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/json-schema": {
|
||||
"version": "7.0.15",
|
||||
"resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
|
||||
"integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/node": {
|
||||
"version": "18.19.113",
|
||||
"resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.113.tgz",
|
||||
"integrity": "sha512-TmSTE9vyebJ9vSEiU+P+0Sp4F5tMgjiEOZaQUW6wA3ODvi6uBgkHQ+EsIu0pbiKvf9QHEvyRCiaz03rV0b+IaA==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"undici-types": "~5.26.4"
|
||||
}
|
||||
},
|
||||
"node_modules/acorn": {
|
||||
"version": "8.15.0",
|
||||
"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
|
||||
"integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"acorn": "bin/acorn"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=0.4.0"
|
||||
}
|
||||
},
|
||||
"node_modules/acorn-walk": {
|
||||
"version": "8.3.4",
|
||||
"resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.4.tgz",
|
||||
"integrity": "sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"acorn": "^8.11.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=0.4.0"
|
||||
}
|
||||
},
|
||||
"node_modules/ansi-regex": {
|
||||
"version": "5.0.1",
|
||||
"resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
|
||||
"integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/ansi-styles": {
|
||||
"version": "4.3.0",
|
||||
"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
|
||||
"integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"color-convert": "^2.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/chalk/ansi-styles?sponsor=1"
|
||||
}
|
||||
},
|
||||
"node_modules/arg": {
|
||||
"version": "4.1.3",
|
||||
"resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz",
|
||||
"integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/balanced-match": {
|
||||
"version": "1.0.2",
|
||||
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
|
||||
"integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/brace-expansion": {
|
||||
"version": "1.1.12",
|
||||
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
|
||||
"integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"balanced-match": "^1.0.0",
|
||||
"concat-map": "0.0.1"
|
||||
}
|
||||
},
|
||||
"node_modules/cliui": {
|
||||
"version": "8.0.1",
|
||||
"resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
|
||||
"integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"string-width": "^4.2.0",
|
||||
"strip-ansi": "^6.0.1",
|
||||
"wrap-ansi": "^7.0.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/color-convert": {
|
||||
"version": "2.0.1",
|
||||
"resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
|
||||
"integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"color-name": "~1.1.4"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=7.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/color-name": {
|
||||
"version": "1.1.4",
|
||||
"resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
|
||||
"integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/concat-map": {
|
||||
"version": "0.0.1",
|
||||
"resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
|
||||
"integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/create-require": {
|
||||
"version": "1.1.1",
|
||||
"resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
|
||||
"integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/diff": {
|
||||
"version": "4.0.2",
|
||||
"resolved": "https://registry.npmjs.org/diff/-/diff-4.0.2.tgz",
|
||||
"integrity": "sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A==",
|
||||
"license": "BSD-3-Clause",
|
||||
"engines": {
|
||||
"node": ">=0.3.1"
|
||||
}
|
||||
},
|
||||
"node_modules/emoji-regex": {
|
||||
"version": "8.0.0",
|
||||
"resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
|
||||
"integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/escalade": {
|
||||
"version": "3.2.0",
|
||||
"resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
|
||||
"integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=6"
|
||||
}
|
||||
},
|
||||
"node_modules/fs.realpath": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
|
||||
"integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
|
||||
"license": "ISC"
|
||||
},
|
||||
"node_modules/get-caller-file": {
|
||||
"version": "2.0.5",
|
||||
"resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
|
||||
"integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
|
||||
"license": "ISC",
|
||||
"engines": {
|
||||
"node": "6.* || 8.* || >= 10.*"
|
||||
}
|
||||
},
|
||||
"node_modules/glob": {
|
||||
"version": "7.2.3",
|
||||
"resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
|
||||
"integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
|
||||
"deprecated": "Glob versions prior to v9 are no longer supported",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"fs.realpath": "^1.0.0",
|
||||
"inflight": "^1.0.4",
|
||||
"inherits": "2",
|
||||
"minimatch": "^3.1.1",
|
||||
"once": "^1.3.0",
|
||||
"path-is-absolute": "^1.0.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": "*"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/isaacs"
|
||||
}
|
||||
},
|
||||
"node_modules/inflight": {
|
||||
"version": "1.0.6",
|
||||
"resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
|
||||
"integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
|
||||
"deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"once": "^1.3.0",
|
||||
"wrappy": "1"
|
||||
}
|
||||
},
|
||||
"node_modules/inherits": {
|
||||
"version": "2.0.4",
|
||||
"resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
|
||||
"integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
|
||||
"license": "ISC"
|
||||
},
|
||||
"node_modules/is-fullwidth-code-point": {
|
||||
"version": "3.0.0",
|
||||
"resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
|
||||
"integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/make-error": {
|
||||
"version": "1.3.6",
|
||||
"resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
|
||||
"integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
|
||||
"license": "ISC"
|
||||
},
|
||||
"node_modules/minimatch": {
|
||||
"version": "3.1.2",
|
||||
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
|
||||
"integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"brace-expansion": "^1.1.7"
|
||||
},
|
||||
"engines": {
|
||||
"node": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/once": {
|
||||
"version": "1.4.0",
|
||||
"resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
|
||||
"integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"wrappy": "1"
|
||||
}
|
||||
},
|
||||
"node_modules/path-equal": {
|
||||
"version": "1.2.5",
|
||||
"resolved": "https://registry.npmjs.org/path-equal/-/path-equal-1.2.5.tgz",
|
||||
"integrity": "sha512-i73IctDr3F2W+bsOWDyyVm/lqsXO47aY9nsFZUjTT/aljSbkxHxxCoyZ9UUrM8jK0JVod+An+rl48RCsvWM+9g==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/path-is-absolute": {
|
||||
"version": "1.0.1",
|
||||
"resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
|
||||
"integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=0.10.0"
|
||||
}
|
||||
},
|
||||
"node_modules/prettier": {
|
||||
"version": "3.6.2",
|
||||
"resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
|
||||
"integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"prettier": "bin/prettier.cjs"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=14"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/prettier/prettier?sponsor=1"
|
||||
}
|
||||
},
|
||||
"node_modules/require-directory": {
|
||||
"version": "2.1.1",
|
||||
"resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
|
||||
"integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=0.10.0"
|
||||
}
|
||||
},
|
||||
"node_modules/safe-stable-stringify": {
|
||||
"version": "2.5.0",
|
||||
"resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz",
|
||||
"integrity": "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=10"
|
||||
}
|
||||
},
|
||||
"node_modules/string-width": {
|
||||
"version": "4.2.3",
|
||||
"resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
|
||||
"integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"emoji-regex": "^8.0.0",
|
||||
"is-fullwidth-code-point": "^3.0.0",
|
||||
"strip-ansi": "^6.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/strip-ansi": {
|
||||
"version": "6.0.1",
|
||||
"resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
|
||||
"integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"ansi-regex": "^5.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/ts-node": {
|
||||
"version": "10.9.2",
|
||||
"resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
|
||||
"integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@cspotcode/source-map-support": "^0.8.0",
|
||||
"@tsconfig/node10": "^1.0.7",
|
||||
"@tsconfig/node12": "^1.0.7",
|
||||
"@tsconfig/node14": "^1.0.0",
|
||||
"@tsconfig/node16": "^1.0.2",
|
||||
"acorn": "^8.4.1",
|
||||
"acorn-walk": "^8.1.1",
|
||||
"arg": "^4.1.0",
|
||||
"create-require": "^1.1.0",
|
||||
"diff": "^4.0.1",
|
||||
"make-error": "^1.1.1",
|
||||
"v8-compile-cache-lib": "^3.0.1",
|
||||
"yn": "3.1.1"
|
||||
},
|
||||
"bin": {
|
||||
"ts-node": "dist/bin.js",
|
||||
"ts-node-cwd": "dist/bin-cwd.js",
|
||||
"ts-node-esm": "dist/bin-esm.js",
|
||||
"ts-node-script": "dist/bin-script.js",
|
||||
"ts-node-transpile-only": "dist/bin-transpile.js",
|
||||
"ts-script": "dist/bin-script-deprecated.js"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@swc/core": ">=1.2.50",
|
||||
"@swc/wasm": ">=1.2.50",
|
||||
"@types/node": "*",
|
||||
"typescript": ">=2.7"
|
||||
},
|
||||
"peerDependenciesMeta": {
|
||||
"@swc/core": {
|
||||
"optional": true
|
||||
},
|
||||
"@swc/wasm": {
|
||||
"optional": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"node_modules/typescript": {
|
||||
"version": "5.9.3",
|
||||
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
|
||||
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
|
||||
"license": "Apache-2.0",
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=14.17"
|
||||
}
|
||||
},
|
||||
"node_modules/typescript-json-schema": {
|
||||
"version": "0.65.1",
|
||||
"resolved": "https://registry.npmjs.org/typescript-json-schema/-/typescript-json-schema-0.65.1.tgz",
|
||||
"integrity": "sha512-tuGH7ff2jPaUYi6as3lHyHcKpSmXIqN7/mu50x3HlYn0EHzLpmt3nplZ7EuhUkO0eqDRc9GqWNkfjgBPIS9kxg==",
|
||||
"license": "BSD-3-Clause",
|
||||
"dependencies": {
|
||||
"@types/json-schema": "^7.0.9",
|
||||
"@types/node": "^18.11.9",
|
||||
"glob": "^7.1.7",
|
||||
"path-equal": "^1.2.5",
|
||||
"safe-stable-stringify": "^2.2.0",
|
||||
"ts-node": "^10.9.1",
|
||||
"typescript": "~5.5.0",
|
||||
"yargs": "^17.1.1"
|
||||
},
|
||||
"bin": {
|
||||
"typescript-json-schema": "bin/typescript-json-schema"
|
||||
}
|
||||
},
|
||||
"node_modules/typescript-json-schema/node_modules/typescript": {
|
||||
"version": "5.5.4",
|
||||
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.4.tgz",
|
||||
"integrity": "sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==",
|
||||
"license": "Apache-2.0",
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=14.17"
|
||||
}
|
||||
},
|
||||
"node_modules/undici-types": {
|
||||
"version": "5.26.5",
|
||||
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
|
||||
"integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/v8-compile-cache-lib": {
|
||||
"version": "3.0.1",
|
||||
"resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz",
|
||||
"integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/wrap-ansi": {
|
||||
"version": "7.0.0",
|
||||
"resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
|
||||
"integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"ansi-styles": "^4.0.0",
|
||||
"string-width": "^4.1.0",
|
||||
"strip-ansi": "^6.0.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=10"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/chalk/wrap-ansi?sponsor=1"
|
||||
}
|
||||
},
|
||||
"node_modules/wrappy": {
|
||||
"version": "1.0.2",
|
||||
"resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
|
||||
"integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
|
||||
"license": "ISC"
|
||||
},
|
||||
"node_modules/y18n": {
|
||||
"version": "5.0.8",
|
||||
"resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
|
||||
"integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
|
||||
"license": "ISC",
|
||||
"engines": {
|
||||
"node": ">=10"
|
||||
}
|
||||
},
|
||||
"node_modules/yargs": {
|
||||
"version": "17.7.2",
|
||||
"resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
|
||||
"integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"cliui": "^8.0.1",
|
||||
"escalade": "^3.1.1",
|
||||
"get-caller-file": "^2.0.5",
|
||||
"require-directory": "^2.1.1",
|
||||
"string-width": "^4.2.3",
|
||||
"y18n": "^5.0.5",
|
||||
"yargs-parser": "^21.1.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/yargs-parser": {
|
||||
"version": "21.1.1",
|
||||
"resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
|
||||
"integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
|
||||
"license": "ISC",
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/yn": {
|
||||
"version": "3.1.1",
|
||||
"resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
|
||||
"integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=6"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,18 +0,0 @@
|
||||
{
|
||||
"name": "types",
|
||||
"version": "1.0.0",
|
||||
"main": "index.js",
|
||||
"scripts": {
|
||||
"generate": "./node_modules/.bin/typescript-json-schema tsconfig.json \"*\" --defaultNumberType integer --required --out ../specification/json/a2a.json",
|
||||
"prettier": "prettier src/types.ts --write"
|
||||
},
|
||||
"author": "",
|
||||
"description": "A2A Types",
|
||||
"dependencies": {
|
||||
"typescript-json-schema": "^0.65.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"prettier": "^3.6.2",
|
||||
"typescript": "^5.9.3"
|
||||
}
|
||||
}
|
||||
1617
types/src/types.ts
@ -1,13 +0,0 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"noEmit": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
"experimentalDecorators": true,
|
||||
"target": "ES5",
|
||||
"module": "CommonJS",
|
||||
"strictNullChecks": false,
|
||||
"skipLibCheck": true
|
||||
},
|
||||
"include": ["**/*.ts"],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||