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