Fair question. Pydantic.ai looks like a wrapper around the client and closer to an agent framework. agents.json is not that.
agents.json makes an existing API format like OpenAPI, interpretable to LLMs. This is done through tool selection and workflow creation.
For example, someone here mentioned the large Twilio API was hard to manage with an LLM. We could write a Twilio agents.json to bundle API calls into outcome-based workflows, and create a searchable collection that lets us get higher accuracy on tool selection.
Not ignorant at all! This is our favorite question.
MCP is taking a stateful approach, where every client maintains a 1:1 connection with a server. This means that for each user/client connected to your platform, you'd need a dedicated MCP server. We're used to writing software that interfaces with APIs, as stateless and deployment agnostic. agents.json keeps it that way.
For example, you can write an web-based chatbot that uses agents.json to interface with APIs. To do the same with MCP, you'd spin up a separate lambda MCP or process MCP server for each user.
We see the same vision you've described, and it'll take thoughtful execution and distribution on our part to continue to make agents.json the standard for tool use.
I've been in touch with the AX team at Netlify since the article was first published. A lot of very relatable philosophies in that article that stuck with me.
The tail of the problem is quite long. Even if the average model is perfect at these things, do we want them to re-reason each time there's an impasse of outcomes? Often, the outcomes we want to achieve have well traversed flows anyways and we can just encode that.
In fact, I'm looking forward to the day that models are better at this so we can generate agents.json automatically and self-heal with RL.
On the business model, ¯\_(ツ)_/¯. We don't charge developers, anyways
1) Thanks for being a part of the journey! We also want something that works for us as agent developers. We didn't feel like anything else was addressing this problem and felt like we had to do it ourselves.
We love feedback! This is our first time doing OSS.
I agree - MCP and agents.json are not mutually exclusive at all. They solve for difference clients.
2) Agreed. Something we're investing in soon is a generic SDK that can run any valid agents.json. That means the docs might getting a revamp soon too.
3) While many API services may not use OpenAPI, their docs pages often do! For example, readme.com lets you export your REST API docs as OpenAPI. As we add more types of action sources, agents.json won't be 1:1 with OpenAPI. In that way, we left the future of agents.json extensible.
llms.txt is a great standard for making website content more readable to LLMs, but it doesn’t address the challenges of taking structured actions. While llms.txt helps LLMs retrieve and interpret information, agents.json enables them to execute multi-step workflows reliably.
The end developer doesn't need to even see or read the agents.json file. It's a means for transparency and meant to be implemented by the API provider. Tooling to make creating an agents.json easier is on our roadmap. We have a process internally where we use a validator to guide creating an agents.json.
So,the api provider, like stripe, is supposed to publish a second API?
And then the "end developer" who is going to be making a chatbot/agent, is supposed to use that to make a chatbot?
Why does the plan involve there being multiple third party developers to make n products per provider? If the plan is to have third parties be creative and combine, say, Stripe with Google Ads, then how is a second API for LLMs useful.
I'm not seeing the vision here. I've seen something similar in a project where a guy wanted LLM developers to use his API for better browsing websites. If your plan involves:
1- Bigger players than you implementing your protocol
2- Everybody else doing the work.
It's just obviously not going to work and you need to rethink your place in the food chain.
We're grateful that bigger players like Resend, Alpaca, etc do want to implement the protocol. The problem is honestly onboarding them fast enough. That's one of the main areas we're going to build out in the next few weeks. Until then, we're writing every agents.json.
If you check out wild-card.ai and create your own collection, you'll find that it's actually really easy to develop with. As a developer, you never have to look at an agents.json if you don't want to.
A couple people have mentioned some relevant things in this thread. This SDK isn't meant to be restrictive. This can be implemented into other open-source frameworks as a plugin(ie. BrowserUse, Mastra, LangChain, CrewAI, ...). We just don't want someone like AWS flip this into a proxy service.
Some have asked us to host a version of the agents.json SDK. We're torn on this because we want to make it easier for people to develop with agents.json but acting as a proxy isn't appealing to us and many of the developers we've talked to.
That said, what do you think is the right license for something like this? This is our first time doing OSS.
