{
 "acronym": "",
 "adoption": {
  "by": null,
  "level": "unmeasured",
  "probe_run": null
 },
 "aliases": [
  "Wildcard agents.json"
 ],
 "analog": "an OpenAPI/Swagger spec, extended with the multi-call recipes a human developer would otherwise write by hand",
 "collisions": [
  "agents.md (unrelated coding-agent instructions file)",
  "agent.json / agentfile.json (various unrelated agent-config conventions used by other frameworks)"
 ],
 "discovery": {
  "mechanism": "Proposed well-known path, though the spec itself notes providers can maintain files without adopting the path; a discretionary third-party registry also exists",
  "path": "/.well-known/agents.json (proposed; not mandatory, per the spec's own FAQ)"
 },
 "dispute": null,
 "evidence": [
  {
   "claim": "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\")",
   "date": "2026",
   "label": "VERIFIED",
   "url": "https://raw.githubusercontent.com/wild-card-ai/agents-json/master/README.md"
  },
  {
   "claim": "The wild-card-ai/agents-json GitHub repository was created 2025-01-30 and last pushed 2026-08-25",
   "date": "2026-08-25",
   "label": "VERIFIED",
   "url": "https://github.com/wild-card-ai/agents-json"
  },
  {
   "claim": "The spec was publicly announced via a March 2025 'Show HN' post positioning it as an OpenAPI specification for LLMs",
   "date": "2025-03",
   "label": "REPORTED",
   "url": "https://news.ycombinator.com/item?id=43243893"
  }
 ],
 "form": "well-known-file",
 "governance": "Wildcard AI; single company controls the spec and the reference \"Wildcard Bridge\" runtime and maintains a discretionary registry of published files",
 "group": null,
 "history": [
  {
   "date": "2026-09-06",
   "note": "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"
  }
 ],
 "id": "agents-json",
 "implementation": "prototype",
 "last_verified": "2026-09-06",
 "name": "agents.json",
 "native_status": "\"An open specification\", version 0.1.0 as published by Wildcard",
 "origin": {
  "date": "2025-03",
  "org": "Wildcard AI (wild-card-ai)"
 },
 "part_of": null,
 "parties": [
  "agent-site"
 ],
 "phase": "draft",
 "probe": {
  "method": "GET",
  "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",
  "parse": "200 response with a JSON body extending an OpenAPI document with `flows` and `links` fields",
  "path": "{origin}/.well-known/agents.json"
 },
 "question": "How does an agent learn which multi-step API call sequences (\"flows\") a service supports, on top of its raw OpenAPI surface?",
 "scope": "general",
 "spec_url": "https://github.com/wild-card-ai/agents-json",
 "step": "act",
 "summary_md": "**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]. 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]. 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.\n\nWhat 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]. 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] (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].\n\nWhat 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]. It is single-vendor: Wildcard AI controls the spec text, the only public runtime implementation, and the registry.\n\nCurrent state: version 0.1.0, first shown publicly in a March 2025 Hacker News post [3], with the GitHub repository still receiving commits as of August 2026 [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.\n\nWhat 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.",
 "track": "single-vendor",
 "version": {
  "date": "2025-03",
  "label": "0.1.0"
 },
 "url": "https://agenticweb.wiki/protocols/agents-json/",
 "category": "act",
 "type": "protocol"
}