Modeling A2A with the x-a2a Extension
Quick answer: The x-a2a extension models an A2A operation inside an OpenAPI document, holding the version, binding, endpoint, method, Agent Card URL, explicit request and response contracts, and examples. It is a vendor extension, not a standard OpenAPI keyword, so the x- prefix signals that it is extra metadata rather than part of the core specification. Keeping the details explicit makes the A2A surface reviewable instead of implied.
Why a vendor extension
A2A details do not all fit into standard OpenAPI fields. The version, the binding, and the Agent Card URL are specific to the protocol, and the request and response need explicit contracts that match the JSON-RPC shape. A vendor extension gives those details a named home without pretending they are standard.
The x- prefix is the OpenAPI convention for this. It marks the data as additional, tool-specific metadata, and a reader can tell at once where the standard document ends and the extension begins.
What the extension holds
| Field | Role |
|---|---|
| Version | The A2A version, such as 1.0 or 0.3 |
| Binding | JSON-RPC, REST, or gRPC |
| Endpoint | Where the request is sent |
| Method | The A2A method being called |
| Agent Card URL | The explicit card discovery URL |
| Request/response contracts | Explicit shapes for the operation |
| Examples | Worked examples for review |
Because the version and binding are named together, an unsupported pair can be caught rather than silently translated, and the card URL keeps discovery tied to the same record.
Consider an operation modeled as a 1.0 JSON-RPC call. The extension names the version as 1.0, the binding as JSON-RPC, the method and endpoint, and the card URL, and it attaches the explicit contracts plus a worked example. When the desktop builds the request, it reads those fields rather than prompting for a guess, and the version header is attached from the record. If someone changes the binding to REST while the version stays 0.3, the unsupported pair is caught at the record rather than sent and rejected. Keeping the version and binding next to each other is what makes that check possible, and the examples give a reviewer a concrete shape to compare against the real agent.
How it supports building and debugging
The extension feeds the Debug surface rather than living as documentation alone.
- Read the version and binding and confirm they are a supported pair.
- Use the endpoint and method to build the request.
- Attach the
A2A-Versionheader. - Assert against the explicit request and response contracts.
- Use the examples to confirm the expected shapes.
This keeps the generated request body grounded in the record, and it makes a 200 that carries a JSON-RPC error visible against the declared response rather than hidden behind the transport status.
Honest limits
Because x-a2a is not a standard keyword, a tool that does not know the extension will simply ignore it rather than interpret it, and the metadata does not certify the runtime behavior. The contracts describe what the operation should look like, and they still need real verification against the agent. A modeled operation is not a confirmed one.
This is the same boundary that keeps a static record from being written as a guarantee. The extension organizes the A2A surface so it can be reviewed and tested, and the actual verdict comes from executing the calls.
Powerduck keeps the extension in the document as structured metadata, with the limits and the later verification kept separate.
Frequently asked questions
Is x-a2a part of the OpenAPI standard? No. It is a vendor extension, and the x- prefix marks it as tool-specific metadata.
What does it capture? Version, binding, endpoint, method, card URL, explicit contracts, and examples for an A2A operation.
Does modeling the operation verify it? No. The record supports building and debugging, but the behavior still needs real calls and assertions.
The bottom line
The x-a2a extension gives A2A operations a named, reviewable home in an OpenAPI document, carrying the version, binding, endpoint, method, card URL, explicit contracts, and examples. It stays a vendor extension rather than a standard keyword, and it does not certify runtime behavior. Its value is organized metadata that feeds the Debug surface and later verification, not a proof by itself. Naming the details is what keeps the A2A surface honest. Read more in the A2A guide.