Docs
文档目录

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。

典型适用场景:

前置

配置项 / 依赖要求与示例(请替换为目标环境的实际值)
API Endpoint目标环境的 API 地址(包含 /v1);项目级路径前缀为 /v1/agent-runtime/project
所属组织与项目组织:Agentbase 企业智能中台(69c6d1aa00062e6bb60);项目:企业智能客服与知识中台(Project ID:enterprise-ai-hub-210,Shared V2 存储模式)
认证头与最小 ScopeX-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
多用户隔离参数 userId1–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)

使用骨架

  1. 初始化项目工作台并保存运行配置:查询 /v1/agent-runtime/project 状态 → 执行幂等初始化 POST /v1/agent-runtime/project → 查询可用模型 GET .../models → 通过 PATCH .../config 配置 qwen-plus、系统提示词、上下文预算及 Memory / Knowledge Search 开关。

  2. 绑定项目词库与 AI Gateway:通过 PUT .../lexicons 挂载企业同义词库与停用词库(配置 stopIntercept: true 与合规拦截话术 stopReply);通过 PUT .../gateway 绑定活跃的 AI Gateway。

  3. 上传与管理 Skill 技能包:通过 multipart/form-data 上传含 SKILL.md 的 .zip / .tar.gz / .tgz 技能包至 /v1/agent-runtime/project/skills,供智能体按需读取标准操作流程。

  4. 为业务用户创建会话并幂等提交 Run:携带业务用户 userId(如 user_zhangwei_001)调用 POST .../threads 创建会话 → 携带 Idempotency-Key 调用 POST .../runs 提交问题(返回 202 Accepted 及 run_id)。

  5. 订阅可恢复 SSE 事件流与读取最终消息:调用 GET .../runs/{runId}/events?userId=... 实时消费 TEXT_MESSAGE_CONTENT、TOOL_CALL_* 等 AG-UI 事件并记录最新帧 id;若网络断开则携带 Last-Event-ID 续连同一 Run;收到 RUN_FINISHED 后调用 GET .../runs/{runId}/messages 读取持久化回答与知识引用。

  6. 处理 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/configBody(无 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/lexiconsBody(无 userId):bindings: [{ lexiconId, priority }](最多 100 项)、enabled: boolean、stopIntercept: boolean、stopReply: string(最长 4096 字符)。返回生效的 LexiconBindings。开启 stopIntercept 后,用户输入命中 stop 词条将短路终止 Run 并直接返回 stopReply。
上传 Skill POST /project/skillsmultipart/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/threadsBody:{ "userId": "user_zhangwei_001" }。201 Created,返回 thread_id、title(初始 null)、status: "ACTIVE"。后续所有对该 Thread 的操作必须使用相同 userId。
创建 Run POST /project/runsHeader: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}/eventsQuery: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-messagesBody:{ "userId", "id", "role": "tool", "toolCallId", "content", "error" }(error 可选),其中 content 必须是 JSON 序列化后的字符串(如 "{\"status\":\"shipped\"}")。202 Accepted,返回 Run(状态回到 QUEUED 继续执行同一 Run,不会新建第二个 Run)。
消息分页 GET .../messagesQuery:userId、after(默认 0,传入上一页最后一条的 message_seq)、limit(默认 100,1–1000)。返回 Message[] 数组(message_id、message_seq、message_type、payload、tool_call_id、trace_id)。

错误与边界

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 回传结果;取消是独立操作,仅在确需停止运行时执行。读取模型调用记录也是单独的只读操作。参见工具回传和运行取消。

示例指引