What is agent.json? — The Standard for AI Agent API Discovery (2026)

Definition

agent.json is a machine-readable JSON file that describes an API's capabilities, actions, inputs, and outputs in a format AI agents can parse and execute. It is served at a well-known URL — typically /.well-known/agent.json — and acts as the primary entry point for any AI agent attempting to discover, understand, and use your API programmatically.

Where traditional API documentation is written for human developers — with prose explanations, code samples, and getting-started guides — agent.json is written exclusively for machines. Every field is structured, typed, and designed to be consumed by an AI model or agent framework without human intervention.

An agent.json file typically contains: the API's name and description, a base URL, authentication requirements, and an array of actions. Each action defines a specific operation the API can perform, including its HTTP method, path, typed input and output schemas, a natural-language description, and — critically — reasoning documentation that tells the agent when andwhy to use that action.

Why agent.json exists

The core problem agent.json solves is API invisibility. As of 2026, there are millions of APIs available on the internet, but AI agents have no reliable way to find them, understand what they do, or figure out how to call them correctly. Without structured metadata, APIs are effectively invisible to autonomous agents.

Human developers solve this problem by reading documentation, following tutorials, and writing integration code. But AI agents cannot browse documentation sites the way humans do. They need a single, parseable file that answers three questions: What can this API do?, How do I call each action?, and When should I use each action?

Before agent.json, every agent framework had its own approach to tool definitions. OpenAI used function calling schemas. LangChain had its own tool format. Anthropic introduced MCP. This fragmentation meant API providers had to create multiple descriptions of their API for different ecosystems. agent.json provides a single, framework-agnostic specification that any agent can consume.

Think of it as what robots.txt did for web crawlers or sitemap.xml did for search engines — agent.json creates a universal discovery point for AI agents. For a deep dive into why this matters, see API Discovery for AI Agents.

The agent.json format

An agent.json file follows a consistent structure. At the top level, it includes metadata about the API (name, description, version, base URL, authentication). The core of the file is the actions array, which contains one entry for each operation the agent can perform.

Here is a complete, 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 or work item. Requires a valid boardId. Returns the created task with its assigned ID and status.",
      "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", "format": "date-time" }
        }
      },
      "example_prompts": [
        "Create a task called 'Fix login bug' on the Engineering board",
        "Add a high-priority task for the Q3 release",
        "Make a new task and assign it to Sarah"
      ]
    },
    {
      "name": "listTasks",
      "description": "List all tasks in a board with optional filtering.",
      "reasoning": "Use to retrieve existing tasks. Supports filtering by status and pagination via limit/offset. Use boardId to scope results to a specific board.",
      "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 },
          "offset": { "type": "number", "default": 0 }
        }
      },
      "output": {
        "type": "object",
        "properties": {
          "tasks": { "type": "array" },
          "total": { "type": "number" },
          "hasMore": { "type": "boolean" }
        }
      },
      "example_prompts": [
        "Show me all open tasks on the Engineering board",
        "What tasks are in progress?",
        "List the last 10 completed tasks"
      ]
    },
    {
      "name": "updateTask",
      "description": "Update an existing task's properties.",
      "reasoning": "Use when the user wants to change a task's title, status, assignee, or priority. Requires the task ID. Only include fields that are changing.",
      "method": "PATCH",
      "path": "/tasks/{taskId}",
      "input": {
        "type": "object",
        "required": ["taskId"],
        "properties": {
          "taskId": { "type": "string" },
          "title": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["open", "in_progress", "done"]
          },
          "assignee": { "type": "string" },
          "priority": {
            "type": "string",
            "enum": ["low", "medium", "high", "urgent"]
          }
        }
      },
      "output": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "example_prompts": [
        "Mark task-123 as done",
        "Change the priority of the login bug to urgent",
        "Reassign task-456 to Mike"
      ]
    }
  ]
}

Key fields to notice in this example:

• reasoning — tells the agent when to use each action and provides contextual hints. This is the field that distinguishes agent.json from traditional API specs.
• example_prompts — natural-language examples of user requests that should trigger this action. Helps the agent match user intent to the correct API call.
• typed input/output schemas — full JSON Schema definitions that let the agent construct valid requests and parse responses without guesswork.
• auth block — standardized authentication description so the agent knows how to authenticate before making any calls.

How AI agents use agent.json

The agent.json discovery flow follows a predictable sequence that mirrors how agents reason about tool use:

agent.json vs OpenAPI/Swagger

OpenAPI (formerly Swagger) has been the industry standard for describing REST APIs since 2015. It is an excellent format for generating client SDKs, API reference documentation, and testing tools. But it was designed for human developers, not AI agents.

The fundamental difference is orientation. OpenAPI is resource-oriented: it organizes everything around URL paths, HTTP methods, request bodies, and response codes. This mirrors how developers think about REST — “I need to POST to /tasks with this JSON body.”

agent.json is action-oriented: it organizes everything around what an agent can do. Instead of describing endpoints, it describes capabilities — “createTask: create a new task, use when the user needs to add work items.” This maps directly to how AI agents reason about tool use: they think in terms of actions and goals, not HTTP verbs and URL paths.

The two formats are complementary. OpenAPI remains essential for developer tooling, while agent.json serves the emerging AI agent ecosystem. For more on this paradigm shift, read Structured Actions vs REST Endpoints.

agent.json vs MCP

MCP (Model Context Protocol) is a standard created by Anthropic for connecting AI models to external tools and data sources. It defines how an agent communicates with a tool server at runtime — the protocol for sending requests and receiving responses.

agent.json and MCP are complementary, not competing. agent.json is the specification — it describes what your API can do, how to authenticate, and when each action should be used. MCP is the protocol — it defines the runtime communication layer between an agent and your API.

In practice, an agent might discover your API through agent.json, then connect to it via an MCP server. Elba generates both formats from a single source of truth, so your API is discoverable (agent.json) and connectable (MCP) simultaneously.

How to implement agent.json

Implementing agent.json for your API involves three steps:

Or skip the manual work entirely — import your OpenAPI spec into Elba and get a complete agent.json generated automatically, along with MCP configs and llms.txt. See our guide to the best API documentation for AI agents for a full comparison of tools.

agent.json and llms.txt

llms.txt is a complementary format that provides a plain-text, high-level overview of your product or API for consumption by large language models. While agent.json provides the detailed, structured data agents need to execute API calls, llms.txt provides the broader context an LLM needs to understand what your product is and how it fits into a user's workflow.

Think of llms.txt as the introduction and agent.json as the technical reference. An LLM might read your llms.txt to decide whether your API is relevant, then fetch your agent.json to get the detailed action definitions needed for actual tool use.

In 2026, publishing both files is becoming standard practice for agent-ready APIs. Together with MCP configs, they form a complete API SEO stack for AI agents — making your API discoverable, understandable, and usable by the growing ecosystem of autonomous AI agents.

Frequently asked questions

Further reading

For a more in-depth exploration of agent.json with additional examples and use cases, read our blog post What is agent.json and Why It Matters for AI Agents. For the complete picture of how to make your API visible and usable by AI agents, see our comprehensive guide: Best API Documentation for AI Agents.

Related topics: What is MCP? · What is llms.txt? · How to Make Your API Usable by AI Agents