Agent 工具调用怎么设计：读、写、执行要分清

Agent 真正变得有用，往往是从“只回答”进入“会调用工具”。它可以查知识库、读数据库、创建任务、生成文件、调用接口、触发工作流。但工具调用越强，权限和风险越高。新手设计 Agent 时，必须把工具分成只读、写入和外部执行三类。

这篇是草稿，正式发布前需要核对具体模型和框架接口。Agent 部署总览可以看 Agent 部署怎么做，MCP 相关概念可以看 MCP 是什么。

适合谁

适合想让 Agent 连接搜索、知识库、CRM、表格、工单、代码仓库、邮件草稿或内部系统的人。你可能已经有聊天功能，但希望它能完成更具体的动作。

也适合给客户做 Agent 方案评估的人。客户经常说“让 AI 自动处理”，但你要拆清哪些动作只是读取，哪些动作会修改数据，哪些动作影响外部用户。

不适合谁

不适合一开始就给 Agent 全部权限的人。没有测试、日志和人工确认时，工具调用越多，越容易出现不可控结果。

如果工具涉及付款、账号权限、生产配置、客户数据、删除内容或发送外部消息，新手不应该独立上线。

只读工具

只读工具包括搜索资料、读取文档、查询订单、查看状态、读取日志。它们风险相对低，但仍然涉及权限和隐私。

只读不代表可以随便读。Agent 只能读取当前用户有权访问的内容，检索结果也要按权限过滤。

写入工具

写入工具包括创建任务、更新表格、写入数据库、保存记忆、生成文档、修改配置。它们会改变系统状态，因此需要更严格的确认。

写入前最好让 Agent 生成计划，让用户确认后再执行。执行后要记录写了什么、写到哪里、谁确认的。

外部执行工具

外部执行包括发送消息、调用第三方 API、运行脚本、部署服务、触发工作流。这类动作影响更大，必须设计审批和回退。

不要让 Agent 在没有确认的情况下执行高影响动作。能先生成草稿，就不要直接发送；能先预览，就不要直接写入生产。

工具描述要清楚

工具名称、参数、返回值和限制要写清楚。模型不知道工具真实能力，只能根据描述决定什么时候调用。

描述含糊会导致误用。比如“updateUser”就不如“updateUserDisplayNameOnly”安全明确。

日志和失败处理

每次工具调用都要记录：用户请求、Agent 计划、工具参数、返回结果、错误和确认人。失败时要能说明原因，而不是让用户看到一团错误。

如果工具失败，Agent 应该停下来、解释、请求补充信息或建议人工处理。

工具调用还要做 dry run 思路。也就是先让 Agent 生成将要执行的动作和参数，给用户预览，不直接执行。用户确认后再真正调用工具。这个流程会慢一点，但能显著降低误操作概率，特别适合写入和外部执行工具。

上线前要准备一组“坏情况”测试：用户让 Agent 做超出权限的事，工具返回空结果，参数缺失，外部服务超时，用户中途取消，前一步结果和后一步冲突。一个可靠 Agent 不只是会成功执行，也要会在这些情况下停下来。

交付时还要写清每个工具的动作边界。比如“可以读取订单状态，但不能修改订单”“可以生成邮件草稿，但不能直接发送”“可以创建任务，但需要用户确认标题和负责人”。这类说明能减少客户对 Agent 能力的误解。

如果客户要求更多自动化，可以先做分阶段开放：第一阶段只读，第二阶段生成草稿，第三阶段人工确认后写入，第四阶段才讨论有限自动执行。这样既能展示价值，也不会一开始就把风险推到最高。

风险提醒

工具调用的核心风险是权限过大和动作不可追踪。Agent 回答错了可以改，执行错了可能造成真实损失。

上线前要用异常场景测试：参数缺失、权限不足、工具超时、用户拒绝、返回结果不一致。测试通过后再逐步开放。

具体步骤

第一步，列出 Agent 需要调用的所有工具。

第二步，把工具分成只读、写入和外部执行三类。

第三步，为每个工具定义权限、参数、确认点和日志。

第四步，测试正常、失败、越权和用户取消场景。

第五步，形成工具权限表。需要模板或人工协助，可以从 工具导航 进入。

免责声明

本文是 Agent 工具调用设计草稿，不构成生产安全或框架实现建议。正式发布前需要人工核对模型接口、工具权限和平台规则。涉及生产系统时，请由专业人员复核。