├── .editorconfig ├── .git-blame-ignore-revs ├── .gitattributes ├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── bug-report.yml │ └── feature-request.yml ├── PULL_REQUEST_TEMPLATE.md ├── actions │ └── spelling │ │ ├── advice.md │ │ ├── allow.txt │ │ ├── excludes.txt │ │ └── line_forbidden.patterns ├── conventional-commit-lint.yaml ├── linters │ ├── .eslintrc.js │ ├── .jscpd.json │ ├── .markdownlint.json │ └── .stylelintrc.json └── workflows │ ├── check-linked-issues.yml │ ├── conventional-commits.yml │ ├── dispatch-a2a-update.yml │ ├── docs.yml │ ├── generate-a2a-json.yml │ ├── issue-metrics.yml │ ├── links.yaml │ ├── linter.yaml │ ├── release-please.yml │ ├── sort-spelling-allowlist.yml │ ├── spelling.yaml │ └── stale.yaml ├── .gitignore ├── .mkdocs └── overrides │ └── main.html ├── .prettierrc ├── .ruff.toml ├── .vscode └── settings.json ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── GOVERNANCE.md ├── LICENSE ├── README.md ├── SECURITY.md ├── docs ├── 404.html ├── README.md ├── assets │ ├── a2a-actors.png │ ├── a2a-banner.png │ ├── a2a-logo-black.svg │ ├── a2a-logo-white.svg │ ├── a2a-main.png │ ├── a2a-mcp-readme.png │ ├── a2a-mcp.png │ ├── adk.svg │ ├── ag2-black.svg │ └── langgraph-color.svg ├── community.md ├── index.md ├── llms.txt ├── partners.md ├── roadmap.md ├── sdk │ └── python │ │ ├── conf.py │ │ └── index.rst ├── 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 │ └── 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 ├── lychee.toml ├── mkdocs.yml ├── requirements-docs.txt ├── scripts ├── build_sdk_docs.sh ├── deploy-404.sh ├── format.sh └── sort_spelling.sh ├── specification ├── grpc │ ├── README.md │ ├── a2a.proto │ ├── buf.gen.yaml │ ├── buf.lock │ └── buf.yaml └── json │ ├── README.md │ └── a2a.json └── types ├── .gitignore ├── README.md ├── package-lock.json ├── package.json ├── src └── types.ts └── tsconfig.json /.editorconfig: -------------------------------------------------------------------------------- 1 | # editorconfig.org 2 | root = true 3 | 4 | [*] 5 | end_of_line = lf 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | 10 | [*.sh] 11 | indent_style = space 12 | indent_size = 2 13 | -------------------------------------------------------------------------------- /.git-blame-ignore-revs: -------------------------------------------------------------------------------- 1 | # Template taken from https://github.com/v8/v8/blob/master/.git-blame-ignore-revs. 2 | # 3 | # This file contains a list of git hashes of revisions to be ignored by git blame. These 4 | # revisions are considered "unimportant" in that they are unlikely to be what you are 5 | # interested in when blaming. Most of these will probably be commits related to linting 6 | # and code formatting. 7 | # 8 | # Instructions: 9 | # - Only large (generally automated) reformatting or renaming CLs should be 10 | # added to this list. Do not put things here just because you feel they are 11 | # trivial or unimportant. If in doubt, do not put it on this list. 12 | # - Precede each revision with a comment containing the PR title and number. 13 | # For bulk work over many commits, place all commits in a block with a single 14 | # comment at the top describing the work done in those commits. 15 | # - Only put full 40-character hashes on this list (not short hashes or any 16 | # other revision reference). 17 | # - Append to the bottom of the file (revisions should be in chronological order 18 | # from oldest to newest). 19 | # - Because you must use a hash, you need to append to this list in a follow-up 20 | # PR to the actual reformatting PR that you are trying to ignore. 21 | 0f8d9750bcb17f6b8b9f48793b46f7b8510cae24 22 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Documentation overrides 2 | /docs/** linguist-documentation=true 3 | /.mkdocs/** linguist-documentation=true 4 | /specification/json/a2a.json linguist-generated=true 5 | noxfile.py linguist-vendored=true 6 | 7 | # Merge and diff setting 8 | CHANGELOG.md merge=union 9 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Code owners file. 2 | # This file controls who is tagged for review for any given pull request. 3 | # 4 | # For syntax help see: 5 | # https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax 6 | 7 | * @a2aproject/google-a2a-eng 8 | docs/ @a2aproject/tech-writing 9 | *.md @a2aproject/tech-writing 10 | .mkdocs/ @a2aproject/tech-writing 11 | .mkdocs.yml @a2aproject/tech-writing 12 | README.md @a2aproject/tech-writing 13 | requirements-docs.txt @a2aproject/tech-writing 14 | specification/ @a2aproject/a2a-tsc 15 | types/ @a2aproject/a2a-tsc 16 | docs/specification.md @a2aproject/a2a-tsc 17 | GOVERNANCE.md @a2aproject/a2a-tsc 18 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug-report.yml: -------------------------------------------------------------------------------- 1 | name: 🐞 Bug Report 2 | description: File a bug report 3 | title: "[Bug]: " 4 | type: "Bug" 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: | 9 | Thanks for stopping by to let us know something could be better! 10 | Private Feedback? Please use this [Google form](https://goo.gle/a2a-feedback) 11 | - type: textarea 12 | id: what-happened 13 | attributes: 14 | label: What happened? 15 | description: Also tell us what you expected to happen and how to reproduce the issue. 16 | placeholder: Tell us what you see! 17 | value: "A bug happened!" 18 | validations: 19 | required: true 20 | - type: textarea 21 | id: logs 22 | attributes: 23 | label: Relevant log output 24 | description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. 25 | render: shell 26 | - type: checkboxes 27 | id: terms 28 | attributes: 29 | label: Code of Conduct 30 | description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/a2aproject/A2A?tab=coc-ov-file#readme) 31 | options: 32 | - label: I agree to follow this project's Code of Conduct 33 | required: true 34 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request.yml: -------------------------------------------------------------------------------- 1 | name: 💡 Feature Request 2 | description: Suggest an idea for this repository 3 | title: "[Feat]: " 4 | type: "Feature" 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: | 9 | Thanks for stopping by to let us know something could be better! 10 | Private Feedback? Please use this [Google form](https://goo.gle/a2a-feedback) 11 | - type: textarea 12 | id: problem 13 | attributes: 14 | label: Is your feature request related to a problem? Please describe. 15 | description: A clear and concise description of what the problem is. 16 | placeholder: Ex. I'm always frustrated when [...] 17 | - type: textarea 18 | id: describe 19 | attributes: 20 | label: Describe the solution you'd like 21 | description: A clear and concise description of what you want to happen. 22 | validations: 23 | required: true 24 | - type: textarea 25 | id: alternatives 26 | attributes: 27 | label: Describe alternatives you've considered 28 | description: A clear and concise description of any alternative solutions or features you've considered. 29 | - type: textarea 30 | id: context 31 | attributes: 32 | label: Additional context 33 | description: Add any other context or screenshots about the feature request here. 34 | - type: checkboxes 35 | id: terms 36 | attributes: 37 | label: Code of Conduct 38 | description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/a2aproject/A2A?tab=coc-ov-file#readme) 39 | options: 40 | - label: I agree to follow this project's Code of Conduct 41 | required: true 42 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Description 2 | 3 | Thank you for opening a Pull Request! 4 | Before submitting your PR, there are a few things you can do to make sure it goes smoothly: 5 | 6 | - [ ] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md). 7 | - [ ] Make your Pull Request title in the specification. 8 | - [ ] Ensure the tests and linter pass (Run `nox -s format` from the repository root to format) 9 | - [ ] Appropriate docs were updated (if necessary) 10 | 11 | Fixes # 🦕 12 | -------------------------------------------------------------------------------- /.github/actions/spelling/advice.md: -------------------------------------------------------------------------------- 1 | 2 |
If the flagged items are :exploding_head: false positives 3 | 4 | If items relate to a ... 5 | 6 | - binary file (or some other file you wouldn't want to check at all). 7 | 8 | Please add a file path to the `excludes.txt` file matching the containing file. 9 | 10 | 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. 11 | 12 | `^` 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). 13 | 14 | - well-formed pattern. 15 | 16 | If you can write a [pattern](https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-patterns) that would match it, 17 | try adding it to the `patterns.txt` file. 18 | 19 | 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. 20 | 21 | Note that patterns can't match multiline strings. 22 | 23 |
24 | 25 | 26 | 27 | :steam_locomotive: If you're seeing this message and your PR is from a branch that doesn't have check-spelling, 28 | please merge to your PR's base branch to get the version configured for your repository. 29 | -------------------------------------------------------------------------------- /.github/actions/spelling/allow.txt: -------------------------------------------------------------------------------- 1 | AAAANSUh 2 | AAAAUA 3 | AAAGHMHc 4 | ACMRTUXB 5 | ACard 6 | AClient 7 | ACo 8 | ADK 9 | AError 10 | AIP 11 | ARequest 12 | ASED 13 | ASGI 14 | AServer 15 | AService 16 | AStarlette 17 | Autogen 18 | Blogs 19 | CAs 20 | CLIs 21 | Camry 22 | Cjava 23 | Cpzuhi 24 | DDo 25 | DGT 26 | DHDe 27 | Djq 28 | Dotnet 29 | EBFF 30 | EUR 31 | EUg 32 | FBT 33 | FHIR 34 | Fbr 35 | GAPI 36 | GAPIC 37 | GBP 38 | GVsb 39 | Gapic 40 | Gci 41 | Genkit 42 | Ghw 43 | HBz 44 | HKRMw 45 | HXo 46 | Hackathon 47 | IFdvcmxk 48 | IMPCUk 49 | INR 50 | Ikp 51 | Imh 52 | Imprd 53 | JFUz 54 | JHv 55 | JPY 56 | JWKS 57 | JWS 58 | JWTs 59 | Jhb 60 | Jra 61 | KGgo 62 | KRW 63 | LHR 64 | LJcvt 65 | LLM 66 | LLMs 67 | Lix 68 | MSIs 69 | MWpm 70 | Mapr 71 | Nszl 72 | OIDC 73 | OOa 74 | Ollama 75 | PLE 76 | PLW 77 | PMEEi 78 | PTH 79 | QFdk 80 | Qvandrcy 81 | RPCs 82 | RUF 83 | SLAs 84 | SLF 85 | Solax 86 | TJS 87 | TMDB 88 | Tful 89 | URLTo 90 | Upserting 91 | Urke 92 | VBORw 93 | Vsb 94 | WHB 95 | WQi 96 | WVw 97 | Witteveen 98 | XBs 99 | Xca 100 | YQGt 101 | YTAKFW 102 | YTT 103 | YWFh 104 | YWdlbn 105 | ZDS 106 | ZKHv 107 | ZXhhb 108 | ZXkt 109 | Zipkin 110 | Zms 111 | aab 112 | aacacac 113 | aboutasha 114 | achat 115 | aconnect 116 | adk 117 | agentcard 118 | agentic 119 | agentskill 120 | ainvoke 121 | aldridge 122 | amannn 123 | aparse 124 | aproject 125 | aprotocol 126 | arxiv 127 | askmarvin 128 | asyncclick 129 | autogen 130 | automodule 131 | autouse 132 | backstory 133 | backticks 134 | bbb 135 | bufbuild 136 | bzr 137 | cae 138 | ccc 139 | cdn 140 | ceee 141 | cfe 142 | cls 143 | coc 144 | codegen 145 | codeowner 146 | crewai 147 | datamodel 148 | datapart 149 | dbc 150 | dcda 151 | dcfa 152 | dde 153 | direnv 154 | docstrings 155 | documentai 156 | dotnet 157 | efaab 158 | efbd 159 | embeddings 160 | endblock 161 | envoyproxy 162 | euo 163 | evt 164 | excinfo 165 | faa 166 | fafd 167 | ffbb 168 | firewalls 169 | flightbook 170 | forbes 171 | fsv 172 | fyi 173 | gapic 174 | gcp 175 | genai 176 | geneknit 177 | genkit 178 | genproto 179 | georoute 180 | gettickets 181 | gle 182 | googleai 183 | googleapi 184 | googleblog 185 | gpt 186 | gstatic 187 | gweb 188 | hqdefault 189 | hughesthe 190 | iat 191 | ietf 192 | inbox 193 | inmemory 194 | iss 195 | jherr 196 | jti 197 | jwks 198 | konami 199 | kty 200 | langgraph 201 | linenums 202 | linkedin 203 | linting 204 | llm 205 | llms 206 | lng 207 | marvin 208 | mcp 209 | mesop 210 | mindsdb 211 | motherlode 212 | mozilla 213 | msword 214 | multiagent 215 | multipage 216 | myorg 217 | nearform 218 | nlp 219 | notif 220 | npush 221 | objc 222 | octicons 223 | oidc 224 | ollama 225 | oneof 226 | oreilly 227 | pqr 228 | prefecthq 229 | protoc 230 | protolint 231 | pyguide 232 | pymdownx 233 | pypackages 234 | pytype 235 | pyupgrade 236 | qwq 237 | rcm 238 | repomapr 239 | reportgen 240 | reposted 241 | rst 242 | rvelicheti 243 | sllm 244 | squidfunk 245 | srcs 246 | sse 247 | stateclass 248 | stephenh 249 | styleguide 250 | svn 251 | systemctl 252 | tagwords 253 | taskssend 254 | taskstate 255 | taskstatus 256 | textpart 257 | threadsafe 258 | toctree 259 | tok 260 | tracestate 261 | ugc 262 | undoc 263 | utm 264 | versioned 265 | vnd 266 | voa 267 | vscode 268 | weavehacks 269 | webpage 270 | whatwg 271 | wikipedia 272 | wsgi 273 | wwwwwwww 274 | xxxxx 275 | xxxxxxxx 276 | youtube 277 | yyyyyyyy 278 | zzzzzzzz 279 | -------------------------------------------------------------------------------- /.github/actions/spelling/excludes.txt: -------------------------------------------------------------------------------- 1 | # See https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-excludes 2 | (?:^|/)(?i)COPYRIGHT 3 | (?:^|/)(?i)LICEN[CS]E 4 | (?:^|/)(?i)CODE_OF_CONDUCT.md\E$ 5 | (?:^|/)(?i).gitignore\E$ 6 | (?:^|/)3rdparty/ 7 | (?:^|/)go\.sum$ 8 | (?:^|/)package(?:-lock|)\.json$ 9 | (?:^|/)Pipfile$ 10 | (?:^|/)pyproject.toml 11 | (?:^|/)requirements(?:-dev|-doc|-test|)\.txt$ 12 | (?:^|/)vendor/ 13 | /CODEOWNERS$ 14 | \.a$ 15 | \.ai$ 16 | \.all-contributorsrc$ 17 | \.avi$ 18 | \.bmp$ 19 | \.bz2$ 20 | \.cer$ 21 | \.class$ 22 | \.coveragerc$ 23 | \.crl$ 24 | \.crt$ 25 | \.csr$ 26 | \.dll$ 27 | \.docx?$ 28 | \.drawio$ 29 | \.DS_Store$ 30 | \.eot$ 31 | \.eps$ 32 | \.exe$ 33 | \.gif$ 34 | \.git-blame-ignore-revs$ 35 | \.gitattributes$ 36 | \.gitkeep$ 37 | \.graffle$ 38 | \.gz$ 39 | \.icns$ 40 | \.ico$ 41 | \.jar$ 42 | \.jks$ 43 | \.jpe?g$ 44 | \.key$ 45 | \.lib$ 46 | \.lock$ 47 | \.map$ 48 | \.min\.. 49 | \.mo$ 50 | \.mod$ 51 | \.mp[34]$ 52 | \.o$ 53 | \.ocf$ 54 | \.otf$ 55 | \.p12$ 56 | \.parquet$ 57 | \.pdf$ 58 | \.pem$ 59 | \.pfx$ 60 | \.png$ 61 | \.psd$ 62 | \.pyc$ 63 | \.pylintrc$ 64 | \.qm$ 65 | \.s$ 66 | \.sig$ 67 | \.so$ 68 | \.svgz?$ 69 | \.sys$ 70 | \.tar$ 71 | \.tgz$ 72 | \.tiff?$ 73 | \.ttf$ 74 | \.wav$ 75 | \.webm$ 76 | \.webp$ 77 | \.woff2?$ 78 | \.xcf$ 79 | \.xlsx?$ 80 | \.xpm$ 81 | \.xz$ 82 | \.zip$ 83 | ^\.github/actions/spelling/ 84 | ^\Q.github/workflows/spelling.yaml\E$ 85 | ^\Q.github/workflows/linter.yaml\E$ 86 | ^\Qlychee.toml\E$ 87 | \.vscode/ 88 | ^\Qdocs/partners.md\E$ 89 | ^\Qspecification/json/a2a.json\E$ 90 | CHANGELOG.md 91 | \.gitignore 92 | ^\Qdocs/robots.txt\E$ 93 | CODE_OF_CONDUCT.md 94 | -------------------------------------------------------------------------------- /.github/actions/spelling/line_forbidden.patterns: -------------------------------------------------------------------------------- 1 | # Should be `HH:MM:SS` 2 | \bHH:SS:MM\b 3 | 4 | # Should probably be `YYYYMMDD` 5 | \b[Yy]{4}[Dd]{2}[Mm]{2}(?!.*[Yy]{4}[Dd]{2}[Mm]{2}).*$ 6 | 7 | # Should be `anymore` 8 | \bany more[,.] 9 | 10 | # Should be `cannot` (or `can't`) 11 | # See https://www.grammarly.com/blog/cannot-or-can-not/ 12 | # > 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`. 13 | # > `Can't` is a contraction of `cannot`, and it's best suited for informal writing. 14 | # > In formal writing and where contractions are frowned upon, use `cannot`. 15 | # > 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.` 16 | # - if you encounter such a case, add a pattern for that case to patterns.txt. 17 | \b[Cc]an not\b 18 | 19 | # Should be `GitHub` 20 | (?> "$GITHUB_OUTPUT" 53 | echo "a2a.json is not up-to-date with types.ts" 54 | else 55 | echo "a2a.json is up-to-date." 56 | fi 57 | 58 | - name: Commit and Push Changes (if on base repository) 59 | if: steps.git_status.outputs.changes_detected == 'true' && github.event.pull_request.head.repo.full_name == github.repository 60 | run: | 61 | git commit -m "chore: Auto-generate a2a.json from types.ts changes" 62 | git push 63 | 64 | - name: Fail on Fork PR if Changes Required 65 | if: steps.git_status.outputs.changes_detected == 'true' && github.event.pull_request.head.repo.full_name != github.repository 66 | run: | 67 | echo "::error::a2a.json is out of date." 68 | echo "Please run 'npm install' then 'npm run generate' in the 'types' directory of your branch and commit the updated 'specification/json/a2a.json' file." 69 | exit 1 # Exit with a non-zero code to fail the workflow 70 | -------------------------------------------------------------------------------- /.github/workflows/issue-metrics.yml: -------------------------------------------------------------------------------- 1 | name: Monthly issue metrics 2 | on: 3 | workflow_dispatch: 4 | schedule: 5 | - cron: "3 2 1 * *" 6 | 7 | permissions: 8 | contents: read 9 | 10 | jobs: 11 | build: 12 | name: issue metrics 13 | runs-on: ubuntu-latest 14 | permissions: 15 | issues: write 16 | pull-requests: read 17 | steps: 18 | - name: Get dates for last month 19 | shell: bash 20 | run: | 21 | # Calculate the first day of the previous month 22 | first_day=$(date -d "last month" +%Y-%m-01) 23 | 24 | # Calculate the last day of the previous month 25 | last_day=$(date -d "$first_day +1 month -1 day" +%Y-%m-%d) 26 | 27 | # Set an environment variable with the date range 28 | echo "$first_day..$last_day" 29 | echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV" 30 | 31 | - name: Run issue-metrics tool 32 | uses: github/issue-metrics@v3 33 | env: 34 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 35 | SEARCH_QUERY: 'repo:a2aproject/A2A is:issue created:${{ env.last_month }} -reason:"not planned"' 36 | 37 | - name: Create issue 38 | uses: peter-evans/create-issue-from-file@v5 39 | with: 40 | title: Monthly issue metrics report 41 | token: ${{ secrets.GITHUB_TOKEN }} 42 | content-filepath: ./issue_metrics.md 43 | -------------------------------------------------------------------------------- /.github/workflows/links.yaml: -------------------------------------------------------------------------------- 1 | name: Links 2 | 3 | on: 4 | repository_dispatch: 5 | workflow_dispatch: 6 | schedule: 7 | - cron: "00 18 * * *" 8 | 9 | jobs: 10 | linkChecker: 11 | runs-on: ubuntu-latest 12 | if: | 13 | github.repository == 'a2aproject/A2A' 14 | 15 | steps: 16 | - uses: actions/checkout@v4 17 | 18 | - name: Link Checker 19 | id: lychee 20 | uses: lycheeverse/lychee-action@v2 21 | 22 | - name: Create Issue From File 23 | if: env.lychee_exit_code != 0 24 | uses: peter-evans/create-issue-from-file@v5 25 | with: 26 | title: Link Checker Report 27 | content-filepath: ./lychee/out.md 28 | labels: report, automated issue 29 | -------------------------------------------------------------------------------- /.github/workflows/linter.yaml: -------------------------------------------------------------------------------- 1 | name: Lint Code Base 2 | 3 | on: 4 | pull_request: 5 | branches: [main] 6 | 7 | jobs: 8 | build: 9 | name: Lint Code Base 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - name: Checkout Code 14 | uses: actions/checkout@v4 15 | with: 16 | fetch-depth: 0 17 | 18 | - name: Lint Code Base 19 | uses: super-linter/super-linter/slim@v8 20 | env: 21 | DEFAULT_BRANCH: main 22 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 23 | LOG_LEVEL: WARN 24 | SHELLCHECK_OPTS: -e SC1091 -e 2086 25 | VALIDATE_ALL_CODEBASE: false 26 | FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|\\.mkdocs/overrides/.*|docs/404.html" 27 | VALIDATE_PYTHON_BLACK: false 28 | VALIDATE_PYTHON_FLAKE8: false 29 | VALIDATE_PYTHON_ISORT: false 30 | VALIDATE_PYTHON_MYPY: false 31 | VALIDATE_PYTHON_PYLINT: false 32 | VALIDATE_CHECKOV: false 33 | VALIDATE_NATURAL_LANGUAGE: false 34 | MARKDOWN_CONFIG_FILE: ".markdownlint.json" 35 | VALIDATE_MARKDOWN_PRETTIER: false 36 | TYPESCRIPT_ES_CONFIG_FILE: ".eslintrc.js" 37 | VALIDATE_JAVASCRIPT_PRETTIER: false 38 | VALIDATE_JSON_PRETTIER: false 39 | VALIDATE_YAML_PRETTIER: false 40 | VALIDATE_GIT_COMMITLINT: false 41 | -------------------------------------------------------------------------------- /.github/workflows/release-please.yml: -------------------------------------------------------------------------------- 1 | on: 2 | push: 3 | branches: 4 | - main 5 | 6 | permissions: 7 | contents: write 8 | pull-requests: write 9 | 10 | name: release-please 11 | 12 | jobs: 13 | release-please: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: googleapis/release-please-action@v4 17 | with: 18 | token: ${{ secrets.A2A_BOT_PAT }} 19 | release-type: simple 20 | -------------------------------------------------------------------------------- /.github/workflows/sort-spelling-allowlist.yml: -------------------------------------------------------------------------------- 1 | name: Auto-sort and update spelling allowlist 2 | 3 | on: 4 | pull_request: 5 | paths: 6 | - ".github/actions/spelling/allow.txt" 7 | types: 8 | - opened 9 | - synchronize 10 | - reopened 11 | 12 | jobs: 13 | sort_and_commit: 14 | name: Sort and Commit Allowlist 15 | runs-on: ubuntu-latest 16 | permissions: 17 | contents: write 18 | 19 | steps: 20 | - name: Checkout Code 21 | uses: actions/checkout@v4 22 | with: 23 | repository: ${{ github.event.pull_request.head.repo.full_name }} 24 | ref: ${{ github.event.pull_request.head.ref }} 25 | persist-credentials: false 26 | 27 | - name: Sort allow.txt 28 | run: | 29 | bash scripts/sort_spelling.sh 30 | 31 | - name: Configure Git 32 | run: | 33 | git config user.name "github-actions[bot]" 34 | git config user.email "41898282+github-actions[bot]@users.noreply.github.com" 35 | 36 | - name: Check for changes 37 | id: git_status 38 | run: | 39 | if ! git diff --quiet .github/actions/spelling/allow.txt; then 40 | echo "changes=true" >> $GITHUB_OUTPUT 41 | fi 42 | 43 | - name: Commit and push changes 44 | if: steps.git_status.outputs.changes == 'true' && github.event.pull_request.head.repo.full_name == github.repository 45 | run: | 46 | git add .github/actions/spelling/allow.txt 47 | git commit -m "ci: sort and unique allow.txt" 48 | git push 49 | 50 | - name: Fail on fork with changes 51 | if: steps.git_status.outputs.changes == 'true' && github.event.pull_request.head.repo.full_name != github.repository 52 | run: | 53 | echo "::error::The 'allow.txt' file is not sorted correctly. Please run 'bash scripts/sort_spelling.sh' and commit the changes." 54 | exit 1 55 | -------------------------------------------------------------------------------- /.github/workflows/spelling.yaml: -------------------------------------------------------------------------------- 1 | name: Check Spelling 2 | 3 | on: 4 | pull_request: 5 | branches: 6 | - "**" 7 | types: 8 | - "opened" 9 | - "reopened" 10 | - "synchronize" 11 | 12 | jobs: 13 | spelling: 14 | name: Check Spelling 15 | permissions: 16 | contents: read 17 | actions: read 18 | security-events: write 19 | outputs: 20 | followup: ${{ steps.spelling.outputs.followup }} 21 | if: ${{ contains(github.event_name, 'pull_request') || github.event_name == 'push' }} 22 | runs-on: ubuntu-latest 23 | concurrency: 24 | group: spelling-${{ github.event.pull_request.number || github.ref }} 25 | # note: If you use only_check_changed_files, you do not want cancel-in-progress 26 | cancel-in-progress: false 27 | steps: 28 | - name: check-spelling 29 | id: spelling 30 | uses: check-spelling/check-spelling@main 31 | with: 32 | suppress_push_for_open_pull_request: ${{ github.actor != 'dependabot[bot]' && 1 }} 33 | checkout: true 34 | check_file_names: 1 35 | spell_check_this: check-spelling/spell-check-this@main 36 | post_comment: 0 37 | use_magic_file: 1 38 | report-timing: 1 39 | 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 40 | experimental_apply_changes_via_bot: 1 41 | dictionary_source_prefixes: '{"cspell": "https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/main/dictionaries/"}' 42 | extra_dictionaries: | 43 | cspell:aws/dict/aws.txt 44 | cspell:bash/samples/bash-words.txt 45 | cspell:companies/dict/companies.txt 46 | cspell:css/dict/css.txt 47 | cspell:data-science/dict/data-science-models.txt 48 | cspell:data-science/dict/data-science.txt 49 | cspell:data-science/dict/data-science-tools.txt 50 | cspell:en_shared/dict/acronyms.txt 51 | cspell:en_shared/dict/shared-additional-words.txt 52 | cspell:en_GB/en_GB.trie 53 | cspell:en_US/en_US.trie 54 | cspell:filetypes/src/filetypes.txt 55 | cspell:fonts/dict/fonts.txt 56 | cspell:fullstack/dict/fullstack.txt 57 | cspell:golang/dict/go.txt 58 | cspell:google/dict/google.txt 59 | cspell:html/dict/html.txt 60 | cspell:java/src/java.txt 61 | cspell:k8s/dict/k8s.txt 62 | cspell:mnemonics/dict/mnemonics.txt 63 | cspell:monkeyc/src/monkeyc_keywords.txt 64 | cspell:node/dict/node.txt 65 | cspell:npm/dict/npm.txt 66 | cspell:people-names/dict/people-names.txt 67 | cspell:python/dict/python.txt 68 | cspell:python/dict/python-common.txt 69 | cspell:shell/dict/shell-all-words.txt 70 | cspell:software-terms/dict/softwareTerms.txt 71 | cspell:software-terms/dict/webServices.txt 72 | cspell:sql/src/common-terms.txt 73 | cspell:sql/src/sql.txt 74 | cspell:sql/src/tsql.txt 75 | cspell:terraform/dict/terraform.txt 76 | cspell:typescript/dict/typescript.txt 77 | check_extra_dictionaries: "" 78 | only_check_changed_files: true 79 | longest_word: "10" 80 | -------------------------------------------------------------------------------- /.github/workflows/stale.yaml: -------------------------------------------------------------------------------- 1 | # This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time. 2 | # 3 | # You can adjust the behavior by modifying this file. 4 | # For more information, see: 5 | # https://github.com/actions/stale 6 | name: Mark stale issues and pull requests 7 | 8 | on: 9 | schedule: 10 | # Scheduled to run at 10.30PM UTC everyday (1530PDT/1430PST) 11 | - cron: "30 22 * * *" 12 | workflow_dispatch: 13 | 14 | jobs: 15 | stale: 16 | runs-on: ubuntu-latest 17 | permissions: 18 | issues: write 19 | pull-requests: write 20 | actions: write 21 | 22 | steps: 23 | - uses: actions/stale@v9 24 | with: 25 | repo-token: ${{ secrets.GITHUB_TOKEN }} 26 | days-before-issue-stale: 14 27 | days-before-issue-close: 13 28 | stale-issue-label: "status:stale" 29 | close-issue-reason: not_planned 30 | any-of-labels: "status:awaiting response,status:more data needed" 31 | stale-issue-message: > 32 | Marking this issue as stale since it has been open for 14 days with no activity. 33 | This issue will be closed if no further activity occurs. 34 | close-issue-message: > 35 | This issue was closed because it has been inactive for 27 days. 36 | Please post a new issue if you need further assistance. Thanks! 37 | days-before-pr-stale: 14 38 | days-before-pr-close: 13 39 | stale-pr-label: "status:stale" 40 | stale-pr-message: > 41 | Marking this pull request as stale since it has been open for 14 days with no activity. 42 | This PR will be closed if no further activity occurs. 43 | close-pr-message: > 44 | This pull request was closed because it has been inactive for 27 days. 45 | Please open a new pull request if you need further assistance. Thanks! 46 | # Label that can be assigned to issues to exclude them from being marked as stale 47 | exempt-issue-labels: "override-stale" 48 | # Label that can be assigned to PRs to exclude them from being marked as stale 49 | exempt-pr-labels: "override-stale" 50 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *.pyc 5 | *$py.class 6 | **/dist 7 | /tmp 8 | /out-tsc 9 | /bazel-out 10 | 11 | # C extensions 12 | *.so 13 | 14 | # Distribution / packaging 15 | .Python 16 | build/ 17 | develop-eggs/ 18 | dist/ 19 | downloads/ 20 | eggs/ 21 | .eggs/ 22 | lib/ 23 | lib64/ 24 | parts/ 25 | sdist/ 26 | var/ 27 | wheels/ 28 | pip-wheel-metadata/ 29 | share/python-wheels/ 30 | *.egg-info/ 31 | .installed.cfg 32 | *.egg 33 | MANIFEST 34 | 35 | # PyInstaller 36 | # Usually these files are written by a python script from a template 37 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 38 | *.manifest 39 | *.spec 40 | 41 | # Installer logs 42 | pip-log.txt 43 | pip-delete-this-directory.txt 44 | 45 | # Unit test / coverage reports 46 | htmlcov/ 47 | .tox/ 48 | .nox/ 49 | .coverage 50 | .coverage.* 51 | .cache 52 | nosetests.xml 53 | coverage.xml 54 | *.cover 55 | *.py,cover 56 | .hypothesis/ 57 | .pytest_cache/ 58 | 59 | # Translations 60 | *.mo 61 | *.pot 62 | 63 | # Django stuff: 64 | *.log 65 | local_settings.py 66 | db.sqlite3 67 | db.sqlite3-journal 68 | 69 | # Flask stuff: 70 | instance/ 71 | .webassets-cache 72 | 73 | # Scrapy stuff: 74 | .scrapy 75 | 76 | # Sphinx documentation 77 | docs/_build/ 78 | 79 | # PyBuilder 80 | target/ 81 | 82 | # Jupyter Notebook 83 | .ipynb_checkpoints 84 | 85 | # IPython 86 | profile_default/ 87 | ipython_config.py 88 | 89 | # pyenv 90 | .python-version 91 | 92 | # pipenv 93 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 94 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 95 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 96 | # install all needed dependencies. 97 | Pipfile.lock 98 | Pipfile 99 | 100 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow 101 | __pypackages__/ 102 | 103 | # Celery stuff 104 | celerybeat-schedule 105 | celerybeat.pid 106 | 107 | # SageMath parsed files 108 | *.sage.py 109 | 110 | # Environments 111 | .env 112 | .venv 113 | .venv* 114 | env/ 115 | venv/ 116 | ENV/ 117 | env.bak/ 118 | venv.bak/ 119 | 120 | # Spyder project settings 121 | .spyderproject 122 | .spyproject 123 | 124 | # Rope project settings 125 | .ropeproject 126 | 127 | # mkdocs documentation 128 | /site 129 | 130 | # mypy 131 | .mypy_cache/ 132 | .dmypy.json 133 | dmypy.json 134 | .ruff_cache/ 135 | 136 | # Pyre type checker 137 | .pyre/ 138 | 139 | # macOS 140 | .DS_Store 141 | 142 | # PyCharm 143 | .idea 144 | 145 | # User-specific files 146 | language/examples/prompt-design/train.csv 147 | README-TOC*.md 148 | 149 | # Terraform 150 | terraform.tfstate** 151 | .terraform* 152 | .Terraform* 153 | 154 | tmp* 155 | 156 | # Node 157 | **/node_modules 158 | npm-debug.log 159 | yarn-error.log 160 | 161 | # IDEs and editors 162 | .idea/ 163 | .project 164 | .classpath 165 | .c9/ 166 | *.launch 167 | .settings/ 168 | *.sublime-workspace 169 | 170 | # Miscellaneous 171 | **/.angular/* 172 | /.angular/cache 173 | .sass-cache/ 174 | /connect.lock 175 | /coverage 176 | /libpeerconnection.log 177 | testem.log 178 | /typings 179 | 180 | # System files 181 | .DS_Store 182 | Thumbs.db 183 | 184 | # Sphinx build artifacts 185 | docs/sdk/python/_build/ 186 | docs/sdk/python/api/ 187 | docs/sdk/python/generated/ 188 | -------------------------------------------------------------------------------- /.mkdocs/overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block announce %}{% endblock %} 4 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "tabWidth": 2, 3 | "useTabs": false, 4 | "trailingComma": "es5", 5 | "bracketSameLine": true, 6 | "overrides": [ 7 | { 8 | "files": "*.md", 9 | "options": { 10 | "tabWidth": 4, 11 | "useTabs": false, 12 | "trailingComma": "es5" 13 | } 14 | } 15 | ] 16 | } 17 | -------------------------------------------------------------------------------- /.ruff.toml: -------------------------------------------------------------------------------- 1 | ################################################################################# 2 | # 3 | # Ruff linter and code formatter for A2A 4 | # 5 | # This file follows the standards in Google Python Style Guide 6 | # https://google.github.io/styleguide/pyguide.html 7 | # 8 | # The settings below are for the IDE configuration, and are optional. 9 | #{ 10 | # "editor.formatOnSave": true, 11 | # "[python]": { 12 | # "editor.defaultFormatter": "charliermarsh.ruff", 13 | # "editor.formatOnSave": true, 14 | # "editor.codeActionsOnSave": { 15 | # "source.organizeImports": "true" 16 | # }, 17 | # }, 18 | # "ruff.importStrategy": "fromEnvironment", 19 | #} 20 | 21 | line-length = 80 # Google Style Guide §3.2: 80 columns 22 | indent-width = 4 # Google Style Guide §3.4: 4 spaces 23 | 24 | target-version = "py312" # Minimum Python version 25 | 26 | [lint] 27 | ignore = [ 28 | "COM812", 29 | "FBT001", 30 | "FBT002", 31 | "D203", 32 | "D213", 33 | "ANN001", 34 | "ANN201", 35 | "ANN204", 36 | "D100", # Ignore Missing docstring in public module (often desired at top level __init__.py) 37 | "D102", # Ignore return type annotation in public method 38 | "D104", # Ignore Missing docstring in public package (often desired at top level __init__.py) 39 | "D107", # Ignore Missing docstring in __init__ (use class docstring) 40 | "TD002", # Ignore Missing author in TODOs (often not required) 41 | "TD003", # Ignore Missing issue link in TODOs (often not required/available) 42 | "T201", # Ignore print presence 43 | "RUF012", # Ignore Mutable class attributes should be annotated with `typing.ClassVar` 44 | "RUF013", # Ignore implicit optional 45 | ] 46 | 47 | select = [ 48 | "E", # pycodestyle errors (PEP 8) 49 | "W", # pycodestyle warnings (PEP 8) 50 | "F", # Pyflakes (logical errors, unused imports/variables) 51 | "I", # isort (import sorting - Google Style §3.1.2) 52 | "D", # pydocstyle (docstring conventions - Google Style §3.8) 53 | "N", # pep8-naming (naming conventions - Google Style §3.16) 54 | "UP", # pyupgrade (use modern Python syntax) 55 | "ANN",# flake8-annotations (type hint usage/style - Google Style §2.22) 56 | "A", # flake8-builtins (avoid shadowing builtins) 57 | "B", # flake8-bugbear (potential logic errors & style issues - incl. mutable defaults B006, B008) 58 | "C4", # flake8-comprehensions (unnecessary list/set/dict comprehensions) 59 | "ISC",# flake8-implicit-str-concat (disallow implicit string concatenation across lines) 60 | "T20",# flake8-print (discourage `print` - prefer logging) 61 | "SIM",# flake8-simplify (simplify code, e.g., `if cond: return True else: return False`) 62 | "PTH",# flake8-use-pathlib (use pathlib instead of os.path where possible) 63 | "PL", # Pylint rules ported to Ruff (PLC, PLE, PLR, PLW) 64 | "PIE",# flake8-pie (misc code improvements, e.g., no-unnecessary-pass) 65 | "RUF",# Ruff-specific rules (e.g., RUF001-003 ambiguous unicode) 66 | "RET",# flake8-return (consistency in return statements) 67 | "SLF",# flake8-self (check for private member access via `self`) 68 | "TID",# flake8-tidy-imports (relative imports, banned imports - configure if needed) 69 | "YTT",# flake8-boolean-trap (checks for boolean positional arguments, truthiness tests - Google Style §3.10) 70 | "TD", # flake8-todos (check TODO format - Google Style §3.7) 71 | ] 72 | 73 | exclude = [ 74 | ".bzr", 75 | ".direnv", 76 | ".eggs", 77 | ".git", 78 | ".hg", 79 | ".mypy_cache", 80 | ".nox", 81 | ".pants.d", 82 | ".pytype", 83 | ".ruff_cache", 84 | ".svn", 85 | ".tox", 86 | ".venv", 87 | "__pypackages__", 88 | "_build", 89 | "buck-out", 90 | "build", 91 | "dist", 92 | "node_modules", 93 | "venv", 94 | "*/migrations/*", 95 | ] 96 | 97 | [lint.isort] 98 | #force-sort-within-sections = true 99 | #combine-as-imports = true 100 | case-sensitive = true 101 | #force-single-line = false 102 | #known-first-party = [] 103 | #known-third-party = [] 104 | lines-after-imports = 2 105 | lines-between-types = 1 106 | #no-lines-before = ["LOCALFOLDER"] 107 | #required-imports = [] 108 | #section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"] 109 | 110 | [lint.pydocstyle] 111 | convention = "google" 112 | 113 | [lint.flake8-annotations] 114 | mypy-init-return = true 115 | allow-star-arg-any = false 116 | 117 | [lint.pep8-naming] 118 | ignore-names = ["test_*", "setUp", "tearDown", "mock_*"] 119 | classmethod-decorators = ["classmethod", "pydantic.validator", "pydantic.root_validator"] 120 | staticmethod-decorators = ["staticmethod"] 121 | 122 | [lint.flake8-tidy-imports] 123 | ban-relative-imports = "all" # Google generally prefers absolute imports (§3.1.2) 124 | 125 | [lint.flake8-quotes] 126 | docstring-quotes = "double" 127 | inline-quotes = "single" 128 | 129 | [lint.per-file-ignores] 130 | "__init__.py" = ["F401"] # Ignore unused imports in __init__.py 131 | "*_test.py" = ["D", "ANN"] # Ignore docstring and annotation issues in test files 132 | "test_*.py" = ["D", "ANN"] # Ignore docstring and annotation issues in test files 133 | 134 | [format] 135 | docstring-code-format = true 136 | docstring-code-line-length = "dynamic" # Or set to 80 137 | quote-style = "single" 138 | indent-style = "space" 139 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "editor.formatOnSave": true, 3 | "[python]": { 4 | "editor.defaultFormatter": "charliermarsh.ruff", 5 | "editor.formatOnSave": true, 6 | "editor.codeActionsOnSave": { 7 | "source.organizeImports": "explicit" 8 | } 9 | }, 10 | "ruff.importStrategy": "fromEnvironment", 11 | "markdownlint.configFile": ".github/linters/.markdownlint.json", 12 | "[json]": { 13 | "editor.defaultFormatter": "vscode.json-language-features", 14 | "editor.formatOnSave": true 15 | }, 16 | "files.trimTrailingWhitespace": true, 17 | "files.insertFinalNewline": true 18 | } 19 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## [0.3.0](https://github.com/a2aproject/A2A/compare/v0.2.6...v0.3.0) (2025-07-30) 4 | 5 | 6 | ### ⚠ BREAKING CHANGES 7 | 8 | * Add mTLS to SecuritySchemes, add oauth2 metadata url field, allow Skills to specify Security ([#901](https://github.com/a2aproject/A2A/issues/901)) 9 | * Change Well-Known URI for Agent Card hosting from `agent.json` to `agent-card.json` ([#841](https://github.com/a2aproject/A2A/issues/841)) 10 | * Add method for fetching extended card ([#929](https://github.com/a2aproject/A2A/issues/929)) 11 | 12 | ### Features 13 | 14 | * Add `signatures` to the `AgentCard` ([#917](https://github.com/a2aproject/A2A/issues/917)) ([ef4a305](https://github.com/a2aproject/A2A/commit/ef4a30505381e99b20103724cabef024389bacef)) 15 | * Add method for fetching extended card ([#929](https://github.com/a2aproject/A2A/issues/929)) ([2cd7d98](https://github.com/a2aproject/A2A/commit/2cd7d98bc8566601b9a18ca8afe92a0b4d203248)) 16 | * 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)) 17 | 18 | 19 | ### Bug Fixes 20 | 21 | * **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)) 22 | * **spec:** Add Transport enum to specification ([#909](https://github.com/a2aproject/A2A/issues/909)) ([e834347](https://github.com/a2aproject/A2A/commit/e834347c279186d9d7873b352298e8b19737dd5a)) 23 | 24 | 25 | ### Code Refactoring 26 | 27 | * 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)) 28 | 29 | ## [0.2.6](https://github.com/a2aproject/A2A/compare/v0.2.5...v0.2.6) (2025-07-17) 30 | 31 | 32 | ### Bug Fixes 33 | 34 | * Type fix and doc clarification ([#877](https://github.com/a2aproject/A2A/issues/877)) ([6f1d17b](https://github.com/a2aproject/A2A/commit/6f1d17ba806c32f2b6fbe465be93ec13bfe7d83c)) 35 | * 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)) 36 | 37 | ## [0.2.5](https://github.com/a2aproject/A2A/compare/v0.2.4...v0.2.5) (2025-06-30) 38 | 39 | 40 | ### ⚠ BREAKING CHANGES 41 | 42 | * **spec:** Add a required protocol version to the agent card. ([#802](https://github.com/a2aproject/A2A/issues/802)) 43 | * Support for multiple pushNotification config per task ([#738](https://github.com/a2aproject/A2A/issues/738)) ([f355d3e](https://github.com/a2aproject/A2A/commit/f355d3e922de61ba97873fe2989a8987fc89eec2)) 44 | 45 | 46 | ### Features 47 | 48 | * **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)) 49 | * **spec:** Support for multiple pushNotification config per task ([#738](https://github.com/a2aproject/A2A/issues/738)) ([f355d3e](https://github.com/a2aproject/A2A/commit/f355d3e922de61ba97873fe2989a8987fc89eec2)) 50 | 51 | 52 | ### Documentation 53 | 54 | * update spec & doc topic with non-restartable tasks ([#770](https://github.com/a2aproject/A2A/issues/770)) ([ebc4157](https://github.com/a2aproject/A2A/commit/ebc4157ca87ae08d1c55e38e522a1a17201f2854)) 55 | 56 | ## [0.2.4](https://github.com/a2aproject/A2A/compare/v0.2.3...v0.2.4) (2025-06-30) 57 | 58 | 59 | ### Features 60 | 61 | * 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)) 62 | 63 | ## [0.2.3](https://github.com/a2aproject/A2A/compare/v0.2.2...v0.2.3) (2025-06-12) 64 | 65 | 66 | ### Bug Fixes 67 | 68 | * Address some typos in gRPC annotations ([#747](https://github.com/a2aproject/A2A/issues/747)) ([f506881](https://github.com/a2aproject/A2A/commit/f506881c9b8ff0632d7c7107d5c426646ae31592)) 69 | 70 | ## [0.2.2](https://github.com/a2aproject/A2A/compare/v0.2.1...v0.2.2) (2025-06-09) 71 | 72 | 73 | ### ⚠ BREAKING CHANGES 74 | 75 | * Resolve spec inconsistencies with JSON-RPC 2.0 76 | 77 | ### Features 78 | 79 | * 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)) 80 | * Add protocol support for extensions ([#716](https://github.com/a2aproject/A2A/issues/716)) ([70f1e2b](https://github.com/a2aproject/A2A/commit/70f1e2b0c68a3631888091ce9460a9f7fbfbdff2)) 81 | * **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)) 82 | 83 | 84 | ### Bug Fixes 85 | 86 | * Protocol should released as 0.2.2 ([22e7541](https://github.com/a2aproject/A2A/commit/22e7541be082c4f0845ff7fa044992cda05b437e)) 87 | * Resolve spec inconsistencies with JSON-RPC 2.0 ([628380e](https://github.com/a2aproject/A2A/commit/628380e7e392bc8f1778ae991d4719bd787c17a9)) 88 | 89 | ## [0.2.1](https://github.com/a2aproject/A2A/compare/v0.2.0...v0.2.1) (2025-05-27) 90 | 91 | ### Features 92 | 93 | * 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)) 94 | * Add optional referenceTaskIds for task followups ([#608](https://github.com/a2aproject/A2A/issues/608)) ([5368e77](https://github.com/a2aproject/A2A/commit/5368e7728cb523caf1a9218fda0b1646325f524b)) 95 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of 9 | experience, education, socio-economic status, nationality, personal appearance, 10 | race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or reject 41 | comments, commits, code, wiki edits, issues, and other contributions that are 42 | not aligned to this Code of Conduct, or to ban temporarily or permanently any 43 | contributor for other behaviors that they deem inappropriate, threatening, 44 | offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | This Code of Conduct also applies outside the project spaces when the Project 56 | Steward has a reasonable belief that an individual's behavior may have a 57 | negative impact on the project or its community. 58 | 59 | ## Conflict Resolution 60 | 61 | We do not believe that all conflict is bad; healthy debate and disagreement 62 | often yield positive results. However, it is never okay to be disrespectful or 63 | to engage in behavior that violates the project’s code of conduct. 64 | 65 | If you see someone violating the code of conduct, you are encouraged to address 66 | the behavior directly with those involved. Many issues can be resolved quickly 67 | and easily, and this gives people more control over the outcome of their 68 | dispute. If you are unable to resolve the matter for any reason, or if the 69 | behavior is threatening or harassing, report it. We are dedicated to providing 70 | an environment where participants feel welcome and safe. 71 | 72 | Reports should be directed to [a2a-coc@googlegroups.com](mailto:a2a-coc@googlegroups.com), the 73 | Project Steward(s) for A2A. It is the Project Steward’s duty to 74 | receive and address reported violations of the code of conduct. They will then 75 | work with a committee consisting of representatives from the A2A project and leadership. 76 | 77 | We will investigate every complaint, but you may not receive a direct response. 78 | We will use our discretion in determining when and how to follow up on reported 79 | incidents, which may range from not taking action to permanent expulsion from 80 | the project and project-sponsored spaces. We will notify the accused of the 81 | report and provide them an opportunity to discuss it before any action is taken. 82 | The identity of the reporter will be omitted from the details of the report 83 | supplied to the accused. In potentially harmful situations, such as ongoing 84 | harassment or threats to anyone's safety, we may take action without notice. 85 | 86 | ## Attribution 87 | 88 | This Code of Conduct is adapted from the Contributor Covenant, version 1.4, 89 | available at 90 | https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 91 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to contribute 2 | 3 | We'd love to accept your patches and contributions to this project. 4 | 5 | ## Contribution process 6 | 7 | ### Code reviews 8 | 9 | All submissions, including submissions by project members, require review. We 10 | use GitHub pull requests for this purpose. Consult 11 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 12 | information on using pull requests. 13 | 14 | ### Contributor Guide 15 | 16 | You may follow these steps to contribute: 17 | 18 | 1. **Fork the official repository.** This will create a copy of the official repository in your own account. 19 | 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. 20 | 3. **Work on your forked repository's feature branch.** This is where you will make your changes to the code. 21 | 4. **Commit your updates on your forked repository's feature branch.** This will save your changes to your copy of the repository. 22 | 5. **Submit a pull request to the official repository's main branch.** This will request that your changes be merged into the official repository. 23 | 6. **Resolve any linting errors.** This will ensure that your changes are formatted correctly. 24 | 25 | Here are some additional things to keep in mind during the process: 26 | 27 | - **Test your changes.** Before you submit a pull request, make sure that your changes work as expected. 28 | - **Be patient.** It may take some time for your pull request to be reviewed and merged. 29 | -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Agent2Agent (A2A) Governance 2 | 3 | The Agent2Agent project is governed by the Technical Steering Committee. The Committee has eight seats, each held by the following companies: 4 | 5 | | Company | Representative | Title | Contact | 6 | | :--- | :--- | :--- | :--- | 7 | | **Google** | Todd Segal | Principal Engineer | [@ToddSegal](https://github.com/ToddSegal) | 8 | | **Microsoft** | Darrel Miller | Partner API Architect | [@darrelmiller](https://github.com/darrelmiller) | 9 | | **Cisco** | Luca Muscariello | Principal Engineer | [@muscariello](https://github.com/muscariello) | 10 | | **Amazon Web Services** | Nicholas Aldridge | Principal Engineer | [@000-000-000-000-000](https://github.com/000-000-000-000-000) | 11 | | **Salesforce** | Sam Sharaf | Sr. Director Product Management | [@samuelsharaf](https://github.com/samuelsharaf) | 12 | | **ServiceNow** | Sean Hughes | AI Ecosystem Director | [@hughesthe1st](https://github.com/hughesthe1st) | 13 | | **SAP** | Sivakumar N. | Vice President | [LinkedIn](https://www.linkedin.com/in/siva-kumar-n/) | 14 | | **IBM Research** | Kate Blair | Director of Incubation | [@geneknit](https://github.com/geneknit) | 15 | 16 | ## Mission and Scope of the Project 17 | 18 | 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: 19 | 20 | 1. the Agent2Agent Protocol (the "Protocol"); 21 | 22 | 2. a SDK for designing implementations of the Protocol and related software components; and 23 | 24 | 3. documentation and other artifacts related to the Project. 25 | 26 | 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. 27 | 28 | ## Technical Steering Committee 29 | 30 | 1. The Technical Steering Committee (the "TSC") will be responsible for all technical oversight of the open source Project. 31 | 2. **TSC Composition** 32 | 33 | 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. 34 | 35 | b. **"Steady State."** The TSC will decide upon a "steady state" composition of the TSC (whether by election, sub-project technical leads, or other method as determined by the TSC) for composition of the TSC from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC. 36 | 37 | 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. 38 | 39 | 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: 40 | 41 | a. **Contributors** include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project; 42 | 43 | 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 44 | 45 | c. A Contributor may become a Maintainer by a vote of the TSC. A Maintainer may be removed by a vote of the TSC. 46 | 47 | 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. 48 | 4. The TSC may: 49 | 1. establish work flow procedures for the submission, approval, and closure/archiving of projects, 50 | 2. set requirements for the promotion of Contributors to Maintainer status, as applicable, and 51 | 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. 52 | 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. 53 | 6. **Responsibilities:** The TSC will be responsible for all aspects of oversight relating to the Project, which may include: 54 | 1. coordinating the technical direction of the Project; 55 | 2. approving project or system proposals (including, but not limited to, incubation, deprecation, and changes to a sub-project's scope); 56 | 3. organizing sub-projects and removing sub-projects; 57 | 4. creating sub-committees or working groups to focus on cross-project technical issues and requirements; 58 | 5. appointing representatives to work with other open source or open standards communities; 59 | 6. establishing community norms, workflows, issuing releases, and security issue reporting policies; 60 | 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; 61 | 8. discussions, seeking consensus, and where necessary, voting on technical matters relating to the code base that affect multiple projects; and 62 | 9. coordinating any marketing, events, or communications regarding the Project. 63 | 64 | ### TSC Voting 65 | 66 | 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. 67 | 68 | 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. 69 | 70 | ### TSC Meetings 71 | 72 | Our hope is that the first TSC meeting will be held in August 2025. Once the TSC representatives are finalized, scheduling will begin. In the interim we have drafted a [working doc for TSC Meeting Agendas](https://docs.google.com/document/d/1Dx6qYfCjSChHKRMwLJcvtDjq6igYTAKFW9Vg1IMPCUk/view). 73 | 74 | ## Project Communications 75 | 76 | 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. 77 | 78 | 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. 79 | 80 | Additional communication avenues will likely be added - stay tuned. 81 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Agent2Agent (A2A) Protocol 2 | 3 | [![PyPI - Version](https://img.shields.io/pypi/v/a2a-sdk)](https://pypi.org/project/a2a-sdk) 4 | [![Apache License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) 5 | [![RepoMapr](https://img.shields.io/badge/RepoMapr-View_Interactive_Diagram-blue)](https://repomapr.com/a2aproject/A2A) 6 | 7 | ![A2A Banner](docs/assets/a2a-banner.png) 8 | 9 | **An open protocol enabling communication and interoperability between opaque agentic applications.** 10 | 11 | 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. 12 | 13 | With A2A, agents can: 14 | 15 | - Discover each other's capabilities. 16 | - Negotiate interaction modalities (text, forms, media). 17 | - Securely collaborate on long running tasks. 18 | - Operate without exposing their internal state, memory, or tools. 19 | 20 | ## Intro to A2A Video 21 | 22 | [![A2A Intro Video](https://img.youtube.com/vi/Fbr_Solax1w/hqdefault.jpg)](https://goo.gle/a2a-video) 23 | 24 | ## Why A2A? 25 | 26 | As AI agents become more prevalent, their ability to interoperate is crucial for building complex, multi-functional applications. A2A aims to: 27 | 28 | - **Break Down Silos:** Connect agents across different ecosystems. 29 | - **Enable Complex Collaboration:** Allow specialized agents to work together on tasks that a single agent cannot handle alone. 30 | - **Promote Open Standards:** Foster a community-driven approach to agent communication, encouraging innovation and broad adoption. 31 | - **Preserve Opacity:** Allow agents to collaborate without needing to share internal memory, proprietary logic, or specific tool implementations, enhancing security and protecting intellectual property. 32 | 33 | ### Key Features 34 | 35 | - **Standardized Communication:** JSON-RPC 2.0 over HTTP(S). 36 | - **Agent Discovery:** Via "Agent Cards" detailing capabilities and connection info. 37 | - **Flexible Interaction:** Supports synchronous request/response, streaming (SSE), and asynchronous push notifications. 38 | - **Rich Data Exchange:** Handles text, files, and structured JSON data. 39 | - **Enterprise-Ready:** Designed with security, authentication, and observability in mind. 40 | 41 | ## Getting Started 42 | 43 | - 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://a2a-protocol.org) for a complete overview, the full protocol specification, tutorials, and guides. 44 | - 📝 **View the Specification:** [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/) 45 | - Use the SDKs: 46 | - [🐍 A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk` 47 | - [🧑‍💻 A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk` 48 | - [☕️ A2A Java SDK](https://github.com/a2aproject/a2a-java) using maven 49 | - [🔷 A2A .NET SDK](https://github.com/a2aproject/a2a-dotnet) using [NuGet](https://www.nuget.org/packages/A2A) `dotnet add package A2A` 50 | - 🎬 Use our [samples](https://github.com/a2aproject/a2a-samples) to see A2A in action 51 | 52 | ## Contributing 53 | 54 | We welcome community contributions to enhance and evolve the A2A protocol! 55 | 56 | - **Questions & Discussions:** Join our [GitHub Discussions](https://github.com/a2aproject/A2A/discussions). 57 | - **Issues & Feedback:** Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues). 58 | - **Contribution Guide:** See our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute. 59 | - **Private Feedback:** Use this [Google Form](https://goo.gle/a2a-feedback). 60 | - **Partner Program:** Google Cloud customers can join our partner program via this [form](https://goo.gle/a2a-partner). 61 | 62 | ## What's next 63 | 64 | ### Protocol Enhancements 65 | 66 | - **Agent Discovery:** 67 | - Formalize inclusion of authorization schemes and optional credentials directly within the `AgentCard`. 68 | - **Agent Collaboration:** 69 | - Investigate a `QuerySkill()` method for dynamically checking unsupported or unanticipated skills. 70 | - **Task Lifecycle & UX:** 71 | - Support for dynamic UX negotiation _within_ a task (e.g., agent adding audio/video mid-conversation). 72 | - **Client Methods & Transport:** 73 | - Explore extending support to client-initiated methods (beyond task management). 74 | - Improvements to streaming reliability and push notification mechanisms. 75 | 76 | ## About 77 | 78 | The A2A Protocol is an open-source project by Google LLC, under the [Apache License 2.0](LICENSE), and is open to contributions from the community. 79 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | To report a security issue, please use [g.co/vulnz](https://g.co/vulnz). 4 | 5 | The Google Security Team will respond within 5 working days of your report on g.co/vulnz. 6 | 7 | We use g.co/vulnz for our intake, and do coordination and disclosure here using GitHub Security Advisory to privately discuss and fix the issue. 8 | -------------------------------------------------------------------------------- /docs/404.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Redirecting... 7 | 40 | 41 | 42 | 43 |

A2A - Page Not Found

44 |

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

45 |

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

46 | 47 | 48 | 49 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # A2A Docs 2 | 3 | 4 | 5 | ## Developing A2A docs 6 | 7 | 1. Clone this repository and `cd` into the repository directory 8 | 2. Run `pip install -r requirements-docs.txt` 9 | 3. Run `mkdocs serve`, edit `.md` files, and live preview 10 | 4. Contribute docs changes as usual 11 | 12 | ## How it works 13 | 14 | - The A2A docs use [mkdocs](https://www.mkdocs.org/) and the 15 | [mkdocs-material theme](https://squidfunk.github.io/mkdocs-material/) 16 | - All of the source documentation / Markdown files related to the A2A docs are 17 | in the `docs/` directory in the A2A repository 18 | - `mkdocs.yml` in the repository root contains all of the docs config, including 19 | the site navigation and organization 20 | - There is a GitHub Action in `.github/workflows/docs.yml` that builds and 21 | publishes the docs and pushes the built assets to the `gh-pages` branch in 22 | this repository using `mkdocs gh-deploy --force`. This happens automatically for all 23 | commits / merges to `main`. 24 | - The A2A documentation is hosted in GitHub pages, and the settings for this are 25 | in the A2A repository settings in GitHub. 26 | 27 | ## Building the Python SDK Documentation 28 | 29 | The Python SDK documentation is built using [Sphinx](https://www.sphinx-doc.org/). 30 | 31 | ### Prerequisites 32 | 33 | Ensure you have installed the documentation dependencies: 34 | 35 | ```bash 36 | pip install -r ../../requirements-docs.txt 37 | ``` 38 | 39 | ### Building the Docs 40 | 41 | 1. Navigate to the `docs/sdk/python` directory. 42 | 2. Run the following command to build the HTML documentation: 43 | 44 | ```bash 45 | sphinx-build -b html docs/sdk/python docs/sdk/python/api 46 | ``` 47 | 48 | 3. The generated HTML files will be in the `_build/html` directory. You can open `_build/html/index.html` in your browser to view the documentation. 49 | -------------------------------------------------------------------------------- /docs/assets/a2a-actors.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google-a2a/A2A/64f1064598e3b33cf06c40981e47aba5fb82f1e3/docs/assets/a2a-actors.png -------------------------------------------------------------------------------- /docs/assets/a2a-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google-a2a/A2A/64f1064598e3b33cf06c40981e47aba5fb82f1e3/docs/assets/a2a-banner.png -------------------------------------------------------------------------------- /docs/assets/a2a-logo-black.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /docs/assets/a2a-logo-white.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /docs/assets/a2a-main.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google-a2a/A2A/64f1064598e3b33cf06c40981e47aba5fb82f1e3/docs/assets/a2a-main.png -------------------------------------------------------------------------------- /docs/assets/a2a-mcp-readme.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google-a2a/A2A/64f1064598e3b33cf06c40981e47aba5fb82f1e3/docs/assets/a2a-mcp-readme.png -------------------------------------------------------------------------------- /docs/assets/a2a-mcp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google-a2a/A2A/64f1064598e3b33cf06c40981e47aba5fb82f1e3/docs/assets/a2a-mcp.png -------------------------------------------------------------------------------- /docs/assets/adk.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /docs/assets/ag2-black.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 7 | 8 | 10 | 22 | 27 | 31 | 35 | 39 | 40 | 41 | -------------------------------------------------------------------------------- /docs/assets/langgraph-color.svg: -------------------------------------------------------------------------------- 1 | LangGraph -------------------------------------------------------------------------------- /docs/community.md: -------------------------------------------------------------------------------- 1 | --- 2 | hide: 3 | - navigation 4 | --- 5 | 6 | # Welcome to the A2A Community 7 | 8 | The **Agent2Agent (A2A) protocol** is generating significant buzz across the 9 | tech world, and for good reason! This open interoperability protocol is designed 10 | to enable **seamless collaboration between AI agents across diverse frameworks 11 | and vendors**. By standardizing communication, A2A aims to unlock complex 12 | workflows, enhance productivity, and foster a new era of **"Agent 13 | Interoperability"**. Don't just take our word for it – see what the community is 14 | saying! 15 | 16 | ## The Word on the Street: Social Highlights 17 | 18 | The launch of A2A has sparked lively discussions and positive reactions on various social platforms. Here's a glimpse of the excitement: 19 | 20 | - **Rapid Interest and Adoption:** The A2A [GitHub repository](https://github.com/a2aproject/A2A) has seen an **explosive surge in popularity**. This rapid interest underscores the industry's eagerness for a standardized agent communication protocol, with many companies collaborating and contributing. 21 | 22 | - **Microsoft's interest via Semantic Kernel:** [Asha Sharma](https://www.linkedin.com/in/aboutasha/), 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: a lightweight JSON-RPC protocol that lets agents swap context, not code or credentials, over plain HTTP. Drop it into your Foundry stack for instant, secure, async interoperability with any A2A-compliant agent, regardless of modality**". The post received numerous positive reactions, including "**A2A support in Semantic Kernel is a key unlock — context-level interoperability without sharing code or creds is how agent ecosystems scale securely across clouds**". 23 | 24 | - **Matt Pocock's Diagramming Intent:** [Matt Pocock](https://x.com/mattpocockuk), a well-known developer educator, [shared on X](https://x.com/mattpocockuk/status/1910002033018421400) "**I've just been reading the Agent2Agent technical docs - Google's new protocol for agent to agent communication. You know what that means. Let's diagram them:**". This tweet, liked and reposted hundreds of times, includes some great diagrams explaining the A2A protocol. 25 | 26 | - **Craig McLuckie's "Hot Take":** [Craig McLuckie](https://www.linkedin.com/in/craigmcluckie/) shared his initial thoughts on [LinkedIn](https://www.linkedin.com/posts/craigmcluckie_hot-take-on-agent2agent-vs-mcp-google-just-activity-7315939233792176128-4rGQ) "**Hot take on Agent2Agent vs MCP**". His post highlighted Google's careful positioning of A2A as focused on interactions _between_ agentic systems, rather than agents interacting with resources (the focus of MCP). This distinction is crucial for improving models' ability to understand expectations from other agents. McLuckie also pointed out the potential for A2A to enable systems to **advertise specific capabilities and specialities**, which is seen as "**sensible**". 27 | 28 | ## Community deep dive videos 29 | 30 | - [Zachary Huang](https://www.youtube.com/@ZacharyLLM) explains in his [YouTube video](https://www.youtube.com/watch?v=wrCF8MoXC_I), A2A "**complements**" MCP. While MCP acts as a "**USB-C port for AI applications**" connecting agents to tools, A2A acts as a communication standard **between the intelligent agents themselves**. This layered approach allows for building powerful systems where agents use A2A to coordinate and MCP to access necessary tools. 31 | - [Jack Herrington](https://www.youtube.com/@jherr) on his [YouTube video](https://www.youtube.com/watch?v=voaKr_JHvF4) walks through some of the provided examples and closes with his opinion that **"Having a specific protocol for agents to talk to other agents is valuable"** and reiterates, **"LLM plus tools are agents. MCP gives agents those tools. So that's why A2A and MCP play really nicely together**". 32 | - [Cole Medin](https://www.youtube.com/@ColeMedin) suggested on his [YouTube video](https://www.youtube.com/watch?v=ywMWpmOOaSo) that "**A2A was released very recently but it's already looking like it's going to follow a similar path**" to MCP in terms of growing interest. He also demonstrates the samples step by step and provides a summary of core concepts. 33 | - [Sam Witteveen](https://www.youtube.com/@samwitteveenai) covered A2A on his [YouTube video](https://www.youtube.com/watch?v=rAeqTaYj_aI) immediately after Google Cloud Next, discussing the value of making protocols open and not ending up with conflicting protocols. 34 | 35 | ## Community Contributions to A2A 36 | 37 | - Python Quickstart Tutorial [PR\#202](https://github.com/a2aproject/A2A/pull/202) 38 | - LlamaIndex submitted a sample implementation [PR\#179](https://github.com/a2aproject/A2A/pull/179) 39 | - Autogen sample server [PR\#232](https://github.com/a2aproject/A2A/pull/232) 40 | - AG2 \+ MCP example [PR\#230](https://github.com/a2aproject/A2A/pull/230) 41 | - PydanticAI example [PR\#127](https://github.com/a2aproject/A2A/pull/127) 42 | - Go example [PR\#52](https://github.com/a2aproject/A2A/pull/52) 43 | - Daytona sandbox running agent [PR\#170](https://github.com/a2aproject/A2A/pull/170) 44 | 45 | ## What is Driving This Excitement? 46 | 47 | The enthusiasm surrounding A2A stems from its potential to address key challenges in building sophisticated AI applications: 48 | 49 | - **Breaking Down Silos:** A2A aims to overcome the limitations of siloed AI systems by providing a **universal framework for agents built on different platforms to communicate and collaborate securely**. 50 | 51 | - **Enabling Complex Collaboration:** For tasks that require the expertise of multiple specialized agents, A2A provides a standardized way for them to **delegate tasks, exchange information, and coordinate actions**. This mirrors how human teams work together, distributing responsibilities for greater efficiency. 52 | 53 | - **Dynamic Agent Discovery:** A key feature of A2A is the ability for agents to **discover the capabilities of other agents** through standardized "**Agent Cards**". This dynamic discovery allows for more flexible and adaptable multi-agent systems. 54 | 55 | - **Complementary to MCP:** As stated on our [A2A ❤️ MCP topic page](topics/a2a-and-mcp.md) and affirmed by many community, A2A "**complements**" MCP. MCP acts as a communication standard between models and resources, providing tools for agents. A2A acts as a communication standard **between the intelligent agents themselves**. This layered approach allows for building powerful systems where agents use A2A to coordinate and MCP to access necessary tools. 56 | 57 | - **Open and Community-Driven:** Google has released A2A as **open source**, inviting contributions from the broader community to refine and expand its functionality. This commitment to open collaboration fosters innovation and broad adoption. 58 | 59 | ## The Future is Interoperable 60 | 61 | The social media buzz surrounding Google's A2A protocol clearly indicates a strong interest and belief in its potential to revolutionize the development of 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, efficiency, and innovation. As enterprises increasingly adopt AI agents for a wide range of tasks, A2A represents a crucial step towards realizing the full power of interconnected AI ecosystems. 62 | 63 | Stay tuned for more updates and join the growing community building the future of AI interoperability with A2A! 64 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | hide: 3 | - navigation 4 | - toc 5 | --- 6 | 7 | # Agent2Agent (A2A) Protocol 8 | 9 |
10 | ![A2A Banner](assets/a2a-banner.png){width="70%"} 11 |
12 | The Agent2Agent (A2A) Protocol is an open standard 13 | designed to enable seamless communication and collaboration between AI agents.
14 | In a world where agents are built using diverse frameworks and by different vendors, 15 | A2A provides a common language, breaking down silos and fostering interoperability. 16 |
17 |
18 | 19 | !!! abstract "" 20 | Build with 21 | **[![ADK Logo](./assets/adk.svg){class="twemoji lg middle"} ADK](https://google.github.io/adk-docs/)** _(or any framework)_, 22 | equip with **MCP** _(or any tool)_, 23 | and communicate with 24 | **![A2A Logo](./assets/a2a-logo-black.svg){class="twemoji sm middle"} A2A**, 25 | to remote agents, local agents, and humans. 26 | 27 |
28 | 29 | - :material-lightbulb-outline:{ .lg .middle } **A2A** Announcements 30 | 31 | Ramp up quickly 32 | 33 | [:octicons-arrow-right-24: Announcing the A2A Protocol (Apr)](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) 34 | our initial blog 35 | 36 | [:octicons-arrow-right-24: Agents are not tools (Jun)](https://www.googlecloudcommunity.com/gc/Community-Blogs/Agents-are-not-tools/ba-p/922716) 37 | our TL thought piece 38 | 39 | [:octicons-arrow-right-24: Google Cloud donates A2A to Linux Foundation (Jun)](https://developers.googleblog.com/en/google-cloud-donates-a2a-to-linux-foundation/) 40 | covered by [Forbes](https://www.forbes.com/sites/janakirammsv/2025/06/25/key-tech-firms-unite-as-google-donates-a2a-to-linux-foundation/) 41 | 42 | Dive deep with end to end examples 43 | 44 | [:octicons-arrow-right-24: Designing with A2A (O'Reilly)](https://www.oreilly.com/radar/designing-collaborative-multi-agent-systems-with-the-a2a-protocol/) 45 | 46 | [:octicons-arrow-right-24: Start the Python Tutorial](tutorials/python/1-introduction.md) 47 | 48 | - :material-play-circle:{ .lg .middle } **Video** Intro in <8 min 49 | 50 | 51 | 52 |
53 | 54 | ## Why A2A Matters 55 | 56 | ![A2A Main Graphic](assets/a2a-main.png){width="50%"} 57 | {style="text-align: center; margin-bottom:1em; margin-top:2em;"} 58 | 59 |
60 | 61 | - :material-account-group-outline:{ .lg .middle } **Interoperability** 62 | 63 | Connect agents built on different platforms (LangGraph, CrewAI, Semantic Kernel, custom solutions) to create powerful, composite AI systems. 64 | 65 | - :material-lan-connect:{ .lg .middle } **Complex Workflows** 66 | 67 | Enable agents to delegate sub-tasks, exchange information, and coordinate actions to solve complex problems that a single agent cannot. 68 | 69 | - :material-shield-key-outline:{ .lg .middle } **Secure & Opaque** 70 | 71 | Agents interact without needing to share internal memory, tools, or proprietary logic, ensuring security and preserving intellectual property. 72 | 73 |
74 | 75 | --- 76 | 77 | ## A2A and MCP: Complementary Protocols 78 | 79 | ![A2A MCP Graphic](assets/a2a-mcp-readme.png){width="60%"} 80 | {style="text-align: center; margin-bottom:1em; margin-top:1em;"} 81 | 82 | A2A and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) are complementary standards for building robust agentic applications: 83 | 84 | - **MCP (Model Context Protocol):** Connects agents to **tools, APIs, and resources** with structured inputs/outputs. Think of it as the way agents access their capabilities. 85 | - **A2A (Agent2Agent Protocol):** Facilitates **dynamic, multimodal communication between different agents** as peers. It's how agents collaborate, delegate, and manage shared tasks. 86 | 87 | [Learn more about A2A and MCP](./topics/a2a-and-mcp.md) 88 | 89 | --- 90 | 91 | ## Get Started with A2A 92 | 93 |
94 | 95 | - :material-book-open:{ .lg .middle } **Read the Introduction** 96 | 97 | Understand the core ideas behind A2A. 98 | 99 | [:octicons-arrow-right-24: What is A2A?](./topics/what-is-a2a.md) 100 | 101 | [:octicons-arrow-right-24: Key Concepts](./topics/key-concepts.md) 102 | 103 | - :material-file-document-outline:{ .lg .middle } **Dive into the Specification** 104 | 105 | Explore the detailed technical definition of the A2A protocol. 106 | 107 | [:octicons-arrow-right-24: Protocol Specification](./specification.md) 108 | 109 | - :material-application-cog-outline:{ .lg .middle } **Follow the Tutorials** 110 | 111 | Build your first A2A-compliant agent with our step-by-step Python quickstart. 112 | 113 | [:octicons-arrow-right-24: Python Tutorial](./tutorials/python/1-introduction.md) 114 | 115 | - :material-code-braces:{ .lg .middle } **Explore Code Samples** 116 | 117 | See A2A in action with sample clients, servers, and agent framework integrations. 118 | 119 | [:fontawesome-brands-github: GitHub Samples](https://github.com/a2aproject/a2a-samples) 120 | 121 | - :material-code-braces:{ .lg .middle } **Download a SDK** 122 | 123 | [:octicons-arrow-right-24: A2A Python SDK](https://github.com/a2aproject/a2a-python) 124 | [:octicons-arrow-right-24: A2A JS SDK](https://github.com/a2aproject/a2a-js) 125 | [:octicons-arrow-right-24: A2A Java SDK](https://github.com/a2aproject/a2a-java) 126 | [:octicons-arrow-right-24: A2A .NET SDK](https://github.com/a2aproject/a2a-dotnet) 127 | 128 |
129 | -------------------------------------------------------------------------------- /docs/partners.md: -------------------------------------------------------------------------------- 1 | --- 2 | hide: 3 | - navigation 4 | --- 5 | 6 | # Partners 7 | 8 | Below is a list of partners (and a link to their A2A announcement or blog post, 9 | if available) who are part of the A2A community and are helping build, codify, 10 | and adopt A2A as the standard protocol for AI agents to communicate and 11 | collaborate effectively with each other and with users. 12 | 13 | !!! note 14 | 15 | If you're interested in becoming a partner of A2A and getting your listing added to or updated on this page, let us know by [submitting this form](https://goo.gle/a2a-partner-form), and we'll contact you soon! 16 | 17 | - [Accelirate Inc](https://www.accelirate.com) 18 | - [Accenture](https://www.accenture.com) 19 | - [Activeloop](https://www.activeloop.ai/) 20 | - [Adobe](https://www.adobe.com) 21 | - [AI21 Labs](https://www.ai21.com/) 22 | - [AI71](https://ai71.ai/) 23 | - [Aisera](https://aisera.com/) 24 | - [Almawave.it](http://www.almawave.it) 25 | - [AliCloud](http://www.alibabacloud.com) 26 | - [ArcBlock](http://www.arcblock.io) 27 | - [Arize](https://arize.com/blog/arize-ai-and-future-of-agent-interoperability-embracing-googles-a2a-protocol/) 28 | - [Articul8](https://www.articul8.ai/news/unleashing-the-next-frontier-of-enterprise-ai-introducing-model-mesh-dock-and-inter-lock-and-our-a2-a-partnership-with-google) 29 | - [ask-ai.com](https://ask-ai.com) 30 | - [Atlassian](https://www.atlassian.com) 31 | - [Auth0](https://auth0.com/blog/auth0-google-a2a/) 32 | - [Autodesk](https://www.autodesk.com) 33 | - [AWS](https://aws.amazon.com/) 34 | - [Beekeeper](http://beekeeper.io) 35 | - [BCG](https://www.bcg.com) 36 | - [Block Inc](https://block.xyz/) 37 | - [Bloomberg LP](http://techatbloomberg.com/) 38 | - [BLUEISH Inc](https://www.blueish.co.jp/) 39 | - [BMC Software Inc](https://www.bmc.com/it-solutions/bmc-helix.html) 40 | - [Boomi](https://boomi.com/) 41 | - [Box](https://www.box.com) 42 | - [Bridge2Things Automation Process GmbH](http://bridge2things.at) 43 | - [Cafe 24](https://www.cafe24corp.com/en/company/about) 44 | - [C3 AI](https://c3.ai) 45 | - [Capgemini](https://www.capgemini.com) 46 | - [Chronosphere](https://chronosphere.io) 47 | - [Cisco](https://www.cisco.com/) 48 | - [Codimite PTE LTD](https://codimite.ai/) 49 | - [Cognigy](https://www.cognigy.com/) 50 | - [Cognizant](https://www.cognizant.com) 51 | - [Cohere](https://cohere.com) 52 | - [Collibra](https://www.collibra.com) 53 | - [Confluent](https://developer.confluent.io) 54 | - [Contextual](https://contextual.ai) 55 | - [Cotality](https://cotality.com) (fka Corelogic) 56 | - [Crubyt](https://www.crubyt.com) 57 | - [Cyderes](http://www.cyderes.com) 58 | - [Datadog](https://www.datadoghq.com) 59 | - [DataRobot](https://www.datarobot.com) 60 | - [DataStax](https://www.datastax.com) 61 | - [Decagon.ai](https://decagon.ai) 62 | - [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) 63 | - [Devnagri](https://devnagri.com) 64 | - [Deutsche Telekom](https://www.telekom.com/en) 65 | - [Dexter Tech Labs](http://www.dextertechlabs.com) 66 | - [Distyl.ai](https://distyl.ai) 67 | - [Elastic](https://www.elastic.co) 68 | - [Ema.co](https://ema.co) 69 | - [EPAM](https://www.epam.com) 70 | - [Eviden (Atos Group)](https://atos.net/) 71 | - [fractal.ai](https://fractal.ai/new) 72 | - [GenAI Nebula9.ai Solutions Pvt Ltd](http://nebula9.ai) 73 | - [Glean](https://www.glean.com) 74 | - [Global Logic](https://www.globallogic.com/) 75 | - [Gravitee](https://www.gravitee.io/) 76 | - [GrowthLoop](https://growthloop.com) 77 | - [Guru](http://www.getguru.com) 78 | - [Harness](https://harness.io) 79 | - [HCLTech](https://www.hcltech.com) 80 | - [Headwaters](https://www.headwaters.co.jp) 81 | - [Hellotars](https://hellotars.com) 82 | - [Hexaware](https://hexaware.com/) 83 | - [HUMAN](https://www.humansecurity.com/) 84 | - [Incorta](https://www.incorta.com) 85 | - [Infinitus](https://www.infinitus.ai/) 86 | - [InfoSys](https://www.infosys.com) 87 | - [Intuit](https://www.intuit.com) 88 | - [Iron Mountain](https://www.ironmountain.com/) 89 | - [JetBrains](https://www.jetbrains.com) 90 | - [JFrog](https://jfrog.com) 91 | - [Kakao](https://www.kakaocorp.com) 92 | - [King's College London](https://www.kcl.ac.uk/informatics) 93 | - [KPMG](https://kpmg.com/us/en/media/news/kpmg-google-cloud-alliance-expansion-agentspace-adoption.html) 94 | - [Kyndryl](http://www.kyndryl.com) 95 | - [LabelBox](https://labelbox.com) 96 | - [LangChain](https://www.langchain.com) 97 | - [LG CNS](http://www.lgcns.com) 98 | - [Livex.ai](https://livex.ai) 99 | - [LlamaIndex](https://x.com/llama_index/status/1912949446322852185) 100 | - [LTIMindTtree](https://www.ltimindtree.com) 101 | - [Lumeris](https://www.lumeris.com/) 102 | - [Lyzr.ai](https://lyzr.ai) 103 | - [Magyar Telekom](https://www.telekom.hu/) 104 | - [Microsoft](https://www.microsoft.com/en-us/microsoft-cloud/blog/2025/05/07/empowering-multi-agent-apps-with-the-open-agent2agent-a2a-protocol/) 105 | - [MindsDB](https://mindsdb.com/blog/mindsdb-now-supports-the-agent2agent-(a2a)-protocol) 106 | - [McKinsey](https://www.mckinsey.com) 107 | - [MongoDB](https://www.mongodb.com) 108 | - [Monite](https://monite.com/) 109 | - [Neo4j](https://neo4j.com) 110 | - [New Relic](https://newrelic.com) 111 | - [Nisum](http://www.nisum.com) 112 | - [Noorle Inc](http://www.noorle.com) 113 | - [Optimizely Inc](https://www.optimizely.com/) 114 | - [Oracle / NetSuite](https://www.oracle.com/netsuite) 115 | - [Palo Alto Networks](https://www.paloaltonetworks.com/) 116 | - [PancakeAI](https://www.pancakeai.tech/) 117 | - [Pendo](https://www.pendo.io) 118 | - [PerfAI.ai](https://perfai.ai) 119 | - [Personal AI](https://personal.ai) 120 | - [Poppulo](https://www.poppulo.com/blog/poppulo-google-a2a-the-future-of-workplace-communication) 121 | - [Productive Edge](https://www.productiveedge.com/) 122 | - [Proofs](https://proofs.io) 123 | - [Publicis Sapient](https://www.publicissapient.com/) 124 | - [PWC](https://www.pwc.com) 125 | - [Quantiphi](https://www.quantiphi.com) 126 | - [Radix](https://radix.website/) 127 | - [RagaAI Inc](https://raga.ai/) 128 | - [Red Hat](https://www.redhat.com) 129 | - [Reltio Inc](http://www.reltio.com) 130 | - [S&P](https://www.spglobal.com) 131 | - [Sage](https://www.sage.com/en-us/) 132 | - [Salesforce](https://www.salesforce.com) 133 | - [SAP](https://news.sap.com/2025/04/sap-google-cloud-enterprise-ai-open-agent-collaboration-model-choice-multimodal-intelligence/) 134 | - [Sayone Technologies](https://www.sayonetech.com/) 135 | - [ServiceNow](https://www.servicenow.com) 136 | - [Siemens AG](https://siemens.com/) 137 | - [SoftBank Corp](https://www.softbank.jp/en//) 138 | - [Solace](https://solace.com/products/agent-mesh/) 139 | - [Solo.io](https://www.solo.io/) 140 | - [Stacklok, Inc](https://stacklok.com) 141 | - [Supertab](https://www.supertab.co/post/supertab-connect-partners-with-google-cloud-to-enable-ai-agents) 142 | - [Suzega](https://suzega.com/) 143 | - [TCS](https://www.tcs.com) 144 | - [Tech Mahindra](https://www.techmahindra.com/) 145 | - [Telefonica](https://www.telefonica.com/) 146 | - [Test Innovation Technology](https://www.test-it.com) 147 | - [the artinet project](https://artinet.io/) 148 | - [Think41](http://www.think41.com) 149 | - [Thoughtworks](https://www.thoughtworks.com/) 150 | - [Tredence](http://www.tredence.com) 151 | - [Two Tall Totems Ltd. DBA TTT Studios](https://ttt.studio) 152 | - [Typeface](https://typeface.ai) 153 | - [UKG](https://www.ukg.com) 154 | - [UiPath](https://www.uipath.com/newsroom/uipath-launches-first-enterprise-grade-platform-for-agentic-automation) 155 | - [Upwork, Inc.](https://www.upwork.com/) 156 | - [Ushur, Inc.](http://ushur.ai) 157 | - [Valle AI](http://www.valleai.com.br) 158 | - [Valtech](https://www.valtech.com/) 159 | - [Vervelo](https://www.vervelo.com/) 160 | - [VoltAgent](https://voltagent.dev/) 161 | - [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) 162 | - [Wipro](https://www.wipro.com) 163 | - [Workday](https://www.workday.com) 164 | - [Writer](https://writer.com) 165 | - [Zenity](https://zenity.io) 166 | - [Zeotap](https://www.zeotap.com) 167 | - [Zocket Technologies , Inc.](https://zocket.ai) 168 | - [Zoom](https://www.zoom.us) 169 | - [zyprova](http://www.zyprova.com) 170 | -------------------------------------------------------------------------------- /docs/roadmap.md: -------------------------------------------------------------------------------- 1 | # A2A protocol roadmap 2 | 3 | **Last updated:** Jul 16, 2025 4 | 5 | ## Near-term initiatives 6 | 7 | - Release `0.3` version of the protocol which we intend to keep supported and without breaking changes for a significant amount of time with backward compatibility of the SDKs starting at version `0.3`. As part of this release there are a few known breaking changes including: 8 | - Update the `/.well-known/agent.json` path for hosting Agent Cards to `/.well-known/agent-card.json` based on feedback from IANA. 9 | - Refactor class fields to be more Pythonic and adopt `snake_case`. [PR 199](https://github.com/a2aproject/a2a-python/pull/199) 10 | - Solidify the support for [A2A extensions](topics/extensions.md) with SDK support (starting with the Python SDK) and publishing sample extensions. 11 | - Introduce support for signed Agent Cards [Discussion 199](https://github.com/a2aproject/A2A/discussions/199#discussioncomment-13770576) to allow verifying the integrity of Agent Card content. 12 | - Enhance the client side support in SDK (starting with Python) to expose ready-to-use A2A clients, streamlined auth handling and improved handling of tasks. 13 | 14 | To review recent protocol changes see [Release Notes](https://github.com/a2aproject/A2A/releases). 15 | 16 | ## Longer term (3-6 month period) roadmap 17 | 18 | ### Governance 19 | 20 | The protocol has been [donated](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents) to the Linux Foundation. The TSC is working on implementing a governance structure that prioritizes community-led development with standardized processes for contributing to the specification, SDKs and tooling. As part of the effort there will be dedicated working groups created for specific areas of the protocol. 21 | 22 | ### Agent Registry 23 | 24 | Agent Registry enables the discovery of agents and is a critical component of a multi-agent system. There is an active and ongoing discussion in the community around the latest [Discussion 741](https://github.com/a2aproject/A2A/discussions/741). 25 | 26 | ### Validation 27 | 28 | As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation which the group will continue to enhance in the coming months. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK). 29 | 30 | ### SDKs 31 | 32 | A2A Project currently hosts SDKs in four languages (Python, JS, Java, .NET) and contributors are adding more including Go (in progress). 33 | 34 | ### Community best practices 35 | 36 | 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. 37 | -------------------------------------------------------------------------------- /docs/sdk/python/conf.py: -------------------------------------------------------------------------------- 1 | # -- Project information ----------------------------------------------------- 2 | 3 | project = 'a2a-sdk' 4 | copyright = '2025, Google LLC' 5 | author = 'Google LLC' 6 | 7 | # -- General configuration --------------------------------------------------- 8 | 9 | extensions = [ 10 | 'sphinx.ext.autodoc', 11 | 'sphinx.ext.autosummary', # Automatically generate summaries 12 | 'sphinx.ext.napoleon', # Support for Google-style docstrings 13 | 'myst_parser', # For Markdown support 14 | ] 15 | 16 | # Tell autosummary to generate stub files 17 | autosummary_generate = True 18 | 19 | templates_path = ['_templates'] 20 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 21 | 22 | # -- Options for HTML output ------------------------------------------------- 23 | 24 | html_theme = 'furo' 25 | 26 | autodoc_member_order = 'alphabetical' 27 | -------------------------------------------------------------------------------- /docs/sdk/python/index.rst: -------------------------------------------------------------------------------- 1 | A2A Python SDK Reference 2 | ======================== 3 | 4 | This page contains the SDK documentation for the ``a2a-sdk`` Python package. 5 | 6 | .. code-block:: sh 7 | 8 | pip install a2a-sdk 9 | 10 | .. toctree:: 11 | :maxdepth: 4 12 | 13 | a2a 14 | -------------------------------------------------------------------------------- /docs/stylesheets/custom.css: -------------------------------------------------------------------------------- 1 | /** 2 | * Copyright 2025 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /* Index page styling */ 18 | 19 | .md-grid { 20 | max-width: 80%; 21 | } 22 | 23 | .footer { 24 | padding-bottom: 30vh; 25 | } 26 | 27 | .centered-logo-text-group { 28 | display: inline-flex; 29 | align-items: center; 30 | gap: 1.5em; 31 | margin-bottom: 0.5em; 32 | vertical-align: middle; 33 | } 34 | 35 | .centered-logo-text-group img { 36 | height: auto; 37 | } 38 | 39 | .centered-logo-text-group h1 { 40 | margin: 0; 41 | text-align: left; 42 | } 43 | 44 | .install-command-container { 45 | max-width: 600px; 46 | margin: 2.5em auto; 47 | padding: 1.5em 2em; 48 | background-color: var(--md-code-bg-color, #f5f5f5); 49 | border-radius: 8px; 50 | text-align: center; 51 | box-shadow: 0 3px 6px rgb(0 0 0 / 5%); 52 | border-left: 5px solid var(--md-primary-fg-color, #526cfe); 53 | margin-top: 30px; 54 | } 55 | 56 | .install-command-container p { 57 | font-size: 1.1em; 58 | color: var(--md-default-fg-color); 59 | margin-bottom: -10px; 60 | margin-top: -10px; 61 | } 62 | 63 | .install-command-container p code { 64 | font-size: 1.1em; 65 | font-weight: 600; 66 | padding: 0.3em 0.6em; 67 | background-color: var(--md-code-fg-color--light); 68 | border-radius: 4px; 69 | display: inline-block; 70 | line-height: 1.4; 71 | } 72 | 73 | .announce .md-button { 74 | font-size: 0.8em; 75 | padding: 0.3em 1em; 76 | margin-left: 0.5em; 77 | } 78 | 79 | h1#agent2agent-a2a-protocol { 80 | display: none; 81 | } 82 | 83 | figure.hero { 84 | margin-top: 0; 85 | margin-bottom: 10px; 86 | } 87 | 88 | figure.hero figcaption { 89 | max-width: 100%; 90 | width: 100%; 91 | margin-bottom: 0; 92 | text-align: left; 93 | } 94 | -------------------------------------------------------------------------------- /docs/topics/a2a-and-mcp.md: -------------------------------------------------------------------------------- 1 | # A2A and MCP: Complementary Protocols for Agentic Systems 2 | 3 | ## A2A ❤️ MCP 4 | 5 | In the landscape of AI agent development, two key types of protocols are emerging to facilitate interoperability: those for connecting agents to **tools and resources**, and those for enabling **agent-to-agent collaboration**. The Agent2Agent (A2A) Protocol and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) address these distinct but related needs. 6 | 7 | **TL;DR;** Agentic applications need both A2A and MCP. We recommend MCP for tools and A2A for agents. 8 | 9 | ## Why Different Protocols? 10 | 11 | The distinction arises from the nature of what an agent interacts with: 12 | 13 | - **Tools & Resources:** 14 | 15 | - These are typically primitives with well-defined, structured inputs and outputs. They perform specific, often stateless, functions (e.g., a calculator, a database query API, a weather lookup service). 16 | - Their behavior is generally predictable and transactional. 17 | - Interaction is often a single request-response cycle. 18 | 19 | - **Agents:** 20 | - These are more autonomous systems. They can reason, plan, use multiple tools, maintain state over longer interactions, and engage in complex, often multi-turn dialogues to achieve novel or evolving tasks. 21 | - Their behavior can be emergent and less predictable than a simple tool. 22 | - Interaction often involves ongoing tasks, context sharing, and negotiation. 23 | 24 | Agentic applications need to leverage both: agents use tools to gather information and perform actions, and agents collaborate with other agents to tackle broader, more complex goals. 25 | 26 | ## Model Context Protocol (MCP) 27 | 28 | - **Focus:** MCP standardizes how AI models and agents connect to and interact with **tools, APIs, data sources, and other external resources.** 29 | - **Mechanism:** It defines a structured way to describe tool capabilities (akin to function calling in Large Language Models), pass inputs to them, and receive structured outputs. 30 | - **Use Cases:** 31 | - Enabling an LLM to call an external API (e.g., fetch current stock prices). 32 | - Allowing an agent to query a database with specific parameters. 33 | - Connecting an agent to a set of predefined functions or services. 34 | - **Ecosystem:** MCP aims to create an ecosystem where tool providers can easily expose their services to various AI models and agent frameworks, and agent developers can easily consume these tools in a standardized way. 35 | 36 | ## Agent2Agent Protocol (A2A) 37 | 38 | - **Focus:** A2A standardizes how independent, often opaque, **AI agents communicate and collaborate with each other as peers.** 39 | - **Mechanism:** It provides an application-level protocol for agents to: 40 | - Discover each other's high-level skills and capabilities (via Agent Cards). 41 | - Negotiate interaction modalities (text, files, structured data). 42 | - Manage shared, stateful, and potentially long-running tasks. 43 | - Exchange conversational context, instructions, and complex, multi-part results. 44 | - **Use Cases:** 45 | - A customer service agent delegating a complex billing inquiry to a specialized billing agent, maintaining context of the customer interaction. 46 | - A travel planning agent coordinating with separate flight, hotel, and activity booking agents, managing a multi-stage booking process. 47 | - Agents exchanging information and status updates for a collaborative project that evolves over time. 48 | - **Key Difference from Tool Interaction:** A2A allows for more dynamic, stateful, and potentially multi-modal interactions than typically seen with simple tool calls. Agents using A2A communicate _as agents_ (or on behalf of users) rather than just invoking a discrete function. 49 | 50 | ## How A2A and MCP Complement Each Other 51 | 52 | A2A and MCP are not mutually exclusive; they are highly complementary and address different layers of an agentic system's interaction needs. 53 | 54 |
55 | 56 | ![Diagram showing A2A and MCP working together. A User interacts with Agent A via A2A. Agent A interacts with Agent B via A2A. Agent B uses MCP to interact with Tool 1 and Tool 2.](../assets/a2a-mcp.png){width="80%"} 57 | 58 | _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._ 59 | 60 |
61 | 62 | ### Example Scenario: The Auto Repair Shop 63 | 64 | > Consider an auto repair shop staffed by autonomous AI agent "mechanics" who use special-purpose tools (such as vehicle jacks, multimeters, and socket wrenches) to diagnose and repair problems. The workers often have to diagnose and repair problems they have not seen before. The repair process can involve extensive conversations with a customer, research, and working with part suppliers. 65 | 66 | 1. **Customer Interaction (User-to-Agent via A2A):** 67 | 68 | - A customer (or their primary assistant agent) uses A2A to communicate with the "Shop Manager" agent: _"My car is making a rattling noise."_ 69 | - The Shop Manager agent uses A2A for a multi-turn diagnostic conversation: _"Can you send a video of the noise?"_, _"I see some fluid leaking. How long has this been happening?"_ 70 | 71 | 2. **Internal Tool Usage (Agent-to-Tool via MCP):** 72 | 73 | - The Mechanic agent, assigned the task by the Shop Manager, needs to diagnose the issue. It uses MCP to interact with its specialized tools: 74 | - MCP call to a "Vehicle Diagnostic Scanner" tool: `scan_vehicle_for_error_codes(vehicle_id='XYZ123')`. 75 | - MCP call to a "Repair Manual Database" tool: `get_repair_procedure(error_code='P0300', vehicle_make='Toyota', vehicle_model='Camry')`. 76 | - MCP call to a "Platform Lift" tool: `raise_platform(height_meters=2)`. 77 | 78 | 3. **Supplier Interaction (Agent-to-Agent via A2A):** 79 | - The Mechanic agent determines a specific part is needed. It uses A2A to communicate with a "Parts Supplier" agent: _"Do you have part #12345 in stock for a Toyota Camry 2018?"_ 80 | - The Parts Supplier agent, also an A2A-compliant system, responds, potentially leading to an order. 81 | 82 | In this example: 83 | 84 | - **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. 85 | - **MCP** enables the mechanic agent to use its specific, structured tools to perform its diagnostic and repair functions. 86 | 87 | ## Representing A2A Agents as MCP Resources 88 | 89 | It's conceivable that an A2A Server (a remote agent) could also 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 via an MCP-style tool description (perhaps derived from its Agent Card). 90 | 91 | 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. 92 | 93 | By leveraging both A2A for inter-agent collaboration and MCP for tool integration, developers can build more powerful, flexible, and interoperable AI systems. 94 | -------------------------------------------------------------------------------- /docs/topics/agent-discovery.md: -------------------------------------------------------------------------------- 1 | # Agent Discovery in A2A 2 | 3 | For AI agents to collaborate using the Agent2Agent (A2A) protocol, they first need to find each other and understand what capabilities the other agents offer. A2A standardizes the format of an agent's self-description through the **[Agent Card](../specification.md#5-agent-discovery-the-agent-card)**. However, the methods for discovering these Agent Cards can vary depending on the environment and requirements. 4 | 5 | ## The Role of the Agent Card 6 | 7 | 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 discovery and initiating interaction. Key information typically included in an Agent Card: 8 | 9 | - **Identity:** `name`, `description`, `provider` information. 10 | - **Service Endpoint:** The `url` where the A2A service can be reached. 11 | - **A2A Capabilities:** Supported protocol features like `streaming` or `pushNotifications`. 12 | - **Authentication:** Required authentication `schemes` (e.g., "Bearer", "OAuth2") to interact with the agent. 13 | - **Skills:** A list of specific tasks or functions the agent can perform (`AgentSkill` objects), including their `id`, `name`, `description`, `inputModes`, `outputModes`, and `examples`. 14 | 15 | Client agents parse the Agent Card to determine if a remote agent is suitable for a given task, how to structure requests for its skills, and how to communicate with it securely. 16 | 17 | ## Discovery Strategies 18 | 19 | Here are common strategies for how a client agent might discover the Agent Card of a remote agent: 20 | 21 | ### 1. Well-Known URI 22 | 23 | This is a recommended approach for public agents or agents intended for broad discoverability within a specific domain. 24 | 25 | - **Mechanism:** A2A Servers host their Agent Card at a standardized, "well-known" path on their domain. 26 | - **Standard Path:** `https://{agent-server-domain}/.well-known/agent-card.json` (following the principles of [RFC 8615](https://www.ietf.org/rfc/rfc8615.txt) for well-known URIs). 27 | - **Process:** 28 | 1. A client agent knows or programmatically discovers the domain of a potential A2A Server (e.g., `smart-thermostat.example.com`). 29 | 2. The client performs an HTTP `GET` request to `https://smart-thermostat.example.com/.well-known/agent-card.json`. 30 | 3. If the Agent Card exists and is accessible, the server returns it as a JSON response. 31 | - **Advantages:** Simple, standardized, and enables automated discovery by crawlers or systems that can resolve domains. Effectively reduces the discovery problem to "find the agent's domain." 32 | - **Considerations:** Best suited for agents intended for open discovery or discovery within an organization that controls the domain. The endpoint serving the Agent Card may itself require authentication if the card contains sensitive information. 33 | 34 | ### 2. Curated Registries (Catalog-Based Discovery) 35 | 36 | For enterprise environments, marketplaces, or specialized ecosystems, Agent Cards can be published to and discovered via a central registry or catalog. 37 | 38 | - **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, desired capabilities). 39 | - **Process:** 40 | 1. A2A Servers (or their administrators) register their Agent Cards with the registry service. The mechanism for this registration is outside the scope of the A2A protocol itself. 41 | 2. Client agents query the registry's API (e.g., "find agents with 'image-generation' skill that support streaming"). 42 | 3. The registry returns a list of matching Agent Cards or references to them. 43 | - **Advantages:** 44 | - Centralized management, curation, and governance of available agents. 45 | - Facilitates discovery based on functional capabilities rather than just domain names. 46 | - Can implement access controls, policies, and trust mechanisms at the registry level. 47 | - Enables scenarios like company-specific or team-specific agent catalogs, or public marketplaces of A2A-compliant agents. 48 | - **Considerations:** Requires an additional registry service. The A2A protocol does not currently define a standard API for such registries, though this is an area of potential future exploration and community standardization. 49 | 50 | ### 3. Direct Configuration / Private Discovery 51 | 52 | In many scenarios, especially within tightly coupled systems, for private agents, or during development and testing, clients might be directly configured with Agent Card information or a URL to fetch it. 53 | 54 | - **Mechanism:** The client application has hardcoded Agent Card details, reads them from a local configuration file, receives them through an environment variable, or fetches them from a private, proprietary API endpoint known to the client. 55 | - **Process:** This is highly specific to the application's deployment and configuration strategy. 56 | - **Advantages:** Simple and effective for known, static relationships between agents or when dynamic discovery is not a requirement. 57 | - **Considerations:** Less flexible for discovering new or updated agents dynamically. Changes to the remote agent's card might require re-configuration of the client. Proprietary API-based discovery is not standardized by A2A. 58 | 59 | ## Securing Agent Cards 60 | 61 | Agent Cards themselves can sometimes contain information that should be protected, such as: 62 | 63 | - The `url` of an internal-only or restricted-access agent. 64 | - Details in the `authentication.credentials` field if it's used for scheme-specific, non-secret information (e.g., an OAuth token URL). Storing actual plaintext secrets in an Agent Card is **strongly discouraged**. 65 | - Descriptions of sensitive or internal skills. 66 | 67 | **Protection Mechanisms:** 68 | 69 | - **Access Control on the Endpoint:** The HTTP endpoint serving the Agent Card (whether it's the `/.well-known/agent-card.json` path, a registry API, or a custom URL) should be secured using standard web practices if the card is not intended for public, unauthenticated access. 70 | - **mTLS:** Require mutual TLS for client authentication if appropriate for the trust model. 71 | - **Network Restrictions:** Limit access to specific IP ranges, VPCs, or private networks. 72 | - **Authentication:** Require standard HTTP authentication (e.g., OAuth 2.0 Bearer token, API Key) to access the Agent Card itself. 73 | - **Selective Disclosure by Registries:** Agent registries can implement logic to return different Agent Cards or varying levels of detail based on the authenticated client's identity and permissions. For example, a public query might return a limited card, while an authenticated partner query might receive a card with more details. 74 | 75 | It's crucial to remember that if an Agent Card were to contain sensitive data (again, **not recommended** for secrets), the card itself **must never** be available without strong authentication and authorization. The A2A protocol encourages authentication schemes where the client obtains dynamic credentials out-of-band, rather than relying on static secrets embedded in the Agent Card. 76 | 77 | ## Future Considerations 78 | 79 | The A2A community may explore standardizing aspects of registry interactions or more advanced, semantic discovery protocols in the future. Feedback and contributions in this area are welcome to enhance the discoverability and interoperability of A2A agents. 80 | -------------------------------------------------------------------------------- /docs/topics/enterprise-ready.md: -------------------------------------------------------------------------------- 1 | # Enterprise-Ready Features for A2A Agents 2 | 3 | The Agent2Agent (A2A) protocol is designed with enterprise requirements at its core. Instead of inventing new, proprietary standards for security and operations, A2A aims to integrate seamlessly with existing enterprise infrastructure and widely adopted best practices. A2A treats remote agents as standard, HTTP-based enterprise applications. This approach allows organizations to leverage their existing investments and expertise in security, monitoring, governance, and identity management. 4 | 5 | A key principle of A2A is that agents are typically "opaque" – they do not share internal memory, tools, or direct resource access with each other. This opacity naturally aligns with standard client/server security paradigms. 6 | 7 | ## 1. Transport Level Security (TLS) 8 | 9 | Ensuring the confidentiality and integrity of data in transit is fundamental. 10 | 11 | - **HTTPS Mandate:** All A2A communication in production environments **MUST** occur over HTTPS. 12 | - **Modern TLS Standards:** Implementations **SHOULD** use modern TLS versions (TLS 1.2 or higher is recommended) with strong, industry-standard cipher suites to protect data from eavesdropping and tampering. 13 | - **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. This prevents man-in-the-middle attacks. 14 | 15 | ## 2. Authentication 16 | 17 | A2A delegates authentication to standard web mechanisms, primarily relying on HTTP headers and established standards like OAuth2 and OpenID Connect. Authentication requirements are advertised by the A2A Server in its [Agent Card](../specification.md#5-agent-discovery-the-agent-card). 18 | 19 | - **No In-Payload Identity:** A2A protocol payloads (JSON-RPC messages) do **not** carry user or client identity information. Identity is established at the transport/HTTP layer. 20 | - **Agent Card Declaration:** The A2A Server's `AgentCard` describes the authentication `schemes` it supports in its `security` field. Each named scheme in this field is an identifier specific to the card. The details for each named scheme, including the scheme type, can be provided in the `securitySchemes` field of the Agent Card. The supported names of the scheme types ("apiKey", "http", "oauth2", "openIdConnect") align with those defined in the [OpenAPI Specification for authentication](https://swagger.io/docs/specification/authentication/). 21 | - **Out-of-Band Credential Acquisition:** The A2A Client is responsible for obtaining the necessary credential materials (e.g., OAuth 2.0 tokens, either in JWT format or some other format; API keys; or other) through processes external to the A2A protocol itself. This could involve OAuth flows (authorization code, client credentials), secure key distribution, etc. 22 | - **HTTP Header Transmission:** Credentials **MUST** be transmitted in standard HTTP headers as per the requirements of the chosen authentication scheme (e.g., `Authorization: Bearer `, `API-Key: `). 23 | - **Server-Side Validation:** The A2A Server **MUST** authenticate **every** incoming request based on the credentials provided in the HTTP headers and its declared requirements. 24 | - If authentication fails or is missing, the server **SHOULD** respond with standard HTTP status codes such as `401 Unauthorized` or `403 Forbidden`. 25 | - A `401 Unauthorized` response **SHOULD** include a `WWW-Authenticate` header indicating the required scheme(s), guiding the client on how to authenticate correctly. 26 | - **In-Task Authentication (Secondary Credentials):** If an agent, during a task, requires additional credentials for a _different_ system (e.g., to access a specific tool on behalf of the user), A2A recommends: 27 | 1. The A2A Server transitions the A2A task to the `input-required` state. 28 | 2. The `TaskStatus.message` (often using a `DataPart`) should provide details about the required authentication for the secondary system, potentially using an `AuthenticationInfo`-like structure. 29 | 3. The A2A Client then obtains these new credentials out-of-band for the secondary system. These credentials might be provided back to the A2A Server (if it's proxying the request) or used by the client to interact directly with the secondary system. 30 | 31 | ## 3. Authorization 32 | 33 | 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. 34 | 35 | - **Granular Control:** Authorization **SHOULD** be applied based on the authenticated identity (which could represent an end user, a client application, or both). 36 | - **Skill-Based Authorization:** Access can be controlled on a per-skill basis, as advertised in the Agent Card. For example, specific OAuth scopes might grant an authenticated client access to invoke certain skills but not others. 37 | - **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. 38 | - **Principle of Least Privilege:** Grant only the necessary permissions required for a client or user to perform their intended operations via the A2A interface. 39 | 40 | ## 4. Data Privacy and Confidentiality 41 | 42 | - **Sensitivity Awareness:** Implementers must be acutely aware of the sensitivity of data exchanged in `Message` and `Artifact` parts of A2A interactions. 43 | - **Compliance:** Ensure compliance with relevant data privacy regulations (e.g., GDPR, CCPA, HIPAA, depending on the domain and data). 44 | - **Data Minimization:** Avoid including or requesting unnecessarily sensitive information in A2A exchanges. 45 | - **Secure Handling:** Protect data both in transit (via TLS, as mandated) and at rest (if persisted by agents) according to enterprise data security policies and regulatory requirements. 46 | 47 | ## 5. Tracing, Observability, and Monitoring 48 | 49 | A2A's reliance on HTTP allows for straightforward integration with standard enterprise tracing, logging, and monitoring tools. 50 | 51 | - **Distributed Tracing:** 52 | - A2A Clients and Servers **SHOULD** participate in distributed tracing systems (e.g., OpenTelemetry, Jaeger, Zipkin). 53 | - Trace context (trace IDs, span IDs) **SHOULD** be propagated via standard HTTP headers (e.g., W3C Trace Context headers like `traceparent` and `tracestate`). 54 | - This enables end-to-end visibility of requests as they flow across multiple agents and underlying services, which is invaluable for debugging and performance analysis. 55 | - **Comprehensive Logging:** Implement detailed logging on both client and server sides. Logs should include relevant identifiers such as `taskId`, `sessionId`, correlation IDs, and trace context to facilitate troubleshooting and auditing. 56 | - **Metrics:** A2A Servers should expose key operational metrics (e.g., request rates, error rates, task processing latency, resource utilization) to enable performance monitoring, alerting, and capacity planning. These can be integrated with systems like Prometheus or Google Cloud Monitoring. 57 | - **Auditing:** Maintain audit trails for significant events, such as task creation, critical state changes, and actions performed by agents, especially those involving sensitive data access, modifications, or high-impact operations. 58 | 59 | ## 6. API Management and Governance 60 | 61 | For A2A Servers exposed externally, across organizational boundaries, or even within large enterprises, integration with API Management solutions is highly recommended. This can provide: 62 | 63 | - **Centralized Policy Enforcement:** Consistent application of security policies (authentication, authorization), rate limiting, and quotas. 64 | - **Traffic Management:** Load balancing, routing, and mediation. 65 | - **Analytics and Reporting:** Insights into agent usage, performance, and trends. 66 | - **Developer Portals:** Facilitate discovery of A2A-enabled agents, provide documentation (including Agent Cards), and streamline onboarding for client developers. 67 | 68 | By adhering to these enterprise-grade practices, A2A implementations can be deployed securely, reliably, and manageably within complex organizational environments, fostering trust and enabling scalable inter-agent collaboration. 69 | -------------------------------------------------------------------------------- /docs/topics/key-concepts.md: -------------------------------------------------------------------------------- 1 | # Key Concepts in A2A 2 | 3 | The Agent2Agent (A2A) protocol is built around a set of core concepts that define how agents interact. Understanding these concepts is crucial for developing or integrating with A2A-compliant systems. 4 | 5 | ![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;" } 6 | 7 | ## Core Actors 8 | 9 | - **User:** The end user (human or automated service) who initiates a request or goal that requires agent assistance. 10 | - **A2A Client (Client Agent):** An application, service, or another AI agent that acts on behalf of the user to request actions or information from a remote agent. The client initiates communication using the A2A protocol. 11 | - **A2A Server (Remote Agent):** An AI agent or agentic system that exposes an HTTP endpoint implementing the A2A protocol. It receives requests from clients, processes tasks, and returns results or status updates. The remote agent operates as an "opaque" system from the client's perspective, meaning the client doesn't need to know its internal workings, memory, or tools. 12 | 13 | ## Fundamental Communication Elements 14 | 15 | - **Agent Card:** 16 | 17 | - A JSON metadata document, typically discoverable at a well-known URL (e.g., `/.well-known/agent-card.json`), that describes an A2A Server. 18 | - It details the agent's identity (name, description), service endpoint URL, version, supported A2A capabilities (like streaming or push notifications), specific skills it offers, default input/output modalities, and authentication requirements. 19 | - Clients use the Agent Card to discover agents and understand how to interact with them securely and effectively. 20 | - See details in the [Protocol Specification: Agent Card](../specification.md#5-agent-discovery-the-agent-card). 21 | 22 | - **Task:** 23 | 24 | - When a client sends a message to an agent, the agent might determine that fulfilling the request requires a stateful task to be completed (e.g., "generate a report," "book a flight," "answer a question"). 25 | - Each task has a unique ID defined by the agent and progresses through a defined lifecycle (e.g., `submitted`, `working`, `input-required`, `completed`, `failed`). 26 | - Tasks are stateful and can involve multiple exchanges (messages) between the client and the server. 27 | - See details in the [Life of a Task](./life-of-a-task.md). 28 | - Protocol specification: [Task Object](../specification.md#61-task-object). 29 | 30 | - **Message:** 31 | 32 | - Represents a single turn or unit of communication between a client and an agent. 33 | - Messages have a `role` (either `"user"` for client-sent messages or `"agent"` for server-sent messages) and contain one or more `Part` objects that carry the actual content. `messageId` part of the Message object is a unique identifier for each message set by the sender of the message. 34 | - Used for conveying instructions, context, questions, answers, or status updates that are not necessarily formal `Artifacts` that are part of a `Task`. 35 | - See details in the [Protocol Specification: Message Object](../specification.md#64-message-object). 36 | 37 | - **Part:** 38 | 39 | - The fundamental unit of content within a `Message` or an `Artifact`. Each part has a specific `type` and can carry different kinds of data: 40 | - `TextPart`: Contains plain textual content. 41 | - `FilePart`: Represents a file, which can be transmitted as inline base64-encoded bytes or referenced via a URI. Includes metadata like filename and Media Type. 42 | - `DataPart`: Carries structured JSON data, useful for forms, parameters, or any machine-readable information. 43 | - See details in the [Protocol Specification: Part Union Type](../specification.md#65-part-union-type). 44 | 45 | - **Artifact:** 46 | - Represents a tangible output or result generated by the remote agent during the processing of a task. 47 | - Examples include generated documents, images, spreadsheets, structured data results, or any other self-contained piece of information that is a direct result of the task. 48 | - Tasks in completed state SHOULD use artifact objects for returning the generated output to the clients. 49 | - Artifacts are composed of one or more `Part` objects and can be streamed incrementally. 50 | - See details in the [Protocol Specification: Artifact Object](../specification.md#67-artifact-object). 51 | 52 | ## Interaction Mechanisms 53 | 54 | - **Request/Response (Polling):** 55 | 56 | - The client sends a request (e.g., using the `message/send` RPC method) and receives a response from the server. 57 | - If the interaction requires a stateful long-running task, the server might initially respond with a `working` status. The client would then periodically call `tasks/get` to poll for updates until the task reaches a terminal state (e.g., `completed`, `failed`). 58 | 59 | - **Streaming (Server-Sent Events - SSE):** 60 | 61 | - For tasks that produce results incrementally or provide real-time progress updates. 62 | - The client initiates an interaction with the server using `message/stream`. 63 | - The server responds with an HTTP connection that remains open, over which it sends a stream of Server-Sent Events (SSE). 64 | - These events can be `Task`, `Message`, or `TaskStatusUpdateEvent` (for status changes) or `TaskArtifactUpdateEvent` (for new or updated artifact chunks). 65 | - This requires the server to advertise the `streaming` capability in its Agent Card. 66 | - Learn more about [Streaming & Asynchronous Operations](./streaming-and-async.md). 67 | 68 | - **Push Notifications:** 69 | - For very long-running tasks or scenarios where maintaining a persistent connection (like SSE) is impractical. 70 | - The client can provide a webhook URL when initiating a task (or by calling `tasks/pushNotificationConfig/set`). 71 | - When the task status changes significantly (e.g., completes, fails, or requires input), the server can send an asynchronous notification (an HTTP POST request) to this client-provided webhook. 72 | - This requires the server to advertise the `pushNotifications` capability in its Agent Card. 73 | - Learn more about [Streaming & Asynchronous Operations](./streaming-and-async.md). 74 | 75 | ## Agent Response: Task or Message 76 | 77 | See details in the [Life of a Task](./life-of-a-task.md). 78 | 79 | ## Other Important Concepts 80 | 81 | - **Context (`contextId`):** A server-generated identifier that can be used to logically group multiple related `Task` objects, providing context across a series of interactions. 82 | - **Transport and Format:** A2A communication occurs over HTTP(S). JSON-RPC 2.0 is used as the payload format for all requests and responses. 83 | - **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 via HTTP headers, separate from the A2A protocol messages themselves. 84 | - Learn more about [Enterprise-Ready Features](./enterprise-ready.md). 85 | - **Agent Discovery:** The process by which clients find Agent Cards to learn about available A2A Servers and their capabilities. 86 | - Learn more about [Agent Discovery](./agent-discovery.md). 87 | - **Extensions:** A2A allows agents to declare custom protocol extensions as part of their AgentCard. 88 | - More documentation coming soon. 89 | 90 | By understanding these core components and mechanisms, developers can effectively design, implement, and utilize A2A for building interoperable and collaborative AI agent systems. 91 | -------------------------------------------------------------------------------- /docs/topics/life-of-a-task.md: -------------------------------------------------------------------------------- 1 | # Life of a Task 2 | 3 | When a message is sent to an agent, it can choose to reply with either: 4 | 5 | - A stateless `Message`. 6 | - A stateful `Task` followed by zero or more `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent`. 7 | 8 | If the response is a `Message`, the interaction is completed. On the other hand, if the response is a `Task`, then the task will be processed by the agent, until it is in a interrupted state (`input-required` or `auth-required`) or a terminal state (`completed`, `cancelled`, `rejected` or `failed`). 9 | 10 | ## Context 11 | 12 | A `contextId` logically composes many `Task` objects and independent `Message` objects. If the A2A agent uses an LLM internally, it can utilize the `contextId` to manage the LLM context. 13 | 14 | For the first message, the agent responds with a server-generated `contextId`. If the agent creates a task, it will also include a server-generated `taskId`. Subsequent client messages can include the same `contextId` to continue the interaction, and optionally the `taskId` to continue a specific task. 15 | 16 | `contextId` allows collaboration over a goal or share a single contextual session across multiple tasks. 17 | 18 | ## Agent: Message or a Task 19 | 20 | Messages can be used for trivial interactions which do not require long-running processing or collaboration. An agent can use messages to negotiate the acceptance of a task. Once an agent maps the intent of an incoming message to a supported capability, it can reply back with a `Task`. 21 | 22 | So conceptually there can be three levels of agents: 23 | 24 | 1. An agent which always responds with `Message` objects only. Doesn't do complex state management, no long running execution and uses contextID to tie messages together. Agent most probably directly wraps around an LLM invocation and simple tools. 25 | 2. Generates a `Task`, does more substantial work that can be tracked and runs over extended life time. 26 | 3. Generates both `Message` and `Task` objects. Uses messages to negotiate agent capability and scope of work for a task. Then sends `Task` object to track its execution and collaborate over task states like more input-needed, error handling, etc. 27 | 28 | An agent can choose to always reply back with `Task` objects and model simple responses as tasks in `completed` state. 29 | 30 | ## Task Refinements & Follow-ups 31 | 32 | Clients may want to follow up with new asks based on the results of a task, and/or refine upon the task results. This can be modeled by starting another interaction using the same `contextId` as the original task. Clients can further hint the agent by providing the reference to the original task using `referenceTaskIds` in `Message` object. Agent would then respond with either a new `Task` or a `Message`. 33 | 34 | Once a task has reached a terminal state (`completed`, `cancelled`, `rejected` or `failed`), it can't be restarted. There are some benefits to this: 35 | 36 | - **Task Immutability**: Clients can reliably reference tasks and their associated state, artifacts, and messages. 37 | - This provides a clean mapping of inputs to outputs. 38 | - Useful for mapping client orchestrator to task execution. 39 | - **Clear Unit of Work**: Every new request, refinement, or a follow-up becomes a distinct task, simplifying bookkeeping and allowing for granular tracking of an agent's work. 40 | - Each artifact can be traced to a unit task. 41 | - This unit of work can be referenced much more granularly by parent agents or other systems like agent optimizers. In case of restartable tasks, all the subsequent refinements are combined, and any reference to an interaction would need to resort to some kind of message index range. 42 | - **Easier Implementation**: No ambiguity for agent developers, whether to create a new task or restart an existing task. Once a task is in terminal state, any related subsequent interaction would need to be within a new task. 43 | 44 | ### Parallel Follow-ups 45 | 46 | Parallel work is supported by having agents 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. 47 | 48 | For example: 49 | 50 | ```none 51 | Task 1: Book a flight to Helsinki. 52 | (After Task 1 finishes) 53 | Task 2: Based on Task 1, book a hotel. 54 | Task 3: Based on Task 1, book a snowmobile activity. 55 | (After Task 2 finishes, while Task 3 is still in progress) 56 | Task 4: Based on Task 2, add a spa reservation to the hotel booking. 57 | ``` 58 | 59 | ### Referencing Previous Artifacts 60 | 61 | The serving agent is responsible for inferring the relevant artifact from the referenced task or from the `contextId`. The serving agent, as the domain expert, is best suited to resolve ambiguity or identify missing information because they are the ones who generated the artifacts. 62 | 63 | If there is ambiguity (e.g., multiple artifacts could fit the request), the agent will ask the client for clarification by returning an input-required state. The client can then specify the artifact in its response. Client can optionally populate artifact reference {artifactId, taskId} in part metadata. This allows for linkage between inputs for follow-up tasks and previously generated artifacts. 64 | 65 | This approach allows for the client implementation to be simple. 66 | 67 | ### Tracking Artifact Mutation 68 | 69 | A follow up or refinement can result in an older artifact being modified and newer artifacts being generated. It would be good to know this linkage and maybe track all mutations of the artifact to make sure only the latest copy is used for future context. Something like a linked list, with the head as the latest version of the task result. 70 | 71 | But the client is best suited, as well as is the real judge of what it considers as an acceptable result. And in fact can reject the mutation as well. Hence, the serving agent should not own this linkage and hence this linkage does not need to be part of A2A protocol spec. Clients can maintain the linkage on their end and show the latest version to the user. 72 | 73 | To help with the tracking, the serving agent should maintain the same artifact-name when generating a refinement on the original artifact. 74 | 75 | For follow-up or refinement tasks, the client is best suited to refer to the "latest" or what it considers to be the intended artifact to be refined upon. If the artifact reference is not explicitly specified, the serving agent can: 76 | 77 | - Use context to figure out the latest artifact. 78 | - Or in case of ambiguity or context not supported, agent can use `input-required` task state. 79 | 80 | ### Example Follow-up 81 | 82 | #### Client sends message to agent 83 | 84 | ```json 85 | { 86 | "jsonrpc": "2.0", 87 | "id": "req-001", 88 | "method": "message/send", 89 | "params": { 90 | "message": { 91 | "role": "user", 92 | "parts": [ 93 | { 94 | "kind": "text", 95 | "text": "Generate an image of a sailboat on the ocean." 96 | } 97 | ], 98 | "messageId": "msg-user-001" 99 | } 100 | } 101 | } 102 | ``` 103 | 104 | #### Agent responds with boat image 105 | 106 | ```json 107 | { 108 | "jsonrpc": "2.0", 109 | "id": "req-001", 110 | "result": { 111 | "id": "task-boat-gen-123", 112 | "contextId": "ctx-conversation-abc", 113 | "status": { 114 | "state": "completed", 115 | }, 116 | "artifacts": [ 117 | { 118 | "artifactId": "artifact-boat-v1-xyz", 119 | "name": "sailboat_image.png", 120 | "description": "A generated image of a sailboat on the ocean.", 121 | "parts": [ 122 | { 123 | "kind": "file", 124 | "file": { 125 | "name": "sailboat_image.png", 126 | "mimeType": "image/png", 127 | "bytes": "" 128 | } 129 | } 130 | ] 131 | } 132 | ], 133 | "kind": "task" 134 | } 135 | } 136 | ``` 137 | 138 | #### Client asks for coloring the boat red 139 | 140 | Refers to previous taskID and uses same contextId. 141 | 142 | ```json 143 | { 144 | "jsonrpc": "2.0", 145 | "id": "req-002", 146 | "method": "message/send", 147 | "params": { 148 | "message": { 149 | "role": "user", 150 | "messageId": "msg-user-002", 151 | "contextId": "ctx-conversation-abc", // Same contextId 152 | "referenceTaskIds": ["task-boat-gen-123"] // Optional: Referencing the previous task 153 | "parts": [ 154 | { 155 | "kind": "text", 156 | "text": "That's great! Can you make the sailboat red?" 157 | // Optional: In case the agent asked for actual relevant artifact. 158 | // Client could provide the artifact data in parts. 159 | // Also it could add metadata to the part to 160 | // reference the specific artifact. 161 | // "metadata": { 162 | // "referenceArtifacts: [ 163 | // { 164 | // "artifactId": "artifact-boat-v1-xyz", 165 | // "taskId": "task-boat-gen-123" 166 | // } 167 | // ] 168 | // } 169 | } 170 | ], 171 | } 172 | } 173 | } 174 | ``` 175 | 176 | #### Agent responds with new image artifact 177 | 178 | - Creates new task in same contextId. 179 | - Boat image artifact has same name. but a new artifactId. 180 | 181 | ```json 182 | { 183 | "jsonrpc": "2.0", 184 | "id": "req-002", 185 | "result": { 186 | "id": "task-boat-color-456", // New task ID 187 | "contextId": "ctx-conversation-abc", // Same contextId 188 | "status": { 189 | "state": "completed", 190 | }, 191 | "artifacts": [ 192 | { 193 | "artifactId": "artifact-boat-v2-red-pqr", // New artifactId 194 | "name": "sailboat_image.png", // Same name as the original artifact 195 | "description": "A generated image of a red sailboat on the ocean.", 196 | "parts": [ 197 | { 198 | "kind": "file", 199 | "file": { 200 | "name": "sailboat_image.png", 201 | "mimeType": "image/png", 202 | "bytes": "" 203 | } 204 | } 205 | ] 206 | } 207 | ], 208 | "kind": "task" 209 | } 210 | } 211 | ``` 212 | -------------------------------------------------------------------------------- /docs/topics/what-is-a2a.md: -------------------------------------------------------------------------------- 1 | # What is A2A? 2 | 3 | The Agent2Agent (A2A) Protocol is an open standard designed to solve a fundamental challenge in the rapidly evolving landscape of artificial intelligence: **how do AI agents, built by different teams, using different technologies, and owned by different organizations, communicate and collaborate effectively?** 4 | 5 | As AI agents become more specialized and capable, the need for them to work together on complex tasks increases. Imagine a user asking their primary AI assistant to plan an international trip. This single request might involve coordinating the capabilities of several specialized agents: 6 | 7 | 1. An agent for flight bookings. 8 | 2. Another agent for hotel reservations. 9 | 3. A third for local tour recommendations and bookings. 10 | 4. A fourth to handle currency conversion and travel advisories. 11 | 12 | Without a common communication protocol, integrating these diverse agents into a cohesive user experience is a significant engineering hurdle. Each integration would likely be a custom, point-to-point solution, making the system difficult to scale, maintain, and extend. 13 | 14 | ## The A2A Solution 15 | 16 | A2A provides a standardized way for these independent, often "opaque" (black-box) agentic systems to interact. It defines: 17 | 18 | - **A common transport and format:** JSON-RPC 2.0 over HTTP(S) for how messages are structured and transmitted. 19 | - **Discovery mechanisms (Agent Cards):** How agents can advertise their capabilities and be found by other agents. 20 | - **Task management workflows:** How collaborative tasks are initiated, progressed, and completed. This includes support for tasks that may be long-running or require multiple turns of interaction. 21 | - **Support for various data modalities:** How agents exchange not just text, but also files, structured data (like forms), and potentially other rich media. 22 | - **Core principles for security and asynchronicity:** Guidelines for secure communication and handling tasks that might take significant time or involve human-in-the-loop processes. 23 | 24 | ## Key Design Principles of A2A 25 | 26 | The development of A2A is guided by several core principles: 27 | 28 | - **Simplicity:** Leverage existing, well-understood standards like HTTP, JSON-RPC, and Server-Sent Events (SSE) where possible, rather than reinventing the wheel. 29 | - **Enterprise Readiness:** Address critical enterprise needs such as authentication, authorization, security, privacy, tracing, and monitoring from the outset by aligning with standard web practices. 30 | - **Asynchronous First:** Natively support long-running tasks and scenarios where agents or users might not be continuously connected, through mechanisms like streaming and push notifications. 31 | - **Modality Agnostic:** Allow agents to communicate using a variety of content types, enabling rich and flexible interactions beyond plain text. 32 | - **Opaque Execution:** Enable collaboration without requiring agents to expose their internal logic, memory, or proprietary tools. Agents interact based on declared capabilities and exchanged context, preserving intellectual property and enhancing security. 33 | 34 | ## Benefits of Using A2A 35 | 36 | Adopting A2A can lead to significant advantages: 37 | 38 | - **Increased Interoperability:** Break down silos between different AI agent ecosystems, allowing agents from various vendors and frameworks to work together. 39 | - **Enhanced Agent Capabilities:** Allow developers to create more sophisticated applications by composing the strengths of multiple specialized agents. 40 | - **Reduced Integration Complexity:** Standardize the "how" of agent communication, allowing teams to focus on the "what" – the value their agents provide. 41 | - **Fostering Innovation:** Encourage the development of a richer ecosystem of specialized agents that can readily plug into larger collaborative workflows. 42 | - **Future-Proofing:** Provide a flexible framework that can adapt as agent technologies continue to evolve. 43 | 44 | By establishing common ground for agent-to-agent communication, A2A aims to accelerate the adoption and utility of AI agents across diverse industries and applications, paving the way for more powerful and collaborative AI systems. 45 | 46 | ## A2A Request Lifecycle 47 | 48 | ```mermaid 49 | sequenceDiagram 50 | participant Client 51 | participant A2A Server 52 | participant Auth Server 53 | 54 | rect rgb(240, 240, 240) 55 | Note over Client, A2A Server: 1. Agent Discovery 56 | Client->>A2A Server: GET agent card eg: (/.well-known/agent-card) 57 | A2A Server-->>Client: Returns Agent Card 58 | end 59 | 60 | rect rgb(240, 240, 240) 61 | Note over Client, Auth Server: 2. Authentication 62 | Client->>Client: Parse Agent Card for securitySchemes 63 | alt securityScheme is openIdConnect 64 | Client->>Auth Server: Request token based on "authorizationUrl" and "tokenUrl" 65 | Auth Server-->>Client: Returns JWT 66 | end 67 | end 68 | 69 | rect rgb(240, 240, 240) 70 | Note over Client, A2A Server: 3. sendMessage API 71 | Client->>Client: Parse Agent Card for "url" param to send API requests to. 72 | Client->>A2A Server: POST /sendMessage (with JWT) 73 | A2A Server->>A2A Server: Process message and create task 74 | A2A Server-->>Client: Returns Task Response 75 | end 76 | 77 | rect rgb(240, 240, 240) 78 | Note over Client, A2A Server: 4. sendMessageStream API 79 | Client->>A2A Server: POST /sendMessageStream (with JWT) 80 | A2A Server-->>Client: Stream: Task (Submitted) 81 | A2A Server-->>Client: Stream: TaskStatusUpdateEvent (Working) 82 | A2A Server-->>Client: Stream: TaskArtifactUpdateEvent (artifact A) 83 | A2A Server-->>Client: Stream: TaskArtifactUpdateEvent (artifact B) 84 | A2A Server-->>Client: Stream: TaskStatusUpdateEvent (Completed) 85 | end 86 | ``` 87 | 88 | Next, learn about the [Key Concepts](./key-concepts.md) that form the foundation of the A2A protocol. 89 | -------------------------------------------------------------------------------- /docs/tutorials/python/1-introduction.md: -------------------------------------------------------------------------------- 1 | # Python Quickstart Tutorial: Building an A2A Agent 2 | 3 | Welcome to the Agent2Agent (A2A) Python Quickstart Tutorial! 4 | 5 | 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). 6 | 7 | This hands-on guide will help you understand: 8 | 9 | - The basic concepts behind the A2A protocol. 10 | - How to set up a Python environment for A2A development using the SDK. 11 | - How Agent Skills and Agent Cards describe an agent. 12 | - How an A2A server handles tasks. 13 | - How to interact with an A2A server using a client. 14 | - How streaming capabilities and multi-turn interactions work. 15 | - How an LLM can be integrated into an A2A agent. 16 | 17 | 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. 18 | 19 | ## Tutorial Sections 20 | 21 | The tutorial is broken down into the following steps: 22 | 23 | 1. **[Introduction (This Page)](./1-introduction.md)** 24 | 2. **[Setup](./2-setup.md)**: Prepare your Python environment and the A2A SDK. 25 | 3. **[Agent Skills & Agent Card](./3-agent-skills-and-card.md)**: Define what your agent can do and how it describes itself. 26 | 4. **[The Agent Executor](./4-agent-executor.md)**: Understand how the agent logic is implemented. 27 | 5. **[Starting the Server](./5-start-server.md)**: Run the Helloworld A2A server. 28 | 6. **[Interacting with the Server](./6-interact-with-server.md)**: Send requests to your agent. 29 | 7. **[Streaming & Multi-Turn Interactions](./7-streaming-and-multiturn.md)**: Explore advanced capabilities with the LangGraph example. 30 | 8. **[Next Steps](./8-next-steps.md)**: Explore further possibilities with A2A. 31 | 32 | Let's get started! 33 | -------------------------------------------------------------------------------- /docs/tutorials/python/2-setup.md: -------------------------------------------------------------------------------- 1 | # 2. Setup Your Environment 2 | 3 | ## Prerequisites 4 | 5 | - Python 3.10 or higher. 6 | - Access to a terminal or command prompt. 7 | - Git, for cloning the repository. 8 | - A code editor (e.g., Visual Studio Code) is recommended. 9 | 10 | ## Clone the Repository 11 | 12 | If you haven't already, clone the A2A Samples repository: 13 | 14 | ```bash 15 | git clone https://github.com/a2aproject/a2a-samples.git -b main --depth 1 16 | cd a2a-samples 17 | ``` 18 | 19 | ## Python Environment & SDK Installation 20 | 21 | 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. 22 | 23 | 1. **Create and activate a virtual environment:** 24 | 25 | Using `venv` (standard library): 26 | 27 | === "Mac/Linux" 28 | 29 | ```sh 30 | python -m venv .venv 31 | source .venv/bin/activate 32 | ``` 33 | 34 | === "Windows" 35 | 36 | ```powershell 37 | python -m venv .venv 38 | .venv\Scripts\activate 39 | ``` 40 | 41 | 2. **Install needed Python dependencies along with the A2A SDK and its dependencies:** 42 | 43 | ```bash 44 | pip install -r samples/python/requirements.txt 45 | ``` 46 | 47 | ## Verify Installation 48 | 49 | After installation, you should be able to import the `a2a` package in a Python interpreter: 50 | 51 | ```bash 52 | python -c "import a2a; print('A2A SDK imported successfully')" 53 | ``` 54 | 55 | If this command runs without error and prints the success message, your environment is set up correctly. 56 | -------------------------------------------------------------------------------- /docs/tutorials/python/3-agent-skills-and-card.md: -------------------------------------------------------------------------------- 1 | # 3. Agent Skills & Agent Card 2 | 3 | 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). 4 | 5 | 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). 6 | 7 | ## Agent Skills 8 | 9 | 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. 10 | 11 | Key attributes of an `AgentSkill` (defined in `a2a.types`): 12 | 13 | - `id`: A unique identifier for the skill. 14 | - `name`: A human-readable name. 15 | - `description`: A more detailed explanation of what the skill does. 16 | - `tags`: Keywords for categorization and discovery. 17 | - `examples`: Sample prompts or use cases. 18 | - `inputModes` / `outputModes`: Supported Media Types for input and output (e.g., "text/plain", "application/json"). 19 | 20 | In `__main__.py`, you can see how a skill for the Helloworld agent is defined: 21 | 22 | ```python { .no-copy } 23 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentSkill" 24 | ``` 25 | 26 | This skill is very simple: it's named "Returns hello world" and primarily deals with text. 27 | 28 | ## Agent Card 29 | 30 | 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. 31 | 32 | Key attributes of an `AgentCard` (defined in `a2a.types`): 33 | 34 | - `name`, `description`, `version`: Basic identity information. 35 | - `url`: The endpoint where the A2A service can be reached. 36 | - `capabilities`: Specifies supported A2A features like `streaming` or `pushNotifications`. 37 | - `defaultInputModes` / `defaultOutputModes`: Default Media Types for the agent. 38 | - `skills`: A list of `AgentSkill` objects that the agent offers. 39 | 40 | The `helloworld` example defines its Agent Card like this: 41 | 42 | ```python { .no-copy } 43 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentCard" 44 | ``` 45 | 46 | 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. 47 | 48 | Understanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it. 49 | -------------------------------------------------------------------------------- /docs/tutorials/python/4-agent-executor.md: -------------------------------------------------------------------------------- 1 | # 4. The Agent Executor 2 | 3 | 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. 4 | 5 | ## `AgentExecutor` Interface 6 | 7 | The `AgentExecutor` class defines two primary methods: 8 | 9 | - `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. 10 | - `async def cancel(self, context: RequestContext, event_queue: EventQueue)`: Handles requests to cancel an ongoing task. 11 | 12 | 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. 13 | 14 | ## Helloworld Agent Executor 15 | 16 | Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`. 17 | 18 | 1. **The Agent (`HelloWorldAgent`)**: 19 | This is a simple helper class that encapsulates the actual "business logic". 20 | 21 | ```python { .no-copy } 22 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent" 23 | ``` 24 | 25 | It has a simple `invoke` method that returns the string "Hello World". 26 | 27 | 2. **The Executor (`HelloWorldAgentExecutor`)**: 28 | This class implements the `AgentExecutor` interface. 29 | 30 | - **`__init__`**: 31 | 32 | ```python { .no-copy } 33 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_init" 34 | ``` 35 | 36 | It instantiates the `HelloWorldAgent`. 37 | 38 | - **`execute`**: 39 | 40 | ```python { .no-copy } 41 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute" 42 | ``` 43 | 44 | When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor): 45 | 46 | 1. It calls `self.agent.invoke()` to get the "Hello World" string. 47 | 2. It creates an A2A `Message` object using the `new_agent_text_message` utility function. 48 | 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. 49 | 50 | - **`cancel`**: 51 | The Helloworld example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent. 52 | 53 | ```python { .no-copy } 54 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel" 55 | ``` 56 | 57 | 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. 58 | -------------------------------------------------------------------------------- /docs/tutorials/python/5-start-server.md: -------------------------------------------------------------------------------- 1 | # 5. Starting the Server 2 | 3 | Now that we have an Agent Card and an Agent Executor, we can set up and start the A2A server. 4 | 5 | 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/). 6 | 7 | ## Server Setup in Helloworld 8 | 9 | Let's look at `__main__.py` again to see how the server is initialized and started. 10 | 11 | ```python { .no-copy } 12 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py" 13 | ``` 14 | 15 | Let's break this down: 16 | 17 | 1. **`DefaultRequestHandler`**: 18 | 19 | - The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`). 20 | - It routes incoming A2A RPC calls to the appropriate methods on your executor (like `execute` or `cancel`). 21 | - 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. 22 | 23 | 2. **`A2AStarletteApplication`**: 24 | 25 | - The `A2AStarletteApplication` class is instantiated with the `agent_card` and the `request_handler` (referred to as `http_handler` in its constructor). 26 | - The `agent_card` is crucial because the server will expose it at the `/.well-known/agent-card.json` endpoint (by default). 27 | - The `request_handler` is responsible for processing all incoming A2A method calls by interacting with your `AgentExecutor`. 28 | 29 | 3. **`uvicorn.run(server_app_builder.build(), ...)`**: 30 | - The `A2AStarletteApplication` has a `build()` method that constructs the actual Starlette application. 31 | - This application is then run using `uvicorn.run()`, making your agent accessible over HTTP. 32 | - `host='0.0.0.0'` makes the server accessible on all network interfaces on your machine. 33 | - `port=9999` specifies the port to listen on. This matches the `url` in the `AgentCard`. 34 | 35 | ## Running the Helloworld Server 36 | 37 | Navigate to the `a2a-samples` directory in your terminal (if you're not already there) and ensure your virtual environment is activated. 38 | 39 | To run the Helloworld server: 40 | 41 | ```bash 42 | # from the a2a-samples directory 43 | python samples/python/agents/helloworld/__main__.py 44 | ``` 45 | 46 | You should see output similar to this, indicating the server is running: 47 | 48 | ```console { .no-copy } 49 | INFO: Started server process [xxxxx] 50 | INFO: Waiting for application startup. 51 | INFO: Application startup complete. 52 | INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit) 53 | ``` 54 | 55 | Your A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it. 56 | -------------------------------------------------------------------------------- /docs/tutorials/python/6-interact-with-server.md: -------------------------------------------------------------------------------- 1 | # 6. Interacting with the Server 2 | 3 | With the Helloworld A2A server running, let's send some requests to it. The SDK includes a client (`A2AClient`) that simplifies these interactions. 4 | 5 | ## The Helloworld Test Client 6 | 7 | The `test_client.py` script demonstrates how to: 8 | 9 | 1. Fetch the Agent Card from the server. 10 | 2. Create an `A2AClient` instance. 11 | 3. Send both non-streaming (`message/send`) and streaming (`message/stream`) requests. 12 | 13 | Open a **new terminal window**, activate your virtual environment, and navigate to the `a2a-samples` directory. 14 | 15 | Activate virtual environment (Be sure to do this in the same directory where you created the virtual environment): 16 | 17 | === "Mac/Linux" 18 | 19 | ```sh 20 | source .venv/bin/activate 21 | ``` 22 | 23 | === "Windows" 24 | 25 | ```powershell 26 | .venv\Scripts\activate 27 | ``` 28 | 29 | Run the test client: 30 | 31 | ```bash 32 | # from the a2a-samples directory 33 | python samples/python/agents/helloworld/test_client.py 34 | ``` 35 | 36 | ## Understanding the Client Code 37 | 38 | Let's look at key parts of `test_client.py`: 39 | 40 | 1. **Fetching the Agent Card & Initializing the Client**: 41 | 42 | ```python { .no-copy } 43 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver" 44 | ``` 45 | 46 | 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. 47 | 48 | 2. **Sending a Non-Streaming Message (`send_message`)**: 49 | 50 | ```python { .no-copy } 51 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message" 52 | ``` 53 | 54 | - The `send_message_payload` constructs the data for `MessageSendParams`. 55 | - This is wrapped in a `SendMessageRequest`. 56 | - It includes a `message` object with the `role` set to "user" and the content in `parts`. 57 | - The Helloworld agent's `execute` method will enqueue a single "Hello World" message. The `DefaultRequestHandler` will retrieve this and send it as the response. 58 | - The `response` will be a `SendMessageResponse` object, which contains either a `SendMessageSuccessResponse` (with the agent's `Message` as the result) or a `JSONRPCErrorResponse`. 59 | 60 | 3. **Handling Task IDs (Illustrative Note for Helloworld)**: 61 | 62 | 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`. 63 | 64 | 4. **Sending a Streaming Message (`send_message_streaming`)**: 65 | 66 | ```python { .no-copy } 67 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming" 68 | ``` 69 | 70 | - This method calls the agent's `message/stream` endpoint. The `DefaultRequestHandler` will invoke the `HelloWorldAgentExecutor.execute` method. 71 | - The `execute` method enqueues one "Hello World" message, and then the event queue is closed. 72 | - The client will receive this single message as one `SendStreamingMessageResponse` event, and then the stream will terminate. 73 | - The `stream_response` is an `AsyncGenerator`. 74 | 75 | ## Expected Output 76 | 77 | When you run `test_client.py`, you'll see JSON outputs for: 78 | 79 | - The non-streaming response (a single "Hello World" message). 80 | - The streaming response (a single "Hello World" message as one chunk, after which the stream ends). 81 | 82 | The `id` fields in the output will vary with each run. 83 | 84 | ```console { .no-copy } 85 | // Non-streaming response 86 | {"jsonrpc":"2.0","id":"xxxxxxxx","result":{"type":"message","role":"agent","parts":[{"type":"text","text":"Hello World"}],"messageId":"yyyyyyyy"}} 87 | // Streaming response (one chunk) 88 | {"jsonrpc":"2.0","id":"zzzzzzzz","result":{"type":"message","role":"agent","parts":[{"type":"text","text":"Hello World"}],"messageId":"wwwwwwww","final":true}} 89 | ``` 90 | 91 | _(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww` will be different UUIDs/request IDs)_ 92 | 93 | This confirms your server is correctly handling basic A2A interactions with the updated SDK structure! 94 | 95 | Now you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running. 96 | -------------------------------------------------------------------------------- /docs/tutorials/python/7-streaming-and-multiturn.md: -------------------------------------------------------------------------------- 1 | # 7. Streaming & Multi-Turn Interactions (LangGraph Example) 2 | 3 | The Helloworld example demonstrates the basic mechanics of A2A. For more advanced features like robust streaming, task state management, and multi-turn conversations powered by an LLM, we'll turn to the LangGraph example located in [`a2a-samples/samples/python/agents/langgraph/`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/langgraph). 4 | 5 | This example features a "Currency Agent" that uses the Gemini model via LangChain and LangGraph to answer currency conversion questions. 6 | 7 | ## Setting up the LangGraph Example 8 | 9 | 1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one. 10 | 11 | 2. **Environment Variable:** 12 | 13 | Create a `.env` file in the `a2a-samples/samples/python/agents/langgraph/` directory: 14 | 15 | ```bash 16 | echo "GOOGLE_API_KEY=YOUR_API_KEY_HERE" > .env 17 | ``` 18 | 19 | Replace `YOUR_API_KEY_HERE` with your actual Gemini API key. 20 | 21 | 3. **Install Dependencies (if not already covered):** 22 | 23 | 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. 24 | 25 | ## Running the LangGraph Server 26 | 27 | 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. 28 | 29 | Start the LangGraph agent server: 30 | 31 | ```bash 32 | python __main__.py 33 | ``` 34 | 35 | This will start the server, usually on `http://localhost:10000`. 36 | 37 | ## Interacting with the LangGraph Agent 38 | 39 | Open a **new terminal window**, activate your virtual environment, and navigate to `a2a-samples/samples/python/agents/langgraph/app`. 40 | 41 | Run its test client: 42 | 43 | ```bash 44 | python test_client.py 45 | ``` 46 | 47 | Now, you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running. 48 | 49 | ## Key Features Demonstrated 50 | 51 | The `langgraph` example showcases several important A2A concepts: 52 | 53 | 1. **LLM Integration**: 54 | 55 | - `agent.py` defines `CurrencyAgent`. It uses `ChatGoogleGenerativeAI` and LangGraph's `create_react_agent` to process user queries. 56 | - This demonstrates how a real LLM can power the agent's logic. 57 | 58 | 2. **Task State Management**: 59 | 60 | - `samples/langgraph/__main__.py` initializes a `DefaultRequestHandler` with an `InMemoryTaskStore`. 61 | 62 | ```python { .no-copy } 63 | --8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/langgraph/app/__main__.py:DefaultRequestHandler" 64 | ``` 65 | 66 | - 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). 67 | - 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. 68 | - The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`. 69 | 70 | 3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**: 71 | 72 | - The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`. 73 | - 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`: 74 | - `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates.."). The `final` flag on these events is `False`. 75 | - `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`. 76 | - A final `TaskStatusUpdateEvent` with `state=TaskState.completed` and `final=True` is sent to signify the end of the task for streaming. 77 | - The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server. 78 | 79 | 4. **Multi-Turn Conversation (`TaskState.input_required`)**: 80 | 81 | - The `CurrencyAgent` can ask for clarification if a query is ambiguous (e.g., user asks "how much is 100 USD?"). 82 | - When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., "To which currency would you like to convert?"). This event will have `final=True` for the current interaction stream. 83 | - The `test_client.py`'s `run_multi_turn_test` function demonstrates this: 84 | - It sends an initial ambiguous query. 85 | - The agent responds (via the `DefaultRequestHandler` processing the enqueued events) with a `Task` whose status is `input_required`. 86 | - 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. 87 | 88 | ## Exploring the Code 89 | 90 | Take some time to look through these files: 91 | 92 | - `__main__.py`: Server setup using `A2AStarletteApplication` and `DefaultRequestHandler`. Note the `AgentCard` definition includes `capabilities.streaming=True`. 93 | - `agent.py`: The `CurrencyAgent` with LangGraph, LLM model, and tool definitions. 94 | - `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). 95 | - `test_client.py`: Demonstrates various interaction patterns, including retrieving task IDs and using them for multi-turn conversations. 96 | 97 | This example provides a much richer illustration of how A2A facilitates complex, stateful, and asynchronous interactions between agents. 98 | -------------------------------------------------------------------------------- /docs/tutorials/python/8-next-steps.md: -------------------------------------------------------------------------------- 1 | # Next Steps 2 | 3 | Congratulations on completing the A2A Python SDK Tutorial! You've learned how to: 4 | 5 | - Set up your environment for A2A development. 6 | - Define Agent Skills and Agent Cards using the SDK's types. 7 | - Implement a basic HelloWorld A2A server and client. 8 | - Understand and implement streaming capabilities. 9 | - Integrate a more complex agent using LangGraph, demonstrating task state management and tool use. 10 | 11 | You now have a solid foundation for building and integrating your own A2A-compliant agents. 12 | 13 | ## Where to Go From Here? 14 | 15 | Here are some ideas and resources to continue your A2A journey: 16 | 17 | - **Explore Other Examples:** 18 | - Check out the other examples in the `a2a-samples/samples/` directory in the [A2A GitHub repository](https://github.com/a2aproject/a2a-samples/tree/main/samples) for more complex agent integrations and features. 19 | - The main A2A repository also has [samples for other languages and frameworks](https://github.com/a2aproject/A2A/tree/main/samples). 20 | - **Deepen Your Protocol Understanding:** 21 | - 📚 Read the complete [A2A Protocol Documentation site](https://google.github.io/A2A/) for a comprehensive overview. 22 | - 📝 Review the detailed [A2A Protocol Specification](../../specification.md) to understand the nuances of all data structures and RPC methods. 23 | - **Review Key A2A Topics:** 24 | - [A2A and MCP](../../topics/a2a-and-mcp.md): Understand how A2A complements the Model Context Protocol for tool usage. 25 | - [Enterprise-Ready Features](../../topics/enterprise-ready.md): Learn about security, observability, and other enterprise considerations. 26 | - [Streaming & Asynchronous Operations](../../topics/streaming-and-async.md): Get more details on SSE and push notifications. 27 | - [Agent Discovery](../../topics/agent-discovery.md): Explore different ways agents can find each other. 28 | - **Build Your Own Agent:** 29 | - Try creating a new A2A agent using your favorite Python agent framework (like LangChain, CrewAI, AutoGen, Semantic Kernel, or a custom solution). 30 | - Implement the `a2a.server.AgentExecutor` interface to bridge your agent's logic with the A2A protocol. 31 | - Think about what unique skills your agent could offer and how its Agent Card would represent them. 32 | - **Experiment with Advanced Features:** 33 | - Implement robust task management with a persistent `TaskStore` if your agent handles long-running or multi-session tasks. 34 | - Explore implementing push notifications if your agent's tasks are very long-lived. 35 | - Consider more complex input and output modalities (e.g., handling file uploads/downloads, or structured data via `DataPart`). 36 | - **Contribute to the A2A Community:** 37 | - Join the discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions). 38 | - Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues). 39 | - Consider contributing code, examples, or documentation. See the [CONTRIBUTING.md](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md) guide. 40 | 41 | 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! 42 | -------------------------------------------------------------------------------- /lychee.toml: -------------------------------------------------------------------------------- 1 | exclude = [ 2 | 'https://fonts.gstatic.com/', 3 | 'https://fonts.googleapis.com/', 4 | 'http://go/github', 5 | 'http://go/github-googlecloudplatform', 6 | 'https://medium.com/', 7 | 'https://x.com/', 8 | 'http://localhost:12000/', 9 | 'http://localhost:10020/', 10 | 'https://www.askmarvin.ai/', 11 | 'https://www.bcg.com/', 12 | 'https://www.oracle.com/netsuite', 13 | 'https://www.spglobal.com/', 14 | 'https://www.epam.com/', 15 | 'https://www.servicenow.com/', 16 | ] 17 | exclude_path = [ 18 | ".github/actions/spelling", 19 | ] 20 | 21 | max_retries = 0 22 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Project information 2 | site_name: Agent2Agent (A2A) Protocol 3 | site_url: https://a2a-protocol.org/ 4 | site_description: >- 5 | An open protocol enabling communication and interoperability between opaque agentic applications. 6 | site_author: The Linux Foundation 7 | site_dir: site 8 | 9 | extra: 10 | a2a_version: !ENV [MIKE_VERSION, 'dev'] 11 | analytics: 12 | provider: google 13 | property: G-RB39M83WHB 14 | 15 | 16 | # Navigation 17 | nav: 18 | - Home: index.md 19 | - Topics: 20 | - What is A2A?: topics/what-is-a2a.md 21 | - Key Concepts: topics/key-concepts.md 22 | - A2A and MCP: topics/a2a-and-mcp.md 23 | - Agent Discovery: topics/agent-discovery.md 24 | - Enterprise-Ready Features: topics/enterprise-ready.md 25 | - Streaming & Asynchronous Operations: topics/streaming-and-async.md 26 | - Extensions: topics/extensions.md 27 | - Life of a Task: topics/life-of-a-task.md 28 | - Specification: specification.md 29 | - Community: community.md 30 | - Partners: partners.md 31 | - SDK Reference: 32 | - Python: sdk/python/api/index.html 33 | - Tutorial (Python): 34 | - Introduction: tutorials/python/1-introduction.md 35 | - Setup: tutorials/python/2-setup.md 36 | - Agent Skills & Agent Card: tutorials/python/3-agent-skills-and-card.md 37 | - Agent Executor: tutorials/python/4-agent-executor.md 38 | - Start Server: tutorials/python/5-start-server.md 39 | - Interact with Server: tutorials/python/6-interact-with-server.md 40 | - Streaming & Multiturn: tutorials/python/7-streaming-and-multiturn.md 41 | - Next Steps: tutorials/python/8-next-steps.md 42 | - Roadmap: roadmap.md 43 | 44 | # Repository 45 | repo_name: a2aproject/A2A 46 | repo_url: https://github.com/a2aproject/A2A 47 | 48 | # Copyright 49 | copyright: © 2025 The Linux Foundation. Licensed under the Apache License, Version 2.0. 50 | 51 | # Custom CSS 52 | extra_css: 53 | - stylesheets/custom.css 54 | 55 | # Configuration 56 | theme: 57 | name: material 58 | custom_dir: .mkdocs/overrides 59 | font: 60 | text: Google Sans 61 | code: Roboto Mono 62 | logo: assets/a2a-logo-white.svg 63 | favicon: assets/a2a-logo-black.svg 64 | icon: 65 | repo: fontawesome/brands/github 66 | admonition: 67 | note: fontawesome/solid/note-sticky 68 | abstract: fontawesome/solid/book 69 | info: fontawesome/solid/circle-info 70 | tip: fontawesome/solid/bullhorn 71 | success: fontawesome/solid/check 72 | question: fontawesome/solid/circle-question 73 | warning: fontawesome/solid/triangle-exclamation 74 | failure: fontawesome/solid/bomb 75 | danger: fontawesome/solid/skull 76 | bug: fontawesome/solid/robot 77 | example: fontawesome/solid/flask 78 | quote: fontawesome/solid/quote-left 79 | palette: 80 | - scheme: default 81 | primary: indigo 82 | accent: white 83 | toggle: 84 | icon: material/brightness-7 85 | name: Switch to dark mode 86 | - scheme: slate 87 | primary: indigo 88 | accent: white 89 | toggle: 90 | icon: material/brightness-4 91 | name: Switch to light mode 92 | features: 93 | - announce.dismiss 94 | - content.code.annotate 95 | - content.code.copy 96 | - content.code.select 97 | - content.tabs.link 98 | - navigation.expand 99 | - navigation.footer 100 | - navigation.indexes 101 | - navigation.instant 102 | - navigation.instant.progress 103 | - navigation.path 104 | - navigation.tabs 105 | - navigation.top 106 | - navigation.tracking 107 | - toc.follow 108 | - versioning: 109 | provider: mike 110 | 111 | # Extensions 112 | markdown_extensions: 113 | - footnotes 114 | - admonition 115 | - attr_list 116 | - md_in_html 117 | - pymdownx.details 118 | - pymdownx.emoji: 119 | emoji_index: !!python/name:material.extensions.emoji.twemoji 120 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 121 | - pymdownx.highlight: 122 | anchor_linenums: true 123 | line_spans: __span 124 | pygments_lang_class: true 125 | - pymdownx.inlinehilite 126 | - pymdownx.snippets: 127 | url_download: true 128 | dedent_subsections: true 129 | - pymdownx.superfences: 130 | custom_fences: 131 | - name: mermaid 132 | class: mermaid 133 | format: !!python/name:pymdownx.superfences.fence_code_format 134 | - pymdownx.tabbed: 135 | alternate_style: true 136 | slugify: !!python/object/apply:pymdownx.slugs.slugify 137 | kwds: 138 | case: lower 139 | - toc: 140 | permalink: true 141 | 142 | # Plugins 143 | plugins: 144 | - search 145 | - macros 146 | - redirects: 147 | redirect_maps: 148 | "spec-json.md": https://raw.githubusercontent.com/a2aproject/A2A/refs/heads/main/specification/json/a2a.json 149 | "specification/overview.md": "specification.md" 150 | "specification/agent-card.md": "specification.md#5-agent-discovery-the-agent-card" 151 | "specification/agent-to-agent-communication.md": "specification.md#6-protocol-data-objects" 152 | "specification/sample-messages.md": "specification.md#9-common-workflows-examples" 153 | "specification/details.md": "specification.md" 154 | "documentation.md": "topics/key-concepts.md" 155 | "resources.md": "index.md" 156 | "topics/push-notifications.md": "topics/streaming-and-async.md" 157 | "specification/topics/a2a_and_mcp.md": "topics/a2a-and-mcp.md" 158 | "specification/topics/agent_discovery.md": "topics/agent-discovery.md" 159 | "specification/topics/enterprise_ready.md": "topics/enterprise-ready.md" 160 | "specification/topics/push_notification.md": "topics/streaming-and-async.md" 161 | "specification/topics/push_notifications.md": "topics/streaming-and-async.md" 162 | "topics/index.md": "topics/what-is-a2a.md" 163 | "topics/roadmap.md": "roadmap.md" 164 | # Tutorial 165 | "tutorials/index.md": "tutorials/python/1-introduction.md" 166 | "tutorials/python/index.md": "tutorials/python/1-introduction.md" 167 | "tutorials/python/1_introduction.md": "tutorials/python/1-introduction.md" 168 | "tutorials/python/3-create-project.md": "tutorials/python/2-setup.md" 169 | "tutorials/python/4-agent-skills.md": "tutorials/python/3-agent-skills-and-card.md" 170 | "tutorials/python/5-add-agent-card.md": "tutorials/python/3-agent-skills-and-card.md" 171 | "tutorials/python/6-start-server.md": "tutorials/python/5-start-server.md" 172 | "tutorials/python/7-interact-with-server.md": "tutorials/python/6-interact-with-server.md" 173 | "tutorials/python/8-agent-capabilities.md": "tutorials/python/7-streaming-and-multiturn.md" 174 | "tutorials/python/9-ollama-agent.md": "tutorials/python/7-streaming-and-multiturn.md" 175 | "tutorials/python/10-next-steps.md": "tutorials/python/8-next-steps.md" 176 | "sdk/python/": "sdk/python/api/index.html" 177 | -------------------------------------------------------------------------------- /requirements-docs.txt: -------------------------------------------------------------------------------- 1 | mkdocs-material==9.6.14 2 | mkdocs-redirects==1.2.2 3 | a2a-sdk 4 | mike 5 | mkdocs-macros-plugin 6 | sphinx 7 | furo 8 | myst-parser 9 | -------------------------------------------------------------------------------- /scripts/build_sdk_docs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e # Exit immediately if a command exits with a non-zero status. 3 | 4 | # --- Configuration --- 5 | PACKAGE_NAME="a2a" # The name of the package to import 6 | PYPI_PACKAGE_NAME="a2a-sdk" # The name on PyPI 7 | DOCS_SOURCE_DIR="docs/sdk/python" 8 | DOCS_BUILD_DIR="${DOCS_SOURCE_DIR}/_build" 9 | VENV_DIR=".doc-venv" 10 | 11 | echo "--- Setting up documentation build environment ---" 12 | 13 | # Create a clean virtual environment 14 | if [ -d "$VENV_DIR" ]; then 15 | rm -rf "$VENV_DIR" 16 | fi 17 | python3 -m venv "$VENV_DIR" 18 | source "$VENV_DIR/bin/activate" 19 | 20 | echo "--- Installing package and dependencies ---" 21 | 22 | # Upgrade pip and install documentation requirements 23 | pip install -U pip 24 | pip install -r "requirements-docs.txt" 25 | 26 | # Install the package itself 27 | pip install "${PYPI_PACKAGE_NAME}" 28 | 29 | echo "--- Finding installed package path ---" 30 | 31 | # Find the installation path of the package 32 | PACKAGE_PATH=$(python -c "import ${PACKAGE_NAME}, os; print(os.path.dirname(${PACKAGE_NAME}.__file__))") 33 | echo "Found '${PACKAGE_NAME}' at: ${PACKAGE_PATH}" 34 | 35 | echo "--- Generating API documentation source files (.rst) ---" 36 | 37 | # Run sphinx-apidoc on the installed package directory 38 | # -f: force overwrite of existing files 39 | # -e: put each module on its own page 40 | sphinx-apidoc -f -e -o "${DOCS_SOURCE_DIR}" "${PACKAGE_PATH}" 41 | 42 | echo "--- Building HTML documentation ---" 43 | 44 | # Build the HTML documentation 45 | sphinx-build -b html "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/html" 46 | 47 | # Deactivate the virtual environment 48 | deactivate 49 | 50 | echo "" 51 | echo "✅ Documentation build complete!" 52 | echo "View the docs by opening: ${DOCS_BUILD_DIR}/html/index.html" 53 | -------------------------------------------------------------------------------- /scripts/deploy-404.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Exit immediately if a command exits with a non-zero status. 4 | set -e 5 | 6 | # This script deploys the custom 404.html page to the root of the gh-pages branch. 7 | # It's designed to be called from the GitHub Actions workflow. 8 | # 9 | # Arguments: 10 | # $1: The GitHub repository name (e.g., "a2aproject/A2A"). 11 | # $2: The GITHUB_TOKEN for authentication. 12 | 13 | # --- Validate Input --- 14 | if [ -z "$1" ] || [ -z "$2" ]; then 15 | echo "Error: Missing required arguments." 16 | echo "Usage: $0 " 17 | exit 1 18 | fi 19 | 20 | REPO_NAME=$1 21 | GH_TOKEN=$2 22 | 23 | echo "Deploying custom 404 page for repository: $REPO_NAME" 24 | 25 | # --- Deployment Logic --- 26 | # Clone the gh-pages branch using the provided token for authentication. 27 | # This ensures we have push access. 28 | git clone --branch=gh-pages --single-branch --depth=1 "https://x-access-token:${GH_TOKEN}@github.com/${REPO_NAME}.git" gh-pages-deploy 29 | 30 | # Copy the 404 page from the main branch checkout into the gh-pages clone 31 | cp docs/404.html gh-pages-deploy/404.html 32 | 33 | # Navigate into the cloned directory 34 | cd gh-pages-deploy 35 | 36 | # Add the 404 page to the staging area 37 | git add 404.html 38 | 39 | # Commit and push only if the 404 page has actually changed 40 | if git diff --staged --quiet; then 41 | echo "404.html is up-to-date. No new commit needed." 42 | else 43 | echo "Committing and pushing updated 404.html..." 44 | git commit -m "docs: deploy custom 404.html for redirects" 45 | git push 46 | fi 47 | 48 | echo "404 page deployment complete." 49 | -------------------------------------------------------------------------------- /scripts/format.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -euo pipefail 4 | # Determine the repository root directory based on the script's location. 5 | SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd) 6 | REPO_ROOT=$(cd -- "$SCRIPT_DIR/.." &>/dev/null && pwd) 7 | bash "${SCRIPT_DIR}/sort_spelling.sh" 8 | 9 | # Define file and directory paths. 10 | MARKDOWN_DIR="${REPO_ROOT}/docs/" 11 | MARKDOWNLINT_CONFIG="${REPO_ROOT}/.github/linters/.markdownlint.json" 12 | 13 | # Install markdownlint-cli if the command doesn't already exist. 14 | if ! command -v markdownlint &>/dev/null; then 15 | echo "Installing markdownlint-cli..." 16 | npm install -g markdownlint-cli 17 | fi 18 | 19 | # Run markdownlint to format files. 20 | echo "Formatting markdown files..." 21 | # Check for the existence of the directory and config file before running. 22 | [ -d "${MARKDOWN_DIR}" ] || { 23 | echo "ERROR: Markdown directory not found: ${MARKDOWN_DIR}" 24 | exit 1 25 | } 26 | [ -f "${MARKDOWNLINT_CONFIG}" ] || { 27 | echo "ERROR: Markdownlint config not found: ${MARKDOWNLINT_CONFIG}" 28 | exit 1 29 | } 30 | 31 | markdownlint "${MARKDOWN_DIR}" --config "${MARKDOWNLINT_CONFIG}" --fix 32 | 33 | echo "Script finished successfully." 34 | -------------------------------------------------------------------------------- /scripts/sort_spelling.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -euo pipefail 4 | 5 | # Determine the repository root directory based on the script's location. 6 | SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd) 7 | REPO_ROOT=$(cd -- "$SCRIPT_DIR/.." &>/dev/null && pwd) 8 | 9 | ALLOW_FILE="${REPO_ROOT}/.github/actions/spelling/allow.txt" 10 | 11 | echo "Sorting spelling allow list..." 12 | [ -f "${ALLOW_FILE}" ] || { 13 | echo "ERROR: Allow list not found: ${ALLOW_FILE}" 14 | exit 1 15 | } 16 | LC_ALL=C sort -u -o "${ALLOW_FILE}" "${ALLOW_FILE}" 17 | -------------------------------------------------------------------------------- /specification/grpc/README.md: -------------------------------------------------------------------------------- 1 | # Protocol Buffer Definitions 2 | 3 | This folder contains the a2a specification in Protocol Buffer (protobuf) format 4 | 5 | ## Prerequisites 6 | 7 | Before you can validate or generate code from these protobuf definitions, you need to install `buf`. 8 | 9 | Follow the installation instructions on the official `buf` GitHub repository: 10 | 11 | 12 | ## Validation 13 | 14 | To validate your protobuf definitions and ensure they adhere to linting rules, run the following command from the root of this folder: 15 | 16 | ```sh 17 | buf lint 18 | ``` 19 | 20 | ## Code Generation 21 | 22 | `buf.gen.yaml` is configured to generate code for the following languages: 23 | 24 | - Go 25 | - Java 26 | - Python 27 | - TypeScript 28 | 29 | To generate code for all configured languages, run the following command from the root of this folder: 30 | 31 | ```sh 32 | buf generate 33 | ``` 34 | 35 | `buf.gen.yaml` uses remote plugins for generation, if you wish to use local plugins change remote to local 36 | 37 | ```yaml 38 | plugins: 39 | - local: protoc-gen-java 40 | out: src/java 41 | - local: protoc-gen-grpc-java 42 | out: src/java 43 | ``` 44 | 45 | Alternatively use `protoc` commandline for code generation 46 | 47 | ```bash 48 | protoc --java_out=./src/java --grpc-java_out=./src/java -I. a2a.proto 49 | ``` 50 | 51 | ### Generating for Specific Languages 52 | 53 | If you do not need to generate code for all the languages listed above, you can comment out the unwanted language sections in your `buf.gen.yaml` file. 54 | 55 | For example, if you only want to generate Java exclude the rest, your `buf.gen.yaml` might look something like this (ensure you adapt this to your actual `buf.gen.yaml` structure): 56 | 57 | ```yaml 58 | # buf.gen.yaml 59 | version: v2 60 | plugins: 61 | # - plugin: buf.build/protocolbuffers/go 62 | # out: src/go 63 | # - plugin: buf.build/protocolbuffers/python 64 | # out: src/python 65 | - plugin: buf.build/protocolbuffers/java 66 | out: src/java 67 | # - plugin: buf.build/grpc/typescript 68 | # out: src/ts 69 | ``` 70 | -------------------------------------------------------------------------------- /specification/grpc/buf.gen.yaml: -------------------------------------------------------------------------------- 1 | # buf generate 2 | # Configuration for the buf generate command 3 | # Uses remote plugins, no separate install required. 4 | # This config generates python, go and java (protobuf) source. 5 | version: v2 6 | plugins: 7 | # Python 8 | - remote: buf.build/protocolbuffers/python:v29.3 9 | out: src/python 10 | - remote: buf.build/grpc/python 11 | out: src/python 12 | 13 | # Go 14 | - remote: buf.build/protocolbuffers/go 15 | out: src/go 16 | 17 | - remote: buf.build/grpc/go 18 | out: src/go 19 | 20 | # Java 21 | - remote: buf.build/protocolbuffers/java 22 | out: src/java 23 | 24 | - remote: buf.build/grpc/java 25 | out: src/java 26 | 27 | # TypeScript 28 | - remote: buf.build/community/stephenh-ts-proto:v1.165.0 29 | out: src/typescript 30 | -------------------------------------------------------------------------------- /specification/grpc/buf.lock: -------------------------------------------------------------------------------- 1 | # Generated by buf. DO NOT EDIT. 2 | version: v2 3 | deps: 4 | - name: buf.build/googleapis/googleapis 5 | commit: 61b203b9a9164be9a834f58c37be6f62 6 | digest: b5:7811a98b35bd2e4ae5c3ac73c8b3d9ae429f3a790da15de188dc98fc2b77d6bb10e45711f14903af9553fa9821dff256054f2e4b7795789265bc476bec2f088c 7 | -------------------------------------------------------------------------------- /specification/grpc/buf.yaml: -------------------------------------------------------------------------------- 1 | version: v2 2 | deps: 3 | # Common Protobuf types. 4 | - buf.build/googleapis/googleapis 5 | lint: 6 | use: 7 | # Indicates that all the default rules should be used. 8 | # See https://buf.build/docs/lint/rules for more details. 9 | - STANDARD 10 | except: 11 | - PACKAGE_DIRECTORY_MATCH 12 | - RPC_REQUEST_RESPONSE_UNIQUE 13 | - RPC_REQUEST_STANDARD_NAME 14 | - RPC_RESPONSE_STANDARD_NAME 15 | breaking: 16 | use: 17 | # Indicates that breaking change detection should be done on a file level. 18 | # See https://buf.build/docs/breaking/rules for more details. 19 | - FILE 20 | -------------------------------------------------------------------------------- /specification/json/README.md: -------------------------------------------------------------------------------- 1 | # A2A Specification JSON 2 | 3 | DO NOT EDIT `a2a.json` directly. 4 | 5 | Make all edits in [`types/src/types.ts`](https://github.com/a2aproject/A2A/blob/main/types/src/types.ts) and follow the directions in [`types/README.md`](https://github.com/a2aproject/A2A/blob/main/types/README.md) 6 | -------------------------------------------------------------------------------- /types/.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules/ 3 | -------------------------------------------------------------------------------- /types/README.md: -------------------------------------------------------------------------------- 1 | # A2A Types 2 | 3 | Core objects and method types for A2A Protocol 4 | 5 | ## Steps to update 6 | 7 | 1. Clone this repository. 8 | 2. Run `npm install` 9 | 3. Update `types.ts` with required changes 10 | 4. Run `npm run generate`, this will update `a2a.json`. 11 | 5. Verify the updates and push to the repository. 12 | 13 | **DO NOT DIRECTLY CHANGE `a2a.json` file. THIS MUST BE GENERATED USING `npm run generate`** 14 | -------------------------------------------------------------------------------- /types/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "types", 3 | "version": "1.0.0", 4 | "main": "index.js", 5 | "scripts": { 6 | "generate": "./node_modules/.bin/typescript-json-schema tsconfig.json \"*\" --defaultNumberType integer --required --out ../specification/json/a2a.json", 7 | "prettier": "prettier src/types.ts --write" 8 | }, 9 | "author": "", 10 | "description": "A2A Types", 11 | "dependencies": { 12 | "typescript-json-schema": "^0.65.1" 13 | }, 14 | "devDependencies": { 15 | "prettier": "^3.5.3", 16 | "typescript": "^5.3.3" 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /types/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "noEmit": true, 4 | "emitDecoratorMetadata": true, 5 | "experimentalDecorators": true, 6 | "target": "ES5", 7 | "module": "CommonJS", 8 | "strictNullChecks": false, 9 | "skipLibCheck": true 10 | }, 11 | "include": ["**/*.ts"], 12 | "exclude": ["node_modules"] 13 | } 14 | --------------------------------------------------------------------------------