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>
74 lines
2.4 KiB
Bash
Executable File
74 lines
2.4 KiB
Bash
Executable File
#!/bin/bash
|
|
set -euo pipefail
|
|
|
|
# Unified docs build script that ensures the non-normative JSON artifact is
|
|
# regenerated (if stale) before invoking MkDocs. Uses pure shell.
|
|
|
|
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
|
|
SCHEMA_JSON="$ROOT_DIR/specification/json/a2a.json"
|
|
PROTO_SRC="$ROOT_DIR/specification/grpc/a2a.proto"
|
|
SPEC_SITE_DIR="$ROOT_DIR/docs/spec"
|
|
SCHEMA_JSON_SITE_FILE="$SPEC_SITE_DIR/a2a.json"
|
|
PROTO_SITE_FILE="$SPEC_SITE_DIR/a2a.proto"
|
|
PROTO_TO_SCHEMA_SCRIPT="$ROOT_DIR/scripts/proto_to_json_schema.sh"
|
|
|
|
regen_needed() {
|
|
if [ ! -f "$SCHEMA_JSON" ]; then return 0; fi
|
|
|
|
local proto_mtime
|
|
local schema_mtime
|
|
if [[ "$(uname)" == "Darwin" ]]; then
|
|
proto_mtime=$(stat -f %m "$PROTO_SRC")
|
|
schema_mtime=$(stat -f %m "$SCHEMA_JSON")
|
|
else
|
|
proto_mtime=$(stat -c %Y "$PROTO_SRC")
|
|
schema_mtime=$(stat -c %Y "$SCHEMA_JSON")
|
|
fi
|
|
[ "$proto_mtime" -gt "$schema_mtime" ]
|
|
}
|
|
|
|
echo "[build_docs] Checking schema freshness..." >&2
|
|
if regen_needed; then
|
|
echo "[build_docs] Regenerating a2a.json from proto" >&2
|
|
if [ -x "$PROTO_TO_SCHEMA_SCRIPT" ]; then
|
|
bash "$PROTO_TO_SCHEMA_SCRIPT" "$SCHEMA_JSON" || {
|
|
echo "[build_docs] Warning: proto to JSON schema conversion failed" >&2
|
|
}
|
|
else
|
|
echo "[build_docs] proto_to_json_schema.sh missing or not executable; skipping schema generation." >&2
|
|
fi
|
|
else
|
|
echo "[build_docs] Schema is up-to-date, skipping regeneration" >&2
|
|
fi
|
|
|
|
# Always ensure spec files are available in docs directory for MkDocs
|
|
mkdir -p "$SPEC_SITE_DIR"
|
|
|
|
if [ -f "$SCHEMA_JSON" ]; then
|
|
cp "$SCHEMA_JSON" "$SCHEMA_JSON_SITE_FILE"
|
|
echo "[build_docs] Published schema to $SCHEMA_JSON_SITE_FILE" >&2
|
|
else
|
|
echo "[build_docs] Warning: Schema file not found at $SCHEMA_JSON - MkDocs may fail" >&2
|
|
fi
|
|
|
|
if [ -f "$PROTO_SRC" ]; then
|
|
cp "$PROTO_SRC" "$PROTO_SITE_FILE"
|
|
echo "[build_docs] Published proto to $PROTO_SITE_FILE" >&2
|
|
else
|
|
echo "[build_docs] Warning: Proto file not found at $PROTO_SRC" >&2
|
|
fi
|
|
|
|
# Build SDK documentation
|
|
echo "[build_docs] Building SDK documentation..." >&2
|
|
SDK_DOCS_SCRIPT="$ROOT_DIR/scripts/build_sdk_docs.sh"
|
|
if [ -x "$SDK_DOCS_SCRIPT" ]; then
|
|
bash "$SDK_DOCS_SCRIPT" || echo "[build_docs] Warning: SDK docs build failed" >&2
|
|
else
|
|
echo "[build_docs] SDK docs script not found or not executable: $SDK_DOCS_SCRIPT" >&2
|
|
fi
|
|
|
|
echo "[build_docs] Building MkDocs site..." >&2
|
|
mkdocs build "$@"
|
|
echo "[build_docs] Done." >&2
|