A2A vs OpenAPI: handing off a goal or calling a described API

A2A (Agent2Agent) is for handing a goal to an agent run by someone else, which decides how to meet it, and for tracking the resulting task until it ends. OpenAPI is for describing an HTTP API’s operations, parameters, schemas and security precisely enough that developers, code generators and language models can call it correctly.

The two are different kinds of thing. A2A is a protocol: it defines one set of operations that every A2A server supports. OpenAPI is a description format: it documents whatever operations a particular API has. So the practical question is whether a caller should delegate through a standard agent protocol or call your specific, documented operations.

Status as of September 26, 2026. The current OpenAPI Specification is 3.2.1, published September 10, 2026. Version 3.2.0 (with 3.1.2) was published on September 19, 2025, and 3.1.0 on February 15, 2021. The specification is maintained by the OpenAPI Initiative, a Linux Foundation project. A2A is a Linux Foundation project whose current protocol version is 1.0 (release v1.0.1, May 28, 2026).

What OpenAPI is for

The specification calls itself a language-agnostic interface description for HTTP APIs. An OpenAPI description tells a reader:

• Where the API lives: servers.
• What it can do: paths, each with operations such as get or post, parameters, request bodies and responses. From 3.1 onward, schemas use JSON Schema Draft 2020-12.
• How to authenticate: securitySchemes of type apiKey, http, mutualTLS, oauth2 or openIdConnect.
• What it sends back later: callbacks, and top-level webhooks for requests the provider initiates.
• How streams are shaped: since 3.2, sequential media types such as text/event-stream and application/jsonl, with an itemSchema for each item.

The caller picks an operation and fills in typed inputs. The server does exactly that operation. The specification recommends naming the entry document openapi.json or openapi.yaml, but it does not define a discovery location.

A fragment of an illustrative description for a freight quote operation:

{
  "openapi": "3.2.1",
  "info": { "title": "Example Freight Rates API", "version": "1.4.0" },
  "paths": {
    "/rates": {
      "post": {
        "operationId": "getFreightRate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["origin", "destination", "pallets"],
                "properties": {
                  "origin": { "type": "string" },
                  "destination": { "type": "string" },
                  "pallets": { "type": "integer", "minimum": 1 }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "A rate for the requested lane" } }
      }
    }
  }
}

What A2A is for

A2A fixes the operations and lets each agent describe its abilities in prose. Every A2A server supports the same calls, such as SendMessage, GetTask and CancelTask, over JSON-RPC 2.0, gRPC or HTTP+JSON. What differs between agents is in the Agent Card: skills with a description, tags, examples and accepted media types, plus the security schemes a client must use.

A client sends a message: text, files or structured data. The agent creates a task, which can pause to ask for more input (TASK_STATE_INPUT_REQUIRED) or for authorization (TASK_STATE_AUTH_REQUIRED), can be refused (TASK_STATE_REJECTED), and ends with artifacts. The caller never sees the agent’s internal APIs. The same freight request over A2A is a message stating the goal, and the remote agent decides which systems to consult. A2A vs MCP shows that request in full.

The two specifications meet in one place. A2A’s SecurityScheme message is described in its proto as a union based on the OpenAPI 3.2 Security Scheme Object, and its scheme types match OpenAPI’s five.

Side by side

	OpenAPI	A2A
Purpose	Describe an HTTP API so callers can use its operations correctly	Let one agent delegate a goal to another agent and track the task
Layer	Description format for HTTP APIs	Application protocol with a fixed set of operations
Who talks to whom	Any HTTP client and the API it describes	A client agent and a remote agent
Transport	Whatever HTTP the API uses; SSE and JSON Lines describable since 3.2	JSON-RPC 2.0, gRPC or HTTP+JSON; SSE streaming; webhook push
Discovery	Not defined; the entry document is recommended to be named openapi.json or openapi.yaml	Agent Card at /.well-known/agent-card.json, registries or direct configuration
Auth	apiKey, http, mutualTLS, oauth2, openIdConnect	The same five scheme types, declared in the Agent Card; optional card signatures
State	None of its own; the API defines any state	Tasks with a lifecycle; contextId for related work
Governance and status	OpenAPI Initiative (Linux Foundation); 3.2.1, September 10, 2026	Linux Foundation project; version 1.0

When to use OpenAPI

Describe an API with OpenAPI when its operations are deterministic and the caller should choose exactly what happens: create an order, read a balance, update a record. It suits partner integrations, SDK generation, API gateways, testing tools, and model tool calling, where a model is given typed functions derived from the description. State the specification version in the document’s openapi field; the specification says tooling should use that field to decide how to interpret the document, and 3.2 features such as itemSchema for streams need a tool that understands 3.2.

When to use A2A

Use A2A when the outcome depends on the other side’s judgment or policy, when the work may take a while or need a follow-up question, or when you do not want callers wired to your internal endpoints. A refund decision, an insurance quote with underwriting questions, and a freight booking with exceptions are all tasks. A caller that states the goal lets the remote agent change its internals without breaking anyone.

Using both

Most organizations that run an A2A agent will also have OpenAPI-described APIs.

• Behind the agent. The agent calls your APIs, often described with OpenAPI and exposed to its model as tools. Callers see the agent, and the agent sees the APIs.
• Side by side. Publish OpenAPI for integrations that need exact operations, and an Agent Card for outside agents that need to delegate. They serve different callers and can share the same authorization server.
• Describing agent protocols. Some agent protocols publish their HTTP surface in OpenAPI. IBM’s Agent Communication Protocol, now merged into A2A, did, and the Agentic Commerce Protocol publishes its checkout API that way.

Common misconceptions

“OpenAPI is a protocol like A2A.” OpenAPI describes APIs. It does not define what operations exist, what a task is, or how two parties discover each other.

“Give a model your OpenAPI file and you have an agent endpoint.” A model can call the operations you describe. Outside agents still get no task lifecycle, no standard discovery and no agent-level contract unless you also implement one, such as A2A.

“A2A skills are typed like OpenAPI operations.” In A2A v1.0 a skill has an ID, a name, a description, tags, examples and media types. It has no JSON Schema of its own. Structured payloads travel in data parts, and any schema is agreed through documentation or an extension.

“OpenAPI cannot describe asynchronous APIs.” It has callbacks, top-level webhooks since 3.1, and since 3.2 sequential media types such as Server-Sent Events.

“A2A replaces REST APIs.” A2A runs over HTTP and gRPC, and A2A agents usually depend on ordinary APIs to do their work.