Docs
文档目录

智能体工作台(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/*),帮助研发与知识运营团队在单个项目内实现“零代码装配调试、一行命令生产接入”:

  1. 托管式多步 ReAct 推理与工具编排循环:

    • 在单次运行(Run)内,Runtime 自动驱动大模型循环执行“理解问题 $\rightarrow$ 选择并调用工具 $\rightarrow$ 读取工具结果 $\rightarrow$ 继续推理”,直至生成最终回答、暂停等待客户端工具结果(WAITING_CLIENT_TOOL),或触达配置的最大步骤数(max_steps)与最大执行时长(max_duration_ms)边界。

    • 同一轮模型输出支持并发请求多个工具,Runtime 按唯一的 toolCallId 精确关联输入参数、执行状态与返回结果。

  2. 项目级全栈 AI 能力按需热装配:

    • 基础对话零门槛启动:无需预先开通长期记忆或 PowerContext,仅需在项目 模型(LLM Gateway) 中配置可用对话模型(如 dashscope-prod 下的 qwen-plus),即可初始化工作台开展多轮流式对话。

    • 企业级可选集成:按业务演进随时勾选挂载 企业知识库(Knowledge Search,最多 100 个知识库)、项目级干预词库(Lexicons,支持同义词改写与 stopIntercept 停用词零 Token 阻断)、长期记忆(Memory)或持久上下文(PowerContext,两者严格二选一互斥)、AI Gateway / MCP 业务工具 以及 Skill 技能说明包。

  3. 可恢复异步运行与有界 SSE 事件流:

    • 提交任务(POST /v1/agent-runtime/project/runs)采用异步受理语义(返回 HTTP 202 Accepted),浏览器关闭标签页或移动端网络闪断均不会中断后台正在执行的任务。

    • 实时增量采用标准 AG-UI SSE 协议(GET .../runs/{runId}/events),支持携带 Last-Event-ID 断点续传与幂等去重;任务完成后,所有用户提问、模型回答、工具调用与工具结果均持久化为带递增序号(message_seq)的消息记录。

  4. 单把项目 API Key 承载多租户业务用户隔离(userId):

    • 业务后端只需持有具备 agent-runtime.project 权限范围(Scope)的项目 API Key,通过在请求中显式传入目标业务用户的 userId(如 user_zhangwei_001、user_lina_002),即可在同一项目下为成千上万名外部终端客户隔离会话列表(Threads)、运行状态(Runs)与长期记忆上下文,无需为每位外部业务用户预先创建 Agentbase 控制台账号。


核心概念与架构

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

智能体工作台(Agent Runtime)概览、架构与快速启用:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心对象层级与职责矩阵

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

核心对象唯一标识与关键状态字段归属粒度架构职责与工程约束说明
项目(Project)projectId(如 enterprise-ai-hub-210)
初始化状态:initialized: true/false
项目级Runtime 配置、模型目录、知识库、词库、AI Gateway 与 Skill 技能包的物理安全边界。首次使用需执行幂等初始化(POST /v1/agent-runtime/project)。
运行配置(Config)config_hash(只读快照哈希)
含 model_id、system_prompt 等
项目级共享定义智能体的主对话模型、采样参数、上下文窗口预算、最大推理步数/时长及知识库、Memory/PowerContext 开关。Run 在受理瞬间锁定当次有效配置,后续修改配置仅作用于新发起的 Run。
会话(Thread)thread_id
状态:ACTIVE(活跃)、ARCHIVED(已归档)
业务用户级(绑定 userId)承载同一业务用户的一段连续多轮交流,按时间顺序组织多次 Run 的历史消息。归档会话(DELETE /threads/{threadId})仅隐藏会话本身,不会删除用户的长期 Memory 或 PowerContext。
运行(Run)run_id
状态: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
类型:USER、ASSISTANT、TOOL_CALL、TOOL_RESULT
会话 / 运行级持久化保存的用户输入、模型最终回答、工具调用请求与工具返回结果。支持按 after={message_seq} 游标稳定增量拉取,用于历史还原与知识来源(Citations)渲染。
工具与技能(Tool & Skill)gateway_id + toolCallId
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
组织角色:owner、admin、developer、editor(billing / analyst 仅只读查看)
自动绑定当前登录的开发者身份,仅用于控制台内交互式装配与对话验证。严禁将 Console Cookie 嵌入外部客户应用。提示词调优、RAG 召回验证、工具联调与故障复现
服务端 HTTP API(项目共享配置面)Header:X-Appwrite-Project + X-Appwrite-Key
必需 Scope:agent-runtime.project
无需传入 userId(涵盖 /project 状态与初始化、/config、/models、/lexicons、/gateway、/skills 共 13 个项目级接口)。自动化 CI/CD 部署智能体配置、批量同步词库与上传 Skill 技能包
服务端 HTTP API(用户会话与运行数据面)Header:X-Appwrite-Project + X-Appwrite-Key
必需 Scope:agent-runtime.project
每次请求必填 userId:
• POST 请求放在 JSON 正文(如 {"userId": "user_zhangwei_001", ...})
• GET / DELETE 请求放在 URL Query 参数(如 ?userId=user_zhangwei_001)
企业业务后端代表不同终端客户(如张伟、李娜)创建会话、发起问答与订阅 SSE 事件流

userId 格式与安全铁律:

  1. 字符集与长度:userId 必须是由 1~128 个 ASCII 字母、数字或下划线组成的字符串(正则:^[A-Za-z0-9_]{1,128}$),且字段名固定为驼峰 userId(不接受 user_id、数字类型、空串或空白字符)。

  2. 大小写不敏感与自动归一化:服务端会将传入的 userId 统一归一化为小写存储与比对(例如 "User_ZhangWei_001" 与 "user_zhangwei_001" 指向同一个业务用户空间)。保留字 system(含任意大小写形式)禁止业务使用。

  3. 严格归属校验:某个 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
GET /models · PATCH /config
POST /threads · POST /runs
2. 模型、提示词、上下文精简与词库拦截configuration.md模型与采样参数、系统提示词乐观自动保存、上下文窗口预算、自动上下文精简(Compaction)与项目词库 stopIntercept 拦截GET/PATCH /v1/agent-runtime/project/config
GET .../context-compactions
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
POST/GET .../runs · POST .../cancel
GET .../events · GET .../model-invocations
4. 企业知识库检索、长期记忆与 PowerContextknowledge-memory.md挂载 1~100 个知识库与引用溯源、启用长期 Memory 或 PowerContext 持久上下文及任务交接、二选一互斥契约PATCH /v1/agent-runtime/project/config
(knowledge_search_enabled / memory_enabled / powercontext_enabled)
5. 业务工具网关、客户端工具与技能包(Skills)tools-skills.mdAI Gateway / MCP 服务端工具绑定、Client Tool 5 步暂停回传协议、Skill 压缩包上传管理、Trace 诊断与 Dataset RAG 质量评测GET/PUT .../gateway
POST .../runs/{runId}/tool-messages
GET/POST/PUT/DELETE .../skills

功能详解与操作指南

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

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

1. 前置条件确认

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

  1. Console 操作:进入 /console/project-default-enterprise-ai-hub-210/agent-runtime。若当前项目首次打开智能体工作台(状态 initialized: false),页面中央会展示初始化引导卡片,单击 启用智能体工作台(Initialize / Enable) 按钮,系统将在数秒内完成项目运行时元数据初始化并展开三栏工作台。

  2. 服务端 curl 验证与幂等初始化:

    # 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,用纯模型对话验证基础链路连通,再按需逐项开启增强能力。

  1. 查询项目内可用于智能体对话的模型列表(GET /v1/agent-runtime/project/models):

    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"]
        }
      ]
    }
  2. 保存项目级运行配置(PATCH /v1/agent-runtime/project/config): 在 Console 右侧配置栏选择模型 qwen-plus,填写系统提示词并设置窗口参数(面板自动触发保存并显示「所有更改已保存」);或通过 API 直接写入:

    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)的咨询时,按以下标准序列创建会话并提交问题:

  1. 为业务用户 user_zhangwei_001 创建新会话(POST /v1/agent-runtime/project/threads):

    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"
    }
  2. 向该会话提交用户问题并启动异步运行(POST /v1/agent-runtime/project/runs): 携带 Idempotency-Key 防止网络超时重试导致重复创建任务,且 userId 必须与创建该 thread_id 时完全一致:

    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 流式订阅(用于前端打字机实时渲染)与 持久化消息拉取(用于落库对账与历史展示):

  1. 订阅 AG-UI 实时事件流(GET /v1/agent-runtime/project/runs/{runId}/events): 注意 GET 请求的 userId 必须通过 URL Query 参数传入:

    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"}
  2. 确认运行终态并拉取持久化消息(GET /v1/agent-runtime/project/runs/{runId}/messages):

    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 的四条协议规范:

  1. 传参位置错误:POST 请求(创建会话、提交 Run、取消 Run、回传工具结果)必须将 userId 放在 JSON 请求体中;GET 与 DELETE 请求(查询会话、消息、事件流、模型调用记录、归档会话)必须将 userId 放在 URL Query 参数中,且禁止同时在 Query 和 Body 中重复传参。

  2. 字段名或类型错误:字段名区分大小写,必须为 userId(不能写成 user_id),且值必须为 JSON 字符串(例如 "10086",不能传数字 10086)。

  3. 非法字符或保留字:仅允许 1~128 位 ASCII 字母、数字与下划线([A-Za-z0-9_]),不支持连字符 -、空格、中文字符或保留字 system。

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

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


相关文档