> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 递归次数限制

在使用 Xpert AI 平台进行智能体调用或任务编排时，若遇到如下错误提示：

```
在达到停止条件之前，已达到递归次数 20 限制。您可以通过在数字专家工作室中的代理设置中设置“递归限制”来增加限制。
```

或类似语义的异常栈信息，说明平台的递归调用深度已超出系统预设限制。本指南将帮助你理解该限制存在的原因，并提供最佳实践与排查建议。

***

### ❓ 为什么需要设置递归调用限制？

Xpert AI 平台支持多个智能体之间的协同工作，支持任务的**多轮处理**、**条件判断**与**上下文传递**。这类逻辑在内部可能涉及嵌套调用，例如：

* 智能体 A 将任务部分转交给智能体 B，B 又转交给 C……
* 某任务执行失败后，触发回滚或重试机制
* 智能体根据输出结果继续调用自身进行推理优化

如果没有设定递归限制，错误配置或逻辑循环会导致**无限调用**，最终引发：

* Token 消耗过多
* 响应延迟急剧升高
* 系统不稳定

因此，为了保障系统性能与稳定性，平台引入了最大递归次数的保护机制。

***

### ✅ 最佳实践

1. **明确任务链路**：确保任务之间的调用路径是**可收敛**的，而不是无限环。
2. **使用跳出机制**：在智能体逻辑中设置中止判断，例如达到最大轮次、目标已完成、置信度不再提升等。
3. **减少不必要的嵌套**：避免设计层层调用的智能体结构，应以扁平化、职责分离为优。
4. **合理配置限制参数**：平台允许在部分调用中手动调整最大递归次数（如开发者模式），建议保守设定。

***

### 🔍 如何排查 `recursion_limit` 错误？

请按照以下步骤逐一排查：

#### 1. **查看调用日志**

* 登录 Xpert AI 控制台
* 进入智能体运行日志记录
* 找到异常任务，展开查看消息链

#### 2. **识别递归路径**

* 检查智能体使用的大模型能力
* 节点是否形成了循环调用，常见模式如：A → B → A → B → …

#### 3. **检查条件判断是否生效**

* 有无终止条件逻辑未生效，如 `if complete`
* 是否明确条件判断来避免重复推理

#### 4. **修正并测试**

* 修改智能体提示词或配置逻辑，避免进入无限回路
* 查看任务逐步运行的日志，观察是否依然触发递归限制

#### 5. **临时调高限制值（不推荐正式环境）**

* 在开发测试阶段可使用高级配置调高 `recursion_limit` 数值
* 请务必配合日志追踪，确认问题已解决后再部署

***

### 📌 示例场景与优化建议

| 场景             | 问题      | 优化建议              |
| -------------- | ------- | ----------------- |
| 智能体持续对回答进行“改写” | 未设置停止条件 | 设置最大重写轮次为 3       |
| 多个子任务依赖彼此完成状态  | 环状依赖    | 明确主控智能体，仅一个控制任务分发 |
| 错误重试逻辑未限制次数    | 无限重试    | 加入最大重试计数器         |

***

### 📞 如需帮助

若您仍无法定位问题，欢迎联系技术支持团队，我们将协助您逐层排查智能体行为链，确保平台运行稳定。