什么是一次迭代

Re-Act Agent 的核心是一个"推理 → 行动 → 观察"的循环。每一轮循环就是一次迭代（iteration）：

1. 模型推理（reasoning），决定要不要调用工具
2. 如果决定调用工具，就执行工具（acting）并拿到结果（observation）
3. 把结果喂回模型，进入下一轮迭代

当模型在某一轮推理中不再请求调用工具、直接给出最终答复时，循环结束，本轮 process() 返回。

maxIterations 的作用

为了避免模型陷入"反复调用工具却始终得不出结论"的死循环，框架给每个 Agent 设置了一个最大迭代次数。当循环达到这个上限仍未得出最终答复时，会强制收尾（见下文 Summary）。

迭代上限的取值规则是"组件覆写优先，否则用全局默认"：

int iters = maxIterations() > 0 ? maxIterations() : 全局 max-iterations;

来源	配置方式	默认值
全局默认	liteflow.agent.defaults.max-iterations	50
单组件覆写	覆写 maxIterations() 返回正数	-1（表示不覆盖，沿用全局）

全局配置

liteflow.agent.defaults.max-iterations=50

单组件覆写

@Override
protected int maxIterations() {
    return 10; // 这个 Agent 最多迭代 10 轮
}

取值建议

• 设得太小：复杂任务可能还没完成就被强制收尾，得到一个不完整的总结
• 设得太大：模型一旦失控，会持续消耗 token 和工具调用，成本和时延都不可控

建议根据 Agent 的实际职责评估：纯问答类 Agent 几轮就够；需要多步查询、读写文件、调用多个工具的复杂 Agent，可以适当调高。

达到上限：Summary 收尾

当 Re-Act 循环达到 maxIterations 仍未得出最终答复时，底层 ReActAgent 会触发一次 Summary（总结）：把目前为止的推理过程和工具结果归纳成一个收尾回复，作为本轮的最终结果。

也就是说，即使迭代到达上限，handleReply(reply) 仍然会被调用，只不过 reply 是一个总结性的回复，而不是模型"自然结束"得出的答案。

在流式事件里观察 Summary

如果通过 ExecuteOption.eventListener(...) 注册了监听器，Summary 过程会以独立的事件类型推送出来：

FlowEvent#getType()	含义
agent.summary	达到最大迭代次数后的总结过程或最终 summary

.eventListener(event -> {
    if ("agent.summary".equals(event.getType())) {
        // 说明这一轮是被迭代上限强制收尾的，可据此打点告警
    }
})

事件类型的完整列表见 流式输出；如果想在更底层拦截 Summary 的生成过程，可以使用 PRE_SUMMARY / POST_SUMMARY 等 Hook 事件，详见 自定义 Hook。

收到 agent.summary 往往是个信号

正常完成的 Agent 不应该频繁触发 Summary。如果线上经常出现 agent.summary，通常意味着：

• maxIterations 设得偏低，任务做不完就被截断
• 系统提示词或工具设计有问题，导致模型反复试探、收敛不了

建议把它当作一个需要关注的运行指标。