Agent Runtime(项目级智能体工作台)
接入前核对目标环境、项目和凭据属于同一环境。
这是什么 / 何时用
Agent Runtime(智能体工作台)是 Agentbase 提供的项目级托管智能体运行引擎(/v1/agent-runtime/project/*)。业务后端无需自行在应用层维护复杂的“Prompt 组装 → 模型推理 → 工具调用 → 上下文压缩 → 流式推送”ReAct 循环:只需在当前 Project 中配置对话模型(如 qwen-plus)、系统提示词及所需能力开关(企业知识库检索 Knowledge Search、长期记忆 Memory 或托管上下文 PowerContext、项目词库 Lexicons、AI Gateway 工具与 Skill 技能包),即可通过统一的 Project API Key 为不同业务终端用户(userId)创建连续会话(Thread)、异步提交任务(Run)、订阅支持断线重连的 AG-UI 流式事件(SSE),并在客户端工具(Client Tool)场景下暂停等待回传后继续同一 Run。
典型适用场景:
多租户企业智能客服与知识助手:后端持单个 Project API Key,通过传入业务系统自身的
userId(如user_zhangwei_001、user_lina_002)隔离不同终端用户的会话历史与长期记忆,同时共享项目级知识库(kb_enterprise_support)与合规词库(lex_enterprise_synonyms、lex_support_stopwords)。业务工具与前端交互协同:通过绑定同项目下的 AI Gateway(
gw_7194685489feb1e169548619),让智能体在推理过程中自动调用受控 MCP / HTTP 服务端工具,或触发CLIENT工具交由应用端执行并回传结果。高可靠长任务与移动端弱网恢复:Run 创建(
202 Accepted)与 SSE 事件流(GET .../events)解耦;客户端网络闪断不会取消后台 Run。重连时可携带Last-Event-ID;游标过期时先查询已有运行状态和持久化消息。
前置
| 配置项 / 依赖 | 要求与示例(请替换为目标环境的实际值) |
|---|---|
| API Endpoint | 目标环境的 API 地址(包含 /v1);项目级路径前缀为 /v1/agent-runtime/project |
| 所属组织与项目 | 组织:Agentbase 企业智能中台(69c6d1aa00062e6bb60);项目:企业智能客服与知识中台(Project ID:enterprise-ai-hub-210,Shared V2 存储模式) |
| 认证头与最小 Scope | X-Appwrite-Project: enterprise-ai-hub-210 + X-Appwrite-Key: <APPBASE_API_KEY>;API Key 必须包含 agent-runtime.project Scope(用于项目配置管理与会话运行接口) |
| SDK 版本基线 | Node.js:agentbase-node-sdk@2.12.0;Python:agentbase-python-sdk==2.12.0;Java:io.agentbase:agentbase-server-java:2.12.0;Go:Release 2.12.0 的 agentbase-go-sdk ZIP |
多用户隔离参数 userId | 1–128 位 ASCII 字母、数字或下划线(^[A-Za-z0-9_]{1,128}$),不区分大小写(服务端统一归一化为小写),system 为保留字。项目共享配置接口不传 userId;用户级 Thread/Run 接口必填 userId(POST 放 JSON Body,GET / DELETE 放 URL Query) |
| 关联项目资源(按需) | 对话模型:qwen-plus / qwen-turbo(Provider:dashscope-prod);向量模型:text-embedding-v3(1024 维);知识库:kb_enterprise_support;词库:lex_enterprise_synonyms、lex_support_stopwords;AI Gateway:gw_7194685489feb1e169548619(需为 Shared V2 项目且 Gateway 状态为 ACTIVE) |
使用骨架
初始化项目工作台并保存运行配置:查询
/v1/agent-runtime/project状态 → 执行幂等初始化POST /v1/agent-runtime/project→ 查询可用模型GET .../models→ 通过PATCH .../config配置qwen-plus、系统提示词、上下文预算及 Memory / Knowledge Search 开关。绑定项目词库与 AI Gateway:通过
PUT .../lexicons挂载企业同义词库与停用词库(配置stopIntercept: true与合规拦截话术stopReply);通过PUT .../gateway绑定活跃的 AI Gateway。上传与管理 Skill 技能包:通过
multipart/form-data上传含SKILL.md的.zip/.tar.gz/.tgz技能包至/v1/agent-runtime/project/skills,供智能体按需读取标准操作流程。为业务用户创建会话并幂等提交 Run:携带业务用户
userId(如user_zhangwei_001)调用POST .../threads创建会话 → 携带Idempotency-Key调用POST .../runs提交问题(返回202 Accepted及run_id)。订阅可恢复 SSE 事件流与读取最终消息:调用
GET .../runs/{runId}/events?userId=...实时消费TEXT_MESSAGE_CONTENT、TOOL_CALL_*等 AG-UI 事件并记录最新帧id;若网络断开则携带Last-Event-ID续连同一 Run;收到RUN_FINISHED后调用GET .../runs/{runId}/messages读取持久化回答与知识引用。处理 Client Tool 回传、显式取消与用量审计:当 Run 进入
WAITING_CLIENT_TOOL时,执行本地获准工具并通过POST .../runs/{runId}/tool-messages回传结果恢复同一 Run;需要终止任务时显式调用POST .../runs/{runId}/cancel;通过GET .../model-invocations与GET .../context-compactions审计 Token 消耗与上下文精简记录。
关键参数与返回
| 接口 / 阶段 | 关键输入参数与位置 | 返回结构核心字段与处理要点 |
|---|---|---|
更新配置 PATCH /project/config | Body(无 userId):system_prompt、model_id、model_parameters(temperature/top_p)、context_window_tokens、reserved_output_tokens、max_steps、max_duration_ms、memory_enabled、powercontext_enabled(与 Memory 互斥)、knowledge_search_enabled、knowledge_base_ids(最多 100 个 ID)、memory_embedding_model_id、memory_embedding_dimensions。 | 返回完整 Config 对象与只读 config_hash。Run 受理时冻结当次配置快照,修改配置不影响在途 Run。 |
绑定词库 PUT /project/lexicons | Body(无 userId):bindings: [{ lexiconId, priority }](最多 100 项)、enabled: boolean、stopIntercept: boolean、stopReply: string(最长 4096 字符)。 | 返回生效的 LexiconBindings。开启 stopIntercept 后,用户输入命中 stop 词条将短路终止 Run 并直接返回 stopReply。 |
上传 Skill POST /project/skills | multipart/form-data(无 userId):二进制文件字段 file(.zip / .tar.gz / .tgz,<= 10 MiB,根目录含 SKILL.md)。 | 201 Created,返回 skill_id、name、description、front_matter、content_hash。列表接口另返回 skill_count 与 skill_limit。 |
创建会话 POST /project/threads | Body:{ "userId": "user_zhangwei_001" }。 | 201 Created,返回 thread_id、title(初始 null)、status: "ACTIVE"。后续所有对该 Thread 的操作必须使用相同 userId。 |
创建 Run POST /project/runs | Header:Idempotency-Key(1–128 bytes);Body:{ "userId", "thread_id", "user_message" }。 | 首次受理返回 202 Accepted(run_id、status: "QUEUED"、created_at);同幂等键同请求体重放返回 200 OK 且 idempotent_replay: true。 |
SSE 事件流 GET /project/runs/{runId}/events | Query:userId;Header:Accept: text/event-stream、重连时带 Last-Event-ID。 | 每帧含外层 id、event 与 data(JSON,含 type、messageId/toolCallId、delta 等)。外层 id 用于 Last-Event-ID 续连,不可与消息序号 message_seq 混用。 |
回传工具结果 POST /project/runs/{runId}/tool-messages | Body:{ "userId", "id", "role": "tool", "toolCallId", "content", "error" }(error 可选),其中 content 必须是 JSON 序列化后的字符串(如 "{\"status\":\"shipped\"}")。 | 202 Accepted,返回 Run(状态回到 QUEUED 继续执行同一 Run,不会新建第二个 Run)。 |
消息分页 GET .../messages | Query:userId、after(默认 0,传入上一页最后一条的 message_seq)、limit(默认 100,1–1000)。 | 返回 Message[] 数组(message_id、message_seq、message_type、payload、tool_call_id、trace_id)。 |
错误与边界
用户隔离与传参位置铁律:
userId只能在受控后端由真实登录态映射生成,严禁将 Project API Key 下发给前端并让前端自填userId。POST接口userId放 JSON Body,GET/DELETE接口userId放 URL Query;遗漏、双传、含连字符-或使用保留字system均返回400 general_argument_invalid。跨用户访问其他userId的 Thread/Run 统一返回404 NOT_FOUND。单会话并发互斥(
409 THREAD_BUSY):同一thread_id同一时刻只允许存在一个未结束的 Run(含WAITING_CLIENT_TOOL状态)。若需发起新对话,必须先完成当前客户端工具回传,或显式调用POST .../cancel并等待状态收敛为CANCELLED。SSE 断开不等于取消,游标过期需先读持久化事实:关闭 SSE 连接不会停止后台 Run。当缓存仍有记录且
Last-Event-ID过于落后时,接口可能返回409 stream_cursor_expired(含earliest_event_id与latest_event_id)。默认保留时间为 30 分钟,普通事件按 Run 截止时间、终态事件按发布时间计算;缓存条数上限也可能提前淘汰事件。整个缓存不存在时,终态或等待客户端工具的 Run 可能返回回退事件,而不一定返回 409——此时应先调用GET .../runs/{runId}与GET .../messages恢复持久化状态与消息,切勿盲目重新创建 Run。Memory 与 PowerContext 互斥:在同一份项目配置中,
memory_enabled与powercontext_enabled不能同时为true;启用任一能力前必须先完成对应项目服务的初始化,而knowledge_search_enabled可与其中任意一种自由组合。外部工具副作用幂等保护:当 Run 返回
TOOL_RESULT_UNKNOWN或发生网络超时重连时,Runtime 不替外部业务系统回滚写操作;客户端按toolCallId去重,有副作用的业务操作必须先查询业务真实状态再决定是否重试。
SDK 类别差异
| SDK 类别与语言面 | 项目级智能体工作台(/v1/agent-runtime/project/*)接入方式 |
|---|---|
| Node.js Server SDK(server-sdk/nodejs.md) | 初始化 agentbase-node-sdk@2.12.0 的 Client(设置 Endpoint、Project ID enterprise-ai-hub-210 与含 agent-runtime.project 的 API Key),复用项目认证头通过原生 fetch / Web Streams 调用本文介绍的项目配置、会话运行接口与可恢复 SSE 流。 |
| Java / Python / Go Server SDK(server-sdk/java.md、server-sdk/python.md、server-sdk/go.md) | 与 Node.js 相同,在受控服务端持有 Project API Key,通过标准 HTTP/SSE 客户端携带 X-Appwrite-Project、X-Appwrite-Key 与业务 userId 接入项目级智能体工作台。 |
| Web Client SDK(client-sdk/web.md) | 浏览器前端不得持有 Project API Key,也不直接调用 /v1/agent-runtime/project/*;前端通过业务后端封装的接口发起提问并消费后端转发的 SSE 事件流。 |
| Console SDK(console-sdk/nodejs.md) | 用于创建项目与签发包含 agent-runtime.project Scope 的 Project API Key。 |
各语言调用示例
本页保留接入概念与语言选型。此前多语言 HTTP 示例存在凭据重定向、失败后继续操作和运行取消时序问题,已暂时移除;各语言示例待逐项重新验证。当前可按下列产品手册中的操作与 REST 示例接入,具体能力以目标环境为准。
项目 API Key 只保存在受控的服务端。自行实现 HTTP 客户端时,请禁用携带密钥请求的自动重定向;每一步先确认 HTTP 2xx 与响应内容,再决定后续操作。不要把密钥写入浏览器、命令行参数或日志。
1. 初始化项目工作台并保存运行配置
先查询工作台状态,按需初始化,再确认项目可用模型并更新配置。权限、入口及单步请求见工作台概览和项目配置。
2. 绑定项目词库与 AI Gateway
词库和网关是可分别配置的能力;按实际需要选择,不必连续执行。参见知识库与词库和工具与技能。
3. 上传与管理 Skill 技能包
确认项目权限与压缩包内容后上传;按实际上传结果核对技能列表和配额。步骤见工具与技能。
4. 为业务用户创建会话并幂等提交 Run
先创建会话并确认成功,从响应取得 thread_id,再单独提交 Run。每次新运行使用独立的 Idempotency-Key;仅重试同一请求时复用。参见会话与运行。
5. 订阅可恢复 SSE 事件流与读取最终消息
记录已接收事件的 id,断线后按需携带 Last-Event-ID 重连同一 Run。流关闭不等于运行结束;遇到 HTTP 409 时先查询已有 Run 状态和持久化消息,不要创建替代 Run。参见事件流与运行状态。
6. 处理 Client Tool 回传、显式取消与用量审计
等待客户端工具时,按当前 Run 和 toolCallId 回传结果;取消是独立操作,仅在确需停止运行时执行。读取模型调用记录也是单独的只读操作。参见工具回传和运行取消。