跳转到内容

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 报告,见 事件。

{ "title": "Optional title, at most 200 characters" }

201:

{ "id": "th_…", "title": "", "createdAt": "2026-11-19T08:00:00.000Z" }
{
"items": [{ "id": "th_…", "title": "…", "createdAt": "…", "updatedAt": "…" }],
"next": "<cursor>"
}

每页 20 个会话。还有更多时会返回 next,把它作为 cursor 传入即可。

{
"id": "th_…",
"title": "…",
"createdAt": "…",
"updatedAt": "…",
"messages": [],
"interrupts": []
}

messages 是 AG-UI 的 Message[]。interrupts 是未完成的中断,结构见 中断。

{ "title": "New title" }

title 必填,去掉首尾空白后为 1 到 200 个字符。返回与列表中相同结构的会话。

204。会话连同其消息、事件、运行、中断和任务一并删除。

请求体是 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。会话空闲时流结束。见 序号。

不需要请求体,也不需要 Content-Type。

  • 运行中:202 {"id": "run_…", "status": "cancelling"},随后运行以 cancelled 结束。
  • 已结束:200 {"id": "run_…", "status": "<当前状态>"}。

当前用户可见的操作,不含角色操作:

{
"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。

参数 含义
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:这段正文只给模型看。见 搜索。

任何已登录用户都可调用。不会返回 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。

用户身份中需要有 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 中。

需要 aidy:admin。删除已保存的设置,让配置中的模型链重新生效,并按 GET 的格式返回。

任何已登录用户都可调用:

{ "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。

操作返回 202 和 {"aidyTask": "<id>"} 即表示延后执行;运行随之以 aidy:task 中断暂停。宿主之后完成该任务:

POST /aidy/v0/tasks/task_123
Content-Type: application/json
Aidy-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 回应任务中断。

为宿主的一项任务执行一次模型补全,例如定时报告的摘要。请求用 op 为 generate 的宿主断言签名;sub 和 ten 表示任务为谁执行。

POST /aidy/v0/generate
Content-Type: application/json
Aidy-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 的签名公钥,供查看。宿主应把它固定在配置中,而不是运行时拉取。