What Is agents.json?
agents.json is an emerging standard for AI agent discoverability — a structured JSON file, hosted at yourdomain.com/agents.json, that describes the AI agents or agentic capabilities your platform exposes. It is to AI agents what robots.txt is to web crawlers and what sitemap.xml is to search engines: a standard location for machine-readable metadata about your site that other automated systems can read without human intervention.
The use case is agent-to-agent discovery. As agentic AI systems (AutoGPT, Claude Agents, Gemini Agents, custom LangChain workflows) become more prevalent, they need a standardized way to discover: what can this platform do? What endpoints can I call? What data does it expose? What actions can I take on behalf of a user? The agents.json file answers these questions in a format that any LLM or agentic orchestrator can read and act on.
Think of it as a structured capability menu for your platform — one that AI systems can read autonomously. A travel booking agent that wants to check hotel availability at your hotel platform can read your agents.json, understand that you expose a check_availability capability, and call it with the right parameters — without needing a human to write a custom integration.
Why AI Agents Need agents.json
The internet in 2026 is increasingly navigated by AI agents on behalf of users rather than by users directly. Perplexity's Deep Research mode, ChatGPT's browsing and tool-use plugins, and Claude's Projects all run agentic workflows that need to discover and interact with external services programmatically. Without a standard like agents.json, each agent must either have hardcoded knowledge of your platform (requiring a bespoke integration) or guess at your API structure by reading documentation — which is slow, error-prone, and not scalable.
agents.json solves the cold-start problem for agent-to-platform interaction. When an orchestrating AI agent encounters your domain — via a citation, a tool call, or a search result — it can fetch /agents.json and immediately understand: this domain exposes agentic capabilities, here is what they are, here is how to authenticate, here is what a capability call looks like.
Key benefits of publishing agents.json:
- AI agents can discover and invoke your capabilities without hardcoded integrations
- Signals to LLMs that your platform is AI-native and agent-ready
- Increases likelihood of being referenced when agents search for tools to accomplish tasks
- Establishes your domain in the emerging agent discovery ecosystem early
- Pairs with llms.txt to give AI systems a complete picture of your platform
The agents.json Format Spec
The agents.json format is a JSON object at the root level. The top-level keys describe the platform and list the capabilities it exposes. Each capability has a name, description, input schema, output schema, and endpoint reference. The format is intentionally minimal — readable by any LLM with a single context window — while being expressive enough to describe complex multi-step agentic interactions.
Top-level fields:
| Field | Type | Description |
|---|---|---|
| schema_version | string | Version of the agents.json spec being used (e.g., "1.0") |
| name | string | Human-readable name of the platform or service |
| description | string | One-paragraph description of what the platform does, written for LLM context |
| contact_email | string | Contact for agent integration questions |
| auth | object | Authentication method (none, api_key, oauth2) |
| capabilities | array | List of capability objects the platform exposes to agents |
| llms_txt_url | string | URL of the companion llms.txt file (optional but recommended) |
Copy-Pasteable agents.json Template
Replace the placeholder values with your actual platform details. The template below covers a SaaS platform with three capabilities: a read capability, a write capability, and a webhook subscription capability. Remove or add capability objects to match your actual API surface.
{
"schema_version": "1.0",
"name": "Your Platform Name",
"description": "A one-to-two sentence description of what your platform does, written for an AI agent that will use it as context. Be specific about the domain, the data it manages, and the actions it can take. Example: 'YourPlatform is a B2B SaaS tool that manages customer support tickets. It exposes capabilities to list, create, update, and close support tickets, as well as subscribe to ticket event webhooks.'",
"homepage_url": "https://yourplatform.com",
"llms_txt_url": "https://yourplatform.com/llms.txt",
"contact_email": "developer@yourplatform.com",
"auth": {
"type": "api_key",
"header_name": "Authorization",
"header_value_format": "Bearer {api_key}",
"docs_url": "https://yourplatform.com/docs/authentication"
},
"base_url": "https://api.yourplatform.com/v1",
"capabilities": [
{
"name": "list_items",
"description": "Returns a paginated list of [items] for the authenticated account. Use this to retrieve existing data before creating or updating.",
"method": "GET",
"endpoint": "/items",
"parameters": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Number of items to return (default 20, max 100)"
},
"offset": {
"type": "integer",
"description": "Pagination offset (default 0)"
},
"status": {
"type": "string",
"enum": ["active", "archived", "all"],
"description": "Filter by status (default 'active')"
}
},
"required": []
},
"response_schema": {
"type": "object",
"properties": {
"items": { "type": "array", "description": "Array of item objects" },
"total": { "type": "integer", "description": "Total count for pagination" }
}
}
},
{
"name": "create_item",
"description": "Creates a new [item] in the authenticated account. Returns the created item with its assigned ID.",
"method": "POST",
"endpoint": "/items",
"parameters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the item to create"
},
"description": {
"type": "string",
"description": "Optional description"
},
"metadata": {
"type": "object",
"description": "Optional key-value metadata object"
}
},
"required": ["name"]
},
"response_schema": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "Unique ID of the created item" },
"name": { "type": "string" },
"created_at": { "type": "string", "format": "date-time" }
}
}
},
{
"name": "subscribe_to_events",
"description": "Registers a webhook URL to receive real-time events from this platform. Use this when you need to react to changes asynchronously rather than polling.",
"method": "POST",
"endpoint": "/webhooks",
"parameters": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The HTTPS URL that will receive POST requests for events"
},
"events": {
"type": "array",
"items": { "type": "string", "enum": ["item.created", "item.updated", "item.deleted"] },
"description": "List of event types to subscribe to"
},
"secret": {
"type": "string",
"description": "Optional HMAC secret for signature verification"
}
},
"required": ["url", "events"]
}
}
]
}
How to Host agents.json at /agents.json
The file must be served at exactly https://yourdomain.com/agents.json with a Content-Type of application/json. The path is a convention — AI agents that support the standard will always check this path first.
Static file servers (Nginx, Apache, Caddy)
Place agents.json in your web root directory. The file will be served automatically at /agents.json. Verify the Content-Type header is application/json (most servers auto-detect for .json files).
Next.js / Vercel
Place agents.json in the /public directory. It will be served at /agents.json automatically. No additional configuration needed.
Express.js
Add a route: app.get('/agents.json', (req, res) => res.json(agentsConfig)) or serve the static file from your public directory.
How agents.json Pairs with llms.txt
agents.json and llms.txt are complementary files that together give AI systems a complete picture of your platform. llms.txt (hosted at /llms.txt) is a Markdown-formatted document that describes your platform in natural language for LLMs — what it does, what content it has, key facts, and an index of important URLs. agents.json is the machine-readable companion that describes your programmatic capabilities.
When an AI agent encounters your domain, it typically reads llms.txt first for context and then reads agents.json to understand what it can do. The agents.json file should cross-reference llms.txt with the llms_txt_url field so agents know to read both.
The discovery stack for your domain: