## 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>
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>
## 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>
## 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>
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.
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>
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>
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>
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>
Hi,
Giving a second read to the repo, I found these additional typos: see
commit diffs.
Didier
---------
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>
Removes usage of deprecated 'kind' discriminators from the Life of a
Task documentation to align with v1.0 specification changes.
Changes:
- Removed 'kind' field from Part objects (4 occurrences) - deprecated in
v1.0 per spec section A.2.1
- Removed invalid 'kind' field from Task objects (2 occurrences) - never
part of Task specification
- Updated Part field names: mimeType → mediaType, bytes → fileWithBytes
The specification (section A.2.1) states that v1.0 removed the 'kind'
discriminator for Part types and streaming events, using JSON member
names as discriminators instead. Task objects never had a 'kind' field
in the proto definition.
Fixes#1220
Fixes inconsistency between topics and specification documentation
regarding push notification payloads. The topics documentation
previously stated the payload was not strictly defined, while the
specification explicitly defines it as StreamResponse format.
- Updated docs/topics/streaming-and-async.md to specify StreamResponse
format
- Added references to specification sections for detailed structure
- Aligns with specification.md sections 3.1.7 and 4.3.3
Fixes#1216
## Problem
**The "filename” metadata label** in key-concept.md does not quite align
with FileBase property. As indicated in the specification.md, name,
mineType or bytes labels are part of the FilePart metadatas, instead of
using filename label.
<img width="950" height="557" alt="image"
src="https://github.com/user-attachments/assets/de687e31-e184-4036-a35b-763649bae682"
/>
## Solution
Replace “filename” metadata label with “name” label to align with
FileBase property.
## Changes
Modify A2A\docs\topics\key-concepts.md and **replace “filename” metadata
label with “name” label** to better align with FileBase property from
specification.
## Testing
✅ Documentation builds successfully with mkdocs
✅ Markdown linting passes
✅ All internal anchor links verified
✅ No broken cross-references
## Issue
Fixes#1167
# Description
fix typo `forseeable` -> `foreseeable`
- [ ✅ ] 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)
Fixes#972🦕
Signed-off-by: Sun Yuhan <sunyuhan1998@users.noreply.github.com>
Co-authored-by: Sun Yuhan <sunyuhan1998@users.noreply.github.com>
There are a few links in the spec doc that are clearly meant to link to
the github repo as the files they link to are outside the docs folder.
This fixes them so they work on the generated site hosted at
https://a2a-protocol.org/
Ideally we would use relative links so that when reading the markdown
file in your IDE the links take you to the corresponding file within the
repo. I tried setting up a redirect in mkdocs.yml but the locally
running website kept downloading the file from github instead of
navigating to it. There is probably some plugin that will make this work
however for now I would like to simply fix the docs on the website.
This pull request fixes a small typo in the Task state description. 🦕
An extra closing parenthesis was placed incorrectly:
Before:
...until it is in a interrupted state ()input-required or
auth-required)...
After:
...until it is in an interrupted state (input-required or
auth-required)...
This change improves clarity and corrects the formatting of the
sentence.
# Description
My initial attempt at documenting extensions. I believe there's more
I'll want to write on this, and there's a lot of room for
diagrams/pretty pictures/code samples/content linking. But I figured I'd
get it started so we have something to share and get feedback early.
---------
Co-authored-by: Holt Skinner <holtskinner@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
In https://github.com/google-a2a/A2A/pull/359, the Agent Card got an
update to replace authentication with security. This doc change in
enterprise-ready.md just reflects that change.
# Description
This updates the protocol to support Extensions. Extension profiles are
documents that describe modifications or additions to the core A2A
profile. AgentCards can declare supported extensions via
`capabilities.extensions`. This declaration can include additional
information via `capabilities.extensions.params`. Clients can use this
as a basis for extension negotiation: if a client supports an extension
that the server supports, the client can then follow the protocol
defined by the extension. This can include, but is not specifically
limited to:
1. Requiring specific structure of messages, such as following a
specific schema for a DataPart.
2. Providing additional information in request/response Message and
Artifact objects via their `metadata` field.
3. Exposing additional methods beyond the core A2A protocol methods.
Messages and Artifacts can now include an indication of which extensions
are present in their content. I do not yet know if extension indications
are necessary on other data structures (such as `MessageSendParams` or
`TaskStatus`). I'd say extension indications are not strictly necessary
at all: it's possible to infer that an extension was followed by
inspecting the message content itself (are the metadata fields you
expect present, does the DataPart follow the schema you expect, etc).
However, they are useful for validation and simplifying extension
implementation logic: "you said you followed this extension, so I'll
validate fields are present and then perform my processing".
Fixes#585
---------
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
# Description
Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:
- [ ] Follow the [`CONTRIBUTING`
Guide](https://github.com/google/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)
Fixes #<issue_number_goes_here> 🦕
- Structuring of Information Architecture
- Combine `specification/*.md` files into a single `specification.md` in
RFC format.
- Combine `documentation.md` into `index.md`
- Rename `push-notifications.md` into `streaming-and-async.md`
- Create `topics/key-concepts.md` and `topics/what-is-a2a.md`
- Remove duplicated content between README/index files.
- Hide Python Tutorial from Nav until SDK is released.
Use mkdocs style relative paths to file.md.
Fix several old paths.
Add redirects to mkdocs.
Replace HTML prev/next links with markdown.
Format markdown.