AgentbaseDocs
文档目录

业务工具网关(AI Gateway / MCP)、客户端工具(Client Tool)与技能包(Skills)

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

为了让智能体从“能查资料回答问题的知识顾问”升级为“能查工单、调接口、遵循标准作业程序(SOP)完成复杂任务的业务代理”,Agentbase 智能体工作台(Agent Runtime) 提供了完整的工具与技能扩展体系:通过绑定项目的 统一 AI 网关(AI Gateway / MCP) 发现并执行已授权的业务工具,通过 客户端工具(Client Tool)暂停与恢复协议 让前端或宿主应用安全参与本地动作执行,通过 **Skill 技能包(SKILL.md) 为模型按需注入标准化领域作业指南,并深度联动 智能体运维(Observability / AgentOps)** 完成端到端 Trace 追踪与数据集 RAG 四维质量评测。


功能概述

在企业生产项目(如 企业智能客服与知识中台,ID:enterprise-ai-hub-210,OceanBase Shared V2 模式)中,工具调用与技能治理往往面临安全边界模糊、前后端协同中断以及效果难以量化评估等挑战。Agent Runtime 通过以下四大支柱构建安全可控的行动闭环:


核心概念与架构

服务端工具(MCP)、客户端工具(Client Tool)与 Skill 协同执行时序图

sequenceDiagram
    participant App as 业务后端 / 宿主应用
    participant Runtime as Agent Runtime (/v1/agent-runtime/project)
    participant GW as AI Gateway (gw_7194685489feb1e169548619)
    participant Skill as 项目 Skill 仓库 (/skills)
    participant LLM as 对话模型 (qwen-plus)

    App->>Runtime: 1. POST /runs (userId="user_zhangwei_001", thread_id, user_message)
    Runtime-->>App: 202 Accepted (run_id, status="QUEUED")
    App->>Runtime: 2. GET /runs/{runId}/events?userId=... (建立 SSE 订阅)

    Runtime->>GW: 发现当前项目已发布快照中的授权工具 Schema (SERVER / CLIENT)
    Runtime->>Skill: 加载可用 Skill 目录元数据 (name + description)
    Runtime->>LLM: Step 1: 发送上下文 + 工具 Schema + Skill 目录

    opt 模型按需读取 Skill 详细作业规范
        LLM-->>Runtime: 请求读取 customer-ticket-sop 技能说明
        Runtime->>Skill: 读取 SKILL.md 内容
        Skill-->>Runtime: 返回 SOP 步骤与排障规范文本
    end

    opt 路径 A:模型调用服务端工具 (toolCallSource="SERVER")
        LLM-->>Runtime: 请求调用 query_customer_ticket(ticket_id="TK-20261022-001")
        Runtime-->>App: SSE: TOOL_CALL_START / ARGS / END (source="SERVER")
        Runtime->>GW: 校验 inputSchema 与权限后执行 MCP/HTTP 工具
        GW-->>Runtime: 返回工单详情 JSON
        Runtime-->>App: SSE: TOOL_CALL_RESULT ({"status":"completed"})
    end

    opt 路径 B:模型调用客户端工具 (toolCallSource="CLIENT")
        LLM-->>Runtime: 请求调用 confirm_local_diagnostics(order_id="ORD-1003")
        Runtime-->>App: SSE: TOOL_CALL_START / ARGS / END (toolCallId="call_cli_01", source="CLIENT")
        Runtime->>Runtime: Run 状态切换为 WAITING_CLIENT_TOOL (暂停等待)
        App->>App: 校验工具名与参数,执行本地获准操作并序列化结果
        App->>Runtime: POST /runs/{runId}/tool-messages (toolCallId="call_cli_01", content="{\"order_id\":\"ORD-1003\",\"status\":\"shipped\"}")
        Runtime-->>App: 202 Accepted (同一 run_id 重新进入 QUEUED -> RUNNING)
        Runtime->>Runtime: 校验 outputSchema (若有),将结果写入持久化消息
    end

    Runtime->>LLM: Step N: 汇总工具结果与证据生成最终回答
    LLM-->>Runtime: 流式输出回答文本
    Runtime-->>App: SSE: TEXT_MESSAGE_START / CONTENT / END -> RUN_FINISHED
    App->>Runtime: GET /runs/{runId}/messages (读取最终持久化消息与 trace_id)

三类扩展能力(Gateway Server Tool / Client Tool / Skill)边界对比表

维度服务端业务工具(Gateway / MCP Tool)客户端工具(Client Tool)技能说明包(Skill Package)
核心用途由平台后端直接调用企业内部微服务、数据库查询或外部 MCP Server 接口交由客户前端或业务宿主应用在本地环境执行操作并将结果回传给同一条 Run为模型提供按需查阅的标准化任务指令(SKILL.md)、领域规范与参考资料
定义与管理位置在同项目 **AI 网关(/ai-gateway)** 中注册、审批并发布网关快照,通过 PUT /project/gateway 绑定在同项目 AI 网关 中注册为 CLIENT 源工具(含 inputSchema 与可选 outputSchema)直接通过智能体工作台右侧 Skills 面板或 /v1/agent-runtime/project/skills 上传压缩包
执行主体与运行状态Runtime 服务端自动执行;Run 保持 RUNNING 状态直至工具返回宿主应用/客户端执行;Run 暂停在 **WAITING_CLIENT_TOOL**,收到 /tool-messages 后恢复不执行任何代码或外部调用;仅由模型在推理中作为文本参考资料读取
安全与幂等约束服务端强制校验 inputSchema 与 Gateway 授权策略;SSE 中参数可能脱敏为 {"redacted":true}应用必须按 toolCallId 去重,校验工具名与参数,对写操作使用业务幂等键;回传受 outputSchema 校验上传 Skill 不会自动执行包内脚本,也不会自动授予模型任何额外的工具调用权限

角色、入口与关联关系

工具网关、客户端工具回传与 Skill 管理接口矩阵

功能模块HTTP 方法与完整路径是否需要 userId成功状态码前置条件与权限 Scope(统一要求 agent-runtime.project)
查询已绑定的 AI GatewayGET /v1/agent-runtime/project/gateway不需要(项目共享)200 OK(未绑定时返回 404)项目须为 OceanBase Shared V2 模式且已开启 AI Gateway 服务
设置 / 切换 AI Gateway 绑定PUT /v1/agent-runtime/project/gateway不需要(项目共享)200 OK请求体传入 {"gateway_id": "..."};目标网关必须属于当前项目、状态为 ACTIVE 且已有已发布的区域快照
回传客户端工具执行结果POST /v1/agent-runtime/project/runs/{runId}/tool-messages必填(JSON 正文 userId)202 Accepted目标 Run 处于 WAITING_CLIENT_TOOL 状态,且 userId、toolCallId 与原调用严格匹配
上传新 Skill 技能包POST /v1/agent-runtime/project/skills不需要(项目共享)201 Createdmultipart/form-data 上传 file 字段(.zip/.tar.gz/.tgz,<= 10 MiB),未超过 skill_limit
列出项目全部 SkillGET /v1/agent-runtime/project/skills不需要(项目共享)200 OK返回 {items: Skill[], skill_catalog_hash, skill_count, skill_limit}
查询单个 Skill 元数据GET /v1/agent-runtime/project/skills/{skillId}不需要(项目共享)200 OK返回 Skill 元数据、front_matter 与 content_hash(不直接下载二进制压缩包)
整包替换已有 SkillPUT /v1/agent-runtime/project/skills/{skillId}不需要(项目共享)200 OKmultipart/form-data 上传新的完整压缩包 file,更新 content_hash 与 updated_at
删除指定 SkillDELETE /v1/agent-runtime/project/skills/{skillId}不需要(项目共享)204 No Content从当前项目工作台移除该 Skill

功能详解与操作指南

1. 绑定项目 AI Gateway 与校验工具输入/输出 Schema

1. 前置准备:确认 Shared V2 模式与已发布网关快照

2. 绑定 AI Gateway 到智能体工作台(PUT / GET /v1/agent-runtime/project/gateway)

在控制台 /console/project-default-enterprise-ai-hub-210/agent-runtime 右侧配置面板的 工具网关(Tools Gateway) 区域选择 prod-enterprise-ai-gateway,或通过 API 绑定:

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

# 1. 将项目智能体工作台绑定至已发布快照的 AI Gateway(无需传 userId)
curl -fsSL -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/gateway" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway_id": "gw_7194685489feb1e169548619"
  }'

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

{
  "gateway_id": "gw_7194685489feb1e169548619",
  "created_at": "2026-10-22T09:10:00Z"
}
# 2. 查询当前工作台已绑定的 AI Gateway
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/gateway" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

注意事项:每个项目同一时间绑定一个 Gateway,可通过再次调用 PUT /gateway 切换到同项目的另一个 Gateway。若尝试绑定尚未发布快照的 Gateway,接口会返回 HTTP 400。当前项目接口不提供通过传入空字符串 "" 解绑的操作。

3. 工具 inputSchema 与 outputSchema 双向校验机制

工具的 Schema 在 AI Gateway 中集中定义(**不需要在每次 POST /runs 请求中传入工具定义**)。以订单/工单状态查询工具为例:

  {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "minLength": 1
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
  {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": ["processing", "shipped", "delivered"]
      }
    },
    "required": ["order_id", "status"],
    "additionalProperties": false
  }

2. 客户端工具(Client Tool)5 步暂停、回传与恢复完整实操

当网关中配置了 toolCallSource: "CLIENT" 的客户端工具,且模型在执行过程中决定调用该工具时,请严格遵循以下 5 步标准协议完成本地执行与结果回传:

步骤 1:从 SSE 事件流捕获 CLIENT 工具调用请求

在订阅 /runs/{runId}/events 时,依次收到以下三类事件:

步骤 2:确认 Run 进入 WAITING_CLIENT_TOOL 状态并核对持久化调用

查询 GET /v1/agent-runtime/project/runs/{runId}?userId=user_zhangwei_001,确认状态已变为 "status": "WAITING_CLIENT_TOOL"。如需获取该工具完整的 output_schema 元数据,可读取 GET /runs/{runId}/messages 中 message_type === "TOOL_CALL" 的 payload(内含 call_id、tool_name、arguments、source: "CLIENT" 及可选 output_schema)。

步骤 3:在宿主应用中安全执行本地动作

应用在本地执行前**必须校验 toolCallName 与参数合法性**,切勿盲目执行任意未授权指令。若该工具涉及创建订单、扣款等外部写副作用,务必以 toolCallId 作为业务幂等键,防止 SSE 断线重放时重复执行。

步骤 4:调用 POST /runs/{runId}/tool-messages 回传执行结果

将本地执行结果序列化为 JSON 字符串 放入 content 字段(注意:content 的类型必须是 string,不能直接放一个未序列化的 JSON Object):

ToolMessage 字段类型必填规范与约束说明
userIdstring必填必须与创建该 Run 的业务用户 userId 完全一致(如 "user_zhangwei_001")。
idstring必填客户端生成的唯一工具消息 ID(如 "tmsg_ord1003_001");网络超时重试同一次回传时必须复用同一 id。
rolestring必填固定为 "tool"。
toolCallIdstring必填必须与服务端 TOOL_CALL_START / TOOL_CALL 消息中的 toolCallId(如 "call_cli_9001")严格一致。
contentstring必填成功结果的 JSON 序列化字符串(如 "{\"order_id\":\"ORD-1003\",\"status\":\"shipped\"}");失败时可传 "{}"。
errorstring可选当客户端工具执行失败时,传入可读错误原因描述(如 "订单系统内网连接超时")。

**回传成功结果 curl 示例**:

curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/tool-messages" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_zhangwei_001",
    "id": "tmsg_ord1003_001",
    "role": "tool",
    "toolCallId": "call_cli_9001",
    "content": "{\"order_id\":\"ORD-1003\",\"status\":\"shipped\"}"
  }'

**回传工具执行失败 curl 示例**:

curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/tool-messages" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_zhangwei_001",
    "id": "tmsg_ord1003_001",
    "role": "tool",
    "toolCallId": "call_cli_9001",
    "content": "{}",
    "error": "订单子系统暂不可用,请稍后重试"
  }'

步骤 5:恢复观察同一条 Run 直至 SUCCEEDED

回传接口成功受理后返回 **HTTP 202 Accepted**:

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

注意:**回传工具结果不会创建新的 run_id**,而是让原 run_id 从 WAITING_CLIENT_TOOL 重新进入 QUEUED $\rightarrow$ RUNNING,模型读取工具结果后生成最终回答并推送 RUN_FINISHED。


3. Skill 技能包制作、上传与全生命周期管理(/v1/agent-runtime/project/skills)

当企业拥有多套细分场景的标准作业流程(例如《OceanBase 锁冲突排障技能》《VIP 工单升级核验技能》)时,可将其打包为 Skill 技能包 上传至智能体工作台。

1. 制作合规的 Skill 压缩包(SKILL.md 规范)

**标准 SKILL.md 示例**:

---
name: ob-troubleshooting-sop
description: 处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。
---

# OceanBase 核心故障标准排障流程

1. **确认故障码与版本**:首先确认用户报错码是 `-4013`(向量内存不足)还是 `-4024`(行锁等待超时),并核实集群是否为 OceanBase 4.3 Shared V2 模式。
2. **检索权威分块**:调用 `knowledge_retrieve` 检索 `kb_enterprise_support` 知识库中的《OceanBase分布式事务与向量索引排障指南.md》。
3. **输出结构化结论**:按「根因定位 → 诊断 SQL/视图 → 参数调整建议 → 风险提示」四段式输出,并保留知识库文档出处。

在本地终端将其打包为 ob-troubleshooting-sop.zip:

zip -r ob-troubleshooting-sop.zip SKILL.md

2. 上传、列出、查询、替换与删除 Skill(Console 与 curl 实操)

# 1. 上传新 Skill 技能包 (POST /v1/agent-runtime/project/skills)
# 注意:使用 --form 'file=@...' 自动生成 multipart/form-data boundary,不要手写 Content-Type boundary
curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/skills" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  --form 'file=@./ob-troubleshooting-sop.zip'

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

{
  "skill_id": "skl_01j8xa1b2c3d4e5f6g7h8j9k0m",
  "name": "ob-troubleshooting-sop",
  "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。",
  "front_matter": {
    "name": "ob-troubleshooting-sop",
    "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。"
  },
  "content_hash": "sha256_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
  "created_by": "user_admin_001",
  "created_at": "2026-10-22T09:25:00Z",
  "updated_at": "2026-10-22T09:25:00Z"
}
# 2. 列出当前项目全部已上传的 Skill 及容量配额 (GET /v1/agent-runtime/project/skills)
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/skills" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

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

{
  "items": [
    {
      "skill_id": "skl_01j8xa1b2c3d4e5f6g7h8j9k0m",
      "name": "ob-troubleshooting-sop",
      "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。",
      "front_matter": {
        "name": "ob-troubleshooting-sop",
        "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。"
      },
      "content_hash": "sha256_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
      "created_by": "user_admin_001",
      "created_at": "2026-10-22T09:25:00Z",
      "updated_at": "2026-10-22T09:25:00Z"
    }
  ],
  "skill_catalog_hash": "cat_7f6e5d4c3b2a1908",
  "skill_count": 1,
  "skill_limit": 10
}

配额判断准则:应用应 dynamically 读取响应中的 skill_count 与 skill_limit 判断剩余可上传槽位,切勿在业务代码中硬编码固定上限。

# 3. 查询单个 Skill 元数据 (GET /v1/agent-runtime/project/skills/{skillId})
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

# 4. 使用新版压缩包整包替换已有 Skill (PUT /v1/agent-runtime/project/skills/{skillId})
curl -fsSL -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  --form 'file=@./ob-troubleshooting-sop-v2.zip'

# 5. 删除不再使用的 Skill (DELETE /v1/agent-runtime/project/skills/{skillId} -> 204 No Content)
curl -i -X DELETE "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

4. 联动智能体运维(Observability):Trace 下钻与 Dataset RAG 四维评测

1. 从工作台对话一键跳转至 Trace 瀑布流

当平台开启 agentops.runtimeExportEnabled 时,智能体工作台的每一次 Run 均自动上报带 capability:agent 标签的 OpenTelemetry 轨迹并整理为 ATIF-v1.8 标准格式。

2. 在数据集(Datasets)中对智能体工作台执行 RAG 四维质量评估与根因分析

智能体工作台不设孤立的弹窗评测按钮,而是深度复用 **智能体运维 → 数据集(/observability/datasets)** 的统一评测流水线(详见评估数据集管理与评估、评分与索引质量评测):

评估指标名称评分比对的真实运行证据质量度量维度关键前置要求与边界说明
检索查询质量(Query Quality)本轮用户原始问题 vs 智能体实际发出的 knowledge_retrieve 检索 Query评估模型改写或生成的检索词是否忠实保留了用户意图与关键限定条件(如故障码 4013)要求本次 Run 实际保存了与样本身份一致的可信 RAG 检索证据
上下文相关性(Context Relevance)用户问题 vs 实际进入最终回答步骤的检索片段集合(含图片理解描述与来源定位)评估知识库召回的文档切片与用户问题的相关程度多个检索步骤按最终模型消息顺序合并;若证据缺失或被压缩摘要截断,标记为“证据不足”而不强行用空上下文打分
答案忠实度(Faithfulness)智能体最终回答 vs 实际送入模型的检索片段评估回答中的事实主张是否有据可查、是否存在脱离检索证据的幻觉(Hallucination)严格比对当次冻结的检索片段,不会重新查询当前知识库去替历史运行补证据
答案准确性(Answer Accuracy)智能体最终回答 vs 数据集样本中冻结的 **标准答案(expectedOutput)**评估最终回答是否正确且完整覆盖了标准答案的核心要点**必须提供样本标准答案(expectedOutput)**;哪怕答案忠实度高,若遗漏了关键排障步骤,答案准确性依然能敏锐识别出低分

常见问题与排障

Q1:调用 PUT /v1/agent-runtime/project/gateway 绑定网关时返回 HTTP 400 或 412 是什么原因?

原因与排查步骤:

Q2:向 /runs/{runId}/tool-messages 回传客户端工具结果时返回 400 INVALID_REQUEST?

原因与排查步骤: 最常见的两类原因如下:

Q3:上传 Skill 压缩包时报错失败,如何快速定位是格式问题还是元数据问题?

原因与排查步骤: 请对照以下清单逐项核查压缩包:


相关文档