159 Commits

Author SHA1 Message Date
Darrel
032e67c46a
Merge branch 'main' into create-not-set 2025-12-01 14:23:45 -05: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
Darrel Miller
1ab7f11789 docs(spec): Rename set push notification configuration methods to create to fix accidental change 2025-11-28 12:21:53 -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
Martin Harrigan
d8dd640d2b
docs: fix conflicting description of artifact name (#1153)
The heading says the artifact name is updated but the following text and
JSON shows that it remains the same.
2025-11-21 17:21:39 +00: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
Ben Clarke
0534ba6a9e
docs: add A2A Net to partners list (#1201)
Added A2A Net to the list of partners.
2025-11-13 08:59:26 -08:00
YoTaro (Yot) Watanabe
b069cc7b19
docs Add NTT DATA to partners list (#1200)
Update partners with NTT DATA

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-11-11 15:34:05 -08:00
Ivan Cheung
7c8181e045
docs: Updated references to Go (#1202) 2025-11-11 15:37:02 -06:00
Farah Juma
202aa069e6
fix: Update the Java tutorials and descriptions (#1181)
Updating the Java section for the Tutorials page to list the current
samples.

Fixes https://github.com/a2aproject/A2A/issues/1182
2025-10-29 10:43:03 -07:00
alan blount
6fd5c38914
docs: updated a2a logo SVGs (#1184) 2025-10-29 10:20:59 -05:00
chitra-venkatesh
db8e55c044
Doc Update partners.md (#1178)
Update partners with ParkourSC
2025-10-26 16:57:53 -07:00
Pastukhov Nikita
e7cf203ecd
docs: Add AG2 link to community resources (#1170)
AG2 0.10 release introduces A2A support, enabling agents to communicate
across different processes, machines, applications, and even different
frameworks and languages. So, I think it would be great to add this
integration to the list.
2025-10-22 15:21:52 +00:00
Holt Skinner
c33cb537bb docs: Add Notes to homepage about being the official documentation 2025-10-21 14:52:25 -05:00
Holt Skinner
058d614e40 docs: Update Specification page to say Latest Released Version 2025-10-21 14:04:24 -05:00
yuri
f7aed0247f
docs: Replace filename metadata label with name to align with FileBase prop… (#1166)
## Problem
**The "filename” metadata label** in key-concept.md does not quite align
with FileBase property. As indicated in the specification.md, name,
mineType or bytes labels are part of the FilePart metadatas, instead of
using filename label.

<img width="950" height="557" alt="image"
src="https://github.com/user-attachments/assets/de687e31-e184-4036-a35b-763649bae682"
/>


## Solution
Replace “filename” metadata label with “name” label to align with
FileBase property.


## Changes
Modify A2A\docs\topics\key-concepts.md and **replace “filename” metadata
label with “name” label** to better align with FileBase property from
specification.

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

## Issue
Fixes #1167
2025-10-21 09:29:28 -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
96d1b6b5cc
docs: Fix Mike Versioning to use canonical and update deployment process for robots.txt (#1144) 2025-10-14 14:33:55 -05:00
abiramit5
51fac35bf6
docs: Add List of Extensions (#1136)
Fixes #1137
2025-10-10 13:05:34 -05:00
chitra-venkatesh
a4ce3e5909
docs: Update partners.md with Ag2AI (#1126) 2025-10-06 10:17:44 -05: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
chitra-venkatesh
99e7efb5ff
docs: Update partners.md (#1103)
Updating to remove intake form - page maintenance

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2025-09-26 10:23:41 -07: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
bbe415fea2
docs: Update Community Page with new content (#1081)
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-09-19 11:48:37 -07:00
abiramit5
70d5cd6f93
docs: update the table of contents and actor/stack images (#1080)
Replaced the images and restructured the TOC.

Closes https://github.com/a2aproject/A2A/issues/1070

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-09-18 16:21:50 +00:00
Holt Skinner
1bd11be91a
docs: Add IBM Research to partners.md (#1035) 2025-09-16 14:48:59 -05:00
abiramit5
0ab97ffa96
docs: Update tutorials/index.md to make tables for Tutorials (#1065)
# Description

Closes #1064

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-09-12 10:04:18 -05:00
Holt Skinner
1c1d72056c
docs: Restructure TOC under Topics (#1060)
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-09-11 12:42:32 -05:00
abiramit5
d38f19b35d
docs: update docs and table of contents (#1056)
# Description

Closes #1048  🦕

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-09-10 18:30:45 +00:00
Holt Skinner
876ba6e2b2 docs: Add A2A integrations section with supported frameworks 2025-09-08 15:30:37 -05:00
Holt Skinner
d4fb040b1a docs: Update description for SEO 2025-09-08 12:59:20 -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
Holt Skinner
598b6d3d0d
docs: Fix Broken Links (#1044)
Fixes #1043 🦕
2025-09-08 10:39:56 -05:00
Holt Skinner
df6aaef36a
docs: Cleanup README and Docs Index with Updated Logos and reduced size images to speed up load time (#1038) 2025-09-05 12:29:31 -05:00
abiramit5
16a8e0eeac
docs: Updated the content in A2A docs topics (#965)
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-09-05 11:05:43 -05:00
alextibbles
c37ab0d3e8
fix(docs)!: update specification to clarify web hook certificate verification (#977)
# Webhook Certificate Checks

## User Benefit
While it is specified that Clients SHOULD verify Server identity through
the certificate, it is not currently explicit that Servers also have
this responsibility when delivering an update to a web hook URL. It
would be beneficial to users if uniform requirements on identity
verification were explicitly specified. Having a variation in
requirements that depends on whether responses are delivered
synchronously or asynchronously is surprising and seems unintentional.
The risk involved in not confirming the web hook certificate includes a
potential breach of confidentiality of response payload.

## This Change
This PR proposes an additional statement making explicit the A2A Server
responsibility when delivering asynchronous payload updates to
authenticate the destination certificate.

## Compatibility
In theory, a previously fully conforming implementation that did not
perform a check on a web hook server certificate would not meet the new
SHOULD statement. I couldn't locate information about what this implies
eg. with respect to versioning.
In practice, it seems at least somewhat unlikely that implementations
does this because verification of server certificates is the default
behavior across many different software toolsets for some time.

Closes #978
2025-09-04 16:22:29 +00:00
Holt Skinner
07f9091733
docs: Update 404 Path to redirect SDK page (#1028)
Fixes #951 🦕
2025-09-03 11:01:55 -05:00
Holt Skinner
ab1f40973a
docs: Restructuring for SEO (#1026) 2025-09-02 12:57:31 -05:00
Holt Skinner
bf9aa07595 docs: Remove versioned robots.txt to be replaced by a root-level file 2025-08-27 17:50:57 +01:00
Michael Vakoc
d69f9bcdb3
docs: Adding Infinitus to partner list (#1008) 2025-08-26 18:05:17 +01:00
Stefano Maestri
42c1dbc3aa
docs: removing TaskList defined only for gRPC and JSON+HTTP (#990)
Fixes #985 🦕
2025-08-20 20:31:46 +01:00
Holt Skinner
87c644e796
docs: Update Docs URL in README 2025-08-20 20:10:37 +01:00
Holt Skinner
bc2b387329
docs: Add MindsDB to partners.md 2025-08-20 18:39:49 +01:00
Holt Skinner
c6b098010b
docs: Fix Manual Redirect Link (#988) 2025-08-13 20:55:51 +01:00
Sun Yuhan
55989487f4
fix: Fix typo forseeable -> foreseeable (#971)
# Description

fix typo `forseeable` -> `foreseeable`

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

Fixes #972 🦕

Signed-off-by: Sun Yuhan <sunyuhan1998@users.noreply.github.com>
Co-authored-by: Sun Yuhan <sunyuhan1998@users.noreply.github.com>
2025-08-12 14:14:13 +01:00
Michael Vakoc
3d340f7d87
chore: Update partners.md (#969)
adding Kakao to partner list

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-08-11 10:42:33 -07:00
Richard Rance
6dcfcae350
docs: fix links on documentation site (#960)
There are a few links in the spec doc that are clearly meant to link to
the github repo as the files they link to are outside the docs folder.
This fixes them so they work on the generated site hosted at
https://a2a-protocol.org/

Ideally we would use relative links so that when reading the markdown
file in your IDE the links take you to the corresponding file within the
repo. I tried setting up a redirect in mkdocs.yml but the locally
running website kept downloading the file from github instead of
navigating to it. There is probably some plugin that will make this work
however for now I would like to simply fix the docs on the website.
2025-08-07 16:06:33 +01:00