What is agent.json and Why It Matters for AI Agents (2026)
agent.json is a machine-readable file that describes an API for AI agents. Learn the format, how it works, and why every API needs one.
What is agent.json
agent.json is a structured, machine-readable file that describes what an API can do in a format AI agents can parse and act on. It lives at a well-known URL — typically /.well-known/agent.json — and serves as the primary entry point for any agent trying to understand and use your API.
Think of agent.json as your API's resume for AI agents. It contains the information an agent needs to decide whether your API is relevant to its current task, what actions it can perform, what inputs each action requires, and what outputs it will receive. Unlike human-readable documentation, every field in agent.json is designed to be parsed programmatically.
The file typically includes: a list of actions your API exposes, typed input and output schemas for each action, descriptions that help agents understand when to use each action, authentication requirements, the base URL for making requests, and metadata about the API itself (name, version, category).
The agent.json format
An agent.json file follows a consistent structure. Here is a realistic example for a project management API:
{
"schema": "https://useelba.com/schemas/agent.json/v1",
"name": "ProjectBoard API",
"description": "Project management API with tasks, boards, and team collaboration",
"version": "2.1.0",
"baseUrl": "https://api.projectboard.io/v2",
"auth": {
"type": "bearer",
"header": "Authorization"
},
"actions": [
{
"name": "createTask",
"description": "Create a new task in a project board",
"reasoning": "Use when the user wants to add a new task. Requires a valid boardId.",
"method": "POST",
"path": "/tasks",
"input": {
"type": "object",
"required": ["boardId", "title"],
"properties": {
"boardId": {
"type": "string",
"description": "ID of the board to add the task to"
},
"title": {
"type": "string",
"description": "Task title (max 200 characters)"
},
"assignee": {
"type": "string",
"description": "User ID of the assignee (optional)"
},
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "urgent"]
}
}
},
"output": {
"type": "object",
"properties": {
"id": { "type": "string" },
"title": { "type": "string" },
"status": { "type": "string" },
"createdAt": { "type": "string" }
}
}
},
{
"name": "listTasks",
"description": "List all tasks in a board with optional filtering",
"reasoning": "Use to retrieve tasks. Use boardId to scope results. Supports pagination.",
"method": "GET",
"path": "/boards/{boardId}/tasks",
"input": {
"type": "object",
"required": ["boardId"],
"properties": {
"boardId": { "type": "string" },
"status": { "type": "string", "enum": ["open", "in_progress", "done"] },
"limit": { "type": "number", "default": 20 }
}
},
"output": {
"type": "object",
"properties": {
"tasks": { "type": "array" },
"total": { "type": "number" },
"hasMore": { "type": "boolean" }
}
}
}
]
}Notice how each action includes not just the technical details (method, path, schema) but also a reasoning field that tells the agent when and how to use it. This combination of structure and guidance is what makes agent.json effective.
Why agent.json is important
The rise of AI agents creates a new requirement for APIs: machine-readable self-description. Agents need to discover APIs, understand their capabilities, and integrate with them dynamically — all without a human writing integration code.
Standardized discovery
By publishing agent.json at a well-known URL, you enable any agent or framework to find and understand your API. This is similar to how robots.txt standardized web crawling or how sitemap.xml standardized search indexing. Agent.json creates a universal discovery point for AI agents.
Tool identification
When an agent encounters a task it cannot complete with its built-in capabilities, it needs to find external tools. Agent.json lets agents identify what tools an API provides, evaluate whether they match the current task, and connect without manual configuration.
Dynamic integration
Instead of hardcoding API integrations, agents can read agent.json at runtime to learn how to interact with your API. This means new APIs can be used immediately without updating the agent's code. The agent adapts to the API, not the other way around.
How agent.json improves API usage
APIs with a published agent.json file see measurable improvements in how agents interact with them:
Less hallucination
With typed schemas and reasoning docs, agents know exactly what parameters to send and what to expect back. This eliminates the guesswork that causes API call hallucinations.
Faster integration
Agents can go from discovering your API to making their first successful call in seconds, not hours. No manual setup, no reading prose documentation, no trial-and-error.
Dynamic tool use
Agent frameworks can load tools from agent.json at runtime. This enables agents to discover and use new APIs without code changes or redeployment.
Better selection
When agents have access to multiple APIs, the descriptions and reasoning in agent.json help them select the right tool for the task, reducing errors and improving outcomes.
agent.json vs OpenAPI
OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. So why do we need agent.json? The answer lies in what each format is optimized for.
OpenAPI is resource-oriented. It describes your API in terms of paths, HTTP methods, request bodies, and response codes. This is excellent for generating client SDKs, API reference pages, and testing tools. But it was designed for human developers who understand REST conventions and can infer how to use endpoints from their structure.
agent.json is action-oriented. It describes your API in terms of what an agent can do with it. Instead of “POST /api/v1/tasks with these parameters”, agent.json says “createTask: create a new task, use when the user needs to add work items, requires a board ID and title.” This shift from resource description to action description is what makes agent.json effective for AI agents.
For a deeper comparison of these two paradigms, see our post on structured actions vs REST endpoints. The two formats are complementary: OpenAPI for human tooling and SDK generation, agent.json for AI agent consumption and discovery.
The future: agent.json alongside MCP and llms.txt
agent.json does not exist in isolation. It is part of an emerging discovery stack that includes multiple complementary formats, each serving a different purpose:
agent.json for structured discovery
The primary machine-readable format. Provides full action definitions, typed schemas, and reasoning documentation. Agents use this to understand what your API can do and how to use it.
MCP for protocol-based access
Model Context Protocol (MCP) provides a standardized way for agents to connect to your API as a tool. While agent.json describes capabilities, MCP provides the runtime connection layer.
llms.txt for LLM context
llms.txt provides a plain-text summary that LLMs can use for general context about your product. It is lighter than agent.json and useful for initial understanding before deeper integration.
Together, these three formats create a complete discovery and integration stack. In 2026, publishing all three is becoming the standard for agent-ready APIs.
How Elba generates agent.json automatically
Writing and maintaining agent.json manually is tedious, especially for APIs with many endpoints. Elba automates the entire process. Import your OpenAPI spec or connect your API, and Elba generates a complete agent.json with typed actions, input/output schemas, and reasoning documentation.
Elba also generates the complementary formats — MCP config, llms.txt, and JSON-LD metadata — so you get the full discovery stack from a single source of truth. When your API changes, update it in Elba and all formats regenerate automatically.
For a comprehensive look at how Elba compares to other documentation platforms for AI agents, see our guide to the best API documentation for AI agents.