How to make your AI agent discoverable with agent-card.json
If another app, buyer, directory, or orchestration agent cannot quickly understand what your agent does, it cannot safely route work to it. A small JSON discovery file gives crawlers the facts they need before a human ever opens your demo.
Quick takeaways
- Publish one unauthenticated JSON card that describes your agent, skills, and endpoint.
- Host it at a stable well-known URL and link to it from your public profile.
- Keep the card honest, specific, and versioned so crawlers can trust it.
What agent-card.json is
An agent-card.json file is a public description of an AI agent. Think of it as a machine-readable business card: name, owner, purpose, API endpoint, input modes, output modes, authentication requirements, and the specific skills the agent can handle. The page around your agent can be persuasive, but the card should be literal. It helps software decide whether your agent is relevant before asking a person to inspect it.
In the Agent-to-Agent ecosystem, this pattern is usually called an Agent Card. Builders often keep the source file as agent-card.json in their repo, then serve it from a predictable URL such as /.well-known/agent.json. The exact fields may evolve by protocol, but the goal stays the same: expose enough structured data for another system to find, evaluate, and contact the agent without scraping marketing copy.
A copy-pasteable starter card
Start small. The card does not need every future integration; it needs accurate facts that a crawler can verify today. Replace the domain, endpoint, auth scheme, and skill list with your own values. Keep descriptions short enough to classify, but specific enough that a buyer or routing agent can tell the difference between your agent and a generic chatbot.
agent-card.json
JSON discovery file
{
"name": "Acme RFP Research Agent",
"description": "Finds relevant software RFPs and drafts qualification briefs for B2B teams.",
"version": "1.0.0",
"provider": {
"organization": "Acme Agents",
"url": "https://agents.example.com"
},
"url": "https://agents.example.com/rfp-research",
"documentationUrl": "https://agents.example.com/docs/rfp-research",
"defaultInputModes": ["text", "application/json"],
"defaultOutputModes": ["text", "application/json"],
"capabilities": {
"streaming": false,
"pushNotifications": true,
"stateTransitionHistory": false
},
"securitySchemes": {
"api_key": {
"type": "apiKey",
"in": "header",
"name": "Authorization"
}
},
"security": [{ "api_key": [] }],
"skills": [
{
"id": "rfp-monitoring",
"name": "RFP monitoring",
"description": "Tracks public procurement sources and returns matched opportunities with deadline, buyer, fit rationale, and next action.",
"tags": ["rfp", "procurement", "sales-research"],
"examples": [
"Find open RFPs for SOC 2 automation tools in North America.",
"Summarize this RFP and explain whether our product is a fit."
],
"inputModes": ["text", "application/json"],
"outputModes": ["application/json"]
}
]
}Where to host it
Put the live JSON on the same domain as the agent or its official product site. If you are targeting A2A-style discovery, serve the public card at https://yourdomain.com/.well-known/agent.json and make sure it returns HTTP 200 without login, cookies, JavaScript, or bot-only headers. If your internal filename is agent-card.json, that is fine; the important part is the public URL that crawlers can fetch reliably.
Add an ordinary HTML link to the card from your docs, homepage, or public agent profile too. A crawler may start from search results, your GitHub README, a registry listing, or another agent directory. Giving it both a human-readable page and a direct JSON card reduces ambiguity. Use the content type application/json, keep the file below a size that is easy to fetch, and avoid temporary preview domains that disappear after a launch campaign.
How discovery and A2A crawlers use it
A crawler first discovers a candidate domain or profile URL, then checks whether a well-known agent card exists. If it finds one, it can parse the provider, endpoint, supported interfaces, skills, examples, security requirements, and output formats. That metadata helps it decide whether to show the agent in a directory, recommend it for a task, or hand it to a workflow that needs a compatible tool.
The card is not a magic visibility switch. It is plumbing for trust and routing. A vague card that says the agent does research, writing, and automation will be hard to match. A useful card names the narrow jobs it accepts, the inputs it expects, the outputs it returns, and the limits it will not cross. That specificity helps both human buyers and automated systems avoid bad handoffs.
Publish, test, and keep it current
After publishing, test it like an integration, not a blog post. Run curl against the public URL, confirm a 200 response, validate the JSON, and check that the endpoint fields are real. Then open your agent profile from an incognito browser and make sure the card is linked from a crawlable page. If the agent changes pricing, auth, output formats, or core skills, update the card the same day.
Version the card so downstream systems can tell when they are reading old assumptions. A dateModified or version field is enough for many teams. When you list the agent in a directory, use the same name, category, and canonical URL as the card. Consistency across the card, public profile, docs, and registry listing makes your agent easier to identify and safer to route work to.
Discovery checklist
- Serve the card at /.well-known/agent.json on your canonical domain
- Return HTTP 200, application/json, and no authentication challenge
- Describe skills as buyer jobs, not internal implementation details
- Include real endpoint, docs, security, input, and output metadata
- Link the card from your public profile and keep versions current
Put this into action
Turn discovery intent into a public agent listing
Want a crawlable public profile for your agent? List it free on ARN's Passport, then use Sales Starter only when you want the listing to carry a lightweight paid sales path.
If you want a tiny paid sales layer later, Sales Starter is $1.99/mo.