Agent 详解 #
Agent 概述 #
在 CrewAI 框架中，Agent 是一个自主单元，能够：
- 执行特定任务
- 根据角色和目标做出决策
- 使用工具完成任务
- 与其他 Agent 通信和协作
- 维护交互记忆
- 在允许时委托任务
Agent 属性 #
核心属性 #
| 属性 | 类型 | 描述 |
|---|---|---|
| role | str | 定义 Agent 在团队中的角色和专业领域 |
| goal | str | 指导 Agent 决策的个人目标 |
| backstory | str | 为 Agent 提供背景和性格，丰富交互 |
能力属性 #
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| llm | Union[str, LLM, Any] | “gpt-4” | Agent 使用的语言模型 |
| tools | List[BaseTool] | [] | Agent 可用的工具列表 |
| function_calling_llm | Optional[Any] | None | 工具调用的 LLM，覆盖 Crew 的设置 |
执行属性 #
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| max_iter | int | 20 | 提供最佳答案前的最大迭代次数 |
| max_rpm | Optional[int] | None | 每分钟最大请求数，避免限流 |
| max_execution_time | Optional[int] | None | 任务执行的最大时间（秒） |
| max_retry_limit | int | 2 | 发生错误时的最大重试次数 |
| verbose | bool | False | 是否启用详细执行日志 |
协作属性 #
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| allow_delegation | bool | False | 是否允许委托任务给其他 Agent |
| step_callback | Optional[Any] | None | 每个 Agent 步骤后调用的函数 |
高级属性 #
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| memory | bool | False | 是否启用记忆功能 |
| cache | bool | True | 是否启用工具使用缓存 |
| allow_code_execution | bool | False | 是否允许代码执行 |
| code_execution_mode | Literal[“safe”, “unsafe”] | “safe” | 代码执行模式 |
| multimodal | bool | False | 是否支持多模态能力 |
| reasoning | bool | False | 是否在执行前进行推理和规划 |
创建 Agent #
方式一：直接代码定义 #
python
from crewai import Agent
from crewai_tools import SerperDevTool
search_tool = SerperDevTool()
agent = Agent(
role="高级数据科学家",
goal="分析和解释复杂数据集，提供可操作的洞察",
backstory="""拥有 10 年数据科学和机器学习经验，
你擅长在复杂数据集中发现模式。""",
llm="gpt-4o",
tools=[search_tool],
verbose=True,
max_iter=25,
allow_delegation=False
)
方式二：YAML 配置（推荐） #
yaml
# config/agents.yaml
researcher:
role: >
{topic} 高级研究分析师
goal: >
发现 {topic} 的前沿趋势和发展
backstory: >
你是一位经验丰富的研究分析师，
擅长发现最新的技术趋势。
你以能够找到最相关的信息
并以清晰简洁的方式呈现而闻名。
reporting_analyst:
role: >
{topic} 报告分析师
goal: >
根据数据分析创建详细报告
backstory: >
你是一位细致入微的分析师，
具有敏锐的洞察力。
你擅长将复杂数据转化为清晰的报告。
python
# crew.py
from crewai import Agent
from crewai.project import CrewBase, agent
@CrewBase
class MyCrew:
agents_config = 'config/agents.yaml'
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
verbose=True
)
@agent
def reporting_analyst(self) -> Agent:
return Agent(
config=self.agents_config['reporting_analyst'],
verbose=True
)
Agent 类型示例 #
研究分析 Agent #
python
from crewai import Agent
from crewai_tools import SerperDevTool, WebsiteSearchTool
search_tool = SerperDevTool()
web_rag_tool = WebsiteSearchTool()
researcher = Agent(
role="市场研究分析师",
goal="提供 AI 行业的最新市场分析",
backstory="一位对市场趋势有敏锐眼光的专家分析师。",
tools=[search_tool, web_rag_tool],
verbose=True
)
代码开发 Agent #
python
from crewai import Agent
dev_agent = Agent(
role="高级 Python 开发者",
goal="编写和调试 Python 代码",
backstory="拥有 10 年经验的 Python 开发专家",
allow_code_execution=True,
code_execution_mode="safe",
max_execution_time=300,
max_retry_limit=3
)
数据分析 Agent #
python
from crewai import Agent
analysis_agent = Agent(
role="数据分析师",
goal="对大型数据集进行深度分析",
backstory="专注于大数据分析和模式识别",
memory=True,
respect_context_window=True,
max_rpm=10,
function_calling_llm="gpt-4o-mini"
)
自定义模板 Agent #
python
from crewai import Agent
custom_agent = Agent(
role="客户服务代表",
goal="协助客户处理咨询",
backstory="专注于客户满意度的客服专家",
system_template="""<|start_header_id|>system<|end_header_id|>
{{ .System }}<|eot_id|>""",
prompt_template="""<|start_header_id|>user<|end_header_id|>
{{ .Prompt }}<|eot_id|>""",
response_template="""<|start_header_id|>assistant<|end_header_id|>
{{ .Response }}<|eot_id|>"""
)
推理规划 Agent #
python
from crewai import Agent
reasoning_agent = Agent(
role="战略规划师",
goal="分析复杂问题并创建详细执行计划",
backstory="擅长系统分解复杂挑战的战略规划专家",
reasoning=True,
max_reasoning_attempts=3,
max_iter=30,
verbose=True
)
多模态 Agent #
python
from crewai import Agent
multimodal_agent = Agent(
role="视觉内容分析师",
goal="分析和处理文本及视觉内容",
backstory="专注于结合文本和图像理解的多模态分析专家",
multimodal=True,
verbose=True
)
日期感知 Agent #
python
from crewai import Agent
strategic_agent = Agent(
role="市场分析师",
goal="跟踪市场动态并提供精确的日期参考和战略规划",
backstory="时间敏感的金融分析和战略报告专家",
inject_date=True,
date_format="%B %d, %Y",
reasoning=True,
max_reasoning_attempts=2,
verbose=True
)
Agent 工具 #
添加工具 #
python
from crewai import Agent
from crewai_tools import SerperDevTool, WikipediaTools
search_tool = SerperDevTool()
wiki_tool = WikipediaTools()
researcher = Agent(
role="AI 技术研究员",
goal="研究最新的 AI 发展",
tools=[search_tool, wiki_tool],
verbose=True
)
工具类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ Agent 工具类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 搜索工具： │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SerperDevTool - 网络搜索 │ │
│ │ WebsiteSearchTool - 网站内容搜索 │ │
│ │ EXASearchTool - 高级搜索 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 文件工具： │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ FileReadTool - 文件读取 │ │
│ │ DirectoryReadTool - 目录读取 │ │
│ │ PDFSearchTool - PDF 搜索 │ │
│ │ CSVSearchTool - CSV 搜索 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 代码工具： │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ CodeInterpreterTool - 代码解释执行 │ │
│ │ CodeDocsSearchTool - 代码文档搜索 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 自定义工具： │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 使用 @tool 装饰器创建 │ │
│ │ 继承 BaseTool 类创建 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Agent 记忆与上下文 #
启用记忆 #
python
from crewai import Agent
analyst = Agent(
role="数据分析师",
goal="分析和记住复杂数据模式",
memory=True,
verbose=True
)
上下文窗口管理 #
python
# 自动处理上下文限制（推荐）
smart_agent = Agent(
role="研究分析师",
goal="分析大型文档和数据集",
backstory="处理大量信息的专家",
respect_context_window=True,
verbose=True
)
# 严格上下文限制
strict_agent = Agent(
role="法律文档审查员",
goal="提供精确的法律分析",
backstory="需要完整上下文的法律专家",
respect_context_window=False,
verbose=True
)
知识源 #
python
from crewai import Agent
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
knowledge = StringKnowledgeSource(
content="你的知识库内容..."
)
agent = Agent(
role="知识专家",
goal="使用知识库回答问题",
backstory="专注于利用结构化知识源",
knowledge_sources=[knowledge],
verbose=True
)
Agent 代码执行 #
安全模式（推荐） #
python
from crewai import Agent
safe_agent = Agent(
role="代码分析师",
goal="分析和执行代码",
backstory="安全代码执行专家",
allow_code_execution=True,
code_execution_mode="safe",
max_execution_time=300
)
不安全模式 #
python
from crewai import Agent
unsafe_agent = Agent(
role="代码执行器",
goal="直接执行代码",
backstory="受信任环境中的代码执行",
allow_code_execution=True,
code_execution_mode="unsafe"
)
直接与 Agent 交互 #
使用 kickoff() #
python
from crewai import Agent
from crewai_tools import SerperDevTool
researcher = Agent(
role="AI 技术研究员",
goal="研究最新的 AI 发展",
tools=[SerperDevTool()],
verbose=True
)
result = researcher.kickoff("语言模型的最新发展是什么？")
print(result.raw)
结构化输出 #
python
from pydantic import BaseModel
from typing import List
class ResearchFindings(BaseModel):
main_points: List[str]
key_technologies: List[str]
future_predictions: str
result = researcher.kickoff(
"总结 2025 年 AI 的最新发展",
response_format=ResearchFindings
)
print(result.pydantic.main_points)
print(result.pydantic.future_predictions)
多轮对话 #
python
messages = [
{"role": "user", "content": "我需要关于大语言模型的信息"},
{"role": "assistant", "content": "我很乐意帮助！您想了解什么？"},
{"role": "user", "content": "2025 年的最新发展是什么？"}
]
result = researcher.kickoff(messages)
异步执行 #
python
import asyncio
async def main():
result = await researcher.kickoff_async("AI 的最新发展是什么？")
print(result.raw)
asyncio.run(main())
Agent 协作 #
允许委托 #
python
from crewai import Agent
manager = Agent(
role="项目经理",
goal="协调团队完成任务",
backstory="经验丰富的项目经理",
allow_delegation=True,
verbose=True
)
specialist = Agent(
role="技术专家",
goal="解决技术问题",
backstory="资深技术专家",
verbose=True
)
协作模式 #
text
┌─────────────────────────────────────────────────────────────┐
│ Agent 协作模式 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 顺序协作： │
│ Agent1 -> Agent2 -> Agent3 │
│ │
│ 层级协作： │
│ Manager Agent │
│ / | \ │
│ Agent1 Agent2 Agent3 │
│ │
│ 委托协作： │
│ Agent1 --委托--> Agent2 │
│ \ | │
│ \ / │
│ <--结果返回-- │
│ │
└─────────────────────────────────────────────────────────────┘
Agent 最佳实践 #
1. 角色设计 #
python
# 好的设计：具体、专业
good_agent = Agent(
role="医疗数据分析师",
goal="分析医疗数据，发现疾病模式",
backstory="""你是一位拥有 15 年经验的医疗数据分析师，
专注于流行病学和疾病预测。你擅长从复杂的医疗数据中
发现隐藏的模式和趋势。"""
)
# 不好的设计：模糊、通用
bad_agent = Agent(
role="分析师",
goal="分析数据",
backstory="我是一个分析师"
)
2. 工具选择 #
python
# 根据任务选择合适的工具
research_agent = Agent(
role="研究员",
tools=[SerperDevTool(), WikipediaTools()],
verbose=True
)
file_agent = Agent(
role="文档分析师",
tools=[FileReadTool(), PDFSearchTool(), DirectoryReadTool()],
verbose=True
)
code_agent = Agent(
role="开发者",
tools=[CodeInterpreterTool()],
allow_code_execution=True,
verbose=True
)
3. 性能优化 #
python
# 限制迭代次数
agent = Agent(
role="分析师",
goal="快速分析",
max_iter=15,
max_rpm=30,
cache=True
)
# 使用更便宜的模型进行工具调用
agent = Agent(
role="分析师",
llm="gpt-4o",
function_calling_llm="gpt-4o-mini"
)
4. 错误处理 #
python
agent = Agent(
role="分析师",
goal="分析数据",
max_retry_limit=3,
max_execution_time=300,
verbose=True
)
常见问题排查 #
速率限制 #
python
# 设置速率限制
agent = Agent(
role="分析师",
max_rpm=10,
cache=True
)
上下文限制 #
python
# 启用上下文窗口管理
agent = Agent(
role="分析师",
respect_context_window=True
)
代码执行问题 #
python
# 确保 Docker 已安装（安全模式）
agent = Agent(
role="开发者",
allow_code_execution=True,
code_execution_mode="safe"
)
下一步 #
现在你已经深入了解了 Agent，接下来学习 Task 详解，掌握任务的定义和执行！
最后更新：2026-04-04