Docs
文档目录

Agent Runtime API

项目级智能体工作台(Project Agent Runtime)REST API 参考文档。业务后端通过项目级 API Key 接入当前项目下的托管智能体运行引擎(/v1/agent-runtime/project/*),统一管理项目运行配置、词库绑定、AI Gateway 工具发现、Skill 技能包上传,并通过 userId 为不同业务终端用户隔离管理会话(Thread)、异步任务(Run)、可恢复流式事件(SSE)与客户端工具回传(Client Tool)。

资源与基础路径

核心资源模型与职责边界

资源对象核心标识与路径归属范围关键语义与生命周期说明
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 执行循环与流式恢复架构

  1. 业务后端持 Project API Key 调用 POST /v1/agent-runtime/project/runs,传入 userId、thread_id、user_message 与 Idempotency-Key。API 校验项目权限和词库停用词规则,冻结配置快照,并返回 202 Accepted(run_id、status=QUEUED)。

  2. 后端通过 GET /v1/agent-runtime/project/runs/{runId}/events?userId=... 订阅 SSE。Runtime 加载 Thread 历史、召回 Memory / PowerContext,计算上下文 Token 预算。

  3. Runtime 在 max_steps 和 max_duration_ms 限制内循环调用模型,发送提示词、上下文与授权工具 Schema;模型返回回答增量或工具调用请求。

  4. 服务端工具调用先校验参数 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。

  5. 推理期间,Runtime 持续推送带递增事件 ID 的 TEXT_MESSAGE_CONTENT 等 SSE 帧。完成后持久化最终 ASSISTANT 消息与 ModelInvocation 用量,将 Run 更新为 SUCCEEDED,并推送 RUN_FINISHED。

  6. 后端通过 GET /v1/agent-runtime/project/runs/{runId}/messages?userId=... 获取持久化消息和知识来源引用。SSE 断线可携带 Last-Event-ID 续传;断线本身不会取消后台 Run。

Run 生命周期状态机

起始状态后续状态触发条件
初始SUBMITTING → QUEUED登记运行并入队
QUEUEDRUNNINGWorker 开始执行
RUNNINGWAITING_CLIENT_TOOL等待客户端工具结果
WAITING_CLIENT_TOOLQUEUED调用 /runs/{runId}/tool-messages 回传结果
RUNNINGSUCCEEDED / FAILED执行成功或失败,进入终态
RUNNINGCANCEL_REQUESTED → CANCELLED调用 /runs/{runId}/cancel,等待执行步退出
QUEUED / WAITING_CLIENT_TOOLCANCELLED调用 /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-Projectenterprise-ai-hub-210必填。指定目标项目 ID,不拼接在 URL 路径中。
X-Appwrite-Key<APPBASE_API_KEY>必填。属于当前项目的有效 Server API Key(支持标准 Project API Key 与动态 Project Key,仅保存在受控业务后端,严禁下发至浏览器或移动端)。
必需权限 Scopeagent-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-Keyreq_zhangwei_20261022_001POST /v1/agent-runtime/project/runs 推荐携带(1–128 字节 ASCII 字符串)。同项目、同 userId、同请求体下重放返回原 Run(HTTP 200 + idempotent_replay: true);同 Key 但不同请求体返回 409 IDEMPOTENCY_KEY_CONFLICT。
Last-Event-ID21GET /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:

  1. 格式与大小写归一化:

    • 字段名严格为驼峰 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)为平台保留身份,禁止外部传入。

  2. 传参位置严格区分(禁止双传):

    • 14 个项目共享配置接口(服务初始化、配置读写、模型列表、词库绑定、AI Gateway 绑定、Skill 技能包管理):不需要也不允许传 userId。

    • 13 个用户级会话与运行接口(/threads、/runs 及其全部子资源):每次请求必填 userId,其中 POST 请求必须放在 JSON 请求体(Body)中,GET 与 DELETE 请求必须放在 URL 查询参数(Query)中;严禁同时在 Query 和 Body 中提供 userId。

  3. 跨用户强隔离语义:

    • 创建 Thread 后,针对该 Thread 及其下属 Run 的所有后续操作(提交 Run、查询状态、订阅 SSE、拉取消息、回传客户端工具结果、取消 Run、归档 Thread)都必须携带与创建时相同的 userId。

    • 若传入 user_lina_002 访问属于 user_zhangwei_001 的 threadId 或 runId,服务端统一按 404 NOT_FOUND(资源不可见)拒绝,既不泄露资源存在性,也不会篡改资源归属。


端点清单

项目级智能体工作台共提供 27 个 HTTP 端点(含 14 个项目共享配置端点与 13 个用户级会话/运行端点),全量清单如下:

分类方法 + 完整路径所需 ScopeuserId 要求与位置幂等性成功状态码用途说明
服务初始化GET /v1/agent-runtime/projectagent-runtime.project不需要幂等200查询当前项目 Agent Runtime 是否已初始化(initialized)
服务初始化POST /v1/agent-runtime/projectagent-runtime.project不需要幂等200显式初始化当前项目 Agent Runtime(重复调用不清空配置)
项目配置GET /v1/agent-runtime/project/configagent-runtime.project不需要幂等200读取当前项目智能体配置与只读 config_hash
项目配置PATCH /v1/agent-runtime/project/configagent-runtime.project不需要条件幂等200稀疏更新项目智能体配置(模型、提示词、预算、Memory/PowerContext/Knowledge 开关)
模型目录GET /v1/agent-runtime/project/modelsagent-runtime.project不需要幂等200列出当前项目可供智能体工作台使用的模型及能力标签(chat / embedding)
词库绑定GET /v1/agent-runtime/project/lexiconsagent-runtime.project不需要幂等200读取当前项目智能体工作台绑定的词库列表与停用词阻断策略
词库绑定PUT /v1/agent-runtime/project/lexiconsagent-runtime.project不需要幂等200全量设置智能体工作台绑定的词库优先级列表、enabled、stopIntercept 与 stopReply
AI GatewayGET /v1/agent-runtime/project/gatewayagent-runtime.project不需要幂等200读取当前项目智能体工作台绑定的 AI Gateway(gateway_id)
AI GatewayPUT /v1/agent-runtime/project/gatewayagent-runtime.project不需要幂等200绑定或切换同项目下处于 ACTIVE 且有可用快照的 AI Gateway
Skill 管理GET /v1/agent-runtime/project/skillsagent-runtime.project不需要幂等200列出当前项目已上传的 Skill 包及容量配额(skill_count / skill_limit)
Skill 管理POST /v1/agent-runtime/project/skillsagent-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/threadsagent-runtime.project必填(JSON Body)非幂等201为指定 userId 创建新的连续对话 Thread
会话管理GET /v1/agent-runtime/project/threadsagent-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}/messagesagent-runtime.project必填(URL Query)幂等200按 after(message_seq)与 limit 游标分页读取会话持久化消息
会话历史GET /v1/agent-runtime/project/threads/{threadId}/context-compactionsagent-runtime.project必填(URL Query)幂等200读取会话的上下文自动精简(Compaction)事件记录
运行管理POST /v1/agent-runtime/project/runsagent-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}/cancelagent-runtime.project必填(JSON Body)幂等202 或 200显式请求取消正在排队、运行或等待客户端工具的 Run
流式事件GET /v1/agent-runtime/project/runs/{runId}/eventsagent-runtime.project必填(URL Query)幂等200订阅 AG-UI 协议 SSE 增量事件流,支持 Last-Event-ID 断线续连
运行消息GET /v1/agent-runtime/project/runs/{runId}/messagesagent-runtime.project必填(URL Query)幂等200按 after(message_seq)与 limit 读取单次 Run 产生的持久化消息
客户端工具POST /v1/agent-runtime/project/runs/{runId}/tool-messagesagent-runtime.project必填(JSON Body)幂等(复用 id)202向处于 WAITING_CLIENT_TOOL 的 Run 回传客户端工具结果以继续执行
模型用量GET /v1/agent-runtime/project/runs/{runId}/model-invocationsagent-runtime.project必填(URL Query)幂等200读取单次 Run 各推理步的模型调用详情、Token 消耗与耗时记录

请求与响应

以下按业务接入顺序逐端点给出完整的输入参数表、输出 Schema、可执行 curl 示例与真实 HTTP 响应示例。

1. 服务状态与初始化

1.1 查询服务初始化状态:GET /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

调用示例:

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

调用示例:

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

调用示例:

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

请求体参数表(ConfigPatch):

字段名类型必填约束与业务语义
system_promptstring | null否系统提示词(0–200,000 字符);传空串或 null 使用平台默认行为。
model_idstring首次必填项目内具备 chat 能力的模型 ID(如 qwen-plus)。
model_parametersobject | null首次必填仅允许 temperature(0–1)与 top_p(0–1);传 {} 或 null 清除显式采样参数。
context_window_tokensinteger首次必填上下文窗口总 Token 数(> 0,如 32768、65536)。
reserved_output_tokensinteger首次必填预留给模型输出的 Token 预算(> 0 且必须小于 context_window_tokens)。
max_stepsinteger首次必填单次 Run 允许的最大 ReAct 推理步数(> 0,如 12)。
max_duration_msinteger首次必填单次 Run 允许的最大执行时长(毫秒,> 0,如 120000)。
memory_enabledboolean否是否启用项目长期记忆(需先在项目中初始化并启用 Memory 服务;与 powercontext_enabled 严格互斥)。
powercontext_enabledboolean否是否启用托管 PowerContext(需 Shared V2 项目先初始化 PowerContext 至 ready 状态;开启时自动关闭 memory_enabled,同一请求同时将两者设为 true 返回 400)。
knowledge_search_enabledboolean否是否启用企业知识库检索工具(knowledge_retrieve)。新开启时必须同时指定至少 1 个 knowledge_base_ids。
knowledge_base_idsstring[]条件必填允许检索的本项目知识库 ID 数组(最多 100 个不重复有效 ID,如 ["kb_enterprise_support"])。
memory_embedding_model_idstring | null否Memory 使用的 Embedding 模型 ID(如 text-embedding-v3)。
memory_embedding_dimensionsinteger | 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

调用示例:

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

字段名类型必填默认值约束与业务语义
bindingsarray是[]有序词库绑定数组(最多 100 项,禁止重复 lexiconId)。每项严格为 {"lexiconId": string, "priority": integer},其中 priority 为 0–2147483647 的整数,数值越小优先级越高。
enabledboolean否false是否启用已绑定的词库规则。
stopInterceptboolean否true当用户输入命中词库中的 stop(停用词)词条时,是否立即短路阻断本次 Run。
stopReplystring否""触发停用词短路阻断时直接返回的预设合规话术(最长 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

调用示例:

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

调用示例:

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

调用示例:

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

调用示例:

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}

调用示例:

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}

调用示例:

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}

调用示例:

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

调用示例:

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

调用示例:

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}

调用示例:

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}

调用示例:

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

消息对象(Message)字段说明:

字段名类型含义说明
message_idstring消息唯一标识
thread_idstring所属会话 ID
run_idstring产生该消息的 Run ID
trace_idstring(可选)关联的 Observability Trace ID
message_seqinteger会话内严格递增的消息序号(用于 after 游标翻页与客户端去重)
message_typestring枚举:USER、ASSISTANT、TOOL_CALL、TOOL_RESULT
payloadstring | objectUSER 与 ASSISTANT 消息为纯字符串文本;TOOL_CALL 与 TOOL_RESULT 为结构化 JSON 对象
tool_call_idstring | null工具调用关联 ID(普通文本消息为 null)
created_atstringRFC 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

调用示例:

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

字段名类型必填约束与说明
userIdstring是必须与目标 thread_id 所属的业务用户 ID 完全一致(忽略大小写)。
thread_idstring是目标会话 ID。同一 Thread 下不能存在未结束的活动 Run,否则返回 409 THREAD_BUSY。
user_messagestring是本轮用户输入的非空文本消息。

调用示例:

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}

调用示例:

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

SSE 事件类型(AG-UI 协议)全集表:

事件 typedata JSON 核心字段客户端处理语义
RUN_STARTEDrunId, threadId标记当前 Run 开始执行
TEXT_MESSAGE_STARTmessageId, role: "assistant"初始化一条助手回答消息容器
TEXT_MESSAGE_CONTENTmessageId, delta: string按 messageId 追加流式回答文本片段
TEXT_MESSAGE_ENDmessageId当前段落文本输出完毕(不代表整次 Run 结束)
REASONING_START / REASONING_END / REASONING_MESSAGE_ENDmessageId维护模型思考推理过程的展示状态边界
REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENTmessageId, role: "reasoning", delta: string展示模型流式思考片段
TOOL_CALL_STARTtoolCallId, toolCallName, toolCallSource记录工具调用开始(toolCallSource 为 "CLIENT" 或服务端工具来源)
TOOL_CALL_ARGStoolCallId, toolCallSource, delta: string按 toolCallId 拼接工具调用参数 JSON 片段(非客户端工具可能脱敏为 {"redacted":true})
TOOL_CALL_ENDtoolCallId, toolCallSource工具参数传输完毕;若 toolCallSource === "CLIENT",查询 Run 状态确认进入 WAITING_CLIENT_TOOL 后执行本地工具并回传
TOOL_CALL_RESULTtoolCallId, messageId, role: "tool", content工具结果已记录(默认通知摘要为 {"status":"completed"},完整结构化结果通过消息接口读取)
RUN_FINISHEDrunId, threadIdRun 正常完成,随后读取 Run 终态与持久化消息
RUN_ERRORrunId, threadId, message, code(可选)Run 执行出错或被取消(如 code: "RUN_CANCELLED"),读取 Run 状态确认终态
CUSTOMname, 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。

字段名类型必填约束与说明
userIdstring是必须与当前 Run 所属的业务用户 ID 一致。
idstring是客户端生成的工具消息唯一标识(重试同一次回传时保持不变)。
rolestring是固定为 "tool"。
toolCallIdstring是对应 TOOL_CALL_START / TOOL_CALL_END 事件中的 toolCallId。
contentstring是JSON 序列化后的字符串(注意:必须是 string,如 "{\"order_id\":\"ORD-20261022-889\",\"status\":\"shipped\"}",不能直接传 JSON 对象;失败回传时可传 "{}")。若工具在 Gateway 中声明了 outputSchema,成功结果将按该 Schema 校验。
errorstring否当本地工具执行失败时填写错误原因说明,让模型感知失败并继续决策。

调用示例(成功回传):

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

调用示例:

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

调用示例:

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

调用示例:

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"
    }
  ]
}

错误与边界

错误响应结构

项目级智能体工作台接口可能返回两类错误结构,客户端应同时兼容:

  1. Runtime 领域错误(RuntimeError):

{
  "error": {
    "code": "THREAD_BUSY",
    "message": "thread has an open run"
  },
  "request_id": "req_01ja9x9z8y7x6w5v4u3t2s1r0q"
}
  1. 平台网关层错误(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"
}
  1. 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 Requestgeneral_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 / 403user_unauthorized / general_access_forbiddenX-Appwrite-Project 与 API Key 不匹配,或 API Key 缺少 agent-runtime.project Scope。在控制台为当前项目的 API Key 勾选 agent-runtime.project 权限 Scope。
404 Not FoundNOT_FOUND / lexicon_not_foundthreadId、runId、skillId 不存在,或传入的 userId 与创建该 Thread/Run 的用户不一致,或尚未绑定 AI Gateway。核对资源 ID 与所属 userId 是否一致;跨用户访问一律按未找到拒绝。
409 ConflictSTATE_CONFLICT项目 Agent Runtime 尚未初始化即调用业务接口,或多人并发更新 /config 发生 config_hash 乐观锁冲突。先调用 POST /v1/agent-runtime/project 初始化;配置冲突时重新 GET /config 后合并变更重试。
409 ConflictTHREAD_BUSY目标 thread_id 当前已有处于 SUBMITTING、QUEUED、RUNNING、WAITING_CLIENT_TOOL 或 CANCEL_REQUESTED 的活动 Run。继续订阅或轮询既有活动 Run;若正在等待客户端工具则回传 tool-messages;确需放弃旧任务时先调用 /cancel 等待终态。
409 ConflictIDEMPOTENCY_KEY_CONFLICT使用相同的 Idempotency-Key 提交了不同的 thread_id、userId 或 user_message。重试同一次提交必须保持请求体完全一致;发起新问题时必须生成新的 Idempotency-Key。
409 Conflictstream_cursor_expired断线重连携带的 Last-Event-ID 已滑出有界事件流缓存窗口。先调用 GET /runs/{runId} 与 GET /runs/{runId}/messages 恢复已持久化的状态与消息,若 Run 仍在运行可从 earliest_event_id - 1 重新订阅,切勿新建重复 Run。
Run FAILEDMODEL_RATE_LIMITED上游模型供应商(如 DashScope)触发 TPM / RPM 限流。检查模型供应商配额与并发度,采用指数退避后按需发起新 Run。
Run FAILEDMODEL_UPSTREAM_FAILED上游模型调用超时、凭证失效或返回异常。查看 GET /runs/{runId}/model-invocations 中的 provider_request_id 与错误详情,排查 LLM Provider 连通性。
Run FAILEDCONTEXT_BUDGET_EXCEEDED / CONTEXT_PREPARE_FAILED / CONTEXT_FRESH_TAIL_TOO_LARGE单次用户输入、工具定义或近期未压缩消息超出了 context_window_tokens - reserved_output_tokens 的输入预算。调大 context_window_tokens、合理缩减 reserved_output_tokens,或精简单轮输入与挂载工具数量。
Run FAILEDRUN_DEADLINE_EXCEEDED单次 Run 总执行时间超过了配置中的 max_duration_ms。排查慢工具调用耗时,或在 PATCH /config 中适当上调 max_duration_ms。
Run FAILEDTOOL_RESULT_UNKNOWN外部工具调用在执行期间发生网络中断或进程重启,无法确认外部写操作是否已生效。严禁盲目自动重做有副作用的工具调用;应先查询外部业务系统真实状态,确认后再决定后续动作。
503 Service UnavailableRUN_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/projectX-Appwrite-Project + X-Appwrite-Key(无 userId)复用 SDK Client 凭据发起 GET / POST {}(详列于 sdks/zh-CN/agent-runtime.md)
读取 / 更新工作台配置GET | PATCH /v1/agent-runtime/project/configX-Appwrite-Project + X-Appwrite-Key(无 userId)GET 读取配置与 config_hash;PATCH 传稀疏 JSON 配置对象
列出可用模型GET /v1/agent-runtime/project/modelsX-Appwrite-Project + X-Appwrite-Key(无 userId)GET 读取 models[](含 model_id 与 capabilities)
读取 / 绑定项目词库GET | PUT /v1/agent-runtime/project/lexiconsX-Appwrite-Project + X-Appwrite-Key(无 userId)GET / PUT JSON { bindings, enabled, stopIntercept, stopReply }
读取 / 绑定 AI GatewayGET | PUT /v1/agent-runtime/project/gatewayX-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)
创建 / 查询 / 归档 ThreadPOST | 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-compactionsQuery 传 userId(消息分页另传 after 与 limit)使用上一页末尾 message_seq 作为下一页 after
创建 / 查询 / 取消 RunPOST /v1/agent-runtime/project/runs、GET .../runs/{runId}、POST .../runs/{runId}/cancelPOST 在 Body 传 userId(创建带 Idempotency-Key 头);GET 在 Query 传 userId创建受理返回 202 与 run_id,与 SSE 订阅分离
订阅可恢复 SSE 事件流GET /v1/agent-runtime/project/runs/{runId}/eventsQuery 传 userId;Header 带 Accept: text/event-stream 与可选 Last-Event-ID使用流式 HTTP 客户端按帧解析 AG-UI 事件并记录最新 id
回传客户端工具结果POST /v1/agent-runtime/project/runs/{runId}/tool-messagesBody 传 { userId, id, role: "tool", toolCallId, content, error? }在 WAITING_CLIENT_TOOL 状态下向同一 runId 回传
读取 Run 消息与模型调用GET .../runs/{runId}/messages、GET .../runs/{runId}/model-invocationsQuery 传 userId终态后读取最终持久化回答、知识检索引用与各步 Token 消耗