Agent Runtime API
项目级智能体工作台(Project Agent Runtime)REST API 参考文档。业务后端通过项目级 API Key 接入当前项目下的托管智能体运行引擎(/v1/agent-runtime/project/*),统一管理项目运行配置、词库绑定、AI Gateway 工具发现、Skill 技能包上传,并通过 userId 为不同业务终端用户隔离管理会话(Thread)、异步任务(Run)、可恢复流式事件(SSE)与客户端工具回传(Client Tool)。
资源与基础路径
Base URL:
https://appbuild-sit.oceanbase.com/v1,项目级智能体工作台路径前缀固定为/v1/agent-runtime/project。关联环境坐标(以 SIT 演示环境为例):
所属组织:
Agentbase 企业智能中台(69c6d1aa00062e6bb60)所属项目:
企业智能客服与知识中台(Project ID:enterprise-ai-hub-210,存储架构:Shared V2)模型供应商:
dashscope-prod(支持对话模型qwen-plus、qwen-turbo,向量模型text-embedding-v31024 维,重排模型qwen3.7-text-rerank,多模态模型qwen-vl-max)AI Gateway:
prod-enterprise-ai-gateway(Gateway ID:gw_7194685489feb1e169548619)企业知识库:
kb_enterprise_support业务词库:
lex_enterprise_synonyms(企业同义词与扩展词库)、lex_support_stopwords(客服合规停用词库)业务终端用户示例:
user_zhangwei_001、user_lina_002
核心资源模型与职责边界
| 资源对象 | 核心标识与路径 | 归属范围 | 关键语义与生命周期说明 |
|---|---|---|---|
| Project Runtime 状态(State) | /v1/agent-runtime/project | 项目共享 | initialized: boolean 表示当前项目智能体工作台是否已完成初始化;重复 POST 初始化保持幂等,不会清空已有配置与历史。 |
| 项目配置(Config) | /v1/agent-runtime/project/config | 项目共享 | 包含 system_prompt、model_id、model_parameters、上下文窗口与输出 Token 预算、最大推理步数与超时时长,以及 memory_enabled、powercontext_enabled(与 Memory 互斥)、knowledge_search_enabled 与 knowledge_base_ids;返回只读 config_hash。Run 受理时冻结当次有效配置,修改项目配置不影响在途 Run。 |
| 可用模型目录(ModelList) | /v1/agent-runtime/project/models | 项目共享 | 列出当前项目已配置且可供智能体工作台选择的对话(chat)与向量(embedding)模型列表。 |
| 项目词库绑定(LexiconBindings) | /v1/agent-runtime/project/lexicons | 项目共享 | 将当前项目下的词库(最多 100 个,按 priority 升序)挂载到智能体工作台,支持查询同义词/扩展词改写以及命中 stop 停用词时的短路拦截(stopIntercept: true)与预设合规回复(stopReply)。 |
| AI Gateway 绑定(Gateway) | /v1/agent-runtime/project/gateway | 项目共享 | 绑定同项目下状态为 ACTIVE 且已有可用发布快照的 AI Gateway(gateway_id),使智能体在运行期自动发现并调用授权范围内的 MCP / HTTP 工具与 Client Tool(仅支持 Shared V2 项目)。 |
| 技能包(Skill) | /v1/agent-runtime/project/skills/{skillId} | 项目共享 | 上传 .zip / .tar.gz / .tgz 归档包(上限 10 MiB,根目录含带 YAML Front Matter 的 SKILL.md),供智能体按需发现和读取任务说明与操作规范;上传技能包不代表执行任意脚本。 |
| 会话(Thread) | /v1/agent-runtime/project/threads/{threadId} | 用户隔离(userId) | 承载同一业务用户的多轮连续对话历史,状态为 ACTIVE 或 ARCHIVED。同一 Thread 同一时刻最多只允许存在一个未结束的 Run。 |
| 运行(Run) | /v1/agent-runtime/project/runs/{runId} | 用户隔离(userId) | 一次用户消息触发的 ReAct 推理与工具调用循环;POST /runs 异步受理并返回 202 Accepted(携带 Idempotency-Key 相同请求重放返回 200 OK 与 idempotent_replay: true)。 |
| 消息(Message) | .../threads/{threadId}/messages、.../runs/{runId}/messages | 用户隔离(userId) | 持久化的会话或单次运行消息记录,按会话内递增序号 message_seq 排序,类型涵盖 USER、ASSISTANT、TOOL_CALL、TOOL_RESULT。 |
| 流式事件(SSE Event) | /v1/agent-runtime/project/runs/{runId}/events | 用户隔离(userId) | 基于 AG-UI 协议的有界增量事件流(text/event-stream),支持通过 Last-Event-ID 断线续传;SSE 断开不会取消后台 Run。 |
| 模型调用记录(ModelInvocation) | /v1/agent-runtime/project/runs/{runId}/model-invocations | 用户隔离(userId) | 记录单次 Run 内每一个模型推理步骤(AGENT_RESPONSE、CONTEXT_COMPACTION、MEMORY)的输入/输出/缓存/推理 Token 用量、耗时与状态。 |
| 上下文精简记录(ContextCompaction) | /v1/agent-runtime/project/threads/{threadId}/context-compactions | 用户隔离(userId) | 当会话历史接近上下文预算时,Runtime 自动将早期历史归纳为摘要并保留近期消息,此端点返回上下文精简事件的审计时间线。 |
ReAct 执行循环与流式恢复架构
业务后端持 Project API Key 调用
POST /v1/agent-runtime/project/runs,传入userId、thread_id、user_message与Idempotency-Key。API 校验项目权限和词库停用词规则,冻结配置快照,并返回202 Accepted(run_id、status=QUEUED)。后端通过
GET /v1/agent-runtime/project/runs/{runId}/events?userId=...订阅 SSE。Runtime 加载 Thread 历史、召回 Memory / PowerContext,计算上下文 Token 预算。Runtime 在
max_steps和max_duration_ms限制内循环调用模型,发送提示词、上下文与授权工具 Schema;模型返回回答增量或工具调用请求。服务端工具调用先校验参数 Schema 与可信身份,再执行 Knowledge 检索或 AI Gateway 工具,并持久化
TOOL_RESULT。客户端工具调用则推送TOOL_CALL_START/TOOL_CALL_ARGS/TOOL_CALL_END,Run 进入WAITING_CLIENT_TOOL;应用向/runs/{runId}/tool-messages回传userId、toolCallId、content/error后,同一 Run 经QUEUED恢复为RUNNING。推理期间,Runtime 持续推送带递增事件 ID 的
TEXT_MESSAGE_CONTENT等 SSE 帧。完成后持久化最终ASSISTANT消息与ModelInvocation用量,将 Run 更新为SUCCEEDED,并推送RUN_FINISHED。后端通过
GET /v1/agent-runtime/project/runs/{runId}/messages?userId=...获取持久化消息和知识来源引用。SSE 断线可携带Last-Event-ID续传;断线本身不会取消后台 Run。
Run 生命周期状态机
| 起始状态 | 后续状态 | 触发条件 |
|---|---|---|
| 初始 | SUBMITTING → QUEUED | 登记运行并入队 |
QUEUED | RUNNING | Worker 开始执行 |
RUNNING | WAITING_CLIENT_TOOL | 等待客户端工具结果 |
WAITING_CLIENT_TOOL | QUEUED | 调用 /runs/{runId}/tool-messages 回传结果 |
RUNNING | SUCCEEDED / FAILED | 执行成功或失败,进入终态 |
RUNNING | CANCEL_REQUESTED → CANCELLED | 调用 /runs/{runId}/cancel,等待执行步退出 |
QUEUED / WAITING_CLIENT_TOOL | CANCELLED | 调用 /runs/{runId}/cancel,直接进入取消终态 |
SUCCEEDED、FAILED 和 CANCELLED 均为终态。
| Run 状态 | 状态分类 | 含义说明 | 客户端标准处理动作 |
|---|---|---|---|
SUBMITTING | 进行中 | 任务正在登记与初始化持久化记录 | 继续轮询或等待进入 QUEUED |
QUEUED | 进行中 | 任务已入队等待 Worker 执行(或客户端工具结果回传后重新排队) | 建立或保持 SSE 订阅,切勿重复创建新 Run |
RUNNING | 进行中 | Worker 正在执行模型推理、上下文精简或服务端工具调用 | 实时消费 SSE 事件流;如需终止则显式调用 /cancel |
WAITING_CLIENT_TOOL | 暂停等待 | 模型触发了 source: "CLIENT" 的客户端工具调用,等待应用回传执行结果 | 校验工具名与参数,执行本地获准操作后调用 POST /runs/{runId}/tool-messages 恢复同一 Run |
CANCEL_REQUESTED | 进行中 | 已受理取消请求,正在等待当前执行步安全退出 | 继续观察状态直至收敛为终态 CANCELLED |
SUCCEEDED | 终态 | 任务执行完成且最终回答已持久化 | 停止事件流监听,调用 GET /runs/{runId}/messages 读取最终持久化消息 |
FAILED | 终态 | 任务因模型限流、上下文超限、上游异常或工具失败而终止 | 读取 Run 对象的 error.code 与 error.message 进行排障或提示用户 |
CANCELLED | 终态 | 任务已被显式取消并完成状态收敛 | 保留已有历史记录;注意取消操作不会自动回滚外部工具已产生的业务副作用 |
认证与权限
通用请求头约定见 通用约定。项目级智能体工作台接口采用 Project API Key 认证 + userId 多租户用户隔离 双层安全模型:
请求头与 API Key Scope 矩阵
| 请求头 / 要求项 | 取值示例 | 必填规则与权限边界说明 |
|---|---|---|
X-Appwrite-Project | enterprise-ai-hub-210 | 必填。指定目标项目 ID,不拼接在 URL 路径中。 |
X-Appwrite-Key | <APPBASE_API_KEY> | 必填。属于当前项目的有效 Server API Key(支持标准 Project API Key 与动态 Project Key,仅保存在受控业务后端,严禁下发至浏览器或移动端)。 |
| 必需权限 Scope | agent-runtime.project | 全端点统一要求 agent-runtime.project。涵盖项目 Runtime 初始化、配置读写、词库绑定、AI Gateway 绑定、Skill 管理以及 Thread/Run 执行全生命周期。仅持有 agent-runtime.read、agent-runtime.write 或 agent-runtime.execute 不满足 /v1/agent-runtime/project/* 接口要求。 |
Idempotency-Key | req_zhangwei_20261022_001 | POST /v1/agent-runtime/project/runs 推荐携带(1–128 字节 ASCII 字符串)。同项目、同 userId、同请求体下重放返回原 Run(HTTP 200 + idempotent_replay: true);同 Key 但不同请求体返回 409 IDEMPOTENCY_KEY_CONFLICT。 |
Last-Event-ID | 21 | GET /v1/agent-runtime/project/runs/{runId}/events 断线重连时可选携带,传入上次收到的外层 SSE 帧 id 续传未读事件。 |
内部服务协同鉴权:当智能体工作台在运行期内部调用同一项目下已启用的 Memory、Knowledge Base 或 AI Gateway 时,由平台自动签发内部可信运行上下文完成鉴权,无需给调用方的 Project API Key 额外勾选 Memory 或 Knowledge 的公开 API Scope。
userId 业务用户隔离契约(核心规范)
业务后端使用同一个 Project API Key 即可服务成千上万名业务终端用户(如 user_zhangwei_001、user_lina_002),无需事先在 Agentbase 中为终端用户创建平台 Account:
格式与大小写归一化:
字段名严格为驼峰
userId(不是user_id)。取值必须为 1–128 个 ASCII 字母、数字或下划线(正则:
^[A-Za-z0-9_]{1,128}$),且必须以 JSON 字符串或 Query 字符串传递(纯数字身份须写为"123",拒绝 JSON 数字、数组、对象、null、连字符-、空白或中文字符)。不区分大小写,服务端统一归一化为小写:
"User_ZhangWei_001"与"user_zhangwei_001"指向同一个用户隔离空间。保留字限制:
system(含任意大小写形式如SYSTEM)为平台保留身份,禁止外部传入。
传参位置严格区分(禁止双传):
14 个项目共享配置接口(服务初始化、配置读写、模型列表、词库绑定、AI Gateway 绑定、Skill 技能包管理):不需要也不允许传
userId。13 个用户级会话与运行接口(
/threads、/runs及其全部子资源):每次请求必填userId,其中POST请求必须放在 JSON 请求体(Body)中,GET与DELETE请求必须放在 URL 查询参数(Query)中;严禁同时在 Query 和 Body 中提供userId。
跨用户强隔离语义:
创建 Thread 后,针对该 Thread 及其下属 Run 的所有后续操作(提交 Run、查询状态、订阅 SSE、拉取消息、回传客户端工具结果、取消 Run、归档 Thread)都必须携带与创建时相同的
userId。若传入
user_lina_002访问属于user_zhangwei_001的threadId或runId,服务端统一按404 NOT_FOUND(资源不可见)拒绝,既不泄露资源存在性,也不会篡改资源归属。
端点清单
项目级智能体工作台共提供 27 个 HTTP 端点(含 14 个项目共享配置端点与 13 个用户级会话/运行端点),全量清单如下:
| 分类 | 方法 + 完整路径 | 所需 Scope | userId 要求与位置 | 幂等性 | 成功状态码 | 用途说明 |
|---|---|---|---|---|---|---|
| 服务初始化 | GET /v1/agent-runtime/project | agent-runtime.project | 不需要 | 幂等 | 200 | 查询当前项目 Agent Runtime 是否已初始化(initialized) |
| 服务初始化 | POST /v1/agent-runtime/project | agent-runtime.project | 不需要 | 幂等 | 200 | 显式初始化当前项目 Agent Runtime(重复调用不清空配置) |
| 项目配置 | GET /v1/agent-runtime/project/config | agent-runtime.project | 不需要 | 幂等 | 200 | 读取当前项目智能体配置与只读 config_hash |
| 项目配置 | PATCH /v1/agent-runtime/project/config | agent-runtime.project | 不需要 | 条件幂等 | 200 | 稀疏更新项目智能体配置(模型、提示词、预算、Memory/PowerContext/Knowledge 开关) |
| 模型目录 | GET /v1/agent-runtime/project/models | agent-runtime.project | 不需要 | 幂等 | 200 | 列出当前项目可供智能体工作台使用的模型及能力标签(chat / embedding) |
| 词库绑定 | GET /v1/agent-runtime/project/lexicons | agent-runtime.project | 不需要 | 幂等 | 200 | 读取当前项目智能体工作台绑定的词库列表与停用词阻断策略 |
| 词库绑定 | PUT /v1/agent-runtime/project/lexicons | agent-runtime.project | 不需要 | 幂等 | 200 | 全量设置智能体工作台绑定的词库优先级列表、enabled、stopIntercept 与 stopReply |
| AI Gateway | GET /v1/agent-runtime/project/gateway | agent-runtime.project | 不需要 | 幂等 | 200 | 读取当前项目智能体工作台绑定的 AI Gateway(gateway_id) |
| AI Gateway | PUT /v1/agent-runtime/project/gateway | agent-runtime.project | 不需要 | 幂等 | 200 | 绑定或切换同项目下处于 ACTIVE 且有可用快照的 AI Gateway |
| Skill 管理 | GET /v1/agent-runtime/project/skills | agent-runtime.project | 不需要 | 幂等 | 200 | 列出当前项目已上传的 Skill 包及容量配额(skill_count / skill_limit) |
| Skill 管理 | POST /v1/agent-runtime/project/skills | agent-runtime.project | 不需要 | 非幂等 | 201 | 通过 multipart/form-data 上传新 Skill 归档包(.zip / .tar.gz / .tgz) |
| Skill 管理 | GET /v1/agent-runtime/project/skills/{skillId} | agent-runtime.project | 不需要 | 幂等 | 200 | 读取指定 Skill 包的元数据、front_matter 与 content_hash |
| Skill 管理 | PUT /v1/agent-runtime/project/skills/{skillId} | agent-runtime.project | 不需要 | 幂等 | 200 | 上传新归档包全量替换指定 skillId 的内容 |
| Skill 管理 | DELETE /v1/agent-runtime/project/skills/{skillId} | agent-runtime.project | 不需要 | 幂等 | 204 | 删除指定 skillId 技能包 |
| 会话管理 | POST /v1/agent-runtime/project/threads | agent-runtime.project | 必填(JSON Body) | 非幂等 | 201 | 为指定 userId 创建新的连续对话 Thread |
| 会话管理 | GET /v1/agent-runtime/project/threads | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 按更新时间倒序列出指定 userId 的会话列表(支持 limit) |
| 会话管理 | GET /v1/agent-runtime/project/threads/{threadId} | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 查询指定 userId 下单个 Thread 的状态与标题 |
| 会话管理 | DELETE /v1/agent-runtime/project/threads/{threadId} | agent-runtime.project | 必填(URL Query) | 幂等 | 204 | 归档指定 userId 的 Thread(状态置为 ARCHIVED,不删除长期记忆) |
| 会话历史 | GET /v1/agent-runtime/project/threads/{threadId}/messages | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 按 after(message_seq)与 limit 游标分页读取会话持久化消息 |
| 会话历史 | GET /v1/agent-runtime/project/threads/{threadId}/context-compactions | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 读取会话的上下文自动精简(Compaction)事件记录 |
| 运行管理 | POST /v1/agent-runtime/project/runs | agent-runtime.project | 必填(JSON Body) | 幂等(需 Idempotency-Key) | 202(重放 200) | 在指定 Thread 内提交用户消息并异步启动一次 ReAct Run |
| 运行管理 | GET /v1/agent-runtime/project/runs/{runId} | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 查询指定 runId 的当前运行状态与错误详情 |
| 运行管理 | POST /v1/agent-runtime/project/runs/{runId}/cancel | agent-runtime.project | 必填(JSON Body) | 幂等 | 202 或 200 | 显式请求取消正在排队、运行或等待客户端工具的 Run |
| 流式事件 | GET /v1/agent-runtime/project/runs/{runId}/events | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 订阅 AG-UI 协议 SSE 增量事件流,支持 Last-Event-ID 断线续连 |
| 运行消息 | GET /v1/agent-runtime/project/runs/{runId}/messages | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 按 after(message_seq)与 limit 读取单次 Run 产生的持久化消息 |
| 客户端工具 | POST /v1/agent-runtime/project/runs/{runId}/tool-messages | agent-runtime.project | 必填(JSON Body) | 幂等(复用 id) | 202 | 向处于 WAITING_CLIENT_TOOL 的 Run 回传客户端工具结果以继续执行 |
| 模型用量 | GET /v1/agent-runtime/project/runs/{runId}/model-invocations | agent-runtime.project | 必填(URL Query) | 幂等 | 200 | 读取单次 Run 各推理步的模型调用详情、Token 消耗与耗时记录 |
请求与响应
以下按业务接入顺序逐端点给出完整的输入参数表、输出 Schema、可执行 curl 示例与真实 HTTP 响应示例。
1. 服务状态与初始化
1.1 查询服务初始化状态:GET /v1/agent-runtime/project
权限 Scope:
agent-runtime.project用户参数:不需要
userId(作用于项目共享资源)。输出 Schema(
State):{ "initialized": boolean }。当返回false时,必须先调用POST /v1/agent-runtime/project完成初始化。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"initialized": true
}1.2 初始化项目智能体工作台:POST /v1/agent-runtime/project
权限 Scope:
agent-runtime.project用户参数:不需要
userId。请求体:空 JSON 对象
{}。重复调用保持幂等,不会重置或清空已有配置。
调用示例:
curl --request POST \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{}'响应示例(200 OK):
{
"initialized": true
}2. 项目配置与可用模型目录
2.1 列出项目可用模型:GET /v1/agent-runtime/project/models
权限 Scope:
agent-runtime.project用户参数:不需要
userId。输出 Schema(
ModelList):包含models数组,每项含model_id(字符串)与capabilities(能力数组,如["chat"]、["embedding"])。智能体主对话模型应选择具备chat能力的模型(如qwen-plus、qwen-turbo)。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/models' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"models": [
{
"model_id": "qwen-plus",
"capabilities": [
"chat"
]
},
{
"model_id": "qwen-turbo",
"capabilities": [
"chat"
]
},
{
"model_id": "text-embedding-v3",
"capabilities": [
"embedding"
]
}
]
}2.2 读取项目智能体配置:GET /v1/agent-runtime/project/config
权限 Scope:
agent-runtime.project用户参数:不需要
userId。输出 Schema(
Config):返回完整配置字段及只读配置摘要config_hash。尚未配置的字段可能返回null,客户端应按“未配置”处理而非数值0。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/config' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"system_prompt": "你是企业智能客服与知识中台助手,请优先检索企业知识库回答问题,保留引用来源。",
"model_id": "qwen-plus",
"model_parameters": {
"temperature": 0.3,
"top_p": 0.9
},
"context_window_tokens": 32768,
"reserved_output_tokens": 2048,
"max_steps": 12,
"max_duration_ms": 120000,
"memory_enabled": true,
"powercontext_enabled": false,
"knowledge_search_enabled": true,
"knowledge_base_ids": [
"kb_enterprise_support"
],
"memory_embedding_model_id": "text-embedding-v3",
"memory_embedding_dimensions": 1024,
"config_hash": "8f9d2a7e4b1c6f03981e2d5c4a7b8e9f"
}2.3 稀疏更新项目智能体配置:PATCH /v1/agent-runtime/project/config
权限 Scope:
agent-runtime.project用户参数:不需要
userId。更新语义:首次保存可执行配置时,必须补齐
model_id、model_parameters、context_window_tokens、reserved_output_tokens、max_steps与max_duration_ms。后续PATCH仅需发送变更字段;注意model_parameters按整个对象替换而非逐键合并。服务端内部自动基于最新config_hash进行并发控制,若并发修改冲突将返回409 STATE_CONFLICT。
请求体参数表(ConfigPatch):
| 字段名 | 类型 | 必填 | 约束与业务语义 |
|---|---|---|---|
system_prompt | string | null | 否 | 系统提示词(0–200,000 字符);传空串或 null 使用平台默认行为。 |
model_id | string | 首次必填 | 项目内具备 chat 能力的模型 ID(如 qwen-plus)。 |
model_parameters | object | null | 首次必填 | 仅允许 temperature(0–1)与 top_p(0–1);传 {} 或 null 清除显式采样参数。 |
context_window_tokens | integer | 首次必填 | 上下文窗口总 Token 数(> 0,如 32768、65536)。 |
reserved_output_tokens | integer | 首次必填 | 预留给模型输出的 Token 预算(> 0 且必须小于 context_window_tokens)。 |
max_steps | integer | 首次必填 | 单次 Run 允许的最大 ReAct 推理步数(> 0,如 12)。 |
max_duration_ms | integer | 首次必填 | 单次 Run 允许的最大执行时长(毫秒,> 0,如 120000)。 |
memory_enabled | boolean | 否 | 是否启用项目长期记忆(需先在项目中初始化并启用 Memory 服务;与 powercontext_enabled 严格互斥)。 |
powercontext_enabled | boolean | 否 | 是否启用托管 PowerContext(需 Shared V2 项目先初始化 PowerContext 至 ready 状态;开启时自动关闭 memory_enabled,同一请求同时将两者设为 true 返回 400)。 |
knowledge_search_enabled | boolean | 否 | 是否启用企业知识库检索工具(knowledge_retrieve)。新开启时必须同时指定至少 1 个 knowledge_base_ids。 |
knowledge_base_ids | string[] | 条件必填 | 允许检索的本项目知识库 ID 数组(最多 100 个不重复有效 ID,如 ["kb_enterprise_support"])。 |
memory_embedding_model_id | string | null | 否 | Memory 使用的 Embedding 模型 ID(如 text-embedding-v3)。 |
memory_embedding_dimensions | integer | null | 否 | Memory 使用的 Embedding 向量维度(> 0,如 1024,须与项目 Memory 配置一致)。 |
调用示例:
curl --request PATCH \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/config' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"system_prompt": "你是企业智能客服与知识中台助手,请优先检索企业知识库回答问题,保留引用来源。",
"model_id": "qwen-plus",
"model_parameters": {
"temperature": 0.3,
"top_p": 0.9
},
"context_window_tokens": 32768,
"reserved_output_tokens": 2048,
"max_steps": 12,
"max_duration_ms": 120000,
"memory_enabled": true,
"powercontext_enabled": false,
"knowledge_search_enabled": true,
"knowledge_base_ids": [
"kb_enterprise_support"
],
"memory_embedding_model_id": "text-embedding-v3",
"memory_embedding_dimensions": 1024
}'响应示例(200 OK):
{
"system_prompt": "你是企业智能客服与知识中台助手,请优先检索企业知识库回答问题,保留引用来源。",
"model_id": "qwen-plus",
"model_parameters": {
"temperature": 0.3,
"top_p": 0.9
},
"context_window_tokens": 32768,
"reserved_output_tokens": 2048,
"max_steps": 12,
"max_duration_ms": 120000,
"memory_enabled": true,
"powercontext_enabled": false,
"knowledge_search_enabled": true,
"knowledge_base_ids": [
"kb_enterprise_support"
],
"memory_embedding_model_id": "text-embedding-v3",
"memory_embedding_dimensions": 1024,
"config_hash": "9c4e1b2d5a8f70316e9d4c2b1a0f8e7d"
}3. 项目词库绑定与停用词阻断(Lexicons)
智能体工作台支持绑定当前项目下的业务词库(同义词 synonym、扩展词 expansion、停用词 stop),在对话检索改写与输入合规拦截阶段生效。
3.1 读取绑定的词库配置:GET /v1/agent-runtime/project/lexicons
权限 Scope:
agent-runtime.project用户参数:不需要
userId。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/lexicons' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"enabled": true,
"stopIntercept": true,
"stopReply": "您好,您咨询的内容涉及企业受限或违规词条,当前请求已被拦截,请联系人工客服处理。",
"bindings": [
{
"lexiconId": "lex_enterprise_synonyms",
"priority": 1
},
{
"lexiconId": "lex_support_stopwords",
"priority": 2
}
]
}3.2 更新绑定的词库配置:PUT /v1/agent-runtime/project/lexicons
权限 Scope:
agent-runtime.project用户参数:不需要
userId。请求体参数表(
LexiconBindingsInput):
| 字段名 | 类型 | 必填 | 默认值 | 约束与业务语义 |
|---|---|---|---|---|
bindings | array | 是 | [] | 有序词库绑定数组(最多 100 项,禁止重复 lexiconId)。每项严格为 {"lexiconId": string, "priority": integer},其中 priority 为 0–2147483647 的整数,数值越小优先级越高。 |
enabled | boolean | 否 | false | 是否启用已绑定的词库规则。 |
stopIntercept | boolean | 否 | true | 当用户输入命中词库中的 stop(停用词)词条时,是否立即短路阻断本次 Run。 |
stopReply | string | 否 | "" | 触发停用词短路阻断时直接返回的预设合规话术(最长 4096 字符)。 |
调用示例:
curl --request PUT \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/lexicons' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"enabled": true,
"stopIntercept": true,
"stopReply": "您好,您咨询的内容涉及企业受限或违规词条,当前请求已被拦截,请联系人工客服处理。",
"bindings": [
{
"lexiconId": "lex_enterprise_synonyms",
"priority": 1
},
{
"lexiconId": "lex_support_stopwords",
"priority": 2
}
]
}'响应示例(200 OK):
{
"enabled": true,
"stopIntercept": true,
"stopReply": "您好,您咨询的内容涉及企业受限或违规词条,当前请求已被拦截,请联系人工客服处理。",
"bindings": [
{
"lexiconId": "lex_enterprise_synonyms",
"priority": 1
},
{
"lexiconId": "lex_support_stopwords",
"priority": 2
}
]
}4. AI Gateway 绑定
AI Gateway 绑定要求当前项目为 Shared V2 存储模式且目标 Gateway 处于 ACTIVE 状态、拥有当前地域已发布的可用快照。
4.1 读取已绑定的 AI Gateway:GET /v1/agent-runtime/project/gateway
权限 Scope:
agent-runtime.project用户参数:不需要
userId。尚未绑定时返回404 NOT_FOUND。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/gateway' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"gateway_id": "gw_7194685489feb1e169548619",
"created_at": "2026-10-22T08:00:00Z"
}4.2 绑定或切换 AI Gateway:PUT /v1/agent-runtime/project/gateway
权限 Scope:
agent-runtime.project用户参数:不需要
userId。请求体:
{ "gateway_id": "gw_7194685489feb1e169548619" }(必填 string;不支持传空字符串解绑,可通过再次PUT切换至其他有效 Gateway)。
调用示例:
curl --request PUT \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/gateway' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"gateway_id": "gw_7194685489feb1e169548619"
}'响应示例(200 OK):
{
"gateway_id": "gw_7194685489feb1e169548619",
"created_at": "2026-10-22T08:00:00Z"
}5. Skill 技能包管理
Skill 归档包支持 .zip、.tar.gz 或 .tgz 格式,单包不超过 10 MiB,根目录必须包含带 YAML Front Matter(name: 1–64 位小写字母/数字/单连字符;description: 1–1024 字符)的 SKILL.md。
5.1 上传 Skill 包:POST /v1/agent-runtime/project/skills
权限 Scope:
agent-runtime.project用户参数:不需要
userId。请求格式:
multipart/form-data,必填二进制文件字段file。
调用示例:
curl --request POST \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/skills' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--form 'file=@./enterprise-order-sop.zip'响应示例(201 Created):
{
"skill_id": "skill_order_sop_01",
"name": "enterprise-order-sop",
"description": "企业订单查询、异常催单与退换货标准处理流程规范。",
"front_matter": {
"name": "enterprise-order-sop",
"description": "企业订单查询、异常催单与退换货标准处理流程规范。"
},
"content_hash": "sha256:4a8b9c1d2e3f5a6b7c8d9e0f1a2b3c4d",
"created_by": "api_key_enterprise",
"created_at": "2026-10-22T08:05:00Z",
"updated_at": "2026-10-22T08:05:00Z"
}5.2 列出项目 Skill 包:GET /v1/agent-runtime/project/skills
权限 Scope:
agent-runtime.project用户参数:不需要
userId。输出 Schema(
SkillList):返回items数组、目录摘要skill_catalog_hash、当前已上传数量skill_count及项目配额上限skill_limit。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/skills' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"items": [
{
"skill_id": "skill_order_sop_01",
"name": "enterprise-order-sop",
"description": "企业订单查询、异常催单与退换货标准处理流程规范。",
"front_matter": {
"name": "enterprise-order-sop",
"description": "企业订单查询、异常催单与退换货标准处理流程规范。"
},
"content_hash": "sha256:4a8b9c1d2e3f5a6b7c8d9e0f1a2b3c4d",
"created_by": "api_key_enterprise",
"created_at": "2026-10-22T08:05:00Z",
"updated_at": "2026-10-22T08:05:00Z"
}
],
"skill_catalog_hash": "cat_9f8e7d6c5b4a3210",
"skill_count": 1,
"skill_limit": 10
}5.3 读取单个 Skill 元数据:GET /v1/agent-runtime/project/skills/{skillId}
权限 Scope:
agent-runtime.project用户参数:不需要
userId。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/skills/skill_order_sop_01' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):返回与上传响应相同的 Skill JSON 对象(不含二进制压缩包流)。
5.4 替换 Skill 包:PUT /v1/agent-runtime/project/skills/{skillId}
权限 Scope:
agent-runtime.project用户参数:不需要
userId。请求格式:
multipart/form-data,必填二进制文件字段file。
调用示例:
curl --request PUT \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/skills/skill_order_sop_01' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--form 'file=@./enterprise-order-sop-v2.zip'响应示例(200 OK):返回更新后的 Skill JSON 对象(content_hash 与 updated_at 刷新)。
5.5 删除 Skill 包:DELETE /v1/agent-runtime/project/skills/{skillId}
权限 Scope:
agent-runtime.project用户参数:不需要
userId。
调用示例:
curl --request DELETE \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/skills/skill_order_sop_01' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例:HTTP/1.1 204 No Content(无响应体)。
6. 会话(Thread)管理与历史读取
6.1 创建会话:POST /v1/agent-runtime/project/threads
权限 Scope:
agent-runtime.project用户参数:
userId必填(JSON Body),指定新会话归属的业务终端用户。
调用示例:
curl --request POST \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/threads' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"userId": "user_zhangwei_001"
}'响应示例(201 Created):
{
"thread_id": "th_01ja9x8k2m4n6p8q0r2s4t6v8w",
"title": null,
"status": "ACTIVE"
}6.2 列出用户会话:GET /v1/agent-runtime/project/threads
权限 Scope:
agent-runtime.projectQuery 参数:
userId(string,必填):目标业务用户 ID(仅返回该用户自己的会话)。limit(integer,可选,默认100,取值范围1–1000):按最近更新时间倒序返回的最大会话条数。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/threads?userId=user_zhangwei_001&limit=50' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
[
{
"thread_id": "th_01ja9x8k2m4n6p8q0r2s4t6v8w",
"title": "专票开具与订单发货咨询",
"status": "ACTIVE"
}
]6.3 查询单个会话:GET /v1/agent-runtime/project/threads/{threadId}
权限 Scope:
agent-runtime.project路径参数:
threadId(必填)。Query 参数:
userId(string,必填,必须与创建该 Thread 的用户一致)。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/threads/th_01ja9x8k2m4n6p8q0r2s4t6v8w?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"thread_id": "th_01ja9x8k2m4n6p8q0r2s4t6v8w",
"title": "专票开具与订单发货咨询",
"status": "ACTIVE"
}6.4 归档会话:DELETE /v1/agent-runtime/project/threads/{threadId}
权限 Scope:
agent-runtime.project路径参数:
threadId(必填)。Query 参数:
userId(string,必填)。行为说明:将会话状态变更为
ARCHIVED,成功返回204 No Content。若会话仍有未结束的 Run,应先等待其结束或调用取消接口;归档会话不会删除该用户在 Memory 或 PowerContext 中的长期记忆。
调用示例:
curl --request DELETE \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/threads/th_01ja9x8k2m4n6p8q0r2s4t6v8w?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例:HTTP/1.1 204 No Content。
6.5 读取会话持久化消息:GET /v1/agent-runtime/project/threads/{threadId}/messages
权限 Scope:
agent-runtime.projectQuery 参数:
userId(string,必填):会话所属用户 ID。after(integer,可选,默认0):会话内递增消息序号message_seq游标;翻下一页时传上一页最后一条消息的message_seq(不可与 SSE 的事件id混用)。limit(integer,可选,默认100,范围1–1000):单页返回条数。
消息对象(Message)字段说明:
| 字段名 | 类型 | 含义说明 |
|---|---|---|
message_id | string | 消息唯一标识 |
thread_id | string | 所属会话 ID |
run_id | string | 产生该消息的 Run ID |
trace_id | string(可选) | 关联的 Observability Trace ID |
message_seq | integer | 会话内严格递增的消息序号(用于 after 游标翻页与客户端去重) |
message_type | string | 枚举:USER、ASSISTANT、TOOL_CALL、TOOL_RESULT |
payload | string | object | USER 与 ASSISTANT 消息为纯字符串文本;TOOL_CALL 与 TOOL_RESULT 为结构化 JSON 对象 |
tool_call_id | string | null | 工具调用关联 ID(普通文本消息为 null) |
created_at | string | RFC 3339 UTC 创建时间 |
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/threads/th_01ja9x8k2m4n6p8q0r2s4t6v8w/messages?userId=user_zhangwei_001&after=0&limit=100' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
[
{
"message_id": "msg_01ja9x9a1b2c3d4e5f6g7h8j9k",
"thread_id": "th_01ja9x8k2m4n6p8q0r2s4t6v8w",
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"message_seq": 1,
"message_type": "USER",
"payload": "请帮我查询订单 ORD-20261022-889 的发货状态,并说明跨月退货如何处理增值税专用发票。",
"tool_call_id": null,
"created_at": "2026-10-22T08:10:00Z"
},
{
"message_id": "msg_01ja9x9f9e8d7c6b5a4f3e2d1c",
"thread_id": "th_01ja9x8k2m4n6p8q0r2s4t6v8w",
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"message_seq": 4,
"message_type": "ASSISTANT",
"payload": "订单 ORD-20261022-889 已通过顺丰发出。若跨月发生退货且增值税专用发票已认证抵扣,需由购买方在税务系统填开《开具红字增值税专用发票信息表》,审核通过后方可开具红字发票。",
"tool_call_id": null,
"created_at": "2026-10-22T08:10:04Z"
}
]6.6 读取会话上下文精简记录:GET /v1/agent-runtime/project/threads/{threadId}/context-compactions
权限 Scope:
agent-runtime.projectQuery 参数:
userId(string,必填)。最多返回 1000 条上下文精简与运行边界事件(CONTEXT_COMPACTION_STARTED、CONTEXT_COMPACTION_COMPLETED、CONTEXT_COMPACTION_FAILED、RUN_FINISHED、RUN_ERROR)。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/threads/th_01ja9x8k2m4n6p8q0r2s4t6v8w/context-compactions?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"items": [
{
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"event_seq": 12,
"type": "CONTEXT_COMPACTION_COMPLETED",
"payload": [],
"created_at": "2026-10-22T08:10:02Z"
}
]
}7. 运行(Run)提交、流式订阅、客户端工具回传与模型调用记录
7.1 创建并异步提交 Run:POST /v1/agent-runtime/project/runs
权限 Scope:
agent-runtime.project请求头:可携带
Idempotency-Key(1–128 字节)。请求体参数表(
CreateRun):
| 字段名 | 类型 | 必填 | 约束与说明 |
|---|---|---|---|
userId | string | 是 | 必须与目标 thread_id 所属的业务用户 ID 完全一致(忽略大小写)。 |
thread_id | string | 是 | 目标会话 ID。同一 Thread 下不能存在未结束的活动 Run,否则返回 409 THREAD_BUSY。 |
user_message | string | 是 | 本轮用户输入的非空文本消息。 |
调用示例:
curl --request POST \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Idempotency-Key: req_zhangwei_20261022_001' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"userId": "user_zhangwei_001",
"thread_id": "th_01ja9x8k2m4n6p8q0r2s4t6v8w",
"user_message": "请帮我查询订单 ORD-20261022-889 的发货状态,并说明跨月退货如何处理增值税专用发票。"
}'首次受理响应示例(202 Accepted):
{
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"status": "QUEUED",
"created_at": "2026-10-22T08:10:00Z"
}相同 Idempotency-Key 与相同请求体重放响应示例(200 OK):
{
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"status": "RUNNING",
"created_at": "2026-10-22T08:10:00Z",
"idempotent_replay": true
}7.2 查询 Run 状态:GET /v1/agent-runtime/project/runs/{runId}
权限 Scope:
agent-runtime.projectQuery 参数:
userId(string,必填)。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"status": "SUCCEEDED",
"created_at": "2026-10-22T08:10:00Z"
}7.3 订阅可恢复 SSE 事件流:GET /v1/agent-runtime/project/runs/{runId}/events
权限 Scope:
agent-runtime.projectQuery 参数:
userId(string,必填)。请求头:
Accept: text/event-stream;断线重连时携带Last-Event-ID: <上次收到的外层帧 id>。
SSE 事件类型(AG-UI 协议)全集表:
事件 type | data JSON 核心字段 | 客户端处理语义 |
|---|---|---|
RUN_STARTED | runId, threadId | 标记当前 Run 开始执行 |
TEXT_MESSAGE_START | messageId, role: "assistant" | 初始化一条助手回答消息容器 |
TEXT_MESSAGE_CONTENT | messageId, delta: string | 按 messageId 追加流式回答文本片段 |
TEXT_MESSAGE_END | messageId | 当前段落文本输出完毕(不代表整次 Run 结束) |
REASONING_START / REASONING_END / REASONING_MESSAGE_END | messageId | 维护模型思考推理过程的展示状态边界 |
REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENT | messageId, role: "reasoning", delta: string | 展示模型流式思考片段 |
TOOL_CALL_START | toolCallId, toolCallName, toolCallSource | 记录工具调用开始(toolCallSource 为 "CLIENT" 或服务端工具来源) |
TOOL_CALL_ARGS | toolCallId, toolCallSource, delta: string | 按 toolCallId 拼接工具调用参数 JSON 片段(非客户端工具可能脱敏为 {"redacted":true}) |
TOOL_CALL_END | toolCallId, toolCallSource | 工具参数传输完毕;若 toolCallSource === "CLIENT",查询 Run 状态确认进入 WAITING_CLIENT_TOOL 后执行本地工具并回传 |
TOOL_CALL_RESULT | toolCallId, messageId, role: "tool", content | 工具结果已记录(默认通知摘要为 {"status":"completed"},完整结构化结果通过消息接口读取) |
RUN_FINISHED | runId, threadId | Run 正常完成,随后读取 Run 终态与持久化消息 |
RUN_ERROR | runId, threadId, message, code(可选) | Run 执行出错或被取消(如 code: "RUN_CANCELLED"),读取 Run 状态确认终态 |
CUSTOM | name, value: object | 平台扩展事件:appbase.context.compaction(上下文精简)、appbase.run.cancelled(取消通知)、appbase.stream.attempt_aborted(Worker 故障切换丢弃临时输出尝试,客户端应按持久化消息校准界面) |
首次连接与断线续传调用示例:
# 首次订阅事件流
curl --request GET -N \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9/events?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Accept: text/event-stream'
# 断线后携带 Last-Event-ID 续传同一 Run
curl --request GET -N \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9/events?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Accept: text/event-stream' \
--header 'Last-Event-ID: 20'SSE 响应流示例(200 OK):
id: 21
event: TEXT_MESSAGE_CONTENT
data: {"type":"TEXT_MESSAGE_CONTENT","timestamp":1792656603000,"messageId":"msg_01ja9x9f9e8d7c6b5a4f3e2d1c","delta":"订单 ORD-20261022-889 已通过顺丰发出。"}
id: 22
event: RUN_FINISHED
data: {"type":"RUN_FINISHED","timestamp":1792656604000,"runId":"run_01ja9x90a1b2c3d4e5f6g7h8j9","threadId":"th_01ja9x8k2m4n6p8q0r2s4t6v8w"}7.4 回传客户端工具结果:POST /v1/agent-runtime/project/runs/{runId}/tool-messages
当 Run 因触发 CLIENT 工具暂停在 WAITING_CLIENT_TOOL 状态时,业务端执行本地获准逻辑并调用本接口回传结果,继续同一个 Run。
权限 Scope:
agent-runtime.project请求体参数表(
ToolMessage):
| 字段名 | 类型 | 必填 | 约束与说明 |
|---|---|---|---|
userId | string | 是 | 必须与当前 Run 所属的业务用户 ID 一致。 |
id | string | 是 | 客户端生成的工具消息唯一标识(重试同一次回传时保持不变)。 |
role | string | 是 | 固定为 "tool"。 |
toolCallId | string | 是 | 对应 TOOL_CALL_START / TOOL_CALL_END 事件中的 toolCallId。 |
content | string | 是 | JSON 序列化后的字符串(注意:必须是 string,如 "{\"order_id\":\"ORD-20261022-889\",\"status\":\"shipped\"}",不能直接传 JSON 对象;失败回传时可传 "{}")。若工具在 Gateway 中声明了 outputSchema,成功结果将按该 Schema 校验。 |
error | string | 否 | 当本地工具执行失败时填写错误原因说明,让模型感知失败并继续决策。 |
调用示例(成功回传):
curl --request POST \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9/tool-messages' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"userId": "user_zhangwei_001",
"id": "tmsg_01ja9x9c4d5e6f7g8h9j0k1l2m",
"role": "tool",
"toolCallId": "call_order_lookup_001",
"content": "{\"order_id\":\"ORD-20261022-889\",\"status\":\"shipped\",\"carrier\":\"SF-Express\"}"
}'响应示例(202 Accepted):
{
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"status": "QUEUED",
"created_at": "2026-10-22T08:10:00Z"
}7.5 取消 Run:POST /v1/agent-runtime/project/runs/{runId}/cancel
权限 Scope:
agent-runtime.project请求体:
{ "userId": "user_zhangwei_001" }(必填)。行为说明:断开 SSE 不会取消后台 Run,必须显式调用此接口。受理后返回
202 Accepted(状态CANCEL_REQUESTED),若已处于终态则返回200 OK。
调用示例:
curl --request POST \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9/cancel' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"userId": "user_zhangwei_001"
}'响应示例(202 Accepted):
{
"run_id": "run_01ja9x90a1b2c3d4e5f6g7h8j9",
"status": "CANCEL_REQUESTED",
"created_at": "2026-10-22T08:10:00Z"
}7.6 读取单次 Run 的持久化消息:GET /v1/agent-runtime/project/runs/{runId}/messages
权限 Scope:
agent-runtime.projectQuery 参数:
userId(必填)、after(可选,默认0)、limit(可选,默认100)。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9/messages?userId=user_zhangwei_001&after=0&limit=100' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):返回与 GET /threads/{threadId}/messages 相同结构的 Message[] 数组,仅包含本次 runId 产生的消息(含 TOOL_CALL、TOOL_RESULT 中的知识库检索片段与最终 ASSISTANT 回答)。
7.7 读取单次 Run 的模型调用记录:GET /v1/agent-runtime/project/runs/{runId}/model-invocations
权限 Scope:
agent-runtime.projectQuery 参数:
userId(string,必填)。
调用示例:
curl --request GET \
'https://appbuild-sit.oceanbase.com/v1/agent-runtime/project/runs/run_01ja9x90a1b2c3d4e5f6g7h8j9/model-invocations?userId=user_zhangwei_001' \
--header 'X-Appwrite-Project: enterprise-ai-hub-210' \
--header 'X-Appwrite-Key: <APPBASE_API_KEY>'响应示例(200 OK):
{
"items": [
{
"invocation_id": "inv_01ja9x92b3c4d5e6f7g8h9j0k1",
"model_step": 1,
"purpose": "AGENT_RESPONSE",
"attempt": 1,
"model_id": "qwen-plus",
"input_tokens": 1420,
"output_tokens": 215,
"cached_tokens": 0,
"reasoning_tokens": null,
"provider_usage_available": true,
"provider_request_id": "chatcmpl-9f8e7d6c-dashscope",
"duration_ms": 1580,
"status": "SUCCEEDED",
"started_at": "2026-10-22T08:10:01Z",
"finished_at": "2026-10-22T08:10:02.580Z"
}
]
}错误与边界
错误响应结构
项目级智能体工作台接口可能返回两类错误结构,客户端应同时兼容:
Runtime 领域错误(
RuntimeError):
{
"error": {
"code": "THREAD_BUSY",
"message": "thread has an open run"
},
"request_id": "req_01ja9x9z8y7x6w5v4u3t2s1r0q"
}平台网关层错误(
PlatformError)(在 API Key 鉴权、Scope 校验、参数格式校验阶段触发):
{
"message": "Invalid `userId` param: Value must be a valid string of 1 to 128 alphanumeric or underscore characters.",
"code": 400,
"type": "general_argument_invalid",
"version": "2.10.0"
}SSE 游标过期错误(HTTP
409):当Last-Event-ID早于 Redis 事件流保留窗口(默认 Run deadline 后保留 30 分钟,单 Run 最多约 8192 条事件)时返回:
{
"code": "stream_cursor_expired",
"earliest_event_id": 300,
"latest_event_id": 650
}常见状态码与业务错误码排障表
| HTTP 状态 / 出现位置 | 错误码(error.code / type / code) | 触发原因 | 客户端标准恢复与排障策略 |
|---|---|---|---|
400 Bad Request | general_argument_invalid / INVALID_REQUEST | 缺失或非法 userId(如含连字符 -、传了 system、放错 Query/Body 位置或双传);或 memory_enabled 与 powercontext_enabled 同时设为 true;或启用知识检索但未选择 knowledge_base_ids。 | 核对 userId 正则(^[A-Za-z0-9_]{1,128}$)与传参位置(POST 放 Body,GET/DELETE 放 Query);核对配置互斥与知识库非空约束。 |
401 / 403 | user_unauthorized / general_access_forbidden | X-Appwrite-Project 与 API Key 不匹配,或 API Key 缺少 agent-runtime.project Scope。 | 在控制台为当前项目的 API Key 勾选 agent-runtime.project 权限 Scope。 |
404 Not Found | NOT_FOUND / lexicon_not_found | threadId、runId、skillId 不存在,或传入的 userId 与创建该 Thread/Run 的用户不一致,或尚未绑定 AI Gateway。 | 核对资源 ID 与所属 userId 是否一致;跨用户访问一律按未找到拒绝。 |
409 Conflict | STATE_CONFLICT | 项目 Agent Runtime 尚未初始化即调用业务接口,或多人并发更新 /config 发生 config_hash 乐观锁冲突。 | 先调用 POST /v1/agent-runtime/project 初始化;配置冲突时重新 GET /config 后合并变更重试。 |
409 Conflict | THREAD_BUSY | 目标 thread_id 当前已有处于 SUBMITTING、QUEUED、RUNNING、WAITING_CLIENT_TOOL 或 CANCEL_REQUESTED 的活动 Run。 | 继续订阅或轮询既有活动 Run;若正在等待客户端工具则回传 tool-messages;确需放弃旧任务时先调用 /cancel 等待终态。 |
409 Conflict | IDEMPOTENCY_KEY_CONFLICT | 使用相同的 Idempotency-Key 提交了不同的 thread_id、userId 或 user_message。 | 重试同一次提交必须保持请求体完全一致;发起新问题时必须生成新的 Idempotency-Key。 |
409 Conflict | stream_cursor_expired | 断线重连携带的 Last-Event-ID 已滑出有界事件流缓存窗口。 | 先调用 GET /runs/{runId} 与 GET /runs/{runId}/messages 恢复已持久化的状态与消息,若 Run 仍在运行可从 earliest_event_id - 1 重新订阅,切勿新建重复 Run。 |
Run FAILED | MODEL_RATE_LIMITED | 上游模型供应商(如 DashScope)触发 TPM / RPM 限流。 | 检查模型供应商配额与并发度,采用指数退避后按需发起新 Run。 |
Run FAILED | MODEL_UPSTREAM_FAILED | 上游模型调用超时、凭证失效或返回异常。 | 查看 GET /runs/{runId}/model-invocations 中的 provider_request_id 与错误详情,排查 LLM Provider 连通性。 |
Run FAILED | CONTEXT_BUDGET_EXCEEDED / CONTEXT_PREPARE_FAILED / CONTEXT_FRESH_TAIL_TOO_LARGE | 单次用户输入、工具定义或近期未压缩消息超出了 context_window_tokens - reserved_output_tokens 的输入预算。 | 调大 context_window_tokens、合理缩减 reserved_output_tokens,或精简单轮输入与挂载工具数量。 |
Run FAILED | RUN_DEADLINE_EXCEEDED | 单次 Run 总执行时间超过了配置中的 max_duration_ms。 | 排查慢工具调用耗时,或在 PATCH /config 中适当上调 max_duration_ms。 |
Run FAILED | TOOL_RESULT_UNKNOWN | 外部工具调用在执行期间发生网络中断或进程重启,无法确认外部写操作是否已生效。 | 严禁盲目自动重做有副作用的工具调用;应先查询外部业务系统真实状态,确认后再决定后续动作。 |
503 Service Unavailable | RUN_ADMISSION_DISABLED | 实例正在维护或暂停接收新 Run。 | 保留原 Idempotency-Key 延迟退避重试。 |
与 Server SDK 的对应
项目级智能体工作台接口(/v1/agent-runtime/project/*)在服务端架构中直接面向项目的 HTTP 接入层设计:在 Node.js(agentbase-node-sdk@2.10.0)、Python(agentbase-python-sdk==2.10.0)、Java(io.agentbase:agentbase-server-java:2.10.0)与 Go(agentbase-go-sdk 2.10.0)集成时,业务后端通过复用 Server SDK Client 配置的 Endpoint、Project ID(X-Appwrite-Project)与 Project API Key(X-Appwrite-Key),或通过标准 HTTP/SSE 客户端直接调用以下路径:
| 业务动作 | HTTP 方法与路径 | 请求认证头与 userId 位置 | 各语言后端 SDK / HTTP 调用方式对照 |
|---|---|---|---|
| 查询 / 初始化工作台 | GET | POST /v1/agent-runtime/project | X-Appwrite-Project + X-Appwrite-Key(无 userId) | 复用 SDK Client 凭据发起 GET / POST {}(详列于 sdks/zh-CN/agent-runtime.md) |
| 读取 / 更新工作台配置 | GET | PATCH /v1/agent-runtime/project/config | X-Appwrite-Project + X-Appwrite-Key(无 userId) | GET 读取配置与 config_hash;PATCH 传稀疏 JSON 配置对象 |
| 列出可用模型 | GET /v1/agent-runtime/project/models | X-Appwrite-Project + X-Appwrite-Key(无 userId) | GET 读取 models[](含 model_id 与 capabilities) |
| 读取 / 绑定项目词库 | GET | PUT /v1/agent-runtime/project/lexicons | X-Appwrite-Project + X-Appwrite-Key(无 userId) | GET / PUT JSON { bindings, enabled, stopIntercept, stopReply } |
| 读取 / 绑定 AI Gateway | GET | PUT /v1/agent-runtime/project/gateway | X-Appwrite-Project + X-Appwrite-Key(无 userId) | GET / PUT JSON { gateway_id } |
| Skill 技能包管理 | GET | POST /v1/agent-runtime/project/skills、GET | PUT | DELETE .../skills/{skillId} | X-Appwrite-Project + X-Appwrite-Key(无 userId) | 上传与替换使用 multipart/form-data(字段 file) |
| 创建 / 查询 / 归档 Thread | POST | GET /v1/agent-runtime/project/threads、GET | DELETE .../threads/{threadId} | POST 在 JSON Body 传 userId;GET/DELETE 在 Query 传 userId | 按业务终端用户映射稳定小写 userId 调用 |
| 读取会话消息与上下文精简 | GET .../threads/{threadId}/messages、GET .../threads/{threadId}/context-compactions | Query 传 userId(消息分页另传 after 与 limit) | 使用上一页末尾 message_seq 作为下一页 after |
| 创建 / 查询 / 取消 Run | POST /v1/agent-runtime/project/runs、GET .../runs/{runId}、POST .../runs/{runId}/cancel | POST 在 Body 传 userId(创建带 Idempotency-Key 头);GET 在 Query 传 userId | 创建受理返回 202 与 run_id,与 SSE 订阅分离 |
| 订阅可恢复 SSE 事件流 | GET /v1/agent-runtime/project/runs/{runId}/events | Query 传 userId;Header 带 Accept: text/event-stream 与可选 Last-Event-ID | 使用流式 HTTP 客户端按帧解析 AG-UI 事件并记录最新 id |
| 回传客户端工具结果 | POST /v1/agent-runtime/project/runs/{runId}/tool-messages | Body 传 { userId, id, role: "tool", toolCallId, content, error? } | 在 WAITING_CLIENT_TOOL 状态下向同一 runId 回传 |
| 读取 Run 消息与模型调用 | GET .../runs/{runId}/messages、GET .../runs/{runId}/model-invocations | Query 传 userId | 终态后读取最终持久化回答、知识检索引用与各步 Token 消耗 |