95 Commits

Author SHA1 Message Date
Holt Skinner
0710b78dee ci(lint): Add API Linting Configuration 2026-02-10 13:04:58 -06:00
Darrel Miller
3628e974ef feat(linter): Add API Linter job to workflow for proto file validation against 2026-02-10 12:58:38 -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
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
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
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
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
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
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
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
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
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
herczyn
1bd263f537
feat(spec): Remove v1s from a2a url http bindings. (#1269)
these can still be part of the agent card.

fixes #1268

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Signed-off-by: Luca Muscariello <lumuscar@cisco.com>
Signed-off-by: Yuri Zhao <yu.zhao5@huawei.com>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-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: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Co-authored-by: yuri <yu.zhao5@huawei.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Martin Harrigan <martinharrigan@gmail.com>
2025-12-04 11:33:39 +01:00
herczyn
cfbce32cb0
feat(spec): Natively Support Multi-tenancy on gRPC through an additional scope field on the request. (#1195)
Add scope field to the requests and AgentInterface, deprecate the three
fields defining transports in favor of a new supported_interfaces field.

fixes #1148
2025-12-03 20:27:26 -05:00
iliesicatrinel
b6ef9eec55
fix(spec): Remove metadata field from ListTasksRequest (#1235)
The ListTasksRequest message includes a google.protobuf.Struct metadata
field, which cannot be represented as simple URL query parameter
required by HTTP GET requests. This causes service config generation to
fail with `http: map field 'google.protobuf.Struct.fields' referred to
by message 'a2a.v1.ListTasksRequest`.

Since it's unclear whether metadata will be useful for ListTasks, I
propose to remove it at least for now to fix the specification.

Fixes #1236 🦕

---------

Co-authored-by: Darrel <darrmi@microsoft.com>
2025-11-29 02:52:52 -06: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
yuri
61d1e3a6f9
docs: Readme files accuracy fix (#1186)
## Problem
There are a couple of readme file with spelling, capitalization fixes to
align with rest of documents.


## Solution
“a2a specification” -> “A2A specification”.
“Helloworld” -> “Hello World”.


## Changes
docs/topics/a2a-and-mcp.md
docs/tutorials/python/4-agent-executor.md
docs/tutorials/python/7-streaming-and-multiturn.md
specification/grpc/README.md

## Testing
✅ Documentation builds successfully with mkdocs
✅ Markdown linting passes
✅ All internal anchor links verified
✅ No broken cross-references

## Issue
Fixes #1185

---------

Signed-off-by: Yuri Zhao <yu.zhao5@huawei.com>
2025-11-21 10:19:44 -06: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
madankumarpichamuthu
a2de7981ca
fix(grpc): missing field in gRPC spec - state_transition_history (#1138)
Add missing fields to align gRPC specification with JSON specification:

- Add reference_task_ids field to Message to support cross-task context
references, matching the referenceTaskIds field in JSON spec
- Add state_transition_history capability flag to AgentCapabilities to
indicate support for task state transition history tracking

These changes ensure feature parity between gRPC and JSON-RPC
implementations of the A2A protocol. Both additions are optional fields
and maintain backward compatibility with existing implementations.

Fixes #1139 
Closes #1139
2025-10-19 10:05:42 -04:00
Copilot
2a1f819aaa
fix(grpc): Fix inconsistent property name between gRPC and JSON-RPC in Message object (#1100)
This PR resolves an inconsistency in the Message object property names
between the two transport protocols:

**Issue:**
- JSON-RPC (TypeScript): Used `parts: Part[]` for the array of content
parts
- gRPC (Protocol Buffers): Used `repeated Part content = 5;` for the
same field

**Solution:**
Updated the gRPC protocol buffer definition in
`specification/grpc/a2a.proto` to use `parts` instead of `content`,
aligning it with the JSON-RPC naming convention:

```proto
// Before
repeated Part content = 5;

// After  
repeated Part parts = 5;
```

Also updated the associated comment to reflect the change from "Content
is the container..." to "Parts is the container...".

**Impact:**
- Ensures consistent property naming across both transport protocols
- Eliminates potential confusion for developers working with different
transports
- Maintains backward compatibility while improving developer experience
- No changes needed to existing JSON schema or TypeScript definitions

The fix is minimal and surgical, changing only the field name in the
gRPC definition to match the established JSON-RPC convention.

Fixes #1083.

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

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

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: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
2025-10-18 13:19:36 -04: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
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
Ioannis Papapanagiotou
b3b266d127
fix: Add missing metadata field to Part message in gRPC specification (#1019)
## Summary
- Adds missing `metadata` field to the `Part` message in the gRPC
specification
- Fixes inconsistency between TypeScript/JSON and gRPC protocol
definitions
- Prevents data loss during Python ↔ gRPC conversions

## Problem
The `Part` message in `specification/grpc/a2a.proto` was missing the
`metadata` field that exists in the TypeScript and Python
specifications. This caused important metadata (like ADK function
call/response types) to be lost during conversions between Python and
gRPC representations.

## Solution
Added `google.protobuf.Struct metadata = 4;` to the `Part` message,
following the same pattern used by other proto messages in the
specification (Task, Message, Artifact, etc.).

Fixes #1005

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2025-09-02 16:56:11 +00:00
hoonji
a8b45dcc42
fix(proto): Adds metadata field to A2A DataPart proto (#1004)
The Python DataPart class [has
metadata](e3a7207164/src/a2a/types.py (L285)),
but the proto doesn't. This leads to loss of important information
during Python->proto conversion; e.g. ADK embeds part types like
"function_call" and "function_response" [in the
metadata](https://github.com/google/adk-python/blob/main/src/google/adk/a2a/converters/part_converter.py#L207-L211).

Fixes #1005 🦕
2025-09-02 11:53:58 -05:00
Che Liu
e6b8c654a8
fix: Revert "chore(gRPC): Update a2a.proto to include metadata on GetTaskRequest" (#1000)
Reverts a2aproject/A2A#996

Fixes #1002 

GetTaskRequest in the REST protocol is a GET. GET does not have request
body, and all fields in GET should be serializable to a query param.

metadata when being a struct cannot be serialized to query param, and
this is causing failure during API discovery doc generation `http: map
field 'google.protobuf.Struct.fields' referred to by message
'a2a.v1.GetTaskRequest' cannot be mapped as an HTTP parameter.`
2025-08-22 10:03:15 -07:00
Shane Price
f0d48cdd5f
chore(gRPC): Update a2a.proto to include metadata on GetTaskRequest (#996)
# Description

https://a2a-protocol.org/latest/specification/#73-tasksget

JsonRPC supports this field while GRPC does not

Part of #998
2025-08-20 20:29:37 +01:00
Shane Price
17e7f62df9
fix(proto): Add icon_url to a2a.proto (#986)
# Description

According to the specification for `0.3.0` there is an optional icon url
in AgentCard, however this is not present in the provided protobuf spec.

~I didn't know which tag is preferred for this field, so I incremented
the highest tag found.~
Gemini helped notify me about the Next Tag comment.

Fixes #987 🦕
2025-08-20 16:00:17 +01:00
Holt Skinner
911f9b059c
fix(grpc): Update CreateTaskPushNotificationConfig endpoint to /v1/{parent=tasks/*/pushNotificationConfigs} (#979)
Seems to have been a typo
2025-08-20 15:49:14 +01:00
Holt Skinner
00cf76e7bb
fix(spec): Suggest Unique Identifier fields to be UUID (#966) 2025-08-13 20:56:28 +01:00
Mike Smith
2b7cb6f840
fix: Add name field to FilePart protobuf message (#983)
This is present in the JSON-RPC spec and was missing from the gRPC
definition.

Fixes: #984
2025-08-13 16:48:03 +01:00
kthota-g
cab1bc3c96
chore(spec): clean up comments in gRPC spec (#959)
# Description

Fixes #861  🦕
2025-08-07 16:05:37 +01:00
kthota-g
8d57eba286
docs: Address typos in docstrings and docs. Fixes #940 (#941)
Fixes #940  🦕

---------

Co-authored-by: a2a-bot <a2a-bot@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2025-07-31 15:59:53 +01:00
dmandar
6a152a83ad
chore: Update default protocol version to 0.3.0 (#932)
We can push this when we release 0.3.0

Release-As: 0.3.0

---------

Co-authored-by: a2a-bot <a2a-bot@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2025-07-30 14:57:35 +00:00
Mike Smith
e162c0c6c4
feat!: Add mTLS to SecuritySchemes, add oauth2 metadata url field, allow Skills to specify Security (#901)
# Description

This PR makes changes to our security representations in AgentCards:

1. Adds a new MutualTLSSecurityScheme type for indicating mTLS
connection requirements. This matches the same field in the OpenAPI
specification v3.1. This type is pretty lacking: there is no way to
indicate any requirements on the certificate that is presented by the
client. I expect we'll want to extend this in the future (for example,
we may want to allow an agent to indicate that a SPIFFE certificate must
be presented). For now, users are advised to put requirements in the
description field.
2. Adds a field for specifying a URL for OAuth2 provider metadata. This
is planned for OpenAPI Specification v3.2, which has not yet been
released. This allows clients to fetch additional information about the
OAuth provider, such as to discover if they support Dynamic Client
Registration.
3. Allows AgentSkills to specify a `security` field. This allows agents
to indicate security requirements for leveraging a particular skill.

I also clarified the usage and expectations for the `security` field in
the base AgentCard.

This change is marked backwards incompatible due to the addition of the
MutualTLSSecurityScheme, which adds a new type to an exhaustive enum
(the security scheme `anyOf`).

Release-As: 0.3.0

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-07-29 13:39:27 -06:00
kthota-g
6fb2b771b0
ci: Trigger ci build for spec update (#936) 2025-07-29 19:50:41 +01:00
kthota-g
476863efa6
chore: Push to trigger spec update wf (#934)
# Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [ ] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md).
- [ ] Make your Pull Request title in the
<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> 🦕

---------

Co-authored-by: a2a-bot <a2a-bot@google.com>
2025-07-29 11:16:51 -07:00
kthota-g
2cd7d98bc8
feat!: Add method for fetching extended card (#929)
# Description
This change adds support for a new JSON-RPC method
`agent/getAuthenticatedExtendedCard` for fetching authenticated extended
card.

This is only applicable if `AgentCard.supportsAuthenticatedExtendedCard`
bit is set to `true` that allows fetching authenticated context specific
agent card.

In the previous versions, the extended card was served via
`{AgentCard.url}/../agent/authenticatedExtendedCard` endpoint. This
endpoint is being removed in favor of the JSON-RPC method. This endpoint
will be deprecated in the SDKs and will be removed in a future release.

Release-As: 0.3.0

---------

Co-authored-by: a2a-bot <a2a-bot@google.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2025-07-29 09:31:45 -07:00
Israel Ekpo
074a3dd06b
docs: Update Docs to Clarify that Task Id Must Be Generated By the A2A Server (#926)
Fixes #925  🦕

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-07-28 17:03:25 +01:00
Mike Smith
ef4a305053
feat: Add signatures to the AgentCard (#917)
# Description

This introduces a `signatures` field on the AgentCard that contains JWS
formatted signatures. See issue #916 and discussion #199 for further
details, including how signatures are constructed and verified.

Fixes #916 🦕
2025-07-25 18:12:25 +00:00