Stop gpu-train-01, the training run is done.
- vm_id
vm-42- Force
- No
bound to argsHash q2Xf…9w
Stopped gpu-train-01. Open server page →
OpenAPI in, agent surfaces out
Annotate your OpenAPI operations with x-aidy. aidy turns them into an in-app agent, an MCP server, a CLI, docs for agents, global search and knowledge answers. Every call runs as the signed-in user.
npm i @aidy-dev/corepip install aidy"post": { "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" } } }}One catalog, six surfaces. Change the annotation and every surface follows.
A dock that acts as the signed-in user. Writes wait for approval, bound to the exact arguments the user saw.
Claude Code, Cursor and other agents use your product at /mcp. Read-only by default; writes need client confirmation.
One generic aidy CLI that reads your operations at run time, and a branded wrapper with your product’s name.
skill.md, llms.txt and an operation reference, generated from the same catalog and your hand-written guide.
A ⌘K palette across your own search endpoints and your docs, fused by rank. Answers cite their sources.
Dock, approval card, forms, search palette, help viewer and model settings. Any AG-UI client works too.
stop_vm is declared once. The chat, the CLI and an MCP client all call the same HTTP operation, with the same confirmation.
Stop gpu-train-01, the training run is done.
vm-42bound to argsHash q2Xf…9w
Stopped gpu-train-01. Open server page →
$ acme vm stop gpu-train-01
Stop server gpu-train-01? [y/N] y
{
"id": "vm-42",
"status": "stopped"
}→ tools/call stop_vm
{ "vm_id": "vm-42" }
← elicitation/create
"Stop server gpu-train-01?"
→ accept
← { "id": "vm-42", "status": "stopped" }The client asks the user through elicitation before the write runs.
Safety is decided in runtime code and pinned by conformance cases. Prompts never decide what may run.
Every call carries the user’s own credential and a signed Ed25519 assertion. Your existing authorization decides, exactly as for a UI request.
aidy freezes the validated arguments and hashes them (JCS, SHA-256). Only that exact call runs, at most once, and the host can require the approval id.
MCP exposes reads. A write appears only when you list mcp for it, and runs only after the client confirms with the user.
POST /api/vm/vm-42/stop
Authorization: Bearer <the user's own token>
Aidy-Assertion: eyJhbGciOiJFZERTQSIs…
{
"sub": "u_123", "op": "stop_vm",
"htm": "POST", "bsh": "47DEQpj8…",
"apr": "apr_7Kc…", "exp": iat + 60
}These tools are good at different things, and several combine with aidy. aidy’s focus is turning an existing product API into agent surfaces that act as the user.
| Focus | Tools come from | Identity and approvals | Surfaces produced | |
|---|---|---|---|---|
| LangGraph | Agent orchestration as state graphs | Code and integrations you wire up | Human-in-the-loop interrupts you wire up | An agent runtime and its API |
| CopilotKit | In-app copilot UI | Frontend actions and backend agents | App-defined; confirmation through UI actions | Chat UI and hooks |
| Stainless / Speakeasy | SDKs and tooling generated from OpenAPI | OpenAPI | API keys of the caller | SDKs, MCP servers, CLIs, docs |
| Vercel AI SDK / Mastra | Model abstraction and agent loops | Code you write | Tool approval hooks you wire up | Libraries and UI hooks |
| aidy | Making an existing product agent-native | OpenAPI + x-aidy | Calls as the user; approvals enforced in code, bound to an argument hash | Agent, MCP, CLI, skill, llms.txt, search, knowledge, React UI |
Embed aidy in a JavaScript host, or run aidy serve beside a host in any language.
import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';import { createAidy } from '@aidy-dev/core';
const app = new OpenAPIHono();
app.openapi( createRoute({ method: 'post', path: '/api/vm/{vm_id}/stop', request: { params: z.object({ vm_id: z.string() }) }, responses: { 200: { description: 'Stopped' } }, 'x-aidy': { name: 'stop_vm', confirmation: { title: 'Stop server {resource_name}?', lookup: { path: '/api/vm/{vm_id}', labelPath: 'name' }, }, }, }), (c) => c.json(stopVm(c.req.valid('param').vm_id)),);app.doc31('/openapi.json', { openapi: '3.1.0', info: { title: 'Acme', version: '1' } });
const aidy = createAidy({ url: 'https://acme.example.com', host: { origin: 'https://acme.example.com', openapi: '/openapi.json', fetch: app.fetch }, signingKey, secret, store, models: { chain: [{ id: 'main', provider: 'openai', model: 'gpt-5-mini', apiKey }] },});
for (const path of ['/aidy/v0/*', '/mcp', '/skill.md', '/llms.txt', '/.well-known/aidy-keys.json']) app.all(path, (c) => aidy.fetch(c.req.raw, c.executionCtx));
export default app;from aidy import opfrom fastapi import FastAPI
app = FastAPI()
@app.post( "/api/vm/{vm_id}/stop", openapi_extra=op( "stop_vm", description="Stop a running cloud server (VM).", confirmation={ "title": "Stop server {resource_name}?", "lookup": {"path": "/api/vm/{vm_id}", "labelPath": "name"}, }, ),)async def stop_vm(vm_id: str) -> dict[str, str]: ...pip install "aidy[fastapi]"# beside your app; route /aidy/, /mcp, /skill.md, /llms.txt to itAIDY_URL=https://acme.example.com AIDY_HOST_ORIGIN=https://acme.example.com \AIDY_SIGNING_KEY=... AIDY_SECRET=... AIDY_DATABASE_URL=sqlite:aidy.db \npx @aidy-dev/server serveGive it to your users’ agents, with the safety your UI already has.