Authenticated Extended Card

Serve a richer Agent Card to authenticated clients while keeping the public .well-known/agent-card.json minimal. The extended card can advertise skills you don’t want exposed anonymously — an authenticated client fetches them over a dedicated, auth-gated method.

This implements the A2A spec’s Authenticated Extended Card (§3.1.11 Get Extended Agent Card, §13.3 Extended Agent Card Access Control). It is opt-in — every card serves only its public skills until you enable it.

How it works

A card has two faces:

Public card — returned from .well-known/agent-card.json to anyone. Contains only skills that are not marked extended-only.
Extended card — returned from GetExtendedAgentCard (or GET /extendedAgentCard) to authenticated clients only. Contains every skill, including the extended-only ones.

When a card advertises the capability, the public card carries capabilities.extendedAgentCard: true as a hint. Clients that see the flag — and that hold credentials — know to call the extended method to discover the full skill set.

The extended card is auth-gated but is not a place for secrets. Per A2A §13.3, treat it as “more skills for signed-in users,” not as a vault — never put credentials, tokens, or private data in skill descriptions or examples.

Wire protocol

The extended card is fetched with the bare GetExtendedAgentCard JSON-RPC method (no agent/ prefix), or the REST equivalent:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "GetExtendedAgentCard",
  "params": {}
}

GET /api/platform/<id>/a2a/extendedAgentCard

Both require an Authorization header. Responses to the request carry cache-control headers so intermediaries don’t cache an authenticated card for anonymous callers.

Two error codes are specific to this method:

Code	Meaning
`-32004`	`UnsupportedOperation` — the card does not advertise `capabilities.extendedAgentCard`.
`-32007`	`ExtendedCardNotConfigured` — the capability is on, but no extended-only content is configured.

Advertising the capability

Turn the feature on from the agent-card editor:

Open the agent card and enter Edit mode.
Scroll to the Authenticated Extended Card toggle (below the Streaming / SSE capability).
Switch it on and Save.

Enabling the toggle writes the capability in two places so every consumer sees it consistently: capabilities.extendedAgentCard: true on the card and config.supportsAuthenticatedExtendedCard: true in its config. From then on the public card advertises the capability and the extended method is live.

The toggle is version-independent — it is available regardless of the card’s A2A protocol version. The extended method itself follows the same A2A-Version negotiation as the rest of the A2A surface.

Authoring extended-only skills

A skill can be marked Extended only so it is served exclusively in the extended card and hidden from the public one:

Open a skill for editing (the skill dialog on the agent-card editor).
Turn on the Extended only toggle.
Save the skill.

Extended-only skills show an Extended only badge in the skill list so you can tell at a glance which skills are hidden from anonymous callers. Under the hood this is the extended_only flag on the skill; the public card filters these out, and only GetExtendedAgentCard returns them.

A typical setup:

Leave general, discovery-friendly skills public.
Mark premium, internal, or partner-only skills Extended only.
Enable the Authenticated Extended Card capability so authenticated clients know to fetch them.

If you enable the capability but mark no skills extended-only, an authenticated client still gets a valid extended card — it just matches the public one. Marking at least one skill extended-only is what makes the two faces differ.

Fetching it in the Protocol Tester

The Protocol Tester fetches the extended card for you:

Discover an A2A card (Agent Card Test tab, or paste an A2A URL on the standalone tester).
When the discovered card advertises the capability, the capabilities strip shows Extended card: Yes and a Fetch extended card button appears.
Set your credentials in the Auth panel, then click Fetch extended card.

The tester sends GetExtendedAgentCard to the selected interface, forwarding your auth and any custom headers (adding A2A-Version: 1.0 unless you set one yourself). The response — including any extended-only skills — is shown in the response viewer and captured in history like any other request.

If the button is absent, the card isn’t advertising capabilities.extendedAgentCard; enable the toggle on the card first.

Configuring via the MCP tools

The A²D MCP tools can both read and set a card’s extended-card configuration, so you can drive the whole feature from an agent without opening the web UI.

Reading:

get_agent_card and get_agent_card_spec return the extendedAgentCard capability and per-skill extended_only flags.

Writing — the capability lives on the card, the visibility lives on each skill:

Tool	Field	Effect
`design_agent_card`	`extended_agent_card` (boolean)	Advertise the capability on a new card — writes `capabilities.extendedAgentCard` and `config.supportsAuthenticatedExtendedCard`.
`update_agent_card`	`extended_agent_card` (boolean)	Toggle the capability on an existing card; merges into the current capabilities/config without clobbering other keys.
`add_agent_skill`	`extended_only` (boolean)	Create a skill that is served only in the extended card.
`update_agent_skill`	`extended_only` (boolean)	Flip an existing skill’s extended-only visibility.
`ai_generate_full_agent_card`	—	Carries the generated capability and any per-skill `extended_only` flags through to the persisted card.

A typical MCP flow: design_agent_card with extended_agent_card: true, then add_agent_skill with extended_only: true for each premium skill.

The MCP tools and the editor toggles write the same fields, so a card configured either way behaves identically — advertise the capability on the card and mark the sensitive skills extended-only.

Next Steps

Signed Agent Cards — Prove authenticity of the card you serve
A2A Protocol Versions — Pick the right version for your card
Protocol Tester — Fetch the extended card and inspect extended-only skills

Keep the public card lean and gate the rest: advertise the capability, mark the sensitive skills extended-only, and let authenticated clients ask for the full set.

Signed Agent Cards Overview