Agents Crewai 故障排查

# CrewAI 故障排查指南 ## 安装问题 ### 缺少依赖 **错误**: `ModuleNotFoundError: No module named 'crewai_tools'` **解决方法**: bash pip install 'crewai[tools]' ### Python 版本问题 **错误**: `Python version not supported` **解决方法**: CrewAI 要求 Python 3.10-3.13 版本： bash python --version # 检查当前版本 # 使用 pyenv 切换版本 pyenv install 3.11 pyenv local 3.11 ### UV 包管理器 **错误**: 与 Poetry 相关的错误 **解决方法**: CrewAI 已从 Poetry 迁移至 UV： bash crewai update # 或手动安装 UV pip install uv ## 智能体 (Agent) 问题 ### 智能体陷入循环 **问题**: 智能体不断迭代，无法完成任务。 **解决方案**: 1. **设置最大迭代次数**: python agent = Agent( role="...", max_iter=10, # 限制迭代次数 max_rpm=5 # 限制速率 ) 2. **更清晰的任务描述**: python task = Task( description="研究 AI 趋势。返回精确的 5 个要点。", expected_output="包含 5 个要点的列表，不要包含其他内容。" ) 3. **开启 verbose 模式进行调试**: python agent = Agent(role="...", verbose=True) ### 智能体不使用工具 **问题**: 智能体忽略了可用的工具。 **解决方案**: 1. **优化工具描述**: python class MyTool(BaseTool): name: str = "Calculator" description: str = "用于执行数学计算。输入：数学表达式，例如 '2+2'" 2. **在目标/背景中包含工具信息**: python agent = Agent( role="数据分析师", goal="使用计算器工具计算指标", backstory="你擅长使用计算工具。" ) 3. **限制工具数量** (最多 3-5 个): python agent = Agent( role="...", tools=[tool1, tool2, tool3] # 不要堆砌过多工具 ) ### 智能体使用了错误的工具 **问题**: 智能体为任务选择了错误的工具。 **解决方法**: 明确区分工具描述： python search_tool = SerperDevTool() search_tool.description = "搜索网络以获取最新新闻和信息。用于近期事件。" pdf_tool = PDFSearchTool() pdf_tool.description = "搜索 PDF 文档内容。用于特定文档的查询。" ## 任务 (Task) 问题 ### 任务未接收到上下文 **问题**: 任务没有使用前一个任务的输出。 **解决方法**: 显式传递上下文： python task1 = Task( description="研究 AI 趋势", expected_output="趋势列表", agent=researcher ) task2 = Task( description="撰写关于研究发现的文章", expected_output="博客文章", agent=writer, context=[task1] # 必须显式引用 ) ### 输出不符合预期 **问题**: 任务输出不符合 `expected_output` 定义的格式。 **解决方案**: 1. **在 expected_output 中具体说明**: python task = Task( description="...", expected_output=""" 一个 JSON 对象，包含： - 'title': 字符串 - 'points': 5 个字符串组成的数组 - 'summary': 100 字以内的字符串 """ ) 2. **使用 output_pydantic 进行结构化输出**: python