实战为知识库增加 Agent 工具调用和工作流编排码海寻道 · 大模型、智能体与 RAG 工程组件系列第 58 篇普通 RAG 适合“检索资料并回答”但企业助手常常还需要查询订单、创建工单、计算数据和请求审批。此时可以把知识库检索封装为只读工具再用工作流控制 Agent 的计划、执行和终止。一、工具清单search_knowledge在用户权限范围内检索文档 get_document_source读取可访问的原文片段 query_business_data调用只读业务 API create_ticket创建工单需要确认 request_approval发起审批流程工具描述、参数 Schema 和权限范围应由服务端维护不能由模型自由生成。每个工具还应声明只读或有副作用、超时、幂等要求、输入输出版本和失败分类。模型只能选择已注册工具并提交参数真正的用户、租户、资源和权限上下文由服务端注入。二、工具路由READ_TOOLS{search_knowledge:search_knowledge,query_business_data:query_business_data,}WRITE_TOOLS{create_ticket:create_ticket,request_approval:request_approval,}defdispatch_tool(name:str,args:dict,user:User):ifnameinREAD_TOOLS:authorize(user,name,args)returnREAD_TOOLS[name](args,user.scope)ifnameinWRITE_TOOLS:returnrequest_confirmation(user,name,args)raisePermissionError(tool not allowed)三、工作流状态classAgentState(TypedDict):question:strmessages:list[dict]tool_results:list[dict]citations:list[dict]pending_action:dict|Nonesteps:intstatus:str状态中保留结构化结果和引用 ID不要只保存一段混合文本。工作流状态应包含run_id、当前节点、尝试次数、预算、审批状态、版本和最后更新时间。长任务需要持久化 Checkpoint进程重启后从状态恢复不能靠进程内变量判断是否已经执行过工具。四、一个受控流程接收问题 ↓ 意图识别 ├── 知识问答 → search_knowledge → 生成回答 ├── 业务查询 → query_business_data → 生成回答 └── 写操作 → 展示待执行动作 → 人工确认 → 执行固定分支优先由代码控制模型只负责在允许的工具中选择不让它无限自主规划。五、工具结果和引用{tool:search_knowledge,status:ok,items:[{chunk_id:doc-001:v3:chunk-08,document_id:doc-001,snippet:……,page:6}]}最终引用由应用根据document_id和权限回查生成不能让模型任意编造来源。六、写操作必须暂停Agent准备创建工单标题……优先级高目标团队财务 ↓ 用户确认 ↓ 服务端再次校验权限和幂等键 ↓ 调用 create_ticket ↓ 保存审计记录工作流框架提供的 interrupt 或人工审批能力可以用于暂停和恢复但实际权限仍由应用层负责。审批记录应绑定具体工具、参数摘要、资源范围、影响预览、审批人和过期时间。恢复时重新检查权限和资源版本不能把旧审批当成永久授权也不能让模型自行修改待审批参数后继续执行。七、循环和成本限制MAX_STEPS8MAX_TOOL_CALLS12ifstate[steps]MAX_STEPS:return{status:limit_reached}对于相同工具和参数保存调用指纹防止 Agent 重复搜索或反复查询。工具超时、429 和权限错误要分类处理。运行时还要限制最大步数、工具次数、Token、并发分支、单租户费用和总耗时。外部副作用使用幂等键结果未知时先查询下游执行记录区分“未执行”“已执行”和“执行状态未知”避免重试造成重复操作。八、与知识库权限结合Agent 不能因为用户说“我有权限”就扩大范围。每次search_knowledge调用都从当前认证上下文生成user_id → team_scope → knowledge_base_scope → vector_filter工具结果回查、引用展示和下载链接生成也要重复授权。九、测试场景只读问题能正确检索并引用无权限文档不会出现在候选写操作会暂停等待确认用户拒绝后不会执行工具超时不会无限循环相同事件重放不会创建重复工单外部文档中的恶意指令不会改变工具权限。结语为知识库增加 Agent不是给 RAG 套一层聊天 Prompt而是要建立工具协议、状态机、权限、审批、循环限制和审计。先把检索工具做成可靠的只读能力再逐步加入有副作用的业务工具。下一篇将为 RAG 系统补齐评估、监控、权限和审计。参考资料LangGraph 官方文档Workflows and AgentsLangGraph 官方文档InterruptsOpenAI 官方文档Function Calling本文为“码海寻道”原创技术文章。Agent 工具调用具有副作用时应进行独立的权限、审计和故障恢复评审。