AgentbaseDocs
文档目录

智能体工作台(Agent Runtime)概览、架构与快速启用

本手册对应 Agentbase v2.10.0(控制台同版本)。

智能体工作台(Agent Runtime / Agent Workbench) 是 Agentbase v2.10.0 提供的项目级托管智能体运行与调试中枢。与仅完成单次文本补全的底层大模型推理接口不同,Agent Runtime 在项目空间(如 企业智能客服与知识中台,ID:enterprise-ai-hub-210)内完整接管了智能体的 多轮 ReAct(Reasoning + Acting)推理执行循环——从解析用户意图、召回跨会话长期记忆(Memory)或持久上下文(PowerContext)、检索企业知识库证据(Knowledge Base)、调用统一 AI 网关(AI Gateway / MCP)服务端工具或暂停等待客户端工具(Client Tool)回传,到通过可恢复的 AG-UI SSE 事件流实时推送推理与回答增量,并将会话消息、工具调用事实及单步模型消耗全量持久化。


功能概述

在企业落地智能客服、排障专家助手与业务自动化代理时,如果仅依赖底层 Chat Completions 接口,工程团队必须在业务后端自行拼装多轮会话状态表、Prompt 历史截断与摘要压缩、RAG 检索工具注入、多工具并发调度、SSE 断线重连游标缓存以及异常取消状态机。一旦并发上升或工具耗时波动,极易出现上下文超限报错、工具重复执行或浏览器刷新后回答丢失等问题。

Agentbase 智能体工作台(Agent Runtime) 将上述复杂的运行机制下沉为项目原生(Project-Native)平台底座,同时提供 Console 可视化三栏工作台 与 **25 个项目级 HTTP API 端点(/v1/agent-runtime/project/*)**,帮助研发与知识运营团队在单个项目内实现“零代码装配调试、一行命令生产接入”:


核心概念与架构

智能体工作台 ReAct 执行循环与全栈协同架构图

flowchart TB
    subgraph Callers["接入层:控制台与业务后端调用方"]
        ConsoleUI["管理控制台三栏工作台\n/console/project-default-enterprise-ai-hub-210/agent-runtime"]
        BizBackend["可信业务后端微服务\nHeader: X-Appwrite-Project + X-Appwrite-Key (agent-runtime.project)\n按 userId (user_zhangwei_001 / user_lina_002) 隔离业务用户"]
    end

    subgraph RuntimeCore["项目级智能体工作台核心引擎 (/v1/agent-runtime/project/*)"]
        InitAndConfig["项目初始化与共享配置中心\nPOST /project (initialized=true)\nGET/PATCH /project/config (config_hash 乐观保存)"]
        LexiconGuard["前置词库改写与停用词阻断器\nGET/PUT /project/lexicons\n(lex_enterprise_synonyms + lex_support_stopwords / stopIntercept)"]
        ThreadMgr["多轮会话管理 (Threads)\nPOST/GET/DELETE /project/threads\n状态: ACTIVE / ARCHIVED + context-compactions"]
        RunScheduler["异步运行状态机与 ReAct 调度器 (Runs)\nSUBMITTING -> QUEUED -> RUNNING <-> WAITING_CLIENT_TOOL\n-> SUCCEEDED / FAILED / CANCELLED"]
        EventStream["有界可恢复 AG-UI SSE 事件流\nGET /project/runs/{runId}/events (Last-Event-ID 续传)"]
        MsgStore["持久化消息与模型调用审计\nGET .../messages (message_seq 游标)\nGET .../model-invocations (Token 与耗时明细)"]
    end

    subgraph Capabilities["项目内生 AI 算力、知识、记忆与工具底座"]
        LLM["模型网关 (LLM Gateway: dashscope-prod)\nqwen-plus / qwen-turbo / text-embedding-v3"]
        KB["知识库检索 (Knowledge Search)\nkb_enterprise_support (hybrid / vector / fulltext)"]
        MemOrPC["长期上下文 (严格二选一互斥)\nMemory (Shared V2 画像与多层记忆) 或 PowerContext (持久上下文与交接)"]
        GatewaySkill["工具与技能扩展\nAI Gateway (prod-enterprise-ai-gateway) / Client Tool / Skill 包"]
        Obs["智能体运维 (AgentOps / Observability)\nATIF-v1.8 Trace 瀑布流 & Dataset RAG 四维质量评测"]
    end

    ConsoleUI --> InitAndConfig & ThreadMgr & RunScheduler & EventStream
    BizBackend --> InitAndConfig & ThreadMgr & RunScheduler & EventStream
    InitAndConfig --> RunScheduler
    ThreadMgr --> RunScheduler
    RunScheduler --> LexiconGuard
    LexiconGuard -->|未命中阻断词| LLM
    RunScheduler --> KB & MemOrPC & GatewaySkill
    RunScheduler --> EventStream & MsgStore
    RunScheduler --> Obs

核心对象层级与职责矩阵

Agent Runtime 围绕 Project $\rightarrow$ Config $\rightarrow$ Thread $\rightarrow$ Run $\rightarrow$ Message 五层核心对象以及 Tool / Skill 扩展实体构建完整的数据模型:

核心对象唯一标识与关键状态字段归属粒度架构职责与工程约束说明
项目(Project)projectId(如 enterprise-ai-hub-210)<br/>初始化状态:initialized: true/false项目级Runtime 配置、模型目录、知识库、词库、AI Gateway 与 Skill 技能包的物理安全边界。首次使用需执行幂等初始化(POST /v1/agent-runtime/project)。
运行配置(Config)config_hash(只读快照哈希)<br/>含 model_id、system_prompt 等项目级共享定义智能体的主对话模型、采样参数、上下文窗口预算、最大推理步数/时长及知识库、Memory/PowerContext 开关。Run 在受理瞬间锁定当次有效配置,后续修改配置仅作用于新发起的 Run。
会话(Thread)thread_id<br/>状态:ACTIVE(活跃)、ARCHIVED(已归档)业务用户级(绑定 userId)承载同一业务用户的一段连续多轮交流,按时间顺序组织多次 Run 的历史消息。归档会话(DELETE /threads/{threadId})仅隐藏会话本身,不会删除用户的长期 Memory 或 PowerContext。
运行(Run)run_id<br/>状态:SUBMITTING $\rightarrow$ QUEUED $\rightarrow$ RUNNING $\leftrightarrow$ WAITING_CLIENT_TOOL $\rightarrow$ SUCCEEDED / FAILED / CANCELLED会话级(绑定 thread_id + userId)一次用户消息触发的异步 ReAct 任务执行。同一个 Thread 在同一时刻最多只允许存在一条未结束的 Run(并发提交返回 409 THREAD_BUSY)。
消息(Message)message_id + 会话内递增序号 message_seq<br/>类型:USER、ASSISTANT、TOOL_CALL、TOOL_RESULT会话 / 运行级持久化保存的用户输入、模型最终回答、工具调用请求与工具返回结果。支持按 after={message_seq} 游标稳定增量拉取,用于历史还原与知识来源(Citations)渲染。
工具与技能(Tool & Skill)gateway_id + toolCallId<br/>skill_id + skill_catalog_hash项目级共享Tool 由绑定的 AI Gateway 提供(含服务端执行工具与 toolCallSource="CLIENT" 的客户端工具);Skill 为上传的 .zip/.tar.gz 任务规范包(含 SKILL.md),供模型在推理中按需查阅。

角色、入口与关联关系

1. 控制台导航路径与三栏工作台布局

登录 Agentbase 控制台,在顶部切换至组织 Agentbase 企业智能中台(69c6d1aa00062e6bb60)与项目 企业智能客服与知识中台(enterprise-ai-hub-210,Shared V2 模式),单击左侧导航栏 AI 分区下的 智能体工作台(Agent Workbench),即可进入精确路由:

初始化完成后,智能体工作台采用高密度的三栏式工程布局:

2. 权限矩阵与 userId 多租户数据隔离契约

访问通道鉴权凭证与权限要求userId 传递规则与隔离边界适用场景
Console 浏览器工作台开发者登录会话 Cookie<br/>组织角色:owner、admin、developer、editor(billing / analyst 仅只读查看)自动绑定当前登录的开发者身份,仅用于控制台内交互式装配与对话验证。严禁将 Console Cookie 嵌入外部客户应用。提示词调优、RAG 召回验证、工具联调与故障复现
服务端 HTTP API(项目共享配置面)Header:X-Appwrite-Project + X-Appwrite-Key<br/>必需 Scope:**agent-runtime.project****无需传入 userId**(涵盖 /project 状态与初始化、/config、/models、/lexicons、/gateway、/skills 共 13 个项目级接口)。自动化 CI/CD 部署智能体配置、批量同步词库与上传 Skill 技能包
服务端 HTTP API(用户会话与运行数据面)Header:X-Appwrite-Project + X-Appwrite-Key<br/>必需 Scope:**agent-runtime.project****每次请求必填 userId**:<br/>• POST 请求放在 JSON 正文(如 {"userId": "user_zhangwei_001", ...})<br/>• GET / DELETE 请求放在 URL Query 参数(如 ?userId=user_zhangwei_001)企业业务后端代表不同终端客户(如张伟、李娜)创建会话、发起问答与订阅 SSE 事件流

**userId 格式与安全铁律**:

  • 字符集与长度:userId 必须是由 1~128 个 ASCII 字母、数字或下划线组成的字符串(正则:^[A-Za-z0-9_]{1,128}$),且字段名固定为驼峰 userId(不接受 user_id、数字类型、空串或空白字符)。
  • 大小写不敏感与自动归一化:服务端会将传入的 userId 统一归一化为小写存储与比对(例如 "User_ZhangWei_001" 与 "user_zhangwei_001" 指向同一个业务用户空间)。保留字 system(含任意大小写形式)禁止业务使用。
  • 严格归属校验:某个 thread_id 或 run_id 一旦由 user_zhangwei_001 创建,后续针对该资源的查询、SSE 订阅、取消、工具结果回传及归档操作**必须传入相同的 userId**。若传入 user_lina_002 访问张伟的会话,服务端将直接按资源不可见(HTTP 404 NOT_FOUND)拒绝,绝不发生跨租户越权或归属篡改。

3. 五篇专题手册导航矩阵

本手册将智能体工作台的全量生产能力拆解为五篇内聚专题,读者可按研发阶段顺序阅读:

专题章节文档链接核心覆盖内容关键 REST API 端点
1. 概览、架构与快速启用(本篇)overview.mdReAct 执行原理、五层对象模型、userId 隔离契约、一键初始化与端到端快速上手GET/POST /v1/agent-runtime/project<br/>GET /models · PATCH /config<br/>POST /threads · POST /runs
2. 模型、提示词、上下文精简与词库拦截configuration.md模型与采样参数、系统提示词乐观自动保存、上下文窗口预算、自动上下文精简(Compaction)与项目词库 stopIntercept 拦截GET/PATCH /v1/agent-runtime/project/config<br/>GET .../context-compactions<br/>GET/PUT /v1/agent-runtime/project/lexicons
3. 多轮会话、异步运行与可恢复 SSE 事件流threads-runs.md会话生命周期与 message_seq 分页、Run 状态机与幂等键、AG-UI SSE 全量事件协议、Last-Event-ID 断点续传与模型调用审计POST/GET/DELETE .../threads<br/>POST/GET .../runs · POST .../cancel<br/>GET .../events · GET .../model-invocations
4. 企业知识库检索、长期记忆与 PowerContextknowledge-memory.md挂载 1~100 个知识库与引用溯源、启用长期 Memory 或 PowerContext 持久上下文及任务交接、二选一互斥契约PATCH /v1/agent-runtime/project/config<br/>(knowledge_search_enabled / memory_enabled / powercontext_enabled)
5. 业务工具网关、客户端工具与技能包(Skills)tools-skills.mdAI Gateway / MCP 服务端工具绑定、Client Tool 5 步暂停回传协议、Skill 压缩包上传管理、Trace 诊断与 Dataset RAG 质量评测GET/PUT .../gateway<br/>POST .../runs/{runId}/tool-messages<br/>GET/POST/PUT/DELETE .../skills

功能详解与操作指南

本节以标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)为例,演示如何从零完成智能体工作台的服务初始化、基础模型装配、首次多轮对话及服务端 API 闭环验证。

步骤 1:检查前置条件并初始化项目智能体工作台

1. 前置条件确认

  export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
  export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
  export APPBASE_API_KEY="<APPBASE_API_KEY>"

2. 控制台与 API 一键初始化(GET / POST /v1/agent-runtime/project)

   # 1. 查询当前项目 Agent Runtime 是否已初始化(无需传 userId)
   curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

若返回 {"initialized": false},执行以下 POST 请求完成初始化(重复调用保持幂等,不会清空已有配置或会话数据):

   # 2. 显式初始化项目 Agent Runtime 服务
   curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{}'

**预期成功响应(HTTP 200 OK)**:

   {
     "initialized": true
   }

步骤 2:查询可用模型并保存基础运行配置

初始化完成后,需为工作台绑定对话模型并设定合理的上下文窗口与执行限制。推荐首次接入时先关闭可选的 Memory、PowerContext 与 Knowledge Search,用纯模型对话验证基础链路连通,再按需逐项开启增强能力。

   curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/models" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

**预期响应(HTTP 200 OK)**:

   {
     "models": [
       {
         "model_id": "qwen-plus",
         "capabilities": ["chat"]
       },
       {
         "model_id": "qwen-turbo",
         "capabilities": ["chat"]
       },
       {
         "model_id": "text-embedding-v3",
         "capabilities": ["embedding"]
       }
     ]
   }
   curl -fsSL -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "system_prompt": "你是 Agentbase 企业智能客服与技术支持专家。请使用清晰、准确、结构化的中文回答用户的技术架构与运维排障问题。",
       "model_id": "qwen-plus",
       "model_parameters": {
         "temperature": 0.3,
         "top_p": 0.9
       },
       "context_window_tokens": 65536,
       "reserved_output_tokens": 4096,
       "max_steps": 16,
       "max_duration_ms": 180000,
       "memory_enabled": false,
       "powercontext_enabled": false,
       "knowledge_search_enabled": false
     }'

**预期响应(HTTP 200 OK)**:返回完整 Config 对象及最新生成的只读快照标识 "config_hash": "cfg_9f8e7d6c5b4a3210"。


步骤 3:为业务用户创建会话(Thread)并提交异步运行(Run)

当企业客服门户后端接收到终端客户张伟(user_zhangwei_001)的咨询时,按以下标准序列创建会话并提交问题:

   curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/threads" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "userId": "user_zhangwei_001"
     }'

**预期响应(HTTP 201 Created)**:

   {
     "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
     "title": null,
     "status": "ACTIVE"
   }
   curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Idempotency-Key: msg-zhangwei-20261022-001" \
     -d '{
       "userId": "user_zhangwei_001",
       "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
       "user_message": "请简要说明 OceanBase Shared V2 项目表模式相比传统模式有哪些核心优势?"
     }'

**预期响应(HTTP 202 Accepted)**:

   {
     "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
     "status": "QUEUED",
     "created_at": "2026-10-22T09:15:00Z"
   }

步骤 4:订阅实时 SSE 事件流并读取持久化最终消息

任务受理后,业务后端可同时或择一使用 SSE 流式订阅(用于前端打字机实时渲染)与 持久化消息拉取(用于落库对账与历史展示):

   curl -N -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9k5a7b9c1d3e5f7g9h1j3/events?userId=user_zhangwei_001" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Accept: text/event-stream"

典型 SSE 帧序列输出:

   id: 1
   event: RUN_STARTED
   data: {"type":"RUN_STARTED","runId":"run_01j8x9k5a7b9c1d3e5f7g9h1j3","threadId":"thd_01j8x9k2m4n6p8q0r2s4t6u8v0"}

   id: 2
   event: TEXT_MESSAGE_START
   data: {"type":"TEXT_MESSAGE_START","messageId":"msg_ast_001","role":"assistant"}

   id: 3
   event: TEXT_MESSAGE_CONTENT
   data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_ast_001","delta":"OceanBase Shared V2 表模式具有以下核心优势:\n1. 原生高性能列类型与向量索引支持..."}

   id: 4
   event: TEXT_MESSAGE_END
   data: {"type":"TEXT_MESSAGE_END","messageId":"msg_ast_001"}

   id: 5
   event: RUN_FINISHED
   data: {"type":"RUN_FINISHED","runId":"run_01j8x9k5a7b9c1d3e5f7g9h1j3","threadId":"thd_01j8x9k2m4n6p8q0r2s4t6u8v0"}
   curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9k5a7b9c1d3e5f7g9h1j3/messages?userId=user_zhangwei_001&after=0&limit=100" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

**预期响应(HTTP 200 OK)**:

   [
     {
       "message_id": "msg_usr_001",
       "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
       "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
       "message_seq": 1,
       "message_type": "USER",
       "payload": "请简要说明 OceanBase Shared V2 项目表模式相比传统模式有哪些核心优势?",
       "tool_call_id": null,
       "created_at": "2026-10-22T09:15:00Z"
     },
     {
       "message_id": "msg_ast_001",
       "thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
       "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
       "trace_id": "4b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e",
       "message_seq": 2,
       "message_type": "ASSISTANT",
       "payload": "OceanBase Shared V2 表模式具有以下核心优势:\n1. 原生高性能列类型与向量索引支持;\n2. 支撑 AI Memory 长期记忆独占表组隔离与统一 AI Gateway 挂载;\n3. 显著降低海量半结构化与向量混合查询的解析开销。",
       "tool_call_id": null,
       "created_at": "2026-10-22T09:15:03Z"
     }
   ]

常见问题与排障

Q1:首次调用 /v1/agent-runtime/project/config 或 /threads 时返回 HTTP 409 STATE_CONFLICT 是什么原因?

原因与排查步骤: 该项目尚未执行 Agent Runtime 初始化(即 GET /v1/agent-runtime/project 返回 {"initialized": false})。请先在 Console 智能体工作台页面单击启用按钮,或通过服务端调用 POST /v1/agent-runtime/project(传入空对象 {})完成初始化,待返回 {"initialized": true} 后再保存配置或创建会话。

Q2:使用项目 API Key 调用 /v1/agent-runtime/project/* 接口时返回 401 general_unauthorized_scope?

原因与排查步骤: 项目级智能体工作台的全部 25 个接口统一要求 API Key 具备 **agent-runtime.project** 权限范围(Scope)。仅勾选 agent-runtime.read、agent-runtime.write 或 agent-runtime.execute 均不满足项目级工作台接口要求。请前往控制台 Overview → Integrations → API keys,编辑当前使用的 Key,勾选 agent-runtime.project 并保存后重试。

Q3:为什么调用会话或运行接口时返回 400 general_argument_invalid 并提示 userId 错误?

原因与排查步骤: 请逐项核对 userId 的四条协议规范:

Q4:能否将具备 agent-runtime.project 权限的 API Key 直接放到前端浏览器代码中,由前端传不同的 userId 来区分用户?

原因与排查步骤: 严禁这样做。持有项目 API Key 的调用方拥有指定该项目下任意 userId 的最高受托权限。一旦将项目 API Key 暴露在浏览器或移动端包体中,恶意用户可以随意构造他人的 userId 读取或篡改他人的会话与长期记忆。正确架构是:将项目 API Key 严格保存在企业可信业务后端,由业务后端验证终端客户的登录态(如项目 Auth Session 或企业自有 SSO),再由后端将已认证的用户身份映射为稳定的小写 userId 转发给 Agent Runtime。


相关文档