工程化工作流 系统设计：工具调用要先定义权限和状态
一、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 系统设计要先定义权限、状态、工具协议和失败边界。模型可以负责计划和推理，但工具执行必须受确定性策略约束，尤其要控制循环、重试和高风险动作确认。