agenticweb.wiki

agents.json

Last checked · 31 primary sources

This page is about agents.json, the OpenAPI-based workflow specification introduced by Wildcard AI that chains API operations into multi-step flows and links for AI agents [1][2]. It is not AGENTS.md, the repository instruction file for coding agents; not agents.txt, whose companion IETF Internet-Draft draft-car-agents-txt-wellknown-00 proposes a different JSON capability file at /.well-known/agents.json [25]; and not other unrelated manifests served at /.well-known/agents.json, including Zapier's agents[] MCP endpoint wrapper [23], Cloudflare's agentprotocol.ai/schemas/agents.json site capability file [24], or the A2A Registry multi-agent array format [26][27].

Overview

agents.json is an open JSON specification (0.1.0) created by Wildcard AI (co-founded by Kaushik Mahorker and Yagnya Patel) that sits on top of OpenAPI 3+ to define multi-step API workflows for AI agents [1][2][6][28]. While standard OpenAPI documents describe individual HTTP endpoints and request/response schemas, they do not specify how multiple calls chain together to achieve a higher-level outcome; agents.json supplies that missing orchestration contract without requiring API providers to deploy new agent servers or modify existing endpoints [1][3]. The specification was developed in the wild-card-ai/agents-json repository (created in January 2025 and introduced on Hacker News in March 2025) alongside a client-side Python runtime called Wildcard Bridge (agentsjson on PyPI) [1][11][14][18]. Public repository commits ceased after August 2025, while Wildcard's main website (wild-card.ai) has since pivoted to AI storefront optimization [11][12][30][31].

A conforming agents.json file is validated against a JSON Schema Draft-07 definition (agentsJson.schema.json) that requires four top-level fields: agentsJson (the semantic version of the specification, "0.1.0"), info (title, version, and description), sources (an array of API sources with a snake_case id and a path pointing to an OpenAPI 3+ YAML or JSON document), and flows [2][5]. An optional top-level overrides array (sourceId, operationId, fieldPath, value) allows a manifest to refine operation descriptions or parameter flags in the referenced OpenAPI file using dot-notation paths without editing the upstream OpenAPI spec [2][15]. Each object in flows defines an outcome-oriented workflow (id, title, description, actions, links, and fields): actions map ordered steps to specific OpenAPI operations via sourceId and operationId, links wire data from an origin (actionId and fieldPath, or null for flow input parameters) to a target (actionId and fieldPath, or null for flow response fields), and fields declare the flow-level parameters, optional requestBody, and responses.success schema exposed to the language model [2][5][16].

For discovery, Wildcard proposes hosting the file at /.well-known/agents.json, while also supporting standalone manifests loaded from a repository or registry before official provider adoption [1][3]. Execution is stateless on the server side: the calling agent maintains conversation state and uses the client-side Wildcard Bridge (agentsjson) runtime to parse the manifest and its referenced OpenAPI specs, expose flows as model tool definitions, resolve links across sequential API calls, and attach Basic, ApiKey, Bearer, or OAuth credentials directly from the caller's environment [1][4][16][17]. Because the /.well-known/agents.json path is not exclusively registered to Wildcard's schema, several incompatible formats use the same well-known URI on the live web—including Zapier's MCP server advertisement, Cloudflare's agentprotocol.ai capability file, the IETF draft-car-agents-txt-wellknown-00 companion to agents.txt, and the A2A Registry multi-agent card array—so clients must inspect the top-level agentsJson, sources, and flows keys rather than assuming path equivalence [2][23][24][25][26][27].

Who uses it

Live external endpoint serving Wildcard's agentsJson/sources/flows schema at /.well-known/agents.json, alongside Wildcard's reference integration manifests (verified HTTP 200 with no redirect on 2026-10-29):

Unrelated manifests served at the same /.well-known/agents.json path (verified HTTP 200 on 2026-10-29; documented here for disambiguation because they do not use Wildcard's agentsJson/sources/flows schema): Zapier (https://zapier.com/.well-known/agents.json) serves a top-level agents array advertising its MCP endpoint (""name": "Zapier MCP", "description": "Connect AI agents to 9,000+ app integrations and 40,000+ actions via the Zapier MCP server.", "url": "https://mcp.zapier.com/api/v1/connect", "protocol": "mcp"") rather than Wildcard OpenAPI flows [23]; Cloudflare (https://www.cloudflare.com/.well-known/agents.json) serves a capability manifest using "$schema": "https://agentprotocol.ai/schemas/agents.json" (""$schema": "https://agentprotocol.ai/schemas/agents.json", "version": "1.0.0", "siteInfo": { "name": "Cloudflare"") with siteInfo, aiContent, and capabilities rather than Wildcard OpenAPI flows [24].

Who reads it

Recent coverage

See also

References

  1. wild-card-ai/agents-json, agents-json/README.md at master (repository README), checked 2026-10-29; quoted from the raw file: "The agents.json Specification is an open specification that formally describes contracts for API and agent interactions, built on top of the OpenAPI standard. The current version is 0.1.0." "Use the Wildcard Bridge Python package to load, parse, and run agents.json." "The agents.json spec contains a set of additions to the OpenAPI spec - optimizing for endpoint discovery and LLM argument generation. These can include updating descriptions and adding examples." "Describing endpoints/data models without describing how they interact together is why AI agents struggle to take the right sequence of actions. To solve this, we introduce flows and links. Flows are contracts with a series of 1 or more API calls that describe an outcome. Links describe how two actions are stitched together." "We propose the file placed in /.well-known/agents.json so it is easily discoverable by agents accessing web services. For now, we maintain a registry for available agents.json files." "We can begin building agents.json files immediately before official adoption by providers. No extra infrastructure changes, servers, or new endpoints. By putting responsibility of execution on the client - the paradigm abides by the same security and orchestration protocol of existing API based applications today. API providers can still choose to maintain official agents.json files." "While MCP is designed to be stateful—relying on persistent connections between clients and servers for exchanging context and requests—Agents.json is stateless. Here, the agent independently manages all context." "[llms.txt](https://llmstxt.org) 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." "This GitHub repository will host informal reviews, allowing for version control and public discussion." "This project is started by Wildcard AI." — https://github.com/wild-card-ai/agents-json/blob/master/README.md
  2. wild-card-ai/agents-json, agents-json/agents_json/agentsJson.schema.json at master (JSON Schema Draft-07 specification), checked 2026-10-29; quoted from the raw file: ""required": ["agentsJson", "info", "sources", "flows"]" "MUST specify the version of the `agents.json` specification being used. Adheres to Semantic Versioning (SemVer) as outlined at [https://semver.org/](https://semver.org/)." "MUST include an array of API sources available for use within flows. Each source references an OpenAPI 3+ specification, enabling the chaining of multiple APIs." "OPTIONAL. An array of overrides that allow customization of specific API operations. Overrides can modify fields within operations based on the specified `fieldPath`, enabling tailored behavior without altering the original API definitions." "MUST include an array of flows that define sequences of API operations to be executed. Each flow represents a cohesive workflow involving multiple actions, data links, and user interactions." "MUST include an array of actions that define the API operations to be executed in the flow. Each action corresponds to a specific API operation from a defined source, orchestrating the overall workflow." "MUST include an array of links that define how data flows between sources and destinations within the flow. Links connect data providers to data consumers, ensuring accurate data transfer." "MUST define the parameters, request body, and responses for the flow. These fields serve as the interface for interaction with the flow, ensuring structured and clear data handling." — https://github.com/wild-card-ai/agents-json/blob/master/agents_json/agentsJson.schema.json
  3. Wildcard documentation, agents.json Specification - Wildcard (wildcard.mintlify.app), checked 2026-10-29: "The agents.json specification is a JSON schema of structured contracts designed for AI agents. API providers use their existing OpenAPI spec to construct this file and agents inspect this file to run accurate series of API calls." "We propose the file placed in /.well-known/agents.json so it is easily discoverable by agents accessing web services. For now, we compose a GitHub repository as a registry for available agents.json files." — https://wildcard.mintlify.app/agentsjson/file-about
  4. Wildcard documentation, Wildcard Bridge - Wildcard (wildcard.mintlify.app), checked 2026-10-29: "Wildcard Bridge enables LLMs to load, parse, and run agents.json. The full source for the Bridge is available on Github." "A developer connects their agent with an agents.json file. The relevant chain(s) are chosen by the agent and arguments populated for a given task. Bridge runs the chain(s). The goal experience is a developer adds an agents.json file in their workflow and the correct set of actions for an integration is executed. Bridge supports adding Basic, ApiKey, and Bearer authentication to requests." — https://wildcard.mintlify.app/agentsjson/bridge-about
  5. Wildcard documentation, Schema Reference - Wildcard (wildcard.mintlify.app), checked 2026-10-29: "A reference of the agents.json schema, providing context and explanations for each element. This reference can be used by implementers and consumers (including LLMs and developers) to better understand how to configure and use agents.json in a workflow." — https://wildcard.mintlify.app/agentsjson/schema
  6. Wildcard documentation, Company - Wildcard (wildcard.mintlify.app), checked 2026-10-29: "This project is started by Wildcard. We're a team of 2 founders, Kaushik and Yagnya, wanting to make agents act predictably and safely." — https://wildcard.mintlify.app/about/company
  7. Wildcard documentation, Licenses - Wildcard (wildcard.mintlify.app), checked 2026-10-29: "The agents.json specification is open source, licensed under the Apache 2.0 License." "The Wildcard Bridge is source-available, licensed under the GNU Affero General Public License (AGPL)." — https://wildcard.mintlify.app/about/licenses
  8. wild-card-ai/agents-json, agents-json/MAINTAINERS.md at master, checked 2026-10-29; quoted from the raw file: "Maintainer GitHub ID Affiliation Yagnya Patel yagnyaPatel Indpendent" — https://github.com/wild-card-ai/agents-json/blob/master/MAINTAINERS.md
  9. wild-card-ai/agents-json, agents-json/LICENSE at master (root MIT License), checked 2026-10-29; quoted from the raw file: "MIT License Copyright (c) 2025 Wildcard AI" — https://github.com/wild-card-ai/agents-json/blob/master/LICENSE
  10. wild-card-ai/agents-json, agents-json/agents_json/LICENSE at master (specification subtree Apache-2.0 License), checked 2026-10-29; quoted from the raw file: "Apache License Version 2.0, January 2004" — https://github.com/wild-card-ai/agents-json/blob/master/agents_json/LICENSE
  11. GitHub - wild-card-ai/agents-json (repository metadata), checked 2026-10-29; quoted from the GitHub API record: ""created_at": "2025-01-30T15:05:18Z"" ""pushed_at": "2025-08-21T22:17:46Z"" — https://github.com/wild-card-ai/agents-json
  12. GitHub API latest commit record for wild-card-ai/agents-json (commits?per_page=1), 2025-08-21, checked 2026-10-29: ""sha": "5f5e60a4074eb0fb2aed5a3b03c8149dc3fd7120"" ""date": "2025-08-21T22:17:45Z" }, "message": "Update README.md"" — https://api.github.com/repos/wild-card-ai/agents-json/commits?per_page=1
  13. wild-card-ai/agents-json, agents-json/python/pyproject.toml at master, checked 2026-10-29; quoted from the raw file: "name = "agentsjson" version = "0.1.11" description = "Agents.json Python Implementation with Core and Integrations"" — https://github.com/wild-card-ai/agents-json/blob/master/python/pyproject.toml
  14. PyPI JSON API record for agentsjson (0.1.14), uploaded 2025-03-01, checked 2026-10-29: ""summary":"Agents.json Python Implementation with Core and Integrations","version":"0.1.14"" ""filename":"agentsjson-0.1.14-py3-none-any.whl","has_sig":false,"md5_digest":"554376c0e4816f13906bdaccfdc05c22","packagetype":"bdist_wheel","python_version":"py3","requires_python":">=3.9","size":3939784,"upload_time":"2025-03-01T20:59:13","upload_time_iso_8601":"2025-03-01T20:59:13.941947Z"" — https://pypi.org/pypi/agentsjson/json
  15. wild-card-ai/agents-json, agents-json/python/agentsjson/core/loader.py at master, checked 2026-10-29; quoted from the raw file: "Apply a list of overrides to an OpenAPI source document." — https://github.com/wild-card-ai/agents-json/blob/master/python/agentsjson/core/loader.py
  16. wild-card-ai/agents-json, agents-json/python/agentsjson/core/executor.py at master, checked 2026-10-29; quoted from the raw file: "Maps values between actions using benedict for robust dot notation support, including array indexing like line_items[0].quantity." "Executes a flow of Actions in order, applying link-based parameter link. Each new link is deep-merged so we don't overwrite nested structures." — https://github.com/wild-card-ai/agents-json/blob/master/python/agentsjson/core/executor.py
  17. wild-card-ai/agents-json, agents-json/examples/single.ipynb at master (Stripe + OpenAI gpt-4o quickstart notebook), checked 2026-10-29; quoted from the raw file: "This notebook demonstrates how to use agents.json to interact with the Stripe API. This simple example shows loading the agents.json file and using it to execute Stripe tasks." "tools=get_tools(agentsjson, format=ToolFormat.OPENAI)," "response = execute(agentsjson, response, format=ToolFormat.OPENAI, auth=auth)" — https://github.com/wild-card-ai/agents-json/blob/master/examples/single.ipynb
  18. yompal, Show HN: Agents.json – OpenAPI Specification for LLMs | Hacker News, 2025-03-03 (with maintainer thread replies on 2025-03-03 and 2025-03-04), checked 2026-10-29: "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." "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." "This can be implemented into other open-source frameworks as a plugin(ie. BrowserUse, Mastra, LangChain, CrewAI,...)." — https://news.ycombinator.com/item?id=43243893
  19. 2s (2s.io), live /.well-known/agents.json manifest, checked 2026-10-29: ""agentsJson": "0.1.0", "info": { "title": "2s API — Agent Flows", "version": "1.0.0"" — https://2s.io/.well-known/agents.json
  20. wild-card-ai/agents-json, agents-json/agents_json/stripe/agents.json at master, checked 2026-10-29; quoted from the raw file: ""agentsJson": "0.1.0", "info": { "title": "Stripe API Agent Flows", "version": "0.1.1", "description": "Agentic workflows for interacting with the Stripe API to automate common tasks and operations." }" — https://github.com/wild-card-ai/agents-json/blob/master/agents_json/stripe/agents.json
  21. wild-card-ai/agents-json, agents-json/agents_json/resend/agents.json at master, checked 2026-10-29; quoted from the raw file: ""agentsJson": "0.1.0", "info": { "title": "Resend API Integration Agents", "version": "0.1.0"" — https://github.com/wild-card-ai/agents-json/blob/master/agents_json/resend/agents.json
  22. wild-card-ai/agents-json, agents-json/agents_json at master (11 integration directories), checked 2026-10-29; quoted from the GitHub Git Trees API: ""path": "agents_json/agentsJson.schema.json"" — https://github.com/wild-card-ai/agents-json/tree/master/agents_json
  23. Zapier, live /.well-known/agents.json endpoint (unrelated MCP directory wrapper format), checked 2026-10-29: ""name": "Zapier MCP", "description": "Connect AI agents to 9,000+ app integrations and 40,000+ actions via the Zapier MCP server.", "url": "https://mcp.zapier.com/api/v1/connect", "protocol": "mcp"" — https://zapier.com/.well-known/agents.json
  24. Cloudflare, live /.well-known/agents.json endpoint (unrelated agentprotocol.ai/schemas/agents.json format), checked 2026-10-29: ""$schema": "https://agentprotocol.ai/schemas/agents.json", "version": "1.0.0", "siteInfo": { "name": "Cloudflare"" — https://www.cloudflare.com/.well-known/agents.json
  25. K. Cardillo, IETF Internet-Draft draft-car-agents-txt-wellknown-00 (AGENTS.TXT: Capability Declarations for Web Agents), June 2026, checked 2026-10-29: "This document requests registration of two Well-Known URIs under the "/.well-known/" path: "agents.txt" and "agents.json". These URIs define a machine-readable capability declaration format: a positive statement of what web agents CAN do on a site -- which endpoints are sanctioned for agent use, which protocols (REST, MCP, A2A, GraphQL, WebSocket) are supported, what authentication mechanisms are expected, and what rate limits the site advertises." "The JSON companion file MUST be served at: https://example.com/.well-known/agents.json The file MUST be served with Content-Type "application/json; charset=utf-8". 3.2. Format The JSON format contains equivalent information to "agents.txt" in a typed JSON structure suitable for direct consumption by programmatic clients." — https://www.ietf.org/archive/id/draft-car-agents-txt-wellknown-00.txt
  26. A2A Registry, A2A Registry — The Global AI Agent Directory & Registry for the Agentic Web (A2A Registry agents.json Spec), checked 2026-10-29: "The A2A Registry /.well-known/agents.json format extends the standard A2A Agent Card to support multiple agents on a single domain. Key Difference While agent-card.json contains a single agent object, agents.json contains an array of agent objects. This allows platforms, marketplaces, and multi-service websites to expose all their agents in one manifest." — https://www.a2a-registry.org/resources/agents-json-spec
  27. Özden Erdinc, Publish an agents.json Manifest — AGENTS WELCOME, published 2026-06-17, updated 2026-09-07, checked 2026-10-29: "Two lineages share the name: Wildcard AI's open specification, which builds on OpenAPI and proposes the /.well-known/agents.json path (Wildcard AI, 2025), and the broader well-known-manifest pattern this site and its audit use." — https://agentswelcome.dev/agent-readiness/agents-json
  28. Nileena Sunil, The American Bazaar, Newly launched startup Wildcard translates APIs for AI agents, 2025-02-21, checked 2026-10-29: "Indian American co-founders Kaushik Mahorker and Yagnya Patel have launched their startup Wildcard, a gateway for AI agents to use APIs, on Thursday. Backed by Y Combinator, Wildcard enables agents to select the right application program interface (API) flows for their tasks, with API providers constructing "agents.json" files to help AI agents discover their APIs." "With Wildcard's open source software development kit (SDK), the user can run actions on their own infrastructure wherever their agent lives. The startup is launching 10 curated APIs, including officially verified ones like Resend, Alpaca and more." — https://americanbazaaronline.com/2025/02/21/newly-launched-startup-wildcard-translates-apis-for-ai-agents459854/
  29. Jan Vlnas, The API Dispatch #2: MCP is coming to eat our APIs! (or maybe not) (bitoff.org), posted 2025-05-27 (originally published March 2025), checked 2026-10-29: "Posted on May 27, 2025 by Jan Vlnas Author's note The API Dispatch is a series I started as an internal newsletter at work. It's also available on LinkedIn. Originally published in March 2025." "Introduced by Wildcard in February 2025, agents.json is much lighter specification which reuses existing API descriptions in OpenAPI specifications, and introduces an additional layer – the agents.json file – which describes how API operations fit together." — https://www.bitoff.org/the-api-dispatch-2/
  30. Dawn Liphardt, A2A, ACP, and agents.json: What's Next for These Agent-Based Protocols - Dawn Liphardt, 2026-03-18, checked 2026-10-29: "Since then, agents.json has not seen a new version – the last one dates from February 2025. The project appears abandoned (nonfunctional demos, 404 documentation, expired Discord invitation, a YouTube channel that hasn't been updated…). Wildcard, the American startup that initiated the project, still exists. It has pivoted to GEO (Generative Engine Optimization)." "The protocol extends the OpenAPI specification to allow the definition of contracts guiding LLMs in API usage. These contracts contain one or more calls describing a result. A way to preserve non-determinism in task execution while constraining the use of tools. The approach is stateless. The agents.json files, preferably hosted in a /.well-known folder, are exposed to LLMs as tools via a dedicated SDK." — https://www.dawnliphardt.com/a2a-acp-and-agents-json-whats-next-for-these-agent-based-protocols/
  31. Wildcard home page, Optimize Your Storefront for AI Search | Wildcard (wild-card.ai), checked 2026-10-29: "Ecommerce and retail brands use Wildcard to win every AI shopping surface. Track what ranks, act on the roadmap, and measure revenue." — https://wild-card.ai/

JSON · Markdown · OKF v0.2