agentbase-docs

Agent Runtime API

项目级 Agent Runtime 接口,分两个权限面:开发者面(/agent-versions/{agentVersionId}/...)对 Draft Agent Version 做配置、Gateway 绑定、Skill 管理、就绪检查与预览 Thread/Run;使用者面(/agents/{agentId}/... 与 /runs/{runId}/...)对 Published Agent 做 Thread/Run、可恢复事件流与 E2E 评估。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域按面划分 scope:

Project、Agent Version 与 Published 指针必须一致;跨 Project 访问按未找到处理,不泄露目标资源。组织级管理面(创建 Agent/Version、发布、归档,Console 管理员 Session)不在本文档范围。

端点清单

方法 + 路径用途
GET /agent-runtime/agent-versions/{agentVersionId}/config读取 Draft Version 配置
PATCH /agent-runtime/agent-versions/{agentVersionId}/config稀疏更新 Draft Version 配置
GET /agent-runtime/agent-versions/{agentVersionId}/gateway读取绑定的 AI Gateway
PUT /agent-runtime/agent-versions/{agentVersionId}/gateway绑定 AI Gateway
GET /agent-runtime/agent-versions/{agentVersionId}/models列出可用模型
GET /agent-runtime/agent-versions/{agentVersionId}/readiness发布前就绪检查
`GET\POST /agent-runtime/agent-versions/{agentVersionId}/skills`Skill 列表/上传
`GET\PUT\DELETE .../skills/{skillId}`Skill 读/替换/删
`GET\POST /agent-runtime/agent-versions/{agentVersionId}/threads`预览 Thread 列表/创建
`GET\DELETE .../threads/{threadId}`预览 Thread 读/删
GET .../threads/{threadId}/messages预览 Thread 消息列表
GET .../threads/{threadId}/context-compactions预览 Thread 上下文压缩记录
POST /agent-runtime/agent-versions/{agentVersionId}/runs创建预览 Run
GET .../runs/{runId}读取预览 Run
POST .../runs/{runId}/cancel取消预览 Run
GET .../runs/{runId}/events预览 Run 可恢复事件流
GET .../runs/{runId}/messages预览 Run 消息列表
GET .../runs/{runId}/model-invocations预览 Run 模型调用列表
POST .../runs/{runId}/tool-messages回传预览 Run 的 Client Tool 结果
`GET\POST /agent-runtime/agents/{agentId}/threads`Published Thread 列表/创建
`GET\DELETE /agent-runtime/agents/{agentId}/threads/{threadId}`Published Thread 读/删
GET .../threads/{threadId}/messagesPublished Thread 消息列表
GET .../threads/{threadId}/context-compactionsPublished Thread 上下文压缩记录
POST /agent-runtime/agents/{agentId}/runs在既有 Thread 中创建 Run
POST /agent-runtime/agents/{agentId}/evaluations受理 Langfuse 兼容 E2E 评估
GET /agent-runtime/runs/{runId}读取 Run
POST /agent-runtime/runs/{runId}/cancel取消 Run
GET /agent-runtime/runs/{runId}/eventsRun 可恢复事件流
GET /agent-runtime/runs/{runId}/messagesRun 消息列表
GET /agent-runtime/runs/{runId}/model-invocationsRun 模型调用列表
POST /agent-runtime/runs/{runId}/tool-messages回传 Client Tool 结果

请求与响应

以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:

Agent Version 配置与就绪

GET /v1/agent-runtime/agent-versions/{agentVersionId}/config

SDK:AgentRuntime.getAgentVersionConfig · scope:agent-runtime.read

读取已认证 Draft Version Project 的当前配置。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。

输出:

200,返回 Draft Version 配置对象(泛化 schema any)。字段名与 PATCH 输入对偶(system_prompt、memory_enabled、knowledge_search_enabled、model_id、model_parameters 等),以实际返回为准。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/config" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "model_id": "gpt-4o-mini",
  "system_prompt": "仅基于企业知识回答问题。",
  "memory_enabled": true,
  "knowledge_search_enabled": true,
  "context_window_tokens": 8192,
  "max_steps": 12
}

PATCH /v1/agent-runtime/agent-versions/{agentVersionId}/config

SDK:AgentRuntime.updateAgentVersionConfig · scope:agent-runtime.write

稀疏更新 Draft Agent Version 配置:模型、Memory、Knowledge Search 与执行上限。仅 Draft 可改;Published Version 配置不可变。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
system_promptbodystring否系统提示词;空串使用平台默认。
memory_enabledbodyboolean否是否启用持久 Memory。
knowledge_search_enabledbodyboolean否是否启用 Knowledge Search。
memory_embedding_model_idbodystring否Memory 使用的 Embedding 模型。
memory_embedding_dimensionsbodyinteger否Memory 使用的 Embedding 维度。
model_idbodystring否模型 ID。
model_parametersbodyobject否模型参数(动态对象)。
context_window_tokensbodyinteger否上下文窗口 token 上限。
reserved_output_tokensbodyinteger否预留输出 token 数。
max_stepsbodyinteger否最大 Agent 步数。
max_duration_msbodyinteger否单次 Run 最大时长(毫秒)。

输出:

200,返回更新后的配置对象(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X PATCH "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/config" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "gpt-4o-mini",
    "system_prompt": "仅基于企业知识回答问题。",
    "memory_enabled": true,
    "knowledge_search_enabled": true,
    "context_window_tokens": 8192,
    "reserved_output_tokens": 1024,
    "max_steps": 12,
    "max_duration_ms": 120000
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "model_id": "gpt-4o-mini",
  "memory_enabled": true,
  "knowledge_search_enabled": true,
  "max_steps": 12
}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/gateway

SDK:AgentRuntime.getAgentVersionGateway · scope:agent-runtime.read

读取绑定到已认证 Version Project 的 AI Gateway。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。

输出:

200,返回绑定的 Gateway 对象(泛化 schema any,字段以实际返回为准;绑定关系字段名与 PUT 输入 gateway_id 对偶)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/gateway" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "gateway_id": "gw_agent_runtime_01"
}

PUT /v1/agent-runtime/agent-versions/{agentVersionId}/gateway

SDK:AgentRuntime.updateAgentVersionGateway · scope:agent-runtime.write

把一个活跃 AI Gateway 绑定到已认证 Draft Version Project。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
gateway_idbodystring是AI Gateway ID。

输出:

200,返回绑定结果(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/gateway" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway_id": "gw_agent_runtime_01"
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "gateway_id": "gw_agent_runtime_01"
}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/models

SDK:AgentRuntime.listAgentVersionModels · scope:agent-runtime.read

列出经已认证 Version Project Gateway 可用的模型。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。

输出:

200,返回可用模型列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/models" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/readiness

SDK:AgentRuntime.getAgentVersionReadiness · scope:agent-runtime.read

发布前就绪检查:分别检查 model、Gateway、Memory、Knowledge Search 与 Skill 的就绪状态。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。

输出:

200,返回就绪报告(泛化 schema any):分项检查 model / memory / knowledge / skills / gateway,顶层 ready=true 时才可发布;其余字段以实际返回为准。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/readiness" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "ready": true
}

Skill 管理

GET /v1/agent-runtime/agent-versions/{agentVersionId}/skills

SDK:AgentRuntime.listAgentVersionSkills · scope:agent-runtime.read

列出已认证 Version Project 中的 Skill。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。

输出:

200,返回 Skill 列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/skills" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/agent-versions/{agentVersionId}/skills

SDK:AgentRuntime.createAgentVersionSkill · scope:agent-runtime.write

向 Draft Agent Version 上传 Skill 包(multipart 上传)。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
filebody(multipart/form-data)string(binary)是Skill 包文件:.zip、.tar.gz 或 .tgz。

输出:

201,返回创建的 Skill 对象(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/skills" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -F "file=@skill-pdf-tools.zip"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/skills/{skillId}

SDK:AgentRuntime.getAgentVersionSkill · scope:agent-runtime.read

读取已认证 Version Project 中的单个 Skill。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
skillIdpathstring是Skill ID。

输出:

200,返回 Skill 对象(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/skills/skill_pdf_tools" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

PUT /v1/agent-runtime/agent-versions/{agentVersionId}/skills/{skillId}

SDK:AgentRuntime.updateAgentVersionSkill · scope:agent-runtime.write

替换 Draft Agent Version 上的 Skill 包(multipart 上传整个新包)。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
skillIdpathstring是Skill ID。
filebody(multipart/form-data)string(binary)是新 Skill 包文件:.zip、.tar.gz 或 .tgz。

输出:

200,返回更新后的 Skill 对象(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/skills/skill_pdf_tools" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -F "file=@skill-pdf-tools-v2.tar.gz"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

DELETE /v1/agent-runtime/agent-versions/{agentVersionId}/skills/{skillId}

SDK:AgentRuntime.deleteAgentVersionSkill · scope:agent-runtime.write

从已认证 Draft Version Project 删除 Skill。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
skillIdpathstring是Skill ID。

输出:

204,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/skills/skill_pdf_tools" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204,无响应体。

预览 Thread(Draft Version)

GET /v1/agent-runtime/agent-versions/{agentVersionId}/threads

SDK:AgentRuntime.listPreviewThreads · scope:agent-runtime.write

列出 Draft Agent Version 的开发者预览 Thread。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回预览 Thread 列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/threads?limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/agent-versions/{agentVersionId}/threads

SDK:AgentRuntime.createPreviewThread · scope:agent-runtime.write

为 Draft Agent Version 创建开发者预览 Thread。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。

无请求体。

输出:

201,返回创建的预览 Thread(泛化 schema any;Thread 标识字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/threads" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/threads/{threadId}

SDK:AgentRuntime.getPreviewThread · scope:agent-runtime.write

读取一个开发者预览 Thread。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
threadIdpathstring是Thread ID。

输出:

200,返回预览 Thread(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/threads/th_0001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

DELETE /v1/agent-runtime/agent-versions/{agentVersionId}/threads/{threadId}

SDK:AgentRuntime.deletePreviewThread · scope:agent-runtime.write

删除一个开发者预览 Thread。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
threadIdpathstring是Thread ID。

输出:

204,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/threads/th_0001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204,无响应体。

GET /v1/agent-runtime/agent-versions/{agentVersionId}/threads/{threadId}/messages

SDK:AgentRuntime.listPreviewThreadMessages · scope:agent-runtime.write

列出开发者预览 Thread 中的消息。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
threadIdpathstring是Thread ID。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回消息列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/threads/th_0001/messages?limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/threads/{threadId}/context-compactions

SDK:AgentRuntime.listPreviewContextCompactions · scope:agent-runtime.write

列出开发者预览 Thread 的上下文压缩(context compaction)记录。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
threadIdpathstring是Thread ID。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回上下文压缩记录列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/threads/th_0001/context-compactions?limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

预览 Run(Draft Version)

POST /v1/agent-runtime/agent-versions/{agentVersionId}/runs

SDK:AgentRuntime.createPreviewRun · scope:agent-runtime.write

为 Draft Agent Version 创建开发者预览 Run。返回 202:Run 异步执行,事件经 GET .../events 订阅。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
thread_idbodystring是预览 Thread ID。
user_messagebodystring是用户消息。

输出:

202,返回受理的预览 Run(泛化 schema any;Run 标识字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "th_0001",
    "user_message": "帮我总结一下最新一篇产品文档的要点。"
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/runs/{runId}

SDK:AgentRuntime.getPreviewRun · scope:agent-runtime.write

读取一个开发者预览 Run。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
runIdpathstring是Run ID。

输出:

200,返回预览 Run(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs/run_0001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/agent-versions/{agentVersionId}/runs/{runId}/cancel

SDK:AgentRuntime.cancelPreviewRun · scope:agent-runtime.write

取消一个开发者预览 Run。SSE 断线不会取消 Run,取消必须显式调用本端点。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
runIdpathstring是Run ID。

无请求体。

输出:

202,返回取消受理结果(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs/run_0001/cancel" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/runs/{runId}/events

SDK:AgentRuntime.streamPreviewRunEvents · scope:agent-runtime.write

订阅开发者预览 Run 的可恢复事件流(SSE):断线后把最后收到的事件 id 作为 Last-Event-ID 重连同一个 Run。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
runIdpathstring是Run ID。

输出:

200(spec 声明为 application/json 泛化 schema any;实际为可恢复的 SSE 事件流,事件类型与负载以实际返回为准)。

调用示例:

curl -N -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs/run_0001/events" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(SSE 流,示意——事件类型与负载以实际返回为准):

id: 17
event: RUN_FINISHED
data: {"run_id": "run_0001"}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/runs/{runId}/messages

SDK:AgentRuntime.listPreviewRunMessages · scope:agent-runtime.write

列出开发者预览 Run 产出的消息。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
runIdpathstring是Run ID。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回消息列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs/run_0001/messages?limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agent-versions/{agentVersionId}/runs/{runId}/model-invocations

SDK:AgentRuntime.listPreviewModelInvocations · scope:agent-runtime.write

列出开发者预览 Run 的模型调用记录。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
runIdpathstring是Run ID。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回模型调用列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs/run_0001/model-invocations?limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/agent-versions/{agentVersionId}/runs/{runId}/tool-messages

SDK:AgentRuntime.submitPreviewToolMessage · scope:agent-runtime.write

向开发者预览 Run 回传一条 Client Tool 执行结果:Run 进入等待 Client Tool 状态后,客户端执行事件携带的调用并用本端点回传。

输入:

参数位置类型必填默认/枚举说明
agentVersionIdpathstring是Agent Version ID。
runIdpathstring是Run ID。
idbodystring是Tool 消息 ID。
rolebodystring是必须为 tool消息角色。
toolCallIdbodystring是Tool 调用 ID。
contentbodystring是JSON 编码的 Tool 结果。
errorbodystring否Tool 执行错误(可选)。

输出:

202,返回受理结果(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agent-versions/av_draft_001/runs/run_0001/tool-messages" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "tm_0001",
    "role": "tool",
    "toolCallId": "tc_0001",
    "content": "{\"tracking\":\"已发货\"}"
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

Published Thread

GET /v1/agent-runtime/agents/{agentId}/threads

SDK:AgentRuntime.listThreads · scope:agent-runtime.execute

列出当前 Project 主体创建的 Thread。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。
agent_version_idquerystring是创建 Thread 时返回的 Published Agent Version。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回 Thread 列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/threads?agent_version_id=av_pub_001&limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/agents/{agentId}/threads

SDK:AgentRuntime.createThread · scope:agent-runtime.execute

用 Agent 当前 Published Version 创建 Thread。响应携带服务端固定的 agent_version_id(字段名以实际返回为准),后续 Run 与读取操作都需带上它。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。

无请求体。

输出:

201,返回创建的 Thread(泛化 schema any;已确证字段:thread_id、agent_version_id,其余以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/threads" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "thread_id": "th_0001",
  "agent_version_id": "av_pub_001"
}

GET /v1/agent-runtime/agents/{agentId}/threads/{threadId}

SDK:AgentRuntime.getThread · scope:agent-runtime.execute

读取当前 Project 主体拥有的 Thread。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。
threadIdpathstring是Thread ID。
agent_version_idquerystring是创建 Thread 时返回的 Published Agent Version。

输出:

200,返回 Thread(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/threads/th_0001?agent_version_id=av_pub_001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

DELETE /v1/agent-runtime/agents/{agentId}/threads/{threadId}

SDK:AgentRuntime.deleteThread · scope:agent-runtime.execute

删除当前 Project 主体拥有的 Thread(DELETE 携带 JSON 请求体)。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。
threadIdpathstring是Thread ID。
agent_version_idbodystring是创建 Thread 时返回的 Published Agent Version。

输出:

204,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/threads/th_0001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_version_id": "av_pub_001"
  }'

响应示例:204,无响应体。

GET /v1/agent-runtime/agents/{agentId}/threads/{threadId}/messages

SDK:AgentRuntime.listThreadMessages · scope:agent-runtime.execute

列出 Thread 中的消息。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。
threadIdpathstring是Thread ID。
agent_version_idquerystring是创建 Thread 时返回的 Published Agent Version。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回消息列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/threads/th_0001/messages?agent_version_id=av_pub_001&limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/agents/{agentId}/threads/{threadId}/context-compactions

SDK:AgentRuntime.listContextCompactions · scope:agent-runtime.execute

列出 Thread 的上下文压缩(context compaction)记录。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。
threadIdpathstring是Thread ID。
agent_version_idquerystring是创建 Thread 时返回的 Published Agent Version。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回上下文压缩记录列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/threads/th_0001/context-compactions?agent_version_id=av_pub_001&limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

Published Run 与评估

POST /v1/agent-runtime/agents/{agentId}/runs

SDK:AgentRuntime.createRun · scope:agent-runtime.execute

在既有 Thread 中创建 Run。返回 202:Run 异步执行,不保持长连接;事件经 GET /runs/{runId}/events 订阅。支持 Idempotency-Key 请求头(1–128 bytes):同一 key + 同一请求重放返回原 Run,同一 key 对应不同请求返回 409。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。
agent_version_idbodystring是创建 Thread 时返回的 Published Agent Version。
thread_idbodystring是Thread ID。
user_messagebodystring是用户消息。

输出:

202,返回受理的 Run(泛化 schema any;已确证字段:run_id,其余以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/runs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: order-query-20260918-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_version_id": "av_pub_001",
    "thread_id": "th_0001",
    "user_message": "我的订单什么时候发货?"
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{
  "run_id": "run_0001"
}

GET /v1/agent-runtime/runs/{runId}

SDK:AgentRuntime.getRun · scope:agent-runtime.execute

读取当前 Project 主体拥有的 Run。

输入:

参数位置类型必填默认/枚举说明
runIdpathstring是Run ID。
agent_version_idquerystring是与 Run 关联的 Published Agent Version。

输出:

200,返回 Run(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/runs/run_0001?agent_version_id=av_pub_001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/runs/{runId}/cancel

SDK:AgentRuntime.cancelRun · scope:agent-runtime.execute

取消当前 Project 主体拥有的 Run。SSE 断线不会取消 Run,取消必须显式调用本端点。

输入:

参数位置类型必填默认/枚举说明
runIdpathstring是Run ID。
agent_version_idbodystring是与 Run 关联的 Published Agent Version。

输出:

202,返回取消受理结果(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/runs/run_0001/cancel" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_version_id": "av_pub_001"
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/runs/{runId}/events

SDK:AgentRuntime.streamRunEvents · scope:agent-runtime.execute

订阅 Run 的可恢复事件流(SSE):断线后把最后收到的事件 id 作为 Last-Event-ID 重连同一个 Run;收到 RUN_FINISHED / RUN_ERROR / RUN_CANCELLED 后读取持久化消息。

输入:

参数位置类型必填默认/枚举说明
runIdpathstring是Run ID。
agent_version_idquerystring是与 Run 关联的 Published Agent Version。

输出:

200(spec 声明为 application/json 泛化 schema any;实际为可恢复的 SSE 事件流,事件类型与负载以实际返回为准)。

调用示例:

curl -N -X GET "https://<your-endpoint>/v1/agent-runtime/runs/run_0001/events?agent_version_id=av_pub_001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(SSE 流,示意——事件类型与负载以实际返回为准):

id: 17
event: RUN_FINISHED
data: {"run_id": "run_0001"}

GET /v1/agent-runtime/runs/{runId}/messages

SDK:AgentRuntime.listRunMessages · scope:agent-runtime.execute

列出 Run 产出的消息。

输入:

参数位置类型必填默认/枚举说明
runIdpathstring是Run ID。
agent_version_idquerystring是与 Run 关联的 Published Agent Version。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回消息列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/runs/run_0001/messages?agent_version_id=av_pub_001&limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

GET /v1/agent-runtime/runs/{runId}/model-invocations

SDK:AgentRuntime.listModelInvocations · scope:agent-runtime.execute

列出 Run 的模型调用记录。

输入:

参数位置类型必填默认/枚举说明
runIdpathstring是Run ID。
agent_version_idquerystring是与 Run 关联的 Published Agent Version。
limitqueryinteger否默认 25单页最大条数。
afterquerystring否默认 ""分页游标。

输出:

200,返回模型调用列表(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/agent-runtime/runs/run_0001/model-invocations?agent_version_id=av_pub_001&limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/runs/{runId}/tool-messages

SDK:AgentRuntime.submitToolMessage · scope:agent-runtime.execute

向等待中的 Run 回传一条 Client Tool 执行结果:Run 进入等待 Client Tool 状态后,客户端执行事件携带的调用并用本端点回传同一个 runId;Tool 失败同样回传并附 error。

输入:

参数位置类型必填默认/枚举说明
runIdpathstring是Run ID。
agent_version_idbodystring是与 Run 关联的 Published Agent Version。
idbodystring是Tool 消息 ID。
rolebodystring是必须为 tool消息角色。
toolCallIdbodystring是Tool 调用 ID。
contentbodystring是JSON 编码的 Tool 结果。
errorbodystring否Tool 执行错误(可选)。

输出:

202,返回受理结果(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/runs/run_0001/tool-messages" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_version_id": "av_pub_001",
    "id": "tm_0001",
    "role": "tool",
    "toolCallId": "tc_0001",
    "content": "{\"tracking\":\"已发货\"}"
  }'

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

POST /v1/agent-runtime/agents/{agentId}/evaluations

SDK:AgentRuntime.evaluateAgent · scope:agent-runtime.execute

受理一个 Langfuse 兼容的 E2E 评估:对当前 Published Agent Version 按真实 Agent loop 执行评估(Memory、RAG、Skill、Tool 按真实链路运行)。

输入:

参数位置类型必填默认/枚举说明
agentIdpathstring是Agent ID。

spec 未声明请求体。

输出:

202,返回受理结果(泛化 schema any,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/agent-runtime/agents/agent_support_bot/evaluations" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(泛化 schema,示意——字段以实际返回为准):

{}

错误与边界

与 Server SDK 的对应

service.method端点
AgentRuntime.getAgentVersionConfig / updateAgentVersionConfigGET / PATCH /agent-runtime/agent-versions/{agentVersionId}/config
AgentRuntime.getAgentVersionGateway / updateAgentVersionGatewayGET / PUT .../gateway
AgentRuntime.listAgentVersionModelsGET .../models
AgentRuntime.getAgentVersionReadinessGET .../readiness
AgentRuntime.listAgentVersionSkills / createAgentVersionSkillGET / POST .../skills
AgentRuntime.getAgentVersionSkill / updateAgentVersionSkill / deleteAgentVersionSkillGET / PUT / DELETE .../skills/{skillId}
AgentRuntime.listPreviewThreads / createPreviewThreadGET / POST .../agent-versions/{agentVersionId}/threads
AgentRuntime.getPreviewThread / deletePreviewThreadGET / DELETE .../threads/{threadId}
AgentRuntime.listPreviewThreadMessages / listPreviewContextCompactionsGET .../threads/{threadId}/messages、GET .../context-compactions
AgentRuntime.createPreviewRun / getPreviewRun / cancelPreviewRunPOST .../runs、GET .../runs/{runId}、POST .../cancel
AgentRuntime.streamPreviewRunEventsGET .../runs/{runId}/events
AgentRuntime.listPreviewRunMessages / listPreviewModelInvocations / submitPreviewToolMessageGET .../messages、GET .../model-invocations、POST .../tool-messages
AgentRuntime.listThreads / createThreadGET / POST /agent-runtime/agents/{agentId}/threads
AgentRuntime.getThread / deleteThreadGET / DELETE .../threads/{threadId}
AgentRuntime.listThreadMessages / listContextCompactionsGET .../threads/{threadId}/messages、GET .../context-compactions
AgentRuntime.createRunPOST /agent-runtime/agents/{agentId}/runs
AgentRuntime.getRun / cancelRun / streamRunEventsGET /agent-runtime/runs/{runId}、POST .../cancel、GET .../events
AgentRuntime.listRunMessages / listModelInvocations / submitToolMessageGET .../messages、GET .../model-invocations、POST .../tool-messages
AgentRuntime.evaluateAgentPOST /agent-runtime/agents/{agentId}/evaluations

事实源