跳转到内容

简介

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" }
}
}
}
入口 是什么 来源
应用内 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
+ 签名断言 搜索 + 知识
  1. 目录。 aidy 用用户的凭据拉取 OpenAPI 文档,保留带 x-aidy 的操作。见目录。
  2. 身份。 一个 role: identity 操作告诉 aidy 凭据属于谁。见身份。
  3. 调用。 agent、MCP 客户端或 CLI 调用某个操作时,aidy 带着用户自己的 Authorization 头和一个签名的 Aidy-Assertion 调用你的 API,由你现有的鉴权做决定。见委托。
  4. 安全。 写操作暂停等待审批。审批绑定到冻结参数的哈希,最多执行一次。见审批。
  5. 流式传输。 运行以 AG-UI 1.0 事件加一层很薄的 aidy profile 流式输出,任何 AG-UI 客户端都能用。见 AG-UI profile。

运行时只用 TypeScript 写一份,基于 Web 标准 API。

  • 内嵌。 JavaScript 宿主在 Node 或 Cloudflare Workers 上进程内挂载它,作为一个 fetch 处理函数。见快速开始:Workers 上的 Hono。
  • 旁路部署。 其他语言的宿主在 API 旁边运行 aidy-server serve,再把 aidy 的路径反向代理过去。见快速开始:FastAPI。

任何语言的宿主只需实现四件事:带注解的 OpenAPI、一个身份操作、搜索操作,以及委托断言的校验。其余都由 aidy 负责。

  1. 目录就是产品的 API。 工具就是产品已有的 HTTP 操作,aidy 不另加一层业务逻辑。
  2. 不超出用户的权限。 每次调用都带着用户自己的凭据和签名断言,宿主像对待自己 UI 的请求一样鉴权。
  3. 安全写在代码里。 是否需要审批由目录策略决定,并绑定到冻结参数的哈希。提示词从不决定什么可以执行。
  4. 单一、干净的契约。 未知的 x-aidy 键会校验失败,没有别名,也没有旧格式。