51 Commits

Author SHA1 Message Date
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
f86c799f09 docs: Update TOC to include 1.0 Blog Post 2026-03-12 12:17:47 -05:00
Holt Skinner
b2daedcadf
docs: Add What's New in V1 to Docs TOC (#1489)
<img width="966" height="661" alt="Screenshot 2026-02-17 at 11 46 47鈥疉M"
src="https://github.com/user-attachments/assets/6730cd94-bbf6-4f0a-8e33-d3a0ae2833ae"
/>
2026-02-17 12:16:53 -06: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
Ivan Shymko
bb527d4299
docs: Bring back Python SDK reference (#1415)
Currently [`SDK Reference >
Python`](https://a2a-protocol.org/latest/sdk/python.md) link gives 404:

<img width="1138" height="308" alt="image"
src="https://github.com/user-attachments/assets/2bd3bda0-0536-4450-8e82-5ec9ee5ce044"
/>

1. Fix the link to open
[this](https://a2a-protocol.org/latest/sdk/python/api/index.html)
instead. This was setup in #949 and is generated automatically from the
latest docs. Looks like it was accidentally changed to `python.md` (the
one not used ever before, it used to be `python/index.md`) in #1160.
2. Fix redirect to use absolute URL with `latest`. This is required due
to https://github.com/mkdocs/mkdocs-redirects/issues/18, current way
isn't going to work. `v0.3.0` tag of the website (the one you get after
clicking `Latest Released Version` from
[here](https://a2a-protocol.org/latest/specification/)) doesn't have the
generated documentation either way, see
[here](https://github.com/a2aproject/A2A/tree/gh-pages/v0.3.0/sdk/python).
3. Replace `Google LLC` with `The Linux Foundation` in the generated SDK
reference.
4. Update copyright year in both places.

Tested via `mkdocs serve`.

Fixes #1347.
2026-01-26 10:12:40 -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
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
d190c1233d docs: Add Link to Markdown Source on pages for LLM Loading 2025-10-17 11:13:32 -05:00
Holt Skinner
b8fc33e67a docs: Update Site Description 2025-10-16 10:51:33 -05: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
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
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
Holt Skinner
96c9854b60 docs: Update Site Name for SEO 2025-09-11 12:08:13 -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
d4fb040b1a docs: Update description for SEO 2025-09-08 12:59:20 -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
Holt Skinner
6524df762e docs: Change site name to include Documentation 2025-09-02 15:44:48 -05:00
Holt Skinner
ab1f40973a
docs: Restructuring for SEO (#1026) 2025-09-02 12:57:31 -05:00
Holt Skinner
9b10e27ee1 docs: Add Linux Foundation as site_author 2025-08-27 18:03:59 +01:00
Holt Skinner
5c54b6ec3b
docs: Update Copyright to Linux Foundation (#1012) 2025-08-27 17:28:52 +01:00
Holt Skinner
6be695da75 docs: Add redirect for sdk/python to new docs location 2025-07-31 20:13:33 +01:00
Holt Skinner
ced1f6fb3d
docs: Update Python SDK Docs to use Sphinx (#949)
Fixes #950
2025-07-31 20:05:24 +01:00
abiramit5
183c6dad28
docs: update GA ID for Google Analytics config (#913) 2025-07-25 18:18:41 +01:00
Holt Skinner
ab412fe553
docs: Move Roadmap out of Topics to be more visible (#886)
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-07-18 16:34:45 +01:00
Michael Vakoc
1c2ccbb18c
docs: Adding roadmap to /topics (#882)
Adding roadmap to the public docs site

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-07-17 22:27:25 +00:00
abiramit5
05f93b5a84
docs: Add Google Analytics to Docs (#865)
Google Analytics Integration: I've configured Google Analytics tracking
for the documentation site by adding a new analytics block to the extra
section within mkdocs.yml.
2025-07-17 16:48:30 +00:00
Holt Skinner
96ed2d3a83 docs: Update Domain to https://a2a-protocol.org 2025-07-16 21:04:47 +01:00
Holt Skinner
3e8f8a5a12 docs: Add 404 Redirect 2025-07-08 11:36:31 -04:00
Holt Skinner
f17edc0b9e docs: Update Redirect Links 2025-07-02 15:47:23 -05:00
alan blount
4a0d92eff7
docs: Homepage Style Updates (#794)
- Minor changes to above-the-fold homepage content
- Add YouTube Intro Video
- Add specific modules to Python SDK Docs to decrease compile time

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-06-30 17:36:22 +00:00
Holt Skinner
08132ac5c7
docs: Repo Link Updates (#780) 2025-06-23 21:34:48 +02:00
swapydapy
ebc4157ca8
docs!: update spec & doc topic with non-restartable tasks (#770) 2025-06-20 17:48:25 +00:00
Mike Smith
94a3a00282
docs: First pass at extensions documentation (#750)
# Description

My initial attempt at documenting extensions. I believe there's more
I'll want to write on this, and there's a lot of room for
diagrams/pretty pictures/code samples/content linking. But I figured I'd
get it started so we have something to share and get feedback early.

---------

Co-authored-by: Holt Skinner <holtskinner@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
2025-06-14 19:22:30 +00:00
Holt Skinner
fea538fe9f
docs: Add Docs versioning with mike (#739) 2025-06-09 15:17:59 -04:00
Holt Skinner
9c4b05ccdc
docs: Cleanup of docs Configuration (#727) 2025-06-04 15:06:54 -05:00
Holt Skinner
e7e43d0ee9
docs: Convert Tutorial code samples to use embedded snippets (#685)
Followup to https://github.com/google-a2a/a2a-samples/pull/68
2025-05-29 10:13:10 -05:00
Holt Skinner
729988a3f5
refactor: Remove Samples/Demo/test directories and change references to google/A2A (#668) 2025-05-27 16:31:32 -05:00
Holt Skinner
9b7b8f6e42
docs: Update SDK Doc to show all enum values (#637)
Fixes #631 馃
2025-05-22 12:56:30 -07:00
Holt Skinner
081fa20bdf
docs: Update SDK Reference page (#603)
- Move SDK Reference before Tutorial in TOC
- Add `pip install` command to SDK Reference page
2025-05-20 07:43:19 -07:00
Holt Skinner
67472e9908
docs: Python SDK Initial Doc Generation (#570)
Create Python SDK Documentation using mkdocstring
2025-05-20 07:38:15 -07:00
Holt Skinner
3ba6bff695
docs: Add redirect for spec-json to point to the a2a.json file (#526) 2025-05-13 14:55:13 -05:00
Holt Skinner
5d0a06d749
docs: Add redirect for /topics to What is A2A? (#523) 2025-05-13 13:55:02 -05:00
Holt Skinner
72cc285c68
docs: Add Redirect from tutorials/ to the tutorial intro (#520) 2025-05-13 12:47:10 -05:00
Holt Skinner
2d44597bc3
docs: Refactoring Python Tutorial (#474) 2025-05-12 14:29:47 -05:00
Holt Skinner
cdcbe6d344
docs: Cleanup of Images (#476)
- Change Logo files to SVG
  - Change Logo in Docs to White for visibility
- Remove unused images
- Move demo architecture diagram to `demo/` folder
2025-05-09 14:25:53 -05:00
Holt Skinner
c09716e0fe
docs(refactor): Refactoring of Documentation (#453)
- Structuring of Information Architecture
- Combine `specification/*.md` files into a single `specification.md` in
RFC format.
  - Combine `documentation.md` into `index.md`
  - Rename `push-notifications.md` into `streaming-and-async.md`
  - Create `topics/key-concepts.md` and `topics/what-is-a2a.md`
- Remove duplicated content between README/index files.
- Hide Python Tutorial from Nav until SDK is released.
2025-05-09 12:50:37 -05:00
alan blount
59d63dc7f5
fix: many broken links (#413)
Use mkdocs style relative paths to file.md.
Fix several old paths.
Add redirects to mkdocs.
Replace HTML prev/next links with markdown.
Format markdown.
2025-05-05 15:23:17 -05:00
Kristopher Overholt
b5fecbe317
feat: Rework documentation, reorganize pages (Stage 2/3) (#365)
# 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/google/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)

Fixes https://github.com/google/A2A/issues/348.

This PR is for docs rework stage 2 of 3. See
https://github.com/google/A2A/issues/347 for full context.

Screenshot at this point:

![Screenshot 2025-05-01 at 4 12
05鈥疨M](https://github.com/user-attachments/assets/c081c8b3-24ee-4164-91f1-a17bceff7e28)
2025-05-01 16:15:18 -05:00
Kristopher Overholt
2f9aa7edd4
feat: Initial commit of A2A docs source and mkdocs site (#350)
Fixes #346.

This PR is for docs rework stage 1 of 3. See #347 for full context.

Screenshot at this point:

![Screenshot 2025-04-30 at 12 55
15鈥疨M](https://github.com/user-attachments/assets/3771ab84-77b9-4b55-82bc-3d38386e55f7)

---------

Co-authored-by: Holt Skinner <holtskinner@google.com>
2025-05-01 11:05:18 -05:00
Kristopher Overholt
cec2b9973a Undo commit 2025-04-30 12:28:50 -05:00