Agent contract specification

This page specifies the structure of the agent contract: the object an agent publishes so the orchestrator can discover and route to it.

The contract is the standard A2A AgentCard, version 0.3. It describes an agent’s identity, how to reach it, and what it can do. Agent Console does not extend or replace this schema, so the authoritative definition is the A2A specification. This page summarises the fields most relevant to building an agent for Agent Console. For a conceptual overview of how the contract is used, see Understanding agent registration.

The card does not describe the tools an agent may call or the permissions it holds. Tool access is governed separately, through the agent’s LiteLLM virtual key, and is not part of the contract. Do not expect fields for tools, permissions, or model selection in the card.

Serving the contract

Each agent serves its own card as JSON at /.well-known/agent-card.json. The route is implemented by the agent itself.

The well-known path changed between A2A versions. In v0.2 the card was served at /.well-known/agent.json and the route was configured automatically by the SDK’s A2AExpressApp helper. In v0.3 the path is /.well-known/agent-card.json, and because A2AExpressApp is deprecated (and removed in v1.0), the agent registers the route itself.

AgentCard object

The top-level object published by every agent. Fields are listed in specification order.

Field Type Required Description

Field	Type	Required	Description
`protocolVersion`	string	Yes	The A2A protocol version the agent supports, for example `"0.3.0"`.
`name`	string	Yes	A human-readable name for the agent, for example `"Copywriter Agent"`.
`description`	string	Yes	A human-readable description of the agent’s purpose.
`url`	string	Yes	The preferred endpoint URL at which the agent is served. The transport at this URL is given by `preferredTransport`.
`preferredTransport`	string	No	The transport protocol used at `url`; defaults to `JSONRPC`. The A2A specification (§5.6.1) treats this as effectively required and says it must match the transport available at `url`, so set it explicitly. See Transport protocols.
`additionalInterfaces`	array of AgentInterface	No	Further transport and URL combinations the agent supports, beyond the preferred one.
`iconUrl`	string	No	A URL to an icon for the agent.
`provider`	AgentProvider	No	Information about the organisation that provides the agent.
`version`	string	Yes	The agent’s own version number, in a format the provider defines.
`documentationUrl`	string	No	A URL to human-readable documentation for the agent.
`capabilities`	AgentCapabilities	Yes	The optional protocol features the agent supports, such as streaming.
`securitySchemes`	map of string to SecurityScheme	No	The security schemes a caller can use to authenticate to the agent, keyed by a scheme name. Omit if the agent requires no authentication.
`security`	array of maps of string to array of string	No	The security requirements for calling the agent. Each entry references scheme names declared in `securitySchemes`. The array is an OR of entries; the requirements within a single entry are ANDed together.
`defaultInputModes`	array of string	Yes	The input MIME types the agent accepts by default, for example `["text/plain"]`. Individual skills can override this.
`defaultOutputModes`	array of string	Yes	The output MIME types the agent produces by default. Individual skills can override this.
`skills`	array of AgentSkill	Yes	The distinct units of work the agent can perform.
`supportsAuthenticatedExtendedCard`	boolean	No	Whether the agent offers a fuller card to authenticated callers. Defaults to `false`.
`signatures`	array of AgentCardSignature	No	JSON Web Signatures over the card, for callers that need to verify its authenticity.

protocolVersion

string

Yes

The A2A protocol version the agent supports, for example "0.3.0".

name

string

Yes

A human-readable name for the agent, for example "Copywriter Agent".

description

string

Yes

A human-readable description of the agent’s purpose.

url

string

Yes

The preferred endpoint URL at which the agent is served. The transport at this URL is given by preferredTransport.

preferredTransport

string

The transport protocol used at url; defaults to JSONRPC. The A2A specification (§5.6.1) treats this as effectively required and says it must match the transport available at url, so set it explicitly. See Transport protocols.

additionalInterfaces

array of AgentInterface

Further transport and URL combinations the agent supports, beyond the preferred one.

iconUrl

string

A URL to an icon for the agent.

provider

AgentProvider

Information about the organisation that provides the agent.

version

string

Yes

The agent’s own version number, in a format the provider defines.

documentationUrl

string

A URL to human-readable documentation for the agent.

capabilities

AgentCapabilities

Yes

The optional protocol features the agent supports, such as streaming.

securitySchemes

map of string to SecurityScheme

The security schemes a caller can use to authenticate to the agent, keyed by a scheme name. Omit if the agent requires no authentication.

security

array of maps of string to array of string

The security requirements for calling the agent. Each entry references scheme names declared in securitySchemes. The array is an OR of entries; the requirements within a single entry are ANDed together.

defaultInputModes

array of string

Yes

The input MIME types the agent accepts by default, for example ["text/plain"]. Individual skills can override this.

defaultOutputModes

array of string

Yes

The output MIME types the agent produces by default. Individual skills can override this.

skills

array of AgentSkill

Yes

The distinct units of work the agent can perform.

supportsAuthenticatedExtendedCard

boolean

Whether the agent offers a fuller card to authenticated callers. Defaults to false.

signatures

array of AgentCardSignature

JSON Web Signatures over the card, for callers that need to verify its authenticity.

AgentProvider object

Identifies the organisation behind an agent.

Field Type Required Description

Field	Type	Required	Description
`organization`	string	Yes	The provider’s organisation name.
`url`	string	Yes	A reference URL for the provider, such as a website or documentation.

organization

string

Yes

The provider’s organisation name.

url

string

Yes

A reference URL for the provider, such as a website or documentation.

AgentCapabilities object

Declares the optional protocol features an agent supports. All fields are optional; an omitted field means the capability is not supported.

Field Type Required Description

Field	Type	Required	Description
`streaming`	boolean	No	Whether the agent supports streaming responses over Server-Sent Events.
`pushNotifications`	boolean	No	Whether the agent can send push notifications to a caller’s webhook for asynchronous updates.
`stateTransitionHistory`	boolean	No	Whether the agent exposes a history of task state transitions.
`extensions`	array of AgentExtension	No	The protocol extensions the agent supports.

streaming

boolean

Whether the agent supports streaming responses over Server-Sent Events.

pushNotifications

boolean

Whether the agent can send push notifications to a caller’s webhook for asynchronous updates.

stateTransitionHistory

boolean

Whether the agent exposes a history of task state transitions.

extensions

array of AgentExtension

The protocol extensions the agent supports.

AgentExtension object

Declares a single protocol extension supported by the agent.

Field Type Required Description

Field	Type	Required	Description
`uri`	string	Yes	The URI that uniquely identifies the extension.
`description`	string	No	How this agent uses the extension.
`required`	boolean	No	Whether a caller must comply with the extension’s requirements to interact with the agent.
`params`	object	No	Extension-specific configuration parameters.

uri

string

Yes

The URI that uniquely identifies the extension.

description

string

How this agent uses the extension.

required

boolean

Whether a caller must comply with the extension’s requirements to interact with the agent.

params

object

Extension-specific configuration parameters.

AgentSkill object

Describes one unit of work an agent can perform.

Field Type Required Description

Field	Type	Required	Description
`id`	string	Yes	A unique identifier for the skill within the agent.
`name`	string	Yes	A human-readable name for the skill.
`description`	string	Yes	A description of what the skill does, suitable for a human or an LLM to read.
`tags`	array of string	Yes	Keywords that categorise the skill and aid selection.
`examples`	array of string	No	Example prompts or scenarios the skill is designed to handle.
`inputModes`	array of string	No	Input MIME types for this skill, overriding `defaultInputModes`.
`outputModes`	array of string	No	Output MIME types for this skill, overriding `defaultOutputModes`.
`security`	array of maps of string to array of string	No	Security requirements specific to this skill, in the same form as the top-level `security` field.

id

string

Yes

A unique identifier for the skill within the agent.

name

string

Yes

A human-readable name for the skill.

description

string

Yes

A description of what the skill does, suitable for a human or an LLM to read.

tags

array of string

Yes

Keywords that categorise the skill and aid selection.

examples

array of string

Example prompts or scenarios the skill is designed to handle.

inputModes

array of string

Input MIME types for this skill, overriding defaultInputModes.

outputModes

array of string

Output MIME types for this skill, overriding defaultOutputModes.

security

array of maps of string to array of string

Security requirements specific to this skill, in the same form as the top-level security field.

AgentInterface object

Declares one transport and URL combination at which the agent is available. Used in additionalInterfaces.

Field Type Required Description

Field	Type	Required	Description
`url`	string	Yes	The URL at which this interface is available. In production this should be an absolute HTTPS URL.
`transport`	string	Yes	The transport protocol available at this URL. See Transport protocols.

url

string

Yes

The URL at which this interface is available. In production this should be an absolute HTTPS URL.

transport

string

Yes

The transport protocol available at this URL. See Transport protocols.

Security schemes

securitySchemes is a map from a scheme name to a security scheme object. The scheme objects follow the OpenAPI 3.0 security scheme model. A scheme is one of the following types.

Scheme Purpose

Scheme	Purpose
`apiKey`	An API key passed in a header, query parameter, or cookie.
`http`	An HTTP authentication scheme as defined by RFC 7235, such as Basic or Bearer.
`oauth2`	OAuth 2.0, configured with one or more flows (authorization code, client credentials, implicit, or password).
`openIdConnect`	OpenID Connect Discovery, configured with a discovery URL.
`mutualTLS`	Mutual TLS client authentication.

apiKey

An API key passed in a header, query parameter, or cookie.

http

An HTTP authentication scheme as defined by RFC 7235, such as Basic or Bearer.

oauth2

OAuth 2.0, configured with one or more flows (authorization code, client credentials, implicit, or password).

openIdConnect

OpenID Connect Discovery, configured with a discovery URL.

mutualTLS

Mutual TLS client authentication.

For the full field set of each scheme type, see the A2A specification and the underlying OpenAPI 3.0 security scheme definitions.

AgentCardSignature object

A JSON Web Signature over the card, following RFC 7515.

Field Type Required Description

Field	Type	Required	Description
`protected`	string	Yes	The Base64url-encoded protected JWS header.
`signature`	string	Yes	The computed signature, Base64url-encoded.
`header`	object	No	Unprotected JWS header values.

protected

string

Yes

The Base64url-encoded protected JWS header.

signature

string

Yes

The computed signature, Base64url-encoded.

header

object

Unprotected JWS header values.

Transport protocols

Used by preferredTransport and by the transport field of an AgentInterface.

Value Description

Value	Description
`JSONRPC`	JSON-RPC 2.0 over HTTP. Mandatory baseline transport.
`GRPC`	gRPC over HTTP/2. Optional.
`HTTP+JSON`	REST-style HTTP with JSON. Optional.

JSONRPC

JSON-RPC 2.0 over HTTP. Mandatory baseline transport.

GRPC

gRPC over HTTP/2. Optional.

HTTP+JSON

REST-style HTTP with JSON. Optional.

Complete example

The following is a synthetic but complete contract, illustrating the required fields together with a provider, capabilities, a security scheme, and a single skill.

{
  "protocolVersion": "0.3.0",
  "name": "Copywriter Agent",
  "description": "Generates marketing copy from a structured brief.",
  "url": "https://copywriter.agents.example.com/",
  "preferredTransport": "JSONRPC",
  "version": "1.2.0",
  "provider": {
    "organization": "Storyteq",
    "url": "https://storyteq.com"
  },
  "documentationUrl": "https://docs.example.com/agents/copywriter",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "securitySchemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key"
    }
  },
  "security": [
    { "apiKey": [] }
  ],
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "generate-copy",
      "name": "Generate copy",
      "description": "Produces marketing copy from a structured brief.",
      "tags": ["copywriting", "marketing"],
      "examples": [
        "Write three subject lines for a spring sale email."
      ]
    }
  ]
}

Agent contract specification

Serving the contract

AgentCard object

AgentProvider object

AgentCapabilities object

AgentExtension object

AgentSkill object

AgentInterface object

Security schemes

AgentCardSignature object

Transport protocols

Complete example

Related pages