把 gpu-train-01 停掉,训练跑完了。
- vm_id
vm-42- 强制
- 否
绑定 argsHash q2Xf…9w
已停止 gpu-train-01。 打开服务器页面 →
输入 OpenAPI,输出 Agent 能力
给 OpenAPI 操作加上 x-aidy 注解,aidy 就把它们变成应用内 Agent、MCP 服务器、CLI、面向 Agent 的文档、全局搜索和知识问答。每一次调用都以当前登录用户的身份进行。
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" } } }}一份操作目录,六个面。改一处注解,所有面同步更新。
以当前登录用户身份行动的侧边栏助手。写操作要等用户批准,批准绑定到用户看到的那组参数。
Claude Code、Cursor 等 Agent 通过 /mcp 使用你的产品。默认只读,写操作需要客户端向用户确认。
一个通用的 aidy CLI,运行时读取你的操作列表;还可以生成带产品名的品牌 CLI。
skill.md、llms.txt 和操作参考,都由同一份目录加上你手写的指南生成。
⌘K 面板同时搜索你自己的搜索接口和文档,按排名融合。回答会附上引用来源。
侧边栏、审批卡片、表单、搜索面板、帮助查看器和模型设置。任何 AG-UI 客户端也都能用。
stop_vm 只声明一次。聊天、CLI 和 MCP 客户端调用的是同一个 HTTP 接口,弹出的是同一个确认。
把 gpu-train-01 停掉,训练跑完了。
vm-42绑定 argsHash q2Xf…9w
已停止 gpu-train-01。 打开服务器页面 →
$ acme vm stop gpu-train-01
停止服务器 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" }写操作执行前,客户端会通过 elicitation 向用户确认。
安全由运行时代码决定,并由一致性用例固定下来。提示词从不决定什么可以执行。
每次调用都带着用户自己的凭证和一份 Ed25519 签名断言。由你现有的鉴权来决定,和处理一次 UI 请求完全一样。
aidy 冻结校验后的参数并计算哈希(JCS、SHA-256)。只有这一次调用会执行,且至多一次;宿主还可以要求带上批准 id。
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 key | SDK、MCP 服务器、CLI、文档 |
| Vercel AI SDK / Mastra | 模型抽象与 Agent 循环 | 自己编写的代码 | 自行接入工具审批钩子 | 库与 UI hooks |
| aidy | 让已有产品原生支持 Agent | OpenAPI + x-aidy | 以用户身份调用;审批由代码强制,绑定参数哈希 | Agent、MCP、CLI、Skill、llms.txt、搜索、知识问答、React 界面 |
在 JavaScript 宿主里直接嵌入 aidy,或者在任意语言的宿主旁边运行 aidy serve。
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 serve把它交给用户的 Agent,同时保留 UI 已有的安全边界。