Agent Card Reader / Agent card field reference

A2A agent card field reference

An agent card is the JSON document an A2A agent serves at /.well-known/agent-card.json. These tables are generated from the A2A 1.0 specification (§4.4 and §4.5); field names are camelCase in JSON (§5.5), and a required array must hold at least one element (§5.7).

Minimal valid agent card

The specification's own minimal card (§8.4.1). It passes every check in the reader: open it in the reader.

{
  "name": "Example Agent",
  "description": "An example agent that echoes messages.",
  "supportedInterfaces": [
    {
      "url": "https://example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extensions": []
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "skills": [
    {
      "id": "echo",
      "name": "Echo",
      "description": "Echoes the input.",
      "tags": [
        "echo"
      ]
    }
  ]
}

Objects

AgentCard §4.4.1
AgentProvider §4.4.2
AgentCapabilities §4.4.3
AgentExtension §4.4.4
AgentSkill §4.4.5
AgentInterface §4.4.6
AgentCardSignature §4.4.7
SecurityScheme §4.5.1
APIKeySecurityScheme §4.5.2
HTTPAuthSecurityScheme §4.5.3
OAuth2SecurityScheme §4.5.4
OpenIdConnectSecurityScheme §4.5.5
MutualTlsSecurityScheme §4.5.6
OAuthFlows §4.5.7
AuthorizationCodeOAuthFlow §4.5.8
ClientCredentialsOAuthFlow §4.5.9
DeviceCodeOAuthFlow §4.5.10

AgentCard §4.4.1

A self-describing manifest for an agent. It provides essential metadata including the agent's identity, capabilities, skills, supported communication methods, and security requirements.

Field	Type	Required	Description
`name`	string	Yes	A human readable name for the agent. Example: "Recipe Agent"
`description`	string	Yes	A human-readable description of the agent, assisting users and other agents in understanding its purpose. Example: "Agent that helps users with recipes and cooking."
`supportedInterfaces`	array of AgentInterface	Yes	Ordered list of supported interfaces. The first entry is preferred.
`provider`	AgentProvider	No	The service provider of the agent.
`version`	string	Yes	The version of the agent. Example: "1.0.0"
`documentationUrl`	string	No	A URL providing additional documentation about the agent.
`capabilities`	AgentCapabilities	Yes	A2A Capability set supported by the agent.
`securitySchemes`	map of string to SecurityScheme	No	The security scheme details used for authenticating with this agent.
`securityRequirements`	array of SecurityRequirement	No	Security requirements for contacting the agent.
`defaultInputModes`	array of string	Yes	The set of interaction modes that the agent supports across all skills. This can be overridden per skill. Defined as media types.
`defaultOutputModes`	array of string	Yes	The media types supported as outputs from this agent.
`skills`	array of AgentSkill	Yes	Skills represent the abilities of an agent. It is largely a descriptive concept but represents a more focused set of behaviors that the agent is likely to succeed at.
`signatures`	array of AgentCardSignature	No	JSON Web Signatures computed for this AgentCard.
`iconUrl`	string	No	Optional. A URL to an icon for the agent.

AgentProvider §4.4.2

Represents the service provider of an agent.

Field	Type	Required	Description
`url`	string	Yes	A URL for the agent provider's website or relevant documentation. Example: "https://ai.google.dev"
`organization`	string	Yes	The name of the agent provider's organization. Example: "Google"

AgentCapabilities §4.4.3

Defines optional capabilities supported by an agent.

Field	Type	Required	Description
`streaming`	boolean	No	Indicates if the agent supports streaming responses.
`pushNotifications`	boolean	No	Indicates if the agent supports sending push notifications for asynchronous task updates.
`extensions`	array of AgentExtension	No	A list of protocol extensions supported by the agent.
`extendedAgentCard`	boolean	No	Indicates if the agent supports providing an extended agent card when authenticated.

AgentExtension §4.4.4

A declaration of a protocol extension supported by an Agent.

Field	Type	Required	Description
`uri`	string	No	The unique URI identifying the extension.
`description`	string	No	A human-readable description of how this agent uses the extension.
`required`	boolean	No	If true, the client must understand and comply with the extension's requirements.
`params`	object	No	Optional. Extension-specific configuration parameters.

AgentSkill §4.4.5

Represents a distinct capability or function that an agent can perform.

Field	Type	Required	Description
`id`	string	Yes	A unique identifier for the agent's skill.
`name`	string	Yes	A human-readable name for the skill.
`description`	string	Yes	A detailed description of the skill.
`tags`	array of string	Yes	A set of keywords describing the skill's capabilities.
`examples`	array of string	No	Example prompts or scenarios that this skill can handle.
`inputModes`	array of string	No	The set of supported input media types for this skill, overriding the agent's defaults.
`outputModes`	array of string	No	The set of supported output media types for this skill, overriding the agent's defaults.
`securityRequirements`	array of SecurityRequirement	No	Security schemes necessary for this skill.

AgentInterface §4.4.6

Declares a combination of a target URL, transport and protocol version for interacting with the agent. This allows agents to expose the same functionality over multiple protocol binding mechanisms.

Field	Type	Required	Description
`url`	string	Yes	The URL or address where this interface is available. For HTTP-based transports, must be a valid absolute HTTPS URL in production. For gRPC, the address should be in the format "hostname:port". Example: "https://api.example.com/a2a/v1", "grpc.example.com:443"
`protocolBinding`	string	Yes	The protocol binding supported at this URL. This is an open form string, to be easily extended for other protocol bindings. The core ones officially supported are JSONRPC, GRPC and HTTP+JSON.
`tenant`	string	No	Optional. An opaque string used for routing requests to a specific agent or tenant when multiple agents are served behind a single A2A endpoint. When set, clients MUST include this value in the tenant field of all request messages sent to this interface. The server is responsible for interpreting the value and routing requests accordingly; the protocol does not define its format or semantics.
`protocolVersion`	string	Yes	The version of the A2A protocol this interface exposes. Use the latest supported minor version per major version. Examples: "0.3", "1.0"

AgentCardSignature §4.4.7

AgentCardSignature represents a JWS signature of an AgentCard. This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).

Field	Type	Required	Description
`protected`	string	Yes	Required. The protected JWS header for the signature. This is always a base64url-encoded JSON object.
`signature`	string	Yes	Required. The computed signature, base64url-encoded.
`header`	object	No	The unprotected JWS header values.

SecurityScheme §4.5.1

Defines a security scheme that can be used to secure an agent's endpoints. This is a discriminated union type based on the OpenAPI 3.2 Security Scheme Object. See: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object

A SecurityScheme MUST contain exactly one of the following: apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme

Field	Type	Required	Description
`apiKeySecurityScheme`	APIKeySecurityScheme	Optional (OneOf)	API key-based authentication.
`httpAuthSecurityScheme`	HTTPAuthSecurityScheme	Optional (OneOf)	HTTP authentication (Basic, Bearer, etc.).
`oauth2SecurityScheme`	OAuth2SecurityScheme	Optional (OneOf)	OAuth 2.0 authentication.
`openIdConnectSecurityScheme`	OpenIdConnectSecurityScheme	Optional (OneOf)	OpenID Connect authentication.
`mtlsSecurityScheme`	MutualTlsSecurityScheme	Optional (OneOf)	Mutual TLS authentication.

APIKeySecurityScheme §4.5.2

Defines a security scheme using an API key.

Field	Type	Required	Description
`description`	string	No	An optional description for the security scheme.
`location`	string	Yes	The location of the API key. Valid values are "query", "header", or "cookie".
`name`	string	Yes	The name of the header, query, or cookie parameter to be used.

HTTPAuthSecurityScheme §4.5.3

Defines a security scheme using HTTP authentication.

Field	Type	Required	Description
`description`	string	No	An optional description for the security scheme.
`scheme`	string	Yes	The name of the HTTP Authentication scheme to be used in the Authorization header, as defined in RFC7235 (e.g., "Bearer"). This value should be registered in the IANA Authentication Scheme registry.
`bearerFormat`	string	No	A hint to the client to identify how the bearer token is formatted (e.g., "JWT"). Primarily for documentation purposes.

OAuth2SecurityScheme §4.5.4

Defines a security scheme using OAuth 2.0.

Field	Type	Required	Description
`description`	string	No	An optional description for the security scheme.
`flows`	OAuthFlows	Yes	An object containing configuration information for the supported OAuth 2.0 flows.
`oauth2MetadataUrl`	string	No	URL to the OAuth2 authorization server metadata RFC 8414. TLS is required.

OpenIdConnectSecurityScheme §4.5.5

Defines a security scheme using OpenID Connect.

Field	Type	Required	Description
`description`	string	No	An optional description for the security scheme.
`openIdConnectUrl`	string	Yes	The OpenID Connect Discovery URL for the OIDC provider's metadata.

MutualTlsSecurityScheme §4.5.6

Defines a security scheme using mTLS authentication.

Field	Type	Required	Description
`description`	string	No	An optional description for the security scheme.

OAuthFlows §4.5.7

Defines the configuration for the supported OAuth 2.0 flows.

A OAuthFlows MUST contain exactly one of the following: authorizationCode, clientCredentials, implicit, password, deviceCode

Field	Type	Required	Description
`authorizationCode`	AuthorizationCodeOAuthFlow	Optional (OneOf)	Configuration for the OAuth Authorization Code flow.
`clientCredentials`	ClientCredentialsOAuthFlow	Optional (OneOf)	Configuration for the OAuth Client Credentials flow.
`implicit`	ImplicitOAuthFlow	Optional (OneOf)	Deprecated: Use Authorization Code + PKCE instead.
`password`	PasswordOAuthFlow	Optional (OneOf)	Deprecated: Use Authorization Code + PKCE or Device Code.
`deviceCode`	DeviceCodeOAuthFlow	Optional (OneOf)	Configuration for the OAuth Device Code flow.

AuthorizationCodeOAuthFlow §4.5.8

Defines configuration details for the OAuth 2.0 Authorization Code flow.

Field	Type	Required	Description
`authorizationUrl`	string	Yes	The authorization URL to be used for this flow.
`tokenUrl`	string	Yes	The token URL to be used for this flow.
`refreshUrl`	string	No	The URL to be used for obtaining refresh tokens.
`scopes`	map of string to string	Yes	The available scopes for the OAuth2 security scheme.
`pkceRequired`	boolean	No	Indicates if PKCE (RFC 7636) is required for this flow. PKCE should always be used for public clients and is recommended for all clients.

ClientCredentialsOAuthFlow §4.5.9

Defines configuration details for the OAuth 2.0 Client Credentials flow.

Field	Type	Required	Description
`tokenUrl`	string	Yes	The token URL to be used for this flow.
`refreshUrl`	string	No	The URL to be used for obtaining refresh tokens.
`scopes`	map of string to string	Yes	The available scopes for the OAuth2 security scheme.

DeviceCodeOAuthFlow §4.5.10

Defines configuration details for the OAuth 2.0 Device Code flow (RFC 8628). This flow is designed for input-constrained devices such as IoT devices, and CLI tools where the user authenticates on a separate device.

Field	Type	Required	Description
`deviceAuthorizationUrl`	string	Yes	The device authorization endpoint URL.
`tokenUrl`	string	Yes	The token URL to be used for this flow.
`refreshUrl`	string	No	The URL to be used for obtaining refresh tokens.
`scopes`	map of string to string	Yes	The available scopes for the OAuth2 security scheme.

Based on the A2A specification (latest, 1.0). Updated 2026-10-14. Check a card now: open the reader.