Introduction
aidy turns the HTTP API your product already serves into everything an agent needs. You annotate
OpenAPI operations with x-aidy; aidy reads that catalog and derives the agent-facing surfaces
from it.
"post": { "operationId": "stopVm", "x-aidy": { "name": "stop_vm", "description": "Stop a running cloud server (VM).", "confirmation": { "title": "Stop server {resource_name}?", "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" } } }}What you get
Section titled “What you get”| Surface | What it is | Derived from |
|---|---|---|
| In-app agent | A chat agent inside your product that acts as the signed-in user. Writes wait for approval, bound to the exact arguments the user saw. | Catalog, identity and search, streamed as AG-UI 1.0 |
| MCP server | Claude, Cursor and other MCP clients can use your product. Read-only by default; writes need client confirmation. | Catalog |
| CLI | A command line for your product, which you can brand (acme vm stop vm-42). |
MCP tools/list, read at run time |
skill.md, llms.txt, operation reference |
Generated agent-facing documents. | Catalog plus your hand-written guide |
| Global search | One ⌘K search across your product’s own search endpoints and its docs. | Every role: search operation, federated |
| Knowledge answers | Answers from your docs with citations. | aidy’s knowledge index, one more search source |
| React components | Dock, thread, approval card, form, search palette, help viewer, model settings. | @aidy-dev/react over the HTTP API |
How it works
Section titled “How it works”Your API (any language) aidy runtime SurfacesOpenAPI 3.1 + x-aidy ───────► catalog, runs, approvals ───► in-app agent (AG-UI 1.0)identity operation forms, resolve, chains MCP server at /mcpsearch operations search federation CLI ◄─────── calls as the user skill.md, llms.txt + signed assertion search + knowledge- Catalog. aidy fetches your OpenAPI document with the user’s credential and keeps the
operations that carry
x-aidy. See The catalog. - Identity. One
role: identityoperation tells aidy who the credential belongs to. See Identity. - Calls. When the agent, an MCP client or the CLI calls an operation, aidy calls your API
with the user’s own
Authorizationheader and a signedAidy-Assertion. Your existing authorization decides. See Delegation. - Safety. Writes pause for approval. The approval binds to a hash of the frozen arguments and runs at most once. See Approvals.
- Streaming. Runs stream AG-UI 1.0 events with a small aidy profile, so any AG-UI client works. See AG-UI profile.
Where the runtime runs
Section titled “Where the runtime runs”The runtime is written once, in TypeScript, on Web-standard APIs.
- Embedded. JavaScript hosts mount it in-process on Node or Cloudflare Workers, as one
fetchhandler. See Quickstart: Hono on Workers. - Beside the host. Hosts in other languages run
aidy-server servenext to their API and reverse-proxy the aidy paths. See Quickstart: FastAPI.
A host in any language implements four things: annotated OpenAPI, one identity operation, search operations, and verification of the delegation assertion. Everything else is aidy’s.
Principles
Section titled “Principles”- The catalog is the product’s API. Tools are HTTP operations your product already serves. aidy adds no second business layer.
- No privilege beyond the user. Every call carries the user’s own credential and a signed assertion; your host authorizes it exactly as a request from your UI.
- Safety in code. Approval is decided by catalog policy and bound to the hash of frozen arguments. Prompts never decide what may run.
- One clean contract. Unknown
x-aidykeys fail validation. There are no aliases and no legacy shapes.
Next steps
Section titled “Next steps”- Start with Quickstart: Hono on Workers or Quickstart: FastAPI.
- Learn the annotation in The catalog and Operations and effects.
- Look up every key in the
x-aidyreference. - Try it in the playground.