What Is agents.json? Advertising AI Agent Capabilities on Your Website

robots.txt has told crawlers for thirty years where they cannot go. That worked for crawlers, but AI agents browse, reason, and take actions on their own. They need a file that tells them what they can do, and agents.json is one attempt at that.

What Is agents.json?

agents.json is a machine-readable JSON file that describes what AI agents can do on or with your website. Where robots.txt is a list of restrictions, agents.json is a list of capabilities. It describes which endpoints your site exposes, which workflows agents can execute, how they authenticate, and which tools are available.

No single standards body owns the concept. Several independent initiatives arrived at the same idea: a discoverable JSON file at /.well-known/agents.json, a machine-readable business card for AI agents that visit your domain. The most prominent version is the agents.json spec by Wildcard AI , an open-source project (v0.1.0) that extends OpenAPI with agent-specific metadata.

Why agents.json Matters

The web was built for humans who click links, and APIs for developers who write code. An AI agent is autonomous software that needs to discover what a website can do, understand how to interact with it, and execute multi-step workflows without a human in the loop.

Today, an AI agent that visits your website has to reverse-engineer your capabilities: it reads the HTML and guesses at API endpoints. That approach is brittle and error-prone. With an agents.json file, agents do not need to guess, because you declare what they can do.

It is like handing someone a menu instead of letting them wander into the kitchen. agents.json is that menu for AI agents.

The Wildcard agents.json Specification

The most developed agents.json spec comes from Wildcard AI , a Y Combinator-backed startup focused on making APIs work for AI agents. Their spec (v0.1.0, Apache 2.0) builds on OpenAPI with three additions:

Flows and Links

The core idea of the Wildcard spec is flows (also called "chains") and links. A flow describes a complete workflow: a sequence of API calls that together achieve an outcome. Links define how those steps connect. Output from step 1 becomes input for step 2.

{
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.example.com",
  "info": {
    "title": "Example API for Agents",
    "description": "Manage orders and customers"
  },
  "chains": {
    "create_order": {
      "description": "Create a new order for an existing customer",
      "agent_instructions": "Look up the customer first, then create the order",
      "steps": [
        {
          "endpoint": "/customers/search",
          "method": "GET",
          "parameters": {
            "query": "$user_input.customer_name"
          }
        },
        {
          "endpoint": "/orders",
          "method": "POST",
          "parameters": {
            "customer_id": "$prev.results[0].id",
            "items": "$user_input.items"
          }
        }
      ]
    }
  }
}

The create_order chain above describes a two-step workflow: search for a customer, then create an order using that customer's ID. The agent_instructions field gives the LLM plain-language context to understand the intent. The steps define the exact API calls.

Authentication

The spec supports three auth schemes, with a fourth on the roadmap:

• API Key: Key passed in a header, query parameter, or cookie
• Bearer Token: Standard OAuth 2.0 bearer tokens
• Basic Auth: Username/password combination
• OAuth: Full OAuth flows (on the roadmap for v0.2)

Design Principles

The Wildcard spec follows four principles:

1. Build on OpenAPI: Don't reinvent what already works. Extend existing API documentation.
2. Optimize for LLMs: Structure the schema for machine consumption, not human readability.
3. Stateless by design: Agents manage their own orchestration. The spec defines what to do, not how to manage sessions.
4. Minimal API changes: Adding agents.json should not require changing your existing API.

How agents.json Compares to Other Discovery Formats

There are now several agent-related JSON files on the web, and at first glance they look similar, but each solves a different problem:

agents.json vs A2A's agent.json

Google's Agent-to-Agent (A2A) protocol uses an "Agent Card" at /.well-known/agent.json for agent-to-agent communication. The difference is directional: A2A's agent.json describes what an agent is (identity, skills, supported modes). agents.json describes what an API can do for agents (endpoints, workflows, auth). A2A is for agents that talk to other agents, and agents.json is for agents that talk to your API.

agents.json vs MCP

Anthropic's Model Context Protocol (MCP) provides a stateful connection between an AI model and external tools. An MCP server must be running for the agent to connect to it. agents.json is a static file and needs no server. As Nordic APIs notes , MCP "lacks a discoverability layer" and probably works best alongside something like agents.json that solves the discovery problem.

agents.json vs OpenAPI

OpenAPI documents APIs for human developers. agents.json adds a layer on top for AI agents. It adds three things: flows (multi-step workflows), agent instructions (plain-language guidance for LLMs), and optimized schemas (structured for machines, not for documentation). You keep your OpenAPI spec and build agents.json on top of it.

Related Initiatives Worth Watching

The idea of machine-readable agent capabilities is being explored from multiple angles. Beyond Wildcard, a few other projects are tackling adjacent problems:

agent-permissions.json

The Lightweight Agent Standards Working Group (LAS-WG) is developing agent-permissions.json, a proposal published on arXiv for a "robots.txt-style permission manifest for web agents." agents.json declares capabilities. agent-permissions.json declares permissions: what agents are allowed to do on specific pages, down to individual HTML elements.

The proposal distinguishes resource-level rules (machine-enforceable, like "don't click this button") and action-level guidelines (behavioral directives, like "use _bot at the end of usernames when registering"). Agents can discover it via a <link rel="agent-permissions"> tag or at /.well-known/agent-permissions.json.

JSON Agents (Portable Agent Manifest)

The JSON Agents project defines a Portable Agent Manifest (PAM): a framework-agnostic format for describing AI agents themselves, including capabilities, tools, runtimes, and governance policies. agents.json describes what your API offers to agents, while PAM makes agent definitions portable across frameworks like LangChain, AutoGen, and MCP.

AI Card (Unified AI Service Metadata)

The AI Card initiative wants to unify the growing number of agent discovery files into a single standard. The proposal is a single /.well-known/ai-card.json that includes metadata for all protocols a server supports (MCP, A2A, custom APIs) in one place. It is still at proposal stage. If adopted, one entry point would replace several separate files.

How to Implement agents.json

Implementation takes five steps, based on the Wildcard spec:

Step 1: Inventory Your API Capabilities

List every endpoint you want AI agents to access, such as product search, order placement, account status checks, and appointment booking. Focus on tasks an agent would perform on behalf of a user.

Step 2: Define Agent Flows

For each user task, define the sequence of API calls. Group related endpoints into named chains with clear descriptions and instructions an LLM can understand:

{
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.mystore.com/v1",
  "info": {
    "title": "MyStore API",
    "description": "E-commerce API for product search, cart management, and checkout"
  },
  "auth": {
    "type": "bearer",
    "description": "OAuth 2.0 access token required for cart and checkout operations"
  },
  "chains": {
    "search_products": {
      "description": "Search the product catalog by keyword, category, or price range",
      "agent_instructions": "Use this to help users find products. Supports filtering by category and price.",
      "steps": [
        {
          "endpoint": "/products/search",
          "method": "GET",
          "parameters": {
            "q": "$user_input.query",
            "category": "$user_input.category",
            "min_price": "$user_input.min_price",
            "max_price": "$user_input.max_price"
          }
        }
      ]
    },
    "add_to_cart_and_checkout": {
      "description": "Add a product to the cart and proceed to checkout",
      "agent_instructions": "First add the item to the cart, then initiate checkout. Requires auth.",
      "steps": [
        {
          "endpoint": "/cart/items",
          "method": "POST",
          "parameters": {
            "product_id": "$user_input.product_id",
            "quantity": "$user_input.quantity"
          }
        },
        {
          "endpoint": "/checkout",
          "method": "POST",
          "parameters": {
            "cart_id": "$prev.cart_id"
          }
        }
      ]
    }
  }
}

Step 3: Host the File

Place your agents.json file at the well-known path on your domain:

https://yourdomain.com/.well-known/agents.json

Serve it with Content-Type: application/json and set CORS headers if agents will access it from different origins.

Step 4: Reference Your OpenAPI Spec

Already have an OpenAPI spec? Reference it from your agents.json so agents can access the detailed type definitions. The agents.json flows are the "what to do" layer, OpenAPI is the "how it works" layer:

{
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.example.com",
  "info": {
    "title": "Example API",
    "openapi_spec": "https://api.example.com/openapi.json"
  },
  "chains": {
    "get_user_profile": {
      "description": "Retrieve a user profile by ID",
      "agent_instructions": "Use this when the user wants to view profile information",
      "steps": [
        {
          "endpoint": "/users/{user_id}",
          "method": "GET"
        }
      ]
    }
  }
}

Step 5: Test and Iterate

Use the Wildcard Bridge SDK (Python 3.10+) to validate your agents.json and test agent interactions:

pip install wildcard-bridge

from wildcard_bridge import AgentsJSON

# Load and validate your spec
spec = AgentsJSON.from_url("https://yourdomain.com/.well-known/agents.json")

# List available chains
for chain_name, chain in spec.chains.items():
    print(f"{chain_name}: {chain.description}")

Who Is Using agents.json?

According to the Nordic APIs comparison , Wildcard has published agents.json files for major API providers including Resend, Alpaca, Slack, HubSpot, and Stripe. These files are not maintained by the API providers themselves. Wildcard created them to demonstrate the format.

OpenBB, a financial data platform, has also adopted the format with their own agents.json reference for describing AI agents that connect to their workspace.

Current Status and Maturity

agents.json is the least standardized of the agent discovery formats. A2A has Google behind it with a formal protocol spec. MCP has Anthropic with a growing ecosystem. agents.json is a community proposal driven by one startup.

The current maturity shows in five points:

• No formal RFC. There is no IETF draft or W3C proposal for agents.json. It is an open-source project on GitHub.
• Single primary author. Wildcard AI drives the specification. Community contributions exist but are limited.
• No browser or platform support. No major AI platform (OpenAI, Google, Anthropic) officially consumes agents.json files.
• Incomplete tooling. The Wildcard Bridge SDK is the primary tool. Alternatives are scarce.
• Active development. The roadmap includes memory management, field transformations, rate-limiting, and conditional logic.

Several separate initiatives (agent-permissions.json, JSON Agents, AI Card) work on related ideas. Whatever name the final standard gets, Wildcard's spec is the most concrete attempt so far at a "robots.txt for capabilities."

The New Complement to robots.txt

For thirty years, the contract between sites and bots was one-directional. It said "Here's what you can't do." With robots.txt, site owners blocked paths, restricted crawl rates, and told bots which pages to ignore.

AI agents need a two-directional contract. Sites still set boundaries (robots.txt, agent-permissions.json), and they also need to advertise capabilities. An AI agent that books a flight, compares insurance quotes, or manages a subscription needs to know what is possible, not only what is forbidden.

One possible model combines four files:

• robots.txt - What crawlers cannot access (restrictions)
• llms.txt - What your site is about (content summary for LLMs)
• agents.json - What agents can do (capabilities and workflows)
• agent.json - What your agent is (identity for agent-to-agent communication)

Together, these files form a layered discovery system: access control (robots.txt), content summary (llms.txt), structured interaction (agents.json), and agent-to-agent communication (agent.json).

Expected Evolution

Based on current developments, I expect the following:

Near-term (2026)

• Wildcard agents.json reaches v0.2 with OAuth support and conditional logic
• More API providers publish their own agents.json files (rather than Wildcard doing it for them)
• The LAS-WG agent-permissions.json gains traction as a complementary standard
• AI platforms begin experimenting with consuming capability files during browsing

Medium-term (2026-2027)

• Convergence between competing formats, possibly through the AI Card initiative or a similar unification effort
• Major AI platforms (OpenAI, Google, Anthropic) begin officially supporting a capability discovery standard
• Potential IETF or W3C working group for agent-web interaction standards

Long-term (2027+)

• A unified agent discovery standard emerges, possibly combining elements from agents.json, A2A, and MCP
• Browser-level support for agent capability files, similar to how browsers handle robots.txt
• Agent-aware web frameworks generate capability files automatically from API definitions

Who Should Implement agents.json?

Because the spec is still early, implementing agents.json pays off most for:

• API-first companies that want AI agents to reliably consume their services
• SaaS platforms building AI agent integrations alongside their MCP or A2A support
• E-commerce sites that want agents to search, compare, and transact on behalf of users
• Developer tool providers whose APIs are frequently used by coding agents and AI assistants
• Early adopters who want to be ready when AI platforms begin consuming capability files

Running a content-focused website without APIs (blog, portfolio, informational site)? agents.json is less relevant for you. Focus first on structured data, llms.txt, and semantic HTML . Those have broader support.

Practical Implementation Checklist

Here is a checklist for implementation:

1. Start with your existing OpenAPI spec (or create one if you don't have it)
2. Identify the top 5-10 workflows agents would want to perform
3. Write chains with clear agent_instructions for each workflow
4. Define your authentication scheme
5. Host the file at /.well-known/agents.json
6. Set appropriate CORS headers for cross-origin access
7. Test with the Wildcard Bridge SDK
8. Monitor and iterate as the specification evolves

The Bottom Line

agents.json is a proposal for a web where you tell AI agents what your site can do, so they do not have to guess. The spec is young, the ecosystem is small, and no major platform officially supports it.

Whether to implement it today depends on your situation. If you run an API that agents should use, experiment with it now. If you run a content site, spend your time on structured data, semantic HTML, and llms.txt first. In both cases, it helps to understand AI agent readiness and the idea of declaring capabilities as well as restrictions.

robots.txt told bots what they cannot do. agents.json tells agents what they can.

Sources

• Wildcard AI - agents.json GitHub Repository - Open-source specification (v0.1.0) for agent-API interaction contracts
• Nordic APIs - Comparing 7 AI Agent-to-API Standards - Comparison including agents.json, MCP, A2A, and more
• Hacker News - Show HN: Agents.json – OpenAPI Specification for LLMs - Community discussion on the agents.json specification
• agents.json: an open source specification for AI-API interaction - Overview of agents.json design and implementation
• LAS-WG - agent-permissions.json - Robots.txt-style permission manifest for web agents
• Permission Manifests for Web Agents (arXiv) - Academic paper by the Lightweight Agent Standards Working Group
• JSON Agents - Portable Agent Manifest Specification - Framework-agnostic agent description format
• AI Card - Unified AI Service Metadata Standard - Proposal for a unified agent discovery format
• OpenBB - agents.json Reference - Real-world agents.json implementation for financial data
• A2A Protocol - Agent Discovery - Google's approach to agent discovery via Agent Cards
• Google Cloud - Trends in Agent Discoverability and Interoperability - Overview of the agent discovery landscape
• From robots.txt to agents.json: Web for AI-Agents - Vision for agents.json as the next evolution of web-bot contracts