Repository: a2aproject/A2A Branch: main Commit: 7b900e77be2e Files: 100 Total size: 509.1 KB Directory structure: gitextract_6mxkg8fn/ ├── .devcontainer/ │ ├── README.md │ ├── devcontainer.json │ └── setup.sh ├── .editorconfig ├── .gemini/ │ └── config.yaml ├── .git-blame-ignore-revs ├── .gitattributes ├── .github/ │ ├── CODEOWNERS │ ├── ISSUE_TEMPLATE/ │ │ ├── bug-report.yml │ │ └── feature-request.yml │ ├── PULL_REQUEST_TEMPLATE/ │ │ ├── PULL_REQUEST_TEMPLATE.md │ │ └── become_a_repo_maintainer.md │ ├── actions/ │ │ └── spelling/ │ │ ├── advice.md │ │ ├── allow.txt │ │ ├── excludes.txt │ │ └── line_forbidden.patterns │ ├── conventional-commit-lint.yaml │ ├── dependabot.yml │ ├── linters/ │ │ ├── .eslintrc.js │ │ ├── .jscpd.json │ │ ├── .markdownlint.json │ │ ├── .protolint.yaml │ │ └── .stylelintrc.json │ ├── super-linter.env │ └── workflows/ │ ├── check-linked-issues.yml │ ├── conventional-commits.yml │ ├── dispatch-a2a-update.yml │ ├── docs.yml │ ├── issue-metrics.yml │ ├── links.yaml │ ├── linter.yaml │ ├── release-please.yml │ ├── sort-spelling-allowlist.yml │ ├── spelling.yaml │ └── stale.yaml ├── .gitignore ├── .gitvote.yml ├── .mkdocs/ │ ├── macros.py │ └── overrides/ │ └── main.html ├── .prettierrc ├── .ruff.toml ├── .vscode/ │ └── settings.json ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.md ├── SECURITY.md ├── adrs/ │ ├── adr-001-protojson-serialization.md │ └── adr-template.md ├── docs/ │ ├── 404.html │ ├── README.md │ ├── announcing-1.0.md │ ├── community.md │ ├── definitions.md │ ├── index.md │ ├── llms.txt │ ├── partners.md │ ├── roadmap.md │ ├── robots.txt │ ├── sdk/ │ │ ├── index.md │ │ └── python.md │ ├── specification.md │ ├── stylesheets/ │ │ └── custom.css │ ├── topics/ │ │ ├── a2a-and-mcp.md │ │ ├── agent-discovery.md │ │ ├── enterprise-ready.md │ │ ├── extensions.md │ │ ├── key-concepts.md │ │ ├── life-of-a-task.md │ │ ├── streaming-and-async.md │ │ └── what-is-a2a.md │ ├── tutorials/ │ │ ├── index.md │ │ └── python/ │ │ ├── 1-introduction.md │ │ ├── 2-setup.md │ │ ├── 3-agent-skills-and-card.md │ │ ├── 4-agent-executor.md │ │ ├── 5-start-server.md │ │ ├── 6-interact-with-server.md │ │ ├── 7-streaming-and-multiturn.md │ │ └── 8-next-steps.md │ └── whats-new-v1.md ├── lychee.toml ├── mkdocs.yml ├── requirements-docs.txt ├── scripts/ │ ├── build_docs.sh │ ├── build_llms_full.sh │ ├── build_sdk_docs.sh │ ├── deploy_root_files.sh │ ├── format.sh │ ├── lint.sh │ ├── proto_to_json_schema.sh │ └── sort_spelling.sh └── specification/ ├── .api-linter.yaml ├── a2a.proto ├── buf.gen.yaml ├── buf.yaml └── json/ └── README.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: .devcontainer/README.md ================================================ # 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 ``` ================================================ FILE: .devcontainer/devcontainer.json ================================================ { "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" } ================================================ FILE: .devcontainer/setup.sh ================================================ #!/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" ================================================ FILE: .editorconfig ================================================ # editorconfig.org root = true [*] end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [*.sh] indent_style = space indent_size = 2 ================================================ FILE: .gemini/config.yaml ================================================ code_review: comment_severity_threshold: LOW ignore_patterns: ['CHANGELOG.md'] ================================================ FILE: .git-blame-ignore-revs ================================================ # Template taken from https://github.com/v8/v8/blob/master/.git-blame-ignore-revs. # # This file contains a list of git hashes of revisions to be ignored by git blame. These # revisions are considered "unimportant" in that they are unlikely to be what you are # interested in when blaming. Most of these will probably be commits related to linting # and code formatting. # # Instructions: # - Only large (generally automated) reformatting or renaming CLs should be # added to this list. Do not put things here just because you feel they are # trivial or unimportant. If in doubt, do not put it on this list. # - Precede each revision with a comment containing the PR title and number. # For bulk work over many commits, place all commits in a block with a single # comment at the top describing the work done in those commits. # - Only put full 40-character hashes on this list (not short hashes or any # other revision reference). # - Append to the bottom of the file (revisions should be in chronological order # from oldest to newest). # - Because you must use a hash, you need to append to this list in a follow-up # PR to the actual reformatting PR that you are trying to ignore. 0f8d9750bcb17f6b8b9f48793b46f7b8510cae24 ================================================ FILE: .gitattributes ================================================ # Documentation overrides /docs/** linguist-documentation=true /.mkdocs/** linguist-documentation=true # Removed committed a2a.json; generated at build time. noxfile.py linguist-vendored=true # Merge and diff setting CHANGELOG.md merge=union ================================================ FILE: .github/CODEOWNERS ================================================ # Code owners file. # This file controls who is tagged for review for any given pull request. # # For syntax help see: # https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax * @a2aproject/a2a-tsc docs/ @a2aproject/a2a-tsc scripts/ @a2aproject/a2a-tsc specification/ @a2aproject/a2a-tsc docs/specification.md @a2aproject/a2a-tsc GOVERNANCE.md @a2aproject/a2a-tsc .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 ================================================ FILE: .github/ISSUE_TEMPLATE/bug-report.yml ================================================ name: 🐞 Bug Report description: File a bug report title: "[Bug]: " type: "Bug" body: - type: markdown attributes: value: | Thanks for stopping by to let us know something could be better! Private Feedback? Please use this [Google form](https://goo.gle/a2a-feedback) - type: textarea id: what-happened attributes: label: What happened? description: Also tell us what you expected to happen and how to reproduce the issue. placeholder: Tell us what you see! value: "A bug happened!" validations: required: true - type: textarea id: logs attributes: label: Relevant log output description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. render: shell - type: checkboxes id: terms attributes: label: Code of Conduct description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/a2aproject/A2A?tab=coc-ov-file#readme) options: - label: I agree to follow this project's Code of Conduct required: true ================================================ FILE: .github/ISSUE_TEMPLATE/feature-request.yml ================================================ name: 💡 Feature Request description: Suggest an idea for this repository title: "[Feat]: " type: "Feature" body: - type: markdown attributes: value: | Thanks for stopping by to let us know something could be better! Private Feedback? Please use this [Google form](https://goo.gle/a2a-feedback) - type: textarea id: problem attributes: label: Is your feature request related to a problem? Please describe. description: A clear and concise description of what the problem is. placeholder: Ex. I'm always frustrated when [...] - type: textarea id: describe attributes: label: Describe the solution you'd like description: A clear and concise description of what you want to happen. validations: required: true - type: textarea id: alternatives attributes: label: Describe alternatives you've considered description: A clear and concise description of any alternative solutions or features you've considered. - type: textarea id: context attributes: label: Additional context description: Add any other context or screenshots about the feature request here. - type: checkboxes id: terms attributes: label: Code of Conduct description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/a2aproject/A2A?tab=coc-ov-file#readme) options: - label: I agree to follow this project's Code of Conduct required: true ================================================ FILE: .github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md ================================================ # Description Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly: - [ ] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md). - [ ] Make your Pull Request title in the specification. - [ ] Ensure the tests and linter pass (Run `nox -s format` from the repository root to format) - [ ] Appropriate docs were updated (if necessary) Fixes # 🦕 ================================================ FILE: .github/PULL_REQUEST_TEMPLATE/become_a_repo_maintainer.md ================================================ --- name: Become a repo maintainer about: Request maintainer status for the A2A repo title: Maintainer Request assignees: amye --- If you'd like to become a maintainer of the Agent2Agent repo on GitHub, please submit this template with your PR to add yourself to a maintainers group in [MAINTAINERS.md](../../MAINTAINERS.md). TSC voting majority will be required to approve maintainers. Once accepted you'll be able to commit to this repo! ### GitHub user id - List your GitHub user id ### Company affiliation - List your company name, or indicate Individual if you're not affiliated with a company ### Requirements - [ ] I have at least one merged Pull Request - [ ] I have reviewed the [contribution guidelines](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md) - [ ] I have enabled [2FA on my GitHub account](https://github.com/settings/security) - [ ] I have joined the A2A discord ================================================ FILE: .github/actions/spelling/advice.md ================================================
If the flagged items are :exploding_head: false positives If items relate to a ... - binary file (or some other file you wouldn't want to check at all). Please add a file path to the `excludes.txt` file matching the containing file. File paths are Perl 5 Regular Expressions - you can [test](https://www.regexplanet.com/advanced/perl/) yours before committing to verify it will match your files. `^` refers to the file's path from the root of the repository, so `^README\.md$` would exclude `README.md` (on whichever branch you're using). - well-formed pattern. If you can write a [pattern](https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-patterns) that would match it, try adding it to the `patterns.txt` file. Patterns are Perl 5 Regular Expressions - you can [test](https://www.regexplanet.com/advanced/perl/) yours before committing to verify it will match your lines. Note that patterns can't match multiline strings.
:steam_locomotive: If you're seeing this message and your PR is from a branch that doesn't have check-spelling, please merge to your PR's base branch to get the version configured for your repository. ================================================ FILE: .github/actions/spelling/allow.txt ================================================ AAAANSUh AAAAUA AAAGHMHc ACMRTUXB ACard AClient ACo ADK ADR AError AExecutor AGP AIP ARequest ASED ASGI AServer AService ASq AStarlette AUTOCOMMIT Agentspace Agno Autogen Bahasa Besen Blogs CAs CLIs Camry Cjava Cpzuhi DDo DGT DHDe Datetimes Debian Djq Dotnet EBFF EUR EUg Espa FBT FHIR Fbr GAPI GAPIC GBP GVsb Gapic Gci Genkit Ghw GitVote HBz HKRMw HRA HSTS HXo Hackathon IFdvcmxk IMPCUk INR Ikp Imh Imprd JFUz JHv JIUz JPY JWKS JWS JWTs Jhb Jra KGgo KRW LHR LJcvt LLM LLMs Lix MSIs MWpm Mapr Mvosg Nszl OIDC OOa Ollama PLE PLW PMEEi PTH Polski Portugu QFdk Qvandrcy RFCs RPCs RUF SLAs SLF SSLv Solax TJS TMDB Tful URLTo Upserting Urke VBORw VHc Vsb WHB WQi WVw Witteveen XBs XVCJ Xca YQGt YTAKFW YTT YWFh YWdlbn ZDS ZKHv ZXhhb ZXkt Zipkin Zms aab aacacac aboutasha achat aconnect adk adr adrs afet affef agentcard agentic agentskill agno agntcy agp ainvoke aip airbnb aldridge alloydb amannn aparse aproject aprotocol argjson arxiv askmarvin asyncclick autogen automodule autouse backstory backticks bbb beeai boq bufbuild bzr cae canceltask ccc cdn ceee cfe chrusty cls coc codegen codeowner codespace codewiki crewai datamodel datapart dbc dcda dcfa dde deepwiki direnv dlai docstrings documentai dotnet eaf ebedef efaab efbd embeddings endblock endmacro envoyproxy euo evt excinfo faa faf fafd fdebd ffbb fff firewalls flightbook forbes fsv fyi gapic gcp genai geneknit genkit genproto georoute gettask gettickets gitleaks gitvote gle googleai googleapi googleapis googleblog gpt gstatic gweb hackathon hackathons hqdefault hughesthe iana iat ietf inardini inbox inmemory ipynb iss jherr jku jqlang jti jwks kadirpekel keystores konami kty langgraph lerhaupt linenums linkedin linting listtasks litellm llm llms lng logtostderr marvin mcp mcr mesop mikefarah mindsdb mintlify motherlode mozilla msword multiagent multipage mydb myorg nearform nlp notif npush objc octicons oidc ollama oneof openaitx openapis openapiv openapiv2 oreilly postgres postgresql pqr prefecthq protoc protojson protolint pyguide pylance pymdownx pypa pypackages pytype pyupgrade qwq rcm regen repomapr reportgen reposted rst rvelicheti sandijean scm sllm sourced sourcing squidfunk srcs sse sss stateclass stephenh styleguide svn systemctl tablefmt tagwords tasksget taskslist taskssend taskstate taskstatus textpart threadsafe toctree tok toolkits tracestate ugc undoc utm venv-docs versioned vnd voa vscode weavehacks webform webpage whatwg wikipedia winget wsgi wwwwwwww xxxxx xxxxxxxx youtube yyyyyyyy zzzzzzzz ================================================ FILE: .github/actions/spelling/excludes.txt ================================================ # See https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-excludes (?:^|/)(?i)COPYRIGHT (?:^|/)(?i)LICEN[CS]E (?:^|/)(?i)CODE_OF_CONDUCT.md\E$ (?:^|/)(?i).gitignore\E$ (?:^|/)3rdparty/ (?:^|/)go\.sum$ (?:^|/)package(?:-lock|)\.json$ (?:^|/)Pipfile$ (?:^|/)pyproject.toml (?:^|/)requirements(?:-dev|-doc|-test|)\.txt$ (?:^|/)vendor/ /CODEOWNERS$ \.a$ \.ai$ \.all-contributorsrc$ \.avi$ \.bmp$ \.bz2$ \.cer$ \.class$ \.coveragerc$ \.crl$ \.crt$ \.csr$ \.dll$ \.docx?$ \.drawio$ \.DS_Store$ \.eot$ \.eps$ \.exe$ \.gif$ \.git-blame-ignore-revs$ \.gitattributes$ \.gitkeep$ \.graffle$ \.gz$ \.icns$ \.ico$ \.jar$ \.jks$ \.jpe?g$ \.key$ \.lib$ \.lock$ \.map$ \.min\.. \.mo$ \.mod$ \.mp[34]$ \.o$ \.ocf$ \.otf$ \.p12$ \.parquet$ \.pdf$ \.pem$ \.pfx$ \.png$ \.psd$ \.pyc$ \.pylintrc$ \.qm$ \.s$ \.sig$ \.so$ \.svgz?$ \.sys$ \.tar$ \.tgz$ \.tiff?$ \.ttf$ \.wav$ \.webm$ \.webp$ \.woff2?$ \.xcf$ \.xlsx?$ \.xpm$ \.xz$ \.zip$ ^\.github/actions/spelling/ ^\Q.github/workflows/spelling.yaml\E$ ^\Q.github/workflows/linter.yaml\E$ ^\Qlychee.toml\E$ \.vscode/ ^\Qdocs/partners.md\E$ ^\Qspecification/json/a2a.json\E$ CHANGELOG.md \.gitignore ^\Qdocs/robots.txt\E$ CODE_OF_CONDUCT.md ================================================ FILE: .github/actions/spelling/line_forbidden.patterns ================================================ # Should be `HH:MM:SS` \bHH:SS:MM\b # Should probably be `YYYYMMDD` \b[Yy]{4}[Dd]{2}[Mm]{2}(?!.*[Yy]{4}[Dd]{2}[Mm]{2}).*$ # Should be `anymore` \bany more[,.] # Should be `cannot` (or `can't`) # See https://www.grammarly.com/blog/cannot-or-can-not/ # > Don't use `can not` when you mean `cannot`. The only time you're likely to see `can not` written as separate words is when the word `can` happens to precede some other phrase that happens to start with `not`. # > `Can't` is a contraction of `cannot`, and it's best suited for informal writing. # > In formal writing and where contractions are frowned upon, use `cannot`. # > It is possible to write `can not`, but you generally find it only as part of some other construction, such as `not only . . . but also.` # - if you encounter such a case, add a pattern for that case to patterns.txt. \b[Cc]an not\b # Should be `GitHub` (?> "$GITHUB_ENV" - name: Run issue-metrics tool uses: github/issue-metrics@v3 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} SEARCH_QUERY: 'repo:a2aproject/A2A is:issue created:${{ env.last_month }} -reason:"not planned"' - name: Create issue uses: peter-evans/create-issue-from-file@v6 with: title: Monthly issue metrics report token: ${{ secrets.GITHUB_TOKEN }} content-filepath: ./issue_metrics.md ================================================ FILE: .github/workflows/links.yaml ================================================ name: Lychee Link Checker on: repository_dispatch: workflow_dispatch: schedule: - cron: "00 18 * * *" pull_request: jobs: check_links: name: Check for Broken Links runs-on: ubuntu-latest if: | github.repository == 'a2aproject/A2A' steps: - name: Checkout Repository uses: actions/checkout@v6 - name: Get relevant changed files id: changed-files if: github.event_name == 'pull_request' uses: tj-actions/changed-files@v47 with: files: | **/*.md **/*.mdx **/*.html **/*.htm **/*.rst **/*.txt - name: Run Lychee on changed files (PR) if: github.event_name == 'pull_request' && steps.changed-files.outputs.all_changed_files != '' uses: lycheeverse/lychee-action@v2 with: args: --no-progress ${{ steps.changed-files.outputs.all_changed_files }} failIfEmpty: false - name: Run Lychee on all files (Scheduled/Manual) if: github.event_name != 'pull_request' uses: lycheeverse/lychee-action@v2 with: args: --no-progress . failIfEmpty: false - name: Create Issue on Failure if: failure() && github.event_name != 'pull_request' uses: peter-evans/create-issue-from-file@v6 with: title: Link Checker Report content-filepath: ./lychee/out.md labels: report, automated issue ================================================ FILE: .github/workflows/linter.yaml ================================================ name: Lint Code Base on: pull_request: branches: [main] jobs: lint: name: Lint Code Base runs-on: ubuntu-latest permissions: contents: read packages: read statuses: write steps: - name: Checkout Code 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 }} 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 ================================================ FILE: .github/workflows/release-please.yml ================================================ on: push: branches: - main permissions: contents: write pull-requests: write name: release-please jobs: release-please: runs-on: ubuntu-latest if: github.repository_owner == 'a2aproject' steps: - uses: googleapis/release-please-action@v4 with: token: ${{ secrets.A2A_BOT_PAT }} release-type: simple ================================================ FILE: .github/workflows/sort-spelling-allowlist.yml ================================================ name: Auto-sort and update spelling allowlist on: pull_request: paths: - ".github/actions/spelling/allow.txt" types: - opened - synchronize - reopened jobs: sort_and_commit: name: Sort and Commit Allowlist runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout Code uses: actions/checkout@v6 with: repository: ${{ github.event.pull_request.head.repo.full_name }} ref: ${{ github.event.pull_request.head.ref }} persist-credentials: false - name: Sort allow.txt run: | bash scripts/sort_spelling.sh - name: Configure Git run: | git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - name: Check for changes id: git_status run: | if ! git diff --quiet .github/actions/spelling/allow.txt; then echo "changes=true" >> $GITHUB_OUTPUT fi - name: Commit and push changes if: steps.git_status.outputs.changes == 'true' && github.event.pull_request.head.repo.full_name == github.repository run: | git add .github/actions/spelling/allow.txt git commit -m "ci: sort and unique allow.txt" git push - name: Fail on fork with changes if: steps.git_status.outputs.changes == 'true' && github.event.pull_request.head.repo.full_name != github.repository run: | echo "::error::The 'allow.txt' file is not sorted correctly. Please run 'bash scripts/sort_spelling.sh' and commit the changes." exit 1 ================================================ FILE: .github/workflows/spelling.yaml ================================================ name: Check Spelling on: pull_request: branches: - "**" types: - "opened" - "reopened" - "synchronize" jobs: spelling: name: Check Spelling permissions: contents: read actions: read security-events: write outputs: followup: ${{ steps.spelling.outputs.followup }} if: ${{ contains(github.event_name, 'pull_request') || github.event_name == 'push' }} runs-on: ubuntu-latest concurrency: group: spelling-${{ github.event.pull_request.number || github.ref }} # note: If you use only_check_changed_files, you do not want cancel-in-progress cancel-in-progress: false steps: - name: check-spelling id: spelling uses: check-spelling/check-spelling@main with: suppress_push_for_open_pull_request: ${{ github.actor != 'dependabot[bot]' && 1 }} checkout: true check_file_names: 1 spell_check_this: check-spelling/spell-check-this@main post_comment: 0 use_magic_file: 1 report-timing: 1 warnings: bad-regex,binary-file,deprecated-feature,ignored-expect-variant,large-file,limited-references,no-newline-at-eof,noisy-file,non-alpha-in-dictionary,token-is-substring,unexpected-line-ending,whitespace-in-dictionary,minified-file,unsupported-configuration,no-files-to-check,unclosed-block-ignore-begin,unclosed-block-ignore-end experimental_apply_changes_via_bot: 1 dictionary_source_prefixes: '{"cspell": "https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/main/dictionaries/"}' extra_dictionaries: | cspell:aws/dict/aws.txt cspell:bash/samples/bash-words.txt cspell:companies/dict/companies.txt cspell:css/dict/css.txt cspell:data-science/dict/data-science-models.txt cspell:data-science/dict/data-science.txt cspell:data-science/dict/data-science-tools.txt cspell:en_shared/dict/acronyms.txt cspell:en_shared/dict/shared-additional-words.txt cspell:en_GB/en_GB.trie cspell:en_US/en_US.trie cspell:filetypes/src/filetypes.txt cspell:fonts/dict/fonts.txt cspell:fullstack/dict/fullstack.txt cspell:golang/dict/go.txt cspell:google/dict/google.txt cspell:html/dict/html.txt cspell:java/src/java.txt cspell:k8s/dict/k8s.txt cspell:mnemonics/dict/mnemonics.txt cspell:monkeyc/src/monkeyc_keywords.txt cspell:node/dict/node.txt cspell:npm/dict/npm.txt cspell:people-names/dict/people-names.txt cspell:python/dict/python.txt cspell:python/dict/python-common.txt cspell:shell/dict/shell-all-words.txt cspell:software-terms/dict/softwareTerms.txt cspell:software-terms/dict/webServices.txt cspell:sql/src/common-terms.txt cspell:sql/src/sql.txt cspell:sql/src/tsql.txt cspell:terraform/dict/terraform.txt cspell:typescript/dict/typescript.txt check_extra_dictionaries: "" only_check_changed_files: true longest_word: "10" ================================================ FILE: .github/workflows/stale.yaml ================================================ # This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time. # # You can adjust the behavior by modifying this file. # For more information, see: # https://github.com/actions/stale name: Mark stale issues and pull requests on: schedule: # Scheduled to run at 10.30PM UTC every day (1530PDT/1430PST) - cron: "30 22 * * *" workflow_dispatch: jobs: stale: runs-on: ubuntu-latest permissions: issues: write pull-requests: write actions: write steps: - uses: actions/stale@v10 with: repo-token: ${{ secrets.GITHUB_TOKEN }} days-before-issue-stale: 14 days-before-issue-close: 13 stale-issue-label: "status:stale" close-issue-reason: not_planned any-of-labels: "status:awaiting response,status:more data needed" stale-issue-message: > Marking this issue as stale since it has been open for 14 days with no activity. This issue will be closed if no further activity occurs. close-issue-message: > This issue was closed because it has been inactive for 27 days. Please post a new issue if you need further assistance. Thanks! days-before-pr-stale: 14 days-before-pr-close: 13 stale-pr-label: "status:stale" stale-pr-message: > Marking this pull request as stale since it has been open for 14 days with no activity. This PR will be closed if no further activity occurs. close-pr-message: > This pull request was closed because it has been inactive for 27 days. Please open a new pull request if you need further assistance. Thanks! # Label that can be assigned to issues to exclude them from being marked as stale exempt-issue-labels: "override-stale" # Label that can be assigned to PRs to exclude them from being marked as stale exempt-pr-labels: "override-stale" ================================================ FILE: .gitignore ================================================ # 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] *.pyc *$py.class **/dist /tmp /out-tsc /bazel-out # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build/ # PyBuilder target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. Pipfile.lock Pipfile # PEP 582; used by e.g. github.com/David-OConnor/pyflow __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .env .venv .venv* env/ venv/ ENV/ env.bak/ venv.bak/ # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json .ruff_cache/ # Pyre type checker .pyre/ # macOS .DS_Store # PyCharm .idea # User-specific files language/examples/prompt-design/train.csv README-TOC*.md # Terraform terraform.tfstate** .terraform* .Terraform* tmp* # Node **/node_modules npm-debug.log yarn-error.log # IDEs and editors .idea/ .project .classpath .c9/ *.launch .settings/ *.sublime-workspace # Miscellaneous **/.angular/* /.angular/cache .sass-cache/ /connect.lock /coverage /libpeerconnection.log testem.log /typings # System files .DS_Store Thumbs.db # Sphinx build artifacts docs/sdk/python/_build/ docs/sdk/python/api/ docs/sdk/python/generated/ specification/.googleapis/ ================================================ FILE: .gitvote.yml ================================================ # GitVote configuration file # # GitVote will look for it in the following locations (in order of precedence): # # - At the root of the repository where the vote was created # - At the root of the .github repository, for organization wide configuration # # Automation (optional) # # Create votes automatically on PRs when any of the files affected by the PR # match any of the patterns provided. Patterns must follow the gitignore # format (https://git-scm.com/docs/gitignore#_pattern_format). # # Each automation rule must include a list of patterns and the profile to use # when creating the vote. This allows creating votes automatically using the # desired configuration based on the patterns matched. Rules are processed in # the order provided, and the first match wins. # # automation: # enabled: true # rules: # - patterns: # - "README.md" # - "*.txt" # profile: default profiles: default: duration: 52w pass_threshold: 51 periodic_status_check: "1 day" allowed_voters: teams: - a2a-tsc exclude_team_maintainers: false close_on_passing: true announcements: discussions: category: announcements ================================================ FILE: .mkdocs/macros.py ================================================ """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:]) ================================================ FILE: .mkdocs/overrides/main.html ================================================ {% extends "base.html" %} {% block announce %} Join the new DeepLearning.AI short course: A2A: The Agent2Agent Protocol! Enroll for free {% endblock %} ================================================ FILE: .prettierrc ================================================ { "tabWidth": 2, "useTabs": false, "trailingComma": "es5", "bracketSameLine": true, "overrides": [ { "files": "*.md", "options": { "tabWidth": 4, "useTabs": false, "trailingComma": "es5" } } ] } ================================================ FILE: .ruff.toml ================================================ ################################################################################# # # Ruff linter and code formatter for A2A # # This file follows the standards in Google Python Style Guide # https://google.github.io/styleguide/pyguide.html line-length = 80 # Google Style Guide §3.2: 80 columns indent-width = 4 # Google Style Guide §3.4: 4 spaces target-version = "py312" # Minimum Python version [lint] ignore = [ "COM812", "FBT001", "FBT002", "D203", "D213", "ANN001", "ANN201", "ANN204", "D100", # Ignore Missing docstring in public module (often desired at top level __init__.py) "D102", # Ignore return type annotation in public method "D104", # Ignore Missing docstring in public package (often desired at top level __init__.py) "D107", # Ignore Missing docstring in __init__ (use class docstring) "TD002", # Ignore Missing author in TODOs (often not required) "TD003", # Ignore Missing issue link in TODOs (often not required/available) "T201", # Ignore print presence "RUF012", # Ignore Mutable class attributes should be annotated with `typing.ClassVar` "RUF013", # Ignore implicit optional ] select = [ "E", # pycodestyle errors (PEP 8) "W", # pycodestyle warnings (PEP 8) "F", # Pyflakes (logical errors, unused imports/variables) "I", # isort (import sorting - Google Style §3.1.2) "D", # pydocstyle (docstring conventions - Google Style §3.8) "N", # pep8-naming (naming conventions - Google Style §3.16) "UP", # pyupgrade (use modern Python syntax) "ANN",# flake8-annotations (type hint usage/style - Google Style §2.22) "A", # flake8-builtins (avoid shadowing builtins) "B", # flake8-bugbear (potential logic errors & style issues - incl. mutable defaults B006, B008) "C4", # flake8-comprehensions (unnecessary list/set/dict comprehensions) "ISC",# flake8-implicit-str-concat (disallow implicit string concatenation across lines) "T20",# flake8-print (discourage `print` - prefer logging) "SIM",# flake8-simplify (simplify code, e.g., `if cond: return True else: return False`) "PTH",# flake8-use-pathlib (use pathlib instead of os.path where possible) "PL", # Pylint rules ported to Ruff (PLC, PLE, PLR, PLW) "PIE",# flake8-pie (misc code improvements, e.g., no-unnecessary-pass) "RUF",# Ruff-specific rules (e.g., RUF001-003 ambiguous unicode) "RET",# flake8-return (consistency in return statements) "SLF",# flake8-self (check for private member access via `self`) "TID",# flake8-tidy-imports (relative imports, banned imports - configure if needed) "YTT",# flake8-boolean-trap (checks for boolean positional arguments, truthiness tests - Google Style §3.10) "TD", # flake8-todos (check TODO format - Google Style §3.7) ] exclude = [ ".bzr", ".direnv", ".eggs", ".git", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "build", "dist", "node_modules", "venv", "*/migrations/*", ] [lint.isort] #force-sort-within-sections = true #combine-as-imports = true case-sensitive = true #force-single-line = false #known-first-party = [] #known-third-party = [] lines-after-imports = 2 lines-between-types = 1 #no-lines-before = ["LOCALFOLDER"] #required-imports = [] #section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"] [lint.pydocstyle] convention = "google" [lint.flake8-annotations] mypy-init-return = true allow-star-arg-any = false [lint.pep8-naming] ignore-names = ["test_*", "setUp", "tearDown", "mock_*"] classmethod-decorators = ["classmethod", "pydantic.validator", "pydantic.root_validator"] staticmethod-decorators = ["staticmethod"] [lint.flake8-tidy-imports] ban-relative-imports = "all" # Google generally prefers absolute imports (§3.1.2) [lint.flake8-quotes] docstring-quotes = "double" inline-quotes = "single" [lint.per-file-ignores] "__init__.py" = ["F401"] # Ignore unused imports in __init__.py "*_test.py" = ["D", "ANN"] # Ignore docstring and annotation issues in test files "test_*.py" = ["D", "ANN"] # Ignore docstring and annotation issues in test files [format] docstring-code-format = true docstring-code-line-length = "dynamic" # Or set to 80 quote-style = "single" indent-style = "space" ================================================ FILE: .vscode/settings.json ================================================ { "editor.formatOnSave": true, "[python]": { "editor.defaultFormatter": "charliermarsh.ruff", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.organizeImports": "explicit" } }, "ruff.importStrategy": "fromEnvironment", "markdownlint.configFile": ".github/linters/.markdownlint.json", "[json]": { "editor.defaultFormatter": "vscode.json-language-features", "editor.formatOnSave": true }, "files.trimTrailingWhitespace": true, "files.insertFinalNewline": true, "codeQL.githubDatabase.download": "never" } ================================================ FILE: CHANGELOG.md ================================================ # Changelog ## [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 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) ### ⚠ BREAKING CHANGES * Add mTLS to SecuritySchemes, add oauth2 metadata url field, allow Skills to specify Security ([#901](https://github.com/a2aproject/A2A/issues/901)) * Change Well-Known URI for Agent Card hosting from `agent.json` to `agent-card.json` ([#841](https://github.com/a2aproject/A2A/issues/841)) * Add method for fetching extended card ([#929](https://github.com/a2aproject/A2A/issues/929)) ### Features * Add `signatures` to the `AgentCard` ([#917](https://github.com/a2aproject/A2A/issues/917)) ([ef4a305](https://github.com/a2aproject/A2A/commit/ef4a30505381e99b20103724cabef024389bacef)) * Add method for fetching extended card ([#929](https://github.com/a2aproject/A2A/issues/929)) ([2cd7d98](https://github.com/a2aproject/A2A/commit/2cd7d98bc8566601b9a18ca8afe92a0b4d203248)) * Add mTLS to SecuritySchemes, add oauth2 metadata url field, allow Skills to specify Security ([#901](https://github.com/a2aproject/A2A/issues/901)) ([e162c0c](https://github.com/a2aproject/A2A/commit/e162c0c6c4f609d2f4eef9042466d176ec75ebda)) ### Bug Fixes * **spec:** Add `SendMessageRequest.request` `json_name` mapping to `message` ([#904](https://github.com/a2aproject/A2A/issues/904)) ([2eef3f6](https://github.com/a2aproject/A2A/commit/2eef3f6113851e690cee70a1b1643e1ffd6d2a60)) * **spec:** Add Transport enum to specification ([#909](https://github.com/a2aproject/A2A/issues/909)) ([e834347](https://github.com/a2aproject/A2A/commit/e834347c279186d9d7873b352298e8b19737dd5a)) ### Code Refactoring * Change Well-Known URI for Agent Card hosting from `agent.json` to `agent-card.json` ([#841](https://github.com/a2aproject/A2A/issues/841)) ([0858ddb](https://github.com/a2aproject/A2A/commit/0858ddb884dc4671681fd819648dfd697176abb3)) ## [0.2.6](https://github.com/a2aproject/A2A/compare/v0.2.5...v0.2.6) (2025-07-17) ### Bug Fixes * Type fix and doc clarification ([#877](https://github.com/a2aproject/A2A/issues/877)) ([6f1d17b](https://github.com/a2aproject/A2A/commit/6f1d17ba806c32f2b6fbe465be93ec13bfe7d83c)) * Update json names of gRPC objects for proper transcoding ([#847](https://github.com/a2aproject/A2A/issues/847)) ([6ba72f0](https://github.com/a2aproject/A2A/commit/6ba72f0d51c2e3d0728f84e9743b6d0e88730b51)) ## [0.2.5](https://github.com/a2aproject/A2A/compare/v0.2.4...v0.2.5) (2025-06-30) ### ⚠ BREAKING CHANGES * **spec:** Add a required protocol version to the agent card. ([#802](https://github.com/a2aproject/A2A/issues/802)) * Support for multiple pushNotification config per task ([#738](https://github.com/a2aproject/A2A/issues/738)) ([f355d3e](https://github.com/a2aproject/A2A/commit/f355d3e922de61ba97873fe2989a8987fc89eec2)) ### Features * **spec:** Add a required protocol version to the agent card. ([#802](https://github.com/a2aproject/A2A/issues/802)) ([90fa642](https://github.com/a2aproject/A2A/commit/90fa64209498948b329a7b2ac6ec38942369157a)) * **spec:** Support for multiple pushNotification config per task ([#738](https://github.com/a2aproject/A2A/issues/738)) ([f355d3e](https://github.com/a2aproject/A2A/commit/f355d3e922de61ba97873fe2989a8987fc89eec2)) ### Documentation * update spec & doc topic with non-restartable tasks ([#770](https://github.com/a2aproject/A2A/issues/770)) ([ebc4157](https://github.com/a2aproject/A2A/commit/ebc4157ca87ae08d1c55e38e522a1a17201f2854)) ## [0.2.4](https://github.com/a2aproject/A2A/compare/v0.2.3...v0.2.4) (2025-06-30) ### Features * feat: Add support for multiple transport announcement in AgentCard ([#749](https://github.com/a2aproject/A2A/issues/749)) ([b35485e](https://github.com/a2aproject/A2A/commit/b35485e02e796d15232dec01acfab93fc858c3ec)) ## [0.2.3](https://github.com/a2aproject/A2A/compare/v0.2.2...v0.2.3) (2025-06-12) ### Bug Fixes * Address some typos in gRPC annotations ([#747](https://github.com/a2aproject/A2A/issues/747)) ([f506881](https://github.com/a2aproject/A2A/commit/f506881c9b8ff0632d7c7107d5c426646ae31592)) ## [0.2.2](https://github.com/a2aproject/A2A/compare/v0.2.1...v0.2.2) (2025-06-09) ### ⚠ BREAKING CHANGES * Resolve spec inconsistencies with JSON-RPC 2.0 ### Features * Add gRPC and REST definitions to A2A protocol specifications ([#695](https://github.com/a2aproject/A2A/issues/695)) ([89bb5b8](https://github.com/a2aproject/A2A/commit/89bb5b82438b74ff7bb0fafbe335db7100a0ac57)) * Add protocol support for extensions ([#716](https://github.com/a2aproject/A2A/issues/716)) ([70f1e2b](https://github.com/a2aproject/A2A/commit/70f1e2b0c68a3631888091ce9460a9f7fbfbdff2)) * **spec:** Add an optional iconUrl field to the AgentCard ([#687](https://github.com/a2aproject/A2A/issues/687)) ([9f3bb51](https://github.com/a2aproject/A2A/commit/9f3bb51257f008bd878d85e00ec5e88357016039)) ### Bug Fixes * 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) ### Features * Add a new boolean for supporting authenticated extended cards ([#618](https://github.com/a2aproject/A2A/issues/618)) ([e0a3070](https://github.com/a2aproject/A2A/commit/e0a3070fc289110d43faf2e91b4ffe3c29ef81da)) * Add optional referenceTaskIds for task followups ([#608](https://github.com/a2aproject/A2A/issues/608)) ([5368e77](https://github.com/a2aproject/A2A/commit/5368e7728cb523caf1a9218fda0b1646325f524b)) ================================================ FILE: CODE_OF_CONDUCT.md ================================================ # Code of Conduct ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: * Using welcoming and inclusive language * Being respectful of differing viewpoints and experiences * Gracefully accepting constructive criticism * Focusing on what is best for the community * Showing empathy towards other community members Examples of unacceptable behavior by participants include: * The use of sexualized language or imagery and unwelcome sexual attention or advances * Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or electronic address, without explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. This Code of Conduct also applies outside the project spaces when the Project Steward has a reasonable belief that an individual's behavior may have a negative impact on the project or its community. ## Conflict Resolution We do not believe that all conflict is bad; healthy debate and disagreement often yield positive results. However, it is never okay to be disrespectful or to engage in behavior that violates the project’s code of conduct. If you see someone violating the code of conduct, you are encouraged to address the behavior directly with those involved. Many issues can be resolved quickly and easily, and this gives people more control over the outcome of their dispute. If you are unable to resolve the matter for any reason, or if the behavior is threatening or harassing, report it. We are dedicated to providing 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. 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 incidents, which may range from not taking action to permanent expulsion from the project and project-sponsored spaces. We will notify the accused of the report and provide them an opportunity to discuss it before any action is taken. The identity of the reporter will be omitted from the details of the report supplied to the accused. In potentially harmful situations, such as ongoing harassment or threats to anyone's safety, we may take action without notice. ## Attribution 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/ ================================================ FILE: CONTRIBUTING.md ================================================ # How to contribute We'd love to accept your patches and contributions to this project. ## Contribution process ### Code reviews All submissions, including submissions by project members, require review. We 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 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. 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. ================================================ FILE: GOVERNANCE.md ================================================ # Agent2Agent (A2A) Governance The Agent2Agent project is governed by the Technical Steering Committee. The Committee has eight seats, each held by the following companies: | Company | Representative | Title | Contact | | :--- | :--- | :--- | :--- | | **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** | 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) | ## Mission and Scope of the Project 1. The mission of the Project is to help AI agents across different ecosystems communicate with each other. The Project includes collaborative development of the following components: 1. the Agent2Agent Protocol (the "Protocol"); 2. a SDK for designing implementations of the Protocol and related software components; and 3. documentation and other artifacts related to the Project. 2. The scope of the Project includes collaborative development under the Project License (as defined herein) supporting the mission, including documentation, testing, integration and the creation of other artifacts that aid the development, deployment, operation or adoption of the open source project. ## Technical Steering Committee 1. The Technical Steering Committee (the "TSC") will be responsible for all technical oversight of the open source Project. 2. **TSC Composition** 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, 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. 3. TSC projects generally will involve Contributors and Maintainers. The TSC may adopt or modify roles so long as the roles are documented in the CONTRIBUTING file. Unless otherwise documented: a. **Contributors** include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project; b. **Maintainers** are Contributors who have earned the ability to modify ("commit") source code, documentation or other technical artifacts in a project's repository; and c. A Contributor may become a Maintainer by a vote of the TSC. A Maintainer may be removed by a vote of the TSC. d. Participation in the Project through becoming a Contributor and Maintainer is open to anyone so long as they abide by the terms of this Charter. 4. The TSC may: 1. establish work flow procedures for the submission, approval, and closure/archiving of projects, 2. set requirements for the promotion of Contributors to Maintainer status, as applicable, and 3. amend, adjust, refine and/or eliminate the roles of Contributors, and Maintainer, and create new roles, and publicly document any TSC roles, as it sees fit. 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 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; 8. discussions, seeking consensus, and where necessary, voting on technical matters relating to the code base that affect multiple projects; and 9. coordinating any marketing, events, or communications regarding the Project. ### 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. 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 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 The A2A project utilizes Discord for chat conversations about the project. All are welcome and encouraged to join the [A2A Discord](http://discord.gg/a2aprotocol). Discussion is encouraged however we do remind the community that chat is ephemeral, and not all members of the project are active in chat at the same time. Therefore, any discussions about feature proposals, significant changes to the project architecture or governance, etc. should be held in GitHub with adequate notice and time for comment. Look for specifics on that timing coming soon as the TSC ramps up. Just keep in mind - our goal is that GitHub is the source of truth for significant project decisions. Additional communication avenues will likely be added - stay tuned. ================================================ FILE: LICENSE ================================================ Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================ FILE: MAINTAINERS.md ================================================ # Maintainers This document lists the maintainers of various repositories within the project. ## Repository Maintainers ### a2a-dotnet - role:maintain - @aalina23 - @adamsitnik - @Blackhex - @iremyux - @karelz - @rokonec - role:admin - @brandonh-msft - @darrelmiller - @markwallace-microsoft - @SergeyMenshykh - @stephentoub ### a2a-go - role:maintain - @yarolegovich - role:admin - @hyangah - @mazas-google ### a2a-java - role:maintain - @Doris26 - @ehsavoie - @kabir - @maeste - role:admin - @ddobrin - @fjuma - @holtskinner ### a2a-js - role:admin - @swapydapy ### a2a-python - role:maintain - @aneeshgarg - @chitra-venkatesh - @dmandar - @holtskinner - @kthota-g - @lkawka - @mikeas1 - @mindpower - @mvakoc - @pstephengoogle - @pwwpche - @rajeshvelicheti - @swapydapy - @ToddSegal - role:admin - @DJ-os - @holtskinner - @koverholt - @kthota-g - @ToddSegal - @zeroasterisk ### a2a-samples - role:admin - @zeroasterisk - @holtskinner - @kthota-g ================================================ FILE: README.md ================================================ # Agent2Agent (A2A) Protocol [![PyPI - Version](https://img.shields.io/pypi/v/a2a-sdk)](https://pypi.org/project/a2a-sdk) [![Apache License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) Ask Code Wiki
🌐 Language
Agent2Agent Protocol Logo

Agent2Agent (A2A) Protocol

**An open protocol enabling communication and interoperability between opaque agentic applications.** The Agent2Agent (A2A) protocol addresses a critical challenge in the AI landscape: enabling gen AI agents, built on diverse frameworks by different companies running on separate servers, to communicate and collaborate effectively - as agents, not just as tools. A2A aims to provide a common language for agents, fostering a more interconnected, powerful, and innovative AI ecosystem. With A2A, agents can: - Discover each other's capabilities. - Negotiate interaction modalities (text, forms, media). - Securely collaborate on long-running tasks. - Operate without exposing their internal state, memory, or tools. ## DeepLearning.AI Course [![A2A DeepLearning.AI](https://img.youtube.com/vi/4gYm0Rp7VHc/maxresdefault.jpg)](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? As AI agents become more prevalent, their ability to interoperate is crucial for building complex, multi-functional applications. A2A aims to: - **Break Down Silos:** Connect agents across different ecosystems. - **Enable Complex Collaboration:** Allow specialized agents to work together on tasks that a single agent cannot handle alone. - **Promote Open Standards:** Foster a community-driven approach to agent communication, encouraging innovation and broad adoption. - **Preserve Opacity:** Allow agents to collaborate without needing to share internal memory, proprietary logic, or specific tool implementations, enhancing security and protecting intellectual property. ### Key Features - **Standardized Communication:** JSON-RPC 2.0 over HTTP(S). - **Agent Discovery:** Via "Agent Cards" detailing capabilities and connection info. - **Flexible Interaction:** Supports synchronous request/response, streaming (SSE), and asynchronous push notifications. - **Rich Data Exchange:** Handles text, files, and structured JSON data. - **Enterprise-Ready:** Designed with security, authentication, and observability in mind. ## Getting Started - 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://a2a-protocol.org) for a complete overview, the full protocol specification, tutorials, and guides. - 📝 **View the Specification:** [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/) - Use the SDKs: - [🐍 A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk` - [🐿️ A2A Go SDK](https://github.com/a2aproject/a2a-go) `go get github.com/a2aproject/a2a-go` - [🧑‍💻 A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk` - [☕️ A2A Java SDK](https://github.com/a2aproject/a2a-java) using maven - [🔷 A2A .NET SDK](https://github.com/a2aproject/a2a-dotnet) using [NuGet](https://www.nuget.org/packages/A2A) `dotnet add package A2A` - 🎬 Use our [samples](https://github.com/a2aproject/a2a-samples) to see A2A in action ## Contributing We welcome community contributions to enhance and evolve the A2A protocol! - **Questions & Discussions:** Join our [GitHub Discussions](https://github.com/a2aproject/A2A/discussions). - **Issues & Feedback:** Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues). - **Contribution Guide:** See our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute. - **Private Feedback:** Use this [Google Form](https://goo.gle/a2a-feedback). - **Partner Program:** Google Cloud customers can join our partner program via this [form](https://goo.gle/a2a-partner). ## What's next ### Protocol Enhancements - **Agent Discovery:** - Formalize inclusion of authorization schemes and optional credentials directly within the `AgentCard`. - **Agent Collaboration:** - Investigate a `QuerySkill()` method for dynamically checking unsupported or unanticipated skills. - **Task Lifecycle & UX:** - Support for dynamic UX negotiation _within_ a task (e.g., agent adding audio/video mid-conversation). - **Client Methods & Transport:** - Explore extending support to client-initiated methods (beyond task management). - Improvements to streaming reliability and push notification mechanisms. ## About 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. ================================================ FILE: SECURITY.md ================================================ # Security Policy To report a security issue, please use email . 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. ================================================ FILE: adrs/adr-001-protojson-serialization.md ================================================ # 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. ================================================ FILE: adrs/adr-template.md ================================================ # 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] ================================================ FILE: docs/404.html ================================================ Redirecting...

A2A - Page Not Found

We are attempting to redirect you to the latest version of this page.

If you are not redirected automatically, please navigate to the A2A project homepage.

================================================ FILE: docs/README.md ================================================ # A2A Docs ## Developing A2A docs 1. Clone this repository and `cd` into the repository directory 2. Run `pip install -r requirements-docs.txt` 3. Run `mkdocs serve`, edit `.md` files, and live preview 4. Contribute docs changes as usual ## How it works - The A2A docs use [mkdocs](https://www.mkdocs.org/) and the [mkdocs-material theme](https://squidfunk.github.io/mkdocs-material/) - All of the source documentation / Markdown files related to the A2A docs are in the `docs/` directory in the A2A repository - `mkdocs.yml` in the repository root contains all of the docs config, including the site navigation and organization - There is a GitHub Action in `.github/workflows/docs.yml` that builds and publishes the docs and pushes the built assets to the `gh-pages` branch in this repository using `mkdocs gh-deploy --force`. This happens automatically for all commits / merges to `main`. - The A2A documentation is hosted in GitHub pages, and the settings for this are in the A2A repository settings in GitHub. ## Building the Python SDK Documentation The Python SDK documentation is built using [Sphinx](https://www.sphinx-doc.org/). ### Prerequisites Ensure you have installed the documentation dependencies: ```bash pip install -r ../../requirements-docs.txt ``` ### Building the Docs 1. Run the following command to build the HTML documentation: ```bash sphinx-build -b html docs/sdk/python docs/sdk/python/api ``` 2. The generated HTML files will be in the `sdk/python/api` directory. You can open `sdk/python/api/index.html` in your browser to view the documentation. ================================================ FILE: docs/announcing-1.0.md ================================================ # 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) ================================================ FILE: docs/community.md ================================================ # A2A Community Hub Welcome to the official community hub for the **Agent2Agent (A2A) protocol**! A2A is an open, standardized protocol that enables seamless interoperability and collaboration between AI agents across all frameworks and vendors. --- ## Recent News & Blog Posts Stay up-to-date with the latest announcements, tutorials, and insights from the A2A team and our community. - **[Announcing Agent Payments Protocol (AP2)](https://cloud.google.com/blog/products/ai-machine-learning/announcing-agent-payments-protocol-ap2)** - *September 16* - **[A2A Extensions Empowering Custom Agent Functionality](https://developers.googleblog.com/en/a2a-extensions-empowering-custom-agent-functionality/)** - *September 9* - **[A2A protocol: Demystifying Tasks vs Messages](https://discuss.google.dev/t/a2a-protocol-demystifying-tasks-vs-messages/255879)** - *August 18* - **[End-to-end evaluation of multi-agent systems on Vertex AI](https://discuss.google.dev/t/end-to-end-evaluation-of-multi-agent-systems-on-vertex-ai-with-cloud-run-deployment-for-a2a-agents/250552)** - *August 7* - **[Agent2Agent (A2A) protocol is getting an upgrade](https://cloud.google.com/blog/products/ai-machine-learning/agent2agent-protocol-is-getting-an-upgrade?e=48754805)** - *July 26* --- ## 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: - **Multi-Agent Workflows:** Chain specialized agents together to automate complex processes, like candidate sourcing for hiring or streamlining supply chain logistics. - **Agent Marketplaces:** Create platforms where agents can discover and utilize the capabilities of other agents from different providers. - **Cross-Platform Integration:** Connect agents built on different frameworks—like LangGraph, BeeAI, and more—to work together seamlessly. - **Evaluating Multi-Agent Systems:** Use frameworks like Vertex AI to assess the performance and success of collaborative agent trajectories. --- ## Community Spotlight ### Featured Contributions A2A is an open-source protocol, and we thrive on community contributions. A huge thank you to everyone who has helped build and improve A2A! Here are some recent highlights: - [Python Quickstart Tutorial (PR#202)](https://github.com/a2aproject/A2A/pull/202) - [LlamaIndex sample implementation (PR#179)](https://github.com/a2aproject/A2A/pull/179) - [Autogen sample server (PR#232)](https://github.com/a2aproject/A2A/pull/232) - [AG2 + MCP example (PR#230)](https://github.com/a2aproject/A2A/pull/230) - [PydanticAI example (PR#127)](https://github.com/a2aproject/A2A/pull/127) ### The Word on the Street The launch of A2A has sparked lively discussions and positive reactions across various social and video platforms. - **Microsoft's Semantic Kernel:** Asha Sharma, Head of AI Platform Product at Microsoft, [announced on LinkedIn](https://www.linkedin.com/posts/aboutasha_a2a-ugcPost-7318649411704602624-0C_8) that "Semantic Kernel now speaks A2A," enabling instant, secure interoperability. - **Matt Pocock's Diagramming:** Well-known developer educator Matt Pocock [shared diagrams on X](https://x.com/mattpocockuk/status/1910002033018421400) explaining the A2A protocol, which were liked and reposted hundreds of times. - **Craig McLuckie's "Hot Take":** Craig McLuckie shared his thoughts on [LinkedIn](https://www.linkedin.com/posts/craigmcluckie_hot-take-on-agent2agent-vs-mcp-google-just-activity-7315939233792176128-4rGQ), highlighting A2A's focus on interactions *between* agentic systems as a sensible approach. - **Zachary Huang's Deep Dive:** In his [YouTube video](https://www.youtube.com/watch?v=wrCF8MoXC_I), Zachary explains how A2A complements MCP, with A2A handling communication between agents and MCP connecting agents to tools. --- ## A2A Integrations 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) - [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/) ## The Future is Interoperable The excitement surrounding Google's A2A protocol clearly indicates a strong belief in its potential to revolutionize multi-agent AI systems. By providing a standardized way for AI agents to communicate and collaborate, A2A is poised to unlock new levels of automation and innovation. As enterprises increasingly adopt AI agents, A2A represents a crucial step towards realizing the full power of interconnected AI ecosystems. **Join the growing community building the future of AI interoperability with A2A!** ================================================ FILE: docs/definitions.md ================================================ # A2A Definition/Schema === "Protobuf"

Protobuf

The normative A2A protocol definition in Protocol Buffers (proto3 syntax). This is the source of truth for the A2A protocol specification.

Download

You can download the proto file directly: [`a2a.proto`](spec/a2a.proto)

Definition

```protobuf --8<-- "docs/spec/a2a.proto" ``` === "JSON"

JSON

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.

Download

You can download the schema file directly: [`a2a.json`](spec/a2a.json)

Definition

```json --8<-- "docs/spec/a2a.json" ``` ================================================ FILE: docs/index.md ================================================ --- hide: - toc ---
Agent2Agent Protocol Logo

Agent2Agent (A2A) Protocol

## What is A2A Protocol? Welcome to the **official documentation** for the **Agent2Agent (A2A) Protocol**, an open standard designed to enable seamless communication and collaboration between AI agents. Originally developed by Google and now donated to the Linux Foundation, A2A provides the definitive common language for agent interoperability in a world where agents are built using diverse frameworks and by different vendors. !!! abstract "" Build with **[![ADK Logo](https://google.github.io/adk-docs/assets/agent-development-kit.png){class="twemoji lg middle"} ADK](https://google.github.io/adk-docs/)** _(or any framework)_, equip with **[![MCP Logo](https://modelcontextprotocol.io/mcp.png){class="twemoji lg middle"} MCP](https://modelcontextprotocol.io)** _(or any tool)_, and communicate with **![A2A Logo](./assets/a2a-logo-black.svg){class="twemoji lg middle"} A2A**, to remote agents, local agents, and humans. ## Get started with A2A
- :material-play-circle:{ .lg .middle } **Video** Intro in <8 min - :material-play-circle:{ .lg .middle } **Course** [DeepLearning.AI](https://deeplearning.ai) - Intro to A2A [![A2A DeepLearning.AI](https://img.youtube.com/vi/4gYm0Rp7VHc/maxresdefault.jpg)](https://goo.gle/dlai-a2a) - :material-book-open:{ .lg .middle } **Read the Introduction** Understand the core ideas behind A2A. [:octicons-arrow-right-24: What is A2A?](./topics/what-is-a2a.md) [:octicons-arrow-right-24: Key Concepts](./topics/key-concepts.md) - :material-file-document-outline:{ .lg .middle } **Dive into the Specification** Explore the detailed technical definition of the A2A protocol. [:octicons-arrow-right-24: Protocol Specification](./specification.md) - :material-application-cog-outline:{ .lg .middle } **Follow the Tutorials** Build your first A2A-compliant agent with our step-by-step Python quickstart. [: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. [:fontawesome-brands-github: GitHub Samples](https://github.com/a2aproject/a2a-samples) - :material-code-braces:{ .lg .middle } **Download the Official SDKs** [:fontawesome-brands-python: Python](https://github.com/a2aproject/a2a-python) [:fontawesome-brands-js: JavaScript](https://github.com/a2aproject/a2a-js) [:fontawesome-brands-java: Java](https://github.com/a2aproject/a2a-java) [:octicons-code-24: C#/.NET](https://github.com/a2aproject/a2a-dotnet) [:fontawesome-brands-golang: Golang](https://github.com/a2aproject/a2a-go)
## Why use the A2A Protocol
```mermaid graph LR User(🧑‍💻 User) <--> ClientAgent(🤖 Client Agent) ClientAgent --> A2A1(**↔️ A2A**) --> RemoteAgent1(🤖 Remote Agent 1) ClientAgent --> A2A2(**↔️ A2A**) --> RemoteAgent2(🤖 Remote Agent 2) style User fill:#fdebd0,stroke:#e67e22,stroke-width:2px style ClientAgent fill:#d6eaf8,stroke:#3498db,stroke-width:2px style RemoteAgent1 fill:#d6eaf8,stroke:#3498db,stroke-width:2px style RemoteAgent2 fill:#d6eaf8,stroke:#3498db,stroke-width:2px style A2A1 fill:#ebedef,stroke:#909497,stroke-width:2px style A2A2 fill:#ebedef,stroke:#909497,stroke-width:2px ```
- :material-account-group-outline:{ .lg .middle } **Interoperability** Connect agents built on different platforms (LangGraph, CrewAI, Semantic Kernel, custom solutions) to create powerful, composite AI systems. - :material-lan-connect:{ .lg .middle } **Complex Workflows** Enable agents to delegate sub-tasks, exchange information, and coordinate actions to solve complex problems that a single agent cannot. - :material-shield-key-outline:{ .lg .middle } **Secure & Opaque** Agents interact without needing to share internal memory, tools, or proprietary logic, ensuring security and preserving intellectual property.
--- ## How does A2A work with MCP? ![A2A MCP Graphic](assets/a2a-mcp-readme.png){width="60%"} {style="text-align: center; margin-bottom:1em; margin-top:1em;"} A2A and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) are complementary standards for building robust agentic applications: - **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 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. ================================================ FILE: docs/llms.txt ================================================ # A2A (Agent2Agent) Protocol High-Level Summary 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 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. ## Key Files & Directories - `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 Reference ## 1. Overview - **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. Core Data Objects ### 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`). ### 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.3 TaskState (Enum) - `SUBMITTED`, `WORKING`, `COMPLETED` (terminal), `FAILED` (terminal), `CANCELED` (terminal), `REJECTED` (terminal), `INPUT_REQUIRED` (interrupted), `AUTH_REQUIRED` (interrupted). ### 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.5 Artifact - A tangible output from a task, containing one or more `Part`s and metadata. ## 3. RPC Methods | 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. | ### 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). ## 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. ## 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. ================================================ FILE: docs/partners.md ================================================ # Partners Below is a list of partners (and a link to their A2A announcement or blog post, if available) who are part of the A2A community and are helping build, codify, and adopt A2A as the standard protocol for AI agents to communicate and collaborate effectively with each other and with users. - [A2A Net](https://a2anet.com) - [Accelirate Inc](https://www.accelirate.com) - [Accenture](https://www.accenture.com) - [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/) - [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) - [ask-ai.com](https://ask-ai.com) - [Atlassian](https://www.atlassian.com) - [Auth0](https://auth0.com/blog/auth0-google-a2a/) - [Autodesk](https://www.autodesk.com) - [AWS](https://aws.amazon.com/) - [Beekeeper](http://beekeeper.io) - [BCG](https://www.bcg.com) - [Block Inc](https://block.xyz/) - [Bloomberg LP](https://techatbloomberg.com/) - [BLUEISH Inc](https://www.blueish.co.jp/) - [BMC Software Inc](https://www.bmc.com/it-solutions/bmc-helix.html) - [Boomi](https://boomi.com/) - [Box](https://www.box.com) - [Bridge2Things Automation Process GmbH](http://bridge2things.at) - [Cafe 24](https://www.cafe24corp.com/en/company/about) - [C3 AI](https://c3.ai) - [Capgemini](https://www.capgemini.com) - [Chronosphere](https://chronosphere.io) - [Cisco](https://www.cisco.com/) - [Codimite PTE LTD](https://codimite.ai/) - [Cognigy](https://www.cognigy.com/) - [Cognizant](https://www.cognizant.com) - [Cohere](https://cohere.com) - [Collibra](https://www.collibra.com) - [Confluent](https://developer.confluent.io) - [Contextual](https://contextual.ai) - [Cotality](https://cotality.com) (fka Corelogic) - [Crubyt](https://www.crubyt.com) - [Cyderes](http://www.cyderes.com) - [Datadog](https://www.datadoghq.com) - [DataRobot](https://www.datarobot.com) - [DataStax](https://www.datastax.com) - [Decagon.ai](https://decagon.ai) - [Deloitte](https://www.prnewswire.com/news-releases/deloitte-expands-alliances-with-google-cloud-and-servicenow-to-accelerate-agentic-ai-adoption-in-the-enterprise-302423941.html) - [Devnagri](https://devnagri.com) - [Deutsche Telekom](https://www.telekom.com/en) - [Dexter Tech Labs](http://www.dextertechlabs.com) - [Distyl.ai](https://distyl.ai) - [Elastic](https://www.elastic.co) - [Ema.co](https://ema.co) - [EPAM](https://www.epam.com) - [Eviden (Atos Group)](https://atos.net/) - [fractal.ai](https://fractal.ai/new) - [GenAI Nebula9.ai Solutions Pvt Ltd](http://nebula9.ai) - [Glean](https://www.glean.com) - [Global Logic](https://www.globallogic.com/) - [Gravitee](https://www.gravitee.io/) - [GrowthLoop](https://growthloop.com) - [Guru](http://www.getguru.com) - [Harness](https://harness.io) - [HCLTech](https://www.hcltech.com) - [Headwaters](https://www.headwaters.co.jp) - [Hellotars](https://hellotars.com) - [Hexaware](https://hexaware.com/) - [HUMAN](https://www.humansecurity.com/) - [IBM Research](https://lfaidata.foundation/communityblog/2025/08/29/acp-joins-forces-with-a2a-under-the-linux-foundations-lf-ai-data/) - [Incorta](https://www.incorta.com) - [Infinitus](https://www.infinitus.ai/) - [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) - [King's College London](https://www.kcl.ac.uk/informatics) - [KPMG](https://kpmg.com/us/en/media/news/kpmg-google-cloud-alliance-expansion-agentspace-adoption.html) - [Kyndryl](http://www.kyndryl.com) - [LabelBox](https://labelbox.com) - [LangChain](https://www.langchain.com) - [LG CNS](http://www.lgcns.com) - [Livex.ai](https://livex.ai) - [LlamaIndex](https://x.com/llama_index/status/1912949446322852185) - [LTIMindTtree](https://www.ltimindtree.com) - [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) - [MongoDB](https://www.mongodb.com) - [Monite](https://monite.com/) - [Neo4j](https://neo4j.com) - [New Relic](https://newrelic.com) - [Nisum](http://www.nisum.com) - [Noorle Inc](http://www.noorle.com) - [NTT DATA](https://www.nttdata.com) - [Optimizely Inc](https://www.optimizely.com/) - [Oracle / NetSuite](https://www.oracle.com/netsuite) - [Palo Alto Networks](https://www.paloaltonetworks.com/) - [PancakeAI](https://www.pancakeai.tech/) - [ParkourSC](https://www.parkoursc.com/) - [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) - [Publicis Sapient](https://www.publicissapient.com/) - [PWC](https://www.pwc.com) - [Quantiphi](https://www.quantiphi.com) - [Radix](https://radix.website/) - [RagaAI Inc](https://raga.ai/) - [Red Hat](https://www.redhat.com) - [Reltio Inc](http://www.reltio.com) - [S&P](https://www.spglobal.com) - [Sage](https://www.sage.com/en-us/) - [Salesforce](https://www.salesforce.com) - [SAP](https://news.sap.com/2025/04/sap-google-cloud-enterprise-ai-open-agent-collaboration-model-choice-multimodal-intelligence/) - [Sayone Technologies](https://www.sayonetech.com/) - [ServiceNow](https://www.servicenow.com) - [Siemens AG](https://siemens.com/) - [SoftBank Corp](https://www.softbank.jp/en//) - [Solace](https://solace.com/products/agent-mesh/) - [Solo.io](https://www.solo.io/) - [Stacklok, Inc](https://stacklok.com) - [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) - [Tech Mahindra](https://www.techmahindra.com/) - [Telefonica](https://www.telefonica.com/) - [Test Innovation Technology](https://www.test-it.com) - [the artinet project](https://artinet.io/) - [Think41](http://www.think41.com) - [Thoughtworks](https://www.thoughtworks.com/) - [Tredence](http://www.tredence.com) - [Two Tall Totems Ltd. DBA TTT Studios](https://ttt.studio) - [Typeface](https://typeface.ai) - [UKG](https://www.ukg.com) - [UiPath](https://www.uipath.com/newsroom/uipath-launches-first-enterprise-grade-platform-for-agentic-automation) - [Upwork, Inc.](https://www.upwork.com/) - [Ushur, Inc.](http://ushur.ai) - [Valle AI](http://www.valleai.com.br) - [Valtech](https://www.valtech.com/) - [Vervelo](https://www.vervelo.com/) - [VoltAgent](https://voltagent.dev/) - [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) - [Zocket Technologies , Inc.](https://zocket.ai) - [Zoom](https://www.zoom.us) - [zyprova](http://www.zyprova.com) ================================================ FILE: docs/roadmap.md ================================================ # A2A protocol roadmap **Last updated:** March 10, 2026 ## Near-term initiatives - 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). ## Longer term (3-6 month period) roadmap ### Governance The TSC looks to streamline opportunities for contribution through [A2A extensions](topics/extensions.md), [Samples](https://github.com/a2aproject/a2a-samples) and participation. ### 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. 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 A2A Project currently hosts SDKs in five languages (Python, Go, JS, Java, .NET). ### Community best practices As companies and individuals deploy A2A systems at an increasing pace, we are looking to accelerate the learning of the community by collecting and sharing the best practices and success stories that A2A enabled. ================================================ FILE: docs/robots.txt ================================================ # Allow all crawlers to access the entire site. User-agent: * Allow: / # Generative AI and LLM crawlers User-agent: GPTBot Allow: / User-agent: ChatGPT-User Allow: / User-agent: ClaudeBot Allow: / User-agent: Claude-Web Allow: / User-agent: PerplexityBot Allow: / User-agent: FacebookBot Allow: / User-agent: Applebot Allow: / User-agent: PerplexityBot Allow: / User-agent: Google-Extended Allow: / User-agent: GoogleOther Allow: / User-agent: DuckAssistBot Allow: / Sitemap: https://a2a-protocol.org/latest/sitemap.xml ================================================ FILE: docs/sdk/index.md ================================================ # A2A SDK A2A currently hosts SDKs in five languages (Python, Go, JS, Java, .NET). 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) | The A2A project provides numerous samples across supported languages in the [a2a-samples repository](https://github.com/a2aproject/a2a-samples). ================================================ FILE: docs/sdk/python.md ================================================ --- redirect: python/api/index.html --- # Python SDK Redirecting to [API reference](python/api/index.html)... ================================================ FILE: docs/specification.md ================================================ # Agent2Agent (A2A) Protocol Specification ??? note "**Latest Released Version** [`1.0.0`](https://a2a-protocol.org/v1.0.0/specification)" **Previous Versions** - [`0.3.0`](https://a2a-protocol.org/v0.3.0/specification) - [`0.2.6`](https://a2a-protocol.org/v0.2.6/specification) - [`0.1.0`](https://a2a-protocol.org/v0.1.0/specification) See [Release Notes](https://github.com/a2aproject/A2A/releases) for changes made between versions. ## 1. Introduction The Agent2Agent (A2A) Protocol is an open standard designed to facilitate communication and interoperability between independent, potentially opaque AI agent systems. In an ecosystem where agents might be built using different frameworks, languages, or by different vendors, A2A provides a common language and interaction model. This document provides the detailed technical specification for the A2A protocol. Its primary goal is to enable agents to: - Discover each other's capabilities. - Negotiate interaction modalities (text, files, structured data). - Manage collaborative tasks. - Securely exchange information to achieve user goals **without needing access to each other's internal state, memory, or tools.** ### 1.1. Key Goals of A2A - **Interoperability:** Bridge the communication gap between disparate agentic systems. - **Collaboration:** Enable agents to delegate tasks, exchange context, and work together on complex user requests. - **Discovery:** Allow agents to dynamically find and understand the capabilities of other agents. - **Flexibility:** Support various interaction modes including synchronous request/response, streaming for real-time updates, and asynchronous push notifications for long-running tasks. - **Security:** Facilitate secure communication patterns suitable for enterprise environments, relying on standard web security practices. - **Asynchronicity:** Natively support long-running tasks and interactions that may involve human-in-the-loop scenarios. ### 1.2. Guiding Principles - **Simple:** Reuse existing, well-understood standards (HTTP, JSON-RPC 2.0, Server-Sent Events). - **Enterprise Ready:** Address authentication, authorization, security, privacy, tracing, and monitoring by aligning with established enterprise practices. - **Async First:** Designed for (potentially very) long-running tasks and human-in-the-loop interactions. - **Modality Agnostic:** Support exchange of diverse content types including text, audio/video (via file references), structured data/forms, and potentially embedded UI components (e.g., iframes referenced in parts). - **Opaque Execution:** Agents collaborate based on declared capabilities and exchanged information, without needing to share their internal thoughts, plans, or tool implementations. For a broader understanding of A2A's purpose and benefits, see [What is A2A?](./topics/what-is-a2a.md). ### 1.3. Specification Structure This specification is organized into three distinct layers that work together to provide a complete protocol definition: ```mermaid graph TB subgraph L1 ["A2A Data Model"] direction LR A[Task] ~~~ B[Message] ~~~ C[AgentCard] ~~~ D[Part] ~~~ E[Artifact] ~~~ F[Extension] end subgraph L2 ["A2A Operations"] direction LR G[Send Message] ~~~ H[Stream Message] ~~~ I[Get Task] ~~~ J[List Tasks] ~~~ K[Cancel Task] ~~~ L[Get Agent Card] end subgraph L3 ["Protocol Bindings"] direction LR M[JSON-RPC Methods] ~~~ N[gRPC RPCs] ~~~ O[HTTP/REST Endpoints] ~~~ P[Custom Bindings] end %% Dependencies between layers L1 --> L2 L2 --> L3 style A fill:#e1f5fe style B fill:#e1f5fe style C fill:#e1f5fe style D fill:#e1f5fe style E fill:#e1f5fe style F fill:#e1f5fe style G fill:#f3e5f5 style H fill:#f3e5f5 style I fill:#f3e5f5 style J fill:#f3e5f5 style K fill:#f3e5f5 style L fill:#f3e5f5 style M fill:#e8f5e8 style N fill:#e8f5e8 style O fill:#e8f5e8 style L1 fill:#f0f8ff,stroke:#333,stroke-width:2px style L2 fill:#faf0ff,stroke:#333,stroke-width:2px style L3 fill:#f0fff0,stroke:#333,stroke-width:2px ``` **Layer 1: Canonical Data Model** defines the core data structures and message formats that all A2A implementations must understand. These are protocol agnostic definitions expressed as Protocol Buffer messages. **Layer 2: Abstract Operations** describes the fundamental capabilities and behaviors that A2A agents must support, independent of how they are exposed over specific protocols. **Layer 3: Protocol Bindings** provides concrete mappings of the abstract operations and data structures to specific protocol bindings (JSON-RPC, gRPC, HTTP/REST), including method names, endpoint patterns, and protocol-specific behaviors. This layered approach ensures that: - Core semantics remain consistent across all protocol bindings - New protocol bindings can be added without changing the fundamental data model - Developers can reason about A2A operations independently of binding concerns - Interoperability is maintained through shared understanding of the canonical data model ### 1.4 Normative Content In addition to the protocol requirements defined in this document, the file `spec/a2a.proto` is the single authoritative normative definition of all protocol data objects and request/response messages. A generated JSON artifact (`spec/a2a.json`, produced at build time and not committed) MAY be published for convenience to tooling and the website, but it is a non-normative build artifact. SDK language bindings, schemas, and any other derived forms **MUST** be regenerated from the proto (directly or via code generation) rather than edited manually. **Change Control and Deprecation Lifecycle:** - Introduction: When a proto message or field is renamed, the new name is added while existing published names remain available, but marked deprecated, until the next major release. - Documentation: Migration guidance MUST be provided via an ancillary document when introducing major breaking changes. - Anchors: Legacy documentation anchors MUST be preserved (as hidden HTML anchors) to avoid breaking inbound links. - SDK/Schema Aliases: SDKs and JSON Schemas SHOULD provide deprecated alias types/definitions to maintain backward compatibility. - Removal: A deprecated name SHOULD NOT be removed earlier than the next major version after introduction of its replacement. **Automated Generation:** The documentation build generates `specification/json/a2a.json` on-the-fly (the file is not tracked in source control). Future improvements may publish an OpenAPI v3 + JSON Schema bundle for enhanced tooling. **Rationale:** Centering the proto file as the normative source ensures protocol neutrality, reduces specification drift, and provides a deterministic evolution path for the ecosystem. ## 2. Terminology ### 2.1. Requirements Language The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). ### 2.2. Core Concepts A2A revolves around several key concepts. For detailed explanations, please refer to the [Key Concepts guide](./topics/key-concepts.md). - **A2A Client:** An application or agent that initiates requests to an A2A Server on behalf of a user or another system. - **A2A Server (Remote Agent):** An agent or agentic system that exposes an A2A-compliant endpoint, processing tasks and providing responses. - **Agent Card:** A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements. - **Message:** A communication turn between a client and a remote agent, having a `role` ("user" or "agent") and containing one or more `Parts`. - **Task:** The fundamental unit of work managed by A2A, identified by a unique ID. Tasks are stateful and progress through a defined lifecycle. - **Part:** The smallest unit of content within a Message or Artifact. Parts can contain text, file references, or structured data. - **Artifact:** An output (e.g., a document, image, structured data) generated by the agent as a result of a task, composed of `Parts`. - **Streaming:** Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via protocol-specific streaming mechanisms. - **Push Notifications:** Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios. - **Context:** An optional identifier to logically group related tasks and messages. - **Extension:** A mechanism for agents to provide additional functionality or data beyond the core A2A specification. ## 3. A2A Protocol Operations This section describes the core operations of the A2A protocol in a binding-independent manner. These operations define the fundamental capabilities that all A2A implementations must support, regardless of the underlying binding mechanism. ### 3.1. Core Operations The following operations define the fundamental capabilities that all A2A implementations must support, independent of the specific protocol binding used. For a quick reference mapping of these operations to protocol-specific method names and endpoints, see [Section 5.3 (Method Mapping Reference)](#53-method-mapping-reference). For detailed protocol-specific implementation details, see: - [Section 9: JSON-RPC Protocol Binding](#9-json-rpc-protocol-binding) - [Section 10: gRPC Protocol Binding](#10-grpc-protocol-binding) - [Section 11: HTTP+JSON/REST Protocol Binding](#11-httpjsonrest-protocol-binding) #### 3.1.1. Send Message The primary operation for initiating agent interactions. Clients send a message to an agent and receive either a task that tracks the processing or a direct response message. **Inputs:** - [`SendMessageRequest`](#321-sendmessagerequest): Request object containing the message, configuration, and metadata **Outputs:** - [`Task`](#411-task): A task object representing the processing of the message, OR - [`Message`](#414-message): A direct response message (for simple interactions that don't require task tracking) **Errors:** - [`ContentTypeNotSupportedError`](#332-error-handling): A Media Type provided in the request's message parts is not supported by the agent. - [`UnsupportedOperationError`](#332-error-handling): Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages. - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. **Behavior:** The agent MAY create a new `Task` to process the provided message asynchronously or MAY return a direct `Message` response for simple interactions. The operation MUST return immediately with either task information or response message. Task processing MAY continue asynchronously after the response when a [`Task`](#411-task) is returned. #### 3.1.2. Send Streaming Message Similar to Send Message but with real-time streaming of updates during processing. **Inputs:** - [`SendMessageRequest`](#321-sendmessagerequest): Request object containing the message, configuration, and metadata **Outputs:** - [`Stream Response`](#323-stream-response) object containing: - Initial response: [`Task`](#411-task) object OR [`Message`](#414-message) object - Subsequent events following a `Task` MAY include stream of [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) and [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects - Final completion indicator **Errors:** - [`UnsupportedOperationError`](#332-error-handling): Streaming is not supported by the agent (see [Capability Validation](#334-capability-validation)). - [`UnsupportedOperationError`](#332-error-handling): Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages. - [`ContentTypeNotSupportedError`](#332-error-handling): A Media Type provided in the request's message parts is not supported by the agent. - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. **Behavior:** The operation MUST establish a streaming connection for real-time updates. The stream MUST follow one of these patterns: 1. **Message-only stream:** If the agent returns a [`Message`](#414-message), the stream MUST contain exactly one `Message` object and then close immediately. No task tracking or updates are provided. 2. **Task lifecycle stream:** If the agent returns a [`Task`](#411-task), the stream MUST begin with the Task object, followed by zero or more [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) or [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects. The stream MUST close when the task reaches a terminal state (e.g. completed, failed, canceled, rejected). The agent MAY return a `Task` for complex processing with status/artifact updates or MAY return a `Message` for direct streaming responses without task overhead. The implementation MUST provide immediate feedback on progress and intermediate results. #### 3.1.3. Get Task Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with message/send, or for fetching the final state of a task after being notified via a push notification or after a stream has ended. **Inputs:** {{ proto_to_table("GetTaskRequest") }} See [History Length Semantics](#324-history-length-semantics) for details about `historyLength`. **Outputs:** - [`Task`](#411-task): Current state and artifacts of the requested task **Errors:** - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. #### 3.1.4. List Tasks Retrieves a list of tasks with optional filtering and pagination capabilities. This method allows clients to discover and manage multiple tasks across different contexts or with specific status criteria. **Inputs:** {{ proto_to_table("ListTasksRequest") }} When `includeArtifacts` is false (the default), the artifacts field MUST be omitted entirely from each Task object in the response. The field should not be present as an empty array or null value. When `includeArtifacts` is true, the artifacts field should be included with its actual content (which may be an empty array if the task has no artifacts). **Outputs:** {{ proto_to_table("ListTasksResponse") }} Note on `nextPageToken`: The `nextPageToken` field MUST always be present in the response. When there are no more results to retrieve (i.e., this is the final page), the field MUST be set to an empty string (""). Clients should check for an empty string to determine if more pages are available. **Errors:** None specific to this operation beyond standard protocol errors. **Behavior:** The operation MUST return only tasks visible to the authenticated client and MUST use cursor-based pagination for performance and consistency. Tasks MUST be sorted by last update time in descending order. Implementations MUST implement appropriate authorization scoping to ensure clients can only access authorized tasks. See [Section 13.1 Data Access and Authorization Scoping](#131-data-access-and-authorization-scoping) for detailed security requirements. ***Pagination Strategy:*** This method uses cursor-based pagination (via `pageToken`/`nextPageToken`) rather than offset-based pagination for better performance and consistency, especially with large datasets. Cursor-based pagination avoids the "deep pagination problem" where skipping large numbers of records becomes inefficient for databases. This approach is consistent with the gRPC specification, which also uses cursor-based pagination (page_token/next_page_token). ***Ordering:*** Implementations MUST return tasks sorted by their status timestamp time in descending order (most recently updated tasks first). This ensures consistent pagination and allows clients to efficiently monitor recent task activity. #### 3.1.5. Cancel Task Requests the cancellation of an ongoing task. The server will attempt to cancel the task, but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage). **Inputs:** {{ proto_to_table("CancelTaskRequest") }} **Outputs:** - Updated [`Task`](#411-task) with cancellation status **Errors:** - [`TaskNotCancelableError`](#332-error-handling): The task is not in a cancelable state (e.g., already completed, failed, or canceled). - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. **Behavior:** The operation attempts to cancel the specified task and returns its updated state. #### 3.1.6. Subscribe to Task Establishes a streaming connection to receive updates for an existing task. **Inputs:** {{ proto_to_table("SubscribeToTaskRequest") }} **Outputs:** - [`Stream Response`](#323-stream-response) object containing: - Initial response: [`Task`](#411-task) object with current state - Stream of [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) and [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) objects **Errors:** - [`UnsupportedOperationError`](#332-error-handling): Streaming is not supported by the agent (see [Capability Validation](#334-capability-validation)). - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. - [`UnsupportedOperationError`](#332-error-handling): The operation is attempted on a task that is in a terminal state (`completed`, `failed`, `canceled`, or `rejected`). **Behavior:** The operation enables real-time monitoring of task progress and can be used with any task that is not in a terminal state. The stream MUST terminate when the task reaches a terminal state (`completed`, `failed`, `canceled`, or `rejected`). The operation MUST return a `Task` object as the first event in the stream, representing the current state of the task at the time of subscription. This prevents a potential loss of information between a call to `GetTask` and calling `SubscribeToTask`. #### 3.1.7. Create Push Notification Config Creates a push notification configuration for a task to receive asynchronous updates via webhook. **Inputs:** {{ proto_to_table("CreateTaskPushNotificationConfigRequest") }} **Outputs:** - [`PushNotificationConfig`](#431-pushnotificationconfig): Created configuration with assigned ID **Errors:** - [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)). - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. **Behavior:** The operation MUST establish a webhook endpoint for task update notifications. When task updates occur, the agent will send HTTP POST requests to the configured webhook URL with [`StreamResponse`](#323-stream-response) payloads (see [Push Notification Payload](#433-push-notification-payload) for details). This operation is only available if the agent supports push notifications capability. The configuration MUST persist until task completion or explicit deletion. #### 3.1.8. Get Push Notification Config Retrieves an existing push notification configuration for a task. **Inputs:** {{ proto_to_table("GetTaskPushNotificationConfigRequest") }} **Outputs:** - [`PushNotificationConfig`](#431-pushnotificationconfig): The requested configuration **Errors:** - [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)). - [`TaskNotFoundError`](#332-error-handling): The push notification configuration does not exist. **Behavior:** The operation MUST return configuration details including webhook URL and notification settings. The operation MUST fail if the configuration does not exist or the client lacks access. #### 3.1.9. List Push Notification Configs Retrieves all push notification configurations for a task. **Inputs:** {{ proto_to_table("ListTaskPushNotificationConfigsRequest") }} **Outputs:** {{ proto_to_table("ListTaskPushNotificationConfigsResponse") }} **Errors:** - [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)). - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist or is not accessible. **Behavior:** The operation MUST return all active push notification configurations for the specified task and MAY support pagination for tasks with many configurations. #### 3.1.10. Delete Push Notification Config Removes a push notification configuration for a task. **Inputs:** {{ proto_to_table("DeleteTaskPushNotificationConfigRequest") }} **Outputs:** - Confirmation of deletion (implementation-specific) **Errors:** - [`PushNotificationNotSupportedError`](#332-error-handling): Push notifications are not supported by the agent (see [Capability Validation](#334-capability-validation)). - [`TaskNotFoundError`](#332-error-handling): The task ID does not exist. **Behavior:** The operation MUST permanently remove the specified push notification configuration. No further notifications will be sent to the configured webhook after deletion. This operation MUST be idempotent - multiple deletions of the same config have the same effect. #### 3.1.11. Get Extended Agent Card Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.capabilities.extendedAgentCard` is `true`. **Inputs:** {{ proto_to_table("GetExtendedAgentCardRequest") }} **Outputs:** - [`AgentCard`](#441-agentcard): A complete Agent Card object, which may contain additional details or skills not present in the public card **Errors:** - [`UnsupportedOperationError`](#332-error-handling): The agent does not support authenticated extended cards (see [Capability Validation](#334-capability-validation)). - [`ExtendedAgentCardNotConfiguredError`](#332-error-handling): The agent declares support but does not have an extended agent card configured. **Behavior:** - **Authentication**: The client MUST authenticate the request using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields. - **Extended Information**: The operation MAY return different details based on client authentication level, including additional skills, capabilities, or configuration not available in the public Agent Card. - **Card Replacement**: Clients retrieving this extended card SHOULD replace their cached public Agent Card with the content received from this endpoint for the duration of their authenticated session or until the card's version changes. - **Availability**: This operation is only available if the public Agent Card declares `capabilities.extendedAgentCard: true`. For detailed security guidance on extended agent cards, see [Section 13.3 Extended Agent Card Access Control](#133-extended-agent-card-access-control). ### 3.2. Operation Parameter Objects This section defines common parameter objects used across multiple operations. #### 3.2.1. SendMessageRequest {{ proto_to_table("SendMessageRequest") }} #### 3.2.2. SendMessageConfiguration {{ proto_to_table("SendMessageConfiguration") }} **Execution Mode:** The `return_immediately` field in [`SendMessageConfiguration`](#322-sendmessageconfiguration) controls whether the operation returns immediately or waits for task completion. Operations are blocking by default: - **Blocking (`return_immediately: false` or unset)**: The operation MUST wait until the task reaches a terminal state (`COMPLETED`, `FAILED`, `CANCELED`, `REJECTED`) or an interrupted state (`INPUT_REQUIRED`, `AUTH_REQUIRED`) before returning. The response MUST include the latest task state with all artifacts and status information. This is the default behavior. - **Non-Blocking (`return_immediately: true`)**: The operation MUST return immediately after creating the task, even if processing is still in progress. The returned task will have an in-progress state (e.g., `working`, `input_required`). It is the caller's responsibility to poll for updates using [Get Task](#313-get-task), subscribe via [Subscribe to Task](#316-subscribe-to-task), or receive updates via push notifications. The `return_immediately` field has no effect: - when the operation returns a direct [`Message`](#414-message) response instead of a task. - for streaming operations, which always return updates in real-time. - on configured push notification configurations, which operates independently of execution mode. #### 3.2.3. Stream Response {{ proto_to_table("StreamResponse") }} This wrapper allows streaming endpoints to return different types of updates through a single response stream while maintaining type safety. #### 3.2.4. History Length Semantics The `historyLength` parameter appears in multiple operations and controls how much task history is returned in responses. This parameter follows consistent semantics across all operations: - **Unset/undefined**: No limit imposed; server returns its default amount of history (implementation-defined, may be all history) - **0**: No history should be returned; the `history` field SHOULD be omitted - **> 0**: Return at most this many recent messages from the task's history #### 3.2.5. Metadata A flexible key-value map for passing additional context or parameters with operations. Metadata keys and are strings and values can be any valid value that can be represented in JSON. [`Extensions`](#46-extensions) can be used to strongly type metadata values for specific use cases. #### 3.2.6 Service Parameters A key-value map for passing horizontally applicable context or parameters with case-insensitive string keys and case-sensitive string values. The transmission mechanism for these service parameter key-value pairs is defined by the specific protocol binding (e.g., HTTP headers for HTTP-based bindings, gRPC metadata for gRPC bindings). Custom protocol bindings **MUST** specify how service parameters are transmitted in their binding specification. **Standard A2A Service Parameters:** | Name | Description | Example Value | | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- | | `A2A-Extensions` | Comma-separated list of extension URIs that the client wants to use for the request | `https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1` | | `A2A-Version` | The A2A protocol version that the client is using. If the version is not supported, the agent returns [`VersionNotSupportedError`](#332-error-handling) | `0.3` | As service parameter names MAY need to co-exist with other parameters defined by the underlying transport protocol or infrastructure, all service parameters defined by this specification will be prefixed with `a2a-`. ### 3.3. Operation Semantics #### 3.3.1. Idempotency - **Get operations** (Get Task, List Tasks, Get Extended Agent Card) are naturally idempotent - **Send Message** operations MAY be idempotent. Agents may utilize the messageId to detect duplicate messages. - **Cancel Task** operations are idempotent - multiple cancellation requests have the same effect. A duplicate cancellation request MAY return `TaskNotFoundError` if the task has already been canceled and purged. #### 3.3.2. Error Handling All operations may return errors in the following categories. Servers **MUST** return appropriate errors and **SHOULD** provide actionable information to help clients resolve issues. **Error Categories and Server Requirements:** - **Authentication Errors**: Invalid or missing credentials - Servers **MUST** reject requests with invalid or missing authentication credentials - Servers **SHOULD** include authentication challenge information in the error response - Servers **SHOULD** specify which authentication scheme is required - Example error codes: HTTP `401 Unauthorized`, gRPC `UNAUTHENTICATED`, JSON-RPC custom error - Example scenarios: Missing bearer token, expired API key, invalid OAuth token - **Authorization Errors**: Insufficient permissions for requested operation - Servers **MUST** return an authorization error when the authenticated client lacks required permissions - Servers **SHOULD** indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access) - Servers **MUST NOT** reveal the existence of resources the client is not authorized to access - Example error codes: HTTP `403 Forbidden`, gRPC `PERMISSION_DENIED`, JSON-RPC custom error - Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes - **Validation Errors**: Invalid input parameters or message format - Servers **MUST** validate all input parameters before processing - Servers **SHOULD** specify which parameter(s) failed validation and why - Servers **SHOULD** provide guidance on valid parameter values or formats - Example error codes: HTTP `400 Bad Request`, gRPC `INVALID_ARGUMENT`, JSON-RPC `-32602 Invalid params` - Example scenarios: Invalid task ID format, missing required message parts, unsupported content type - **Resource Errors**: Requested task not found or not accessible - Servers **MUST** return a not found error when a requested resource does not exist or is not accessible to the authenticated client - Servers **SHOULD NOT** distinguish between "does not exist" and "not authorized" to prevent information leakage - Example error codes: HTTP `404 Not Found`, gRPC `NOT_FOUND`, JSON-RPC custom error (see A2A-specific errors) - Example scenarios: Task ID does not exist, task has been deleted, configuration not found - **System Errors**: Internal agent failures or temporary unavailability - Servers **SHOULD** return appropriate error codes for temporary failures vs. permanent errors - Servers **MAY** include retry guidance (e.g., Retry-After header in HTTP) - Servers **SHOULD** log system errors for diagnostic purposes - Example error codes: HTTP `500 Internal Server Error` or `503 Service Unavailable`, gRPC `INTERNAL` or `UNAVAILABLE`, JSON-RPC `-32603 Internal error` - Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded **Error Payload Structure:** All error responses in the A2A protocol, regardless of binding, **MUST** convey the following information: 1. **Error Code**: A machine-readable identifier for the error type (e.g., string code, numeric code, or protocol-specific status) 2. **Error Message**: A human-readable description of the error 3. **Error Details** (optional): Additional structured information about the error, such as: - Affected fields or parameters - Contextual information (e.g., task ID, timestamp) - Suggestions for resolution Protocol bindings **MUST** map these elements to their native error representations while preserving semantic meaning. See binding-specific sections for concrete error format examples: [JSON-RPC Error Handling](#95-error-handling), [gRPC Error Handling](#106-error-handling), and [HTTP/REST Error Handling](#116-error-handling). **A2A-Specific Errors:** | Error Name | Description | | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TaskNotFoundError` | The specified task ID does not correspond to an existing or accessible task. It might be invalid, expired, or already completed and purged. | | `TaskNotCancelableError` | An attempt was made to cancel a task that is not in a cancelable state (e.g., it has already reached a terminal state like `completed`, `failed`, or `canceled`). | | `PushNotificationNotSupportedError` | Client attempted to use push notification features but the server agent does not support them (i.e., `AgentCard.capabilities.pushNotifications` is `false`). | | `UnsupportedOperationError` | The requested operation or a specific aspect of it is not supported by this server agent implementation. | | `ContentTypeNotSupportedError` | A Media Type provided in the request's message parts or implied for an artifact is not supported by the agent or the specific skill being invoked. | | `InvalidAgentResponseError` | An agent returned a response that does not conform to the specification for the current method. | | `ExtendedAgentCardNotConfiguredError` | The agent does not have an extended agent card configured when one is required for the requested operation. | | `ExtensionSupportRequiredError` | Server requested use of an extension marked as `required: true` in the Agent Card but the client did not declare support for it in the request. | | `VersionNotSupportedError` | The A2A protocol version specified in the request (via `A2A-Version` service parameter) is not supported by the agent. | #### 3.3.3. Asynchronous Processing A2A operations are designed for asynchronous task execution. Operations return immediately with either [`Task`](#411-task) objects or [`Message`](#414-message) objects, and when a Task is returned, processing continues in the background. Clients retrieve task updates through polling, streaming, or push notifications (see [Section 3.5](#35-task-update-delivery-mechanisms)). Agents MAY accept additional messages for tasks in non-terminal states to enable multi-turn interactions (see [Section 3.4](#34-multi-turn-interactions)). #### 3.3.4. Capability Validation Agents declare optional capabilities in their [`AgentCard`](#441-agentcard). When clients attempt to use operations or features that require capabilities not declared as supported in the Agent Card, the agent **MUST** return an appropriate error response: - **Push Notifications**: If `AgentCard.capabilities.pushNotifications` is `false` or not present, operations related to push notification configuration (Create, Get, List, Delete) **MUST** return [`PushNotificationNotSupportedError`](#332-error-handling). - **Streaming**: If `AgentCard.capabilities.streaming` is `false` or not present, attempts to use `SendStreamingMessage` or `SubscribeToTask` operations **MUST** return [`UnsupportedOperationError`](#332-error-handling). - **Extended Agent Card**: If `AgentCard.capabilities.extendedAgentCard` is `false` or not present, attempts to call the Get Extended Agent Card operation **MUST** return [`UnsupportedOperationError`](#332-error-handling). If the agent declares support but has not configured an extended card, it **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling). - **Extensions**: When a server requests use of an extension marked as `required: true` in the Agent Card but the client does not declare support for it, the agent **MUST** return [`ExtensionSupportRequiredError`](#332-error-handling). Clients **SHOULD** validate capability support by examining the Agent Card before attempting operations that require optional capabilities. ### 3.4. Multi-Turn Interactions The A2A protocol supports multi-turn conversations through context identifiers and task references, enabling agents to maintain conversational continuity across multiple interactions. #### 3.4.1. Context Identifier Semantics A `contextId` is an identifier that logically groups multiple related [`Task`](#411-task) and [`Message`](#414-message) objects, providing continuity across a series of interactions. **Generation and Assignment:** - Agents **MAY** generate a new `contextId` when processing a [`Message`](#414-message) that does not include a `contextId` field - If an agent generates a new `contextId`, it **MUST** be included in the response (either [`Task`](#411-task) or [`Message`](#414-message)) - Agents **MAY** accept and preserve client-provided `contextId` values - If an agent cannot accept a client-provided `contextId`, it **MUST** reject the request with an error and **MUST NOT** generate a new `contextId` for the response - Clients **SHOULD NOT** provide a client-generated `contextId` to a server unless they understand how the server will process that `contextId` - Server-generated `contextId` values **SHOULD** be treated as opaque identifiers by clients **Grouping and Scope:** - A `contextId` logically groups multiple [`Task`](#411-task) objects and [`Message`](#414-message) objects that are part of the same conversational context - All tasks and messages with the same `contextId` **SHOULD** be treated as part of the same conversational session - Agents **MAY** use the `contextId` to maintain internal state, conversational history, or LLM context across multiple interactions - Agents **MAY** implement context expiration or cleanup policies and **SHOULD** document any such policies #### 3.4.2. Task Identifier Semantics A `taskId` is a unique identifier for a [`Task`](#411-task) object, representing a stateful unit of work with a defined lifecycle. **Generation and Assignment:** - Task IDs are **server-generated** when a new task is created in response to a [`Message`](#414-message) - Agents **MUST** generate a unique `taskId` for each new task they create - The generated `taskId` **MUST** be included in the [`Task`](#411-task) object returned to the client - When a client includes a `taskId` in a [`Message`](#414-message), it **MUST** reference an existing task - Agents **MUST** return a [`TaskNotFoundError`](#332-error-handling) if the provided `taskId` does not correspond to an existing task - Client-provided `taskId` values for creating new tasks is **NOT** supported #### 3.4.3. Multi-Turn Conversation Patterns The A2A protocol supports several patterns for multi-turn interactions: **Context Continuity:** - [`Task`](#411-task) objects maintain conversation context through the `contextId` field - Clients **MAY** include the `contextId` in subsequent messages to indicate continuation of a previous interaction - Clients **MAY** use `taskId` (with or without `contextId`) to continue or refine a specific task - Clients **MAY** use `contextId` without `taskId` to start a new task within an existing conversation context - Agents **MUST** infer `contextId` from the task if only `taskId` is provided - Agents **MUST** reject messages containing mismatching `contextId` and `taskId` (i.e., the provided `contextId` is different from that of the referenced [`Task`](#411-task)). **Input Required State:** - Agents can request additional input mid-processing by transitioning a task to the `input-required` state - The client continues the interaction by sending a new message with the same `taskId` and `contextId` **Follow-up Messages:** - Clients can send additional messages with `taskId` references to continue or refine existing tasks - Clients **SHOULD** use the `referenceTaskIds` field in [`Message`](#414-message) to explicitly reference related tasks - Agents **SHOULD** use referenced tasks to understand the context and intent of follow-up requests **Context Inheritance:** - New tasks created within the same `contextId` can inherit context from previous interactions - Agents **SHOULD** leverage the shared `contextId` to provide contextually relevant responses ### 3.5. Task Update Delivery Mechanisms The A2A protocol provides three complementary mechanisms for clients to receive updates about task progress and completion. #### 3.5.1. Overview of Update Mechanisms **Polling (Get Task):** - Client periodically calls Get Task ([Section 3.1.3](#313-get-task)) to check task status - Simple to implement, works with all protocol bindings - Higher latency, potential for unnecessary requests - Best for: Simple integrations, infrequent updates, clients behind restrictive firewalls **Streaming:** - Real-time delivery of events as they occur - Operations: Stream Message ([Section 3.1.2](#312-send-streaming-message)) and Subscribe to Task ([Section 3.1.6](#316-subscribe-to-task)) - Low latency, efficient for frequent updates - Requires persistent connection support - Best for: Interactive applications, real-time dashboards, live progress monitoring - Requires `AgentCard.capabilities.streaming` to be `true` **Push Notifications (WebHooks):** - Agent sends HTTP POST requests to client-registered endpoints when task state changes - Client does not maintain persistent connection - Asynchronous delivery, client must be reachable via HTTP - Best for: Server-to-server integrations, long-running tasks, event-driven architectures - Operations: Create ([Section 3.1.7](#317-create-push-notification-config)), Get ([Section 3.1.8](#76-taskspushnotificationconfigget)), List ([Section 3.1.9](#319-list-push-notification-configs)), Delete ([Section 3.1.10](#3110-delete-push-notification-config)) - Event types: TaskStatusUpdateEvent ([Section 4.2.1](#421-taskstatusupdateevent)), TaskArtifactUpdateEvent ([Section 4.2.2](#422-taskartifactupdateevent)), WebHook payloads ([Section 4.3](#43-push-notification-objects)) - Requires `AgentCard.capabilities.pushNotifications` to be `true` - Regardless of the protocol binding being used by the agent, WebHook calls use plain HTTP and the JSON payloads as defined in the HTTP protocol binding #### 3.5.2. Streaming Event Delivery **Event Ordering:** All implementations MUST deliver events in the order they were generated. Events MUST NOT be reordered during transmission, regardless of protocol binding. **Multiple Streams Per Task:** An agent MAY serve multiple concurrent streams to one or more clients for the same task. This allows multiple clients (or the same client with multiple connections) to independently subscribe to and receive updates about a task's progress. When multiple streams are active for a task: - Events MUST be broadcast to all active streams for that task - Each stream MUST receive the same events in the same order - Closing one stream MUST NOT affect other active streams for the same task - The task lifecycle is independent of any individual stream's lifecycle This capability enables scenarios such as: - Multiple team members monitoring the same long-running task - A client reconnecting to a task after a network interruption by opening a new stream - Different applications or dashboards displaying real-time updates for the same task #### 3.5.3. Push Notification Delivery Push notifications are delivered via HTTP POST to client-registered webhook endpoints. The delivery semantics and reliability guarantees are defined in [Section 4.3](#43-push-notification-objects). ### 3.6 Versioning The specific version of the A2A protocol in use is identified using the `Major.Minor` elements (e.g. `1.0`) of the corresponding A2A specification version. Patch version numbers used by the specification, do not affect protocol compatibility. Patch version numbers SHOULD NOT be used in requests, responses and Agent Cards, and MUST not be considered when clients and servers negotiate protocol versions. #### 3.6.1 Client Responsibilities Clients MUST send the `A2A-Version` header with each request to maintain compatibility after an agent upgrades to a new version of the protocol (except for 0.3 Clients - 0.3 will be assumed for empty header). Sending the `A2A-Version` header also provides visibility to agents about version usage in the ecosystem, which can help inform the risks of inplace version upgrades. **Example of HTTP GET Request with Version Header:** ```http GET /tasks/task-123 HTTP/1.1 Host: agent.example.com A2A-Version: 1.0 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json ``` Clients MAY provide the `A2A-Version` as a request parameter instead of a header. **Example of HTTP GET Request with Version request parameter:** ```http GET /tasks/task-123?A2A-Version=1.0 HTTP/1.1 Host: agent.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json ``` #### 3.6.2 Server Responsibilities Agents MUST process requests using the semantics of the requested `A2A-Version` (matching `Major.Minor`). If the version is not supported by the interface, agents MUST return a [`VersionNotSupportedError`](#332-error-handling). Agents MUST interpret empty value as 0.3 version. Agents CAN expose multiple interfaces for the same transport with different versions under the same or different URLs. #### 3.6.3 Tooling support Tooling libraries and SDKs that implement the A2A protocol MUST provide mechanisms to help clients manage protocol versioning, such as negotiation of the transport and protocol version used. Client Agents that require the latest features of the protocol should be configured to request specific versions and avoid automatic fallback to older versions, to prevent silently losing functionality. ### 3.7 Messages and Artifacts Messages and Artifacts serve distinct purposes within the A2A protocol. The core interaction model defined by A2A is for clients to send messages to initiate a task that produces one or more artifacts. Messages play several key roles: - **Task Initiation**: Clients send Messages to agents to initiate new tasks. - **Clarification Messages**: Agents may send Messages back to the client to request clarification prior to initiating a task. - **Status Messages**: Agents attach Messages to status update events to inform clients about task progress, request additional input, or provide informational updates. - **Task Interaction**: Clients send Messages to provide additional input or instructions for ongoing tasks. Messages SHOULD NOT be used to deliver task outputs. Results SHOULD BE returned using Artifacts associated with a Task. This separation allows for a clear distinction between communication (Messages) and data output (Artifacts). The Task History field contains Messages exchanged during task execution. However, not all Messages are guaranteed to be persisted in the Task history; for example, transient informational messages may not be stored. Messages exchanged prior to task creation may not be stored in Task history. The agent is responsible to determine which Messages are persisted in the Task History. Clients using streaming to retrieve task updates MAY not receive all status update messages if the client is disconnected and then reconnects. Messages MUST NOT be considered a reliable delivery mechanism for critical information. Agents MAY choose to persist all Messages that contain important information in the Task history to ensure clients can retrieve it later. However, clients MUST NOT rely on this behavior unless negotiated out-of-band. ## 4. Protocol Data Model The A2A protocol defines a canonical data model using Protocol Buffers. All protocol bindings **MUST** provide functionally equivalent representations of these data structures. ### 4.1. Core Objects #### 4.1.1. Task {{ proto_to_table("Task") }} #### 4.1.2. TaskStatus {{ proto_to_table("TaskStatus") }} #### 4.1.3. TaskState {{ proto_enum_to_table("TaskState") }} #### 4.1.4. Message {{ proto_to_table("Message") }} #### 4.1.5. Role {{ proto_enum_to_table("Role") }} #### 4.1.6. Part {{ proto_to_table("Part") }} #### 4.1.7. Artifact {{ proto_to_table("Artifact") }} ### 4.2. Streaming Events #### 4.2.1. TaskStatusUpdateEvent {{ proto_to_table("TaskStatusUpdateEvent") }} #### 4.2.2. TaskArtifactUpdateEvent {{ proto_to_table("TaskArtifactUpdateEvent") }} ### 4.3. Push Notification Objects #### 4.3.1. PushNotificationConfig {{ proto_to_table("PushNotificationConfig") }} #### 4.3.2. AuthenticationInfo {{ proto_to_table("AuthenticationInfo") }} #### 4.3.3. Push Notification Payload When a task update occurs, the agent sends an HTTP POST request to the configured webhook URL. The payload uses the same [`StreamResponse`](#323-stream-response) format as streaming operations, allowing push notifications to deliver the same event types as real-time streams. **Request Format:** ```http POST {webhook_url} Authorization: {authentication_scheme} {credentials} Content-Type: application/json { /* StreamResponse object - one of: */ "task": { /* Task object */ }, "message": { /* Message object */ }, "statusUpdate": { /* TaskStatusUpdateEvent object */ }, "artifactUpdate": { /* TaskArtifactUpdateEvent object */ } } ``` **Payload Structure:** The webhook payload is a [`StreamResponse`](#323-stream-response) object containing exactly one of the following: - **task**: A [`Task`](#411-task) object with the current task state - **message**: A [`Message`](#414-message) object containing a message response - **statusUpdate**: A [`TaskStatusUpdateEvent`](#421-taskstatusupdateevent) indicating a status change - **artifactUpdate**: A [`TaskArtifactUpdateEvent`](#422-taskartifactupdateevent) indicating artifact updates **Authentication:** The agent MUST include authentication credentials in the request headers as specified in the [`PushNotificationConfig.authentication`](#432-authenticationinfo) field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.). **Client Responsibilities:** - Clients MUST respond with HTTP 2xx status codes to acknowledge successful receipt - Clients SHOULD process notifications idempotently, as duplicate deliveries may occur - Clients MUST validate the task ID matches an expected task - Clients SHOULD implement appropriate security measures to verify the notification source **Server Guarantees:** - Agents MUST attempt delivery at least once for each configured webhook - Agents MAY implement retry logic with exponential backoff for failed deliveries - Agents SHOULD include a reasonable timeout for webhook requests (recommended: 10-30 seconds) - Agents MAY stop attempting delivery after a configured number of consecutive failures For detailed security guidance on push notifications, see [Section 13.2 Push Notification Security](#132-push-notification-security). ### 4.4. Agent Discovery Objects #### 4.4.1. AgentCard {{ proto_to_table("AgentCard") }} #### 4.4.2. AgentProvider {{ proto_to_table("AgentProvider") }} #### 4.4.3. AgentCapabilities {{ proto_to_table("AgentCapabilities") }} #### 4.4.4. AgentExtension {{ proto_to_table("AgentExtension") }} #### 4.4.5. AgentSkill {{ proto_to_table("AgentSkill") }} #### 4.4.6. AgentInterface {{ proto_to_table("AgentInterface") }} #### 4.4.7. AgentCardSignature {{ proto_to_table("AgentCardSignature") }} ### 4.5. Security Objects #### 4.5.1. SecurityScheme {{ proto_to_table("SecurityScheme") }} #### 4.5.2. APIKeySecurityScheme {{ proto_to_table("APIKeySecurityScheme") }} #### 4.5.3. HTTPAuthSecurityScheme {{ proto_to_table("HTTPAuthSecurityScheme") }} #### 4.5.4. OAuth2SecurityScheme {{ proto_to_table("OAuth2SecurityScheme") }} #### 4.5.5. OpenIdConnectSecurityScheme {{ proto_to_table("OpenIdConnectSecurityScheme") }} #### 4.5.6. MutualTlsSecurityScheme {{ proto_to_table("MutualTlsSecurityScheme") }} #### 4.5.7. OAuthFlows {{ proto_to_table("OAuthFlows") }} #### 4.5.8. AuthorizationCodeOAuthFlow {{ proto_to_table("AuthorizationCodeOAuthFlow") }} #### 4.5.9. ClientCredentialsOAuthFlow {{ proto_to_table("ClientCredentialsOAuthFlow") }} #### 4.5.10. DeviceCodeOAuthFlow {{ proto_to_table("DeviceCodeOAuthFlow") }} ### 4.6. Extensions The A2A protocol supports extensions to provide additional functionality or data beyond the core specification while maintaining backward compatibility and interoperability. Extensions allow agents to declare additional capabilities such as protocol enhancements or vendor-specific features, maintain compatibility with clients that don't support specific extensions, enable innovation through experimental or domain-specific features without modifying the core protocol, and facilitate standardization by providing a pathway for community-developed features to become part of the core specification. #### 4.6.1. Extension Declaration Agents declare their supported extensions in the [`AgentCard`](#441-agentcard) using the `extensions` field, which contains an array of [`AgentExtension`](#444-agentextension) objects. *Example: Agent declaring extension support in AgentCard:* ```json { "name": "Research Assistant Agent", "description": "AI agent for academic research and fact-checking", "supportedInterfaces": [ { "url": "https://research-agent.example.com/a2a/v1", "protocolBinding": "HTTP+JSON", "protocolVersion": "0.3", } ], "capabilities": { "streaming": false, "pushNotifications": false, "extensions": [ { "uri": "https://standards.org/extensions/citations/v1", "description": "Provides citation formatting and source verification", "required": false }, { "uri": "https://example.com/extensions/geolocation/v1", "description": "Location-based search capabilities", "required": false } ] }, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [ { "id": "academic-research", "name": "Academic Research Assistant", "description": "Provides research assistance with citations and source verification", "tags": ["research", "citations", "academic"], "examples": ["Find peer-reviewed articles on climate change"], "inputModes": ["text/plain"], "outputModes": ["text/plain"] } ] } ``` Clients indicate their desire to opt into the use of specific extensions through binding-specific mechanisms such as HTTP headers, gRPC metadata, or JSON-RPC request parameters that identify the extension identifiers they wish to utilize during the interaction. *Example: HTTP client opting into extensions using headers:* ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/json Authorization: Bearer token A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 { "message": { "role": "ROLE_USER", "parts": [{"text": "Find restaurants near me"}], "extensions": ["https://example.com/extensions/geolocation/v1"], "metadata": { "https://example.com/extensions/geolocation/v1": { "latitude": 37.7749, "longitude": -122.4194 } } } } ``` #### 4.6.2. Extensions Points Extensions can be integrated into the A2A protocol at several well-defined extension points: **Message Extensions:** Messages can be extended to allow clients to provide additional strongly typed context or parameters relevant to the message being sent, or TaskStatus Messages to include extra information about the task's progress. *Example: A location extension using the extensions and metadata arrays:* ```json { "role": "ROLE_USER", "parts": [ {"text": "Find restaurants near me"} ], "extensions": ["https://example.com/extensions/geolocation/v1"], "metadata": { "https://example.com/extensions/geolocation/v1": { "latitude": 37.7749, "longitude": -122.4194, "accuracy": 10.0, "timestamp": "2025-10-21T14:30:00Z" } } } ``` **Artifact Extensions:** Artifacts can include extension data to provide strongly typed context or metadata about the generated content. *Example: An artifact with citation extension for research sources:* ```json { "artifactId": "research-summary-001", "name": "Climate Change Summary", "parts": [ { "text": "Global temperatures have risen by 1.1°C since pre-industrial times, with significant impacts on weather patterns and sea levels." } ], "extensions": ["https://standards.org/extensions/citations/v1"], "metadata": { "https://standards.org/extensions/citations/v1": { "sources": [ { "title": "Global Temperature Anomalies - 2023 Report", "authors": ["Smith, J.", "Johnson, M."], "url": "https://climate.gov/reports/2023-temperature", "accessDate": "2025-10-21", "relevantText": "Global temperatures have risen by 1.1°C" } ] } } } ``` #### 4.6.3. Extension Versioning and Compatibility Extensions **SHOULD** include version information in their URI identifier. This allows clients and agents to negotiate compatible versions of extensions during interactions. A new URI **MUST** be created for breaking changes to an extension. If a client requests a versions of an extension that the agent does not support, the agent **SHOULD** ignore the extension for that interaction and proceed without it, unless the extension is marked as `required` in the AgentCard, in which case the agent **MUST** return an error indicating unsupported extension. It **MUST NOT** fall back to a previous version of the extension automatically. ## 5. Protocol Binding Requirements and Interoperability ### 5.1. Functional Equivalence Requirements When an agent supports multiple protocols, all supported protocols **MUST**: - **Identical Functionality**: Provide the same set of operations and capabilities - **Consistent Behavior**: Return semantically equivalent results for the same requests - **Same Error Handling**: Map errors consistently using appropriate protocol-specific codes - **Equivalent Authentication**: Support the same authentication schemes declared in the AgentCard ### 5.2. Protocol Selection and Negotiation - **Agent Declaration**: Agents **MUST** declare all supported protocols in their AgentCard - **Client Choice**: Clients **MAY** choose any protocol declared by the agent - **Fallback Behavior**: Clients **SHOULD** implement fallback logic for alternative protocols ### 5.3. Method Mapping Reference | Functionality | JSON-RPC Method | gRPC Method | REST Endpoint | | :------------------------------ | :--------------------------------- | :--------------------------------- | :------------------------------------------------------ | | Send message | `SendMessage` | `SendMessage` | `POST /message:send` | | Stream message | `SendStreamingMessage` | `SendStreamingMessage` | `POST /message:stream` | | Get task | `GetTask` | `GetTask` | `GET /tasks/{id}` | | List tasks | `ListTasks` | `ListTasks` | `GET /tasks` | | Cancel task | `CancelTask` | `CancelTask` | `POST /tasks/{id}:cancel` | | Subscribe to task | `SubscribeToTask` | `SubscribeToTask` | `POST /tasks/{id}:subscribe` | | Create push notification config | `CreateTaskPushNotificationConfig` | `CreateTaskPushNotificationConfig` | `POST /tasks/{id}/pushNotificationConfigs` | | Get push notification config | `GetTaskPushNotificationConfig` | `GetTaskPushNotificationConfig` | `GET /tasks/{id}/pushNotificationConfigs/{configId}` | | List push notification configs | `ListTaskPushNotificationConfigs` | `ListTaskPushNotificationConfigs` | `GET /tasks/{id}/pushNotificationConfigs` | | Delete push notification config | `DeleteTaskPushNotificationConfig` | `DeleteTaskPushNotificationConfig` | `DELETE /tasks/{id}/pushNotificationConfigs/{configId}` | | Get extended Agent Card | `GetExtendedAgentCard` | `GetExtendedAgentCard` | `GET /extendedAgentCard` | ### 5.4. Error Code Mappings All A2A-specific errors defined in [Section 3.3.2](#332-error-handling) **MUST** be mapped to binding-specific error representations. The following table provides the canonical mappings for each standard protocol binding: | A2A Error Type | JSON-RPC Code | gRPC Status | HTTP Status | | :------------------------------------ | :------------ | :-------------------- | :--------------------------- | | `TaskNotFoundError` | `-32001` | `NOT_FOUND` | `404 Not Found` | | `TaskNotCancelableError` | `-32002` | `FAILED_PRECONDITION` | `409 Conflict` | | `PushNotificationNotSupportedError` | `-32003` | `UNIMPLEMENTED` | `400 Bad Request` | | `UnsupportedOperationError` | `-32004` | `UNIMPLEMENTED` | `400 Bad Request` | | `ContentTypeNotSupportedError` | `-32005` | `INVALID_ARGUMENT` | `415 Unsupported Media Type` | | `InvalidAgentResponseError` | `-32006` | `INTERNAL` | `502 Bad Gateway` | | `ExtendedAgentCardNotConfiguredError` | `-32007` | `FAILED_PRECONDITION` | `400 Bad Request` | | `ExtensionSupportRequiredError` | `-32008` | `FAILED_PRECONDITION` | `400 Bad Request` | | `VersionNotSupportedError` | `-32009` | `UNIMPLEMENTED` | `400 Bad Request` | **Custom Binding Requirements:** Custom protocol bindings **MUST** define equivalent error code mappings that preserve the semantic meaning of each A2A error type. The binding specification **SHOULD** provide a similar mapping table showing how each A2A error type is represented in the custom binding's native error format. For binding-specific error structures and examples, see: - [JSON-RPC Error Handling](#95-error-handling) - [gRPC Error Handling](#106-error-handling) - [HTTP/REST Error Handling](#116-error-handling) ### 5.5. JSON Field Naming Convention All JSON serializations of the A2A protocol data model **MUST** use **camelCase** naming for field names, not the snake_case convention used in Protocol Buffer definitions. **Naming Convention:** - Protocol Buffer field: `protocol_version` → JSON field: `protocolVersion` - Protocol Buffer field: `context_id` → JSON field: `contextId` - Protocol Buffer field: `default_input_modes` → JSON field: `defaultInputModes` - Protocol Buffer field: `push_notification_config` → JSON field: `pushNotificationConfig` **Enum Values:** - Enum values **MUST** be represented according to the [ProtoJSON specification](https://protobuf.dev/programming-guides/json/), which serializes enums as their string names **as defined in the Protocol Buffer definition** (typically SCREAMING_SNAKE_CASE). **Examples:** - Protocol Buffer enum: `TASK_STATE_INPUT_REQUIRED` → JSON value: `"TASK_STATE_INPUT_REQUIRED"` - Protocol Buffer enum: `ROLE_USER` → JSON value: `"ROLE_USER"` **Note:** This follows the ProtoJSON specification as adopted in [ADR-001](../adrs/adr-001-protojson-serialization.md). ### 5.6. Data Type Conventions This section documents conventions for common data types used throughout the A2A protocol, particularly as they apply to protocol bindings. #### 5.6.1. Timestamps The A2A protocol uses [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) for all timestamp fields in the Protocol Buffer definitions. When serialized to JSON (in JSON-RPC, HTTP/REST, or other JSON-based bindings), these timestamps **MUST** be represented as ISO 8601 formatted strings in UTC timezone. **Format Requirements:** - **Format:** ISO 8601 combined date and time representation - **Timezone:** UTC (denoted by 'Z' suffix) - **Precision:** Millisecond precision **SHOULD** be used where available - **Pattern:** `YYYY-MM-DDTHH:mm:ss.sssZ` **Examples:** ```json { "timestamp": "2025-10-28T10:30:00.000Z", "createdAt": "2025-10-28T14:25:33.142Z", "lastModified": "2025-10-31T17:45:22.891Z" } ``` **Implementation Notes:** - Protocol Buffer's `google.protobuf.Timestamp` represents time as seconds since Unix epoch (January 1, 1970, 00:00:00 UTC) plus nanoseconds - JSON serialization automatically converts this to ISO 8601 format when using standard Protocol Buffer JSON encoding - Clients and servers **MUST** parse and generate ISO 8601 timestamps correctly - When millisecond precision is not available, the fractional seconds portion **MAY** be omitted or zero-filled - Timestamps **MUST NOT** include timezone offsets other than 'Z' (all times are UTC) ### 5.7. Field Presence and Optionality The Protocol Buffer definition in `specification/a2a.proto` uses [`google.api.field_behavior`](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) annotations to indicate whether fields are `REQUIRED`. These annotations serve as both documentation and validation hints for implementations. **Required Fields:** Fields marked with `[(google.api.field_behavior) = REQUIRED]` indicate that the field **MUST** be present and set in valid messages. Implementations **SHOULD** validate these requirements and reject messages with missing required fields. Arrays marked as required **MUST** contain at least one element. **Optional Field Presence:** The Protocol Buffer `optional` keyword is used to distinguish between a field being explicitly set versus omitted. This distinction is critical for two scenarios: 1. **Explicit Default Values:** Some fields in the specification define default values that differ from Protocol Buffer's implicit defaults. Implementations should apply the default value when the field is not explicitly provided. 2. **Agent Card Canonicalization:** When creating cryptographic signatures of Agent Cards, it is required to produce a canonical JSON representation. The `optional` keyword enables implementations to distinguish between fields that were explicitly set (and should be included in the canonical form) versus fields that were omitted (and should be excluded from canonicalization). This ensures Agent Cards can be reconstructed to accurately match their signature. **Unrecognized Fields:** Implementations **SHOULD** ignore unrecognized fields in messages, allowing for forward compatibility as the protocol evolves. ## 6. Common Workflows & Examples This section provides illustrative examples of common A2A interactions across different bindings. ### 6.1. Basic Task Execution **Scenario:** Client asks a question and receives a completed task response. **Request:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "ROLE_USER", "parts": [{"text": "What is the weather today?"}], "messageId": "msg-uuid" } } ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "task-uuid", "contextId": "context-uuid", "status": {"state": "TASK_STATE_COMPLETED"}, "artifacts": [{ "artifactId": "artifact-uuid", "name": "Weather Report", "parts": [{"text": "Today will be sunny with a high of 75°F"}] }] } } ``` ### 6.2. Streaming Task Execution **Scenario:** Client requests a long-running task with real-time updates. **Request:** ```http POST /message:stream HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "ROLE_USER", "parts": [{"text": "Write a detailed report on climate change"}], "messageId": "msg-uuid" } } ``` **SSE Response Stream:** ```http HTTP/1.1 200 OK Content-Type: text/event-stream data: {"task": {"id": "task-uuid", "status": {"state": "TASK_STATE_WORKING"}}} data: {"artifactUpdate": {"taskId": "task-uuid", "artifact": {"parts": [{"text": "# Climate Change Report\n\n"}]}}} data: {"statusUpdate": {"taskId": "task-uuid", "status": {"state": "TASK_STATE_COMPLETED"}}} ``` ### 6.3. Multi-Turn Interaction **Scenario:** Agent requires additional input to complete a task. **Initial Request:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "ROLE_USER", "parts": [{"text": "Book me a flight"}], "messageId": "msg-1" } } ``` **Response (Input Required):** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "task-uuid", "status": { "state": "TASK_STATE_INPUT_REQUIRED", "message": { "role": "ROLE_AGENT", "parts": [{"text": "I need more details. Where would you like to fly from and to?"}] } } } } ``` **Follow-up Request:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "taskId": "task-uuid", "role": "ROLE_USER", "parts": [{"text": "From San Francisco to New York"}], "messageId": "msg-2" } } ``` ### 6.4. Version Negotiation Error **Scenario:** Client requests an unsupported protocol version. **Request:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token A2A-Version: 0.5 { "message": { "role": "ROLE_USER", "parts": [{"text": "Hello"}], "messageId": "msg-uuid" } } ``` **Response:** ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json { "type": "https://a2a-protocol.org/errors/version-not-supported", "title": "Protocol Version Not Supported", "status": 400, "detail": "The requested A2A protocol version 0.5 is not supported by this agent", "supportedVersions": ["0.3"] } ``` ### 6.5. Task Listing and Management **Scenario:** Client wants to see all tasks from a specific context or all tasks with a particular status. #### Request: All tasks from a specific context **Request:** ```http GET /tasks?contextId=c295ea44-7543-4f78-b524-7a38915ad6e4&pageSize=10&historyLength=3 HTTP/1.1 Host: agent.example.com Authorization: Bearer token ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "tasks": [ { "id": "3f36680c-7f37-4a5f-945e-d78981fafd36", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2024-03-15T10:15:00Z" } } ], "totalSize": 5, "pageSize": 10, "nextPageToken": "" } ``` #### Request: All working tasks across all contexts **Request:** ```http GET /tasks?status=TASK_STATE_WORKING&pageSize=20 HTTP/1.1 Host: agent.example.com Authorization: Bearer token ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "tasks": [ { "id": "789abc-def0-1234-5678-9abcdef01234", "contextId": "another-context-id", "status": { "state": "TASK_STATE_WORKING", "message": { "role": "ROLE_AGENT", "parts": [ { "text": "Processing your document analysis..." } ], "messageId": "msg-status-update" }, "timestamp": "2024-03-15T10:20:00Z" } } ], "totalSize": 1, "pageSize": 20, "nextPageToken": "" } ``` #### Pagination Example **Request:** ```http GET /tasks?contextId=c295ea44-7543-4f78-b524-7a38915ad6e4&pageSize=10&pageToken=base64-encoded-cursor-token HTTP/1.1 Host: agent.example.com Authorization: Bearer token ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "tasks": [ /* ... additional tasks */ ], "totalSize": 15, "pageSize": 10, "nextPageToken": "base64-encoded-next-cursor-token" } ``` #### Validation Error Example **Request:** ```http GET /tasks?pageSize=150&historyLength=-5&status=TASK_STATE_RUNNING HTTP/1.1 Host: agent.example.com Authorization: Bearer token ``` **Response:** ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json { "status": 400, "detail": "Invalid parameters", "errors": [ { "field": "pageSize", "message": "Must be between 1 and 100 inclusive, got 150" }, { "field": "historyLength", "message": "Must be non-negative integer, got -5" }, { "field": "status", "message": "Invalid status value 'running'. Must be one of: pending, working, completed, failed, canceled" } ] } ``` ### 6.6. Push Notification Setup and Usage **Scenario:** Client requests a long-running report generation and wants to be notified via webhook when it's done. **Initial Request with Push Notification Config:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "ROLE_USER", "parts": [ { "text": "Generate the Q1 sales report. This usually takes a while. Notify me when it's ready." } ], "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6" }, "configuration": { "pushNotificationConfig": { "url": "https://client.example.com/webhook/a2a-notifications", "token": "secure-client-token-for-task-aaa", "authentication": { "schemes": ["Bearer"] } } } } ``` **Response (Task Submitted):** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "43667960-d455-4453-b0cf-1bae4955270d", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "submitted", "timestamp": "2024-03-15T11:00:00Z" } } } ``` **Later: Server POSTs Notification to Webhook:** ```http POST /webhook/a2a-notifications HTTP/1.1 Host: client.example.com Authorization: Bearer server-generated-jwt Content-Type: application/a2a+json X-A2A-Notification-Token: secure-client-token-for-task-aaa { "statusUpdate": { "taskId": "43667960-d455-4453-b0cf-1bae4955270d", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2024-03-15T18:30:00Z" } } } ``` ### 6.7. File Exchange (Upload and Download) **Scenario:** Client sends an image for analysis, and the agent returns a modified image. **Request with File Upload:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "ROLE_USER", "parts": [ { "text": "Analyze this image and highlight any faces." }, { "raw": "iVBORw0KGgoAAAANSUhEUgAAAAUA..." "filename": "input_image.png", "mediaType": "image/png", } ], "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6" } } ``` **Response with File Reference:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "43667960-d455-4453-b0cf-1bae4955270d", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2024-03-15T12:05:00Z" }, "artifacts": [ { "artifactId": "9b6934dd-37e3-4eb1-8766-962efaab63a1", "name": "processed_image_with_faces.png", "parts": [ { "url": "https://storage.example.com/processed/task-bbb/output.png?token=xyz", "filename": "output.png", "mediaType": "image/png" } ] } ] } } ``` ### 6.8. Structured Data Exchange **Scenario:** Client asks for a list of open support tickets in a specific JSON format. **Request:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/a2a+json Authorization: Bearer token { "message": { "role": "ROLE_USER", "parts": [ { "text": "Show me a list of my open IT tickets", "metadata": { "mediaType": "application/json", "schema": { "type": "array", "items": { "type": "object", "properties": { "ticketNumber": { "type": "string" }, "description": { "type": "string" } } } } } } ], "messageId": "85b26db5-ffbb-4278-a5da-a7b09dea1b47" } } ``` **Response with Structured Data:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "task": { "id": "d8c6243f-5f7a-4f6f-821d-957ce51e856c", "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4", "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2025-04-17T17:47:09.680794Z" }, "artifacts": [ { "artifactId": "c5e0382f-b57f-4da7-87d8-b85171fad17c", "parts": [ { "text": "[{\"ticketNumber\":\"REQ12312\",\"description\":\"request for VPN access\"},{\"ticketNumber\":\"REQ23422\",\"description\":\"Add to DL - team-gcp-onboarding\"}]" } ] } ] } } ``` ### 6.9. Fetching Authenticated Extended Agent Card **Scenario:** A client discovers a public Agent Card indicating support for an authenticated extended card and wants to retrieve the full details. **Step 1: Client fetches the public Agent Card:** ```http GET /.well-known/agent-card.json HTTP/1.1 Host: example.com ``` **Response includes:** ```json { "capabilities": { "extendedAgentCard": true }, "securitySchemes": { "google": { "openIdConnectSecurityScheme": { "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration" } } } } ``` ### Step 2: Client obtains credentials (out-of-band OAuth 2.0 flow) ### Step 3: Client fetches authenticated extended Agent Card ```http GET /extendedAgentCard HTTP/1.1 Host: agent.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` **Response:** ```http HTTP/1.1 200 OK Content-Type: application/a2a+json { "name": "Extended Agent with Additional Skills", "skills": [ /* Extended skills available to authenticated users */ ] } ``` ## 7. Authentication and Authorization A2A treats agents as standard enterprise applications, relying on established web security practices. Identity information is handled at the protocol layer, not within A2A semantics. For a comprehensive guide on enterprise security aspects, see [Enterprise-Ready Features](./topics/enterprise-ready.md). ### 7.1. Protocol Security Production deployments **MUST** use encrypted communication (HTTPS for HTTP-based bindings, TLS for gRPC). Implementations **SHOULD** use modern TLS configurations (TLS 1.3+ recommended) with strong cipher suites. ### 7.2. Server Identity Verification A2A Clients **SHOULD** verify the A2A Server's identity by validating its TLS certificate against trusted certificate authorities (CAs) during the TLS handshake. ### 7.3. Client Authentication Process 1. **Discovery of Requirements:** The client discovers the server's required authentication schemes via the `securitySchemes` field in the AgentCard. 2. **Credential Acquisition (Out-of-Band):** The client obtains the necessary credentials through an out-of-band process specific to the required authentication scheme. 3. **Credential Transmission:** The client includes these credentials in protocol-appropriate headers or metadata for every A2A request. ### 7.4. Server Authentication Responsibilities The A2A Server: - **MUST** authenticate every incoming request based on the provided credentials and its declared authentication requirements. - **SHOULD** use appropriate binding-specific error codes for authentication challenges or rejections. - **SHOULD** provide relevant authentication challenge information with error responses. ### 7.5. Server Authorization Responsibilities Once authenticated, the A2A Server authorizes requests based on the authenticated identity and its own policies. Authorization logic is implementation-specific and **MAY** consider: - Specific skills requested - Actions attempted within tasks - Data access policies - OAuth scopes (if applicable) ### 7.6. In-Task Authorization In the course of performing a task, an agent may require authorization to perform some action. Examples include: - An agent requiring an OAuth access token to call an API or another agent - An agent requiring human approval before a destructive action is taken In the sections below, we refer to the object that represents the approved authorization as a credential. Agents may have multiple means for retrieving this authorization, such as via directly sending messages to a human. A2A provides the capability for agents to delegate the fulfillment of this authorization to the client via the `TASK_STATE_AUTH_REQUIRED` Task state. This provides agents a fallback path for requesting authorization by passing the responsibility to the client. #### 7.6.1 In-Task Authorization Agent Responsibilities To request that a client fulfills an authorization request, the agent: 1. MUST use a Task to track the operation it is performing 2. MUST transition the TaskState to `TASK_STATE_AUTH_REQUIRED` 3. MUST include a TaskStatus message explaining the required authorization, unless the details of the authorization have been negotiated out-of-band or via an extension Agents MUST arrange to receive credentials via an out-of-band means, unless an in-band mechanism has been negotiated out-of-band or via an extension. If the credential is received out-of-band, the agent SHOULD maintain any active response streams with the client after setting the TaskState to `TASK_STATE_AUTH_REQUIRED`. The agent MAY immediately continue Task processing after receiving the credential, without a requirement that clients send a follow-up message. Agents SHOULD support receiving messages directed to the Task while the Task remains in `TASK_STATE_AUTH_REQUIRED`. This enables clients to negotiate, correct, or reject an authorization request. #### 7.6.2 In-Task Authorization Client Responsibilities Upon receiving a Task in `TASK_STATE_AUTH_REQUIRED`, a client is expected to take action in some way to resolve the agent's request for authorization. A client may: - Send a response message to the Task to negotiate, correct, or reject the authorization request. - Contact another human, agent, or service to fulfill the authorization request - Directly fulfill the authorization request via an out-of-band or extension negotiated means If the client is itself an A2A agent actively processing a Task, the client may further delegate the authorization request to its client by transitioning its own Task to `TASK_STATE_AUTH_REQUIRED`. The client SHOULD follow all [In-Task Authorization Agent Responsibilities](#761-in-task-authorization-agent-responsibilities). This enables forming a chain of Tasks in `TASK_STATE_AUTH_REQUIRED`. Clients may not be aware of when the agent receives credentials out-of-band and subsequently continues Task processing. If a client does not have an active response stream open with the agent, the client risks missing Task updates. To avoid this, a client SHOULD perform one of the following: - Subscribe to a stream of events for the Task using the [Subscribe to Task](#316-subscribe-to-task) operation - Register a webhook to receive events, if supported by the agent, using the [Create Push Notification Config](#317-create-push-notification-config) operation - Begin polling the Task using the [Get Task](#313-get-task) operation #### 7.6.3 In-Task Authorization Security Considerations Agents SHOULD receive credentials for in-task authorization requests out of band via a secure channel, such as HTTPS. This ensures that credentials are provided directly to the agent. In-band credential exchange may be negotiated via out-of-band means or by using extensions. In-band credential exchange can allow credentials to be passed across chains of multiple A2A agents, exposing those credentials to each agent participating in the chain. If using in-band credential exchange, we recommend adhering to the following security practices: - Credentials SHOULD be bound to the agent which originated the request, such that only this agent is able to use the credentials. This ensures that credentials propagating through a chain of A2A requests are only usable by the requesting agent. - Credentials containing sensitive information SHOULD be only readable by the agent which originated the request, such as by encrypting the credential. ## 8. Agent Discovery: The Agent Card ### 8.1. Purpose A2A Servers **MUST** make an Agent Card available. The Agent Card describes the server's identity, capabilities, skills, and interaction requirements. Clients use this information for discovering suitable agents and configuring interactions. For more on discovery strategies, see the [Agent Discovery guide](./topics/agent-discovery.md). ### 8.2. Discovery Mechanisms Clients can find Agent Cards through: - **Well-Known URI:** Accessing `https://{server_domain}/.well-known/agent-card.json` (see [Section 8.6](#86-caching) for caching guidance) - **Registries/Catalogs:** Querying curated catalogs of agents - **Direct Configuration:** Pre-configured Agent Card URLs or content ### 8.3. Protocol Declaration Requirements The AgentCard **MUST** properly declare supported protocols: #### 8.3.1. Supported Interfaces Declaration - The `supportedInterfaces` field **SHOULD** declare all supported protocol combinations in preference order - The first entry in `supportedInterfaces` represents the preferred interface - Each interface **MUST** accurately declare its transport protocol and URL - URLs **MAY** be reused if multiple transports are available at the same endpoint #### 8.3.2. Client Protocol Selection Clients **MUST** follow these rules: 1. Parse `supportedInterfaces` if present, and select the first supported transport 2. Prefer earlier entries in the ordered list when multiple options are supported 3. Use the correct URL for the selected transport ### 8.4. Agent Card Signing Agent Cards **MAY** be digitally signed using JSON Web Signature (JWS) as defined in [RFC 7515](https://tools.ietf.org/html/rfc7515) to ensure authenticity and integrity. Signatures allow clients to verify that an Agent Card has not been tampered with and originates from the claimed provider. #### 8.4.1. Canonicalization Requirements Before signing, the Agent Card content **MUST** be canonicalized using the JSON Canonicalization Scheme (JCS) as defined in [RFC 8785](https://tools.ietf.org/html/rfc8785). This ensures consistent signature generation and verification across different JSON implementations. **Canonicalization Rules:** 1. **Field Presence and Default Value Handling**: Before canonicalization, the JSON representation **MUST** respect Protocol Buffer field presence semantics as defined in [Section 5.7](#57-field-presence-and-optionality). This ensures that the canonical form accurately reflects which fields were explicitly provided versus which were omitted, enabling signature verification when Agent Cards are reconstructed: - **Optional fields not explicitly set**: Fields marked with the `optional` keyword that were not explicitly set **MUST** be omitted from the JSON object - **Optional fields explicitly set to defaults**: Fields marked with `optional` that were explicitly set to a value (even if that value matches a default) **MUST** be included in the JSON object - **Required fields**: Fields marked with `REQUIRED` **MUST** always be present, even if the field value matches the default. - **Default values**: Fields with default values **MUST** be omitted unless the field is marked as `REQUIRED` or has the `optional` keyword. 2. **RFC 8785 Compliance**: The Agent Card JSON **MUST** be canonicalized according to RFC 8785, which specifies: - Predictable ordering of object properties (lexicographic by key) - Consistent representation of numbers, strings, and other primitive values - Removal of insignificant whitespace 3. **Signature Field Exclusion**: The `signatures` field itself **MUST** be excluded from the content being signed to avoid circular dependencies. **Example of Default Value Removal:** Original Agent Card fragment: ```json { "name": "Example Agent", "description": "", "capabilities": { "streaming": false, "pushNotifications": false, "extensions": [] }, "skills": [] } ``` Applying the canonicalization rules: - `name`: "Example Agent" - REQUIRED field → **include** - `description`: "" - REQUIRED field → **include** - `capabilities`: object - REQUIRED field → **include** (after processing children) - `streaming`: false - optional field, present in JSON (explicitly set) → **include** - `pushNotifications`: false - optional field, present in JSON (explicitly set) → **include** - `extensions`: [] - repeated field (not REQUIRED) with empty array → **omit** - `skills`: [] - REQUIRED field → **include** After applying RFC 8785: ```json {"capabilities":{"pushNotifications":false,"streaming":false},"description":"","name":"Example Agent","skills":[]} ``` #### 8.4.2. Signature Format Signatures use the JSON Web Signature (JWS) format as defined in [RFC 7515](https://tools.ietf.org/html/rfc7515). The [`AgentCardSignature`](#447-agentcardsignature) object represents JWS components using three fields: - **`protected`** (required, string): Base64url-encoded JSON object containing the JWS Protected Header - **`signature`** (required, string): Base64url-encoded signature value - **`header`** (optional, object): JWS Unprotected Header as a JSON object (not base64url-encoded) **JWS Protected Header Parameters:** The protected header **MUST** include: - `alg`: Algorithm used for signing (e.g., "ES256", "RS256") - `typ`: **SHOULD** be set to "JOSE" for JWS - `kid`: Key ID for identifying the signing key The protected header **MAY** include: - `jku`: URL to JSON Web Key Set (JWKS) containing the public key **Signature Generation Process:** 1. **Prepare the payload:** - Remove properties with default values from the Agent Card - Exclude the `signatures` field - Canonicalize the resulting JSON using RFC 8785 to produce the canonical payload 2. **Create the protected header:** - Construct a JSON object with the required header parameters (`alg`, `typ`, `kid`) and any optional parameters (`jku`) - Serialize the header to JSON - Base64url-encode the serialized header to produce the `protected` field value 3. **Compute the signature:** - Construct the JWS Signing Input: `ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload))` - Sign the JWS Signing Input using the algorithm specified in the `alg` header parameter and the private key - Base64url-encode the resulting signature bytes to produce the `signature` field value 4. **Assemble the AgentCardSignature:** - Set `protected` to the base64url-encoded protected header from step 2 - Set `signature` to the base64url-encoded signature value from step 3 - Optionally set `header` to a JSON object containing any unprotected header parameters. **Example:** Given a canonical Agent Card payload and signing key, the signature generation produces: ```json { "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0", "signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ" } ``` Where the `protected` value decodes to: ```json {"alg":"ES256","typ":"JOSE","kid":"key-1","jku":"https://example.com/agent/jwks.json"} ``` #### 8.4.3. Signature Verification Clients verifying Agent Card signatures **MUST**: 1. Extract the signature from the `signatures` array 2. Retrieve the public key using the `kid` and `jku` (or from a trusted key store) 3. Remove properties with default values from the received Agent Card 4. Exclude the `signatures` field 5. Canonicalize the resulting JSON using RFC 8785 6. Verify the signature against the canonicalized payload **Security Considerations:** - Clients **SHOULD** verify at least one signature before trusting an Agent Card - Public keys **SHOULD** be retrieved over secure channels (HTTPS) - Clients **MAY** maintain a trusted key store for known agent providers - Expired or revoked keys **MUST NOT** be used for verification - Multiple signatures **MAY** be present to support key rotation ### 8.5. Sample Agent Card ```json { "name": "GeoSpatial Route Planner Agent", "description": "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.", "supportedInterfaces": [ {"url": "https://georoute-agent.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}, {"url": "https://georoute-agent.example.com/a2a/grpc", "protocolBinding": "GRPC", "protocolVersion": "1.0"}, {"url": "https://georoute-agent.example.com/a2a/json", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"} ], "provider": { "organization": "Example Geo Services Inc.", "url": "https://www.examplegeoservices.com" }, "iconUrl": "https://georoute-agent.example.com/icon.png", "version": "1.2.0", "documentationUrl": "https://docs.examplegeoservices.com/georoute-agent/api", "capabilities": { "streaming": true, "pushNotifications": true, "stateTransitionHistory": false, "extendedAgentCard": true }, "securitySchemes": { "google": { "openIdConnectSecurityScheme": { "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration" } } }, "security": [{ "google": ["openid", "profile", "email"] }], "defaultInputModes": ["application/json", "text/plain"], "defaultOutputModes": ["application/json", "image/png"], "skills": [ { "id": "route-optimizer-traffic", "name": "Traffic-Aware Route Optimizer", "description": "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).", "tags": ["maps", "routing", "navigation", "directions", "traffic"], "examples": [ "Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.", "{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}" ], "inputModes": ["application/json", "text/plain"], "outputModes": [ "application/json", "application/vnd.geo+json", "text/html" ] }, { "id": "custom-map-generator", "name": "Personalized Map Generator", "description": "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.", "tags": ["maps", "customization", "visualization", "cartography"], "examples": [ "Generate a map of my upcoming road trip with all planned stops highlighted.", "Show me a map visualizing all coffee shops within a 1-mile radius of my current location." ], "inputModes": ["application/json"], "outputModes": [ "image/png", "image/jpeg", "application/json", "text/html" ] } ], "signatures": [ { "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0", "signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ" } ] } ``` ### 8.6. Caching Agent Card content changes infrequently relative to the frequency at which clients may fetch it. Servers and clients **SHOULD** use standard HTTP caching mechanisms to reduce unnecessary network overhead. #### 8.6.1. Server Requirements - Agent Card HTTP endpoints **SHOULD** include a `Cache-Control` response header with a `max-age` directive appropriate for the agent's expected update frequency - Agent Card HTTP endpoints **SHOULD** include an `ETag` response header derived from the Agent Card's `version` field or a hash of the card content - Agent Card HTTP endpoints **MAY** include a `Last-Modified` response header #### 8.6.2. Client Requirements - Clients **SHOULD** honor HTTP caching semantics as defined in [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) when fetching Agent Cards - When a cached Agent Card has expired, clients **SHOULD** use conditional requests (`If-None-Match` with the stored `ETag`, or `If-Modified-Since`) to avoid re-downloading unchanged cards - When the server does not include caching headers, clients **MAY** apply an implementation-specific default cache duration ## 9. JSON-RPC Protocol Binding The JSON-RPC protocol binding provides a simple, HTTP-based interface using JSON-RPC 2.0 for method calls and Server-Sent Events for streaming. ### 9.1. Protocol Requirements - **Protocol:** JSON-RPC 2.0 over HTTP(S) - **Content-Type:** `application/json` for requests and responses - **Method Naming:** PascalCase method names matching gRPC conventions (e.g., `SendMessage`, `GetTask`) - **Streaming:** Server-Sent Events (`text/event-stream`) ### 9.2. Service Parameter Transmission A2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using standard HTTP request headers, as JSON-RPC 2.0 operates over HTTP(S). **Service Parameter Requirements:** - Service parameter names **MUST** be transmitted as HTTP header fields - Service parameter keys are case-insensitive per HTTP specification (RFC 7230) - Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single header field **Example Request with A2A Service Parameters:** ```http POST /rpc HTTP/1.1 Host: agent.example.com Content-Type: application/json Authorization: Bearer token A2A-Version: 0.3 A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 { "jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": { /* SendMessageRequest */ } } ``` ### 9.3. Base Request Structure All JSON-RPC requests **MUST** follow the standard JSON-RPC 2.0 format: ```json { "jsonrpc": "2.0", "id": "unique-request-id", "method": "category/action", "params": { /* method-specific parameters */ } } ``` ### 9.4. Core Methods #### 9.4.1. `SendMessage` Sends a message to initiate or continue a task. **Request:** ```json { "jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": { /* SendMessageRequest object */ } } ``` **Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest), [`Message`](#414-message) **Response:** ```json { "jsonrpc": "2.0", "id": 1, "result": { /* SendMessageResponse object, contains one of: * "task": { Task object } * "message": { Message object } */ } ``` **Referenced Objects:** [`Task`](#411-task), [`Message`](#414-message) #### 9.4.2. `SendStreamingMessage` Sends a message and subscribes to real-time updates via Server-Sent Events. **Request:** Same as `SendMessage` **Response:** HTTP 200 with `Content-Type: text/event-stream` ```text data: {"jsonrpc": "2.0", "id": 1, "result": { /* StreamResponse object */ }} data: {"jsonrpc": "2.0", "id": 1, "result": { /* StreamResponse object */ }} ``` **Referenced Objects:** [`StreamResponse`](#323-stream-response) #### 9.4.3. `GetTask` Retrieves the current state of a task. **Request:** ```json { "jsonrpc": "2.0", "id": 2, "method": "GetTask", "params": { "id": "task-uuid", "historyLength": 10 } } ``` #### 9.4.4. `ListTasks` Lists tasks with optional filtering and pagination. **Request:** ```json { "jsonrpc": "2.0", "id": 3, "method": "ListTasks", "params": { "contextId": "context-uuid", "status": "TASK_STATE_WORKING", "pageSize": 50, "pageToken": "cursor-token" } } ``` #### 9.4.5. `CancelTask` Cancels an ongoing task. **Request:** ```json { "jsonrpc": "2.0", "id": 4, "method": "CancelTask", "params": { "id": "task-uuid" } } ``` #### 9.4.6. `SubscribeToTask` Subscribes to a task stream for receiving updates on a task that is not in a terminal state. **Request:** ```json { "jsonrpc": "2.0", "id": 5, "method": "SubscribeToTask", "params": { "id": "task-uuid" } } ``` **Response:** SSE stream (same format as `SendStreamingMessage`) **Error:** Returns `UnsupportedOperationError` if the task is in a terminal state (`completed`, `failed`, `canceled`, or `rejected`). #### 9.4.7. Push Notification Configuration Methods - `CreateTaskPushNotificationConfig` - Create push notification configuration - `GetTaskPushNotificationConfig` - Get push notification configuration - `ListTaskPushNotificationConfigs` - List push notification configurations - `DeleteTaskPushNotificationConfig` - Delete push notification configuration #### 9.4.8. `GetExtendedAgentCard` Retrieves an extended Agent Card. **Request:** ```json { "jsonrpc": "2.0", "id": 6, "method": "GetExtendedAgentCard" } ``` ### 9.5. Error Handling JSON-RPC error responses use the standard [JSON-RPC 2.0 error object](https://www.jsonrpc.org/specification#error_object) structure, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows: - **Error Code**: Mapped to `error.code` (numeric JSON-RPC error code) - **Error Message**: Mapped to `error.message` (human-readable string) - **Error Details**: Mapped to `error.data` (array containing `google.protobuf.Any` messages, using ProtoJSON representation) **Standard JSON-RPC Error Codes:** | JSON-RPC Error Code | Error Name | Standard Message | Description | | :------------------ | :-------------------- | :--------------------------------- | :------------------------------------------------------ | | `-32700` | `JSONParseError` | "Invalid JSON payload" | The server received invalid JSON | | `-32600` | `InvalidRequestError` | "Request payload validation error" | The JSON sent is not a valid Request object | | `-32601` | `MethodNotFoundError` | "Method not found" | The requested method does not exist or is not available | | `-32602` | `InvalidParamsError` | "Invalid parameters" | The method parameters are invalid | | `-32603` | `InternalError` | "Internal error" | An internal error occurred on the server | **A2A-Specific Error Codes:** A2A-specific errors use codes in the range `-32001` to `-32099`. For the complete mapping of A2A error types to JSON-RPC error codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings). **A2A Error Representation:** For A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `data` array with: - `@type`: Set to `"type.googleapis.com/google.rpc.ErrorInfo"` - `reason`: The A2A error type in UPPER_SNAKE_CASE without the "Error" suffix (e.g., `TASK_NOT_FOUND`) - `domain`: Set to `"a2a-protocol.org"` - `metadata`: Optional map of additional error context Additional error context **MAY** be included in the `data` array. **Error Response Structure:** ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found", "data": { "method": "invalid/method" } } } ``` **Example A2A-Specific Error Response:** ```json { "jsonrpc": "2.0", "id": 2, "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": "nonexistent-task-id", "timestamp": "2025-11-09T10:30:00.000Z" } } ] } } ``` ## 10. gRPC Protocol Binding The gRPC Protocol Binding provides a high-performance, strongly-typed interface using Protocol Buffers over HTTP/2. The gRPC Protocol Binding leverages the [API guidelines](https://google.aip.dev/general) to simplify gRPC to HTTP mapping. ### 10.1. Protocol Requirements - **Protocol:** gRPC over HTTP/2 with TLS - **Definition:** Use the normative Protocol Buffers definition in `specification/a2a.proto` - **Serialization:** Protocol Buffers version 3 - **Service:** Implement the `A2AService` gRPC service ### 10.2. Service Parameter Transmission A2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using gRPC metadata (headers). **Service Parameter Requirements:** - Service parameter names **MUST** be transmitted as gRPC metadata keys - Metadata keys are case-insensitive and automatically converted to lowercase by gRPC - Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single metadata entry **Example gRPC Request with A2A Service Parameters:** ```go // Go example using gRPC metadata md := metadata.Pairs( "authorization", "Bearer token", "a2a-version", "0.3", "a2a-extensions", "https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1", ) ctx := metadata.NewOutgoingContext(context.Background(), md) // Make the RPC call with the context containing metadata response, err := client.SendMessage(ctx, request) ``` **Metadata Handling:** - Implementations **MUST** extract A2A service parameters from gRPC metadata for processing - Servers **SHOULD** validate required service parameters (e.g., `A2A-Version`) from metadata - Service parameter keys in metadata are normalized to lowercase per gRPC conventions ### 10.3. Service Definition {{ proto_service_to_table("A2AService") }} ### 10.4. Core Methods #### 10.4.1. SendMessage Sends a message to an agent. **Request:** {{ proto_to_table("SendMessageRequest") }} **Response:** {{ proto_to_table("SendMessageResponse") }} #### 10.4.2. SendStreamingMessage Sends a message with streaming updates. **Request:** {{ proto_to_table("SendMessageRequest") }} **Response:** Server streaming [`StreamResponse`](#stream-response) objects. #### 10.4.3. GetTask Retrieves task status. **Request:** {{ proto_to_table("GetTaskRequest") }} **Response:** See [`Task`](#411-task) object definition. #### 10.4.4. ListTasks Lists tasks with filtering. **Request:** {{ proto_to_table("ListTasksRequest") }} **Response:** {{ proto_to_table("ListTasksResponse") }} #### 10.4.5. CancelTask Cancels a running task. **Request:** {{ proto_to_table("CancelTaskRequest") }} **Response:** See [`Task`](#411-task) object definition. #### 10.4.6. SubscribeToTask Subscribe to task updates via streaming. Returns `UnsupportedOperationError` if the task is in a terminal state. **Request:** {{ proto_to_table("SubscribeToTaskRequest") }} **Response:** Server streaming [`StreamResponse`](#stream-response) objects. #### 10.4.7. CreateTaskPushNotificationConfig Creates a push notification configuration for a task. **Request:** {{ proto_to_table("CreateTaskPushNotificationConfigRequest") }} **Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition. #### 10.4.8. GetTaskPushNotificationConfig Retrieves an existing push notification configuration for a task. **Request:** {{ proto_to_table("GetTaskPushNotificationConfigRequest") }} **Response:** See [`PushNotificationConfig`](#431-pushnotificationconfig) object definition. #### 10.4.9. ListTaskPushNotificationConfigs Lists all push notification configurations for a task. **Request:** {{ proto_to_table("ListTaskPushNotificationConfigsRequest") }} **Response:** {{ proto_to_table("ListTaskPushNotificationConfigsResponse") }} #### 10.4.10. DeleteTaskPushNotificationConfig Removes a push notification configuration for a task. **Request:** {{ proto_to_table("DeleteTaskPushNotificationConfigRequest") }} **Response:** `google.protobuf.Empty` #### 10.4.11. GetExtendedAgentCard Retrieves the agent's extended capability card after authentication. **Request:** {{ proto_to_table("GetExtendedAgentCardRequest") }} **Response:** See [`AgentCard`](#441-agentcard) object definition. ### 10.5. gRPC-Specific Data Types #### 10.5.1. TaskPushNotificationConfig Resource wrapper for push notification configurations. This is a gRPC-specific type used in resource-oriented operations to provide the full resource name along with the configuration data. {{ proto_to_table("TaskPushNotificationConfig") }} **Fields:** {{ proto_to_table("TaskPushNotificationConfig") }} ### 10.6. Error Handling gRPC error responses use the standard [gRPC status](https://grpc.io/docs/guides/error/) structure with [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto), which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows: - **Error Code**: Mapped to `status.code` (gRPC status code enum) - **Error Message**: Mapped to `status.message` (human-readable string) - **Error Details**: Mapped to `status.details` (repeated google.protobuf.Any messages) **A2A Error Representation:** For A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `status.details` array with: - `reason`: The A2A error type in UPPER_SNAKE_CASE without the "Error" suffix (e.g., `TASK_NOT_FOUND`) - `domain`: Set to `"a2a-protocol.org"` - `metadata`: Optional map of additional error context For the complete mapping of A2A error types to gRPC status codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings). **Error Response Example:** ```proto // Standard gRPC invalid argument error status { code: INVALID_ARGUMENT message: "Invalid request parameters" details: [ { type: "type.googleapis.com/google.rpc.BadRequest" field_violations: [ { field: "message.parts" description: "At least one part is required" } ] } ] } ``` **Example A2A-Specific Error Response:** ```proto // A2A-specific task not found error status { code: NOT_FOUND message: "Task with ID 'task-123' not found" details: [ { type: "type.googleapis.com/google.rpc.ErrorInfo" reason: "TASK_NOT_FOUND" domain: "a2a-protocol.org" metadata: { task_id: "task-123" timestamp: "2025-11-09T10:30:00Z" } } ] } ``` ### 10.7. Streaming gRPC streaming uses server streaming RPCs for real-time updates. The `StreamResponse` message provides a union of possible streaming events: {{ proto_to_table("StreamResponse") }} ## 11. HTTP+JSON/REST Protocol Binding The HTTP+JSON protocol binding provides a RESTful interface using standard HTTP methods and JSON payloads. ### 11.1. Protocol Requirements - **Protocol:** HTTP(S) with JSON payloads - **Content-Type:** `application/json` for requests and responses - **Methods:** Standard HTTP verbs (GET, POST, PUT, DELETE) - **URL Patterns:** RESTful resource-based URLs - **Streaming:** Server-Sent Events for real-time updates ### 11.2. Service Parameter Transmission A2A service parameters defined in [Section 3.2.6](#326-service-parameters) **MUST** be transmitted using standard HTTP request headers. **Service Parameter Requirements:** - Service parameter names **MUST** be transmitted as HTTP header fields - Service parameter keys are case-insensitive per HTTP specification (RFC 9110) - Multiple values for the same service parameter (e.g., `A2A-Extensions`) **SHOULD** be comma-separated in a single header field **Example Request with A2A Service Parameters:** ```http POST /message:send HTTP/1.1 Host: agent.example.com Content-Type: application/json Authorization: Bearer token A2A-Version: 0.3 A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 { "message": { "role": "ROLE_USER", "parts": [{"text": "Find restaurants near me"}] } } ``` ### 11.3. URL Patterns and HTTP Methods #### 11.3.1. Message Operations - `POST /message:send` - Send message - `POST /message:stream` - Send message with streaming (SSE response) #### 11.3.2. Task Operations - `GET /tasks/{id}` - Get task status - `GET /tasks` - List tasks (with query parameters) - `POST /tasks/{id}:cancel` - Cancel task - `POST /tasks/{id}:subscribe` - Subscribe to task updates (SSE response, returns error for terminal tasks) #### 11.3.3. Push Notification Configuration - `POST /tasks/{id}/pushNotificationConfigs` - Create configuration - `GET /tasks/{id}/pushNotificationConfigs/{configId}` - Get configuration - `GET /tasks/{id}/pushNotificationConfigs` - List configurations - `DELETE /tasks/{id}/pushNotificationConfigs/{configId}` - Delete configuration #### 11.3.4. Agent Card - `GET /extendedAgentCard` - Get authenticated extended Agent Card ### 11.4. Request/Response Format All requests and responses use JSON objects structurally equivalent to the Protocol Buffer definitions. **Example Send Message:** ```http POST /message:send Content-Type: application/json { "message": { "messageId": "uuid", "role": "ROLE_USER", "parts": [{"text": "Hello"}] }, "configuration": { "acceptedOutputModes": ["text/plain"] } } ``` **Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest), [`Message`](#414-message) **Response:** ```http HTTP/1.1 200 OK Content-Type: application/json { "task": { "id": "task-uuid", "contextId": "context-uuid", "status": { "state": "TASK_STATE_COMPLETED" } } } ``` **Referenced Objects:** [`Task`](#411-task) ### 11.5. Query Parameter Naming for Request Parameters HTTP methods that do not support request bodies (GET, DELETE) **MUST** transmit operation request parameters as path parameters or query parameters. This section defines how to map Protocol Buffer field names to query parameter names. **Naming Convention:** Query parameter names **MUST** use `camelCase` to match the JSON serialization of Protocol Buffer field names. This ensures consistency with request bodies used in POST operations. **Example Mappings:** | Protocol Buffer Field | Query Parameter Name | Example Usage | | --------------------- | -------------------- | ------------------- | | `context_id` | `contextId` | `?contextId=uuid` | | `page_size` | `pageSize` | `?pageSize=50` | | `page_token` | `pageToken` | `?pageToken=cursor` | | `task_id` | `taskId` | `?taskId=uuid` | **Usage Examples:** List tasks with filtering: ```http GET /tasks?contextId=uuid&status=working&pageSize=50&pageToken=cursor ``` Get task with history: ```http GET /tasks/{id}?historyLength=10 ``` **Field Type Handling:** - **Strings**: Passed directly as query parameter values - **Booleans**: Represented as lowercase strings (`true`, `false`) - **Numbers**: Represented as decimal strings - **Enums**: Represented using their string values (e.g., `status=working`) - **Repeated Fields**: Multiple values **MAY** be passed by repeating the parameter name (e.g., `?tag=value1&tag=value2`) or as comma-separated values (e.g., `?tag=value1,value2`) - **Nested Objects**: Not supported in query parameters; operations requiring nested objects **MUST** use POST with a request body - **Datetimes/Timestamps**: Represented as ISO 8601 strings (e.g., `2025-11-09T10:30:00Z`) **URL Encoding:** All query parameter values **MUST** be properly URL-encoded per [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html). ### 11.6. Error Handling HTTP error responses use the representation specified in [AIP-193](https://google.aip.dev/193#http11json-representation) which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows: - **Error Code**: Mapped to the HTTP status code and the `error.code` field - **Error Message**: Mapped to the `error.message` field (human-readable string) - **Error Details**: Mapped to the `error.details` array (containing `google.protobuf.Any` messages) **A2A Error Representation:** For A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `details` array with: - `@type`: Set to `"type.googleapis.com/google.rpc.ErrorInfo"` - `reason`: The A2A error type in UPPER_SNAKE_CASE without the "Error" suffix (e.g., `TASK_NOT_FOUND`) - `domain`: Set to `"a2a-protocol.org"` - `metadata`: Optional map of additional error context For the complete mapping of A2A error types to HTTP status codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings). Additional error context **MAY** be included in the `details` array of the Status object. **Error Response Example:** ```http HTTP/1.1 404 Not Found Content-Type: application/json { "error": { "code": 404, "status": "NOT_FOUND", "message": "The specified task ID does not exist or is not accessible", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "TASK_NOT_FOUND", "domain": "a2a-protocol.org", "metadata": { "taskId": "task-123", "timestamp": "2025-11-09T10:30:00.000Z" } } ] } } ``` Extension fields like `taskId` and `timestamp` provide additional context to help diagnose the error. ### 11.7. Streaming REST streaming uses Server-Sent Events with the `data` field containing JSON serializations of the protocol data objects: ```http POST /message:stream Content-Type: application/json { /* SendMessageRequest object */ } ``` **Referenced Objects:** [`SendMessageRequest`](#321-sendmessagerequest) **Response:** ```http HTTP/1.1 200 OK Content-Type: text/event-stream data: { /* StreamResponse object */ } data: { /* StreamResponse object */ } ``` **Referenced Objects:** [`StreamResponse`](#323-stream-response) Streaming responses are simple, linearly ordered sequences: first a `Task` (or single `Message`), then zero or more status or artifact update events until the task reaches a terminal or interrupted state, at which point the stream closes. Implementations SHOULD avoid re-ordering events and MAY optionally resend a final `Task` snapshot before closing. ## 12. Custom Binding Guidelines While the A2A protocol provides three standard bindings (JSON-RPC, gRPC, and HTTP+JSON/REST), implementers **MAY** create custom protocol bindings to support additional transport mechanisms or communication patterns. Custom bindings **MUST** comply with all requirements defined in [Section 5 (Protocol Binding Requirements and Interoperability)](#5-protocol-binding-requirements-and-interoperability). This section provides additional guidelines specific to developing custom bindings. ### 12.1. Binding Requirements Custom protocol bindings **MUST**: 1. **Implement All Core Operations**: Support all operations defined in [Section 3 (A2A Protocol Operations)](#3-a2a-protocol-operations) 2. **Preserve Data Model**: Use data structures functionally equivalent to those defined in [Section 4 (Protocol Data Model)](#4-protocol-data-model) 3. **Maintain Semantics**: Ensure operations behave consistently with the abstract operation definitions 4. **Document Completely**: Provide comprehensive documentation of the binding specification ### 12.2. Data Type Mappings Custom bindings **MUST** provide clear mappings for: - **Protocol Buffer Types**: Define how each Protocol Buffer message type is represented - **Timestamps**: Follow the conventions in [Section 5.6.1 (Timestamps)](#561-timestamps) - **Binary Data**: Specify encoding for binary content (e.g., base64 for text-based protocols) - **Enumerations**: Define representation of enum values (e.g., strings, integers) ### 12.3. Service Parameter Transmission As specified in [Section 3.2.6 (Service Parameters)](#326-service-parameters), custom protocol bindings **MUST** document how service parameters are transmitted. The binding specification **MUST** address: 1. **Transmission Mechanism**: The protocol-specific method for transmitting service parameter key-value pairs 2. **Value Constraints**: Any limitations on service parameter values (e.g., character encoding, size limits) 3. **Reserved Names**: Any service parameter names reserved by the binding itself 4. **Fallback Strategy**: What happens when the protocol lacks native header support (e.g., passing service parameters in metadata) **Example Documentation Requirements:** - **For native header support**: "Service parameters are transmitted using HTTP request headers. Service parameter keys are case-insensitive and must conform to RFC 7230. Service parameter values must be UTF-8 strings." - **For protocols without headers**: "Service parameters are serialized as a JSON object and transmitted in the request metadata field `a2a-service-parameters`." ### 12.4. Error Mapping Custom bindings **MUST**: 1. **Map Standard Errors**: Provide mappings for all A2A-specific error types defined in [Section 3.2.2 (Error Handling)](#332-error-handling) 2. **Preserve Error Information**: Ensure error details are accessible to clients 3. **Use Appropriate Codes**: Map to protocol-native error codes where applicable 4. **Document Error Format**: Specify the structure of error responses ### 12.5. Streaming Support If the binding supports streaming operations: 1. **Define Stream Mechanism**: Document how streaming is implemented (e.g., WebSockets, long-polling, chunked encoding) 2. **Event Ordering**: Specify ordering guarantees for streaming events 3. **Reconnection**: Define behavior for connection interruption and resumption 4. **Stream Termination**: Specify how stream completion is signaled If streaming is not supported, the binding **MUST** clearly document this limitation in the Agent Card. ### 12.6. Authentication and Authorization Custom bindings **MUST**: 1. **Support Standard Schemes**: Implement authentication schemes declared in the Agent Card 2. **Document Integration**: Specify how credentials are transmitted in the protocol 3. **Handle Challenges**: Define how authentication challenges are communicated 4. **Maintain Security**: Follow security best practices for the transport protocol ### 12.7. Agent Card Declaration Custom bindings **MUST** be declared in the Agent Card: 1. **Transport Identifier**: Use a clear, descriptive transport name 2. **Endpoint URL**: Provide the full URL where the binding is available 3. **Documentation Link**: Include a URL to the complete binding specification **Example:** ```json { "supportedInterfaces": [ { "url": "wss://agent.example.com/a2a/websocket", "protocolBinding": "WEBSOCKET" } ] } ``` ### 12.8. Interoperability Testing Custom binding implementers **SHOULD**: 1. **Test Against Reference**: Verify behavior matches standard bindings 2. **Document Differences**: Clearly note any deviations from standard binding behavior 3. **Provide Examples**: Include sample requests and responses 4. **Test Edge Cases**: Verify handling of error conditions, large payloads, and long-running tasks ## 13. Security Considerations This section consolidates security guidance and best practices for implementing and operating A2A agents. For additional enterprise security considerations, see [Enterprise-Ready Features](./topics/enterprise-ready.md). ### 13.1. Data Access and Authorization Scoping Implementations **MUST** ensure appropriate scope limitation based on the authenticated caller's authorization boundaries. This applies to all operations that access or list tasks and other resources. **Authorization Principles:** - Servers **MUST** implement authorization checks on every [A2A Protocol Operations](#3-a2a-protocol-operations) request - Implementations **MUST** scope results to the caller's authorized access boundaries as defined by the agent's authorization model - Even when `contextId` or other filter parameters are not specified in requests, implementations **MUST** scope results to the caller's authorized access boundaries - Authorization models are agent-defined and **MAY** be based on: - User identity (user-based authorization) - Organizational roles or groups (role-based authorization) - Project or workspace membership (project-based authorization) - Organizational or tenant boundaries (multi-tenant authorization) - Custom authorization logic specific to the agent's domain **Operations Requiring Scope Limitation:** - [`List Tasks`](#314-list-tasks): **MUST** only return tasks visible to the authenticated client according to the agent's authorization model - [`Get Task`](#313-get-task): **MUST** verify the authenticated client has access to the requested task according to the agent's authorization model - Task-related operations (Cancel, Subscribe, Push Notification Config): **MUST** verify the client has appropriate access rights according to the agent's authorization model **Implementation Requirements:** - Authorization boundaries are defined by each agent's authorization model, not prescribed by the protocol - Authorization checks **MUST** occur before any database queries or operations that could leak information about the existence of resources outside the caller's authorization scope - Agents **SHOULD** document their authorization model and access control policies See also: [Section 3.1.4 List Tasks (Security Note)](#314-list-tasks) for operation-specific requirements. ### 13.2. Push Notification Security When implementing push notifications, both agents (as webhook callers) and clients (as webhook receivers) have security responsibilities. **Agent (Webhook Caller) Requirements:** - Agents **MUST** include authentication credentials in webhook requests as specified in [`PushNotificationConfig.authentication`](#432-authenticationinfo) - Agents **SHOULD** implement reasonable timeout values for webhook requests (recommended: 10-30 seconds) - Agents **SHOULD** implement retry logic with exponential backoff for failed deliveries - Agents **MAY** stop attempting delivery after a configured number of consecutive failures - Agents **SHOULD** validate webhook URLs to prevent SSRF (Server-Side Request Forgery) attacks: - Reject private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) - Reject localhost and link-local addresses - Implement URL allowlists where appropriate **Client (Webhook Receiver) Requirements:** - Clients **MUST** validate webhook authenticity using the provided authentication credentials - Clients **SHOULD** verify the task ID in the payload matches an expected task they created - Clients **MUST** respond with HTTP 2xx status codes to acknowledge successful receipt - Clients **SHOULD** process notifications idempotently, as duplicate deliveries may occur - Clients **SHOULD** implement rate limiting to prevent webhook flooding - Clients **SHOULD** use HTTPS endpoints for webhook URLs to ensure confidentiality **Configuration Security:** - Webhook URLs **SHOULD** use HTTPS to protect payload confidentiality in transit - Authentication tokens in [`PushNotificationConfig`](#431-pushnotificationconfig) **SHOULD** be treated as secrets and rotated periodically - Agents **SHOULD** securely store push notification configurations and credentials - Clients **SHOULD** use unique, single-purpose tokens for each push notification configuration See also: [Section 4.3 Push Notification Objects](#43-push-notification-objects) and [Section 4.3.3 Push Notification Payload](#433-push-notification-payload). ### 13.3. Extended Agent Card Access Control The extended Agent Card feature allows agents to provide additional capabilities or information to authenticated clients beyond what is available in the public Agent Card. **Access Control Requirements:** - The [`Get Extended Agent Card`](#3111-get-extended-agent-card) operation **MUST** require authentication - Agents **MUST** authenticate requests using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields - Agents **MAY** return different extended card content based on the authenticated client's identity or authorization level - Agents **SHOULD** implement appropriate caching headers to control client-side caching of extended cards **Capability-Based Access:** - Extended cards **MAY** include additional skills not present in the public card - Extended cards **MAY** expose more detailed capability information (e.g., rate limits, quotas) - Extended cards **MAY** include organization-specific or user-specific configuration - Agents **SHOULD** document which capabilities are available at different authentication levels **Security Considerations:** - Extended cards **SHOULD NOT** include sensitive information that could be exploited if leaked (e.g., internal service URLs, unmasked credentials) - Agents **MUST** validate that clients have appropriate permissions before returning privileged information in extended cards - Clients retrieving extended cards **SHOULD** replace their cached public Agent Card with the extended version for the duration of their authenticated session - Agents **SHOULD** version extended cards appropriately and honor client cache invalidation **Availability Declaration:** - Agents declare extended card support via `AgentCard.capabilities.extendedAgentCard` - When `capabilities.extendedAgentCard` is `false` or not present, the operation **MUST** return [`UnsupportedOperationError`](#332-error-handling) - When support is declared but no extended card is configured, the operation **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling) See also: [Section 3.1.11 Get Extended Agent Card](#3111-get-extended-agent-card) and [Section 3.3.4 Capability Validation](#334-capability-validation). ### 13.4. General Security Best Practices **Transport Security:** - Production deployments **MUST** use encrypted communication (HTTPS for HTTP-based bindings, TLS for gRPC) - Implementations **SHOULD** use modern TLS configurations (TLS 1.3+ recommended) with strong cipher suites - Agents **SHOULD** enforce HSTS (HTTP Strict Transport Security) headers when using HTTP-based bindings - Implementations **SHOULD** disable support for deprecated SSL/TLS versions (SSLv3, TLS 1.0, TLS 1.1) **Input Validation:** - Agents **MUST** validate all input parameters before processing - Agents **SHOULD** implement appropriate limits on message sizes, file sizes, and request complexity - Agents **SHOULD** sanitize or validate file content types and reject unexpected media types **Credential Management:** - API keys, tokens, and other credentials **MUST** be treated as secrets - Credentials **SHOULD** be rotated periodically - Credentials **SHOULD** be transmitted only over encrypted connections - Agents **SHOULD** implement credential revocation mechanisms - Agents **SHOULD** log authentication failures and implement rate limiting to prevent brute-force attacks **Audit and Monitoring:** - Agents **SHOULD** log security-relevant events (authentication failures, authorization denials, suspicious requests) - Agents **SHOULD** implement monitoring for unusual patterns (rapid task creation, excessive cancellations) - Agents **SHOULD** provide audit trails for sensitive operations - Logs **MUST NOT** include sensitive information (credentials, personal data) unless required and properly protected **Rate Limiting and Abuse Prevention:** - Agents **SHOULD** implement rate limiting on all operations - Agents **SHOULD** return appropriate error responses when rate limits are exceeded - Agents **MAY** implement different rate limits for different operations or user tiers **Data Privacy:** - Agents **MUST** comply with applicable data protection regulations - Agents **SHOULD** provide mechanisms for users to request deletion of their data - Agents **SHOULD** implement appropriate data retention policies - Agents **SHOULD** minimize logging of sensitive or personal information **Custom Binding Security:** - Custom protocol bindings **MUST** address security considerations in their specification - Custom bindings **SHOULD** follow the same security principles as standard bindings - Custom bindings **MUST** document authentication integration and credential transmission See also: [Section 12.6 Authentication and Authorization (Custom Bindings)](#126-authentication-and-authorization). ## 14. IANA Considerations This section provides registration templates for the A2A protocol's media type, HTTP headers, and well-known URI, intended for submission to the Internet Assigned Numbers Authority (IANA). ### 14.1. Media Type Registration #### 14.1.1. application/a2a+json **Type name:** `application` **Subtype name:** `a2a+json` **Required parameters:** None **Optional parameters:** - None **Encoding considerations:** Binary (UTF-8 encoding MUST be used for JSON text) **Security considerations:** This media type shares security considerations common to all JSON-based formats as described in RFC 8259, Section 12. Additionally: - Content MUST be validated against the A2A protocol schema before processing - Implementations MUST sanitize user-provided content to prevent injection attacks - File references within A2A messages MUST be validated to prevent server-side request forgery (SSRF) - Authentication and authorization MUST be enforced as specified in Section 7 of the A2A specification - Sensitive information in task history and artifacts MUST be protected according to applicable data protection regulations **Interoperability considerations:** The A2A protocol supports multiple protocol bindings. This media type is intended for the HTTP+JSON/REST binding. **Published specification:** Agent2Agent (A2A) Protocol Specification, available at: **Applications that use this media type:** AI agent platforms, agentic workflow systems, multi-agent collaboration tools, and enterprise automation systems that implement the A2A protocol for agent-to-agent communication. **Fragment identifier considerations:** None **Additional information:** - **Deprecated alias names for this type:** None - **Magic number(s):** None - **File extension(s):** .a2a.json - **Macintosh file type code(s):** TEXT **Person & email address to contact for further information:** A2A Protocol Working Group, **Intended usage:** COMMON **Restrictions on usage:** None **Author:** A2A Protocol Working Group **Change controller:** A2A Protocol Working Group **Provisional registration:** No ### 14.2. HTTP Header Field Registrations **Note:** The following HTTP headers represent the HTTP-based protocol binding implementation of the abstract A2A service parameters defined in [Section 3.2.6](#326-service-parameters). These registrations are specific to HTTP/HTTPS transports. #### 14.2.1. A2A-Version Header **Header field name:** A2A-Version **Applicable protocol:** HTTP **Status:** Standard **Author/Change controller:** A2A Protocol Working Group **Specification document:** Section 3.2.5 of the A2A Protocol Specification **Related information:** The A2A-Version header field indicates the A2A protocol version that the client is using. The value MUST be in the format `Major.Minor` (e.g., "0.3"). If the version is not supported by the agent, the agent returns a `VersionNotSupportedError`. **Example:** ```text A2A-Version: 0.3 ``` #### 14.2.2. A2A-Extensions Header **Header field name:** A2A-Extensions **Applicable protocol:** HTTP **Status:** Standard **Author/Change controller:** A2A Protocol Working Group **Specification document:** Section 3.2.5 of the A2A Protocol Specification **Related information:** The A2A-Extensions header field contains a comma-separated list of extension URIs that the client wants to use for the request. Extensions allow agents to provide additional functionality beyond the core A2A specification while maintaining backward compatibility. **Example:** ```text A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1 ``` ### 14.3. Well-Known URI Registration **URI suffix:** agent-card.json **Change controller:** A2A Protocol Working Group **Specification document:** Section 8.2 of the A2A Protocol Specification **Related information:** The `.well-known/agent-card.json` URI provides a standardized location for discovering an A2A agent's capabilities, supported protocols, authentication requirements, and available skills. The resource at this URI MUST return an AgentCard object as defined in Section 4.4.1 of the A2A specification. **Status:** Permanent **Security considerations:** - The Agent Card MAY contain public information about an agent's capabilities and SHOULD NOT include sensitive credentials or internal implementation details - Implementations SHOULD support HTTPS to ensure authenticity and integrity of the Agent Card - Agent Cards MAY be signed using JSON Web Signatures (JWS) as specified in the AgentCardSignature object (Section 4.4.7) - Clients SHOULD verify signatures when present to ensure the Agent Card has not been tampered with - Extended Agent Cards retrieved via authenticated endpoints (Section 3.1.11) MAY contain additional information and MUST enforce appropriate access controls **Example:** ```text https://agent.example.com/.well-known/agent-card.json ``` --- ## Appendix A. Migration & Legacy Compatibility This appendix catalogs renamed protocol messages and objects, their legacy identifiers, and the planned deprecation/removal schedule. All legacy names and anchors MUST remain resolvable until the stated earliest removal version. | Legacy Name | Current Name | Earliest Removal Version | Notes | | ----------------------------------------------- | ----------------------------------------- | ------------------------ | ------------------------------------------------------ | | `MessageSendParams` | `SendMessageRequest` | >= 0.5.0 | Request payload rename for clarity (request vs params) | | `SendMessageSuccessResponse` | `SendMessageResponse` | >= 0.5.0 | Unified success response naming | | `SendStreamingMessageSuccessResponse` | `StreamResponse` | >= 0.5.0 | Shorter, binding-agnostic streaming response | | `SetTaskPushNotificationConfigRequest` | `CreateTaskPushNotificationConfigRequest` | >= 0.5.0 | Explicit creation intent | | `ListTaskPushNotificationConfigSuccessResponse` | `ListTaskPushNotificationConfigsResponse` | >= 0.5.0 | Consistent response suffix removal | | `GetAuthenticatedExtendedCardRequest` | `GetExtendedAgentCardRequest` | >= 0.5.0 | Removed "Authenticated" from naming | Planned Lifecycle (example timeline; adjust per release strategy): 1. 0.3.x: New names introduced; legacy names documented; aliases added. 2. 0.4.x: Legacy names marked "deprecated" in SDKs and schemas; warning notes added. 3. ≥0.5.0: Legacy names eligible for removal after review; migration appendix updated. ### A.1 Legacy Documentation Anchors Hidden anchor spans preserve old inbound links: Each legacy span SHOULD be placed adjacent to the current object's heading (to be inserted during detailed object section edits). If an exact numeric-prefixed anchor existed (e.g., `#414-message`), add an additional span matching that historical form if known. ### A.2 Migration Guidance Client Implementations SHOULD: - Prefer new names immediately for all new integrations. - Implement dual-handling where schemas/types permit (e.g., union type or backward-compatible decoder). - Log a warning when receiving legacy-named objects after the first deprecation announcement release. Server Implementations MAY: - Accept both legacy and current request message forms during the overlap period. - Emit only current form in responses (recommended) while providing explicit upgrade notes. #### A.2.1 Breaking Change: Kind Discriminator Removed **Version 1.0 introduces a breaking change** in how polymorphic objects are represented in the protocol. This affects `Part` types and streaming event types. **Legacy Pattern (v0.3.x):** Objects used an inline `kind` field as a discriminator to identify the object type: **Example 1 - TextPart:** ```json { "kind": "text", "text": "Hello, world!" } ``` **Example 2 - FilePart:** ```json { "kind": "file", "file": { "name": "diagram.png", "mimeType": "image/png", "fileWithBytes": "iVBORw0KGgo..." } } ``` **Current Pattern (v1.0):** Objects now use the **JSON member name** itself to identify the type. The member name acts as the discriminator, and the value structure depends on the specific type: **Example 1 - TextPart:** ```json { "text": "Hello, world!" } ``` **Example 2 - FilePart:** ```json { "raw": "iVBORw0KGgo...", "filename": "diagram.png", "mediaType": "image/png" } ``` **Affected Types:** 1. **Part Union Types**: - **TextPart**: - **Legacy:** `{ "kind": "text", "text": "..." }` - **Current:** `{ "text": "..." }` (member presence acts as discriminator) - **FilePart**: - **Legacy:** `{ "kind": "file", "file": { "name": "...", "mimeType": "...", "fileWithBytes": "..." } }` - **Current:** `{ "raw": "...", "filename": "...", "mediaType": "..." }` (or `url` instead of `raw`) - **DataPart**: - **Legacy:** `{ "kind": "data", "data": {...} }` - **Current:** `{ "data": {...}, "mediaType": "application/json" }` 2. **Streaming Event Types**: - **TaskStatusUpdateEvent**: - **Legacy:** `{ "kind": "status-update", "taskId": "...", "status": {...} }` - **Current:** `{ "statusUpdate": { "taskId": "...", "status": {...} } }` - **TaskArtifactUpdateEvent**: - **Legacy:** `{ "kind": "artifact-update", "taskId": "...", "artifact": {...} }` - **Current:** `{ "artifactUpdate": { "taskId": "...", "artifact": {...} } }` **Migration Strategy:** For **Clients** upgrading from pre-0.3.x: 1. Update parsers to expect wrapper objects with member names as discriminators 2. When constructing requests, use the new wrapper format 3. Implement version detection based on the agent's `protocolVersions` in the `AgentCard` 4. Consider maintaining backward compatibility by detecting and handling both formats during a transition period For **Servers** upgrading from pre-0.3.x: 1. Update serialization logic to emit wrapper objects 2. **Breaking:** The `kind` field is no longer part of the protocol and should not be emitted 3. Update deserialization to expect wrapper objects with member names 4. Ensure the `AgentCard` declares the correct `protocolVersions` (e.g., ["1.0"] or later) **Rationale:** This change aligns with modern API design practices and Protocol Buffers' `oneof` semantics, where the field name itself serves as the type discriminator. This approach: - Reduces redundancy (no need for both a field name and a `kind` value) - Aligns JSON-RPC and gRPC representations more closely - Simplifies code generation from schema definitions - Eliminates the need for representing inheritance structures in schema languages - Improves type safety in strongly-typed languages #### A.2.2 Breaking Change: Extended Agent Card Field Relocated **Version 1.0 relocates the extended agent card capability** from a top-level field to the capabilities object for architectural consistency. **Legacy Structure (pre-1.0):** ```json { "supportsExtendedAgentCard": true, "capabilities": { "streaming": true } } ``` **Current Structure (1.0+):** ```json { "capabilities": { "streaming": true, "extendedAgentCard": true } } ``` **Proto Changes:** - Removed: `AgentCard.supports_extended_agent_card` (field 13) - Added: `AgentCapabilities.extended_agent_card` (field 5) **Migration Steps:** For **Agent Implementations**: 1. Remove `supportsExtendedAgentCard` from top-level AgentCard 2. Add `extendedAgentCard` to `capabilities` object 3. Update validation: `agentCard.capabilities?.extendedAgentCard` For **Client Implementations**: 1. Update capability checks: `agentCard.capabilities?.extendedAgentCard` 2. Temporary fallback (transition period): ```javascript const supported = agentCard.capabilities?.extendedAgentCard || agentCard.supportsExtendedAgentCard; ``` 3. Remove fallback after agent ecosystem migrates For **SDK Developers**: 1. Regenerate code from updated proto 2. Update type definitions 3. Document breaking change in release notes **Rationale:** All optional features enabling specific operations (`streaming`, `pushNotifications`, `stateTransitionHistory`) reside in `AgentCapabilities`. Moving `extendedAgentCard` achieves: - Architectural consistency - Improved discoverability - Semantic correctness (it is a capability) ### A.3 Future Automation Once the proto→schema generation pipeline lands, this appendix will be partially auto-generated (legacy mapping table sourced from a maintained manifest). Until then, edits MUST be manual and reviewed in PRs affecting `a2a.proto`. ## Appendix B. Relationship to MCP (Model Context Protocol) A2A and MCP are complementary protocols designed for different aspects of agentic systems: - **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/):** Focuses on standardizing how AI models and agents connect to and interact with **tools, APIs, data sources, and other external resources.** It defines structured ways to describe tool capabilities (like function calling in LLMs), pass inputs, and receive structured outputs. Think of MCP as the "how-to" for an agent to *use* a specific capability or access a resource. - **Agent2Agent Protocol (A2A):** Focuses on standardizing how independent, often opaque, **AI agents communicate and collaborate with each other as peers.** A2A provides an application-level protocol for agents to discover each other, negotiate interaction modalities, manage shared tasks, and exchange conversational context or complex results. It's about how agents *partner* or *delegate* work. **How they work together:** An A2A Client agent might request an A2A Server agent to perform a complex task. The Server agent, in turn, might use MCP to interact with several underlying tools, APIs, or data sources to gather information or perform actions necessary to fulfill the A2A task. For a more detailed comparison, see the [A2A and MCP guide](./topics/a2a-and-mcp.md). --- ================================================ FILE: docs/stylesheets/custom.css ================================================ /** * Copyright 2025 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* Index page styling */ .md-grid { max-width: 80%; } .footer { padding-bottom: 30vh; } .centered-logo-text-group { display: inline-flex; align-items: center; gap: 1.5em; margin-bottom: 0.5em; vertical-align: middle; } .centered-logo-text-group img { height: auto; } .centered-logo-text-group h1 { margin: 0; text-align: left; } .install-command-container { max-width: 600px; margin: 2.5em auto; padding: 1.5em 2em; background-color: var(--md-code-bg-color, #f5f5f5); border-radius: 8px; text-align: center; box-shadow: 0 3px 6px rgb(0 0 0 / 5%); border-left: 5px solid var(--md-primary-fg-color, #526cfe); margin-top: 30px; } .install-command-container p { font-size: 1.1em; color: var(--md-default-fg-color); margin-bottom: -10px; margin-top: -10px; } .install-command-container p code { font-size: 1.1em; font-weight: 600; padding: 0.3em 0.6em; background-color: var(--md-code-fg-color--light); border-radius: 4px; display: inline-block; line-height: 1.4; } .announce .md-button { font-size: 0.8em; padding: 0.3em 1em; margin-left: 0.5em; } h1#agent2agent-a2a-protocol { display: none; } figure.hero { margin-top: 0; margin-bottom: 10px; } figure.hero figcaption { max-width: 100%; width: 100%; margin-bottom: 0; text-align: left; } iframe.video-container { width: 100%; aspect-ratio: 16 / 9; height: auto; border-radius: 4px; } ================================================ FILE: docs/topics/a2a-and-mcp.md ================================================ # A2A and MCP: Detailed Comparison In AI agent development, two key protocol types emerge to facilitate interoperability. One connects agents to tools and resources. The other enables agent-to-agent collaboration. The Agent2Agent (A2A) Protocol and the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) address these distinct but highly complementary needs. ## Model Context Protocol The Model Context Protocol (MCP) defines how an AI agent interacts with and utilizes individual tools and resources, such as a database or an API. This protocol offers the following capabilities: - Standardizes how AI models and agents connect to and interact with tools, APIs, and other external resources. - Defines a structured way to describe tool capabilities, similar to function calling in Large Language Models. - Passes inputs to tools and receives structured outputs. - Supports common use cases, such as an LLM calling an external API, an agent querying a database, or an agent connecting to predefined functions. ## Agent2Agent Protocol The Agent2Agent Protocol focuses on enabling different agents to collaborate with one another to achieve a common goal. This protocol offers the following capabilities: - Standardizes how independent, often opaque, AI agents communicate and collaborate as peers. - Provides an application-level protocol for agents to discover each other, negotiate interactions, manage shared tasks, and exchange conversational context and complex data. - Supports typical use cases, including a customer service agent delegating an inquiry to a billing agent, or a travel agent coordinating with flight, hotel, and activity agents. ## Why Different Protocols? Both the MCP and A2A protocols are essential for building complex AI systems, and they address distinct but highly complementary needs. The distinction between A2A and MCP depends on what an agent interacts with. - **Tools and Resources (MCP Domain)**: - **Characteristics:** These are typically primitives with well-defined, structured inputs and outputs. They perform specific, often stateless, functions. Examples include a calculator, a database query API, or a weather lookup service. - **Purpose:** Agents use tools to gather information and perform discrete functions. - **Agents (A2A domain)**: - **Characteristics:** These are more autonomous systems. They reason, plan, use multiple tools, maintain state over longer interactions, and engage in complex, often multi-turn dialogues to achieve novel or evolving tasks. - **Purpose:** Agents collaborate with other agents to tackle broader, more complex goals. ## A2A ❤️ MCP: Complementary Protocols for Agentic Systems An agentic application might primarily use A2A to communicate with other agents. Each individual agent internally uses MCP to interact with its specific tools and resources.
![Diagram showing A2A and MCP working together. A User interacts with Agent A using A2A. Agent A interacts with Agent B using A2A. Agent B uses MCP to interact with Tool 1 and Tool 2.](../assets/a2a-mcp.png){width="80%"} _An agentic application might use A2A to communicate with other agents, while each agent internally uses MCP to interact with its specific tools and resources._
### Example Scenario: The Auto Repair Shop Consider an auto repair shop staffed by autonomous AI agent "mechanics". These mechanics use special-purpose tools, such as vehicle diagnostic scanners, repair manuals, and platform lifts, to diagnose and repair problems. The repair process can involve extensive conversations, research, and interaction with part suppliers. - **Customer Interaction (User-to-Agent using A2A)**: A customer (or their primary assistant agent) uses A2A to communicate with the "Shop Manager" agent. For example, the customer might say, "My car is making a rattling noise". - **Multi-turn Diagnostic Conversation (Agent-to-Agent using A2A)**: The Shop Manager agent uses A2A for a multi-turn diagnostic conversation. For example, the Manager might ask, "Can you send a video of the noise?" or "I see some fluid leaking. How long has this been happening?". - **Internal Tool Usage (Agent-to-Tool using MCP)**: The Mechanic agent, assigned the task by the Shop Manager, needs to diagnose the issue. The Mechanic agent uses MCP to interact with its specialized tools. For example: - MCP call to a "Vehicle Diagnostic Scanner" tool: `scan_vehicle_for_error_codes(vehicle_id='XYZ123')` - MCP call to a "Repair Manual Database" tool: `get_repair_procedure(error_code='P0300', vehicle_make='Toyota', vehicle_model='Camry')` - MCP call to a "Platform Lift" tool: `raise_platform(height_meters=2)` - **Supplier Interaction (Agent-to-Agent using A2A)**: The Mechanic agent determines that a specific part is needed. The Mechanic agent uses A2A to communicate with a "Parts Supplier" agent to order a part. For example, the Mechanic agent might ask, "Do you have part #12345 in stock for a Toyota Camry 2018?" - **Order processing (Agent-to-Agent using A2A)**: The Parts Supplier agent, which is also an A2A-compliant system, responds, potentially leading to an order. In this example: - A2A facilitates the higher-level, conversational, and task-oriented interactions between the customer and the shop, and between the shop's agents and external supplier agents. - MCP enables the mechanic agent to use its specific, structured tools to perform its diagnostic and repair functions. An A2A server could expose some of its skills as MCP-compatible resources. However, A2A's primary strength lies in its support for more flexible, stateful, and collaborative interactions. These interactions go beyond a typical tool invocation. A2A focuses on agents partnering on tasks, whereas MCP focuses on agents using capabilities. ## Representing A2A Agents as MCP Resources An A2A Server (a remote agent) could expose some of its skills as MCP-compatible resources, especially if those skills are well-defined and can be invoked in a more tool-like, stateless manner. In such a case, another agent might "discover" this A2A agent's specific skill through an MCP-style tool description (perhaps derived from its Agent Card). However, the primary strength of A2A lies in its support for more flexible, stateful, and collaborative interactions that go beyond typical tool invocation. A2A is about agents _partnering_ on tasks, while MCP is more about agents _using_ capabilities. By leveraging both A2A for inter-agent collaboration and MCP for tool integration, developers can build more powerful, flexible, and interoperable AI systems. ================================================ FILE: docs/topics/agent-discovery.md ================================================ # Agent Discovery in A2A To collaborate using the Agent2Agent (A2A) protocol, AI agents need to first find each other and understand their capabilities. A2A standardizes agent self-descriptions through the **[Agent Card](../specification.md#5-agent-discovery-the-agent-card)**. However, discovery methods for these Agent Cards vary by environment and requirements. The Agent Card defines what an agent offers. Various strategies exist for a client agent to discover these cards. The choice of strategy depends on the deployment environment and security requirements. ## The Role of the Agent Card The Agent Card is a JSON document that serves as a digital "business card" for an A2A Server (the remote agent). It is crucial for agent discovery and interaction. The key information included in an Agent Card is as follows: - **Identity:** Includes `name`, `description`, and `provider` information. - **Service Endpoint:** Specifies the `url` for the A2A service. - **A2A Capabilities:** Lists supported features such as `streaming` or `pushNotifications`. - **Authentication:** Details the required `schemes` (e.g., "Bearer", "OAuth2"). - **Skills:** Describes the agent's tasks using `AgentSkill` objects, including `id`, `name`, `description`, `inputModes`, `outputModes`, and `examples`. Client agents use the Agent Card to determine an agent's suitability, structure requests, and ensure secure communication. ## Discovery Strategies The following sections detail common strategies used by client agents to discover remote Agent Cards: ### 1. Well-Known URI This approach is recommended for public agents or agents intended for broad discovery within a specific domain. - **Mechanism:** A2A Servers make their Agent Card discoverable by hosting it at a standardized, `well-known` URI on their domain. The standard path is `https://{agent-server-domain}/.well-known/agent-card.json`, following the principles of [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615). - **Process:** 1. A client agent knows or programmatically discovers the domain of a potential A2A Server (e.g., `smart-thermostat.example.com`). 2. The client performs an HTTP GET request to `https://smart-thermostat.example.com/.well-known/agent-card.json`. 3. If the Agent Card exists and is accessible, the server returns it as a JSON response. - **Advantages:** - Ease of implementation - Adheres to standards - Facilitates automated discovery - **Considerations:** - Best suited for open or domain-controlled discovery scenarios. - Authentication is necessary at the endpoint serving the Agent Card if it contains sensitive details. ### 2. Curated Registries (Catalog-Based Discovery) This approach is employed in enterprise environments or public marketplaces, where Agent Cards are often managed by a central registry. The curated registry acts as a central repository, allowing clients to query and discover agents based on criteria like "skills" or "tags". - **Mechanism:** An intermediary service (the registry) maintains a collection of Agent Cards. Clients query this registry to find agents based on various criteria (e.g., skills offered, tags, provider name, capabilities). - **Process:** 1. A2A Servers publish their Agent Cards to the registry. 2. Client agents query the registry's API, and search by criteria such as "specific skills". 3. The registry returns matching Agent Cards or references. - **Advantages:** - Centralized management and governance. - Capability-based discovery (e.g., by skill). - Support for access controls and trust frameworks. - Applicable in both private and public marketplaces. - **Considerations:** - Requires deployment and maintenance of a registry service. - The current A2A specification does not prescribe a standard API for curated registries. ### 3. Direct Configuration / Private Discovery This approach is used for tightly coupled systems, private agents, or development purposes, where clients are directly configured with Agent Card information or URLs. - **Mechanism:** Client applications utilize hardcoded details, configuration files, environment variables, or proprietary APIs for discovery. - **Process:** The process is specific to the application's deployment and configuration strategy. - **Advantages:** This method is straightforward for establishing connections within known, static relationships. - **Considerations:** - Inflexible for dynamic discovery scenarios. - Changes to Agent Card information necessitate client reconfiguration. - Proprietary API-based discovery also lacks standardization. ## Securing Agent Cards Agent Cards include sensitive information, such as: - URLs for internal or restricted agents. - Descriptions of sensitive skills. ### Protection Mechanisms To mitigate risks, the following protection mechanisms should be considered: - **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) - HTTP Authentication (e.g., OAuth 2.0) - **Registry Selective Disclosure:** Registries return different Agent Cards based on the client's identity and permissions. 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. ================================================ FILE: docs/topics/enterprise-ready.md ================================================ # Enterprise Implementation of A2A The Agent2Agent (A2A) protocol is designed with enterprise requirements at its core. Rather than inventing new, proprietary standards for security and operations, A2A aims to integrate seamlessly with existing enterprise infrastructure and widely adopted best practices. This approach allows organizations to use their existing investments and expertise in security, monitoring, governance, and identity management. A key principle of A2A is that agents are typically **opaque** because they don't share internal memory, tools, or direct resource access with each other. This opacity naturally aligns with standard client-server security paradigms, treating remote agents as standard HTTP-based enterprise applications. ## Transport Level Security (TLS) Ensuring the confidentiality and integrity of data in transit is fundamental for any enterprise application. - **HTTPS Mandate**: All A2A communication in production environments must occur over `HTTPS`. - **Modern TLS Standards**: Implementations should use modern TLS versions. TLS 1.2 or higher is recommended. Strong, industry-standard cipher suites should be used to protect data from eavesdropping and tampering. - **Server Identity Verification**: A2A clients should verify the A2A server's identity by validating its TLS certificate against trusted certificate authorities during the TLS handshake. This prevents man-in-the-middle attacks. ## Authentication A2A delegates authentication to standard web mechanisms. It primarily relies on HTTP headers and established standards like OAuth2 and OpenID Connect. Authentication requirements are advertised by the A2A server in its Agent Card. - **No Identity in Payload**: A2A protocol payloads, such as `JSON-RPC` messages, don't carry user or client identity information directly. Identity is established at the transport/HTTP layer. - **Agent Card Declaration**: The A2A server's Agent Card describes the authentication schemes it supports in its `security` field and aligns with those defined in the OpenAPI Specification for authentication. - **Out-of-Band Credential Acquisition**: The A2A Client obtains the necessary credentials, such as OAuth 2.0 tokens or API keys, through processes external to the A2A protocol itself. Examples include OAuth flows or secure key distribution. - **HTTP Header Transmission**: Credentials **must** be transmitted in standard HTTP headers as per the requirements of the chosen authentication scheme. Examples include `Authorization: Bearer ` or `API-Key: `. - **Server-Side Validation**: The A2A server **must** authenticate every incoming request using the credentials provided in the HTTP headers. - If authentication fails or credentials are missing, the server **should** respond with a standard HTTP status code: - `401 Unauthorized`: If the credentials are missing or invalid. This response **should** include a `WWW-Authenticate` header to inform the client about the supported authentication methods. - `403 Forbidden`: If the credentials are valid, but the authenticated client does not have permission to perform the requested action. - **In-Task Authentication (Secondary Credentials)**: If an agent needs additional credentials to access a different system or service during a task (for example, to use a specific tool on the user's behalf), the A2A server indicates to the client that more information is needed. The client is then responsible for obtaining these secondary credentials through a process outside of the A2A protocol itself (for example, an OAuth flow) and providing them back to the A2A server to continue the task. ## Authorization Once a client is authenticated, the A2A server is responsible for authorizing the request. Authorization logic is specific to the agent's implementation, the data it handles, and applicable enterprise policies. - **Granular Control**: Authorization **should** be applied based on the authenticated identity, which could represent an end user, a client application, or both. - **Skill-Based Authorization**: Access can be controlled on a per-skill basis, as advertised in the Agent Card. For example, specific OAuth scopes **should** grant an authenticated client access to invoke certain skills but not others. - **Data and Action-Level Authorization**: Agents that interact with backend systems, databases, or tools **must** enforce appropriate authorization before performing sensitive actions or accessing sensitive data through those underlying resources. The agent acts as a gatekeeper. - **Principle of Least Privilege**: Agents **must** grant only the necessary permissions required for a client or user to perform their intended operations through the A2A interface. ## Data Privacy and Confidentiality Protecting sensitive data exchanged between agents is paramount, requiring strict adherence to privacy regulations and best practices. - **Sensitivity Awareness**: Implementers must be acutely aware of the sensitivity of data exchanged in Message and Artifact parts of A2A interactions. - **Compliance**: Ensure compliance with relevant data privacy regulations such as GDPR, CCPA, and HIPAA, based on the domain and data involved. - **Data Minimization**: Avoid including or requesting unnecessarily sensitive information in A2A exchanges. - **Secure Handling**: Protect data both in transit, using TLS as mandated, and at rest if persisted by agents, according to enterprise data security policies and regulatory requirements. ## Tracing, Observability, and Monitoring A2A's reliance on HTTP allows for straightforward integration with standard enterprise tracing, logging, and monitoring tools, providing critical visibility into inter-agent workflows. - **Distributed Tracing**: A2A Clients and Servers **should** participate in distributed tracing systems. For example, use OpenTelemetry to propagate trace context, including trace IDs and span IDs, through standard HTTP headers, such as W3C Trace Context headers. This enables end-to-end visibility for debugging and performance analysis. - **Comprehensive Logging**: Log details on both client and server, including taskId, sessionId, correlation IDs, and trace context for troubleshooting and auditing. - **Metrics**: A2A servers should expose key operational metrics, such as request rates, error rates, task processing latency, and resource utilization, to enable performance monitoring, alerting, and capacity planning. - **Auditing**: Audit significant events, such as task creation, critical state changes, and agent actions, especially when involving sensitive data or high-impact operations. ## API Management and Governance For A2A servers exposed externally, across organizational boundaries, or even within large enterprises, integration with API Management solutions is highly recommended, as this provides: - **Centralized Policy Enforcement**: Consistent application of security policies such as authentication and authorization, rate limiting, and quotas. - **Traffic Management**: Load balancing, routing, and mediation. - **Analytics and Reporting**: Insights into agent usage, performance, and trends. - **Developer Portals**: Facilitate discovery of A2A-enabled agents, provide documentation such as Agent Cards, and streamline onboarding for client developers. By adhering to these enterprise-grade practices, A2A implementations can be deployed securely, reliably, and manageably within complex organizational environments. This fosters trust and enables scalable inter-agent collaboration. ================================================ FILE: docs/topics/extensions.md ================================================ # Extensions in A2A The Agent2Agent (A2A) protocol provides a strong foundation for inter-agent communication. However, specific domains or advanced use cases often require additional structure, custom data, or new interaction patterns beyond the generic methods. Extensions are A2A's powerful mechanism for layering new capabilities onto the 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 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. The flexibility of extensions allows for customizing A2A without fragmenting the core standard, fostering innovation and domain-specific optimizations. ## Scope of Extensions The exact set of possible ways to use extensions is intentionally broad, facilitating the ability to expand A2A beyond known use cases. However, some foreseeable applications include: - **Data-only Extensions**: Exposing new, structured information in the Agent Card that doesn't impact the request-response flow. For example, an extension could add structured data about an agent's GDPR compliance. - **Profile Extensions**: Overlaying additional structure and state change requirements on the core request-response messages. This type effectively acts as a profile on the core A2A protocol, narrowing the space of allowed 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' 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 capability or function an agent gains or exposes specifically through the implementation of an extension that defines new RPC methods. For example, a `task-history` extension might add a `tasks/search` RPC method to retrieve a list of previous tasks, effectively providing the agent with a new, extended skill. - **State Machine Extensions**: Adding new states or transitions to the task state machine. ## List of Example Extensions | Extension | Description | | :-------- | :------------ | | [Secure Passport Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/secure-passport) | Adds a trusted, contextual layer for immediate personalization and reduced overhead (v1). | | [Hello World or Timestamp Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/timestamp) | A simple extension demonstrating how to augment base A2A types by adding timestamps to the `metadata` field of `Message` and `Artifact` objects (v1). | | [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 protocol provides extension points in the specification, allowing agents to advertise and negotiate extended capabilities. This section defines a formal governance framework for how extensions are proposed, developed, promoted, and maintained within the A2A organization. ### Extension Tiers This framework defines two tiers of extensions within the A2A organization. Anyone may develop and publish their own extensions independently; these tiers apply specifically to extensions hosted under the `a2aproject` GitHub organization. #### Official Extensions Official extensions are developed and maintained under the `a2aproject` GitHub organization, officially recommended by the TSC, and use the `https://a2a-protocol.org/extensions/` URI prefix. **Repository Structure:** - Extension repositories use the `ext-` prefix: `github.com/a2aproject/ext-{name}` - Examples: `ext-ui`, `ext-payments`, `ext-auth` - Each repository has designated maintainers identified in `MAINTAINERS.md` **Requirements:** - Extension specifications MUST use the same language as the core specification ([RFC 2119](https://tools.ietf.org/html/rfc2119)) - Extensions MUST be licensed under Apache 2.0 - Extensions MUST have at least one reference implementation - Extensions SHOULD have associated documentation on the A2A website #### Experimental Extensions Experimental extensions provide an incubation pathway for community contributors to prototype and collaborate on extension ideas before graduation to official status. **Repository Structure:** - Experimental repositories use the `experimental-ext-` prefix: `github.com/a2aproject/experimental-ext-{name}` - Example: `experimental-ext-orchestration` **Creation Requirements:** - An experimental extension repository can ONLY be created with sponsorship from an A2A Maintainer - The sponsoring Maintainer is responsible for initial oversight of the experimental extension - 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 ### Extension Lifecycle Extensions progress through the following phases: #### Proposal Phase Any community member may propose an extension: 1. **Open an Issue**: Create an issue in the main `a2aproject/A2A` repository describing: - An abstract describing the extension's purpose - Motivation explaining why this cannot be achieved with the core protocol - 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 extension proposal 2. **Repository Creation**: The sponsoring Maintainer creates the `experimental-ext-*` 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 extension 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 Extension To graduate an experimental extension 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 extension 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**: - Upon approval, the repository is renamed from `experimental-ext-*` to `ext-*` - Documentation is added to the A2A website's extensions page #### Official Extension Iteration Once official, extensions may be iterated on: - Extension 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 extension 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. 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 and its adoption - TSC vote with standard quorum and majority requirements applies - Not all extensions are suitable for core inclusion; many will remain as extensions indefinitely ### SDK Extension Support 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 ### Legal Requirements #### Licensing Official extensions 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 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 developers acknowledge that: - They may compete with other participants - They have no obligation to implement any extension - They are free to develop competing extensions - Status as an official extension does not create an exclusive relationship ## 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. 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 and annotate additional semantic meaning in the `metadata` field. ## Extension Declaration Agents declare their support for extensions in their Agent Card by including `AgentExtension` objects within their `AgentCapabilities` object. {{ proto_to_table("AgentExtension") }} The following is an example of an Agent Card with an extension: ```json { "name": "Magic 8-ball", "description": "An agent that can tell your future... maybe.", "version": "0.1.0", "url": "https://example.com/agents/eightball", "capabilities": { "streaming": true, "extensions": [ { "uri": "https://example.com/ext/konami-code/v1", "description": "Provide cheat codes to unlock new fortunes", "required": false, "params": { "hints": [ "When your sims need extra cash fast", "You might deny it, but we've seen the evidence of those cows." ] } } ] }, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [ { "id": "fortune", "name": "Fortune teller", "description": "Seek advice from the mystical magic 8-ball", "tags": ["mystical", "untrustworthy"] } ] } ``` ## Required Extensions While extensions generally offer optional functionality, some agents may have stricter requirements. When an Agent Card declares an extension as `required: true`, it signals to clients that some aspect of the extension impacts how requests are structured or processed, and that the client must abide by it. Agents shouldn't mark data-only extensions as required. If a client does not request activation of a required extension, or fails to follow its protocol, the agent should reject the incoming request with an appropriate error. ## Extension Specification The detailed behavior and structure of an extension are defined by its **specification**. While the exact format is not mandated, it should contain at least: - The specific URI(s) that identify the extension. - The schema and meaning of objects specified in the `params` field of the `AgentExtension` object. - Schemas of any additional data structures communicated between client and agent. - Details of new request-response flows, additional endpoints, or any other logic required to implement the extension. ## Extension Dependencies Extensions might depend on other extensions. This can be a required dependency (where the extension cannot function without the dependent) or an optional one (where additional functionality is enabled if another extension is present). Extension specifications should document these dependencies. It is the client's responsibility to activate an extension and all its required dependencies as listed in the extension's specification. ## Extension Activation Extensions default to being inactive, providing a baseline 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 `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 `A2A-Extensions` header, listing all extensions that were successfully activated for that request. ![A2A Extension Flow Diagram](https://storage.googleapis.com/gweb-developer-goog-blog-assets/images/Screenshot_2025-09-04_at_13.03.31.original.png){ width="70%" style="margin:20px auto;display:block;" } **Example request showing extension activation:** ```http POST /agents/eightball HTTP/1.1 Host: example.com Content-Type: application/json A2A-Extensions: https://example.com/ext/konami-code/v1 Content-Length: 519 { "jsonrpc": "2.0", "method": "SendMessage", "id": "1", "params": { "message": { "messageId": "1", "role": "ROLE_USER", "parts": [{"text": "Oh magic 8-ball, will it rain today?"}] }, "metadata": { "https://example.com/ext/konami-code/v1/code": "motherlode" } } } ``` **Corresponding response echoing activated extensions:** ```http HTTP/1.1 200 OK Content-Type: application/json A2A-Extensions: https://example.com/ext/konami-code/v1 Content-Length: 338 { "jsonrpc": "2.0", "id": "1", "result": { "message": { "messageId": "2", "role": "ROLE_AGENT", "parts": [{"text": "That's a bingo!"}] } } } ``` ## Implementation Considerations While the A2A protocol defines the functionality of extensions, this section provides guidance on their implementation—best practices for authoring, versioning, and distributing extension implementations. - **Versioning**: Extension specifications evolve. It is crucial to have a clear versioning strategy to ensure that clients and agents can negotiate compatible implementations. - **Recommendation**: Use the extension's URI as the primary version identifier, ideally including a version number (for example, `https://example.com/ext/my-extension/v1`). - **Breaking Changes**: A new URI MUST be used when introducing a breaking change to an extension's logic, data structures, or required parameters. - Handling Mismatches: If a client requests a version not supported by the agent, the agent SHOULD ignore the activation request for that extension; it MUST NOT fall back to a different version. - **Discoverability and Publication**: - **Specification Hosting**: The extension specification document **should** be hosted at the extension's URI. - **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**: 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 server applications. - An extension implementation should be distributed as a standard package for its language ecosystem (for example, a PyPI package for Python, an npm package for TypeScript/JavaScript). - The objective is to provide a streamlined integration experience for developers. A well-designed extension package should allow a developer to add it to their server with minimal code, for example: ```python --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/adk_expense_reimbursement/__main__.py" ``` This example showcases how A2A SDKs or libraries such as `a2a.server` in Python facilitate the implementation of A2A agents and extensions. - **Security**: Extensions modify the core behavior of the A2A protocol, and therefore introduce new security considerations: - **Input Validation**: Any new data fields, parameters, or methods introduced by an extension MUST be rigorously validated. Treat all extension-related data from an external party as untrusted input. - **Scope of Required Extensions**: Be mindful when marking an extension as `required: true` in an Agent Card. This creates a hard dependency for all clients and should only be used for extensions fundamental to the agent's core function and security (for example, a message signing extension). - **Authentication and Authorization**: If an extension adds new methods, the implementation MUST ensure these methods are subject to the same authentication and authorization checks as the core A2A methods. An extension MUST NOT provide a way to bypass the agent's primary security controls. For more information, see the [A2A Extensions: Empowering Custom Agent Functionality](https://developers.googleblog.com/en/a2a-extensions-empowering-custom-agent-functionality/) blog post. ================================================ FILE: docs/topics/key-concepts.md ================================================ # Core Concepts and Components in A2A A2A uses a set of core concepts that define how agents interact. Understand these core building blocks to develop or integrate with A2A-compliant systems. ![A2A Actors showing a User, A2A Client (Client Agent), and A2A Server (Remote Agent)](../assets/a2a-actors.png){ width="70%" style="margin:20px auto;display:block;" } ## Core Actors in A2A Interactions - **User**: The end user, which can be a human operator or an automated service. The user initiates a request or defines a goal that requires assistance from one or more AI agents. - **A2A Client (Client Agent)**: An application, service, or another AI agent that acts on behalf of the user. The client initiates communication using the A2A protocol. - **A2A Server (Remote Agent)**: An AI agent or an agentic system that exposes an HTTP endpoint implementing the A2A protocol. It receives requests from clients, processes tasks, and returns results or status updates. From the client's perspective, the remote agent operates as an _opaque_ (black-box) system, meaning its internal workings, memory, or tools are not exposed. ## Fundamental Communication Elements The following table describes the fundamental communication elements in A2A: | Element | Description | Key Purpose | | :------ | :---------- | :---------- | | 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 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 The A2A Protocol supports various interaction patterns to accommodate different needs for responsiveness and persistence. These mechanisms ensure that agents can exchange information efficiently and reliably, regardless of the task's complexity or duration: - **Request/Response (Polling)**: Clients send a request and the server responds. For long-running tasks, the client periodically polls the server for updates. - **Streaming with Server-Sent Events (SSE)**: Clients initiate a stream to receive real-time, incremental results or status updates from the server over an open HTTP connection. - **Push Notifications**: For very long-running tasks or disconnected scenarios, the server can actively send asynchronous notifications to a client-provided webhook when significant task updates occur. For a detailed exploration of streaming and push notifications, refer to the [Streaming & Asynchronous Operations](./streaming-and-async.md) document. ## Agent Cards The Agent Card is a JSON document that serves as a digital business card for initial discovery and interaction setup. It provides essential metadata about an agent. Clients parse this information to determine if an agent is suitable for a given task, how to structure requests, and how to communicate securely. Key information includes identity, service endpoint (URL), A2A capabilities, authentication requirements, and a list of skills. ## Messages and Parts A message represents a single turn of communication between a client and an 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 `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: - `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 An artifact represents a tangible output or a concrete result generated by a remote agent during task processing. Unlike general messages, artifacts are the actual deliverables. An artifact has a unique `artifactId`, a human-readable name, and consists of one or more part objects. Artifacts are closely tied to the task lifecycle and can be streamed incrementally to the client. ## Agent Response: Task or Message The agent response can be a new `Task` (when the agent needs to perform a long-running operation) or a `Message` (when the agent can respond immediately). For more details, see [Life of a Task](./life-of-a-task.md). ## Other Important Concepts - **Context (`contextId`):** A server-generated identifier that can be used to logically group multiple related `Task` objects, providing context across a series of interactions. - **Transport and Format:** A2A communication occurs over HTTP(S). JSON-RPC 2.0 is used as the payload format for all requests and responses. - **Authentication & Authorization:** A2A relies on standard web security practices. Authentication requirements are declared in the Agent Card, and credentials (e.g., OAuth tokens, API keys) are typically passed through HTTP headers, separate from the A2A protocol messages themselves. For more information, see [Enterprise-Ready Features](./enterprise-ready.md). - **Agent Discovery:** The process by which clients find Agent Cards to learn about available A2A Servers and their capabilities. For more information, see [Agent Discovery](./agent-discovery.md). - **Extensions:** A2A allows agents to declare custom protocol extensions as part of their AgentCard. For more information, see [Extensions](./extensions.md). ================================================ FILE: docs/topics/life-of-a-task.md ================================================ # Life of a Task In the Agent2Agent (A2A) Protocol, interactions can range from simple, stateless exchanges to complex, long-running processes. When an agent receives a message from a client, it can respond in one of two fundamental ways: - **Respond with a Stateless `Message`**: This type of response is typically used for immediate, self-contained interactions that conclude without requiring further state management. - **Initiate a Stateful `Task`**: If the response is a `Task`, the agent will process it through a defined lifecycle, communicating progress and requiring input as needed, until it reaches an interrupted state (e.g., `input-required`, `auth-required`) or a terminal state (e.g., `completed`, `canceled`, `rejected`, `failed`). ## Group Related Interactions A `contextId` is a crucial identifier that logically groups multiple `Task` objects and independent `Message` objects, providing continuity across a series of interactions. - When a client sends a message for the first time, the agent responds with a new `contextId`. If a task is initiated, it will also have a `taskId`. - Clients can send subsequent messages and include the same `contextId` to indicate that they are continuing their previous interaction within the same context. - Clients optionally attach the `taskId` to a subsequent message to indicate that it continues that specific task. The `contextId` enables collaboration towards a common goal or a shared contextual session across multiple, potentially concurrent tasks. Internally, an A2A agent (especially one using an LLM) uses the `contextId` to manage its internal conversational state or its LLM context. ## Agent Response: Message or Task The choice between responding with a `Message` or a `Task` depends on the nature of the interaction and the agent's capabilities: - **Messages for Trivial Interactions**: `Message` objects are suitable for transactional interactions that don't require long-running processing or complex state management. An agent might use messages to negotiate the acceptance or scope of a task before committing to a `Task` object. - **Tasks for Stateful Interactions**: Once an agent maps the intent of an incoming message to a supported capability that requires substantial, trackable work over an extended period, the agent responds with a `Task` object. Conceptually, agents operate at different levels of complexity: - **Message-only Agents**: Always respond with `Message` objects. They typically don't manage complex state or long-running executions, and use `contextId` to tie messages together. These agents might directly wrap LLM invocations and simple tools. - **Task-generating Agents**: Always respond with `Task` objects, even for responses, which are then modeled as completed tasks. Once a task is created, the agent will only return `Task` objects in response to messages sent, and once a task is complete, no more messages can be sent. This approach avoids deciding between `Task` versus `Message`, but creates completed task objects for even simple interactions. - **Hybrid Agents**: Generate both `Message` and `Task` objects. These agents use messages to negotiate agent capability and the scope of work for a task, then send a `Task` object to track execution and manage states like `input-required` or error handling. Once a task is created, the agent will only return `Task` objects in response to messages sent, and once a task is complete, no more messages can be sent. A hybrid agent uses messages to negotiate the scope of a task, and then generate a task to track its execution. For more information about hybrid agents, see [A2A protocol: Demystifying Tasks vs Messages](https://discuss.google.dev/t/a2a-protocol-demystifying-tasks-vs-messages/255879). ## Task Refinements Clients often need to send new requests based on task results or refine the outputs of previous tasks. This is modeled by starting another interaction using the same `contextId` as the original task. Clients further hint the agent by providing references to the original task using `referenceTaskIds` in the `Message` object. The agent then responds with either a new `Task` or a `Message`. ## Task Immutability Once a task reaches a terminal state (completed, canceled, rejected, or failed), it cannot restart. Any subsequent interaction related to that task, such as a refinement, must initiate a new task within the same `contextId`. This principle offers several benefits: - **Task Immutability.** Clients reliably reference tasks and their associated state, artifacts, and messages, providing a clean mapping of inputs to outputs. This is valuable for orchestration and traceability. - **Clear Unit of Work.** Every new request, refinement, or follow-up becomes a distinct task. This simplifies bookkeeping, allows for granular tracking of an agent's work, and enables tracing each artifact to a specific unit of work. - **Easier Implementation.** This removes ambiguity for agent developers regarding whether to create a new task or restart an existing one. ## Parallel Follow-ups A2A supports parallel work by enabling agents to create distinct, parallel tasks for each follow-up message sent within the same `contextId`. This allows clients to track individual tasks and create new dependent tasks as soon as a prerequisite task is complete. For example: - Task 1: Book a flight to Helsinki. - Task 2: Based on Task 1, book a hotel. - Task 3: Based on Task 1, book a snowmobile activity. - Task 4: Based on Task 2, add a spa reservation to the hotel booking. ## Referencing Previous Artifacts The serving agent infers the relevant artifact from a referenced task or from the `contextId`. As the domain expert, the serving agent is best suited to resolve ambiguity or identify missing information. If there is ambiguity, the agent asks the client for clarification by returning an `input-required` state. The client then specifies the artifact in its response, optionally populating artifact references (`artifactId`, `taskId`) in `Part` metadata. ## Tracking Artifact Mutation Follow-up or refinement tasks often lead to the creation of new artifacts based on older ones. Tracking these mutations is important to ensure that only the most recent version of an artifact is used in subsequent interactions. This could be conceptualized as a version history, where each new artifact is linked to its predecessor. However, the client is in the best position to manage this artifact linkage. The client determines what constitutes an acceptable result and has the ability to accept or reject new versions. Therefore, the serving agent shouldn't be responsible for tracking artifact mutations, and this linkage is not part of the A2A protocol specification. Clients should maintain this version history on their end and present the latest acceptable version to the user. To facilitate client-side tracking, serving agents should use a consistent `artifact-name` when generating a refined version of an existing artifact. When initiating follow-up or refinement tasks, the client should explicitly reference the specific artifact they intend to refine, ideally the "latest" version from their perspective. If the artifact reference is not provided, the serving agent can: - Attempt to infer the intended artifact based on the current `contextId`. - If there is ambiguity or insufficient context, the agent should respond with an `input-required` task state to request clarification from the client. ## Example Follow-up Scenario The following example illustrates a typical task flow with a follow-up: 1. Client sends a message to the agent: ```json { "jsonrpc": "2.0", "id": "req-001", "method": "SendMessage", "params": { "message": { "role": "user", "parts": [ { "text": "Generate an image of a sailboat on the ocean." } ], "messageId": "msg-user-001" } } } ``` 2. Agent responds with a boat image (completed task): ```json { "jsonrpc": "2.0", "id": "req-001", "result": { "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" } ] } ] } } } ``` 3. Client asks to color the boat red. This refinement request refers to the previous `taskId` and uses the same `contextId`. ```json { "jsonrpc": "2.0", "id": "req-002", "method": "SendMessage", "params": { "message": { "role": "user", "messageId": "msg-user-002", "contextId": "ctx-conversation-abc", "referenceTaskIds": [ "task-boat-gen-123" ], "parts": [ { "text": "Please modify the sailboat to be red." } ] } } } ``` 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`. ```json { "jsonrpc": "2.0", "id": "req-002", "result": { "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" } ] } ] } } } ``` ================================================ FILE: docs/topics/streaming-and-async.md ================================================ # Streaming and Asynchronous Operations for Long-Running Tasks The Agent2Agent (A2A) protocol is explicitly designed to handle tasks that might not complete immediately. Many AI-driven operations are often long-running, involve multiple steps, produce incremental results, or require human intervention. A2A provides mechanisms for managing such asynchronous interactions, ensuring that clients receive updates effectively, whether they remain continuously connected or operate in a more disconnected fashion. ## Streaming with Server-Sent Events (SSE) For tasks that produce incremental results (like generating a long document or streaming media) or provide ongoing status updates, A2A supports real-time communication using Server-Sent Events (SSE). This approach is ideal when the client is able to maintain an active HTTP connection with the A2A Server. The following key features detail how SSE streaming is implemented and managed within the A2A protocol: - **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 `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#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:** 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 `SubscribeToTask` RPC method. ### When to Use Streaming Streaming with SSE is best suited for: - Real-time progress monitoring of long-running tasks. - Receiving large results (artifacts) incrementally. - Interactive, conversational exchanges where immediate feedback or partial responses are beneficial. - Applications requiring low-latency updates from the agent. ### Protocol Specification References Refer to the Protocol Specification for detailed structures: - [`SendStreamingMessage`](../specification.md#72-messagestream) - [`SubscribeToTask`](../specification.md#79-taskssubscribe) ## Push Notifications for Disconnected Scenarios For very long-running tasks (for example, lasting minutes, hours, or even days) or when clients are unable to or prefer not to maintain persistent connections (like mobile clients or serverless functions), A2A supports asynchronous updates using push notifications. This allows the A2A Server to actively notify a client-provided webhook when a significant task update occurs. 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#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 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 Push notifications are ideal for: - Very long-running tasks that can take minutes, hours, or days to complete. - Clients that cannot or prefer not to maintain persistent connections, such as mobile applications or serverless functions. - Scenarios where clients only need to be notified of significant state changes rather than continuous updates. ### Protocol Specification References Refer to the Protocol Specification for detailed structures: - [`CreateTaskPushNotificationConfig`](../specification.md#317-create-push-notification-config) - [`GetTask`](../specification.md#76-taskspushnotificationconfigget) ### Client-Side Push Notification Service The `url` specified in `PushNotificationConfig.url` points to a client-side Push Notification Service. This service is responsible for receiving the HTTP POST notification from the A2A Server. Its responsibilities include authenticating the incoming notification, validating its relevance, and relaying the notification or its content to the appropriate client application logic or system. ### Security Considerations for Push Notifications Security is paramount for push notifications due to their asynchronous and server-initiated outbound nature. Both the A2A Server (sending the notification) and the client's webhook receiver have critical responsibilities. #### A2A Server Security (when sending notifications to client webhook) - **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 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) - **Authenticating the A2A Server:** The webhook endpoint MUST rigorously verify the authenticity of incoming notification requests to ensure they originate from the legitimate A2A Server and not an imposter. - **Verification methods:** Verify signatures/tokens (for example, JWT signatures against the A2A Server's trusted public keys, HMAC signatures, or API key validation). Also, validate the `PushNotificationConfig.token` if provided. - **Preventing Replay Attacks:** - **Timestamps:** Notifications SHOULD include a timestamp. The webhook SHOULD reject notifications that are too old. - **Nonces/unique IDs:** For critical notifications, consider using unique, single-use identifiers (for example, JWT's `jti` claim or event IDs) to prevent processing duplicate notifications. - **Secure Key Management and Rotation:** Implement secure key management practices, including regular key rotation, especially for cryptographic keys. Protocols like JWKS (JSON Web Key Set) facilitate key rotation for asymmetric keys. #### Example Asymmetric Key Flow (JWT + JWKS) 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`). - The A2A Server makes its public keys available through a JWKS endpoint. 3. Client Webhook, upon receiving the notification: - Extracts the JWT from the Authorization header. - Inspects the `kid` (key ID) in the JWT header. - Fetches the corresponding public key from the A2A Server's JWKS endpoint (caching keys is recommended). - Verifies the JWT signature using the public key. - Validates claims (`iss`, `aud`, `iat`, `exp`, `jti`). - Checks the `PushNotificationConfig.token` if provided. This comprehensive, layered approach to security for push notifications helps ensure that messages are authentic, integral, and timely, protecting both the sending A2A Server and the receiving client webhook infrastructure. ================================================ FILE: docs/topics/what-is-a2a.md ================================================ # What is A2A? The A2A protocol is an open standard that enables seamless communication and collaboration between AI agents. It provides a common language for agents built using diverse frameworks and by different vendors, fostering interoperability and breaking down silos. Agents are autonomous problem-solvers that act independently within their environment. A2A allows agents from different developers, built on different frameworks, and owned by different organizations to unite and work together. ## Why Use the A2A Protocol A2A addresses key challenges in AI agent collaboration. It provides a standardized approach for agents to interact. This section explains the problems A2A solves and the benefits it offers. ### Problems that A2A Solves Consider a user request for an AI assistant to plan an international trip. This task involves orchestrating multiple specialized agents, such as: - A flight booking agent - A hotel reservation agent - An agent for local tour recommendations - A currency conversion agent Without A2A, integrating these diverse agents presents several challenges: - **Agent Exposure**: Developers often wrap agents as tools to expose them to other agents, similar to how tools are exposed in a Multi-agent Control Platform (Model Context Protocol). However, this approach is inefficient because agents are designed to negotiate directly. Wrapping agents as tools limits their capabilities. A2A allows agents to be exposed as they are, without requiring this wrapping. - **Custom Integrations**: Each interaction requires custom, point-to-point solutions, creating significant engineering overhead. - **Slow Innovation**: Bespoke development for each new integration slows innovation. - **Scalability Issues**: Systems become difficult to scale and maintain as the number of agents and interactions grows. - **Interoperability**: This approach limits interoperability, preventing the organic formation of complex AI ecosystems. - **Security Gaps**: Ad hoc communication often lacks consistent security measures. The A2A protocol addresses these challenges by establishing interoperability for AI agents to interact reliably and securely. ### A2A Example Scenario This section provides an example scenario to illustrate the benefits of using an A2A (Agent2Agent) protocol for complex interactions between AI agents. #### A User's Complex Request A user interacts with an AI assistant, giving it a complex prompt like "Plan an international trip." ```mermaid graph LR User --> Prompt --> AI_Assistant[AI Assistant] ``` #### The Need for Collaboration The AI assistant receives the prompt and realizes it needs to call upon multiple specialized agents to fulfill the request. These agents include a Flight Booking Agent, a Hotel Reservation Agent, a Currency Conversion Agent, and a Local Tours Agent. ```mermaid graph LR subgraph "Specialized Agents" FBA[✈️ Flight Booking Agent] HRA[🏨 Hotel Reservation Agent] CCA[💱 Currency Conversion Agent] LTA[🚌 Local Tours Agent] end AI_Assistant[🤖 AI Assistant] --> FBA AI_Assistant --> HRA AI_Assistant --> CCA AI_Assistant --> LTA ``` #### The Interoperability Challenge The core problem: The agents are unable to work together because each has its own bespoke development and deployment. The consequence of a lack of a standardized protocol is that these agents cannot collaborate with each other let alone discover what they can do. The individual agents (Flight, Hotel, Currency, and Tours) are isolated. #### The "With A2A" Solution The A2A Protocol provides standard methods and data structures for agents to communicate with one another, regardless of their underlying implementation, so the same agents can be used as an interconnected system, communicating seamlessly through the standardized protocol. The AI assistant, now acting as an orchestrator, receives the cohesive information from all the A2A-enabled agents. It then presents a single, complete travel plan as a seamless response to the user's initial prompt. ![A2A Actors showing a User, A2A Client (Client Agent), and A2A Server (Remote Agent)](../assets/a2a-actors.png){ width="70%" style="margin:20px auto;display:block;" } ### Core Benefits of A2A Implementing the A2A protocol offers significant advantages across the AI ecosystem: - **Secure collaboration**: Without a standard, it's difficult to ensure secure communication between agents. A2A uses HTTPS for secure communication and maintains opaque operations, so agents can't see the inner workings of other agents during collaboration. - **Interoperability**: A2A breaks down silos between different AI agent ecosystems, enabling agents from various vendors and frameworks to work together seamlessly. - **Agent autonomy**: A2A allows agents to retain their individual capabilities and act as autonomous entities while collaborating with other agents. - **Reduced integration complexity**: The protocol standardizes agent communication, enabling teams to focus on the unique value their agents provide. - **Support for LRO**: The protocol supports long-running operations (LRO) and streaming with Server-Sent Events (SSE) and asynchronous execution. ### Key Design Principles of A2A A2A development follows principles that prioritize broad adoption, enterprise-grade capabilities, and future-proofing. - **Simplicity**: A2A leverages existing standards like HTTP, JSON-RPC, and Server-Sent Events (SSE). This avoids reinventing core technologies and accelerates developer adoption. - **Enterprise Readiness**: A2A addresses critical enterprise needs. It aligns with standard web practices for robust authentication, authorization, security, privacy, tracing, and monitoring. - **Asynchronous**: A2A natively supports long-running tasks. It handles scenarios where agents or users might not remain continuously connected. It uses mechanisms like streaming and push notifications. - **Modality Independent**: The protocol allows agents to communicate using a wide variety of content types. This enables rich and flexible interactions beyond plain text. - **Opaque Execution**: Agents collaborate effectively without exposing their internal logic, memory, or proprietary tools. Interactions rely on declared capabilities and exchanged context. This preserves intellectual property and enhances security. ### Understanding the Agent Stack: A2A, MCP, Agent Frameworks and Models A2A is situated within a broader agent stack, which includes: - **A2A:** Standardizes communication among agents deployed in different organizations and developed using diverse frameworks. - **MCP:** Connects models to data and external resources. - **Frameworks (like ADK):** Provide toolkits for constructing agents. - **Models:** Fundamental to an agent's reasoning, these can be any Large Language Model (LLM). ![ADK versus MCP](../assets/agentic-stack.png){ width="70%" style="margin:20px auto;display:block;" } #### A2A and MCP In the broader ecosystem of AI communication, you might be familiar with protocols designed to facilitate interactions between agents, models, and tools. Notably, the Model Context Protocol (MCP) is an emerging standard focused on connecting Large Language Models (LLMs) with data and external resources. The Agent2Agent (A2A) protocol is designed to standardize communication between AI agents, particularly those deployed in external systems. A2A is positioned to complement MCP, addressing a distinct yet related aspect of agent interaction. - **MCP's Focus:** Reducing the complexity involved in connecting agents with tools and data. Tools are typically stateless and perform specific, predefined functions (e.g., a calculator, a database query). - **A2A's Focus:** Enabling agents to collaborate within their native modalities, allowing them to communicate as agents (or as users) rather than being constrained to tool-like interactions. This enables complex, multi-turn interactions where agents reason, plan, and delegate tasks to other agents. For example, this facilitates multi-turn interactions, such as those involving negotiation or clarification when placing an order. ![ADK + MCP](../assets/a2a-mcp-readme.png){ width="70%" style="margin:20px auto;display:block;" } The practice of encapsulating an agent as a simple tool is fundamentally limiting, as it fails to capture the agent's full capabilities. This critical distinction is explored in the post, [Why Agents Are Not Tools](https://discuss.google.dev/t/agents-are-not-tools/192812). For a more in-depth comparison, refer to the [A2A and MCP Comparison](a2a-and-mcp.md) document. #### A2A and ADK The [Agent Development Kit (ADK)](https://google.github.io/adk-docs) is an open-source agent development toolkit developed by Google. A2A is a communication protocol for agents that enables inter-agent communication, regardless of the framework used for their construction (e.g., ADK, LangGraph, or Crew AI). ADK is a flexible and modular framework for developing and deploying AI agents. While optimized for Gemini AI and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and built for compatibility with other frameworks. ### A2A Request Lifecycle The A2A request lifecycle is a sequence that details the four main steps a request follows: agent discovery, authentication, `sendMessage` API, and `sendMessageStream` API. The following diagram provides a deeper look into the operational flow, illustrating the interactions between the client, A2A server, and auth server. ```mermaid sequenceDiagram participant Client participant A2A Server participant Auth Server rect rgb(240, 240, 240) Note over Client, A2A Server: 1. Agent Discovery Client->>A2A Server: GET agent card eg: (/.well-known/agent-card) A2A Server-->>Client: Returns Agent Card end rect rgb(240, 240, 240) Note over Client, Auth Server: 2. Authentication Client->>Client: Parse Agent Card for securitySchemes alt securityScheme is "openIdConnect" Client->>Auth Server: Request token based on "authorizationUrl" and "tokenUrl". Auth Server-->>Client: Returns JWT end end rect rgb(240, 240, 240) Note over Client, A2A Server: 3. sendMessage API Client->>Client: Parse Agent Card for "url" param to send API requests to. Client->>A2A Server: POST /sendMessage (with JWT) A2A Server->>A2A Server: Process message and create task A2A Server-->>Client: Returns Task Response end rect rgb(240, 240, 240) Note over Client, A2A Server: 4. sendMessageStream API Client->>A2A Server: POST /sendMessageStream (with JWT) A2A Server-->>Client: Stream: Task (Submitted) A2A Server-->>Client: Stream: TaskStatusUpdateEvent (Working) A2A Server-->>Client: Stream: TaskArtifactUpdateEvent (artifact A) A2A Server-->>Client: Stream: TaskArtifactUpdateEvent (artifact B) A2A Server-->>Client: Stream: TaskStatusUpdateEvent (Completed) end ``` ## What's Next Learn about the [Key Concepts](./key-concepts.md) that form the foundation of the A2A protocol. ================================================ FILE: docs/tutorials/index.md ================================================ # Tutorials ## Python Tutorial | Description | Difficulty :--------|:------------|:----------- [A2A and Python Quickstart](./python/1-introduction.md) | Learn to build a simple Python-based "echo" A2A server and client. | Easy [ADK facts](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/adk_facts) | Build and test a simple Personal Assistant agent using the Agent Development Kit (ADK) that can provide interesting facts. | Easy [ADK agent on Cloud Run](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/adk_cloud_run) | Deploy, manage, and observe an ADK-based agent as a scalable, serverless service on Google Cloud Run.| Easy [Multi-agent collaboration using A2A](https://github.com/a2aproject/a2a-samples/tree/main/demo) | Learn how to set up an orchestrator (host agent) that routes and manages requests among several specialized A2A-compatible agents. | Easy [Airbnb and weather multi-agent](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/airbnb_planner_multiagent) | Build a complex multi-agent system where agents collaborate using A2A to plan a trip, finding both Airbnb accommodations and weather information. | Medium [A2A Client-Server example using remote ADK agent](https://goo.gle/adk-a2a) | Learn how a local A2A client agent discovers and consumes the capabilities of a separate, remote ADK-based agent (for example, a prime number checker). | Easy [Colab Notebook](https://github.com/a2aproject/a2a-samples/blob/main/notebooks/multi_agents_eval_with_cloud_run_deployment.ipynb) | Use Colab Notebook to deploy A2A agents to Cloud Run from your browser, and then evaluate their performance with Vertex AI. | Easy ## Java Tutorial | Description | Difficulty :--------|:------------|:----------- [Weather Agent](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/weather_mcp) | Build a weather information agent using an MCP server.

**To make use of this agent in a multi-language, multi-agent system, check out the [weather_and_airbnb_planner sample](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/weather_and_airbnb_planner).** | Easy [Content Writer Agent](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/content_writer) | Build a content writer agent that generates engaging pieces of content from outlines.

**To make use of this agent in a content creation multi-language, multi-agent system, check out the [content_creation sample](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/content_creation).** | Easy [Content Editor Agent](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/content_editor) | Build a content editor agent that proof-reads and polishes content.

**To make use of this agent in a content creation multi-language, multi-agent system, check out the [content_creation sample](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/content_creation).** | Easy [Dice Agent (Multi-Transport)](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/dice_agent_multi_transport) | Build a multi-transport agent that rolls dice and checks for prime numbers. | Medium [Magic 8 Ball Agent (Security)](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents/magic_8_ball_security) | Build a Magic 8 Ball agent to learn how to secure A2A servers with Keycloak using bearer token authentication and configure an A2A client to obtain and pass the required token. | Medium ## JavaScript Tutorial | Description :--------|:------------ [Movie research agent using JavaScript](https://github.com/a2aproject/a2a-samples/tree/main/samples/js) | Build an A2A agent with Node.js that uses the TMDB (The Movie Database) API to handle movie searches and queries. ## C#/.NET Tutorial | Description :--------|:------------ [All .NET samples](https://github.com/a2aproject/a2a-dotnet/tree/main/samples) | Repository of foundational samples showing how to build A2A clients and servers, including an Echo Agent, using the C#/.NET SDK. ================================================ FILE: docs/tutorials/python/1-introduction.md ================================================ # Python Quickstart Tutorial: Building an A2A Agent Welcome to the Agent2Agent (A2A) Python Quickstart Tutorial! In this tutorial, you will explore a simple "echo" A2A server using the Python SDK. This will introduce you to the fundamental concepts and components of an A2A server. You will then look at a more advanced example that integrates a Large Language Model (LLM). This hands-on guide will help you understand: - The basic concepts behind the A2A protocol. - How to set up a Python environment for A2A development using the SDK. - How Agent Skills and Agent Cards describe an agent. - How an A2A server handles tasks. - How to interact with an A2A server using a client. - How streaming capabilities and multi-turn interactions work. - How an LLM can be integrated into an A2A agent. By the end of this tutorial, you will have a functional understanding of A2A agents and a solid foundation for building or integrating A2A-compliant applications. ## Tutorial Sections The tutorial is broken down into the following steps: 1. **[Introduction (This Page)](./1-introduction.md)** 2. **[Setup](./2-setup.md)**: Prepare your Python environment and the A2A SDK. 3. **[Agent Skills & Agent Card](./3-agent-skills-and-card.md)**: Define what your agent can do and how it describes itself. 4. **[The Agent Executor](./4-agent-executor.md)**: Understand how the agent logic is implemented. 5. **[Starting the Server](./5-start-server.md)**: Run the Helloworld A2A server. 6. **[Interacting with the Server](./6-interact-with-server.md)**: Send requests to your agent. 7. **[Streaming & Multi-Turn Interactions](./7-streaming-and-multiturn.md)**: Explore advanced capabilities with the LangGraph example. 8. **[Next Steps](./8-next-steps.md)**: Explore further possibilities with A2A. Let's get started! ================================================ FILE: docs/tutorials/python/2-setup.md ================================================ # 2. Setup Your Environment ## Prerequisites - Python 3.10 or higher. - Access to a terminal or command prompt. - Git, for cloning the repository. - A code editor (e.g., Visual Studio Code) is recommended. ## Clone the Repository If you haven't already, clone the A2A Samples repository: ```bash git clone https://github.com/a2aproject/a2a-samples.git -b main --depth 1 cd a2a-samples ``` ## Python Environment & SDK Installation We recommend using a virtual environment for Python projects. The A2A Python SDK uses `uv` for dependency management, but you can use `pip` with `venv` as well. 1. **Create and activate a virtual environment:** Using `venv` (standard library): === "Mac/Linux" ```sh python -m venv .venv source .venv/bin/activate ``` === "Windows" ```powershell python -m venv .venv .venv\Scripts\activate ``` 2. **Install needed Python dependencies along with the A2A SDK and its dependencies:** ```bash pip install -r samples/python/requirements.txt ``` ## Verify Installation After installation, you should be able to import the `a2a` package in a Python interpreter: ```bash python -c "import a2a; print('A2A SDK imported successfully')" ``` If this command runs without error and prints the success message, your environment is set up correctly. ================================================ FILE: docs/tutorials/python/3-agent-skills-and-card.md ================================================ # 3. Agent Skills & Agent Card Before an A2A agent can do anything, it needs to define what it _can_ do (its skills) and how other agents or clients can find out about these capabilities (its Agent Card). We'll use the `helloworld` example located in [`a2a-samples/samples/python/agents/helloworld/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/helloworld). ## Agent Skills 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`): - `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"). In `__main__.py`, you can see how a skill for the Helloworld agent is defined: ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentSkill" ``` This skill is very simple: it's named "Returns hello world" and primarily deals with text. ## Agent Card The **Agent Card** is a JSON document that an A2A Server makes available, typically at a `.well-known/agent-card.json` endpoint. It's like a digital business card for the agent. 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. - `skills`: A list of `AgentSkill` objects that the agent offers. The `helloworld` example defines its Agent Card like this: ```python { .no-copy } --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. ================================================ FILE: docs/tutorials/python/4-agent-executor.md ================================================ # 4. The Agent Executor The core logic of how an A2A agent processes requests and generates responses/events is handled by an **Agent Executor**. The A2A Python SDK provides an abstract base class `a2a.server.agent_execution.AgentExecutor` that you implement. ## `AgentExecutor` Interface The `AgentExecutor` class defines two primary methods: - `async def execute(self, context: RequestContext, event_queue: EventQueue)`: Handles incoming requests that expect a response or a stream of events. It processes the user's input (available via `context`) and uses the `event_queue` to send back `Message`, `Task`, `TaskStatusUpdateEvent`, or `TaskArtifactUpdateEvent` objects. - `async def cancel(self, context: RequestContext, event_queue: EventQueue)`: Handles requests to cancel an ongoing task. The `RequestContext` provides information about the incoming request, such as the user's message and any existing task details. The `EventQueue` is used by the executor to send events back to the client. ## Helloworld Agent Executor Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`. 1. **The Agent (`HelloWorldAgent`)**: This is a simple helper class that encapsulates the actual "business logic". ```python { .no-copy } --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". 2. **The Executor (`HelloWorldAgentExecutor`)**: This class implements the `AgentExecutor` interface. - **`__init__`**: ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_init" ``` It instantiates the `HelloWorldAgent`. - **`execute`**: ```python { .no-copy } --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): 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. - **`cancel`**: The Hello World example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent. ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel" ``` 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. ================================================ FILE: docs/tutorials/python/5-start-server.md ================================================ # 5. Starting the Server 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/). ## Server Setup in Helloworld Let's look at `__main__.py` again to see how the server is initialized and started. ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py" ``` Let's break this down: 1. **`DefaultRequestHandler`**: - The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`). - 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. 2. **`A2AStarletteApplication`**: - 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`. 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`. ## Running the Helloworld Server Navigate to the `a2a-samples` directory in your terminal (if you're not already there) and ensure your virtual environment is activated. To run the Helloworld server: ```bash # from the a2a-samples directory python samples/python/agents/helloworld/__main__.py ``` You should see output similar to this, indicating the server is running: ```console { .no-copy } 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) ``` Your A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it. ================================================ FILE: docs/tutorials/python/6-interact-with-server.md ================================================ # 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. ## 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. 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): === "Mac/Linux" ```sh source .venv/bin/activate ``` === "Windows" ```powershell .venv\Scripts\activate ``` Run the test client: ```bash # from the a2a-samples directory python samples/python/agents/helloworld/test_client.py ``` ## Understanding the Client Code Let's look at key parts of `test_client.py`: 1. **Fetching the Agent Card & Initializing the Client**: ```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. 2. **Sending a Non-Streaming Message (`send_message`)**: ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message" ``` - 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`. 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`)**: ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming" ``` - 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`. ## Expected Output When you run `test_client.py`, you'll see JSON outputs 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 `id` fields in the output will vary with each run. ```console { .no-copy } // Non-streaming response {"jsonrpc":"2.0","id":"xxxxxxxx","result":{"message":{"role":"ROLE_AGENT","parts":[{"text":"Hello World"}],"messageId":"yyyyyyyy"}}} // Streaming response (one chunk) {"jsonrpc":"2.0","id":"zzzzzzzz","result":{"message":{"role":"ROLE_AGENT","parts":[{"text":"Hello World"}],"messageId":"wwwwwwww"}}} ``` _(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww` will be different UUIDs/request IDs)_ 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. ================================================ FILE: docs/tutorials/python/7-streaming-and-multiturn.md ================================================ # 7. Streaming & Multi-Turn Interactions (LangGraph Example) 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. 2. **Environment Variable:** Create a `.env` file in the `a2a-samples/samples/python/agents/langgraph/` directory: ```bash echo "GOOGLE_API_KEY=YOUR_API_KEY_HERE" > .env ``` Replace `YOUR_API_KEY_HERE` with your actual Gemini API key. 3. **Install Dependencies (if not already covered):** The `langgraph` example has its own `pyproject.toml` which includes dependencies like `langchain-google-genai` and `langgraph`. When you installed the SDK from the `a2a-samples` root using `pip install -e .[dev]`, this should have also installed the dependencies for the workspace examples, including `langgraph-example`. If you encounter import errors, ensure your primary SDK installation from the root directory was successful. ## Running the LangGraph Server Navigate to the `a2a-samples/samples/python/agents/langgraph/app` directory in your terminal and ensure your virtual environment (from the SDK root) is activated. Start the LangGraph agent server: ```bash python __main__.py ``` This will start the server, usually on `http://localhost:10000`. ## Interacting with the LangGraph Agent Open a **new terminal window**, activate your virtual environment, and navigate to `a2a-samples/samples/python/agents/langgraph/app`. Run its test client: ```bash python test_client.py ``` Now, you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running. ## Key Features Demonstrated The `langgraph` example showcases several important A2A concepts: 1. **LLM Integration**: - `agent.py` defines `CurrencyAgent`. It uses `ChatGoogleGenerativeAI` and LangGraph's `create_react_agent` to process user queries. - This demonstrates how a real LLM can power the agent's logic. 2. **Task State Management**: - `samples/langgraph/__main__.py` initializes a `DefaultRequestHandler` with an `InMemoryTaskStore`. ```python { .no-copy } --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/langgraph/app/__main__.py:DefaultRequestHandler" ``` - 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. - 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.."). - `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` 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?"). 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`. - The client then sends a second message, including the `taskId` and `contextId` from the first turn's `Task` response, to provide the missing information ("in GBP"). This continues the same task. ## Exploring the Code Take some time to look through these files: - `__main__.py`: Server setup using `A2AStarletteApplication` and `DefaultRequestHandler`. Note the `AgentCard` definition includes `capabilities.streaming=True`. - `agent.py`: The `CurrencyAgent` with LangGraph, LLM model, and tool definitions. - `agent_executor.py`: The `CurrencyAgentExecutor` implementing the `execute` (and `cancel`) method. It uses the `RequestContext` to understand the ongoing task and the `EventQueue` to send back various events (`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`, new `Task` object implicitly via the first event if no task exists). - `test_client.py`: Demonstrates various interaction patterns, including retrieving task IDs and using them for multi-turn conversations. This example provides a much richer illustration of how A2A facilitates complex, stateful, and asynchronous interactions between agents. ================================================ FILE: docs/tutorials/python/8-next-steps.md ================================================ # Next Steps Congratulations on completing the A2A Python SDK Tutorial! You've learned how to: - Set up your environment for A2A development. - Define Agent Skills and Agent Cards using the SDK's types. - Implement a basic HelloWorld A2A server and client. - Understand and implement streaming capabilities. - Integrate a more complex agent using LangGraph, demonstrating task state management and tool use. You now have a solid foundation for building and integrating your own A2A-compliant agents. ## Where to Go From Here? Here are some ideas and resources to continue your A2A journey: - **Explore Other Examples:** - Check out the other examples in the [a2a-samples GitHub repository](https://github.com/a2aproject/a2a-samples/tree/main/samples) for more complex agent integrations and features. - **Deepen Your Protocol Understanding:** - 📚 Read the complete [A2A Protocol Documentation site](https://a2a-protocol.org) for a comprehensive overview. - 📝 Review the detailed [A2A Protocol Specification](../../specification.md) to understand the nuances of all data structures and RPC methods. - **Review Key A2A Topics:** - [A2A and MCP](../../topics/a2a-and-mcp.md): Understand how A2A complements the Model Context Protocol for tool usage. - [Enterprise-Ready Features](../../topics/enterprise-ready.md): Learn about security, observability, and other enterprise considerations. - [Streaming & Asynchronous Operations](../../topics/streaming-and-async.md): Get more details on SSE and push notifications. - [Agent Discovery](../../topics/agent-discovery.md): Explore different ways agents can find each other. - **Build Your Own Agent:** - Try creating a new A2A agent using your favorite Python agent framework (like LangChain, CrewAI, AutoGen, Semantic Kernel, or a custom solution). - Implement the `a2a.server.AgentExecutor` interface to bridge your agent's logic with the A2A protocol. - Think about what unique skills your agent could offer and how its Agent Card would represent them. - **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 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). - Consider contributing code, examples, or documentation. See the [CONTRIBUTING.md](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md) guide. The A2A protocol aims to foster an ecosystem of interoperable AI agents. By building and sharing A2A-compliant agents, you can be a part of this exciting development! ================================================ FILE: docs/whats-new-v1.md ================================================ # 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. ================================================ FILE: lychee.toml ================================================ exclude = [ 'https://fonts.gstatic.com/', 'https://fonts.googleapis.com/', 'https://medium.com/', 'https://x.com/', 'http://localhost:12000/', 'http://localhost:10020/', 'https://goo.gle/', ] exclude_path = [ ".github/actions/spelling", "CHANGELOG.md", "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] max_retries = 0 skip_missing = true ================================================ FILE: mkdocs.yml ================================================ # Project information site_name: A2A Protocol site_url: https://a2a-protocol.org/ site_description: >- The official documentation for the Agent2Agent (A2A) protocol. The A2A protocol is an open standard that allows different AI agents to securely communicate, collaborate, and solve complex problems together. site_author: The Linux Foundation site_dir: site edit_uri: edit/main/docs/ # Exclude files from the docs directory exclude_docs: | README.md extra: a2a_version: !ENV [MIKE_VERSION, "dev"] analytics: provider: google property: G-RB39M83WHB # Navigation nav: - Home: index.md - 🆕 Announcing Version 1.0: announcing-1.0.md - Documentation: - 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 - 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 - 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 - Community: community.md - Partners: partners.md - Roadmap: roadmap.md # Repository repo_name: a2aproject/A2A repo_url: https://github.com/a2aproject/A2A # Copyright copyright: Copyright 2026 The Linux Foundation. Licensed under the Apache License, Version 2.0. # Custom CSS extra_css: - stylesheets/custom.css # Configuration theme: name: material custom_dir: .mkdocs/overrides font: text: Google Sans code: Roboto Mono logo: assets/a2a-logo-white.svg favicon: assets/a2a-logo-black.svg icon: repo: fontawesome/brands/github view: material/pencil-box-multiple admonition: note: fontawesome/solid/note-sticky abstract: fontawesome/solid/book info: fontawesome/solid/circle-info tip: fontawesome/solid/bullhorn success: fontawesome/solid/check question: fontawesome/solid/circle-question warning: fontawesome/solid/triangle-exclamation failure: fontawesome/solid/bomb danger: fontawesome/solid/skull bug: fontawesome/solid/robot example: fontawesome/solid/flask quote: fontawesome/solid/quote-left palette: - scheme: default primary: indigo accent: white features: - announce.dismiss - content.action.view - content.code.annotate - content.code.copy - content.code.select - content.tabs.link - navigation.footer - navigation.indexes - navigation.instant - navigation.instant.progress - navigation.path - navigation.top - navigation.tracking - toc.follow - versioning: provider: mike # Extensions markdown_extensions: - meta - footnotes - admonition - attr_list - md_in_html - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true - pymdownx.inlinehilite - pymdownx.snippets: base_path: . url_download: true dedent_subsections: true - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower - toc: permalink: true # Plugins plugins: - search - macros: module_name: .mkdocs/macros - redirects: redirect_maps: "specification/overview.md": "specification.md" "specification/agent-card.md": "specification.md#5-agent-discovery-the-agent-card" "specification/agent-to-agent-communication.md": "specification.md#6-protocol-data-objects" "specification/sample-messages.md": "specification.md#9-common-workflows-examples" "specification/details.md": "specification.md" "documentation.md": "topics/key-concepts.md" "resources.md": "index.md" "topics/push-notifications.md": "topics/streaming-and-async.md" "specification/topics/a2a_and_mcp.md": "topics/a2a-and-mcp.md" "specification/topics/agent_discovery.md": "topics/agent-discovery.md" "specification/topics/enterprise_ready.md": "topics/enterprise-ready.md" "specification/topics/push_notification.md": "topics/streaming-and-async.md" "specification/topics/push_notifications.md": "topics/streaming-and-async.md" "topics/index.md": "topics/what-is-a2a.md" "topics/roadmap.md": "roadmap.md" # Tutorial "tutorials/python/index.md": "tutorials/python/1-introduction.md" "tutorials/python/1_introduction.md": "tutorials/python/1-introduction.md" "tutorials/python/3-create-project.md": "tutorials/python/2-setup.md" "tutorials/python/4-agent-skills.md": "tutorials/python/3-agent-skills-and-card.md" "tutorials/python/5-add-agent-card.md": "tutorials/python/3-agent-skills-and-card.md" "tutorials/python/6-start-server.md": "tutorials/python/5-start-server.md" "tutorials/python/7-interact-with-server.md": "tutorials/python/6-interact-with-server.md" "tutorials/python/8-agent-capabilities.md": "tutorials/python/7-streaming-and-multiturn.md" "tutorials/python/9-ollama-agent.md": "tutorials/python/7-streaming-and-multiturn.md" "tutorials/python/10-next-steps.md": "tutorials/python/8-next-steps.md" - mike: canonical_version: latest ================================================ FILE: requirements-docs.txt ================================================ mkdocs-material mkdocs-redirects a2a-sdk[all] mike mkdocs-macros-plugin sphinx furo myst-parser proto-schema-parser tabulate ================================================ FILE: scripts/build_docs.sh ================================================ #!/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 ================================================ FILE: scripts/build_llms_full.sh ================================================ #!/bin/bash set -e # This script concatenates all documentation and specification files # into a single file for LLM consumption. # --- Configuration --- OUTPUT_FILE="docs/llms-full.txt" DOCS_DIR="docs" SPEC_DIR="specification" SDK_DOCS_SCRIPT="scripts/build_sdk_docs.sh" PROJECT_NAME="A2A (Agent2Agent) Protocol" echo "--- Generating consolidated LLM file: ${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 # Clear the output file and add introduction cat <"${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 "" cat "$file_path" echo "" echo } >>"${OUTPUT_FILE}" else echo "Warning: File not found, skipping: $file_path" >&2 fi } # --- 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 { 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}" ================================================ FILE: scripts/build_sdk_docs.sh ================================================ #!/bin/bash set -e # Exit immediately if a command exits with a non-zero status. # --- Configuration --- PACKAGE_NAME="a2a" # The name of the package to import PYPI_PACKAGE_NAME="a2a-sdk" # The name on PyPI DOCS_SOURCE_DIR="docs/sdk/python" DOCS_BUILD_DIR="${DOCS_SOURCE_DIR}/_build" VENV_DIR=".doc-venv" echo "--- Setting up documentation build environment ---" # Create a clean virtual environment if [ -d "$VENV_DIR" ]; then rm -rf "$VENV_DIR" fi uv venv "$VENV_DIR" source "$VENV_DIR/bin/activate" echo "--- Installing package and dependencies ---" # Install documentation requirements uv pip install -r "requirements-docs.txt" # Install the package itself uv pip install "${PYPI_PACKAGE_NAME}" echo "--- Finding installed package path ---" # Find the installation path of the package PACKAGE_PATH=$(python -c "import ${PACKAGE_NAME}, os; print(os.path.dirname(${PACKAGE_NAME}.__file__))") echo "Found '${PACKAGE_NAME}' at: ${PACKAGE_PATH}" echo "--- Generating API documentation source files (.rst) ---" # Run sphinx-apidoc on the installed package directory # -f: force overwrite of existing files # -e: put each module on its own page sphinx-apidoc -f -e -o "${DOCS_SOURCE_DIR}" "${PACKAGE_PATH}" 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: ${SDK_API_DIR}/index.html" ================================================ FILE: scripts/deploy_root_files.sh ================================================ #!/bin/bash # Exit immediately if a command exits with a non-zero status. set -e # This script deploys a list of specified files (e.g., 404.html, robots.txt) # to the root of the gh-pages branch. # It's designed to be called from a GitHub Actions workflow. # # Arguments: # $1: The GitHub repository name (e.g., "a2aproject/A2A"). # $2: The GITHUB_TOKEN for authentication. # --- Configuration --- # List of files to copy from the source directory to the root of the gh-pages branch. FILES_TO_DEPLOY=("404.html" "robots.txt" "llms.txt", "llms-full.txt") # The source directory in the main branch where these files are located. SOURCE_DIR="docs" # --- Validate Input --- if [ -z "$1" ] || [ -z "$2" ]; then echo "Error: Missing required arguments." echo "Usage: $0 " exit 1 fi REPO_NAME=$1 GH_TOKEN=$2 echo "Deploying root-level site files for repository: $REPO_NAME" echo "Files to deploy: ${FILES_TO_DEPLOY[*]}" # --- Deployment Logic --- # Clone the gh-pages branch using the provided token for authentication. # This ensures we have push access. git clone --branch=gh-pages --single-branch --depth=1 "https://x-access-token:${GH_TOKEN}@github.com/${REPO_NAME}.git" gh-pages-deploy # Navigate into the cloned directory cd gh-pages-deploy # Loop through the files, copy them from the source checkout, and add them to git. # The source checkout is in the parent directory (`../`). for file in "${FILES_TO_DEPLOY[@]}"; do SOURCE_FILE="../${SOURCE_DIR}/${file}" if [ -f "$SOURCE_FILE" ]; then echo "Copying $file..." cp "$SOURCE_FILE" "./$file" git add "$file" else echo "Warning: Source file not found, skipping: $SOURCE_FILE" fi done # Commit and push only if any of the files have actually changed if git diff --staged --quiet; then echo "Root files are up-to-date. No new commit needed." else echo "Committing and pushing updated root files..." # Configure git user for commit git config user.name "GitHub Actions" git config user.email "github-actions@github.com" git commit -m "docs: Deploy root-level site files" git push fi # Go back to the original directory and clean up cd .. rm -rf gh-pages-deploy echo "Root file deployment complete." ================================================ FILE: scripts/format.sh ================================================ #!/bin/bash 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) bash "${SCRIPT_DIR}/sort_spelling.sh" # Define file and directory paths. MARKDOWN_DIR="${REPO_ROOT}/docs/" MARKDOWNLINT_CONFIG="${REPO_ROOT}/.github/linters/.markdownlint.json" # Install markdownlint-cli if the command doesn't already exist. if ! command -v markdownlint &>/dev/null; then echo "Installing markdownlint-cli..." npm install -g markdownlint-cli fi # Run markdownlint to format files. echo "Formatting markdown files..." # Check for the existence of the directory and config file before running. [ -d "${MARKDOWN_DIR}" ] || { echo "ERROR: Markdown directory not found: ${MARKDOWN_DIR}" exit 1 } [ -f "${MARKDOWNLINT_CONFIG}" ] || { echo "ERROR: Markdownlint config not found: ${MARKDOWNLINT_CONFIG}" exit 1 } markdownlint "${MARKDOWN_DIR}" --config "${MARKDOWNLINT_CONFIG}" --fix echo "Script finished successfully." ================================================ FILE: scripts/lint.sh ================================================ #!/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 ================================================ FILE: scripts/proto_to_json_schema.sh ================================================ #!/bin/bash set -euo pipefail # Convert proto files to JSON Schema in a single operation. # Usage: proto_to_json_schema.sh OUTPUT=${1:-} if [[ -z "$OUTPUT" ]]; then echo "Usage: $0 " >&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 ================================================ FILE: scripts/sort_spelling.sh ================================================ #!/bin/bash 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) ALLOW_FILE="${REPO_ROOT}/.github/actions/spelling/allow.txt" echo "Sorting spelling allow list..." [ -f "${ALLOW_FILE}" ] || { echo "ERROR: Allow list not found: ${ALLOW_FILE}" exit 1 } LC_ALL=C sort -u -o "${ALLOW_FILE}" "${ALLOW_FILE}" ================================================ FILE: specification/.api-linter.yaml ================================================ # 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" ================================================ FILE: specification/a2a.proto ================================================ // 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 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 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 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 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 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 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 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; } ================================================ FILE: specification/buf.gen.yaml ================================================ # buf generate # Configuration for the buf generate command # Uses remote plugins, no separate install required. # This config generates python, go and java (protobuf) source. version: v2 plugins: # Python - remote: buf.build/protocolbuffers/python:v29.3 out: src/python - remote: buf.build/grpc/python out: src/python # Go - remote: buf.build/protocolbuffers/go out: src/go - remote: buf.build/grpc/go out: src/go # Java - remote: buf.build/protocolbuffers/java out: src/java - remote: buf.build/grpc/java out: src/java # TypeScript - remote: buf.build/community/stephenh-ts-proto:v1.165.0 out: src/typescript ================================================ FILE: specification/buf.yaml ================================================ version: v2 deps: # Common Protobuf types. - buf.build/googleapis/googleapis lint: use: # 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 - RPC_REQUEST_STANDARD_NAME - RPC_RESPONSE_STANDARD_NAME breaking: use: # Indicates that breaking change detection should be done on a file level. # See https://buf.build/docs/breaking/rules for more details. - FILE ================================================ FILE: specification/json/README.md ================================================ # A2A JSON Artifact `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. 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.
macOS/Linux ### 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.
Windows #### 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
#### 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.