HTTP API
aidy 在宿主的域名下提供以下路由。宿主可以反向代理它们,嵌入 aidy 时也可以直接挂载处理函数。协议版本字符串为 aidy/0,API 前缀为 /aidy/v0。
| 端点 | 用途 |
|---|---|
POST /aidy/v0/threads |
创建会话(thread)。 |
GET /aidy/v0/threads?cursor= |
当前用户的会话,最新的在前。 |
GET /aidy/v0/threads/{id} |
会话本身、其消息和未完成的中断。 |
PATCH /aidy/v0/threads/{id} |
重命名会话。 |
DELETE /aidy/v0/threads/{id} |
删除会话。 |
POST /aidy/v0/threads/{id}/runs |
发起一次运行,响应是该运行的 SSE 事件流。 |
GET /aidy/v0/threads/{id}/events?after={seq} |
从 seq 之后回放,然后继续实时跟随(SSE)。 |
PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback |
评价一条助手消息。 |
POST /aidy/v0/runs/{id}/cancel |
取消运行。 |
GET /aidy/v0/info |
助手名称,供界面显示。 |
GET /aidy/v0/catalog |
当前用户可见的操作。 |
GET /aidy/v0/search |
联合搜索。 |
GET、PUT、DELETE /aidy/v0/settings |
模型设置。PUT 和 DELETE 需要 aidy:admin。 |
GET /aidy/v0/feedback |
所有用户的反馈,需要 aidy:admin。 |
POST /aidy/v0/tasks/{taskId} |
宿主完成一个延后任务。 |
POST /aidy/v0/generate |
为宿主任务执行一次模型补全。 |
/mcp |
基于 streamable HTTP 的 MCP。 |
GET /skill.md、GET /llms.txt |
生成的面向 agent 的文档。 |
GET /.well-known/aidy-keys.json |
aidy 的委托公钥。 |
每个请求都携带用户自己的凭据:Authorization 头、Cookie 头,或两者兼有。aidy 把它们转发给目录中的 role: identity 操作,以确认用户是谁,见 身份。会话归属于一个 (subject, tenant),访问他人的会话返回 404。
POST /aidy/v0/tasks/{taskId} 和 POST /aidy/v0/generate 是例外:宿主用 Aidy-Host-Assertion 认证自己的调用。
对于 POST、PUT、PATCH 和 DELETE:
- 带有
Sec-Fetch-Site: cross-site的请求被拒绝,返回403 cross_site; - 在
/aidy/v0下,带请求体的请求必须发送Content-Type: application/json,不带Content-Type的请求不能有请求体,否则返回415 unsupported_media_type。DELETE和取消运行两者都不需要。
这两条规则合起来,防止其他网站冒用基于 Cookie 认证的用户身份。
除 SSE 流之外,错误都以 JSON 返回:
{ "error": { "code": "not_found", "message": "No such thread." } }| 状态码 | code |
场景 |
|---|---|---|
| 400 | invalid_request |
请求体或查询参数无效。 |
| 401 | unauthorized |
identity 操作拒绝了凭据。在 /mcp 上,若配置了 OAuth,WWW-Authenticate 会指向受保护资源元数据。 |
| 401 | aidy_assertion_invalid |
完成任务或宿主任务时缺少有效的 Aidy-Host-Assertion。 |
| 403 | forbidden |
没有 aidy:admin 却调用 PUT、DELETE /settings 或 GET /feedback。 |
| 403 | cross_site |
跨站的写请求。 |
| 404 | not_found |
当前用户下没有这个会话、运行或任务。 |
| 404 | session_not_found |
未知的 MCP 会话。 |
| 409 | run_active |
会话已有一个进行中的运行。 |
| 409 | task_closed |
任务已经完成或已被取消。 |
| 415 | unsupported_media_type |
写请求的请求体不是 application/json。 |
| 422 | invalid_output |
宿主任务的回答经过一次修正后仍不符合 schema。 |
| 500 | internal |
其他错误。 |
| 503 | settings_unreadable |
保存的设置是用 aidy 已经没有的密钥加密的。 |
| 503 | model_unavailable |
宿主任务找不到能回答的模型端点。 |
| 504 | timeout |
宿主任务超过了运行超时。 |
运行中的失败在事件流里以 RUN_ERROR 报告,见 事件。
POST /aidy/v0/threads
Section titled “POST /aidy/v0/threads”{ "title": "Optional title, at most 200 characters" }201:
{ "id": "th_…", "title": "", "createdAt": "2026-11-19T08:00:00.000Z" }GET /aidy/v0/threads?cursor=
Section titled “GET /aidy/v0/threads?cursor=”{ "items": [{ "id": "th_…", "title": "…", "createdAt": "…", "updatedAt": "…" }], "next": "<cursor>"}每页 20 个会话。还有更多时会返回 next,把它作为 cursor 传入即可。
GET /aidy/v0/threads/{id}
Section titled “GET /aidy/v0/threads/{id}”{ "id": "th_…", "title": "…", "createdAt": "…", "updatedAt": "…", "messages": [], "interrupts": []}messages 是 AG-UI 的 Message[]。interrupts 是未完成的中断,结构见 中断。
PATCH /aidy/v0/threads/{id}
Section titled “PATCH /aidy/v0/threads/{id}”{ "title": "New title" }title 必填,去掉首尾空白后为 1 到 200 个字符。返回与列表中相同结构的会话。
DELETE /aidy/v0/threads/{id}
Section titled “DELETE /aidy/v0/threads/{id}”204。会话连同其消息、事件、运行、中断和任务一并删除。
POST /aidy/v0/threads/{id}/runs
Section titled “POST /aidy/v0/threads/{id}/runs”请求体是 AG-UI 的 RunAgentInput。aidy 读取其中三个字段:
{ "messages": [ { "id": "m_1", "role": "user", "content": [ { "type": "text", "text": "Why is this box slow?" }, { "type": "image", "source": { "type": "url", "value": "/files/shot.png", "mimeType": "image/png" }, "metadata": { "aidy": { "name": "shot.png" } } } ] } ], "context": [{ "description": "The page the user is on", "value": "/console/instance/vm-42" }], "resume": [ { "interruptId": "int_…", "status": "resolved", "payload": { "approved": true }, "metadata": { "aidy": { "argsHash": "q2…" } } } ]}- 用户消息的
content是文本,或类型为text、image、document的 AG-UI content part,图片和文档合计最多 10 个。其他类型返回400。aidy 如何把它们交给模型,见 AG-UI:用户消息。 context([{description, value}])描述用户正在看的内容。aidy 只把它作为信息(而非指令)加入本次运行的系统提示词:最多 16 条,值合计最多 8000 个字符,超出时先截掉靠后的条目。它不会被保存。- 历史记录由服务端持有。
messages可以重复 aidy 已有的消息,只有 id 为新的消息才会追加。修改过的旧消息会使运行以history_conflict失败。 - 会话有未完成的中断时,必须在
resume[]中逐一回应(status为resolved或cancelled),否则运行以open_interrupts失败。用户如果改为发送新消息,需要为每个未完成的中断附带一条cancelled。
响应是 text/event-stream,包含本次运行的事件。每个事件由一行 id: <seq> 和一行 data: <AG-UI 事件 JSON> 组成;注释行(: keepalive)用于保持连接。运行到达终止事件后流结束。
运行的生命周期长于 HTTP 响应。关闭流不会取消运行,因此已确认的写操作总会执行完并被记录。会话已有运行进行中时返回 409 run_active。
GET /aidy/v0/threads/{id}/events?after={seq}
Section titled “GET /aidy/v0/threads/{id}/events?after={seq}”以 SSE 回放序号大于 after 的事件,然后继续实时跟随。Last-Event-ID 优先于 after。会话空闲时流结束。见 序号。
POST /aidy/v0/runs/{id}/cancel
Section titled “POST /aidy/v0/runs/{id}/cancel”不需要请求体,也不需要 Content-Type。
- 运行中:
202 {"id": "run_…", "status": "cancelling"},随后运行以cancelled结束。 - 已结束:
200 {"id": "run_…", "status": "<当前状态>"}。
GET /aidy/v0/catalog
Section titled “GET /aidy/v0/catalog”当前用户可见的操作,不含角色操作:
{ "operations": [ { "name": "stop_vm", "title": "Stop server", "description": "Stop a running cloud server (VM).", "effect": "update", "approval": "always", "surfaces": ["agent", "cli"], "input": { "type": "object", "properties": { "vm_id": { "type": "string" } }, "required": ["vm_id"] } } ]}input 是 派生的输入 schema。
GET /aidy/v0/search
Section titled “GET /aidy/v0/search”| 参数 | 含义 |
|---|---|
q |
必填,查询词;为空或缺失时返回 400。 |
limit |
返回的结果数。默认 10,最多 50。 |
types |
逗号分隔的结果类型,只保留这些类型(vm,doc)。 |
aidy 以用户身份并行查询每个 role: search 操作和每个配置的来源(例如 knowledge),每个来源有自己的超时:操作的 x-aidy.timeoutSeconds(默认 2,最大 10),配置来源的 timeoutMs(默认 2000,最大 10 000)。结果按倒数排名融合(reciprocal rank fusion,k = 60)合并。
{ "hits": [ { "source": "search_vms", "type": "vm", "id": "vm-42", "title": "gpu-train-01", "excerpt": "Running · 8 × H100 · cn-beijing-a", "url": "/console/instance/vm-42", "updatedAt": "2026-11-19T08:00:00Z" } ], "failed": [{ "source": "search_chat", "code": "timeout" }]}失败的来源列在 failed 中,代码为 timeout、http_<status> 或 invalid_response;单个来源失败不会导致整个搜索失败。结果不带 content:这段正文只给模型看。见 搜索。
GET /aidy/v0/settings
Section titled “GET /aidy/v0/settings”任何已登录用户都可调用。不会返回 API key:
{ "models": { "chain": [ { "id": "primary", "provider": "openai-compatible", "model": "qwen-plus", "baseURL": "https://…", "hasApiKey": true } ] }}设置了 vision、temperature、maxOutputTokens 和 cooldownSeconds 的条目也会返回这些字段。在代码中以自定义 LanguageModel 提供的模型,provider 显示为 custom。如果保存的设置是用 aidy 已经没有的密钥加密的,所有设置路由都返回 503 settings_unreadable。
PUT /aidy/v0/settings
Section titled “PUT /aidy/v0/settings”用户身份中需要有 aidy:admin scope,否则返回 403 forbidden。请求体会替换整条模型链:
{ "models": { "chain": [ { "id": "primary", "provider": "openai-compatible", "model": "qwen-plus", "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-…", "vision": false, "providerOptions": { "openai-compatible": { "enable_thinking": false } } } ] }}| 字段 | 含义 |
|---|---|
id |
必填,1 到 64 个字符,在链中唯一。 |
provider |
openai-compatible、openai 或 anthropic。 |
model |
必填,模型 id。 |
baseURL |
可选 URL。 |
apiKey |
可选。省略时保留同 id 条目原有的 key。key 在存储时以 AES-GCM 加密。 |
vision |
带图片的轮次使用此模型。 |
temperature、maxOutputTokens |
每次调用该端点时带上。 |
cooldownSeconds |
{quota?, rateLimit?, error?}:失败后的休眠时长(默认 6 小时、60 秒、5 分钟)。 |
providerOptions |
按 provider 名称传给 provider 的选项。 |
模型按顺序尝试。这条链会替换配置中的模型链,包括其中的自定义模型。响应与 GET 相同,为新的设置。见 模型。
设置只包含模型链,知识库设置不在这个 API 中。
DELETE /aidy/v0/settings
Section titled “DELETE /aidy/v0/settings”需要 aidy:admin。删除已保存的设置,让配置中的模型链重新生效,并按 GET 的格式返回。
GET /aidy/v0/info
Section titled “GET /aidy/v0/info”任何已登录用户都可调用:
{ "name": "Aidy" }name 是助手的显示名称(createAidy({ name })、AIDY_NAME),由 @aidy-dev/react 显示。
PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback
Section titled “PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback”{ "rating": "down", "comment": "It stopped the wrong server." }rating 为 up 或 down;comment 可选,最多 2000 个字符。对同一消息的新评价会替换旧评价。返回该反馈条目;消息不是调用者会话中的助手消息时返回 404。删除会话会一并删除其反馈。
GET /aidy/v0/feedback?since=&limit=&cursor=
Section titled “GET /aidy/v0/feedback?since=&limit=&cursor=”需要 aidy:admin。返回调用者所在租户各会话的反馈,最早的在前:
{ "items": [ { "threadId": "th_…", "messageId": "msg_…", "rating": "down", "comment": "It stopped the wrong server.", "subject": "u_1", "createdAt": "2026-11-19T08:00:00.000Z" } ], "next": "<cursor>"}since 是 RFC 3339 时间;limit 默认 50,最多 200。subject 是做出评价的用户,createdAt 是最近一次评价的时间。next 是下一页的 cursor。
POST /aidy/v0/tasks/{taskId}
Section titled “POST /aidy/v0/tasks/{taskId}”操作返回 202 和 {"aidyTask": "<id>"} 即表示延后执行;运行随之以 aidy:task 中断暂停。宿主之后完成该任务:
POST /aidy/v0/tasks/task_123Content-Type: application/jsonAidy-Host-Assertion: <compact JWS>
{"status": "succeeded", "result": {"id": "vm-43"}}| 字段 | 含义 |
|---|---|
status |
succeeded 或 failed。 |
result |
可选。成功时作为工具结果,按操作的 redact 规则脱敏。 |
宿主断言的 op 为发起延后的操作,sub(以及 ten)为任务所属用户的身份。
| 状态码 | 响应体 |
|---|---|
202 |
{"runId": "run_…"}:aidy 已发起一次运行来恢复该中断。 |
401 |
aidy_assertion_invalid:断言缺失、无效或被重放,或未配置宿主公钥。 |
404 |
not_found:没有这个任务。 |
409 |
task_closed(已完成或已取消)或 run_active。 |
用户只能以 cancelled 回应任务中断。
POST /aidy/v0/generate
Section titled “POST /aidy/v0/generate”为宿主的一项任务执行一次模型补全,例如定时报告的摘要。请求用 op 为 generate 的宿主断言签名;sub 和 ten 表示任务为谁执行。
POST /aidy/v0/generateContent-Type: application/jsonAidy-Host-Assertion: <compact JWS>
{ "instructions": "Write the weekly report's summary in two sentences.", "input": "Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).", "schema": { "type": "object", "properties": { "headline": { "type": "string" } }, "required": ["headline"] }, "maxOutputTokens": 400}| 字段 | 含义 |
|---|---|
input |
必填,要处理的文本。 |
instructions |
可选,系统指令。 |
schema |
可选,JSON Schema。提供时返回 {object},一个符合该 schema 的值;否则返回 {text}。 |
maxOutputTokens |
可选,优先于端点自己的设置。 |
调用走模型链,没有工具,也没有会话,受运行超时限制。不符合 schema 的回答会连同问题说明发回同一端点重试一次。见宿主任务。
| 状态码 | 响应体 |
|---|---|
200 |
{"text": "…"} 或 {"object": {…}}。 |
400 |
invalid_request:请求体或 schema 无效。 |
401 |
aidy_assertion_invalid。 |
422 |
invalid_output:第二次回答仍不符合。 |
503 |
model_unavailable。 |
504 |
timeout。 |
Aidy-Host-Assertion 是用宿主私钥签名的 EdDSA JWS,对应公钥配置在 aidy 中(hostKeys、AIDY_HOST_KEYS)。它的头部与委托断言相同,为 {"alg": "EdDSA", "kid": "…", "typ": "aidy-call+jwt"};它的声明与 委托断言 相同,取值如下:
iss为宿主的源,aud为 aidy 自己的 URL;htm为POST;htu为 aidy 公开 URL 的源加上宿主请求的路径和查询串,无论代理把请求转发到哪个内部地址;bsh为本请求体的哈希;op为延后的操作或generate;sub(以及ten)表示调用为谁执行;exp - iat不超过 60 秒;每个jti只接受一次。
校验失败返回 401 aidy_assertion_invalid。JavaScript 宿主可以用 @aidy-dev/spec/delegation 中的 signAssertion(claims, key) 签名,示例见宿主任务。Python 套件没有签名辅助函数,请用任意 Ed25519 JWS 库签出 compact JWS。
/mcp 以用户的 bearer 凭据提供基于 streamable HTTP 的 MCP。工具是带有 mcp surface 的目录操作,外加 search。写操作工具要求客户端通过 MCP elicitation 确认;不支持 elicitation 的客户端能看到该工具,但调用会被拒绝并附上说明。每个工具在 _meta.aidy 中带有它的 CLI 写法({command, args, effect})。
配置了 mcp.authorizationServers 时,aidy 还会提供 GET /.well-known/oauth-protected-resource/mcp。见 MCP 客户端。
| 路由 | 内容 |
|---|---|
GET /skill.md |
text/markdown。调用者可见目录对应的 agent skill。始终返回 200:无凭据时使用宿主匿名提供的 OpenAPI 文档;若宿主对其返回 401/403,则只返回手写指南和连接方式,不列出操作(结果缓存 5 分钟)。GET /llms.txt 同理。 |
GET /llms.txt |
text/plain。同一目录的 llmstxt.org 文件。 |
GET /.well-known/aidy-keys.json |
{"keys": [{"kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "…"}]}:aidy 的签名公钥,供查看。宿主应把它固定在配置中,而不是运行时拉取。 |