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>
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.
## Problem
**The "filename” metadata label** in key-concept.md does not quite align
with FileBase property. As indicated in the specification.md, name,
mineType or bytes labels are part of the FilePart metadatas, instead of
using filename label.
<img width="950" height="557" alt="image"
src="https://github.com/user-attachments/assets/de687e31-e184-4036-a35b-763649bae682"
/>
## Solution
Replace “filename” metadata label with “name” label to align with
FileBase property.
## Changes
Modify A2A\docs\topics\key-concepts.md and **replace “filename” metadata
label with “name” label** to better align with FileBase property from
specification.
## Testing
✅ Documentation builds successfully with mkdocs
✅ Markdown linting passes
✅ All internal anchor links verified
✅ No broken cross-references
## Issue
Fixes#1167
# Description
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>
### 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
# 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
# Description
fix typo `forseeable` -> `foreseeable`
- [ ✅ ] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md).
- [ ✅ ] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [ ✅ ] Ensure the tests and linter pass (Run `nox -s format` from the
repository root to format)
- [ ✅ ] Appropriate docs were updated (if necessary)
Fixes#972🦕
Signed-off-by: Sun Yuhan <sunyuhan1998@users.noreply.github.com>
Co-authored-by: Sun Yuhan <sunyuhan1998@users.noreply.github.com>
There are a few links in the spec doc that are clearly meant to link to
the github repo as the files they link to are outside the docs folder.
This fixes them so they work on the generated site hosted at
https://a2a-protocol.org/
Ideally we would use relative links so that when reading the markdown
file in your IDE the links take you to the corresponding file within the
repo. I tried setting up a redirect in mkdocs.yml but the locally
running website kept downloading the file from github instead of
navigating to it. There is probably some plugin that will make this work
however for now I would like to simply fix the docs on the website.