构建知识与工单协同的服务台助手
本实战构建一个通过 Invoke API 使用的服务台助手。员工询问制度时，智能体从团队维护的资料中检索；员工查询工单时，智能体把查询请求交给业务调用方执行；一个问题同时包含制度和工单信息时，回答会分别说明信息来源。
完成后，可以验证五种情况：只查制度、只查工单、同时查询两类信息、资料没有答案，以及工单不存在。
准备条件和样例
开始前需要：
- 一个可用的模型凭证和模型。
- 创建 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 调用方运行。系统提示词帮助智能体选择信息来源，但不能替代调用方的权限检查和参数校验。
以下入口仅在租户已启用知识库和 API 调用能力时可用。按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。
准备知识资源
- 按照构建可追溯的企业知识助手中的步骤，创建名为
recipe-service-desk-knowledge-v1的 Collection，并上传support-policy.md和escalation-guide.md。 - 等待两份文件的构建任务成功，并打开 日志 确认没有解析、分块、Embedding 或写入错误。
- 创建名为
recipe-service-desk-rag-template-v1的知识库组模板，将 默认检索条数（top_k） 保持为4，并选择刚创建的 Collection。 - 从该模板创建名为
recipe-service-desk-rag-instance-v1的知识库组实例。
检查点 1：知识库组实例显示目标 Collection，Collection 的构建历史显示两份文件均已成功处理。
创建服务台助手
打开创建智能体模板页面。
将 模板名称 设为
recipe-service-desk-assistant-v1，并选择可用的 模型凭证和模型。在 系统提示词 中输入：
language-text你是企业服务台助手。 制度、响应目标和升级流程必须先检索已连接的知识库，只根据检索结果回答。 当前工单状态必须调用 get_ticket_status，不要根据制度资料或对话内容猜测。 一个问题同时包含制度和工单信息时，分别说明“制度资料”和“工单系统”提供了哪些信息。 资料没有答案或工具返回错误时，明确说明没有取得对应信息，不要编造政策、金额、状态或负责人。在 插件配置 中添加 知识库 RAG - 实例，选择
recipe-service-desk-rag-instance-v1。再次选择 添加插件，选择 用户工具包。
把工单助手样例包中
user-toolkit.json的完整内容粘贴到 默认值，选择 格式化。创建智能体模板，并在 插件 中确认知识库组实例和用户工具包都已关联。
创建名为
recipe-service-desk-assistant-test-v1的智能体实例。
检查点 2：智能体实例的来源模板同时显示知识库组实例和用户工具包，Playground 显示 已连接。
开启 API 调用并创建 Token
打开测试智能体实例的 API 调用。
开启 API 调用状态，复制完整 Invoke URL。
打开 凭证管理。
在 Agent API Token 中创建一个绑定到
recipe-service-desk-assistant-test-v1的 Token，并按团队策略设置有效期。立即把只显示一次的 Token 明文放入当前终端会话使用的安全位置。不要把 Token 写入脚本、样例包或版本控制。
检查点 3：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 事件的首次响应目标是多少？"回答应包含 15 分钟，并说明信息来自制度资料。调用方不应收到 get_ticket_status 中断。
验证工单问题
node service-desk-assistant-client.mjs \
"查询工单 INC-1024 的当前状态。"调用方应收到 get_ticket_status 中断，并从 tickets.json 返回 处理中和网络支持组。最终回答不得从制度资料猜测工单状态。
验证混合问题
node service-desk-assistant-client.mjs \
"P1 事件的首次响应目标是多少？另外查询工单 INC-1024 的当前状态，并分别说明信息来源。"回答应把 15 分钟归为制度资料，把工单状态和负责团队归为工单系统。
打开智能体实例的 Trace，确认同一次调用中包含：
- 指向本实战 Collection 的知识检索。
- 参数为
INC-1024的get_ticket_status调用。 - 调用方返回工具结果后的最终模型输出。
验证资料和业务数据缺失
运行资料缺失问题：
node service-desk-assistant-client.mjs \
"P1 事件可以获得多少合同赔付？"回答应说明样例资料没有提供赔付金额，不得编造金额，也不应查询工单。
再运行不存在的工单：
node service-desk-assistant-client.mjs \
"查询工单 INC-9999 的当前状态。"调用方会把 ERROR 结果交回智能体，其中包含 ticket INC-9999 was not found。智能体可以说明没有取得状态，但不得编造状态或负责人。
收到工具错误后，智能体可能再次请求查询同一工单。样例调用方会继续处理这类中断，但最多尝试 3 次。智能体即使在收到错误后生成了说明，调用方仍会以 ServiceDeskToolError 结束；达到尝试上限时也会以同一错误类型结束。这样可以区分“智能体已经解释失败”与“业务查询已经成功”，同时避免外部系统异常造成无休止重试。
完成测试后运行：
unset AGENTWORKS_TOKEN检查点 4：五条固定用例符合预期；混合问题的 Trace 同时显示知识检索和工单工具调用，两个缺失用例都没有产生虚构信息。
调整为自己的服务台
- 更换制度资料：为 Collection 指定内容负责人，记录文档版本和固定问题，并在每次更新后重跑制度、混合和资料缺失用例。
- 连接真实工单系统：在调用方中替换虚构查询，同时增加用户身份、业务权限、参数校验、超时、重试边界和审计。
- 增加写操作：为创建、更新或关闭工单增加幂等键和明确确认；不要只依赖系统提示词控制写操作。
- 改用 MCP：业务工具已经由远程 MCP Server 提供时，使用 MCP 模板或实例，不再由 Invoke 调用方处理中断。
- 通过渠道交付：飞书和 QQ 不会运行本地用户工具代码。渠道场景应使用平台工具包、MCP 或由业务系统通过 Invoke API 承担工具执行。
准备上线和清理
上线前应分别指定知识内容负责人和业务接口负责人，并把固定问题、工具错误、Token 轮换、Trace 检查和外部调用审计纳入变更流程。参见将智能体投入生产。
仅清理本实战创建的资源：
- 关闭测试智能体实例的 API 调用。
- 停用并删除本实战创建的 Agent API Token。
- 删除测试智能体实例和智能体模板。
- 删除知识库组实例和模板。
- 删除本实战的构建记录。
- 删除
recipe-service-desk-knowledge-v1Collection。
删除前确认没有其他智能体引用知识库组或 Collection。不要把共享生产资料当作实战资源清理。