跳转到内容

输入 OpenAPI,输出 Agent 能力

用你现有的 API,让产品原生支持 Agent。

给 OpenAPI 操作加上 x-aidy 注解,aidy 就把它们变成应用内 Agent、MCP 服务器、CLI、面向 Agent 的文档、全局搜索和知识问答。每一次调用都以当前登录用户的身份进行。

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" }
}
}
}
在已有的接口上加一段注解

你会得到什么

一份操作目录,六个面。改一处注解,所有面同步更新。

同一个操作,三个入口

stop_vm 只声明一次。聊天、CLI 和 MCP 客户端调用的是同一个 HTTP 接口,弹出的是同一个确认。

聊天

把 gpu-train-01 停掉,训练跑完了。

停止服务器 gpu-train-01?中风险
vm_id
vm-42
强制
否
批准拒绝

绑定 argsHash q2Xf…9w

已停止 gpu-train-01。 打开服务器页面 →

CLI
$ acme vm stop gpu-train-01
停止服务器 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" }

写操作执行前,客户端会通过 elicitation 向用户确认。

安全模型

安全由运行时代码决定,并由一致性用例固定下来。提示词从不决定什么可以执行。

  1. 权限不超过用户本人

    每次调用都带着用户自己的凭证和一份 Ed25519 签名断言。由你现有的鉴权来决定,和处理一次 UI 请求完全一样。

  2. 批准绑定到参数

    aidy 冻结校验后的参数并计算哈希(JCS、SHA-256)。只有这一次调用会执行,且至多一次;宿主还可以要求带上批准 id。

  3. MCP 默认只读

    MCP 只开放读操作。写操作只有在你为它列出 mcp 时才出现,并且要等客户端向用户确认后才会执行。

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
}

和其他方案的对比

这些工具各有所长,其中几个还能和 aidy 组合使用。aidy 专注于把已有产品的 API 变成以用户身份行动的 Agent 能力。

关注点工具来源身份与审批产出的面
LangGraph以状态图编排 Agent自己编写或接入的代码自行接入 human-in-the-loop 中断Agent 运行时及其 API
CopilotKit应用内 Copilot 界面前端 action 与后端 Agent由应用定义;通过 UI action 确认聊天界面与 hooks
Stainless / Speakeasy从 OpenAPI 生成 SDK 和工具OpenAPI调用方自己的 API keySDK、MCP 服务器、CLI、文档
Vercel AI SDK / Mastra模型抽象与 Agent 循环自己编写的代码自行接入工具审批钩子库与 UI hooks
aidy让已有产品原生支持 AgentOpenAPI + x-aidy以用户身份调用;审批由代码强制,绑定参数哈希Agent、MCP、CLI、Skill、llms.txt、搜索、知识问答、React 界面

查看完整对比 →

快速开始

在 JavaScript 宿主里直接嵌入 aidy,或者在任意语言的宿主旁边运行 aidy serve。

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 快速开始 →

你的 API 早已描述了你的产品。

把它交给用户的 Agent,同时保留 UI 已有的安全边界。