Schema reference · 14 fieldsA2A v1.0
An Agent Card is the standardized JSON document that tells A2A clients who an agent is, where to reach it, what it can do, and how access is secured. This reference covers every v1.0 field with types, requirements, examples, and the mistakes validators catch most often.
How discovery works
An A2A client fetches the Agent Card from the well-known URI, evaluates skills, capabilities, and security requirements against its task, then calls the preferred interface — the first entry in supportedInterfaces. If capabilities.extendedAgentCard is true, authenticated clients can request a richer Agent Card through the GetExtendedAgentCard operation.
The spec registers /.well-known/agent-card.json as the standard location. Older v0.x deployments used /.well-known/agent.json, which is why our validator checks both.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Field reference
Required flags follow the v1.0 protobuf definitions in the official specification. Anchor links make each field citable from issues, reviews, and CI output.
Human-readable name of the agent.
Shown in marketplace listings and client UIs. Keep it short and specific — clients use it as the primary label when comparing candidate agents.
Common mistake: Using a generic name like "AI Assistant" that gives routing systems nothing to differentiate on.
"name": "GeoSpatial Route Planner Agent"
What the agent does and when another agent should call it.
This is the main free-text signal for both human integrators and LLM-based routers deciding whether your agent fits a task. State the task domain, key abilities, and boundaries.
Common mistake: One-line descriptions under 20 characters. Routers cannot match what you do not describe.
"description": "Provides advanced route planning, traffic analysis, and custom map generation services."
Ordered list of endpoints and protocol bindings. The first entry is preferred.
New in v1.0: replaces the old top-level url, preferredTransport, and additionalInterfaces fields. Each entry declares its own url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, or a custom binding URI), protocolVersion, and an optional tenant routing key — so one agent can serve multiple protocol versions and transports simultaneously.
Common mistake: Declaring a binding the server does not actually serve at that URL — the spec requires each entry to be accurate.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Who operates the agent: organization and website.
Trust signal for marketplaces and enterprise audits. v1.0 renamed the name field to organization; url is required inside the object when present.
Common mistake: Still using provider.name (pre-1.0). Validators reading v1.0 Agent Cards will not recognize it.
"provider": {
"organization": "Example Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}The version of the agent itself, not the protocol.
Lets clients detect when an Agent Card has materially changed and re-evaluate compatibility. Follow your own release scheme, typically semver.
Common mistake: Confusing this with the A2A protocol version — that now lives on each supportedInterfaces entry.
"version": "1.2.0"
Link to human-readable documentation for the agent.
Give integrators a place to read the full API contract, rate limits, and terms that do not belong in a discovery document.
Common mistake: Pointing at a marketing homepage instead of technical documentation.
"documentationUrl": "https://docs.example.com/agent"
Protocol feature flags: streaming, pushNotifications, extensions, extendedAgentCard.
Clients MUST NOT call features you did not declare — undeclared streaming calls return errors. extendedAgentCard: true advertises a richer authenticated Agent Card via the GetExtendedAgentCard operation. v1.0 removed stateTransitionHistory.
Common mistake: Declaring streaming: true when the server has no streaming endpoint. Clients will call it and fail.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Named authentication schemes: API key, HTTP auth, OAuth 2.0, OpenID Connect, or mutual TLS.
Each named scheme wraps one concrete scheme object (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Clients discover how to authenticate from here — credentials themselves are always obtained out-of-band.
Common mistake: Embedding an actual API key or token in the Agent Card. An Agent Card is a public document.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Which declared schemes (and scopes) are required to call the agent.
Each entry maps a scheme name from securitySchemes to the scopes it needs, mirroring the OpenAPI security requirement pattern. Omit both fields entirely for intentionally public agents.
Common mistake: Declaring securitySchemes but no security requirements, leaving clients to guess whether auth is enforced.
"security": [{ "google": ["openid", "profile", "email"] }]Media types the agent accepts across all skills.
Standard MIME types such as text/plain, application/json, or image/png. Individual skills can override with their own inputModes.
Common mistake: Omitting the field. It is required in v1.0 — clients need it to shape requests.
"defaultInputModes": ["application/json", "text/plain"]
Media types the agent returns across all skills.
Tells callers whether to expect prose, structured JSON, images, or files. Skills can override per-skill with outputModes.
Common mistake: Listing only text/plain when the agent actually returns structured artifacts.
"defaultOutputModes": ["application/json", "image/png"]
The concrete abilities the agent is likely to succeed at.
Each skill requires id, name, description, and tags; examples, per-skill modes, and per-skill security are optional. Skills are the unit of discovery — routers match tasks against them, so scope each one to a single task boundary.
Common mistake: Skills without tags. Tags became required in v1.0 and drive skill-level matching.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Traffic-Aware Route Optimizer",
"description": "Calculates optimal driving routes using real-time traffic...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Plan a route from A to B avoiding tolls."]
}]JSON Web Signatures proving the Agent Card was issued by the provider.
Each signature carries a base64url protected JWS header and signature value, computed over the RFC 8785 (JCS) canonicalized Agent Card. Clients SHOULD verify at least one signature before trusting an Agent Card fetched from the open web.
Common mistake: Signing the card and then editing any field — even whitespace-insignificant value changes invalidate the JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL to an icon representing the agent.
Used by catalogs and client UIs. Serve it over HTTPS from a stable location.
Common mistake: Linking an icon on a different, untrusted domain that can change out from under your listing.
"iconUrl": "https://agent.example.com/icon.png"
Version migration
If your Agent Card still has a top-level url or preferredTransport, it predates v1.0. The validator flags each of these automatically.
| v0.x field | v1.0 replacement | Why it changed |
|---|---|---|
| url | supportedInterfaces[0].url | The preferred endpoint is now simply the first interface entry. |
| preferredTransport | supportedInterfaces[] ordering | Preference is expressed by array order instead of a separate field. |
| additionalInterfaces | supportedInterfaces[] | All interfaces live in one ordered array. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Each interface declares its own protocol version, enabling multi-version support. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Moved into the capabilities object; the RPC was renamed to GetExtendedAgentCard. |
| provider.name | provider.organization | Renamed for clarity. |
| capabilities.stateTransitionHistory | — removed | Not part of v1.0; model equivalent behavior as an extension if needed. |
Boilerplate
Drop these interfaces into a client, server, or CI check to parse and produce Agent Cards with type safety. They mirror the protobuf definitions in the official spec repository, in the camelCase JSON form Agent Cards are published in.
Building an Agent Card by hand instead? The generator produces this exact shape.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Integrity
Because Agent Cards are fetched from the open web, v1.0 formalizes signing: the Agent Card (minus the signatures field and default values) is canonicalized with RFC 8785 JSON Canonicalization, then signed as a JWS. Clients should verify at least one signature — via the kid/jku header or a trusted key store — before acting on an Agent Card. Multiple signatures support key rotation.
Serve the Agent Card at /.well-known/agent-card.json over HTTPS.
Every supportedInterfaces entry is reachable and speaks the declared binding.
Skills have required tags plus descriptions with clear task boundaries.
Declared capabilities match the server — undeclared features must return errors, declared ones must work.
securitySchemes describe how to authenticate; no credentials appear anywhere in the Agent Card.
version is bumped whenever the Agent Card content changes.
A customer-support agent with OAuth 2.0, streaming, and push notifications — every required field present. More patterns live in the examples library.
{
"name": "Customer Support Agent",
"description": "Answers customer support questions, retrieves order context, and escalates unresolved issues to a human team.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Example Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Resolve customer support request",
"description": "Classifies a customer support request, gathers needed context, proposes a resolution, and escalates when confidence is low.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Help me return my order."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}FAQ
The version changes, discovery fields, and publishing details that decide whether an Agent Card passes review.
v1.0 consolidated url, preferredTransport, and additionalInterfaces into one ordered supportedInterfaces array where each entry declares its own url, protocolBinding, and protocolVersion. supportsAuthenticatedExtendedCard moved to capabilities.extendedAgentCard, provider.name became provider.organization, skill tags became required, and JWS Agent Card signatures were formalized with RFC 8785 canonicalization.
No. An Agent Card is a discovery document for an agent. It summarizes identity, interfaces, capabilities, skills, modes, provider, and security metadata, while a full API schema describes detailed request and response shapes. It plays the role a README or OpenAPI overview plays for a service: enough to decide whether and how to call it.
name, description, supportedInterfaces, skills (with tags), defaultInputModes, defaultOutputModes, capabilities, provider, and security metadata. Routing systems match tasks against your description and skill tags, then use interfaces and capabilities to plan the actual call.
Only publish skills that are safe for unauthenticated discovery. If a richer private Agent Card is needed, set capabilities.extendedAgentCard to true and expose sensitive skills through the authenticated GetExtendedAgentCard operation.
At the well-known URI https://{your-domain}/.well-known/agent-card.json, served with content type application/a2a+json (application/json also works in practice). Earlier implementations used /.well-known/agent.json, so publishing both during the transition is a pragmatic choice.
Put the schema to work
Generate a v1.0-shaped Agent Card from your service details, or paste an existing Agent Card into the validator to see exactly which of these fields need attention.