Agent 工具调用实战：从函数调用到可靠执行的设计方法

开头痛点：为什么 Agent 会“会想但不会做”

很多团队在接入大模型后，很快会遇到同一个问题：模型能理解需求、能给出方案，却无法稳定完成真实任务。原因通常不在“模型不够聪明”，而在工具调用链路没有设计好。

Agent 的价值不是把回答写得更像人，而是让模型能够调用搜索、数据库、代码执行、工作流、业务系统等外部工具，把“判断”变成“行动”。但如果工具描述模糊、参数约束不足、权限边界不清、结果校验缺失，Agent 就容易出现误调用、漏调用、重复调用，甚至把错误结果当成事实继续推理。

本文系统讲清楚 Agent 工具调用的核心概念、执行流程、工程实践、提示词模板与常见误区，适合正在做 AI 应用、智能客服、数据分析助手、办公自动化 Agent 的产品和技术团队参考。

核心概念：Agent 工具调用到底是什么

Agent 工具调用，是指大模型在理解用户目标后，选择合适的外部能力，并按结构化参数发起调用，再基于工具返回结果继续推理或完成任务的过程。

它通常包含四个要素：

1. 工具定义：告诉模型这个工具能做什么、什么时候用、输入输出是什么。
2. 调用决策：模型判断是否需要调用工具，以及调用哪一个工具。
3. 参数生成：模型把自然语言需求转换成结构化参数，例如 JSON、表单字段或 API 参数。
4. 结果消费：模型读取工具返回结果，进行校验、总结、下一步规划或最终回复。

从工程视角看，工具调用不是简单的“给模型一个 API”。更准确地说，它是一套围绕大模型的任务执行协议：模型负责理解、规划和参数生成；工具负责确定性执行；系统负责权限、审计、重试和安全控制。

实践方法：设计可靠工具调用链路的六个步骤

1. 明确工具边界，不要让一个工具什么都做

一个好工具应该目标单一、输入明确、输出稳定。例如“查询订单状态”和“取消订单”应拆成两个工具，而不是合并成一个万能订单工具。边界越清晰，模型越容易选对工具，权限也更容易控制。

工具命名建议使用动词加对象，例如：search_documents、create_ticket、query_customer_profile。避免使用handle_request、do_task这类含义过宽的名称。

2. 用结构化 Schema 约束输入

工具参数必须可验证。推荐为每个字段定义类型、是否必填、枚举值、长度限制和示例。

例如：

{"tool":"search_documents","description":"根据关键词检索内部知识库文档","parameters":{"query":"string，必填，用户检索关键词","top_k":"integer，可选，默认 5，范围 1-10","date_range":"string，可选，格式 YYYY-MM-DD..YYYY-MM-DD"}}

Schema 的作用不是为了好看，而是减少模型自由发挥的空间，让工具调用从“猜测”变成“可验证的结构化动作”。

3. 在工具描述中写清楚“何时不要调用”

很多工具调用失败并不是因为模型不会用，而是因为工具描述只写了适用场景，没写禁用场景。建议每个工具都包含三类信息：

• 适合什么时候调用；
• 不适合什么时候调用；
• 调用前需要满足什么条件。

例如：“只有当用户明确要求查询实时库存时才调用库存接口；如果用户只是询问库存规则，不要调用接口，直接回答规则说明。”

4. 增加调用前确认与权限分级

涉及删除、支付、发布、发消息、修改配置等高风险行为时，Agent 不应自动执行。更稳妥的做法是把工具分为只读、低风险写入、高风险写入三类。

• 只读工具：可自动调用，例如搜索、查询、读取公开信息；
• 低风险写入：可在明确任务范围内执行，例如创建草稿、生成临时文件；
• 高风险写入：必须二次确认，例如发布文章、删除数据、付款、修改安全配置。

这能显著降低 Agent 从“自动化助手”变成“自动化事故源”的概率。

5. 对工具结果做校验，而不是直接相信

工具返回结果并不等于最终事实。系统需要检查状态码、关键字段、时间戳、数据完整性和异常信息。模型也应被要求在关键场景中引用工具返回的证据。

例如保存草稿后，不只看接口是否返回 200，还要确认：saved=true、not_published=true、草稿 ID 存在、标题与正文标记匹配。

6. 记录调用日志，方便追踪与复盘

生产环境中的 Agent 工具调用必须可观测。建议记录：用户请求、模型选择的工具、参数、工具结果、失败原因、重试次数、最终回复。日志不是为了监控模型，而是为了在出错时知道问题发生在哪一层：理解、规划、参数、接口还是权限。

示例/模板：一个可直接复用的工具调用提示词

下面是一段适合放入 Agent 系统提示词或开发者提示词中的模板：

你可以调用工具完成任务。调用前必须遵守以下规则： 1. 只有当工具能提供比直接回答更准确、更新或可执行的信息时，才调用工具。 2. 调用工具前，先判断用户目标、所需信息和风险等级。 3. 严格按照工具 Schema 生成参数，不要编造不存在的字段。 4. 如果必填参数缺失，先向用户澄清，不要猜测。 5. 对高风险操作，如删除、支付、发布、修改权限，必须先说明影响并获得明确确认。 6. 工具返回后，检查状态、关键字段和错误信息，再给出结论。 7. 如果工具失败，说明失败阶段和可替代方案，不要假装成功。

一个典型工具定义可以写成：

{"name":"create_csdn_draft","description":"将 Markdown 内容保存为 CSDN 草稿。只保存草稿，绝不发布。适用于用户明确要求生成 CSDN 草稿的场景。","parameters":{"title":{"type":"string","description":"文章标题，建议 15-40 个中文字符"},"markdown_file":{"type":"string","description":"本地 Markdown 文件路径"},"summary":{"type":"string","description":"256 字以内的文章摘要"}},"risk_level":"low_write","success_check":["saved=true","not_published=true","draft_id exists"]}

常见误区：Agent 工具调用最容易踩的坑

误区一：工具越多，Agent 越强

工具数量增加会提高模型选择成本。如果工具命名相似、功能重叠，模型更容易选错。更好的策略是先设计高频、稳定、边界清晰的工具，再逐步扩展。

误区二：把业务规则全部塞进工具描述

工具描述应简洁清楚，复杂业务规则应由业务系统或规则引擎承担。让模型同时记住大量规则并做精确判断，稳定性通常不如显式校验。

误区三：只关注调用成功率，不关注任务成功率

工具被成功调用，不代表用户任务完成。例如搜索工具返回了结果，但结果不相关；草稿保存成功，但标题错误；工单创建成功，但分类错了。评估指标应从 API 成功率升级到任务完成率。

误区四：没有失败分支

真实环境中，接口超时、权限不足、登录失效、参数缺失都很常见。Agent 需要明确失败后的策略：重试、降级、澄清、暂停或交给人工，而不是继续编造结果。

误区五：忽视安全边界

任何能对外发送、发布、删除、支付、修改配置的工具，都必须有确认机制和审计记录。Agent 的自动化能力越强，越需要把“不能做什么”写清楚。

总结：可靠的 Agent，关键在工具工程

Agent 工具调用的本质，是把大模型的语言理解能力接入真实世界的可执行系统。要让 Agent 真正可用，不能只依赖模型变聪明，而要把工具定义、参数约束、权限控制、结果校验和日志观测一起做好。

一句话总结：好的 Agent 工具调用设计，不是让模型“随便用工具”，而是让模型在正确的边界内，用正确的参数，调用正确的工具，并对结果负责。

对于技术团队来说，最值得优先投入的不是一次性接入很多 API，而是先把少数关键工具做稳定、做可验证、做可追踪。这样构建出来的 Agent，才有机会从演示级 Demo 走向生产级应用。