https://a2a-protocol.org

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

• 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.

AI agents are a first-class audience for these docs. Alongside the HTML site we publish three plain-text files at the site root:

• llms.txt — a curated index following the llms.txt convention: a short summary plus one-line descriptions of the pages worth reading. Hand-maintained at docs/llms.txt; update it whenever a page is added, renamed, or removed.
• llms-reference.txt — a condensed, non-normative protocol reference (core objects, RPC methods, task states). Hand-maintained at docs/llms-reference.txt; update it when the proto changes. Both files state the released protocol version in their opening lines, so they need a pass at each release.
• llms-full.txt — every doc page, the normative proto, and the Python SDK reference concatenated into one file, with layout-only markup stripped. Generated by scripts/build_llms_full.sh during the docs build and ignored by git, so don't edit or commit it by hand.

scripts/deploy_root_files.sh copies all three, plus robots.txt, to the root of the gh-pages branch. MkDocs also copies them into each versioned site, so /latest/llms.txt works too.

When writing docs, keep them readable without a browser:

• Put content in Markdown. Styling wrappers such as <div class="grid cards"> are fine, and llms-full.txt strips them — but no information should live only inside HTML or a JavaScript widget, because that is what gets dropped.
• Give every diagram a text equivalent: descriptive alt text for images, and a caption or surrounding paragraph that states what the diagram shows.
• Prefer real Markdown headings, lists, and tables over styled <div> blocks.

The Python SDK documentation is built using Sphinx.

Ensure you have installed the documentation dependencies:

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

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.