Agent 实践
从工具调用理解 Agent 的工程边界
围绕工具调用、任务规划、状态管理和失败恢复，理解 Agent 在工程落地中的边界。
背景
Agent 的吸引力在于让模型不只生成文本，还能调用工具、读取结果、继续规划下一步。但工程落地时，真正重要的是边界控制。
如果把 Agent 理解成“让模型自己决定一切”，系统会很快变得不可测试。模型可能选择错误工具，可能重复执行同一个动作，也可能在信息不足时继续推进。对于真实产品来说，Agent 的价值不在于无限自由，而在于把模型判断放进受控流程。
我更倾向把 Agent 看成一个带工具的工作流节点：它可以根据上下文做局部决策，但必须在权限、输入输出、日志和人工审批范围内运行。
关键问题
Agent 系统至少要回答四个问题：
- 模型可以调用哪些工具。
- 每个工具的输入输出是否足够清晰。
- 任务失败时如何重试或停止。
- 人在什么节点介入审批。
工程边界
工具调用越强，约束就越重要。比如写文件、发请求、操作账号这类能力，都应该有权限边界、日志记录和可回滚策略。
我会把工具分成三类。第一类是只读工具，例如搜索、读取文档、查询状态，风险较低，但仍然要限制数据范围。第二类是可写工具，例如创建文件、修改配置、提交表单，需要明确审批或沙箱。第三类是外部副作用工具，例如发邮件、调用支付、操作线上资源，默认不应该让模型自动执行。
状态管理也是边界的一部分。Agent 每一步做了什么、为什么这样做、工具返回了什么，都应该被记录下来。否则出现错误时无法复盘，只能重新猜测模型当时的意图。
实现策略
一个更稳的实现方式是先定义固定工作流，再把模型放在其中一两个需要判断的节点。例如“读取需求 -> 生成计划 -> 等待确认 -> 执行工具 -> 汇总结果”。模型可以生成计划，也可以选择工具参数，但执行前需要校验。
工具 schema 要尽量窄。与其给一个万能的 runCommand，不如提供 searchDocs、createDraft、summarizeResult 这类语义明确的工具。工具越具体，越容易做权限控制和测试。
失败恢复也要提前设计。常见策略包括最大重试次数、相同错误停止、危险操作人工确认、输出格式校验失败时要求模型修正，以及所有执行动作保留审计日志。
结果
采用边界清晰的设计后，Agent 系统的能力看起来没有那么“自由”，但稳定性更高。对于求职项目或企业内部工具，这种设计更容易解释，也更容易上线：面试官能看到工具权限、状态流转和失败处理，而不是只看到一次成功演示。
复盘
很多场景并不需要完全开放式 Agent。固定工作流加局部模型决策，往往更稳定、更容易测试，也更适合交付。
后续如果继续扩展，我会优先补三件事：一是工具调用日志页面，二是危险工具的审批机制，三是基于固定任务集的回归测试。Agent 的成熟度不是看它能做多少事，而是看它在做错时能不能被发现、阻止和修复。
Reusable projects
关联可复用项目
本文已经进入以下工程项目；项目页提供固定版本、运行命令和结果工件。
- 已独立复现
本文把 Agent 收敛为固定工作流中的局部决策，并提出窄工具 schema、写操作审批、审计与失败恢复；本项目将这些原则具体化为 MCP 权限网关和未知终态恢复状态机。
讨论