92 Commits

Author SHA1 Message Date
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
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
Holt Skinner
6845a87b50
docs: Update Specification.md for 1.0.0 from release candidate (#1620) 2026-03-12 11:47:56 -05: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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Vinay Ramesh
e8c0f0fd61
docs(spec): patched security scheme and add anchor tag for Security (#1279)
Minor patch to `security_scheme` reference to `securityScheme` and added
a missing anchor tag for `Security`. Another docs change should be added
to clarify usage of `Security`. Opened
https://github.com/a2aproject/A2A/discussions/1278 for clarification.

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

Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
2026-01-12 13:34:26 -05:00
Sam Betts
60f83c3faa
fix(spec)!: Remove deprecated fields from a2a.proto for v1.0 release (#1301)
As v1.0 is a major release and may contain breaking changes this commit
cleans up the deprecated fields in the a2a.proto and references to this
in the spec doc.

Closes: #1227
2026-01-06 11:29:53 -05:00
Kuba Herczyński
a336a5a484
fix(spec): Clarify contextId behavior when message is sent with taskId but without contextId (#1309)
Fixes #1249.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
2025-12-24 11:33:17 -05:00
Didier Durand
dec450b3c4
docs: fix typos in specification.md (#1304)
Hi,
Recent changes in in specification.md brought some typos: this PR fixes
them.
See commit diffs for details.
Didier
2025-12-11 09:30:47 -06:00
madankumarpichamuthu
c196824396
fix(spec)!: Rename supportsAuthenticatedExtendedCard to supportsExtendedAgentCard (#1222)
Fixes naming inconsistency between the agent card property and the
GetExtendedAgentCard method. The property name now matches the method
naming convention.

- Updated proto definition: supports_authenticated_extended_card →
supports_extended_agent_card
- Updated all documentation references across specification.md and
llms.txt
- Maintains semantic meaning while improving consistency

Fixes #1215
2025-12-05 18:54:19 +00:00
iliesicatrinel
d381cea9d0
docs(spec): Update specification to use proto_to_table macro for all core operations (#1242)
We should use the proto_to_table macro for describing inputs/outputs of
operations to avoid having to modify the specification manually after
protobuf definition changes.

Other changes:
- small updates to capitalization/markdown annotations to ensure
consistency with the rest of the specification
- modified proto_to_table to return `None` string if proto is empty
(e.g. `GetExtendedAgentRequest`). We should use macro for this request
even if it's empty, because we may add fields
(https://github.com/a2aproject/A2A/pull/1195).

Fixes https://github.com/a2aproject/A2A/issues/1243 🦕

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel Miller <darrel.miller@microsoft.com>
2025-11-28 16:01:09 -05:00
Emmanuel Hugonnet
5792804372
fix(doc): Makes JSON-RPC SendMessage response clearer (#1241)
Fixing issue #1240 by providing something more in line with what is
expected.

Fixes https://github.com/a2aproject/A2A/issues/1240 🦕

---------

Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-11-26 15:36:32 -05:00
Darrel
18ca2533bf
docs(spec): Updated specification to render data models as a table generated from the proto instead of a raw proto snippet (#1225)
In the currently published specification the data model definitions
include a proto snippet and then have a list of fields under the
snippet. This creates duplicated information. To prevent this
duplication while maintaining an easy to read presentation of the
abstract data models, this PR uses a Python macro to convert the proto
into a markdown table.

Also took the opportunity to do an editorial pass on the comments in the
a2a.proto before the field descriptions were removed from the
specification.md. Some of this content came from the types.ts file that
often had information that was not in a2a.proto.

A preview of the changes can be seen here
https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#41-core-objects

# Proto to Markdown Table Conversion

The macro system provides two main functions (`proto_to_table` and
`proto_enum_to_table`) that convert Protocol Buffer definitions into
formatted markdown tables:

1. **Locates Definitions**: Reads the `.proto` file and uses region
markers (`--8<-- [start:Name]` and `--8<-- [end:Name]`) to extract
specific message or enum definitions.

2. **Parses Structure**: Analyzes the proto content to separate three
sections:
- **Description**: Comments appearing before the message/enum
declaration
- **Fields/Values**: The actual field or enum value definitions with
their inline comments
   - **Notes**: Comments appearing after the closing brace

3. **Extracts Field Details**: For each field, it captures:
- Field name (converted from snake_case to camelCase, or using
`json_name` annotation)
- Type (mapped to readable formats like "string", "array of integer",
"map of string")
- Required status (based on `REQUIRED` annotation or `optional` keyword)
   - Description (from preceding comment lines)

4. **Generates Output**: Assembles the markdown output with:
   - Description text at the top
- A formatted table with columns for Field/Type/Required/Description (or
Value/Description for enums)
   - Special notes for `oneof` groups
   - Additional notes from comments after the definition

The conversion automatically handles multi-line field definitions, map
types, repeated fields, and filters out protolint directives and region
markers from the output.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-11-25 09:11:28 -08:00
Darrel
b078419954
docs(spec): Large refactor of specification to separate application protocol definition from mapping to transports. (#1160)
Related to #1151 

Fixes https://github.com/a2aproject/A2A/issues/998
Fixes https://github.com/a2aproject/A2A/issues/1091
Fixes https://github.com/a2aproject/A2A/issues/1072
Fixes https://github.com/a2aproject/A2A/issues/1058
Fixes https://github.com/a2aproject/A2A/issues/975
Fixes https://github.com/a2aproject/A2A/issues/1105
Fixes https://github.com/a2aproject/A2A/issues/989
Fixes https://github.com/a2aproject/A2A/issues/1189
Fixes https://github.com/a2aproject/A2A/issues/1187
Fixes https://github.com/a2aproject/A2A/issues/1177
Fixes https://github.com/a2aproject/A2A/issues/1180
Fixes https://github.com/a2aproject/A2A/issues/1172



In order to more effectively describe the A2A protocol in a consistent
way across different protocols, this PR refactors the specification to
describe the application protocol in a transport agnostic way, and then
have separate sections that describe how each of the transports map to
the abstract application protocol. To see a preview of what it looks
like you can go here
https://purple-moss-0838db51e.3.azurestaticapps.net/specification/

The goal of the TSC is to use the changes in this PR as the baseline for
a v1.0 Release Candidate. This will give SDK maintainers an stable
document to validate the changes in the specification through
implementations before v1.0 release.

There are many pending feature requests for the A2A specifications that
the TSC are supportive of. However, getting a stable, consistent,
unambiguous, multi-protocol specification is necessary before additional
features can be added safely.

## Document Restructuring 

- [A2A
Operations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#3-a2a-protocol-operations)
are described independent of wire protocol
- [Protocol Data
Model](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#4-protocol-data-model)
is described using protobuf as source of truth. All other serializations
are derived from that.
- Protocol bindings (formerly described as transports) are now described
in their own sections
-
[JSON-RPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#9-json-rpc-protocol-binding)
-
[gRPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#10-grpc-protocol-binding)
-
[HTTP](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#11-httpjsonrest-protocol-binding)
- [Operation Parameters
](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#32-operation-parameter-objects)
describe structures reused across different operations
- [Operation
Semantics](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#33-operation-semantics)
describe common behavior patterns across operations

## New Sections

- [Requirements
Language](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#21-requirements-language)
- [Capability
Validation](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#334-capability-validation)
- [Abstract description of error
handling](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#332-error-handling)
- [Abstract description of
"headers"](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#325-headers)
-
[Extensions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#46-extensions)
-
[Versioning](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#36-versioning)
- [Custom Binding
Guidelines](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#12-custom-binding-guidelines)
- [JSON Field Naming
Conventions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#54-json-field-naming-convention)
- [Data Type
Conventions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#55-data-type-conventions)
- [Security
Considerations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#77-security-considerations)
- [Agent Card
Signing](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#84-agent-card-signing)
- [IANA
Considerations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#13-iana-considerations)

## Protocol Clarifications

- Defining order for events returned from [Stream
Message](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#312-stream-message)
- [JSON
Examples](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#416-filepart)
provided for protobuf definitions of data model objects that previously
used discriminators
- Clarification of returned errors where multiple are applicable. e.g.
[Cancel
Task](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#315-cancel-task)
- Defined returned events and usage scenarios for
[Resubscribe](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#316-resubscribe-to-task)
- Defined protocol binding for errors using protocol native capabilities
for all bindings
-
[JSON-RPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#94-error-handling)
-
[gRPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#104-error-handling)
-
[HTTP](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#115-error-handling)
  
## Artifact Generation

The scripts have been changed to enable a2a.json to be generated from
the a2a.proto so that a2a.proto and specification.md are the only
normative source. Additional work is required to align the generated
a2a.json with the original one.

Release-As: 1.0

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Signed-off-by: Luca Muscariello <lumuscar@cisco.com>
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>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2025-11-20 14:52:09 -05:00
Holt Skinner
058d614e40 docs: Update Specification page to say Latest Released Version 2025-10-21 14:04:24 -05:00
Eden Reich
0a9f629e80
feat(spec): Add tasks/list method with filtering and pagination to the specification (#831)
# 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:

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

Fixes #761  🦕

---------

Signed-off-by: Eden Reich <eden.reich@gmail.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
2025-10-16 12:47:20 -07:00
Holt Skinner
b1124ec68f
docs: Add header for 7.1.2 MessageSendConfiguration Object (#1110)
- Fixes incorrect display of objects notated in #1092
2025-09-29 16:47:19 -05:00
Holt Skinner
ebd85f6272 docs: Update specification.md links to only include working versions 2025-09-24 12:12:28 -05:00
Holt Skinner
b445cd7c50
docs: Update Specification Documentation Release to only publish when a release is made (#1096)
### Issues with this approach

- Style updates or link changes relating to other documentation pages
won't be propagated to the specification doc when other pages are
updated.

### Alternatives

- Maintain copies of the specification docs for each minor version
`0.X.0`
- Similar to MCP Docs
https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification
- This would also allow us to not use mike for versioning (would get rid
of `latest` in URLs and could simplify SEO)
  
Follow-up to #1077
2025-09-24 11:53:05 -05:00
Holt Skinner
7d73a5766e
docs: Add gRPC Data Structures to Specification.md (#1040)
- Added region tags in gRPC proto for imports
2025-09-08 12:49:53 -05:00