Dify 插件开发实验（09）：Agent策略插件——如何控制 Agent 的工具使用策略？

1. 业务场景

先讲一个我们实际遇到的场景。

客服工单 SaaS 的门户对话 Agent 上线前，业务方提了两条硬要求：第一，限制工具调用次数——单轮最多 3 次工具调用，防止模型反复试错把 token 烧光；第二，强制先检索后回答——涉及知识的问题必须先查知识库再回答，不许凭空编。但默认的 Agent 策略把「要不要调工具、调几次」完全交给模型自主决定——模型试错多少次、先回答还是先检索，业务方一概管不了。

我们第一次接这类需求时，第一反应也是「把约束写进系统提示词不就行了」。真正动手才发现——提示词只是「建议」，不是「约束」：模型在错误路径上反复试错，一次对话烧掉几十次工具调用；知识类问题不先检索就张口就来——业务方要的是「自主但有边界」，这需要一个能落地的策略层，而不是一段话术。

这不是个例。任何要对外提供 Agent 服务的场景都是这个模式：银行客服要限定查询次数防滥用、医疗问答要求必须先检索证据、电商助手要控制工具调用成本——「模型自主」和「业务可控」之间的平衡，是企业定制 Agent 的常见诉求。

2. 场景痛点

这个流程的痛点，在业务方身上体现得最直接：

• 工具调用次数不可控：模型在错误路径上反复试错，一次对话烧掉几十次工具调用，成本失控。
• 幻觉直接回答：不先检索就回答，知识类问题张口就来，错误信息发给客户，信任直接崩塌。
• 业务约束无法落地：业务方说「最多查 3 次」「先查再答」，默认策略根本不认这些规则——约束写在需求文档里，落不到系统里。
• 行为不可观测：模型为什么调这个工具、为什么不调，过程不可见，出问题无从排查。

本质上，默认策略给的是「模型自主」，企业要的是「自主但有边界」——工具调用次数、检索顺序这类业务约束，需要一个能落地的策略层。

3. 方案：为什么是 Agent 策略插件

选 Agent 策略插件，我们实际对比过：

• 官方扩展点：agent-strategy 策略插件是 Dify 官方支持的扩展点，自定义 Agent 推理循环（选工具 → 调工具 → 评估结果 → 继续/结束），不改平台代码；
• 硬约束软约束分层：maximum_iterations 是硬约束（达上限强制结束，不依赖模型自觉），force_retrieve 是软约束（策略引导先检索，最终由模型执行）——约束可强可弱，按业务需要配置；
• 可对照验证：同一组问题双策略各跑一遍，行为差异可量化，业务方看得见约束是否生效。

这篇文章我们就用它写一个 limited 策略插件：maximum_iterations（硬约束上限）+ force_retrieve（强制先检索），复用 106-01 的 time_tool 与 106-08 的 retrieve_tool，双策略对照验证约束是否真正落地。

4. 整体架构

链路很清晰：用户问题 → 策略循环（选工具/调工具/评估）→ 有答案或达上限结束。关键设计是硬约束在策略层拦截——达上限时不再把工具调用发给模型，直接强制结束并说明，而不是「建议」模型停止。

5. 模块设计

5.1 策略参数声明（strategies/limited.yaml）

自定义参数写在 strategy yaml 的 parameters 里，安装后即出现在 Agent 节点配置面板：

parameters:

  - name: maximum_iterations

    type: number

    required: true

    label:

      zh_Hans: 最大迭代次数

    default: 3

    min: 1

    max: 10

  - name: force_retrieve

    type: boolean

    required: false

    label:

      zh_Hans: 强制先检索后回答

    default: false

5.2 硬约束实现（strategies/limited.py）

达上限时不再把工具调用发给模型，直接拦截并说明：

for step in range(1, max_iter + 1):

    result = self.session.model.llm.invoke(

        model_config=model_config, prompt_messages=messages,

        stream=False, tools=prompt_tools)

    msg = result.message

    tool_calls = msg.tool_calls or []

    if not tool_calls:

        yield self.create_text_message(msg.content or "")

        return

    # 达上限：不再调用工具，强制结束并说明（硬约束）

    if step >= max_iter:

        names = ", ".join(tc.function.name for tc in tool_calls)

        yield self.create_text_message(

            f"已达到最大工具调用次数上限（{max_iter} 次），已停止调用工具"

            f"（本次意图调用：{names}）。请基于已有信息回答。")

        return

5.3 参数类型转换

策略接口收到的 parameters["tools"]/parameters["model"] 是 dict，需要 ToolEntity.model_validate / AgentModelConfig.model_validate 转成实体（官方 FunctionCallingParams(**parameters) 也是靠 pydantic 自动转）。

6. 运行验证

对照结论：limited 的强制检索指令使知识题稳定先检索（业务约束生效）；上限硬约束在构造场景下明确拦截——默认策略无此能力（模型自主决定，不受硬限制）。

7. 实战坑

排障提示：策略执行错误出现在 run error 的 PluginInvokeError 里（无 traceback）——用「故意 raise 带类型信息」的探针 + daemon cwd 代码目录核对运行版本，是本实验实测有效的排障法。

8. 实验文档及源码获取

• 实验文档：DIFY-106-09：Agent策略插件.md
• 验证应用 DSL：dify106_09_验证对话.yml | dify106_09_对照默认策略.yml | dify106_09_上限验证.yml
• 插件安装包：dify106_09_agent_strategy.signed.difypkg
• 源码目录：dify-106/dsl | dify-106/plugins

文章聚焦核心配置与采坑点，完整分步操作与双策略对照实验记录见实验文档原文。