https://dh7.github.io/slash-agents
The backstory
Autonomous AI agents are increasingly operating APIs directly, but there is a gap between what an OpenAPI schema describes and what an agent actually needs to run in production.
OpenAPI tells you the shape of the endpoints — parameters, schemas, HTTP verbs. But it rarely covers things like rate limits, retry behavior, idempotency rules, or what happens when a queue fills up. Those are the things that make or break an agent operating in the wild.
The convention is simple: every API can expose a runtime guide at `GET /agents` in plain text. Given only an API base URL, an agent fetches one URL and learns how to safely operate that API.
What slash-agents does
SlashAgents defines `/agents` (and the compatibility routes `/.well-known/agents` and `/.well-known/agent-api`) as a convention for a plain-text runtime operating guide, complementary to existing standards:
- `/openapi.json` — endpoint shape and schema (auto-generated)
- `/docs` — human browsing and exploration
- `/agents` — plain-text runtime guide for autonomous agents
The `/agents` guide covers what OpenAPI typically does not express:
- Auth methods and token lifecycle
- Rate limits and retry/backoff guidance
- Idempotency and pagination contracts
- Error models and recovery instructions
- Concurrency, queueing, and health-check behavior
The spec is currently draft v0.1, open for community feedback. A `/agents.json` structured companion is also proposed for teams that want strict machine parsing.
How it was created:
Built as a minimal convention with a launch page and examples:
- GitHub Pages static site
- Next.js 15, React 18, TypeScript, Tailwind CSS
- Cloudflare Pages deployment
- Examples (`agents.txt`, `agents.json`) in the repo
- Open Graph images generated via dynamic metadata</callout>