yompal

You're the best :) thanks for inspiring

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.

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 to flip this into a proxy service.

That said, what do you think is the right license for something like this? This is our first time doing OSS.

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.

Funnily enough, a search tool to solve this problem was our product going into YC. Now it’s a part of what we do with wild-card.ai and agents.json. I’d love to extend the tool search functionality for all the tools in your belt

It took us a decently long time to get the search quality good. Just a heads up in case you want to implement this yourself

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

Interesting! Reach out if you want to chat about it :)

That approach does a lot better, but LLMs still have positional bias problem baked into the transformer architecture (https://arxiv.org/html/2406.07791v1). This is where the LLM biases selecting information earlier in the prompt than later, which is unfortunate for tool selection accuracy.

Since 2 steps are required anyways, might as well use a dedicated semantic search for tools like in agents.json.

Potentially. I also have reservations about it not technically being open source

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.

4) Great idea! I think this would be so useful

No worries! In other cases, I believe you would be right. But splitting up context is not optional with MCP. Part of the whole state will always reside in an external entity.

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.

Bearish on everyone needing to be on stateful protocols. Developers should have the option to have their state managed internal to their application.

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.

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.

We work with API providers to write this file. It takes a non-negligible amount of thought to put together since we're encoding which outcomes would be useful to enable/disable for an LLM. The standard is open so anyone can write and read and agents.json. Mainly intended for API providers to write.

LLMs do well with outcome-described tools and APIs are written as resource-based atomic actions. By describing an API as a collection of outcomes, LLMs don't need to re-reason each time an action needs to be taken.

Also, when an OpenAPI spec gets sufficiently big, you face a need-in-the-haystack problem https://arxiv.org/abs/2407.01437.

It now reads "MUST provide the title of the `agents.json` specification file. ..." Thanks for the heads up!

It's not that Arazzo can't work for LLMs, just that it's not the primary use case. We want to add LLM enabled transformations between linkages. Arazzo having to serve other use cases like API workflow testing and guided docs experiences may not be incentivized to support these types of features.

Yup. The specification is under Apache 2.0 and the Python package is under AGPL.

The full licenses can be found here: https://docs.wild-card.ai/about/licenses

We've been keeping a close eye on this topic: https://github.com/modelcontextprotocol/specification/discus...

The options being considered to do this are:

1) maintain a session token mapping to the state -- which is still statefulness

2) create a separate stateless MCP protocol and reimplement -- agents.json is already the stateless protocol

3) reimplement every MCP as stateless and abandon the existing stateful MCP initiative

As you can tell, we're not bullish on any of these.

We've been in touch with Arazzo after we learned of the similarities. The long-term goal is to be aligned with Arazzo. However, the tooling around Arazzo isn't there today and we think it might take a while. agents.json is meant to be more native to LLMs, since Arazzo serves other use cases than LLMs.

To be more specific, we're planning to support multiple types of sources alongside REST APIs, like internal SDKs, GraphQL, gRPC, etc.

MCP is great for the stateful systems, where shared context is a benefit, but this is a rarity. Developers generally write clients to use APIs in a stateless way, and we want to help this majority of users.

That said, agents.json is not mutually exclusive to MCP. I can see a future where an MCP for agents.json is created to access any API.

Thanks! 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 or deployed MCP server for each user.

That's a good point. I'll add a download button to the registry. The agents.json are also available here https://github.com/wild-card-ai/agents-json/tree/master/agen...

EDIT: updated

We think the main opportunity is to charge API providers, to get white-gloved onto this standard.