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>
65 lines
1.9 KiB
Bash
Executable File
65 lines
1.9 KiB
Bash
Executable File
#!/bin/bash
|
|
set -e # Exit immediately if a command exits with a non-zero status.
|
|
|
|
# --- Configuration ---
|
|
PACKAGE_NAME="a2a" # The name of the package to import
|
|
PYPI_PACKAGE_NAME="a2a-sdk" # The name on PyPI
|
|
DOCS_SOURCE_DIR="docs/sdk/python"
|
|
DOCS_BUILD_DIR="${DOCS_SOURCE_DIR}/_build"
|
|
VENV_DIR=".doc-venv"
|
|
|
|
echo "--- Setting up documentation build environment ---"
|
|
|
|
# Create a clean virtual environment
|
|
if [ -d "$VENV_DIR" ]; then
|
|
rm -rf "$VENV_DIR"
|
|
fi
|
|
python3 -m venv "$VENV_DIR"
|
|
source "$VENV_DIR/bin/activate"
|
|
|
|
echo "--- Installing package and dependencies ---"
|
|
|
|
# Upgrade pip and install documentation requirements
|
|
pip install -U pip
|
|
pip install -r "requirements-docs.txt"
|
|
|
|
# Install the package itself
|
|
pip install "${PYPI_PACKAGE_NAME}"
|
|
|
|
echo "--- Finding installed package path ---"
|
|
|
|
# Find the installation path of the package
|
|
PACKAGE_PATH=$(python -c "import ${PACKAGE_NAME}, os; print(os.path.dirname(${PACKAGE_NAME}.__file__))")
|
|
echo "Found '${PACKAGE_NAME}' at: ${PACKAGE_PATH}"
|
|
|
|
echo "--- Generating API documentation source files (.rst) ---"
|
|
|
|
# Run sphinx-apidoc on the installed package directory
|
|
# -f: force overwrite of existing files
|
|
# -e: put each module on its own page
|
|
sphinx-apidoc -f -e -o "${DOCS_SOURCE_DIR}" "${PACKAGE_PATH}"
|
|
|
|
echo "--- Building HTML documentation ---"
|
|
|
|
# Build the HTML documentation
|
|
sphinx-build -b html "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/html"
|
|
|
|
echo "--- Copying SDK docs to MkDocs integration path ---"
|
|
|
|
# Copy SDK docs to where MkDocs expects them (docs/sdk/python/api/)
|
|
SDK_API_DIR="${DOCS_SOURCE_DIR}/api"
|
|
if [ -d "${DOCS_BUILD_DIR}/html" ]; then
|
|
rm -rf "${SDK_API_DIR}"
|
|
cp -r "${DOCS_BUILD_DIR}/html" "${SDK_API_DIR}"
|
|
echo "SDK docs copied to: ${SDK_API_DIR}"
|
|
else
|
|
echo "Warning: SDK docs build directory not found at ${DOCS_BUILD_DIR}/html"
|
|
fi
|
|
|
|
# Deactivate the virtual environment
|
|
deactivate
|
|
|
|
echo ""
|
|
echo "✅ Documentation build complete!"
|
|
echo "View the docs by opening: ${SDK_API_DIR}/index.html"
|