构建知识与工单协同的服务台助手
本实战构建一个通过 Invoke API 使用的服务台助手。员工询问制度时，智能体从团队维护的资料中检索；员工查询工单时，智能体把查询请求交给业务调用方执行；一个问题同时包含制度和工单信息时，回答会分别说明信息来源。
完成后，可以通过一个组合问题确认：同一次调用既检索了制度资料，也由业务调用方执行了工单查询，最终回答没有混淆两种来源。
本实战将帮助你理解
- 知识库组如何提供团队维护的制度内容，用户工具包如何让业务调用方提供实时工单数据。
- 为什么用户工具包只定义工具契约，实际权限校验和工单查询仍由 Invoke API 调用方完成。
- 如何用 Trace 区分知识检索、工具中断、调用方返回结果和最终回答。
准备条件和样例
开始前需要：
- 一个已经完成基础回复验证的模型凭证和模型。尚未验证时，先完成创建第一个智能体并完成基础验证。
- 创建 Collection、知识库组、智能体模板、智能体实例和 Agent API Token 的权限。
- 上传 Markdown 文件并开启智能体实例 API 调用的权限。
- Node.js 18 或更高版本，用于运行样例调用方。
- 可以访问智能体开发服务平台（AgentWorks）Invoke API 的网络环境。
下载并解压以下三个样例包：
可以另外查看服务台助手样例清单和校验值。
本文使用固定的 recipe-service-desk-* 名称，便于识别和清理实战资源。如果环境中已经存在同名资源，请统一追加简短后缀，例如 -team-a；不要修改或复用来源不明的同名资源。
样例资料和工单均为虚构内容。不要把模型凭证、Agent API Token、客户资料或真实工单数据写入样例文件。
理解信息从哪里取得
知识检索由 AgentWorks 运行。get_ticket_status 是用户工具，实际业务查询由 Invoke 调用方运行。系统提示词帮助智能体选择信息来源，但不能替代调用方的权限检查和参数校验。参见用户工具包中的工具在哪里运行？。
下面先由 AgentWorks 配置者准备知识、智能体和 Token；到“运行固定验收问题”时，再由业务调用方运行样例并处理工具中断。
以下入口仅在租户已启用知识库和 API 调用能力时可用。按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。
准备知识资源
- 在 知识库管理 中创建名为
recipe-service-desk-knowledge-v1的 Collection。 - 上传知识助手样例包中的
support-policy.md和escalation-guide.md，选择 生成 RAG 知识库。 - 等待两份文件的构建任务成功，并打开 日志 确认没有解析、分块、Embedding 或写入错误。
- 在 知识库组 中创建名为
recipe-service-desk-rag-template-v1的知识库组模板，将 默认检索条数（top_k） 保持为4，选择刚创建的 Collection，并记录页面显示的 Collection 资源 ID。 - 从该模板创建名为
recipe-service-desk-rag-instance-v1的知识库组实例。
继续前，确认知识库组实例的 集合数 为 1。打开实例详情，在 引用的知识库集合 中确认包含刚才记录的 Collection 资源 ID；Collection 的构建历史应显示两份文件均已成功处理。更完整的入库检查参见构建可追溯的企业知识助手。
创建服务台助手
打开创建智能体模板页面。
将 模板名称 设为
recipe-service-desk-assistant-v1，并选择可用的 模型凭证和模型。在 系统提示词 中输入：
language-text你是企业服务台助手。 制度、响应目标和升级流程必须先检索已连接的知识库，只根据检索结果回答。 当前工单状态必须调用 get_ticket_status，不要根据制度资料或对话内容猜测。 一个问题同时包含制度和工单信息时，分别说明“制度资料”和“工单系统”提供了哪些信息。 资料没有答案或工具返回错误时，明确说明没有取得对应信息，不要编造政策、金额、状态或负责人。在 插件配置 中添加 知识库 RAG - 实例，选择
recipe-service-desk-rag-instance-v1。再次选择 添加插件，选择 用户工具包。
把工单助手样例包中
user-toolkit.json的完整内容粘贴到 默认值，选择 格式化。注意
用户工具包只描述调用方式
user-toolkit.json告诉智能体工具名称、参数和返回结构，但不会连接或执行工单系统。后面的样例调用方收到工具中断后，先校验工具名称和参数，再从tickets.json取得结果并返回给智能体。接入真实系统时，调用方仍要执行用户身份和业务权限检查。关闭默认开启的 启用文件系统，不添加其他能力。本实战只测试知识检索和调用方执行的用户工具。
创建智能体模板，并在 插件 中确认知识库组实例和用户工具包都已关联。
创建名为
recipe-service-desk-assistant-test-v1的智能体实例。
继续前，确认智能体实例的来源模板同时显示知识库组实例和用户工具包，Playground 显示 已连接。
开启 API 调用并创建 Token
打开测试智能体实例的 API 调用。
开启 API 调用状态，复制完整 Invoke URL。
打开 凭证管理。
在 Agent API Token 中创建一个绑定到
recipe-service-desk-assistant-test-v1的 Token，并按团队策略设置有效期。立即把只显示一次的 Token 明文放入当前终端会话使用的安全位置。不要把 Token 写入脚本、样例包或版本控制。
继续前，确认 API 调用已开启，Invoke URL 已复制，并取得一个仍在有效期内且绑定目标实例的 Agent API Token。
运行固定验收问题
在服务台助手样例包所在目录设置临时环境变量。AGENTWORKS_TICKETS_PATH 指向工单助手样例包中的 tickets.json：
export AGENTWORKS_INVOKE_URL="{invoke_url}"
export AGENTWORKS_TICKETS_PATH="{path_to_ticket_assistant}/tickets.json"
printf 'Agent API Token: '
read -s AGENTWORKS_TOKEN
printf '\n'
export AGENTWORKS_TOKEN样例调用方会为每条问题发起新会话。先运行组合问题，确认知识检索和工单工具在同一次调用中各自提供正确的信息。
验证组合问题
node service-desk-assistant-client.mjs \
"P1 事件的首次响应目标是多少？另外查询工单 INC-1024 的当前状态，并分别说明信息来源。"回答应把 15 分钟归为制度资料，把处理中和网络支持组归为工单系统。
注意
最终回答正确不表示两项能力都已运行
模型可能仅凭上下文生成看似合理的回答。请检查同一次 Trace 中的知识检索和 get_ticket_status 调用，确认制度内容来自本实战 Collection，工单结果来自调用方返回的工具结果。
打开智能体实例的 Trace，确认同一次调用中包含：
- 指向本实战 Collection 的知识检索。
- 参数为
INC-1024的get_ticket_status调用。 - 调用方返回工具结果后的最终模型输出。
完成结果：一次 Invoke 调用同时取得制度资料和当前工单状态；最终回答分别标明两种来源，Trace 显示知识检索、工单工具中断和调用方返回结果。
如果不继续执行下一节的可选验证，请运行 unset AGENTWORKS_TOKEN，清除当前终端会话中的 Token。
完成可选验证
前面的组合问题已经完成本实战。需要进一步检查单一来源路由和缺失信息处理时，再运行以下固定用例。
验证制度问题
node service-desk-assistant-client.mjs \
"P1 事件的首次响应目标是多少？"回答应包含 15 分钟，并说明信息来自制度资料。调用方不应收到 get_ticket_status 中断。
验证工单问题
node service-desk-assistant-client.mjs \
"查询工单 INC-1024 的当前状态。"调用方应收到 get_ticket_status 中断，并从 tickets.json 返回 处理中和网络支持组。最终回答不得从制度资料猜测工单状态。
验证资料和业务数据缺失
运行资料缺失问题：
node service-desk-assistant-client.mjs \
"P1 事件可以获得多少合同赔付？"回答应说明样例资料没有提供赔付金额，不得编造金额，也不应查询工单。
再运行不存在的工单：
node service-desk-assistant-client.mjs \
"查询工单 INC-9999 的当前状态。"调用方会把 ERROR 结果交回智能体，其中包含 ticket INC-9999 was not found。智能体可以说明没有取得状态，但不得编造状态或负责人。
收到工具错误后，智能体可能再次请求查询同一工单。样例调用方最多处理 3 次，并最终以 ServiceDeskToolError 结束；即使智能体已经解释错误，也不把业务查询记为成功。
运行完选择的用例后，从当前终端移除 Token：
unset AGENTWORKS_TOKEN如果验证没有通过
- 制度资料没有参与回答：确认两份文件的构建任务成功、智能体模板关联了正确的知识库组实例，并在 Trace 中核对 Collection 资源 ID。
- 调用方没有收到工具中断：确认用户工具包包含
get_ticket_status，智能体实例已经采用当前模板配置，并检查问题是否明确要求查询当前工单状态。 - 工具结果没有返回智能体：检查调用方的工具名称和参数允许列表、
AGENTWORKS_TICKETS_PATH，以及中断响应中的调用 ID；不要把本地查询结果直接拼接成最终回答来绕过中断处理。 - Token 或 Invoke 请求失败：核对 Token 是否仍有效并绑定目标智能体实例、Invoke URL 是否完整，以及 API 调用状态是否开启。不要在日志或命令历史中输出 Token。
调整为自己的服务台
- 更换制度资料：为 Collection 指定内容负责人，记录文档版本和固定问题，并在每次更新后重跑制度、混合和资料缺失用例。
- 连接真实工单系统：在调用方中替换虚构查询，同时增加用户身份、业务权限、参数校验、超时、重试边界和审计。
- 增加写操作：为创建、更新或关闭工单增加幂等键和明确确认；不要只依赖系统提示词控制写操作。
- 改用 MCP：业务工具已经由远程 MCP Server 提供时，使用 MCP 模板或实例，不再由 Invoke 调用方处理中断。
- 通过渠道交付：飞书和 QQ 不会运行本地用户工具代码。渠道场景应使用平台工具包、MCP 或由业务系统通过 Invoke API 承担工具执行。
准备上线和清理
上线前应分别指定知识内容负责人和业务接口负责人，并把固定问题、工具错误、Token 轮换、Trace 检查和外部调用审计纳入变更流程。参见将智能体投入生产。
仅清理本实战创建的资源：
删除前确认没有其他智能体引用知识库组或 Collection。无法确认资源归属或引用关系时，请停止清理；不要把共享生产资料当作实战资源删除。
- 关闭测试智能体实例的 API 调用。
- 停用并删除本实战创建的 Agent API Token。
- 删除测试智能体实例和智能体模板。
- 删除知识库组实例和模板。
- 删除本实战的构建记录。
- 删除
recipe-service-desk-knowledge-v1Collection。