Websites were built for people. You see a button, you click it. You see a form, you fill it in. But more and more visitors aren’t people. They’re AI agents, small programs that do jobs for someone, like booking a table or checking an order.
These agents have a hard time on most websites. They have to guess what each button does. That’s where a new kind of file comes in. So, what is an agents.json file, and should you have one? This guide covers what it is, what goes inside it, where it lives, how it compares to llms.txt and robots.txt, and how to make your website ready for AI agents.
What is an agents.json file?
An agents.json file is a small file on a website that tells AI agents what they can do there and how to do it. It lists the actions the site offers, like searching for products or placing an order, and the steps to finish each one. Agents read the file instead of guessing which buttons to click.
Think of it like a menu at a restaurant. Without a menu, you’d have to walk into the kitchen and ask the cook what they can make. With a menu, you see every dish and how to order it. An agents.json file is a menu for AI agents.
The file is written in JSON, a simple text format that computers read easily. JSON stands for JavaScript Object Notation. It uses curly brackets with names and values, like "name": "My Store".
The best known version is an open project started by a company called Wildcard AI. Anyone can use it for free, and you can read the full details on GitHub. It’s still young. The current version is 0.1.0.
Why do websites need a file for AI agents?
Right now, most AI agents use a website the hard way. They load the page, read the text and try to work out which button to press. If the design changes, the agent can get lost. If a popup appears, it can get stuck.
Many sites also have an API. An API is a side door made for programs. It lets software ask for data or send an order without clicking anything. But APIs were written for human developers. They list each action one by one. They don’t explain how to put actions together to finish a real job.
Take buying a product. An agent may need to search for it, add it to the cart and then check out. That’s three actions in the right order. An agents.json file spells out that order, so the agent doesn’t have to guess.
In short, the file helps in three ways:
- Agents find what your site can do faster. No more digging through pages.
- Fewer mistakes. Clear steps mean fewer failed orders or wrong bookings.
- You stay in charge. You pick which actions to share and which to keep private.
What goes inside an agents.json file?
Wildcard’s version has four main parts:
Part | What it means | Example |
|---|---|---|
info | Basic details, like the name, a short description and the file version | “Example Store” |
sources | Where the full API description lives, usually an OpenAPI file | A link to openapi.json |
flows | Ready to use jobs an agent can do, made of one or more API calls in order | “Find and buy a product” |
links | How the result of one step feeds into the next step | The product ID from the search goes into “add to cart” |
OpenAPI is a common way to describe an API, and many companies already have one. An agents.json file doesn’t replace it. It sits on top and adds the extra hints agents need, like which steps go together and what each job is for.
A simple agents.json example
Here’s a short example for an online store. It follows the main shape of Wildcard’s format, with some parts trimmed so it’s easy to read.
Read it like this. The store offers one job called “Find and buy a product.” It takes three steps: search, add to cart and pay. The link says to take the product ID from the search results and use it when adding to the cart. Before you build a real file, check the full format in the official docs, because it has more fields than this.
Where does the agents.json file go?
The file sits on your own website. The main specification suggests this address:
https://yourwebsite.com/.well-known/agents.json
The /.well-known/ folder is a standard spot on websites for files that programs look for. Other machine files, like security.txt and the A2A agent card, live there too. Some guides put the file at the root instead, at yourwebsite.com/agents.json. The .well-known address is the better choice because it’s the one the specification asks for.
How do AI agents use an agents.json file?
Here’s what happens, step by step:
- A person gives an agent a job, like “Order more printer paper from my usual store.”
- The agent visits the store’s site and checks for /.well-known/agents.json.
- It reads the flows and picks the one that fits, such as “Find and buy a product.”
- It fills in the details, like the product name and how many to buy.
- It runs each step through the API, one after another, and reports back.
The file doesn’t do anything by itself. It’s a set of directions. The agent, or a helper tool such as Wildcard’s Bridge library, does the actual work. The file also doesn’t remember anything between visits. The agent keeps track of what happened.
Clear directions matter even more when several agents share one job. You can read more about that in our guide to single agent vs multi-agent systems.
agents.json vs llms.txt, robots.txt and agent cards
Several small files now talk to bots and agents. Their names sound alike, so they’re easy to mix up. Here’s how they compare:
File | What it tells programs | Format | Where it lives |
|---|---|---|---|
robots.txt | Which pages crawlers may or may not visit | Plain text | /robots.txt |
llms.txt | A short summary of your content for AI tools | Markdown | /llms.txt |
agents.json | What actions agents can take and in what order | JSON | /.well-known/agents.json |
A2A agent card | Who one AI agent is and how to talk to it | JSON | /.well-known/agent-card.json |
Here’s an easy way to remember it. Robots.txt sets the rules. llms.txt shares your content. Agents.json shares your actions. An A2A agent card introduces one agent so other agents can work with it.
What about MCP?
MCP, short for Model Context Protocol, also lets AI tools use outside apps. The difference is that MCP needs a live server that answers the AI tool in real time. An agents.json file is a plain file that just sits on your site. Some teams use both.
agent.json vs agents.json
One letter makes a big difference. “agent.json” with no s has been used for a few different things, including the old name of the A2A agent card. The A2A project now calls that file agent-card.json. “agents.json” with an s usually means a file that describes what a website lets agents do. When you read a guide, check which one it means.
Is agents.json an official standard?
No, not yet. Here’s where things stand in November 2026:
- Wildcard’s agents.json specification is an open project at version 0.1.0. It’s free to use, but no standards group owns it.
- In June 2026, an independent author sent a draft to the IETF, the group behind many internet standards. It describes an agents.txt file and a matching agents.json file with a different layout. It’s only a draft. The IETF hasn’t approved it, and it ends in December 2026 unless someone updates it.
- Other companies use the same file name for their own formats.
- Google hasn’t said it uses agents.json in search. We found no official Google guidance on it.
So treat agents.json as an early, useful idea, not a rule. That’s also why it’s smart to build it on something solid, like a clean OpenAPI file. That part stays useful whatever happens to the name.
Does your website need an agents.json file?
It depends on what your site does.
It’s worth adding if:
- People can book, order, buy or sign up on your site.
- You have a public API or a software product people log in to.
- You want AI assistants to finish tasks for your customers.
It can wait if:
- Your site is a simple information site or a blog.
- You have no API and no online actions.
- Your basic site setup still needs work. Fix that first.
For most small business sites, the bigger win today is a fast site with clear pages that agents and search engines can both read. Add agents.json when you have real actions to share.
How to make your website ready for AI agents
Getting ready takes more than one file. Work through these steps in order:
- Make your pages easy to read. Your main text should be in the page’s HTML, not only added later by scripts. Many AI crawlers don’t run JavaScript.
- Add structured data. Schema markup tells programs what your business is, what you sell and who wrote each page.
- Check your robots.txt. Make sure you’re not blocking the AI tools you want to reach you, like GPTBot, ClaudeBot or PerplexityBot.
- Describe your API. If you have one, write it up with OpenAPI.
- Add agents.json. List the main jobs agents can do as flows.
- Test it. Make sure the file loads and has no typing errors. Then try a real task with an agent.
How to check if a website is AI agent ready
You can do these quick checks in about 10 minutes:
- Open yoursite.com/robots.txt and look for lines that block AI bots.
- Right click a page and choose “View page source.” Can you see your main text there?
- Test a page in Google’s Rich Results Test to see your structured data.
- Visit yoursite.com/.well-known/agents.json. Does it load?
- Paste your file into a free JSON checker to spot typing mistakes.
There are also free online scanners that score how ready a site is for agents. They can help, but read their advice with care. Many are run by companies that sell the fixes.
How to create an agents.json file
If your site has an API, here’s how to build the file:
- List the jobs. Write down the three to five tasks customers do most, like “check order status” or “book a call.”
- Match each job to API calls. Find the right endpoints in your OpenAPI file. An endpoint is one action the API can do.
- Write the flows. Give each one a clear title and description in plain words. Agents read them like instructions.
- Add the links. Show which result from one step goes into the next.
- Put it online. Upload it to /.well-known/agents.json so it opens as a JSON file.
- Check it and keep it fresh. Test the file, and update it every time your API changes.
Keep it safe
Your agents.json file is public. Anyone can read it. So follow a few simple rules:
- Only list actions you’re happy for agents to use.
- Keep sign in and payments protected. The file is a guide, not a lock.
- Never put passwords or API keys in it.
- Watch your site logs for strange spikes in traffic.
How BSi Innovation can help
We build websites and AI agents for businesses in the US and around the world. We can check if your site is ready for agents, describe your API and set up your agents.json file. If you want an agent of your own, take a look at our AI agent development services or tell us about your project.
FAQs about agents.json
What is an agents.json file in simple words?
It’s a small file on a website that works like a menu for AI agents. It lists the jobs an agent can do on the site and the steps to finish each one.
Where should I put my agents.json file?
Put it at yourwebsite.com/.well-known/agents.json. That’s the address the main specification suggests.
What is the difference between agents.json and llms.txt?
llms.txt shares a summary of your content so AI tools can read it. agents.json shares your actions so AI agents can do things on your site, like place an order.
Is agents.json the same as agent.json?
No. agents.json usually describes what a website lets agents do. agent.json has been used for other things, including an old name for the A2A agent card, which is now called agent-card.json.
Does agents.json help with Google rankings?
There’s no sign that it does. Google hasn’t said it uses agents.json. The file is there to help agents take actions, not to rank pages.
Do I need an API to use agents.json?
For the main version, yes. It’s built on top of an API description called OpenAPI. If your site has no API, start there first.
Is it safe to publish an agents.json file?
Yes, if you set it up with care. Only list actions you’re happy to share, keep sign in and payments protected, and never put passwords or keys in the file.
Key takeaways
- An agents.json file tells AI agents what your website can do and the steps to do it.
- It lives at /.well-known/agents.json and is built on top of your OpenAPI file.
- It shares actions. llms.txt shares content. robots.txt sets rules.
- It’s still an early idea, not an official standard, and Google hasn’t said it uses it.
- Add one if people can book, buy or sign up on your site. Fix the basics first if they can’t.