工程化工作流 系统设计：工具调用要先定义权限和状态

工程化工作流 系统设计工具调用要先定义权限和状态一、Agent 不是会聊天的脚本执行器AI Agent 的吸引力在于它能理解目标、拆解任务、调用工具并根据结果继续推理。但生产中的 Agent 不能只是“模型加工具列表”。它需要清晰的权限边界、状态管理、工具协议、失败处理和审计记录。否则一旦模型误判就可能调用错误工具、重复执行动作或泄露敏感数据。设计 Agent 时第一步不是接入更多工具而是定义它能做什么、不能做什么、需要用户确认什么。读取资料、总结内容、查询状态通常风险较低写数据库、发送邮件、执行命令、发起支付则属于高风险动作。工具能力越强确定性策略越重要。二、执行链路计划、工具、观察和修正flowchart TD A[用户目标] -- B[Agent 生成计划] B -- C[权限检查] C -- D[工具调用] D -- E[观察结果] E -- F{目标是否完成} F -- 否 -- B F -- 是 -- G[输出总结]Agent 的状态应显式保存。当前目标、已执行步骤、工具返回、错误信息、用户确认和中间结论都应可追踪。只依赖模型上下文记忆很难保证长期任务稳定。尤其是多步骤任务一次网络失败或工具超时就可能让模型走偏。三、工具协议输入输出要结构化下面是一个工具调用结果结构。重点是让模型看到可解析状态而不是自由文本。from typing import Any, Literal ToolStatus Literal[ok, failed, need_confirmation] def tool_result(status: ToolStatus, data: Any None, reason: str ) - dict: if status ! ok and not reason: raise ValueError(failed tool call should include reason) return { status: status, data: data, reason: reason, }工具描述也要克制。不要把内部实现、密钥、复杂业务规则全部塞进工具说明。工具说明应写清楚用途、参数、权限和失败语义。模型不需要知道数据库连接细节只需要知道查询范围和返回结构。信息越多不一定越好过多上下文会增加误用概率。四、稳定性边界循环、重试和人工确认Agent 最常见的问题是循环执行。模型看到工具失败后继续换一种说法重试结果消耗大量资源。系统应限制最大步骤数、最大工具调用次数、总耗时和单工具重试次数。连续失败后应停止并把上下文交给用户或人工系统而不是继续“努力”。高风险工具必须有确认。确认不是弹个框这么简单应该展示动作摘要、影响对象、风险等级和可回滚性。比如 Agent 准备删除文件应展示文件路径和数量准备发送邮件应展示收件人和正文准备修改配置应展示 diff。用户确认的是具体动作不是抽象授权。审计日志决定 Agent 能不能进入真实业务。每一步应记录 requestId、用户、工具、参数摘要、策略判断、结果和耗时。出现问题时团队要能回答模型建议了什么策略允许了什么工具实际做了什么。没有审计Agent 只能停留在 Demo。生产落地补充从能跑到可维护从生产落地角度看这类方案不能只停留在主流程。更关键的是把输入校验、失败分支、资源上限和回滚路径提前写清楚。主流程通常容易在演示环境里跑通真正暴露问题的是异常输入、依赖抖动、并发放大和权限边界。一篇技术方案如果没有解释这些约束读者很难判断它能否放进真实系统。评估时建议先定义三类指标正确性指标、稳定性指标和成本指标。正确性指标回答结果是否可信稳定性指标回答失败时是否可控成本指标回答持续运行是否划算。三类指标要同时进入验收清单不能只用平均耗时或单次成功率证明方案有效。实现层面还需要把观测数据留出来。日志至少包含请求标识、关键参数摘要、耗时、状态和错误类型指标至少覆盖成功率、超时率、重试次数和队列长度必要时再补 Trace 关联上下游调用。这样排查问题时不用靠猜也能区分是代码逻辑、外部依赖还是容量配置导致的故障。五、总结AI Agent 系统设计要先定义权限、状态、工具协议和失败边界。模型可以负责计划和推理但工具执行必须受确定性策略约束尤其要控制循环、重试和高风险动作确认。