Skip to content

OpenAPI in, agent surfaces out

Make your product agent-native from the API you already have.

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
openapi.json
"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 annotation on an operation you already serve

What you get

One catalog, six surfaces. Change the annotation and every surface follows.

One operation, three surfaces

stop_vm is declared once. The chat, the CLI and an MCP client all call the same HTTP operation, with the same confirmation.

Chat

Stop gpu-train-01, the training run is done.

Stop server gpu-train-01?medium risk
vm_id
vm-42
Force
No
ApproveDeny

bound to argsHash q2Xf…9w

Stopped gpu-train-01. Open server page →

CLI
$ acme vm stop gpu-train-01
Stop server gpu-train-01? [y/N] y
{
  "id": "vm-42",
  "status": "stopped"
}
MCP
→ 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.

Security model

Safety is decided in runtime code and pinned by conformance cases. Prompts never decide what may run.

  1. No privilege beyond the user

    Every call carries the user’s own credential and a signed Ed25519 assertion. Your existing authorization decides, exactly as for a UI request.

  2. Approvals bound to arguments

    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.

  3. Read-only MCP by default

    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
}

How aidy compares

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.

FocusTools come fromIdentity and approvalsSurfaces produced
LangGraphAgent orchestration as state graphsCode and integrations you wire upHuman-in-the-loop interrupts you wire upAn agent runtime and its API
CopilotKitIn-app copilot UIFrontend actions and backend agentsApp-defined; confirmation through UI actionsChat UI and hooks
Stainless / SpeakeasySDKs and tooling generated from OpenAPIOpenAPIAPI keys of the callerSDKs, MCP servers, CLIs, docs
Vercel AI SDK / MastraModel abstraction and agent loopsCode you writeTool approval hooks you wire upLibraries and UI hooks
aidyMaking an existing product agent-nativeOpenAPI + x-aidyCalls as the user; approvals enforced in code, bound to an argument hashAgent, MCP, CLI, skill, llms.txt, search, knowledge, React UI

Read the full comparison →

Quickstart

Embed aidy in a JavaScript host, or run aidy serve beside a host in any language.

src/index.ts
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;

Hono quickstart →

Your API already describes your product.

Give it to your users’ agents, with the safety your UI already has.