Holt Skinner c24b1151d1
docs(spec): Update inconsistencies in documentation for 1.0 Spec (#1466)
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.
2026-02-10 11:45:49 -06:00
..
2025-12-15 11:59:10 -06:00

A2A Docs

https://a2a-protocol.org

Developing A2A docs

  1. Clone this repository and cd into the repository directory
  2. Run pip install -r requirements-docs.txt
  3. Run mkdocs serve, edit .md files, and live preview
  4. Contribute docs changes as usual

How it works

  • The A2A docs use mkdocs and the mkdocs-material theme
  • All of the source documentation / Markdown files related to the A2A docs are in the docs/ directory in the A2A repository
  • mkdocs.yml in the repository root contains all of the docs config, including the site navigation and organization
  • There is a GitHub Action in .github/workflows/docs.yml that builds and publishes the docs and pushes the built assets to the gh-pages branch in this repository using mkdocs gh-deploy --force. This happens automatically for all commits / merges to main.
  • The A2A documentation is hosted in GitHub pages, and the settings for this are in the A2A repository settings in GitHub.

Building the Python SDK Documentation

The Python SDK documentation is built using Sphinx.

Prerequisites

Ensure you have installed the documentation dependencies:

pip install -r ../../requirements-docs.txt

Building the Docs

  1. Run the following command to build the HTML documentation:

    sphinx-build -b html docs/sdk/python docs/sdk/python/api
    
  2. The generated HTML files will be in the sdk/python/api directory. You can open sdk/python/api/index.html in your browser to view the documentation.