简介
aidy 把产品已经提供的 HTTP API 变成 agent 所需的一切。你在 OpenAPI 操作上加 x-aidy 注解,aidy 读取这份目录(catalog),由它派生出所有面向 agent 的入口。
"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" } } }}你会得到什么
Section titled “你会得到什么”| 入口 | 是什么 | 来源 |
|---|---|---|
| 应用内 agent | 产品内的对话 agent,以当前登录用户的身份行事。写操作要等用户审批,审批绑定到用户看到的确切参数。 | 目录、身份和搜索,以 AG-UI 1.0 流式传输 |
| MCP 服务器 | Claude、Cursor 等 MCP 客户端可以使用你的产品。默认只读;写操作需要客户端确认。 | 目录 |
| CLI | 产品的命令行,可以换成你自己的品牌(acme vm stop vm-42)。 |
运行时读取 MCP tools/list |
skill.md、llms.txt、操作参考 |
自动生成的面向 agent 的文档。 | 目录加上你手写的指南 |
| 全局搜索 | 一个 ⌘K 搜索,覆盖产品自己的搜索接口和文档。 | 所有 role: search 操作,联邦检索 |
| 知识问答 | 基于文档回答,附带引用。 | aidy 的知识索引,作为又一个搜索源 |
| React 组件 | 侧边栏、对话、审批卡片、表单、搜索面板、帮助查看器、模型设置。 | 基于 HTTP API 的 @aidy-dev/react |
你的 API(任意语言) aidy 运行时 入口OpenAPI 3.1 + x-aidy ───────► 目录、运行、审批 ───► 应用内 agent(AG-UI 1.0)身份操作 表单、resolve、链式调用 /mcp 上的 MCP 服务器搜索操作 联邦搜索 CLI ◄─────── 以用户身份调用 skill.md、llms.txt + 签名断言 搜索 + 知识- 目录。 aidy 用用户的凭据拉取 OpenAPI 文档,保留带
x-aidy的操作。见目录。 - 身份。 一个
role: identity操作告诉 aidy 凭据属于谁。见身份。 - 调用。 agent、MCP 客户端或 CLI 调用某个操作时,aidy 带着用户自己的
Authorization头和一个签名的Aidy-Assertion调用你的 API,由你现有的鉴权做决定。见委托。 - 安全。 写操作暂停等待审批。审批绑定到冻结参数的哈希,最多执行一次。见审批。
- 流式传输。 运行以 AG-UI 1.0 事件加一层很薄的 aidy profile 流式输出,任何 AG-UI 客户端都能用。见 AG-UI profile。
运行时在哪里运行
Section titled “运行时在哪里运行”运行时只用 TypeScript 写一份,基于 Web 标准 API。
- 内嵌。 JavaScript 宿主在 Node 或 Cloudflare Workers 上进程内挂载它,作为一个
fetch处理函数。见快速开始:Workers 上的 Hono。 - 旁路部署。 其他语言的宿主在 API 旁边运行
aidy-server serve,再把 aidy 的路径反向代理过去。见快速开始:FastAPI。
任何语言的宿主只需实现四件事:带注解的 OpenAPI、一个身份操作、搜索操作,以及委托断言的校验。其余都由 aidy 负责。
- 目录就是产品的 API。 工具就是产品已有的 HTTP 操作,aidy 不另加一层业务逻辑。
- 不超出用户的权限。 每次调用都带着用户自己的凭据和签名断言,宿主像对待自己 UI 的请求一样鉴权。
- 安全写在代码里。 是否需要审批由目录策略决定,并绑定到冻结参数的哈希。提示词从不决定什么可以执行。
- 单一、干净的契约。 未知的
x-aidy键会校验失败,没有别名,也没有旧格式。
- 从快速开始:Workers 上的 Hono 或快速开始:FastAPI 开始。
- 在目录和操作与效果中了解注解。
- 在
x-aidy参考中查阅每个键。 - 在 playground 里试一试。