文档中心
费用中心控制台

构建知识与工单协同的服务台助手 ​

连接 AI 助手

本篇是在工单助手实战基础上的组合扩展练习：为已经通过 API 接入智能体的业务客户端增加知识检索。员工询问制度时，智能体从团队维护的资料中检索；员工查询工单时，智能体把查询请求交给业务调用方执行；一个问题同时包含制度和工单信息时，回答会分别说明信息来源。

完成后，可以通过一个组合问题确认：同一次调用既检索了制度资料，也由业务调用方执行了工单查询，最终回答没有混淆两种来源。

本实战将帮助你理解 ​

  • 知识库组如何提供团队维护的制度内容，用户工具包如何让业务调用方提供实时工单数据。
  • 为什么用户工具包只定义工具契约，实际权限校验和工单查询仍由调用方应用完成。
  • 如何用 Trace 区分知识检索、工具中断、调用方返回结果和最终回答。

准备条件和样例 ​

开始前需要：

  • 一个已经完成基础回复验证的模型凭证和模型。尚未验证时，先完成创建第一个智能体并完成基础验证。
  • 创建 Collection、知识库组、智能体模板、智能体实例和 WebSocket 渠道账号及 Token 的权限。
  • 上传 Markdown 文件的权限。
  • 已完成工单助手实战，并准备能提交任意测试问题、处理工具中断和接收最终结果的业务客户端。本篇不提供组合客户端脚本。
  • 可以访问智能体开发服务平台（AgentWorks）调用 API 的网络环境。

准备以下资料和工具定义：

本文使用固定的 recipe-service-desk-* 名称，便于识别和清理实战资源。如果环境中已经存在同名资源，请统一追加简短后缀，例如 -team-a；不要修改或复用来源不明的同名资源。

样例资料和工单均为虚构内容。不要把模型凭证、WebSocket Token、客户资料或真实工单数据写入样例文件。

理解信息从哪里取得 ​

图表预览

知识检索由 AgentWorks 运行。get_ticket_status 是用户工具，实际业务查询由调用方应用运行。系统提示词帮助智能体选择信息来源，但不能替代调用方的权限检查和参数校验。参见用户工具包中的工具在哪里运行？。

下面先由 AgentWorks 配置者准备知识、智能体和 Token；到“运行固定验收问题”时，再由业务调用方使用已准备的 API 客户端处理工具中断。

操作账号需有创建和管理知识库资源、智能体及 WebSocket 渠道账号的权限。

准备知识资源 ​

  1. 打开 知识库管理，创建名为 recipe-service-desk-knowledge-v1 的 Collection。

    打开知识库管理

  2. 上传知识助手样例包中的 support-policy.md 和 escalation-guide.md，选择 生成 RAG 知识库。

  3. 等待两份文件的构建任务成功，并打开 日志 确认没有解析、分块、Embedding 或写入错误。

  4. 打开 知识库组，创建名为 recipe-service-desk-rag-template-v1 的知识库组模板，将 默认检索条数（top_k） 保持为 4，选择刚创建的 Collection，并记录页面显示的 Collection 资源 ID。

    打开知识库组

  5. 从该模板创建名为 recipe-service-desk-rag-instance-v1 的知识库组实例。

继续前，确认知识库组实例的 集合数 为 1。打开实例详情，在 引用的知识库集合 中确认包含刚才记录的 Collection 资源 ID；Collection 的构建历史应显示两份文件均已成功处理。更完整的入库检查参见构建可追溯的企业知识助手。

创建服务台助手 ​

  1. 打开创建智能体模板页面。

    创建智能体模板

  2. 将 模板名称 设为 recipe-service-desk-assistant-v1，并选择可用的 模型凭证和模型。

  3. 在 系统提示词 中输入：

    language-text
    你是企业服务台助手。
制度、响应目标和升级流程必须先检索已连接的知识库，只根据检索结果回答。
当前工单状态必须调用 get_ticket_status，不要根据制度资料或对话内容猜测。
一个问题同时包含制度和工单信息时，分别说明“制度资料”和“工单系统”提供了哪些信息。
资料没有答案或工具返回错误时，明确说明没有取得对应信息，不要编造政策、金额、状态或负责人。

  4. 在 插件配置 中添加 知识库 RAG - 实例，选择 recipe-service-desk-rag-instance-v1。

  5. 再次选择 添加插件，选择 用户工具包。

  6. 把工单助手样例包中 user-toolkit.json 的完整内容粘贴到 默认值，选择 格式化。

    注意

    用户工具包只描述调用方式

    user-toolkit.json 告诉智能体工具名称、参数和返回结构，但不会连接或执行工单系统。业务调用方收到工具中断后，先校验工具名称和参数，再从 tickets.json 取得结果并返回给智能体。接入真实系统时，调用方仍要执行用户身份和业务权限检查。

  7. 关闭默认开启的 启用文件系统，不添加其他能力。本实战只测试知识检索和调用方执行的用户工具。

  8. 创建智能体模板，并在 插件 中确认知识库组实例和用户工具包都已关联。

  9. 创建名为 recipe-service-desk-assistant-test-v1 的智能体实例。

继续前，确认智能体实例的来源模板同时显示知识库组实例和用户工具包。用户工具需要业务调用方执行，不能用网页版对话代替组合客户端验收。

准备 API 接入和 Token ​

  1. 打开 渠道账号，按通过 API 调用智能体创建测试渠道账号，绑定 recipe-service-desk-assistant-test-v1。

    打开渠道账号

  2. 为该账号创建专用 WebSocket Token，并按团队策略设置有效期。仅保存在业务服务端，不写入脚本、样例包或版本控制。

  3. 使用服务提供方给出的 HTTP 地址和 WebSocket 地址配置业务客户端。

  4. 确认客户端能按可信用户身份管理会话，使用本轮请求标识关联事件，并按中断标识返回工具结果。

不要直接使用工单实战的固定问题脚本执行本篇组合问题。组合客户端需要保留知识检索的完整运行过程，同时处理中断；不能把本地查询结果直接拼成最终答案。

运行固定验收问题 ​

用准备好的 API 客户端提交以下固定问题。每项用例开启独立会话，只使用样例资料和虚构工单。客户端收到 get_ticket_status 请求后，应校验工具名称、参数和权限，再查询 tickets.json 并通过中断响应返回结果。

验证组合问题 ​

language-text
P1 事件的首次响应目标是多少？另外查询工单 INC-1024 的当前状态，并分别说明信息来源。

回答应把 15 分钟归为制度资料，把处理中和网络支持组归为工单系统。

注意

最终回答正确不表示两项能力都已运行

模型可能仅凭上下文生成看似合理的回答。请检查同一次 Trace 中的知识检索和 get_ticket_status 调用，确认制度内容来自本实战 Collection，工单结果来自调用方返回的工具结果。

服务台助手的 Trace 同时显示知识检索和工单工具调用

打开智能体实例的 Trace，确认同一次调用中包含：

  1. 指向本实战 Collection 的知识检索。
  2. 参数为 INC-1024 的 get_ticket_status 调用。
  3. 调用方返回工具结果后的最终模型输出。

完成结果：一次智能体调用同时取得制度资料和当前工单状态；最终回答分别标明两种来源，Trace 显示知识检索、工单工具中断和调用方返回结果。

如果不继续执行下一节的可选验证，请结束测试客户端并清除本次使用的临时凭证。

完成可选验证 ​

前面的组合问题已经完成本实战。需要进一步检查单一来源路由和缺失信息处理时，再运行以下固定用例。

验证制度问题 ​

language-text
P1 事件的首次响应目标是多少？

回答应包含 15 分钟，并说明信息来自制度资料。调用方不应收到 get_ticket_status 中断。

验证工单问题 ​

language-text
查询工单 INC-1024 的当前状态。

调用方应收到 get_ticket_status 中断，并从 tickets.json 返回 处理中和网络支持组。最终回答不得从制度资料猜测工单状态。

验证资料和业务数据缺失 ​

运行资料缺失问题：

language-text
P1 事件可以获得多少合同赔付？

回答应说明样例资料没有提供赔付金额，不得编造金额，也不应查询工单。

再运行不存在的工单：

language-text
查询工单 INC-9999 的当前状态。

调用方应通过 HTTP 中断响应返回失败结果，其中包含 ticket INC-9999 was not found。智能体可以说明没有取得状态，但不得编造状态或负责人。

收到工具错误后，智能体可能再次请求查询同一工单。调用方应限制重复尝试，并在达到限制后结束测试；即使智能体已经解释错误，也不把业务查询记为成功。

运行完选定用例后，结束测试客户端，清除本次使用的临时凭证。

如果验证没有通过 ​

  • 制度资料没有参与回答：确认两份文件的构建任务成功、智能体模板关联了正确的知识库组实例，并在 Trace 中核对 Collection 资源 ID。
  • 调用方没有收到工具中断：确认用户工具包包含 get_ticket_status，智能体实例已经采用当前模板配置，并检查问题是否明确要求查询当前工单状态。
  • 工具结果没有返回智能体：检查调用方的工具名称和参数允许列表、测试工单数据，以及中断响应中的记录标识；不要把本地查询结果直接拼接成最终回答来绕过中断处理。
  • Token 或 API 调用失败：核对 Token 是否有效并绑定正确渠道账号、账号是否启用，以及 HTTP 和 WebSocket 地址是否正确。不要在日志中输出 Token。

调整为自己的服务台 ​

  • 更换制度资料：为 Collection 指定内容负责人，记录文档版本和固定问题，并在每次更新后重跑制度、混合和资料缺失用例。
  • 连接真实工单系统：在调用方中替换虚构查询，同时增加用户身份、业务权限、参数校验、超时、重试边界和审计。
  • 增加写操作：为创建、更新或关闭工单增加幂等键和明确确认；不要只依赖系统提示词控制写操作。
  • 改用 MCP：业务工具已经由远程 MCP Server 提供时，使用 MCP 模板或实例，不再由调用方应用处理中断。
  • 通过渠道交付：飞书和 QQ 不会运行本地用户工具代码。渠道场景应使用平台工具包、MCP 或由业务系统通过 API 接入并执行工具。

准备上线和清理 ​

上线前应分别指定知识内容负责人和业务接口负责人，并把固定问题、工具错误、Token 轮换、Trace 检查和外部调用审计纳入变更流程。参见将智能体投入生产。

仅清理本实战创建的资源：

删除前确认没有其他智能体引用知识库组或 Collection。无法确认资源归属或引用关系时，请停止清理；不要把共享生产资料当作实战资源删除。

  1. 停止测试客户端，停用本实战创建的 WebSocket 渠道账号。
  2. 停用并删除该账号的测试 Token，再删除测试渠道账号。
  3. 删除测试智能体实例和智能体模板。
  4. 删除知识库组实例和模板。
  5. 删除本实战的构建记录。
  6. 删除 recipe-service-desk-knowledge-v1 Collection。