agents.json: The Missing File That Makes Your Website Agent-Accessible

Most websites have optimized for two audiences: humans and search crawlers. The agent economy requires a third: AI agents. These are autonomous software systems that browse, evaluate, and take actions on websites on behalf of users. And unlike search crawlers, they don't just index your content. They want to do things: book appointments, request quotes, compare pricing, download documentation, trigger API calls.

The robots.txt-style agents.json specification is the file that enables this. It sits at the root of your domain and declares what actions an AI agent is permitted and able to take on your site. Without it, agents have to guess your capabilities by scraping your HTML. With it, you give them a direct, machine-readable map of what's possible.

What agents.json Does

agents.json is to AI agents what robots.txt is to web crawlers: a standardized file at a known path that communicates intent and capability. But where robots.txt restricts access, agents.json extends it, telling agents specifically what they can do rather than what they can't.

A well-formed agents.json file typically declares:

• The name and version of the agent-facing API or interface
• Available actions (search, book, compare, quote, contact, download)
• Required authentication methods
• Rate limits and usage policies
• Contact and support endpoints
• Links to more detailed API documentation

The file lives at /agents.json on your root domain, making it discoverable without prior knowledge: any agent visiting your site can check this path directly.

Why This Matters Now

The number of AI agents interacting with websites is growing rapidly. Browser agents (like OpenAI's Operator and Anthropic's Claude computer use), procurement agents, and customer support agents are all actively navigating websites to complete tasks on behalf of users. Many of them default to scraping unstructured HTML when no structured agent interface is available, which produces inconsistent results and frequently breaks.

Businesses that publish agents.json give these agents a reliable interaction path. Businesses that don't get scraped anyway, with worse results, or get skipped in favor of competitors that have made agent interaction explicit.

The analogy to early SEO is apt. In 2004, most businesses didn't have a sitemap. Now every serious site publishes one because it directly affects search visibility. agents.json is at the same stage: early, optional, but with a first-mover advantage that is rapidly closing.

agents.json vs. agent.json: Understanding the Difference

Two similar filenames serve related but distinct purposes:

agents.json (root of domain, e.g., example.com/agents.json) declares what AI agents can do on your website at a high level: available actions, API endpoints, authentication methods, rate limits. It's a capability manifest for your site.

agent.json (at /.well-known/agent.json) is an Agent-to-Agent (A2A) card, a Google-led standard for declaring that your service can function as an AI agent itself and can be composed with other agents. It's primarily relevant if you're building or exposing an AI service, not just making your website accessible to agents.

For most businesses, agents.json is the more immediately relevant file. The A2A card matters if your product has an API that other AI systems will call directly.

What a Minimal agents.json Looks Like

Here is a minimal agents.json for a SaaS company that wants to declare basic agent accessibility:

{
  "schema_version": "1.0",
  "name": "Acme Platform",
  "description": "Project management software for agencies",
  "url": "https://acme.io",
  "contact": "api@acme.io",
  "agents_supported": true,
  "authentication": {
    "type": "oauth2",
    "authorization_url": "https://acme.io/oauth/authorize",
    "token_url": "https://acme.io/oauth/token",
    "scopes": ["read:projects", "write:tasks"]
  },
  "actions": [
    {
      "name": "search_projects",
      "description": "Search active projects by name or keyword",
      "endpoint": "/api/v1/projects/search",
      "method": "GET",
      "parameters": ["q", "status", "limit"]
    },
    {
      "name": "create_task",
      "description": "Create a new task in a project",
      "endpoint": "/api/v1/tasks",
      "method": "POST",
      "parameters": ["project_id", "title", "assignee", "due_date"]
    },
    {
      "name": "get_pricing",
      "description": "Retrieve current plan pricing and features",
      "endpoint": "/api/v1/pricing",
      "method": "GET",
      "auth_required": false
    }
  ],
  "rate_limits": {
    "requests_per_minute": 60,
    "requests_per_day": 10000
  },
  "documentation": "https://docs.acme.io/agents"
}

Note that get_pricing is declared with auth_required: false. Pricing discovery is one of the most common things AI agents try to do on behalf of users evaluating software, and making it available without authentication removes a friction point that causes agents to abandon your site.

The Most Important Agent Actions to Declare

Not all actions carry equal weight. Based on how procurement and evaluation agents currently operate, the highest-value actions to declare are:

Pricing retrieval is the most common agent task. Agents evaluating software for users will hit your pricing endpoint first. If there's no structured way to retrieve it, they either scrape your pricing page (with variable accuracy) or report that pricing is unavailable, which hurts your conversion rate in agent-mediated research.

Product or service comparison agents frequently compare multiple vendors simultaneously. Structured comparison data with consistent fields (features, limits, pricing tiers) makes your product easier to evaluate accurately against competitors.

Documentation access is critical for technical buyers. If an agent can retrieve your API documentation, integration guides, or technical specs directly, it can provide much more informed recommendations.

Contact and quote request actions give agents a clear conversion path. Without a structured contact endpoint, agents may try to fill out web forms programmatically, which often fails.

Authentication Considerations

A common mistake is requiring authentication for all agent actions. Authentication creates friction that causes agents to skip your site or report limited capability. The better approach is a tiered model:

• Public read actions (pricing, documentation, product details) require no authentication
• Comparison and search actions may require a lightweight API key (free tier, no credit card)
• Write actions (creating accounts, submitting requests, triggering purchases) require full OAuth or bearer token auth

The goal is to make agents as capable as possible with the lowest reasonable authentication barrier, while protecting write operations that have commercial or security consequences.

How Agent Discovery Works

AI agents discover what a site supports through a layered process:

1. Check robots.txt for crawl permissions and declared discovery files
2. Fetch llms.txt for a natural language overview of what the site offers
3. Check agents.json for machine-readable capability declarations
4. Check /.well-known/agent.json for A2A agent card (if looking for composable AI services)
5. Fall back to HTML scraping if no structured files exist

Steps 1 through 4 are fast and structured. Step 5 is slow, error-prone, and produces inconsistent results. Every file you publish at steps 1 through 4 improves the quality of agent interaction with your site.

You can also declare agents.json in your robots.txt to make it more discoverable:

User-agent: *
Allow: /

# AI agent discovery
Sitemap: https://example.com/sitemap.xml
AI-Agents: https://example.com/agents.json
LLMs-Txt: https://example.com/llms.txt

Publishing Your First agents.json

If you have a simple brochure site or informational business without an API, your agents.json can still be useful even without action declarations. A minimal version that declares your business identity, contact info, and what kind of agent interactions are supported gives agents a structured starting point.

For businesses with an API, the process is:

1. Inventory your existing API endpoints and what each one does
2. Classify each as public (no auth), low-friction (API key), or authenticated
3. Write action declarations for your five most agent-relevant endpoints
4. Add rate limit and authentication declarations
5. Publish at /agents.json on your root domain
6. Reference it from your robots.txt

Use Faro's AI Readiness Scan to verify the file is correctly formatted and discoverable after publishing.

The agents.json Ecosystem

The agents.json specification is evolving. Several standards are competing for adoption, including the Anthropic Model Context Protocol (MCP) server pattern, which solves a similar problem through a different mechanism: rather than declaring static capability files, MCP lets AI systems invoke live tool functions directly.

The likely outcome is that agents.json serves as the discovery layer (what can I do here?) while MCP or similar protocols serve as the execution layer (do the thing). Publishing agents.json now positions your business for this architecture regardless of which execution protocol wins.

In Short

agents.json is the machine-readable manifest that tells AI agents what they can do on your website. It sits at your root domain, declares available actions, authentication requirements, and rate limits, and serves as the primary discovery document for any agent visiting your site. Most websites don't have one yet. Publishing a well-formed agents.json today gives you a structural advantage in agent-mediated search, comparison, and procurement over competitors who haven't built for the agent economy.

Check whether your site already has an agents.json with Faro's free AI Readiness Scan. If it doesn't, the scan will also check the other discovery files you need.

Frequently Asked Questions

Is agents.json an official standard?

agents.json is an emerging standard with broad industry adoption underway, but it has not been formally standardized by a body like W3C or IETF as of mid-2026. Several variants of agent capability declaration files are competing for adoption. The file name agents.json (at the root domain) is the most commonly implemented. Publishing one now is a low-risk, high-upside move regardless of how the formal standardization resolves.

Do I need an API to publish agents.json?

No. Even without a public API, you can publish an agents.json that declares your business identity, contact information, and what types of agent interaction your site supports. As you add API capabilities, you extend the file to declare them. Starting with a minimal file is better than waiting for a complete API.

How is agents.json different from llms.txt?

llms.txt is a natural language file written for AI models to understand what your business is and what your site contains. It's human-readable prose that a language model can parse. agents.json is a machine-readable JSON file that declares specific technical capabilities: what API endpoints exist, what authentication they require, and what parameters they accept. You need both: llms.txt for context, agents.json for capability.

How do I validate my agents.json?

You can validate the JSON structure with any JSON linter. For agent-specific validation, Faro's AI Readiness Scan checks that your agents.json is correctly placed, valid JSON, contains required fields, and is properly referenced from robots.txt.