Agent Runtime API
项目级 Agent Runtime 接口,分两个权限面:开发者面(/agent-versions/{agentVersionId}/...)对 Draft Agent Version 做配置、Gateway 绑定、Skill 管理、就绪检查与预览 Thread/Run;使用者面(/agents/{agentId}/... 与 /runs/{runId}/...)对 Published Agent 做 Thread/Run、可恢复事件流与 E2E 评估。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/agent-runtime。 - 开发者面资源层级:Draft Agent Version
{agentVersionId}→ 预览 Thread{threadId}/ 预览 Run{runId}/ Skill{skillId}。 - 使用者面资源层级:Published Agent
{agentId}→ Thread{threadId}→ Run{runId};Run 另可从/runs/{runId}直读。 - Run 创建(
202)与事件流(GET .../events)分离:先创建 Run,再连接事件流;断线后用最后收到的事件id作为Last-Event-ID续连同一个 Run。
认证与权限
认证与请求头约定见 通用约定。本域按面划分 scope:
- 开发者面(Draft Version Project,仅 Project + API Key):
agent-runtime.read(config/gateway/models/readiness/skills 读取)、agent-runtime.write(配置写、Gateway 绑定、Skill 上传、预览 Thread/Run 全部操作)。 - 使用者面(Published Version Project,Session/JWT 或仅含执行 scope 的 API Key):
agent-runtime.execute覆盖 Thread/Run/事件流/评估全部端点。
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}/messages | Published Thread 消息列表 | ||
GET .../threads/{threadId}/context-compactions | Published 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}/events | Run 可恢复事件流 | ||
GET /agent-runtime/runs/{runId}/messages | Run 消息列表 | ||
GET /agent-runtime/runs/{runId}/model-invocations | Run 模型调用列表 | ||
POST /agent-runtime/runs/{runId}/tool-messages | 回传 Client Tool 结果 |
请求与响应
以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:
- 认证:开发者面示例携带
X-Appwrite-Project: <YOUR_PROJECT_ID>(Draft Version Project)与X-Appwrite-Key: <YOUR_API_KEY>;使用者面可换用 Session/JWT,示例统一用双头写法。 - **本域全部端点的响应在 spec 中均为泛化 schema
any(object),未声明字段级模型**:下文「输出」只标注已确证的字段(来自请求体对偶字段或语义参考),其余字段以实际返回为准。 - 列表端点统一用
limit(默认 25)+after(游标,默认"")分页。 - 示例中的资源 ID(
av_draft_001、agent_support_bot、th_0001、run_0001、skill_pdf_tools)请替换为实际值。
Agent Version 配置与就绪
GET /v1/agent-runtime/agent-versions/{agentVersionId}/config
SDK:AgentRuntime.getAgentVersionConfig · scope:agent-runtime.read
读取已认证 Draft Version Project 的当前配置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | 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 配置不可变。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
system_prompt | body | string | 否 | 系统提示词;空串使用平台默认。 | |
memory_enabled | body | boolean | 否 | 是否启用持久 Memory。 | |
knowledge_search_enabled | body | boolean | 否 | 是否启用 Knowledge Search。 | |
memory_embedding_model_id | body | string | 否 | Memory 使用的 Embedding 模型。 | |
memory_embedding_dimensions | body | integer | 否 | Memory 使用的 Embedding 维度。 | |
model_id | body | string | 否 | 模型 ID。 | |
model_parameters | body | object | 否 | 模型参数(动态对象)。 | |
context_window_tokens | body | integer | 否 | 上下文窗口 token 上限。 | |
reserved_output_tokens | body | integer | 否 | 预留输出 token 数。 | |
max_steps | body | integer | 否 | 最大 Agent 步数。 | |
max_duration_ms | body | integer | 否 | 单次 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
gateway_id | body | string | 是 | 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 可用的模型。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | 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 的就绪状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | 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 上传)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
file | body(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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
skillId | path | string | 是 | 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 上传整个新包)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
skillId | path | string | 是 | Skill ID。 | |
file | body(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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
skillId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
threadId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
threadId | path | string | 是 | 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 中的消息。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
threadId | path | string | 是 | Thread ID。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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)记录。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
threadId | path | string | 是 | Thread ID。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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 订阅。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
thread_id | body | string | 是 | 预览 Thread ID。 | |
user_message | body | string | 是 | 用户消息。 |
输出:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
runId | path | string | 是 | 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,取消必须显式调用本端点。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
runId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
runId | path | string | 是 | 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 产出的消息。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
runId | path | string | 是 | Run ID。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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 的模型调用记录。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
runId | path | string | 是 | Run ID。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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 状态后,客户端执行事件携带的调用并用本端点回传。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentVersionId | path | string | 是 | Agent Version ID。 | |
runId | path | string | 是 | Run ID。 | |
id | body | string | 是 | Tool 消息 ID。 | |
role | body | string | 是 | 必须为 tool | 消息角色。 |
toolCallId | body | string | 是 | Tool 调用 ID。 | |
content | body | string | 是 | JSON 编码的 Tool 结果。 | |
error | body | string | 否 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | Agent ID。 | |
agent_version_id | query | string | 是 | 创建 Thread 时返回的 Published Agent Version。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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 与读取操作都需带上它。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | Agent ID。 | |
threadId | path | string | 是 | Thread ID。 | |
agent_version_id | query | string | 是 | 创建 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 请求体)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | Agent ID。 | |
threadId | path | string | 是 | Thread ID。 | |
agent_version_id | body | string | 是 | 创建 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 中的消息。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | Agent ID。 | |
threadId | path | string | 是 | Thread ID。 | |
agent_version_id | query | string | 是 | 创建 Thread 时返回的 Published Agent Version。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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)记录。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | Agent ID。 | |
threadId | path | string | 是 | Thread ID。 | |
agent_version_id | query | string | 是 | 创建 Thread 时返回的 Published Agent Version。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | Agent ID。 | |
agent_version_id | body | string | 是 | 创建 Thread 时返回的 Published Agent Version。 | |
thread_id | body | string | 是 | Thread ID。 | |
user_message | body | string | 是 | 用户消息。 |
输出:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runId | path | string | 是 | Run ID。 | |
agent_version_id | query | string | 是 | 与 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,取消必须显式调用本端点。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runId | path | string | 是 | Run ID。 | |
agent_version_id | body | string | 是 | 与 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 后读取持久化消息。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runId | path | string | 是 | Run ID。 | |
agent_version_id | query | string | 是 | 与 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 产出的消息。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runId | path | string | 是 | Run ID。 | |
agent_version_id | query | string | 是 | 与 Run 关联的 Published Agent Version。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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 的模型调用记录。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runId | path | string | 是 | Run ID。 | |
agent_version_id | query | string | 是 | 与 Run 关联的 Published Agent Version。 | |
limit | query | integer | 否 | 默认 25 | 单页最大条数。 |
after | query | string | 否 | 默认 "" | 分页游标。 |
输出:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runId | path | string | 是 | Run ID。 | |
agent_version_id | body | string | 是 | 与 Run 关联的 Published Agent Version。 | |
id | body | string | 是 | Tool 消息 ID。 | |
role | body | string | 是 | 必须为 tool | 消息角色。 |
toolCallId | body | string | 是 | Tool 调用 ID。 | |
content | body | string | 是 | JSON 编码的 Tool 结果。 | |
error | body | string | 否 | 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 按真实链路运行)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
agentId | path | string | 是 | 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,示意——字段以实际返回为准):
{}错误与边界
- 跨 Project / 跨 Version 访问按未找到处理(
404语义),不泄露目标资源存在性。 - Draft 专属操作(配置更新、Skill 上传、预览)对 Published / Archived Version 不可用;发布前
readiness未通过时发布被拒(409)。 - Run admission 会冻结 Version、Project、Principal 与有效配置:Run 开始后编辑 Draft 不影响已开始的 Run。
- 事件流断线不取消 Run;游标早于事件保留窗口时重连返回
409 stream_cursor_expired——先读取持久化 Run/消息终态,不要新建重复 Run。 - Run 创建幂等:
Idempotency-Key同 key 同请求重放返回原 Run(200+idempotent_replay=true),同 key 不同请求返回409;调用方须保存并复用 key。 - Client Tool 回传必须用同一个
runId,不能创建第二个 Run 顶替。 - 列表分页统一
limit+after游标;limit默认 25。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
AgentRuntime.getAgentVersionConfig / updateAgentVersionConfig | GET / PATCH /agent-runtime/agent-versions/{agentVersionId}/config |
AgentRuntime.getAgentVersionGateway / updateAgentVersionGateway | GET / PUT .../gateway |
AgentRuntime.listAgentVersionModels | GET .../models |
AgentRuntime.getAgentVersionReadiness | GET .../readiness |
AgentRuntime.listAgentVersionSkills / createAgentVersionSkill | GET / POST .../skills |
AgentRuntime.getAgentVersionSkill / updateAgentVersionSkill / deleteAgentVersionSkill | GET / PUT / DELETE .../skills/{skillId} |
AgentRuntime.listPreviewThreads / createPreviewThread | GET / POST .../agent-versions/{agentVersionId}/threads |
AgentRuntime.getPreviewThread / deletePreviewThread | GET / DELETE .../threads/{threadId} |
AgentRuntime.listPreviewThreadMessages / listPreviewContextCompactions | GET .../threads/{threadId}/messages、GET .../context-compactions |
AgentRuntime.createPreviewRun / getPreviewRun / cancelPreviewRun | POST .../runs、GET .../runs/{runId}、POST .../cancel |
AgentRuntime.streamPreviewRunEvents | GET .../runs/{runId}/events |
AgentRuntime.listPreviewRunMessages / listPreviewModelInvocations / submitPreviewToolMessage | GET .../messages、GET .../model-invocations、POST .../tool-messages |
AgentRuntime.listThreads / createThread | GET / POST /agent-runtime/agents/{agentId}/threads |
AgentRuntime.getThread / deleteThread | GET / DELETE .../threads/{threadId} |
AgentRuntime.listThreadMessages / listContextCompactions | GET .../threads/{threadId}/messages、GET .../context-compactions |
AgentRuntime.createRun | POST /agent-runtime/agents/{agentId}/runs |
AgentRuntime.getRun / cancelRun / streamRunEvents | GET /agent-runtime/runs/{runId}、POST .../cancel、GET .../events |
AgentRuntime.listRunMessages / listModelInvocations / submitToolMessage | GET .../messages、GET .../model-invocations、POST .../tool-messages |
AgentRuntime.evaluateAgent | POST /agent-runtime/agents/{agentId}/evaluations |
事实源
- Server API spec:
agentbase-sdksv2.7.2specs/open-api3-latest-server.json(/agent-runtime/域 29 个路径、x-appwrite scope/group、multipart 上传契约)。 - Server SDK 生成物:
server-nodejsv2.7.0AgentRuntimeservice(方法名与参数序实读src/services/agent-runtime.ts)。 - 语义深度参考:
skills/ob-agentbase/references/agent-runtime.md(三种权限面、SSE 续连与stream_cursor_expired、Run 幂等、Client Tool 回传、E2E 评估语义)。 - 上游发布:appbase
v2.7.0(release-2.7.0 分支尖端34b7c8633813a8fe75cc58e8348bd4a9efdd0e21)。 - 证据缺口:本域响应全部为泛化 schema
any,字段级响应模型以实际返回为准;未对 SIT/生产实例做实机调用验证。