ADL

Appearance

A2A & the Agent Card ​

ADL describes A2A agents. A2A (Agent-to-Agent) is an open protocol for how an agent advertises what it can do and exchanges messages with clients and other agents over HTTP. ADL is the manifest; A2A is the protocol the generated agent speaks on the wire. For the full wire format, see the upstream A2A specification.

A2A does not require an LLM. The protocol is about how agents are discovered and talk to each other - an agent can satisfy it with deterministic tools alone and no spec.agent block. See A2A Agent Without an LLM.

The Agent Card ​

Every A2A agent publishes an Agent Card: a small JSON document, served at /.well-known/agent-card.json, that tells callers who the agent is, where it lives, which protocol version and transport it speaks, and what it can do. It's the discovery handshake - a client fetches the card before it sends a single message.

ADL doesn't make you write that JSON by hand. Three manifest blocks declare the card, and the generator emits .well-known/agent-card.json from them (see Generate & Run):

  • metadata - the agent's name, description, and version.
  • spec.capabilities - the protocol features the agent supports.
  • spec.card - supported interfaces (endpoint URL, protocol binding and version), and the input/output modes it accepts.

spec.skills also surface on the card, so callers can discover what the agent knows how to do.

What the capability flags mean to a caller ​

spec.capabilities is required because it's part of the contract a caller reads off the card before connecting. Each flag answers a question the client needs settled up front:

  • streaming - can the caller subscribe to incremental results (Server-Sent Events), or must it wait for a single buffered response?
  • pushNotifications - can the caller register a webhook and be notified of progress on a long-running task instead of polling for it?
  • extendedAgentCard - does the agent serve a richer card once the caller has authenticated?

A runtime should never have to guess these, so the schema makes streaming and pushNotifications explicit - see the note on defaults.

(stateTransitionHistory used to sit alongside these; the A2A v1.0.1 AgentCard dropped it, so ADL dropped it too.)

ADL → A2A Agent Card ​

Each ADL manifest field maps to a field on the published A2A AgentCard (A2A v1.0.1) - in most cases the same name, with the ADL container (metadata, spec.capabilities, spec.card) dropped:

text
ADL manifest field                          A2A AgentCard field (v1.0.1)
------------------------------------------  ----------------------------------
metadata.name                           ->  name
metadata.description                    ->  description
metadata.version                        ->  version
spec.capabilities.streaming             ->  capabilities.streaming
spec.capabilities.pushNotifications     ->  capabilities.pushNotifications
spec.capabilities.extendedAgentCard     ->  capabilities.extendedAgentCard
spec.card.supportedInterfaces           ->  supportedInterfaces[] (url, protocolBinding, protocolVersion)
spec.card.defaultInputModes             ->  defaultInputModes
spec.card.defaultOutputModes            ->  defaultOutputModes
spec.card.documentationUrl              ->  documentationUrl
spec.card.iconUrl                       ->  iconUrl
spec.card.securitySchemes               ->  securitySchemes
spec.card.securityRequirements          ->  securityRequirements
spec.skills[]                           ->  skills[]

In A2A the capability flags are nested under a capabilities object on the card. ADL keeps them as a separate required block (spec.capabilities) and folds them back in at generation time. Everything under spec.card is optional; omit the block and the generator still produces a valid card from metadata and capabilities.

capabilities.extensions has no manifest field. A2A extensions are runtime behaviour, so the ADK runtime declares the ones it serves on the card it publishes. A generated agent's served card can therefore list extensions its manifest never mentions - for example the usage extension, which reports a task's token usage and execution stats to clients that activate it with the A2A-Extensions header.

ADL field names track the current AgentCard: when A2A renames a field, ADL renames it too rather than keeping an alias. Earlier ADL versions spelled the endpoint as spec.card.url / spec.card.preferredTransport / spec.card.protocolVersion (now one supportedInterfaces entry), spec.card.security (now securityRequirements) and spec.card.supportsExtendedAgentCard (now spec.capabilities.extendedAgentCard); spec.capabilities.stateTransitionHistory is gone with the wire field.

The outbound side: agent as client ​

The sections above cover how an ADL agent is discovered and called by clients. But an ADL agent is also a client itself: it can call other A2A agents and reach external tools through MCP servers declared in spec.agent.mcp. The generated agent ships with a built-in MCP client that connects to those servers at runtime, discovers their tools, and makes them available to the model alongside the agent's own spec.tools. That client is generated for Go agents only, and connects to http servers only - see What the reference consumer wires.

See Connecting to MCP Servers for the full guide and the MCP example for a complete manifest.

Next steps ​