Dify Agent 实战：让 AI 调用工具，从聊天助手升级为任务执行助手

公众号：码海寻道

在前面的文章中，我们已经介绍了 Dify 的平台能力、应用选型、RAG 知识库和 Workflow 工作流。

如果说 RAG 让 AI 能够基于企业知识回答问题，Workflow 让 AI 能够进入可控流程，那么 Agent 解决的就是另一个更具想象力的问题：

如何让 AI 不只是回答问题，而是根据任务目标主动调用工具完成事情？

普通聊天助手主要负责“回答”。Agent 则更进一步，它可以根据用户意图拆解任务、选择工具、调用外部能力，并把结果整理后返回给用户。

这篇文章将从工程实践角度，讲清楚 Dify Agent 的适用场景、工具设计方法、安全边界和落地注意事项。

1. Agent 和普通聊天助手有什么区别

普通 Chat Assistant 更像一个问答助手。用户问什么，它根据模型能力、Prompt 和知识库给出回答。

Agent 则更像一个任务执行助手。它不仅理解用户问题，还可以决定是否需要调用工具。

例如用户说：

帮我查一下今天北京天气，如果下雨就提醒我带伞。

普通聊天助手可能只能根据已有知识泛泛回答。Agent 则可以调用天气查询工具，获取实时天气，再根据结果生成建议。

两者的差异可以这样理解：

Agent 的优势是灵活，但它也带来了更高的治理要求。

2. Agent 适合什么场景

Agent 适合任务路径不完全固定，且需要调用外部工具的场景。

常见应用包括：

• • 查询天气、汇率、物流、订单状态。
• • 查询企业内部系统数据。
• • 调用搜索工具补充实时信息。
• • 根据用户目标生成计划并逐步执行。
• • 自动创建工单、日程或提醒。
• • 辅助运维排查问题。
• • 根据数据生成分析结论。

这些场景有一个共同点：模型只靠生成文本不够，它需要连接外部系统。

但并不是所有复杂任务都应该使用 Agent。如果流程本身非常确定，例如固定的审批流、分类流、报告生成流，Workflow 往往更稳。

可以用一句话判断：

路径固定，用 Workflow；路径不固定，需要模型自己选工具，用 Agent。

3. 本文实战目标

本文以一个“智能订单查询助手”为例。

用户可以用自然语言提问：

帮我查一下订单 20240515001 的物流状态。

Agent 需要完成：

• • 识别用户想查询订单。
• • 提取订单号。
• • 调用订单查询工具。
• • 判断查询结果是否正常。
• • 用自然语言返回给用户。
• • 如果缺少订单号，引导用户补充。

这个案例虽然简单，但覆盖了 Agent 的核心链路：

用户意图 → 参数提取 → 工具选择 → 工具调用 → 结果解释 → 回复用户

4. Agent 的基本工作方式

Agent 通常包含几个关键组成部分：

• • 模型：负责理解用户意图、推理和决策。
• • 指令 Prompt：规定 Agent 的角色、边界和行为规范。
• • 工具 Tools：Agent 可以调用的外部能力。
• • 工具参数 Schema：规定工具需要哪些输入。
• • 执行日志：记录 Agent 调用了什么工具、传了什么参数、返回了什么结果。

一个典型执行过程是：

用户提出任务→ Agent 判断是否需要工具→ 选择合适工具→ 提取工具参数→ 调用工具→ 获取工具返回结果→ 生成最终回答

Agent 的效果不只取决于模型，也取决于工具设计是否清晰。

5. 第一步：设计工具边界

工具设计是 Agent 落地中最重要的一步。

不要一开始就给 Agent 一个功能过大的万能工具，例如：

调用内部系统 API

这种工具边界太宽，模型很难稳定使用，也不利于权限控制。

更推荐把工具设计得具体、明确，例如：

查询订单状态查询物流轨迹查询用户会员等级创建售后工单查询知识库文档

每个工具只做一类事情。

对于本文案例，可以定义一个工具：

工具名称：query_order_status工具描述：根据订单号查询订单状态、支付状态和物流信息。

工具描述要写清楚适用场景，因为 Agent 会根据描述判断是否调用它。

6. 第二步：设计工具参数

工具参数要尽量结构化、明确、可校验。

例如 query_order_status 可以设计为：

{"order_id":"订单编号，例如 20240515001"}

不要让工具接收一大段自然语言，再由后端自己猜。

不推荐：

{"query":"帮我查一下刚才那个订单"}

推荐：

{"order_id":"20240515001"}

参数越清晰，工具调用越稳定，后端校验越简单。

如果参数缺失，Agent 应该追问用户，而不是编造参数。

7. 第三步：准备工具返回格式

工具返回结果也应该结构化。

例如订单查询接口可以返回：

{"order_id":"20240515001","order_status":"shipped","payment_status":"paid","logistics_company":"顺丰速运","tracking_number":"SF1234567890","latest_trace":"包裹已到达上海转运中心","estimated_delivery_time":"2024-05-16 18:00 前"}

Agent 拿到结构化结果后，再转成自然语言：

订单 20240515001 已支付并发货，当前由顺丰速运配送。最新物流显示包裹已到达上海转运中心，预计 2024-05-16 18:00 前送达。

工具返回不要只给一段模糊文本，否则 Agent 很难稳定处理异常和不同状态。

8. 第四步：编写 Agent 指令 Prompt

Agent 的 Prompt 要强调工具使用规则和安全边界。

示例：

你是一个订单查询助手。你的任务是帮助用户查询订单状态、支付状态和物流信息。行为规则：1. 当用户需要查询订单时，必须先获取订单号。2. 如果用户没有提供订单号，请礼貌追问。3. 不要编造订单状态、物流状态或预计送达时间。4. 只有在获得订单号后，才能调用 query_order_status 工具。5. 工具返回为空或失败时，请说明暂时无法查询，并建议用户稍后重试或联系人工客服。6. 不要执行退款、改地址、取消订单等操作，只能提供查询结果。

这个 Prompt 的重点是限制 Agent 的行动范围。

Agent 越能调用外部系统，就越需要明确边界。

9. 第五步：配置 Agent 工具

在 Dify 中创建 Agent 应用后，可以为它配置可用工具。

配置时重点检查：

• • 工具名称是否清晰。
• • 工具描述是否准确。
• • 参数说明是否明确。
• • 返回结果是否稳定。
• • 是否需要鉴权。
• • 是否有调用失败处理。

如果工具连接的是企业内部 API，建议通过后端服务做一层封装，而不是让 Agent 直接接触底层复杂接口。

推荐架构是：

Dify Agent→ 业务网关或后端服务→ 内部订单系统→ 返回结构化结果

这样可以在后端统一做权限、参数校验、日志和风控。

10. 第六步：测试典型对话

Agent 配置完成后，需要测试不同类型输入。

10.1 正常查询

用户：

帮我查一下订单 20240515001 的物流状态。

期望行为：

Agent 提取订单号 → 调用 query_order_status → 返回物流状态。

10.2 缺少参数

用户：

帮我查一下订单。

期望行为：

Agent 不调用工具，而是追问订单号。

10.3 无关问题

用户：

帮我写一首诗。

期望行为：

Agent 说明自己主要负责订单查询，避免偏离职责。

10.4 工具查询失败

工具返回：

{"error":"ORDER_NOT_FOUND"}

期望行为：

Agent 告知未查询到该订单，并建议确认订单号是否正确。

10.5 越权请求

用户：

帮我把这个订单取消掉。

期望行为：

Agent 不执行取消操作，说明当前仅支持查询，并引导用户联系人工客服或进入正式取消流程。

测试 Agent 时，不只要看它能不能调用工具，更要看它在不该调用工具时是否能克制。

11. Agent 的风险边界

Agent 最大的问题不是“不够聪明”，而是“太主动”。

在企业场景中，需要特别关注以下风险。

11.1 参数幻觉

用户没有提供订单号时，Agent 可能从上下文中猜一个看似合理的编号。

解决方法是：

• • Prompt 中明确要求缺少参数必须追问。
• • 工具参数在后端做校验。
• • 无效参数直接返回错误。

11.2 错误工具调用

当工具很多时，Agent 可能选错工具。

解决方法是：

• • 工具名称和描述要清晰。
• • 相似工具不要过多。
• • 工具职责不要重叠。
• • 对关键工具增加确认步骤。

11.3 高风险操作

查询类工具风险较低，写操作风险较高。

高风险工具包括：

• • 退款。
• • 删除数据。
• • 修改权限。
• • 取消订单。
• • 发送通知。
• • 修改客户资料。

这类操作不建议让 Agent 直接执行。更安全的方式是让 Agent 生成建议或草稿，再由人工确认。

11.4 权限泄露

Agent 调用内部系统时，必须遵守用户权限。

不能因为 Agent 拿到了工具能力，就允许任何用户查询任何数据。

权限控制应该放在业务后端，而不是只依赖 Prompt。

12. Agent 与 Workflow 怎么选

很多场景既可以用 Agent，也可以用 Workflow。选型关键在于流程是否确定。

例如：

• • 用户随意提出“帮我查订单、查物流、查售后政策”，Agent 更灵活。
• • 后端每天定时分析 1000 条订单异常，Workflow 更稳。

推荐原则是：

前台自然语言任务助手，可以考虑 Agent。后台稳定业务流水线，优先使用 Workflow。

13. Agent 落地最佳实践

13.1 从查询类工具开始

查询类工具风险低，适合 Agent 试点。

例如：

• • 查询订单。
• • 查询物流。
• • 查询库存。
• • 查询 FAQ。
• • 查询日程。

等流程稳定后，再考虑引入需要写操作的工具。

13.2 工具越少越好

不要一次给 Agent 配几十个工具。工具越多，选择错误的概率越高。

建议从 2 到 5 个核心工具开始，逐步扩展。

13.3 工具描述要像 API 文档一样清晰

工具描述应该说明：

• • 什么时候使用。
• • 需要哪些参数。
• • 不适合哪些场景。
• • 返回结果代表什么。

工具描述越清楚，Agent 越容易稳定调用。

13.4 所有工具调用都要有日志

生产环境必须记录：

• • 谁发起了请求。
• • Agent 调用了哪个工具。
• • 传入了哪些参数。
• • 工具返回了什么结果。
• • 最终回复是什么。

没有日志，就无法排查问题，也无法做审计。

13.5 高风险操作必须人工确认

Agent 可以辅助判断，但不应该在没有确认的情况下执行高风险操作。

建议使用类似字段：

{"action":"cancel_order","need_human_confirm":true,"reason":"该操作会影响订单状态"}

14. 一个推荐的 Agent 落地路径

如果团队准备在 Dify 中落地 Agent，可以按以下步骤推进：

1. 选择低风险查询场景2. 明确 Agent 的职责边界3. 设计 1 到 3 个核心工具4. 定义工具参数和返回格式5. 编写 Agent 行为规则 Prompt6. 接入后端服务并做权限校验7. 准备测试对话集8. 检查工具调用日志9. 小范围试点10. 根据误调用和失败案例优化工具描述11. 稳定后再扩展工具数量和场景

这套路径的核心思想是：先让 Agent 做对小事，再逐步扩大能力范围。

15. 总结

Dify Agent 的价值在于把大模型从“内容生成器”升级为“任务执行助手”。

它可以理解用户目标，选择工具，调用外部系统，并把结果整理成自然语言返回。

但 Agent 的工程化落地不能只追求智能感，更要关注可控性、安全性和可追踪性。

一个可靠的 Agent 应该满足三点：

知道自己能做什么；知道什么时候该调用工具；知道什么时候必须停止并交给人工。

对于 Dify 用户来说，Agent 是非常重要的进阶能力，但它不应该替代 Workflow、权限系统和业务规则。

真正稳妥的做法，是让 Agent 负责理解和协助，让业务系统负责校验和执行，让人工保留关键决策权。

这样，AI 才能从一个会聊天的助手，逐步变成一个可被信任的任务协作者。