业务工具网关(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 通过以下四大支柱构建安全可控的行动闭环:
- **AI Gateway 与 MCP 服务端业务工具挂载(
/v1/agent-runtime/project/gateway)**: - 将智能体工作台与同项目下已激活(
ACTIVE)且发布了区域快照的统一 AI 网关实例(如prod-enterprise-ai-gateway,ID:gw_7194685489feb1e169548619)一键绑定。 - Runtime 自动从绑定的 Gateway 快照中发现当前调用上下文获准使用的工具定义,并在调用前按工具的
inputSchema严格校验模型生成的参数;工具权限与外部认证完全由服务端 Gateway 强管控,模型无法通过伪造工具名越权调用。
- 将智能体工作台与同项目下已激活(
- **客户端工具(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。
- 当智能体需要执行必须由业务应用或客户端本地完成的动作(如读取本地上下文、弹窗请用户确认订单操作、调用内网受限组件)时,模型发出
- **项目级 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挤占固定上下文窗口。
- 支持上传
- 全链路 Trace 跳转与 Dataset RAG 四维质量评估闭环:
- 每次运行生成的
ASSISTANT消息均携带关联trace_id,支持一键跳转至 智能体运维 → 链路(Traces) 查看ATIF-v1.8规范轨迹与瀑布图。 - 在 智能体运维 → 数据集(Datasets) 中,可直接将项目智能体工作台选为评测目标,一键运行 检索查询质量、上下文相关性、答案忠实度 与 答案准确性 四大 RAG 指标评估,并启用模型辅助根因分析(RCA)生成可落地的优化建议。
- 每次运行生成的
核心概念与架构
服务端工具(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 Gateway | GET /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 Created | multipart/form-data 上传 file 字段(.zip/.tar.gz/.tgz,<= 10 MiB),未超过 skill_limit |
| 列出项目全部 Skill | GET /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(不直接下载二进制压缩包) |
| 整包替换已有 Skill | PUT /v1/agent-runtime/project/skills/{skillId} | 不需要(项目共享) | 200 OK | multipart/form-data 上传新的完整压缩包 file,更新 content_hash 与 updated_at |
| 删除指定 Skill | DELETE /v1/agent-runtime/project/skills/{skillId} | 不需要(项目共享) | 204 No Content | 从当前项目工作台移除该 Skill |
功能详解与操作指南
1. 绑定项目 AI Gateway 与校验工具输入/输出 Schema
1. 前置准备:确认 Shared V2 模式与已发布网关快照
- 表模式要求:AI Gateway 挂载与客户端工具要求项目运行在 OceanBase **
Shared V2** 存储模式下(传统JsonTable项目不支持启用 AI Gateway)。 - 网关实例与快照就绪:在项目左侧导航 **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 绑定:
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,接口会返回 HTTP400。当前项目接口不提供通过传入空字符串""解绑的操作。
3. 工具 inputSchema 与 outputSchema 双向校验机制
工具的 Schema 在 AI Gateway 中集中定义(**不需要在每次 POST /runs 请求中传入工具定义**)。以订单/工单状态查询工具为例:
- **输入约束(
inputSchema)**:Runtime 在模型发起工具调用时,自动使用inputSchema校验模型生成的参数 JSON:
{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"minLength": 1
}
},
"required": ["order_id"],
"additionalProperties": false
}- **输出约束(
outputSchema,可选)**:若客户端工具在 Gateway 中声明了outputSchema,当应用调用POST /runs/{runId}/tool-messages回传成功结果时,Runtime 会按本次调用保存的outputSchema严格校验content反序列化后的 JSON 结构:
{
"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 时,依次收到以下三类事件:
TOOL_CALL_START:{"type": "TOOL_CALL_START", "toolCallId": "call_cli_9001", "toolCallName": "query_order_status", "toolCallSource": "CLIENT"}——应用按唯一的toolCallId建立本地待处理记录;TOOL_CALL_ARGS:按toolCallId拼接delta字符串片段;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 字段 | 类型 | 必填 | 规范与约束说明 |
|---|---|---|---|
userId | string | 必填 | 必须与创建该 Run 的业务用户 userId 完全一致(如 "user_zhangwei_001")。 |
id | string | 必填 | 客户端生成的唯一工具消息 ID(如 "tmsg_ord1003_001");网络超时重试同一次回传时必须复用同一 id。 |
role | string | 必填 | 固定为 "tool"。 |
toolCallId | string | 必填 | 必须与服务端 TOOL_CALL_START / TOOL_CALL 消息中的 toolCallId(如 "call_cli_9001")严格一致。 |
content | string | 必填 | 成功结果的 JSON 序列化字符串(如 "{\"order_id\":\"ORD-1003\",\"status\":\"shipped\"}");失败时可传 "{}"。 |
error | string | 可选 | 当客户端工具执行失败时,传入可读错误原因描述(如 "订单系统内网连接超时")。 |
**回传成功结果 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 规范)
- 压缩包格式与体积限制:仅支持
.zip、.tar.gz或.tgz格式,单个压缩包文件大小 **<= 10 MiB**,且归档内不能包含路径穿越(..)或非法符号链接。 - **根目录
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 分布式事务锁冲突(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.md2. 上传、列出、查询、替换与删除 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 标准格式。
- 在智能体工作台每轮回答底部(或通过持久化
ASSISTANT消息中的trace_id字段),单击 查看轨迹(View Trace) 即可直达 **/console/project-default-enterprise-ai-hub-210/observability/traces**,下钻分析每一跳GENERATION(大模型调用)、RETRIEVER(知识库检索)与TOOL(网关工具执行)的耗时占比与输入输出详情(详见轨迹、会话与用户分析)。
2. 在数据集(Datasets)中对智能体工作台执行 RAG 四维质量评估与根因分析
智能体工作台不设孤立的弹窗评测按钮,而是深度复用 **智能体运维 → 数据集(/observability/datasets)** 的统一评测流水线(详见评估数据集管理与评估、评分与索引质量评测):
- 发起数据集评测运行:
- 进入 智能体运维 → 数据集,选择黄金评测集(如
enterprise-support-golden-v1)$\rightarrow$ 切换到 运行(Runs) 页签 $\rightarrow$ 单击 创建运行(Create run); - 第一步(选择评测对象):选择 智能体工作台(Agent Workbench) 及当前运行配置;
- 第二步(选择 RAG 评估器):从内置评估器库中同时勾选四大核心 RAG 指标(每個指标保留独立变量映射,并使用项目默认评估模型 Judge LLM)。
- 进入 智能体运维 → 数据集,选择黄金评测集(如
- 四大 RAG 评测指标及证据判定口径表:
| 评估指标名称 | 评分比对的真实运行证据 | 质量度量维度 | 关键前置要求与边界说明 |
|---|---|---|---|
| 检索查询质量(Query Quality) | 本轮用户原始问题 vs 智能体实际发出的 knowledge_retrieve 检索 Query | 评估模型改写或生成的检索词是否忠实保留了用户意图与关键限定条件(如故障码 4013) | 要求本次 Run 实际保存了与样本身份一致的可信 RAG 检索证据 |
| 上下文相关性(Context Relevance) | 用户问题 vs 实际进入最终回答步骤的检索片段集合(含图片理解描述与来源定位) | 评估知识库召回的文档切片与用户问题的相关程度 | 多个检索步骤按最终模型消息顺序合并;若证据缺失或被压缩摘要截断,标记为“证据不足”而不强行用空上下文打分 |
| 答案忠实度(Faithfulness) | 智能体最终回答 vs 实际送入模型的检索片段 | 评估回答中的事实主张是否有据可查、是否存在脱离检索证据的幻觉(Hallucination) | 严格比对当次冻结的检索片段,不会重新查询当前知识库去替历史运行补证据 |
| 答案准确性(Answer Accuracy) | 智能体最终回答 vs 数据集样本中冻结的 **标准答案(expectedOutput)** | 评估最终回答是否正确且完整覆盖了标准答案的核心要点 | **必须提供样本标准答案(expectedOutput)**;哪怕答案忠实度高,若遗漏了关键排障步骤,答案准确性依然能敏锐识别出低分 |
- 查看模型辅助根因分析(RCA)与优化建议: 评测完成后,点开低分样本的 评分详情(Score Details)。当开启项目“使用模型进行根因分析”时,系统会自动对比「用户问题 $\rightarrow$ 检索 Query $\rightarrow$ 召回切片 $\rightarrow$ 最终回答 $\rightarrow$ 冻结标准答案」,定位究竟是检索改写偏差、知识库切片相关性不足还是模型总结遗漏,并基于当前有效配置参数给出可落地的调优建议(由管理员确认后自主决定是否修改工作台配置,系统不会未经授权自动篡改线上配置)。
常见问题与排障
Q1:调用 PUT /v1/agent-runtime/project/gateway 绑定网关时返回 HTTP 400 或 412 是什么原因?
原因与排查步骤:
- 检查项目表模式与服务开关:绑定 AI Gateway 要求项目必须为 OceanBase **
Shared V2表模式,且已在 Settings → Overview → Services 中开启了 AI Gateway** 服务。 - 检查网关状态与区域快照:目标
gateway_id(如gw_7194685489feb1e169548619)必须归属于当前项目、状态为ACTIVE,且已在 AI 网关 控制台中成功发布了至少一个可用快照(绑定从未发布过快照的空网关会稳定返回400)。
Q2:向 /runs/{runId}/tool-messages 回传客户端工具结果时返回 400 INVALID_REQUEST?
原因与排查步骤: 最常见的两类原因如下:
- **
content字段未序列化为字符串**:ToolMessage.content必须是 JSON 序列化后的字符串(例如"{\"status\":\"shipped\"}"),如果直接传了 JSON 对象{"status": "shipped"}会因类型不匹配被拒绝。 - **违反了工具声明的
outputSchema**:若该客户端工具在 AI Gateway 中定义了outputSchema(例如要求必填order_id和枚举值status),而回传的contentJSON 缺少必填字段或包含additionalProperties: false禁止的额外字段,服务端 Schema 校验器会直接拒绝回传。
Q3:上传 Skill 压缩包时报错失败,如何快速定位是格式问题还是元数据问题?
原因与排查步骤: 请对照以下清单逐项核查压缩包:
- 归档结构:解压后 **
SKILL.md必须直接位于归档根目录**(即unzip -l your-skill.zip应看到顶层的SKILL.md,而不是嵌套在my-folder/SKILL.md子目录下一层); - YAML Frontmatter 格式:
SKILL.md顶部必须以---包裹name和description;其中name只能包含1~64位小写字母、数字和单个连字符(如customer-support-v1),不能有大写字母、空格、下划线_或连续连字符--; - 体积与数量配额:压缩包大小不能超过
10 MiB,且当前项目已上传的skill_count未达到GET /skills返回的skill_limit。