Modeling A2A with the x-a2a Extension

The x-a2a extension is a vendor extension used in OpenAPI documents to model A2A (Application-to-Application) operations. It holds specific metadata such as version, binding, endpoint, method, Agent Card URL, explicit request and response contracts, and examples. This extension is not a standard OpenAPI keyword, so the x- prefix signifies that it is additional metadata.

The version, binding, and Agent Card URL are unique to the protocol, while the request and response contracts need explicit shapes that match the JSON-RPC structure. By using a vendor extension, these details have a named home, avoiding the assumption that they are part of the standard. The x- prefix is the OpenAPI convention for this, signaling that the data is tool-specific metadata and distinguishing it from the core specification.

The extension provides several benefits during building and debugging. It helps confirm that the version and binding are a supported pair, builds the request using the endpoint and method, attaches the A2A-Version header, asserts against explicit request and response contracts, and uses examples to verify expected shapes. This ensures that the generated request body remains grounded in the record and that a 200 response carrying a JSON-RPC error remains visible within the declared response.

It is crucial to understand that the x-a2a extension is not a standard keyword, and tools that do not recognize the extension will simply ignore it. The metadata does not certify runtime behavior; instead, it organizes the A2A surface for review and testing. The actual validation comes from executing the calls. The extension provides organized metadata that supports building and debugging, while real verification is still necessary. This boundary separates the static record from guaranteeing the behavior.