Compare commits

..

105 Commits

Author SHA1 Message Date
Iva Sokolaj
ae6a562d5d
docs: rename "Stream Message" to "Send Streaming Message" and replace legacy method names (#1784)
## Summary
Standardizes the operation names used throughout the spec and Python
tutorials so they match the canonical A2A operation names (`Send
Message` / `Send Streaming Message`) instead of the older JSON-RPC-style
identifiers (`message/send`, `message/stream`) or the inconsistent short
form `Stream Message`.
## Changes
- **`docs/specification.md`**
  - Architecture diagram: `Stream Message` → `Send Streaming Message`.
  - Section 3.1.3 (Get Task): `message/send` → `Send Message`.
  - Event delivery section: `Stream Message` → `Send Streaming Message`.
- Multi-protocol functionality table: `Stream message` → `Send Streaming
Message`.
- **`docs/tutorials/python/4-agent-executor.md`**: `message/send` /
`message/stream` → `Send Message` / `Send Streaming Message`.
- **`docs/tutorials/python/6-interact-with-server.md`**: same rename in
the `test_client.py` description.
- **`docs/tutorials/python/7-streaming-and-multiturn.md`**:
`message/send` → `Send Message` in the `CurrencyAgentExecutor`
walkthrough.
## Why
The docs previously mixed three different names for the same operations
(`message/stream`, `Stream Message`, `SendStreamingMessage`), which was
confusing for readers cross-referencing the spec, tutorials, and SDK.
This change picks one human-readable form per operation and uses it
consistently in prose, while leaving the code-level identifiers
(`SendMessage`, `SendStreamingMessage`, `POST /message:stream`, etc.)
untouched in the protocol-binding tables.
2026-04-23 13:54:31 +02:00
Iva Sokolaj
434d1fecbb
docs: use 127.0.0.1 in tutorial as in the referenced sample (#1783)
## Description
Follow-up cleanup to the Python helloworld tutorial to use the address
that the samples actually bind to.
## Changes
- **Host address**: Update tutorial references from
`http://localhost:9999/` to `http://127.0.0.1:9999/` so the docs match
the URL printed by the helloworld sample's Agent Card.
- Updated in `docs/tutorials/python/3-agent-skills-and-card.md` and
`docs/tutorials/python/6-interact-with-server.md`.
2026-04-23 12:27:17 +02:00
Iva Sokolaj
c5104cec72
docs: update Python helloworld tutorial for a2a-sdk v1.0 (#1775)
# Description
Update the Python tutorial to be compliant with the newly released A2A
SDK v1.0.

`Helloworld sample` referenced in the Python tutorial was updated to use
the new `v1.0.1`: [PR
527](https://github.com/a2aproject/a2a-samples/pull/527)
2026-04-23 11:23:52 +02:00
madankumarpichamuthu
7ff1004159
fix(spec): prefer application/a2a+json in HTTP binding (#1753)
## Summary
- Updates HTTP+JSON/REST binding guidance to state that
`application/a2a+json` SHOULD be used for request/response payloads.
- Aligns HTTP A2A examples in the spec to use `Content-Type:
application/a2a+json`.
- Keeps JSON-RPC-specific `/rpc` example on `application/json` to avoid
changing JSON-RPC semantics.

## Why
Issue #1748 identified inconsistent guidance: Section 11.1 said
`application/json`, while many HTTP examples and the registered A2A
media type (`application/a2a+json`) already pointed to A2A-specific
media typing.

This change resolves that inconsistency and improves interoperability
clarity for HTTP+JSON implementations.

Fixes #1748

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-04-21 09:53:57 -07:00
Yaroslav
757f0ec6d0
fix(spec): recent transcoding-related error changes (#1627)
Fix error code mappings table so that http codes correspond to
[`google.rpc.Code`](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto#L32)-defined
mappings.

Undo changes made in https://github.com/a2aproject/A2A/pull/1600 to
jsonrpc error handling section. The changes made were meant to address
http-grpc transcoding compatibility. I don't see a convincing reason for
forcing jsonrpc error data format, so I assume JSONRPC section was
updated by mistake.

Fixes https://github.com/a2aproject/A2A/issues/1596

---------

Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Mike Smith <mikeas@google.com>
2026-04-14 15:37:40 -04:00
Amye Scavarda Perrin
3947dacff8
docs(GOVERNANCE.md): How to add new TSC members (#1571)
1) How to add new TSC members

---------

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2026-04-09 13:23:55 -04:00
Holt Skinner
8dda73b3b4
docs: Add Rust SDK to list of official SDKs (#1729)
- Change table header to include repository instead of stability (all
are currently stable)

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Sampath Kumar <sam1990kumar@gmail.com>
2026-04-09 08:38:46 +00:00
Iva Sokolaj
b9f03d4c96
docs: update code snippet markers to match refactored sample identifiers (#1732)
Fixes:
https://a2a-protocol.org/latest/tutorials/python/6-interact-with-server/#understanding-the-client-code

Sample update: #508
2026-04-09 09:55:38 +02:00
dependabot[bot]
f1b45c522a
chore(deps): bump github-community-projects/issue-metrics from 3 to 4 in the github-actions group across 1 directory (#1707)
Bumps the github-actions group with 1 update in the / directory:
[github-community-projects/issue-metrics](https://github.com/github-community-projects/issue-metrics).

Updates `github-community-projects/issue-metrics` from 3 to 4
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/github-community-projects/issue-metrics/releases">github-community-projects/issue-metrics's
releases</a>.</em></p>
<blockquote>
<h2>v4.0.0</h2>
<h1>Changelog</h1>
<h2>🧰 Maintenance</h2>
<ul>
<li>build: update org name from github to github-community-projects <a
href="https://github.com/zkoppert"><code>@​zkoppert</code></a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/684">#684</a>)</li>
<li>chore(deps): bump pylint from 4.0.4 to 4.0.5 in the dependencies
group @<a href="https://github.com/apps/dependabot">dependabot[bot]</a>
(<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/681">#681</a>)</li>
<li>chore(deps): bump python from <code>486b809</code> to
<code>6a27522</code> @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/680">#680</a>)</li>
<li>ci: Update contributors action reference after repo transfer <a
href="https://github.com/zkoppert"><code>@​zkoppert</code></a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/677">#677</a>)</li>
<li>chore(deps): bump actions/stale from 10.1.1 to 10.2.0 in the
dependencies group @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/676">#676</a>)</li>
<li>chore(deps): bump python from <code>3955a7d</code> to
<code>486b809</code> @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/675">#675</a>)</li>
<li>chore(deps): bump black from 25.12.0 to 26.1.0 @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/673">#673</a>)</li>
<li>chore(deps): bump python from <code>2751cbe</code> to
<code>3955a7d</code> @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/664">#664</a>)</li>
<li>chore(deps): bump numpy from 2.4.1 to 2.4.2 in the dependencies
group @<a href="https://github.com/apps/dependabot">dependabot[bot]</a>
(<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/672">#672</a>)</li>
<li>chore(deps): bump numpy from 2.4.0 to 2.4.1 in the dependencies
group @<a href="https://github.com/apps/dependabot">dependabot[bot]</a>
(<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/666">#666</a>)</li>
<li>chore(deps): bump types-requests from 2.32.4.20250913 to
2.32.4.20260107 @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/667">#667</a>)</li>
<li>chore(deps): bump the dependencies group across 1 directory with 2
updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/671">#671</a>)</li>
<li>chore(deps): bump numpy from 2.3.5 to 2.4.0 in the dependencies
group @<a href="https://github.com/apps/dependabot">dependabot[bot]</a>
(<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/660">#660</a>)</li>
<li>chore(deps): bump the dependencies group with 6 updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/661">#661</a>)</li>
<li>chore(deps): bump actions/upload-artifact from 5.0.0 to 6.0.0 @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/659">#659</a>)</li>
<li>chore(deps): bump github/contributors from 1.7.7 to 1.7.8 in the
dependencies group @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/658">#658</a>)</li>
<li>chore(deps): bump mypy from 1.19.0 to 1.19.1 in the dependencies
group @<a href="https://github.com/apps/dependabot">dependabot[bot]</a>
(<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/657">#657</a>)</li>
</ul>
<p>See details of <a
href="https://github.com/github-community-projects/issue-metrics/compare/v3.25.5...v4.0.0">all
code changes</a> since previous release</p>
<h2>v3.25.5</h2>
<h1>Changelog</h1>
<h2>🧰 Maintenance</h2>
<ul>
<li>chore(deps): bump the dependencies group with 2 updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/655">#655</a>)</li>
<li>chore(deps): bump the dependencies group with 2 updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/654">#654</a>)</li>
<li>chore(deps): bump python from <code>b823ded</code> to
<code>2751cbe</code> @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/653">#653</a>)</li>
<li>chore(deps): bump python from <code>0aecac0</code> to
<code>b823ded</code> @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/648">#648</a>)</li>
</ul>
<p>See details of <a
href="https://github.com/github/issue-metrics/compare/v3.25.4...v3.25.5">all
code changes</a> since previous release</p>
<h2>v3.25.4</h2>
<h1>Changelog</h1>
<h2>🧰 Maintenance</h2>
<ul>
<li>chore(deps): bump the dependencies group with 4 updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/644">#644</a>)</li>
<li>chore(deps): bump the dependencies group with 2 updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/645">#645</a>)</li>
</ul>
<p>See details of <a
href="https://github.com/github/issue-metrics/compare/v3.25.3...v3.25.4">all
code changes</a> since previous release</p>
<h2>v3.25.3</h2>
<h1>Changelog</h1>
<h2>🧰 Maintenance</h2>
<ul>
<li>chore(deps): bump actions/checkout from 5.0.0 to 6.0.0 @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/639">#639</a>)</li>
<li>chore(deps): bump the dependencies group with 2 updates @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/638">#638</a>)</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="7bee6e6914"><code>7bee6e6</code></a>
chore(deps): bump cryptography from 46.0.5 to 46.0.6 (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/716">#716</a>)</li>
<li><a
href="ff28a0cbff"><code>ff28a0c</code></a>
Merge pull request <a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/715">#715</a>
from github-community-projects/fix/test-time-to-first...</li>
<li><a
href="7a3a883da1"><code>7a3a883</code></a>
fix: correct TypeError test to actually exercise exception handler</li>
<li><a
href="8bd2f25bef"><code>8bd2f25</code></a>
Merge pull request <a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/683">#683</a>
from meoyushi/feat-time-to-first-review</li>
<li><a
href="18503f1d94"><code>18503f1</code></a>
chore(deps): bump requests from 2.32.5 to 2.33.0 (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/712">#712</a>)</li>
<li><a
href="87b910fc69"><code>87b910f</code></a>
chore(deps): bump python from <code>584e89d</code> to
<code>fb83750</code> (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/710">#710</a>)</li>
<li><a
href="034369d98e"><code>034369d</code></a>
chore(deps): bump astral-sh/setup-uv in the dependencies group (<a
href="https://redirect.github.com/redirect.github.community-projects/issue-metrics/issues/711">#711</a>)</li>
<li><a
href="be94607e29"><code>be94607</code></a>
doc: mdformat for README.md</li>
<li><a
href="676b5cfd25"><code>676b5cf</code></a>
doc: README.md edited for time_to_first_review metric</li>
<li><a
href="10383509e0"><code>1038350</code></a>
doc: README.md edited for time_to_first_review metric</li>
<li>Additional commits viewable in <a
href="https://github.com/github-community-projects/issue-metrics/compare/v3...v4">compare
view</a></li>
</ul>
</details>
<br />

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-04-08 10:49:33 -05:00
Holt Skinner
a40261c464
docs: Add local build steps to Contributing Guide (#1726) 2026-04-07 14:50:14 -05:00
Amye Scavarda Perrin
43bddf8cc1
[Feat]: New logos + mascot (#1719)
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-04-07 13:09:37 -04:00
Sampath Kumar
3c0e23e996
docs: fix table duplication in A2A Specification document (#1704) 2026-04-07 10:13:34 -05:00
Sam Betts
66df070988
docs: Add custom protocol bindings documentation (#1619)
## Summary

- Adds `docs/topics/custom-protocol-bindings.md`, a dedicated page
documenting custom protocol bindings as a concept distinct from
extensions; covers declaration in the Agent Card, specification
requirements, key areas to address (data type mappings, service
parameters, error mapping, streaming, authentication), and
interoperability testing
- Adds `docs/topics/extension-and-binding-governance.md`, merging the
governance content previously in `extensions.md` with the equivalent
custom protocol binding governance; deduplicates the tiers section into
a single section with a naming table; notes that SDKs SHOULD implement
official custom protocol bindings vs MAY for extensions
- Adds spec section 5.8 defining URI-based custom binding identification
as a SHOULD requirement and updates the section 12.7 Agent Card example
accordingly
- Replaces the verbose inline governance sections in `extensions.md` and
`custom-protocol-bindings.md` with short summaries linking to the new
governance page
- Adds Custom Protocol Bindings and Extension & Binding Governance to
the mkdocs.yml nav

---------

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-04-07 13:31:18 +02:00
Sam Betts
74c7c62286
fix: pin check-spelling action to v0.0.26 (#1722)
# Description

- [ ] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md).
- [ ] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [ ] Ensure the tests and linter pass (Run `nox -s format` from the
repository root to format)
- [ ] Appropriate docs were updated (if necessary)

Pins the `check-spelling/check-spelling` action to `v0.0.26` to resolve
the unsafe workflow configuration error (exit code 5) that was blocking
all PRs from passing the Check Spelling CI gate.

Fixes #1710 🦕

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2026-04-07 13:07:06 +02:00
Zack Koppert
c1169f4572
fix: update OSPO action references to canonical org path (#1705)
Updates GitHub Actions workflow references from the legacy `github/` org
path to the canonical `github-community-projects/` path.

The following OSPO actions have been transferred to the
`github-community-projects` organization:

| Legacy path | Canonical path |
|---|---|
| `github/issue-metrics` | `github-community-projects/issue-metrics` |

While GitHub's repo redirect ensures the old paths still work today,
updating to the canonical path avoids depending on the redirect and
ensures long-term stability.

**No functional changes** - the same action versions are referenced.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-03-31 13:42:10 -07:00
alan blount
f991a08f2c
docs: add Community SDKs (#1698)
## Summary

Add a Community SDKs section to the Community Hub page listing
community-maintained A2A SDK implementations for languages not covered
by official SDKs.

Fixes #1602

## Changes

- **Updated: `docs/community.md`** — inline SDK directory section with
listings and submission requirements
- **Updated: `mkdocs.yml`** — cleaned up nav
- **Updated: `.github/actions/spelling/allow.txt`** — added GitHub
usernames

## Initial Listings

| Language | Repository | Package | Spec Version |
|----------|-----------|---------|-------------|
| 🦀 Rust | [tomtom215/a2a-rust](https://github.com/tomtom215/a2a-rust) |
[crates.io](https://crates.io/crates/a2a-protocol-sdk) | 1.0.0 |
| 🦀 Rust | [EmilLindfors/a2a-rs](https://github.com/EmilLindfors/a2a-rs)
| [crates.io](https://crates.io/crates/a2a-rs) | 0.3.0 |
| 🍎 Swift |
[tolgaki/a2a-client-swift](https://github.com/tolgaki/a2a-client-swift)
| SPM | 1.0.0 |
| 💧 Elixir |
[actioncard/a2a-elixir](https://github.com/actioncard/a2a-elixir) |
[hex.pm](https://hex.pm/packages/a2a) | 0.2.0 |

## Context

Community SDKs are emerging (see
[#1638](https://github.com/a2aproject/A2A/issues/1638) for the Rust
SDK), but there was no place in the docs for users to discover them.
Rather than a standalone page, these are inlined as a section on the
Community Hub for better discoverability.

---------

Co-authored-by: Zaf (AI Assistant) <zaf@0-a.org>
2026-03-31 09:43:27 -07:00
petterlindstrom79
5ac9d2c7d7
docs: add Strale to partners list (#1702)
Adds [Strale](https://strale.dev) to the A2A partners list.

Strale is an API capability marketplace for AI agents with a live A2A
implementation:

- **Agent Card**: https://api.strale.io/.well-known/agent-card.json
- **A2A endpoint**: `POST https://api.strale.io/a2a` (JSON-RPC:
`message/send`, `tasks/get`)
- **273 skills** across compliance, company data (27 countries),
financial validation, Web3/DeFi, and developer tools
- **Link header** on all responses: `Link:
</.well-known/agent-card.json>; rel="agent-card"`

Also accessible via MCP (Streamable HTTP), REST API, and x402 (USDC
micropayments on Base).
2026-03-30 07:35:29 -07:00
ivoshemi-sys
72d1459ddb
Add OIXA Protocol to partners list (#1692)
## Summary

[OIXA Protocol](https://oixa.io) is a live open protocol where AI agents
hire and pay other AI agents autonomously — built on A2A for agent
communication, with economic guarantees on Base Mainnet.

## How OIXA uses A2A

OIXA builds directly on A2A as the communication layer for agent
discovery and task coordination. It publishes a standard A2A agent card:

```
http://64.23.235.34:8000/.well-known/agent.json
```

**Protocol stack:**
- **COMMS:** A2A + MCP — agent discovery and task protocol
- **PAYMENT:** x402 Protocol — autonomous HTTP payments
- **FUNDS:** Base Mainnet + USDC — trustless on-chain escrow
- **REGISTRY:** ERC-8004 — on-chain agent identity

## What OIXA adds on top of A2A

A2A defines *how* agents communicate. OIXA defines *how they transact*
when that communication leads to work that should exchange value:

- Reverse auction discovery: agents bid to complete tasks (lowest bid
wins)
- On-chain USDC escrow: funds lock at bid acceptance, release
automatically on verified delivery
- Cryptographic output verification: not just delivery confirmation but
quality verification
- Stake-based anti-Sybil: 20% stake per bid makes economic attacks
impossible
- On-chain reputation: every completed A2A transaction builds a
verifiable score

## Links

- Site: https://oixa.io
- GitHub: https://github.com/ivoshemi-sys/oixa-protocol
- SDK: `pip install oixa-protocol` (LangChain, CrewAI, AutoGen,
Haystack, MCP)
- Live API: http://64.23.235.34:8000/docs
- A2A agent card: http://64.23.235.34:8000/.well-known/agent.json

Co-authored-by: Openclaw <Openclaw@Mac-mini-de-Ivan.local>
2026-03-27 09:37:45 -07:00
Iva Sokolaj
32a7d3a0bd
docs: update python tutorial for a2a-sdk v1.0.0-alpha.0 (#1678)
Issue: #1679

# Description

[a2a-samples/python](https://github.com/a2aproject/a2a-samples/tree/main/samples/python)
is being updated to use the new `v1.0`:
[samples-#462](https://github.com/a2aproject/a2a-samples/issues/462). We
are looking to merge [update helloworld sample to
v1.0-alpha](https://github.com/a2aproject/a2a-samples/pull/474) and
consequently need to update python tutorial in A2A as it references the
`helloworld sample`.

# Key Changes
- **Agent Skills & Card** (3-agent-skills-and-card.md): Updated the docs
to match the new AgentCard schema. Replaced the legacy `url` property
with `icon_url`, documented the new `supported_interfaces` field for
protocol bindings, and added mentions of the extended_agent_card
capability.
- **HelloWorldAgentExecutor logic** (4-agent-executor.md): Rewrote the
walkthrough for the execute method to reflect the modern event-driven
approach and to make the difference between non-streaming and streaming
more clear. It now explicitly describes enqueueing Task,
TaskStatusUpdateEvent (with `TASK_STATE_WORKING`),
TaskArtifactUpdateEvent, and TaskStatusUpdateEvent (with
`TASK_STATE_COMPLETED`) instead of single string messages.
- **Server Setup** (5-start-server.md): Replaced `0.0.0.0` with
`127.0.0.1` in the host binding tutorial and log examples to enforce
safer local testing defaults.
- **Client Interaction** (6-interact-with-server.md): 
- Replaced MessageSendParams dictionaries with native protobuf
`Message/Part/Role` construction.
- Replaced direct A2ACardResolver instantiation with the new
`ClientFactory` approach.
- Unified the documentation around `send_message` (which now handles
streams dynamically based on `config` and agent capabilities) and
updated expected log outputs.
2026-03-26 13:50:49 +01:00
Amye Scavarda Perrin
7b900e77be
Update CODEOWNERS (#1644)
TSC is the reviewing body for this project!
2026-03-16 11:25:06 -07:00
Alex
3c1a5ff473
docs: add WritBase to partners list (#1634)
Closes #1636

Adds [WritBase](https://github.com/Writbase/writbase) to the A2A
partners list.

WritBase is an MCP-native task management control plane for AI agent
fleets — Postgres-backed, multi-tenant, with full provenance tracking.
It includes bidirectional A2A↔WritBase status mapping alignment and
supports inter-agent task delegation with assignment tracking and
delegation safety.
2026-03-16 11:18:55 -07:00
Amye Scavarda Perrin
7df7685561
Update main.html
Reverting to previous announcement.
2026-03-12 11:59:00 -07:00
Amye Scavarda Perrin
b750332f4c
Update main.html
Dropping the override.
2026-03-12 11:25:32 -07:00
Amye Scavarda Perrin
625146ede8
Update main.html (#1623) 2026-03-12 11:18:16 -07:00
Holt Skinner
f86c799f09 docs: Update TOC to include 1.0 Blog Post 2026-03-12 12:17:47 -05:00
Darrel
4f77f1bdd0
docs: Blog post announcing V1.0 (#1621)
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
Co-authored-by: ToddSegal <10716715+ToddSegal@users.noreply.github.com>
2026-03-12 17:02:05 +00:00
Holt Skinner
ee335737c9
ci(docs): Update docs workflow to allow manual updates for versions (#1622) 2026-03-12 11:55:05 -05:00
Holt Skinner
6845a87b50
docs: Update Specification.md for 1.0.0 from release candidate (#1620) 2026-03-12 11:47:56 -05:00
Agent2Agent (A2A) Bot
1736957556
chore(main): release 1.0.0 (#1221)
🤖 I have created a release *beep* *boop*
---


## [1.0.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v1.0.0)
(2026-03-12)


### ⚠ BREAKING CHANGES

* **spec:** Combine `TaskPushNotificationConfig` and
`PushNotificationConfig`
([#1500](https://github.com/a2aproject/A2A/issues/1500))
* **spec:** remove duplicated ID from the create task push config
request ([#1487](https://github.com/a2aproject/A2A/issues/1487))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs`
([#1486](https://github.com/a2aproject/A2A/issues/1486))
* **spec:** Add LF prefix to the package.
([#1474](https://github.com/a2aproject/A2A/issues/1474))
* **spec:** Switch to non-complex IDs in requests
([#1389](https://github.com/a2aproject/A2A/issues/1389))
* **spec:** Standardize spelling of "canceled" to use American Spelling
throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283))
* **spec:** Align enum format with ADR-001 ProtoJSON specification
([#1384](https://github.com/a2aproject/A2A/issues/1384))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent`
([#1308](https://github.com/a2aproject/A2A/issues/1308))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities`
([#1307](https://github.com/a2aproject/A2A/issues/1307))
* **spec:** Fixes for the last_updated_after field
([#1358](https://github.com/a2aproject/A2A/issues/1358))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add
device code / pkce
([#1303](https://github.com/a2aproject/A2A/issues/1303))
* **spec:** Make "message" field name consistent between protocol
bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release
([#1301](https://github.com/a2aproject/A2A/issues/1301))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to
`supportsExtendedAgentCard`
([#1222](https://github.com/a2aproject/A2A/issues/1222))
* **spec:** Remove v1s from a2a url http bindings
* **spec:** Large refactor of specification to separate application
protocol definition from mapping to transports

### Features

* **spec:** Add `tasks/list` method with filtering and pagination to the
specification
([0a9f629](0a9f629e80))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add
device code / pkce
([#1303](https://github.com/a2aproject/A2A/issues/1303))
([525ff38](525ff38e5f))
* **spec:** Natively Support Multi-tenancy on gRPC through an additional
scope field on the request.
([#1195](https://github.com/a2aproject/A2A/issues/1195))
([cfbce32](cfbce32cb0)),
closes [#1148](https://github.com/a2aproject/A2A/issues/1148)
* **spec:** Provide ability for SDKs to be backwards compatible.
([#1401](https://github.com/a2aproject/A2A/issues/1401))
([227e249](227e2493c3))
* **spec:** Remove v1s from a2a url http bindings
([1bd263f](1bd263f537))


### Bug Fixes

* Add missing metadata field to Part message in gRPC specification
([#1019](https://github.com/a2aproject/A2A/issues/1019))
([b3b266d](b3b266d127)),
closes [#1005](https://github.com/a2aproject/A2A/issues/1005)
* Add name field to FilePart protobuf message
([#983](https://github.com/a2aproject/A2A/issues/983))
([2b7cb6f](2b7cb6f840)),
closes [#984](https://github.com/a2aproject/A2A/issues/984)
* Clarify blocking calls return on interrupted states
([#1403](https://github.com/a2aproject/A2A/issues/1403))
([0655ff3](0655ff324a))
* **doc:** Makes JSON-RPC SendMessage response clearer
([#1241](https://github.com/a2aproject/A2A/issues/1241))
([5792804](5792804372))
* **docs:** Clearer wording around context id.
([#1588](https://github.com/a2aproject/A2A/issues/1588))
([dec790a](dec790aa06))
* **grpc:** Fix inconsistent property name between gRPC and JSON-RPC in
Message object ([#1100](https://github.com/a2aproject/A2A/issues/1100))
([2a1f819](2a1f819aaa))
* **grpc:** missing field in gRPC spec - state_transition_history
([#1138](https://github.com/a2aproject/A2A/issues/1138))
([a2de798](a2de7981ca)),
closes [#1139](https://github.com/a2aproject/A2A/issues/1139)
* **grpc:** Update `CreateTaskPushNotificationConfig` endpoint to
`/v1/{parent=tasks/*/pushNotificationConfigs}`
([#979](https://github.com/a2aproject/A2A/issues/979))
([911f9b0](911f9b059c))
* **proto:** Add icon_url to a2a.proto
([#986](https://github.com/a2aproject/A2A/issues/986))
([17e7f62](17e7f62df9))
* **proto:** Adds metadata field to A2A DataPart proto
([#1004](https://github.com/a2aproject/A2A/issues/1004))
([a8b45dc](a8b45dcc42))
* Remove unimplemented state_transition_history capability field
([#1396](https://github.com/a2aproject/A2A/issues/1396))
([c768a44](c768a44da0)),
closes [#1228](https://github.com/a2aproject/A2A/issues/1228)
* Restore CreateTaskPushNotificationConfig method naming
([#1402](https://github.com/a2aproject/A2A/issues/1402))
([d14f410](d14f410711))
* Revert "chore(gRPC): Update a2a.proto to include metadata on
GetTaskRequest" ([#1000](https://github.com/a2aproject/A2A/issues/1000))
([e6b8c65](e6b8c654a8))
* Simplify Part message structure by flattening FilePart and DataPart
([#1411](https://github.com/a2aproject/A2A/issues/1411))
([bfae8f7](bfae8f7791))
* **spec:** Add LF prefix to the package.
([#1474](https://github.com/a2aproject/A2A/issues/1474))
([a54e809](a54e80904a))
* **spec:** add metadata to `CancelTaskRequest`
([#1485](https://github.com/a2aproject/A2A/issues/1485))
([c441b91](c441b910b6)),
closes [#1484](https://github.com/a2aproject/A2A/issues/1484)
* **spec:** Added clarification on timestamps in HTTP query params
([#1425](https://github.com/a2aproject/A2A/issues/1425))
([6292104](6292104e35))
* **spec:** Added clarifying text around messages and artifacts
([#1424](https://github.com/a2aproject/A2A/issues/1424))
([b03d141](b03d141aea))
* **spec:** Adjust field number for `ListTasksRequest.tenant` to prevent
missing number ([#1470](https://github.com/a2aproject/A2A/issues/1470))
([cd16c52](cd16c5276b))
* **spec:** Clarify contextId behavior when message is sent with taskId
but without contextId
([#1309](https://github.com/a2aproject/A2A/issues/1309))
([a336a5a](a336a5a484))
* **spec:** Clarify versioning strategy and client responsibilities in
protocol specification
([#1259](https://github.com/a2aproject/A2A/issues/1259))
([a4afeea](a4afeea788))
* **spec:** Fix/1251 clarify authentication scheme
([#1256](https://github.com/a2aproject/A2A/issues/1256))
([3e6c7db](3e6c7db907))
* **spec:** Fixes for the last_updated_after field
([#1358](https://github.com/a2aproject/A2A/issues/1358))
([0e204bf](0e204bf878))
* **spec:** Make "message" field name consistent between protocol
bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302))
([1e5f462](1e5f462064)),
closes [#1230](https://github.com/a2aproject/A2A/issues/1230)
* **spec:** make `history_length` optional
([#1071](https://github.com/a2aproject/A2A/issues/1071))
([0572953](057295311b))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs`
([#1486](https://github.com/a2aproject/A2A/issues/1486))
([cf735cb](cf735cb870))
* **spec:** Remove config from binding.
([#1587](https://github.com/a2aproject/A2A/issues/1587))
([010b9cc](010b9cc936))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release
([#1301](https://github.com/a2aproject/A2A/issues/1301))
([60f83c3](60f83c3faa)),
closes [#1227](https://github.com/a2aproject/A2A/issues/1227)
* **spec:** remove duplicated ID from the create task push config
request ([#1487](https://github.com/a2aproject/A2A/issues/1487))
([393898d](393898dfee))
* **spec:** Remove metadata field from ListTasksRequest
([#1235](https://github.com/a2aproject/A2A/issues/1235))
([b6ef9ee](b6ef9eec55))
* **spec:** Remove reserved and fix tags ordering
([#1494](https://github.com/a2aproject/A2A/issues/1494))
([1997c9d](1997c9d630))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to
`supportsExtendedAgentCard`
([#1222](https://github.com/a2aproject/A2A/issues/1222))
([c196824](c196824396)),
closes [#1215](https://github.com/a2aproject/A2A/issues/1215)
* **spec:** Standardize spelling of "canceled" to use American Spelling
throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283))
([4dd980f](4dd980f6ff))
* **spec:** Suggest Unique Identifier fields to be UUID
([#966](https://github.com/a2aproject/A2A/issues/966))
([00cf76e](00cf76e7bb))
* **spec:** Switch to non-complex IDs in requests
([#1389](https://github.com/a2aproject/A2A/issues/1389))
([2596c1c](2596c1c5e0)),
closes [#1390](https://github.com/a2aproject/A2A/issues/1390)
* **spec:** Update security schemes example
([#1364](https://github.com/a2aproject/A2A/issues/1364))
([f9a8f5b](f9a8f5b85d))
* Update the Java tutorials and descriptions
([#1181](https://github.com/a2aproject/A2A/issues/1181))
([202aa06](202aa069e6))


### Documentation

* **spec:** Align enum format with ADR-001 ProtoJSON specification
([#1384](https://github.com/a2aproject/A2A/issues/1384))
([810eaa1](810eaa1c6e)),
closes [#1344](https://github.com/a2aproject/A2A/issues/1344)


### Code Refactoring

* **spec:** Combine `TaskPushNotificationConfig` and
`PushNotificationConfig`
([#1500](https://github.com/a2aproject/A2A/issues/1500))
([d1ed0da](d1ed0da587))
* **spec:** Large refactor of specification to separate application
protocol definition from mapping to transports
([b078419](b078419954))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities`
([#1307](https://github.com/a2aproject/A2A/issues/1307))
([40d6286](40d6286fbe))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent`
([#1308](https://github.com/a2aproject/A2A/issues/1308))
([5b101cc](5b101cce0f))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-03-12 12:34:00 -04:00
Copilot
087604615d
docs: fix inconsistent HTTP method for list tasks examples in specification (#1613)
Fixes #1612

Section 6.5 examples used `POST /tasks/list` with a JSON body,
contradicting section 11.3.2 which correctly defines list tasks as `GET
/tasks` with query parameters.

## Changes

- **`docs/specification.md` — Section 6.5 (Task Listing and
Management):** Updated all four HTTP examples to use `GET /tasks` with
query parameters instead of `POST /tasks/list` with a request body:

  | Example | Before | After |
  |---|---|---|
| All tasks from a specific context | `POST /tasks/list` + JSON body |
`GET /tasks?contextId=...&pageSize=10&historyLength=3` |
| All working tasks across all contexts | `POST /tasks/list` + JSON body
| `GET /tasks?status=working&pageSize=20` |
| Pagination | `POST /tasks/list` + JSON body | `GET
/tasks?contextId=...&pageSize=10&pageToken=...` |
| Validation error | `POST /tasks/list` + JSON body | `GET
/tasks?pageSize=150&historyLength=-5&status=running` |

Enum values in query parameters now use the short form (e.g.,
`status=working`) per the field type handling rules already defined in
section 11.5.

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/a2aproject/A2A/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: darrelmiller <447694+darrelmiller@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-03-12 11:30:50 -05:00
Ritsuki Yamada
727168fe1f
docs(spec): Add HTTP caching guidance for Agent Card endpoints (#1479)
Closes #1478. Related to #306.

The specification provides caching guidance for Extended Agent Cards
(Sections 3.1.11 and 13.3) but has no equivalent guidance for public
Agent Cards. This creates a gap for SDK and framework implementers —
none of the five official SDKs currently implement Agent Card caching,
and framework implementers have noted the lack of protocol-level
guidance (google/adk-python#3297).

This PR adds SHOULD-level HTTP caching guidance, following the precedent
of OpenID Connect Discovery 1.0 (same `.well-known` URI pattern).

**Changes:**

- **`docs/specification.md`**: Add Section 8.6 "Caching" with normative
guidance on `Cache-Control`, `ETag`, and conditional requests. Placed
after Section 8.5 (Sample Agent Card) to avoid renumbering existing
sections and breaking anchor links.
- **`docs/topics/agent-discovery.md`**: Add "Caching Considerations"
section with practical guidance for implementers.

---------

Co-authored-by: Darrel <darrmi@microsoft.com>
2026-03-12 16:24:35 +00:00
Kuba Herczyński
149cb82d38
docs: Fixes to the "what's new in v1" docs. (#1616) 2026-03-12 16:22:50 +00:00
Mike Smith
7415773696
refactor(spec): Update HTTP+JSON error mapping to use google.rpc.Status AIP-193 (#1600)
Updates the specification to require use of `google.rpc.Status`
formatted JSON objects for error response bodies in HTTP+JSON mapping.

See related issue for reasoning.

Fixes #1596

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-03-12 09:15:26 -07:00
dependabot[bot]
5fed760884
chore(deps): bump astral-sh/setup-uv from 5 to 7 in the github-actions group (#1572)
Bumps the github-actions group with 1 update:
[astral-sh/setup-uv](https://github.com/astral-sh/setup-uv).

Updates `astral-sh/setup-uv` from 5 to 7
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/setup-uv/releases">astral-sh/setup-uv's
releases</a>.</em></p>
<blockquote>
<h2>v7.2.1 🌈 update known checksums up to 0.9.28</h2>
<h2>Changes</h2>
<h2>🧰 Maintenance</h2>
<ul>
<li>chore: update known checksums for 0.9.28 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/744">#744</a>)</li>
<li>chore: update known checksums for 0.9.27 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/742">#742</a>)</li>
<li>chore: update known checksums for 0.9.26 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/734">#734</a>)</li>
<li>chore: update known checksums for 0.9.25 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/733">#733</a>)</li>
<li>chore: update known checksums for 0.9.24 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/730">#730</a>)</li>
</ul>
<h2>📚 Documentation</h2>
<ul>
<li>Clarify impact of using actions/setup-python <a
href="https://github.com/eifinger"><code>@​eifinger</code></a> (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/732">#732</a>)</li>
</ul>
<h2>⬆️ Dependency updates</h2>
<ul>
<li>Bump zizmorcore/zizmor-action from 0.3.0 to 0.4.1 @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/741">#741</a>)</li>
</ul>
<h2>v7.0.0 🌈 node24 and a lot of bugfixes</h2>
<h2>Changes</h2>
<p>This release comes with a load of bug fixes and a speed up. Because
of switching from node20 to node24 it is also a breaking change. If you
are running on GitHub hosted runners this will just work, if you are
using self-hosted runners make sure, that your runners are up to date.
If you followed the normal installation instructions your self-hosted
runner will keep itself updated.</p>
<p>This release also removes the deprecated input
<code>server-url</code> which was used to download uv releases from a
different server.
The <a
href="https://github.com/astral-sh/setup-uv?tab=readme-ov-file#manifest-file">manifest-file</a>
input supersedes that functionality by adding a flexible way to define
available versions and where they should be downloaded from.</p>
<h3>Fixes</h3>
<ul>
<li>The action now respects when the environment variable
<code>UV_CACHE_DIR</code> is already set and does not overwrite it. It
now also finds <a
href="https://docs.astral.sh/uv/reference/settings/#cache-dir">cache-dir</a>
settings in config files if you set them.</li>
<li>Some users encountered problems that <a
href="https://github.com/astral-sh/setup-uv?tab=readme-ov-file#disable-cache-pruning">cache
pruning</a> took forever because they had some <code>uv</code> processes
running in the background. Starting with uv version <code>0.8.24</code>
this action uses <code>uv cache prune --ci --force</code> to ignore the
running processes</li>
<li>If you just want to install uv but not have it available in path,
this action now respects <code>UV_NO_MODIFY_PATH</code></li>
<li>Some other actions also set the env var <code>UV_CACHE_DIR</code>.
This action can now deal with that but as this could lead to unwanted
behavior in some edgecases a warning is now displayed.</li>
</ul>
<h3>Improvements</h3>
<p>If you are using minimum version specifiers for the version of uv to
install for example</p>
<pre lang="toml"><code>[tool.uv]
required-version = &quot;&gt;=0.8.17&quot;
</code></pre>
<p>This action now detects that and directly uses the latest version.
Previously it would download all available releases from the uv repo
to determine the highest matching candidate for the version specifier,
which took much more time.</p>
<p>If you are using other specifiers like <code>0.8.x</code> this action
still needs to download all available releases because the specifier
defines an upper bound (not 0.9.0 or later) and &quot;latest&quot; would
possibly not satisfy that.</p>
<h2>🚨 Breaking changes</h2>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="5a095e7a20"><code>5a095e7</code></a>
Bump github/codeql-action from 4.31.9 to 4.32.2 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/766">#766</a>)</li>
<li><a
href="b12532f27f"><code>b12532f</code></a>
fix: fall back to VERSION_CODENAME when VERSION_ID is not available (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/774">#774</a>)</li>
<li><a
href="0098a7571c"><code>0098a75</code></a>
chore: update known checksums for 0.10.6 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/771">#771</a>)</li>
<li><a
href="2e7ed0e2bb"><code>2e7ed0e</code></a>
chore: update known checksums for 0.10.5 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/770">#770</a>)</li>
<li><a
href="04224aa8ca"><code>04224aa</code></a>
chore: update known checksums for 0.10.4 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/768">#768</a>)</li>
<li><a
href="2bc602ff89"><code>2bc602f</code></a>
chore: update known checksums for 0.10.3 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/767">#767</a>)</li>
<li><a
href="dd9d748439"><code>dd9d748</code></a>
chore: update known checksums for 0.10.2 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/765">#765</a>)</li>
<li><a
href="14eede1834"><code>14eede1</code></a>
chore: update known checksums for 0.10.1 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/764">#764</a>)</li>
<li><a
href="c452423b2c"><code>c452423</code></a>
Bump zizmorcore/zizmor-action from 0.4.1 to 0.5.0 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/763">#763</a>)</li>
<li><a
href="eac588ad8d"><code>eac588a</code></a>
Bump typesafegithub/github-actions-typing from 2.2.1 to 2.2.2 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/753">#753</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/astral-sh/setup-uv/compare/v5...v7">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=astral-sh/setup-uv&package-manager=github_actions&previous-version=5&new-version=7)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-03-12 16:09:12 +00:00
Sunil Prakash
0833a5f5fd
docs: add JamJet to partners list (#1615)
## Summary

- Adds [JamJet](https://github.com/jamjet-labs/jamjet) to the partners
list in alphabetical order
- JamJet is an open-source agent-native runtime with native A2A client +
server support built in Rust

Closes #1602

---------

Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
2026-03-11 10:21:20 -07:00
Vinay Ramesh
e2eb7d2b4b
docs: Extension governance (#1488)
Brings extension governance from issue #1406 into A2A documentation spec

Closes #1406

---------

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Kuba Herczyński <herczyn@google.com>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2026-03-11 13:44:49 +01:00
Amye Scavarda Perrin
2c9bc7ecd9
docs: Update roadmap.md (#1610)
Update roadmap to forthcoming 1.0 release

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-03-10 11:44:17 -07:00
Mike Smith
477a0ee304
docs: Expand details on In-Task Authorization. (#1597)
The previous wording was very barebones. We have explored this area
significantly more, and the specification now reflects further guidance
on how to handle retrieving authorizations and credentials during Task
processing.

This specifically addresses the missing guidance on how clients are
expected to respond to a Task in `TASK_STATE_AUTH_REQUIRED`.

Fixes #1582.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-03-10 13:16:01 -04:00
Ivan Shymko
601c408aec
refactor(spec): rename SendMessageConfiguration.blocking to SendMessageConfiguration.return_immediately (#1507)
As mentioned in the linked issue, defaulting to non-blocking behavior is
counterintuitive and is implemented the opposite way in the SDKs.

Renaming it to `return_immediately` makes default behavior simpler while
advanced scenario requires an extra flag.

---
Previos proposals:
1. `polling` has inaccurate meaning in this context as pointed out in
the comments.
2. `non_blocking` is a negative boolean which leads to confusing
conditional expressions (`not non_blocking`).

Fixes #1453

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-03-10 17:06:43 +01:00
Amye Scavarda Perrin
aca981cee3
Update GOVERNANCE.md (#1598)
Adding new TSC member from AWS
2026-03-06 12:55:06 -08:00
Kuba Herczyński
dec790aa06
fix(docs): Clearer wording around context id. (#1588)
client side context id passing can be supported, server can choose to
reject, client's should know how to fallback accordingly
if server accepts, server must respond with the context id
if server cannot accept client side context id it MUST respond with an
error (i.e. it SHOULD not respond with a task with a different context
id?)
servers may not accept a client side context id for a number of reasons:
clashes, validation errors, not supporting context ids

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-03-05 12:33:36 +01:00
Kuba Herczyński
010b9cc936
fix(spec): Remove config from binding. (#1587)
Fix error caused by #1500:

× Failed to build `a2a-sdk @
file:///home/runner/work/a2a-python/a2a-python`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `hatchling.build.build_editable` failed (exit status: 1)

      [stderr]
      Failure: failed_precondition: plugin
"buf.build/grpc-ecosystem/openapiv2:v2.28.0" failed: no field "config"
      found in TaskPushNotificationConfig
2026-03-04 13:33:14 +01:00
Kuba Herczyński
d1ed0da587
refactor(spec)!: Combine TaskPushNotificationConfig and PushNotificationConfig (#1500)
**this PR:**
- removes CreateTaskPushNotificationConfigRequest and replace it with
TaskPushNotificationConfig (same fields).
- flattend TaskPushNotificationConfig and PushNotificationConfig
removing the latter
- puts TaskPushNotificationConfig in SendMessageConfig instead of the
removed PushNotificationConfig

**why:** more readable structure, with less messages but with the same
possibilities

Release-As: 1.0.0

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-03-03 18:56:38 +01:00
AgentTrust.ai
dbb1bf8e60
docs: add AgentTrust to partners list (#1568)
This PR adds [AgentTrust](https://agenttrust.ai) to the partners list,
alphabetically between AG2AI and AI21 Labs.

**About AgentTrust:**
AgentTrust is trust and identity infrastructure for agentic
collaboration. We provide hosted A2A endpoints with Agent Card
discovery, Ed25519 message signing, human-in-the-loop escalation, and
prompt injection detection.

**What we've built:**
- Hosted A2A endpoints — agents get a public A2A identity at
`/a2a/{slug}` without running a server
- Standard Agent Card served at `/.well-known/agent.json` per agent
- Direct A2A JSON-RPC ingress (`tasks/send`) with allowlist,
InjectionGuard, and HITL rules
- Ed25519 message signing — cryptographic identity verification between
agents
- Negotiation lifecycle extending A2A task states via metadata
extensions (`propose_complete`, `disputed`, `rejected`)
- MCP server with 13 tools —
[npm](https://www.npmjs.com/package/@agenttrust/mcp-server) |
[GitHub](https://github.com/agenttrust/mcp-server)
- Webhook delivery with HMAC-SHA256 signatures

**Links:**
- Website: https://agenttrust.ai
- MCP Server: https://github.com/agenttrust/mcp-server
- npm: https://www.npmjs.com/package/@agenttrust/mcp-server

Built on Google's A2A protocol. We fill the identity and trust gap — A2A
defines how agents talk, AgentTrust helps them prove who they are.

---------

Co-authored-by: AgentTrust <hello@agenttrust.ai>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
2026-03-02 15:09:02 -08:00
Pinchwork
789bc73d8b
docs: add Pinchwork to partners list (#1498)
Hi Amye and team,

Following up on issue #1443 ("Add Pinchwork as A2A-compatible agent
marketplace") — thank you for the warm welcome and for pointing us to
the partners list!

This PR adds [Pinchwork](https://pinchwork.dev) to the partners list,
alphabetically between Personal AI and Poppulo.

**About Pinchwork:**
Pinchwork is an agent-to-agent task marketplace where AI agents can post
tasks, pick up work, and earn credits — all via a simple API. We have a
live A2A endpoint at `/.well-known/agent-card.json` and a JSON-RPC A2A
endpoint at `/a2a`, supporting `message/send`, `tasks/get`, and
`tasks/cancel`.

We're excited to be part of the A2A ecosystem and look forward to
contributing to interoperability between agents.

Resolves #1443

Co-authored-by: Pinchwork <hello@pinchwork.dev>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
2026-03-02 14:45:10 -08:00
Holt Skinner
4890b77d6f
docs: Fix embedded version of AgentExtension in extensions (#1550) 2026-02-26 13:14:05 -06:00
Ivan Shymko
a3e2e1f8c6
build: use go 1.25 to work with latest buf (#1509)
https://github.com/a2aproject/A2A/actions/runs/22359664144 fails with

```
go: github.com/bufbuild/buf/cmd/buf@latest: github.com/bufbuild/buf@v1.66.0 requires go >= 1.25.6 (running go 1.24.12; GOTOOLCHAIN=local)
```

Long term docs.yml probably shouldn't use `@latest` to avoid such
breakages in CI without code changes.

Re #1510 (adding `no-issue` as it's not `Fixes`)
2026-02-24 10:35:28 -06:00
Gijs Walraven
629190aea9
docs: wrap Task in result.task in life-of-a-task examples (#1492)
## Issue

Closes #1368 — Clarify whether JSON-RPC result should wrap Task/Message
objects

## Problem

Both response examples in `docs/topics/life-of-a-task.md` returned Task
fields directly inside `result`:

```json
"result": {
  "id": "task-boat-gen-123",
  "status": { ... },
  "artifacts": [ ... ]
}
```

The v1.0 specification defines `SendMessageResponse` as:

```
oneof response {
  Task task = 1;
  Message message = 2;
}
```

This means the result **must** contain either a `"task"` or `"message"`
wrapper key, not direct Task fields.

## Fix

Both response examples now correctly wrap the Task:

```json
"result": {
  "task": {
    "id": "task-boat-gen-123",
    "status": { ... },
    "artifacts": [ ... ]
  }
}
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Gijs Walraven <gijs.walraven@delaware.pro>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-02-18 16:13:47 +00:00
Gijs Walraven
8bf133addc
docs: use correct v1.0 method name "SendMessage" in life-of-a-task example (#1491)
## Summary

The follow-up scenario example in \`docs/topics/life-of-a-task.md\` used
\`"message.send"\` (dot notation) for the first request, while the
second request in the same example correctly used \`"SendMessage"\`
(v1.0 PascalCase). This made the file internally inconsistent and showed
a method name that doesn't exist in any version of the protocol.

## Change

\`\`\`diff
- "method": "message.send",
+ "method": "SendMessage",
\`\`\`

**File:** \`docs/topics/life-of-a-task.md\`

## Related

- Closes #1493
- Related to #1367 (method name inconsistencies across documentation)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Gijs Walraven <gijs.walraven@delaware.pro>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-18 10:12:17 -06:00
Gijs Walraven
7245512250
docs: correct Part discriminator values and remove stale v0.3.x type names (#1490)
## Summary

Fixes documentation inconsistencies related to Part discriminator field
values, identified in #1365.

## Changes

### `docs/specification.md` — Appendix A.2.1

- **Legacy Part `kind` values**: corrected from PascalCase (`"kind":
"TextPart"`, `"kind": "FilePart"`, `"kind": "DataPart"`) to lowercase
(`"kind": "text"`, `"kind": "file"`, `"kind": "data"`), consistent with
what `whats-new-v1.md` documents as the v0.3.0 format
- **Legacy FilePart structure**: added the missing nested `file` object
wrapper
- **Legacy streaming event `kind` values**: corrected from PascalCase
(`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`) to camelCase
(`taskStatusUpdate`, `taskArtifactUpdate`)
- **Current `DataPart` migration target**: removed incorrect
double-wrapping (`{ "data": { "data": {...} } }` → `{ "data": {...},
"mediaType": "application/json" }`)
- **Current streaming event member names**: aligned with
`whats-new-v1.md` (`taskStatusUpdate` / `taskArtifactUpdate`)

### `docs/topics/key-concepts.md`

- Updated Part description to use v1.0 terminology, removing references
to the removed `TextPart`, `FilePart`, and `DataPart` types

### `docs/tutorials/python/8-next-steps.md`

- Replaced reference to removed `DataPart` type with v1.0 Part field
names

### `CONTRIBUTING.md`

- Added **Documentation Guidelines** section with correct v1.0 Part
examples (member-presence pattern) and guidance on the correct v0.3.x
lowercase `kind` discriminator values for migration docs

## Related

- Closes #1365
- External community site fix:
https://github.com/sing1ee/a2a-directory/pull/12

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Gijs Walraven <gijs.walraven@delaware.pro>
2026-02-18 10:11:37 -06:00
Kuba Herczyński
1997c9d630
fix(spec): Remove reserved and fix tags ordering (#1494)
fixes #1495 1495
2026-02-17 14:37:58 -08:00
Holt Skinner
b2daedcadf
docs: Add What's New in V1 to Docs TOC (#1489)
<img width="966" height="661" alt="Screenshot 2026-02-17 at 11 46 47 AM"
src="https://github.com/user-attachments/assets/6730cd94-bbf6-4f0a-8e33-d3a0ae2833ae"
/>
2026-02-17 12:16:53 -06:00
Sam Betts
857a995a3d
docs(spec): Correct wording around blocking=true (#1398)
This corrects the wording so that blocking=True includes terminal and
interrupted states as triggers for returning to the client.

Fixes: #1264

---------

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-02-17 18:06:57 +00:00
Yaroslav
393898dfee
fix(spec)!: remove duplicated ID from the create task push config request (#1487)
ID is already present in the config object.
It is not used in path segment bindings and also uses inconsistent
naming with other push-related rpc payloads.

fixes https://github.com/a2aproject/A2A/issues/1451

Follow-up to #1389

---------

Co-authored-by: Kuba Herczyński <herczyn@google.com>
2026-02-17 09:59:50 -08:00
Yaroslav
cf735cb870
fix(spec)!: pluralize configs in ListTaskPushNotificationConfigs (#1486)
Pluralize PushNotificationConfig in ListTaskPushNotificationConfig
request and responses.

This is consistent with ListTasks.

Part of #1451

---------

Co-authored-by: Kuba Herczyński <herczyn@google.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-02-17 09:40:07 -08:00
Yaroslav
c441b910b6
fix(spec): add metadata to CancelTaskRequest (#1485)
In v0.3 almost all requests had metadata. Event push-related RPCs were
extending TaskIDParams inheriting the metadata field from them.

In v1.0 only SendMessage request has it. The absence of metadata is
especially problematic in CancelTaskRequest because in some sense it
reaches the agent. It makes it harder to develop an extension which
modifies agentic behavior if there's no way to influence request or
response of event produced in response to cancelation request.

fixes #1484

Co-authored-by: Kuba Herczyński <herczyn@google.com>
2026-02-17 09:35:16 -08:00
Kuba Herczyński
a54e80904a
fix(spec)!: Add LF prefix to the package. (#1474)
Fixes #1473

Release-As: 1.0.0

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-02-17 09:09:04 -08:00
Ivan Shymko
73d5f59a32
docs(spec): Fix whats-new-v1.md (#1460)
Changes below as they appear in the file.

- `blocking` flag existed in 0.3:
[source](https://a2a-protocol.org/v0.3.0/specification/#712-messagesendconfiguration-object)
- `SendMessage`: remove "MAY return Message"/"MUST return Task" which
are not in the spec, remove service parameters mention as they are
covered above
- streaming was specified for gRPC in proto definition as `returns
(stream StreamResponse)`
- `SubscribeToTask` is not a new operation
- blocking has no effect for streaming operations:
[source](https://a2a-protocol.org/latest/specification/#322-sendmessageconfiguration)
- `TaskNotCancelableError` was mentioned in 0.3:
[source](https://a2a-protocol.org/v0.3.0/specification/#82-a2a-specific-errors)
- RFC 7515 was mentioned for Agent Card signatures in 0.3:
[source](https://a2a-protocol.org/v0.3.0/specification/#556-agentcardsignature-object),
kept only RFC 8785 for canonicalization which wasn't
- `agentId` field does not exist and never did
- extension declarations (AgentExtension object) did not change between
[0.3](https://a2a-protocol.org/v0.3.0/specification/#5521-agentextension-object)
and
[1.0](https://a2a-protocol.org/latest/specification/#444-agentextension)
- Mutual TLS existed in 0.3:
[source](https://a2a-protocol.org/v0.3.0/specification/#553-securityscheme-object)
- subscribing to tasks not originally created via streaming is not a
behavior change and is not explicitly mentioned in 1.0
- `token` is not removed from `PushNotificationConfig`:
[source](https://a2a-protocol.org/latest/specification/#431-pushnotificationconfig)
- `configId` does not exist in `PushNotificationConfig`
([source](https://a2a-protocol.org/latest/specification/#431-pushnotificationconfig))
and `id` was there in 0.3
([source](https://a2a-protocol.org/v0.3.0/specification/#68-pushnotificationconfig-object))
- `PushNotificationNotSupportedError` existed in 0.3:
[source](https://a2a-protocol.org/v0.3.0/specification/#82-a2a-specific-errors)
- `SendMessageRequest` example fixed to match the spec
- `createdAt` and `lastModified` do not exist in `Task`:
[source](https://a2a-protocol.org/latest/specification/#411-task)
- changes to nested `Task` objects removed as they are covered in
respective sections (`TaskStatus`, `Message`, `Artifact`)
- `timestamp` was not added to `Message`:
[source](https://a2a-protocol.org/latest/specification/#414-message)
- there is no "stricter typing" for `metadata`
- "retained" should not be in the changelog
- `createdAt` was not added to `Artifact`:
[source](https://a2a-protocol.org/latest/specification/#417-artifact)
- `signatures` field was there in 0.3:
[source](https://a2a-protocol.org/v0.3.0/specification/#55-agentcard-object-structure)

Re #1436.

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-02-17 16:28:14 +00:00
Darrel
a9cffef493
ci(linter): Add API Linter job to workflow for proto file validation (#1257)
docs(spec): Adjust comments in `a2a.proto` to follow standard practices.

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-02-17 10:16:45 -06:00
Holt Skinner
fde2bd8da8
ci(docs): Update llms-full.txt script to include text versions of sdk docs and updated proto path (#1476) 2026-02-17 10:11:23 -06:00
Holt Skinner
cd16c5276b
fix(spec): Adjust field number for ListTasksRequest.tenant to prevent missing number (#1470)
Introduced in https://github.com/a2aproject/A2A/pull/1195

- Breaking change should be fine because `ListTasksRequest` is new for
1.0.0

Release-As: 1.0.0
2026-02-17 10:10:26 -06:00
Yaroslav
05603f973f
docs(spec): minor spec corrections (#1482)
* Removed outdated part format from examples
* Added a missing TaskNotFoundError to non-streaming rpc errors list
* Removed outdated final flag from status update examples

The referenced issues has some other things:
1. Should ListTaskPushNotificationConfig be pluralized into
ListTaskPushNotificationConfigs?
2. Should all request operating on push configs settle on either
configID or ID naming. Create vs (Delete|List|Get) RPCs differ at the
moment.
3. In CreateRequest we have ID based on the request root level and in
config payload. Should the former be removed?

https://github.com/a2aproject/A2A/issues/1451
2026-02-17 10:07:02 -06:00
Holt Skinner
f63f6551c5
docs: Fix link redirect issues (#1471)
Fixes #1467
2026-02-12 16:43:14 -06:00
Holt Skinner
68727dcb35
docs: Update A2A course link in README 2026-02-11 10:40:02 -06:00
Holt Skinner
7cf67271cf
docs: Add DeepLearning.AI Course to README and docs (#1469) 2026-02-11 10:39:23 -06:00
Holt Skinner
a3d78dcad3
docs(spec): Convert Proto Table display in specification to use existing libraries (#1427)
Convert bespoke `macros.py` to use `proto-schema-parser` and `tabulate`
to display tables

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-02-10 13:19:52 -06:00
Holt Skinner
c24b1151d1
docs(spec): Update inconsistencies in documentation for 1.0 Spec (#1466)
In the future, we should probably explore refactoring the docs set to
avoid these becoming out of sync going forward

This pull request updates the project documentation to align with the
v1.0 Agent2Agent (A2A) Protocol Specification defined in
specification/a2a.proto. It ensures that all conceptual guides,
summaries, and tutorials reflect the current normative definitions,
  RPC method names, and wire formats.

  Summary of Changes


1. RPC Method Naming Updates
Standardized all method references to use the v1.0 PascalCase naming
convention:

   * `message/send` → `SendMessage`
   * `message/stream` → `SendStreamingMessage`
   * `tasks/get` → `GetTask`
   * `tasks/list` → `ListTasks`
   * `tasks/cancel` → `CancelTask`
* `tasks/pushNotificationConfig/set` →
`CreateTaskPushNotificationConfig`
   * `tasks/resubscribe` → `SubscribeToTask`
   * `agent/getAuthenticatedExtendedCard` → `GetExtendedAgentCard`

2. JSON Example & Wire Format Corrections
Updated examples across all "Topic" files and the Python Quickstart to
match v1.0 breaking changes:
* Removed `kind` discriminators: Examples for Message, Task, Part, and
StreamResponse now use member-based polymorphism (e.g.,
     {"text": "..."} instead of {"kind": "text", "text": "..."}).
* Enum Standardization: Changed role and state enums from
kebab-case/lowercase to SCREAMING_SNAKE_CASE with type prefixes (e.g.,
     `"ROLE_USER"`, `"TASK_STATE_COMPLETED"`).
* Response Wrapping: Updated examples to reflect that `SendMessage` and
`SendStreamingMessage` return a unified response object where
     the message or task is nested within the result.

  3. LLM Context (`docs/llms.txt`)
* Completely refreshed the protocol summary and RPC method list to
ensure LLM-based tools (like Gemini CLI) have an accurate
     representation of the v1.0 API surface and error codes.

  4. Link & Anchor Maintenance
* Updated internal documentation links and spans to point to the correct
sections in the specification.md (e.g., correcting the
     anchor for GetExtendedAgentCard).

  Why this is needed
The v1.0 release introduced significant structural improvements for
ProtoJSON compliance and architectural consistency. Documentation
examples were previously showing v0.3.0 patterns which would cause
integration errors for developers using the latest SDKs.
2026-02-10 11:45:49 -06:00
Ivan Shymko
3f6ad2d9d6
docs(spec): Fix MTLS scheme proto embedding (#1462)
Currently properties for `MutualTlsSecurityScheme` are not renderred
([source](https://a2a-protocol.org/latest/specification/#456-mutualtlssecurityscheme)):
<img width="1273" height="374" alt="image"
src="https://github.com/user-attachments/assets/be4c7dbb-749d-4391-aec8-fdd55c0dd625"
/>

This PR makes casing consistent for both mkdocs anchors and heading.

Tested via `mkdocs serve`:
<img width="1505" height="626" alt="image"
src="https://github.com/user-attachments/assets/348a6ef9-3868-43bf-8319-efe63092b95b"
/>

Re https://github.com/a2aproject/A2A/pull/1460#discussion_r2783691658
2026-02-10 18:17:45 +01:00
Ivan Shymko
741ccaa3af
docs(spec): Fix streaming examples (#1458)
1. Reference `StreamResponse` instead of duplicated and inconsistent
definitions in JSON-RPC and HTTP+JSON/REST message streaming protocol
bindings. Currently JSON-RPC example also contains outdated `/* Task |
Message | TaskArtifactUpdateEvent | TaskStatusUpdateEvent */` definition
which implies `kind` field.
2. Minor consistency fix:
```diff
-Referenced Objects:
+**Referenced Objects:**
```

Fixes #1459.
2026-02-09 16:21:26 +01:00
Shingo OKAWA
8c17173de3
ci: add local script to run super-linter (#1289)
## Summary

This PR adds a local helper script (`scripts/lint.sh`) to run GitHub
Super Linter in a Docker container.
It mirrors the configuration used in our CI workflow, allowing
contributors to validate linting rules locally before opening a Pull
Request.

## Details

 - Added `scripts/lint.sh` for running Super Linter locally
- Uses the same environment variables and config files as
`.github/workflows/linter.yaml`

## Motivation

The CI lint job sometimes fails due to rule violations that are hard to
reproduce locally.
This script ensures consistent developer experience by enabling
contributors to run the exact same linter setup.

## Notes

 - No functional changes to source code
 - CI behavior remains unchanged
 
 Closes #1290

Signed-off-by: Shingo OKAWA <shingo.okawa.g.h.c@gmail.com>
2026-02-06 12:56:45 -06:00
Darrel
ed97dea512
docs(spec): What changed from v0.3.0 to v1.0 (#1436)
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-02-05 12:23:18 -05:00
Kuba Herczyński
ce73987171
docs(spec): Fix wording around A2A-version header. (#1435)
fixes #1417

---------

Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-02-05 09:05:49 -08:00
Holt Skinner
47eda410c3
docs: Update A2A Intro Video thumbnail resolution 2026-02-04 19:02:04 -06:00
Amye Scavarda Perrin
d22ee06d36
doc: Update GOVERNANCE.md (#1447)
Adding link to LFX meetings
2026-02-03 14:07:54 -08:00
Darrel
6292104e35
fix(spec): Added clarification on timestamps in HTTP query params (#1425) 2026-01-29 15:09:21 -05:00
Luca Muscariello
b86d8bb2ed
docs: clean up documentation build chain and fix broken links (#1400)
- Move a2a.proto to specification/ root
- Update build scripts and macros to support new proto location
- Fix broken internal links and anchor references in specification.md
- Update .gitignore to properly exclude generated SDK docs
- Configure Sphinx to suppress external SDK warnings
- Fix MkDocs redirects and Python SDK toctree structure

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>
2026-01-29 21:00:02 +01:00
Darrel
b03d141aea
fix(spec): Added clarifying text around messages and artifacts (#1424)
This pull request updates the A2A protocol specification to clarify the
distinction between Messages and Artifacts, and makes a minor adjustment
to protocol negotiation requirements.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-29 14:44:25 -05:00
Sam Betts
2596c1c5e0
fix(spec)!: Switch to non-complex IDs in requests (#1389)
Some operations like GetTask / SubscribeToTask still used complex /
compound identifiers like `tasks/<uuid>` which requires the
clients/servers to deconstruct/construct these IDs as they are normally
using just the UUID to store the resource in the DB etc.

This commit refactors them so they are just the IDs, in some cases this
meant that we needed to split one field into two i.e. parent + name.

Fixes: #1390

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-29 14:26:14 -05:00
Kuba Herczyński
227e2493c3
feat(spec): Provide ability for SDKs to be backwards compatible. (#1401)
fixes #1417
for context see #1416

---------

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-29 14:22:35 -05:00
Didier Durand
f6129cafa1
docs: fix some typos in various files. (#1198)
Hi,
As per title, fixing typos in various files: see commit diffs for
details
Cheers
Didier

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-01-29 11:03:42 -06:00
Open AI Tx
59ea3f614c
docs: Auto-translate README and Wiki (#1326)
Added language badges to the README for easier access to translated
versions: German, Spanish, French, Japanese, Korean, Portuguese, and
Russian 20 languages.
System will auto-update translation for README and Wiki when this
repository updated, and support multiple languages google/bing SEO
search, and it's open source project, we can change web or local file
mode.

The updated links can be previewed in my forked repository:
https://github.com/openaitx-system/A2A/tree/Auto_translate_README_and_Wiki

Demo links : 
-
[Español](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=es)
-
[简体中文](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-CN)
-
[日本語](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ja)
-
[한국어](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ko)
-
[Français](https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fr)
..


<img width="1178" height="537" alt="Image"
src="https://github.com/user-attachments/assets/7cd54a88-59c1-455f-9c7d-2db7f05b2962
" />

If this doesn't align with your expectations, feel free to close this
PR. Thanks for your time! 🙌

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-01-29 11:00:33 -06:00
Holt Skinner
f6e786c652
chore: Modify CODEOWNERS for updated directory paths
Updated CODEOWNERS to reflect new directory structure.
2026-01-29 11:00:10 -06:00
Holt Skinner
871924e804
chore: Update CODEOWNERS
Add Tech Writing and Google A2A Eng as owners for non-spec files
2026-01-29 10:57:43 -06:00
madankumarpichamuthu
4dd980f6ff
fix(spec)!: Standardize spelling of "canceled" to use American Spelling throughout (#1283)
Fixes inconsistent spelling of cancel-related terms across the
specification and documentation. The proto definition uses
TASK_STATE_CANCELLED (double 'l'), but various documentation files were
using single 'l' spelling.

Changes:
- cancelled → canceled
- cancellable → cancelable
- `TaskNotCancellableError` → `TaskNotCancelableError`

Files modified:
- docs/specification.md
- docs/llms.txt
- docs/topics/life-of-a-task.md

All documentation now consistently uses single 'l' to match the proto
definition and JSON naming conventions.

Fixes #1270

Release-As: 1.0.0

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2026-01-29 09:51:18 -06:00
madankumarpichamuthu
0655ff324a
fix: Clarify blocking calls return on interrupted states (#1403)
Updates the specification to clarify that blocking SendMessage calls
must return when tasks reach interrupted states (input_required,
auth_required) in addition to terminal states. This prevents deadlock
scenarios where tasks waiting for user input would cause blocking calls
to hang indefinitely.

Changes:
- specification/grpc/a2a.proto: Updated blocking field comment to
include "terminal or interrupted state"
- specification/grpc/a2a.proto: Fixed AUTH_REQUIRED classification to be
an "interrupted state" (consistent with INPUT_REQUIRED)
- docs/specification.md: Updated blocking behavior description to
include interrupted states and changed "final task state" to "current
task state"

This enables proper client workflows where blocking calls can return on
INPUT_REQUIRED or AUTH_REQUIRED, allowing clients to provide the needed
information and resume with subsequent SendMessage calls.

Fixes #1264

---------

Co-authored-by: madankumarpichamuthu <madankumarpichamuthu@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-29 11:52:29 +01:00
Darrel
bfae8f7791
fix: Simplify Part message structure by flattening FilePart and DataPart (#1411)
This change simplifies the Part message design by:
- Renaming oneof 'part' to 'content' for clarity
- Flattening FilePart fields (file_with_uri -> url, file_with_bytes ->
bytes) directly into Part
- Flattening DataPart by using google.protobuf.Value instead of Struct
- Moving media_type and filename to Part level (available for all
content types)
- Removing separate FilePart and DataPart messages

Also updated migration guidance documentation to reference ancillary
documents instead of requiring an in-spec appendix.

Related to issue #1255

Replaces PR #1363

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-28 17:48:33 +01:00
madankumarpichamuthu
810eaa1c6e
docs(spec)!: Align enum format with ADR-001 ProtoJSON specification (#1384)
Updates specification to use ProtoJSON enum format
(SCREAMING_SNAKE_CASE) instead of kebab-case, aligning with ADR-001
decision.

Changes:
- Updated Section 5.5 enum value formatting rules
- Added reference to ADR-001 and ProtoJSON specification
- Updated all JSON examples to use SCREAMING_SNAKE_CASE enums:
  - Role enums: user -> ROLE_USER, agent -> ROLE_AGENT
- Task state enums: working -> TASK_STATE_WORKING, completed ->
TASK_STATE_COMPLETED, etc.

This aligns the specification with the TSC-approved ADR-001 decision to
leverage ProtoJSON for JSON serialization.

Fixes #1344

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
2026-01-27 09:53:46 -08:00
Darrel
3e6c7db907
fix(spec): Fix/1251 clarify authentication scheme (#1256)
Fixes #1251

---------

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-27 09:39:39 -08:00
madankumarpichamuthu
5b101cce0f
refactor(spec)!: Remove redundant final field from TaskStatusUpdateEvent (#1308)
Terminal states (COMPLETED, FAILED, CANCELLED, REJECTED) already
indicate task completion, making the final field redundant. This creates
consistency across streaming, polling, and push notification
communication patterns.

Changes:
- Removed final field (field 4) from TaskStatusUpdateEvent in proto
- Updated examples to remove final: true references
- Clarified that streams close upon terminal states
- Added migration guidance in Appendix A.2.2

Fixes #1232

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-27 09:07:50 -08:00
Vinay Ramesh
19e2059852
docs: provide clarity in task id specification to address #1406 (#1407)
# Description
Provides clarity on server generated task ids in the specification
documentation to address underspecification of Message payloads and
expected error handling.

Fixes: #1406

Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-27 09:06:05 -08:00
hugo-romero-mm
229d005bff
docs(partners): Add MasOrange to partners list (#1409)
Hi A2A Team,
I’d like to submit [MasOrange](https://masorange.es/en/) to be added to
the A2A partners list: https://a2a-protocol.org/latest/partners/

A2A integration: We are working with A2A as a core building block for
agent discovery and agent-to-agent interoperability across our
ecosystem. We also maintain ongoing discussions with Google on
A2A-related topics, including Gemini Enterprise integrations and agentic
cloud capabilities, providing them direct feedback. We are implementing
A2A as the default protocol for exposing and connecting agentic systems
within MasOrange, adapting its usage to our security and governance
requirements, with future potential benefits for the OSS community.


Best regards,
Hugo Romero, AI Engineer at MasOrange

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-01-26 09:41:30 -08:00
Ivan Shymko
bb527d4299
docs: Bring back Python SDK reference (#1415)
Currently [`SDK Reference >
Python`](https://a2a-protocol.org/latest/sdk/python.md) link gives 404:

<img width="1138" height="308" alt="image"
src="https://github.com/user-attachments/assets/2bd3bda0-0536-4450-8e82-5ec9ee5ce044"
/>

1. Fix the link to open
[this](https://a2a-protocol.org/latest/sdk/python/api/index.html)
instead. This was setup in #949 and is generated automatically from the
latest docs. Looks like it was accidentally changed to `python.md` (the
one not used ever before, it used to be `python/index.md`) in #1160.
2. Fix redirect to use absolute URL with `latest`. This is required due
to https://github.com/mkdocs/mkdocs-redirects/issues/18, current way
isn't going to work. `v0.3.0` tag of the website (the one you get after
clicking `Latest Released Version` from
[here](https://a2a-protocol.org/latest/specification/)) doesn't have the
generated documentation either way, see
[here](https://github.com/a2aproject/A2A/tree/gh-pages/v0.3.0/sdk/python).
3. Replace `Google LLC` with `The Linux Foundation` in the generated SDK
reference.
4. Update copyright year in both places.

Tested via `mkdocs serve`.

Fixes #1347.
2026-01-26 10:12:40 -06:00
madankumarpichamuthu
d14f410711
fix: Restore CreateTaskPushNotificationConfig method naming (#1402)
Bypassing tech-writing review as it is a simple rename and the majority of the changes are in the specification.  Changes to conceptual docs are just for aligning names.

Restores the intentional rename from "Set" to "Create" for push
notification configuration methods that was lost during refactoring.
When the protocol was updated to support multiple Push Notification
Configurations, the method was changed from "Set" (which implies
replacing a single config) to "Create" (which implies creating a new
instance among many).

Changes across all documentation and proto files:
- specification/grpc/a2a.proto: Renamed RPC method and request message
- docs/specification.md: Updated all references, section titles, and
method tables
- docs/topics/streaming-and-async.md: Updated links and text
- docs/llms.txt: Updated method reference

Fixes #1394

---------

Co-authored-by: madankumarpichamuthu <madankumarpichamuthu@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-25 11:42:23 -05:00
madankumarpichamuthu
c768a44da0
fix: Remove unimplemented state_transition_history capability field (#1396)
Removes the `state_transition_history` field from `AgentCapabilities`
message as it has no corresponding API implementation. This capability
flag could mislead clients into expecting functionality that doesn't
exist in v1.0.

The field can be reintroduced in a future version when a proper
implementation is designed, including:
- Adding status_history field to Task message
- Adding include_status_history parameters to Get/List operations
- Defining behavior for history storage and retrieval

Fixes #1228

Co-authored-by: madankumarpichamuthu <madankumarpichamuthu@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-25 11:25:26 -05:00
madankumarpichamuthu
92e6fb712e
docs(spec): Update outdated method references in proto file comments (#1282)
Fixes inconsistencies between proto file documentation and the actual
method names defined in section 5.3 of the specification.

Updated method references in proto comments:
- message/send → SendMessage
- tasks/get → GetTask
- tasks/cancel → CancelTask
- tasks/pushNotificationConfig/delete → DeleteTaskPushNotificationConfig
- tasks/pushNotificationConfig/set → SetTaskPushNotificationConfig
- tasks/pushNotificationConfig/list → ListTaskPushNotificationConfig

These changes align the proto documentation with the Method Mapping
Reference table in section 5.3 of specification.md, which defines the
canonical method names for JSON-RPC and gRPC bindings.

Fixes #1267

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-22 11:54:32 +01:00
Yaroslav
057295311b
fix(spec): make history_length optional (#1071)
### Description

Both fields are optional in
[types.ts](https://github.com/yarolegovich/A2A/blob/main/types/src/types.ts#L637)
and [jsonrpc
schema](https://github.com/a2aproject/A2A/blob/main/specification/json/a2a.json#L1683).
For both cases it might be useful to differentiate 0 and unset. For
example:
1. A client calls GetTask and doesn't want History to be fetched /
included in the response.
2. A client calls SendMessage and doesn't want history to be persisted
at all.

The change is backward-compatible and makes it possible for a2a servers
to provide consistent behavior regardless of the selected transport.

Fixes #1072

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-21 17:30:25 +01:00
madankumarpichamuthu
4befaeacaf
docs: Remove v1 from HTTP binding URLs in specification (#1383)
Updates specification documentation to align with proto file changes by
removing /v1/ prefix from all HTTP REST endpoint URLs.

Changes:
- Updated all HTTP endpoint examples (POST, GET, DELETE)
- Updated API operation reference table
- Removed /v1/ from 41 occurrences throughout the specification

Fixes #1350
2026-01-20 09:19:25 -08:00
Jeff Mesnil
f9a8f5b85d
fix(spec): Update security schemes example (#1364)
Update security scheme example to use the correct key for the security
schemes instead of the `type` field.

This fixes #1355

Signed-off-by: Jeff Mesnil <jmesnil@redhat.com>
2026-01-15 11:32:26 -05:00
Amye Scavarda Perrin
ca615d78e5
Update GOVERNANCE.md (#1371)
spetschulatSFDC is now the Salesforce rep!
2026-01-14 13:37:15 -08:00
madankumarpichamuthu
40d6286fbe
refactor(spec)!: Move extendedAgentCard field to AgentCapabilities (#1307)
Relocates `supports_extended_agent_card` from AgentCard to
AgentCapabilities for architectural consistency. All optional features
that enable specific operations now reside in the capabilities object.

Rationale:
- Consistent placement: streaming, push_notifications, and
state_transition_history are all in AgentCapabilities
- Improved discoverability: developers naturally check capabilities for
optional features
- Semantic correctness: extended agent card support is a capability

Changes:
- Proto: Removed field 13 from AgentCard, added field 5 to
AgentCapabilities
- Field renamed: supports_extended_agent_card → extended_agent_card
- Updated all references: AgentCard.supportsExtendedAgentCard →
AgentCard.capabilities.extendedAgentCard
- Updated JSON examples to reflect new structure
- Added migration guidance in Appendix A.2.2 of specification

Breaking change: Clients and agents must update capability checking
logic. See specification Appendix A.2.2 for migration steps.

Fixes #1229

---------

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-14 08:41:30 -05:00
Sam Betts
0e204bf878
fix(spec)!: Fixes for the last_updated_after field (#1358)
This PR combines two fixes for the ListTaskRequest last_updated_after
field one changes the field to a timestamp type and one renames it and
clarifies the ordering of the task list result.

Original PR for the timestamp type fix was:
https://github.com/a2aproject/A2A/pull/1288

Fixes: #1287
Fixes: #1206

---------

Co-authored-by: Yaroslav Shevchuk <yarolegovich@gmail.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-14 08:34:02 -05:00
Mauro Sardara
525ff38e5f
feat(spec)!: modernize oauth 2.0 flows - remove implicit/password, add device code / pkce (#1303)
## Description

Modernizes OAuth 2.0 flow support by removing deprecated
flows and adding modern, secure alternatives.

Fixes: #1234 

## Changes

### Breaking Changes

**Removed (deprecated by OAuth 2.0 Security BCP):**
- `ImplicitOAuthFlow` - Use Authorization Code + PKCE instead
- `PasswordOAuthFlow` - Use Authorization Code + PKCE or Device Code
instead

### Added

**New OAuth Flow:**
- `DeviceCodeOAuthFlow` (RFC 8628) - For CLI tools, IoT devices, and
input-constrained scenarios

**Enhanced Security:**
- `pkce_required` field added to `AuthorizationCodeOAuthFlow` (RFC 7636)

Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-13 22:24:49 -05:00
Darrel
e6c5699c55
docs: Added adr template and protojson adr (#1214)
Added ADR that captures decision to use ProtoJSON as the normative
reference for JSON serialization

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2026-01-13 22:16:06 -05:00
Darrel
a4afeea788
fix(spec): Clarify versioning strategy and client responsibilities in protocol specification (#1259)
Fixes #1258

### High level summary of changes:

- protocolVersion in AgentCard is now an array called protocolVersions
- Servers are expected to return UnsupportedVersionError if they get a
request with an A2A-Version header higher than they support.
- Clients are expected to fallback to a supported version if that is
acceptable to them. Tooling should help here.
- Not every minor version needs to be enumerated in the protocolVersions
array. 2.2 infers support for 2.1 and 2.0.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2026-01-13 22:10:38 -05:00
Sam Betts
1e5f462064
fix(spec)!: Make "message" field name consistent between protocol bindings (#1302)
While this is a reserved word for proto itself, best practise is to
avoid field names that conflict with language (python etc) keywords, as
"message" isn't a language keyword this improves the consistency and
readability when using the types generated from the proto and avoids
needing to translate the name for JSON encoding.

Closes: #1230

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-13 22:00:11 -05:00
76 changed files with 8465 additions and 1971 deletions

12
.github/CODEOWNERS vendored
View File

@ -5,10 +5,14 @@
# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax
* @a2aproject/a2a-tsc
docs/ @a2aproject/tech-writing
docs/ @a2aproject/a2a-tsc
scripts/ @a2aproject/a2a-tsc
specification/ @a2aproject/a2a-tsc
types/ @a2aproject/a2a-tsc
docs/specification.md @a2aproject/a2a-tsc
GOVERNANCE.md @a2aproject/a2a-tsc
.mkdocs.yml @a2aproject/tech-writing
.mkdocs/ @a2aproject/a2a-tsc
.mkdocs.yml @a2aproject/a2a-tsc
README.md @a2aproject/a2a-tsc
.gemini/ @a2aproject/a2a-tsc
.mkdocs/ @a2aproject/a2a-tsc
.github/ @a2aproject/a2a-tsc

View File

@ -6,6 +6,7 @@ ACard
AClient
ACo
ADK
ADR
AError
AExecutor
AGP
@ -18,9 +19,12 @@ AService
ASq
AStarlette
AUTOCOMMIT
Abhimanyu
Agentspace
Agno
Autogen
Bahasa
Besen
Blogs
CAs
CLIs
@ -30,12 +34,14 @@ Cpzuhi
DDo
DGT
DHDe
Datetimes
Debian
Djq
Dotnet
EBFF
EUR
EUg
Espa
FBT
FHIR
Fbr
@ -71,10 +77,12 @@ Jhb
Jra
KGgo
KRW
LFX
LHR
LJcvt
LLM
LLMs
Lindfors
Lix
MSIs
MWpm
@ -83,18 +91,25 @@ Mvosg
Nszl
OIDC
OOa
OTP
Ollama
PLE
PLW
PMEEi
PTH
Petschulat
Polski
Portugu
QFdk
Qvandrcy
RFCs
RPCs
RUF
SFDC
SLAs
SLF
SSLv
Siwach
Solax
TJS
TMDB
@ -103,6 +118,7 @@ URLTo
Upserting
Urke
VBORw
VHc
Vsb
WHB
WQi
@ -127,7 +143,10 @@ aacacac
aboutasha
achat
aconnect
actioncard
adk
adr
adrs
afet
affef
agentcard
@ -165,12 +184,14 @@ ccc
cdn
ceee
cfe
chrusty
cls
coc
codegen
codeowner
codespace
codewiki
cpb
crewai
datamodel
datapart
@ -180,6 +201,7 @@ dcfa
dde
deepwiki
direnv
dlai
docstrings
documentai
dotnet
@ -214,6 +236,7 @@ genproto
georoute
gettask
gettickets
gitleaks
gitvote
gle
googleai
@ -225,10 +248,13 @@ gstatic
gweb
hackathon
hackathons
hexpm
hqdefault
hughesthe
iana
iat
ietf
inardini
inbox
inmemory
ipynb
@ -239,10 +265,12 @@ jqlang
jti
jwks
kadirpekel
keystores
konami
kty
langgraph
lerhaupt
lfx
linenums
linkedin
linting
@ -275,6 +303,7 @@ octicons
oidc
ollama
oneof
openaitx
openapis
openapiv
openapiv2
@ -284,6 +313,7 @@ postgresql
pqr
prefecthq
protoc
protojson
protolint
pyguide
pylance
@ -300,7 +330,9 @@ reportgen
reposted
rst
rvelicheti
sandijean
scm
siwachabhi
sllm
sourced
sourcing
@ -313,6 +345,7 @@ stephenh
styleguide
svn
systemctl
tablefmt
tagwords
tasksget
taskslist
@ -321,8 +354,11 @@ taskstate
taskstatus
textpart
threadsafe
tiangolo
toctree
tok
tolgaki
tomtom
toolkits
tracestate
ugc
@ -333,6 +369,7 @@ versioned
vnd
voa
vscode
vvvvvvvv
weavehacks
webform
webpage

6
.github/actions/spelling/expect.txt vendored Normal file
View File

@ -0,0 +1,6 @@
Abhimanyu
lfx
Petschulat
SFDC
Siwach
siwachabhi

View File

@ -5,7 +5,8 @@
"**/images/**",
"**/samples/**",
"**/tests/**",
"**/.git/**"
"**/.git/**",
"**/a2a_logo/**"
],
"threshold": 3,
"reporters": ["html", "markdown"]

22
.github/super-linter.env vendored Normal file
View File

@ -0,0 +1,22 @@
SHELLCHECK_OPTS=-e SC1091 -e SC2086
VALIDATE_ALL_CODEBASE=false
FILTER_REGEX_EXCLUDE=^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|MAINTAINERS.md
VALIDATE_BASH=true
VALIDATE_BASH_EXEC=true
VALIDATE_CSS=true
VALIDATE_EDITORCONFIG=true
VALIDATE_GIT_MERGE_CONFLICT_MARKERS=true
VALIDATE_GITHUB_ACTIONS=true
VALIDATE_GITLEAKS=true
VALIDATE_JSCPD=true
VALIDATE_JSON=true
VALIDATE_MARKDOWN=true
VALIDATE_PROTOBUF=true
VALIDATE_PYTHON_RUFF=true
VALIDATE_SHELL_SHFMT=true
VALIDATE_TOML=true
VALIDATE_TYPESCRIPT_ES=true
VALIDATE_YAML=true
TYPESCRIPT_ES_CONFIG_FILE=.eslintrc.js
MARKDOWN_CONFIG_FILE=.markdownlint.json
PROTOBUF_CONFIG_FILE=.protolint.yaml

View File

@ -23,6 +23,11 @@ on:
types:
- published
workflow_dispatch:
inputs:
version:
description: 'Version to deploy to (e.g., v1.0.0)'
required: true
default: 'dev'
jobs:
build_and_deploy:
@ -50,6 +55,9 @@ jobs:
with:
python-version: 3.13
- name: Setup uv
uses: astral-sh/setup-uv@v7
- name: Restore pip cache
uses: actions/cache@v5
with:
@ -64,7 +72,7 @@ jobs:
- name: Setup Go
uses: actions/setup-go@v6
with:
go-version: '1.24'
go-version: '1.25'
- name: Install build tools
run: |
@ -92,18 +100,6 @@ jobs:
- name: Generate protocol specification files
run: ./scripts/build_docs.sh
- name: Generate and Build Python SDK Docs
run: |
# Find the path to the installed package
PACKAGE_PATH=$(python -c "import a2a, os; print(os.path.dirname(a2a.__file__))")
echo "Found 'a2a' package at: ${PACKAGE_PATH}"
# Generate RST source files from the installed package
sphinx-apidoc -f -o docs/sdk/python "${PACKAGE_PATH}"
# Build the HTML from the generated RST files
sphinx-build -b html docs/sdk/python docs/sdk/python/api
- name: Generate consolidated llms-full.txt file
run: bash scripts/build_llms_full.sh
@ -137,3 +133,14 @@ jobs:
bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}
env:
GITHUB_EVENT_RELEASE_TAG_NAME: ${{ github.event.release.tag_name }}
- name: Manually deploy specific version from main
if: github.event_name == 'workflow_dispatch'
run: |
mike deploy --push --update-aliases ${{ github.event.inputs.version }} latest
echo "Setting 'latest' as the default version for the site..."
mike set-default --push latest
# Re-deploy 404 page
bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}

View File

@ -29,7 +29,7 @@ jobs:
echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
- name: Run issue-metrics tool
uses: github/issue-metrics@v3
uses: github-community-projects/issue-metrics@v4
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SEARCH_QUERY: 'repo:a2aproject/A2A is:issue created:${{ env.last_month }} -reason:"not planned"'

View File

@ -19,29 +19,45 @@ jobs:
with:
fetch-depth: 0
- name: Load Super Linter Environment Variables into GITHUB_ENV
run: |
grep -v '^\\(#.*\\|\\s\\?\\)$' .github/super-linter.env >> "${GITHUB_ENV}"
- name: GitHub Super Linter
uses: super-linter/super-linter/slim@v8
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SHELLCHECK_OPTS: -e SC1091 -e 2086
VALIDATE_ALL_CODEBASE: false
FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|MAINTAINERS.md"
VALIDATE_BASH: true
VALIDATE_BASH_EXEC: true
VALIDATE_CSS: true
VALIDATE_EDITORCONFIG: true
VALIDATE_GIT_MERGE_CONFLICT_MARKERS: true
VALIDATE_GITHUB_ACTIONS: true
VALIDATE_GITLEAKS: true
VALIDATE_JSCPD: true
VALIDATE_JSON: true
VALIDATE_MARKDOWN: true
VALIDATE_PROTOBUF: true
VALIDATE_PYTHON_RUFF: true
VALIDATE_SHELL_SHFMT: true
VALIDATE_TOML: true
VALIDATE_TYPESCRIPT_ES: true
VALIDATE_YAML: true
TYPESCRIPT_ES_CONFIG_FILE: ".eslintrc.js"
MARKDOWN_CONFIG_FILE: ".markdownlint.json"
PROTOBUF_CONFIG_FILE: ".protolint.yaml"
api-linter:
name: API Linter
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout Code
uses: actions/checkout@v6
- name: Install buf
run: |
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64" -o buf
sudo mv buf /usr/local/bin/buf
sudo chmod +x /usr/local/bin/buf
- name: Download proto dependencies
working-directory: specification
run: |
buf dep update
buf export buf.build/googleapis/googleapis --output=.googleapis
- name: Install api-linter
run: |
curl -L https://github.com/googleapis/api-linter/releases/download/v1.67.6/api-linter-1.67.6-linux-amd64.tar.gz -o api-linter.tar.gz
tar -xzf api-linter.tar.gz
sudo mv api-linter /usr/local/bin/
sudo chmod +x /usr/local/bin/api-linter
- name: Run API Linter
run: |
# Run api-linter with exported googleapis protos
api-linter --config specification/.api-linter.yaml --output-format github --set-exit-status --proto-path specification --proto-path specification/.googleapis specification/a2a.proto

View File

@ -27,7 +27,7 @@ jobs:
steps:
- name: check-spelling
id: spelling
uses: check-spelling/check-spelling@main
uses: check-spelling/check-spelling@v0.0.26
with:
suppress_push_for_open_pull_request: ${{ github.actor != 'dependabot[bot]' && 1 }}
checkout: true

11
.gitignore vendored
View File

@ -11,6 +11,15 @@ specification/json/*.json
!specification/json/README.md
docs/spec/
# Generated SDK docs
docs/sdk/*
!docs/sdk/index.md
!docs/sdk/python.md
!docs/sdk/python/
docs/sdk/python/*
!docs/sdk/python/conf.py
!docs/sdk/python/index.rst
# Third-party dependencies (generated by setup)
third_party/
@ -201,3 +210,5 @@ Thumbs.db
docs/sdk/python/_build/
docs/sdk/python/api/
docs/sdk/python/generated/
specification/.googleapis/

View File

@ -1,514 +1,325 @@
"""
Custom MkDocs macros for A2A documentation.
"""Custom MkDocs macros for A2A documentation.
This module provides macros for rendering Protocol Buffer definitions
as markdown tables.
"""
import re
from pathlib import Path
from typing import Dict, List, Optional, Tuple
from typing import Any
from proto_schema_parser.ast import (
Comment,
Enum,
EnumValue,
Field,
MapField,
Message,
Method,
OneOf,
Service,
)
from proto_schema_parser.parser import Parser
from tabulate import tabulate
def _is_primitive_type(proto_type: str) -> bool:
"""Check if a proto type is a primitive type that shouldn't be linked."""
primitive_types = {
'string', 'int32', 'int64', 'bool', 'bytes',
'google.protobuf.Struct', 'google.protobuf.Timestamp'
}
return proto_type in primitive_types
# -----------------------------------------------------------------------------
# Configuration & Helpers
# -----------------------------------------------------------------------------
TYPE_MAP = {
'string': 'string',
'int32': 'integer',
'int64': 'integer',
'bool': 'boolean',
'bytes': 'bytes',
'double': 'float',
'float': 'float',
'google.protobuf.Struct': 'object',
'google.protobuf.Timestamp': 'timestamp',
'google.protobuf.Value': 'any',
'google.protobuf.Empty': 'empty',
}
# -----------------------------------------------------------------------------
# Main Macros
# -----------------------------------------------------------------------------
def define_env(env):
"""
Define custom macros for MkDocs.
"""Define custom macros for MkDocs."""
This function is called by the mkdocs-macros plugin.
"""
def _parse_proto(file_path: str):
"""Parses a .proto file and returns the AST with comments attached."""
full_path = Path(env.conf['docs_dir']).parent / file_path
if not full_path.exists():
raise FileNotFoundError(f'Proto not found: {file_path}')
ast = Parser().parse(full_path.read_text(encoding='utf-8'))
_attach_comments(ast.file_elements)
return ast.file_elements
@env.macro
def proto_to_table(proto_file: str, message_name: str) -> str:
"""
Parse a Protocol Buffer message definition and render it with description and table.
def proto_to_table(
message_name: str, proto_file: str = 'specification/a2a.proto'
) -> str:
"""Parses a .proto file and renders a message table."""
try:
elements = _parse_proto(proto_file)
except FileNotFoundError as e:
return f'**Error:** {e}'
Args:
proto_file: Relative path to the .proto file (e.g., "specification/grpc/a2a.proto")
message_name: Name of the message to extract (e.g., "Message")
# Find the specific message object
target_message = _find_type(elements, message_name, Message)
if not target_message:
return f'**Error:** Message `{message_name}` not found.'
Returns:
Markdown representation with description before table and notes after
"""
# Resolve the proto file path relative to the project root
project_root = Path(env.conf['docs_dir']).parent
proto_path = project_root / proto_file
# Extract data
rows = []
oneof_groups = {} # Map[oneof_name] -> List[field_names]
if not proto_path.exists():
return f"**Error:** Proto file not found: {proto_file}"
# Iterate over elements inside the message
# elements can be Field, MapField, OneOf, Enum, Message, etc.
for el in target_message.elements:
# Handle Standard/Map Fields
if isinstance(el, Field | MapField):
rows.append(_process_field(el))
elif isinstance(el, OneOf):
for oneof_el in el.elements:
if isinstance(oneof_el, Field):
# Process field normally
row = _process_field(oneof_el, is_oneof=True)
rows.append(row)
# Add display name to group tracker
oneof_groups.setdefault(el.name, []).append(
row[0].strip('`') # Remove code ticks for the note
)
# Read the proto file content
content = proto_path.read_text(encoding='utf-8')
if not rows:
return 'None'
# Extract the message definition between the region markers
pattern = rf'// --8<-- \[start:{re.escape(message_name)}\](.*?)// --8<-- \[end:{re.escape(message_name)}\]'
match = re.search(pattern, content, re.DOTALL)
if not match:
return f"**Error:** Message '{message_name}' not found in {proto_file}"
message_content = match.group(1)
# Extract description (before message), fields, and notes (after message)
description, fields, notes, oneof_groups = _parse_proto_message_full(message_content)
# Handle the case of empty proto message
if not fields:
return "None"
# Build the output
# Generate Output
output = []
if description:
output.append(description)
output.append('') # Empty line
# Message Description
msg_desc = _extract_comments(target_message)
if msg_desc:
output.append(msg_desc)
output.append('')
output.append(_generate_markdown_table(fields))
# Render Table
headers = ['Field', 'Type', 'Required', 'Description']
output.append(tabulate(rows, headers, tablefmt='github'))
# Add oneof notes after the table
# Add OneOf Notes
if oneof_groups:
output.append('') # Empty line
for oneof_name, oneof_fields in oneof_groups.items():
if len(oneof_fields) > 1:
field_list = ', '.join(f'`{field}`' for field in oneof_fields)
output.append(f'**Note:** A {message_name} MUST contain exactly one of the following: {field_list}')
if notes:
output.append('') # Empty line
output.append(notes)
output.append('')
for _, fields in oneof_groups.items():
if len(fields) > 1:
field_list = ', '.join(f'`{f}`' for f in fields)
output.append(
f'**Note:** A `{message_name}` MUST contain exactly one of the following: {field_list}'
)
return '\n'.join(output)
@env.macro
def proto_enum_to_table(proto_file: str, enum_name: str) -> str:
"""
Parse a Protocol Buffer enum definition and render it with description and table.
def proto_enum_to_table(
enum_name: str, proto_file: str = 'specification/a2a.proto'
):
"""Parses a .proto file and renders an Enum table."""
try:
elements = _parse_proto(proto_file)
el = _find_type(elements, enum_name, Enum)
if not el:
return f'**Error:** Enum `{enum_name}` not found.'
Args:
proto_file: Relative path to the .proto file
enum_name: Name of the enum to extract
rows = [
[f'`{e.name}`', _extract_comments(e)]
for e in el.elements
if isinstance(e, EnumValue)
]
return f'{_extract_comments(el)}\n\n' + tabulate(
rows, ['Value', 'Description'], tablefmt='github'
)
except Exception as e:
return f'**Error:** {e}'
Returns:
Markdown representation with description before table and notes after
"""
# Resolve the proto file path relative to the project root
project_root = Path(env.conf['docs_dir']).parent
proto_path = project_root / proto_file
@env.macro
def proto_service_to_table(
service_name: str, proto_file: str = 'specification/a2a.proto'
) -> str:
"""Parses a .proto file and renders a Service table."""
try:
elements = _parse_proto(proto_file)
service = _find_type(elements, service_name, Service)
if not service:
return f'**Error:** Service `{service_name}` not found.'
if not proto_path.exists():
return f"**Error:** Proto file not found: {proto_file}"
rows = []
for el in service.elements:
if isinstance(el, Method):
# Request Type
# input_type is a MessageType(type='...', stream=True/False)
req_str = _format_type_for_docs(el.input_type.type)
if el.input_type.stream:
req_str = f'stream {req_str}'
# Read the proto file content
content = proto_path.read_text(encoding='utf-8')
# Response Type
res_str = _format_type_for_docs(el.output_type.type)
if el.output_type.stream:
res_str = f'stream {res_str}'
# Extract the enum definition between the region markers
pattern = rf'// --8<-- \[start:{re.escape(enum_name)}\](.*?)// --8<-- \[end:{re.escape(enum_name)}\]'
match = re.search(pattern, content, re.DOTALL)
rows.append(
[
f'`{el.name}`',
req_str,
res_str,
_extract_comments(el),
]
)
if not match:
return f"**Error:** Enum '{enum_name}' not found in {proto_file}"
if not rows:
return 'None'
enum_content = match.group(1)
headers = ['Method', 'Request', 'Response', 'Description']
return tabulate(rows, headers, tablefmt='github')
# Extract description (before enum), values, and notes (after enum)
description, values, notes = _parse_proto_enum_full(enum_content)
if not values:
return f"**Error:** No values found in enum '{enum_name}'"
# Build the output
output = []
if description:
output.append(description)
output.append('') # Empty line
output.append(_generate_enum_table(values))
if notes:
output.append('') # Empty line
output.append(notes)
return '\n'.join(output)
except Exception as e:
return f'**Error:** {e}'
def _should_skip_comment(comment_text: str) -> bool:
"""Check if a comment line should be skipped (protolint directives, region markers, etc.)."""
return (comment_text.startswith('protolint:') or
comment_text.startswith('--8<--') or
comment_text.startswith('Next ID:'))
# -----------------------------------------------------------------------------
# Helper Functions
# -----------------------------------------------------------------------------
def _parse_field_definition(field_def: str) -> Optional[Dict[str, any]]:
"""
Parse a single field definition and extract its components.
def _extract_comments(element: Any) -> str:
"""Clean and combine comments from an AST element."""
cleaned_parts = []
raw_comments = getattr(element, 'comments', [])
Returns:
Dict with keys: field_type, field_name, annotations, is_repeated, is_optional, is_required
or None if the field definition doesn't match any known pattern
"""
# Check for map type first
map_match = re.match(
r'map<[\w.]+,\s*([\w.]+)>\s+([\w_]+)\s*=\s*\d+(\s*\[(.*?)\])?;',
field_def
for comment in raw_comments:
text = (
comment.strip()
.removeprefix('//')
.removeprefix('/*')
.removesuffix('*/')
)
lines = (
line.strip().removeprefix('*').strip() for line in text.splitlines()
)
combined = ' '.join(filter(None, lines))
if combined and not combined.startswith(
(
'protolint:',
'--8<--',
'Next ID:',
'(-- api-linter',
'api-linter',
'aip.dev/not-precedent',
)
):
cleaned_parts.append(combined)
return ' '.join(cleaned_parts)
def _attach_comments(elements: list[Any]) -> None:
"""Recursively attach preceding comments to each non-comment element."""
buffer = []
for el in elements:
if isinstance(el, Comment):
buffer.append(el.text)
else:
# Attach collected comments to this element
el.comments = buffer
buffer = []
# Recursively handle nested elements (e.g. inside Message or OneOf)
if hasattr(el, 'elements'):
_attach_comments(el.elements)
def _format_type_for_docs(
proto_type: str, is_repeated: bool = False, map_key: str | None = None
) -> str:
"""Formats the type name with Markdown links for non-primitive types."""
# Handle fully qualified names by taking only the last part for the link label,
# but keep it if it's a known google.protobuf type we mapped.
display_name = TYPE_MAP.get(proto_type, proto_type.split('.')[-1])
is_primitive = proto_type in TYPE_MAP or proto_type.startswith(
'google.protobuf'
)
if map_match:
return {
'field_type': f'map<{map_match.group(1)}>',
'field_name': map_match.group(2),
'annotations': map_match.group(4) or '',
'is_repeated': False,
'is_optional': False,
'is_required': 'REQUIRED' in (map_match.group(4) or '')
}
# Check for optional keyword
optional_match = re.match(
r'optional\s+([\w.]+)\s+([\w_]+)\s*=\s*\d+(\s*\[(.*?)])?;',
field_def
)
if optional_match:
return {
'field_type': optional_match.group(1),
'field_name': optional_match.group(2),
'annotations': optional_match.group(4) or '',
'is_repeated': False,
'is_optional': True,
'is_required': False
}
# Create a slug for the link. Messages are usually CamelCase, so lowercase it.
label = f'`{display_name}`'
if not is_primitive:
label = f'[{label}](#{display_name.lower()})'
# Try regular field pattern
field_match = re.match(
r'(repeated\s+)?([\w.]+)\s+([\w_]+)\s*=\s*\d+(\s*\[(.*?)\])?;',
field_def
)
if field_match:
annotations = field_match.group(5) or ''
return {
'field_type': field_match.group(2),
'field_name': field_match.group(3),
'annotations': annotations,
'is_repeated': field_match.group(1) is not None,
'is_optional': False,
'is_required': 'REQUIRED' in annotations
}
if map_key:
key_label = TYPE_MAP.get(map_key, map_key)
return f'map of {key_label} to {label}'
if is_repeated:
return f'array of {label}'
return label
def _find_type(elements: list[Any], name: str, target_cls: type) -> Any | None:
"""Recursively searches for a Message or Enum by name."""
for el in elements:
if getattr(el, 'name', None) == name and isinstance(el, target_cls):
return el
if isinstance(el, Message):
found = _find_type(el.elements, name, target_cls)
if found:
return found
return None
def _get_display_name(field_name: str, annotations: str) -> str:
"""Extract display name from json_name annotation or convert from snake_case."""
json_name_match = re.search(r'json_name\s*=\s*"([^"]+)"', annotations)
if json_name_match:
return json_name_match.group(1)
return _snake_to_camel_case(field_name)
def _process_field(field: Field, is_oneof: bool = False) -> list[str]:
"""Converts a Field or MapField object into a table row."""
options = getattr(field, 'options', [])
cardinality_obj = getattr(field, 'cardinality', None)
cardinality = (
getattr(cardinality_obj, 'value', None) if cardinality_obj else None
)
# Determine Display Name (json_name vs snake_case)
json_name = next(
(o.value.strip('"') for o in options if o.name == 'json_name'), None
)
display_name = json_name or _snake_to_camel_case(field.name)
def _determine_required_value(is_required: bool, is_optional: bool) -> str:
"""Determine the required column value for a field."""
if is_required:
return 'Yes'
elif is_optional:
return 'Optional'
return 'No'
# Determine Type
is_map = isinstance(field, MapField)
is_repeated = cardinality == 'REPEATED'
type_to_format = field.value_type if is_map else field.type
map_key = getattr(field, 'key_type', None)
def _parse_proto_message_full(content: str) -> Tuple[str, List[Dict[str, str]], str, Dict[str, List[str]]]:
"""
Parse proto message content and extract description, fields, and notes.
type_str = _format_type_for_docs(type_to_format, is_repeated, map_key)
Returns:
Tuple of (description_before, fields, notes_after, oneof_groups)
where oneof_groups is a dict mapping oneof names to lists of field names
"""
fields = []
oneof_groups = {}
lines = content.split('\n')
current_comment = []
description_lines = []
notes_lines = []
inside_message = False
message_ended = False
inside_oneof = False
current_oneof_name = None
accumulated_line = ''
# Determine Required/Optional
has_required_behavior = any(
'REQUIRED' in str(opt.value)
for opt in options
if 'field_behavior' in opt.name
)
for line in lines:
stripped = line.strip()
# Collect description before the message declaration
if not inside_message and not message_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
description_lines.append(comment_text)
elif stripped.startswith('message '):
inside_message = True
continue
elif stripped: # Non-comment, non-message line
continue
# Collect notes after the message ends
elif message_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
notes_lines.append(comment_text)
continue
# Process content inside the message
elif inside_message:
# Check if message has ended
if stripped == '}' and not inside_oneof:
message_ended = True
continue
# Check for end of oneof block
if stripped == '}' and inside_oneof:
inside_oneof = False
current_oneof_name = None
continue
# Check for start of oneof block
oneof_match = re.match(r'oneof\s+([\w_]+)\s*{', stripped)
if oneof_match:
inside_oneof = True
current_oneof_name = oneof_match.group(1)
oneof_groups[current_oneof_name] = []
continue
# Collect comment lines for fields
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
current_comment.append(comment_text)
# Parse field definition - handle multi-line definitions
elif stripped and not stripped.startswith('message') and not stripped.startswith('enum'):
# Accumulate line if it doesn't end with semicolon
if accumulated_line:
accumulated_line += ' ' + stripped
else:
accumulated_line = stripped
# Process only when we have a complete field definition (ends with semicolon)
if not accumulated_line.endswith(';'):
continue
# Parse the complete field definition
field_info = _parse_field_definition(accumulated_line)
accumulated_line = '' # Reset for next field
if field_info:
# Convert proto type to readable format
readable_type = _format_proto_type(
field_info['field_type'],
field_info['is_repeated']
)
# Join comment lines
description = ' '.join(current_comment) if current_comment else ''
# Get display name and required value
display_name = _get_display_name(
field_info['field_name'],
field_info['annotations']
)
required_value = _determine_required_value(
field_info['is_required'],
field_info['is_optional']
)
fields.append({
'name': display_name,
'type': readable_type,
'required': required_value,
'description': description
})
# Track oneof fields
if inside_oneof and current_oneof_name:
oneof_groups[current_oneof_name].append(display_name)
# Reset comment buffer
current_comment = []
else:
# Reset comment buffer if not a field
if not inside_oneof:
current_comment = []
description = ' '.join(description_lines).strip()
notes = ' '.join(notes_lines).strip()
return description, fields, notes, oneof_groups
def _parse_proto_enum_full(content: str) -> Tuple[str, List[Dict[str, str]], str]:
"""
Parse proto enum content and extract description, values, and notes.
Returns:
Tuple of (description_before, values, notes_after)
"""
values = []
lines = content.split('\n')
current_comment = []
description_lines = []
notes_lines = []
inside_enum = False
enum_ended = False
for line in lines:
stripped = line.strip()
# Collect description before the enum declaration
if not inside_enum and not enum_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
description_lines.append(comment_text)
elif stripped.startswith('enum '):
inside_enum = True
continue
elif stripped: # Non-comment, non-enum line
continue
# Collect notes after the enum ends
elif enum_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not comment_text.startswith('protolint:') and not comment_text.startswith('--8<--'):
notes_lines.append(comment_text)
continue
# Process content inside the enum
elif inside_enum:
# Check if enum has ended
if stripped == '}':
enum_ended = True
continue
# Collect comment lines
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
# Skip protolint directives and region markers
if not comment_text.startswith('protolint:') and not comment_text.startswith('--8<--'):
current_comment.append(comment_text)
# Parse enum value definition
elif stripped and not stripped.startswith('enum'):
value_match = re.match(r'([\w_]+)\s*=\s*(\d+);', stripped)
if value_match:
value_name = value_match.group(1)
# Join comment lines
description = ' '.join(current_comment) if current_comment else ''
values.append({
'name': value_name,
'description': description
})
# Reset comment buffer
current_comment = []
description = ' '.join(description_lines).strip()
notes = ' '.join(notes_lines).strip()
return description, values, notes
def _format_proto_type(proto_type: str, is_repeated: bool) -> str:
"""
Format proto type to a more readable format with links to specification.
Non-primitive types are automatically linked to their anchor in specification.md.
"""
# Map proto types to readable types
type_map = {
'string': 'string',
'int32': 'integer',
'int64': 'integer',
'bool': 'boolean',
'bytes': 'bytes',
'google.protobuf.Struct': 'object',
'google.protobuf.Timestamp': 'timestamp',
}
# Check for map type first
map_match = re.match(r'map<(.+)>', proto_type)
if map_match:
value_type = map_match.group(1)
readable_value_type = type_map.get(value_type, value_type)
# Create link for non-primitive types
if not _is_primitive_type(value_type):
readable_value_type = f'[`{readable_value_type}`](#{value_type})'
else:
readable_value_type = f'`{readable_value_type}`'
return f'map of {readable_value_type}'
readable_type = type_map.get(proto_type, proto_type)
# Create link for non-primitive types
if not _is_primitive_type(proto_type):
formatted_type = f'[`{readable_type}`](#{proto_type})'
if is_oneof:
req_val = 'Optional (OneOf)'
elif cardinality == 'REQUIRED' or has_required_behavior:
req_val = 'Yes'
else:
formatted_type = f'`{readable_type}`'
req_val = 'No'
if is_repeated:
return f'array of {formatted_type}'
desc = _extract_comments(field)
return formatted_type
return [f'`{display_name}`', type_str, req_val, desc]
def _snake_to_camel_case(snake_str: str) -> str:
"""
Convert snake_case to camelCase for field names.
"""
"""Convert snake_case to camelCase."""
components = snake_str.split('_')
# Keep the first component lowercase, capitalize the rest
return components[0] + ''.join(x.title() for x in components[1:])
def _generate_markdown_table(fields: List[Dict[str, str]]) -> str:
"""
Generate a markdown table from field definitions.
"""
# Table header
table = "| Field | Type | Required | Description |\n"
table += "|-------|------|----------|-------------|\n"
# Table rows
for field in fields:
name = field['name']
field_type = field['type']
required = field['required']
description = field['description'].replace('\n', ' ').replace('|', '\\|')
table += f"| `{name}` | {field_type} | {required} | {description} |\n"
return table
def _generate_enum_table(values: List[Dict[str, str]]) -> str:
"""
Generate a markdown table from enum values.
"""
# Table header with much wider Value column hint
table = "| Value | Description |\n"
table += "|:--------------------------------------|:------------|\n"
# Table rows
for value in values:
name = value['name']
description = value['description'].replace('\n', ' ').replace('|', '\\|')
table += f"| `{name}` | {description} |\n"
return table

View File

@ -1,3 +1,8 @@
{% extends "base.html" %}
{% block announce %}{% endblock %}
{% block announce %}
Join the new DeepLearning.AI short course: <strong>A2A: The Agent2Agent Protocol</strong>!
<a href="https://goo.gle/dlai-a2a" class="md-button">
Enroll for free
</a>
{% endblock %}

View File

@ -1,10 +1,88 @@
# Changelog
## [0.4.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v0.4.0) (2025-09-15)
## [1.0.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v1.0.0) (2026-03-12)
### ⚠ BREAKING CHANGES
* **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](https://github.com/a2aproject/A2A/issues/1500))
* **spec:** remove duplicated ID from the create task push config request ([#1487](https://github.com/a2aproject/A2A/issues/1487))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](https://github.com/a2aproject/A2A/issues/1486))
* **spec:** Add LF prefix to the package. ([#1474](https://github.com/a2aproject/A2A/issues/1474))
* **spec:** Switch to non-complex IDs in requests ([#1389](https://github.com/a2aproject/A2A/issues/1389))
* **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283))
* **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](https://github.com/a2aproject/A2A/issues/1384))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](https://github.com/a2aproject/A2A/issues/1308))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](https://github.com/a2aproject/A2A/issues/1307))
* **spec:** Fixes for the last_updated_after field ([#1358](https://github.com/a2aproject/A2A/issues/1358))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](https://github.com/a2aproject/A2A/issues/1303))
* **spec:** Make "message" field name consistent between protocol bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](https://github.com/a2aproject/A2A/issues/1301))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](https://github.com/a2aproject/A2A/issues/1222))
* **spec:** Remove v1s from a2a url http bindings
* **spec:** Large refactor of specification to separate application protocol definition from mapping to transports
### Features
* **spec:** Add `tasks/list` method for retrieving and filtering tasks with pagination
* **spec:** Add `tasks/list` method with filtering and pagination to the specification ([0a9f629](https://github.com/a2aproject/A2A/commit/0a9f629e801d4ae89f94991fc28afe9429c91cbc))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](https://github.com/a2aproject/A2A/issues/1303)) ([525ff38](https://github.com/a2aproject/A2A/commit/525ff38e5fe2a118f5be5d25189708b590616dd4))
* **spec:** Natively Support Multi-tenancy on gRPC through an additional scope field on the request. ([#1195](https://github.com/a2aproject/A2A/issues/1195)) ([cfbce32](https://github.com/a2aproject/A2A/commit/cfbce32cb0ac2a630597eb8b771691cac5b20a4b)), closes [#1148](https://github.com/a2aproject/A2A/issues/1148)
* **spec:** Provide ability for SDKs to be backwards compatible. ([#1401](https://github.com/a2aproject/A2A/issues/1401)) ([227e249](https://github.com/a2aproject/A2A/commit/227e2493c317004b7e6f7ef4a484e220ffd0b77e))
* **spec:** Remove v1s from a2a url http bindings ([1bd263f](https://github.com/a2aproject/A2A/commit/1bd263f5373fdc8fa7c17ec8bdb24088996b6828))
### Bug Fixes
* Add missing metadata field to Part message in gRPC specification ([#1019](https://github.com/a2aproject/A2A/issues/1019)) ([b3b266d](https://github.com/a2aproject/A2A/commit/b3b266d127dde3d1000ec103b252d1de81289e83)), closes [#1005](https://github.com/a2aproject/A2A/issues/1005)
* Add name field to FilePart protobuf message ([#983](https://github.com/a2aproject/A2A/issues/983)) ([2b7cb6f](https://github.com/a2aproject/A2A/commit/2b7cb6f8408e6324c48fb82c71839c67a18f1fab)), closes [#984](https://github.com/a2aproject/A2A/issues/984)
* Clarify blocking calls return on interrupted states ([#1403](https://github.com/a2aproject/A2A/issues/1403)) ([0655ff3](https://github.com/a2aproject/A2A/commit/0655ff324a93b7e0eaebc108666e6703998b4a9c))
* **doc:** Makes JSON-RPC SendMessage response clearer ([#1241](https://github.com/a2aproject/A2A/issues/1241)) ([5792804](https://github.com/a2aproject/A2A/commit/57928043727e5e002a1395dadfb5f699d0626b1c))
* **docs:** Clearer wording around context id. ([#1588](https://github.com/a2aproject/A2A/issues/1588)) ([dec790a](https://github.com/a2aproject/A2A/commit/dec790aa063943e3ac70e972f9da513c25ab420c))
* **grpc:** Fix inconsistent property name between gRPC and JSON-RPC in Message object ([#1100](https://github.com/a2aproject/A2A/issues/1100)) ([2a1f819](https://github.com/a2aproject/A2A/commit/2a1f819aaa2540602ee81498e159ebe0192be818))
* **grpc:** missing field in gRPC spec - state_transition_history ([#1138](https://github.com/a2aproject/A2A/issues/1138)) ([a2de798](https://github.com/a2aproject/A2A/commit/a2de7981cadeaa5197bee56cbd6ab7b2c5da2541)), closes [#1139](https://github.com/a2aproject/A2A/issues/1139)
* **grpc:** Update `CreateTaskPushNotificationConfig` endpoint to `/v1/{parent=tasks/*/pushNotificationConfigs}` ([#979](https://github.com/a2aproject/A2A/issues/979)) ([911f9b0](https://github.com/a2aproject/A2A/commit/911f9b059c52dd65497b76ccf63d196ca84c7f0e))
* **proto:** Add icon_url to a2a.proto ([#986](https://github.com/a2aproject/A2A/issues/986)) ([17e7f62](https://github.com/a2aproject/A2A/commit/17e7f62df9a3e4ca0768ab8d4f0bb7573b3d73e1))
* **proto:** Adds metadata field to A2A DataPart proto ([#1004](https://github.com/a2aproject/A2A/issues/1004)) ([a8b45dc](https://github.com/a2aproject/A2A/commit/a8b45dcc429a5571ef8a24c36336bf84b89bbd7f))
* Remove unimplemented state_transition_history capability field ([#1396](https://github.com/a2aproject/A2A/issues/1396)) ([c768a44](https://github.com/a2aproject/A2A/commit/c768a44da0f719595e375636f3cab9898ff6df75)), closes [#1228](https://github.com/a2aproject/A2A/issues/1228)
* Restore CreateTaskPushNotificationConfig method naming ([#1402](https://github.com/a2aproject/A2A/issues/1402)) ([d14f410](https://github.com/a2aproject/A2A/commit/d14f4107119bf0fe0dff9e2c577eb4ab70b51793))
* Revert "chore(gRPC): Update a2a.proto to include metadata on GetTaskRequest" ([#1000](https://github.com/a2aproject/A2A/issues/1000)) ([e6b8c65](https://github.com/a2aproject/A2A/commit/e6b8c654a86a6ee461bb5c7be5d5b81004b80a92))
* Simplify Part message structure by flattening FilePart and DataPart ([#1411](https://github.com/a2aproject/A2A/issues/1411)) ([bfae8f7](https://github.com/a2aproject/A2A/commit/bfae8f7791e019f21f6662dd73fce0b3ab261cd6))
* **spec:** Add LF prefix to the package. ([#1474](https://github.com/a2aproject/A2A/issues/1474)) ([a54e809](https://github.com/a2aproject/A2A/commit/a54e80904aa32c74a14bc2c3d21bf82936ccbbdd))
* **spec:** add metadata to `CancelTaskRequest` ([#1485](https://github.com/a2aproject/A2A/issues/1485)) ([c441b91](https://github.com/a2aproject/A2A/commit/c441b910b64d45514ae929a42e7367c2a9a2f6c3)), closes [#1484](https://github.com/a2aproject/A2A/issues/1484)
* **spec:** Added clarification on timestamps in HTTP query params ([#1425](https://github.com/a2aproject/A2A/issues/1425)) ([6292104](https://github.com/a2aproject/A2A/commit/6292104e359efca05bd8703174517b6f961ae4e1))
* **spec:** Added clarifying text around messages and artifacts ([#1424](https://github.com/a2aproject/A2A/issues/1424)) ([b03d141](https://github.com/a2aproject/A2A/commit/b03d141aeab6abd71a229e85c81f7e4c00b537ec))
* **spec:** Adjust field number for `ListTasksRequest.tenant` to prevent missing number ([#1470](https://github.com/a2aproject/A2A/issues/1470)) ([cd16c52](https://github.com/a2aproject/A2A/commit/cd16c5276b4c662ca1823678d07487a624cad606))
* **spec:** Clarify contextId behavior when message is sent with taskId but without contextId ([#1309](https://github.com/a2aproject/A2A/issues/1309)) ([a336a5a](https://github.com/a2aproject/A2A/commit/a336a5a4846fdf85079d4e310339ea0128922ee7))
* **spec:** Clarify versioning strategy and client responsibilities in protocol specification ([#1259](https://github.com/a2aproject/A2A/issues/1259)) ([a4afeea](https://github.com/a2aproject/A2A/commit/a4afeea788b3877101f7a63c2e50091709490058))
* **spec:** Fix/1251 clarify authentication scheme ([#1256](https://github.com/a2aproject/A2A/issues/1256)) ([3e6c7db](https://github.com/a2aproject/A2A/commit/3e6c7db90790c2d05dad3ab1a313de26debe5cb7))
* **spec:** Fixes for the last_updated_after field ([#1358](https://github.com/a2aproject/A2A/issues/1358)) ([0e204bf](https://github.com/a2aproject/A2A/commit/0e204bf878eb63619e205d3419ebc48d4cd35849))
* **spec:** Make "message" field name consistent between protocol bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302)) ([1e5f462](https://github.com/a2aproject/A2A/commit/1e5f46206403982cc629a0dad535856b28c269aa)), closes [#1230](https://github.com/a2aproject/A2A/issues/1230)
* **spec:** make `history_length` optional ([#1071](https://github.com/a2aproject/A2A/issues/1071)) ([0572953](https://github.com/a2aproject/A2A/commit/057295311b8ddda63bdda56c82a694c76d307e37))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](https://github.com/a2aproject/A2A/issues/1486)) ([cf735cb](https://github.com/a2aproject/A2A/commit/cf735cb87056ff6d62abd21a1a66ccb14a23c38e))
* **spec:** Remove config from binding. ([#1587](https://github.com/a2aproject/A2A/issues/1587)) ([010b9cc](https://github.com/a2aproject/A2A/commit/010b9cc936fbafd66610282ad66070da2cb28855))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](https://github.com/a2aproject/A2A/issues/1301)) ([60f83c3](https://github.com/a2aproject/A2A/commit/60f83c3faac4770b231f038406c9e02282887a25)), closes [#1227](https://github.com/a2aproject/A2A/issues/1227)
* **spec:** remove duplicated ID from the create task push config request ([#1487](https://github.com/a2aproject/A2A/issues/1487)) ([393898d](https://github.com/a2aproject/A2A/commit/393898dfeefa37186aced5b61733c5d2c0d9c34a))
* **spec:** Remove metadata field from ListTasksRequest ([#1235](https://github.com/a2aproject/A2A/issues/1235)) ([b6ef9ee](https://github.com/a2aproject/A2A/commit/b6ef9eec558c877fb69024df090a8bb63c542a1c))
* **spec:** Remove reserved and fix tags ordering ([#1494](https://github.com/a2aproject/A2A/issues/1494)) ([1997c9d](https://github.com/a2aproject/A2A/commit/1997c9d63058ca0b89361a7d6e508f4641a6f68b))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](https://github.com/a2aproject/A2A/issues/1222)) ([c196824](https://github.com/a2aproject/A2A/commit/c196824396bb4af4c595f30e2c503a5ab1dbac4b)), closes [#1215](https://github.com/a2aproject/A2A/issues/1215)
* **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283)) ([4dd980f](https://github.com/a2aproject/A2A/commit/4dd980f6ff1989177faffa631a695aba811c56ad))
* **spec:** Suggest Unique Identifier fields to be UUID ([#966](https://github.com/a2aproject/A2A/issues/966)) ([00cf76e](https://github.com/a2aproject/A2A/commit/00cf76e7bbc752842ef254f3d4136ed1b5751f6e))
* **spec:** Switch to non-complex IDs in requests ([#1389](https://github.com/a2aproject/A2A/issues/1389)) ([2596c1c](https://github.com/a2aproject/A2A/commit/2596c1c5e0effd941880e8487d38d78b74b9c0bf)), closes [#1390](https://github.com/a2aproject/A2A/issues/1390)
* **spec:** Update security schemes example ([#1364](https://github.com/a2aproject/A2A/issues/1364)) ([f9a8f5b](https://github.com/a2aproject/A2A/commit/f9a8f5b85d5b07824c52d55d63f7d71ccc6303c5))
* Update the Java tutorials and descriptions ([#1181](https://github.com/a2aproject/A2A/issues/1181)) ([202aa06](https://github.com/a2aproject/A2A/commit/202aa069e66f701bacf2156d42d8916fc96a5188))
### Documentation
* **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](https://github.com/a2aproject/A2A/issues/1384)) ([810eaa1](https://github.com/a2aproject/A2A/commit/810eaa1c6e6462f845a00774f8622b998272116e)), closes [#1344](https://github.com/a2aproject/A2A/issues/1344)
### Code Refactoring
* **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](https://github.com/a2aproject/A2A/issues/1500)) ([d1ed0da](https://github.com/a2aproject/A2A/commit/d1ed0da587d2d634ba0b81a40d082cee0850b81b))
* **spec:** Large refactor of specification to separate application protocol definition from mapping to transports ([b078419](https://github.com/a2aproject/A2A/commit/b0784199543eebf2e95dcb02e9336cb213923506))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](https://github.com/a2aproject/A2A/issues/1307)) ([40d6286](https://github.com/a2aproject/A2A/commit/40d6286fbe29fb083d416b77e84122df8d70ae9d))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](https://github.com/a2aproject/A2A/issues/1308)) ([5b101cc](https://github.com/a2aproject/A2A/commit/5b101cce0fff449c1120ad50ce360acf7c90bac3))
## [0.3.0](https://github.com/a2aproject/A2A/compare/v0.2.6...v0.3.0) (2025-07-30)

View File

@ -72,7 +72,7 @@ an environment where participants feel welcome and safe.
Reports should be directed to [a2a-coc@googlegroups.com](mailto:a2a-coc@googlegroups.com), the
Project Steward(s) for A2A. It is the Project Steward’s duty to
receive and address reported violations of the code of conduct. They will then
work with a committee consisting of representatives from the A2A project and leadership.
work with a committee consisting of representatives from the A2A project and leadership.
We will investigate every complaint, but you may not receive a direct response.
We will use our discretion in determining when and how to follow up on reported
@ -87,4 +87,4 @@ harassment or threats to anyone's safety, we may take action without notice.
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
available at
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
https://www.contributor-covenant.org/version/1/4/code-of-conduct/

View File

@ -2,7 +2,84 @@
We'd love to accept your patches and contributions to this project.
## Contribution process
## Development Setup
### Prerequisites
To contribute to this project, you will need the following tools installed:
- [Python 3.10+](https://www.python.org/downloads/)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) - Fast Python package installer and resolver.
- [Node.js & npm](https://nodejs.org/en/download/) - For markdown formatting tools.
- [Docker](https://www.docker.com/get-started) - Required for running the local linter.
## Working with Documentation
The A2A documentation is built using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/).
### Local Setup
1. **Create a virtual environment:**
```bash
uv venv .doc-venv
```
2. **Activate the virtual environment:**
```bash
source .doc-venv/bin/activate # Unix/macOS
# .doc-venv\Scripts\activate # Windows
```
3. **Install dependencies:**
```bash
uv pip install -r requirements-docs.txt
```
### Build and Serve
1. **Build the documentation:**
This script regenerates the JSON schema from the protocol definition, builds the SDK documentation, and then builds the MkDocs site.
```bash
./scripts/build_docs.sh
```
2. **Serve the documentation locally:**
Run the following command to start a local server with live reloading:
```bash
mkdocs serve
```
3. **View the documentation:**
Open [http://localhost:8000](http://localhost:8000) in your browser.
## Code Standards
### Linting
We use [Super Linter](https://github.com/super-linter/super-linter) to ensure code quality across the repository. You can run the linter locally using Docker:
```bash
./scripts/lint.sh
```
### Formatting
We use [markdownlint](https://github.com/igorshubovych/markdownlint-cli) for formatting markdown files. You can fix most formatting issues automatically by running:
```bash
./scripts/format.sh
```
### Conventional Commits
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for our commit messages. This helps us automate our release process and maintain a clear changelog.
## Contribution Process
### Code reviews
@ -11,18 +88,17 @@ use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.
### Contributor Guide
### Workflow
You may follow these steps to contribute:
1. **Fork the official repository.** This will create a copy of the official repository in your own account.
2. **Sync the branches.** This will ensure that your copy of the repository is up-to-date with the latest changes from the official repository.
3. **Work on your forked repository's feature branch.** This is where you will make your changes to the code.
4. **Commit your updates on your forked repository's feature branch.** This will save your changes to your copy of the repository.
5. **Submit a pull request to the official repository's main branch.** This will request that your changes be merged into the official repository.
6. **Resolve any linting errors.** This will ensure that your changes are formatted correctly.
4. **Test your changes.** Build and preview the documentation locally to ensure everything looks correct.
5. Format and lint your code. Run ./scripts/format.sh and ./scripts/lint.sh to ensure your changes meet our standards.
6. **Commit your updates.** Use conventional commit messages on your feature branch.
7. **Submit a pull request.** Submit a PR from your fork's feature branch to the official repository's `main` branch.
8. **Resolve any feedback.** Work with reviewers to address any comments or requested changes.
Here are some additional things to keep in mind during the process:
- **Test your changes.** Before you submit a pull request, make sure that your changes work as expected.
- **Be patient.** It may take some time for your pull request to be reviewed and merged.
Be patient! It may take some time for your pull request to be reviewed and merged.

View File

@ -6,9 +6,9 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
| :--- | :--- | :--- | :--- |
| **Google** | Todd Segal | Principal Engineer | [@ToddSegal](https://github.com/ToddSegal) |
| **Microsoft** | Darrel Miller | Partner API Architect | [@darrelmiller](https://github.com/darrelmiller) |
| **Cisco** | Luca Muscariello | Principal Engineer | [@muscariello](https://github.com/muscariello) |
| **Amazon Web Services** | Nicholas Aldridge | Principal Engineer | [@000-000-000-000-000](https://github.com/000-000-000-000-000) |
| **Salesforce** | Gary Lerhaupt | VP, Product Architecture | [@lerhaupt](https://github.com/lerhaupt) |
| **Cisco** | Luca Muscariello | Distinguished Engineer | [@muscariello](https://github.com/muscariello) |
| **Amazon Web Services** | Abhimanyu Siwach | Senior Software Engineer | [@siwachabhi](https://github.com/siwachabhi) |
| **Salesforce** | Stephen Petschulat | Principal Architect | [@spetschulatSFDC](https://github.com/spetschulatSFDC) |
| **ServiceNow** | Sean Hughes | Director of Open Science | [@hughesthe1st](https://github.com/hughesthe1st) |
| **SAP** | Sivakumar N. | Vice President | [@SivaNSAP](https://github.com/SivaNSAP) |
| **IBM Research** | Kate Blair | Director of Incubation | [@geneknit](https://github.com/geneknit) |
@ -32,6 +32,8 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
a. **"Startup Phase."** At the inception of the Project, each organization listed in the [`GOVERNANCE`](GOVERNANCE.md) file in the governance repository of the Project will have the right to appoint (and remove and replace) one employee to serve as a voting member of the TSC.
Adding new organizations to the GOVERNANCE file will be determined through a proposal to the TSC GOVERNANCE.md file. Any new organization will be added through a majority vote of the TSC, and an employee of that organization will serve as a voting member of the TSC.
b. **"Steady State."** The TSC will decide upon a "steady state" composition of the TSC (whether by election, subproject technical leads, or other method as determined by the TSC), to take effect from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC.
c. The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file. Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person.
@ -63,13 +65,15 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
### TSC Voting
While the Project aims to operate as a consensus-based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis.
While the Project aims to operate as a consensus-based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis.
Quorum for TSC meetings requires at least fifty percent of all voting members of the TSC to be present. The TSC may continue to meet if quorum is not met but will be prevented from making any decisions at the meeting. Except as provided in Section 7.c. and 8.a, decisions by vote at a meeting require a majority vote of those in attendance, provided quorum is met. Decisions made by electronic vote without a meeting require a majority vote of all voting members of the TSC.
### TSC Meetings
A voting member who has not attended a meeting of the TSC within the last six weeks (as measured by the LFX attendance tracking) shall be determined to be an inactive voting member. They will not be included in active votes, which means that they will not be counted for quorum, and the sponsoring organization may choose to replace the named TSC member within a reasonable timeframe.
Our hope is that the first TSC meeting will be held in August 2025. Once the TSC representatives are finalized, scheduling will begin. In the interim we have drafted a [working doc for TSC Meeting Agendas](https://docs.google.com/document/d/1Dx6qYfCjSChHKRMwLJcvtDjq6igYTAKFW9Vg1IMPCUk/view).
### TSC Meetings
TSC Meetings are held on the Linux Foundation's meeting platform. [https://zoom-lfx.platform.linuxfoundation.org/meetings/agent2agent](https://zoom-lfx.platform.linuxfoundation.org/meetings/agent2agent) has meeting details and recordings of past meetings.
Our [working doc for TSC Meeting Agendas](https://docs.google.com/document/d/1Dx6qYfCjSChHKRMwLJcvtDjq6igYTAKFW9Vg1IMPCUk/view) is in Google Docs.
## Project Communications

View File

@ -6,6 +6,37 @@
<img src="https://www.gstatic.com/_/boq-sdlc-agents-ui/_/r/Mvosg4klCA4.svg" alt="Ask Code Wiki" height="20">
</a>
<div style="text-align: left;">
<details>
<summary>🌐 Language</summary>
<div>
<div style="text-align: center;">
<a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=en">English</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-CN">简体中文</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=zh-TW">繁體中文</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ja">日本語</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ko">한국어</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=hi">हिन्दी</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=th">ไทย</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fr">Français</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=de">Deutsch</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=es">Español</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=it">Italiano</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ru">Русский</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=pt">Português</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=nl">Nederlands</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=pl">Polski</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=ar">العربية</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=fa">فارسی</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=tr">Türkçe</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=vi">Tiếng Việt</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=id">Bahasa Indonesia</a>
| <a href="https://openaitx.github.io/view.html?user=a2aproject&project=A2A&lang=as">অসমীয়া</a>
</div>
</div>
</details>
</div>
<!-- markdownlint-disable MD041 -->
<div style="text-align: center;">
<div class="centered-logo-text-group">
@ -25,9 +56,19 @@ With A2A, agents can:
- Securely collaborate on long-running tasks.
- Operate without exposing their internal state, memory, or tools.
## Intro to A2A Video
## DeepLearning.AI Course
[![A2A Intro Video](https://img.youtube.com/vi/Fbr_Solax1w/hqdefault.jpg)](https://goo.gle/a2a-video)
[![A2A DeepLearning.AI](https://img.youtube.com/vi/4gYm0Rp7VHc/maxresdefault.jpg)](https://goo.gle/dlai-a2a)
Join this short course on [A2A: The Agent2Agent Protocol](https://goo.gle/dlai-a2a), built in partnership with Google Cloud and IBM Research, and taught by [Holt Skinner](https://github.com/holtskinner), [Ivan Nardini](https://github.com/inardini), and [Sandi Besen](https://github.com/sandijean90).
**What you'll learn:**
- **Make agents A2A-compliant:** Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.
- **Connect agents:** Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.
- **Orchestrate workflows:** Build sequential and hierarchical workflows of A2A-compliant agents.
- **Multi-agent systems:** Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.
- **A2A and MCP:** Learn how A2A complements MCP by enabling agents to collaborate with each other.
## Why A2A?

View File

@ -0,0 +1,73 @@
# ADR-001: Leverage ProtoJSON Specification for JSON Serialization
**Status:** Accepted
**Date:** 2025-11-18
**Decision Makers:** Technical Steering Committee (TSC)
**Technical Story:** JSON serialization approach for A2A specification
## Context
The A2A specification defines message structures using Protocol Buffers (proto definitions) but also needs to support JSON serialization for HTTP/REST-based communication and JSONRPC payloads. We needed to establish a normative approach for how JSON payloads should be serialized based on the proto definitions referenced by the specification.
Without a clearly specified approach to JSON serialization from proto definitions, implementers could create incompatible JSON representations, leading to interoperability issues across different A2A implementations.
## Decision Drivers
* Need for a standardized, well-documented approach to JSON serialization
* Ability to leverage existing Protocol Buffer tooling
* Clear specification for handling edge cases and type mappings
* Idiomatic use of JSON conventions
* Coupling of specification to tool chain
## Considered Options
* ProtoJSON (canonical JSON encoding for Protocol Buffers)
* Explicit transformation rules defined in the A2A specification
## Decision Outcome
**Chosen option:** "ProtoJSON specification"
The TSC has decided to leverage the ProtoJSON specification as the normative approach to serializing JSON based on the proto definition referenced by the specification. This provides a well-defined, standardized way to convert Protocol Buffer messages to JSON format.
This decision was made with some reservation due to the dependency on ProtoJSON mechanisms and potential impact on protocol bindings unrelated to protobuf and gRPC. However, the decision is reversible if we identify significant issues during implementation, at which point we can duplicate the ProtoJSON conventions in the A2A specification where applicable and describe differences as needed.
### Consequences
#### Positive
* Standardized approach with clear documentation and specification
* Wide ecosystem support with mature libraries across multiple languages
* Consistent behavior across different implementations
* Reduced ambiguity in JSON representation
* Built-in handling for proto3 types and conventions
* Provides well-defined rules for wire-unsafe changes
* Removes the need to define data type handling rules for dates and numbers in the A2A specification
#### Negative
* **Breaking change**: This decision will result in breaking changes to existing JSON payloads, specifically relating to the casing of enum values (ProtoJSON uses SCREAMING_SNAKE_CASE for enums)
* **Loss of roundtrip capability**: We will not be able to roundtrip unknown values because ProtoJSON doesn't support preserving unknown fields in the JSON representation
* Migration effort required for existing implementations
* **Ugly enums** Developers are not used to seeing enum values in SCREAMING_SNAKE_CASE in JSON, which may lead to confusion or errors during implementation
* Changes to the ProtoJSON specification for the benefit of gRPC could have an impact on other protocol bindings.
* Enums require a "unspecified" value even when they are only used for required fields to meet Proto best practices.
* Certain field names need to have less than optimal names to avoid conflicts with proto keywords. e.g. message.
#### Neutral
* Implementations must follow ProtoJSON specification strictly
* Documentation must clearly communicate the breaking changes
## References
* [ProtoJSON format](https://protobuf.dev/programming-guides/json/)
## Notes
This decision was made to ensure long-term interoperability and maintainability of the A2A specification. While it introduces breaking changes in the short term, the benefits of standardization and ecosystem alignment outweigh the migration costs.
Implementers should be aware that the enum casing change is the most visible breaking change and should plan accordingly for version transitions.

113
adrs/adr-template.md Normal file
View File

@ -0,0 +1,113 @@
# ADR-[number]: [Title]
**Status:** [Proposed | Accepted | Deprecated | Superseded]
**Date:** YYYY-MM-DD
**Decision Makers:** [List of people involved in the decision]
**Technical Story:** [Optional: Link to related issue/story]
## Context
[Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?]
## Decision Drivers
* [Driver 1: e.g., performance requirements]
* [Driver 2: e.g., maintainability concerns]
* [Driver 3: e.g., team expertise]
* [Driver 4: e.g., cost considerations]
## Considered Options
* [Option 1]
* [Option 2]
* [Option 3]
## Decision Outcome
**Chosen option:** "[Option X]"
[Describe why this option was selected. What are the expected positive outcomes?]
### Consequences
#### Positive
* [Positive consequence 1]
* [Positive consequence 2]
#### Negative
* [Negative consequence 1]
* [Negative consequence 2]
#### Neutral
* [Neutral consequence 1]
## [Optional] Pros and Cons of the Options
### [Option 1]
[Brief description of option 1]
**Pros:**
* [Advantage 1]
* [Advantage 2]
**Cons:**
* [Disadvantage 1]
* [Disadvantage 2]
### [Option 2]
[Brief description of option 2]
**Pros:**
* [Advantage 1]
* [Advantage 2]
* [Advantage 2]
**Cons:**
* [Disadvantage 1]
* [Disadvantage 2]
### [Option 3]
[Brief description of option 3]
**Pros:**
* [Advantage 1]
* [Advantage 2]
* [Advantage 2]
**Cons:**
* [Disadvantage 1]
* [Disadvantage 2]
## Implementation
[Optional: Describe the implementation plan, timeline, and any specific technical details]
## Related Decisions
* [Link to related ADR 1]
* [Link to related ADR 2]
## References
* [Link to resource 1]
* [Link to resource 2]
* [Link to resource 3]
## Notes
[Any additional notes, follow-up items, or context that doesn't fit elsewhere]

55
docs/announcing-1.0.md Normal file
View File

@ -0,0 +1,55 @@
# A2A Protocol Ships v1.0: Production-Ready Standard for Agent-to-Agent Communication
The A2A Protocol community today are announcing the release of A2A Protocol v1.0, marking the first stable, production-ready version of the open standard for communication between AI agents. The protocol is guided by a technical steering committee with representatives from eight major technology companies.
As organizations build increasingly sophisticated multi-agent systems, interoperability has become the defining challenge. Teams can coordinate agents effectively within a single platform, but connecting those systems across technology stacks and organizational boundaries remains difficult. A2A addresses that challenge by combining support for multiple protocol bindings, seamless version negotiation, and a common semantic model so agents can interoperate across systems with predictable behavior.
The v1.0 release emphasizes maturity rather than reinvention: the core ideas remain intact, while rough edges have been removed, ambiguous areas clarified, and enterprise deployment requirements addressed more directly. The official SDKs ensure v1.0 A2A agents work seamlessly with older versions.
## Delivering on enterprise requirements
The v1.0 release introduces several capabilities aimed at production environments where trust, scale, and operational control are non-negotiable.
- **Heterogeneous environment support** enables interoperability across diverse technology stacks through multi-protocol bindings and version negotiation, so enterprises are not tied to a single vendor or platform.
- **Multi-tenancy support** allows a single endpoint to securely host many agents.
- **Signed Agent Cards** provide cryptographic verification of agent identity and metadata, establishing trust before interaction across organizational boundaries.
- **Improved security posture** modernizes security flows and removes legacy patterns that are no longer aligned with current best practices.
Together, these changes move A2A from early adopter implementations toward broader enterprise confidence, especially in regulated or multi-party scenarios.
## Web-aligned architecture for scale
A2A v1.0 aligns with core architectural principles of the web: stateless, layered architecture, standard protocol bindings, and infrastructure-friendly communication patterns. That alignment matters operationally because organizations can scale agent interactions with the same proven load balancing, gateway, security and observability patterns they already use for web systems.
The standard builds on industry-proven protocols, including JSON+HTTP, gRPC, and JSON-RPC. It also keeps the barrier to entry low: in its simplest form, an A2A interaction can begin with a single HTTP request.
A2A also gives consumers flexibility in how they receive results. Depending on workload and operational needs, clients can use polling, streaming, or webhooks to consume task updates and responses.
## Complementary to MCP, not a replacement
The release also reinforces A2A's relationship with the Model Context Protocol (MCP), a point that has generated confusion in early ecosystem discussions.
MCP and A2A solve different layers of the problem. MCP is commonly used for tool and context integration at the individual agent level. A2A focuses on communication and coordination between agents. In practice, many systems will use both: MCP inside agents, A2A between agents.
## Smooth migration from earlier versions
The v1.0 release tightens specification behavior, which includes breaking changes in the interaction protocol. AgentCard, however, has evolved in a backward-compatible way and now allows agents to advertise support for both existing v0.3 protocol behavior and v1.0 simultaneously. This enables clients to migrate progressively rather than through a single cutover.
That approach is intended to protect current investments while still delivering the benefits of a cleaner, more durable standard.
## Why this release matters now
AI agents are increasingly deployed across departments, products, and partner ecosystems. At that scale, the key question is no longer whether agents can coordinate within one stack, but whether they can collaborate reliably across organizational and platform boundaries. Open protocols determine whether organizations can compose best-of-breed systems or become locked into isolated stacks.
A2A v1.0 gives the market a stronger foundation for open multi-agent collaboration. The community is now focused on delivering multi-language v1.0 SDK support to help developers build conformant solutions with ease.
The complete v1.0 materials, including specification and migration documentation, are available at [a2a-protocol.org](https://a2a-protocol.org) and on [GitHub](https://github.com/a2aproject/A2A).
---
**About A2A Protocol**
The Agent-to-Agent (A2A) Protocol is an open standard that enables AI agents to discover capabilities, communicate, and delegate tasks across teams, products, and organizations. The A2A Technical Steering Committee includes representatives from AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow.
**Media Contact**
A2A Protocol Community
[https://a2a-protocol.org](https://a2a-protocol.org)

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 226 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 125 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 51 KiB

View File

@ -67,6 +67,39 @@ These agentic frameworks have built-in A2A integration, making it easy to get st
- [Slide (Tyler)](https://slide.mintlify.app/guides/a2a-integration)
- [Strands Agents](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/multi-agent/agent-to-agent/)
## Community SDKs
Building an A2A agent in a language not covered by the [official SDKs](./sdk/index.md)? These community-maintained implementations have you covered.
### 🦀 Rust — a2a-rust
![Stars](https://img.shields.io/github/stars/tomtom215/a2a-rust?style=flat-square) [![Crate](https://img.shields.io/crates/v/a2a-protocol-sdk?style=flat-square)](https://crates.io/crates/a2a-protocol-sdk)
[tomtom215/a2a-rust](https://github.com/tomtom215/a2a-rust) · A2A spec v1.0.0 · Full SDK with JSON-RPC, REST, WebSocket, and gRPC transports.
### 🦀 Rust — a2a-rs
![Stars](https://img.shields.io/github/stars/EmilLindfors/a2a-rs?style=flat-square) [![Crate](https://img.shields.io/crates/v/a2a-rs?style=flat-square)](https://crates.io/crates/a2a-rs)
[EmilLindfors/a2a-rs](https://github.com/EmilLindfors/a2a-rs) · A2A spec v0.3.0 · Modular workspace with core protocol, AP2 extension, and agent framework.
### 🍎 Swift — A2AClient
![Stars](https://img.shields.io/github/stars/tolgaki/a2a-client-swift?style=flat-square)
[tolgaki/a2a-client-swift](https://github.com/tolgaki/a2a-client-swift) · A2A spec v1.0.0 · Swift Package Manager. iOS 15+, macOS 12+, watchOS 8+, tvOS 15+.
### 💧 Elixir — a2a
![Stars](https://img.shields.io/github/stars/actioncard/a2a-elixir?style=flat-square) [![Hex](https://img.shields.io/hexpm/v/a2a?style=flat-square)](https://hex.pm/packages/a2a)
[actioncard/a2a-elixir](https://github.com/actioncard/a2a-elixir) · A2A spec v0.2.0 · OTP-native with Agent behaviour, TaskStore, and supervision tree.
!!! tip "Want to add your SDK?"
Open an issue on [a2aproject/A2A](https://github.com/a2aproject/A2A/issues/new?title=Community%20SDK%20Submission) with a link to your repository and published package.
**Requirements:** Spec compliance, published package on standard registry, documentation, tests with CI, Apache 2.0 license, and active maintenance.
## The Future is Interoperable
The excitement surrounding Google's A2A protocol clearly indicates a strong belief in its potential to revolutionize multi-agent AI systems. By providing a standardized way for AI agents to communicate and collaborate, A2A is poised to unlock new levels of automation and innovation. As enterprises increasingly adopt AI agents, A2A represents a crucial step towards realizing the full power of interconnected AI ecosystems.

View File

@ -31,7 +31,11 @@ Originally developed by Google and now donated to the Linux Foundation, A2A prov
- :material-play-circle:{ .lg .middle } **Video** Intro in <8 min
<iframe width="560" height="315" src="https://www.youtube.com/embed/Fbr_Solax1w?si=QxPMEEiO5kLr5_0F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
<iframe class="video-container" src="https://www.youtube.com/embed/Fbr_Solax1w?si=QxPMEEiO5kLr5_0F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
- :material-play-circle:{ .lg .middle } **Course** [DeepLearning.AI](https://deeplearning.ai) - Intro to A2A
[![A2A DeepLearning.AI](https://img.youtube.com/vi/4gYm0Rp7VHc/maxresdefault.jpg)](https://goo.gle/dlai-a2a)
- :material-book-open:{ .lg .middle } **Read the Introduction**
@ -53,6 +57,8 @@ Originally developed by Google and now donated to the Linux Foundation, A2A prov
[:octicons-arrow-right-24: Python Tutorial](./tutorials/python/1-introduction.md)
[:octicons-arrow-right-24: Walkthrough with AI Agent Frameworks](https://github.com/holtskinner/A2AWalkthrough)
- :material-code-braces:{ .lg .middle } **Explore Code Samples**
See A2A in action with sample clients, servers, and agent framework integrations.

View File

@ -1,210 +1,81 @@
# A2A (Agent2Agent) Protocol High-Level Summary
This project defines and demonstrates the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. The core goal is to allow agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) or by different vendors to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely.
This project defines the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. It allows agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely without exposing internal state.
The repository provides:
The repository contains:
1. **Formal Specification:** Protobuf definitions (`specification/a2a.proto`) and JSON Schema (`specification/json/a2a.json`).
2. **Core Concepts Documentation:** Guides on discovery, task lifecycle, streaming, and enterprise-readiness (`docs/topics/`).
3. **SDKs:** Production-ready SDKs for Python, JS/TS, Java, Go, and .NET.
4. **Sample Implementations:** Real-world examples integrated with various agent frameworks.
1. **Formal Specification:** A detailed JSON Schema (`specification/json/a2a.json`) and Protobuf definitions (`specification/grpc/a2a.proto`) that define the structure of A2A messages, including requests, responses, tasks, artifacts, and agent metadata (Agent Cards).
2. **Core Concepts Documentation:** A comprehensive set of documents in the `docs/topics/` directory covering agent discovery, task lifecycle, streaming, push notifications, and enterprise-readiness.
3. **SDKs and Sample Implementations:**
* **SDKs:** Production-ready SDKs for Python, Java, JavaScript, and C#/.NET, with more in development.
* **Example Agents:** Demonstrations of integrating A2A into various agent frameworks:
* **Python:** LangGraph (currency conversion, streaming), CrewAI (image generation, file artifacts), Google ADK (expense reports, form handling).
* **JavaScript/TypeScript:** Genkit (movie info via API, code generation with file artifacts).
* **Example Hosts:** Applications that consume A2A services, including CLIs for direct interaction and a Python-based multi-agent orchestrator.
4. **Demo Web Application:** A web UI demonstrating multi-agent interactions facilitated by the A2A protocol, including visualization of conversations, tasks, events, and agent discovery.
## Key Files & Directories
Key features of the A2A protocol include: agent discovery via Agent Cards, standardized task management (`send`, `get`, `cancel`), support for rich content types (text, files, structured data), real-time streaming updates for long-running tasks, and mechanisms for asynchronous push notifications. The project is open-source and encourages community contribution.
- `specification/a2a.proto`: The authoritative Protobuf definition of the protocol.
- `docs/topics/`: Detailed conceptual guides (Discovery, Lifecycle, Security, etc.).
- `docs/tutorials/`: Step-by-step guides for building A2A-compliant agents.
- `scripts/`: Utility scripts for building documentation and formatting.
# A2A (Agent2Agent) Protocol
# A2A (Agent2Agent) Protocol Reference
## 1. Overview
- **Project Name:** Agent2Agent (A2A) Protocol
- **Purpose:** An open protocol enabling communication and interoperability between AI agents built on different frameworks or by different vendors.
- **Core Goal:** Allow agents to discover capabilities, negotiate interaction, and collaborate securely on tasks.
- **Communication:** Uses JSON-RPC 2.0 over HTTP(S). Supports standard request/response and Server-Sent Events (SSE) for streaming. Also includes a gRPC specification.
- **Key Components:** Formal Specification (JSON Schema, Protobuf), SDKs (Python, JS, Java, .NET), Sample Implementations, and Core Documentation.
- **Purpose:** Open standard for agent-to-agent interoperability.
- **Communication Bindings:** Supports JSON-RPC 2.0 (HTTP/SSE), gRPC, and HTTP/REST.
- **Key Concepts:** Agent Cards for discovery, Task-based execution, Multi-turn Messages, and Artifact outputs.
## 2. Protocol Specification (`specification/json/a2a.json`)
## 2. Core Data Objects
### 2.1. Core JSON-RPC Structures
### 2.1 AgentCard (`/.well-known/agent-card.json`)
Describes an agent's identity and capabilities.
- `name`, `description`, `version`: Identity metadata.
- `supported_interfaces`: List of `AgentInterface` (URL, protocol binding, tenant, protocol version).
- `capabilities`: `streaming`, `push_notifications`, `extended_agent_card`, `extensions`.
- `skills`: List of `AgentSkill` (id, name, description, tags, examples).
- `security_schemes`, `security_requirements`: Authentication configuration (API Key, OAuth2, OIDC, mTLS, HTTP Auth).
- `default_input_modes`, `default_output_modes`: Supported MIME types (e.g., `text/plain`, `application/json`).
- **`JSONRPCMessage`:** Base for requests/responses. Contains `jsonrpc: "2.0"` and optional `id`.
- **`JSONRPCRequest`:** Represents a request with `method`, `params`, and `id`.
- **`JSONRPCResponse`:** Represents a response with either `result` or `error`, and a matching `id`.
- **`JSONRPCError`:** Represents an error with `code`, `message`, and optional `data`.
### 2.2 Task
Represents a stateful unit of work.
- `id`, `context_id`: Identifiers for the task and its conversational context.
- `status`: `TaskStatus` (state, message, timestamp).
- `artifacts`: List of `Artifact` (outputs produced).
- `history`: List of `Message` (conversation history).
- `metadata`: Custom structured data.
### 2.2. Key A2A Data Objects
### 2.3 TaskState (Enum)
- `SUBMITTED`, `WORKING`, `COMPLETED` (terminal), `FAILED` (terminal), `CANCELED` (terminal), `REJECTED` (terminal), `INPUT_REQUIRED` (interrupted), `AUTH_REQUIRED` (interrupted).
- **`AgentCard`:** Metadata describing an agent, typically found at `/.well-known/agent-card.json`.
- `protocolVersion`: (string) The version of the A2A protocol supported.
- `name`, `description`, `version`: (string) Agent's identity.
- `url`: (string) The preferred endpoint URL for the agent's A2A service.
- `provider`: (`AgentProvider`) Organization details.
- `capabilities`: (`AgentCapabilities`) Features supported (streaming, push notifications, extensions).
- `securitySchemes`, `security`: (object, array) Authentication and authorization requirements, following OpenAPI specifications.
- `defaultInputModes`, `defaultOutputModes`: (string[]) Default supported MIME types.
- `skills`: (`AgentSkill[]`) List of specific capabilities.
- `supportsExtendedAgentCard`: (boolean) Indicates if a more detailed card is available post-authentication.
- `signatures`: (`AgentCardSignature[]`) JWS signatures for verifying the card's integrity.
- **`AgentSkill`:** A specific capability of an agent, with `id`, `name`, `description`, `tags`, and `examples`.
- **`Task`:** Represents a stateful unit of work.
- `id`, `contextId`: (string) Unique identifiers for the task and its conversational context.
- `status`: (`TaskStatus`) Current state information.
- `artifacts`: (`Artifact[]`) Outputs produced by the agent.
- `history`: (`Message[]`) The conversation history associated with the task (if enabled by `stateTransitionHistory` capability).
- `metadata`: (object) Custom key-value data.
- `kind`: ("task") Type discriminator.
- **`TaskStatus`:**
- `state`: (`TaskState`) Current lifecycle state (e.g., "working", "completed").
- `message`: (`Message`) An optional, human-readable message from the agent providing status details.
- `timestamp`: (string) ISO-8601 timestamp.
- **`TaskState`:** (enum) `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`, `rejected`, `auth-required`, `unknown`.
- **`Message`:** A single unit of communication.
- `role`: ("user" | "agent") Sender's role.
- `parts`: (`Part[]`) The content of the message.
- `messageId`, `taskId`, `contextId`: (string) Identifiers linking the message.
- `referenceTaskIds`: (string[]) List of prior tasks for context.
- **`Part` (Union Type):** A segment of content within a `Message` or `Artifact`.
- **`TextPart`:** Plain text content.
- **`FilePart`:** A file, referenced by URI or with inline base64-encoded bytes.
- **`DataPart`:** Structured JSON data.
- **`Artifact`:** A tangible output generated by a task, composed of one or more `Part`s.
- **`PushNotificationConfig`:** Configuration for receiving asynchronous updates via a webhook URL.
- **`agent/getAuthenticatedExtendedCard`:** An RPC method to retrieve a more detailed `AgentCard` after authentication.
### 2.4 Message & Part
- `Message`: Contains `message_id`, `role` (USER/AGENT), `parts`, `context_id`, `task_id`, `reference_task_ids`.
- `Part`: Union type containing `text`, `raw` (bytes), `url`, or `data` (JSON). Includes `media_type` and `filename`.
### 2.3. A2A RPC Methods
### 2.5 Artifact
- A tangible output from a task, containing one or more `Part`s and metadata.
- **`message/send`:** (Request/Response)
- Sends a message to initiate or continue a task.
- `params`: `MessageSendParams` (includes `taskId`, `contextId`, `message`, optionally `configuration`).
- `result`: `Task` (final state after synchronous processing).
- **`message/stream`:** (Request/Stream)
- Sends a message and subscribes to real-time updates via Server-Sent Events (SSE).
- `params`: `MessageSendParams`.
- `result` (stream events): `SendStreamingMessageResponse` containing one of: `MessageEvent`, `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`. Final event has `final: true`.
- **`tasks/get`:** (Request/Response)
- Retrieves the current state of a task.
- `params`: `TaskQueryParams` (includes `id`, optionally `historyLength`).
- `result`: `Task`.
- **`tasks/list`:** (Request/Response)
- Retrieves a list of tasks with optional filtering and pagination.
- `params`: `ListTasksParams` (optional: `contextId`, `status`, `pageSize`, `pageToken`, `historyLength`, `lastUpdatedAfter`, `includeArtifacts`, `metadata`).
- `result`: `ListTasksResult` (includes `tasks[]`, `totalSize`, `pageSize`, `nextPageToken`).
- **`tasks/cancel`:** (Request/Response)
- Requests cancellation of a running task.
- `params`: `TaskIdParams` (includes `id`).
- `result`: `Task` (updated state, likely 'canceled') or error if not cancelable.
- **`tasks/pushNotificationConfig/set`:** (Request/Response)
- Sets or updates the push notification configuration for a task.
- `params`: `TaskPushNotificationConfig`.
- `result`: `TaskPushNotificationConfig` (confirmed configuration).
- **`tasks/pushNotificationConfig/get`:** (Request/Response)
- Retrieves the current push notification configuration for a task.
- `params`: `TaskIdParams` (includes `taskId`).
- `result`: `TaskPushNotificationConfig`.
- **`tasks/resubscribe`:** (Request/Stream)
- Resubscribes to task updates after a connection interruption (SSE).
- `params`: `TaskQueryParams`.
- `result` (stream events): `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent`.
## 3. RPC Methods
### 2.4. Streaming Update Events (Result of `message/stream` or `tasks/resubscribe`)
| Method | Request | Response | Description |
| :--- | :--- | :--- | :--- |
| `SendMessage` | `SendMessageRequest` | `SendMessageResponse` | Initiates or continues a task. |
| `SendStreamingMessage` | `SendMessageRequest` | `stream StreamResponse` | Sends message and receives real-time SSE updates. |
| `GetTask` | `GetTaskRequest` | `Task` | Retrieves current task state. |
| `ListTasks` | `ListTasksRequest` | `ListTasksResponse` | Filter and paginate tasks. |
| `CancelTask` | `CancelTaskRequest` | `Task` | Requests cancellation of a task. |
| `SubscribeToTask` | `SubscribeToTaskRequest` | `stream StreamResponse` | Subscribes to updates for an existing task. |
| `GetExtendedAgentCard` | `GetExtendedAgentCardRequest` | `AgentCard` | Fetches detailed metadata after authentication. |
- **`SendStreamingMessageResponse`:** Contains a message from the agent.
- `type`: "message"
- `message`: (`Message`) The message content.
- `contextId`: (string) Context identifier the message is associated with.
- `kind`: ("streaming-response") Type discriminator.
- `final`: (boolean) True if this is the final message for the task.
- **`TaskStatusUpdateEvent`:** Signals a change in task status.
- `type`: "task-status"
- `taskId`: (string) Task ID.
- `contextId`: (string) Context identifier the task is associated with.
- `kind`: ("status-update") Type discriminator.
- `status`: (`TaskStatus`) The new status object.
- `final`: (boolean) True if this is the terminal update for the task.
- **`TaskArtifactUpdateEvent`:** Signals a new or updated artifact.
- `type`: "task-artifact"
- `taskId`: (string) Task ID.
- `artifact`: (`Artifact`) The artifact data.
- `append`: (boolean) If true, append parts to artifact; if false (default), replace.
- `lastChunk`: (boolean) If true, indicates this is the final update for the artifact.
- `final`: (boolean) Usually false for artifacts, can signal end concurrently with status.
### 3.1 Streaming Events (`StreamResponse`)
Streams return a payload containing one of:
- `task`: Full task state.
- `message`: A discrete message part.
- `status_update`: `TaskStatusUpdateEvent` (taskId, contextId, status).
- `artifact_update`: `TaskArtifactUpdateEvent` (taskId, artifact, append, last_chunk).
### 2.5. Standard Error Codes
## 4. Security & Authentication
- **Transport:** HTTPS/TLS required for production.
- **Authentication:** Declared in `AgentCard` via OpenAPI-style security schemes.
- **Push Notifications:** Webhooks secured via authentication tokens/schemes configured per task.
- `-32700`: `JSONParseError`
- `-32600`: `InvalidRequestError`
- `-32601`: `MethodNotFoundError`
- `-32602`: `InvalidParamsError`
- `-32603`: `InternalError`
### 2.6. A2A Specific Error Codes
- `-32001`: `TaskNotFoundError`
- `-32002`: `TaskNotCancelableError`
- `-32003`: `PushNotificationNotSupportedError`
- `-32004`: `UnsupportedOperationError`
- `-32005`: `ContentTypeNotSupportedError`
- `-32006`: `InvalidAgentResponseError`
- `-32007`: `AuthenticatedExtendedCardNotConfiguredError`
## 3. Core Concepts
- **Agent Discovery:** Clients find agents by fetching their `AgentCard` JSON, typically from a `/.well-known/agent-card.json` URI or a curated registry.
- **Task Lifecycle:** Tasks progress through defined states (`submitted` -> `working` -> `completed`/`failed`, etc.), enabling tracking of long-running operations.
- **Communication:** Interactions use `Message` objects containing `Part`s (text, file, data). Task outputs are delivered as `Artifact`s.
- **Streaming:** Long-running tasks provide real-time updates via SSE using the `message/stream` method. Updates can be `Task`, `Message`, `TaskStatusUpdateEvent`, or `TaskArtifactUpdateEvent` objects.
- **Push Notifications:** For disconnected clients, agents can send updates to a webhook URL configured via `tasks/pushNotificationConfig/set`.
- **Authentication:** A2A leverages standard web security (e.g., OAuth, API keys), declared in the `AgentCard`. Credentials are sent via HTTP headers, not in the A2A payload.
## 4. Security Considerations
- **Transport Security:** Production environments MUST use HTTPS with modern TLS.
- **Authentication:** Servers MUST authenticate every request based on schemes declared in the `AgentCard`.
- **Authorization:** Authorization logic is implementation-specific and MUST enforce the principle of least privilege, potentially on a per-skill basis.
- **Push Notification Security:** Both the server (validating webhook URLs to prevent SSRF) and the client (verifying incoming notifications) have critical security responsibilities.
- **Input Validation:** Servers MUST rigorously validate all RPC parameters and message content.
## 5. Implementations & Samples
### 5.1. SDKs
- **Python:** `a2a-sdk` on PyPI.
- **JavaScript/TypeScript:** `@a2a-js/sdk` on npm.
- **Java:** `a2a-java` on Maven.
- **C#/.NET:** `A2A` on NuGet.
### 5.2. Python Samples
- **Location:** `a2a-samples/samples/python/`
- **Agents:**
- **LangGraph:** Currency conversion agent demonstrating tool use, multi-turn conversation (`input-required`), and streaming via `message/stream`.
- **CrewAI:** Image generation agent demonstrating file artifact handling.
- **Google ADK:** Expense report agent demonstrating structured data/forms.
- **Hosts:**
- **CLI:** Command-line client for interacting with any A2A agent.
- **Multi-Agent Orchestrator:** An ADK-based agent that delegates tasks to other A2A agents.
### 5.3. JavaScript/TypeScript Samples
- **Location:** `a2a-samples/samples/js/`
- **Framework:** Genkit
- **Agents:**
- **Movie Agent:** Uses an external API to answer questions.
- **Coder Agent:** Generates code and demonstrates file artifact creation.
### 5.4. Demo Application
- **Location:** `a2a-samples/demo/`
- A web application built with Mesop that visualizes multi-agent conversations orchestrated by a host agent, rendering text, images, and forms.
## 6. Development & Setup
- **Prerequisites:** Python (>=3.10), Node.js (>=18).
- **API Keys:** LLM access requires API keys (e.g., `GOOGLE_API_KEY`), typically set via `.env` files.
- **Running Samples:** Involves starting an agent server and then running a host/client application to interact with it.
## 7. Contribution
- See `CONTRIBUTING.md` for guidelines.
- Join discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
- Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
- Provide private feedback via this [Google Form](https://goo.gle/a2a-feedback).
## 5. Implementation Status
- **Official SDKs:** Python (`a2a-sdk`), JS/TS (`@a2a-js/sdk`), Java, Go, C#/.NET.
- **Integrations:** LangGraph, CrewAI, Google ADK, Genkit, AG2, BeeAI, PydanticAI, and more.

View File

@ -11,6 +11,7 @@ collaborate effectively with each other and with users.
- [Activeloop](https://www.activeloop.ai/)
- [Adobe](https://www.adobe.com)
- [AG2AI](https://ag2.ai)
- [AgentTrust](https://agenttrust.ai/)
- [AI21 Labs](https://www.ai21.com/)
- [AI71](https://ai71.ai/)
- [Aisera](https://aisera.com/)
@ -81,6 +82,7 @@ collaborate effectively with each other and with users.
- [InfoSys](https://www.infosys.com)
- [Intuit](https://www.intuit.com)
- [Iron Mountain](https://www.ironmountain.com/)
- [JamJet](https://github.com/jamjet-labs/jamjet)
- [JetBrains](https://www.jetbrains.com)
- [JFrog](https://jfrog.com)
- [Kakao](https://www.kakaocorp.com)
@ -96,6 +98,7 @@ collaborate effectively with each other and with users.
- [Lumeris](https://www.lumeris.com/)
- [Lyzr.ai](https://lyzr.ai)
- [Magyar Telekom](https://www.telekom.hu/)
- [MasOrange](https://masorange.es/en/)
- [Microsoft](https://www.microsoft.com/en-us/microsoft-cloud/blog/2025/05/07/empowering-multi-agent-apps-with-the-open-agent2agent-a2a-protocol/)
- [MindsDB](https://mindsdb.com/blog/mindsdb-now-supports-the-agent2agent-(a2a)-protocol)
- [McKinsey](https://www.mckinsey.com)
@ -106,6 +109,7 @@ collaborate effectively with each other and with users.
- [Nisum](http://www.nisum.com)
- [Noorle Inc](http://www.noorle.com)
- [NTT DATA](https://www.nttdata.com)
- [OIXA Protocol](https://oixa.io)
- [Optimizely Inc](https://www.optimizely.com/)
- [Oracle / NetSuite](https://www.oracle.com/netsuite)
- [Palo Alto Networks](https://www.paloaltonetworks.com/)
@ -114,6 +118,7 @@ collaborate effectively with each other and with users.
- [Pendo](https://www.pendo.io)
- [PerfAI.ai](https://perfai.ai)
- [Personal AI](https://personal.ai)
- [Pinchwork](https://pinchwork.dev)
- [Poppulo](https://www.poppulo.com/blog/poppulo-google-a2a-the-future-of-workplace-communication)
- [Productive Edge](https://www.productiveedge.com/)
- [Proofs](https://proofs.io)
@ -135,6 +140,7 @@ collaborate effectively with each other and with users.
- [Solace](https://solace.com/products/agent-mesh/)
- [Solo.io](https://www.solo.io/)
- [Stacklok, Inc](https://stacklok.com)
- [Strale](https://strale.dev)
- [Supertab](https://www.supertab.co/post/supertab-connect-partners-with-google-cloud-to-enable-ai-agents)
- [Suzega](https://suzega.com/)
- [TCS](https://www.tcs.com)
@ -158,6 +164,7 @@ collaborate effectively with each other and with users.
- [Weights & Biases](https://wandb.ai/wandb_fc/product-announcements-fc/reports/Powering-Agent-Collaboration-Weights-Biases-Partners-with-Google-Cloud-on-Agent2Agent-Interoperability-Protocol---VmlldzoxMjE3NDg3OA)
- [Wipro](https://www.wipro.com)
- [Workday](https://www.workday.com)
- [WritBase](https://github.com/Writbase/writbase)
- [Writer](https://writer.com)
- [Zenity](https://zenity.io)
- [Zeotap](https://www.zeotap.com)

View File

@ -1,15 +1,13 @@
# A2A protocol roadmap
**Last updated:** Jul 16, 2025
**Last updated:** March 10, 2026
## Near-term initiatives
- Release `0.3` version of the protocol which we intend to keep supported and without breaking changes for a significant amount of time with backward compatibility of the SDKs starting at version `0.3`. As part of this release there are a few known breaking changes including:
- Update the `/.well-known/agent.json` path for hosting Agent Cards to `/.well-known/agent-card.json` based on feedback from IANA.
- Refactor class fields to be more Pythonic and adopt `snake_case`. [PR 199](https://github.com/a2aproject/a2a-python/pull/199)
- Solidify the support for [A2A extensions](topics/extensions.md) with SDK support (starting with the Python SDK) and publishing sample extensions.
- Introduce support for signed Agent Cards [Discussion 199](https://github.com/a2aproject/A2A/discussions/199#discussioncomment-13770576) to allow verifying the integrity of Agent Card content.
- Enhance the client side support in SDK (starting with Python) to expose ready-to-use A2A clients, streamlined auth handling and improved handling of tasks.
- Release `1.0` version of the protocol which represents significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
- [What's New in A2A Protocol v1.0](https://a2a-protocol.org/latest/whats-new-v1/) has further updates.
- Continue to support additional [A2A extensions](topics/extensions.md) with SDK support.
- Prioritize community-led development with standardized processes for contributing to the specification, SDKs and tooling.
To review recent protocol changes see [Release Notes](https://github.com/a2aproject/A2A/releases).
@ -17,15 +15,12 @@ To review recent protocol changes see [Release Notes](https://github.com/a2aproj
### Governance
The protocol has been [donated](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents) to the Linux Foundation. The TSC is working on implementing a governance structure that prioritizes community-led development with standardized processes for contributing to the specification, SDKs and tooling. As part of the effort there will be dedicated working groups created for specific areas of the protocol.
The TSC looks to streamline opportunities for contribution through [A2A extensions](topics/extensions.md), [Samples](https://github.com/a2aproject/a2a-samples) and participation.
### Agent Registry
Agent Registry enables the discovery of agents and is a critical component of a multi-agent system. There is an active and ongoing discussion in the community around the latest [Discussion 741](https://github.com/a2aproject/A2A/discussions/741).
### Validation
As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation which the group will continue to enhance in the coming months. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).
As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).
### SDKs

View File

@ -1,15 +1,14 @@
# A2A SDK
A2A currently hosts SDKs in five languages (Python, Go, JS, Java, .NET).
The following table lists the supported languages for official A2A SDKs and their repositories.
The following table lists the supported languages and their stability.
| Language | Support |
| :--------- | :------- |
| Python | [Stable](https://github.com/a2aproject/a2a-python) |
| Go | [Stable](https://github.com/a2aproject/a2a-go) |
| Java | [Stable](https://github.com/a2aproject/a2a-java) |
| JavaScript | [Stable](https://github.com/a2aproject/a2a-js) |
| C#/.NET | [Stable](https://github.com/a2aproject/a2a-dotnet) |
| Language | Repository |
|------------|----------------------------------------------------------|
| Python | [`a2a-python`](https://github.com/a2aproject/a2a-python) |
| Go | [`a2a-go`](https://github.com/a2aproject/a2a-go) |
| Java | [`a2a-java`](https://github.com/a2aproject/a2a-java) |
| JavaScript | [`a2a-js`](https://github.com/a2aproject/a2a-js) |
| C#/.NET | [`a2a-dotnet`](https://github.com/a2aproject/a2a-dotnet) |
| Rust | [`a2a-rs`](https://github.com/a2aproject/a2a-rs) |
The A2A project provides numerous samples across supported languages in the [a2a-samples repository](https://github.com/a2aproject/a2a-samples).

7
docs/sdk/python.md Normal file
View File

@ -0,0 +1,7 @@
---
redirect: python/api/index.html
---
# Python SDK
Redirecting to [API reference](python/api/index.html)...

View File

@ -1,8 +1,8 @@
# -- Project information -----------------------------------------------------
project = 'a2a-sdk'
copyright = '2025, Google LLC'
author = 'Google LLC'
copyright = '2026, The Linux Foundation'
author = 'The Linux Foundation'
# -- General configuration ---------------------------------------------------
@ -16,6 +16,13 @@ extensions = [
# Tell autosummary to generate stub files
autosummary_generate = True
# Suppress warnings from external SDK package
suppress_warnings = [
'ref.python', # Suppress "more than one target found for cross-reference"
'ref.ref', # Suppress "undefined label"
'toc.not_included', # Suppress "document isn't included in any toctree"
]
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

View File

@ -10,4 +10,4 @@ This page contains the SDK documentation for the ``a2a-sdk`` Python package.
.. toctree::
:maxdepth: 4
a2a
modules

File diff suppressed because it is too large Load Diff

View File

@ -91,3 +91,10 @@ figure.hero figcaption {
margin-bottom: 0;
text-align: left;
}
iframe.video-container {
width: 100%;
aspect-ratio: 16 / 9;
height: auto;
border-radius: 4px;
}

View File

@ -81,7 +81,7 @@ Agent Cards include sensitive information, such as:
To mitigate risks, the following protection mechanisms should be considered:
- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#710-agentgetauthenticatedextendedcard) for sensitive information or for serving a more detailed version of the card.
- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#3111-get-extended-agent-card) for sensitive information or for serving a more detailed version of the card.
- **Secure Endpoints:** Implement access controls on the HTTP endpoint serving the Agent Card (e.g., `/.well-known/agent-card.json` or registry API). The methods include:
- Mutual TLS (mTLS)
- Network restrictions (e.g., IP ranges)
@ -91,6 +91,22 @@ To mitigate risks, the following protection mechanisms should be considered:
Any Agent Card containing sensitive data must be protected with authentication and authorization mechanisms. The A2A specification strongly recommends the use of out-of-band dynamic credentials rather than embedding static secrets within the Agent Card.
## Caching Considerations
Agent Cards describe an agent's capabilities and typically change infrequently — for example, when skills are added or authentication requirements are updated. Applying standard HTTP caching practices to Agent Card endpoints reduces unnecessary network requests while ensuring clients eventually receive updated information.
### Server Guidance
Servers hosting Agent Card endpoints should include HTTP caching headers in their responses. The `Cache-Control` header with an appropriate `max-age` directive allows clients and intermediaries to cache the card for a specified duration. Including an `ETag` header — derived from the card's `version` field or a content hash — enables clients to make conditional requests and avoid re-downloading unchanged cards.
### Client Guidance
Clients fetching Agent Cards should honor standard HTTP caching semantics. When a cached card expires, clients should use conditional requests (for example, `If-None-Match` with the stored `ETag` or `If-Modified-Since`) rather than unconditionally re-fetching the full card. When the server does not provide caching headers, clients may apply a reasonable default cache duration.
For Extended Agent Cards, clients should also follow the session-scoped caching guidance described in the [specification](../specification.md#133-extended-agent-card-access-control).
For normative requirements, see [Section 8.6](../specification.md#86-caching) of the specification.
## Future Considerations
The A2A community explores standardizing registry interactions or advanced discovery protocols.

View File

@ -0,0 +1,135 @@
# Custom Protocol Bindings
The A2A protocol ships with three standard bindings (JSON-RPC, gRPC, and
HTTP+JSON/REST) that cover the majority of deployment scenarios. Custom protocol
bindings let implementers expose A2A operations over additional transport
mechanisms not covered by the standard set.
Custom protocol bindings are a complementary but distinct concept to
[Extensions](extensions.md). Extensions modify the *behavior* of protocol
interactions by adding new data, methods, or state transitions on top of an
existing transport. Custom protocol bindings change the *transport layer*
itself—for example, exposing A2A over WebSockets for low-latency bidirectional
communication, or over MQTT for IoT environments with constrained connectivity.
## Declaration in the Agent Card
Custom protocol bindings are declared in the Agent Card's `supportedInterfaces`
list. Each entry identifies the transport by URI, the endpoint URL, and the A2A
protocol version it implements. The `protocolBinding` field should be a URI that uniquely identifies the
binding (see [Section 5.8 of the specification](../specification.md#58-custom-binding-identification)
for the normative requirement and versioning guidance).
```json
{
"supportedInterfaces": [
{
"url": "wss://agent.example.com/a2a/websocket",
"protocolBinding": "https://a2a-protocol.org/bindings/websocket",
"protocolVersion": "1.0"
}
]
}
```
Agents that support multiple bindings list all of them. Clients parse
`supportedInterfaces` in order and select the first transport they support, so
entries should be listed in preference order.
## Requirements
Custom protocol bindings must comply with all requirements in the
[Protocol Binding Requirements and Interoperability](../specification.md#5-protocol-binding-requirements-and-interoperability)
section of the specification. In particular:
- **All core operations must be supported.** The binding must expose every
operation defined in the abstract operations layer (send message, get task,
cancel task, streaming, push notifications, etc.).
- **The data model must be preserved.** All data structures must be
functionally equivalent to the canonical Protocol Buffer definitions. JSON
serializations must use camelCase field names, and timestamps must be
ISO 8601 strings in UTC.
- **Behavior must be consistent.** Semantically equivalent requests must
produce semantically equivalent results regardless of which binding is used.
## Key Areas to Specify
A custom binding specification must address each of the following areas.
### Data Type Mappings
Document how each Protocol Buffer type is represented in the custom transport,
including:
- Binary data encoding (e.g., base64 for text-based transports)
- Enum representation (strings, integers, or named constants)
- Timestamp format (ISO 8601 strings in UTC per the core convention)
### Service Parameters
Service parameters are key-value pairs used to carry horizontally applicable
context such as tracing identifiers or authentication hints. The binding
specification must state:
- The mechanism used to carry service parameters (e.g., custom message headers,
a top-level metadata field)
- Any character encoding or size constraints on keys and values
- Any names reserved by the binding itself
For transports that lack native header support, a common pattern is to embed
service parameters as a JSON object in a dedicated metadata field, for example
`a2a-service-parameters`.
### Error Mapping
The binding must map all A2A error types to transport-native error
representations while preserving their semantic meaning. Provide a mapping
table equivalent to the one in the specification's
[Error Code Mappings](../specification.md#54-error-code-mappings) section, showing
how each A2A error type (e.g., `TaskNotFoundError`, `UnsupportedOperationError`) is expressed in the custom binding's native error format.
### Streaming
If the transport supports streaming, document:
- The stream mechanism (e.g., WebSocket frames, chunked encoding, long polling)
- Ordering guarantees (events must be delivered in the order they were
generated)
- Reconnection behavior when a connection is interrupted
- How stream completion or termination is signaled to the client
If the transport does not support streaming, state this limitation clearly in
the Agent Card so clients can fall back to polling.
### Authentication and Authorization
Document how authentication credentials declared in the Agent Card are
transmitted using the custom transport. Define how authentication challenges are
communicated to clients and ensure the custom binding does not inadvertently
bypass the agent's primary security controls.
## Interoperability Testing
Before publishing a custom binding, verify that:
- All operations behave identically to the standard bindings for the same
logical requests
- Error conditions, large payloads, and long-running tasks are handled correctly
- Any intentional deviations from standard binding behavior are clearly
documented
- Sample requests and responses are included in the specification to help
implementers
## Governance
The A2A organization uses a formal governance framework for how custom protocol
bindings are proposed, developed, promoted, and maintained. Official bindings
use the `https://a2a-protocol.org/bindings/` URI prefix and are hosted under
the `a2aproject` organization with the `cpb-` repository prefix (experimental
bindings use `experimental-cpb-`). A2A SDKs SHOULD implement official custom
protocol bindings.
For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
page.

View File

@ -0,0 +1,189 @@
# Extension and Protocol Binding Governance
The A2A organization uses a unified governance framework for both
[Extensions](extensions.md) and [Custom Protocol Bindings](custom-protocol-bindings.md).
This document defines the formal process for proposing, developing, promoting,
and maintaining these artifacts within the A2A organization.
Anyone may develop and publish extensions or custom protocol bindings
independently. The tiers and lifecycle described here apply specifically to
those hosted under the `a2aproject` GitHub organization.
## Tiers
Both extensions and custom protocol bindings use a two-tier system within the
`a2aproject` organization. Repository naming and URI prefixes differ by type:
| | Extensions | Custom Protocol Bindings |
| :----------------------- | :---------------------------------------------- | :--------------------------------------------- |
| Official repo prefix | `ext-{name}` | `cpb-{name}` |
| Experimental repo prefix | `experimental-ext-{name}` | `experimental-cpb-{name}` |
| Official URI prefix | `https://a2a-protocol.org/extensions/` | `https://a2a-protocol.org/bindings/` |
### Official
Official artifacts are developed and maintained under the `a2aproject` GitHub
organization, officially recommended by the TSC. Each repository has designated
maintainers identified in `MAINTAINERS.md`.
**Requirements:**
- Specifications MUST use the same language as the core specification
([RFC 2119](https://tools.ietf.org/html/rfc2119))
- MUST be licensed under Apache 2.0
- MUST have at least one reference implementation
- SHOULD have associated documentation on the A2A website
### Experimental
Experimental artifacts provide an incubation pathway for community contributors
to prototype and collaborate on ideas before graduation to official status.
**Creation Requirements:**
- An experimental repository can ONLY be created with sponsorship from an A2A
Maintainer
- The sponsoring Maintainer is responsible for initial oversight of the
experimental artifact
- Experimental repositories MUST clearly indicate their experimental/non-official
status in the README
- Any published packages MUST use naming that clearly indicates experimental
status
- The TSC retains oversight, including the ability to archive or remove
experimental repositories
## Lifecycle
Extensions and custom protocol bindings progress through the following phases.
### Proposal Phase
Any community member may propose an extension or custom protocol binding:
1. **Open an Issue**: Create an issue in the main `a2aproject/A2A` repository
describing:
- An abstract describing the extension's purpose or the binding's transport
and use case
- Motivation explaining why this cannot be achieved with the core protocol
or existing standard bindings
- An initial technical approach or specification draft
2. **Community Discussion**: The proposal is open for community feedback and
refinement
### Maintainer Sponsorship
For a proposal to proceed to experimental status:
1. **Secure a Sponsor**: An A2A Maintainer must agree to sponsor the proposal
2. **Repository Creation**: The sponsoring Maintainer creates the
`experimental-ext-*` or `experimental-cpb-*` repository under `a2aproject`
3. **Oversight**: The sponsoring Maintainer provides initial oversight and
ensures alignment with A2A design principles
### Experimental Development
While in experimental status:
- Contributors iterate on the specification and reference implementations
- The experimental artifact MAY be used by early adopters with the
understanding that breaking changes are expected
- Community feedback is gathered and incorporated
- The experimental repository MUST clearly indicate its non-official status
### Graduation to Official Status
To graduate an experimental extension or binding to official status:
1. **Maturity Requirements**:
- At least one production-quality reference implementation
- Documentation meeting A2A standards
- Evidence of community adoption or interest
- Clear maintainer commitment for ongoing maintenance
2. **Graduation Proposal**: Open an issue in `a2aproject/A2A` with:
- Reference to the experimental repository and its implementations
- Summary of community feedback and adoption
- Proposed maintainers for the official artifact
3. **TSC Vote**:
- The proposal is added to the TSC meeting agenda
- **Quorum Requirement**: At least 50% of TSC voting members must be
present
- **Approval**: Requires majority vote of those in attendance (per A2A
governance)
- The TSC may request revisions before a final vote
4. **Acceptance**:
- (Extensions) The repository is renamed from `experimental-ext-*` to
`ext-*`; documentation is added to the A2A website's extensions page
- (Custom Protocol Bindings) The repository is renamed from
`experimental-cpb-*` to `cpb-*`; documentation is added to the A2A
website's custom protocol bindings page
### Official Iteration
Once official, extensions and bindings may be iterated on:
- Repository maintainers are responsible for day-to-day governance
- Changes SHOULD be coordinated via the relevant working group if one exists
- Breaking changes require a new identifier
- Breaking changes require TSC review
- Maintainers SHOULD coordinate with SDK maintainers for implementation updates
### Promotion to Core Protocol
Some extensions may eventually transition to core protocol features, and some
custom protocol bindings may transition to core bindings. This is governed
through the existing A2A specification enhancement process:
- A proposal is submitted following the standard specification change process
- The proposal references the official extension or binding and its adoption
- TSC vote with standard quorum and majority requirements applies
- Not all extensions or bindings are suitable for core inclusion; many will
remain as extensions or custom bindings indefinitely
## SDK Support
SDK support requirements differ between extensions and official custom protocol
bindings, reflecting their different roles in the protocol ecosystem.
**Extensions**: A2A SDKs MAY implement extensions. Where implemented:
- Extensions MUST be disabled by default and require explicit opt-in
- SDK documentation SHOULD list supported extensions
- SDK maintainers have full autonomy over extension support decisions
- Extension support is not required for protocol conformance
**Official Custom Protocol Bindings**: A2A SDKs SHOULD implement official
custom protocol bindings. Where implemented:
- Custom protocol bindings MUST be disabled by default and require explicit
opt-in
- SDK documentation SHOULD list supported custom protocol bindings
- SDK maintainers have full autonomy over binding support decisions
- Custom protocol binding support is not required for protocol conformance
## Legal Requirements
### Licensing
Official extensions and custom protocol bindings MUST be available under the
Apache 2.0 license, consistent with the core A2A project.
### Contributor License Grant
By submitting a contribution to an official A2A extension or custom protocol
binding repository, contributors represent that:
1. They have the legal authority to grant the rights
2. The contribution is original work or they have sufficient rights to submit it
3. They grant to the Linux Foundation and recipients a perpetual, worldwide,
non-exclusive, royalty-free license to use, reproduce, modify, and
distribute the contribution
### Antitrust
Extension and custom protocol binding developers acknowledge that:
- They may compete with other participants
- They have no obligation to implement any extension or binding
- They are free to develop competing extensions or bindings
- Status as an official extension or binding does not create an exclusive
relationship

View File

@ -51,13 +51,26 @@ However, some foreseeable applications include:
| [Traceability Extension](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/extensions/traceability) | Explore the Python implementation and basic usage of the Traceability Extension (v1). |
| [Agent Gateway Protocol (AGP) Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/agp) | A Core Protocol Layer or Routing Extension that introduces Autonomous Squads (ASq) and routes Intent payloads based on declared Capabilities, enhancing scalability (v1). |
## Extension Governance
The A2A organization uses a formal governance framework for how extensions are
proposed, developed, promoted, and maintained. Official extensions use the
`https://a2a-protocol.org/extensions/` URI prefix and are hosted under the
`a2aproject` organization with the `ext-` repository prefix (experimental
extensions use `experimental-ext-`).
For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
page.
## Limitations
There are some changes to the protocol that extensions don't allow, primarily
to prevent breaking core type validations:
- **Changing the Definition of Core Data Structures**: For example, adding new
fields or removing required fields to protocol-defined data structures).
fields or removing required fields to protocol-defined data structures.
Extensions should place custom attributes in the `metadata` map present on
core data structures.
- **Adding New Values to Enum Types**: Extensions should use existing enum values
@ -68,9 +81,7 @@ to prevent breaking core type validations:
Agents declare their support for extensions in their Agent Card by including
`AgentExtension` objects within their `AgentCapabilities` object.
```ts { .no-copy }
--8<-- "types/src/types.ts:AgentExtension"
```
{{ proto_to_table("AgentExtension") }}
The following is an example of an Agent Card with an extension:
@ -170,14 +181,13 @@ A2A-Extensions: https://example.com/ext/konami-code/v1
Content-Length: 519
{
"jsonrpc": "2.0",
"method": "message/send",
"method": "SendMessage",
"id": "1",
"params": {
"message": {
"kind": "message",
"messageId": "1",
"role": "user",
"parts": [{"kind": "text", "text": "Oh magic 8-ball, will it rain today?"}]
"role": "ROLE_USER",
"parts": [{"text": "Oh magic 8-ball, will it rain today?"}]
},
"metadata": {
"https://example.com/ext/konami-code/v1/code": "motherlode"
@ -197,10 +207,11 @@ Content-Length: 338
"jsonrpc": "2.0",
"id": "1",
"result": {
"kind": "message",
"messageId": "2",
"role": "agent",
"parts": [{"kind": "text", "text": "That's a bingo!"}]
"message": {
"messageId": "2",
"role": "ROLE_AGENT",
"parts": [{"text": "That's a bingo!"}]
}
}
}
```
@ -228,9 +239,10 @@ versioning, and distributing extension implementations.
- **Permanent Identifiers**: Authors are encouraged to use a permanent
identifier service, such as `w3id.org`, for their extension URIs to
prevent broken links.
- **Community Registry (Future)**: The A2A community might establish a
central registry for discovering and browsing available extensions in
the future.
- **Community Registry**: The A2A [Extension Governance](#extension-governance)
framework defines a tiered system for official and experimental
extensions hosted under the `a2aproject` organization, including a
lifecycle for proposing and promoting extensions.
- **Packaging and Reusability (A2A SDKs and Libraries)**:
To promote adoption, extension logic should be packaged into reusable
libraries that can be integrated into existing A2A client and

View File

@ -28,7 +28,7 @@ The following table describes the fundamental communication elements in A2A:
| Agent Card | A JSON metadata document describing an agent's identity, capabilities, endpoint, skills, and authentication requirements. | Enables clients to discover agents and understand how to interact with them securely and effectively. |
| Task | A stateful unit of work initiated by an agent, with a unique ID and defined lifecycle. | Facilitates tracking of long-running operations and enables multi-turn interactions and collaboration. |
| Message | A single turn of communication between a client and an agent, containing content and a role ("user" or "agent"). | Conveys instructions, context, questions, answers, or status updates that are not necessarily formal artifacts. |
| Part | The fundamental content container (for example, TextPart, FilePart, DataPart) used within Messages and Artifacts. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
| Part | The fundamental content container used within Messages and Artifacts. A Part holds one of: text content, a file reference (URL or inline bytes), or structured data. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
| Artifact | A tangible output generated by an agent during a task (for example, a document, image, or structured data). | Delivers the concrete results of an agent's work, ensuring structured and retrievable outputs. |
## Interaction Mechanisms
@ -67,13 +67,18 @@ agent. It includes a role ("user" or "agent") and a unique `messageId`. It
contains one or more Part objects, which are granular containers for the actual
content. This design allows A2A to be modality independent.
The primary part kinds are:
The `Part` object is a flexible container that can hold different types of content using a `oneof` field structure. A Part must contain exactly one of the following content fields:
- `TextPart`: Contains plain textual content.
- `FilePart`: Represents a file. It can be transmitted either inline (Base64
encoded) or through a URI. It includes metadata like "name" and "mimeType".
- `DataPart`: Carries structured JSON data. This is useful for forms,
parameters, or any machine-readable information.
- `text`: A string containing plain textual content.
- `raw`: A byte array containing binary file data (inline).
- `url`: A string URI referencing external file content.
- `data`: A structured JSON value (e.g., object, array) for machine-readable data.
Additionally, every `Part` can include:
- `mediaType`: The MIME type of the content (e.g., `"text/plain"`, `"image/png"`, `"application/json"`).
- `filename`: An optional name for the file or content.
- `metadata`: A key-value map for additional context.
## Artifacts

View File

@ -141,7 +141,7 @@ The following example illustrates a typical task flow with a follow-up:
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "message.send",
"method": "SendMessage",
"params": {
"message": {
"role": "user",
@ -163,27 +163,27 @@ The following example illustrates a typical task flow with a follow-up:
"jsonrpc": "2.0",
"id": "req-001",
"result": {
"id": "task-boat-gen-123",
"contextId": "ctx-conversation-abc",
"status": {
"state": "completed"
},
"artifacts": [
{
"artifactId": "artifact-boat-v1-xyz",
"name": "sailboat_image.png",
"description": "A generated image of a sailboat on the ocean.",
"parts": [
{
"file": {
"name": "sailboat_image.png",
"task": {
"id": "task-boat-gen-123",
"contextId": "ctx-conversation-abc",
"status": {
"state": "TASK_STATE_COMPLETED"
},
"artifacts": [
{
"artifactId": "artifact-boat-v1-xyz",
"name": "sailboat_image.png",
"description": "A generated image of a sailboat on the ocean.",
"parts": [
{
"filename": "sailboat_image.png",
"mediaType": "image/png",
"fileWithBytes": "base64_encoded_png_data_of_a_sailboat"
"raw": "base64_encoded_png_data_of_a_sailboat"
}
}
]
}
]
]
}
]
}
}
}
```
@ -195,7 +195,7 @@ The following example illustrates a typical task flow with a follow-up:
{
"jsonrpc": "2.0",
"id": "req-002",
"method": "message.send",
"method": "SendMessage",
"params": {
"message": {
"role": "user",
@ -223,27 +223,27 @@ The following example illustrates a typical task flow with a follow-up:
"jsonrpc": "2.0",
"id": "req-002",
"result": {
"id": "task-boat-color-456",
"contextId": "ctx-conversation-abc",
"status": {
"state": "completed"
},
"artifacts": [
{
"artifactId": "artifact-boat-v2-red-pqr",
"name": "sailboat_image.png",
"description": "A generated image of a red sailboat on the ocean.",
"parts": [
{
"file": {
"name": "sailboat_image.png",
"task": {
"id": "task-boat-color-456",
"contextId": "ctx-conversation-abc",
"status": {
"state": "TASK_STATE_COMPLETED"
},
"artifacts": [
{
"artifactId": "artifact-boat-v2-red-pqr",
"name": "sailboat_image.png",
"description": "A generated image of a red sailboat on the ocean.",
"parts": [
{
"filename": "sailboat_image.png",
"mediaType": "image/png",
"fileWithBytes": "base64_encoded_png_data_of_a_RED_sailboat"
"raw": "base64_encoded_png_data_of_a_RED_sailboat"
}
}
]
}
]
]
}
]
}
}
}
```

View File

@ -10,19 +10,19 @@ The following key features detail how SSE streaming is implemented and managed w
- **Server Capability:** The A2A Server must indicate its support for streaming by setting `capabilities.streaming: true` in its Agent Card.
- **Initiating a Stream:** The client uses the `message/stream` RPC method to send an initial message (for example, a prompt or command) and simultaneously subscribe to updates for that task.
- **Initiating a Stream:** The client uses the `SendStreamingMessage` RPC method to send an initial message (for example, a prompt or command) and simultaneously subscribe to updates for that task.
- **Server Response and Connection:** If the subscription is successful, the server responds with an HTTP 200 OK status and a `Content-Type: text/event-stream`. This HTTP connection remains open for the server to push events to the client.
- **Event Structure and Types:** The server sends events over this stream. Each event's `data` field contains a JSON-RPC 2.0 Response object, typically a `SendStreamingMessageResponse`. The `result` field of the `SendStreamingMessageResponse` contains:
- [`Task`](../specification.md#61-task-object): Represents the current state of the work.
- [`TaskStatusUpdateEvent`](../specification.md#722-taskstatusupdateevent-object): Communicates changes in the task's lifecycle state (for example, from `working` to `input-required` or `completed`). It also provides intermediate messages from the agent.
- [`TaskArtifactUpdateEvent`](../specification.md#723-taskartifactupdateevent-object): Delivers new or updated Artifacts generated by the task. This is used to stream large files or data structures in chunks, with fields like `append` and `lastChunk` to help reassemble.
- [`TaskStatusUpdateEvent`](../specification.md#taskstatusupdateevent): Communicates changes in the task's lifecycle state (for example, from `working` to `input-required` or `completed`). It also provides intermediate messages from the agent.
- [`TaskArtifactUpdateEvent`](../specification.md#taskartifactupdateevent): Delivers new or updated Artifacts generated by the task. This is used to stream large files or data structures in chunks, with fields like `append` and `lastChunk` to help reassemble.
- **Stream Termination:** The server signals the end of updates for a cycle by setting `final: true` in a `TaskStatusUpdateEvent`. This typically occurs when the task reaches a terminal state. After this, the server usually closes the SSE connection.
- **Stream Termination:** When a task reaches a terminal or interrupted state (e.g., `COMPLETED`, `FAILED`, `CANCELED`, `REJECTED`, or `INPUT_REQUIRED`), the server closes the stream and sends no further updates.
- **Resubscription:** If a client's SSE connection breaks prematurely while a task is still active, the client is able to attempt to reconnect to the stream using the `tasks/resubscribe` RPC method.
- **Resubscription:** If a client's SSE connection breaks prematurely while a task is still active, the client is able to attempt to reconnect to the stream using the `SubscribeToTask` RPC method.
### When to Use Streaming
@ -37,8 +37,8 @@ Streaming with SSE is best suited for:
Refer to the Protocol Specification for detailed structures:
- [`message/stream`](../specification.md#72-messagestream)
- [`tasks/subscribe`](../specification.md#79-taskssubscribe)
- [`SendStreamingMessage`](../specification.md#72-messagestream)
- [`SubscribeToTask`](../specification.md#79-taskssubscribe)
## Push Notifications for Disconnected Scenarios
@ -47,13 +47,13 @@ For very long-running tasks (for example, lasting minutes, hours, or even days)
The following key features detail how push notifications are implemented and managed within the A2A protocol:
- **Server Capability:** The A2A Server must indicate its support for this feature by setting `capabilities.pushNotifications: true` in its Agent Card.
- **Configuration:** The client provides a [`PushNotificationConfig`](../specification.md#68-pushnotificationconfig-object) to the server. This configuration is supplied:
- Within the initial `message/send` or `message/stream` request, or
- Separately, using the `tasks/pushNotificationConfig/set` RPC method for an existing task.
- **Configuration:** The client provides a [`PushNotificationConfig`](../specification.md#pushnotificationconfig) to the server. This configuration is supplied:
- Within the initial `SendMessage` or `SendStreamingMessage` request, or
- Separately, using the `CreateTaskPushNotificationConfig` RPC method for an existing task.
The `PushNotificationConfig` includes a `url` (the HTTPS webhook URL), an optional `token` (for client-side validation), and optional `authentication` details (for the A2A Server to authenticate to the webhook).
- **Notification Trigger:** The A2A Server decides when to send a push notification, typically when a task reaches a significant state change (for example, terminal state, `input-required`, or `auth-required`).
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#323-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#434-push-notification-payload) for detailed structure.
- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `tasks/get` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#323-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#pushnotificationpayload) for detailed structure.
- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `GetTask` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.
### When to Use Push Notifications
@ -67,8 +67,8 @@ Push notifications are ideal for:
Refer to the Protocol Specification for detailed structures:
- [`tasks/pushNotificationConfig/set`](../specification.md#75-taskspushnotificationconfigset)
- [`tasks/get`](../specification.md#76-taskspushnotificationconfigget)
- [`CreateTaskPushNotificationConfig`](../specification.md#317-create-push-notification-config)
- [`GetTask`](../specification.md#76-taskspushnotificationconfigget)
### Client-Side Push Notification Service
@ -82,7 +82,7 @@ Security is paramount for push notifications due to their asynchronous and serve
- **Webhook URL Validation:** Servers SHOULD NOT blindly trust and send POST requests to any URL provided by a client. Malicious clients could provide URLs pointing to internal services or unrelated third-party systems, leading to Server-Side Request Forgery (SSRF) attacks or acting as Distributed Denial of Service (DDoS) amplifiers.
- **Mitigation strategies:** Allowlisting of trusted domains, ownership verification (for example, challenge-response mechanisms), and network controls (e.g., egress firewalls).
- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme(s) specified in `PushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).
- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme specified in `PushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).
#### Client Webhook Receiver Security (when receiving notifications from A2A server)
@ -95,7 +95,7 @@ Security is paramount for push notifications due to their asynchronous and serve
#### Example Asymmetric Key Flow (JWT + JWKS)
1. Client sets `PushNotificationConfig` specifying `authentication.schemes: ["Bearer"]` and possibly an expected `issuer` or `audience` for the JWT.
1. Client creates a `PushNotificationConfig` specifying `authentication.scheme: "Bearer"` and possibly an expected `issuer` or `audience` for the JWT.
2. A2A Server, when sending a notification:
- Generates a JWT, signing it with its private key. The JWT includes claims like `iss` (issuer), `aud` (audience), `iat` (issued at), `exp` (expires), `jti` (JWT ID), and `taskId`.
- The JWT header indicates the signing algorithm and key ID (`kid`).

View File

@ -1,4 +1,4 @@
# 2. Setup Your Environment
# 2. Set Up Your Environment
## Prerequisites
@ -38,7 +38,7 @@ We recommend using a virtual environment for Python projects. The A2A Python SDK
.venv\Scripts\activate
```
2. **Install needed Python dependencies along with the A2A SDK and its dependencies:**
2. **Install the A2A SDK and its required Python dependencies:**
```bash
pip install -r samples/python/requirements.txt

View File

@ -8,14 +8,15 @@ We'll use the `helloworld` example located in [`a2a-samples/samples/python/agent
An **Agent Skill** describes a specific capability or function the agent can perform. It's a building block that tells clients what kinds of tasks the agent is good for.
Key attributes of an `AgentSkill` (defined in `a2a.types`):
Attributes of an `AgentSkill` (defined in `a2a.types`):
- `id`: A unique identifier for the skill.
- `name`: A human-readable name.
- `description`: A more detailed explanation of what the skill does.
- `tags`: Keywords for categorization and discovery.
- `examples`: Sample prompts or use cases.
- `inputModes` / `outputModes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
- `input_modes` / `output_modes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
- `security_requirements`: Security schemes necessary for this skill.
In `__main__.py`, you can see how a skill for the Helloworld agent is defined:
@ -32,9 +33,9 @@ The **Agent Card** is a JSON document that an A2A Server makes available, typica
Key attributes of an `AgentCard` (defined in `a2a.types`):
- `name`, `description`, `version`: Basic identity information.
- `url`: The endpoint where the A2A service can be reached.
- `capabilities`: Specifies supported A2A features like `streaming` or `pushNotifications`.
- `defaultInputModes` / `defaultOutputModes`: Default Media Types for the agent.
- `supported_interfaces`: Ordered list of endpoints and protocols where the A2A service can be reached.
- `capabilities`: Supported A2A features like `streaming` or `extended_agent_card`.
- `default_input_modes` / `default_output_modes`: Default Media Types for the agent.
- `skills`: A list of `AgentSkill` objects that the agent offers.
The `helloworld` example defines its Agent Card like this:
@ -43,6 +44,4 @@ The `helloworld` example defines its Agent Card like this:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentCard"
```
This card tells us the agent is named "Hello World Agent", runs at `http://localhost:9999/`, supports text interactions, and has the `hello_world` skill. It also indicates public authentication, meaning no specific credentials are required.
Understanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it.
This card tells us the agent is named "Hello World Agent", can be run at `http://127.0.0.1:9999/`, supports text interactions, and has the `hello_world` skill.

View File

@ -22,7 +22,7 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent"
```
It has a simple `invoke` method that returns the string "Hello World".
It has a simple `invoke` method that returns the string "Hello, World!".
2. **The Executor (`HelloWorldAgentExecutor`)**:
This class implements the `AgentExecutor` interface.
@ -41,17 +41,16 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute"
```
When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor):
When a `Send Message` or `Send Streaming Message` request comes in (both are handled by `execute` in this simplified executor), the following steps occur:
1. It calls `self.agent.invoke()` to get the "Hello World" string.
2. It creates an A2A `Message` object using the `new_agent_text_message` utility function.
3. It enqueues this message onto the `event_queue`. The underlying `DefaultRequestHandler` will then process this queue to send the response(s) to the client. For a single message like this, it will result in a single response for `message/send` or a single event for `message/stream` before the stream closes.
**Step 1.** The `A2A instance` (server) retrieves the current task from the context. If there is no task in context, then it creates a new task and adds it to the `EventQueue`.
- **`cancel`**:
The Hello World example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent.
**Step 2.** It enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_WORKING` to indicate the agent has begun processing.
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel"
```
**Step 3.** It calls `self.agent.invoke()` to execute the actual business logic (which simply returns "Hello, World!").
**Step 4.** It enqueues a `TaskArtifactUpdateEvent` containing the result text from the agent.
**Step 5.** Finally, it enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_COMPLETED` to conclude the task.
The `AgentExecutor` acts as the bridge between the A2A protocol (managed by the request handler and server application) and your agent's specific logic. It receives context about the request and uses an event queue to communicate results or updates back.

View File

@ -2,7 +2,9 @@
Now that we have an Agent Card and an Agent Executor, we can set up and start the A2A server.
The A2A Python SDK provides an `A2AStarletteApplication` class that simplifies running an A2A-compliant HTTP server. It uses [Starlette](https://www.starlette.io/) for the web framework and is typically run with an ASGI server like [Uvicorn](https://www.uvicorn.org/).
To set up an A2A server, the Python SDK provides a route factory and helper functions (`create_agent_card_routes`, `create_jsonrpc_routes`, `create_rest_routes`). Use the route factory to create routes for the A2A server's services. These routes can be attached natively to popular frameworks like [Starlette](https://www.starlette.io/) and [FastAPI](https://fastapi.tiangolo.com/), which give you better control over authentication, logging, and other features.
In this tutorial, we will use Starlette with [Uvicorn](https://www.uvicorn.org/).
## Server Setup in Helloworld
@ -16,21 +18,22 @@ Let's break this down:
1. **`DefaultRequestHandler`**:
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`).
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (`HelloWorldAgentExecutor`), a `TaskStore` (`InMemoryTaskStore`), and the public and extended `AgentCard` objects.
- It routes incoming A2A RPC calls to the appropriate methods on your executor (like `execute` or `cancel`).
- The `TaskStore` is used by the `DefaultRequestHandler` to manage the lifecycle of tasks, especially for stateful interactions, streaming, and resubscription. Even if your agent executor is simple, the handler needs a task store.
- `agent_card` is passed to the handler so it can verify the agent's declared capabilities when processing incoming requests. For example, it checks whether streaming or push notifications are supported before handling those request types.
- `extended_agent_card` is passed so the handler can serve it via the `GetExtendedAgentCard` RPC method to authenticated clients.
2. **`A2AStarletteApplication`**:
2. **`create_agent_card_routes` and `create_jsonrpc_routes`**:
- The `A2AStarletteApplication` class is instantiated with the `agent_card` and the `request_handler` (referred to as `http_handler` in its constructor).
- The `agent_card` is crucial because the server will expose it at the `/.well-known/agent-card.json` endpoint (by default).
- The `request_handler` is responsible for processing all incoming A2A method calls by interacting with your `AgentExecutor`.
- `create_agent_card_routes(public_agent_card)` returns Starlette routes that expose the Agent Card at the `/.well-known/agent-card.json` endpoint for public discovery.
- `create_jsonrpc_routes(request_handler, '/')` returns Starlette routes that handle all incoming A2A JSON-RPC method calls by delegating to the `request_handler`.
- These route lists are combined and passed to a standard `Starlette` application.
3. **`uvicorn.run(server_app_builder.build(), ...)`**:
- The `A2AStarletteApplication` has a `build()` method that constructs the actual Starlette application.
- This application is then run using `uvicorn.run()`, making your agent accessible over HTTP.
- `host='0.0.0.0'` makes the server accessible on all network interfaces on your machine.
- `port=9999` specifies the port to listen on. This matches the `url` in the `AgentCard`.
3. **`uvicorn.run(app, ...)`**:
- The constructed `Starlette` app is run using `uvicorn.run()`, making your agent accessible over HTTP.
- `host='127.0.0.1'` makes the server accessible only from your local machine.
- `port=9999` specifies the port to listen on. This matches the endpoints defined in the `AgentCard`'s `supported_interfaces`.
## Running the Helloworld Server
@ -49,7 +52,7 @@ You should see output similar to this, indicating the server is running:
INFO: Started server process [xxxxx]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)
INFO: Uvicorn running on http://127.0.0.1:9999 (Press CTRL+C to quit)
```
Your A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it.

View File

@ -1,18 +1,18 @@
# 6. Interacting with the Server
With the Helloworld A2A server running, let's send some requests to it. The SDK includes a client (`A2AClient`) that simplifies these interactions.
With the Helloworld A2A server running, let's send some requests to it.
## The Helloworld Test Client
The `test_client.py` script demonstrates how to:
1. Fetch the Agent Card from the server.
2. Create an `A2AClient` instance.
3. Send both non-streaming (`message/send`) and streaming (`message/stream`) requests.
2. Create a client using `create_client`.
3. Send both `Send Message` and `Send Streaming Message` requests.
Open a **new terminal window**, activate your virtual environment, and navigate to the `a2a-samples` directory.
Activate virtual environment (Be sure to do this in the same directory where you created the virtual environment):
Activate the virtual environment (be sure to do this in the same directory where you created it):
=== "Mac/Linux"
@ -37,59 +37,201 @@ python samples/python/agents/helloworld/test_client.py
Let's look at key parts of `test_client.py`:
1. **Fetching the Agent Card & Initializing the Client**:
1. **Fetching the Agent Card**:
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver"
```
The `A2ACardResolver` class is a convenience. It first fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL) and then initializes the client with it.
The `A2ACardResolver` class is a convenience. When `get_agent_card()` is called, it fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL), which is then used to initialize the client.
2. **Sending a Non-Streaming Message (`send_message`)**:
2. **Initializing the Client & Sending a Non-Streaming Message**:
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message"
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_send"
```
- The `send_message_payload` constructs the data for `MessageSendParams`.
- This is wrapped in a `SendMessageRequest`.
- It includes a `message` object with the `role` set to "user" and the content in `parts`.
- The Helloworld agent's `execute` method will enqueue a single "Hello World" message. The `DefaultRequestHandler` will retrieve this and send it as the response.
- The `response` will be a `SendMessageResponse` object, which contains either a `SendMessageSuccessResponse` (with the agent's `Message` as the result) or a `JSONRPCErrorResponse`.
- The `create_client` function creates a `Client` based on the information provided by the `AgentCard` and a `ClientConfig`.
- We construct a `Message` using the `new_text_message` helper (passing `role=Role.ROLE_USER`), then wrap it in a `SendMessageRequest`.
- The client's `send_message` method returns an async iterator that yields a single final `Task` or `Message` response from the agent. In this example, it is a `Task`.
3. **Handling Task IDs (Illustrative Note for Helloworld)**:
The Helloworld client (`test_client.py`) doesn't attempt `get_task` or `cancel_task` directly because the simple Helloworld agent's `execute` method, when called via `message/send`, results in the `DefaultRequestHandler` returning a direct `Message` response rather than a `Task` object. More complex agents that explicitly manage tasks (like the LangGraph example) would return a `Task` object from `message/send`, and its `id` could then be used for `get_task` or `cancel_task`.
4. **Sending a Streaming Message (`send_message_streaming`)**:
3. **Initializing the Client & Sending a Streaming Message**:
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming"
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_stream"
```
- This method calls the agent's `message/stream` endpoint. The `DefaultRequestHandler` will invoke the `HelloWorldAgentExecutor.execute` method.
- The `execute` method enqueues one "Hello World" message, and then the event queue is closed.
- The client will receive this single message as one `SendStreamingMessageResponse` event, and then the stream will terminate.
- The `stream_response` is an `AsyncGenerator`.
- A separate streaming client is created via `create_client` with `streaming=True` in its `ClientConfig`.
- We again call `send_message`, which now streams events: each iteration of the loop prints a discrete chunk as it arrives over the network.
- Call `await streaming_client.close()` after the loop to release the underlying HTTP connection.
## Expected Output
When you run `test_client.py`, you'll see JSON outputs for:
When you run `test_client.py`, you'll see output for:
- The non-streaming response (a single "Hello World" message).
- The streaming response (a single "Hello World" message as one chunk, after which the stream ends).
- The public agent card, displayed in a formatted summary.
- The non-streaming response: a single `task` in protobuf text format containing the completed status, the generated artifact with "Hello, World!", and the agent's intermediate status message in history.
- The streaming response: four chunks — the initial `task`, a `status_update` for WORKING, an `artifact_update` with the result, and a final `status_update` for COMPLETED.
- The extended agent card, displayed in a formatted summary (with an additional `super_hello_world` skill).
The `id` fields in the output will vary with each run.
```console { .no-copy }
AgentCard
--- General ---
Name : Hello World Agent
Description : Just a hello world agent
Version : 0.0.1
--- Interfaces ---
[0] http://127.0.0.1:9999 (JSONRPC)
--- Capabilities ---
Streaming : True
Push notifications : False
Extended agent card : True
--- I/O Modes ---
Input : text/plain
Output : text/plain
--- Skills ---
----------------------------------------------------
ID : hello_world
Name : Returns hello world
Description : just returns hello world
Tags : hello world
Example : hi
Example : hello world
--- Non-Streaming Call ---
Non-streaming Client initialized.
Response:
// Non-streaming response
{"jsonrpc":"2.0","id":"xxxxxxxx","result":{"type":"message","role":"agent","parts":[{"type":"text","text":"Hello World"}],"messageId":"yyyyyyyy"}}
// Streaming response (one chunk)
{"jsonrpc":"2.0","id":"zzzzzzzz","result":{"type":"message","role":"agent","parts":[{"type":"text","text":"Hello World"}],"messageId":"wwwwwwww","final":true}}
task {
id: "xxxxxxxx"
context_id: "yyyyyyyy"
status {
state: TASK_STATE_COMPLETED
}
artifacts {
artifact_id: "zzzzzzzz"
name: "result"
parts {
text: "Hello, World!"
}
}
history {
message_id: "vvvvvvvv"
context_id: "yyyyyyyy"
task_id: "xxxxxxxx"
role: ROLE_USER
parts {
text: "Say hello."
}
}
history {
message_id: "wwwwwwww"
role: ROLE_AGENT
parts {
text: "Processing request..."
}
}
}
// Streaming response
task {
id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
status {
state: TASK_STATE_SUBMITTED
}
history {
message_id: "vvvvvvvv"
context_id: "yyyyyyyy-s"
task_id: "xxxxxxxx-s"
role: ROLE_USER
parts {
text: "Say hello."
}
}
}
Response chunk:
status_update {
task_id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
status {
state: TASK_STATE_WORKING
message {
message_id: "zzzzzzzz-s"
role: ROLE_AGENT
parts {
text: "Processing request..."
}
}
}
}
Response chunk:
artifact_update {
task_id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
artifact {
artifact_id: "wwwwwwww-s"
name: "result"
parts {
text: "Hello, World!"
}
}
}
Response chunk:
status_update {
task_id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
status {
state: TASK_STATE_COMPLETED
}
}
AgentCard
--- General ---
Name : Hello World Agent - Extended Edition
Description : The full-featured hello world agent for authenticated users.
Version : 0.0.2
--- Interfaces ---
[0] http://127.0.0.1:9999 (JSONRPC)
--- Capabilities ---
Streaming : True
Push notifications : False
Extended agent card : True
--- I/O Modes ---
Input : text/plain
Output : text/plain
--- Skills ---
----------------------------------------------------
ID : hello_world
Name : Returns hello world
Description : just returns hello world
Tags : hello world
Example : hi
Example : hello world
----------------------------------------------------
ID : super_hello_world
Name : Returns a SUPER Hello World
Description : A more enthusiastic greeting, only for authenticated users.
Tags : hello world, super, extended
Example : super hi
Example : give me a super hello
```
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww` will be different UUIDs/request IDs)_
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww`, and `vvvvvvvv` will be different UUIDs in each run.)_
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure!
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure.
Now you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.
You can now shut down the server by pressing Ctrl+C in the terminal window where `__main__.py` is running.

View File

@ -6,7 +6,7 @@ This example features a "Currency Agent" that uses the Gemini model via LangChai
## Setting up the LangGraph Example
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one.
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key) if you don't already have one.
2. **Environment Variable:**
@ -64,22 +64,22 @@ The `langgraph` example showcases several important A2A concepts:
```
- The `CurrencyAgentExecutor` (in `samples/langgraph/agent_executor.py`), when its `execute` method is called by the `DefaultRequestHandler`, interacts with the `RequestContext` which contains the current task (if any).
- For `message/send`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `message/send` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
- For `Send Message`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `Send Message` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
- The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`.
3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**:
- The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`.
- As the LangGraph agent processes the request (which might involve calling tools like `get_exchange_rate`), the `CurrencyAgentExecutor` enqueues different types of events onto the `EventQueue`:
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates.."). The `final` flag on these events is `False`.
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates...").
- `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`.
- A final `TaskStatusUpdateEvent` with `state=TaskState.completed` and `final=True` is sent to signify the end of the task for streaming.
- A final `TaskStatusUpdateEvent` with `state=TaskState.completed` is sent to signify the end of the task, closing the stream.
- The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server.
4. **Multi-Turn Conversation (`TaskState.input_required`)**:
- The `CurrencyAgent` can ask for clarification if a query is ambiguous (e.g., user asks "how much is 100 USD?").
- When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., "To which currency would you like to convert?"). This event will have `final=True` for the current interaction stream.
- When this happens, the `CurrencyAgentExecutor` will enqueue a `TaskStatusUpdateEvent` where `status.state` is `TaskState.input_required` and `status.message` contains the agent's question (e.g., "To which currency would you like to convert?"). The stream closes after this event.
- The `test_client.py`'s `run_multi_turn_test` function demonstrates this:
- It sends an initial ambiguous query.
- The agent responds (via the `DefaultRequestHandler` processing the enqueued events) with a `Task` whose status is `input_required`.

View File

@ -31,7 +31,7 @@ Here are some ideas and resources to continue your A2A journey:
- **Experiment with Advanced Features:**
- Implement robust task management with a persistent `TaskStore` if your agent handles long-running or multi-session tasks.
- Explore implementing push notifications if your agent's tasks are very long-lived.
- Consider more complex input and output modalities (e.g., handling file uploads/downloads, or structured data via `DataPart`).
- Consider more complex input and output modalities (e.g., handling file uploads/downloads via file Parts, or structured data via data Parts).
- **Contribute to the A2A Community:**
- Join the discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
- Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).

990
docs/whats-new-v1.md Normal file
View File

@ -0,0 +1,990 @@
# What's New in A2A Protocol v1.0
This document provides a comprehensive overview of changes from A2A Protocol v0.3.0 to v1.0. The v1.0 release represents a significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
## Overview of Major Themes
The v1.0 release focuses on four major themes:
### 1. **Protocol Maturity and Standardization**
- Elevate a2a.proto from being a gRPC-specific implementation file to the universal, normative source of truth
- Leverage formal specification standards (RFC 8785, RFC 7515) and google.rpc.Status where possible
- Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings
- Enhanced versioning strategy with explicit backward compatibility rules
- Comprehensive error taxonomy with protocol-specific mappings
### 2. **Enhanced Type Safety and Clarity**
- Removal of discriminator `kind` fields in favor of JSON member-based polymorphism
- **Breaking:** Enum values changed from `kebab-case` to `SCREAMING_SNAKE_CASE` for compliance with the ProtoJSON specification
- Stricter field naming conventions (`camelCase` for JSON)
- More precise timestamp specifications (ISO 8601 with millisecond precision)
- Better-defined data types with clearer Optional vs Required semantics
### 3. **Improved Developer Experience**
- Renamed operations for consistency and clarity
- Reorganized Agent Card structure for better logical grouping
- Enhanced extension mechanism with versioning and requirement declarations
- More explicit service parameter handling (A2A-Version, A2A-Extensions headers)
- **Simplified ID format** - Removed complex compound IDs (e.g., `tasks/{id}`) in favor of simple UUIDs
- **Protocol versioning per interface** - Each AgentInterface specifies its own protocol version for better backward compatibility
- **Multi-tenancy support** - Native tenant scoping in gRPC requests
### 4. **Enterprise-Ready Features**
- Agent Card signature verification using JWS and JSON Canonicalization
- Formal specification of all three protocol bindings with equivalence guarantees
- Enhanced security scheme declarations with mutual TLS support
- **Modern OAuth 2.0 flows** - Added Device Code flow (RFC 8628), removed deprecated implicit/password flows
- **PKCE support** - Added `pkce_required` field to Authorization Code flow for enhanced security
- Cursor-based pagination for scalable task listing
---
## Behavioral Changes for Core Operations
### Send Message (`message/send` → **`SendMessage`**)
**v0.3.0 Behavior:**
- Operation named `message/send`
- Less formal specification of when `Task` vs `Message` is returned
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **`SendMessage`**
- **✅ CLARIFIED:** More precise specification of Task vs Message return semantics
### Send Streaming Message (`message/stream` → **SendStreamingMessage**)
**v0.3.0 Behavior:**
- Operation named `message/stream`
- Stream events had `kind` discriminator field
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **`SendStreamingMessage`**
- **✅ BREAKING:** Stream events no longer have `kind` field
- Use JSON member names to discriminate between `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`
- **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.
- **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events
### Get Task (`tasks/get` → **GetTask**)
**v0.3.0 Behavior:**
- Operation named `tasks/get`
- Returns task with status, artifacts, and optionally history
- Less formal specification of what "include history" means
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **GetTask**
- **✅ NEW:** `createdAt` and `lastModified` timestamp fields added to Task object
- **✅ CLARIFIED:** More precise specification of history inclusion behavior
- **✅ NEW:** Task object now includes `extensions[]` array in messages and artifacts
- **✅ CLARIFIED:** Authentication/authorization scoping - servers MUST only return tasks visible to caller
### List Tasks (`tasks/list` → **ListTasks**)
**v0.3.0 Behavior:**
- Operation unavailable.
**v1.0 Changes:**
- **✅ NEW:** New operation **ListTasks** with filtering capabilities
- **✅ CLARIFIED:** Task visibility scoped to authenticated caller
### Cancel Task (`tasks/cancel` → **CancelTask**)
**v0.3.0 Behavior:**
- Operation named `tasks/cancel`
- Request with taskId, returns Task
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **CancelTask**
- **✅ CLARIFIED:** More precise specification of when cancellation is allowed
- **✅ CLARIFIED:** Task state transitions for cancellation scenarios
### Get Agent Card (Well-known URI and **GetExtendedAgentCard**)
**v0.3.0 Behavior:**
- Discovery via `/.well-known/agent-card.json`
- Extended card via `agent/getAuthenticatedExtendedCard`
- `supportsAuthenticatedExtendedCard` boolean at top level
**v1.0 Changes:**
- **✅ RENAMED:** `agent/getAuthenticatedExtendedCard` → **GetExtendedAgentCard**
- **✅ BREAKING:** `supportsAuthenticatedExtendedCard` moved to `capabilities.extendedAgentCard`
- **✅ NEW:** Canonicalization (RFC 8785) clarified for Agent Card signature
- **✅ BREAKING:** `protocolVersion` moved from AgentCard to individual AgentInterface objects
- **✅ BREAKING:** `preferredTransport` and `additionalInterfaces` consolidated into `supportedInterfaces[]`
- Each interface has `url`, `protocolBinding`, and `protocolVersion`
### Subscribe to task (`tasks/resubscribe` → **SubscribeToTask**)
**v0.3.0 Behavior:**
- Used `tasks/resubscribe` to reconnect interrupted SSE streams
- Backfill behavior implementation-dependent
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **SubscribeToTask**
- **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle
- **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state
- **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task
### Push Notification Operations
**v0.3.0 Operations:**
- `tasks/pushNotificationConfig/set`
- `tasks/pushNotificationConfig/get`
- `tasks/pushNotificationConfig/list`
- `tasks/pushNotificationConfig/delete`
**v1.0 Changes:**
- **✅ RENAMED:** Operations now **CreateTaskPushNotificationConfig**, **GetTaskPushNotificationConfig**, **ListTaskPushNotificationConfigs**, **DeleteTaskPushNotificationConfig**
- **✅ NEW:** `createdAt` timestamp field added to PushNotificationConfig
- **✅ CLARIFIED:** Push notification payloads now use StreamResponse format
- **✅ BREAKING:** model changed for all methods, with TaskPushNotificationConfig flattened
### NEW: Multi-Tenancy Support
**v0.3.0:**
- No native multi-tenancy support in protocol
- Tenants handled implicitly via authentication or URL paths
**v1.0 Changes:**
- **✅ NEW:** `tenant` field added to all request messages
- **✅ NEW:** `tenant` field added to `AgentInterface` to specify default tenant
- **✅ CLARIFIED:** Tenant provided per-request, inherited from AgentInterface
- **✅ USE CASE:** Enables to serve multiple agents from a single endpoint
### Protocol Simplifications
#### ID Format Simplification (#1389)
**v0.3.0:**
- Some operations used complex compound IDs like `tasks/{taskId}`
- Required clients/servers to construct/deconstruct resource names
**v1.0 Changes:**
- **✅ BREAKING:** All IDs are now simple literals
- **✅ BREAKING:** Operations that previously used compound IDs now separate parent and resource ID
- Example: `tasks/{taskId}/pushNotificationConfigs/{configId}` → separate `task_id` and `config_id` fields
- **✅ BENEFIT:** Simpler to implement - IDs map directly to database keys
#### HTTP URL Path Simplification (#1269)
**v0.3.0:**
- HTTP+JSON binding used `/v1/` prefix in URLs
- Example: `POST /v1/message:send`
**v1.0 Changes:**
- **✅ BREAKING:** Removed `/v1` prefix from HTTP+JSON URL paths
- **✅ NEW:** Examples: `POST /message:send`, `GET /tasks/{id}`
- **✅ RATIONALE:** Version can be part of the base url if required by agent owner
- **✅ BENEFIT:** Cleaner URLs, version management at interface level
---
## Structural Changes in Core Model Objects
### TaskStatus Object
**Modified Fields:**
- ✅ `state`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
- v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"canceled"`, `"rejected"`, `"input-required"`, `"auth-required"`
- v1.0: `"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_AUTH_REQUIRED"`
- ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
**Removed Fields:**
- None
**Example Migration:**
```json
// v0.3.0
{
"status": {
"state": "completed",
"timestamp": "2024-03-15T10:15:00Z"
}
}
// v1.0
{
"status": {
"state": "TASK_STATE_COMPLETED",
"timestamp": "2024-03-15T10:15:00.000Z"
}
}
```
### Message Object
**Added Fields:**
- ✅ `extensions[]`: Array of extension URIs applicable to this message
**Modified Fields:**
- ✅ `role`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `ROLE_` prefix
- v0.3.0: `"user"`, `"agent"`
- v1.0: `"ROLE_USER"`, `"ROLE_AGENT"`
**Example Migration:**
```json
// v0.3.0
{
"role": "user",
"parts": [{"kind": "text", "text": "Hello"}]
}
// v1.0
{
"role": "ROLE_USER",
"parts": [{"text": "Hello"}],
}
```
**Behavior Changes:**
- Parts array now uses member-based discrimination instead of `kind` field
### Part Object
**BREAKING CHANGE - Complete Redesign:**
The Part structure has been completely redesigned in v1.0. Instead of separate TextPart, FilePart, and DataPart message types, there is now a single unified `Part` message.
**v0.3.0 Structure (Separate Types):**
```json
// Text example
{
"kind": "text",
"text": "Hello world"
}
// File example
{
"kind": "file",
"file": {
"fileWithUri": "https://example.com/doc.pdf",
"mimeType": "application/pdf"
}
}
// Data example
{
"kind": "data",
"data": {"key": "value"}
}
```
**v1.0 Structure (Unified Part):**
```json
// Text example
{
"text": "Hello world",
"mediaType": "text/plain"
}
// File with URL example
{
"url": "https://example.com/doc.pdf",
"filename": "doc.pdf",
"mediaType": "application/pdf"
}
// File with raw bytes example
{
"raw": "base64encodedcontent==",
"filename": "image.png",
"mediaType": "image/png"
}
// Data example
{
"data": {"key": "value"},
"mediaType": "application/json"
}
```
**Changes:**
- ⛔ **REMOVED:** Separate `TextPart`, `FilePart`, and `DataPart` types
- ⛔ **REMOVED:** `kind` discriminator field
- ⛔ **REMOVED:** Nested `file` object structure
- ✅ **NEW:** Single unified `Part` message with `oneof content` field
- ✅ **NEW:** Content type determined by which field is present: `text`, `raw`, `url`, or `data`
- ✅ **NEW:** `mediaType` field (replaces `mimeType`) - available for all part types
- ✅ **NEW:** `filename` field - available for all part types (not just files)
- ✅ **NEW:** `raw` field for inline binary content (base64 in JSON)
- ✅ **NEW:** `url` field for file references (replaces `file.fileWithUri`)
**Migration Examples:**
```typescript
// v0.3.0
const textPart = { kind: "text", text: "Hello" };
const filePart = { kind: "file", file: { fileWithUri: "https://...", mimeType: "image/png" } };
const dataPart = { kind: "data", data: { key: "value" } };
// v1.0
const textPart = { text: "Hello", mediaType: "text/plain" };
const filePart = { url: "https://...", mediaType: "image/png", filename: "image.png" };
const dataPart = { data: { key: "value" }, mediaType: "application/json" };
// Discrimination changed from kind field to member presence
if (part.kind === "text") { ... } // v0.3.0
if ("text" in part) { ... } // v1.0
```
### Artifact Object
**Added Fields:**
- ✅ `extensions[]`: Array of extension URIs
**Modified Fields:**
- ✅ `parts[]`: Now uses member-based Part discrimination (see Part changes above)
### AgentCard Object
**Added Fields:**
- ✅ `supportedInterfaces[]`: Array of `AgentInterface` objects
**Removed Fields:**
- ⛔ `protocolVersion`: Removed from AgentCard (now in each AgentInterface)
- ⛔ `preferredTransport`: Consolidated into `supportedInterfaces`
- ⛔ `additionalInterfaces`: Consolidated into `supportedInterfaces`
- ⛔ `supportsAuthenticatedExtendedCard`: Moved to `capabilities.extendedAgentCard`
- ⛔ `url`: Primary endpoint now in `supportedInterfaces[0].url`
**Structure Example:**
**v0.3.0:**
```json
{
"protocolVersion": "0.3",
"url": "https://agent.example.com/a2a",
"preferredTransport": "JSONRPC",
"supportsAuthenticatedExtendedCard": true,
"additionalInterfaces": [...]
}
```
**v1.0:**
```json
{
"supportedInterfaces": [
{
"url": "https://agent.example.com/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"capabilities": {
"extendedAgentCard": true
},
"signatures": [...]
}
```
### AgentCapabilities Object
**Modified Fields:**
- ✅ `extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard` field
### PushNotificationConfig Object
**Added Fields:**
- ✅ `configId`: Unique identifier for the configuration
- ✅ `createdAt`: Timestamp - Configuration creation time
**Modified Fields:**
- ✅ `authentication`: Enhanced PushNotificationAuthenticationInfo structure
### Stream Event Objects
**TaskStatusUpdateEvent:**
**v0.3.0:**
```json
{
"kind": "taskStatusUpdate",
"taskId": "...",
"contextId": "...",
"status": {...},
"final": true
}
```
**v1.0:**
```json
{
"taskStatusUpdate": {
"taskId": "...",
"contextId": "...",
"status": {...}
}
}
```
**Changes:**
- ⛔ **REMOVED:** `kind` discriminator
- ⛔ **REMOVED:** `final` boolean field (stream closure indicates completion instead)
- ✅ **NEW PATTERN:** Event type determined by JSON member name (`taskStatusUpdate` or `taskArtifactUpdate`)
- ✅ **CLARIFIED:** Terminal state indicated by protocol-specific stream closure mechanism
**TaskArtifactUpdateEvent:**
**v0.3.0:**
```json
{
"kind": "taskArtifactUpdate",
"taskId": "...",
"contextId": "...",
"artifact": {...}
}
```
**v1.0:**
```json
{
"taskArtifactUpdate": {
"taskId": "...",
"contextId": "...",
"artifact": {...},
"index": 0
}
}
```
**Changes:**
- ⛔ **REMOVED:** `kind` discriminator
- ✅ **NEW PATTERN:** Wrapped in `taskArtifactUpdate` object
- ✅ **NEW:** `index` field indicates artifact position in task's artifacts array
### OAuth 2.0 Security Updates (#1303)
v1.0 modernizes OAuth 2.0 support in alignment with OAuth 2.0 Security Best Current Practice (BCP).
**Removed Flows (Deprecated by OAuth BCP):**
- ⛔ `ImplicitOAuthFlow` - Deprecated due to token leakage risks in browser history/logs
- ⛔ `PasswordOAuthFlow` - Deprecated due to credential exposure risks
**Added Flows:**
- ✅ `DeviceCodeOAuthFlow` (RFC 8628) - For CLI tools, IoT devices, and input-constrained scenarios
- Provides `device_authorization_url` endpoint
- Supports `verification_uri`, `user_code` pattern
- Ideal for headless environments
**Enhanced Security:**
- ✅ `pkce_required` field added to `AuthorizationCodeOAuthFlow` (RFC 7636)
- Indicates whether PKCE (Proof Key for Code Exchange) is mandatory
- Protects against authorization code interception attacks
- Recommended for all OAuth clients, required for public clients
**Migration Guide:**
```typescript
// v0.3.0 - Implicit Flow (now removed)
{
"implicitFlow": {
"authorizationUrl": "https://auth.example.com/authorize",
"scopes": {"read": "Read access"}
}
}
// v1.0 - Use Authorization Code + PKCE instead
{
"authorizationCodeFlow": {
"authorizationUrl": "https://auth.example.com/authorize",
"tokenUrl": "https://auth.example.com/token",
"pkceRequired": true,
"scopes": {"read": "Read access"}
}
}
```
---
## New Dependencies on Other Specifications
v1.0 introduces several new formal dependencies on industry-standard specifications:
### Added Specifications
#### ✅ google.rpc.Status / google.rpc.ErrorInfo
- **Purpose:** Standardized error response model with ProtoJSON representation
- **Usage:** Error responses for HTTP+JSON and JSON-RPC bindings
- **Impact:** Replaces RFC 9457 for HTTP errors. Enforces structured `ErrorInfo` with `reason` and `domain` for A2A-specific errors.
#### ✅ RFC 8785 - JSON Canonicalization Scheme (JCS)
- **Purpose:** Deterministic JSON serialization for signing
- **Usage:** Agent Card signature verification
- **Impact:** Enables cryptographic verification of Agent Card integrity
- **Details:** Canonical form used before JWS signing (excludes `signatures` field)
#### ✅ RFC 7515 - JSON Web Signature (JWS)
- **Purpose:** Cryptographic signing standard
- **Usage:** Agent Card signatures field
- **Impact:** Industry-standard signature format for trust verification
- **Details:** Supports detached signatures with public key retrieval via `jku` or trusted keystores
#### ✅ Google API Design Guidelines
- **Purpose:** gRPC best practices and conventions
- **Usage:** gRPC binding design patterns
- **Impact:** Better alignment with gRPC ecosystem expectations
#### ✅ ISO 8601
- **Purpose:** Timestamp format standard
- **Usage:** All timestamp fields (createdAt, lastModified, timestamp)
- **Impact:** Explicit format requirement: UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
### Existing Dependencies (Retained from v0.3.0)
- JSON-RPC 2.0
- gRPC / Protocol Buffers 3
- HTTP/HTTPS (various RFCs)
- Server-Sent Events (SSE) - W3C specification
- RFC 8615 - Well-known URIs
- OAuth 2.0, OpenID Connect (for authentication)
- TLS (RFC 8446 recommended)
### Complementary Protocol
**Model Context Protocol (MCP):**
- Relationship clarified: MCP handles tool/resource integration, A2A handles agent-to-agent coordination
- Protocols are complementary, not competing
- Agents may support both protocols for different use cases
---
## Impact on Developers
### Breaking Changes Requiring Code Updates
#### 1. Part Type Unification (CRITICAL IMPACT)
The most significant breaking change: TextPart, FilePart, and DataPart types have been removed and replaced with a single unified Part structure.
**Before (v0.3.0):**
```typescript
// Separate types with kind discriminator
if (part.kind === "text") {
return part.text;
} else if (part.kind === "file") {
if (part.file.fileWithUri) {
return fetchFile(part.file.fileWithUri);
} else {
return part.file.fileWithBytes;
}
} else if (part.kind === "data") {
return part.data;
}
```
**After (v1.0):**
```typescript
// Unified Part with oneof content
if ("text" in part) {
return part.text;
} else if ("url" in part) {
return fetchFile(part.url);
} else if ("raw" in part) {
return decodeBase64(part.raw);
} else if ("data" in part) {
return part.data;
}
```
#### 2. Stream Event Discriminator Pattern (HIGH IMPACT)
Stream events changed from kind-based to wrapper-based discrimination:
**Before (v0.3.0):**
```typescript
if (event.kind === "taskStatusUpdate") {
handleStatusUpdate(event);
} else if (event.kind === "taskArtifactUpdate") {
handleArtifactUpdate(event);
}
```
**After (v1.0):**
```typescript
if ("taskStatusUpdate" in event) {
handleStatusUpdate(event.taskStatusUpdate);
} else if ("taskArtifactUpdate" in event) {
handleArtifactUpdate(event.taskArtifactUpdate);
}
```
#### 3. Agent Card Structure (HIGH IMPACT)
Agent discovery and capability checking requires updates:
**Before (v0.3.0):**
```typescript
const endpoint = agentCard.url;
const transport = agentCard.preferredTransport;
const supportsExtended = agentCard.supportsAuthenticatedExtendedCard;
```
**After (v1.0):**
```typescript
const primaryInterface = agentCard.supportedInterfaces[0];
const endpoint = primaryInterface.url;
const transport = primaryInterface.protocolBinding;
const supportsExtended = agentCard.capabilities.extendedAgentCard;
```
#### 4. Pagination (MEDIUM IMPACT)
List Tasks implementation must switch from page-based to cursor-based:
**Before (v0.3.0):**
```typescript
const response = await listTasks({ page: 1, perPage: 50 });
```
**After (v1.0):**
```typescript
let cursor = undefined;
do {
const response = await listTasks({ cursor, limit: 50 });
// process response.tasks
cursor = response.nextCursor;
} while (cursor);
```
#### 5. Enum Value Changes (HIGH IMPACT)
All enum values now use SCREAMING_SNAKE_CASE with type prefixes:
**TaskState:**
```typescript
// v0.3.0
if (task.status.state === "completed") { ... }
if (task.status.state === "input-required") { ... }
// v1.0
if (task.status.state === "TASK_STATE_COMPLETED") { ... }
if (task.status.state === "TASK_STATE_INPUT_REQUIRED") { ... }
```
**MessageRole:**
```typescript
// v0.3.0
const message = { role: "user", parts: [...] };
// v1.0
const message = { role: "ROLE_USER", parts: [...] };
```
**Complete Mapping:**
- `"submitted"` → `"TASK_STATE_SUBMITTED"`
- `"working"` → `"TASK_STATE_WORKING"`
- `"completed"` → `"TASK_STATE_COMPLETED"`
- `"failed"` → `"TASK_STATE_FAILED"`
- `"canceled"` → `"TASK_STATE_CANCELED"`
- `"rejected"` → `"TASK_STATE_REJECTED"`
- `"input-required"` → `"TASK_STATE_INPUT_REQUIRED"`
- `"auth-required"` → `"TASK_STATE_AUTH_REQUIRED"`
- `"user"` → `"ROLE_USER"`
- `"agent"` → `"ROLE_AGENT"`
#### 6. Field Name Changes (LOW IMPACT)
- `file.mimeType` → `mediaType`
- Operation names (aliases provided during transition)
#### 7. Standardized Error Handling via google.rpc.Status (HIGH IMPACT)
HTTP+JSON error responses have been updated to use the ProtoJSON representation of `google.rpc.Status` instead of RFC 9457 (Problem Details). JSON-RPC and HTTP+JSON bindings now use `google.rpc.ErrorInfo` within the `data` / `details` array to provide A2A-specific error context.
**Changes:**
- **HTTP+JSON Content-Type:** Changed from `application/problem+json` to `application/json`.
- **Error Model:** Uses `google.rpc.Status` fields (`code`, `message`, `details`).
- **A2A Error Info:** MUST include a `google.rpc.ErrorInfo` object in `details` with `reason` (UPPER_SNAKE_CASE from A2A error types) and `domain: "a2a-protocol.org"`.
**JSON-RPC Example Migration:**
```json
// v0.3.0
"error": {
"code": -32001,
"message": "Task not found",
"data": { "taskId": "123" }
}
// v1.0
"error": {
"code": -32001,
"message": "Task not found",
"data": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org",
"metadata": { "taskId": "123" }
}
]
}
```
**HTTP+JSON Example Migration:**
```http
// v0.3.0 (Draft using RFC 9457)
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
"type": "https://a2a-protocol.org/errors/task-not-found",
"title": "Task Not Found",
"status": 404,
"detail": "The specified task ID does not exist"
}
// v1.0
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error": {
"code": 404,
"status": "NOT_FOUND",
"message": "The specified task ID does not exist",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org"
}
]
}
}
```
### New Capabilities to Leverage
#### 1. Execution Mode Control
```typescript
// Wait for task completion (Default)
const result = await sendMessage(message, { returnImmediately: false });
// Return immediately, poll later
const task = await sendMessage(message, { returnImmediately: true });
```
#### 2. Agent Card Signature Verification
```typescript
if (agentCard.signatures && agentCard.signatures.length > 0) {
const verified = await verifyAgentCardSignature(agentCard);
if (!verified) {
throw new Error("Agent Card signature verification failed");
}
}
```
#### 3. Extension Requirements
```typescript
const requiredExtensions = agentCard.extensions
.filter(ext => ext.required)
.map(ext => ext.uri);
// Check if client supports required extensions
if (!clientSupportsAll(requiredExtensions)) {
throw new Error("Missing required extension support");
}
```
#### 4. Enhanced Timestamp Tracking
```typescript
const taskAge = Date.now() - new Date(task.createdAt).getTime();
const timeSinceUpdate = Date.now() - new Date(task.lastModified).getTime();
```
#### 5. Versioning Negotiation
```typescript
// Client sends A2A-Version header
headers["A2A-Version"] = "1.0";
// Server validates and rejects if unsupported
if (!supportedVersions.includes(requestedVersion)) {
throw new VersionNotSupportedError();
}
```
### Migration Strategy Recommendations
#### Phase 1: Compatibility Layer
1. Add support for parsing both old and new discriminator patterns
2. Implement version detection based on protocol version
3. Support both Agent Card structures during transition
#### Phase 2: Dual Support
1. Update all APIs to emit v1.0 format
2. Maintain backward compatibility readers for v0.3.0
3. Add A2A-Version header handling
4. Implement cursor-based pagination alongside legacy page-based
#### Phase 3: v1.0 Only
1. Deprecate v0.3.0 compatibility code
2. Remove legacy discriminator parsing
3. Remove page-based pagination
4. Clean up dual-format support code
#### Backward Compatibility Strategy (#1401)
v1.0 introduces a formal approach to protocol versioning that enables SDK backward compatibility.
**Protocol Version Per Interface:**
- Each `AgentInterface` now specifies its own `protocolVersion` field
- Agents can support multiple protocol versions simultaneously by exposing multiple interfaces
- Clients negotiate version by selecting appropriate interface from Agent Card
**SDK Implementation Pattern:**
```typescript
// SDK can support multiple protocol versions
class A2AClient {
async connect(agentCardUrl: string) {
const card = await this.getAgentCard(agentCardUrl);
// Find best matching interface
const interface = card.supportedInterfaces.find(i =>
this.supportedVersions.includes(i.protocolVersion)
);
if (!interface) {
throw new Error("No compatible protocol version");
}
// Use version-specific adapter
return this.createAdapter(interface.protocolVersion, interface);
}
}
```
**Benefits:**
- SDKs can maintain support for multiple protocol versions
- Agents can gradually migrate by supporting both old and new versions
- Clients automatically select best compatible version
- Enables graceful deprecation of old protocol versions
### Testing Considerations
- Test with both v0.3.0 and v1.0 formatted data
- Validate Agent Card signature verification
- Test cursor-based pagination edge cases (empty results, single page, etc.)
- Verify proper handling of new error types
- Test extension requirement validation
### Recommended Priority
#### Critical (Do Immediately)
- Update Part and streaming event parsing (discriminator pattern)
- Update Agent Card parsing (structure changes)
- Add A2A-Version header to all requests
#### High (Within 1 Month)
- Implement cursor-based pagination
- Update enum value handling (state field)
- Add return_immediately parameter support
#### Medium (Within 3 Months)
- Implement Agent Card signature verification
- Add extension requirement checking
- Update timestamp handling to ISO 8601 format
- Implement new error types
#### Low (Nice to Have)
- Add createdAt/lastModified timestamp tracking
- Leverage enhanced metadata capabilities
- Implement mutual TLS authentication support
---
## Conclusion
A2A Protocol v1.0 represents a significant step forward in protocol maturity while maintaining the core architectural principles of v0.3.0. The changes focus on standardization, type safety, and enterprise readiness, requiring developers to update their implementations but providing clearer specifications and better developer experience in return.
The breaking changes, while requiring code updates, are straightforward to implement and improve code clarity. The new capabilities around versioning, signatures, and enhanced extensions provide a solid foundation for future protocol evolution within the v1.x line.
Developers should plan for a phased migration approach, prioritizing the critical breaking changes while gradually adopting new capabilities over time.

View File

@ -1,12 +1,11 @@
exclude = [
'https://fonts.gstatic.com/',
'https://fonts.googleapis.com/',
'http://go/github',
'http://go/github-googlecloudplatform',
'https://medium.com/',
'https://x.com/',
'http://localhost:12000/',
'http://localhost:10020/',
'https://goo.gle/',
]
exclude_path = [
".github/actions/spelling",
@ -14,7 +13,7 @@ exclude_path = [
"docs/partners.md",
"docs/robots.txt",
"docs/llms.txt",
"docs/spec-json.md",
"docs/spec/a2a.json",
"docs/spec-proto.md",
"docs/sdk/python.md",
]

View File

@ -20,6 +20,7 @@ extra:
# Navigation
nav:
- Home: index.md
- 🆕 Announcing Version 1.0: announcing-1.0.md
- Documentation:
- What is A2A?: topics/what-is-a2a.md
- Core Concepts: topics/key-concepts.md
@ -27,6 +28,8 @@ nav:
- Enterprise Features: topics/enterprise-ready.md
- Life of a Task: topics/life-of-a-task.md
- Extensions: topics/extensions.md
- Custom Protocol Bindings: topics/custom-protocol-bindings.md
- Extension & Binding Governance: topics/extension-and-binding-governance.md
- Streaming & Asynchronous Operations: topics/streaming-and-async.md
- A2A and MCP: topics/a2a-and-mcp.md
- Tutorials and Samples:
@ -40,12 +43,14 @@ nav:
- Interact with Server: tutorials/python/6-interact-with-server.md
- Streaming & Multiturn: tutorials/python/7-streaming-and-multiturn.md
- Next Steps: tutorials/python/8-next-steps.md
- DeepLearning.AI Course: https://goo.gle/dlai-a2a
- Specification:
- Overview: specification.md
- What's New in v1.0: whats-new-v1.md
- Protocol Definition: definitions.md
- SDK Reference:
- sdk/index.md
- Python: sdk/python.md
- Python: sdk/python/api/index.html
- Community: community.md
- Partners: partners.md
- Roadmap: roadmap.md
@ -55,7 +60,7 @@ repo_name: a2aproject/A2A
repo_url: https://github.com/a2aproject/A2A
# Copyright
copyright: Copyright 2025 The Linux Foundation. Licensed under the Apache License, Version 2.0.
copyright: Copyright 2026 The Linux Foundation. Licensed under the Apache License, Version 2.0.
# Custom CSS
extra_css:
@ -174,6 +179,5 @@ plugins:
"tutorials/python/8-agent-capabilities.md": "tutorials/python/7-streaming-and-multiturn.md"
"tutorials/python/9-ollama-agent.md": "tutorials/python/7-streaming-and-multiturn.md"
"tutorials/python/10-next-steps.md": "tutorials/python/8-next-steps.md"
"sdk/python/": "sdk/python/api/index.html"
- mike:
canonical_version: latest

View File

@ -6,3 +6,5 @@ mkdocs-macros-plugin
sphinx
furo
myst-parser
proto-schema-parser
tabulate

View File

@ -7,7 +7,7 @@ set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SCHEMA_JSON="$ROOT_DIR/specification/json/a2a.json"
PROTO_SRC="$ROOT_DIR/specification/grpc/a2a.proto"
PROTO_SRC="$ROOT_DIR/specification/a2a.proto"
SPEC_SITE_DIR="$ROOT_DIR/docs/spec"
SCHEMA_JSON_SITE_FILE="$SPEC_SITE_DIR/a2a.json"
PROTO_SITE_FILE="$SPEC_SITE_DIR/a2a.proto"
@ -68,6 +68,17 @@ else
echo "[build_docs] SDK docs script not found or not executable: $SDK_DOCS_SCRIPT" >&2
fi
echo "[build_docs] Building MkDocs site..." >&2
mkdocs build "$@"
# Add venv bin to PATH to ensure mike finds mkdocs and plugins
if [ -d "$ROOT_DIR/.doc-venv/bin" ]; then
export PATH="$ROOT_DIR/.doc-venv/bin:$PATH"
fi
if [ "${1:-}" = "deploy" ]; then
shift
echo "[build_docs] Deploying with mike..." >&2
mike deploy "$@"
else
echo "[build_docs] Building MkDocs site..." >&2
mkdocs build "$@"
fi
echo "[build_docs] Done." >&2

View File

@ -8,23 +8,51 @@ set -e
OUTPUT_FILE="docs/llms-full.txt"
DOCS_DIR="docs"
SPEC_DIR="specification"
SDK_DOCS_SCRIPT="scripts/build_sdk_docs.sh"
PROJECT_NAME="A2A (Agent2Agent) Protocol"
echo "--- Generating consolidated LLM file: ${OUTPUT_FILE} ---"
# Clear the output file to start fresh
true >"${OUTPUT_FILE}"
# --- Generate Python SDK Text Documentation ---
if [ -f "$SDK_DOCS_SCRIPT" ]; then
echo "Generating Python SDK documentation..."
bash "$SDK_DOCS_SCRIPT"
else
echo "Warning: SDK docs script not found at $SDK_DOCS_SCRIPT"
fi
# --- Helper function to append file content with a header ---
# Clear the output file and add introduction
cat <<EOF >"${OUTPUT_FILE}"
# ${PROJECT_NAME} - Full Documentation
This file is a consolidated version of all documentation, specifications, and API references
for the ${PROJECT_NAME} project, optimized for LLM consumption.
EOF
# Include llms.txt as the core summary if it exists
if [ -f "${DOCS_DIR}/llms.txt" ]; then
echo "Including summary from ${DOCS_DIR}/llms.txt"
{
echo "## Project Summary"
echo
cat "${DOCS_DIR}/llms.txt"
echo
echo "---"
echo
} >>"${OUTPUT_FILE}"
fi
# --- Helper function to append file content with XML-style tags ---
append_file() {
local file_path="$1"
local display_path="${2:-$file_path}"
if [ -f "$file_path" ]; then
echo "Appending: $file_path"
{
echo "--- START OF FILE ${file_path} ---"
echo
echo "<file path=\"${display_path}\">"
cat "$file_path"
echo
echo "================================================="
echo "</file>"
echo
} >>"${OUTPUT_FILE}"
else
@ -32,15 +60,59 @@ append_file() {
fi
}
# --- Process Documentation Files ---
# Find all markdown and rst files in the docs directory, sort them for consistent output,
# and append each one.
find "${DOCS_DIR}" -type f \( -name "*.md" -o -name "*.rst" \) | sort | while read -r doc_file; do
append_file "$doc_file"
# --- Build File List ---
echo "## File Index" >>"${OUTPUT_FILE}"
echo >>"${OUTPUT_FILE}"
# Collect all files we intend to include
FILES_TO_INCLUDE=()
FILES_TO_INCLUDE+=("README.md")
# Doc files
while IFS= read -r doc_file; do
FILES_TO_INCLUDE+=("$doc_file")
done < <(find "${DOCS_DIR}" -type f \( -name "*.md" -o -name "*.rst" \) \
-not -path "docs/sdk/python/*" \
-not -path "docs/README.md" \
-not -path "docs/sdk/python.md" \
-not -path "docs/llms-full.txt" | sort)
# SDK text files
SDK_TEXT_DIR="docs/sdk/python/_build/text"
if [ -d "$SDK_TEXT_DIR" ]; then
while IFS= read -r sdk_file; do
FILES_TO_INCLUDE+=("$sdk_file")
done < <(find "$SDK_TEXT_DIR" -type f -name "*.txt" | sort)
fi
# Specification
if [ -f "${SPEC_DIR}/a2a.proto" ]; then
FILES_TO_INCLUDE+=("${SPEC_DIR}/a2a.proto")
fi
# Write the index to the output file
for f in "${FILES_TO_INCLUDE[@]}"; do
display_name="$f"
# Clean up display name for SDK files
if [[ "$f" == "$SDK_TEXT_DIR"* ]]; then
display_name="sdk/python/${f#"$SDK_TEXT_DIR"/}"
fi
echo "- ${display_name}" >>"${OUTPUT_FILE}"
done
# --- Process Specification Files ---
append_file "${SPEC_DIR}/grpc/a2a.proto"
append_file "${SPEC_DIR}/json/a2a.json"
{
echo
echo "---"
echo
} >>"${OUTPUT_FILE}"
# --- Append file contents ---
for f in "${FILES_TO_INCLUDE[@]}"; do
display_name="$f"
if [[ "$f" == "$SDK_TEXT_DIR"* ]]; then
display_name="sdk/python/${f#"$SDK_TEXT_DIR"/}"
fi
append_file "$f" "$display_name"
done
echo "✅ Consolidated LLM file generated successfully at ${OUTPUT_FILE}"

View File

@ -14,17 +14,16 @@ echo "--- Setting up documentation build environment ---"
if [ -d "$VENV_DIR" ]; then
rm -rf "$VENV_DIR"
fi
python3 -m venv "$VENV_DIR"
uv venv "$VENV_DIR"
source "$VENV_DIR/bin/activate"
echo "--- Installing package and dependencies ---"
# Upgrade pip and install documentation requirements
pip install -U pip
pip install -r "requirements-docs.txt"
# Install documentation requirements
uv pip install -r "requirements-docs.txt"
# Install the package itself
pip install "${PYPI_PACKAGE_NAME}"
uv pip install "${PYPI_PACKAGE_NAME}"
echo "--- Finding installed package path ---"
@ -44,6 +43,11 @@ echo "--- Building HTML documentation ---"
# Build the HTML documentation
sphinx-build -b html "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/html"
echo "--- Building Text documentation ---"
# Build the Text documentation
sphinx-build -b text "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/text"
echo "--- Copying SDK docs to MkDocs integration path ---"
# Copy SDK docs to where MkDocs expects them (docs/sdk/python/api/)

25
scripts/lint.sh Executable file
View File

@ -0,0 +1,25 @@
#!/bin/bash
# Exit on error (-e), undefined variable usage (-u), or failed pipe command (-o pipefail).
set -euo pipefail
# Determine the repository root directory based on the script's location.
SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
REPO_ROOT=$(cd -- "${SCRIPT_DIR}/.." &>/dev/null && pwd)
# Absolute path to the Super Linter configuration file.
SUPER_LINTER_ENV="${REPO_ROOT}/.github/super-linter.env"
# Detect the default branch from the remote repository.
DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
# Run Super Linter locally using Docker.
# This mirrors the configuration used in GitHub Actions to provide consistent linting behavior.
docker run \
--rm -t \
--platform linux/x86_64 \
-v "${REPO_ROOT}":/tmp/lint \
-e SHELL=/bin/bash \
-e DEFAULT_BRANCH="${DEFAULT_BRANCH}" \
-e RUN_LOCAL=true \
-e LOG_LEVEL=INFO \
--env-file "${SUPER_LINTER_ENV}" \
ghcr.io/super-linter/super-linter:slim-v8

View File

@ -10,7 +10,7 @@ if [[ -z "$OUTPUT" ]]; then
fi
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PROTO_DIR="$ROOT_DIR/specification/grpc"
PROTO_DIR="$ROOT_DIR/specification"
PROTO_FILE="$PROTO_DIR/a2a.proto"
GOOGLEAPIS_DIR="${GOOGLEAPIS_DIR:-}"
@ -26,6 +26,19 @@ check_command "protoc"
check_command "protoc-gen-jsonschema"
check_command "jq"
# Verify protoc-gen-jsonschema is the correct implementation (bufbuild/protoschema-plugins)
# The bufbuild implementation outputs a version string starting with "v" (e.g., "v0.5.2")
# Other implementations (like chrusty/protoc-gen-jsonschema) typically output "protoc-gen-jsonschema version X.Y.Z"
PLUGIN_VERSION=$(protoc-gen-jsonschema --version 2>&1 || true)
if [[ ! "$PLUGIN_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "Error: Incorrect protoc-gen-jsonschema plugin detected." >&2
echo "Current version output: '$PLUGIN_VERSION'" >&2
echo "This script requires the plugin from github.com/bufbuild/protoschema-plugins" >&2
echo "Please install it with:" >&2
echo " go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest" >&2
exit 1
fi
# Create temporary directory for intermediate files
TEMP_DIR=$(mktemp -d)
trap 'rm -rf "$TEMP_DIR"' EXIT
@ -61,12 +74,10 @@ echo "→ Cleaning proto comments..." >&2
# Define path for the cleaned proto in the temp directory
CLEAN_PROTO_FILE="$TEMP_DIR/$(basename "$PROTO_FILE")"
# Use sed to remove lines containing specific patterns:
# Use grep to remove lines containing specific patterns:
# 1. matches "// --8<--"
# 2. matches "// protolint:"
sed -e '/\/\/ --8<--/d' \
-e '/\/\/ protolint:/d' \
"$PROTO_FILE" >"$CLEAN_PROTO_FILE"
grep -v -e "// --8<--" -e "// protolint:" "$PROTO_FILE" >"$CLEAN_PROTO_FILE"
# Add the temp dir to the include path so protoc finds the clean file context
# We prepend it so it takes precedence over the original file

View File

@ -0,0 +1,58 @@
# API Linter Configuration
# https://linter.aip.dev/
- included_paths:
- "**/*.proto"
disabled_rules:
- "core::0140::abbreviations"
- "core::0191::java-multiple-files"
- "core::0191::java-outer-classname"
- "core::0191::java-package"
- "core::0191::proto-package"
- "core::0123::resource-annotation"
- "core::0203::optional"
- "core::0203::required"
- "core::0127::http-annotation"
- "core::0131::request-message-name"
- "core::0132::response-message-name"
- "core::0158::request-required-fields"
- "core::0203::input-only"
- "core::0203::output-only"
- "core::0203::immutable"
# TODO: Evaluate if the following should be enabled due to breaking changes
- "core::0131::method-signature"
- "core::0131::http-uri-name"
- "core::0127::resource-name-extraction"
- "core::0131::request-name-required"
- "core::0131::request-required-fields"
- "core::0131::response-message-name"
- "core::0131::request-unknown-fields"
- "core::0132::request-required-fields"
- "core::0132::request-unknown-fields"
- "core::0132::request-parent-required"
- "core::0132::response-unknown-fields"
- "core::0133::http-body"
- "core::0133::request-required-fields"
- "core::0133::request-unknown-fields"
- "core::0133::request-parent-required"
- "core::0133::request-resource-field"
- "core::0133::request-id-field"
- "core::0133::http-uri-parent"
- "core::0135::http-uri-name"
- "core::0135::request-name-required"
- "core::0135::method-signature"
- "core::0135::request-unknown-fields"
- "core::0135::request-required-fields"
- "core::0136::http-uri-suffix"
- "core::0136::prepositions"
- "core::0136::request-message-name"
- "core::0136::response-message-name"
- "core::0140::uri"
- "core::0140::base64"
- "core::0140::prepositions"
- "core::0142::time-field-names"
- "core::0191::file-layout"
- "core::0203::field-behavior-required"
- "core::0216::state-field-output-only"
- "core::0216::nesting"

File diff suppressed because it is too large Load Diff

6
specification/buf.lock Normal file
View File

@ -0,0 +1,6 @@
# Generated by buf. DO NOT EDIT.
version: v2
deps:
- name: buf.build/googleapis/googleapis
commit: 004180b77378443887d3b55cabc00384
digest: b5:e8f475fe3330f31f5fd86ac689093bcd274e19611a09db91f41d637cb9197881ce89882b94d13a58738e53c91c6e4bae7dc1feba85f590164c975a89e25115dc

View File

@ -7,6 +7,7 @@ lint:
# Indicates that all the default rules should be used.
# See https://buf.build/docs/lint/rules for more details.
- STANDARD
- COMMENTS
except:
- PACKAGE_DIRECTORY_MATCH
- RPC_REQUEST_RESPONSE_UNIQUE

View File

@ -1,69 +0,0 @@
# Protocol Buffer Definitions
This folder contains the A2A specification in Protocol Buffer (protobuf) format
## Prerequisites
Before you can validate or generate code from these protobuf definitions, you need to install `buf`.
Follow the installation instructions on the official `buf` GitHub repository:
<https://github.com/bufbuild/buf/>
## Validation
To validate your protobuf definitions and ensure they adhere to linting rules, run the following command from the root of this folder:
```sh
buf lint
```
## Code Generation
`buf.gen.yaml` is configured to generate code for the following languages:
- Go
- Java
- Python
- TypeScript
To generate code for all configured languages, run the following command from the root of this folder:
```sh
buf generate
```
`buf.gen.yaml` uses remote plugins for generation, if you wish to use local plugins change remote to local
```yaml
plugins:
- local: protoc-gen-java
out: src/java
- local: protoc-gen-grpc-java
out: src/java
```
Alternatively use `protoc` commandline for code generation
```bash
protoc --java_out=./src/java --grpc-java_out=./src/java -I. a2a.proto
```
### Generating for Specific Languages
If you do not need to generate code for all the languages listed above, you can comment out the unwanted language sections in your `buf.gen.yaml` file.
For example, if you only want to generate Java exclude the rest, your `buf.gen.yaml` might look something like this (ensure you adapt this to your actual `buf.gen.yaml` structure):
```yaml
# buf.gen.yaml
version: v2
plugins:
# - plugin: buf.build/protocolbuffers/go
# out: src/go
# - plugin: buf.build/protocolbuffers/python
# out: src/python
- plugin: buf.build/protocolbuffers/java
out: src/java
# - plugin: buf.build/grpc/typescript
# out: src/ts
```

View File

@ -1,6 +0,0 @@
# Generated by buf. DO NOT EDIT.
version: v2
deps:
- name: buf.build/googleapis/googleapis
commit: 61b203b9a9164be9a834f58c37be6f62
digest: b5:7811a98b35bd2e4ae5c3ac73c8b3d9ae429f3a790da15de188dc98fc2b77d6bb10e45711f14903af9553fa9821dff256054f2e4b7795789265bc476bec2f088c

View File

@ -1,18 +1,17 @@
# A2A JSON Artifact
`a2a.json` is a **non-normative build artifact** derived from the canonical proto definition at `specification/grpc/a2a.proto`. It is generated during builds and intentionally **not** committed to source control.
`a2a.json` is a **non-normative build artifact** derived from the canonical proto definition at `specification/a2a.proto`. It is generated during builds and intentionally **not** committed to source control.
Generation pipeline:
1. `scripts/proto_to_json_schema.sh` converts proto directly to JSON Schema using bufbuild's `protoc-gen-jsonschema` plugin.
2. The resulting `a2a.json` (JSON Schema 2020-12 bundle) is copied to `docs/spec-json/a2a.json` for site publishing.
2. The resulting `a2a.json` (JSON Schema 2020-12 bundle) is copied to `docs/spec/a2a.json` for site publishing.
The build uses `protoc` with `protoc-gen-jsonschema` plugin and `jq` for bundling. Only source (`a2a.proto`) and scripts remain under version control.
The artifact is generated automatically in:
- Local docs builds (`scripts/build_docs.sh`)
- CI workflow (`.github/workflows/generate-a2a-json.yml`) on proto changes
## Do Not Edit