递归次数限制
在使用 Xpert AI 平台进行智能体调用或任务编排时，若遇到如下错误提示：
在达到停止条件之前，已达到递归次数 20 限制。您可以通过在数字专家工作室中的代理设置中设置“递归限制”来增加限制。
或类似语义的异常栈信息，说明平台的递归调用深度已超出系统预设限制。本指南将帮助你理解该限制存在的原因，并提供最佳实践与排查建议。
❓ 为什么需要设置递归调用限制？
Xpert AI 平台支持多个智能体之间的协同工作，支持任务的多轮处理、条件判断与上下文传递。这类逻辑在内部可能涉及嵌套调用，例如：
- 智能体 A 将任务部分转交给智能体 B，B 又转交给 C……
- 某任务执行失败后，触发回滚或重试机制
- 智能体根据输出结果继续调用自身进行推理优化
如果没有设定递归限制，错误配置或逻辑循环会导致无限调用，最终引发：
- Token 消耗过多
- 响应延迟急剧升高
- 系统不稳定
因此，为了保障系统性能与稳定性，平台引入了最大递归次数的保护机制。
✅ 最佳实践
- 明确任务链路：确保任务之间的调用路径是可收敛的，而不是无限环。
- 使用跳出机制：在智能体逻辑中设置中止判断，例如达到最大轮次、目标已完成、置信度不再提升等。
- 减少不必要的嵌套：避免设计层层调用的智能体结构，应以扁平化、职责分离为优。
- 合理配置限制参数：平台允许在部分调用中手动调整最大递归次数（如开发者模式），建议保守设定。
🔍 如何排查 recursion_limit 错误？
请按照以下步骤逐一排查：
1. 查看调用日志
- 登录 Xpert AI 控制台
- 进入智能体运行日志记录
- 找到异常任务，展开查看消息链
2. 识别递归路径
- 检查智能体使用的大模型能力
- 节点是否形成了循环调用，常见模式如：A → B → A → B → …
3. 检查条件判断是否生效
- 有无终止条件逻辑未生效，如
if complete - 是否明确条件判断来避免重复推理
4. 修正并测试
- 修改智能体提示词或配置逻辑，避免进入无限回路
- 查看任务逐步运行的日志，观察是否依然触发递归限制
5. 临时调高限制值（不推荐正式环境）
- 在开发测试阶段可使用高级配置调高
recursion_limit数值 - 请务必配合日志追踪，确认问题已解决后再部署
📌 示例场景与优化建议
| 场景 | 问题 | 优化建议 |
|---|---|---|
| 智能体持续对回答进行“改写” | 未设置停止条件 | 设置最大重写轮次为 3 |
| 多个子任务依赖彼此完成状态 | 环状依赖 | 明确主控智能体，仅一个控制任务分发 |
| 错误重试逻辑未限制次数 | 无限重试 | 加入最大重试计数器 |
📞 如需帮助
若您仍无法定位问题，欢迎联系技术支持团队，我们将协助您逐层排查智能体行为链，确保平台运行稳定。