Docs
文档目录

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

为了让智能体从“能查资料回答问题的知识顾问”升级为“能查工单、调接口、遵循标准作业程序(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 通过以下四大支柱构建安全可控的行动闭环:

  1. AI Gateway 与 MCP 服务端业务工具挂载(/v1/agent-runtime/project/gateway):

    • 将智能体工作台与同项目下已激活(ACTIVE)且发布了区域快照的统一 AI 网关实例(如 prod-enterprise-ai-gateway,ID:gw_7194685489feb1e169548619)一键绑定。

    • Runtime 自动从绑定的 Gateway 快照中发现当前调用上下文获准使用的工具定义,并在调用前按工具的 inputSchema 严格校验模型生成的参数;工具权限与外部认证完全由服务端 Gateway 强管控,模型无法通过伪造工具名越权调用。

  2. 客户端工具(Client Tool)5 步暂停、回传与同 Run 恢复协议(/runs/{runId}/tool-messages):

    • 当智能体需要执行必须由业务应用或客户端本地完成的动作(如读取本地上下文、弹窗请用户确认订单操作、调用内网受限组件)时,模型发出 toolCallSource: "CLIENT" 的工具调用,当前 Run 自动暂停并进入 WAITING_CLIENT_TOOL 状态。

    • 宿主应用执行完本地操作后,通过 POST /v1/agent-runtime/project/runs/{runId}/tool-messages 回传结构化结果(若工具声明了 outputSchema,服务端会自动校验回传内容)或错误信息,同一个 Run 随即重新入队(QUEUED $\rightarrow$ RUNNING)继续推理直至终态,无需新建第二条 Run。

  3. 项目级 Skill 技能包全生命周期管理(/v1/agent-runtime/project/skills):

    • 支持上传 .zip、.tar.gz 或 .tgz 格式(<= 10 MiB)的标准化技能包(根目录包含带 YAML Frontmatter 的 SKILL.md 及辅助参考文档),支持列表查询(返回 skill_count、skill_limit 与 skill_catalog_hash)、详情读取、整包替换与删除。

    • 模型在 ReAct 推理过程中可按任务需要自主发现并按需读取相关 Skill 的作业指导说明,避免将成百上千行的全部业务 SOP 硬塞进 system_prompt 挤占固定上下文窗口。

  4. 全链路 Trace 跳转与 Dataset RAG 四维质量评估闭环:

    • 每次运行生成的 ASSISTANT 消息均携带关联 trace_id,支持一键跳转至 智能体运维 → 链路(Traces) 查看 ATIF-v1.8 规范轨迹与瀑布图。

    • 在 智能体运维 → 数据集(Datasets) 中,可直接将项目智能体工作台选为评测目标,一键运行 检索查询质量、上下文相关性、答案忠实度 与 答案准确性 四大 RAG 指标评估,并启用模型辅助根因分析(RCA)生成可落地的优化建议。


核心概念与架构

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

维度服务端业务工具(Gateway / MCP Tool)客户端工具(Client Tool)技能说明包(Skill Package)
核心用途由平台后端直接调用企业内部微服务、数据库查询或外部 MCP Server 接口交由客户前端或业务宿主应用在本地环境执行操作并将结果回传给同一条 Run为模型提供按需查阅的标准化任务指令(SKILL.md)、领域规范与参考资料
定义与管理位置在同项目 AI 网关(/ai-gateway) 中注册、审批并发布网关快照,通过 PUT /project/gateway 绑定在绑定网关的已发布快照中提供,包含输入定义和可选的 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项目 API Key 调用时 JSON 正文必填 userId;控制台会话可省略202 Accepted目标 Run 处于 WAITING_CLIENT_TOOL 状态;用户身份与 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 模式与已发布网关快照

  1. 表模式要求:绑定 AI Gateway 的项目需使用 OceanBase Shared V2 存储模式。

  2. 网关实例与快照就绪:在项目左侧导航 AI 网关(/ai-gateway) 中,确认已创建网关实例 prod-enterprise-ai-gateway(ID:gw_7194685489feb1e169548619),已在 工具与智能体(/ai-gateway/tools-agents) 中注册并授权了业务工具,且已发布了当前区域可用的运行时快照(详见统一 AI 网关)。

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 绑定:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"

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

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

{
  "gateway_id": "gw_7194685489feb1e169548619",
  "created_at": "2026-10-22T09:10:00Z"
}
(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 2. 查询当前工作台已绑定的 AI Gateway
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/gateway" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-
)

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

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

网关工具的 Schema 在 AI Gateway 中定义,并随已发布的网关快照提供。以订单/工单状态查询工具为例:


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

当本次运行可用的客户端工具被模型选中时,事件中标记为 toolCallSource: "CLIENT"。下面以绑定网关提供的客户端工具为例,介绍应用如何完成本地执行与结果回传;知识库的内置确认工具属于独立场景。

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

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

  1. TOOL_CALL_START:{"type": "TOOL_CALL_START", "toolCallId": "call_cli_9001", "toolCallName": "query_order_status", "toolCallSource": "CLIENT"}——应用按唯一的 toolCallId 建立本地待处理记录;

  2. TOOL_CALL_ARGS:按 toolCallId 拼接 delta 字符串片段;

  3. TOOL_CALL_END:参数传输完毕,解析拼接后的 JSON 得到 {"order_id": "ORD-1003"}。

步骤 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 示例:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/tool-messages" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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 示例:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/tool-messages" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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_FINISHED)、失败(RUN_ERROR),或再次等待客户端工具。


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

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

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

  1. 压缩包格式与体积限制:仅支持 .zip、.tar.gz 或 .tgz 格式,单个压缩包文件大小 <= 10 MiB,且归档内不能包含路径穿越(..)或非法符号链接。

  2. 根目录 SKILL.md 与 YAML Frontmatter 规范: 压缩包根目录必须包含 SKILL.md 文件,且文件开头必须包含以下 YAML Frontmatter 元数据:

    • name:必填,长度为 1~64 个字符,仅允许使用小写英文字母、数字或单个连字符 -(正则:^[a-z0-9]+(-[a-z0-9]+)*$,禁止大写字母、下划线或连续连字符 --);

    • description:必填,长度为 1~1024 个字符,简要说明该技能的适用场景(模型根据此描述决定何时按需读取该技能全文)。

标准 SKILL.md 示例:

---
name: ob-troubleshooting-sop
description: 排查 OceanBase 4013 内存分配失败的示例流程;需结合日志和资源指标定位具体原因。
---

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

1. **确认故障码与版本**:确认报错码、OceanBase 版本和错误发生的操作;4013 表示内存分配失败,不能仅凭错误码认定具体原因。
2. **检索并核实证据**:调用 `knowledge_retrieve` 查询相关排障资料,结合错误日志、租户和节点内存指标判断。
3. **输出排查结论**:说明已确认的证据、尚需核实的原因和下一步检查,并保留知识来源。

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

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

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

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 1. 上传新 Skill 技能包 (POST /v1/agent-runtime/project/skills)
# 注意:使用 --form 'file=@...' 自动生成 multipart/form-data boundary,不要手写 Content-Type boundary
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/skills" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  --form 'file=@./ob-troubleshooting-sop.zip'
)

预期响应(HTTP 201 Created):

{
  "skill_id": "skl_01j8xa1b2c3d4e5f6g7h8j9k0m",
  "name": "ob-troubleshooting-sop",
  "description": "排查 OceanBase 4013 内存分配失败的示例流程;需结合日志和资源指标定位具体原因。",
  "front_matter": {
    "name": "ob-troubleshooting-sop",
    "description": "排查 OceanBase 4013 内存分配失败的示例流程;需结合日志和资源指标定位具体原因。"
  },
  "content_hash": "sha256_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
  "created_by": "user_admin_001",
  "created_at": "2026-10-22T09:25:00Z",
  "updated_at": "2026-10-22T09:25:00Z"
}
(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 2. 列出当前项目全部已上传的 Skill 及容量配额 (GET /v1/agent-runtime/project/skills)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/skills" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-
)

预期响应(HTTP 200 OK):

{
  "items": [
    {
      "skill_id": "skl_01j8xa1b2c3d4e5f6g7h8j9k0m",
      "name": "ob-troubleshooting-sop",
      "description": "排查 OceanBase 4013 内存分配失败的示例流程;需结合日志和资源指标定位具体原因。",
      "front_matter": {
        "name": "ob-troubleshooting-sop",
        "description": "排查 OceanBase 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 判断剩余可上传槽位,切勿在业务代码中硬编码固定上限。

将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),确认项目和凭据属于该环境。各操作相互独立,请按需执行。 请将示例中的 Skill ID 替换为确认过的目标 ID。

  1. 查询单个 Skill 元数据 (GET /v1/agent-runtime/project/skills/{skillId})

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}"
)
  1. 使用新版压缩包整包替换已有 Skill (PUT /v1/agent-runtime/project/skills/{skillId})

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    --form 'file=@./ob-troubleshooting-sop-v2.zip'
)
  1. 删除不再使用的 Skill (DELETE /v1/agent-runtime/project/skills/{skillId} -> 204 No Content)。确认不再使用后再执行。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -i -X DELETE "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}"
)

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

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

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

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

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

  1. 发起数据集评测运行:

    • 进入 智能体运维 → 数据集,选择黄金评测集(如 enterprise-support-golden-v1)$\rightarrow$ 切换到 运行(Runs) 页签 $\rightarrow$ 单击 创建运行(Create run);

    • 第一步(选择评测对象):选择 智能体工作台(Agent Workbench) 及当前运行配置;

    • 第二步(选择 RAG 评估器):从内置评估器库中同时勾选四大核心 RAG 指标(每個指标保留独立变量映射,并使用项目默认评估模型 Judge LLM)。

  2. 四大 RAG 评测指标及证据判定口径表:

评估指标名称评分比对的真实运行证据质量度量维度关键前置要求与边界说明
检索查询质量(Query Quality)本轮用户原始问题 vs 智能体实际发出的 knowledge_retrieve 检索 Query评估模型改写或生成的检索词是否忠实保留了用户意图与关键限定条件(如故障码 4013)要求本次 Run 实际保存了与样本身份一致的可信 RAG 检索证据
上下文相关性(Context Relevance)用户问题 vs 实际进入最终回答步骤的检索片段集合(含图片理解描述与来源定位)评估知识库召回的文档切片与用户问题的相关程度多个检索步骤按最终模型消息顺序合并;若证据缺失或被压缩摘要截断,标记为“证据不足”而不强行用空上下文打分
答案忠实度(Faithfulness)智能体最终回答 vs 实际送入模型的检索片段评估回答中的事实主张是否有据可查、是否存在脱离检索证据的幻觉(Hallucination)严格比对当次冻结的检索片段,不会重新查询当前知识库去替历史运行补证据
答案准确性(Answer Accuracy)智能体最终回答 vs 数据集样本中冻结的 标准答案(expectedOutput)评估最终回答是否正确且完整覆盖了标准答案的核心要点必须提供样本标准答案(expectedOutput);哪怕答案忠实度高,若遗漏了关键排障步骤,答案准确性依然能敏锐识别出低分
  1. 查看模型辅助根因分析(RCA)与优化建议: 评测完成后,点开低分样本的 评分详情(Score Details)。当开启项目“使用模型进行根因分析”时,系统会自动对比「用户问题 $\rightarrow$ 检索 Query $\rightarrow$ 召回切片 $\rightarrow$ 最终回答 $\rightarrow$ 冻结标准答案」,定位究竟是检索改写偏差、知识库切片相关性不足还是模型总结遗漏,并基于当前有效配置参数给出可落地的调优建议(由管理员确认后自主决定是否修改工作台配置,系统不会未经授权自动篡改线上配置)。


常见问题与排障

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

原因与排查步骤:

  1. 检查项目表模式与服务开关:绑定 AI Gateway 要求项目必须为 OceanBase Shared V2 表模式,且已在 设置 → 概览 → 服务 中开启了 AI Gateway 服务。

  2. 检查网关状态与区域快照:目标 gateway_id(如 gw_7194685489feb1e169548619)必须归属于当前项目、状态为 ACTIVE,且已在 AI 网关 控制台中成功发布了至少一个可用快照(绑定从未发布过快照的空网关会稳定返回 400)。

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

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

  1. content 字段未序列化为字符串:ToolMessage.content 必须是 JSON 序列化后的字符串(例如 "{\"status\":\"shipped\"}"),如果直接传了 JSON 对象 {"status": "shipped"} 会因类型不匹配被拒绝。

  2. 违反了工具声明的 outputSchema:若该客户端工具在 AI Gateway 中定义了 outputSchema(例如要求必填 order_id 和枚举值 status),而回传的 content JSON 缺少必填字段或包含 additionalProperties: false 禁止的额外字段,服务端 Schema 校验器会直接拒绝回传。

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

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

  1. 归档结构:解压后 SKILL.md 必须直接位于归档根目录(即 unzip -l your-skill.zip 应看到顶层的 SKILL.md,而不是嵌套在 my-folder/SKILL.md 子目录下一层);

  2. YAML Frontmatter 格式:SKILL.md 顶部必须以 --- 包裹 name 和 description;其中 name 只能包含 1~64 位小写字母、数字和单个连字符(如 customer-support-v1),不能有大写字母、空格、下划线 _ 或连续连字符 --;

  3. 体积与数量配额:压缩包大小不能超过 10 MiB,且当前项目已上传的 skill_count 未达到 GET /skills 返回的 skill_limit。


相关文档