A2A Agent Card Explained: Schema, JSON Examples and Discovery

TL;DR

• An A2A agent card is the JSON document every A2A server publishes to describe its identity, endpoints, capabilities, skills, and authentication.
• In A2A v1.0 the card is served at /.well-known/agent-card.json, and endpoints live in an ordered supportedInterfaces array whose entries carry url, protocolBinding, and protocolVersion.
• v1.0 removed the top-level url, preferredTransport, and protocolVersion fields and moved the extended card flag into capabilities.
• Bifrost registers an agent by its full card URL, serves a rewritten card with gateway endpoints and gateway authentication, strips upstream signatures, and uses card order to pick the upstream transport.

An A2A agent card is the discovery document an Agent2Agent (A2A) server publishes so other agents can find it, judge whether it fits a task, and learn how to call it. Bifrost, the open-source AI gateway built by Maxim AI, reads agent cards to register A2A agents and serves its own rewritten card to callers. This reference covers the v1.0 schema, three annotated JSON examples, the extended card, signatures, discovery patterns, common mistakes, and what changes behind a gateway.

What Is an A2A Agent Card?

An A2A agent card is a self-describing JSON manifest for an agent. It states the agent's identity, the interfaces where it accepts requests, its optional features, media types, skills, and the security schemes a client must satisfy. The A2A specification requires every server to publish one.

A client agent uses the card for three decisions in order: whether the agent can do the job (skills and modes), how to prove identity (security schemes), and where to send the request (the first supported interface). For the rest of the protocol, see how A2A traffic runs through a gateway.

Figure 1: The card drives every later choice a client makes: which agent, which credential, which endpoint.

The card carries no task state or credentials. Those belong to messages, tasks, and contexts, which start after discovery and which the Agent Gateway in Bifrost records per session.

Where the Agent Card Is Served: The Well-Known Path

The A2A v1.0 agent card is served at https://{agent-server-domain}/.well-known/agent-card.json, following the well-known URI convention in RFC 8615. A client sends an HTTP GET and receives JSON; the spec includes an IANA registration template for this URI.

A2A v0.2.5 used /.well-known/agent.json; v0.3.0 renamed it to agent-card.json. A server answering only on agent.json is not found by clients that follow the current spec.

Card endpoints should send Cache-Control and an ETag so clients can revalidate with If-None-Match. Registering an agent in Bifrost requires the complete card URL, such as https://research.example.com/.well-known/agent-card.json; the base URL alone is not enough.

A2A Agent Card Schema: Every Important Field

The A2A agent card schema in v1.0 has eight required top-level fields: name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes, and skills. Provider, security, documentation, icon, and signature fields are optional. JSON field names are camelCase.

Each interface requires url, protocolBinding (JSONRPC, GRPC, or HTTP+JSON), and protocolVersion, plus an optional tenant. Skills can override default modes and declare their own securityRequirements. Each securitySchemes value wraps exactly one type, such as httpAuthSecurityScheme, and agent authentication through Bifrost reads these declarations to choose which credential fields to request.

A2A Agent Card Examples in JSON

The three examples below are valid JSON matching the A2A v1.0 schema: a minimal card, a card with authentication and two skills, and a card advertising three transports with a signature. All describe the same research agent.

Minimal public agent card

{
  "name": "Library Research Agent",
  "description": "Answers questions about software libraries and APIs.",
  "supportedInterfaces": [
    {"url": "<https://research.example.com/a2a/jsonrpc>", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
  ],
  "version": "1.0.0",
  "capabilities": {},
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {"id": "library-lookup", "name": "Library lookup", "description": "Explains how to use a library API.", "tags": ["libraries"]}
  ]
}

capabilities is required but its fields are optional, so {} declares no streaming, push, or extended card. With no securitySchemes, the agent accepts unauthenticated requests. A Bifrost registration preview shows these skills, interfaces, and capabilities before you save.

Agent card with security schemes and skills

{
  "name": "Library Research Agent",
  "description": "Answers questions about software libraries and APIs.",
  "supportedInterfaces": [
    {"url": "<https://research.example.com/a2a/jsonrpc>", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
  ],
  "provider": {"organization": "Example Platform Team", "url": "<https://platform.example.com>"},
  "version": "1.2.0",
  "capabilities": {"streaming": true, "pushNotifications": true, "extendedAgentCard": true},
  "securitySchemes": {
    "agentBearer": {"httpAuthSecurityScheme": {"scheme": "Bearer", "bearerFormat": "JWT"}},
    "agentOAuth": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "<https://auth.example.com/oauth/token>",
            "scopes": {"research.read": "Ask questions", "research.reports": "Generate reports"}
          }
        }
      }
    }
  },
  "securityRequirements": [
    {"schemes": {"agentBearer": {"list": []}}},
    {"schemes": {"agentOAuth": {"list": ["research.read"]}}}
  ],
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "library-lookup", "name": "Library lookup",
      "description": "Explains how to use a library API.", "tags": ["libraries"],
      "examples": ["How do I reuse one HTTP client in Go?"]
    },
    {
      "id": "compatibility-report", "name": "Compatibility report",
      "description": "Compares two versions of a dependency.", "tags": ["dependencies", "reports"],
      "outputModes": ["text/markdown"],
      "securityRequirements": [{"schemes": {"agentOAuth": {"list": ["research.reports"]}}}]
    }
  ]
}

Following OpenAPI convention, the two top-level securityRequirements entries are alternatives: a bearer token, or an OAuth token with research.read. Schemes inside one schemes object must all be satisfied.

Agent card advertising multiple transports

{
  "name": "Library Research Agent",
  "description": "Answers questions about software libraries and APIs.",
  "supportedInterfaces": [
    {"url": "<https://research.example.com/a2a/jsonrpc>", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"},
    {"url": "research.example.com:443", "protocolBinding": "GRPC", "protocolVersion": "1.0"},
    {"url": "<https://research.example.com/a2a/rest>", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}
  ],
  "version": "1.2.0",
  "capabilities": {"streaming": true},
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {"id": "library-lookup", "name": "Library lookup", "description": "Explains how to use a library API.", "tags": ["libraries"]}
  ],
  "signatures": [
    {
      "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJyZXNlYXJjaC1jYXJkLTIwMjYiLCJqa3UiOiJodHRwczovL3Jlc2VhcmNoLmV4YW1wbGUuY29tLy53ZWxsLWtub3duL2p3a3MuanNvbiJ9",
      "signature": "REPLACE_WITH_BASE64URL_ES256_SIGNATURE"
    }
  ]
}

Interface order is preference order. The gRPC url is a bare host:port, as the spec requires. The signature value is a placeholder for your key's output.

The Authenticated Extended Agent Card

The authenticated extended card is a more detailed card an agent returns only to authenticated clients. The public card advertises it with capabilities.extendedAgentCard: true, and clients call GetExtendedAgentCard after authenticating with a scheme the public card declares.

If the flag is absent, the call must return UnsupportedOperationError; if it is set but no extended card exists, ExtendedAgentCardNotConfiguredError. The v0.3 field supportsAuthenticatedExtendedCard is gone. Agent Logs in Bifrost record GetAgentCard and GetExtendedAgentCard separately, so teams can audit who fetched the detailed card.

Agent Card Signatures

A card signature is a JSON Web Signature (JWS) that lets a client verify the card is unaltered and came from the claimed provider. Each entry in the optional signatures array carries a base64url protected header, a signature, and an optional header.

To sign, remove fields set to default values, exclude signatures, canonicalize with the JSON Canonicalization Scheme in RFC 8785, and sign with the algorithm in the protected header, which must include alg, typ, and kid and may include jku. Verifiers repeat the canonicalization; multiple signatures support key rotation.

Any intermediary that edits the card invalidates its signature, so governance at the agent layer needs a clear rule for which card a client trusts.

Agent Discovery Patterns: Well-Known URL, Registries, Direct Config

A2A defines three ways to find a card: fetching the well-known URI on the agent's domain, querying a curated registry, or reading a URL from direct configuration. All three end in the same JSON document.

Figure 2: Discovery patterns differ only in how the client finds the card; the card itself is the same document.

The A2A agent discovery guide notes that no standard registry API exists yet. A gateway that serves registered cards behind access control works as a governed catalog: callers reach only agents their virtual keys are granted, a role covered in choosing an agent gateway.

Common Agent Card Mistakes

Most card failures come from v0.3 to v1.0 drift, unreachable endpoints, or sensitive data in a public document. These mistakes most often break discovery or registration.

The last row matters when a gateway switches transports: transport recovery in Bifrost does not copy task state between endpoints. An unapproved runtime origin is another frequent agent registration error.

How Bifrost Serves a Rewritten Agent Card

Bifrost, the AI gateway, registers an A2A agent from its full card URL and serves its own card to callers. On each request to the gateway card URL, Bifrost fetches the current upstream card, rewrites its interfaces to gateway endpoints and its authentication to gateway authentication, removes upstream signatures, and returns the result.

Figure 3: Clients discover gateway routes, never the agent server's own addresses or credentials.

• Separate credentials. Card fetch options authenticate only the card request; request authentication is pre-selected from the card's requirements, with a manual override.
• Origin checks. The card's origin is permitted automatically; runtime endpoints on other origins need approval, and private addresses need the Private Network Allowlist.
• Gateway card URL. Clients use /agents/a2a/{name}/.well-known/agent-card.json, which needs the External Client URL set; otherwise it returns 503.
• No stale copy. The served card is fetched live; if the upstream fetch fails, the client gets an error.

Signatures are removed because the rewrite invalidates them; the registration preview still shows the originals. Agent access grants control who can call the agent, as part of AI governance in Bifrost; an agent grant does not authorize the agent's own model or tool calls. The Agent Gateway launch post covers the design.

How Card Order Sets the Upstream Transport

In Bifrost, the order of supportedInterfaces in the upstream agent card sets the initial transport preference. Bifrost keeps interfaces with a supported A2A v1 version, binding (JSONRPC, HTTP+JSON, or GRPC), and valid endpoint, orders them by protocol version, and preserves card order among equal versions.

Figure 4: Put the preferred interface first; Bifrost retries on another interface only when the endpoint was not reached or cannot serve the operation.

No rule prefers gRPC or matches the caller's transport; to change preference, edit the upstream card. Failover follows the card:

• A dial failure, HTTP 404, 405, 410, 426, method-not-found, or gRPC Unimplemented tries the next candidate.
• HTTP 5xx or an ambiguous failure returns the error without replay, since a task may have started.
• Streaming operations are never replayed automatically.
• Statuses suggesting a stale address trigger a throttled background card refresh.

For the wider architecture, compare an agent gateway with an LLM gateway and review enterprise agent gateway criteria.

Frequently Asked Questions

What is an agent card in A2A?

An agent card is the JSON discovery document every A2A server must publish. It lists the agent's name, description, version, ordered interfaces, optional capabilities, media types, skills, and security schemes. Clients read it before sending any A2A message or task.

Where is the A2A agent card located?

In A2A v1.0 the agent card lives at https://{domain}/.well-known/agent-card.json, under the RFC 8615 well-known URI convention. Clients can also use a registry or a configured URL. Bifrost serves a rewritten card at its own gateway endpoint, such as /agents/a2a/{name}/.well-known/agent-card.json.

What is the difference between agent.json and agent-card.json?

/.well-known/agent.json is the path from A2A v0.2.5. Version 0.3.0 renamed it to /.well-known/agent-card.json, and v1.0 keeps that path. Servers should serve agent-card.json.

What fields are required in an A2A agent card?

A v1.0 agent card requires name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes, and skills. Each interface requires url, protocolBinding, and protocolVersion, and each skill requires id, name, description, and tags. Provider, security schemes, documentation URL, icon, and signatures are optional.

Should an agent card contain API keys or secrets?

No. The card declares which authentication schemes an agent accepts, never the credentials. The A2A specification recommends out-of-band dynamic credentials over static secrets. Sensitive skills or internal endpoints belong in the authenticated extended card or behind access control on the card endpoint, using mTLS, network restrictions, or OAuth.

Why does a gateway-served agent card have no signatures?

A gateway that rewrites endpoints and authentication changes the signed content, so the upstream JWS no longer verifies. Bifrost removes the original signatures instead of serving signatures that would fail. The upstream signatures stay visible in the registration preview, and raw HTTP capture can preserve the original document when enabled.

Getting Started with Agent Cards in Bifrost

A correct A2A agent card uses v1.0 fields, the right well-known path, ordered interfaces that share task state, and no secrets. Bifrost then registers the agent, serves a gateway card behind access controls, and logs agent traffic next to model calls and the tool calls that run through the MCP gateway. Start with agent registration, then book a demo to see how Bifrost governs agent cards and A2A traffic for enterprise teams.