What is agent.json? Why Your Website Needs It to Talk to AI

agent.json is a structured metadata file placed at the root of your domain that tells AI agents what your product or service does, how to interact with it, and what capabilities it offers. Think of it as your website's machine-readable business card — a standardized way for autonomous AI systems to discover, evaluate, and integrate with your offering without human intervention.

What Is agent.json and Why Does It Exist?

As AI assistants evolve from passive question-answerers into autonomous agents that browse the web, compare products, and take actions on behalf of users, they need a reliable way to understand what a website offers. Traditional HTML pages are designed for humans. Crawlers and scrapers can extract information, but the results are inconsistent and error-prone. agent.json solves this by providing a single, predictable file that any AI system can fetch and parse in milliseconds.

The concept is simple: place a JSON file at https://yourdomain.com/agent.json that describes your service in a structured format. AI agents visiting your site can read this file to understand your capabilities, pricing model, integration options, and contact information — all without scraping a single page.

This is part of a broader AEO (AI Engine Optimization) strategy. While schema markup helps search engines understand page-level content, agent.json operates at the service level, giving AI systems a holistic view of your entire offering.

A Complete agent.json Example

Here is a full agent.json file for a fictional project management SaaS:

{
  "schema_version": "1.0",
  "name": "TaskFlow",
  "description": "TaskFlow is a project management platform designed for remote teams. It combines task tracking, real-time collaboration, and automated reporting into a single workspace.",
  "url": "https://taskflow.io",
  "logo": "https://taskflow.io/logo.png",
  "capabilities": [
    "task-management",
    "team-collaboration",
    "time-tracking",
    "reporting",
    "integrations",
    "api-access"
  ],
  "contact": {
    "email": "hello@taskflow.io",
    "support_url": "https://taskflow.io/support",
    "documentation": "https://docs.taskflow.io"
  },
  "features": [
    {
      "name": "Kanban Boards",
      "description": "Visual task boards with drag-and-drop cards, custom columns, and swimlanes for organizing work across teams."
    },
    {
      "name": "Sprint Planning",
      "description": "Agile sprint tools with velocity tracking, backlog grooming, and burndown charts."
    },
    {
      "name": "Time Tracking",
      "description": "Built-in time tracking with automatic timesheets and billable hour reports."
    },
    {
      "name": "Team Chat",
      "description": "Real-time messaging with threaded conversations, file sharing, and task-linked discussions."
    },
    {
      "name": "Automated Reports",
      "description": "Scheduled project status reports delivered via email or Slack with customizable metrics."
    }
  ],
  "pricing": {
    "model": "subscription",
    "currency": "USD",
    "plans": [
      {
        "name": "Free",
        "price": 0,
        "billing_cycle": "month",
        "features": ["Up to 5 users", "Basic boards", "1 GB storage"]
      },
      {
        "name": "Pro",
        "price": 12,
        "billing_cycle": "month",
        "per": "user",
        "features": ["Unlimited users", "Advanced boards", "Time tracking", "50 GB storage"]
      },
      {
        "name": "Enterprise",
        "price": null,
        "billing_cycle": "month",
        "per": "user",
        "features": ["SSO/SAML", "Audit logs", "Dedicated support", "Unlimited storage"],
        "contact_sales": true
      }
    ],
    "free_trial": {
      "available": true,
      "duration_days": 14
    }
  },
  "integrations": [
    {
      "name": "Slack",
      "type": "messaging",
      "url": "https://docs.taskflow.io/integrations/slack"
    },
    {
      "name": "GitHub",
      "type": "development",
      "url": "https://docs.taskflow.io/integrations/github"
    },
    {
      "name": "Google Calendar",
      "type": "calendar",
      "url": "https://docs.taskflow.io/integrations/google-calendar"
    },
    {
      "name": "Zapier",
      "type": "automation",
      "url": "https://docs.taskflow.io/integrations/zapier"
    }
  ],
  "api": {
    "available": true,
    "documentation": "https://docs.taskflow.io/api",
    "spec_url": "https://taskflow.io/openapi.json",
    "auth_type": "bearer_token"
  },
  "compliance": ["SOC2", "GDPR", "HIPAA"],
  "languages": ["en", "es", "de", "ja", "zh"],
  "updated_at": "2026-01-15T00:00:00Z"
}

This single file communicates everything an AI agent needs to recommend TaskFlow to a user asking for project management tools — capabilities, pricing, integrations, compliance, and how to get started.

agent.json vs llms.txt: What's the Difference?

Both agent.json and llms.txt serve the goal of making your service understandable to AI systems, but they do so in fundamentally different ways. llms.txt is a markdown-based file designed to be readable by large language models in their context windows — it's essentially a briefing document written in natural language. agent.json is a structured data file designed for programmatic consumption by AI agents that need to parse, compare, and act on service information.

In practice, you should have both. llms.txt tells an AI model the story of your product in rich, persuasive prose. agent.json gives an AI agent the structured facts it needs to filter, compare, and take action. They are complementary layers of a complete AEO strategy.

Full Field Reference

Every field in agent.json serves a specific purpose. Here is a comprehensive breakdown of the specification:

Required Fields

Recommended Fields

Optional Fields

Best Practices for Each Field

• description: Write in third person. State what the product does, who it's for, and what makes it distinct. Avoid subjective claims like "the best" — AI agents favor factual, verifiable statements.
• capabilities: Use standardized vocabulary where possible. An AI agent filtering for "time-tracking" needs to match your capability tag exactly.
• pricing: Set price to null for custom/enterprise plans and include "contact_sales": true. Always specify billing_cycle and currency.
• features: Limit descriptions to 1–2 sentences. Focus on what the feature does, not why it's great.
• updated_at: Keep this current. Stale timestamps signal abandoned or unreliable data.

How to Deploy agent.json

Deploying agent.json takes five steps. Each one is straightforward, but skipping any of them can prevent AI agents from discovering or trusting your file.

Step 1: Place It at Your Domain Root

The file must be accessible at https://yourdomain.com/agent.json. This is the canonical location that AI agents check first, similar to how search engines look for robots.txt or sitemap.xml at the root.

For static sites, place the file in your public/ or static/ directory. For server-rendered applications, create a route handler:

// Next.js example: app/agent.json/route.ts
import { NextResponse } from "next/server";
import agentData from "@/data/agent.json";

export async function GET() {
  return NextResponse.json(agentData, {
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Cache-Control": "public, max-age=86400",
    },
  });
}

Step 2: Configure CORS Headers

AI agents operate from various domains and need permission to fetch your file. Set the Access-Control-Allow-Origin header to * for your agent.json endpoint. If you're using Cloudflare, Vercel, or Nginx, add CORS headers at the configuration level:

# Nginx configuration
location = /agent.json {
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Methods "GET, OPTIONS";
    add_header Content-Type "application/json";
}

Step 3: Validate JSON Syntax

A single misplaced comma or unclosed bracket will render your entire file unparseable. Before deploying, validate your JSON:

# Validate with Python
python -m json.tool agent.json > /dev/null

# Or use jq
jq . agent.json > /dev/null

Online validators like JSONLint work as well, but command-line tools integrate better into CI/CD pipelines.

Step 4: Test Accessibility

After deployment, verify that your file is publicly accessible and returns valid JSON:

curl -s https://yourdomain.com/agent.json | jq .

Check that the response includes the correct Content-Type: application/json header and that CORS headers are present:

curl -I https://yourdomain.com/agent.json

Step 5: Reference in llms.txt

If you also maintain an llms.txt file, add a reference to your agent.json so AI systems can discover both:

# Your Product Name
> One-line description of your product

## Machine-Readable Data
- [agent.json](https://yourdomain.com/agent.json): Structured service metadata for AI agents

This cross-referencing creates a complete discovery surface for all types of AI systems.

Real-World Use Cases

agent.json isn't a theoretical specification — it's already shaping how AI agents interact with web services.

Product Discovery and Comparison

When a user asks an AI assistant "Find me a project management tool with time tracking that integrates with Slack under $15/user/month," the agent can fetch agent.json from multiple providers, filter by the capabilities array for "time-tracking", check the integrations array for Slack, and compare pricing.plans objects to find matches under the price threshold. This structured approach is orders of magnitude more reliable than scraping pricing pages.

Automated Integration Workflows

AI coding assistants can read the api field of agent.json to determine whether an API is available, find its OpenAPI specification, and generate integration code automatically. A developer saying "Connect our app to TaskFlow" can trigger an agent that reads TaskFlow's agent.json, discovers the API docs, and scaffolds the integration.

Compliance Screening

Enterprise procurement AI can check the compliance array to quickly filter vendors that meet regulatory requirements. Instead of searching through an entire website for SOC2 certification badges, the agent reads a single field.

Multilingual Recommendations

AI agents serving international users can check the languages array to ensure a recommended product supports the user's language before suggesting it.

How Skillaeo Auto-Generates agent.json

Building an agent.json from scratch requires understanding the spec, gathering accurate product information, and structuring it correctly. Skillaeo's Skills Pack feature automates this entire process.

When you run an AEO audit with Skillaeo, the platform analyzes your website and existing structured data to extract key information about your service — capabilities, features, pricing signals, integrations, and more. It then generates a complete agent.json file tailored to your product, alongside your llms.txt and other AEO assets.

The Skills Pack output includes:

• A validated agent.json file ready for deployment
• An llms.txt file with natural language descriptions
• Schema markup recommendations for page-level optimization
• Deployment instructions specific to your hosting platform

This means you go from zero AI discoverability to a fully deployable agent.json in minutes, without manually writing a single line of JSON.

Common Mistakes

Even straightforward specifications can trip up teams during implementation. Here are the most frequent agent.json errors and how to avoid them.

Invalid JSON Syntax

This is by far the most common issue. Trailing commas, unquoted keys, and single quotes instead of double quotes all produce invalid JSON that agents silently reject:

// ❌ Invalid: trailing comma
{
  "name": "MyApp",
  "url": "https://myapp.com",
}

// ✅ Valid: no trailing comma
{
  "name": "MyApp",
  "url": "https://myapp.com"
}

Always validate before deploying. Integrate JSON validation into your CI/CD pipeline to catch errors before they reach production.

Missing Required Fields

Every agent.json must include schema_version, name, description, and url. Omitting any of these causes agents to treat the file as incomplete and unreliable. Some agents discard the entire file if required fields are missing.

Outdated Information

Pricing changes, new features launch, integrations are added — but the agent.json stays frozen. Set a recurring reminder to review your agent.json monthly, or better yet, generate it dynamically from your product database.

Wrong CORS Configuration

If your server doesn't send Access-Control-Allow-Origin: * on the agent.json endpoint, browser-based AI agents cannot fetch the file. This is especially common on sites using strict security headers. Test from a different origin to verify.

Marketing Language Instead of Facts

agent.json is not a landing page. Descriptions like "The world's most powerful platform" are useless to an AI agent filtering by capability. Write factual, specific descriptions: "Project management platform for teams of 5–500 with Kanban boards, sprint planning, and time tracking."

How agent.json Compares to Other Standards

agent.json exists within an ecosystem of structured data formats, each serving a different purpose. Understanding where it fits helps you build a complete AI optimization strategy.

For maximum AI visibility, implement all four where applicable. Schema.org JSON-LD handles page-level SEO. llms.txt handles narrative context for language models. OpenAPI documents your API for developer-facing agents. And agent.json ties everything together at the service level, giving AI agents a single entry point for understanding your entire offering.

Learn more about how schema markup supports AI optimization and how to audit your full AEO setup.

Frequently Asked Questions

Is agent.json an official web standard?

Not yet. agent.json is an emerging convention in the AEO community, similar to how llms.txt emerged from a need to communicate with large language models. While there is no W3C or IETF specification, adoption is growing as AI agents become more prevalent. Following the structure outlined in this guide ensures compatibility with current implementations.

Can agent.json replace my Schema.org markup?

No. They serve different purposes. Schema.org JSON-LD is embedded in individual HTML pages and helps search engines understand page-specific content — a product, an article, an event. agent.json sits at the domain root and describes your entire service. Use both for complete coverage.

How often should I update agent.json?

Update it whenever your product changes in ways that affect the information in the file — new features, pricing changes, added integrations, new compliance certifications, or language support. At minimum, review quarterly. Set the updated_at field to reflect the actual date of the last change.

Do AI assistants like ChatGPT and Claude already read agent.json?

AI assistants with web browsing capabilities can fetch and parse agent.json when researching products. As the convention matures, more AI systems are expected to check for this file during product evaluation tasks. Deploying it now positions you ahead of broader adoption.

What if I have multiple products under one domain?

For multi-product domains, you have two options. You can create a single agent.json at the root that describes all products using a top-level products array, or you can place separate agent.json files at product-specific paths (e.g., /product-a/agent.json). The root-level approach is recommended for discoverability, with references to product-specific files if needed.

Start Building Your agent.json Today

agent.json is a small file with outsized impact. As AI agents increasingly mediate how users discover, evaluate, and choose products, having a machine-readable service description at your domain root is no longer optional — it's the cost of being visible.

The specification is straightforward, deployment takes minutes, and the payoff is immediate: your service becomes parseable, comparable, and actionable for every AI agent that visits your domain.

Want to generate your agent.json automatically? Run a free AEO audit with Skillaeo and create your complete Skills Pack in minutes.