Agent Card vs OpenAPI document: what each describes and who reads it

An Agent Card is for telling other agents who an A2A agent is, where to reach it, what it can help with and how to authenticate, in one JSON document that every A2A client knows how to read. An OpenAPI document is for describing every operation of an HTTP API, with typed inputs and outputs, so developers, tools and models can call each one correctly.

Both are machine-readable JSON (OpenAPI also allows YAML) and both declare authentication. The difference is what they describe. A card describes an agent that accepts goals through a fixed protocol. An OpenAPI document describes an API whose operations are the interface.

Status as of September 26, 2026. The Agent Card is defined by the A2A specification, a Linux Foundation project at protocol version 1.0; its normative schema is the AgentCard message in a2a.proto. The current OpenAPI Specification is 3.2.1, published September 10, 2026, and maintained by the OpenAPI Initiative, also a Linux Foundation project.

What an Agent Card contains

In A2A v1.0, a card must have name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes and skills. Optional fields include provider, documentationUrl, iconUrl, securitySchemes, securityRequirements and signatures. Illustrative:

{
  "name": "Example Freight Quotes",
  "description": "Quotes and books less-than-truckload freight between Canadian and US cities.",
  "provider": { "organization": "Example Freight Inc.", "url": "https://example.com" },
  "supportedInterfaces": [
    { "url": "https://example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "version": "2.3.0",
  "capabilities": { "streaming": true, "pushNotifications": true },
  "securitySchemes": {
    "partnerOAuth": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.example.com/oauth/token",
            "scopes": { "quotes": "Request freight quotes" }
          }
        }
      }
    }
  },
  "securityRequirements": [{ "schemes": { "partnerOAuth": { "list": ["quotes"] } } }],
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "ltl-quote",
      "name": "LTL freight quote",
      "description": "Quotes a pallet shipment and can hold the rate for 24 hours.",
      "tags": ["freight", "quote"],
      "examples": ["Quote 12 pallets from Toronto to Chicago, pickup Monday"]
    }
  ]
}

A skill says what the agent can help with, in prose, with tags, examples and accepted media types. It has no parameter schema. The client talks to every A2A agent with the same operations, so the card does not list operations at all.

What an OpenAPI document contains

An OpenAPI document must have openapi (the specification version) and info (with at least title and version), plus at least one of paths, components or webhooks. It usually adds servers, and declares authentication in components.securitySchemes and security. Every operation lists its parameters, request body and responses, with JSON Schema describing each payload. Illustrative, reduced to the essentials:

{
  "openapi": "3.2.1",
  "info": { "title": "Example Freight Rates API", "version": "1.4.0" },
  "servers": [{ "url": "https://api.example.com/v1" }],
  "paths": {
    "/rates/{rateId}": {
      "get": {
        "operationId": "getRate",
        "parameters": [{ "name": "rateId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "The stored rate" } }
      }
    }
  }
}

Field by field

Question	Agent Card	OpenAPI document
What it describes	One agent	One HTTP API
Name and version	name, description, version, provider	info.title, info.description, info.version, info.contact, info.license
Where to connect	supportedInterfaces: URL, binding and protocol version	servers, plus each path
What it can do	skills: prose descriptions, tags, examples, media types	paths: operations with typed parameters, bodies and responses
Optional features	capabilities: streaming, pushNotifications, extendedAgentCard, extensions	Callbacks, webhooks, sequential media types such as SSE
Authentication	securitySchemes and securityRequirements	components.securitySchemes and security
Integrity	Optional JWS signatures over the canonicalized card	No signing mechanism in the specification
Discovery	/.well-known/agent-card.json, registries, direct configuration	No defined location; entry document recommended to be named openapi.json or openapi.yaml
Extending it	Extension URIs in capabilities.extensions	Fields prefixed x-
Caching	Servers SHOULD send Cache-Control and an ETag	Not specified
Audience-specific versions	An extended card for authenticated clients via GetExtendedAgentCard	Not specified

The authentication rows line up closely by design. The A2A proto describes its SecurityScheme as a union based on the OpenAPI 3.2 Security Scheme Object, with the same five types: API key, HTTP, OAuth 2.0, OpenID Connect and mutual TLS.

Versioning and change

Both documents carry two kinds of version, and they are easy to mix up.

	Agent Card	OpenAPI document
Version of the standard	protocolVersion on each entry in supportedInterfaces, such as 1.0	The openapi field, such as 3.2.1
Version of your thing	version: the agent’s own version	info.version: the API description’s version

The difference matters when you publish a change. An Agent Card is fetched at run time. The A2A specification says servers should send Cache-Control with a max-age and an ETag derived from the card’s version or content, and clients should revalidate when their copy expires. A new endpoint or security requirement reaches clients within one cache lifetime, so bump version whenever the card changes and keep the old endpoint working until cached copies expire.

An OpenAPI document is usually consumed at build time. Client libraries are generated from it, and gateways and test suites load it when they are deployed. A change reaches callers only when they rebuild, so a breaking change needs a new API version and a period when both versions run.

A signed card adds one more step: every change to a signed field needs a new signature, or careful clients will reject the card.

Who reads each one

An Agent Card is read by client agents and their developers. A client fetches it, picks an interface it supports, checks the capability flags before streaming or registering a webhook, obtains credentials for a declared scheme, and decides from the skills whether to send the task. Registries and directories read it too, and a signed card lets them detect tampering after it leaves your domain.

An OpenAPI document is read by developers and tools. Code generators build client libraries from it, gateways enforce it, test tools exercise it, documentation sites render it, and model tool-calling setups turn its operations into functions.

When to publish each

Publish an Agent Card when you run an A2A agent, whether or not you also have an API. Every A2A server must make one available. It is how outside agents find your endpoint and learn your authentication requirements.

Publish an OpenAPI document for any HTTP API that others integrate with directly, so callers use exact operations and types.

Publish both when you offer both surfaces: an agent for delegated, multi-step work, and an API for precise operations. Keep the provider name, contact details and authorization server consistent across the two, ideally generated from the same source.

Common misconceptions

“An Agent Card is an OpenAPI document for agents.” A card lists no operations. It describes an agent that speaks a protocol whose operations are fixed by the A2A specification.

“Skills should carry JSON Schemas, like operations.” Not in the v1.0 card. If a skill expects a structured payload, say so in its description and examples, accept application/json data parts, and document the shape, or define an A2A extension.

“Putting an OpenAPI file at a well-known path makes it discoverable like a card.” OpenAPI defines no discovery location, and clients will not look there by convention. The Agent Card’s path is a well-known URI in the RFC 8615 sense, and the A2A specification defines it, so A2A clients know to look there.

“Signing a card also covers the API behind it.” A card signature covers the card’s content. It says nothing about responses from the endpoint, and it says nothing about any OpenAPI document you publish.