new tests

Co-Authored-By: Joe Moura <joao@crewai.com>

docs/concepts/agents.mdx

@@ -58,6 +58,8 @@ The Visual Agent Builder enables:
 | **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
 
@@ -226,6 +228,18 @@ custom_agent = Agent(
 )
 ```
 
+#### Date-Aware Agent
+```python Code
+date_aware_agent = Agent(
+    role="Market Analyst",
+    goal="Track market movements with precise date references",
+    backstory="Expert in time-sensitive financial analysis and reporting",
+    inject_date=True,  # Automatically inject current date into tasks
+    date_format="%B %d, %Y",  # Format as "May 21, 2025"
+    verbose=True
+)
+```
+
 ### Parameter Details
 
 #### Critical Parameters
@@ -332,6 +346,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
+- 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
+
 ### Model Compatibility
 - Set `use_system_prompt: false` for older models that don't support system messages
 - Ensure your chosen `llm` supports the features you need (like function calling)

docs/concepts/reasoning.mdx

@@ -0,0 +1,140 @@
+---
+title: "Agent Reasoning"
+---
+
+# Agent Reasoning
+
+Agent reasoning is a feature that allows agents to reflect on a task and create a plan before execution. This helps agents approach tasks more methodically and ensures they're ready to perform the assigned work.
+
+## How to Use Agent Reasoning
+
+To enable reasoning for an agent, simply set `reasoning=True` when creating the agent:
+
+```python
+from crewai import Agent
+
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze complex datasets and provide insights",
+    backstory="You are an experienced data analyst with expertise in finding patterns in complex data.",
+    reasoning=True,  # Enable reasoning
+    max_reasoning_attempts=3  # Optional: Set a maximum number of reasoning attempts
+)
+```
+
+## How It Works
+
+When reasoning is enabled, before executing a task, the agent will:
+
+1. Reflect on the task and create a detailed plan
+2. Evaluate whether it's ready to execute the task
+3. Refine the plan as necessary until it's ready or max_reasoning_attempts is reached
+4. Inject the reasoning plan into the task description before execution
+
+This process helps the agent break down complex tasks into manageable steps and identify potential challenges before starting.
+
+## Configuration Options
+
+- `reasoning` (bool): Enable or disable reasoning (default: False)
+- `max_reasoning_attempts` (int, optional): Maximum number of attempts to refine the plan before proceeding with execution. If None (default), the agent will continue refining until it's ready.
+
+## Example
+
+Here's a complete example:
+
+```python
+from crewai import Agent, Task, Crew
+
+# Create an agent with reasoning enabled
+analyst = Agent(
+    role="Data Analyst",
+    goal="Analyze data and provide insights",
+    backstory="You are an expert data analyst.",
+    reasoning=True,
+    max_reasoning_attempts=3  # Optional: Set a limit on reasoning attempts
+)
+
+# Create a task
+analysis_task = Task(
+    description="Analyze the provided sales data and identify key trends.",
+    expected_output="A report highlighting the top 3 sales trends.",
+    agent=analyst
+)
+
+# Create a crew and run the task
+crew = Crew(agents=[analyst], tasks=[analysis_task])
+result = crew.kickoff()
+
+print(result)
+```
+
+## Error Handling
+
+The reasoning process is designed to be robust, with error handling built in. If an error occurs during reasoning, the agent will proceed with executing the task without the reasoning plan. This ensures that tasks can still be executed even if the reasoning process fails.
+
+Here's how to handle potential errors in your code:
+
+```python
+from crewai import Agent, Task
+import logging
+
+# Set up logging to capture any reasoning errors
+logging.basicConfig(level=logging.INFO)
+
+# Create an agent with reasoning enabled
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze data and provide insights",
+    reasoning=True,
+    max_reasoning_attempts=3
+)
+
+# Create a task
+task = Task(
+    description="Analyze the provided sales data and identify key trends.",
+    expected_output="A report highlighting the top 3 sales trends.",
+    agent=agent
+)
+
+# Execute the task
+# If an error occurs during reasoning, it will be logged and execution will continue
+result = agent.execute_task(task)
+```
+
+## Example Reasoning Output
+
+Here's an example of what a reasoning plan might look like for a data analysis task:
+
+```
+Task: Analyze the provided sales data and identify key trends.
+
+Reasoning Plan:
+I'll analyze the sales data to identify the top 3 trends. 
+
+1. Understanding of the task:
+   I need to analyze sales data to identify key trends that would be valuable for business decision-making.
+
+2. Key steps I'll take:
+   - First, I'll examine the data structure to understand what fields are available
+   - Then I'll perform exploratory data analysis to identify patterns
+   - Next, I'll analyze sales by time periods to identify temporal trends
+   - I'll also analyze sales by product categories and customer segments
+   - Finally, I'll identify the top 3 most significant trends
+
+3. Approach to challenges:
+   - If the data has missing values, I'll decide whether to fill or filter them
+   - If the data has outliers, I'll investigate whether they're valid data points or errors
+   - If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns
+
+4. Use of available tools:
+   - I'll use data analysis tools to explore and visualize the data
+   - I'll use statistical tools to identify significant patterns
+   - I'll use knowledge retrieval to access relevant information about sales analysis
+
+5. Expected outcome:
+   A concise report highlighting the top 3 sales trends with supporting evidence from the data.
+
+READY: I am ready to execute the task.
+```
+
+This reasoning plan helps the agent organize its approach to the task, consider potential challenges, and ensure it delivers the expected output.

docs/docs.json

@@ -139,6 +139,12 @@
               "tools/youtubevideosearchtool"
             ]
           },
+          {
+            "group": "MCP Integration",
+            "pages": [
+              "mcp/crewai-mcp-integration"
+            ] 
+          },
           {
             "group": "Agent Monitoring & Observability",
             "pages": [

docs/enterprise/introduction.mdx

@@ -64,14 +64,14 @@ CrewAI Enterprise extends the power of the open-source framework with features d
       Sign Up
     </Card>
   </Step>
-  <Step title="Create your first crew">
-    Use code or Crew Studio to create your crew
+  <Step title="Build your first crew">
+    Use code or Crew Studio to build your crew
     <Card 
-      title="Create Crew" 
+      title="Build Crew" 
       icon="paintbrush"
-      href="/enterprise/guides/create-crew"
+      href="/enterprise/guides/build-crew"
     >
-      Create Crew
+      Build Crew
     </Card>
   </Step>
   <Step title="Deploy your crew">

docs/mcp/crewai-mcp-integration.mdx

@@ -0,0 +1,229 @@
+---
+title: 'MCP Servers as Tools in CrewAI'
+description: 'Learn how to integrate MCP servers as tools in your CrewAI agents using the `crewai-tools` library.'
+icon: 'plug'
+---
+
+## Overview
+
+The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) provides a standardized way for AI agents to provide context to LLMs by communicating with external services, known as MCP Servers. 
+The `crewai-tools` library extends CrewAI's capabilities by allowing you to seamlessly integrate tools from these MCP servers into your agents. 
+This gives your crews access to a vast ecosystem of functionalities. For now, we support **Standard Input/Output** (Stdio) and **Server-Sent Events** (SSE) transport mechanisms. 
+
+<Info>
+We will also be integrating **Streamable HTTP** transport in the near future. 
+Streamable HTTP is designed for efficient, bi-directional communication over a single HTTP connection.
+</Info>
+
+## Installation
+
+Before you start using MCP with `crewai-tools`, you need to install the `mcp` extra `crewai-tools` dependency with the following command:
+
+```shell
+uv pip install 'crewai-tools[mcp]'
+```
+
+### Integrating MCP Tools with `MCPServerAdapter`
+
+The `MCPServerAdapter` class from `crewai-tools` is the primary way to connect to an MCP server and make its tools available to your CrewAI agents. 
+It supports different transport mechanisms, primarily **Stdio** (for local servers) and **SSE** (Server-Sent Events).You have two main options for managing the connection lifecycle:
+
+### Option 1: Fully Managed Connection (Recommended)
+
+Using a Python context manager (`with` statement) is the recommended approach. It automatically handles starting and stopping the connection to the MCP server.
+
+**For a local Stdio-based MCP server:**
+
+```python
+from crewai import Agent, Task, Crew
+from crewai_tools import MCPServerAdapter
+from mcp import StdioServerParameters
+import os
+
+server_params=StdioServerParameters(
+    command="uxv", # Or your python3 executable i.e. "python3"
+    args=["mock_server.py"],
+    env={"UV_PYTHON": "3.12", **os.environ},
+)
+
+with MCPServerAdapter(server_params) as tools:
+    print(f"Available tools from Stdio MCP server: {[tool.name for tool in tools]}")
+
+    # Example: Using the tools from the Stdio MCP server in a CrewAI Agent
+    agent = Agent(
+        role="Web Information Retriever",
+        goal="Scrape content from a specified URL.",
+        backstory="An AI that can fetch and process web page data via an MCP tool.",
+        tools=tools,
+        verbose=True,
+    )
+    task = Task(
+        description="Scrape content from a specified URL.",
+        expected_output="Scraped content from the specified URL.",
+        agent=agent,
+    )
+    crew = Crew(
+        agents=[agent],
+        tasks=[task],
+        verbose=True,
+    )
+    result = crew.kickoff()
+    print(result)
+```
+
+**For a remote SSE-based MCP server:**
+
+```python
+from crewai_tools import MCPServerAdapter
+from crewai import Agent, Task, Crew
+
+server_params = {"url": "http://localhost:8000/sse"}
+
+with MCPServerAdapter(server_params) as tools:
+    print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}")
+
+    # Example: Using the tools from the SSE MCP server in a CrewAI Agent
+    agent = Agent(
+        role="Web Information Retriever",
+        goal="Scrape content from a specified URL.",
+        backstory="An AI that can fetch and process web page data via an MCP tool.",
+        tools=tools,
+        verbose=True,
+    )
+    task = Task(
+        description="Scrape content from a specified URL.",
+        expected_output="Scraped content from the specified URL.",
+        agent=agent,
+    )
+    crew = Crew(
+        agents=[agent],
+        tasks=[task],
+        verbose=True,
+    )
+    result = crew.kickoff()
+    print(result)
+```
+
+### Option 2: More control over the MCP server connection lifecycle
+
+If you need finer-grained control over the MCP server connection lifecycle, you can instantiate `MCPServerAdapter` directly and manage its `start()` and `stop()` methods.
+
+<Info>
+You **MUST** call `mcp_server_adapter.stop()` to ensure the connection is closed and resources are released. Using a `try...finally` block is highly recommended.
+</Info>
+
+#### Stdio Transport Example (Manual)
+
+```python
+from mcp import StdioServerParameters
+from crewai_tools import MCPServerAdapter
+from crewai import Agent, Task, Crew
+import os
+
+stdio_params = StdioServerParameters(
+    command="uvx", # Or your python3 executable i.e. "python3"
+    args=["--quiet", "your-mcp-server@0.1.3"],
+    env={"UV_PYTHON": "3.12", **os.environ},
+)
+
+mcp_server_adapter = MCPServerAdapter(server_params=stdio_params)
+try:
+    mcp_server_adapter.start() # Manually start the connection
+    tools = mcp_server_adapter.tools
+    print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}")
+
+    # Use 'tools' with your Agent, Task, Crew setup as in Option 1
+    agent = Agent(
+        role="Medical Researcher", 
+        goal="Find recent studies on a given topic using PubMed.", 
+        backstory="An AI assistant specialized in biomedical literature research.", 
+        tools=tools,
+        verbose=True 
+    )
+    
+    task = Task(
+        description="Search for recent articles on 'crispr gene editing'.",
+        expected_output="A summary of the top 3 recent articles.",
+        agent=agent
+    )
+    
+    crew = Crew(
+        agents=[agent],
+        tasks=[task],
+        verbose=True,
+        process=Process.sequential
+    )
+    
+    result = crew.kickoff()
+    print(result)
+finally:
+    print("Stopping Stdio MCP server connection (manual)...")
+    mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
+```
+
+
+#### SSE Transport Example (Manual)
+
+```python
+from crewai_tools import MCPServerAdapter
+from crewai import Agent, Task, Crew, Process
+from mcp import StdioServerParameters
+
+
+server_params = {"url": "http://localhost:8000/sse"}
+
+try:
+    mcp_server_adapter = MCPServerAdapter(server_params)
+    mcp_server_adapter.start()
+    tools = mcp_server_adapter.tools
+    print(f"Available tools (manual SSE): {[tool.name for tool in tools]}")
+
+    agent = Agent(
+        role="Medical Researcher", 
+        goal="Find recent studies on a given topic using PubMed.", 
+        backstory="An AI assistant specialized in biomedical literature research.", 
+        tools=tools,
+        verbose=True 
+    )
+    
+    task = Task(
+        description="Search for recent articles on 'crispr gene editing'.",
+        expected_output="A summary of the top 3 recent articles.",
+        agent=agent
+    )
+    
+    crew = Crew(
+        agents=[agent],
+        tasks=[task],
+        verbose=True,
+        process=Process.sequential
+    )
+    
+    result = crew.kickoff()
+    print(result)
+finally:
+    print("Stopping SSE MCP server connection (manual)...")
+    mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
+```
+
+## Staying Safe with MCP
+<Warning>
+Always ensure that you trust an MCP Server before using it.
+</Warning>
+
+#### Security Warning: DNS Rebinding Attacks
+SSE transports can be vulnerable to DNS rebinding attacks if not properly secured. 
+To prevent this:
+
+1. **Always validate Origin headers** on incoming SSE connections to ensure they come from expected sources
+2. **Avoid binding servers to all network interfaces** (0.0.0.0) when running locally - bind only to localhost (127.0.0.1) instead
+3. **Implement proper authentication** for all SSE connections
+
+Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites.
+
+For more details, see the [MCP Transport Security](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) documentation.
+
+### Limitations
+*   **Supported Primitives**: Currently, `MCPServerAdapter` primarily supports adapting MCP `tools`. 
+Other MCP primitives like `prompts` or `resources` are not directly integrated as CrewAI components through this adapter at this time.
+*   **Output Handling**: The adapter typically processes the primary text output from an MCP tool (e.g., `.content[0].text`). Complex or multi-modal outputs might require custom handling if not fitting this pattern.

src/crewai/agent.py

@@ -115,10 +115,26 @@ class Agent(BaseAgent):
         default=False,
         description="Whether the agent is multimodal.",
     )
+    inject_date: bool = Field(
+        default=False,
+        description="Whether to automatically inject the current date into tasks.",
+    )
+    date_format: str = Field(
+        default="%Y-%m-%d",
+        description="Format string for date when inject_date is enabled.",
+    )
     code_execution_mode: Literal["safe", "unsafe"] = Field(
         default="safe",
         description="Mode for code execution: 'safe' (using Docker) or 'unsafe' (direct execution).",
     )
+    reasoning: bool = Field(
+        default=False,
+        description="Whether the agent should reflect and create a plan before executing a task.",
+    )
+    max_reasoning_attempts: Optional[int] = Field(
+        default=None,
+        description="Maximum number of reasoning attempts before executing the task. If None, will try until ready.",
+    )
     embedder: Optional[Dict[str, Any]] = Field(
         default=None,
         description="Embedder configuration for the agent.",
@@ -225,6 +241,23 @@ class Agent(BaseAgent):
             ValueError: If the max execution time is not a positive integer.
             RuntimeError: If the agent execution fails for other reasons.
         """
+        if self.reasoning:
+            try:
+                from crewai.utilities.reasoning_handler import AgentReasoning, AgentReasoningOutput
+                
+                reasoning_handler = AgentReasoning(task=task, agent=self)
+                reasoning_output: AgentReasoningOutput = reasoning_handler.handle_agent_reasoning()
+                
+                # Add the reasoning plan to the task description
+                task.description += f"\n\nReasoning Plan:\n{reasoning_output.plan.plan}"
+            except Exception as e:
+                if hasattr(self, '_logger'):
+                    self._logger.log("error", f"Error during reasoning process: {str(e)}")
+                else:
+                    print(f"Error during reasoning process: {str(e)}")
+            
+        self._inject_date_to_task(task)
+            
         if self.tools_handler:
             self.tools_handler.last_used_tool = {}  # type: ignore # Incompatible types in assignment (expression has type "dict[Never, Never]", variable has type "ToolCalling")
 
@@ -585,6 +618,26 @@ class Agent(BaseAgent):
 
         return description
 
+    def _inject_date_to_task(self, task):
+        """Inject the current date into the task description if inject_date is enabled."""
+        if self.inject_date:
+            from datetime import datetime
+            try:
+                valid_format_codes = ['%Y', '%m', '%d', '%H', '%M', '%S', '%B', '%b', '%A', '%a']
+                is_valid = any(code in self.date_format for code in valid_format_codes)
+                
+                if not is_valid:
+                    raise ValueError(f"Invalid date format: {self.date_format}")
+                
+                current_date: str = datetime.now().strftime(self.date_format)
+                task.description += f"\n\nCurrent Date: {current_date}"
+            except Exception as e:
+                if hasattr(self, '_logger'):
+                    self._logger.log("warning", f"Failed to inject date: {str(e)}")
+                else:
+                    print(f"Warning: Failed to inject date: {str(e)}")
+
+
     def _validate_docker_installation(self) -> None:
         """Check if Docker is installed and running."""
         if not shutil.which("docker"):

src/crewai/task.py

@@ -135,6 +135,10 @@ class Task(BaseModel):
         description="Whether the task should have a human review the final answer of the agent",
         default=False,
     )
+    markdown: Optional[bool] = Field(
+        description="Whether the task should instruct the agent to return the final answer formatted in Markdown",
+        default=False,
+    )
     converter_cls: Optional[Type[Converter]] = Field(
         description="A converter class used to export structured output",
         default=None,
@@ -522,10 +526,14 @@ class Task(BaseModel):
         return guardrail_result
 
     def prompt(self) -> str:
-        """Prompt the task.
-
+        """Generates the task prompt with optional markdown formatting.
+        
+        When the markdown attribute is True, instructions for formatting the
+        response in Markdown syntax will be added to the prompt.
+        
         Returns:
-            Prompt of the task.
+            str: The formatted prompt string containing the task description,
+                 expected output, and optional markdown formatting instructions.
         """
         tasks_slices = [self.description]
 
@@ -533,6 +541,17 @@ class Task(BaseModel):
             expected_output=self.expected_output
         )
         tasks_slices = [self.description, output]
+        
+        if self.markdown:
+            markdown_instruction = """Your final answer MUST be formatted in Markdown syntax.
+Follow these guidelines:
+- Use # for headers
+- Use ** for bold text
+- Use * for italic text
+- Use - or * for bullet points
+- Use `code` for inline code
+- Use ```language for code blocks"""
+            tasks_slices.append(markdown_instruction)
         return "\n".join(tasks_slices)
 
     def interpolate_inputs_and_add_conversation_history(

src/crewai/translations/en.json

@@ -51,5 +51,11 @@
       "description": "See image to understand its content, you can optionally ask a question about the image",
       "default_action": "Please provide a detailed description of this image, including all visual elements, context, and any notable details you can observe."
     }
+  },
+  "reasoning": {
+    "initial_plan": "You are {role}, a professional with the following background: {backstory}\n\nYour primary goal is: {goal}\n\nAs {role}, you are creating a strategic plan for a task that requires your expertise and unique perspective.",
+    "refine_plan": "You are {role}, a professional with the following background: {backstory}\n\nYour primary goal is: {goal}\n\nAs {role}, you are refining a strategic plan for a task that requires your expertise and unique perspective.",
+    "create_plan_prompt": "You are {role} with this background: {backstory}\n\nYour primary goal is: {goal}\n\nYou have been assigned the following task:\n{description}\n\nExpected output:\n{expected_output}\n\nAvailable tools: {tools}\n\nBefore executing this task, create a detailed plan that leverages your expertise as {role} and outlines:\n1. Your understanding of the task from your professional perspective\n2. The key steps you'll take to complete it, drawing on your background and skills\n3. How you'll approach any challenges that might arise, considering your expertise\n4. How you'll strategically use the available tools based on your experience\n5. The expected outcome and how it aligns with your goal\n\nAfter creating your plan, assess whether you feel ready to execute the task.\nConclude with one of these statements:\n- \"READY: I am ready to execute the task.\"\n- \"NOT READY: I need to refine my plan because [specific reason].\"",
+    "refine_plan_prompt": "You are {role} with this background: {backstory}\n\nYour primary goal is: {goal}\n\nYou created the following plan for this task:\n{current_plan}\n\nHowever, you indicated that you're not ready to execute the task yet.\n\nPlease refine your plan further, drawing on your expertise as {role} to address any gaps or uncertainties.\n\nAfter refining your plan, assess whether you feel ready to execute the task.\nConclude with one of these statements:\n- \"READY: I am ready to execute the task.\"\n- \"NOT READY: I need to refine my plan further because [specific reason].\""
   }
 }

src/crewai/utilities/events/event_listener.py

@@ -56,6 +56,11 @@ from .tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
+from .reasoning_events import (
+    AgentReasoningStartedEvent,
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+)
 
 
 class EventListener(BaseEventListener):
@@ -406,5 +411,30 @@ class EventListener(BaseEventListener):
                 self.formatter.current_crew_tree,
             )
 
+        # ----------- REASONING EVENTS -----------
+
+        @crewai_event_bus.on(AgentReasoningStartedEvent)
+        def on_agent_reasoning_started(source, event: AgentReasoningStartedEvent):
+            self.formatter.handle_reasoning_started(
+                self.formatter.current_agent_branch,
+                event.attempt,
+                self.formatter.current_crew_tree,
+            )
+
+        @crewai_event_bus.on(AgentReasoningCompletedEvent)
+        def on_agent_reasoning_completed(source, event: AgentReasoningCompletedEvent):
+            self.formatter.handle_reasoning_completed(
+                event.plan,
+                event.ready,
+                self.formatter.current_crew_tree,
+            )
+
+        @crewai_event_bus.on(AgentReasoningFailedEvent)
+        def on_agent_reasoning_failed(source, event: AgentReasoningFailedEvent):
+            self.formatter.handle_reasoning_failed(
+                event.error,
+                self.formatter.current_crew_tree,
+            )
+
 
 event_listener = EventListener()

src/crewai/utilities/events/event_types.py

@@ -43,6 +43,11 @@ from .tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
+from .reasoning_events import (
+    AgentReasoningStartedEvent,
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+)
 
 EventTypes = Union[
     CrewKickoffStartedEvent,
@@ -74,4 +79,7 @@ EventTypes = Union[
     LLMStreamChunkEvent,
     LLMGuardrailStartedEvent,
     LLMGuardrailCompletedEvent,
+    AgentReasoningStartedEvent,
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
 ]

src/crewai/utilities/events/reasoning_events.py

@@ -0,0 +1,31 @@
+from crewai.utilities.events.base_events import BaseEvent
+
+
+class AgentReasoningStartedEvent(BaseEvent):
+    """Event emitted when an agent starts reasoning about a task."""
+
+    type: str = "agent_reasoning_started"
+    agent_role: str
+    task_id: str
+    attempt: int = 1  # The current reasoning/refinement attempt
+
+
+class AgentReasoningCompletedEvent(BaseEvent):
+    """Event emitted when an agent finishes its reasoning process."""
+
+    type: str = "agent_reasoning_completed"
+    agent_role: str
+    task_id: str
+    plan: str
+    ready: bool
+    attempt: int = 1
+
+
+class AgentReasoningFailedEvent(BaseEvent):
+    """Event emitted when the reasoning process fails."""
+
+    type: str = "agent_reasoning_failed"
+    agent_role: str
+    task_id: str
+    error: str
+    attempt: int = 1

src/crewai/utilities/events/utils/console_formatter.py

@@ -15,6 +15,7 @@ class ConsoleFormatter:
     current_method_branch: Optional[Tree] = None
     current_lite_agent_branch: Optional[Tree] = None
     tool_usage_counts: Dict[str, int] = {}
+    current_reasoning_branch: Optional[Tree] = None  # Track reasoning status
 
     def __init__(self, verbose: bool = False):
         self.console = Console(width=None)
@@ -399,7 +400,11 @@ class ConsoleFormatter:
         tree_to_use = branch_to_use or crew_tree
 
         if branch_to_use is None or tree_to_use is None:
-            return None
+            # If we don't have a valid branch, default to crew_tree if provided
+            if crew_tree is not None:
+                branch_to_use = tree_to_use = crew_tree
+            else:
+                return None
 
         # Update tool usage count
         self.tool_usage_counts[tool_name] = self.tool_usage_counts.get(tool_name, 0) + 1
@@ -501,7 +506,11 @@ class ConsoleFormatter:
         tree_to_use = branch_to_use or crew_tree
 
         if branch_to_use is None or tree_to_use is None:
-            return None
+            # If we don't have a valid branch, default to crew_tree if provided
+            if crew_tree is not None:
+                branch_to_use = tree_to_use = crew_tree
+            else:
+                return None
 
         # Only add thinking status if we don't have a current tool branch
         if self.current_tool_branch is None:
@@ -797,7 +806,7 @@ class ConsoleFormatter:
         tree_to_use = branch_to_use or crew_tree
 
         if branch_to_use is None or tree_to_use is None:
-            # If we don't have a valid branch, use crew_tree as the branch if available
+            # If we don't have a valid branch, default to crew_tree if provided
             if crew_tree is not None:
                 branch_to_use = tree_to_use = crew_tree
             else:
@@ -982,3 +991,118 @@ class ConsoleFormatter:
             "Knowledge Search Failed", "Search Error", "red", Error=error
         )
         self.print_panel(error_content, "Search Error", "red")
+
+    # ----------- AGENT REASONING EVENTS -----------
+
+    def handle_reasoning_started(
+        self,
+        agent_branch: Optional[Tree],
+        attempt: int,
+        crew_tree: Optional[Tree],
+    ) -> Optional[Tree]:
+        """Handle agent reasoning started (or refinement) event."""
+        if not self.verbose:
+            return None
+
+        # Prefer LiteAgent branch if we are within a LiteAgent context
+        branch_to_use = self.current_lite_agent_branch or agent_branch
+        tree_to_use = branch_to_use or crew_tree
+
+        if branch_to_use is None or tree_to_use is None:
+            # If we don't have a valid branch, default to crew_tree if provided
+            if crew_tree is not None:
+                branch_to_use = tree_to_use = crew_tree
+            else:
+                return None
+
+        # Reuse existing reasoning branch if present
+        reasoning_branch = self.current_reasoning_branch
+        if reasoning_branch is None:
+            reasoning_branch = branch_to_use.add("")
+            self.current_reasoning_branch = reasoning_branch
+
+        # Build label text depending on attempt
+        status_text = (
+            f"Reasoning (Attempt {attempt})" if attempt > 1 else "Reasoning..."
+        )
+        self.update_tree_label(reasoning_branch, "🧠", status_text, "blue")
+
+        self.print(tree_to_use)
+        self.print()
+
+        return reasoning_branch
+
+    def handle_reasoning_completed(
+        self,
+        plan: str,
+        ready: bool,
+        crew_tree: Optional[Tree],
+    ) -> None:
+        """Handle agent reasoning completed event."""
+        if not self.verbose:
+            return
+
+        reasoning_branch = self.current_reasoning_branch
+        tree_to_use = (
+            self.current_lite_agent_branch
+            or self.current_agent_branch
+            or crew_tree
+        )
+
+        style = "green" if ready else "yellow"
+        status_text = "Reasoning Completed" if ready else "Reasoning Completed (Not Ready)"
+
+        if reasoning_branch is not None:
+            self.update_tree_label(reasoning_branch, "✅", status_text, style)
+
+        if tree_to_use is not None:
+            self.print(tree_to_use)
+
+        # Show plan in a panel (trim very long plans)
+        if plan:
+            plan_panel = Panel(
+                Text(plan, style="white"),
+                title="🧠 Reasoning Plan",
+                border_style=style,
+                padding=(1, 2),
+            )
+            self.print(plan_panel)
+
+        self.print()
+
+        # Clear stored branch after completion
+        self.current_reasoning_branch = None
+
+    def handle_reasoning_failed(
+        self,
+        error: str,
+        crew_tree: Optional[Tree],
+    ) -> None:
+        """Handle agent reasoning failure event."""
+        if not self.verbose:
+            return
+
+        reasoning_branch = self.current_reasoning_branch
+        tree_to_use = (
+            self.current_lite_agent_branch
+            or self.current_agent_branch
+            or crew_tree
+        )
+
+        if reasoning_branch is not None:
+            self.update_tree_label(reasoning_branch, "❌", "Reasoning Failed", "red")
+
+        if tree_to_use is not None:
+            self.print(tree_to_use)
+
+        # Error panel
+        error_content = self.create_status_content(
+            "Reasoning Failed",
+            "Error",
+            "red",
+            Error=error,
+        )
+        self.print_panel(error_content, "Reasoning Error", "red")
+
+        # Clear stored branch after failure
+        self.current_reasoning_branch = None

src/crewai/utilities/reasoning_handler.py

@@ -0,0 +1,387 @@
+import logging
+import json
+from typing import Tuple, cast
+
+from pydantic import BaseModel, Field
+
+from crewai.agent import Agent
+from crewai.task import Task
+from crewai.utilities import I18N
+from crewai.llm import LLM
+from crewai.utilities.events.crewai_event_bus import crewai_event_bus
+from crewai.utilities.events.reasoning_events import (
+    AgentReasoningStartedEvent,
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+)
+
+
+class ReasoningPlan(BaseModel):
+    """Model representing a reasoning plan for a task."""
+    plan: str = Field(description="The detailed reasoning plan for the task.")
+    ready: bool = Field(description="Whether the agent is ready to execute the task.")
+
+
+class AgentReasoningOutput(BaseModel):
+    """Model representing the output of the agent reasoning process."""
+    plan: ReasoningPlan = Field(description="The reasoning plan for the task.")
+
+
+class ReasoningFunction(BaseModel):
+    """Model for function calling with reasoning."""
+    plan: str = Field(description="The detailed reasoning plan for the task.")
+    ready: bool = Field(description="Whether the agent is ready to execute the task.")
+
+
+class AgentReasoning:
+    """
+    Handles the agent reasoning process, enabling an agent to reflect and create a plan
+    before executing a task.
+    """
+    def __init__(self, task: Task, agent: Agent):
+        if not task or not agent:
+            raise ValueError("Both task and agent must be provided.")
+        self.task = task
+        self.agent = agent
+        self.llm = cast(LLM, agent.llm)
+        self.logger = logging.getLogger(__name__)
+        self.i18n = I18N()
+
+    def handle_agent_reasoning(self) -> AgentReasoningOutput:
+        """
+        Public method for the reasoning process that creates and refines a plan
+        for the task until the agent is ready to execute it.
+
+        Returns:
+            AgentReasoningOutput: The output of the agent reasoning process.
+        """
+        # Emit a reasoning started event (attempt 1)
+        try:
+            crewai_event_bus.emit(
+                self.agent,
+                AgentReasoningStartedEvent(
+                    agent_role=self.agent.role,
+                    task_id=str(self.task.id),
+                    attempt=1,
+                ),
+            )
+        except Exception:
+            # Ignore event bus errors to avoid breaking execution
+            pass
+
+        try:
+            output = self.__handle_agent_reasoning()
+
+            # Emit reasoning completed event
+            try:
+                crewai_event_bus.emit(
+                    self.agent,
+                    AgentReasoningCompletedEvent(
+                        agent_role=self.agent.role,
+                        task_id=str(self.task.id),
+                        plan=output.plan.plan,
+                        ready=output.plan.ready,
+                        attempt=1,
+                    ),
+                )
+            except Exception:
+                pass
+
+            return output
+        except Exception as e:
+            # Emit reasoning failed event
+            try:
+                crewai_event_bus.emit(
+                    self.agent,
+                    AgentReasoningFailedEvent(
+                        agent_role=self.agent.role,
+                        task_id=str(self.task.id),
+                        error=str(e),
+                        attempt=1,
+                    ),
+                )
+            except Exception:
+                pass
+
+            raise
+
+    def __handle_agent_reasoning(self) -> AgentReasoningOutput:
+        """
+        Private method that handles the agent reasoning process.
+
+        Returns:
+            AgentReasoningOutput: The output of the agent reasoning process.
+        """
+        plan, ready = self.__create_initial_plan()
+
+        plan, ready = self.__refine_plan_if_needed(plan, ready)
+
+        reasoning_plan = ReasoningPlan(plan=plan, ready=ready)
+        return AgentReasoningOutput(plan=reasoning_plan)
+
+    def __create_initial_plan(self) -> Tuple[str, bool]:
+        """
+        Creates the initial reasoning plan for the task.
+
+        Returns:
+            Tuple[str, bool]: The initial plan and whether the agent is ready to execute the task.
+        """
+        reasoning_prompt = self.__create_reasoning_prompt()
+
+        if self.llm.supports_function_calling():
+            plan, ready = self.__call_with_function(reasoning_prompt, "initial_plan")
+            return plan, ready
+        else:
+            system_prompt = self.i18n.retrieve("reasoning", "initial_plan").format(
+                role=self.agent.role,
+                goal=self.agent.goal,
+                backstory=self.__get_agent_backstory()
+            )
+
+            response = self.llm.call(
+                [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": reasoning_prompt}
+                ]
+            )
+
+            return self.__parse_reasoning_response(str(response))
+
+    def __refine_plan_if_needed(self, plan: str, ready: bool) -> Tuple[str, bool]:
+        """
+        Refines the reasoning plan if the agent is not ready to execute the task.
+
+        Args:
+            plan: The current reasoning plan.
+            ready: Whether the agent is ready to execute the task.
+
+        Returns:
+            Tuple[str, bool]: The refined plan and whether the agent is ready to execute the task.
+        """
+        attempt = 1
+        max_attempts = self.agent.max_reasoning_attempts
+
+        while not ready and (max_attempts is None or attempt < max_attempts):
+            # Emit event for each refinement attempt
+            try:
+                crewai_event_bus.emit(
+                    self.agent,
+                    AgentReasoningStartedEvent(
+                        agent_role=self.agent.role,
+                        task_id=str(self.task.id),
+                        attempt=attempt + 1,
+                    ),
+                )
+            except Exception:
+                pass
+
+            refine_prompt = self.__create_refine_prompt(plan)
+
+            if self.llm.supports_function_calling():
+                plan, ready = self.__call_with_function(refine_prompt, "refine_plan")
+            else:
+                system_prompt = self.i18n.retrieve("reasoning", "refine_plan").format(
+                    role=self.agent.role,
+                    goal=self.agent.goal,
+                    backstory=self.__get_agent_backstory()
+                )
+
+                response = self.llm.call(
+                    [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": refine_prompt}
+                    ]
+                )
+                plan, ready = self.__parse_reasoning_response(str(response))
+
+            attempt += 1
+
+            if max_attempts is not None and attempt >= max_attempts:
+                self.logger.warning(
+                    f"Agent reasoning reached maximum attempts ({max_attempts}) without being ready. Proceeding with current plan."
+                )
+                break
+
+        return plan, ready
+
+    def __call_with_function(self, prompt: str, prompt_type: str) -> Tuple[str, bool]:
+        """
+        Calls the LLM with function calling to get a reasoning plan.
+
+        Args:
+            prompt: The prompt to send to the LLM.
+            prompt_type: The type of prompt (initial_plan or refine_plan).
+
+        Returns:
+            Tuple[str, bool]: A tuple containing the plan and whether the agent is ready.
+        """
+        self.logger.debug(f"Using function calling for {prompt_type} reasoning")
+
+        function_schema = {
+            "type": "function",
+            "function": {
+                "name": "create_reasoning_plan",
+                "description": "Create or refine a reasoning plan for a task",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "plan": {
+                            "type": "string",
+                            "description": "The detailed reasoning plan for the task."
+                        },
+                        "ready": {
+                            "type": "boolean",
+                            "description": "Whether the agent is ready to execute the task."
+                        }
+                    },
+                    "required": ["plan", "ready"]
+                }
+            }
+        }
+
+        try:
+            system_prompt = self.i18n.retrieve("reasoning", prompt_type).format(
+                role=self.agent.role,
+                goal=self.agent.goal,
+                backstory=self.__get_agent_backstory()
+            )
+
+            # Prepare a simple callable that just returns the tool arguments as JSON
+            def _create_reasoning_plan(plan: str, ready: bool):  # noqa: N802
+                """Return the reasoning plan result in JSON string form."""
+                return json.dumps({"plan": plan, "ready": ready})
+
+            response = self.llm.call(
+                [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": prompt}
+                ],
+                tools=[function_schema],
+                available_functions={"create_reasoning_plan": _create_reasoning_plan},
+            )
+
+            self.logger.debug(f"Function calling response: {response[:100]}...")
+
+            try:
+                result = json.loads(response)
+                if "plan" in result and "ready" in result:
+                    return result["plan"], result["ready"]
+            except (json.JSONDecodeError, KeyError):
+                pass
+
+            response_str = str(response)
+            return response_str, "READY: I am ready to execute the task." in response_str
+
+        except Exception as e:
+            self.logger.warning(f"Error during function calling: {str(e)}. Falling back to text parsing.")
+
+            try:
+                system_prompt = self.i18n.retrieve("reasoning", prompt_type).format(
+                    role=self.agent.role,
+                    goal=self.agent.goal,
+                    backstory=self.__get_agent_backstory()
+                )
+
+                fallback_response = self.llm.call(
+                    [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": prompt}
+                    ]
+                )
+
+                fallback_str = str(fallback_response)
+                return fallback_str, "READY: I am ready to execute the task." in fallback_str
+            except Exception as inner_e:
+                self.logger.error(f"Error during fallback text parsing: {str(inner_e)}")
+                return "Failed to generate a plan due to an error.", True  # Default to ready to avoid getting stuck
+
+    def __get_agent_backstory(self) -> str:
+        """
+        Safely gets the agent's backstory, providing a default if not available.
+
+        Returns:
+            str: The agent's backstory or a default value.
+        """
+        return getattr(self.agent, "backstory", "No backstory provided")
+
+    def __create_reasoning_prompt(self) -> str:
+        """
+        Creates a prompt for the agent to reason about the task.
+
+        Returns:
+            str: The reasoning prompt.
+        """
+        available_tools = self.__format_available_tools()
+
+        return self.i18n.retrieve("reasoning", "create_plan_prompt").format(
+            role=self.agent.role,
+            goal=self.agent.goal,
+            backstory=self.__get_agent_backstory(),
+            description=self.task.description,
+            expected_output=self.task.expected_output,
+            tools=available_tools
+        )
+
+    def __format_available_tools(self) -> str:
+        """
+        Formats the available tools for inclusion in the prompt.
+
+        Returns:
+            str: Comma-separated list of tool names.
+        """
+        try:
+            return ', '.join([tool.name for tool in (self.task.tools or [])])
+        except (AttributeError, TypeError):
+            return "No tools available"
+
+    def __create_refine_prompt(self, current_plan: str) -> str:
+        """
+        Creates a prompt for the agent to refine its reasoning plan.
+
+        Args:
+            current_plan: The current reasoning plan.
+
+        Returns:
+            str: The refine prompt.
+        """
+        return self.i18n.retrieve("reasoning", "refine_plan_prompt").format(
+            role=self.agent.role,
+            goal=self.agent.goal,
+            backstory=self.__get_agent_backstory(),
+            current_plan=current_plan
+        )
+
+    def __parse_reasoning_response(self, response: str) -> Tuple[str, bool]:
+        """
+        Parses the reasoning response to extract the plan and whether
+        the agent is ready to execute the task.
+
+        Args:
+            response: The LLM response.
+
+        Returns:
+            Tuple[str, bool]: The plan and whether the agent is ready to execute the task.
+        """
+        if not response:
+            return "No plan was generated.", False
+
+        plan = response
+        ready = False
+
+        if "READY: I am ready to execute the task." in response:
+            ready = True
+
+        return plan, ready
+
+    def _handle_agent_reasoning(self) -> AgentReasoningOutput:
+        """
+        Deprecated method for backward compatibility.
+        Use handle_agent_reasoning() instead.
+
+        Returns:
+            AgentReasoningOutput: The output of the agent reasoning process.
+        """
+        self.logger.warning(
+            "The _handle_agent_reasoning method is deprecated. Use handle_agent_reasoning instead."
+        )
+        return self.handle_agent_reasoning()

tests/agent_reasoning_test.py

@@ -0,0 +1,261 @@
+"""Tests for reasoning in agents."""
+
+import json
+import pytest
+
+from crewai import Agent, Task
+from crewai.llm import LLM
+from crewai.utilities.reasoning_handler import AgentReasoning
+
+
+@pytest.fixture
+def mock_llm_responses():
+    """Fixture for mock LLM responses."""
+    return {
+        "ready": "I'll solve this simple math problem.\n\nREADY: I am ready to execute the task.\n\n",
+        "not_ready": "I need to think about derivatives.\n\nNOT READY: I need to refine my plan because I'm not sure about the derivative rules.",
+        "ready_after_refine": "I'll use the power rule for derivatives where d/dx(x^n) = n*x^(n-1).\n\nREADY: I am ready to execute the task.",
+        "execution": "4"
+    }
+
+
+def test_agent_with_reasoning(mock_llm_responses):
+    """Test agent with reasoning."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        verbose=True
+    )
+    
+    task = Task(
+        description="Simple math task: What's 2+2?",
+        expected_output="The answer should be a number.",
+        agent=agent
+    )
+    
+    agent.llm.call = lambda messages, *args, **kwargs: (
+        mock_llm_responses["ready"]
+        if any("create a detailed plan" in msg.get("content", "") for msg in messages)
+        else mock_llm_responses["execution"]
+    )
+    
+    result = agent.execute_task(task)
+    
+    assert result == mock_llm_responses["execution"]
+    assert "Reasoning Plan:" in task.description
+
+
+def test_agent_with_reasoning_not_ready_initially(mock_llm_responses):
+    """Test agent with reasoning that requires refinement."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        max_reasoning_attempts=2,
+        verbose=True
+    )
+    
+    task = Task(
+        description="Complex math task: What's the derivative of x²?",
+        expected_output="The answer should be a mathematical expression.",
+        agent=agent
+    )
+    
+    call_count = [0]
+    
+    def mock_llm_call(messages, *args, **kwargs):
+        if any("create a detailed plan" in msg.get("content", "") for msg in messages) or any("refine your plan" in msg.get("content", "") for msg in messages):
+            call_count[0] += 1
+            if call_count[0] == 1:
+                return mock_llm_responses["not_ready"]
+            else:
+                return mock_llm_responses["ready_after_refine"]
+        else:
+            return "2x"
+    
+    agent.llm.call = mock_llm_call
+    
+    result = agent.execute_task(task)
+    
+    assert result == "2x"
+    assert call_count[0] == 2  # Should have made 2 reasoning calls
+    assert "Reasoning Plan:" in task.description
+
+
+def test_agent_with_reasoning_max_attempts_reached():
+    """Test agent with reasoning that reaches max attempts without being ready."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        max_reasoning_attempts=2,
+        verbose=True
+    )
+    
+    task = Task(
+        description="Complex math task: Solve the Riemann hypothesis.",
+        expected_output="A proof or disproof of the hypothesis.",
+        agent=agent
+    )
+    
+    call_count = [0]
+    
+    def mock_llm_call(messages, *args, **kwargs):
+        if any("create a detailed plan" in msg.get("content", "") for msg in messages) or any("refine your plan" in msg.get("content", "") for msg in messages):
+            call_count[0] += 1
+            return f"Attempt {call_count[0]}: I need more time to think.\n\nNOT READY: I need to refine my plan further."
+        else:
+            return "This is an unsolved problem in mathematics."
+    
+    agent.llm.call = mock_llm_call
+    
+    result = agent.execute_task(task)
+    
+    assert result == "This is an unsolved problem in mathematics."
+    assert call_count[0] == 2  # Should have made exactly 2 reasoning calls (max_attempts)
+    assert "Reasoning Plan:" in task.description
+
+
+def test_agent_reasoning_input_validation():
+    """Test input validation in AgentReasoning."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True
+    )
+    
+    with pytest.raises(ValueError, match="Both task and agent must be provided"):
+        AgentReasoning(task=None, agent=agent)
+    
+    task = Task(
+        description="Simple task",
+        expected_output="Simple output"
+    )
+    with pytest.raises(ValueError, match="Both task and agent must be provided"):
+        AgentReasoning(task=task, agent=None)
+
+
+def test_agent_reasoning_error_handling():
+    """Test error handling during the reasoning process."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True
+    )
+    
+    task = Task(
+        description="Task that will cause an error",
+        expected_output="Output that will never be generated",
+        agent=agent
+    )
+    
+    call_count = [0]
+    
+    def mock_llm_call_error(*args, **kwargs):
+        call_count[0] += 1
+        if call_count[0] <= 2:  # First calls are for reasoning
+            raise Exception("LLM error during reasoning")
+        return "Fallback execution result"  # Return a value for task execution
+    
+    agent.llm.call = mock_llm_call_error
+    
+    result = agent.execute_task(task)
+    
+    assert result == "Fallback execution result"
+    assert call_count[0] > 2  # Ensure we called the mock multiple times
+
+
+def test_agent_with_function_calling():
+    """Test agent with reasoning using function calling."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        verbose=True
+    )
+    
+    task = Task(
+        description="Simple math task: What's 2+2?",
+        expected_output="The answer should be a number.",
+        agent=agent
+    )
+    
+    agent.llm.supports_function_calling = lambda: True
+    
+    def mock_function_call(messages, *args, **kwargs):
+        if "tools" in kwargs:
+            return json.dumps({
+                "plan": "I'll solve this simple math problem: 2+2=4.",
+                "ready": True
+            })
+        else:
+            return "4"
+    
+    agent.llm.call = mock_function_call
+    
+    result = agent.execute_task(task)
+    
+    assert result == "4"
+    assert "Reasoning Plan:" in task.description
+    assert "I'll solve this simple math problem: 2+2=4." in task.description
+
+
+def test_agent_with_function_calling_fallback():
+    """Test agent with reasoning using function calling that falls back to text parsing."""
+    llm = LLM("gpt-3.5-turbo")
+    
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        verbose=True
+    )
+    
+    task = Task(
+        description="Simple math task: What's 2+2?",
+        expected_output="The answer should be a number.",
+        agent=agent
+    )
+    
+    agent.llm.supports_function_calling = lambda: True
+    
+    def mock_function_call(messages, *args, **kwargs):
+        if "tools" in kwargs:
+            return "Invalid JSON that will trigger fallback. READY: I am ready to execute the task."
+        else:
+            return "4"
+    
+    agent.llm.call = mock_function_call
+    
+    result = agent.execute_task(task)
+    
+    assert result == "4"
+    assert "Reasoning Plan:" in task.description
+    assert "Invalid JSON that will trigger fallback" in task.description

tests/cassettes/test_task_with_max_execution_time_exceeded.yaml

@@ -78,4 +78,134 @@ interactions:
     status:
       code: 200
       message: OK
+- request:
+    body: '{"messages": [{"role": "system", "content": "You are Researcher. You''re
+      an expert researcher, specialized in technology, software engineering, AI and
+      startups. You work as a freelancer and are now working on doing research and
+      analysis for a new customer.\nYour personal goal is: Make the best research
+      and analysis on content about AI and AI agents. Use the tool provided to you.\nYou
+      ONLY have access to the following tools, and should NEVER make up tools that
+      are not listed here:\n\nTool Name: what amazing tool\nTool Arguments: {}\nTool
+      Description: My tool\n\nIMPORTANT: Use the following format in your response:\n\n```\nThought:
+      you should always think about what to do\nAction: the action to take, only one
+      name of [what amazing tool], just the name, exactly as it''s written.\nAction
+      Input: the input to the action, just a simple JSON object, enclosed in curly
+      braces, using \" to wrap keys and values.\nObservation: the result of the action\n```\n\nOnce
+      all necessary information is gathered, return the following format:\n\n```\nThought:
+      I now know the final answer\nFinal Answer: the final answer to the original
+      input question\n```"}, {"role": "user", "content": "\nCurrent Task: Give me
+      a list of 5 interesting ideas to explore for an article, what makes them unique
+      and interesting.\n\nThis is the expected criteria for your final answer: Bullet
+      point list of 5 interesting ideas.\nyou MUST return the actual complete content
+      as the final answer, not a summary.\n\nBegin! This is VERY important to you,
+      use the tools available and give your best Final Answer, your job depends on
+      it!\n\nThought:"}], "model": "gpt-4o-mini", "stop": ["\nObservation:"]}'
+    headers:
+      accept:
+      - application/json
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      content-length:
+      - '1666'
+      content-type:
+      - application/json
+      cookie:
+      - _cfuvid=CW_cKQGYWY3cL.S6Xo5z0cmkmWHy5Q50OA_KjPEijNk-1735926034530-0.0.1.1-604800000
+      host:
+      - api.openai.com
+      user-agent:
+      - OpenAI/Python 1.68.2
+      x-stainless-arch:
+      - arm64
+      x-stainless-async:
+      - 'false'
+      x-stainless-lang:
+      - python
+      x-stainless-os:
+      - MacOS
+      x-stainless-package-version:
+      - 1.68.2
+      x-stainless-raw-response:
+      - 'true'
+      x-stainless-read-timeout:
+      - '600.0'
+      x-stainless-retry-count:
+      - '0'
+      x-stainless-runtime:
+      - CPython
+      x-stainless-runtime-version:
+      - 3.11.7
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAAAwAAAP//jJNPb9swDMXv+RSELrskRZukSZNbBxRbUWwYdhmwtTAYiba5ypQn0f2z
+        It+9kNPW6dYBu9iAfnzP5BP9MAIw7MwajK1RbdP6yfvvG7r79PnDxYK/LPni5uO35uxstfp6fTvz
+        1oyzImx+ktVn1YENTetJOcgO20iolF2PlvPlyfR4NZ/1oAmOfJZVrU7mYdKw8GR6OJ1PDpeTo5Mn
+        dR3YUjJr+DECAHjon7lPcXRn1nA4fj5pKCWsyKxfigBMDD6fGEyJk6KoGQ/QBlGSvvVzECIHGqAi
+        oYhKgOA5KYQSWJQiJWWpAKOy9QTsCBNE8nm4rDs9BxTXvyoSTWMog+1S1gQBrYkjdMK/OhJKqa+N
+        5OkGxRKwgAaH9+8SKNlagg8VW/TgUVyy2NLBpVzKqc25ruG2RgVs8Hd21xA8wDOEc2k7XcPDFmB/
+        1khllzDnLZ33ewBFgmKW9ilfPZHtS64+VG0Mm/SH1JQsnOoiEqYgOcOkoTU93Y4Arvr7615diWlj
+        aFotNFxT/7nZdLHzM8PaDHR+9AQ1KPo91WI5fsOvcKTIPu1tgLFoa3KDdFgX7ByHPTDam/rvbt7y
+        3k3OUv2P/QCspVbJFW0kx/b1xENZpPxX/avsJeW+YZMo3rClQplivglHJXZ+t+sm3SelpihZKopt
+        5N3Cl21xPKfNfOMWq5kZbUePAAAA//8DALOFcXD+AwAA
+    headers:
+      CF-RAY:
+      - 9433a372ec1069e6-LAS
+      Connection:
+      - keep-alive
+      Content-Encoding:
+      - gzip
+      Content-Type:
+      - application/json
+      Date:
+      - Wed, 21 May 2025 11:12:24 GMT
+      Server:
+      - cloudflare
+      Set-Cookie:
+      - __cf_bm=SC.7rKr584CqggyyZVMEQ5_zFD.g4Q5djrKS1Kg2ifs-1747825944-1.0.1.1-M3vY0AX_JtRWZBGWsq8v4VWUTYLoQRB5_X2WbagS7emC73L80mIv3OUlMwPOwh7ag8LdkVtbkQ_hpAdM9kVJ_wyV7mhTNCoCPLE._sZWMeI;
+        path=/; expires=Wed, 21-May-25 11:42:24 GMT; domain=.api.openai.com; HttpOnly;
+        Secure; SameSite=None
+      - _cfuvid=LMbhtXYRu2foKMlmDSxZF0LlpAWtafPdjq_4PWulGz0-1747825944424-0.0.1.1-604800000;
+        path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - nosniff
+      access-control-expose-headers:
+      - X-Request-ID
+      alt-svc:
+      - h3=":443"; ma=86400
+      cf-cache-status:
+      - DYNAMIC
+      openai-organization:
+      - crewai-iuxna1
+      openai-processing-ms:
+      - '819'
+      openai-version:
+      - '2020-10-01'
+      strict-transport-security:
+      - max-age=31536000; includeSubDomains; preload
+      x-envoy-upstream-service-time:
+      - '827'
+      x-ratelimit-limit-requests:
+      - '30000'
+      x-ratelimit-limit-tokens:
+      - '150000000'
+      x-ratelimit-remaining-requests:
+      - '29999'
+      x-ratelimit-remaining-tokens:
+      - '149999620'
+      x-ratelimit-reset-requests:
+      - 2ms
+      x-ratelimit-reset-tokens:
+      - 0s
+      x-request-id:
+      - req_93e3b862779b855ab166d171911fa9e0
+    status:
+      code: 200
+      message: OK
 version: 1

tests/conftest.py

@@ -46,4 +46,6 @@ def setup_test_environment():
 def vcr_config(request) -> dict:
     return {
         "cassette_library_dir": "tests/cassettes",
+        "record_mode": "new_episodes",
+        "filter_headers": [("authorization", "AUTHORIZATION-XXX")],
     }

tests/task_test.py

@@ -398,6 +398,79 @@ def test_output_json_hierarchical():
     assert result.json == '{"score": 4}'
     assert result.to_dict() == {"score": 4}
 
+@pytest.mark.vcr(filter_headers=["authorization"])
+def test_inject_date():
+    reporter = Agent(
+        role="Reporter",
+        goal="Report the date",
+        backstory="You're an expert reporter, specialized in reporting the date.",
+        allow_delegation=False,
+        inject_date=True,
+    )
+
+    task = Task(
+        description="What is the date today?",
+        expected_output="The date today as you were told, same format as the date you were told.",
+        agent=reporter,
+    )
+
+    crew = Crew(
+        agents=[reporter],
+        tasks=[task],
+        process=Process.sequential,
+    )
+    result = crew.kickoff()
+    assert "2025-05-21" in result.raw
+
+@pytest.mark.vcr(filter_headers=["authorization"])
+def test_inject_date_custom_format():
+    reporter = Agent(
+        role="Reporter",
+        goal="Report the date",
+        backstory="You're an expert reporter, specialized in reporting the date.",
+        allow_delegation=False,
+        inject_date=True,
+        date_format="%B %d, %Y",
+    )
+
+    task = Task(
+        description="What is the date today?",
+        expected_output="The date today.",
+        agent=reporter,
+    )
+
+    crew = Crew(
+        agents=[reporter],
+        tasks=[task],
+        process=Process.sequential,
+    )
+    result = crew.kickoff()
+    assert "May 21, 2025" in result.raw
+
+@pytest.mark.vcr(filter_headers=["authorization"])
+def test_no_inject_date():
+    reporter = Agent(
+        role="Reporter",
+        goal="Report the date",
+        backstory="You're an expert reporter, specialized in reporting the date.",
+        allow_delegation=False,
+        inject_date=False,
+    )
+
+    task = Task(
+        description="What is the date today?",
+        expected_output="The date today.",
+        agent=reporter,
+    )
+
+    crew = Crew(
+        agents=[reporter],
+        tasks=[task],
+        process=Process.sequential,
+    )
+    result = crew.kickoff()
+    assert "2025-05-21" not in result.raw
+
 
 @pytest.mark.vcr(filter_headers=["authorization"])
 def test_json_property_without_output_json():

tests/test_agent_inject_date.py

@@ -0,0 +1,117 @@
+from datetime import datetime
+from unittest.mock import patch
+
+from crewai.agent import Agent
+from crewai.task import Task
+
+
+def test_agent_inject_date():
+    """Test that the inject_date flag injects the current date into the task.
+    
+    Tests that when inject_date=True, the current date is added to the task description.
+    """
+    with patch('datetime.datetime') as mock_datetime:
+        mock_datetime.now.return_value = datetime(2025, 1, 1)
+        
+        agent = Agent(
+            role="test_agent",
+            goal="test_goal",
+            backstory="test_backstory",
+            inject_date=True,
+        )
+        
+        task = Task(
+            description="Test task",
+            expected_output="Test output",
+            agent=agent,
+        )
+        
+        # Store original description
+        original_description = task.description
+        
+        agent._inject_date_to_task(task)
+        
+        assert "Current Date: 2025-01-01" in task.description
+        assert task.description != original_description
+
+
+def test_agent_without_inject_date():
+    """Test that without inject_date flag, no date is injected.
+    
+    Tests that when inject_date=False (default), no date is added to the task description.
+    """
+    agent = Agent(
+        role="test_agent",
+        goal="test_goal",
+        backstory="test_backstory",
+        # inject_date is False by default
+    )
+    
+    task = Task(
+        description="Test task",
+        expected_output="Test output",
+        agent=agent,
+    )
+    
+    original_description = task.description
+    
+    agent._inject_date_to_task(task)
+    
+    assert task.description == original_description
+
+
+def test_agent_inject_date_custom_format():
+    """Test that the inject_date flag with custom date_format works correctly.
+    
+    Tests that when inject_date=True with a custom date_format, the date is formatted correctly.
+    """
+    with patch('datetime.datetime') as mock_datetime:
+        mock_datetime.now.return_value = datetime(2025, 1, 1)
+        
+        agent = Agent(
+            role="test_agent",
+            goal="test_goal",
+            backstory="test_backstory",
+            inject_date=True,
+            date_format="%d/%m/%Y",
+        )
+        
+        task = Task(
+            description="Test task",
+            expected_output="Test output",
+            agent=agent,
+        )
+        
+        # Store original description
+        original_description = task.description
+        
+        agent._inject_date_to_task(task)
+        
+        assert "Current Date: 01/01/2025" in task.description
+        assert task.description != original_description
+
+
+def test_agent_inject_date_invalid_format():
+    """Test error handling with invalid date format.
+    
+    Tests that when an invalid date_format is provided, the task description remains unchanged.
+    """
+    agent = Agent(
+        role="test_agent",
+        goal="test_goal",
+        backstory="test_backstory",
+        inject_date=True,
+        date_format="invalid",
+    )
+    
+    task = Task(
+        description="Test task",
+        expected_output="Test output",
+        agent=agent,
+    )
+    
+    original_description = task.description
+    
+    agent._inject_date_to_task(task)
+    
+    assert task.description == original_description

tests/test_markdown_task.py

@@ -0,0 +1,96 @@
+"""Test the markdown attribute in Task class."""
+
+import pytest
+from pydantic import BaseModel
+
+from crewai import Agent, Task
+
+
+@pytest.mark.parametrize(
+    "markdown_enabled,should_contain_instructions",
+    [
+        (True, True),
+        (False, False),
+    ],
+)
+def test_markdown_option_in_task_prompt(markdown_enabled, should_contain_instructions):
+    """Test that markdown flag correctly controls the inclusion of markdown formatting instructions."""
+    
+    researcher = Agent(
+        role="Researcher",
+        goal="Research a topic",
+        backstory="You're a researcher specialized in providing well-formatted content.",
+        allow_delegation=False,
+    )
+
+    task = Task(
+        description="Research advances in AI in 2023",
+        expected_output="A summary of key AI advances in 2023",
+        markdown=markdown_enabled,
+        agent=researcher,
+    )
+
+    prompt = task.prompt()
+    
+    assert "Research advances in AI in 2023" in prompt
+    assert "A summary of key AI advances in 2023" in prompt
+    
+    if should_contain_instructions:
+        assert "Your final answer MUST be formatted in Markdown syntax." in prompt
+        assert "Use # for headers" in prompt
+        assert "Use ** for bold text" in prompt
+    else:
+        assert "Your final answer MUST be formatted in Markdown syntax." not in prompt
+
+
+def test_markdown_with_empty_description():
+    """Test markdown formatting with empty description."""
+    
+    researcher = Agent(
+        role="Researcher",
+        goal="Research a topic",
+        backstory="You're a researcher.",
+        allow_delegation=False,
+    )
+
+    task = Task(
+        description="",
+        expected_output="A summary",
+        markdown=True,
+        agent=researcher,
+    )
+
+    prompt = task.prompt()
+    
+    assert prompt.strip() != ""
+    assert "A summary" in prompt
+    assert "Your final answer MUST be formatted in Markdown syntax." in prompt
+
+
+def test_markdown_with_complex_output_format():
+    """Test markdown with JSON output format to ensure compatibility."""
+    
+    class ResearchOutput(BaseModel):
+        title: str
+        findings: list[str]
+    
+    researcher = Agent(
+        role="Researcher",
+        goal="Research a topic",
+        backstory="You're a researcher.",
+        allow_delegation=False,
+    )
+
+    task = Task(
+        description="Research topic",
+        expected_output="Research results",
+        markdown=True,
+        output_json=ResearchOutput,
+        agent=researcher,
+    )
+
+    prompt = task.prompt()
+    
+    assert "Your final answer MUST be formatted in Markdown syntax." in prompt
+    assert "Research topic" in prompt
+    assert "Research results" in prompt