The full agents.json source code can be found at Github. For discussion, join us on Discord

​
Motivations

Enabling AI agents to interact with APIs is difficult. We faced the same problem as many others building agents: altering APIs to work reliably with LLMs and executing multiple API calls successfully in a row is a trial and error process.

APIs are designed for developers and not LLMs. If you’re building integrations for AI agents, you need to write boilerplate, experiment with system prompts, optimize tool definitions, and parse responses into vector stores - for each API.

For example, the Gmail API has endpoints to search for threads, list the emails in a thread, and reply with an email given base64 RFC 822 content. Instead, LLMs need a clear, top-level directive that can handle all of this with one tool.

Why is agents.json built on OpenAPI? — OpenAPI is the gold standard for describing how API endpoints work and can be executed. Most API providers have OpenAPI specs or have APIs that can be described fully by OpenAPI. These specs alone aren’t sufficient for the age of AI agents, but provide great groundwork for API agent communication.

So we implemented agents.json. We built this for us and we’re excited to share it with you.

​
Design Tenets

  1. Build on top of the OpenAPI standard Leverage existing standards and infrastructure where possible.

  2. Optimize schema for LLMs, not humans Design with AI consumption in mind.

  3. Enforce Statelessness Orchestration is handled by the calling agent.

  4. Require minimal changes to existing APIs Make adoption as seamless as possible.

​
Why Now?

With OpenAI’s release of Operator, we’ve seen a paradigm shift in what AI will automate. Letting AI run free on the internet will ask for both features and guardrails to be built on web experiences for agents. Yet, for the majority of services - this is exactly the functionality APIs already provide - and more.

Rather than just optimizing UXs for web agents - enriching APIs will create more scalable, powerful, and safe agents. APIs are supported by backend infrastructure built for scale.

There are still open questions and more to be done. Starting the discussion now and building iteratively gives us a place to adapt alongside evolving paradigms in AI agent development.

agents.json Specification