Agent禁止递归自我调用，循环任务检测机制
在使用 197.Agent 编排自动化任务时，递归自我调用是导致任务无限循环、资源耗尽的高频原因。
简单说，就是 Agent 在执行某个任务时，又把自己作为下一个任务发起调用，并且没有终止条件，最终形成死循环。
本文讲清楚 197.Agent 为什么默认禁止递归自我调用，以及循环任务检测机制如何配置、验证和排错，让零基础用户也能直接上手。
为什么 Agent 必须禁止递归自我调用
Agent 的递归自调用通常出现在任务链中：
比如任务 A 完成后，
Agent 根据结果生成了“再次执行任务 A”的指令，
而这条指令又触发了任务 A 的入队，
于是 A 任务不断重新创建自己。
197.Agent 默认采用调用深度限制和任务指纹去重两种手段来阻断死循环。
调用深度限制是指每个任务最多允许经过 N 次递归，超过 N 次后直接拒绝；
任务指纹去重则是把当前任务的输入、参数和函数名生成一个哈希值，如果哈希值在短时间内重复出现，就判定为循环并终止。
循环任务检测机制的配置步骤
下面以 197.Agent 的配置文件 agent.yaml 为例，演示如何开启和调整循环检测参数。
如果你用的是可视化后台，可以在“任务设置-安全策略”里找到对应选项。
- 打开 Agent 项目根目录下的
agent.yaml，找到recursion配置块：
recursion:
enabled: true
max_depth: 3
window_seconds: 60
same_fingerprint_limit: 2- 其中
max_depth是最大允许的递归嵌套层数，建议从3开始测试，避免小任务误触发。 window_seconds是指纹统计的时间窗口，单位秒；same_fingerprint_limit表示在窗口内相同指纹任务最多出现几次。- 保存配置后，运行
agentctl reload使配置生效。
如何验证递归自调用已被拦截
配置完成后，可以构造一个会自我调用的测试任务来确认拦截效果。
在 197.Agent 的任务目录下新建 test_recursion.yaml，写入一个脚本，内容为：
self.invoke(name="test_recursion")提交任务后，正常情况下你会看到以下两种输出之一：
- 日志中出现
recursion limit reached，说明深度限制生效； - 日志中出现
duplicate fingerprint detected, skip，说明指纹去重拦截了重复任务。
如果任务仍能无限执行，检查 enabled 是否被误设为 false，以及是否在代码中手动调用了底层 API 绕过了检测层。
高频问题与避坑提醒
设置过高的 max_depth 会让递归失效。
很多新手把最大深度调到 10 或更大，结果循环被执行多次后才被拦住，已造成大量资源消耗。
正常业务中，超过 3 层递归就应该视为异常。
不要完全关闭同指纹检测。
即使你的任务链看起来每次参数都不同，也要保留同一时间窗口内相同方法的调用次数限制，防止因随机数或时间戳导致误判。
检测到循环后要留下可追溯日志。
建议将拦截记录输出到独立日志文件，并在“循环清理”回调里发送告警，方便后续定位是代码 bug 还是配置错误。
最终效果确认
完成上述配置并观察运行日志，如果连续运行 24 小时没有出现死循环，且测试任务的拦截日志都正常触发，说明 197.Agent 的循环任务检测机制已可靠落地。
后续如果调整业务逻辑，请同步复查 max_depth 和 same_fingerprint_limit 是否需要微调。
