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.
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>
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>
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>
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>
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>
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>
# 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>
Hi A2A Team,
I’d like to submit [MasOrange](https://masorange.es/en/) to be added to
the A2A partners list: https://a2a-protocol.org/latest/partners/
A2A integration: We are working with A2A as a core building block for
agent discovery and agent-to-agent interoperability across our
ecosystem. We also maintain ongoing discussions with Google on
A2A-related topics, including Gemini Enterprise integrations and agentic
cloud capabilities, providing them direct feedback. We are implementing
A2A as the default protocol for exposing and connecting agentic systems
within MasOrange, adapting its usage to our security and governance
requirements, with future potential benefits for the OSS community.
Best regards,
Hugo Romero, AI Engineer at MasOrange
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
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>
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
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>
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>
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/1288Fixes: #1287Fixes: #1206
---------
Co-authored-by: Yaroslav Shevchuk <yarolegovich@gmail.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
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>
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>
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>
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
Hi A2A Team,
I would like to submit AmikoNet (https://amikonet.ai/) to be added to
the A2A partners list.
About AmikoNet: AmikoNet is the first social network where AI agents and
humans interact as equals.
Our platform enables AI agents to have their own profiles(which include
its agent card), create content, and collaborate with both humans and
other agents. All content is stored in markdown format optimized for AI
agent consumption.
A2A Integration: We use Google A2A as our core protocol for agent
discovery, allowing autonomous agents to find and connect with each
other across our network. This makes AmikoNet a natural fit for the A2A
ecosystem.
We're excited to be part of the A2A community and help advance the
standard for AI agent collaboration.
Best regards,
William
Amiko Team
This PR adds Hector to the A2A integrations list. Hector is a pure
A2A-native declarative AI agent platform written in Go that enables
building powerful agents through YAML configuration alone, with zero
code required. Unlike other frameworks that retrofit A2A support, Hector
is built from the ground up on the A2A protocol specification, providing
100% compliance with agent discovery, task execution, streaming (SSE),
and session management. Its unique value proposition is seamless
integration of external A2A agents via simple YAML configuration (type:
"a2a", url: "https://agent-url"), enabling true multi-agent
orchestration across heterogeneous systems and demonstrating the full
potential of A2A interoperability.
Homepage: https://gohector.dev
Repository: https://github.com/kadirpekel/hector
Would love to see Hector to the A2A integrations list if you also agree.
I believe it demonstrates the protocol's potential for true agent
interoperability.
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 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
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
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>
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>
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>