## 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>
5.7 KiB
Custom Protocol Bindings
The A2A protocol ships with three standard bindings (JSON-RPC, gRPC, and HTTP+JSON/REST) that cover the majority of deployment scenarios. Custom protocol bindings let implementers expose A2A operations over additional transport mechanisms not covered by the standard set.
Custom protocol bindings are a complementary but distinct concept to Extensions. Extensions modify the behavior of protocol interactions by adding new data, methods, or state transitions on top of an existing transport. Custom protocol bindings change the transport layer itself—for example, exposing A2A over WebSockets for low-latency bidirectional communication, or over MQTT for IoT environments with constrained connectivity.
Declaration in the Agent Card
Custom protocol bindings are declared in the Agent Card's supportedInterfaces
list. Each entry identifies the transport by URI, the endpoint URL, and the A2A
protocol version it implements. The protocolBinding field should be a URI that uniquely identifies the
binding (see Section 5.8 of the specification
for the normative requirement and versioning guidance).
{
"supportedInterfaces": [
{
"url": "wss://agent.example.com/a2a/websocket",
"protocolBinding": "https://a2a-protocol.org/bindings/websocket",
"protocolVersion": "1.0"
}
]
}
Agents that support multiple bindings list all of them. Clients parse
supportedInterfaces in order and select the first transport they support, so
entries should be listed in preference order.
Requirements
Custom protocol bindings must comply with all requirements in the Protocol Binding Requirements and Interoperability section of the specification. In particular:
- All core operations must be supported. The binding must expose every operation defined in the abstract operations layer (send message, get task, cancel task, streaming, push notifications, etc.).
- The data model must be preserved. All data structures must be functionally equivalent to the canonical Protocol Buffer definitions. JSON serializations must use camelCase field names, and timestamps must be ISO 8601 strings in UTC.
- Behavior must be consistent. Semantically equivalent requests must produce semantically equivalent results regardless of which binding is used.
Key Areas to Specify
A custom binding specification must address each of the following areas.
Data Type Mappings
Document how each Protocol Buffer type is represented in the custom transport, including:
- Binary data encoding (e.g., base64 for text-based transports)
- Enum representation (strings, integers, or named constants)
- Timestamp format (ISO 8601 strings in UTC per the core convention)
Service Parameters
Service parameters are key-value pairs used to carry horizontally applicable context such as tracing identifiers or authentication hints. The binding specification must state:
- The mechanism used to carry service parameters (e.g., custom message headers, a top-level metadata field)
- Any character encoding or size constraints on keys and values
- Any names reserved by the binding itself
For transports that lack native header support, a common pattern is to embed
service parameters as a JSON object in a dedicated metadata field, for example
a2a-service-parameters.
Error Mapping
The binding must map all A2A error types to transport-native error
representations while preserving their semantic meaning. Provide a mapping
table equivalent to the one in the specification's
Error Code Mappings section, showing
how each A2A error type (e.g., TaskNotFoundError, UnsupportedOperationError) is expressed in the custom binding's native error format.
Streaming
If the transport supports streaming, document:
- The stream mechanism (e.g., WebSocket frames, chunked encoding, long polling)
- Ordering guarantees (events must be delivered in the order they were generated)
- Reconnection behavior when a connection is interrupted
- How stream completion or termination is signaled to the client
If the transport does not support streaming, state this limitation clearly in the Agent Card so clients can fall back to polling.
Authentication and Authorization
Document how authentication credentials declared in the Agent Card are transmitted using the custom transport. Define how authentication challenges are communicated to clients and ensure the custom binding does not inadvertently bypass the agent's primary security controls.
Interoperability Testing
Before publishing a custom binding, verify that:
- All operations behave identically to the standard bindings for the same logical requests
- Error conditions, large payloads, and long-running tasks are handled correctly
- Any intentional deviations from standard binding behavior are clearly documented
- Sample requests and responses are included in the specification to help implementers
Governance
The A2A organization uses a formal governance framework for how custom protocol
bindings are proposed, developed, promoted, and maintained. Official bindings
use the https://a2a-protocol.org/bindings/ URI prefix and are hosted under
the a2aproject organization with the cpb- repository prefix (experimental
bindings use experimental-cpb-). A2A SDKs SHOULD implement official custom
protocol bindings.
For the full governance process—including tiers, lifecycle, SDK support, and legal requirements—see the Extension and Protocol Binding Governance page.