Agent card examples
The same small agent — a recipe helper with one skill — published through three SDKs, each card exactly as that SDK served it on 2026-11-05(versions named below; only whitespace was added). Under each: what Agent Galaxy's reader and admission checks make of it. This is not a recommendation of one SDK over another.
1. python a2a-sdk 1.3.0
Code
from a2a.types import AgentCard, AgentSkill, AgentCapabilities, AgentProvider, AgentInterface, AgentExtension
from a2a.server.routes.agent_card_routes import create_agent_card_routes
from starlette.applications import Starlette
card = AgentCard(
name="Recipe Helper",
description="Suggests dinner recipes from the ingredients you have.",
supported_interfaces=[AgentInterface(url="https://recipes.example/a2a",
protocol_binding="JSONRPC", protocol_version="1.0")],
provider=AgentProvider(organization="Example Kitchen", url="https://recipes.example"),
version="1.0.0",
documentation_url="https://recipes.example/docs",
capabilities=AgentCapabilities(streaming=True, extensions=[
AgentExtension(uri="https://a2a-registry.org/extensions/registry/v1", description="listing hint"),
AgentExtension(uri="https://agentgalaxy.dev/extensions/claim/v1", description="Agent Galaxy claim",
params={"agentGalaxySlug": "recipe-helper"})]),
default_input_modes=["text/plain"], default_output_modes=["text/plain"],
skills=[AgentSkill(id="suggest-recipe", name="Suggest a recipe",
description="Given ingredients, returns three recipes.",
tags=["cooking", "recipes"],
examples=["What can I cook with eggs and spinach?"])],
)
app = Starlette(routes=list(create_agent_card_routes(card)))Served at /.well-known/agent-card.json
{
"name": "Recipe Helper",
"description": "Suggests dinner recipes from the ingredients you have.",
"supportedInterfaces": [
{
"url": "https://recipes.example/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"url": "https://recipes.example",
"organization": "Example Kitchen"
},
"version": "1.0.0",
"documentationUrl": "https://recipes.example/docs",
"capabilities": {
"streaming": true,
"extensions": [
{
"uri": "https://a2a-registry.org/extensions/registry/v1",
"description": "listing hint"
},
{
"uri": "https://agentgalaxy.dev/extensions/claim/v1",
"description": "Agent Galaxy claim",
"params": {
"agentGalaxySlug": "recipe-helper"
}
}
]
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"skills": [
{
"id": "suggest-recipe",
"name": "Suggest a recipe",
"description": "Given ingredients, returns three recipes.",
"tags": [
"cooking",
"recipes"
],
"examples": [
"What can I cook with eggs and spinach?"
]
}
]
}Response headers: content-type: application/json, a weak ETag; no Cache-Control. /.well-known/agent.json (the 0.3 path) answers 404.
Worth knowing: the card is a protobuf message, so it cannot carry a field its schema does not know — AgentCard(agentGalaxySlug="…") raises Protocol message AgentCard has no "agentGalaxySlug" field. Registration's fifth check reads that field at the top level or in the params of a capabilities.extensions entry whose uri is https://agentgalaxy.dev/extensions/claim/v1, so a card served this way claims through the entry — the AgentExtension(...) line in the code above, which the served card below carries.
2. @a2a-js/sdk 1.3.0 with Express 5.3.0
Code
import express from "express";
import { agentCardHandler } from "@a2a-js/sdk/server/express";
const card = {
name: "Recipe Helper",
description: "Suggests dinner recipes from the ingredients you have.",
supportedInterfaces: [{ url: "https://recipes.example/a2a", protocolBinding: "JSONRPC", protocolVersion: "1.0" }],
provider: { organization: "Example Kitchen", url: "https://recipes.example" },
version: "1.0.0",
documentationUrl: "https://recipes.example/docs",
capabilities: { streaming: true, extensions: [{ uri: "https://a2a-registry.org/extensions/registry/v1", description: "listing hint", params: { listed: true } }] },
securitySchemes: {},
securityRequirements: [],
defaultInputModes: ["text/plain"],
defaultOutputModes: ["text/plain"],
skills: [{ id: "suggest-recipe", name: "Suggest a recipe", description: "Given ingredients, returns three recipes.",
tags: ["cooking", "recipes"], examples: ["What can I cook with eggs and spinach?"],
inputModes: ["text/plain"], outputModes: ["text/plain"], securityRequirements: [] }],
agentGalaxySlug: "recipe-helper",
};
const app = express();
app.use("/.well-known/agent-card.json", agentCardHandler({ agentCardProvider: async () => card }));Served
{
"name": "Recipe Helper",
"description": "Suggests dinner recipes from the ingredients you have.",
"supportedInterfaces": [
{
"url": "https://recipes.example/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Example Kitchen",
"url": "https://recipes.example"
},
"version": "1.0.0",
"documentationUrl": "https://recipes.example/docs",
"capabilities": {
"streaming": true,
"extensions": [
{
"uri": "https://a2a-registry.org/extensions/registry/v1",
"description": "listing hint",
"params": {
"listed": true
}
}
]
},
"securitySchemes": {},
"securityRequirements": [],
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"skills": [
{
"id": "suggest-recipe",
"name": "Suggest a recipe",
"description": "Given ingredients, returns three recipes.",
"tags": [
"cooking",
"recipes"
],
"examples": [
"What can I cook with eggs and spinach?"
],
"inputModes": [
"text/plain"
],
"outputModes": [
"text/plain"
],
"securityRequirements": []
}
],
"agentGalaxySlug": "recipe-helper"
}The object above, byte for byte — including agentGalaxySlug. Response headers: content-type: application/json; charset=utf-8, Cache-Control: public, max-age=3600, a weak ETag.
Worth knowing: the handler serialises your object as it is, so an extra top-level key survives and this card can claim its listing today. The handler registers only /; mount it at the well-known path yourself, as above. With legacyCompat: { enabled: true } the route demands at least one interface whose protocolVersion is in [0.3, 1.0) — a card that declares only "1.0" answers 400 (-32009). Without legacyCompat, /.well-known/agent.json is not served.
3. Google ADK 2.13.0 (to_a2a)
Code
from google.adk.agents import LlmAgent
from google.adk.a2a.utils.agent_to_a2a import to_a2a
agent = LlmAgent(name="recipe_helper", model="gemini-2.5-flash",
description="Suggests dinner recipes from the ingredients you have.",
instruction="You suggest recipes.")
app = to_a2a(agent, host="recipes.example", port=443, protocol="https")Served
{
"name": "recipe_helper",
"description": "Suggests dinner recipes from the ingredients you have.",
"supportedInterfaces": [
{
"url": "https://recipes.example:443",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"version": "0.0.1",
"capabilities": {
"streaming": true
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"skills": [
{
"id": "recipe_helper",
"name": "model",
"description": "Suggests dinner recipes from the ingredients you have.",
"tags": [
"llm"
]
}
]
}With AgentCardBuilder and the claim entry
import asyncio
from google.adk.agents import LlmAgent
from google.adk.a2a.utils.agent_card_builder import AgentCardBuilder
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from a2a.types import AgentCapabilities, AgentExtension, AgentProvider
agent = LlmAgent(name="recipe_helper", model="gemini-2.5-flash",
description="Suggests dinner recipes from the ingredients you have.",
instruction="You suggest recipes.")
card = asyncio.run(AgentCardBuilder(
agent=agent, rpc_url="https://recipes.example/a2a", agent_version="1.0.0",
provider=AgentProvider(organization="Example Kitchen", url="https://recipes.example"),
doc_url="https://recipes.example/docs",
capabilities=AgentCapabilities(streaming=True, extensions=[AgentExtension(
uri="https://agentgalaxy.dev/extensions/claim/v1", description="Agent Galaxy claim",
params={"agentGalaxySlug": "recipe-helper"})]),
).build())
app = to_a2a(agent, host="recipes.example", port=443, protocol="https", agent_card=card){
"name": "recipe_helper",
"description": "Suggests dinner recipes from the ingredients you have.",
"supportedInterfaces": [
{
"url": "https://recipes.example/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"url": "https://recipes.example",
"organization": "Example Kitchen"
},
"version": "1.0.0",
"documentationUrl": "https://recipes.example/docs",
"capabilities": {
"streaming": true,
"extensions": [
{
"uri": "https://agentgalaxy.dev/extensions/claim/v1",
"description": "Agent Galaxy claim",
"params": {
"agentGalaxySlug": "recipe-helper"
}
}
]
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"skills": [
{
"id": "recipe_helper",
"name": "model",
"description": "Suggests dinner recipes from the ingredients you have.",
"tags": [
"llm"
]
}
]
}Response headers: content-type: application/json; /.well-known/agent.json answers 404.
Worth knowing: the generated skill's name is the literal "model", version defaults to "0.0.1", and the URL carries :443. Build the card yourself — AgentCardBuilder(agent=…, rpc_url=…, agent_version=…, provider=…, doc_url=…) — or hand to_a2a an agent_card, to publish your own name, version and documentation. The card type is the same protobuf as the python SDK's, with the same limit on extra fields — the claim goes in the extension entry, as the second card shows.
How Agent Galaxy reads them
All three are A2A 1.0 cards. Agent Galaxy's reader takes a top-level url when there is one (0.3 cards), else the first non-gRPC supportedInterfaces entry with a url, the skills with their tags, provider and documentationUrl. A card at a public https URL can appear as an Unclaimed listing — suggest it with POST /api/v1/public/observed:suggest, or let a peer directory list it. Registration adds the sixth thing: the card must name the slug being registered as agentGalaxySlug, at the top level or in the claim extension entry. Run any card through the checks first: Check an agent card.
Measured 2026-11-05 with a2a-sdk 1.3.0, @a2a-js/sdk 1.3.0 + express 5.3.0, google-adk 2.13.0 (with a2a-sdk 1.3.0), Node 24, Python 3.14. The JSON is what each served; only whitespace was added.