An A2A agent card is a JSON file at a fixed address that tells other agents who you are, where to reach you, how to authenticate, and what you can do. Most examples online describe a weather bot or a route planner. This post walks through an A2A agent card example for something closer to my world: a staffing vendor's agent that a buyer's recruiting agent might call to request vetted engineers.
One warning before the JSON. A lot of examples floating around are out of date. The path changed from `agent.json` to `agent-card.json` in A2A v0.3.0, and the v1.0 spec moved the endpoint out of a top-level `url` field. If you copy a 2025 blog post, your card will be wrong.
Key Takeaways
- Per the A2A v1.0 specification, the card lives at `https://{your-domain}/.well-known/agent-card.json`.
- Required fields: name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes and skills.
- Skills are the part buyers' agents read most. Write them like a contract: what you take in, what you return, and what you won't do.
- A card is a claim. It proves nothing about the quality of what's behind it, so treat a vendor's card the way you'd treat their homepage.
The A2A agent card example
Here's a card for a fictional vendor, written against the v1.0 sample in section 8.5 of the spec. The domain is example.com on purpose.
{
"name": "Example Staffing Shortlist Agent",
"description": "Takes a hiring brief for senior software engineers and returns a shortlist of blind, pre-vetted profiles. Does not sign contracts or share candidate identity.",
"supportedInterfaces": [
{"url": "https://agents.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
],
"provider": {
"organization": "Example Staffing Inc.",
"url": "https://www.example.com"
},
"version": "1.0.0",
"documentationUrl": "https://www.example.com/docs/agent",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"securitySchemes": {
"oidc": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://auth.example.com/.well-known/openid-configuration"
}
}
},
"securityRequirements": [{ "schemes": { "oidc": { "list": ["openid", "email"] } } }],
"defaultInputModes": ["text/plain", "application/json"],
"defaultOutputModes": ["application/json"],
"skills": [
{
"id": "request-shortlist",
"name": "Request a vetted engineer shortlist",
"description": "Accepts a role, stack, seniority, timezone overlap and start date. Returns blind profiles with assessment summaries. May ask follow-up questions before starting.",
"tags": ["hiring", "staff augmentation", "engineers", "shortlist"],
"examples": [
"Two senior Python engineers, Django and Postgres, 5 hours of US Eastern overlap, start in 3 weeks.",
"{\"role\": \"senior backend engineer\", \"stack\": [\"Go\", \"Kubernetes\"], \"overlap_hours\": 6}"
],
"inputModes": ["text/plain", "application/json"],
"outputModes": ["application/json"]
}
]
}That's a complete, valid shape. Now the parts that matter.
Field by field: what a buyer's agent reads
supportedInterfaces. This replaced the old top-level `url`. Each entry has a URL, a binding (the spec defines JSONRPC, GRPC and HTTP+JSON) and a protocol version. One interface is fine. Don't list bindings you haven't tested.
capabilities. Be honest here. A shortlist takes hours or days, not seconds, so this example sets `streaming` to false and `pushNotifications` to true: the buyer's agent registers a webhook, and the vendor posts back when the task completes. `extendedAgentCard: true` means an authenticated client can fetch a fuller card, which is the right place for anything you don't want on a public URL, like rate bands or contract terms.
securitySchemes and securityRequirements. The spec supports API keys, HTTP auth, OAuth 2.0, OpenID Connect and mutual TLS. For hiring, anonymous access is a bad idea: you want to know which company's agent is asking before you return a single profile.
skills. This is your sales page for machines. The description should say what you return and what you refuse. The example's description says "Does not sign contracts or share candidate identity," because a buyer's agent shouldn't plan around a step that needs a human. Examples matter too; agents use them to shape requests.
Mistakes I see in agent cards
- Overclaiming skills. A card that says "hire engineers" invites an agent to assume the hire is done when the task completes. Say "returns a shortlist."
- Stale paths. `/.well-known/agent.json` is the pre-0.3 path. Serve the current one.
- Secrets in the public card. Anything on the well-known URL is public. Put pricing detail and internal endpoints behind the extended card.
- No version discipline. The spec suggests caching headers derived from the card's version. Bump it when skills change, or clients will keep calling a skill you removed.
For the bigger picture of where A2A sits next to MCP, read A2A vs MCP for hiring.
A Concrete Version
A buyer's recruiting agent at a 60-person SaaS company needs a senior Go engineer.
1. It fetches `https://www.example.com/.well-known/agent-card.json`. One GET, cached for a day.
2. It sees the `request-shortlist` skill, the OIDC requirement and push notifications. It authenticates and registers a webhook.
3. It sends a message: Go, Kubernetes, 6 hours Eastern overlap, start in 3 weeks. The task enters the submitted state.
4. The vendor's agent replies with input-required: "Is the budget band fixed, and is a contract-to-hire conversion needed?" The buyer's agent asks the hiring manager, gets an answer in 40 minutes, and resumes the task.
5. A day or two later the task completes with an artifact: three blind profiles with assessment summaries.
Everything after step 5 is human: the hiring manager picks who to meet, signs the vendor's agreement, and interviews the engineers. The card made the request cheap. It didn't make the decision.
The Honest Counterpoint
Most staffing vendors don't need an agent card in 2026. Few buyers run their own agents that delegate to outside agents yet, and an MCP server reaches far more of them today through Claude and ChatGPT. Building an A2A endpoint before anyone calls it is a fine experiment and a poor priority.
We ran that experiment anyway, so you can compare this example with a real card: ours is at mcp.ruzora.com/.well-known/agent-card.json. It lists one JSON-RPC interface on A2A 1.0 and eight skills, from searching blind profiles of vetted engineers to requesting a vetted shortlist. Streaming and push notifications are off, because each skill either answers in one request or pauses in input-required to name the missing field. It also publishes a JSON Schema for each skill's input as an optional extension, which is the part I'd copy first.
And for buyers: a perfectly written card says nothing about whether the vendor vets anyone. I could publish the card above tonight with no bench behind it. Check the vendor the same way you would without agents. Our questions to ask a staffing agency still apply word for word.
Frequently Asked Questions
Where does an A2A agent card go?
At `https://{your-domain}/.well-known/agent-card.json`, per the current spec. The older `agent.json` path was replaced in v0.3.0 in July 2025.
Is there an official A2A agent card example?
Yes. Section 8.5 of the A2A specification includes a full sample card for a route-planning agent. The example above follows the same v1.0 field names.
Should an agent card include pricing?
Not on the public card. Use the authenticated extended agent card for rate bands or terms, so only verified clients see them.
The Bottom Line
A good agent card is short, current and honest about what the agent returns. Use the v1.0 fields, serve it at the new path, require auth, and describe skills as outputs, not promises. If you're on the buying side and want engineers who were vetted before any agent asked, see our bench or request a shortlist.
Roberto Espinoza is CEO of Ruzora, which helps US startups hire pre-vetted senior LATAM engineers, with a vetted shortlist in 72 hours. See available engineers.
