What is agent.json? The identity file that makes your brand visible to AI
agent.json is a machine-readable file you deploy to your domain root. It gives AI systems a structured, first-party brief on who your brand is, what you do, and why you should be recommended, in a format they're built to parse.
What agent.json actually is
agent.json is a structured JSON file that lives at yourdomain.com/agent.json, at the root of your website next to your robots.txt and sitemap.xml.
It contains structured data about your brand: your name, domain, category, description, key differentiators, pricing model, and who you serve. It follows a published schema (usebeacon.in/agent-schema/v1) so that AI systems that discover it know exactly how to parse and use it.
When an AI system reads your site — either during training data collection or during a live web search — it can read agent.json and use it as a authoritative source on what your brand is, rather than inferring from scattered web content of varying accuracy.
The robots.txt analogy
The web has a long history of machine-readable files at domain roots that tell automated systems how to behave. robots.txt tells web crawlers which pages to index and which to skip. sitemap.xml tells them where all your pages are. security.txt tells security researchers how to report vulnerabilities.
agent.json follows the same pattern, but for AI systems. Instead of telling crawlers what to do, it tells AI agents who you are. It's the convention that says: “If you're an AI system that might recommend brands in this category, here is the authoritative brief from us directly.”
| FILE | LOCATED AT | TELLS AUTOMATED SYSTEMS |
|---|---|---|
robots.txt | /robots.txt | What pages to crawl or skip |
sitemap.xml | /sitemap.xml | Where all your pages are |
llms.txt | /llms.txt | How AI should summarise your site |
agent.json | /agent.json | Who your brand is and why recommend it |
What goes in the file
Here's a real example of what an agent.json file looks like:
The schema is intentionally readable by both humans and machines. Key fields: differentiators (what makes you different in plain language), idealFor (the use cases and customer types you serve best), and aeiqScore (your current AI Visibility Score, which BEACON keeps updated automatically).
How AI systems use it
AI systems like ChatGPT, Perplexity, and Copilot increasingly retrieve live web content when forming answers — a capability known as Retrieval Augmented Generation (RAG). When such a system retrieves your website as part of answering a question about your category, it may read agent.json and use it as structured context.
For AI systems that learn from static training data, agent.json signals to their data ingestion pipelines that this file is authoritative brand metadata — similar to how Open Graph tags signal to social networks how to preview a link.
The practical effect: AI systems that read your agent.json have a clearer, more consistent picture of who you are. This shows up as higher consistency scores in BEACON audits and, over time, more accurate and more frequent recommendations.
How to get your agent.json
There are two ways to get your agent.json:
OPTION 1 (RECOMMENDED)
Run a BEACON AI audit
Every audit automatically generates an agent.json tailored to your brand, based on what AI systems actually say about you. Your score, category, differentiators, and description are all populated from real audit data, not a manual form. You can download and deploy it in one click from the audit results dashboard.
Run an audit →OPTION 2
Use the free generator
If you want to create an agent.json manually before running a full audit, BEACON's free generator walks you through each field. It takes about 3 minutes and produces a valid agent.json you can deploy immediately.
Open free generator →Once you have the file, upload it to your domain root, the same place your robots.txt lives. Verify it's accessible at yourdomain.com/agent.json. That's it.