[HN Gopher] Show HN: Agents.json - OpenAPI Specification for LLMs
___________________________________________________________________
Show HN: Agents.json - OpenAPI Specification for LLMs
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!
Author : yompal
Score : 65 points
Date : 2025-03-03 17:01 UTC (5 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| ahamilton454 wrote:
| 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 wrote:
| We think the main opportunity is to charge API providers, to
| get white-gloved onto this standard.
| sandinmyjoints wrote:
| Looks cool! How is it similar/different from MCP?
| yompal wrote:
| 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.
| melvinmelih wrote:
| 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 wrote:
| 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 wrote:
| Great, thanks!
| tsunego wrote:
| I like your approach but it's not clear to me whether it's MCP
| compatible
|
| Anthropic just announced a MCP registry
| yompal wrote:
| 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 wrote:
| 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 wrote:
| We've been keeping a close eye on this topic: https://githu
| b.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.
| esafak wrote:
| Isn't the idea to create a data lake to better inform models?
| Why are you bearish on stateful protocols? Could you
| elaborate on your thinking?
| yompal wrote:
| Bearish on everyone needing to be on stateful protocols.
| Developers should have the option to have their state
| managed internal to their application.
| esafak wrote:
| Can't you simply use a stateful protocol and not report
| any state? Doesn't statefulness subsume statelessness? I
| am beginning to wrap my head around this space, so excuse
| the naive questions.
| yompal wrote:
| 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.
| winkle wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| pritambarhate wrote:
| 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 wrote:
| 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 wrote:
| 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."
| yompal wrote:
| It now reads "MUST provide the title of the `agents.json`
| specification file. ..." Thanks for the heads up!
| alooPotato wrote:
| Can some help me understand why agents can't just use APIs
| documented by an openapi spec? Seems to work well in my own
| testing but I'm sure I'm missing something.
| yompal wrote:
| 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.
| bberenberg wrote:
| Cool idea but seems to be dead on arrival due to licensing. Would
| love to have the team explain how anyone can possibly adopt their
| agpl package into their product.
| froggertoaster wrote:
| Echoing this - is there a commericialization play you're hoping
| to make?
| favorited wrote:
| Sounds like the spec is Apache 2.0. The Python package is
| AGPLv3, but the vast majority of the code in there looks to be
| codegen from OpenAPI specs. I'd imagine someone could create
| their own implementation without too much headache, though I'm
| just making an educated guess.
| yompal wrote:
| 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.
| ripped_britches wrote:
| Can you explain what the LLM sees in your Gmail example instead
| of the chain?
|
| And how is that translation layer created? Do you write it
| yourself for whatever you need? Or is the idea for API owners to
| provide this?
|
| I'm sure the details are there if I dig deeper but I just read
| the readme and this post.
| yompal wrote:
| 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.
| TZubiri wrote:
| Is this Agents.json file automatically generated or is one
| supposed to invest thousands of lines into it?
| yompal wrote:
| 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.
| TZubiri wrote:
| 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.
| yompal wrote:
| 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.
| sidhusmart wrote:
| How does this compare to llms.txt? I think that's also emerging
| as a sort of standard to let LLMs understand APIs. I guess
| agents.json does a better packaging/ structural understanding of
| different endpoints?
| yompal wrote:
| 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.
| thomasfromcdnjs wrote:
| I've been following agents.json for a little while. I think it
| has legs, and would love to see some protocol win this space
| soon.
|
| Will be interesting to see where the state/less conversation
| goes, my gut tells me MCP and "something" (agent.json perhaps)
| will co-exist. My reasoning being purely organisational, MCP
| focuses on a lot more, and there ability to make a slimmed down
| stateless protocol might be nigh impossible.
|
| ---
|
| Furthermore, if agents.json wants to win as a protocol through
| early adoption, the docs need to be far easier to grok. An
| example should be immediately viewable, and the schema close by.
| The pitch should be very succinct, the fields in the schema need
| to have the same amount of clarity at first glance. Maybe a tool,
| that anyone can paste their OpenAPI schema into, and it gets
| passed to an LLM to generate a first pass of what their
| agents.json could look like.
|
| ---
|
| The OpenAPI <> agents.json portability is a nice touch, but might
| actually be overkill. OpenAPI is popular but it never actually
| took over the market imo. If there is added complexity to
| agents.json because of this, I'd really question if it is worth
| supporting it. They don't have to be 100% inoperable, custom
| converters could manage partial support.
|
| ---
|
| A lot of people are using agentic IDE's now, would be nice if
| agent.json shared a snippet with instructions on how to use it,
| where to find docs and how to pull a list and/or search the
| registry that people can just drop straight into Windsurf/Cursor.
___________________________________________________________________
(page generated 2025-03-03 23:00 UTC)