build: ensure tiktoken greather than 0.8.0 due Python 3.13 compatibility

Added explicit tokenizers dependency: Added tokenizers>=0.20.3 to ensure a version compatible with Python 3.13 is used.

.github/workflows/tests.yml

@@ -14,7 +14,7 @@ jobs:
     timeout-minutes: 15
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

README.md

@@ -403,7 +403,7 @@ In addition to the sequential process, you can use the hierarchical process, whi
 
 ## Key Features
 
-CrewAI stands apart as a lean, standalone, high-performance framework delivering simplicity, flexibility, and precise control—free from the complexity and limitations found in other agent frameworks.
+CrewAI stands apart as a lean, standalone, high-performance multi-AI Agent framework delivering simplicity, flexibility, and precise control—free from the complexity and limitations found in other agent frameworks.
 
 - **Standalone & Lean**: Completely independent from other frameworks like LangChain, offering faster execution and lighter resource demands.
 - **Flexible & Precise**: Easily orchestrate autonomous agents through intuitive [Crews](https://docs.crewai.com/concepts/crews) or precise [Flows](https://docs.crewai.com/concepts/flows), achieving perfect balance for your needs.

docs/common-room-tracking.js

@@ -0,0 +1,18 @@
+(function() {
+  if (typeof window === 'undefined') return;
+  if (typeof window.signals !== 'undefined') return;
+  var script = document.createElement('script');
+  script.src = 'https://cdn.cr-relay.com/v1/site/883520f4-c431-44be-80e7-e123a1ee7a2b/signals.js';
+  script.async = true;
+  window.signals = Object.assign(
+    [],
+    ['page', 'identify', 'form'].reduce(function (acc, method){
+      acc[method] = function () {
+        signals.push([method, arguments]);
+        return signals;
+      };
+     return acc;
+    }, {})
+  );
+  document.head.appendChild(script);
+})(); 

docs/docs.json

@@ -85,7 +85,12 @@
           {
             "group": "MCP Integration",
             "pages": [
-              "mcp/crewai-mcp-integration"
+              "mcp/overview",
+              "mcp/stdio",
+              "mcp/sse",
+              "mcp/streamable-http",
+              "mcp/multiple-servers",
+              "mcp/security"
             ]
           },
           {
@@ -217,7 +222,6 @@
               "learn/dalle-image-generation",
               "learn/force-tool-output-as-result",
               "learn/hierarchical-process",
-              "learn/human-in-the-loop",
               "learn/human-input-on-execution",
               "learn/kickoff-async",
               "learn/kickoff-for-each",
@@ -269,6 +273,7 @@
               "enterprise/guides/slack-trigger",
               "enterprise/guides/team-management",
               "enterprise/guides/webhook-automation",
+              "enterprise/guides/human-in-the-loop",
               "enterprise/guides/zapier-trigger"
             ]
           },

docs/enterprise/guides/human-in-the-loop.mdx

@@ -0,0 +1,78 @@
+---
+title: "HITL Workflows"
+description: "Learn how to implement Human-In-The-Loop workflows in CrewAI for enhanced decision-making"
+icon: "user-check"
+---
+
+Human-In-The-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. This guide shows you how to implement HITL within CrewAI.
+
+## Setting Up HITL Workflows
+
+<Steps>
+    <Step title="Configure Your Task">
+        Set up your task with human input enabled:
+        <Frame>
+            <img src="/images/enterprise/crew-human-input.png" alt="Crew Human Input" />
+        </Frame>
+    </Step>
+
+    <Step title="Provide Webhook URL">
+        When kicking off your crew, include a webhook URL for human input:
+        <Frame>
+            <img src="/images/enterprise/crew-webhook-url.png" alt="Crew Webhook URL" />
+        </Frame>
+    </Step>
+
+    <Step title="Receive Webhook Notification">
+        Once the crew completes the task requiring human input, you'll receive a webhook notification containing:
+            - **Execution ID**
+            - **Task ID**
+            - **Task output**
+    </Step>
+
+    <Step title="Review Task Output">
+        The system will pause in the `Pending Human Input` state. Review the task output carefully.
+    </Step>
+
+    <Step title="Submit Human Feedback">
+        Call the resume endpoint of your crew with the following information:
+        <Frame>
+            <img src="/images/enterprise/crew-resume-endpoint.png" alt="Crew Resume Endpoint" />
+        </Frame>
+        <Warning>
+            **Feedback Impact on Task Execution**:
+            It's crucial to exercise care when providing feedback, as the entire feedback content will be incorporated as additional context for further task executions.
+        </Warning>
+        This means:
+        - All information in your feedback becomes part of the task's context.
+        - Irrelevant details may negatively influence it.
+        - Concise, relevant feedback helps maintain task focus and efficiency.
+        - Always review your feedback carefully before submission to ensure it contains only pertinent information that will positively guide the task's execution.
+    </Step>
+    <Step title="Handle Negative Feedback">
+        If you provide negative feedback:
+        - The crew will retry the task with added context from your feedback.
+        - You'll receive another webhook notification for further review.
+        - Repeat steps 4-6 until satisfied.
+    </Step>
+
+    <Step title="Execution Continuation">
+        When you submit positive feedback, the execution will proceed to the next steps.
+    </Step>
+</Steps>
+
+## Best Practices
+
+- **Be Specific**: Provide clear, actionable feedback that directly addresses the task at hand
+- **Stay Relevant**: Only include information that will help improve the task execution
+- **Be Timely**: Respond to HITL prompts promptly to avoid workflow delays
+- **Review Carefully**: Double-check your feedback before submitting to ensure accuracy
+
+## Common Use Cases
+
+HITL workflows are particularly valuable for:
+- Quality assurance and validation
+- Complex decision-making scenarios
+- Sensitive or high-stakes operations
+- Creative tasks requiring human judgment
+- Compliance and regulatory reviews 

docs/installation.mdx

@@ -22,7 +22,7 @@ Watch this video tutorial for a step-by-step demonstration of the installation p
 <Note>
   **Python Version Requirements**
 
-  CrewAI requires `Python >=3.10 and <3.13`. Here's how to check your version:
+  CrewAI requires `Python >=3.10 and <=3.13`. Here's how to check your version:
   ```bash
   python3 --version
   ```

docs/learn/llm-connections.mdx

@@ -9,7 +9,7 @@ icon: brain-circuit
 CrewAI uses LiteLLM to connect to a wide variety of Language Models (LLMs). This integration provides extensive versatility, allowing you to use models from numerous providers with a simple, unified interface.
 
 <Note>
-    By default, CrewAI uses the `gpt-4o-mini` model. This is determined by the `OPENAI_MODEL_NAME` environment variable, which defaults to "gpt-4o-mini" if not set. 
+    By default, CrewAI uses the `gpt-4o-mini` model. This is determined by the `OPENAI_MODEL_NAME` environment variable, which defaults to "gpt-4o-mini" if not set.
     You can easily configure your agents to use a different model or provider as described in this guide.
 </Note>
 
@@ -117,18 +117,27 @@ You can connect to OpenAI-compatible LLMs using either environment variables or
 <Tabs>
     <Tab title="Using Environment Variables">
         <CodeGroup>
-        ```python Code
+        ```python Generic
         import os
 
         os.environ["OPENAI_API_KEY"] = "your-api-key"
         os.environ["OPENAI_API_BASE"] = "https://api.your-provider.com/v1"
         os.environ["OPENAI_MODEL_NAME"] = "your-model-name"
         ```
+
+        ```python Google
+        import os
+
+        # Example using Gemini's OpenAI-compatible API.
+        os.environ["OPENAI_API_KEY"] = "your-gemini-key"  # Should start with AIza...
+        os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/"
+        os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash"  # Add your Gemini model here, under openai/
+        ```
         </CodeGroup>
     </Tab>
     <Tab title="Using LLM Class Attributes">
         <CodeGroup>
-            ```python Code
+            ```python Generic
             llm = LLM(
                 model="custom-model-name",
                 api_key="your-api-key",
@@ -136,6 +145,16 @@ You can connect to OpenAI-compatible LLMs using either environment variables or
             )
             agent = Agent(llm=llm, ...)
             ```
+
+            ```python Google
+            # Example using Gemini's OpenAI-compatible API
+            llm = LLM(
+                model="openai/gemini-2.0-flash",
+                base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
+                api_key="your-gemini-key",  # Should start with AIza...
+            )
+            agent = Agent(llm=llm, ...)
+            ```
         </CodeGroup>
     </Tab>
 </Tabs>
@@ -169,7 +188,7 @@ For local models like those provided by Ollama:
 
 You can change the base API URL for any LLM provider by setting the `base_url` parameter:
 
-```python Code  
+```python Code
 llm = LLM(
     model="custom-model-name",
     base_url="https://api.your-provider.com/v1",

docs/mcp/crewai-mcp-integration.mdx

@@ -1,243 +0,0 @@
----
-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>
-
-## Video Tutorial
-Watch this video tutorial for a comprehensive guide on MCP integration with CrewAI:
-
-<iframe
-  width="100%"
-  height="400"
-  src="https://www.youtube.com/embed/TpQ45lAZh48"
-  title="CrewAI MCP Integration Guide"
-  frameborder="0"
-  style={{ borderRadius: '10px' }}
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowfullscreen
-></iframe>
-
-## 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.

docs/mcp/multiple-servers.mdx

@@ -0,0 +1,64 @@
+---
+title: Connecting to Multiple MCP Servers
+description: Learn how to use MCPServerAdapter in CrewAI to connect to multiple MCP servers simultaneously and aggregate their tools.
+icon: layer-group
+---
+
+## Overview
+
+`MCPServerAdapter` in `crewai-tools` allows you to connect to multiple MCP servers concurrently. This is useful when your agents need to access tools distributed across different services or environments. The adapter aggregates tools from all specified servers, making them available to your CrewAI agents.
+
+## Configuration
+
+To connect to multiple servers, you provide a list of server parameter dictionaries to `MCPServerAdapter`. Each dictionary in the list should define the parameters for one MCP server.
+
+Supported transport types for each server in the list include `stdio`, `sse`, and `streamable-http`.
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+from mcp import StdioServerParameters # Needed for Stdio example
+
+# Define parameters for multiple MCP servers
+server_params_list = [
+    # Streamable HTTP Server
+    {
+        "url": "http://localhost:8001/mcp", 
+        "transport": "streamable-http"
+    },
+    # SSE Server
+    {
+        "url": "http://localhost:8000/sse",
+        "transport": "sse"
+    },
+    # StdIO Server
+    StdioServerParameters(
+        command="python3",
+        args=["servers/your_stdio_server.py"],
+        env={"UV_PYTHON": "3.12", **os.environ},
+    )
+]
+
+try:
+    with MCPServerAdapter(server_params_list) as aggregated_tools:
+        print(f"Available aggregated tools: {[tool.name for tool in aggregated_tools]}")
+
+        multi_server_agent = Agent(
+            role="Versatile Assistant",
+            goal="Utilize tools from local Stdio, remote SSE, and remote HTTP MCP servers.",
+            backstory="An AI agent capable of leveraging a diverse set of tools from multiple sources.",
+            tools=aggregated_tools, # All tools are available here
+            verbose=True,
+        )
+
+        ... # Your other agent, tasks, and crew code here
+
+except Exception as e:
+    print(f"Error connecting to or using multiple MCP servers (Managed): {e}")
+    print("Ensure all MCP servers are running and accessible with correct configurations.")
+
+```
+
+## Connection Management
+
+When using the context manager (`with` statement), `MCPServerAdapter` handles the lifecycle (start and stop) of all connections to the configured MCP servers. This simplifies resource management and ensures that all connections are properly closed when the context is exited.

docs/mcp/overview.mdx

@@ -0,0 +1,164 @@
+---
+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. 
+
+We currently support the following transport mechanisms: 
+
+- **Stdio**: for local servers (communication via standard input/output between processes on the same machine)
+- **Server-Sent Events (SSE)**: for remote servers (unidirectional, real-time data streaming from server to client over HTTP)
+- **Streamable HTTP**: for remote servers (flexible, potentially bi-directional communication over HTTP, often utilizing SSE for server-to-client streams)
+
+## Video Tutorial
+Watch this video tutorial for a comprehensive guide on MCP integration with CrewAI:
+
+<iframe
+  width="100%"
+  height="400"
+  src="https://www.youtube.com/embed/TpQ45lAZh48"
+  title="CrewAI MCP Integration Guide"
+  frameborder="0"
+  style={{ borderRadius: '10px' }}
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+## 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]'
+```
+
+## Key Concepts & Getting Started
+
+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 and simplifies connection management.
+
+Using a Python context manager (`with` statement) is the **recommended approach** for `MCPServerAdapter`. It automatically handles starting and stopping the connection to the MCP server.
+
+```python
+from crewai import Agent
+from crewai_tools import MCPServerAdapter
+from mcp import StdioServerParameters # For Stdio Server
+
+# Example server_params (choose one based on your server type):
+# 1. Stdio Server:
+server_params=StdioServerParameters(
+    command="python3", 
+    args=["servers/your_server.py"],
+    env={"UV_PYTHON": "3.12", **os.environ},
+)
+
+# 2. SSE Server:
+server_params = {
+    "url": "http://localhost:8000/sse", 
+    "transport": "sse"
+}
+
+# 3. Streamable HTTP Server:
+server_params = {
+    "url": "http://localhost:8001/mcp", 
+    "transport": "streamable-http"
+}
+
+# Example usage (uncomment and adapt once server_params is set):
+with MCPServerAdapter(server_params) as mcp_tools:
+    print(f"Available tools: {[tool.name for tool in mcp_tools]}")
+    
+    my_agent = Agent(
+        role="MCP Tool User",
+        goal="Utilize tools from an MCP server.",
+        backstory="I can connect to MCP servers and use their tools.",
+        tools=mcp_tools, # Pass the loaded tools to your agent
+        reasoning=True,
+        verbose=True
+    )
+    # ... rest of your crew setup ...
+```
+This general pattern shows how to integrate tools. For specific examples tailored to each transport, refer to the detailed guides below.
+
+## Explore MCP Integrations
+
+<CardGroup cols={2}>
+  <Card 
+    title="Stdio Transport" 
+    icon="server" 
+    href="/mcp/stdio"
+    color="#3B82F6"
+  >
+    Connect to local MCP servers via standard input/output. Ideal for scripts and local executables.
+  </Card>
+  <Card 
+    title="SSE Transport" 
+    icon="wifi" 
+    href="/mcp/sse"
+    color="#10B981"
+  >
+    Integrate with remote MCP servers using Server-Sent Events for real-time data streaming.
+  </Card>
+  <Card 
+    title="Streamable HTTP Transport" 
+    icon="globe" 
+    href="/mcp/streamable-http"
+    color="#F59E0B"
+  >
+    Utilize flexible Streamable HTTP for robust communication with remote MCP servers.
+  </Card>
+  <Card 
+    title="Connecting to Multiple Servers" 
+    icon="layer-group" 
+    href="/mcp/multiple-servers"
+    color="#8B5CF6"
+  >
+    Aggregate tools from several MCP servers simultaneously using a single adapter.
+  </Card>
+  <Card 
+    title="Security Considerations" 
+    icon="lock" 
+    href="/mcp/security"
+    color="#EF4444"
+  >
+    Review important security best practices for MCP integration to keep your agents safe.
+  </Card>
+</CardGroup>
+
+Checkout this repository for full demos and examples of MCP integration with CrewAI! 👇
+
+<Card 
+title="GitHub Repository"
+icon="github"
+href="https://github.com/tonykipkemboi/crewai-mcp-demo"
+target="_blank"
+>
+CrewAI MCP Demo
+</Card>
+
+## 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 [Anthropic's MCP Transport Security docs](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).
+
+### 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.

docs/mcp/security.mdx

@@ -0,0 +1,166 @@
+---
+title: MCP Security Considerations
+description: Learn about important security best practices when integrating MCP servers with your CrewAI agents.
+icon: lock
+---
+
+## Overview
+
+<Warning>
+The most critical aspect of MCP security is **trust**. You should **only** connect your CrewAI agents to MCP servers that you fully trust.
+</Warning>
+
+When integrating external services like MCP (Model Context Protocol) servers into your CrewAI agents, security is paramount. 
+MCP servers can execute code, access data, or interact with other systems based on the tools they expose. 
+It's crucial to understand the implications and follow best practices to protect your applications and data.
+
+### Risks
+
+- Execute arbitrary code on the machine where the agent is running (especially with `Stdio` transport if the server can control the command executed).
+- Expose sensitive data from your agent or its environment.
+- Manipulate your agent's behavior in unintended ways, including making unauthorized API calls on your behalf.
+- Hijack your agent's reasoning process through sophisticated prompt injection techniques (see below).
+
+### 1. Trusting MCP Servers
+
+<Warning>
+**Only connect to MCP servers that you trust.**
+</Warning>
+
+Before configuring `MCPServerAdapter` to connect to an MCP server, ensure you know:
+- **Who operates the server?** Is it a known, reputable service, or an internal server under your control?
+- **What tools does it expose?** Understand the capabilities of the tools. Could they be misused if an attacker gained control or if the server itself is malicious?
+- **What data does it access or process?** Be aware of any sensitive information that might be sent to or handled by the MCP server.
+
+Avoid connecting to unknown or unverified MCP servers, especially if your agents handle sensitive tasks or data.
+
+### 2. Secure Prompt Injection via Tool Metadata: The "Model Control Protocol" Risk
+
+A significant and subtle risk is the potential for prompt injection through tool metadata. Here's how it works:
+
+1.  When your CrewAI agent connects to an MCP server, it typically requests a list of available tools.
+2.  The MCP server responds with metadata for each tool, including its name, description, and parameter descriptions.
+3.  Your agent's underlying Language Model (LLM) uses this metadata to understand how and when to use the tools. This metadata is often incorporated into the LLM's system prompt or context.
+4.  A malicious MCP server can craft its tool metadata (names, descriptions) to include hidden or overt instructions. These instructions can act as a prompt injection, effectively telling your LLM to behave in a certain way, reveal sensitive information, or perform malicious actions.
+
+**Crucially, this attack can occur simply by connecting to a malicious server and listing its tools, even if your agent never explicitly decides to *use* any of those tools.** The mere exposure to the malicious metadata can be enough to compromise the agent's behavior.
+
+**Mitigation:**
+
+*   **Extreme Caution with Untrusted Servers:** Reiterate: *Do not connect to MCP servers you do not fully trust.* The risk of metadata injection makes this paramount.
+
+### Stdio Transport Security
+
+Stdio (Standard Input/Output) transport is typically used for local MCP servers running on the same machine as your CrewAI application.
+
+- **Process Isolation**: While generally safer as it doesn't involve network exposure by default, ensure the script or command run by `StdioServerParameters` is from a trusted source and has appropriate file system permissions. A malicious Stdio server script could still harm your local system.
+- **Input Sanitization**: If your Stdio server script takes complex inputs derived from agent interactions, ensure the script itself sanitizes these inputs to prevent command injection or other vulnerabilities within the script's logic.
+- **Resource Limits**: Be mindful that a local Stdio server process consumes local resources (CPU, memory). Ensure it's well-behaved and won't exhaust system resources.
+
+### Confused Deputy Attacks
+
+The [Confused Deputy Problem](https://en.wikipedia.org/wiki/Confused_deputy_problem) is a classic security vulnerability that can manifest in MCP integrations, especially when an MCP server acts as a proxy to other third-party services (e.g., Google Calendar, GitHub) that use OAuth 2.0 for authorization.
+
+**Scenario:**
+
+1.  An MCP server (let's call it `MCP-Proxy`) allows your agent to interact with `ThirdPartyAPI`.
+2.  `MCP-Proxy` uses its own single, static `client_id` when talking to `ThirdPartyAPI`'s authorization server.
+3.  You, as the user, legitimately authorize `MCP-Proxy` to access `ThirdPartyAPI` on your behalf. During this, `ThirdPartyAPI`'s auth server might set a cookie in your browser indicating your consent for `MCP-Proxy`'s `client_id`.
+4.  An attacker crafts a malicious link. This link initiates an OAuth flow with `MCP-Proxy`, but is designed to trick `ThirdPartyAPI`'s auth server.
+5.  If you click this link, and `ThirdPartyAPI`'s auth server sees your existing consent cookie for `MCP-Proxy`'s `client_id`, it might *skip* asking for your consent again.
+6.  `MCP-Proxy` might then be tricked into forwarding an authorization code (for `ThirdPartyAPI`) to the attacker, or an MCP authorization code that the attacker can use to impersonate you to `MCP-Proxy`.
+
+**Mitigation (Primarily for MCP Server Developers):**
+
+*   MCP proxy servers using static client IDs for downstream services **must** obtain explicit user consent for *each client application or agent* connecting to them *before* initiating an OAuth flow with the third-party service. This means `MCP-Proxy` itself should show a consent screen.
+
+**CrewAI User Implication:**
+
+*   Be cautious if an MCP server redirects you for multiple OAuth authentications, especially if it seems unexpected or if the permissions requested are overly broad.
+*   Prefer MCP servers that clearly delineate their own identity versus the third-party services they might proxy.
+
+### Remote Transport Security (SSE & Streamable HTTP)
+
+When connecting to remote MCP servers via Server-Sent Events (SSE) or Streamable HTTP, standard web security practices are essential.
+
+### SSE Security Considerations
+
+### a. DNS Rebinding Attacks (Especially for SSE)
+
+<Critical>
+**Protect against DNS Rebinding Attacks.**
+</Critical>
+
+DNS rebinding allows an attacker-controlled website to bypass the same-origin policy and make requests to servers on the user's local network (e.g., `localhost`) or intranet. This is particularly risky if you run an MCP server locally (e.g., for development) and an agent in a browser-like environment (though less common for typical CrewAI backend setups) or if the MCP server is on an internal network.
+
+**Mitigation Strategies for MCP Server Implementers:**
+- **Validate `Origin` and `Host` Headers**: MCP servers (especially SSE ones) should validate the `Origin` and/or `Host` HTTP headers to ensure requests are coming from expected domains/clients.
+- **Bind to `localhost` (127.0.0.1)**: When running MCP servers locally for development, bind them to `127.0.0.1` instead of `0.0.0.0`. This prevents them from being accessible from other machines on the network.
+- **Authentication**: Require authentication for all connections to your MCP server if it's not intended for public anonymous access.
+
+### b. Use HTTPS
+
+- **Encrypt Data in Transit**: Always use HTTPS (HTTP Secure) for the URLs of remote MCP servers. This encrypts the communication between your CrewAI application and the MCP server, protecting against eavesdropping and man-in-the-middle attacks. `MCPServerAdapter` will respect the scheme (`http` or `https`) provided in the URL.
+
+### c. Token Passthrough (Anti-Pattern)
+
+This is primarily a concern for MCP server developers but understanding it helps in choosing secure servers.
+
+"Token passthrough" is when an MCP server accepts an access token from your CrewAI agent (which might be a token for a *different* service, say `ServiceA`) and simply passes it through to another downstream API (`ServiceB`) without proper validation. Specifically, `ServiceB` (or the MCP server itself) should only accept tokens that were explicitly issued *for them* (i.e., the 'audience' claim in the token matches the server/service).
+
+**Risks:**
+
+*   Bypasses security controls (like rate limiting or fine-grained permissions) on the MCP server or the downstream API.
+*   Breaks audit trails and accountability.
+*   Allows misuse of stolen tokens.
+
+**Mitigation (For MCP Server Developers):**
+
+*   MCP servers **MUST NOT** accept tokens that were not explicitly issued for them. They must validate the token's audience claim.
+
+**CrewAI User Implication:**
+
+*   While not directly controllable by the user, this highlights the importance of connecting to well-designed MCP servers that adhere to security best practices.
+
+#### Authentication and Authorization
+
+- **Verify Identity**: If the MCP server provides sensitive tools or access to private data, it MUST implement strong authentication mechanisms to verify the identity of the client (your CrewAI application). This could involve API keys, OAuth tokens, or other standard methods.
+- **Principle of Least Privilege**: Ensure the credentials used by `MCPServerAdapter` (if any) have only the necessary permissions to access the required tools.
+
+### d. Input Validation and Sanitization
+
+- **Input Validation is Critical**: MCP servers **must** rigorously validate all inputs received from agents *before* processing them or passing them to tools. This is a primary defense against many common vulnerabilities:
+    - **Command Injection:** If a tool constructs shell commands, SQL queries, or other interpreted language statements based on input, the server must meticulously sanitize this input to prevent malicious commands from being injected and executed.
+    - **Path Traversal:** If a tool accesses files based on input parameters, the server must validate and sanitize these paths to prevent access to unauthorized files or directories (e.g., by blocking `../` sequences).
+    - **Data Type & Range Checks:** Servers must ensure that input data conforms to the expected data types (e.g., string, number, boolean) and falls within acceptable ranges or adheres to defined formats (e.g., regex for URLs).
+    - **JSON Schema Validation:** All tool parameters should be strictly validated against their defined JSON schema. This helps catch malformed requests early.
+- **Client-Side Awareness**: While server-side validation is paramount, as a CrewAI user, be mindful of the data your agents are constructed to send to MCP tools, especially if interacting with less-trusted or new MCP servers.
+
+### e. Rate Limiting and Resource Management
+
+- **Prevent Abuse**: MCP servers should implement rate limiting to prevent abuse, whether intentional (Denial of Service attacks) or unintentional (e.g., a misconfigured agent making too many requests).
+- **Client-Side Retries**: Implement sensible retry logic in your CrewAI tasks if transient network issues or server rate limits are expected, but avoid aggressive retries that could exacerbate server load.
+
+## 4. Secure MCP Server Implementation Advice (For Developers)
+
+If you are developing an MCP server that CrewAI agents might connect to, consider these best practices in addition to the points above:
+
+- **Follow Secure Coding Practices**: Adhere to standard secure coding principles for your chosen language and framework (e.g., OWASP Top 10).
+- **Principle of Least Privilege**: Ensure the process running the MCP server (especially for `Stdio`) has only the minimum necessary permissions. Tools themselves should also operate with the least privilege required to perform their function.
+- **Dependency Management**: Keep all server-side dependencies, including operating system packages, language runtimes, and third-party libraries, up-to-date to patch known vulnerabilities. Use tools to scan for vulnerable dependencies.
+- **Secure Defaults**: Design your server and its tools to be secure by default. For example, features that could be risky should be off by default or require explicit opt-in with clear warnings.
+- **Access Control for Tools**: Implement robust mechanisms to control which authenticated and authorized agents or users can access specific tools, especially those that are powerful, sensitive, or incur costs.
+- **Secure Error Handling**: Servers should not expose detailed internal error messages, stack traces, or debugging information to the client, as these can reveal internal workings or potential vulnerabilities. Log errors comprehensively on the server-side for diagnostics.
+- **Comprehensive Logging and Monitoring**: Implement detailed logging of security-relevant events (e.g., authentication attempts, tool invocations, errors, authorization changes). Monitor these logs for suspicious activity or abuse patterns.
+- **Adherence to MCP Authorization Spec**: If implementing authentication and authorization, strictly follow the [MCP Authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization) and relevant [OAuth 2.0 security best practices](https://datatracker.ietf.org/doc/html/rfc9700).
+- **Regular Security Audits**: If your MCP server handles sensitive data, performs critical operations, or is publicly exposed, consider periodic security audits by qualified professionals.
+
+## 5. Further Reading
+
+For more detailed information on MCP security, refer to the official documentation:
+- **[MCP Transport Security](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)**
+
+By understanding these security considerations and implementing best practices, you can safely leverage the power of MCP servers in your CrewAI projects. 
+These are by no means exhaustive, but they cover the most common and critical security concerns. 
+The threats will continue to evolve, so it's important to stay informed and adapt your security measures accordingly.
+

docs/mcp/sse.mdx

@@ -0,0 +1,150 @@
+---
+title: SSE Transport
+description: Learn how to connect CrewAI to remote MCP servers using Server-Sent Events (SSE) for real-time communication.
+icon: wifi
+---
+
+## Overview
+
+Server-Sent Events (SSE) provide a standard way for a web server to send updates to a client over a single, long-lived HTTP connection. In the context of MCP, SSE is used for remote servers to stream data (like tool responses) to your CrewAI application in real-time.
+
+## Key Concepts
+
+- **Remote Servers**: SSE is suitable for MCP servers hosted remotely.
+- **Unidirectional Stream**: Typically, SSE is a one-way communication channel from server to client.
+- **`MCPServerAdapter` Configuration**: For SSE, you'll provide the server's URL and specify the transport type.
+
+## Connecting via SSE
+
+You can connect to an SSE-based MCP server using two main approaches for managing the connection lifecycle:
+
+### 1. Fully Managed Connection (Recommended)
+
+Using a Python context manager (`with` statement) is the recommended approach. It automatically handles establishing and closing the connection to the SSE MCP server.
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+
+server_params = {
+    "url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
+    "transport": "sse" 
+}
+
+# Using MCPServerAdapter with a context manager
+try:
+    with MCPServerAdapter(server_params) as tools:
+        print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}")
+
+        # Example: Using a tool from the SSE MCP server
+        sse_agent = Agent(
+            role="Remote Service User",
+            goal="Utilize a tool provided by a remote SSE MCP server.",
+            backstory="An AI agent that connects to external services via SSE.",
+            tools=tools,
+            reasoning=True,
+            verbose=True,
+        )
+
+        sse_task = Task(
+            description="Fetch real-time stock updates for 'AAPL' using an SSE tool.",
+            expected_output="The latest stock price for AAPL.",
+            agent=sse_agent,
+            markdown=True
+        )
+
+        sse_crew = Crew(
+            agents=[sse_agent],
+            tasks=[sse_task],
+            verbose=True,
+            process=Process.sequential
+        )
+        
+        if tools: # Only kickoff if tools were loaded
+            result = sse_crew.kickoff() # Add inputs={'stock_symbol': 'AAPL'} if tool requires it
+            print("\nCrew Task Result (SSE - Managed):\n", result)
+        else:
+            print("Skipping crew kickoff as tools were not loaded (check server connection).")
+
+except Exception as e:
+    print(f"Error connecting to or using SSE MCP server (Managed): {e}")
+    print("Ensure the SSE MCP server is running and accessible at the specified URL.")
+
+```
+
+<Note>
+Replace `"http://localhost:8000/sse"` with the actual URL of your SSE MCP server.
+</Note>
+
+### 2. Manual Connection Lifecycle
+
+If you need finer-grained control, you can manage the `MCPServerAdapter` connection lifecycle manually.
+
+<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>
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+
+server_params = {
+    "url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
+    "transport": "sse"
+}
+
+mcp_server_adapter = None 
+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]}")
+
+    manual_sse_agent = Agent(
+        role="Remote Data Analyst",
+        goal="Analyze data fetched from a remote SSE MCP server using manual connection management.",
+        backstory="An AI skilled in handling SSE connections explicitly.",
+        tools=tools,
+        verbose=True
+    )
+    
+    analysis_task = Task(
+        description="Fetch and analyze the latest user activity trends from the SSE server.",
+        expected_output="A summary report of user activity trends.",
+        agent=manual_sse_agent
+    )
+    
+    analysis_crew = Crew(
+        agents=[manual_sse_agent],
+        tasks=[analysis_task],
+        verbose=True,
+        process=Process.sequential
+    )
+    
+    result = analysis_crew.kickoff()
+    print("\nCrew Task Result (SSE - Manual):\n", result)
+
+except Exception as e:
+    print(f"An error occurred during manual SSE MCP integration: {e}")
+    print("Ensure the SSE MCP server is running and accessible.")
+finally:
+    if mcp_server_adapter and mcp_server_adapter.is_connected:
+        print("Stopping SSE MCP server connection (manual)...")
+        mcp_server_adapter.stop()  # **Crucial: Ensure stop is called**
+    elif mcp_server_adapter:
+        print("SSE MCP server adapter was not connected. No stop needed or start failed.")
+
+```
+
+## Security Considerations for SSE
+
+<Warning>
+**DNS Rebinding Attacks**: SSE transports can be vulnerable to DNS rebinding attacks if the MCP server is not properly secured. This could allow malicious websites to interact with local or intranet-based MCP servers.
+</Warning>
+
+To mitigate this risk:
+- MCP server implementations should **validate `Origin` headers** on incoming SSE connections.
+- When running local SSE MCP servers for development, **bind only to `localhost` (`127.0.0.1`)** rather than all network interfaces (`0.0.0.0`).
+- Implement **proper authentication** for all SSE connections if they expose sensitive tools or data.
+
+For a comprehensive overview of security best practices, please refer to our [Security Considerations](./security.mdx) page and the official [MCP Transport Security documentation](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).

docs/mcp/stdio.mdx

@@ -0,0 +1,134 @@
+---
+title: Stdio Transport
+description: Learn how to connect CrewAI to local MCP servers using the Stdio (Standard Input/Output) transport mechanism.
+icon: server
+---
+
+## Overview
+
+The Stdio (Standard Input/Output) transport is designed for connecting `MCPServerAdapter` to local MCP servers that communicate over their standard input and output streams. This is typically used when the MCP server is a script or executable running on the same machine as your CrewAI application.
+
+## Key Concepts
+
+- **Local Execution**: Stdio transport manages a locally running process for the MCP server.
+- **`StdioServerParameters`**: This class from the `mcp` library is used to configure the command, arguments, and environment variables for launching the Stdio server.
+
+## Connecting via Stdio
+
+You can connect to an Stdio-based MCP server using two main approaches for managing the connection lifecycle:
+
+### 1. Fully Managed Connection (Recommended)
+
+Using a Python context manager (`with` statement) is the recommended approach. It automatically handles starting the MCP server process and stopping it when the context is exited.
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+from mcp import StdioServerParameters
+import os
+
+# Create a StdioServerParameters object
+server_params=StdioServerParameters(
+    command="python3", 
+    args=["servers/your_stdio_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
+    research_agent = Agent(
+        role="Local Data Processor",
+        goal="Process data using a local Stdio-based tool.",
+        backstory="An AI that leverages local scripts via MCP for specialized tasks.",
+        tools=tools,
+        reasoning=True,
+        verbose=True,
+    )
+    
+    processing_task = Task(
+        description="Process the input data file 'data.txt' and summarize its contents.",
+        expected_output="A summary of the processed data.",
+        agent=research_agent,
+        markdown=True
+    )
+    
+    data_crew = Crew(
+        agents=[research_agent],
+        tasks=[processing_task],
+        verbose=True,
+        process=Process.sequential 
+    )
+   
+    result = data_crew.kickoff()
+    print("\nCrew Task Result (Stdio - Managed):\n", result)
+
+```
+
+### 2. Manual Connection Lifecycle
+
+If you need finer-grained control over when the Stdio MCP server process is started and stopped, you can manage the `MCPServerAdapter` lifecycle manually.
+
+<Info>
+You **MUST** call `mcp_server_adapter.stop()` to ensure the server process is terminated and resources are released. Using a `try...finally` block is highly recommended.
+</Info>
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+from mcp import StdioServerParameters
+import os
+
+# Create a StdioServerParameters object
+stdio_params=StdioServerParameters(
+    command="python3", 
+    args=["servers/your_stdio_server.py"],
+    env={"UV_PYTHON": "3.12", **os.environ},
+)
+
+mcp_server_adapter = MCPServerAdapter(server_params=stdio_params)
+try:
+    mcp_server_adapter.start()  # Manually start the connection and server process
+    tools = mcp_server_adapter.tools
+    print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}")
+
+    # Example: Using the tools with your Agent, Task, Crew setup
+    manual_agent = Agent(
+        role="Local Task Executor",
+        goal="Execute a specific local task using a manually managed Stdio tool.",
+        backstory="An AI proficient in controlling local processes via MCP.",
+        tools=tools,
+        verbose=True
+    )
+    
+    manual_task = Task(
+        description="Execute the 'perform_analysis' command via the Stdio tool.",
+        expected_output="Results of the analysis.",
+        agent=manual_agent
+    )
+    
+    manual_crew = Crew(
+        agents=[manual_agent],
+        tasks=[manual_task],
+        verbose=True,
+        process=Process.sequential
+    )
+        
+       
+    result = manual_crew.kickoff() # Actual inputs depend on your tool
+    print("\nCrew Task Result (Stdio - Manual):\n", result)
+            
+except Exception as e:
+    print(f"An error occurred during manual Stdio MCP integration: {e}")
+finally:
+    if mcp_server_adapter and mcp_server_adapter.is_connected: # Check if connected before stopping
+        print("Stopping Stdio MCP server connection (manual)...")
+        mcp_server_adapter.stop()  # **Crucial: Ensure stop is called**
+    elif mcp_server_adapter: # If adapter exists but not connected (e.g. start failed)
+        print("Stdio MCP server adapter was not connected. No stop needed or start failed.")
+
+```
+
+Remember to replace placeholder paths and commands with your actual Stdio server details. The `env` parameter in `StdioServerParameters` can 
+be used to set environment variables for the server process, which can be useful for configuring its behavior or providing necessary paths (like `PYTHONPATH`).

docs/mcp/streamable-http.mdx

@@ -0,0 +1,135 @@
+---
+title: Streamable HTTP Transport
+description: Learn how to connect CrewAI to remote MCP servers using the flexible Streamable HTTP transport.
+icon: globe
+---
+
+## Overview
+
+Streamable HTTP transport provides a flexible way to connect to remote MCP servers. It's often built upon HTTP and can support various communication patterns, including request-response and streaming, sometimes utilizing Server-Sent Events (SSE) for server-to-client streams within a broader HTTP interaction.
+
+## Key Concepts
+
+- **Remote Servers**: Designed for MCP servers hosted remotely.
+- **Flexibility**: Can support more complex interaction patterns than plain SSE, potentially including bi-directional communication if the server implements it.
+- **`MCPServerAdapter` Configuration**: You'll need to provide the server's base URL for MCP communication and specify `"streamable-http"` as the transport type.
+
+## Connecting via Streamable HTTP
+
+You have two primary methods for managing the connection lifecycle with a Streamable HTTP MCP server:
+
+### 1. Fully Managed Connection (Recommended)
+
+The recommended approach is to use a Python context manager (`with` statement), which handles the connection's setup and teardown automatically.
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+
+server_params = {
+    "url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
+    "transport": "streamable-http"
+}
+
+try:
+    with MCPServerAdapter(server_params) as tools:
+        print(f"Available tools from Streamable HTTP MCP server: {[tool.name for tool in tools]}")
+
+        http_agent = Agent(
+            role="HTTP Service Integrator",
+            goal="Utilize tools from a remote MCP server via Streamable HTTP.",
+            backstory="An AI agent adept at interacting with complex web services.",
+            tools=tools,
+            verbose=True,
+        )
+
+        http_task = Task(
+            description="Perform a complex data query using a tool from the Streamable HTTP server.",
+            expected_output="The result of the complex data query.",
+            agent=http_agent,
+        )
+
+        http_crew = Crew(
+            agents=[http_agent],
+            tasks=[http_task],
+            verbose=True,
+            process=Process.sequential
+        )
+        
+        result = http_crew.kickoff() 
+        print("\nCrew Task Result (Streamable HTTP - Managed):\n", result)
+
+except Exception as e:
+    print(f"Error connecting to or using Streamable HTTP MCP server (Managed): {e}")
+    print("Ensure the Streamable HTTP MCP server is running and accessible at the specified URL.")
+
+```
+**Note:** Replace `"http://localhost:8001/mcp"` with the actual URL of your Streamable HTTP MCP server.
+
+### 2. Manual Connection Lifecycle
+
+For scenarios requiring more explicit control, you can manage the `MCPServerAdapter` connection manually.
+
+<Info>
+It is **critical** to call `mcp_server_adapter.stop()` when you are done to close the connection and free up resources. A `try...finally` block is the safest way to ensure this.
+</Info>
+
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai_tools import MCPServerAdapter
+
+server_params = {
+    "url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
+    "transport": "streamable-http"
+}
+
+mcp_server_adapter = None 
+try:
+    mcp_server_adapter = MCPServerAdapter(server_params)
+    mcp_server_adapter.start()
+    tools = mcp_server_adapter.tools
+    print(f"Available tools (manual Streamable HTTP): {[tool.name for tool in tools]}")
+
+    manual_http_agent = Agent(
+        role="Advanced Web Service User",
+        goal="Interact with an MCP server using manually managed Streamable HTTP connections.",
+        backstory="An AI specialist in fine-tuning HTTP-based service integrations.",
+        tools=tools,
+        verbose=True
+    )
+    
+    data_processing_task = Task(
+        description="Submit data for processing and retrieve results via Streamable HTTP.",
+        expected_output="Processed data or confirmation.",
+        agent=manual_http_agent
+    )
+    
+    data_crew = Crew(
+        agents=[manual_http_agent],
+        tasks=[data_processing_task],
+        verbose=True,
+        process=Process.sequential
+    )
+    
+    result = data_crew.kickoff()
+    print("\nCrew Task Result (Streamable HTTP - Manual):\n", result)
+
+except Exception as e:
+    print(f"An error occurred during manual Streamable HTTP MCP integration: {e}")
+    print("Ensure the Streamable HTTP MCP server is running and accessible.")
+finally:
+    if mcp_server_adapter and mcp_server_adapter.is_connected:
+        print("Stopping Streamable HTTP MCP server connection (manual)...")
+        mcp_server_adapter.stop()  # **Crucial: Ensure stop is called**
+    elif mcp_server_adapter:
+        print("Streamable HTTP MCP server adapter was not connected. No stop needed or start failed.")
+```
+
+## Security Considerations
+
+When using Streamable HTTP transport, general web security best practices are paramount:
+- **Use HTTPS**: Always prefer HTTPS (HTTP Secure) for your MCP server URLs to encrypt data in transit.
+- **Authentication**: Implement robust authentication mechanisms if your MCP server exposes sensitive tools or data.
+- **Input Validation**: Ensure your MCP server validates all incoming requests and parameters.
+
+For a comprehensive guide on securing your MCP integrations, please refer to our [Security Considerations](./security.mdx) page and the official [MCP Transport Security documentation](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).

pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "crewai"
-version = "0.121.0"
+version = "0.121.1"
 description = "Cutting-edge framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks."
 readme = "README.md"
-requires-python = ">=3.10,<3.13"
+requires-python = ">=3.10,<3.14"
 authors = [
     { name = "Joao Moura", email = "joao@crewai.com" }
 ]
@@ -22,6 +22,8 @@ dependencies = [
     "opentelemetry-exporter-otlp-proto-http>=1.30.0",
     # Data Handling
     "chromadb>=0.5.23",
+    "tokenizers>=0.20.3",
+    "onnxruntime==1.22.0",
     "openpyxl>=3.1.5",
     "pyvis>=0.3.2",
     # Authentication and Security
@@ -47,10 +49,9 @@ Repository = "https://github.com/crewAIInc/crewAI"
 [project.optional-dependencies]
 tools = ["crewai-tools~=0.45.0"]
 embeddings = [
-    "tiktoken~=0.7.0"
+    "tiktoken~=0.8.0"
 ]
 agentops = ["agentops>=0.3.0"]
-fastembed = ["fastembed>=0.4.1"]
 pdfplumber = [
     "pdfplumber>=0.11.4",
 ]
@@ -100,6 +101,27 @@ exclude = ["cli/templates"]
 [tool.bandit]
 exclude_dirs = ["src/crewai/cli/templates"]
 
+# PyTorch index configuration, since torch 2.5.0 is not compatible with python 3.13
+[[tool.uv.index]]
+name = "pytorch-nightly"
+url = "https://download.pytorch.org/whl/nightly/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = [
+  { index = "pytorch-nightly", marker = "python_version >= '3.13'" },
+  { index = "pytorch", marker = "python_version < '3.13'" },
+]
+torchvision = [
+  { index = "pytorch-nightly", marker = "python_version >= '3.13'" },
+  { index = "pytorch", marker = "python_version < '3.13'" },
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

src/crewai/__init__.py

@@ -18,7 +18,7 @@ warnings.filterwarnings(
     category=UserWarning,
     module="pydantic.main",
 )
-__version__ = "0.121.0"
+__version__ = "0.121.1"
 __all__ = [
     "Agent",
     "Crew",

src/crewai/cli/templates/crew/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.13"
 dependencies = [
-    "crewai[tools]>=0.121.0,<1.0.0"
+    "crewai[tools]>=0.121.1,<1.0.0"
 ]
 
 [project.scripts]

src/crewai/cli/templates/flow/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.13"
 dependencies = [
-    "crewai[tools]>=0.121.0,<1.0.0",
+    "crewai[tools]>=0.121.1,<1.0.0",
 ]
 
 [project.scripts]

src/crewai/cli/templates/tool/pyproject.toml

@@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
 dependencies = [
-    "crewai[tools]>=0.121.0"
+    "crewai[tools]>=0.121.1"
 ]
 
 [tool.crewai]

src/crewai/knowledge/embedder/fastembed.py

@@ -1,93 +0,0 @@
-from pathlib import Path
-from typing import List, Optional, Union
-
-import numpy as np
-
-from .base_embedder import BaseEmbedder
-
-try:
-    from fastembed_gpu import TextEmbedding  # type: ignore
-
-    FASTEMBED_AVAILABLE = True
-except ImportError:
-    try:
-        from fastembed import TextEmbedding
-
-        FASTEMBED_AVAILABLE = True
-    except ImportError:
-        FASTEMBED_AVAILABLE = False
-
-
-class FastEmbed(BaseEmbedder):
-    """
-    A wrapper class for text embedding models using FastEmbed
-    """
-
-    def __init__(
-        self,
-        model_name: str = "BAAI/bge-small-en-v1.5",
-        cache_dir: Optional[Union[str, Path]] = None,
-    ):
-        """
-        Initialize the embedding model
-
-        Args:
-            model_name: Name of the model to use
-            cache_dir: Directory to cache the model
-            gpu: Whether to use GPU acceleration
-        """
-        if not FASTEMBED_AVAILABLE:
-            raise ImportError(
-                "FastEmbed is not installed. Please install it with: "
-                "uv pip install fastembed or uv pip install fastembed-gpu for GPU support"
-            )
-
-        self.model = TextEmbedding(
-            model_name=model_name,
-            cache_dir=str(cache_dir) if cache_dir else None,
-        )
-
-    def embed_chunks(self, chunks: List[str]) -> List[np.ndarray]:
-        """
-        Generate embeddings for a list of text chunks
-
-        Args:
-            chunks: List of text chunks to embed
-
-        Returns:
-            List of embeddings
-        """
-        embeddings = list(self.model.embed(chunks))
-        return embeddings
-
-    def embed_texts(self, texts: List[str]) -> List[np.ndarray]:
-        """
-        Generate embeddings for a list of texts
-
-        Args:
-            texts: List of texts to embed
-
-        Returns:
-            List of embeddings
-        """
-        embeddings = list(self.model.embed(texts))
-        return embeddings
-
-    def embed_text(self, text: str) -> np.ndarray:
-        """
-        Generate embedding for a single text
-
-        Args:
-            text: Text to embed
-
-        Returns:
-            Embedding array
-        """
-        return self.embed_texts([text])[0]
-
-    @property
-    def dimension(self) -> int:
-        """Get the dimension of the embeddings"""
-        # Generate a test embedding to get dimensions
-        test_embed = self.embed_text("test")
-        return len(test_embed)

src/crewai/llm.py

@@ -5,7 +5,7 @@ import sys
 import threading
 import warnings
 from collections import defaultdict
-from contextlib import contextmanager, redirect_stderr, redirect_stdout
+from contextlib import contextmanager
 from typing import (
     Any,
     DefaultDict,
@@ -18,7 +18,7 @@ from typing import (
     Union,
     cast,
 )
-
+from datetime import datetime
 from dotenv import load_dotenv
 from litellm.types.utils import ChatCompletionDeltaToolCall
 from pydantic import BaseModel, Field
@@ -30,6 +30,11 @@ from crewai.utilities.events.llm_events import (
     LLMCallType,
     LLMStreamChunkEvent,
 )
+from crewai.utilities.events.tool_usage_events import (
+    ToolUsageStartedEvent,
+    ToolUsageFinishedEvent,
+    ToolUsageErrorEvent,
+)
 
 with warnings.catch_warnings():
     warnings.simplefilter("ignore", UserWarning)
@@ -833,7 +838,26 @@ class LLM(BaseLLM):
                 fn = available_functions[function_name]
 
                 # --- 3.2) Execute function
+                assert hasattr(crewai_event_bus, "emit")
+                started_at = datetime.now()
+                crewai_event_bus.emit(
+                    self,
+                    event=ToolUsageStartedEvent(
+                        tool_name=function_name,
+                        tool_args=function_args,
+                    ),
+                )
                 result = fn(**function_args)
+                crewai_event_bus.emit(
+                    self,
+                    event=ToolUsageFinishedEvent(
+                        output=result,
+                        tool_name=function_name,
+                        tool_args=function_args,
+                        started_at=started_at,
+                        finished_at=datetime.now(),
+                    ),
+                )
 
                 # --- 3.3) Emit success event
                 self._handle_emit_call_events(result, LLMCallType.TOOL_CALL)
@@ -849,6 +873,14 @@ class LLM(BaseLLM):
                     self,
                     event=LLMCallFailedEvent(error=f"Tool execution error: {str(e)}"),
                 )
+                crewai_event_bus.emit(
+                    self,
+                    event=ToolUsageErrorEvent(
+                        tool_name=function_name,
+                        tool_args=function_args,
+                        error=f"Tool execution error: {str(e)}"
+                    ),
+                )
         return None
 
     def call(

src/crewai/utilities/events/event_listener.py

@@ -2,7 +2,7 @@ from io import StringIO
 from typing import Any, Dict
 
 from pydantic import Field, PrivateAttr
-
+from crewai.llm import LLM
 from crewai.task import Task
 from crewai.telemetry.telemetry import Telemetry
 from crewai.utilities import Logger
@@ -283,27 +283,43 @@ class EventListener(BaseEventListener):
 
         @crewai_event_bus.on(ToolUsageStartedEvent)
         def on_tool_usage_started(source, event: ToolUsageStartedEvent):
-            self.formatter.handle_tool_usage_started(
-                self.formatter.current_agent_branch,
-                event.tool_name,
+            if isinstance(source, LLM):
+                self.formatter.handle_llm_tool_usage_started(
+                    event.tool_name,
+                )
+            else:
+                self.formatter.handle_tool_usage_started(
+                    self.formatter.current_agent_branch,
+                    event.tool_name,
                 self.formatter.current_crew_tree,
             )
 
         @crewai_event_bus.on(ToolUsageFinishedEvent)
         def on_tool_usage_finished(source, event: ToolUsageFinishedEvent):
-            self.formatter.handle_tool_usage_finished(
-                self.formatter.current_tool_branch,
-                event.tool_name,
-                self.formatter.current_crew_tree,
-            )
+            if isinstance(source, LLM):
+                self.formatter.handle_llm_tool_usage_finished(
+                    event.tool_name,
+                )
+            else:
+                self.formatter.handle_tool_usage_finished(
+                    self.formatter.current_tool_branch,
+                    event.tool_name,
+                    self.formatter.current_crew_tree,
+                )
 
         @crewai_event_bus.on(ToolUsageErrorEvent)
         def on_tool_usage_error(source, event: ToolUsageErrorEvent):
-            self.formatter.handle_tool_usage_error(
-                self.formatter.current_tool_branch,
-                event.tool_name,
-                event.error,
-                self.formatter.current_crew_tree,
+            if isinstance(source, LLM):
+                self.formatter.handle_llm_tool_usage_error(
+                    event.tool_name,
+                    event.error,
+                )
+            else:
+                self.formatter.handle_tool_usage_error(
+                    self.formatter.current_tool_branch,
+                    event.tool_name,
+                    event.error,
+                    self.formatter.current_crew_tree,
             )
 
         # ----------- LLM EVENTS -----------

src/crewai/utilities/events/tool_usage_events.py

@@ -7,11 +7,11 @@ from .base_events import BaseEvent
 class ToolUsageEvent(BaseEvent):
     """Base event for tool usage tracking"""
 
-    agent_key: str
-    agent_role: str
+    agent_key: Optional[str] = None
+    agent_role: Optional[str] = None
     tool_name: str
     tool_args: Dict[str, Any] | str
-    tool_class: str
+    tool_class: Optional[str] = None
     run_attempts: int | None = None
     delegations: int | None = None
     agent: Optional[Any] = None

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

@@ -17,6 +17,7 @@ class ConsoleFormatter:
     current_lite_agent_branch: Optional[Tree] = None
     tool_usage_counts: Dict[str, int] = {}
     current_reasoning_branch: Optional[Tree] = None  # Track reasoning status
+    current_llm_tool_tree: Optional[Tree] = None
 
     def __init__(self, verbose: bool = False):
         self.console = Console(width=None)
@@ -426,6 +427,51 @@ class ConsoleFormatter:
         self.print()
         return method_branch
 
+    def get_llm_tree(self, tool_name: str):
+        text = Text()
+        text.append(f"🔧 Using {tool_name} from LLM available_function", style="yellow")
+
+        tree = self.current_flow_tree or self.current_crew_tree
+
+        if tree:
+            tree.add(text)
+
+        return tree or Tree(text)
+
+    def handle_llm_tool_usage_started(
+        self,
+        tool_name: str,
+    ):
+        tree = self.get_llm_tree(tool_name)
+        self.add_tree_node(tree, "🔄 Tool Usage Started", "green")
+        self.print(tree)
+        self.print()
+        return tree
+
+    def handle_llm_tool_usage_finished(
+        self,
+        tool_name: str,
+    ):
+        tree = self.get_llm_tree(tool_name)
+        self.add_tree_node(tree, "✅ Tool Usage Completed", "green")
+        self.print(tree)
+        self.print()
+
+    def handle_llm_tool_usage_error(
+        self,
+        tool_name: str,
+        error: str,
+    ):
+        tree = self.get_llm_tree(tool_name)
+        self.add_tree_node(tree, "❌ Tool Usage Failed", "red")
+        self.print(tree)
+        self.print()
+
+        error_content = self.create_status_content(
+            "Tool Usage Failed", tool_name, "red", Error=error
+        )
+        self.print_panel(error_content, "Tool Error", "red")
+
     def handle_tool_usage_started(
         self,
         agent_branch: Optional[Tree],

tests/cassettes/test_handle_streaming_tool_calls_with_error.yaml

@@ -0,0 +1,143 @@
+interactions:
+- request:
+    body: '{"messages": [{"role": "user", "content": "What is the weather in New York?"}],
+      "model": "gpt-4o", "stop": [], "stream": true, "stream_options": {"include_usage":
+      true}, "tools": [{"type": "function", "function": {"name": "get_weather", "description":
+      "Get the current weather in a given location", "parameters": {"type": "object",
+      "properties": {"location": {"type": "string", "description": "The city and state,
+      e.g. San Francisco, CA"}}, "required": ["location"]}}}]}'
+    headers:
+      accept:
+      - application/json
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      content-length:
+      - '470'
+      content-type:
+      - application/json
+      cookie:
+      - _cfuvid=3UeEmz_rnmsoZxrVUv32u35gJOi766GDWNe5_RTjiPk-1736537376739-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.12.9
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: 'data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"role":"assistant","content":null,"tool_calls":[{"index":0,"id":"call_UkMsNK0RTJ1nlT19WqgLJYV9","type":"function","function":{"name":"get_weather","arguments":""}}],"refusal":null},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\""}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"location"}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\":\""}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"New"}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"
+        York"}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":","}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"
+        NY"}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\"}"}}]},"logprobs":null,"finish_reason":null}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"tool_calls"}],"usage":null}
+
+
+        data: {"id":"chatcmpl-BcY6NFDeu4HFOAIarpwSNAUEMuPTg","object":"chat.completion.chunk","created":1748527251,"model":"gpt-4o-2024-08-06","service_tier":"default","system_fingerprint":"fp_07871e2ad8","choices":[],"usage":{"prompt_tokens":68,"completion_tokens":17,"total_tokens":85,"prompt_tokens_details":{"cached_tokens":0,"audio_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}}}
+
+
+        data: [DONE]
+
+
+        '
+    headers:
+      CF-RAY:
+      - 947685373af8a435-GRU
+      Connection:
+      - keep-alive
+      Content-Type:
+      - text/event-stream; charset=utf-8
+      Date:
+      - Thu, 29 May 2025 14:00:51 GMT
+      Server:
+      - cloudflare
+      Set-Cookie:
+      - __cf_bm=fFoq7oCHLgmljA4hsHWxTGHMEWJ.0t1XTuDptZPPkOc-1748527251-1.0.1.1-PP3Hd7XzA4AQFn0JQWjuQdhFwey0Pj9maUWKfFG16Bkl69Uk65A8XKN73UbsvO327TruwxameKb_m_HDePCR.YN0TZlE8Pu45WsA9shDwKY;
+        path=/; expires=Thu, 29-May-25 14:30:51 GMT; domain=.api.openai.com; HttpOnly;
+        Secure; SameSite=None
+      - _cfuvid=ut1CVX5GOYnv03fiV2Dsv7cm5soJmwgSutkPAEuVXWg-1748527251565-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:
+      - '332'
+      openai-version:
+      - '2020-10-01'
+      strict-transport-security:
+      - max-age=31536000; includeSubDomains; preload
+      x-envoy-upstream-service-time:
+      - '334'
+      x-ratelimit-limit-requests:
+      - '10000'
+      x-ratelimit-limit-tokens:
+      - '30000000'
+      x-ratelimit-remaining-requests:
+      - '9999'
+      x-ratelimit-remaining-tokens:
+      - '29999989'
+      x-ratelimit-reset-requests:
+      - 6ms
+      x-ratelimit-reset-tokens:
+      - 0s
+      x-request-id:
+      - req_1dc91fc964a8d23ee023693400e5c181
+    status:
+      code: 200
+      message: OK
+version: 1

tests/cassettes/test_llm_callback_replacement.yaml

@@ -202,4 +202,63 @@ interactions:
       - req_366bcd7dfe94e2a2b5640fd9bb1c5a6b
     http_version: HTTP/1.1
     status_code: 200
+- request:
+    body: !!binary |
+      CtcMCiQKIgoMc2VydmljZS5uYW1lEhIKEGNyZXdBSS10ZWxlbWV0cnkSrgwKEgoQY3Jld2FpLnRl
+      bGVtZXRyeRKUCAoQu3w5ZNCcMWutYN9ACENEihIIIWUtKzKLQXoqDENyZXcgQ3JlYXRlZDABOcjc
+      jv4SBEQYQWg/lv4SBEQYShsKDmNyZXdhaV92ZXJzaW9uEgkKBzAuMTIwLjFKGgoOcHl0aG9uX3Zl
+      cnNpb24SCAoGMy4xMi45Si4KCGNyZXdfa2V5EiIKIDY5NDY1NGEzMThmNzE5ODgzYzA2ZjhlNmQ5
+      YTc1NDlmSjEKB2NyZXdfaWQSJgokMjI4NzU3NTAtYjIwMC00MTI4LWJmYjUtYTFmNTFjNDhlNDk5
+      ShwKDGNyZXdfcHJvY2VzcxIMCgpzZXF1ZW50aWFsShEKC2NyZXdfbWVtb3J5EgIQAEoaChRjcmV3
+      X251bWJlcl9vZl90YXNrcxICGAFKGwoVY3Jld19udW1iZXJfb2ZfYWdlbnRzEgIYAUo6ChBjcmV3
+      X2ZpbmdlcnByaW50EiYKJDBhZGQxM2U2LTBhYWQtNDUyNS1iYTE0LWZhMDUzZGM2ZjE0ZUo7Chtj
+      cmV3X2ZpbmdlcnByaW50X2NyZWF0ZWRfYXQSHAoaMjAyNS0wNS0yOVQxMDo1NzoxNC45NTE4MTlK
+      zAIKC2NyZXdfYWdlbnRzErwCCrkCW3sia2V5IjogIjU1ODY5YmNiMTYzMjNlNzEyOWQyNTIzNjJj
+      ODU1ZGE2IiwgImlkIjogIjJiY2UyZTE0LWIyN2UtNDM1MC1iZmIyLWE1YTNkMTRmYTJhMCIsICJy
+      b2xlIjogIlNheSBIaSIsICJ2ZXJib3NlPyI6IGZhbHNlLCAibWF4X2l0ZXIiOiAyNSwgIm1heF9y
+      cG0iOiBudWxsLCAiZnVuY3Rpb25fY2FsbGluZ19sbG0iOiAiIiwgImxsbSI6ICJ0ZXN0LW1vZGVs
+      IiwgImRlbGVnYXRpb25fZW5hYmxlZD8iOiBmYWxzZSwgImFsbG93X2NvZGVfZXhlY3V0aW9uPyI6
+      IGZhbHNlLCAibWF4X3JldHJ5X2xpbWl0IjogMiwgInRvb2xzX25hbWVzIjogW119XUr7AQoKY3Jl
+      d190YXNrcxLsAQrpAVt7ImtleSI6ICJkZTI5NDBmMDZhZDhhNDE2YzI4Y2MwZjI2MTBmMTgwYiIs
+      ICJpZCI6ICJiM2MyMzNkZC1kNDk2LTQ1YjQtYWFkMy1kYzYyZGI3ZjJiZWEiLCAiYXN5bmNfZXhl
+      Y3V0aW9uPyI6IGZhbHNlLCAiaHVtYW5faW5wdXQ/IjogZmFsc2UsICJhZ2VudF9yb2xlIjogIlNh
+      eSBIaSIsICJhZ2VudF9rZXkiOiAiNTU4NjliY2IxNjMyM2U3MTI5ZDI1MjM2MmM4NTVkYTYiLCAi
+      dG9vbHNfbmFtZXMiOiBbXX1degIYAYUBAAEAABKABAoQaW1V2ASOUN5hjxpKH5WT+BIIe6lsRrYF
+      84MqDFRhc2sgQ3JlYXRlZDABOfA/rv4SBEQYQSC1rv4SBEQYSi4KCGNyZXdfa2V5EiIKIDY5NDY1
+      NGEzMThmNzE5ODgzYzA2ZjhlNmQ5YTc1NDlmSjEKB2NyZXdfaWQSJgokMjI4NzU3NTAtYjIwMC00
+      MTI4LWJmYjUtYTFmNTFjNDhlNDk5Si4KCHRhc2tfa2V5EiIKIGRlMjk0MGYwNmFkOGE0MTZjMjhj
+      YzBmMjYxMGYxODBiSjEKB3Rhc2tfaWQSJgokYjNjMjMzZGQtZDQ5Ni00NWI0LWFhZDMtZGM2MmRi
+      N2YyYmVhSjoKEGNyZXdfZmluZ2VycHJpbnQSJgokMGFkZDEzZTYtMGFhZC00NTI1LWJhMTQtZmEw
+      NTNkYzZmMTRlSjoKEHRhc2tfZmluZ2VycHJpbnQSJgokZGVlNDA1YjgtMTkxNC00N2NkLTlkMTgt
+      ZTdmZDA0NjFkOGE4SjsKG3Rhc2tfZmluZ2VycHJpbnRfY3JlYXRlZF9hdBIcChoyMDI1LTA1LTI5
+      VDEwOjU3OjE0Ljk1MTc4M0o7ChFhZ2VudF9maW5nZXJwcmludBImCiRiNWQ0NGNlMS00NGRjLTQ0
+      YzYtYTU1YS0xODZhM2QxZmU2YjJ6AhgBhQEAAQAA
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '1626'
+      Content-Type:
+      - application/x-protobuf
+      User-Agent:
+      - OTel-OTLP-Exporter-Python/1.31.1
+    method: POST
+    uri: https://telemetry.crewai.com:4319/v1/traces
+  response:
+    body:
+      string: "\n\0"
+    headers:
+      Content-Length:
+      - '2'
+      Content-Type:
+      - application/x-protobuf
+      Date:
+      - Thu, 29 May 2025 13:57:17 GMT
+    status:
+      code: 200
+      message: OK
 version: 1

tests/llm_test.py

@@ -2,7 +2,6 @@ import os
 from time import sleep
 from unittest.mock import MagicMock, patch
 
-import litellm
 import pytest
 from pydantic import BaseModel
 
@@ -11,7 +10,11 @@ from crewai.llm import CONTEXT_WINDOW_USAGE_RATIO, LLM
 from crewai.utilities.events import (
     LLMCallCompletedEvent,
     LLMStreamChunkEvent,
+    ToolUsageStartedEvent,
+    ToolUsageFinishedEvent,
+    ToolUsageErrorEvent,
 )
+
 from crewai.utilities.token_counter_callback import TokenCalcHandler
 
 
@@ -222,7 +225,7 @@ def test_get_custom_llm_provider_gemini():
 
 def test_get_custom_llm_provider_openai():
     llm = LLM(model="gpt-4")
-    assert llm._get_custom_llm_provider() == None
+    assert llm._get_custom_llm_provider() is None
 
 
 def test_validate_call_params_supported():
@@ -511,12 +514,18 @@ def assert_event_count(
     expected_completed_tool_call: int = 0,
     expected_stream_chunk: int = 0,
     expected_completed_llm_call: int = 0,
+    expected_tool_usage_started: int = 0,
+    expected_tool_usage_finished: int = 0,
+    expected_tool_usage_error: int = 0,
     expected_final_chunk_result: str = "",
 ):
     event_count = {
         "completed_tool_call": 0,
         "stream_chunk": 0,
         "completed_llm_call": 0,
+        "tool_usage_started": 0,
+        "tool_usage_finished": 0,
+        "tool_usage_error": 0,
     }
     final_chunk_result = ""
     for _call in mock_emit.call_args_list:
@@ -535,12 +544,21 @@ def assert_event_count(
             and event.call_type.value == "llm_call"
         ):
             event_count["completed_llm_call"] += 1
+        elif isinstance(event, ToolUsageStartedEvent):
+            event_count["tool_usage_started"] += 1
+        elif isinstance(event, ToolUsageFinishedEvent):
+            event_count["tool_usage_finished"] += 1
+        elif isinstance(event, ToolUsageErrorEvent):
+            event_count["tool_usage_error"] += 1
         else:
             continue
 
     assert event_count["completed_tool_call"] == expected_completed_tool_call
     assert event_count["stream_chunk"] == expected_stream_chunk
     assert event_count["completed_llm_call"] == expected_completed_llm_call
+    assert event_count["tool_usage_started"] == expected_tool_usage_started
+    assert event_count["tool_usage_finished"] == expected_tool_usage_finished
+    assert event_count["tool_usage_error"] == expected_tool_usage_error
     assert final_chunk_result == expected_final_chunk_result
 
 
@@ -574,6 +592,34 @@ def test_handle_streaming_tool_calls(get_weather_tool_schema, mock_emit):
         expected_completed_tool_call=1,
         expected_stream_chunk=10,
         expected_completed_llm_call=1,
+        expected_tool_usage_started=1,
+        expected_tool_usage_finished=1,
+        expected_final_chunk_result=expected_final_chunk_result,
+    )
+
+@pytest.mark.vcr(filter_headers=["authorization"])
+def test_handle_streaming_tool_calls_with_error(get_weather_tool_schema, mock_emit):
+    def get_weather_error(location):
+        raise Exception("Error")
+        
+    llm = LLM(model="openai/gpt-4o", stream=True)
+    response = llm.call(
+        messages=[
+            {"role": "user", "content": "What is the weather in New York?"},
+        ],
+        tools=[get_weather_tool_schema],
+        available_functions={
+            "get_weather": get_weather_error
+        },
+    )
+    assert response == ""
+    expected_final_chunk_result = '{"location":"New York, NY"}'
+    assert_event_count(
+        mock_emit=mock_emit,
+        expected_stream_chunk=9,
+        expected_completed_llm_call=1,
+        expected_tool_usage_started=1,
+        expected_tool_usage_error=1,    
         expected_final_chunk_result=expected_final_chunk_result,
     )