Skip to content

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" }
}
}
}
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
Your API (any language) aidy runtime Surfaces
OpenAPI 3.1 + x-aidy ───────► catalog, runs, approvals ───► in-app agent (AG-UI 1.0)
identity operation forms, resolve, chains MCP server at /mcp
search operations search federation CLI
◄─────── calls as the user skill.md, llms.txt
+ signed assertion search + knowledge
  1. Catalog. aidy fetches your OpenAPI document with the user’s credential and keeps the operations that carry x-aidy. See The catalog.
  2. Identity. One role: identity operation tells aidy who the credential belongs to. See Identity.
  3. Calls. When the agent, an MCP client or the CLI calls an operation, aidy calls your API with the user’s own Authorization header and a signed Aidy-Assertion. Your existing authorization decides. See Delegation.
  4. Safety. Writes pause for approval. The approval binds to a hash of the frozen arguments and runs at most once. See Approvals.
  5. Streaming. Runs stream AG-UI 1.0 events with a small aidy profile, so any AG-UI client works. See AG-UI profile.

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 fetch handler. See Quickstart: Hono on Workers.
  • Beside the host. Hosts in other languages run aidy-server serve next 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.

  1. The catalog is the product’s API. Tools are HTTP operations your product already serves. aidy adds no second business layer.
  2. 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.
  3. Safety in code. Approval is decided by catalog policy and bound to the hash of frozen arguments. Prompts never decide what may run.
  4. One clean contract. Unknown x-aidy keys fail validation. There are no aliases and no legacy shapes.