Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs: update agent and task documentation with new parameters (#2891)
Tony Kipkemboi2d6deee753d0
diff --git a/docs/concepts/agents.mdx b/docs/concepts/agents.mdxindex af565a0c0..9803a5c6d 100644--- a/docs/concepts/agents.mdx+++ b/docs/concepts/agents.mdx@@ -55,11 +55,14 @@ The Visual Agent Builder enables:| **Max Retry Limit** _(optional)_ | `max_retry_limit` | `int` | Maximum number of retries when an error occurs. Default is 2. || **Respect Context Window** _(optional)_ | `respect_context_window` | `bool` | Keep messages under context window size by summarizing. Default is True. || **Code Execution Mode** _(optional)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | Mode for code execution: 'safe' (using Docker) or 'unsafe' (direct). Default is 'safe'. |+| **Multimodal** _(optional)_ | `multimodal` | `bool` | Whether the agent supports multimodal capabilities. Default is False. |+| **Inject Date** _(optional)_ | `inject_date` | `bool` | Whether to automatically inject the current date into tasks. Default is False. |+| **Date Format** _(optional)_ | `date_format` | `str` | Format string for date when inject_date is enabled. Default is "%Y-%m-%d" (ISO format). |+| **Reasoning** _(optional)_ | `reasoning` | `bool` | Whether the agent should reflect and create a plan before executing a task. Default is False. |+| **Max Reasoning Attempts** _(optional)_ | `max_reasoning_attempts` | `Optional[int]` | Maximum number of reasoning attempts before executing the task. If None, will try until ready. || **Embedder** _(optional)_ | `embedder` | `Optional[Dict[str, Any]]` | Configuration for the embedder used by the agent. || **Knowledge Sources** _(optional)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | Knowledge sources available to the agent. || **Use System Prompt** _(optional)_ | `use_system_prompt` | `Optional[bool]` | Whether to use system prompt (for o1 model support). Default is True. |-| **Inject Date** _(optional)_ | `inject_date` | `bool` | Whether to automatically inject the current date into tasks. Default is False. |-| **Date Format** _(optional)_ | `date_format` | `str` | Format string for date when inject_date is enabled. Default is "%Y-%m-%d" (ISO format). |## Creating Agents@@ -164,6 +167,11 @@ agent = Agent(code_execution_mode="safe", # Default: "safe" (options: "safe", "unsafe")respect_context_window=True, # Default: Trueuse_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: Nonetools=[SerperDevTool()], # Optional: List of toolsknowledge_sources=None, # Optional: List of knowledge sourcesembedder=None, # Optional: Custom embedder configuration@@ -228,14 +236,40 @@ custom_agent = Agent()```-#### Date-Aware Agent+#### Date-Aware Agent with Reasoning```python Code-date_aware_agent = Agent(+strategic_agent = Agent(role="Market Analyst",- goal="Track market movements with precise date references",- backstory="Expert in time-sensitive financial analysis and reporting",+ 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 tasksdate_format="%B %d, %Y", # Format as "May 21, 2025"+ reasoning=True, # Enable strategic planning+ max_reasoning_attempts=2, # Limit planning iterations+ verbose=True+)+```++#### Reasoning Agent+```python Code+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+)+```++#### Multimodal Agent+```python Code+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 capabilitiesverbose=True)```@@ -263,6 +297,11 @@ date_aware_agent = Agent(- `"safe"`: Uses Docker (recommended for production)- `"unsafe"`: Direct execution (use only in trusted environments)+#### Advanced Features+- `multimodal`: Enable multimodal capabilities for processing text and visual content+- `reasoning`: Enable agent to reflect and create plans before executing tasks+- `inject_date`: Automatically inject current date into task descriptions+#### Templates- `system_template`: Defines agent's core behavior- `prompt_template`: Structures input format@@ -320,6 +359,170 @@ analyst = Agent(When `memory` is enabled, the agent will maintain context across multiple interactions, improving its ability to handle complex, multi-step tasks.</Note>+## Context Window Management++CrewAI includes sophisticated automatic context window management to handle situations where conversations exceed the language model's token limits. This powerful feature is controlled by the `respect_context_window` parameter.++### How Context Window Management Works++When an agent's conversation history grows too large for the LLM's context window, CrewAI automatically detects this situation and can either:++1. **Automatically summarize content** (when `respect_context_window=True`)+2. **Stop execution with an error** (when `respect_context_window=False`)++### Automatic Context Handling (`respect_context_window=True`)++This is the **default and recommended setting** for most use cases. When enabled, CrewAI will:++```python Code+# 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+)+```++**What happens when context limits are exceeded:**+- β οΈ **Warning message**: `"Context length exceeded. Summarizing content to fit the model context window."`+- π **Automatic summarization**: CrewAI intelligently summarizes the conversation history+- β **Continued execution**: Task execution continues seamlessly with the summarized context+- π **Preserved information**: Key information is retained while reducing token count++### Strict Context Limits (`respect_context_window=False`)++When you need precise control and prefer execution to stop rather than lose any information:++```python Code+# 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+)+```++**What happens when context limits are exceeded:**+- β **Error message**: `"Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."`+- π **Execution stops**: Task execution halts immediately+- π§ **Manual intervention required**: You need to modify your approach++### Choosing the Right Setting++#### Use `respect_context_window=True` (Default) when:+- **Processing large documents** that might exceed context limits+- **Long-running conversations** where some summarization is acceptable+- **Research tasks** where general context is more important than exact details+- **Prototyping and development** where you want robust execution++```python Code+# 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+)+```++#### Use `respect_context_window=False` when:+- **Precision is critical** and information loss is unacceptable+- **Legal or medical tasks** requiring complete context+- **Code review** where missing details could introduce bugs+- **Financial analysis** where accuracy is paramount++```python Code+# 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+)+```++### Alternative Approaches for Large Data++When dealing with very large datasets, consider these strategies:++#### 1. Use RAG Tools+```python Code+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+```python Code+# 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+)+```++### Context Window Best Practices++1. **Monitor Context Usage**: Enable `verbose=True` to see context management in action+2. **Design for Efficiency**: Structure tasks to minimize context accumulation+3. **Use Appropriate Models**: Choose LLMs with context windows suitable for your tasks+4. **Test Both Settings**: Try both `True` and `False` to see which works better for your use case+5. **Combine with RAG**: Use RAG tools for very large datasets instead of relying solely on context windows++### Troubleshooting Context Issues++**If you're getting context limit errors:**+```python Code+# 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+```++**If automatic summarization loses important information:**+```python Code+# 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+)+```++<Note>+The context window management feature works automatically in the background. You don't need to call any special functions - just set `respect_context_window` to your preferred behavior and CrewAI handles the rest!+</Note>+## Important Considerations and Best Practices### Security and Code Execution@@ -336,9 +539,16 @@ When `memory` is enabled, the agent will maintain context across multiple intera### Memory and Context Management- Use `memory: true` for tasks requiring historical context- Leverage `knowledge_sources` for domain-specific information-- Configure `embedder_config` when using custom embedding models+- Configure `embedder` when using custom embedding models- Use custom templates (`system_template`, `prompt_template`, `response_template`) for fine-grained control over agent behavior+### Advanced Features+- Enable `reasoning: true` for agents that need to plan and reflect before executing complex tasks+- Set appropriate `max_reasoning_attempts` to control planning iterations (None for unlimited attempts)+- Use `inject_date: true` to provide agents with current date awareness for time-sensitive tasks+- Customize the date format with `date_format` using standard Python datetime format codes+- Enable `multimodal: true` for agents that need to process both text and visual content+### Agent Collaboration- Enable `allow_delegation: true` when agents need to work together- Use `step_callback` to monitor and log agent interactions@@ -346,11 +556,12 @@ When `memory` is enabled, the agent will maintain context across multiple intera- Main `llm` for complex reasoning- `function_calling_llm` for efficient tool usage-### Date Awareness-- Use `inject_date: true` to provide agents with current date awareness+### Date Awareness and Reasoning+- Use `inject_date: true` to provide agents with current date awareness for time-sensitive tasks- Customize the date format with `date_format` using standard Python datetime format codes- Valid format codes include: %Y (year), %m (month), %d (day), %B (full month name), etc.- Invalid date formats will be logged as warnings and will not modify the task description+- Enable `reasoning: true` for complex tasks that benefit from upfront planning and reflection### Model Compatibility- Set `use_system_prompt: false` for older models that don't support system messagesdiff --git a/docs/concepts/tasks.mdx b/docs/concepts/tasks.mdxindex 89e290b30..63b95fecb 100644--- a/docs/concepts/tasks.mdx+++ b/docs/concepts/tasks.mdx@@ -51,6 +51,7 @@ crew = Crew(| **Context** _(optional)_ | `context` | `Optional[List["Task"]]` | Other tasks whose outputs will be used as context for this task. || **Async Execution** _(optional)_ | `async_execution` | `Optional[bool]` | Whether the task should be executed asynchronously. Defaults to False. || **Human Input** _(optional)_ | `human_input` | `Optional[bool]` | Whether the task should have a human review the final answer of the agent. Defaults to False. |+| **Markdown** _(optional)_ | `markdown` | `Optional[bool]` | Whether the task should instruct the agent to return the final answer formatted in Markdown. Defaults to False. || **Config** _(optional)_ | `config` | `Optional[Dict[str, Any]]` | Task-specific configuration parameters. || **Output File** _(optional)_ | `output_file` | `Optional[str]` | File path for storing the task output. || **Output JSON** _(optional)_ | `output_json` | `Optional[Type[BaseModel]]` | A Pydantic model to structure the JSON output. |@@ -94,6 +95,7 @@ reporting_task:A fully fledge reports with the mains topics, each with a full section of information.Formatted as markdown without '```'agent: reporting_analyst+ markdown: trueoutput_file: report.md```@@ -182,9 +184,9 @@ reporting_task = Task(""",expected_output="""A fully fledge reports with the mains topics, each with a full section of information.- Formatted as markdown without '```'""",agent=reporting_analyst,+ markdown=True, # Enable markdown formatting for the final outputoutput_file="report.md")```@@ -257,6 +259,54 @@ if task_output.pydantic:print(f"Pydantic Output: {task_output.pydantic}")```+## Markdown Output Formatting++The `markdown` parameter enables automatic markdown formatting for task outputs. When set to `True`, the task will instruct the agent to format the final answer using proper Markdown syntax.++### Using Markdown Formatting++```python Code+# Example task with markdown formatting enabled+formatted_task = Task(+ description="Create a comprehensive report on AI trends",+ expected_output="A well-structured report with headers, sections, and bullet points",+ agent=reporter_agent,+ markdown=True # Enable automatic markdown formatting+)+```++When `markdown=True`, the agent will receive additional instructions to format the output using:+- `#` for headers+- `**text**` for bold text+- `*text*` for italic text+- `-` or `*` for bullet points+- `` `code` `` for inline code+- ``` ```language ``` for code blocks++### YAML Configuration with Markdown++```yaml tasks.yaml+analysis_task:+ description: >+ Analyze the market data and create a detailed report+ expected_output: >+ A comprehensive analysis with charts and key findings+ agent: analyst+ markdown: true # Enable markdown formatting+ output_file: analysis.md+```++### Benefits of Markdown Output++- **Consistent Formatting**: Ensures all outputs follow proper markdown conventions+- **Better Readability**: Structured content with headers, lists, and emphasis+- **Documentation Ready**: Output can be directly used in documentation systems+- **Cross-Platform Compatibility**: Markdown is universally supported++<Note>+The markdown formatting instructions are automatically added to the task prompt when `markdown=True`, so you don't need to specify formatting requirements in your task description.+</Note>+## Task Dependencies and ContextTasks can depend on the output of other tasks using the `context` attribute. For example: