Show HN: Agents.json – OpenAPI Specification for LLMs
18 comments
·March 3, 2025pritambarhate
What's the license of the Python package: https://pypi.org/project/agentsjson/
AGPL? https://github.com/wild-card-ai/agents-json/blob/master/LICE...
yompal
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
luke-stanley
This could be more simple, which is a good thing, well done!
BTW I might have found a bug in the info property title in the spec: "MUST provide the title of the `agents.json` specification. This title serves as a human-readable name for the specification."
winkle
In what ways is the agents.json file different from an OpenAPI Arazzo specification? Is it more native for LLM use? Looking at the example, I'm seeing similar concepts between them.
yompal
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.
winkle
Thanks, that's helpful. I agree there are many other sources REST APIs where this would be helpful. Outside of that I would be interested in understanding the ways where Arazzo takes a broader approach and doesn't really fit an LLM use case.
yompal
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.
melvinmelih
This is interesting but why do you make it so hard to view the actual agents.json file? After clicking around in the registry (https://wild-card.ai/registry) for 10 minutes I still haven't found one example.
yompal
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
melvinmelih
Great, thanks!
ahamilton454
Hey this looks pretty interesting. I saw that you guys are a YC company, how do you intend on making money deploying a protocol?
yompal
We think the main opportunity is to charge API providers, to get white-gloved onto this standard.
tsunego
I like your approach but it's not clear to me whether it's MCP compatible
Anthropic just announced a MCP registry
yompal
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.
winkle
I think MCP being stateful is true in the short term. It's currently at the top of their roadmap to add to the protocol https://modelcontextprotocol.io/development/roadmap.
yompal
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.
sandinmyjoints
Looks cool! How is it similar/different from MCP?
yompal
Thanks! MCP is taking a stateful approach, where every client maintains a 1:1 connection with a server. Developers write applications with stateless APIs. agents.json keeps it that way.
Hey HN, we’re building an open specification that lets agents discover and invoke APIs with natural language, built on the OpenAPI standard. agents.json clearly defines the contract between LLMs and API as a standard that's open, observable, and replicable. Here’s a walkthrough of how it works: https://youtu.be/kby2Wdt2Dtk?si=59xGCDy48Zzwr7ND.
There’s 2 parts to this:
1. An agents.json file describes how to link API calls together into outcome-based tools for LLMs. This file sits alongside an OpenAPI file.
2. The agents.json SDK loads agents.json files as tools for an LLM that can then be executed as a series of API calls.
Why is this worth building? Developers are realizing that to use tools with their LLMs in a stateless way, they have to implement an API manually to work with LLMs. We see devs sacrifice agentic, non-deterministic behavior for hard-coded workflows to create outcomes that can work. agents.json lets LLMs be non-deterministic for the outcomes they want to achieve and deterministic for the API calls it takes to get there.
We’ve put together some real examples if you're curious what the final output looks like. Under the hood, these LLMs have the same system prompt and we plug in a different agents.json to give access to different APIs. It’s all templatized.
- Resend (https://demo.wild-card.ai/resend)
- Google Sheets (https://demo.wild-card.ai/googlesheets)
- Slack (https://demo.wild-card.ai/slack)
- Stripe (https://demo.wild-card.ai/stripe)
We really wanted to solve real production use cases, and knew this couldn’t just be a proxy. Our approach allows you to make API calls from your own infrastructure. The open-source specification + runner package make this paradigm possible. Agents.json is truly stateless; the client manages all memory/state and it can be deployed on existing infra like serverless environments.
You might be wondering - isn’t OpenAPI enough? Why can’t I just put that in the LLM’s context?
We thought so too, at first, when building an agent with access to Gmail. But putting the API spec into LLM context gave us poor accuracy in tool selection and in tool calling. Even with cutting down our output space to 5-10 endpoints, we’d see the LLMs fail to select the right tool. We wanted the LLM to just work given an outcome rather than having it reason each time which series of API calls to make.
The Gmail API, for example, has endpoints to search for threads, list the emails in a thread, and reply with an email given base64 RFC 822 content. All that has to happen in order with the right arguments for our agent to reply to a thread. We found that APIs are designed for developers, not for LLMs.
So we implemented agents.json. It started off as a config file we were using internally that we slowly started adding features to like auth registration, tool search, and multiple API sources. 3 weeks ago, Dharmesh (CTO of Hubspot) posted about the concept of a specification that could translate APIs for LLMs. It sounded a lot like what we already had working internally and we decided to make it open source. We built agents.json for ourselves but we’re excited to share it.
In the weeks since we’ve put it out there, agents.json has 10 vetted API integrations (some of them official) and more are being added every day. We recently made the tool search and custom collection platform free for everyone so it’s even easier for devs to scale the number of tools. (https://wild-card.ai)
Please tell us what you think! Especially if you’re building agents or creating APIs!