Agents

关于如何在 CrewAI 框架中创建和管理 Agent 的详细指南。

Agent 概览

在 CrewAI 框架中，Agent 是一个自治单元，它可以：

• 执行特定任务
• 根据自身角色和目标做出决策
• 使用工具完成目标
• 与其他 Agent 沟通和协作
• 维护交互记忆
• 在被允许时委派任务

Agent 属性

创建 Agent

在 CrewAI 中有两种方式可以创建 Agent：使用 YAML 配置（推荐） 或 直接在代码中定义。

YAML 配置（推荐）

使用 YAML 配置是一种更清晰、更易维护的 Agent 定义方式。我们强烈建议你在 CrewAI 项目中采用这种方式。

按照 安装 章节所述创建 CrewAI 项目后，进入 src/latest_ai_development/config/agents.yaml 文件，并修改模板以符合你的需求。

以下是一个使用 YAML 配置 Agent 的示例：

# src/latest_ai_development/config/agents.yaml
researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
  backstory: >
    You're a seasoned researcher with a knack for uncovering the latest
    developments in {topic}. Known for your ability to find the most relevant
    information and present it in a clear and concise manner.
reporting_analyst:
  role: >
    {topic} Reporting Analyst
  goal: >
    Create detailed reports based on {topic} data analysis and research findings
  backstory: >
    You're a meticulous analyst with a keen eye for detail. You're known for
    your ability to turn complex data into clear and concise reports, making
    it easy for others to understand and act on the information you provide.

要在代码中使用这份 YAML 配置，请创建一个继承自 CrewBase 的 crew 类：

# src/latest_ai_development/crew.py
from crewai import Agent, Crew, Process
from crewai.project import CrewBase, agent, crew
from crewai_tools import SerperDevTool
@CrewBase
class LatestAiDevelopmentCrew():
  """LatestAiDevelopment crew"""
  agents_config = "config/agents.yaml"
  @agent
  def researcher(self) -> Agent:
    return Agent(
      config=self.agents_config['researcher'], # type: ignore[index]
      verbose=True,
      tools=[SerperDevTool()]
    )
  @agent
  def reporting_analyst(self) -> Agent:
    return Agent(
      config=self.agents_config['reporting_analyst'], # type: ignore[index]
      verbose=True
    )

直接用代码定义

你也可以通过实例化 Agent 类，直接在代码中创建 Agent。下面是一个展示所有可用参数的完整示例：

from crewai import Agent
from crewai_tools import SerperDevTool
# Create an agent with all available parameters
agent = Agent(
    role="Senior Data Scientist",
    goal="Analyze and interpret complex datasets to provide actionable insights",
    backstory="With over 10 years of experience in data science and machine learning, "
              "you excel at finding patterns in complex datasets.",
    llm="gpt-4",  # Default: OPENAI_MODEL_NAME or "gpt-4"
    function_calling_llm=None,  # Optional: Separate LLM for tool calling
    verbose=False,  # Default: False
    allow_delegation=False,  # Default: False
    max_iter=20,  # Default: 20 iterations
    max_rpm=None,  # Optional: Rate limit for API calls
    max_execution_time=None,  # Optional: Maximum execution time in seconds
    max_retry_limit=2,  # Default: 2 retries on error
    allow_code_execution=False,  # Default: False
    code_execution_mode="safe",  # Default: "safe" (options: "safe", "unsafe")
    respect_context_window=True,  # Default: True
    use_system_prompt=True,  # Default: True
    multimodal=False,  # Default: False
    inject_date=False,  # Default: False
    date_format="%Y-%m-%d",  # Default: ISO format
    reasoning=False,  # Default: False
    max_reasoning_attempts=None,  # Default: None
    tools=[SerperDevTool()],  # Optional: List of tools
    knowledge_sources=None,  # Optional: List of knowledge sources
    embedder=None,  # Optional: Custom embedder configuration
    system_template=None,  # Optional: Custom system prompt template
    prompt_template=None,  # Optional: Custom prompt template
    response_template=None,  # Optional: Custom response template
    step_callback=None,  # Optional: Callback function for monitoring
)

下面我们拆解一些常见用例中的关键参数组合：

基础研究 Agent

research_agent = Agent(
    role="Research Analyst",
    goal="Find and summarize information about specific topics",
    backstory="You are an experienced researcher with attention to detail",
    tools=[SerperDevTool()],
    verbose=True  # Enable logging for debugging
)

代码开发 Agent

dev_agent = Agent(
    role="Senior Python Developer",
    goal="Write and debug Python code",
    backstory="Expert Python developer with 10 years of experience",
    allow_code_execution=True,
    code_execution_mode="safe",  # Uses Docker for safety
    max_execution_time=300,  # 5-minute timeout
    max_retry_limit=3  # More retries for complex code tasks
)

长时间运行的分析 Agent

analysis_agent = Agent(
    role="Data Analyst",
    goal="Perform deep analysis of large datasets",
    backstory="Specialized in big data analysis and pattern recognition",
    memory=True,
    respect_context_window=True,
    max_rpm=10,  # Limit API calls
    function_calling_llm="gpt-4o-mini"  # Cheaper model for tool calls
)

自定义模板 Agent

custom_agent = Agent(
    role="Customer Service Representative",
    goal="Assist customers with their inquiries",
    backstory="Experienced in customer support with a focus on satisfaction",
    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

strategic_agent = Agent(
    role="Market Analyst",
    goal="Track market movements with precise date references and strategic planning",
    backstory="Expert in time-sensitive financial analysis and strategic reporting",
    inject_date=True,  # Automatically inject current date into tasks
    date_format="%B %d, %Y",  # Format as "May 21, 2025"
    reasoning=True,  # Enable strategic planning
    max_reasoning_attempts=2,  # Limit planning iterations
    verbose=True
)

推理型 Agent

reasoning_agent = Agent(
    role="Strategic Planner",
    goal="Analyze complex problems and create detailed execution plans",
    backstory="Expert strategic planner who methodically breaks down complex challenges",
    reasoning=True,  # Enable reasoning and planning
    max_reasoning_attempts=3,  # Limit reasoning attempts
    max_iter=30,  # Allow more iterations for complex planning
    verbose=True
)

多模态 Agent

multimodal_agent = Agent(
    role="Visual Content Analyst",
    goal="Analyze and process both text and visual content",
    backstory="Specialized in multimodal analysis combining text and image understanding",
    multimodal=True,  # Enable multimodal capabilities
    verbose=True
)

参数详解

关键参数

• role、goal 和 backstory 是必填项，它们共同塑造 Agent 的行为
• llm 决定所使用的语言模型（默认：OpenAI 的 GPT-4）

记忆与上下文

• memory：启用后可保持对话历史
• respect_context_window：防止出现 Token 上限问题
• knowledge_sources：添加领域特定知识库

执行控制

• max_iter：在给出最佳答案前允许的最大尝试次数
• max_execution_time：超时时间（秒）
• max_rpm：API 调用速率限制
• max_retry_limit：出错后的重试次数

代码执行

• allow_code_execution：必须设为 True 才能运行代码

• code_execution_mode：

  • "safe"：使用 Docker（生产环境推荐）
  • "unsafe"：直接执行（仅在可信环境中使用）

高级特性

• multimodal：启用后可处理文本和视觉内容
• reasoning：启用后，Agent 会先反思并制定计划，再执行任务
• inject_date：自动将当前日期注入任务描述中

模板

• system_template：定义 Agent 的核心行为
• prompt_template：定义输入格式结构
• response_template：定义 Agent 的响应格式

Agent 工具

你可以为 Agent 配置多种工具，以增强其能力。CrewAI 支持以下来源的工具：

• CrewAI Toolkit
• LangChain Tools

以下是为 Agent 添加工具的方法：

from crewai import Agent
from crewai_tools import SerperDevTool, WikipediaTools
# Create tools
search_tool = SerperDevTool()
wiki_tool = WikipediaTools()
# Add tools to agent
researcher = Agent(
    role="AI Technology Researcher",
    goal="Research the latest AI developments",
    tools=[search_tool, wiki_tool],
    verbose=True
)

Agent 记忆与上下文

Agent 可以保留其交互记忆，并使用前面任务提供的上下文。这对于需要跨多个任务保留信息的复杂工作流尤其有用。

from crewai import Agent
analyst = Agent(
    role="Data Analyst",
    goal="Analyze and remember complex data patterns",
    memory=True,  # Enable memory
    verbose=True
)

上下文窗口管理

CrewAI 内置了复杂的自动上下文窗口管理机制，用于处理对话内容超出语言模型 Token 限制的情况。这个强大功能由 respect_context_window 参数控制。

上下文窗口管理如何工作

当 Agent 的对话历史过大，超过 LLM 的上下文窗口时，CrewAI 会自动检测这种情况，并可以选择：

1. 自动总结内容（当 respect_context_window=True 时）
2. 报错并停止执行（当 respect_context_window=False 时）

自动上下文处理（respect_context_window=True）

这是 默认且推荐 的设置，适用于大多数场景。启用后，CrewAI 会：

# Agent with automatic context management (default)
smart_agent = Agent(
    role="Research Analyst",
    goal="Analyze large documents and datasets",
    backstory="Expert at processing extensive information",
    respect_context_window=True,  # 🔑 Default: auto-handle context limits
    verbose=True
)

当上下文超限时会发生：

• ⚠️ 警告信息："Context length exceeded. Summarizing content to fit the model context window."
• 🔄 自动摘要：CrewAI 会智能总结对话历史
• ✅ 继续执行：任务会在摘要后的上下文上无缝继续
• 📝 保留关键信息：核心信息会被保留，同时减少 Token 数量

严格上下文限制（respect_context_window=False）

当你需要精确控制，并且宁愿中止执行也不接受信息损失时：

# Agent with strict context limits
strict_agent = Agent(
    role="Legal Document Reviewer",
    goal="Provide precise legal analysis without information loss",
    backstory="Legal expert requiring complete context for accurate analysis",
    respect_context_window=False,  # ❌ Stop execution on context limit
    verbose=True
)

当上下文超限时会发生：

• ❌ 错误信息："Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."
• 🛑 停止执行：任务会立即中止
• 🔧 需要人工干预：你必须修改处理方式

如何选择合适的设置

以下场景建议使用 respect_context_window=True（默认）：

• 处理大型文档，可能超出上下文限制
• 长时间对话，允许一定程度的总结
• 研究任务，更关注总体上下文而非逐字精确内容
• 原型开发阶段，希望执行更稳健

# Perfect for document processing
document_processor = Agent(
    role="Document Analyst",
    goal="Extract insights from large research papers",
    backstory="Expert at analyzing extensive documentation",
    respect_context_window=True,  # Handle large documents gracefully
    max_iter=50,  # Allow more iterations for complex analysis
    verbose=True
)

以下场景建议使用 respect_context_window=False：

• 精度至关重要，不能接受任何信息丢失
• 法律或医疗任务，要求完整上下文
• 代码审查，遗漏细节可能引入 Bug
• 金融分析，准确性要求极高

# Perfect for precision tasks
precision_agent = Agent(
    role="Code Security Auditor",
    goal="Identify security vulnerabilities in code",
    backstory="Security expert requiring complete code context",
    respect_context_window=False,  # Prefer failure over incomplete analysis
    max_retry_limit=1,  # Fail fast on context issues
    verbose=True
)

处理大数据的替代方案

当处理非常大的数据集时，可以考虑以下策略：

1. 使用 RAG 工具

from crewai_tools import RagTool
# Create RAG tool for large document processing
rag_tool = RagTool()
rag_agent = Agent(
    role="Research Assistant",
    goal="Query large knowledge bases efficiently",
    backstory="Expert at using RAG tools for information retrieval",
    tools=[rag_tool],  # Use RAG instead of large context windows
    respect_context_window=True,
    verbose=True
)

2. 使用知识源

# Use knowledge sources instead of large prompts
knowledge_agent = Agent(
    role="Knowledge Expert",
    goal="Answer questions using curated knowledge",
    backstory="Expert at leveraging structured knowledge sources",
    knowledge_sources=[your_knowledge_sources],  # Pre-processed knowledge
    respect_context_window=True,
    verbose=True
)

上下文窗口最佳实践

1. 监控上下文使用情况：启用 verbose=True，观察上下文管理是如何工作的
2. 为效率而设计：设计任务时尽量减少上下文累积
3. 选择合适的模型：使用具有足够上下文窗口的 LLM
4. 两种设置都进行测试：分别尝试 True 和 False，找到更适合你的场景的方式
5. 结合 RAG 使用：对于特别大的数据集，使用 RAG，而不是只依赖上下文窗口

排查上下文问题

如果你遇到上下文上限报错：

# Quick fix: Enable automatic handling
agent.respect_context_window = True
# Better solution: Use RAG tools for large data
from crewai_tools import RagTool
agent.tools = [RagTool()]
# Alternative: Break tasks into smaller pieces
# Or use knowledge sources instead of large prompts

如果自动摘要丢失了重要信息：

# Disable auto-summarization and use RAG instead
agent = Agent(
    role="Detailed Analyst",
    goal="Maintain complete information accuracy",
    backstory="Expert requiring full context",
    respect_context_window=False,  # No summarization
    tools=[RagTool()],  # Use RAG for large data
    verbose=True
)

使用 kickoff() 进行 Agent 直接交互

你可以不经过 task 或 crew 工作流，而是直接使用 kickoff() 方法与 Agent 交互。当你不需要完整 crew 编排能力时，这是一种更简单的方式。

kickoff() 如何工作

kickoff() 方法允许你直接向 Agent 发送消息并获得回复，类似于直接与 LLM 交互，但同时保留了 Agent 的全部能力（工具、推理等）。

from crewai import Agent
from crewai_tools import SerperDevTool
# Create an agent
researcher = Agent(
    role="AI Technology Researcher",
    goal="Research the latest AI developments",
    tools=[SerperDevTool()],
    verbose=True
)
# Use kickoff() to interact directly with the agent
result = researcher.kickoff("What are the latest developments in language models?")
# Access the raw response
print(result.raw)

参数与返回值

该方法返回一个 LiteAgentOutput 对象，具有以下属性：

• raw：原始输出文本字符串
• pydantic：解析后的 Pydantic 模型（如果提供了 response_format）
• agent_role：生成该输出的 Agent 角色
• usage_metrics：本次执行的 Token 使用统计

结构化输出

你可以通过传入 Pydantic 模型作为 response_format 来获取结构化输出：

from pydantic import BaseModel
from typing import List
class ResearchFindings(BaseModel):
    main_points: List[str]
    key_technologies: List[str]
    future_predictions: str
# Get structured output
result = researcher.kickoff(
    "Summarize the latest developments in AI for 2025",
    response_format=ResearchFindings
)
# Access structured data
print(result.pydantic.main_points)
print(result.pydantic.future_predictions)

多轮消息

你也可以传入一个由消息字典组成的对话历史列表：

messages = [
    {"role": "user", "content": "I need information about large language models"},
    {"role": "assistant", "content": "I'd be happy to help with that! What specifically would you like to know?"},
    {"role": "user", "content": "What are the latest developments in 2025?"}
]
result = researcher.kickoff(messages)

异步支持

可以通过 kickoff_async() 使用异步版本，参数保持一致：

import asyncio
async def main():
    result = await researcher.kickoff_async("What are the latest developments in AI?")
    print(result.raw)
asyncio.run(main())

重要注意事项与最佳实践

安全性与代码执行

• 当使用 allow_code_execution 时，要谨慎处理用户输入，并始终进行校验
• 在生产环境中使用 code_execution_mode: "safe"（Docker）
• 考虑设置合理的 max_execution_time，防止无限循环

性能优化

• 使用 respect_context_window: true，避免 Token 上限问题
• 设置适当的 max_rpm，避免触发速率限制
• 启用 cache: true，提升重复任务的性能
• 根据任务复杂度调整 max_iter 和 max_retry_limit

记忆与上下文管理

• 使用 knowledge_sources 注入领域知识
• 在使用自定义嵌入模型时配置 embedder
• 使用自定义模板（system_template、prompt_template、response_template）精细控制 Agent 行为

高级特性

• 对需要在执行复杂任务前先计划和反思的 Agent，启用 reasoning: true
• 设置合适的 max_reasoning_attempts，控制规划迭代次数（None 表示不设上限）
• 使用 inject_date: true，让 Agent 具备当前日期感知能力，以处理时效性任务
• 使用标准 Python datetime 格式码，通过 date_format 自定义日期格式
• 对需要同时处理文本和视觉内容的 Agent，启用 multimodal: true

Agent 协作

• 当 Agent 需要彼此配合时，启用 allow_delegation: true
• 使用 step_callback 监控并记录 Agent 交互

• 考虑为不同用途使用不同的 LLM：

  • 主 llm 用于复杂推理
  • function_calling_llm 用于高效工具调用

日期感知与推理

• 使用 inject_date: true，让 Agent 具备日期感知能力
• 使用标准 Python datetime 格式码通过 date_format 自定义日期格式
• 常见格式码包括：%Y（年）、%m（月）、%d（日）、%B（完整月份名）等
• 无效日期格式会以警告形式记录，并且不会修改任务描述
• 对于适合提前规划与反思的复杂任务，启用 reasoning: true

模型兼容性

• 对于不支持 system message 的旧模型，请设置 use_system_prompt: false
• 确保所选 llm 支持你需要的功能（例如 function calling）

常见问题排查

1. 速率限制：如果你遇到了 API 速率限制：

   • 设置合适的 max_rpm
   • 为重复操作启用缓存
   • 考虑批量处理请求

2. 上下文窗口错误：如果你超过了上下文限制：

   • 启用 respect_context_window
   • 使用更高效的 Prompt
   • 定期清理 Agent 记忆

3. 代码执行问题：如果代码执行失败：

   • 确认 safe 模式下 Docker 已安装
   • 检查执行权限
   • 查看代码沙箱设置

4. 记忆问题：如果 Agent 的回复看起来不一致：

   • 检查知识源配置
   • 检查对话历史管理方式

请记住，只有根据具体用例进行恰当配置时，Agent 才能发挥最大效果。花时间理解你的需求，并相应调整这些参数。