# agents.json

[5 · Act](/category/act/)

| agents.json |
| --- |
| Category | [Act](/category/act/) |
| Governed by | Wildcard AI; single company controls the spec and the reference "Wildcard Bridge" runtime and maintains a discretionary registry of published files |
| Status | "An open specification", version 0.1.0 as published by Wildcard |
| Phase | draft |
| Implementation | prototype |
| Adoption | unmeasured |
| Version | 0.1.0 (2025-03) |
| Specification | [https://github.com/wild-card-ai/agents-json](https://github.com/wild-card-ai/agents-json) |
| Found at | /.well-known/agents.json (proposed; not mandatory, per the spec's own FAQ) |
| Acronym collisions | agents.md (unrelated coding-agent instructions file), agent.json / agentfile.json (various unrelated agent-config conventions used by other frameworks) |
| Last checked | 2026-09-06 |

[Act](/category/act/) Moved from the Read step to Act. agents.json is Wildcard AI's specification for describing multi-step API call sequences ("flows") for LLM agents, built as an extension of OpenAPI rather than a competitor to it [[1]](#ref-1). It belongs under "Act" (do something for me), not "Read": its own FAQ explicitly contrasts it with llms.txt — "llms.txt ... doesn't address the challenges of taking structured actions ... agents.json enables them to execute multi-step workflows reliably" [[1]](#ref-1). It was included in this batch as a read-step candidate but is a discovery-plus-invocation spec for API actions, so it is reported here with a corrected step rather than filed under Read.

## Overview
What it is: a JSON document, structurally an annotated OpenAPI spec, adding two concepts — flows (a named sequence of one or more API calls that accomplishes an outcome) and links (how the output of one call feeds the input of the next) — so an agent doesn't have to infer multi-call sequences (e.g., "search Gmail threads, list messages in a thread, reply with base64 RFC 822 content") from raw endpoint descriptions alone [[1]](#ref-1). It proposes, but does not require, publishing the file at /.well-known/agents.json, and maintains a discretionary registry of published files at wild-card.ai/registry [[1]](#ref-1) (not independently verified in this pass). The reference runtime, "Wildcard Bridge", is a Python package that loads an agents.json file and executes the described flows with Basic/ApiKey/Bearer auth [[1]](#ref-1).

What it does not do: it is explicitly stateless — orchestration and context are the calling agent's responsibility, not the spec's — and it does not define a serving protocol beyond "an agent fetches this JSON document" [[1]](#ref-1). It is single-vendor: Wildcard AI controls the spec text, the only public runtime implementation, and the registry.

Current state: version 0.1.0, first shown publicly in a March 2025 Hacker News post [[3]](#ref-3), with the GitHub repository still receiving commits as of August 2026 [[2]](#ref-2). No changelog entry or version bump beyond 0.1.0 was found during this pass, and no independent (non-Wildcard) implementation of the spec or the registry was located.

What is disputed or unknown: adoption beyond Wildcard's own quickstart examples (Resend, Stripe, Rootly, Twitter+Giphy, and a Resend+Hubspot+Google Sheets demo) is unmeasured; there is no evidence of provider-side publication of agents.json files outside Wildcard's own demos, and the well-known path is explicitly optional per the spec's own FAQ, so counting adoption by well-known-path presence alone would understate or misstate real usage.

## Discovery and probe

Proposed well-known path, though the spec itself notes providers can maintain files without adopting the path; a discretionary third-party registry also exists · /.well-known/agents.json (proposed; not mandatory, per the spec's own FAQ)

```
GET {origin}/.well-known/agents.json
parse:     200 response with a JSON body extending an OpenAPI document with `flows` and `links` fields
on absent: No agents.json at the well-known path; the provider may still have one published in Wildcard's registry or elsewhere, since the path is a proposal, not a requirement
```

Live check run by [the MCP probe](/mcp/server-card): GET /.well-known/agents.json. agents.json extends OpenAPI with a flows field.

```
{
 "path": "/.well-known/agents.json",
 "expect": {
  "json_keys": [
   "flows"
  ]
 },
 "note": "agents.json extends OpenAPI with a flows field."
}
```

## History
- 2026-09-06 — new record added during read-step verification; reclassified to the act step and verified against the wild-card-ai/agents-json README and repository metadata

## Instances

- [Wildcard Bridge (Python reference runtime: load, parse, run agents.json flows)](https://github.com/wild-card-ai/agents-json) · Recorded 2026-09-06 · site
- [Stripe demo agent](https://demo.wild-card.ai/stripe) · Recorded 2026-09-06 · agent
- [Rootly demo agent](https://demo.wild-card.ai/rootly) · Recorded 2026-09-06 · agent
- [Resend demo agent](https://demo.wild-card.ai/resend) · Recorded 2026-09-06 · agent
- [Google Sheets demo agent](https://demo.wild-card.ai/googlesheets) · Recorded 2026-09-06 · agent

Every instance with its source is listed on the [instances page](/instances/).

## See also

- Not to be confused with: agents.md (unrelated coding-agent instructions file), agent.json / agentfile.json (various unrelated agent-config conventions used by other frameworks)

## References

- agents.json is an OpenAPI-based specification (current version 0.1.0) adding `flows` (multi-call contracts) and `links` (how calls chain together) on top of an existing OpenAPI document; it proposes but does not mandate `/.well-known/agents.json`; and the maintainers explicitly distinguish it from MCP (stateless vs. MCP's stateful connections) and from llms.txt ("llms.txt ... doesn't address the challenges of taking structured actions") — [https://raw.githubusercontent.com/wild-card-ai/agents-json/master/README.md](https://raw.githubusercontent.com/wild-card-ai/agents-json/master/README.md) (2026) VERIFIED
- The wild-card-ai/agents-json GitHub repository was created 2025-01-30 and last pushed 2026-08-25 — [https://github.com/wild-card-ai/agents-json](https://github.com/wild-card-ai/agents-json) (2026-08-25) VERIFIED
- The spec was publicly announced via a March 2025 'Show HN' post positioning it as an OpenAPI specification for LLMs — [https://news.ycombinator.com/item?id=43243893](https://news.ycombinator.com/item?id=43243893) (2025-03) REPORTED

[JSON](/data/protocols/agents-json.json) · [Markdown](/protocols/agents-json/index.md)