docs: update Python version requirement from <=3.13 to <3.14

This correctly reflects support for all 3.13.x patch version

.github/workflows/linter.yml

@@ -30,4 +30,7 @@ jobs:
       - name: Run Ruff on Changed Files
         if: ${{ steps.changed-files.outputs.files != '' }}
         run: |
-          echo "${{ steps.changed-files.outputs.files }}" | tr " " "\n" | xargs -I{} ruff check "{}"
+          echo "${{ steps.changed-files.outputs.files }}" \
+            | tr ' ' '\n' \
+            | grep -v 'src/crewai/cli/templates/' \
+            | xargs -I{} ruff check "{}"

.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

@@ -1,32 +1,75 @@
-<div align="center">
+<p align="center">
+  <a href="https://github.com/crewAIInc/crewAI">
+    <img src="docs/images/crewai_logo.png" width="600px" alt="Open source Multi-AI Agent orchestration framework">
+  </a>
+</p>
+<p align="center" style="display: flex; justify-content: center; gap: 20px; align-items: center;">
+  <a href="https://trendshift.io/repositories/11239" target="_blank">
+    <img src="https://trendshift.io/api/badge/repositories/11239" alt="crewAIInc%2FcrewAI | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
+  </a>
+</p>
 
-![Logo of CrewAI](./docs/crewai_logo.png)
+<p align="center">
+  <a href="https://crewai.com">Homepage</a>
+  ·
+  <a href="https://docs.crewai.com">Docs</a>
+  ·
+  <a href="https://app.crewai.com">Start Cloud Trial</a>
+  ·
+  <a href="https://blog.crewai.com">Blog</a>
+  ·
+  <a href="https://community.crewai.com">Forum</a>
+</p>
 
+<p align="center">
+  <a href="https://github.com/crewAIInc/crewAI">
+    <img src="https://img.shields.io/github/stars/crewAIInc/crewAI" alt="GitHub Repo stars">
+  </a>
+  <a href="https://github.com/crewAIInc/crewAI/network/members">
+    <img src="https://img.shields.io/github/forks/crewAIInc/crewAI" alt="GitHub forks">
+  </a>
+  <a href="https://github.com/crewAIInc/crewAI/issues">
+    <img src="https://img.shields.io/github/issues/crewAIInc/crewAI" alt="GitHub issues">
+  </a>
+  <a href="https://github.com/crewAIInc/crewAI/pulls">
+    <img src="https://img.shields.io/github/issues-pr/crewAIInc/crewAI" alt="GitHub pull requests">
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT">
+  </a>
+</p>
 
-</div>
+<p align="center">
+  <a href="https://pypi.org/project/crewai/">
+    <img src="https://img.shields.io/pypi/v/crewai" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/crewai/">
+    <img src="https://img.shields.io/pypi/dm/crewai" alt="PyPI downloads">
+  </a>
+  <a href="https://twitter.com/crewAIInc">
+    <img src="https://img.shields.io/twitter/follow/crewAIInc?style=social" alt="Twitter Follow">
+  </a>
+</p>
 
 ### Fast and Flexible Multi-Agent Automation Framework
 
-CrewAI is a lean, lightning-fast Python framework built entirely from
-scratch—completely **independent of LangChain or other agent frameworks**.
-It empowers developers with both high-level simplicity and precise low-level
-control, ideal for creating autonomous AI agents tailored to any scenario.
+> CrewAI is a lean, lightning-fast Python framework built entirely from scratch—completely **independent of LangChain or other agent frameworks**.
+> It empowers developers with both high-level simplicity and precise low-level control, ideal for creating autonomous AI agents tailored to any scenario.
 
 - **CrewAI Crews**: Optimize for autonomy and collaborative intelligence.
 - **CrewAI Flows**: Enable granular, event-driven control, single LLM calls for precise task orchestration and supports Crews natively
 
-With over 100,000 developers certified through our community courses at
-[learn.crewai.com](https://learn.crewai.com), CrewAI is rapidly becoming the
+With over 100,000 developers certified through our community courses at [learn.crewai.com](https://learn.crewai.com), CrewAI is rapidly becoming the
 standard for enterprise-ready AI automation.
 
 # CrewAI Enterprise Suite
 
-CrewAI Enterprise Suite is a comprehensive bundle tailored for organizations
-that require secure, scalable, and easy-to-manage agent-driven automation.
+CrewAI Enterprise Suite is a comprehensive bundle tailored for organizations that require secure, scalable, and easy-to-manage agent-driven automation.
 
 You can try one part of the suite the [Crew Control Plane for free](https://app.crewai.com)
 
 ## Crew Control Plane Key Features:
+
 - **Tracing & Observability**: Monitor and track your AI agents and workflows in real-time, including metrics, logs, and traces.
 - **Unified Control Plane**: A centralized platform for managing, monitoring, and scaling your AI agents and workflows.
 - **Seamless Integrations**: Easily connect with existing enterprise systems, data sources, and cloud infrastructure.
@@ -35,21 +78,9 @@ You can try one part of the suite the [Crew Control Plane for free](https://app.
 - **24/7 Support**: Dedicated enterprise support to ensure uninterrupted operation and quick resolution of issues.
 - **On-premise and Cloud Deployment Options**: Deploy CrewAI Enterprise on-premise or in the cloud, depending on your security and compliance requirements.
 
-CrewAI Enterprise is designed for enterprises seeking a powerful,
-reliable solution to transform complex business processes into efficient,
+CrewAI Enterprise is designed for enterprises seeking a powerful, reliable solution to transform complex business processes into efficient,
 intelligent automations.
 
-<h3>
-
-[Homepage](https://www.crewai.com/) | [Documentation](https://docs.crewai.com/) | [Chat with Docs](https://chatg.pt/DWjSBZn) | [Discourse](https://community.crewai.com)
-
-</h3>
-
-[![GitHub Repo stars](https://img.shields.io/github/stars/joaomdmoura/crewAI)](https://github.com/crewAIInc/crewAI)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-
-</div>
-
 ## Table of contents
 
 - [Why CrewAI?](#why-crewai)
@@ -73,7 +104,7 @@ intelligent automations.
 ## Why CrewAI?
 
 <div align="center" style="margin-bottom: 30px;">
-  <img src="docs/asset.png" alt="CrewAI Logo" width="100%">
+  <img src="docs/images/asset.png" alt="CrewAI Logo" width="100%">
 </div>
 
 CrewAI unlocks the true potential of multi-agent automation, delivering the best-in-class combination of speed, flexibility, and control with either Crews of AI Agents or Flows of Events:
@@ -88,9 +119,15 @@ CrewAI empowers developers and enterprises to confidently build intelligent auto
 
 ## Getting Started
 
-### Learning Resources
+Setup and run your first CrewAI agents by following this tutorial.
+
+[![CrewAI Getting Started Tutorial](https://img.youtube.com/vi/-kSOTtYzgEw/hqdefault.jpg)](https://www.youtube.com/watch?v=-kSOTtYzgEw "CrewAI Getting Started Tutorial")
+
+###
+ Learning Resources
 
 Learn CrewAI through our comprehensive courses:
+
 - [Multi AI Agent Systems with CrewAI](https://www.deeplearning.ai/short-courses/multi-ai-agent-systems-with-crewai/) - Master the fundamentals of multi-agent systems
 - [Practical Multi AI Agents and Advanced Use Cases](https://www.deeplearning.ai/short-courses/practical-multi-ai-agents-and-advanced-use-cases-with-crewai/) - Deep dive into advanced implementations
 
@@ -99,18 +136,20 @@ Learn CrewAI through our comprehensive courses:
 CrewAI offers two powerful, complementary approaches that work seamlessly together to build sophisticated AI applications:
 
 1. **Crews**: Teams of AI agents with true autonomy and agency, working together to accomplish complex tasks through role-based collaboration. Crews enable:
+
    - Natural, autonomous decision-making between agents
    - Dynamic task delegation and collaboration
    - Specialized roles with defined goals and expertise
    - Flexible problem-solving approaches
-
 2. **Flows**: Production-ready, event-driven workflows that deliver precise control over complex automations. Flows provide:
+
    - Fine-grained control over execution paths for real-world scenarios
    - Secure, consistent state management between tasks
    - Clean integration of AI agents with production Python code
    - Conditional branching for complex business logic
 
 The true power of CrewAI emerges when combining Crews and Flows. This synergy allows you to:
+
 - Build complex, production-grade applications
 - Balance autonomy with precise control
 - Handle sophisticated real-world scenarios
@@ -122,18 +161,20 @@ To get started with CrewAI, follow these simple steps:
 
 ### 1. Installation
 
-Ensure you have Python >=3.10 <3.13 installed on your system. CrewAI uses [UV](https://docs.astral.sh/uv/) for dependency management and package handling, offering a seamless setup and execution experience.
+Ensure you have Python >=3.10 <3.14 installed on your system. CrewAI uses [UV](https://docs.astral.sh/uv/) for dependency management and package handling, offering a seamless setup and execution experience.
 
 First, install CrewAI:
 
 ```shell
 pip install crewai
 ```
+
 If you want to install the 'crewai' package along with its optional features that include additional tools for agents, you can do so by using the following command:
 
 ```shell
 pip install 'crewai[tools]'
 ```
+
 The command above installs the basic package and also adds extra components which require more dependencies to function.
 
 ### Troubleshooting Dependencies
@@ -143,10 +184,11 @@ If you encounter issues during installation or usage, here are some common solut
 #### Common Issues
 
 1. **ModuleNotFoundError: No module named 'tiktoken'**
+
    - Install tiktoken explicitly: `pip install 'crewai[embeddings]'`
    - If using embedchain or other tools: `pip install 'crewai[tools]'`
-
 2. **Failed building wheel for tiktoken**
+
    - Ensure Rust compiler is installed (see installation steps above)
    - For Windows: Verify Visual C++ Build Tools are installed
    - Try upgrading pip: `pip install --upgrade pip`
@@ -361,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.
@@ -407,7 +449,8 @@ You can test different real life examples of AI crews in the [CrewAI-examples re
 
 CrewAI's power truly shines when combining Crews with Flows to create sophisticated automation pipelines.
 CrewAI flows support logical operators like `or_` and `and_` to combine multiple conditions. This can be used with `@start`, `@listen`, or `@router` decorators to create complex triggering conditions.
-- `or_`: Triggers when any of the specified conditions are met. 
+
+- `or_`: Triggers when any of the specified conditions are met.
 - `and_`Triggers when all of the specified conditions are met.
 
 Here's how you can orchestrate multiple Crews within a Flow:
@@ -495,6 +538,7 @@ class AdvancedAnalysisFlow(Flow[MarketState]):
 ```
 
 This example demonstrates how to:
+
 1. Use Python code for basic data operations
 2. Create and execute Crews as steps in your workflow
 3. Use Flow decorators to manage the sequence of operations
@@ -515,7 +559,6 @@ Please refer to the [Connect CrewAI to LLMs](https://docs.crewai.com/how-to/LLM-
 *P.S. CrewAI demonstrates significant performance advantages over LangGraph, executing 5.76x faster in certain cases like this QA task example ([see comparison](https://github.com/crewAIInc/crewAI-examples/tree/main/Notebooks/CrewAI%20Flows%20%26%20Langgraph/QA%20Agent)) while achieving higher evaluation scores with faster completion times in certain coding tasks, like in this example ([detailed analysis](https://github.com/crewAIInc/crewAI-examples/blob/main/Notebooks/CrewAI%20Flows%20%26%20Langgraph/Coding%20Assistant/coding_assistant_eval.ipynb)).*
 
 - **Autogen**: While Autogen excels at creating conversational agents capable of working together, it lacks an inherent concept of process. In Autogen, orchestrating agents' interactions requires additional programming, which can become complex and cumbersome as the scale of tasks grows.
-
 - **ChatDev**: ChatDev introduced the idea of processes into the realm of AI agents, but its implementation is quite rigid. Customizations in ChatDev are limited and not geared towards production environments, which can hinder scalability and flexibility in real-world applications.
 
 ## Contribution
@@ -606,10 +649,10 @@ Users can opt-in to Further Telemetry, sharing the complete telemetry data by se
 
 CrewAI is released under the [MIT License](https://github.com/crewAIInc/crewAI/blob/main/LICENSE).
 
-
 ## Frequently Asked Questions (FAQ)
 
 ### General
+
 - [What exactly is CrewAI?](#q-what-exactly-is-crewai)
 - [How do I install CrewAI?](#q-how-do-i-install-crewai)
 - [Does CrewAI depend on LangChain?](#q-does-crewai-depend-on-langchain)
@@ -617,6 +660,7 @@ CrewAI is released under the [MIT License](https://github.com/crewAIInc/crewAI/b
 - [Does CrewAI collect data from users?](#q-does-crewai-collect-data-from-users)
 
 ### Features and Capabilities
+
 - [Can CrewAI handle complex use cases?](#q-can-crewai-handle-complex-use-cases)
 - [Can I use CrewAI with local AI models?](#q-can-i-use-crewai-with-local-ai-models)
 - [What makes Crews different from Flows?](#q-what-makes-crews-different-from-flows)
@@ -624,84 +668,110 @@ CrewAI is released under the [MIT License](https://github.com/crewAIInc/crewAI/b
 - [Does CrewAI support fine-tuning or training custom models?](#q-does-crewai-support-fine-tuning-or-training-custom-models)
 
 ### Resources and Community
+
 - [Where can I find real-world CrewAI examples?](#q-where-can-i-find-real-world-crewai-examples)
 - [How can I contribute to CrewAI?](#q-how-can-i-contribute-to-crewai)
 
 ### Enterprise Features
+
 - [What additional features does CrewAI Enterprise offer?](#q-what-additional-features-does-crewai-enterprise-offer)
 - [Is CrewAI Enterprise available for cloud and on-premise deployments?](#q-is-crewai-enterprise-available-for-cloud-and-on-premise-deployments)
 - [Can I try CrewAI Enterprise for free?](#q-can-i-try-crewai-enterprise-for-free)
 
-
-
 ### Q: What exactly is CrewAI?
+
 A: CrewAI is a standalone, lean, and fast Python framework built specifically for orchestrating autonomous AI agents. Unlike frameworks like LangChain, CrewAI does not rely on external dependencies, making it leaner, faster, and simpler.
 
 ### Q: How do I install CrewAI?
+
 A: Install CrewAI using pip:
+
 ```shell
 pip install crewai
 ```
+
 For additional tools, use:
+
 ```shell
 pip install 'crewai[tools]'
 ```
+
 ### Q: Does CrewAI depend on LangChain?
+
 A: No. CrewAI is built entirely from the ground up, with no dependencies on LangChain or other agent frameworks. This ensures a lean, fast, and flexible experience.
 
 ### Q: Can CrewAI handle complex use cases?
+
 A: Yes. CrewAI excels at both simple and highly complex real-world scenarios, offering deep customization options at both high and low levels, from internal prompts to sophisticated workflow orchestration.
 
 ### Q: Can I use CrewAI with local AI models?
+
 A: Absolutely! CrewAI supports various language models, including local ones. Tools like Ollama and LM Studio allow seamless integration. Check the [LLM Connections documentation](https://docs.crewai.com/how-to/LLM-Connections/) for more details.
 
 ### Q: What makes Crews different from Flows?
+
 A: Crews provide autonomous agent collaboration, ideal for tasks requiring flexible decision-making and dynamic interaction. Flows offer precise, event-driven control, ideal for managing detailed execution paths and secure state management. You can seamlessly combine both for maximum effectiveness.
 
 ### Q: How is CrewAI better than LangChain?
+
 A: CrewAI provides simpler, more intuitive APIs, faster execution speeds, more reliable and consistent results, robust documentation, and an active community—addressing common criticisms and limitations associated with LangChain.
 
 ### Q: Is CrewAI open-source?
+
 A: Yes, CrewAI is open-source and actively encourages community contributions and collaboration.
 
 ### Q: Does CrewAI collect data from users?
+
 A: CrewAI collects anonymous telemetry data strictly for improvement purposes. Sensitive data such as prompts, tasks, or API responses are never collected unless explicitly enabled by the user.
 
 ### Q: Where can I find real-world CrewAI examples?
+
 A: Check out practical examples in the [CrewAI-examples repository](https://github.com/crewAIInc/crewAI-examples), covering use cases like trip planners, stock analysis, and job postings.
 
 ### Q: How can I contribute to CrewAI?
+
 A: Contributions are warmly welcomed! Fork the repository, create your branch, implement your changes, and submit a pull request. See the Contribution section of the README for detailed guidelines.
 
 ### Q: What additional features does CrewAI Enterprise offer?
+
 A: CrewAI Enterprise provides advanced features such as a unified control plane, real-time observability, secure integrations, advanced security, actionable insights, and dedicated 24/7 enterprise support.
 
 ### Q: Is CrewAI Enterprise available for cloud and on-premise deployments?
+
 A: Yes, CrewAI Enterprise supports both cloud-based and on-premise deployment options, allowing enterprises to meet their specific security and compliance requirements.
 
 ### Q: Can I try CrewAI Enterprise for free?
+
 A: Yes, you can explore part of the CrewAI Enterprise Suite by accessing the [Crew Control Plane](https://app.crewai.com) for free.
 
 ### Q: Does CrewAI support fine-tuning or training custom models?
+
 A: Yes, CrewAI can integrate with custom-trained or fine-tuned models, allowing you to enhance your agents with domain-specific knowledge and accuracy.
 
 ### Q: Can CrewAI agents interact with external tools and APIs?
+
 A: Absolutely! CrewAI agents can easily integrate with external tools, APIs, and databases, empowering them to leverage real-world data and resources.
 
 ### Q: Is CrewAI suitable for production environments?
+
 A: Yes, CrewAI is explicitly designed with production-grade standards, ensuring reliability, stability, and scalability for enterprise deployments.
 
 ### Q: How scalable is CrewAI?
+
 A: CrewAI is highly scalable, supporting simple automations and large-scale enterprise workflows involving numerous agents and complex tasks simultaneously.
 
 ### Q: Does CrewAI offer debugging and monitoring tools?
+
 A: Yes, CrewAI Enterprise includes advanced debugging, tracing, and real-time observability features, simplifying the management and troubleshooting of your automations.
 
 ### Q: What programming languages does CrewAI support?
+
 A: CrewAI is primarily Python-based but easily integrates with services and APIs written in any programming language through its flexible API integration capabilities.
 
 ### Q: Does CrewAI offer educational resources for beginners?
+
 A: Yes, CrewAI provides extensive beginner-friendly tutorials, courses, and documentation through learn.crewai.com, supporting developers at all skill levels.
 
 ### Q: Can CrewAI automate human-in-the-loop workflows?
+
 A: Yes, CrewAI fully supports human-in-the-loop workflows, allowing seamless collaboration between human experts and AI agents for enhanced decision-making.

docs/api-reference/introduction.mdx

@@ -0,0 +1,119 @@
+---
+title: "Introduction"
+description: "Complete reference for the CrewAI Enterprise REST API"
+icon: "code"
+---
+
+# CrewAI Enterprise API
+
+Welcome to the CrewAI Enterprise API reference. This API allows you to programmatically interact with your deployed crews, enabling integration with your applications, workflows, and services.
+
+## Quick Start
+
+<Steps>
+  <Step title="Get Your API Credentials">
+    Navigate to your crew's detail page in the CrewAI Enterprise dashboard and copy your Bearer Token from the Status tab.
+  </Step>
+  
+  <Step title="Discover Required Inputs">
+    Use the `GET /inputs` endpoint to see what parameters your crew expects.
+  </Step>
+  
+  <Step title="Start a Crew Execution">
+    Call `POST /kickoff` with your inputs to start the crew execution and receive a `kickoff_id`.
+  </Step>
+  
+  <Step title="Monitor Progress">
+    Use `GET /status/{kickoff_id}` to check execution status and retrieve results.
+  </Step>
+</Steps>
+
+## Authentication
+
+All API requests require authentication using a Bearer token. Include your token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
+  https://your-crew-url.crewai.com/inputs
+```
+
+### Token Types
+
+| Token Type | Scope | Use Case |
+|:-----------|:--------|:----------|
+| **Bearer Token** | Organization-level access | Full crew operations, ideal for server-to-server integration |
+| **User Bearer Token** | User-scoped access | Limited permissions, suitable for user-specific operations |
+
+<Tip>
+You can find both token types in the Status tab of your crew's detail page in the CrewAI Enterprise dashboard.
+</Tip>
+
+## Base URL
+
+Each deployed crew has its own unique API endpoint:
+
+```
+https://your-crew-name.crewai.com
+```
+
+Replace `your-crew-name` with your actual crew's URL from the dashboard.
+
+## Typical Workflow
+
+1. **Discovery**: Call `GET /inputs` to understand what your crew needs
+2. **Execution**: Submit inputs via `POST /kickoff` to start processing  
+3. **Monitoring**: Poll `GET /status/{kickoff_id}` until completion
+4. **Results**: Extract the final output from the completed response
+
+## Error Handling
+
+The API uses standard HTTP status codes:
+
+| Code | Meaning |
+|------|:--------|
+| `200` | Success |
+| `400` | Bad Request - Invalid input format |
+| `401` | Unauthorized - Invalid bearer token |
+| `404` | Not Found - Resource doesn't exist |
+| `422` | Validation Error - Missing required inputs |
+| `500` | Server Error - Contact support |
+
+## Interactive Testing
+
+<Info>
+**Why no "Send" button?** Since each CrewAI Enterprise user has their own unique crew URL, we use **reference mode** instead of an interactive playground to avoid confusion. This shows you exactly what the requests should look like without non-functional send buttons.
+</Info>
+
+Each endpoint page shows you:
+- ✅ **Exact request format** with all parameters
+- ✅ **Response examples** for success and error cases  
+- ✅ **Code samples** in multiple languages (cURL, Python, JavaScript, etc.)
+- ✅ **Authentication examples** with proper Bearer token format
+
+### **To Test Your Actual API:**
+
+<CardGroup cols={2}>
+  <Card title="Copy cURL Examples" icon="terminal">
+    Copy the cURL examples and replace the URL + token with your real values
+  </Card>
+  <Card title="Use Postman/Insomnia" icon="play">
+    Import the examples into your preferred API testing tool
+  </Card>
+</CardGroup>
+
+**Example workflow:**
+1. **Copy this cURL example** from any endpoint page
+2. **Replace `your-actual-crew-name.crewai.com`** with your real crew URL  
+3. **Replace the Bearer token** with your real token from the dashboard
+4. **Run the request** in your terminal or API client
+
+## Need Help?
+
+<CardGroup cols={2}>
+  <Card title="Enterprise Support" icon="headset" href="mailto:support@crewai.com">
+    Get help with API integration and troubleshooting
+  </Card>
+  <Card title="Enterprise Dashboard" icon="chart-line" href="https://app.crewai.com">
+    Manage your crews and view execution logs
+  </Card>
+</CardGroup>

docs/changelog.mdx

@@ -4,23 +4,136 @@ description: View the latest updates and changes to CrewAI
 icon: timeline
 ---
 
-<Update label="2025-04-30" description="v0.117.1">
+<Update label="2024-05-22" description="v0.121.0" tags={["Latest"]}>
   ## Release Highlights
   <Frame>
-    <img src="/images/releases/v01171.png" />
+    <img src="/images/releases/v01210.png" />
   </Frame>
   
   <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
-    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.117.1">View on GitHub</a>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.121.0">View on GitHub</a>
   </div>
 
   **Core Improvements & Fixes**
-  - Upgraded **crewai-tools** to latest version
-  - Upgraded **liteLLM** to latest version
-  - Fixed **Mem0 OSS**
+  - Fixed encoding error when creating tools
+  - Fixed failing llama test
+  - Updated logging configuration for consistency
+  - Enhanced telemetry initialization and event handling
+
+  **New Features & Enhancements**
+  - Added **markdown attribute** to the Task class
+  - Added **reasoning attribute** to the Agent class
+  - Added **inject_date flag** to Agent for automatic date injection
+  - Implemented **HallucinationGuardrail** (no-op with test coverage)
+
+  **Documentation & Guides**
+  - Added documentation for **StagehandTool** and improved MDX structure
+  - Added documentation for **MCP integration** and updated enterprise docs
+  - Documented knowledge events and updated reasoning docs
+  - Added stop parameter documentation
+  - Fixed import references in doc examples (before_kickoff, after_kickoff)
+  - General docs updates and restructuring for clarity
 </Update>
 
-<Update label="2025-04-28" description="v0.117.0">
+<Update label="2024-05-15" description="v0.120.1">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01201.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.120.1">View on GitHub</a>
+  </div>
+
+  **Core Improvements & Fixes**
+  - Fixed **interpolation with hyphens**
+</Update>
+
+<Update label="2024-05-14" description="v0.120.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01200.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.120.0">View on GitHub</a>
+  </div>
+
+  **Core Improvements & Fixes**
+  - Enabled **full Ruff rule set** by default for stricter linting
+  - Addressed race condition in FilteredStream using context managers
+  - Fixed agent knowledge reset issue
+  - Refactored agent fetching logic into utility module
+
+  **New Features & Enhancements**
+  - Added support for **loading an Agent directly from a repository**
+  - Enabled setting an empty context for Task
+  - Enhanced Agent repository feedback and fixed Tool auto-import behavior
+  - Introduced direct initialization of knowledge (bypassing knowledge_sources)
+
+  **Documentation & Guides**
+  - Updated security.md for current security practices
+  - Cleaned up Google setup section for clarity
+  - Added link to AI Studio when entering Gemini key
+  - Updated Arize Phoenix observability guide
+  - Refreshed flow documentation
+</Update>
+
+<Update label="2024-05-08" description="v0.119.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01190.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.119.0">View on GitHub</a>
+  </div>
+
+  **Core Improvements & Fixes**
+  - Improved test reliability by enhancing pytest handling for flaky tests
+  - Fixed memory reset crash when embedding dimensions mismatch
+  - Enabled parent flow identification for Crew and LiteAgent
+  - Prevented telemetry-related crashes when unavailable
+  - Upgraded **LiteLLM version** for better compatibility
+  - Fixed llama converter tests by removing skip_external_api
+
+  **New Features & Enhancements**
+  - Introduced **knowledge retrieval prompt re-writing** in Agent for improved tracking and debugging
+  - Made LLM setup and quickstart guides model-agnostic
+
+  **Documentation & Guides**
+  - Added advanced configuration docs for the RAG tool
+  - Updated Windows troubleshooting guide
+  - Refined documentation examples for better clarity
+  - Fixed typos across docs and config files
+</Update>
+
+<Update label="2024-04-28" description="v0.118.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01180.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.118.0">View on GitHub</a>
+  </div>
+
+  **Core Improvements & Fixes**
+  - Fixed issues with missing prompt or system templates
+  - Removed global logging configuration to avoid unintended overrides
+  - Renamed **TaskGuardrail to LLMGuardrail** for improved clarity
+  - Downgraded litellm to version 1.167.1 for compatibility
+  - Added missing init.py files to ensure proper module initialization
+
+  **New Features & Enhancements**
+  - Added support for **no-code Guardrail creation** to simplify AI behavior controls
+
+  **Documentation & Guides**
+  - Removed CrewStructuredTool from public documentation to reflect internal usage
+  - Updated enterprise documentation and YouTube embed for improved onboarding experience
+</Update>
+
+<Update label="2024-04-20" description="v0.117.0">
   ## Release Highlights
   <Frame>
     <img src="/images/releases/v01170.png" />
@@ -57,7 +170,23 @@ icon: timeline
   - Improved SEO, contextual navigation, and error handling for documentation pages.
 </Update>
 
-<Update label="2025-04-07" description="v0.114.0">
+<Update label="2024-04-25" description="v0.117.1">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01171.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.117.1">View on GitHub</a>
+  </div>
+
+  **Core Improvements & Fixes**
+  - Upgraded **crewai-tools** to latest version
+  - Upgraded **liteLLM** to latest version
+  - Fixed **Mem0 OSS**
+</Update>
+
+<Update label="2024-04-07" description="v0.114.0">
   ## Release Highlights
   <Frame>
     <img src="/images/releases/v01140.png" />
@@ -91,7 +220,7 @@ icon: timeline
   - Guide on using singular agents within Flows.
 </Update>
 
-<Update label="2025-03-17" description="v0.108.0">
+<Update label="2024-03-17" description="v0.108.0">
   ## Release Highlights
   <Frame>
     <img src="/images/releases/v01080.png" />
@@ -120,7 +249,16 @@ icon: timeline
   - Added documentation for `ApifyActorsTool`
 </Update>
 
-<Update label="2025-03-10" description="v0.105.0">
+<Update label="2024-03-10" description="v0.105.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01050.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.105.0">View on GitHub</a>
+  </div>
+
   **Core Improvements & Fixes**
   - Fixed issues with missing template variables and user memory configuration
   - Improved async flow support and addressed agent response formatting
@@ -141,7 +279,16 @@ icon: timeline
   - Fixed typos in prompts and updated Amazon Bedrock model listings
 </Update>
 
-<Update label="2025-02-12" description="v0.102.0">
+<Update label="2024-02-12" description="v0.102.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01020.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.102.0">View on GitHub</a>
+  </div>
+
   **Core Improvements & Fixes**
   - Enhanced LLM Support: Improved structured LLM output, parameter handling, and formatting for Anthropic models
   - Crew & Agent Stability: Fixed issues with cloning agents/crews using knowledge sources, multiple task outputs in conditional tasks, and ignored Crew task callbacks
@@ -161,7 +308,16 @@ icon: timeline
   - Fixed Various Typos & Formatting Issues
 </Update>
 
-<Update label="2025-01-28" description="v0.100.0">
+<Update label="2024-01-28" description="v0.100.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v01000.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.100.0">View on GitHub</a>
+  </div>
+
   **Features**
   - Add Composio docs
   - Add SageMaker as a LLM provider
@@ -176,7 +332,16 @@ icon: timeline
   - Improve formatting and clarity in CLI and Composio Tool docs
 </Update>
 
-<Update label="2025-01-20" description="v0.98.0">
+<Update label="2024-01-20" description="v0.98.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v0980.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.98.0">View on GitHub</a>
+  </div>
+
   **Features**
   - Conversation crew v1
   - Add unique ID to flow states
@@ -197,7 +362,16 @@ icon: timeline
   - Fixed typos, nested pydantic model issue, and docling issues
 </Update>
 
-<Update label="2025-01-04" description="v0.95.0">
+<Update label="2024-01-04" description="v0.95.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v0950.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.95.0">View on GitHub</a>
+  </div>
+
   **New Features**
   - Adding Multimodal Abilities to Crew
   - Programatic Guardrails
@@ -228,6 +402,14 @@ icon: timeline
 </Update>
 
 <Update label="2024-12-05" description="v0.86.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v0860.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.86.0">View on GitHub</a>
+  </div>
   **Changes**
   - Remove all references to pipeline and pipeline router
   - Add Nvidia NIM as provider in Custom LLM
@@ -238,6 +420,14 @@ icon: timeline
 </Update>
 
 <Update label="2024-12-04" description="v0.85.0">
+  ## Release Highlights
+  <Frame>
+    <img src="/images/releases/v0850.png" />
+  </Frame>
+  
+  <div style={{ textAlign: 'center', marginBottom: '1rem' }}>
+    <a href="https://github.com/crewAIInc/crewAI/releases/tag/0.85.0">View on GitHub</a>
+  </div>
   **Features**
   - Added knowledge to agent level
   - Feat/remove langchain

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/concepts/agents.mdx

@@ -43,7 +43,6 @@ The Visual Agent Builder enables:
 | **Max Iterations** _(optional)_         | `max_iter`               | `int`                         | Maximum iterations before the agent must provide its best answer. Default is 20.                                      |
 | **Max RPM** _(optional)_                | `max_rpm`                | `Optional[int]`               | Maximum requests per minute to avoid rate limits.                                                                     |
 | **Max Execution Time** _(optional)_     | `max_execution_time`     | `Optional[int]`               | Maximum time (in seconds) for task execution.                                                                         |
-| **Memory** _(optional)_                 | `memory`                 | `bool`                        | Whether the agent should maintain memory of interactions. Default is True.                                            |
 | **Verbose** _(optional)_                | `verbose`                | `bool`                        | Enable detailed execution logs for debugging. Default is False.                                                       |
 | **Allow Delegation** _(optional)_       | `allow_delegation`       | `bool`                        | Allow the agent to delegate tasks to other agents. Default is False.                                                  |
 | **Step Callback** _(optional)_          | `step_callback`          | `Optional[Any]`               | Function called after each agent step, overrides crew callback.                                                       |
@@ -55,11 +54,14 @@ The Visual Agent Builder enables:
 | **Max Retry Limit** _(optional)_        | `max_retry_limit`        | `int`                         | Maximum number of retries when an error occurs. Default is 2.                                                         |
 | **Respect Context Window** _(optional)_ | `respect_context_window` | `bool`                        | Keep messages under context window size by summarizing. Default is True.                                              |
 | **Code Execution Mode** _(optional)_    | `code_execution_mode`    | `Literal["safe", "unsafe"]`   | Mode for code execution: 'safe' (using Docker) or 'unsafe' (direct). Default is 'safe'.                               |
+| **Multimodal** _(optional)_             | `multimodal`             | `bool`                        | Whether the agent supports multimodal capabilities. Default is False.                                                  |
+| **Inject Date** _(optional)_            | `inject_date`            | `bool`                        | Whether to automatically inject the current date into tasks. Default is False.                                         |
+| **Date Format** _(optional)_            | `date_format`            | `str`                         | Format string for date when inject_date is enabled. Default is "%Y-%m-%d" (ISO format).                               |
+| **Reasoning** _(optional)_              | `reasoning`              | `bool`                        | Whether the agent should reflect and create a plan before executing a task. Default is False.                         |
+| **Max Reasoning Attempts** _(optional)_ | `max_reasoning_attempts` | `Optional[int]`               | Maximum number of reasoning attempts before executing the task. If None, will try until ready.                         |
 | **Embedder** _(optional)_               | `embedder`               | `Optional[Dict[str, Any]]`    | Configuration for the embedder used by the agent.                                                                     |
 | **Knowledge Sources** _(optional)_      | `knowledge_sources`      | `Optional[List[BaseKnowledgeSource]]` | Knowledge sources available to the agent.                                                                     |
 | **Use System Prompt** _(optional)_      | `use_system_prompt`      | `Optional[bool]`              | Whether to use system prompt (for o1 model support). Default is True.                                                 |
-| **Inject Date** _(optional)_           | `inject_date`            | `bool`                        | Whether to automatically inject the current date into tasks. Default is False.                                         |
-| **Date Format** _(optional)_           | `date_format`            | `str`                         | Format string for date when inject_date is enabled. Default is "%Y-%m-%d" (ISO format).                                |
 
 ## Creating Agents
 
@@ -153,7 +155,6 @@ agent = Agent(
               "you excel at finding patterns in complex datasets.",
     llm="gpt-4",  # Default: OPENAI_MODEL_NAME or "gpt-4"
     function_calling_llm=None,  # Optional: Separate LLM for tool calling
-    memory=True,  # Default: True
     verbose=False,  # Default: False
     allow_delegation=False,  # Default: False
     max_iter=20,  # Default: 20 iterations
@@ -164,6 +165,11 @@ agent = Agent(
     code_execution_mode="safe",  # Default: "safe" (options: "safe", "unsafe")
     respect_context_window=True,  # Default: True
     use_system_prompt=True,  # Default: True
+    multimodal=False,  # Default: False
+    inject_date=False,  # Default: False
+    date_format="%Y-%m-%d",  # Default: ISO format
+    reasoning=False,  # Default: False
+    max_reasoning_attempts=None,  # Default: None
     tools=[SerperDevTool()],  # Optional: List of tools
     knowledge_sources=None,  # Optional: List of knowledge sources
     embedder=None,  # Optional: Custom embedder configuration
@@ -228,14 +234,40 @@ custom_agent = Agent(
 )
 ```
 
-#### Date-Aware Agent
+#### Date-Aware Agent with Reasoning
 ```python Code
-date_aware_agent = Agent(
+strategic_agent = Agent(
     role="Market Analyst",
-    goal="Track market movements with precise date references",
-    backstory="Expert in time-sensitive financial analysis and reporting",
+    goal="Track market movements with precise date references and strategic planning",
+    backstory="Expert in time-sensitive financial analysis and strategic reporting",
     inject_date=True,  # Automatically inject current date into tasks
     date_format="%B %d, %Y",  # Format as "May 21, 2025"
+    reasoning=True,  # Enable strategic planning
+    max_reasoning_attempts=2,  # Limit planning iterations
+    verbose=True
+)
+```
+
+#### Reasoning Agent
+```python Code
+reasoning_agent = Agent(
+    role="Strategic Planner",
+    goal="Analyze complex problems and create detailed execution plans",
+    backstory="Expert strategic planner who methodically breaks down complex challenges",
+    reasoning=True,  # Enable reasoning and planning
+    max_reasoning_attempts=3,  # Limit reasoning attempts
+    max_iter=30,  # Allow more iterations for complex planning
+    verbose=True
+)
+```
+
+#### Multimodal Agent
+```python Code
+multimodal_agent = Agent(
+    role="Visual Content Analyst",
+    goal="Analyze and process both text and visual content",
+    backstory="Specialized in multimodal analysis combining text and image understanding",
+    multimodal=True,  # Enable multimodal capabilities
     verbose=True
 )
 ```
@@ -263,6 +295,11 @@ date_aware_agent = Agent(
   - `"safe"`: Uses Docker (recommended for production)
   - `"unsafe"`: Direct execution (use only in trusted environments)
 
+#### Advanced Features
+- `multimodal`: Enable multimodal capabilities for processing text and visual content
+- `reasoning`: Enable agent to reflect and create plans before executing tasks
+- `inject_date`: Automatically inject current date into task descriptions
+
 #### Templates
 - `system_template`: Defines agent's core behavior
 - `prompt_template`: Structures input format
@@ -320,6 +357,170 @@ analyst = Agent(
 When `memory` is enabled, the agent will maintain context across multiple interactions, improving its ability to handle complex, multi-step tasks.
 </Note>
 
+## Context Window Management
+
+CrewAI includes sophisticated automatic context window management to handle situations where conversations exceed the language model's token limits. This powerful feature is controlled by the `respect_context_window` parameter.
+
+### How Context Window Management Works
+
+When an agent's conversation history grows too large for the LLM's context window, CrewAI automatically detects this situation and can either:
+
+1. **Automatically summarize content** (when `respect_context_window=True`)
+2. **Stop execution with an error** (when `respect_context_window=False`)
+
+### Automatic Context Handling (`respect_context_window=True`)
+
+This is the **default and recommended setting** for most use cases. When enabled, CrewAI will:
+
+```python Code
+# Agent with automatic context management (default)
+smart_agent = Agent(
+    role="Research Analyst",
+    goal="Analyze large documents and datasets",
+    backstory="Expert at processing extensive information",
+    respect_context_window=True,  # 🔑 Default: auto-handle context limits
+    verbose=True
+)
+```
+
+**What happens when context limits are exceeded:**
+- ⚠️ **Warning message**: `"Context length exceeded. Summarizing content to fit the model context window."`
+- 🔄 **Automatic summarization**: CrewAI intelligently summarizes the conversation history
+- ✅ **Continued execution**: Task execution continues seamlessly with the summarized context
+- 📝 **Preserved information**: Key information is retained while reducing token count
+
+### Strict Context Limits (`respect_context_window=False`)
+
+When you need precise control and prefer execution to stop rather than lose any information:
+
+```python Code
+# Agent with strict context limits
+strict_agent = Agent(
+    role="Legal Document Reviewer",
+    goal="Provide precise legal analysis without information loss",
+    backstory="Legal expert requiring complete context for accurate analysis",
+    respect_context_window=False,  # ❌ Stop execution on context limit
+    verbose=True
+)
+```
+
+**What happens when context limits are exceeded:**
+- ❌ **Error message**: `"Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."`
+- 🛑 **Execution stops**: Task execution halts immediately
+- 🔧 **Manual intervention required**: You need to modify your approach
+
+### Choosing the Right Setting
+
+#### Use `respect_context_window=True` (Default) when:
+- **Processing large documents** that might exceed context limits
+- **Long-running conversations** where some summarization is acceptable
+- **Research tasks** where general context is more important than exact details
+- **Prototyping and development** where you want robust execution
+
+```python Code
+# Perfect for document processing
+document_processor = Agent(
+    role="Document Analyst", 
+    goal="Extract insights from large research papers",
+    backstory="Expert at analyzing extensive documentation",
+    respect_context_window=True,  # Handle large documents gracefully
+    max_iter=50,  # Allow more iterations for complex analysis
+    verbose=True
+)
+```
+
+#### Use `respect_context_window=False` when:
+- **Precision is critical** and information loss is unacceptable
+- **Legal or medical tasks** requiring complete context
+- **Code review** where missing details could introduce bugs
+- **Financial analysis** where accuracy is paramount
+
+```python Code
+# Perfect for precision tasks
+precision_agent = Agent(
+    role="Code Security Auditor",
+    goal="Identify security vulnerabilities in code",
+    backstory="Security expert requiring complete code context",
+    respect_context_window=False,  # Prefer failure over incomplete analysis
+    max_retry_limit=1,  # Fail fast on context issues
+    verbose=True
+)
+```
+
+### Alternative Approaches for Large Data
+
+When dealing with very large datasets, consider these strategies:
+
+#### 1. Use RAG Tools
+```python Code
+from crewai_tools import RagTool
+
+# Create RAG tool for large document processing
+rag_tool = RagTool()
+
+rag_agent = Agent(
+    role="Research Assistant",
+    goal="Query large knowledge bases efficiently",
+    backstory="Expert at using RAG tools for information retrieval",
+    tools=[rag_tool],  # Use RAG instead of large context windows
+    respect_context_window=True,
+    verbose=True
+)
+```
+
+#### 2. Use Knowledge Sources
+```python Code
+# Use knowledge sources instead of large prompts
+knowledge_agent = Agent(
+    role="Knowledge Expert",
+    goal="Answer questions using curated knowledge",
+    backstory="Expert at leveraging structured knowledge sources",
+    knowledge_sources=[your_knowledge_sources],  # Pre-processed knowledge
+    respect_context_window=True,
+    verbose=True
+)
+```
+
+### Context Window Best Practices
+
+1. **Monitor Context Usage**: Enable `verbose=True` to see context management in action
+2. **Design for Efficiency**: Structure tasks to minimize context accumulation
+3. **Use Appropriate Models**: Choose LLMs with context windows suitable for your tasks
+4. **Test Both Settings**: Try both `True` and `False` to see which works better for your use case
+5. **Combine with RAG**: Use RAG tools for very large datasets instead of relying solely on context windows
+
+### Troubleshooting Context Issues
+
+**If you're getting context limit errors:**
+```python Code
+# Quick fix: Enable automatic handling
+agent.respect_context_window = True
+
+# Better solution: Use RAG tools for large data
+from crewai_tools import RagTool
+agent.tools = [RagTool()]
+
+# Alternative: Break tasks into smaller pieces
+# Or use knowledge sources instead of large prompts
+```
+
+**If automatic summarization loses important information:**
+```python Code
+# Disable auto-summarization and use RAG instead
+agent = Agent(
+    role="Detailed Analyst",
+    goal="Maintain complete information accuracy",
+    backstory="Expert requiring full context",
+    respect_context_window=False,  # No summarization
+    tools=[RagTool()],  # Use RAG for large data
+    verbose=True
+)
+```
+
+<Note>
+The context window management feature works automatically in the background. You don't need to call any special functions - just set `respect_context_window` to your preferred behavior and CrewAI handles the rest!
+</Note>
+
 ## Important Considerations and Best Practices
 
 ### Security and Code Execution
@@ -334,11 +535,17 @@ When `memory` is enabled, the agent will maintain context across multiple intera
 - Adjust `max_iter` and `max_retry_limit` based on task complexity
 
 ### Memory and Context Management
-- Use `memory: true` for tasks requiring historical context
 - Leverage `knowledge_sources` for domain-specific information
-- Configure `embedder_config` when using custom embedding models
+- Configure `embedder` when using custom embedding models
 - Use custom templates (`system_template`, `prompt_template`, `response_template`) for fine-grained control over agent behavior
 
+### Advanced Features
+- Enable `reasoning: true` for agents that need to plan and reflect before executing complex tasks
+- Set appropriate `max_reasoning_attempts` to control planning iterations (None for unlimited attempts)
+- Use `inject_date: true` to provide agents with current date awareness for time-sensitive tasks
+- Customize the date format with `date_format` using standard Python datetime format codes
+- Enable `multimodal: true` for agents that need to process both text and visual content
+
 ### Agent Collaboration
 - Enable `allow_delegation: true` when agents need to work together
 - Use `step_callback` to monitor and log agent interactions
@@ -346,11 +553,12 @@ When `memory` is enabled, the agent will maintain context across multiple intera
   - Main `llm` for complex reasoning
   - `function_calling_llm` for efficient tool usage
 
-### Date Awareness
-- Use `inject_date: true` to provide agents with current date awareness
+### Date Awareness and Reasoning
+- Use `inject_date: true` to provide agents with current date awareness for time-sensitive tasks
 - Customize the date format with `date_format` using standard Python datetime format codes
 - Valid format codes include: %Y (year), %m (month), %d (day), %B (full month name), etc.
 - Invalid date formats will be logged as warnings and will not modify the task description
+- Enable `reasoning: true` for complex tasks that benefit from upfront planning and reflection
 
 ### Model Compatibility
 - Set `use_system_prompt: false` for older models that don't support system messages
@@ -374,7 +582,6 @@ When `memory` is enabled, the agent will maintain context across multiple intera
    - Review code sandbox settings
 
 4. **Memory Issues**: If agent responses seem inconsistent:
-   - Verify memory is enabled
    - Check knowledge source configuration
    - Review conversation history management
 

docs/concepts/cli.mdx

@@ -200,6 +200,37 @@ Deploy the crew or flow to [CrewAI Enterprise](https://app.crewai.com).
     ```
     - Reads your local project configuration.
     - Prompts you to confirm the environment variables (like `OPENAI_API_KEY`, `SERPER_API_KEY`) found locally. These will be securely stored with the deployment on the Enterprise platform. Ensure your sensitive keys are correctly configured locally (e.g., in a `.env` file) before running this.
+
+### 11. Organization Management
+
+Manage your CrewAI Enterprise organizations.
+
+```shell Terminal
+crewai org [COMMAND] [OPTIONS]
+```
+
+#### Commands:
+
+- `list`: List all organizations you belong to
+```shell Terminal
+crewai org list
+```
+
+- `current`: Display your currently active organization
+```shell Terminal
+crewai org current
+```
+
+- `switch`: Switch to a specific organization
+```shell Terminal
+crewai org switch <organization_id>
+```
+
+<Note>
+You must be authenticated to CrewAI Enterprise to use these organization management commands.
+</Note>
+
+- **Create a deployment** (continued):
     - Links the deployment to the corresponding remote GitHub repository (it usually detects this automatically).
 
 - **Deploy the Crew**: Once you are authenticated, you can deploy your crew or flow to CrewAI Enterprise.

docs/concepts/collaboration.mdx

@@ -1,51 +1,362 @@
 ---
 title: Collaboration
-description: Exploring the dynamics of agent collaboration within the CrewAI framework, focusing on the newly integrated features for enhanced functionality.
+description: How to enable agents to work together, delegate tasks, and communicate effectively within CrewAI teams.
 icon: screen-users
 ---
 
-## Overview    
+## Overview
 
-Collaboration in CrewAI is fundamental, enabling agents to combine their skills, share information, and assist each other in task execution, embodying a truly cooperative ecosystem.
+Collaboration in CrewAI enables agents to work together as a team by delegating tasks and asking questions to leverage each other's expertise. When `allow_delegation=True`, agents automatically gain access to powerful collaboration tools.
 
-- **Information Sharing**: Ensures all agents are well-informed and can contribute effectively by sharing data and findings.
-- **Task Assistance**: Allows agents to seek help from peers with the required expertise for specific tasks.
-- **Resource Allocation**: Optimizes task execution through the efficient distribution and sharing of resources among agents.
+## Quick Start: Enable Collaboration
 
-## Enhanced Attributes for Improved Collaboration
+```python
+from crewai import Agent, Crew, Task
 
-The `Crew` class has been enriched with several attributes to support advanced functionalities:
+# Enable collaboration for agents
+researcher = Agent(
+    role="Research Specialist",
+    goal="Conduct thorough research on any topic",
+    backstory="Expert researcher with access to various sources",
+    allow_delegation=True,  # 🔑 Key setting for collaboration
+    verbose=True
+)
 
-| Feature                                    | Description                                                                                                                                                                                                                  |
-|:-------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Language Model Management** (`manager_llm`, `function_calling_llm`) | Manages language models for executing tasks and tools. `manager_llm` is required for hierarchical processes, while `function_calling_llm` is optional with a default value for streamlined interactions.                    |
-| **Custom Manager Agent** (`manager_agent`) | Specifies a custom agent as the manager, replacing the default CrewAI manager.                                                                                                                                                |
-| **Process Flow** (`process`)           | Defines execution logic (e.g., sequential, hierarchical) for task distribution.                                                                                                                                                |
-| **Verbose Logging** (`verbose`)        | Provides detailed logging for monitoring and debugging. Accepts integer and boolean values to control verbosity level.                                                                                                       |
-| **Rate Limiting** (`max_rpm`)          | Limits requests per minute to optimize resource usage. Setting guidelines depend on task complexity and load.                                                                                                                 |
-| **Internationalization / Customization** (`prompt_file`) | Supports prompt customization for global usability. [Example of file](https://github.com/joaomdmoura/crewAI/blob/main/src/crewai/translations/en.json)                                                                                      |
-| **Callback and Telemetry** (`step_callback`, `task_callback`) | Enables step-wise and task-level execution monitoring and telemetry for performance analytics.                                                                                                                               |
-| **Crew Sharing** (`share_crew`)        | Allows sharing crew data with CrewAI for model improvement. Privacy implications and benefits should be considered.                                                                                                          |
-| **Usage Metrics** (`usage_metrics`)    | Logs all LLM usage metrics during task execution for performance insights.                                                                                                                           |
-| **Memory Usage** (`memory`)            | Enables memory for storing execution history, aiding in agent learning and task efficiency.                                                                                                                                  |
-| **Embedder Configuration** (`embedder`) | Configures the embedder for language understanding and generation, with support for provider customization.                                                                                                                   |
-| **Cache Management** (`cache`)         | Specifies whether to cache tool execution results, enhancing performance.                                                                                                                                                   |
-| **Output Logging** (`output_log_file`) | Defines the file path for logging crew execution output.                                                                                                                                                                      |
-| **Planning Mode** (`planning`)         | Enables action planning before task execution. Set `planning=True` to activate.                                                                                                                                              |
-| **Replay Feature** (`replay`)         | Provides CLI for listing tasks from the last run and replaying from specific tasks, aiding in task management and troubleshooting.                                                                                           |
+writer = Agent(
+    role="Content Writer", 
+    goal="Create engaging content based on research",
+    backstory="Skilled writer who transforms research into compelling content",
+    allow_delegation=True,  # 🔑 Enables asking questions to other agents
+    verbose=True
+)
 
-## Delegation (Dividing to Conquer)
+# Agents can now collaborate automatically
+crew = Crew(
+    agents=[researcher, writer],
+    tasks=[...],
+    verbose=True
+)
+```
 
-Delegation enhances functionality by allowing agents to intelligently assign tasks or seek help, thereby amplifying the crew's overall capability.
+## How Agent Collaboration Works
 
-## Implementing Collaboration and Delegation
+When `allow_delegation=True`, CrewAI automatically provides agents with two powerful tools:
 
-Setting up a crew involves defining the roles and capabilities of each agent. CrewAI seamlessly manages their interactions, ensuring efficient collaboration and delegation, with enhanced customization and monitoring features to adapt to various operational needs.
+### 1. **Delegate Work Tool**
+Allows agents to assign tasks to teammates with specific expertise.
 
-## Example Scenario
+```python
+# Agent automatically gets this tool:
+# Delegate work to coworker(task: str, context: str, coworker: str)
+```
 
-Consider a crew with a researcher agent tasked with data gathering and a writer agent responsible for compiling reports. The integration of advanced language model management and process flow attributes allows for more sophisticated interactions, such as the writer delegating complex research tasks to the researcher or querying specific information, thereby facilitating a seamless workflow.
+### 2. **Ask Question Tool** 
+Enables agents to ask specific questions to gather information from colleagues.
 
-## Conclusion
+```python
+# Agent automatically gets this tool:
+# Ask question to coworker(question: str, context: str, coworker: str)
+```
 
-The integration of advanced attributes and functionalities into the CrewAI framework significantly enriches the agent collaboration ecosystem. These enhancements not only simplify interactions but also offer unprecedented flexibility and control, paving the way for sophisticated AI-driven solutions capable of tackling complex tasks through intelligent collaboration and delegation.
+## Collaboration in Action
+
+Here's a complete example showing agents collaborating on a content creation task:
+
+```python
+from crewai import Agent, Crew, Task, Process
+
+# Create collaborative agents
+researcher = Agent(
+    role="Research Specialist",
+    goal="Find accurate, up-to-date information on any topic",
+    backstory="""You're a meticulous researcher with expertise in finding 
+    reliable sources and fact-checking information across various domains.""",
+    allow_delegation=True,
+    verbose=True
+)
+
+writer = Agent(
+    role="Content Writer",
+    goal="Create engaging, well-structured content",
+    backstory="""You're a skilled content writer who excels at transforming 
+    research into compelling, readable content for different audiences.""",
+    allow_delegation=True,
+    verbose=True
+)
+
+editor = Agent(
+    role="Content Editor",
+    goal="Ensure content quality and consistency",
+    backstory="""You're an experienced editor with an eye for detail, 
+    ensuring content meets high standards for clarity and accuracy.""",
+    allow_delegation=True,
+    verbose=True
+)
+
+# Create a task that encourages collaboration
+article_task = Task(
+    description="""Write a comprehensive 1000-word article about 'The Future of AI in Healthcare'.
+    
+    The article should include:
+    - Current AI applications in healthcare
+    - Emerging trends and technologies  
+    - Potential challenges and ethical considerations
+    - Expert predictions for the next 5 years
+    
+    Collaborate with your teammates to ensure accuracy and quality.""",
+    expected_output="A well-researched, engaging 1000-word article with proper structure and citations",
+    agent=writer  # Writer leads, but can delegate research to researcher
+)
+
+# Create collaborative crew
+crew = Crew(
+    agents=[researcher, writer, editor],
+    tasks=[article_task],
+    process=Process.sequential,
+    verbose=True
+)
+
+result = crew.kickoff()
+```
+
+## Collaboration Patterns
+
+### Pattern 1: Research → Write → Edit
+```python
+research_task = Task(
+    description="Research the latest developments in quantum computing",
+    expected_output="Comprehensive research summary with key findings and sources",
+    agent=researcher
+)
+
+writing_task = Task(
+    description="Write an article based on the research findings",
+    expected_output="Engaging 800-word article about quantum computing",
+    agent=writer,
+    context=[research_task]  # Gets research output as context
+)
+
+editing_task = Task(
+    description="Edit and polish the article for publication",
+    expected_output="Publication-ready article with improved clarity and flow",
+    agent=editor,
+    context=[writing_task]  # Gets article draft as context
+)
+```
+
+### Pattern 2: Collaborative Single Task
+```python
+collaborative_task = Task(
+    description="""Create a marketing strategy for a new AI product.
+    
+    Writer: Focus on messaging and content strategy
+    Researcher: Provide market analysis and competitor insights
+    
+    Work together to create a comprehensive strategy.""",
+    expected_output="Complete marketing strategy with research backing",
+    agent=writer  # Lead agent, but can delegate to researcher
+)
+```
+
+## Hierarchical Collaboration
+
+For complex projects, use a hierarchical process with a manager agent:
+
+```python
+from crewai import Agent, Crew, Task, Process
+
+# Manager agent coordinates the team
+manager = Agent(
+    role="Project Manager",
+    goal="Coordinate team efforts and ensure project success",
+    backstory="Experienced project manager skilled at delegation and quality control",
+    allow_delegation=True,
+    verbose=True
+)
+
+# Specialist agents
+researcher = Agent(
+    role="Researcher",
+    goal="Provide accurate research and analysis",
+    backstory="Expert researcher with deep analytical skills",
+    allow_delegation=False,  # Specialists focus on their expertise
+    verbose=True
+)
+
+writer = Agent(
+    role="Writer", 
+    goal="Create compelling content",
+    backstory="Skilled writer who creates engaging content",
+    allow_delegation=False,
+    verbose=True
+)
+
+# Manager-led task
+project_task = Task(
+    description="Create a comprehensive market analysis report with recommendations",
+    expected_output="Executive summary, detailed analysis, and strategic recommendations",
+    agent=manager  # Manager will delegate to specialists
+)
+
+# Hierarchical crew
+crew = Crew(
+    agents=[manager, researcher, writer],
+    tasks=[project_task],
+    process=Process.hierarchical,  # Manager coordinates everything
+    manager_llm="gpt-4o",  # Specify LLM for manager
+    verbose=True
+)
+```
+
+## Best Practices for Collaboration
+
+### 1. **Clear Role Definition**
+```python
+# ✅ Good: Specific, complementary roles
+researcher = Agent(role="Market Research Analyst", ...)
+writer = Agent(role="Technical Content Writer", ...)
+
+# ❌ Avoid: Overlapping or vague roles  
+agent1 = Agent(role="General Assistant", ...)
+agent2 = Agent(role="Helper", ...)
+```
+
+### 2. **Strategic Delegation Enabling**
+```python
+# ✅ Enable delegation for coordinators and generalists
+lead_agent = Agent(
+    role="Content Lead",
+    allow_delegation=True,  # Can delegate to specialists
+    ...
+)
+
+# ✅ Disable for focused specialists (optional)
+specialist_agent = Agent(
+    role="Data Analyst", 
+    allow_delegation=False,  # Focuses on core expertise
+    ...
+)
+```
+
+### 3. **Context Sharing**
+```python
+# ✅ Use context parameter for task dependencies
+writing_task = Task(
+    description="Write article based on research",
+    agent=writer,
+    context=[research_task],  # Shares research results
+    ...
+)
+```
+
+### 4. **Clear Task Descriptions**
+```python
+# ✅ Specific, actionable descriptions
+Task(
+    description="""Research competitors in the AI chatbot space.
+    Focus on: pricing models, key features, target markets.
+    Provide data in a structured format.""",
+    ...
+)
+
+# ❌ Vague descriptions that don't guide collaboration
+Task(description="Do some research about chatbots", ...)
+```
+
+## Troubleshooting Collaboration
+
+### Issue: Agents Not Collaborating
+**Symptoms:** Agents work in isolation, no delegation occurs
+```python
+# ✅ Solution: Ensure delegation is enabled
+agent = Agent(
+    role="...",
+    allow_delegation=True,  # This is required!
+    ...
+)
+```
+
+### Issue: Too Much Back-and-Forth
+**Symptoms:** Agents ask excessive questions, slow progress
+```python
+# ✅ Solution: Provide better context and specific roles
+Task(
+    description="""Write a technical blog post about machine learning.
+    
+    Context: Target audience is software developers with basic ML knowledge.
+    Length: 1200 words
+    Include: code examples, practical applications, best practices
+    
+    If you need specific technical details, delegate research to the researcher.""",
+    ...
+)
+```
+
+### Issue: Delegation Loops
+**Symptoms:** Agents delegate back and forth indefinitely
+```python
+# ✅ Solution: Clear hierarchy and responsibilities
+manager = Agent(role="Manager", allow_delegation=True)
+specialist1 = Agent(role="Specialist A", allow_delegation=False)  # No re-delegation
+specialist2 = Agent(role="Specialist B", allow_delegation=False)
+```
+
+## Advanced Collaboration Features
+
+### Custom Collaboration Rules
+```python
+# Set specific collaboration guidelines in agent backstory
+agent = Agent(
+    role="Senior Developer",
+    backstory="""You lead development projects and coordinate with team members.
+    
+    Collaboration guidelines:
+    - Delegate research tasks to the Research Analyst
+    - Ask the Designer for UI/UX guidance  
+    - Consult the QA Engineer for testing strategies
+    - Only escalate blocking issues to the Project Manager""",
+    allow_delegation=True
+)
+```
+
+### Monitoring Collaboration
+```python
+def track_collaboration(output):
+    """Track collaboration patterns"""
+    if "Delegate work to coworker" in output.raw:
+        print("🤝 Delegation occurred")
+    if "Ask question to coworker" in output.raw:
+        print("❓ Question asked")
+
+crew = Crew(
+    agents=[...],
+    tasks=[...],
+    step_callback=track_collaboration,  # Monitor collaboration
+    verbose=True
+)
+```
+
+## Memory and Learning
+
+Enable agents to remember past collaborations:
+
+```python
+agent = Agent(
+    role="Content Lead",
+    memory=True,  # Remembers past interactions
+    allow_delegation=True,
+    verbose=True
+)
+```
+
+With memory enabled, agents learn from previous collaborations and improve their delegation decisions over time.
+
+## Next Steps
+
+- **Try the examples**: Start with the basic collaboration example
+- **Experiment with roles**: Test different agent role combinations  
+- **Monitor interactions**: Use `verbose=True` to see collaboration in action
+- **Optimize task descriptions**: Clear tasks lead to better collaboration
+- **Scale up**: Try hierarchical processes for complex projects
+
+Collaboration transforms individual AI agents into powerful teams that can tackle complex, multi-faceted challenges together.

docs/concepts/crews.mdx

@@ -325,12 +325,12 @@ for result in results:
 
 # Example of using kickoff_async
 inputs = {'topic': 'AI in healthcare'}
-async_result = my_crew.kickoff_async(inputs=inputs)
+async_result = await my_crew.kickoff_async(inputs=inputs)
 print(async_result)
 
 # Example of using kickoff_for_each_async
 inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
-async_results = my_crew.kickoff_for_each_async(inputs=inputs_array)
+async_results = await my_crew.kickoff_for_each_async(inputs=inputs_array)
 for async_result in async_results:
     print(async_result)
 ```

docs/concepts/llms.mdx

@@ -152,6 +152,39 @@ In this section, you'll find detailed examples that help you select, configure,
     | o1                  | 200,000 tokens   | Fast reasoning, complex reasoning             |
   </Accordion>
 
+  <Accordion title="Meta-Llama">
+    Meta's Llama API provides access to Meta's family of large language models.
+    The API is available through the [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website).
+    Set the following environment variables in your `.env` file:
+
+    ```toml Code
+    # Meta Llama API Key Configuration
+    LLAMA_API_KEY=LLM|your_api_key_here
+    ```
+
+    Example usage in your CrewAI project:
+    ```python Code
+    from crewai import LLM
+
+    # Initialize Meta Llama LLM
+    llm = LLM(
+        model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8",
+        temperature=0.8,
+        stop=["END"],
+        seed=42
+    )
+    ```
+
+    All models listed here https://llama.developer.meta.com/docs/models/ are supported.
+
+    | Model ID | Input context length | Output context length | Input Modalities | Output Modalities |
+    | --- | --- | --- | --- | --- |
+    | `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
+    | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
+    | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | Text | Text |
+    | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | Text | Text |
+  </Accordion>
+
   <Accordion title="Anthropic">
     ```toml Code
     # Required

docs/concepts/planning.mdx

@@ -29,6 +29,10 @@ my_crew = Crew(
 
 From this point on, your crew will have planning enabled, and the tasks will be planned before each iteration.
 
+<Warning>
+When planning is enabled, crewAI will use `gpt-4o-mini` as the default LLM for planning, which requires a valid OpenAI API key. Since your agents might be using different LLMs, this could cause confusion if you don't have an OpenAI API key configured or if you're experiencing unexpected behavior related to LLM API calls.
+</Warning>
+
 #### Planning LLM
 
 Now you can define the LLM that will be used to plan the tasks. 

docs/concepts/tasks.mdx

@@ -51,6 +51,7 @@ crew = Crew(
 | **Context** _(optional)_         | `context`         | `Optional[List["Task"]]`      | Other tasks whose outputs will be used as context for this task.                                                     |
 | **Async Execution** _(optional)_ | `async_execution` | `Optional[bool]`              | Whether the task should be executed asynchronously. Defaults to False.                                               |
 | **Human Input** _(optional)_     | `human_input`     | `Optional[bool]`              | Whether the task should have a human review the final answer of the agent. Defaults to False.                        |
+| **Markdown** _(optional)_        | `markdown`        | `Optional[bool]`              | Whether the task should instruct the agent to return the final answer formatted in Markdown. Defaults to False.      |
 | **Config** _(optional)_          | `config`          | `Optional[Dict[str, Any]]`    | Task-specific configuration parameters.                                                                              |
 | **Output File** _(optional)_     | `output_file`     | `Optional[str]`               | File path for storing the task output.                                                                               |
 | **Output JSON** _(optional)_     | `output_json`     | `Optional[Type[BaseModel]]`   | A Pydantic model to structure the JSON output.                                                                       |
@@ -94,6 +95,7 @@ reporting_task:
     A fully fledge reports with the mains topics, each with a full section of information.
     Formatted as markdown without '```'
   agent: reporting_analyst
+  markdown: true
   output_file: report.md
 ```
 
@@ -182,9 +184,9 @@ reporting_task = Task(
     """,
     expected_output="""
         A fully fledge reports with the mains topics, each with a full section of information.
-        Formatted as markdown without '```'
     """,
     agent=reporting_analyst,
+    markdown=True,  # Enable markdown formatting for the final output
     output_file="report.md"
 )
 ```
@@ -257,6 +259,54 @@ if task_output.pydantic:
     print(f"Pydantic Output: {task_output.pydantic}")
 ```
 
+## Markdown Output Formatting
+
+The `markdown` parameter enables automatic markdown formatting for task outputs. When set to `True`, the task will instruct the agent to format the final answer using proper Markdown syntax.
+
+### Using Markdown Formatting
+
+```python Code
+# Example task with markdown formatting enabled
+formatted_task = Task(
+    description="Create a comprehensive report on AI trends",
+    expected_output="A well-structured report with headers, sections, and bullet points",
+    agent=reporter_agent,
+    markdown=True  # Enable automatic markdown formatting
+)
+```
+
+When `markdown=True`, the agent will receive additional instructions to format the output using:
+- `#` for headers
+- `**text**` for bold text  
+- `*text*` for italic text
+- `-` or `*` for bullet points
+- `` `code` `` for inline code
+- ``` ```language ``` for code blocks
+
+### YAML Configuration with Markdown
+
+```yaml tasks.yaml
+analysis_task:
+  description: >
+    Analyze the market data and create a detailed report
+  expected_output: >
+    A comprehensive analysis with charts and key findings
+  agent: analyst
+  markdown: true  # Enable markdown formatting
+  output_file: analysis.md
+```
+
+### Benefits of Markdown Output
+
+- **Consistent Formatting**: Ensures all outputs follow proper markdown conventions
+- **Better Readability**: Structured content with headers, lists, and emphasis
+- **Documentation Ready**: Output can be directly used in documentation systems
+- **Cross-Platform Compatibility**: Markdown is universally supported
+
+<Note>
+The markdown formatting instructions are automatically added to the task prompt when `markdown=True`, so you don't need to specify formatting requirements in your task description.
+</Note>
+
 ## Task Dependencies and Context
 
 Tasks can depend on the output of other tasks using the `context` attribute. For example:
@@ -319,7 +369,7 @@ blog_task = Task(
    - Type hints are recommended but optional
 
 2. **Return Values**:
-   - On success: it returns a tuple of `(bool, Any)`. For example: `(True, validated_result)` 
+   - On success: it returns a tuple of `(bool, Any)`. For example: `(True, validated_result)`
    - On Failure: it returns a tuple of `(bool, str)`. For example: `(False, "Error message explain the failure")`
 
 ### LLMGuardrail
@@ -330,7 +380,7 @@ The `LLMGuardrail` class offers a robust mechanism for validating task outputs.
 
 1. **Structured Error Responses**:
 ```python Code
-from crewai import TaskOutput
+from crewai import TaskOutput, LLMGuardrail
 
 def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]:
     try:

docs/concepts/tools.mdx

@@ -32,6 +32,7 @@ The Enterprise Tools Repository includes:
 - **Customizability**: Provides the flexibility to develop custom tools or utilize existing ones, catering to the specific needs of agents.
 - **Error Handling**: Incorporates robust error handling mechanisms to ensure smooth operation.
 - **Caching Mechanism**: Features intelligent caching to optimize performance and reduce redundant operations.
+- **Asynchronous Support**: Handles both synchronous and asynchronous tools, enabling non-blocking operations.
 
 ## Using CrewAI Tools
 
@@ -177,6 +178,62 @@ class MyCustomTool(BaseTool):
         return "Tool's result"
 ```
 
+## Asynchronous Tool Support
+
+CrewAI supports asynchronous tools, allowing you to implement tools that perform non-blocking operations like network requests, file I/O, or other async operations without blocking the main execution thread.
+
+### Creating Async Tools
+
+You can create async tools in two ways:
+
+#### 1. Using the `tool` Decorator with Async Functions
+
+```python Code
+from crewai.tools import tool
+
+@tool("fetch_data_async")
+async def fetch_data_async(query: str) -> str:
+    """Asynchronously fetch data based on the query."""
+    # Simulate async operation
+    await asyncio.sleep(1)
+    return f"Data retrieved for {query}"
+```
+
+#### 2. Implementing Async Methods in Custom Tool Classes
+
+```python Code
+from crewai.tools import BaseTool
+
+class AsyncCustomTool(BaseTool):
+    name: str = "async_custom_tool"
+    description: str = "An asynchronous custom tool"
+    
+    async def _run(self, query: str = "") -> str:
+        """Asynchronously run the tool"""
+        # Your async implementation here
+        await asyncio.sleep(1)
+        return f"Processed {query} asynchronously"
+```
+
+### Using Async Tools
+
+Async tools work seamlessly in both standard Crew workflows and Flow-based workflows:
+
+```python Code
+# In standard Crew
+agent = Agent(role="researcher", tools=[async_custom_tool])
+
+# In Flow
+class MyFlow(Flow):
+    @start()
+    async def begin(self):
+        crew = Crew(agents=[agent])
+        result = await crew.kickoff_async()
+        return result
+```
+
+The CrewAI framework automatically handles the execution of both synchronous and asynchronous tools, so you don't need to worry about how to call them differently.
+
 ### Utilizing the `tool` Decorator
 
 ```python Code

docs/docs.json

@@ -7,9 +7,14 @@
     "light": "#F3A78B",
     "dark": "#C94C3C"
   },
-  "favicon": "favicon.svg",
+  "favicon": "images/favicon.svg",
   "contextual": {
-    "options": ["copy", "view", "chatgpt", "claude"]
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude"
+    ]
   },
   "navigation": {
     "tabs": [
@@ -83,101 +88,155 @@
             ]
           },
           {
-            "group": "Tools",
+            "group": "MCP Integration",
             "pages": [
-              "tools/aimindtool",
-              "tools/apifyactorstool",
-              "tools/bedrockinvokeagenttool",
-              "tools/bedrockkbretriever",
-              "tools/bravesearchtool",
-              "tools/browserbaseloadtool",
-              "tools/codedocssearchtool",
-              "tools/codeinterpretertool",
-              "tools/composiotool",
-              "tools/csvsearchtool",
-              "tools/dalletool",
-              "tools/directorysearchtool",
-              "tools/directoryreadtool",
-              "tools/docxsearchtool",
-              "tools/exasearchtool",
-              "tools/filereadtool",
-              "tools/filewritetool",
-              "tools/firecrawlcrawlwebsitetool",
-              "tools/firecrawlscrapewebsitetool",
-              "tools/firecrawlsearchtool",
-              "tools/githubsearchtool",
-              "tools/hyperbrowserloadtool",
-              "tools/linkupsearchtool",
-              "tools/llamaindextool",
-              "tools/langchaintool",
-              "tools/serperdevtool",
-              "tools/s3readertool",
-              "tools/s3writertool",
-              "tools/scrapegraphscrapetool",
-              "tools/scrapeelementfromwebsitetool",
-              "tools/jsonsearchtool",
-              "tools/mdxsearchtool",
-              "tools/mysqltool",
-              "tools/multiontool",
-              "tools/nl2sqltool",
-              "tools/patronustools",
-              "tools/pdfsearchtool",
-              "tools/pgsearchtool",
-              "tools/qdrantvectorsearchtool",
-              "tools/ragtool",
-              "tools/scrapewebsitetool",
-              "tools/scrapflyscrapetool",
-              "tools/seleniumscrapingtool",
-              "tools/snowflakesearchtool",
-              "tools/spidertool",
-              "tools/stagehandtool",
-              "tools/txtsearchtool",
-              "tools/visiontool",
-              "tools/weaviatevectorsearchtool",
-              "tools/websitesearchtool",
-              "tools/xmlsearchtool",
-              "tools/youtubechannelsearchtool",
-              "tools/youtubevideosearchtool"
+              "mcp/overview",
+              "mcp/stdio",
+              "mcp/sse",
+              "mcp/streamable-http",
+              "mcp/multiple-servers",
+              "mcp/security"
             ]
           },
           {
-            "group": "MCP Integration",
+            "group": "Tools",
             "pages": [
-              "mcp/crewai-mcp-integration"
-            ] 
+              "tools/overview",
+              {
+                "group": "File & Document",
+                "pages": [
+                  "tools/file-document/overview",
+                  "tools/file-document/filereadtool",
+                  "tools/file-document/filewritetool",
+                  "tools/file-document/pdfsearchtool",
+                  "tools/file-document/docxsearchtool",
+                  "tools/file-document/mdxsearchtool",
+                  "tools/file-document/xmlsearchtool",
+                  "tools/file-document/txtsearchtool",
+                  "tools/file-document/jsonsearchtool",
+                  "tools/file-document/csvsearchtool",
+                  "tools/file-document/directorysearchtool",
+                  "tools/file-document/directoryreadtool"
+                ]
+              },
+              {
+                "group": "Web Scraping & Browsing",
+                "pages": [
+                  "tools/web-scraping/overview",
+                  "tools/web-scraping/scrapewebsitetool",
+                  "tools/web-scraping/scrapeelementfromwebsitetool",
+                  "tools/web-scraping/scrapflyscrapetool",
+                  "tools/web-scraping/seleniumscrapingtool",
+                  "tools/web-scraping/scrapegraphscrapetool",
+                  "tools/web-scraping/spidertool",
+                  "tools/web-scraping/browserbaseloadtool",
+                  "tools/web-scraping/hyperbrowserloadtool",
+                  "tools/web-scraping/stagehandtool",
+                  "tools/web-scraping/firecrawlcrawlwebsitetool",
+                  "tools/web-scraping/firecrawlscrapewebsitetool",
+                  "tools/web-scraping/firecrawlsearchtool"
+                ]
+              },
+              {
+                "group": "Search & Research",
+                "pages": [
+                  "tools/search-research/overview",
+                  "tools/search-research/serperdevtool",
+                  "tools/search-research/bravesearchtool",
+                  "tools/search-research/exasearchtool",
+                  "tools/search-research/linkupsearchtool",
+                  "tools/search-research/githubsearchtool",
+                  "tools/search-research/websitesearchtool",
+                  "tools/search-research/codedocssearchtool",
+                  "tools/search-research/youtubechannelsearchtool",
+                  "tools/search-research/youtubevideosearchtool"
+                ]
+              },
+              {
+                "group": "Database & Data",
+                "pages": [
+                  "tools/database-data/overview",
+                  "tools/database-data/mysqltool",
+                  "tools/database-data/pgsearchtool",
+                  "tools/database-data/snowflakesearchtool",
+                  "tools/database-data/nl2sqltool",
+                  "tools/database-data/qdrantvectorsearchtool",
+                  "tools/database-data/weaviatevectorsearchtool"
+                ]
+              },
+              {
+                "group": "AI & Machine Learning",
+                "pages": [
+                  "tools/ai-ml/overview",
+                  "tools/ai-ml/dalletool",
+                  "tools/ai-ml/visiontool",
+                  "tools/ai-ml/aimindtool",
+                  "tools/ai-ml/llamaindextool",
+                  "tools/ai-ml/langchaintool",
+                  "tools/ai-ml/ragtool",
+                  "tools/ai-ml/codeinterpretertool"
+                ]
+              },
+              {
+                "group": "Cloud & Storage",
+                "pages": [
+                  "tools/cloud-storage/overview",
+                  "tools/cloud-storage/s3readertool",
+                  "tools/cloud-storage/s3writertool",
+                  "tools/cloud-storage/bedrockinvokeagenttool",
+                  "tools/cloud-storage/bedrockkbretriever"
+                ]
+              },
+              {
+                "group": "Automation & Integration",
+                "pages": [
+                  "tools/automation/overview",
+                  "tools/automation/apifyactorstool",
+                  "tools/automation/composiotool",
+                  "tools/automation/multiontool"
+                ]
+              }
+            ]
           },
           {
-            "group": "Agent Monitoring & Observability",
+            "group": "Observability",
             "pages": [
-              "how-to/agentops-observability",
-              "how-to/arize-phoenix-observability",
-              "how-to/langfuse-observability",
-              "how-to/langtrace-observability",
-              "how-to/mlflow-observability",
-              "how-to/openlit-observability",
-              "how-to/opik-observability",
-              "how-to/portkey-observability",
-              "how-to/weave-integration"
+              "observability/overview",
+              "observability/agentops",
+              "observability/arize-phoenix",
+              "observability/langfuse",
+              "observability/langtrace",
+              "observability/maxim",
+              "observability/mlflow",
+              "observability/openlit",
+              "observability/opik",
+              "observability/patronus-evaluation",
+              "observability/portkey",
+              "observability/weave"
             ]
           },
           {
             "group": "Learn",
             "pages": [
-              "how-to/conditional-tasks",
-              "how-to/coding-agents",
-              "how-to/create-custom-tools",
-              "how-to/custom-llm",
-              "how-to/custom-manager-agent",
-              "how-to/customizing-agents",
-              "how-to/force-tool-output-as-result",
-              "how-to/hierarchical-process",
-              "how-to/human-input-on-execution",
-              "how-to/kickoff-async",
-              "how-to/kickoff-for-each",
-              "how-to/llm-connections",
-              "how-to/multimodal-agents",
-              "how-to/replay-tasks-from-latest-crew-kickoff",
-              "how-to/sequential-process"
+              "learn/overview",
+              "learn/llm-selection-guide",
+              "learn/conditional-tasks",
+              "learn/coding-agents",
+              "learn/create-custom-tools",
+              "learn/custom-llm",
+              "learn/custom-manager-agent",
+              "learn/customizing-agents",
+              "learn/dalle-image-generation",
+              "learn/force-tool-output-as-result",
+              "learn/hierarchical-process",
+              "learn/human-input-on-execution",
+              "learn/kickoff-async",
+              "learn/kickoff-for-each",
+              "learn/llm-connections",
+              "learn/multimodal-agents",
+              "learn/replay-tasks-from-latest-crew-kickoff",
+              "learn/sequential-process",
+              "learn/using-annotations"
             ]
           },
           {
@@ -197,6 +256,16 @@
               "enterprise/introduction"
             ]
           },
+          {
+            "group": "Features",
+            "pages": [
+              "enterprise/features/tool-repository",
+              "enterprise/features/webhook-streaming",
+              "enterprise/features/traces",
+              "enterprise/features/hallucination-guardrail",
+              "enterprise/features/integrations"
+            ]
+          },
           {
             "group": "How-To Guides",
             "pages": [
@@ -204,16 +273,16 @@
               "enterprise/guides/deploy-crew",
               "enterprise/guides/kickoff-crew",
               "enterprise/guides/update-crew",
-              "enterprise/guides/use-crew-api",
-              "enterprise/guides/enable-crew-studio"
-            ]
-          },
-          {
-            "group": "Features",
-            "pages": [
-              "enterprise/features/tool-repository",
-              "enterprise/features/webhook-streaming",
-              "enterprise/features/traces"
+              "enterprise/guides/enable-crew-studio",
+              "enterprise/guides/azure-openai-setup",
+              "enterprise/guides/hubspot-trigger",
+              "enterprise/guides/react-component-export",
+              "enterprise/guides/salesforce-trigger",
+              "enterprise/guides/slack-trigger",
+              "enterprise/guides/team-management",
+              "enterprise/guides/webhook-automation",
+              "enterprise/guides/human-in-the-loop",
+              "enterprise/guides/zapier-trigger"
             ]
           },
           {
@@ -224,6 +293,21 @@
           }
         ]
       },
+      {
+        "tab": "API Reference",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "api-reference/introduction"
+            ]
+          },
+          {
+            "group": "Endpoints",
+            "openapi": "enterprise-api.yaml"
+          }
+        ]
+      },
       {
         "tab": "Examples",
         "groups": [
@@ -259,6 +343,11 @@
           "href": "https://community.crewai.com",
           "icon": "discourse"
         },
+        {
+          "anchor": "Crew GPT",
+          "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
+          "icon": "robot"
+        },
         {
           "anchor": "Get Help",
           "href": "mailto:support@crewai.com",
@@ -268,8 +357,8 @@
     }
   },
   "logo": {
-    "light": "crew_only_logo.png",
-    "dark": "crew_only_logo.png"
+    "light": "images/crew_only_logo.png",
+    "dark": "images/crew_only_logo.png"
   },
   "appearance": {
     "default": "dark",
@@ -278,7 +367,7 @@
   "navbar": {
     "links": [
       {
-        "label": "Start Free Trial",
+        "label": "Start Cloud Trial",
         "href": "https://app.crewai.com"
       }
     ],
@@ -290,6 +379,16 @@
   "search": {
     "prompt": "Search CrewAI docs"
   },
+  "api": {
+    "baseUrl": "https://your-actual-crew-name.crewai.com",
+    "auth": {
+      "method": "bearer",
+      "name": "Authorization"
+    },
+    "playground": {
+      "mode": "simple"
+    }
+  },
   "seo": {
     "indexing": "all"
   },
@@ -308,4 +407,4 @@
       "reddit": "https://www.reddit.com/r/crewAIInc/"
     }
   }
-}
+}

docs/enterprise-api.yaml

@@ -0,0 +1,434 @@
+openapi: 3.0.3
+info:
+  title: CrewAI Enterprise API
+  description: |
+    REST API for interacting with your deployed CrewAI crews on CrewAI Enterprise.
+    
+    ## Getting Started
+    
+    1. **Find your crew URL**: Get your unique crew URL from the CrewAI Enterprise dashboard
+    2. **Copy examples**: Use the code examples from each endpoint page as templates
+    3. **Replace placeholders**: Update URLs and tokens with your actual values
+    4. **Test with your tools**: Use cURL, Postman, or your preferred API client
+    
+    ## Authentication
+    
+    All API requests require a bearer token for authentication. There are two types of tokens:
+    
+    - **Bearer Token**: Organization-level token for full crew operations
+    - **User Bearer Token**: User-scoped token for individual access with limited permissions
+    
+    You can find your bearer tokens in the Status tab of your crew's detail page in the CrewAI Enterprise dashboard.
+    
+    ## Reference Documentation
+    
+    This documentation provides comprehensive examples for each endpoint:
+    
+    - **Request formats** with all required and optional parameters
+    - **Response examples** for success and error scenarios
+    - **Code samples** in multiple programming languages
+    - **Authentication patterns** with proper Bearer token usage
+    
+    Copy the examples and customize them with your actual crew URL and authentication tokens.
+    
+    ## Workflow
+    
+    1. **Discover inputs** using `GET /inputs`
+    2. **Start execution** using `POST /kickoff`  
+    3. **Monitor progress** using `GET /status/{kickoff_id}`
+  version: 1.0.0
+  contact:
+    name: CrewAI Support
+    email: support@crewai.com
+    url: https://crewai.com
+servers:
+  - url: https://your-actual-crew-name.crewai.com
+    description: Replace with your actual deployed crew URL from the CrewAI Enterprise dashboard
+  - url: https://my-travel-crew.crewai.com
+    description: Example travel planning crew (replace with your URL)
+  - url: https://content-creation-crew.crewai.com
+    description: Example content creation crew (replace with your URL)
+  - url: https://research-assistant-crew.crewai.com
+    description: Example research assistant crew (replace with your URL)
+security:
+  - BearerAuth: []
+paths:
+  /inputs:
+    get:
+      summary: Get Required Inputs
+      description: |
+        **📋 Reference Example Only** - *This shows the request format. To test with your actual crew, copy the cURL example and replace the URL + token with your real values.*
+        
+        Retrieves the list of all required input parameters that your crew expects for execution.
+        Use this endpoint to discover what inputs you need to provide when starting a crew execution.
+      operationId: getRequiredInputs
+      responses:
+        '200':
+          description: Successfully retrieved required inputs
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  inputs:
+                    type: array
+                    items:
+                      type: string
+                    description: Array of required input parameter names
+                    example: ["budget", "interests", "duration", "age"]
+              examples:
+                travel_crew:
+                  summary: Travel planning crew inputs
+                  value:
+                    inputs: ["budget", "interests", "duration", "age"]
+                outreach_crew:
+                  summary: Outreach crew inputs  
+                  value:
+                    inputs: ["name", "title", "company", "industry", "our_product", "linkedin_url"]
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '404':
+          $ref: '#/components/responses/NotFoundError'
+        '500':
+          $ref: '#/components/responses/ServerError'
+
+  /kickoff:
+    post:
+      summary: Start Crew Execution
+      description: |
+        **📋 Reference Example Only** - *This shows the request format. To test with your actual crew, copy the cURL example and replace the URL + token with your real values.*
+        
+        Initiates a new crew execution with the provided inputs. Returns a kickoff ID that can be used 
+        to track the execution progress and retrieve results.
+        
+        Crew executions can take anywhere from seconds to minutes depending on their complexity.
+        Consider using webhooks for real-time notifications or implement polling with the status endpoint.
+      operationId: startCrewExecution
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - inputs
+              properties:
+                inputs:
+                  type: object
+                  description: Key-value pairs of all required inputs for your crew
+                  additionalProperties:
+                    type: string
+                  example:
+                    budget: "1000 USD"
+                    interests: "games, tech, ai, relaxing hikes, amazing food"
+                    duration: "7 days"
+                    age: "35"
+                meta:
+                  type: object
+                  description: Additional metadata to pass to the crew
+                  additionalProperties: true
+                  example:
+                    requestId: "user-request-12345"
+                    source: "mobile-app"
+                taskWebhookUrl:
+                  type: string
+                  format: uri
+                  description: Callback URL executed after each task completion
+                  example: "https://your-server.com/webhooks/task"
+                stepWebhookUrl:
+                  type: string
+                  format: uri
+                  description: Callback URL executed after each agent thought/action
+                  example: "https://your-server.com/webhooks/step"
+                crewWebhookUrl:
+                  type: string
+                  format: uri
+                  description: Callback URL executed when the crew execution completes
+                  example: "https://your-server.com/webhooks/crew"
+            examples:
+              travel_planning:
+                summary: Travel planning crew
+                value:
+                  inputs:
+                    budget: "1000 USD"
+                    interests: "games, tech, ai, relaxing hikes, amazing food"
+                    duration: "7 days" 
+                    age: "35"
+                  meta:
+                    requestId: "travel-req-123"
+                    source: "web-app"
+              outreach_campaign:
+                summary: Outreach crew with webhooks
+                value:
+                  inputs:
+                    name: "John Smith"
+                    title: "CTO"
+                    company: "TechCorp"
+                    industry: "Software"
+                    our_product: "AI Development Platform"
+                    linkedin_url: "https://linkedin.com/in/johnsmith"
+                  taskWebhookUrl: "https://api.example.com/webhooks/task"
+                  crewWebhookUrl: "https://api.example.com/webhooks/crew"
+      responses:
+        '200':
+          description: Crew execution started successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  kickoff_id:
+                    type: string
+                    format: uuid
+                    description: Unique identifier for tracking this execution
+                    example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+        '400':
+          description: Invalid request body or missing required inputs
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '422':
+          description: Validation error - ensure all required inputs are provided
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationError'
+        '500':
+          $ref: '#/components/responses/ServerError'
+
+  /status/{kickoff_id}:
+    get:
+      summary: Get Execution Status
+      description: |
+        **📋 Reference Example Only** - *This shows the request format. To test with your actual crew, copy the cURL example and replace the URL + token with your real values.*
+        
+        Retrieves the current status and results of a crew execution using its kickoff ID.
+        
+        The response structure varies depending on the execution state:
+        - **running**: Execution in progress with current task info
+        - **completed**: Execution finished with full results
+        - **error**: Execution failed with error details
+      operationId: getExecutionStatus
+      parameters:
+        - name: kickoff_id
+          in: path
+          required: true
+          description: The kickoff ID returned from the /kickoff endpoint
+          schema:
+            type: string
+            format: uuid
+            example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+      responses:
+        '200':
+          description: Successfully retrieved execution status
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ExecutionRunning'
+                  - $ref: '#/components/schemas/ExecutionCompleted'
+                  - $ref: '#/components/schemas/ExecutionError'
+              examples:
+                running:
+                  summary: Execution in progress
+                  value:
+                    status: "running"
+                    current_task: "research_task"
+                    progress:
+                      completed_tasks: 1
+                      total_tasks: 3
+                completed:
+                  summary: Execution completed successfully
+                  value:
+                    status: "completed"
+                    result:
+                      output: "Comprehensive travel itinerary for 7 days in Japan focusing on tech culture..."
+                      tasks:
+                        - task_id: "research_task"
+                          output: "Research findings on tech destinations in Japan..."
+                          agent: "Travel Researcher"
+                          execution_time: 45.2
+                        - task_id: "planning_task"
+                          output: "7-day detailed itinerary with activities and recommendations..."
+                          agent: "Trip Planner"
+                          execution_time: 62.8
+                    execution_time: 108.5
+                error:
+                  summary: Execution failed
+                  value:
+                    status: "error"
+                    error: "Task execution failed: Invalid API key for external service"
+                    execution_time: 23.1
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '404':
+          description: Kickoff ID not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: "Execution not found"
+                message: "No execution found with ID: abcd1234-5678-90ef-ghij-klmnopqrstuv"
+        '500':
+          $ref: '#/components/responses/ServerError'
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      description: |
+        **📋 Reference Documentation** - *The tokens shown in examples are placeholders for reference only.*
+        
+        Use your actual Bearer Token or User Bearer Token from the CrewAI Enterprise dashboard for real API calls.
+        
+        **Bearer Token**: Organization-level access for full crew operations
+        **User Bearer Token**: User-scoped access with limited permissions
+
+  schemas:
+    ExecutionRunning:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["running"]
+          example: "running"
+        current_task:
+          type: string
+          description: Name of the currently executing task
+          example: "research_task"
+        progress:
+          type: object
+          properties:
+            completed_tasks:
+              type: integer
+              description: Number of completed tasks
+              example: 1
+            total_tasks:
+              type: integer  
+              description: Total number of tasks in the crew
+              example: 3
+
+    ExecutionCompleted:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["completed"]
+          example: "completed"
+        result:
+          type: object
+          properties:
+            output:
+              type: string
+              description: Final output from the crew execution
+              example: "Comprehensive travel itinerary..."
+            tasks:
+              type: array
+              items:
+                $ref: '#/components/schemas/TaskResult'
+        execution_time:
+          type: number
+          description: Total execution time in seconds
+          example: 108.5
+
+    ExecutionError:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["error"]
+          example: "error"
+        error:
+          type: string
+          description: Error message describing what went wrong
+          example: "Task execution failed: Invalid API key"
+        execution_time:
+          type: number
+          description: Time until error occurred in seconds
+          example: 23.1
+
+    TaskResult:
+      type: object
+      properties:
+        task_id:
+          type: string
+          description: Unique identifier for the task
+          example: "research_task"
+        output:
+          type: string
+          description: Output generated by this task
+          example: "Research findings..."
+        agent:
+          type: string
+          description: Name of the agent that executed this task
+          example: "Travel Researcher"
+        execution_time:
+          type: number
+          description: Time taken to execute this task in seconds
+          example: 45.2
+
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+          description: Error type or title
+          example: "Authentication Error"
+        message:
+          type: string
+          description: Detailed error message
+          example: "Invalid bearer token provided"
+
+    ValidationError:
+      type: object
+      properties:
+        error:
+          type: string
+          example: "Validation Error"
+        message:
+          type: string
+          example: "Missing required inputs"
+        details:
+          type: object
+          properties:
+            missing_inputs:
+              type: array
+              items:
+                type: string
+              example: ["budget", "interests"]
+
+  responses:
+    UnauthorizedError:
+      description: Authentication failed - check your bearer token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: "Unauthorized"
+            message: "Invalid or missing bearer token"
+
+    NotFoundError:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: "Not Found"
+            message: "The requested resource was not found"
+
+    ServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: "Internal Server Error" 
+            message: "An unexpected error occurred" 

docs/enterprise/features/hallucination-guardrail.mdx

@@ -0,0 +1,250 @@
+---
+title: Hallucination Guardrail
+description: "Prevent and detect AI hallucinations in your CrewAI tasks"
+icon: "shield-check"
+---
+
+## Overview
+
+The Hallucination Guardrail is an enterprise feature that validates AI-generated content to ensure it's grounded in facts and doesn't contain hallucinations. It analyzes task outputs against reference context and provides detailed feedback when potentially hallucinated content is detected.
+
+## What are Hallucinations?
+
+AI hallucinations occur when language models generate content that appears plausible but is factually incorrect or not supported by the provided context. The Hallucination Guardrail helps prevent these issues by:
+
+- Comparing outputs against reference context
+- Evaluating faithfulness to source material
+- Providing detailed feedback on problematic content
+- Supporting custom thresholds for validation strictness
+
+## Basic Usage
+
+### Setting Up the Guardrail
+
+```python
+from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
+from crewai import LLM
+
+# Basic usage - will use task's expected_output as context
+guardrail = HallucinationGuardrail(
+    llm=LLM(model="gpt-4o-mini")
+)
+
+# With explicit reference context
+context_guardrail = HallucinationGuardrail(
+    context="AI helps with various tasks including analysis and generation.",
+    llm=LLM(model="gpt-4o-mini")
+)
+```
+
+### Adding to Tasks
+
+```python
+from crewai import Task
+
+# Create your task with the guardrail
+task = Task(
+    description="Write a summary about AI capabilities",
+    expected_output="A factual summary based on the provided context",
+    agent=my_agent,
+    guardrail=guardrail  # Add the guardrail to validate output
+)
+```
+
+## Advanced Configuration
+
+### Custom Threshold Validation
+
+For stricter validation, you can set a custom faithfulness threshold (0-10 scale):
+
+```python
+# Strict guardrail requiring high faithfulness score
+strict_guardrail = HallucinationGuardrail(
+    context="Quantum computing uses qubits that exist in superposition states.",
+    llm=LLM(model="gpt-4o-mini"),
+    threshold=8.0  # Requires score >= 8 to pass validation
+)
+```
+
+### Including Tool Response Context
+
+When your task uses tools, you can include tool responses for more accurate validation:
+
+```python
+# Guardrail with tool response context
+weather_guardrail = HallucinationGuardrail(
+    context="Current weather information for the requested location",
+    llm=LLM(model="gpt-4o-mini"),
+    tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies"
+)
+```
+
+## How It Works
+
+### Validation Process
+
+1. **Context Analysis**: The guardrail compares task output against the provided reference context
+2. **Faithfulness Scoring**: Uses an internal evaluator to assign a faithfulness score (0-10)
+3. **Verdict Determination**: Determines if content is faithful or contains hallucinations
+4. **Threshold Checking**: If a custom threshold is set, validates against that score
+5. **Feedback Generation**: Provides detailed reasons when validation fails
+
+### Validation Logic
+
+- **Default Mode**: Uses verdict-based validation (FAITHFUL vs HALLUCINATED)
+- **Threshold Mode**: Requires faithfulness score to meet or exceed the specified threshold
+- **Error Handling**: Gracefully handles evaluation errors and provides informative feedback
+
+## Guardrail Results
+
+The guardrail returns structured results indicating validation status:
+
+```python
+# Example of guardrail result structure
+{
+    "valid": False,
+    "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context."
+}
+```
+
+### Result Properties
+
+- **valid**: Boolean indicating whether the output passed validation
+- **feedback**: Detailed explanation when validation fails, including:
+  - Faithfulness score
+  - Verdict classification
+  - Specific reasons for failure
+
+## Integration with Task System
+
+### Automatic Validation
+
+When a guardrail is added to a task, it automatically validates the output before the task is marked as complete:
+
+```python
+# Task output validation flow
+task_output = agent.execute_task(task)
+validation_result = guardrail(task_output)
+
+if validation_result.valid:
+    # Task completes successfully
+    return task_output
+else:
+    # Task fails with validation feedback
+    raise ValidationError(validation_result.feedback)
+```
+
+### Event Tracking
+
+The guardrail integrates with CrewAI's event system to provide observability:
+
+- **Validation Started**: When guardrail evaluation begins
+- **Validation Completed**: When evaluation finishes with results
+- **Validation Failed**: When technical errors occur during evaluation
+
+## Best Practices
+
+### Context Guidelines
+
+<Steps>
+  <Step title="Provide Comprehensive Context">
+    Include all relevant factual information that the AI should base its output on:
+
+    ```python
+    context = """
+    Company XYZ was founded in 2020 and specializes in renewable energy solutions.
+    They have 150 employees and generated $50M revenue in 2023.
+    Their main products include solar panels and wind turbines.
+    """
+    ```
+  </Step>
+
+  <Step title="Keep Context Relevant">
+    Only include information directly related to the task to avoid confusion:
+
+    ```python
+    # Good: Focused context
+    context = "The current weather in New York is 18°C with light rain."
+
+    # Avoid: Unrelated information
+    context = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
+    ```
+  </Step>
+
+  <Step title="Update Context Regularly">
+    Ensure your reference context reflects current, accurate information.
+  </Step>
+</Steps>
+
+### Threshold Selection
+
+<Steps>
+  <Step title="Start with Default Validation">
+    Begin without custom thresholds to understand baseline performance.
+  </Step>
+
+  <Step title="Adjust Based on Requirements">
+    - **High-stakes content**: Use threshold 8-10 for maximum accuracy
+    - **General content**: Use threshold 6-7 for balanced validation
+    - **Creative content**: Use threshold 4-5 or default verdict-based validation
+  </Step>
+
+  <Step title="Monitor and Iterate">
+    Track validation results and adjust thresholds based on false positives/negatives.
+  </Step>
+</Steps>
+
+## Performance Considerations
+
+### Impact on Execution Time
+
+- **Validation Overhead**: Each guardrail adds ~1-3 seconds per task
+- **LLM Efficiency**: Choose efficient models for evaluation (e.g., gpt-4o-mini)
+
+### Cost Optimization
+
+- **Model Selection**: Use smaller, efficient models for guardrail evaluation
+- **Context Size**: Keep reference context concise but comprehensive
+- **Caching**: Consider caching validation results for repeated content
+
+## Troubleshooting
+
+<Accordion title="Validation Always Fails">
+  **Possible Causes:**
+  - Context is too restrictive or unrelated to task output
+  - Threshold is set too high for the content type
+  - Reference context contains outdated information
+
+  **Solutions:**
+  - Review and update context to match task requirements
+  - Lower threshold or use default verdict-based validation
+  - Ensure context is current and accurate
+</Accordion>
+
+<Accordion title="False Positives (Valid Content Marked Invalid)">
+  **Possible Causes:**
+  - Threshold too high for creative or interpretive tasks
+  - Context doesn't cover all valid aspects of the output
+  - Evaluation model being overly conservative
+
+  **Solutions:**
+  - Lower threshold or use default validation
+  - Expand context to include broader acceptable content
+  - Test with different evaluation models
+</Accordion>
+
+<Accordion title="Evaluation Errors">
+  **Possible Causes:**
+  - Network connectivity issues
+  - LLM model unavailable or rate limited
+  - Malformed task output or context
+
+  **Solutions:**
+  - Check network connectivity and LLM service status
+  - Implement retry logic for transient failures
+  - Validate task output format before guardrail evaluation
+</Accordion>
+
+<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
+  Contact our support team for assistance with hallucination guardrail configuration or troubleshooting.
+</Card>

docs/enterprise/features/integrations.mdx

@@ -0,0 +1,185 @@
+---
+title: Integrations
+description: "Connected applications for your agents to take actions."
+icon: "plug"
+---
+
+## Overview
+
+Enable your agents to authenticate with any OAuth enabled provider and take actions. From Salesforce and HubSpot to Google and GitHub, we've got you covered with 16+ integrated services.
+
+<Frame>
+  ![Integrations](/images/enterprise/crew_connectors.png)
+</Frame>
+
+## Supported Integrations
+
+### **Communication & Collaboration**
+- **Gmail** - Manage emails and drafts
+- **Slack** - Workspace notifications and alerts
+- **Microsoft** - Office 365 and Teams integration
+
+### **Project Management**
+- **Jira** - Issue tracking and project management
+- **ClickUp** - Task and productivity management
+- **Asana** - Team task and project coordination
+- **Notion** - Page and database management
+- **Linear** - Software project and bug tracking
+- **GitHub** - Repository and issue management
+
+### **Customer Relationship Management**
+- **Salesforce** - CRM account and opportunity management
+- **HubSpot** - Sales pipeline and contact management
+- **Zendesk** - Customer support ticket management
+
+### **Business & Finance**
+- **Stripe** - Payment processing and customer management
+- **Shopify** - E-commerce store and product management
+
+### **Productivity & Storage**
+- **Google Sheets** - Spreadsheet data synchronization
+- **Google Calendar** - Event and schedule management
+- **Box** - File storage and document management
+
+and more to come!
+
+## Prerequisites
+
+Before using Authentication Integrations, ensure you have:
+
+- A [CrewAI Enterprise](https://app.crewai.com) account. You can get started with a free trial.
+
+
+## Setting Up Integrations
+
+### 1. Connect Your Account
+
+1. Navigate to [CrewAI Enterprise](https://app.crewai.com)
+2. Go to **Integrations** tab - https://app.crewai.com/crewai_plus/connectors
+3. Click **Connect** on your desired service from the Authentication Integrations section
+4. Complete the OAuth authentication flow
+5. Grant necessary permissions for your use case
+6. Get your Enterprise Token from your [CrewAI Enterprise](https://app.crewai.com) account page - https://app.crewai.com/crewai_plus/settings/account
+
+<Frame>
+  ![Integrations](/images/enterprise/enterprise_action_auth_token.png)
+</Frame>
+
+### 2. Install Integration Tools
+
+All you need is the latest version of `crewai-tools` package.
+
+```bash
+uv add crewai-tools
+```
+
+## Usage Examples
+
+### Basic Usage
+<Tip>
+  All the services you are authenticated into will be available as tools. So all you need to do is add the `CrewaiEnterpriseTools` to your agent and you are good to go.
+</Tip>
+
+```python
+from crewai import Agent, Task, Crew
+from crewai_tools import CrewaiEnterpriseTools
+
+# Get enterprise tools (Gmail tool will be included)
+enterprise_tools = CrewaiEnterpriseTools(
+    enterprise_token="your_enterprise_token"
+)
+# print the tools
+print(enterprise_tools)
+
+# Create an agent with Gmail capabilities
+email_agent = Agent(
+    role="Email Manager",
+    goal="Manage and organize email communications",
+    backstory="An AI assistant specialized in email management and communication.",
+    tools=[enterprise_tools]
+)
+
+# Task to send an email
+email_task = Task(
+    description="Draft and send a follow-up email to john@example.com about the project update",
+    agent=email_agent,
+    expected_output="Confirmation that email was sent successfully"
+)
+
+# Run the task
+crew = Crew(
+    agents=[email_agent],
+    tasks=[email_task]
+)
+
+# Run the crew
+crew.kickoff()
+```
+
+### Filtering Tools
+
+```python
+from crewai_tools import CrewaiEnterpriseTools
+
+enterprise_tools = CrewaiEnterpriseTools(
+    actions_list=["gmail_find_email"] # only gmail_find_email tool will be available
+)
+gmail_tool = enterprise_tools[0]
+
+gmail_agent = Agent(
+    role="Gmail Manager",
+    goal="Manage gmail communications and notifications",
+    backstory="An AI assistant that helps coordinate gmail communications.",
+    tools=[gmail_tool]
+)
+
+notification_task = Task(
+    description="Find the email from john@example.com",
+    agent=gmail_agent,
+    expected_output="Email found from john@example.com"
+)
+
+# Run the task
+crew = Crew(
+    agents=[slack_agent],
+    tasks=[notification_task]
+)
+```
+
+## Best Practices
+
+### Security
+- **Principle of Least Privilege**: Only grant the minimum permissions required for your agents' tasks
+- **Regular Audits**: Periodically review connected integrations and their permissions
+- **Secure Credentials**: Never hardcode credentials; use CrewAI's secure authentication flow
+
+
+### Filtering Tools
+On a deployed crew, you can specify which actions are avialbel for each integration from the settings page of the service you connected to.
+
+<Frame>
+  ![Integrations](/images/enterprise/filtering_enterprise_action_tools.png)
+</Frame>
+
+
+### Scoped Deployments for multi user organizations
+You can deploy your crew and scope each integration to a specific user. For example, a crew that connects to google can use a specific user's gmail account.
+
+<Tip>
+  This is useful for multi user organizations where you want to scope the integration to a specific user.
+</Tip>
+
+
+Use the `user_bearer_token` to scope the integration to a specific user so that when the crew is kicked off, it will use the user's bearer token to authenticate with the integration. If user is not logged in, then the crew will not use any connected integrations. Use the default bearer token to authenticate with the integrations thats deployed with the crew.
+
+<Frame>
+  ![Integrations](/images/enterprise/user_bearer_token.png)
+</Frame>
+
+
+
+### Getting Help
+
+<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
+  Contact our support team for assistance with integration setup or troubleshooting.
+</Card>

docs/enterprise/features/tool-repository.mdx

@@ -21,6 +21,7 @@ Before using the Tool Repository, ensure you have:
 
 - A [CrewAI Enterprise](https://app.crewai.com) account
 - [CrewAI CLI](https://docs.crewai.com/concepts/cli#cli) installed
+- uv>=0.5.0 installed. Check out [how to upgrade](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv)
 - [Git](https://git-scm.com) installed and configured
 - Access permissions to publish or install tools in your CrewAI Enterprise organization
 

docs/enterprise/guides/azure-openai-setup.mdx

@@ -0,0 +1,51 @@
+---
+title: "Azure OpenAI Setup"
+description: "Configure Azure OpenAI with Crew Studio for enterprise LLM connections"
+icon: "microsoft"
+---
+
+This guide walks you through connecting Azure OpenAI with Crew Studio for seamless enterprise AI operations.
+
+## Setup Process
+
+<Steps>
+    <Step title="Access Azure OpenAI Studio">
+        1. In Azure, go to `Azure AI Services > select your deployment > open Azure OpenAI Studio`.
+        2. On the left menu, click `Deployments`. If you don't have one, create a deployment with your desired model.
+        3. Once created, select your deployment and locate the `Target URI` and `Key` on the right side of the page. Keep this page open, as you'll need this information.
+            <Frame>
+                <img src="/images/enterprise/azure-openai-studio.png" alt="Azure OpenAI Studio" />
+            </Frame>
+    </Step>
+
+    <Step title="Configure CrewAI Enterprise Connection">
+        4. In another tab, open `CrewAI Enterprise > LLM Connections`. Name your LLM Connection, select Azure as the provider, and choose the same model you selected in Azure.
+        5. On the same page, add environment variables from step 3:
+            - One named `AZURE_DEPLOYMENT_TARGET_URL` (using the Target URI). The URL should look like this: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview
+            - Another named `AZURE_API_KEY` (using the Key).
+        6. Click `Add Connection` to save your LLM Connection.
+    </Step>
+
+    <Step title="Set Default Configuration">
+        7. In `CrewAI Enterprise > Settings > Defaults > Crew Studio LLM Settings`, set the new LLM Connection and model as defaults.
+    </Step>
+
+    <Step title="Configure Network Access">
+        8. Ensure network access settings:
+            - In Azure, go to `Azure OpenAI > select your deployment`.
+            - Navigate to `Resource Management > Networking`.
+            - Ensure that `Allow access from all networks` is enabled. If this setting is restricted, CrewAI may be blocked from accessing your Azure OpenAI endpoint.
+    </Step>
+</Steps>
+
+## Verification
+
+You're all set! Crew Studio will now use your Azure OpenAI connection. Test the connection by creating a simple crew or task to ensure everything is working properly.
+
+## Troubleshooting
+
+If you encounter issues:
+- Verify the Target URI format matches the expected pattern
+- Check that the API key is correct and has proper permissions
+- Ensure network access is configured to allow CrewAI connections
+- Confirm the deployment model matches what you've configured in CrewAI 

docs/enterprise/guides/deploy-crew.mdx

@@ -1,41 +1,41 @@
 ---
 title: "Deploy Crew"
-description: "Deploy your local CrewAI project to the Enterprise platform"
-icon: "cloud-arrow-up"
+description: "Deploying a Crew on CrewAI Enterprise"
+icon: "rocket"
 ---
 
-## Overview
-
-This guide will walk you through the process of deploying your locally developed CrewAI project to the CrewAI Enterprise platform, 
-transforming it into a production-ready API endpoint.
-
-## Option 1: CLI Deployment
-
-<iframe 
-    width="100%"
-    height="400"
-    src="https://www.youtube.com/embed/3EqSV-CYDZA" 
-    title="Deploying a Crew to CrewAI Enterprise" 
-    frameborder="0"
-    style={{ borderRadius: '10px' }}
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-    allowfullscreen
-></iframe>
-
-### Prerequisites
-
-Before starting the deployment process, make sure you have:
-
-- A CrewAI project built locally ([follow our quickstart guide](/quickstart) if you haven't created one yet)
-- Your code pushed to a GitHub repository
-- The latest version of the CrewAI CLI installed (`uv tool install crewai`)
-
 <Note>
-For a quick reference project, you can clone our example repository at [github.com/tonykipkemboi/crewai-latest-ai-development](https://github.com/tonykipkemboi/crewai-latest-ai-development).
+After creating a crew locally or through Crew Studio, the next step is deploying it to the CrewAI Enterprise platform. This guide covers multiple deployment methods to help you choose the best approach for your workflow.
 </Note>
 
+## Prerequisites
+
+<CardGroup cols={2}>
+  <Card title="Crew Ready for Deployment" icon="users">
+    You should have a working crew either built locally or created through Crew Studio
+  </Card>
+  <Card title="GitHub Repository" icon="github">
+    Your crew code should be in a GitHub repository (for GitHub integration method)
+  </Card>
+</CardGroup>
+
+## Option 1: Deploy Using CrewAI CLI
+
+The CLI provides the fastest way to deploy locally developed crews to the Enterprise platform.
 
 <Steps>
+  <Step title="Install CrewAI CLI">
+    If you haven't already, install the CrewAI CLI:
+
+    ```bash
+    pip install crewai[tools]
+    ```
+
+    <Tip>
+    The CLI comes with the main CrewAI package, but the `[tools]` extra ensures you have all deployment dependencies.
+    </Tip>
+
+  </Step>
 
   <Step title="Authenticate with the Enterprise Platform">
     First, you need to authenticate your CLI with the CrewAI Enterprise platform:
@@ -189,6 +189,62 @@ You can also deploy your crews directly through the CrewAI Enterprise web interf
 
 </Steps>
 
+## ⚠️ Environment Variable Security Requirements
+
+<Warning>
+**Important**: CrewAI Enterprise has security restrictions on environment variable names that can cause deployment failures if not followed.
+</Warning>
+
+### Blocked Environment Variable Patterns
+
+For security reasons, the following environment variable naming patterns are **automatically filtered** and will cause deployment issues:
+
+**Blocked Patterns:**
+- Variables ending with `_TOKEN` (e.g., `MY_API_TOKEN`)
+- Variables ending with `_PASSWORD` (e.g., `DB_PASSWORD`) 
+- Variables ending with `_SECRET` (e.g., `API_SECRET`)
+- Variables ending with `_KEY` in certain contexts
+
+**Specific Blocked Variables:**
+- `GITHUB_USER`, `GITHUB_TOKEN`
+- `AWS_REGION`, `AWS_DEFAULT_REGION` 
+- Various internal CrewAI system variables
+
+### Allowed Exceptions
+
+Some variables are explicitly allowed despite matching blocked patterns:
+- `AZURE_AD_TOKEN`
+- `AZURE_OPENAI_AD_TOKEN` 
+- `ENTERPRISE_ACTION_TOKEN`
+- `CREWAI_ENTEPRISE_TOOLS_TOKEN`
+
+### How to Fix Naming Issues
+
+If your deployment fails due to environment variable restrictions:
+
+```bash
+# ❌ These will cause deployment failures
+OPENAI_TOKEN=sk-...
+DATABASE_PASSWORD=mypassword
+API_SECRET=secret123
+
+# ✅ Use these naming patterns instead  
+OPENAI_API_KEY=sk-...
+DATABASE_CREDENTIALS=mypassword
+API_CONFIG=secret123
+```
+
+### Best Practices
+
+1. **Use standard naming conventions**: `PROVIDER_API_KEY` instead of `PROVIDER_TOKEN`
+2. **Test locally first**: Ensure your crew works with the renamed variables
+3. **Update your code**: Change any references to the old variable names
+4. **Document changes**: Keep track of renamed variables for your team
+
+<Tip>
+If you encounter deployment failures with cryptic environment variable errors, check your variable names against these patterns first.
+</Tip>
+
 ### Interact with Your Deployed Crew
 
 Once deployment is complete, you can access your crew through:

docs/enterprise/guides/hubspot-trigger.mdx

@@ -0,0 +1,53 @@
+---
+title: "HubSpot Trigger"
+description: "Trigger CrewAI crews directly from HubSpot Workflows"
+icon: "hubspot"
+---
+
+This guide provides a step-by-step process to set up HubSpot triggers for CrewAI Enterprise, enabling you to initiate crews directly from HubSpot Workflows.
+
+## Prerequisites
+
+- A CrewAI Enterprise account
+- A HubSpot account with the [HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows) feature
+
+## Setup Steps
+
+<Steps>
+    <Step title="Connect your HubSpot account with CrewAI Enterprise">
+        - Log in to your `CrewAI Enterprise account > Triggers`
+        - Select `HubSpot` from the list of available triggers
+        - Choose the HubSpot account you want to connect with CrewAI Enterprise
+        - Follow the on-screen prompts to authorize CrewAI Enterprise access to your HubSpot account
+        - A confirmation message will appear once HubSpot is successfully connected with CrewAI Enterprise
+    </Step>
+    <Step title="Create a HubSpot Workflow">
+        - Log in to your `HubSpot account > Automations > Workflows > New workflow`
+        - Select the workflow type that fits your needs (e.g., Start from scratch)
+        - In the workflow builder, click the Plus (+) icon to add a new action.
+        - Choose `Integrated apps > CrewAI > Kickoff a Crew`.
+        - Select the Crew you want to initiate.
+        - Click `Save` to add the action to your workflow
+        <Frame>
+            <img src="/images/enterprise/hubspot-workflow-1.png" alt="HubSpot Workflow 1" />
+        </Frame>
+    </Step>
+    <Step title="Use Crew results with other actions">
+        - After the Kickoff a Crew step, click the Plus (+) icon to add a new action.
+        - For example, to send an internal email notification, choose `Communications > Send internal email notification`
+        - In the Body field, click `Insert data`, select `View properties or action outputs from > Action outputs > Crew Result` to include Crew data in the email
+            <Frame>
+                <img src="/images/enterprise/hubspot-workflow-2.png" alt="HubSpot Workflow 2" />
+            </Frame>
+        - Configure any additional actions as needed
+        - Review your workflow steps to ensure everything is set up correctly
+        - Activate the workflow
+            <Frame>
+                <img src="/images/enterprise/hubspot-workflow-3.png" alt="HubSpot Workflow 3" />
+            </Frame>
+    </Step>
+</Steps>
+
+## Additional Resources
+
+For more detailed information on available actions and customization options, refer to the [HubSpot Workflows Documentation](https://knowledge.hubspot.com/workflows/create-workflows). 

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/enterprise/guides/react-component-export.mdx

@@ -0,0 +1,103 @@
+---
+title: "React Component Export"
+description: "Learn how to export and integrate CrewAI Enterprise React components into your applications"
+icon: "react"
+---
+
+This guide explains how to export CrewAI Enterprise crews as React components and integrate them into your own applications.
+
+## Exporting a React Component
+
+<Steps>
+    <Step title="Export the Component">
+        Click on the ellipsis (three dots on the right of your deployed crew) and select the export option and save the file locally. We will be using `CrewLead.jsx` for our example.
+
+        <Frame>
+            <img src="/images/enterprise/export-react-component.png" alt="Export React Component" />
+        </Frame>
+    </Step>
+</Steps>
+
+## Setting Up Your React Environment
+
+To run this React component locally, you'll need to set up a React development environment and integrate this component into a React project.
+
+<Steps>
+    <Step title="Install Node.js">
+        - Download and install Node.js from the official website: https://nodejs.org/
+        - Choose the LTS (Long Term Support) version for stability.
+    </Step>
+
+    <Step title="Create a new React project">
+        - Open Command Prompt or PowerShell
+        - Navigate to the directory where you want to create your project
+        - Run the following command to create a new React project:
+
+            ```bash
+            npx create-react-app my-crew-app
+            ```
+        - Change into the project directory:
+        
+            ```bash
+            cd my-crew-app
+            ```
+    </Step>
+
+    <Step title="Install necessary dependencies">
+        ```bash
+        npm install react-dom
+        ```
+    </Step>
+
+    <Step title="Create the CrewLead component">
+        - Move the downloaded file `CrewLead.jsx` into the `src` folder of your project,
+    </Step>
+
+    <Step title="Modify your App.js to use the CrewLead component">
+        - Open `src/App.js`
+        - Replace its contents with something like this:
+
+        ```jsx
+        import React from 'react';
+        import CrewLead from './CrewLead';
+
+        function App() {
+            return (
+                <div className="App">
+                    <CrewLead baseUrl="YOUR_API_BASE_URL" bearerToken="YOUR_BEARER_TOKEN" />
+                </div>
+            );
+        }
+
+        export default App;
+        ```
+        - Replace `YOUR_API_BASE_URL` and `YOUR_BEARER_TOKEN` with the actual values for your API.
+    </Step>
+
+    <Step title="Start the development server">
+        - In your project directory, run:
+        
+            ```bash
+            npm start
+            ```
+        - This will start the development server, and your default web browser should open automatically to http://localhost:3000, where you'll see your React app running.
+    </Step>
+</Steps>
+
+## Customization
+
+You can then customise the `CrewLead.jsx` to add color, title etc
+
+<Frame>
+    <img src="/images/enterprise/customise-react-component.png" alt="Customise React Component" />
+</Frame>
+<Frame>
+    <img src="/images/enterprise/customise-react-component-2.png" alt="Customise React Component" />
+</Frame>
+
+## Next Steps
+
+- Customize the component styling to match your application's design
+- Add additional props for configuration
+- Integrate with your application's state management
+- Add error handling and loading states 

docs/enterprise/guides/salesforce-trigger.mdx

@@ -0,0 +1,44 @@
+---
+title: "Salesforce Trigger"
+description: "Trigger CrewAI crews from Salesforce workflows for CRM automation"
+icon: "salesforce"
+---
+
+CrewAI Enterprise can be triggered from Salesforce to automate customer relationship management workflows and enhance your sales operations.
+
+## Overview
+
+Salesforce is a leading customer relationship management (CRM) platform that helps businesses streamline their sales, service, and marketing operations. By setting up CrewAI triggers from Salesforce, you can:
+
+- Automate lead scoring and qualification
+- Generate personalized sales materials
+- Enhance customer service with AI-powered responses
+- Streamline data analysis and reporting
+
+## Demo
+
+<Frame>
+    <iframe width="100%" height="400" src="https://www.youtube.com/embed/oJunVqjjfu4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+</Frame>
+
+## Getting Started
+
+To set up Salesforce triggers:
+
+1. **Contact Support**: Reach out to CrewAI Enterprise support for assistance with Salesforce trigger setup
+2. **Review Requirements**: Ensure you have the necessary Salesforce permissions and API access
+3. **Configure Connection**: Work with the support team to establish the connection between CrewAI and your Salesforce instance
+4. **Test Triggers**: Verify the triggers work correctly with your specific use cases
+
+## Use Cases
+
+Common Salesforce + CrewAI trigger scenarios include:
+
+- **Lead Processing**: Automatically analyze and score incoming leads
+- **Proposal Generation**: Create customized proposals based on opportunity data
+- **Customer Insights**: Generate analysis reports from customer interaction history
+- **Follow-up Automation**: Create personalized follow-up messages and recommendations
+
+## Next Steps
+
+For detailed setup instructions and advanced configuration options, please contact CrewAI Enterprise support who can provide tailored guidance for your specific Salesforce environment and business needs. 

docs/enterprise/guides/slack-trigger.mdx

@@ -0,0 +1,61 @@
+---
+title: "Slack Trigger"
+description: "Trigger CrewAI crews directly from Slack using slash commands"
+icon: "slack"
+---
+
+This guide explains how to start a crew directly from Slack using CrewAI triggers.
+
+## Prerequisites
+
+- CrewAI Slack trigger installed and connected to your Slack workspace
+- At least one crew configured in CrewAI
+
+## Setup Steps
+
+<Steps>
+    <Step title="Ensure the CrewAI Slack trigger is set up">
+        In the CrewAI dashboard, navigate to the **Triggers** section.
+
+        <Frame>
+            <img src="/images/enterprise/slack-integration.png" alt="CrewAI Slack Integration" />
+        </Frame>
+
+        Verify that Slack is listed and is connected.
+    </Step>
+    <Step title="Open your Slack channel">
+        - Navigate to the channel where you want to kickoff the crew.
+        - Type the slash command "**/kickoff**" to initiate the crew kickoff process.
+        - You should see a  "**Kickoff crew**" appear as you type:
+            <Frame>
+                <img src="/images/enterprise/kickoff-slack-crew.png" alt="Kickoff crew" />
+            </Frame>
+        - Press Enter or select the "**Kickoff crew**" option. A dialog box titled "**Kickoff an AI Crew**" will appear.
+    </Step>
+    <Step title="Select the crew you want to start">
+        - In the dropdown menu labeled "**Select of the crews online:**", choose the crew you want to start.
+        - In the example below, "**prep-for-meeting**" is selected:
+            <Frame>
+                <img src="/images/enterprise/kickoff-slack-crew-dropdown.png" alt="Kickoff crew dropdown" />
+            </Frame>
+        - If your crew requires any inputs, click the "**Add Inputs**" button to provide them.
+            <Note>
+                The "**Add Inputs**" button is shown in the example above but is not yet clicked.
+            </Note>
+    </Step>
+    <Step title="Click Kickoff and wait for the crew to complete">
+        - Once you've selected the crew and added any necessary inputs, click "**Kickoff**" to start the crew.
+            <Frame>
+                <img src="/images/enterprise/kickoff-slack-crew-kickoff.png" alt="Kickoff crew" />
+            </Frame>
+        - The crew will start executing and you will see the results in the Slack channel.
+            <Frame>
+                <img src="/images/enterprise/kickoff-slack-crew-results.png" alt="Kickoff crew results" />
+            </Frame>
+    </Step>
+</Steps>
+
+## Tips
+
+- Make sure you have the necessary permissions to use the `/kickoff` command in your Slack workspace.
+- If you don't see your desired crew in the dropdown, ensure it's properly configured and online in CrewAI. 

docs/enterprise/guides/team-management.mdx

@@ -0,0 +1,87 @@
+---
+title: "Team Management"
+description: "Learn how to invite and manage team members in your CrewAI Enterprise organization"
+icon: "users"
+---
+
+As an administrator of a CrewAI Enterprise account, you can easily invite new team members to join your organization. This guide will walk you through the process step-by-step.
+
+## Inviting Team Members
+
+<Steps>
+    <Step title="Access the Settings Page">
+        - Log in to your CrewAI Enterprise account
+        - Look for the gear icon (⚙️) in the top right corner of the dashboard
+        - Click on the gear icon to access the **Settings** page:
+            <Frame>
+                <img src="/images/enterprise/settings-page.png" alt="Settings Page" />
+            </Frame>
+    </Step>
+    <Step title="Navigate to the Members Section">
+        - On the Settings page, you'll see a `Members` tab
+        - Click on the `Members` tab to access the **Members** page:
+            <Frame>
+                <img src="/images/enterprise/members-tab.png" alt="Members Tab" />
+            </Frame>
+    </Step>
+    <Step title="Invite New Members">
+        - In the Members section, you'll see a list of current members (including yourself)
+        - Locate the `Email` input field
+        - Enter the email address of the person you want to invite
+        - Click the `Invite` button to send the invitation
+    </Step>
+    <Step title="Repeat as Needed">
+        - You can repeat this process to invite multiple team members
+        - Each invited member will receive an email invitation to join your organization
+    </Step>
+</Steps>
+
+## Adding Roles
+
+You can add roles to your team members to control their access to different parts of the platform.
+
+<Steps>
+    <Step title="Access the Settings Page">
+        - Log in to your CrewAI Enterprise account
+        - Look for the gear icon (⚙️) in the top right corner of the dashboard
+        - Click on the gear icon to access the **Settings** page:
+            <Frame>
+                <img src="/images/enterprise/settings-page.png" alt="Settings Page" />
+            </Frame>
+    </Step>
+    <Step title="Navigate to the Members Section">
+        - On the Settings page, you'll see a `Roles` tab
+        - Click on the `Roles` tab to access the **Roles** page.
+            <Frame>
+                <img src="/images/enterprise/roles-tab.png" alt="Roles Tab" />
+            </Frame>
+        - Click on the `Add Role` button to add a new role.
+        - Enter the details and permissions of the role and click the `Create Role` button to create the role.
+            <Frame>
+                <img src="/images/enterprise/add-role-modal.png" alt="Add Role Modal" />
+            </Frame>
+    </Step>
+    <Step title="Add Roles to Members">
+        - In the Members section, you'll see a list of current members (including yourself)
+           <Frame>
+                <img src="/images/enterprise/member-accepted-invitation.png" alt="Member Accepted Invitation" />
+           </Frame>
+        - Once the member has accepted the invitation, you can add a role to them.
+        - Navigate back to `Roles` tab
+        - Go to the member you want to add a role to and under the `Role` column, click on the dropdown
+        - Select the role you want to add to the member
+        - Click the `Update` button to save the role
+            <Frame>
+                <img src="/images/enterprise/assign-role.png" alt="Add Role to Member" />
+            </Frame>
+    </Step>
+</Steps>
+
+## Important Notes
+
+- **Admin Privileges**: Only users with administrative privileges can invite new members
+- **Email Accuracy**: Ensure you have the correct email addresses for your team members
+- **Invitation Acceptance**: Invited members will need to accept the invitation to join your organization
+- **Email Notifications**: You may want to inform your team members to check their email (including spam folders) for the invitation
+
+By following these steps, you can easily expand your team and collaborate more effectively within your CrewAI Enterprise organization. 

docs/enterprise/guides/use-crew-api.mdx

@@ -1,319 +0,0 @@
----
-title: "Trigger Deployed Crew API"
-description: "Using your deployed crew's API on CrewAI Enterprise"
-icon: "arrow-up-right-from-square"
----
-
-Once you have deployed your crew to CrewAI Enterprise, it automatically becomes available as a REST API. This guide explains how to interact with your crew programmatically.
-
-## API Basics
-
-Your deployed crew exposes several endpoints that allow you to:
-1. Discover required inputs
-2. Start crew executions
-3. Monitor execution status
-4. Receive results
-
-### Authentication
-
-All API requests require a bearer token for authentication, which is generated when you deploy your crew:
-
-```bash
-curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com/...
-```
-
-<Tip>
-You can find your bearer token in the Status tab of your crew's detail page in the CrewAI Enterprise dashboard.
-</Tip>
-
-<Frame>
-  ![Bearer Token](/images/enterprise/bearer-token.png)
-</Frame>
-
-## Available Endpoints
-
-Your crew API provides three main endpoints:
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/inputs` | GET | Lists all required inputs for crew execution |
-| `/kickoff` | POST | Starts a crew execution with provided inputs |
-| `/status/{kickoff_id}` | GET | Retrieves the status and results of an execution |
-
-## GET /inputs
-
-The inputs endpoint allows you to discover what parameters your crew requires:
-
-```bash
-curl -X GET \
-  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
-  https://your-crew-url.crewai.com/inputs
-```
-
-### Response
-
-```json
-{
-  "inputs": ["budget", "interests", "duration", "age"]
-}
-```
-
-This response indicates that your crew expects four input parameters: `budget`, `interests`, `duration`, and `age`.
-
-## POST /kickoff
-
-The kickoff endpoint starts a new crew execution:
-
-```bash
-curl -X POST \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
-  -d '{
-    "inputs": {
-      "budget": "1000 USD",
-      "interests": "games, tech, ai, relaxing hikes, amazing food",
-      "duration": "7 days",
-      "age": "35"
-    }
-  }' \
-  https://your-crew-url.crewai.com/kickoff
-```
-
-### Request Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `inputs` | Object | Yes | Key-value pairs of all required inputs |
-| `meta` | Object | No | Additional metadata to pass to the crew |
-| `taskWebhookUrl` | String | No | Callback URL executed after each task |
-| `stepWebhookUrl` | String | No | Callback URL executed after each agent thought |
-| `crewWebhookUrl` | String | No | Callback URL executed when the crew finishes |
-
-### Example with Webhooks
-
-```json
-{
-  "inputs": {
-    "budget": "1000 USD",
-    "interests": "games, tech, ai, relaxing hikes, amazing food",
-    "duration": "7 days",
-    "age": "35"
-  },
-  "meta": {
-    "requestId": "user-request-12345",
-    "source": "mobile-app"
-  },
-  "taskWebhookUrl": "https://your-server.com/webhooks/task",
-  "stepWebhookUrl": "https://your-server.com/webhooks/step",
-  "crewWebhookUrl": "https://your-server.com/webhooks/crew"
-}
-```
-
-### Response
-
-```json
-{
-  "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"
-}
-```
-
-The `kickoff_id` is used to track and retrieve the execution results.
-
-## GET /status/{kickoff_id}
-
-The status endpoint allows you to check the progress and results of a crew execution:
-
-```bash
-curl -X GET \
-  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
-  https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
-```
-
-### Response Structure
-
-The response structure will vary depending on the execution state:
-
-#### In Progress
-
-```json
-{
-  "status": "running",
-  "current_task": "research_task",
-  "progress": {
-    "completed_tasks": 0,
-    "total_tasks": 2
-  }
-}
-```
-
-#### Completed
-
-```json
-{
-  "status": "completed",
-  "result": {
-    "output": "Comprehensive travel itinerary...",
-    "tasks": [
-      {
-        "task_id": "research_task",
-        "output": "Research findings...",
-        "agent": "Researcher",
-        "execution_time": 45.2
-      },
-      {
-        "task_id": "planning_task",
-        "output": "7-day itinerary plan...",
-        "agent": "Trip Planner",
-        "execution_time": 62.8
-      }
-    ]
-  },
-  "execution_time": 108.5
-}
-```
-
-## Webhook Integration
-
-When you provide webhook URLs in your kickoff request, the system will make POST requests to those URLs at specific points in the execution:
-
-### taskWebhookUrl
-
-Called when each task completes:
-
-```json
-{
-  "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
-  "task_id": "research_task",
-  "status": "completed",
-  "output": "Research findings...",
-  "agent": "Researcher",
-  "execution_time": 45.2
-}
-```
-
-### stepWebhookUrl
-
-Called after each agent thought or action:
-
-```json
-{
-  "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
-  "task_id": "research_task",
-  "agent": "Researcher",
-  "step_type": "thought",
-  "content": "I should first search for popular destinations that match these interests..."
-}
-```
-
-### crewWebhookUrl
-
-Called when the entire crew execution completes:
-
-```json
-{
-  "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
-  "status": "completed",
-  "result": {
-    "output": "Comprehensive travel itinerary...",
-    "tasks": [
-      {
-        "task_id": "research_task",
-        "output": "Research findings...",
-        "agent": "Researcher",
-        "execution_time": 45.2
-      },
-      {
-        "task_id": "planning_task",
-        "output": "7-day itinerary plan...",
-        "agent": "Trip Planner",
-        "execution_time": 62.8
-      }
-    ]
-  },
-  "execution_time": 108.5,
-  "meta": {
-    "requestId": "user-request-12345",
-    "source": "mobile-app"
-  }
-}
-```
-
-## Best Practices
-
-### Handling Long-Running Executions
-
-Crew executions can take anywhere from seconds to minutes depending on their complexity. Consider these approaches:
-
-1. **Webhooks (Recommended)**: Set up webhook endpoints to receive notifications when the execution completes
-2. **Polling**: Implement a polling mechanism with exponential backoff
-3. **Client-Side Timeout**: Set appropriate timeouts for your API requests
-
-### Error Handling
-
-The API may return various error codes:
-
-| Code | Description | Recommended Action |
-|------|-------------|-------------------|
-| 401 | Unauthorized | Check your bearer token |
-| 404 | Not Found | Verify your crew URL and kickoff_id |
-| 422 | Validation Error | Ensure all required inputs are provided |
-| 500 | Server Error | Contact support with the error details |
-
-### Sample Code
-
-Here's a complete Python example for interacting with your crew API:
-
-```python
-import requests
-import time
-
-# Configuration
-CREW_URL = "https://your-crew-url.crewai.com"
-BEARER_TOKEN = "your-crew-token"
-HEADERS = {
-    "Authorization": f"Bearer {BEARER_TOKEN}",
-    "Content-Type": "application/json"
-}
-
-# 1. Get required inputs
-response = requests.get(f"{CREW_URL}/inputs", headers=HEADERS)
-required_inputs = response.json()["inputs"]
-print(f"Required inputs: {required_inputs}")
-
-# 2. Start crew execution
-payload = {
-    "inputs": {
-        "budget": "1000 USD",
-        "interests": "games, tech, ai, relaxing hikes, amazing food",
-        "duration": "7 days",
-        "age": "35"
-    }
-}
-
-response = requests.post(f"{CREW_URL}/kickoff", headers=HEADERS, json=payload)
-kickoff_id = response.json()["kickoff_id"]
-print(f"Execution started with ID: {kickoff_id}")
-
-# 3. Poll for results
-MAX_RETRIES = 30
-POLL_INTERVAL = 10  # seconds
-for i in range(MAX_RETRIES):
-    print(f"Checking status (attempt {i+1}/{MAX_RETRIES})...")
-    response = requests.get(f"{CREW_URL}/status/{kickoff_id}", headers=HEADERS)
-    data = response.json()
-    
-    if data["status"] == "completed":
-        print("Execution completed!")
-        print(f"Result: {data['result']['output']}")
-        break
-    elif data["status"] == "error":
-        print(f"Execution failed: {data.get('error', 'Unknown error')}")
-        break
-    else:
-        print(f"Status: {data['status']}, waiting {POLL_INTERVAL} seconds...")
-        time.sleep(POLL_INTERVAL)
-```
-
-<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
-  Contact our support team for assistance with API integration or troubleshooting.
-</Card>

docs/enterprise/guides/webhook-automation.mdx

@@ -0,0 +1,121 @@
+---
+title: "Webhook Automation"
+description: "Automate CrewAI Enterprise workflows using webhooks with platforms like ActivePieces, Zapier, and Make.com"
+icon: "webhook"
+---
+
+CrewAI Enterprise allows you to automate your workflow using webhooks. This article will guide you through the process of setting up and using webhooks to kickoff your crew execution, with a focus on integration with ActivePieces, a workflow automation platform similar to Zapier and Make.com.
+
+## Setting Up Webhooks
+
+<Steps>
+    <Step title="Accessing the Kickoff Interface">
+        - Navigate to the CrewAI Enterprise dashboard
+        - Look for the `/kickoff` section, which is used to start the crew execution
+            <Frame>
+                <img src="/images/enterprise/kickoff-interface.png" alt="Kickoff Interface" />
+            </Frame>
+    </Step>
+
+    <Step title="Configuring the JSON Content">
+        In the JSON Content section, you'll need to provide the following information:
+
+        - **inputs**: A JSON object containing:
+            - `company`: The name of the company (e.g., "tesla")
+            - `product_name`: The name of the product (e.g., "crewai")
+            - `form_response`: The type of response (e.g., "financial")
+            - `icp_description`: A brief description of the Ideal Customer Profile
+            - `product_description`: A short description of the product
+            - `taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`: URLs for various webhook endpoints (ActivePieces, Zapier, Make.com or another compatible platform)
+    </Step>
+
+    <Step title="Integrating with ActivePieces">
+        In this example we will be using ActivePieces. You can use other platforms such as Zapier and Make.com
+
+        To integrate with ActivePieces:
+
+        1. Set up a new flow in ActivePieces
+        2. Add a trigger (e.g., `Every Day` schedule)
+            <Frame>
+                <img src="/images/enterprise/activepieces-trigger.png" alt="ActivePieces Trigger" />
+            </Frame>
+
+        3. Add an HTTP action step
+            - Set the action to `Send HTTP request`
+            - Use `POST` as the method
+            - Set the URL to your CrewAI Enterprise kickoff endpoint
+            - Add necessary headers (e.g., `Bearer Token`)
+                <Frame>
+                    <img src="/images/enterprise/activepieces-headers.png" alt="ActivePieces Headers" />
+                </Frame>
+
+            - In the body, include the JSON content as configured in step 2
+                <Frame>
+                    <img src="/images/enterprise/activepieces-body.png" alt="ActivePieces Body" />
+                </Frame>
+
+            - The crew will then kickoff at the pre-defined time.
+    </Step>
+
+    <Step title="Setting Up the Webhook">
+        1. Create a new flow in ActivePieces and name it 
+            <Frame>
+                <img src="/images/enterprise/activepieces-flow.png" alt="ActivePieces Flow" />
+            </Frame>
+
+        2. Add a webhook step as the trigger:
+            - Select `Catch Webhook` as the trigger type
+            - This will generate a unique URL that will receive HTTP requests and trigger your flow
+                <Frame>
+                    <img src="/images/enterprise/activepieces-webhook.png" alt="ActivePieces Webhook" />
+                </Frame>
+
+            - Configure the email to use crew webhook body text
+                <Frame>
+                    <img src="/images/enterprise/activepieces-email.png" alt="ActivePieces Email" />
+                </Frame>
+    </Step>
+</Steps>
+
+## Webhook Output Examples
+
+<Tabs>
+    <Tab title="Step Webhook">
+        `stepWebhookUrl` - Callback that will be executed upon each agent inner thought
+
+        ```json
+        {
+            "action": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
+            "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
+        }
+        ```
+    </Tab>
+    <Tab title="Task Webhook">
+        `taskWebhookUrl` - Callback that will be executed upon the end of each task
+
+        ```json
+        {
+            "description": "Using the information gathered from the lead's data, conduct preliminary research on the lead's industry, company background, and potential use cases for crewai. Focus on finding relevant data that can aid in scoring the lead and planning a strategy to pitch them crewai.The financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
+            "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
+        }
+        ```
+    </Tab>
+    <Tab title="Crew Webhook">
+        `crewWebhookUrl` - Callback that will be executed upon the end of the crew execution
+
+        ```json
+        {
+            "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
+            "result": {
+                "lead_score": "Customer service enhancement, and compliance are particularly relevant.",
+                "talking_points": [
+                    "Highlight how crewai's AI solutions can transform customer service with automated, personalized experiences and 24/7 support, improving both customer satisfaction and operational efficiency.",
+                    "Discuss crewai's potential to help the institution achieve its sustainability goals through better data analysis and decision-making, contributing to responsible investing and green initiatives.",
+                    "Emphasize crewai's ability to enhance compliance with evolving regulations through efficient data processing and reporting, reducing the risk of non-compliance penalties.",
+                    "Stress the adaptability of crewai to support both extensive multinational operations and smaller, targeted projects, ensuring the solution grows with the institution's needs."
+                ]
+            }
+        }
+        ```
+    </Tab>
+</Tabs> 

docs/enterprise/guides/zapier-trigger.mdx

@@ -0,0 +1,103 @@
+---
+title: "Zapier Trigger"
+description: "Trigger CrewAI crews from Zapier workflows to automate cross-app workflows"
+icon: "bolt"
+---
+
+This guide will walk you through the process of setting up Zapier triggers for CrewAI Enterprise, allowing you to automate workflows between CrewAI Enterprise and other applications.
+
+## Prerequisites
+
+- A CrewAI Enterprise account
+- A Zapier account
+- A Slack account (for this specific example)
+
+## Step-by-Step Setup
+
+<Steps>
+    <Step title="Set Up the Slack Trigger">
+        - In Zapier, create a new Zap.
+
+        <Frame>
+            <img src="/images/enterprise/zapier-1.png" alt="Zapier 1" />
+        </Frame>
+    </Step>
+
+    <Step title="Choose Slack as your trigger app">
+        <Frame>
+            <img src="/images/enterprise/zapier-2.png" alt="Zapier 2" />
+        </Frame>
+        - Select `New Pushed Message` as the Trigger Event.
+        - Connect your Slack account if you haven't already.
+    </Step>
+
+    <Step title="Configure the CrewAI Enterprise Action">
+        - Add a new action step to your Zap.
+        - Choose CrewAI+ as your action app and Kickoff as the Action Event
+
+        <Frame>
+            <img src="/images/enterprise/zapier-3.png" alt="Zapier 5" />
+        </Frame>
+    </Step>
+
+    <Step title="Connect your CrewAI Enterprise account">
+        - Connect your CrewAI Enterprise account.
+        - Select the appropriate Crew for your workflow.
+
+        <Frame>
+            <img src="/images/enterprise/zapier-4.png" alt="Zapier 6" />
+        </Frame>
+        - Configure the inputs for the Crew using the data from the Slack message.
+    </Step>
+
+    <Step title="Format the CrewAI Enterprise Output">
+        - Add another action step to format the text output from CrewAI Enterprise.
+        - Use Zapier's formatting tools to convert the Markdown output to HTML.
+
+        <Frame>
+            <img src="/images/enterprise/zapier-5.png" alt="Zapier 8" />
+        </Frame>
+        <Frame>
+            <img src="/images/enterprise/zapier-6.png" alt="Zapier 9" />
+        </Frame>
+    </Step>
+
+    <Step title="Send the Output via Email">
+        - Add a final action step to send the formatted output via email.
+        - Choose your preferred email service (e.g., Gmail, Outlook).
+        - Configure the email details, including recipient, subject, and body.
+        - Insert the formatted CrewAI Enterprise output into the email body.
+
+        <Frame>
+            <img src="/images/enterprise/zapier-7.png" alt="Zapier 7" />
+        </Frame>
+    </Step>
+
+    <Step title="Kick Off the crew from Slack">
+        - Enter the text in your Slack channel
+
+        <Frame>
+            <img src="/images/enterprise/zapier-7b.png" alt="Zapier 10" />
+        </Frame>
+
+        - Select the 3 ellipsis button and then chose Push to Zapier
+
+        <Frame>
+            <img src="/images/enterprise/zapier-8.png" alt="Zapier 11" />
+        </Frame>
+    </Step>
+
+    <Step title="Select the crew and then Push to Kick Off">
+        <Frame>
+            <img src="/images/enterprise/zapier-9.png" alt="Zapier 12" />
+        </Frame>
+    </Step>
+</Steps>
+
+## Tips for Success
+
+- Ensure that your CrewAI Enterprise inputs are correctly mapped from the Slack message.
+- Test your Zap thoroughly before turning it on to catch any potential issues.
+- Consider adding error handling steps to manage potential failures in the workflow.
+
+By following these steps, you'll have successfully set up Zapier triggers for CrewAI Enterprise, allowing for automated workflows triggered by Slack messages and resulting in email notifications with CrewAI Enterprise output. 

docs/guides/advanced/customizing-prompts.mdx

@@ -6,7 +6,7 @@ icon: message-pen
 
 ## Why Customize Prompts?
 
-Although CrewAI's default prompts work well for many scenarios, low-level customization opens the door to significantly more flexible and powerful agent behavior. Here’s why you might want to take advantage of this deeper control:
+Although CrewAI's default prompts work well for many scenarios, low-level customization opens the door to significantly more flexible and powerful agent behavior. Here's why you might want to take advantage of this deeper control:
 
 1. **Optimize for specific LLMs** – Different models (such as GPT-4, Claude, or Llama) thrive with prompt formats tailored to their unique architectures.
 2. **Change the language** – Build agents that operate exclusively in languages beyond English, handling nuances with precision.
@@ -20,13 +20,174 @@ This guide explores how to tap into CrewAI's prompts at a lower level, giving yo
 
 Under the hood, CrewAI employs a modular prompt system that you can customize extensively:
 
-- **Agent templates** – Govern each agent’s approach to their assigned role.
+- **Agent templates** – Govern each agent's approach to their assigned role.
 - **Prompt slices** – Control specialized behaviors such as tasks, tool usage, and output structure.
 - **Error handling** – Direct how agents respond to failures, exceptions, or timeouts.
 - **Tool-specific prompts** – Define detailed instructions for how tools are invoked or utilized.
 
 Check out the [original prompt templates in CrewAI's repository](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) to see how these elements are organized. From there, you can override or adapt them as needed to unlock advanced behaviors.
 
+## Understanding Default System Instructions
+
+<Warning>
+**Production Transparency Issue**: CrewAI automatically injects default instructions into your prompts that you might not be aware of. This section explains what's happening under the hood and how to gain full control.
+</Warning>
+
+When you define an agent with `role`, `goal`, and `backstory`, CrewAI automatically adds additional system instructions that control formatting and behavior. Understanding these default injections is crucial for production systems where you need full prompt transparency.
+
+### What CrewAI Automatically Injects
+
+Based on your agent configuration, CrewAI adds different default instructions:
+
+#### For Agents Without Tools
+```text
+"I MUST use these formats, my job depends on it!"
+```
+
+#### For Agents With Tools  
+```text
+"IMPORTANT: Use the following format in your response:
+
+Thought: you should always think about what to do
+Action: the action to take, only one name of [tool_names]
+Action Input: the input to the action, just a simple JSON object...
+```
+
+#### For Structured Outputs (JSON/Pydantic)
+```text
+"Ensure your final answer contains only the content in the following format: {output_format}
+Ensure the final output does not include any code block markers like ```json or ```python."
+```
+
+### Viewing the Complete System Prompt
+
+To see exactly what prompt is being sent to your LLM, you can inspect the generated prompt:
+
+```python
+from crewai import Agent, Crew, Task
+from crewai.utilities.prompts import Prompts
+
+# Create your agent
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze data and provide insights",
+    backstory="You are an expert data analyst with 10 years of experience.",
+    verbose=True
+)
+
+# Create a sample task
+task = Task(
+    description="Analyze the sales data and identify trends",
+    expected_output="A detailed analysis with key insights and trends",
+    agent=agent
+)
+
+# Create the prompt generator
+prompt_generator = Prompts(
+    agent=agent,
+    has_tools=len(agent.tools) > 0,
+    use_system_prompt=agent.use_system_prompt
+)
+
+# Generate and inspect the actual prompt
+generated_prompt = prompt_generator.task_execution()
+
+# Print the complete system prompt that will be sent to the LLM
+if "system" in generated_prompt:
+    print("=== SYSTEM PROMPT ===")
+    print(generated_prompt["system"])
+    print("\n=== USER PROMPT ===")
+    print(generated_prompt["user"])
+else:
+    print("=== COMPLETE PROMPT ===")
+    print(generated_prompt["prompt"])
+
+# You can also see how the task description gets formatted
+print("\n=== TASK CONTEXT ===")
+print(f"Task Description: {task.description}")
+print(f"Expected Output: {task.expected_output}")
+```
+
+### Overriding Default Instructions
+
+You have several options to gain full control over the prompts:
+
+#### Option 1: Custom Templates (Recommended)
+```python
+from crewai import Agent
+
+# Define your own system template without default instructions
+custom_system_template = """You are {role}. {backstory}
+Your goal is: {goal}
+
+Respond naturally and conversationally. Focus on providing helpful, accurate information."""
+
+custom_prompt_template = """Task: {input}
+
+Please complete this task thoughtfully."""
+
+agent = Agent(
+    role="Research Assistant", 
+    goal="Help users find accurate information",
+    backstory="You are a helpful research assistant.",
+    system_template=custom_system_template,
+    prompt_template=custom_prompt_template,
+    use_system_prompt=True  # Use separate system/user messages
+)
+```
+
+#### Option 2: Custom Prompt File
+Create a `custom_prompts.json` file to override specific prompt slices:
+
+```json
+{
+  "slices": {
+    "no_tools": "\nProvide your best answer in a natural, conversational way.",
+    "tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.",
+    "formatted_task_instructions": "Format your response as: {output_format}"
+  }
+}
+```
+
+Then use it in your crew:
+
+```python
+crew = Crew(
+    agents=[agent],
+    tasks=[task],
+    prompt_file="custom_prompts.json",
+    verbose=True
+)
+```
+
+#### Option 3: Disable System Prompts for o1 Models
+```python
+agent = Agent(
+    role="Analyst",
+    goal="Analyze data", 
+    backstory="Expert analyst",
+    use_system_prompt=False  # Disables system prompt separation
+)
+```
+
+### Debugging with Observability Tools
+
+For production transparency, integrate with observability platforms to monitor all prompts and LLM interactions. This allows you to see exactly what prompts (including default instructions) are being sent to your LLMs.
+
+See our [Observability documentation](/how-to/observability) for detailed integration guides with various platforms including Langfuse, MLflow, Weights & Biases, and custom logging solutions.
+
+### Best Practices for Production
+
+1. **Always inspect generated prompts** before deploying to production
+2. **Use custom templates** when you need full control over prompt content
+3. **Integrate observability tools** for ongoing prompt monitoring (see [Observability docs](/how-to/observability))
+4. **Test with different LLMs** as default instructions may work differently across models
+5. **Document your prompt customizations** for team transparency
+
+<Tip>
+The default instructions exist to ensure consistent agent behavior, but they can interfere with domain-specific requirements. Use the customization options above to maintain full control over your agent's behavior in production systems.
+</Tip>
+
 ## Best Practices for Managing Prompt Files
 
 When engaging in low-level prompt customization, follow these guidelines to keep things organized and maintainable:
@@ -44,7 +205,7 @@ One straightforward approach is to create a JSON file for the prompts you want t
 1. Craft a JSON file with your updated prompt slices.
 2. Reference that file via the `prompt_file` parameter in your Crew.
 
-CrewAI then merges your customizations with the defaults, so you don’t have to redefine every prompt. Here’s how:
+CrewAI then merges your customizations with the defaults, so you don't have to redefine every prompt. Here's how:
 
 ### Example: Basic Prompt Customization
 
@@ -93,14 +254,14 @@ With these few edits, you gain low-level control over how your agents communicat
 
 ## Optimizing for Specific Models
 
-Different models thrive on differently structured prompts. Making deeper adjustments can significantly boost performance by aligning your prompts with a model’s nuances.
+Different models thrive on differently structured prompts. Making deeper adjustments can significantly boost performance by aligning your prompts with a model's nuances.
 
 ### Example: Llama 3.3 Prompting Template
 
-For instance, when dealing with Meta’s Llama 3.3, deeper-level customization may reflect the recommended structure described at:
+For instance, when dealing with Meta's Llama 3.3, deeper-level customization may reflect the recommended structure described at:
 https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template
 
-Here’s an example to highlight how you might fine-tune an Agent to leverage Llama 3.3 in code:
+Here's an example to highlight how you might fine-tune an Agent to leverage Llama 3.3 in code:
 
 ```python
 from crewai import Agent, Crew, Task, Process
@@ -148,8 +309,8 @@ Through this deeper configuration, you can exercise comprehensive, low-level con
 
 ## Conclusion
 
-Low-level prompt customization in CrewAI opens the door to super custom, complex use cases. By establishing well-organized prompt files (or direct inline templates), you can accommodate various models, languages, and specialized domains. This level of flexibility ensures you can craft precisely the AI behavior you need, all while knowing CrewAI still provides reliable defaults when you don’t override them.
+Low-level prompt customization in CrewAI opens the door to super custom, complex use cases. By establishing well-organized prompt files (or direct inline templates), you can accommodate various models, languages, and specialized domains. This level of flexibility ensures you can craft precisely the AI behavior you need, all while knowing CrewAI still provides reliable defaults when you don't override them.
 
 <Check>
-You now have the foundation for advanced prompt customizations in CrewAI. Whether you’re adapting for model-specific structures or domain-specific constraints, this low-level approach lets you shape agent interactions in highly specialized ways.
+You now have the foundation for advanced prompt customizations in CrewAI. Whether you're adapting for model-specific structures or domain-specific constraints, this low-level approach lets you shape agent interactions in highly specialized ways.
 </Check>

docs/guides/concepts/evaluating-use-cases.mdx

@@ -11,7 +11,7 @@ When building AI applications with CrewAI, one of the most important decisions y
 At the heart of this decision is understanding the relationship between **complexity** and **precision** in your application:
 
 <Frame caption="Complexity vs. Precision Matrix for CrewAI Applications">
-  <img src="../..//complexity_precision.png" alt="Complexity vs. Precision Matrix" />
+  <img src="../../images/complexity_precision.png" alt="Complexity vs. Precision Matrix" />
 </Frame>
 
 This matrix helps visualize how different approaches align with varying requirements for complexity and precision. Let's explore what each quadrant means and how it guides your architectural choices.

docs/guides/crews/first-crew.mdx

@@ -54,7 +54,7 @@ This will generate a project with the basic structure needed for your crew. The
 - A main script to run the crew
 
 <Frame caption="CrewAI Framework Overview">
-  <img src="../../crews.png" alt="CrewAI Framework Overview" />
+  <img src="../../images/crews.png" alt="CrewAI Framework Overview" />
 </Frame>
 
 

docs/guides/flows/first-flow.mdx

@@ -59,7 +59,7 @@ cd guide_creator_flow
 This will generate a project with the basic structure needed for your flow.
 
 <Frame caption="CrewAI Framework Overview">
-  <img src="../../flows.png" alt="CrewAI Framework Overview" />
+  <img src="../../images/flows.png" alt="CrewAI Framework Overview" />
 </Frame>
 
 ## Step 2: Understanding the Project Structure

docs/guides/flows/mastering-flow-state.mdx

@@ -277,22 +277,23 @@ This pattern allows you to combine direct data passing with state updates for ma
 
 One of CrewAI's most powerful features is the ability to persist flow state across executions. This enables workflows that can be paused, resumed, and even recovered after failures.
 
-### The @persist Decorator
+### The @persist() Decorator
 
-The `@persist` decorator automates state persistence, saving your flow's state at key points in execution.
+The `@persist()` decorator automates state persistence, saving your flow's state at key points in execution.
 
 #### Class-Level Persistence
 
-When applied at the class level, `@persist` saves state after every method execution:
+When applied at the class level, `@persist()` saves state after every method execution:
 
 ```python
-from crewai.flow.flow import Flow, listen, persist, start
+from crewai.flow.flow import Flow, listen, start
+from crewai.flow.persistence import persist
 from pydantic import BaseModel
 
 class CounterState(BaseModel):
     value: int = 0
 
-@persist  # Apply to the entire flow class
+@persist()  # Apply to the entire flow class
 class PersistentCounterFlow(Flow[CounterState]):
     @start()
     def increment(self):
@@ -319,10 +320,11 @@ print(f"Second run result: {result2}")  # Will be higher due to persisted state
 
 #### Method-Level Persistence
 
-For more granular control, you can apply `@persist` to specific methods:
+For more granular control, you can apply `@persist()` to specific methods:
 
 ```python
-from crewai.flow.flow import Flow, listen, persist, start
+from crewai.flow.flow import Flow, listen, start
+from crewai.flow.persistence import persist
 
 class SelectivePersistFlow(Flow):
     @start()
@@ -330,7 +332,7 @@ class SelectivePersistFlow(Flow):
         self.state["count"] = 1
         return "First step"
 
-    @persist  # Only persist after this method
+    @persist()  # Only persist after this method
     @listen(first_step)
     def important_step(self, prev_result):
         self.state["count"] += 1

docs/how-to/custom-llm.mdx

@@ -1,646 +0,0 @@
----
-title: Custom LLM Implementation
-description: Learn how to create custom LLM implementations in CrewAI.
-icon: code
----
-
-## Custom LLM Implementations
-
-CrewAI now supports custom LLM implementations through the `BaseLLM` abstract base class. This allows you to create your own LLM implementations that don't rely on litellm's authentication mechanism.
-
-To create a custom LLM implementation, you need to:
-
-1. Inherit from the `BaseLLM` abstract base class
-2. Implement the required methods:
-   - `call()`: The main method to call the LLM with messages
-   - `supports_function_calling()`: Whether the LLM supports function calling
-   - `supports_stop_words()`: Whether the LLM supports stop words
-   - `get_context_window_size()`: The context window size of the LLM
-
-## Example: Basic Custom LLM
-
-```python
-from crewai import BaseLLM
-from typing import Any, Dict, List, Optional, Union
-
-class CustomLLM(BaseLLM):
-    def __init__(self, api_key: str, endpoint: str):
-        super().__init__()  # Initialize the base class to set default attributes
-        if not api_key or not isinstance(api_key, str):
-            raise ValueError("Invalid API key: must be a non-empty string")
-        if not endpoint or not isinstance(endpoint, str):
-            raise ValueError("Invalid endpoint URL: must be a non-empty string")
-        self.api_key = api_key
-        self.endpoint = endpoint
-        self.stop = []  # You can customize stop words if needed
-        
-    def call(
-        self,
-        messages: Union[str, List[Dict[str, str]]],
-        tools: Optional[List[dict]] = None,
-        callbacks: Optional[List[Any]] = None,
-        available_functions: Optional[Dict[str, Any]] = None,
-    ) -> Union[str, Any]:
-        """Call the LLM with the given messages.
-        
-        Args:
-            messages: Input messages for the LLM.
-            tools: Optional list of tool schemas for function calling.
-            callbacks: Optional list of callback functions.
-            available_functions: Optional dict mapping function names to callables.
-            
-        Returns:
-            Either a text response from the LLM or the result of a tool function call.
-            
-        Raises:
-            TimeoutError: If the LLM request times out.
-            RuntimeError: If the LLM request fails for other reasons.
-            ValueError: If the response format is invalid.
-        """
-        # Implement your own logic to call the LLM
-        # For example, using requests:
-        import requests
-        
-        try:
-            headers = {
-                "Authorization": f"Bearer {self.api_key}",
-                "Content-Type": "application/json"
-            }
-            
-            # Convert string message to proper format if needed
-            if isinstance(messages, str):
-                messages = [{"role": "user", "content": messages}]
-            
-            data = {
-                "messages": messages,
-                "tools": tools
-            }
-            
-            response = requests.post(
-                self.endpoint, 
-                headers=headers, 
-                json=data,
-                timeout=30  # Set a reasonable timeout
-            )
-            response.raise_for_status()  # Raise an exception for HTTP errors
-            return response.json()["choices"][0]["message"]["content"]
-        except requests.Timeout:
-            raise TimeoutError("LLM request timed out")
-        except requests.RequestException as e:
-            raise RuntimeError(f"LLM request failed: {str(e)}")
-        except (KeyError, IndexError, ValueError) as e:
-            raise ValueError(f"Invalid response format: {str(e)}")
-        
-    def supports_function_calling(self) -> bool:
-        """Check if the LLM supports function calling.
-        
-        Returns:
-            True if the LLM supports function calling, False otherwise.
-        """
-        # Return True if your LLM supports function calling
-        return True
-        
-    def supports_stop_words(self) -> bool:
-        """Check if the LLM supports stop words.
-        
-        Returns:
-            True if the LLM supports stop words, False otherwise.
-        """
-        # Return True if your LLM supports stop words
-        return True
-        
-    def get_context_window_size(self) -> int:
-        """Get the context window size of the LLM.
-        
-        Returns:
-            The context window size as an integer.
-        """
-        # Return the context window size of your LLM
-        return 8192
-```
-
-## Error Handling Best Practices
-
-When implementing custom LLMs, it's important to handle errors properly to ensure robustness and reliability. Here are some best practices:
-
-### 1. Implement Try-Except Blocks for API Calls
-
-Always wrap API calls in try-except blocks to handle different types of errors:
-
-```python
-def call(
-    self,
-    messages: Union[str, List[Dict[str, str]]],
-    tools: Optional[List[dict]] = None,
-    callbacks: Optional[List[Any]] = None,
-    available_functions: Optional[Dict[str, Any]] = None,
-) -> Union[str, Any]:
-    try:
-        # API call implementation
-        response = requests.post(
-            self.endpoint,
-            headers=self.headers,
-            json=self.prepare_payload(messages),
-            timeout=30  # Set a reasonable timeout
-        )
-        response.raise_for_status()  # Raise an exception for HTTP errors
-        return response.json()["choices"][0]["message"]["content"]
-    except requests.Timeout:
-        raise TimeoutError("LLM request timed out")
-    except requests.RequestException as e:
-        raise RuntimeError(f"LLM request failed: {str(e)}")
-    except (KeyError, IndexError, ValueError) as e:
-        raise ValueError(f"Invalid response format: {str(e)}")
-```
-
-### 2. Implement Retry Logic for Transient Failures
-
-For transient failures like network issues or rate limiting, implement retry logic with exponential backoff:
-
-```python
-def call(
-    self,
-    messages: Union[str, List[Dict[str, str]]],
-    tools: Optional[List[dict]] = None,
-    callbacks: Optional[List[Any]] = None,
-    available_functions: Optional[Dict[str, Any]] = None,
-) -> Union[str, Any]:
-    import time
-    
-    max_retries = 3
-    retry_delay = 1  # seconds
-    
-    for attempt in range(max_retries):
-        try:
-            response = requests.post(
-                self.endpoint,
-                headers=self.headers,
-                json=self.prepare_payload(messages),
-                timeout=30
-            )
-            response.raise_for_status()
-            return response.json()["choices"][0]["message"]["content"]
-        except (requests.Timeout, requests.ConnectionError) as e:
-            if attempt < max_retries - 1:
-                time.sleep(retry_delay * (2 ** attempt))  # Exponential backoff
-                continue
-            raise TimeoutError(f"LLM request failed after {max_retries} attempts: {str(e)}")
-        except requests.RequestException as e:
-            raise RuntimeError(f"LLM request failed: {str(e)}")
-```
-
-### 3. Validate Input Parameters
-
-Always validate input parameters to prevent runtime errors:
-
-```python
-def __init__(self, api_key: str, endpoint: str):
-    super().__init__()
-    if not api_key or not isinstance(api_key, str):
-        raise ValueError("Invalid API key: must be a non-empty string")
-    if not endpoint or not isinstance(endpoint, str):
-        raise ValueError("Invalid endpoint URL: must be a non-empty string")
-    self.api_key = api_key
-    self.endpoint = endpoint
-```
-
-### 4. Handle Authentication Errors Gracefully
-
-Provide clear error messages for authentication failures:
-
-```python
-def call(
-    self,
-    messages: Union[str, List[Dict[str, str]]],
-    tools: Optional[List[dict]] = None,
-    callbacks: Optional[List[Any]] = None,
-    available_functions: Optional[Dict[str, Any]] = None,
-) -> Union[str, Any]:
-    try:
-        response = requests.post(self.endpoint, headers=self.headers, json=data)
-        if response.status_code == 401:
-            raise ValueError("Authentication failed: Invalid API key or token")
-        elif response.status_code == 403:
-            raise ValueError("Authorization failed: Insufficient permissions")
-        response.raise_for_status()
-        # Process response
-    except Exception as e:
-        # Handle error
-        raise
-```
-
-## Example: JWT-based Authentication
-
-For services that use JWT-based authentication instead of API keys, you can implement a custom LLM like this:
-
-```python
-from crewai import BaseLLM, Agent, Task
-from typing import Any, Dict, List, Optional, Union
-
-class JWTAuthLLM(BaseLLM):
-    def __init__(self, jwt_token: str, endpoint: str):
-        super().__init__()  # Initialize the base class to set default attributes
-        if not jwt_token or not isinstance(jwt_token, str):
-            raise ValueError("Invalid JWT token: must be a non-empty string")
-        if not endpoint or not isinstance(endpoint, str):
-            raise ValueError("Invalid endpoint URL: must be a non-empty string")
-        self.jwt_token = jwt_token
-        self.endpoint = endpoint
-        self.stop = []  # You can customize stop words if needed
-        
-    def call(
-        self,
-        messages: Union[str, List[Dict[str, str]]],
-        tools: Optional[List[dict]] = None,
-        callbacks: Optional[List[Any]] = None,
-        available_functions: Optional[Dict[str, Any]] = None,
-    ) -> Union[str, Any]:
-        """Call the LLM with JWT authentication.
-        
-        Args:
-            messages: Input messages for the LLM.
-            tools: Optional list of tool schemas for function calling.
-            callbacks: Optional list of callback functions.
-            available_functions: Optional dict mapping function names to callables.
-            
-        Returns:
-            Either a text response from the LLM or the result of a tool function call.
-            
-        Raises:
-            TimeoutError: If the LLM request times out.
-            RuntimeError: If the LLM request fails for other reasons.
-            ValueError: If the response format is invalid.
-        """
-        # Implement your own logic to call the LLM with JWT authentication
-        import requests
-        
-        try:
-            headers = {
-                "Authorization": f"Bearer {self.jwt_token}",
-                "Content-Type": "application/json"
-            }
-            
-            # Convert string message to proper format if needed
-            if isinstance(messages, str):
-                messages = [{"role": "user", "content": messages}]
-            
-            data = {
-                "messages": messages,
-                "tools": tools
-            }
-            
-            response = requests.post(
-                self.endpoint,
-                headers=headers,
-                json=data,
-                timeout=30  # Set a reasonable timeout
-            )
-            
-            if response.status_code == 401:
-                raise ValueError("Authentication failed: Invalid JWT token")
-            elif response.status_code == 403:
-                raise ValueError("Authorization failed: Insufficient permissions")
-                
-            response.raise_for_status()  # Raise an exception for HTTP errors
-            return response.json()["choices"][0]["message"]["content"]
-        except requests.Timeout:
-            raise TimeoutError("LLM request timed out")
-        except requests.RequestException as e:
-            raise RuntimeError(f"LLM request failed: {str(e)}")
-        except (KeyError, IndexError, ValueError) as e:
-            raise ValueError(f"Invalid response format: {str(e)}")
-        
-    def supports_function_calling(self) -> bool:
-        """Check if the LLM supports function calling.
-        
-        Returns:
-            True if the LLM supports function calling, False otherwise.
-        """
-        return True
-        
-    def supports_stop_words(self) -> bool:
-        """Check if the LLM supports stop words.
-        
-        Returns:
-            True if the LLM supports stop words, False otherwise.
-        """
-        return True
-        
-    def get_context_window_size(self) -> int:
-        """Get the context window size of the LLM.
-        
-        Returns:
-            The context window size as an integer.
-        """
-        return 8192
-```
-
-## Troubleshooting
-
-Here are some common issues you might encounter when implementing custom LLMs and how to resolve them:
-
-### 1. Authentication Failures
-
-**Symptoms**: 401 Unauthorized or 403 Forbidden errors
-
-**Solutions**:
-- Verify that your API key or JWT token is valid and not expired
-- Check that you're using the correct authentication header format
-- Ensure that your token has the necessary permissions
-
-### 2. Timeout Issues
-
-**Symptoms**: Requests taking too long or timing out
-
-**Solutions**:
-- Implement timeout handling as shown in the examples
-- Use retry logic with exponential backoff
-- Consider using a more reliable network connection
-
-### 3. Response Parsing Errors
-
-**Symptoms**: KeyError, IndexError, or ValueError when processing responses
-
-**Solutions**:
-- Validate the response format before accessing nested fields
-- Implement proper error handling for malformed responses
-- Check the API documentation for the expected response format
-
-### 4. Rate Limiting
-
-**Symptoms**: 429 Too Many Requests errors
-
-**Solutions**:
-- Implement rate limiting in your custom LLM
-- Add exponential backoff for retries
-- Consider using a token bucket algorithm for more precise rate control
-
-## Advanced Features
-
-### Logging
-
-Adding logging to your custom LLM can help with debugging and monitoring:
-
-```python
-import logging
-from typing import Any, Dict, List, Optional, Union
-
-class LoggingLLM(BaseLLM):
-    def __init__(self, api_key: str, endpoint: str):
-        super().__init__()
-        self.api_key = api_key
-        self.endpoint = endpoint
-        self.logger = logging.getLogger("crewai.llm.custom")
-        
-    def call(
-        self,
-        messages: Union[str, List[Dict[str, str]]],
-        tools: Optional[List[dict]] = None,
-        callbacks: Optional[List[Any]] = None,
-        available_functions: Optional[Dict[str, Any]] = None,
-    ) -> Union[str, Any]:
-        self.logger.info(f"Calling LLM with {len(messages) if isinstance(messages, list) else 1} messages")
-        try:
-            # API call implementation
-            response = self._make_api_call(messages, tools)
-            self.logger.debug(f"LLM response received: {response[:100]}...")
-            return response
-        except Exception as e:
-            self.logger.error(f"LLM call failed: {str(e)}")
-            raise
-```
-
-### Rate Limiting
-
-Implementing rate limiting can help avoid overwhelming the LLM API:
-
-```python
-import time
-from typing import Any, Dict, List, Optional, Union
-
-class RateLimitedLLM(BaseLLM):
-    def __init__(
-        self, 
-        api_key: str, 
-        endpoint: str, 
-        requests_per_minute: int = 60
-    ):
-        super().__init__()
-        self.api_key = api_key
-        self.endpoint = endpoint
-        self.requests_per_minute = requests_per_minute
-        self.request_times: List[float] = []
-        
-    def call(
-        self,
-        messages: Union[str, List[Dict[str, str]]],
-        tools: Optional[List[dict]] = None,
-        callbacks: Optional[List[Any]] = None,
-        available_functions: Optional[Dict[str, Any]] = None,
-    ) -> Union[str, Any]:
-        self._enforce_rate_limit()
-        # Record this request time
-        self.request_times.append(time.time())
-        # Make the actual API call
-        return self._make_api_call(messages, tools)
-        
-    def _enforce_rate_limit(self) -> None:
-        """Enforce the rate limit by waiting if necessary."""
-        now = time.time()
-        # Remove request times older than 1 minute
-        self.request_times = [t for t in self.request_times if now - t < 60]
-        
-        if len(self.request_times) >= self.requests_per_minute:
-            # Calculate how long to wait
-            oldest_request = min(self.request_times)
-            wait_time = 60 - (now - oldest_request)
-            if wait_time > 0:
-                time.sleep(wait_time)
-```
-
-### Metrics Collection
-
-Collecting metrics can help you monitor your LLM usage:
-
-```python
-import time
-from typing import Any, Dict, List, Optional, Union
-
-class MetricsCollectingLLM(BaseLLM):
-    def __init__(self, api_key: str, endpoint: str):
-        super().__init__()
-        self.api_key = api_key
-        self.endpoint = endpoint
-        self.metrics: Dict[str, Any] = {
-            "total_calls": 0,
-            "total_tokens": 0,
-            "errors": 0,
-            "latency": []
-        }
-        
-    def call(
-        self,
-        messages: Union[str, List[Dict[str, str]]],
-        tools: Optional[List[dict]] = None,
-        callbacks: Optional[List[Any]] = None,
-        available_functions: Optional[Dict[str, Any]] = None,
-    ) -> Union[str, Any]:
-        start_time = time.time()
-        self.metrics["total_calls"] += 1
-        
-        try:
-            response = self._make_api_call(messages, tools)
-            # Estimate tokens (simplified)
-            if isinstance(messages, str):
-                token_estimate = len(messages) // 4
-            else:
-                token_estimate = sum(len(m.get("content", "")) // 4 for m in messages)
-            self.metrics["total_tokens"] += token_estimate
-            return response
-        except Exception as e:
-            self.metrics["errors"] += 1
-            raise
-        finally:
-            latency = time.time() - start_time
-            self.metrics["latency"].append(latency)
-            
-    def get_metrics(self) -> Dict[str, Any]:
-        """Return the collected metrics."""
-        avg_latency = sum(self.metrics["latency"]) / len(self.metrics["latency"]) if self.metrics["latency"] else 0
-        return {
-            **self.metrics,
-            "avg_latency": avg_latency
-        }
-```
-
-## Advanced Usage: Function Calling
-
-If your LLM supports function calling, you can implement the function calling logic in your custom LLM:
-
-```python
-import json
-from typing import Any, Dict, List, Optional, Union
-
-def call(
-    self,
-    messages: Union[str, List[Dict[str, str]]],
-    tools: Optional[List[dict]] = None,
-    callbacks: Optional[List[Any]] = None,
-    available_functions: Optional[Dict[str, Any]] = None,
-) -> Union[str, Any]:
-    import requests
-    
-    try:
-        headers = {
-            "Authorization": f"Bearer {self.jwt_token}",
-            "Content-Type": "application/json"
-        }
-        
-        # Convert string message to proper format if needed
-        if isinstance(messages, str):
-            messages = [{"role": "user", "content": messages}]
-        
-        data = {
-            "messages": messages,
-            "tools": tools
-        }
-        
-        response = requests.post(
-            self.endpoint,
-            headers=headers,
-            json=data,
-            timeout=30
-        )
-        response.raise_for_status()
-        response_data = response.json()
-        
-        # Check if the LLM wants to call a function
-        if response_data["choices"][0]["message"].get("tool_calls"):
-            tool_calls = response_data["choices"][0]["message"]["tool_calls"]
-            
-            # Process each tool call
-            for tool_call in tool_calls:
-                function_name = tool_call["function"]["name"]
-                function_args = json.loads(tool_call["function"]["arguments"])
-                
-                if available_functions and function_name in available_functions:
-                    function_to_call = available_functions[function_name]
-                    function_response = function_to_call(**function_args)
-                    
-                    # Add the function response to the messages
-                    messages.append({
-                        "role": "tool",
-                        "tool_call_id": tool_call["id"],
-                        "name": function_name,
-                        "content": str(function_response)
-                    })
-            
-            # Call the LLM again with the updated messages
-            return self.call(messages, tools, callbacks, available_functions)
-        
-        # Return the text response if no function call
-        return response_data["choices"][0]["message"]["content"]
-    except requests.Timeout:
-        raise TimeoutError("LLM request timed out")
-    except requests.RequestException as e:
-        raise RuntimeError(f"LLM request failed: {str(e)}")
-    except (KeyError, IndexError, ValueError) as e:
-        raise ValueError(f"Invalid response format: {str(e)}")
-```
-
-## Using Your Custom LLM with CrewAI
-
-Once you've implemented your custom LLM, you can use it with CrewAI agents and crews:
-
-```python
-from crewai import Agent, Task, Crew
-from typing import Dict, Any
-
-# Create your custom LLM instance
-jwt_llm = JWTAuthLLM(
-    jwt_token="your.jwt.token", 
-    endpoint="https://your-llm-endpoint.com/v1/chat/completions"
-)
-
-# Use it with an agent
-agent = Agent(
-    role="Research Assistant",
-    goal="Find information on a topic",
-    backstory="You are a research assistant tasked with finding information.",
-    llm=jwt_llm,
-)
-
-# Create a task for the agent
-task = Task(
-    description="Research the benefits of exercise",
-    agent=agent,
-    expected_output="A summary of the benefits of exercise",
-)
-
-# Execute the task
-result = agent.execute_task(task)
-print(result)
-
-# Or use it with a crew
-crew = Crew(
-    agents=[agent],
-    tasks=[task],
-    manager_llm=jwt_llm,  # Use your custom LLM for the manager
-)
-
-# Run the crew
-result = crew.kickoff()
-print(result)
-```
-
-## Implementing Your Own Authentication Mechanism
-
-The `BaseLLM` class allows you to implement any authentication mechanism you need, not just JWT or API keys. You can use:
-
-- OAuth tokens
-- Client certificates
-- Custom headers
-- Session-based authentication
-- Any other authentication method required by your LLM provider
-
-Simply implement the appropriate authentication logic in your custom LLM class.

docs/how-to/portkey-observability.mdx

@@ -1,202 +0,0 @@
----
-title: Portkey Integration
-description: How to use Portkey with CrewAI
-icon: key
----
-
-<img src="https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/main/Portkey-CrewAI.png" alt="Portkey CrewAI Header Image" width="70%" />
-
-
-[Portkey](https://portkey.ai/?utm_source=crewai&utm_medium=crewai&utm_campaign=crewai) is a 2-line upgrade to make your CrewAI agents reliable, cost-efficient, and fast.
-
-Portkey adds 4 core production capabilities to any CrewAI agent:
-1. Routing to **200+ LLMs**
-2. Making each LLM call more robust
-3. Full-stack tracing & cost, performance analytics
-4. Real-time guardrails to enforce behavior
-
-## Getting Started
-
-<Steps>
-    <Step title="Install CrewAI and Portkey">
-    ```bash
-    pip install -qU crewai portkey-ai
-    ```
-    </Step>
-    <Step title="Configure the LLM Client">
-    To build CrewAI Agents with Portkey, you'll need two keys:
-    - **Portkey API Key**: Sign up on the [Portkey app](https://app.portkey.ai/?utm_source=crewai&utm_medium=crewai&utm_campaign=crewai) and copy your API key
-    - **Virtual Key**: Virtual Keys securely manage your LLM API keys in one place. Store your LLM provider API keys securely in Portkey's vault
-
-    ```python
-    from crewai import LLM
-    from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL
-
-    gpt_llm = LLM(
-        model="gpt-4",
-        base_url=PORTKEY_GATEWAY_URL,
-        api_key="dummy", # We are using Virtual key
-        extra_headers=createHeaders(
-            api_key="YOUR_PORTKEY_API_KEY",
-            virtual_key="YOUR_VIRTUAL_KEY", # Enter your Virtual key from Portkey
-        )
-    )
-    ```
-    </Step>
-    <Step title="Create and Run Your First Agent">
-    ```python
-    from crewai import Agent, Task, Crew
-
-    # Define your agents with roles and goals
-    coder = Agent(
-        role='Software developer',
-        goal='Write clear, concise code on demand',
-        backstory='An expert coder with a keen eye for software trends.',
-        llm=gpt_llm
-    )
-
-    # Create tasks for your agents
-    task1 = Task(
-        description="Define the HTML for making a simple website with heading- Hello World! Portkey is working!",
-        expected_output="A clear and concise HTML code",
-        agent=coder
-    )
-
-    # Instantiate your crew
-    crew = Crew(
-        agents=[coder],
-        tasks=[task1],
-    )
-
-    result = crew.kickoff()
-    print(result)
-    ```
-    </Step>
-</Steps>
-
-## Key Features
-
-| Feature | Description |
-|:--------|:------------|
-| 🌐 Multi-LLM Support | Access OpenAI, Anthropic, Gemini, Azure, and 250+ providers through a unified interface |
-| 🛡️ Production Reliability | Implement retries, timeouts, load balancing, and fallbacks |
-| 📊 Advanced Observability | Track 40+ metrics including costs, tokens, latency, and custom metadata |
-| 🔍 Comprehensive Logging | Debug with detailed execution traces and function call logs |
-| 🚧 Security Controls | Set budget limits and implement role-based access control |
-| 🔄 Performance Analytics | Capture and analyze feedback for continuous improvement |
-| 💾 Intelligent Caching | Reduce costs and latency with semantic or simple caching |
-
-
-## Production Features with Portkey Configs
-
-All features mentioned below are through Portkey's Config system. Portkey's Config system allows you to define routing strategies using simple JSON objects in your LLM API calls. You can create and manage Configs directly in your code or through the Portkey Dashboard. Each Config has a unique ID for easy reference.
-
-<Frame>
-    <img src="https://raw.githubusercontent.com/Portkey-AI/docs-core/refs/heads/main/images/libraries/libraries-3.avif"/>
-</Frame>
-
-
-### 1. Use 250+ LLMs
-Access various LLMs like Anthropic, Gemini, Mistral, Azure OpenAI, and more with minimal code changes. Switch between providers or use them together seamlessly. [Learn more about Universal API](https://portkey.ai/docs/product/ai-gateway/universal-api)
-
-
-Easily switch between different LLM providers:
-
-```python
-# Anthropic Configuration
-anthropic_llm = LLM(
-    model="claude-3-5-sonnet-latest",
-    base_url=PORTKEY_GATEWAY_URL,
-    api_key="dummy",
-    extra_headers=createHeaders(
-        api_key="YOUR_PORTKEY_API_KEY",
-        virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY", #You don't need provider when using Virtual keys
-        trace_id="anthropic_agent"
-    )
-)
-
-# Azure OpenAI Configuration
-azure_llm = LLM(
-    model="gpt-4",
-    base_url=PORTKEY_GATEWAY_URL,
-    api_key="dummy",
-    extra_headers=createHeaders(
-        api_key="YOUR_PORTKEY_API_KEY",
-        virtual_key="YOUR_AZURE_VIRTUAL_KEY", #You don't need provider when using Virtual keys
-        trace_id="azure_agent"
-    )
-)
-```
-
-
-### 2. Caching
-Improve response times and reduce costs with two powerful caching modes:
-- **Simple Cache**: Perfect for exact matches
-- **Semantic Cache**: Matches responses for requests that are semantically similar
-[Learn more about Caching](https://portkey.ai/docs/product/ai-gateway/cache-simple-and-semantic)
-
-```py
-config = {
-    "cache": {
-        "mode": "semantic",  # or "simple" for exact matching
-    }
-}
-```
-
-### 3. Production Reliability
-Portkey provides comprehensive reliability features:
-- **Automatic Retries**: Handle temporary failures gracefully
-- **Request Timeouts**: Prevent hanging operations
-- **Conditional Routing**: Route requests based on specific conditions
-- **Fallbacks**: Set up automatic provider failovers
-- **Load Balancing**: Distribute requests efficiently
-
-[Learn more about Reliability Features](https://portkey.ai/docs/product/ai-gateway/)
-
-
-
-### 4. Metrics
-
-Agent runs are complex. Portkey automatically logs **40+ comprehensive metrics** for your AI agents, including cost, tokens used, latency, etc. Whether you need a broad overview or granular insights into your agent runs, Portkey's customizable filters provide the metrics you need.
-
-
-- Cost per agent interaction
-- Response times and latency
-- Token usage and efficiency
-- Success/failure rates
-- Cache hit rates
-
-<img src="https://github.com/siddharthsambharia-portkey/Portkey-Product-Images/blob/main/Portkey-Dashboard.png?raw=true" width="70%" alt="Portkey Dashboard" />
-
-### 5. Detailed Logging
-Logs are essential for understanding agent behavior, diagnosing issues, and improving performance. They provide a detailed record of agent activities and tool use, which is crucial for debugging and optimizing processes.
-
-
-Access a dedicated section to view records of agent executions, including parameters, outcomes, function calls, and errors. Filter logs based on multiple parameters such as trace ID, model, tokens used, and metadata.
-
-<details>
-  <summary><b>Traces</b></summary>
-  <img src="https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/main/Portkey-Traces.png" alt="Portkey Traces" width="70%" />
-</details>
-
-<details>
-  <summary><b>Logs</b></summary>
-  <img src="https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/main/Portkey-Logs.png" alt="Portkey Logs" width="70%" />
-</details>
-
-### 6. Enterprise Security Features
-- Set budget limit and rate limts per Virtual Key (disposable API keys)
-- Implement role-based access control
-- Track system changes with audit logs
-- Configure data retention policies
-
-
-
-For detailed information on creating and managing Configs, visit the [Portkey documentation](https://docs.portkey.ai/product/ai-gateway/configs).
-
-## Resources
-
-- [📘 Portkey Documentation](https://docs.portkey.ai)
-- [📊 Portkey Dashboard](https://app.portkey.ai/?utm_source=crewai&utm_medium=crewai&utm_campaign=crewai)
-- [🐦 Twitter](https://twitter.com/portkeyai)
-- [💬 Discord Community](https://discord.gg/DD7vgKK299)

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.14`. Here's how to check your version:
   ```bash
   python3 --version
   ```

docs/introduction.mdx

@@ -23,7 +23,7 @@ With over 100,000 developers certified through our community courses, CrewAI is
 </Note>
 
 <Frame caption="CrewAI Framework Overview">
-  <img src="crews.png" alt="CrewAI Framework Overview" />
+  <img src="images/crews.png" alt="CrewAI Framework Overview" />
 </Frame>
 
 | Component | Description | Key Features |
@@ -64,7 +64,7 @@ With over 100,000 developers certified through our community courses, CrewAI is
 </Note>
 
 <Frame caption="CrewAI Framework Overview">
-  <img src="flows.png" alt="CrewAI Framework Overview" />
+  <img src="images/flows.png" alt="CrewAI Framework Overview" />
 </Frame>
 
 | Component | Description | Key Features |

docs/learn/custom-llm.mdx

@@ -0,0 +1,350 @@
+---
+title: Custom LLM Implementation
+description: Learn how to create custom LLM implementations in CrewAI.
+icon: code
+---
+
+## Overview
+
+CrewAI supports custom LLM implementations through the `BaseLLM` abstract base class. This allows you to integrate any LLM provider that doesn't have built-in support in LiteLLM, or implement custom authentication mechanisms.
+
+## Quick Start
+
+Here's a minimal custom LLM implementation:
+
+```python
+from crewai import BaseLLM
+from typing import Any, Dict, List, Optional, Union
+import requests
+
+class CustomLLM(BaseLLM):
+    def __init__(self, model: str, api_key: str, endpoint: str, temperature: Optional[float] = None):
+        # IMPORTANT: Call super().__init__() with required parameters
+        super().__init__(model=model, temperature=temperature)
+        
+        self.api_key = api_key
+        self.endpoint = endpoint
+        
+    def call(
+        self,
+        messages: Union[str, List[Dict[str, str]]],
+        tools: Optional[List[dict]] = None,
+        callbacks: Optional[List[Any]] = None,
+        available_functions: Optional[Dict[str, Any]] = None,
+    ) -> Union[str, Any]:
+        """Call the LLM with the given messages."""
+        # Convert string to message format if needed
+        if isinstance(messages, str):
+            messages = [{"role": "user", "content": messages}]
+        
+        # Prepare request
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": self.temperature,
+        }
+        
+        # Add tools if provided and supported
+        if tools and self.supports_function_calling():
+            payload["tools"] = tools
+        
+        # Make API call
+        response = requests.post(
+            self.endpoint,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json"
+            },
+            json=payload,
+            timeout=30
+        )
+        response.raise_for_status()
+        
+        result = response.json()
+        return result["choices"][0]["message"]["content"]
+        
+    def supports_function_calling(self) -> bool:
+        """Override if your LLM supports function calling."""
+        return True  # Change to False if your LLM doesn't support tools
+        
+    def get_context_window_size(self) -> int:
+        """Return the context window size of your LLM."""
+        return 8192  # Adjust based on your model's actual context window
+```
+
+## Using Your Custom LLM
+
+```python
+from crewai import Agent, Task, Crew
+
+# Assuming you have the CustomLLM class defined above
+# Create your custom LLM
+custom_llm = CustomLLM(
+    model="my-custom-model",
+    api_key="your-api-key",
+    endpoint="https://api.example.com/v1/chat/completions",
+    temperature=0.7
+)
+
+# Use with an agent
+agent = Agent(
+    role="Research Assistant",
+    goal="Find and analyze information",
+    backstory="You are a research assistant.",
+    llm=custom_llm
+)
+
+# Create and execute tasks
+task = Task(
+    description="Research the latest developments in AI",
+    expected_output="A comprehensive summary",
+    agent=agent
+)
+
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+## Required Methods
+
+### Constructor: `__init__()`
+
+**Critical**: You must call `super().__init__(model, temperature)` with the required parameters:
+
+```python
+def __init__(self, model: str, api_key: str, temperature: Optional[float] = None):
+    # REQUIRED: Call parent constructor with model and temperature
+    super().__init__(model=model, temperature=temperature)
+    
+    # Your custom initialization
+    self.api_key = api_key
+```
+
+### Abstract Method: `call()`
+
+The `call()` method is the heart of your LLM implementation. It must:
+
+- Accept messages (string or list of dicts with 'role' and 'content')
+- Return a string response
+- Handle tools and function calling if supported
+- Raise appropriate exceptions for errors
+
+### Optional Methods
+
+```python
+def supports_function_calling(self) -> bool:
+    """Return True if your LLM supports function calling."""
+    return True  # Default is True
+
+def supports_stop_words(self) -> bool:
+    """Return True if your LLM supports stop sequences."""
+    return True  # Default is True
+
+def get_context_window_size(self) -> int:
+    """Return the context window size."""
+    return 4096  # Default is 4096
+```
+
+## Common Patterns
+
+### Error Handling
+
+```python
+import requests
+
+def call(self, messages, tools=None, callbacks=None, available_functions=None):
+    try:
+        response = requests.post(
+            self.endpoint,
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            json=payload,
+            timeout=30
+        )
+        response.raise_for_status()
+        return response.json()["choices"][0]["message"]["content"]
+        
+    except requests.Timeout:
+        raise TimeoutError("LLM request timed out")
+    except requests.RequestException as e:
+        raise RuntimeError(f"LLM request failed: {str(e)}")
+    except (KeyError, IndexError) as e:
+        raise ValueError(f"Invalid response format: {str(e)}")
+```
+
+### Custom Authentication
+
+```python
+from crewai import BaseLLM
+from typing import Optional
+
+class CustomAuthLLM(BaseLLM):
+    def __init__(self, model: str, auth_token: str, endpoint: str, temperature: Optional[float] = None):
+        super().__init__(model=model, temperature=temperature)
+        self.auth_token = auth_token
+        self.endpoint = endpoint
+    
+    def call(self, messages, tools=None, callbacks=None, available_functions=None):
+        headers = {
+            "Authorization": f"Custom {self.auth_token}",  # Custom auth format
+            "Content-Type": "application/json"
+        }
+        # Rest of implementation...
+```
+
+### Stop Words Support
+
+CrewAI automatically adds `"\nObservation:"` as a stop word to control agent behavior. If your LLM supports stop words:
+
+```python
+def call(self, messages, tools=None, callbacks=None, available_functions=None):
+    payload = {
+        "model": self.model,
+        "messages": messages,
+        "stop": self.stop  # Include stop words in API call
+    }
+    # Make API call...
+
+def supports_stop_words(self) -> bool:
+    return True  # Your LLM supports stop sequences
+```
+
+If your LLM doesn't support stop words natively:
+
+```python
+def call(self, messages, tools=None, callbacks=None, available_functions=None):
+    response = self._make_api_call(messages, tools)
+    content = response["choices"][0]["message"]["content"]
+    
+    # Manually truncate at stop words
+    if self.stop:
+        for stop_word in self.stop:
+            if stop_word in content:
+                content = content.split(stop_word)[0]
+                break
+    
+    return content
+
+def supports_stop_words(self) -> bool:
+    return False  # Tell CrewAI we handle stop words manually
+```
+
+## Function Calling
+
+If your LLM supports function calling, implement the complete flow:
+
+```python
+import json
+
+def call(self, messages, tools=None, callbacks=None, available_functions=None):
+    # Convert string to message format
+    if isinstance(messages, str):
+        messages = [{"role": "user", "content": messages}]
+    
+    # Make API call
+    response = self._make_api_call(messages, tools)
+    message = response["choices"][0]["message"]
+    
+    # Check for function calls
+    if "tool_calls" in message and available_functions:
+        return self._handle_function_calls(
+            message["tool_calls"], messages, tools, available_functions
+        )
+    
+    return message["content"]
+
+def _handle_function_calls(self, tool_calls, messages, tools, available_functions):
+    """Handle function calling with proper message flow."""
+    for tool_call in tool_calls:
+        function_name = tool_call["function"]["name"]
+        
+        if function_name in available_functions:
+            # Parse and execute function
+            function_args = json.loads(tool_call["function"]["arguments"])
+            function_result = available_functions[function_name](**function_args)
+            
+            # Add function call and result to message history
+            messages.append({
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [tool_call]
+            })
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tool_call["id"],
+                "name": function_name,
+                "content": str(function_result)
+            })
+            
+            # Call LLM again with updated context
+            return self.call(messages, tools, None, available_functions)
+    
+    return "Function call failed"
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Constructor Errors**
+```python
+# ❌ Wrong - missing required parameters
+def __init__(self, api_key: str):
+    super().__init__()
+
+# ✅ Correct
+def __init__(self, model: str, api_key: str, temperature: Optional[float] = None):
+    super().__init__(model=model, temperature=temperature)
+```
+
+**Function Calling Not Working**
+- Ensure `supports_function_calling()` returns `True`
+- Check that you handle `tool_calls` in the response
+- Verify `available_functions` parameter is used correctly
+
+**Authentication Failures**
+- Verify API key format and permissions
+- Check authentication header format
+- Ensure endpoint URLs are correct
+
+**Response Parsing Errors**
+- Validate response structure before accessing nested fields
+- Handle cases where content might be None
+- Add proper error handling for malformed responses
+
+## Testing Your Custom LLM
+
+```python
+from crewai import Agent, Task, Crew
+
+def test_custom_llm():
+    llm = CustomLLM(
+        model="test-model",
+        api_key="test-key",
+        endpoint="https://api.test.com"
+    )
+    
+    # Test basic call
+    result = llm.call("Hello, world!")
+    assert isinstance(result, str)
+    assert len(result) > 0
+    
+    # Test with CrewAI agent
+    agent = Agent(
+        role="Test Agent",
+        goal="Test custom LLM",
+        backstory="A test agent.",
+        llm=llm
+    )
+    
+    task = Task(
+        description="Say hello",
+        expected_output="A greeting",
+        agent=agent
+    )
+    
+    crew = Crew(agents=[agent], tasks=[task])
+    result = crew.kickoff()
+    assert "hello" in result.raw.lower()
+```
+
+This guide covers the essentials of implementing custom LLMs in CrewAI.

docs/learn/dalle-image-generation.mdx

@@ -0,0 +1,73 @@
+---
+title: "Image Generation with DALL-E"
+description: "Learn how to use DALL-E for AI-powered image generation in your CrewAI projects"
+icon: "image"
+---
+
+CrewAI supports integration with OpenAI's DALL-E, allowing your AI agents to generate images as part of their tasks. This guide will walk you through how to set up and use the DALL-E tool in your CrewAI projects.
+
+## Prerequisites
+
+- crewAI installed (latest version)
+- OpenAI API key with access to DALL-E
+
+## Setting Up the DALL-E Tool
+
+<Steps>
+    <Step title="Import the DALL-E tool">
+        ```python
+        from crewai_tools import DallETool
+        ```
+    </Step>
+
+    <Step title="Add the DALL-E tool to your agent configuration">
+        ```python
+        @agent
+        def researcher(self) -> Agent:
+            return Agent(
+                config=self.agents_config['researcher'],
+                tools=[SerperDevTool(), DallETool()],  # Add DallETool to the list of tools
+                allow_delegation=False,
+                verbose=True
+            )
+        ```
+    </Step>
+</Steps>
+
+## Using the DALL-E Tool
+
+Once you've added the DALL-E tool to your agent, it can generate images based on text prompts. The tool will return a URL to the generated image, which can be used in the agent's output or passed to other agents for further processing.
+
+### Example Agent Configuration
+
+```yaml
+role: >
+    LinkedIn Profile Senior Data Researcher
+goal: >
+    Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
+    Generate a Dall-e image based on domain {domain}
+backstory: >
+    You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
+    Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
+    professional information clearly and concisely.
+```
+
+### Expected Output
+
+The agent with the DALL-E tool will be able to generate the image and provide a URL in its response. You can then download the image.
+
+<Frame>
+    <img src="/images/enterprise/dall-e-image.png" alt="DALL-E Image" />
+</Frame>
+
+## Best Practices
+
+1. **Be specific in your image generation prompts** to get the best results.
+2. **Consider generation time** - Image generation can take some time, so factor this into your task planning.
+3. **Follow usage policies** - Always comply with OpenAI's usage policies when generating images.
+
+## Troubleshooting
+
+1. **Check API access** - Ensure your OpenAI API key has access to DALL-E.
+2. **Version compatibility** - Check that you're using the latest version of crewAI and crewai-tools.
+3. **Tool configuration** - Verify that the DALL-E tool is correctly added to the agent's tool list. 

docs/learn/human-in-the-loop.mdx

@@ -0,0 +1,78 @@
+---
+title: "Human-in-the-Loop (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/learn/kickoff-async.mdx

@@ -108,6 +108,7 @@ crew_2 = Crew(agents=[coding_agent], tasks=[task_2])
 
 # Async function to kickoff multiple crews asynchronously and wait for all to finish
 async def async_multiple_crews():
+    # Create coroutines for concurrent execution
     result_1 = crew_1.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]})
     result_2 = crew_2.kickoff_async(inputs={"ages": [20, 22, 24, 28, 30]})
 

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/learn/llm-selection-guide.mdx

@@ -0,0 +1,729 @@
+---
+title: 'Strategic LLM Selection Guide'
+description: 'Strategic framework for choosing the right LLM for your CrewAI AI agents and writing effective task and agent definitions'
+icon: 'brain-circuit'
+---
+
+## The CrewAI Approach to LLM Selection
+
+Rather than prescriptive model recommendations, we advocate for a **thinking framework** that helps you make informed decisions based on your specific use case, constraints, and requirements. The LLM landscape evolves rapidly, with new models emerging regularly and existing ones being updated frequently. What matters most is developing a systematic approach to evaluation that remains relevant regardless of which specific models are available.
+
+<Note>
+This guide focuses on strategic thinking rather than specific model recommendations, as the LLM landscape evolves rapidly.
+</Note>
+
+## Quick Decision Framework
+
+<Steps>
+  <Step title="Analyze Your Tasks">
+    Begin by deeply understanding what your tasks actually require. Consider the cognitive complexity involved, the depth of reasoning needed, the format of expected outputs, and the amount of context the model will need to process. This foundational analysis will guide every subsequent decision.
+  </Step>
+  <Step title="Map Model Capabilities">
+    Once you understand your requirements, map them to model strengths. Different model families excel at different types of work; some are optimized for reasoning and analysis, others for creativity and content generation, and others for speed and efficiency.
+  </Step>
+  <Step title="Consider Constraints">
+    Factor in your real-world operational constraints including budget limitations, latency requirements, data privacy needs, and infrastructure capabilities. The theoretically best model may not be the practically best choice for your situation.
+  </Step>
+  <Step title="Test and Iterate">
+    Start with reliable, well-understood models and optimize based on actual performance in your specific use case. Real-world results often differ from theoretical benchmarks, so empirical testing is crucial.
+  </Step>
+</Steps>
+
+## Core Selection Framework
+
+### a. Task-First Thinking
+
+The most critical step in LLM selection is understanding what your task actually demands. Too often, teams select models based on general reputation or benchmark scores without carefully analyzing their specific requirements. This approach leads to either over-engineering simple tasks with expensive, complex models, or under-powering sophisticated work with models that lack the necessary capabilities.
+
+<Tabs>
+  <Tab title="Reasoning Complexity">
+    - **Simple Tasks** represent the majority of everyday AI work and include basic instruction following, straightforward data processing, and simple formatting operations. These tasks typically have clear inputs and outputs with minimal ambiguity. The cognitive load is low, and the model primarily needs to follow explicit instructions rather than engage in complex reasoning.
+
+    - **Complex Tasks** require multi-step reasoning, strategic thinking, and the ability to handle ambiguous or incomplete information. These might involve analyzing multiple data sources, developing comprehensive strategies, or solving problems that require breaking down into smaller components. The model needs to maintain context across multiple reasoning steps and often must make inferences that aren't explicitly stated.
+
+    - **Creative Tasks** demand a different type of cognitive capability focused on generating novel, engaging, and contextually appropriate content. This includes storytelling, marketing copy creation, and creative problem-solving. The model needs to understand nuance, tone, and audience while producing content that feels authentic and engaging rather than formulaic.
+  </Tab>
+  
+  <Tab title="Output Requirements">
+    - **Structured Data** tasks require precision and consistency in format adherence. When working with JSON, XML, or database formats, the model must reliably produce syntactically correct output that can be programmatically processed. These tasks often have strict validation requirements and little tolerance for format errors, making reliability more important than creativity.
+
+    - **Creative Content** outputs demand a balance of technical competence and creative flair. The model needs to understand audience, tone, and brand voice while producing content that engages readers and achieves specific communication goals. Quality here is often subjective and requires models that can adapt their writing style to different contexts and purposes.
+
+    - **Technical Content** sits between structured data and creative content, requiring both precision and clarity. Documentation, code generation, and technical analysis need to be accurate and comprehensive while remaining accessible to the intended audience. The model must understand complex technical concepts and communicate them effectively.
+  </Tab>
+  
+  <Tab title="Context Needs">
+    - **Short Context** scenarios involve focused, immediate tasks where the model needs to process limited information quickly. These are often transactional interactions where speed and efficiency matter more than deep understanding. The model doesn't need to maintain extensive conversation history or process large documents.
+
+    - **Long Context** requirements emerge when working with substantial documents, extended conversations, or complex multi-part tasks. The model needs to maintain coherence across thousands of tokens while referencing earlier information accurately. This capability becomes crucial for document analysis, comprehensive research, and sophisticated dialogue systems.
+
+    - **Very Long Context** scenarios push the boundaries of what's currently possible, involving massive document processing, extensive research synthesis, or complex multi-session interactions. These use cases require models specifically designed for extended context handling and often involve trade-offs between context length and processing speed.
+  </Tab>
+</Tabs>
+
+### b. Model Capability Mapping
+
+Understanding model capabilities requires looking beyond marketing claims and benchmark scores to understand the fundamental strengths and limitations of different model architectures and training approaches.
+
+<AccordionGroup>
+  <Accordion title="Reasoning Models" icon="brain">
+    Reasoning models represent a specialized category designed specifically for complex, multi-step thinking tasks. These models excel when problems require careful analysis, strategic planning, or systematic problem decomposition. They typically employ techniques like chain-of-thought reasoning or tree-of-thought processing to work through complex problems step by step.
+
+    The strength of reasoning models lies in their ability to maintain logical consistency across extended reasoning chains and to break down complex problems into manageable components. They're particularly valuable for strategic planning, complex analysis, and situations where the quality of reasoning matters more than speed of response.
+
+    However, reasoning models often come with trade-offs in terms of speed and cost. They may also be less suitable for creative tasks or simple operations where their sophisticated reasoning capabilities aren't needed. Consider these models when your tasks involve genuine complexity that benefits from systematic, step-by-step analysis.
+  </Accordion>
+  
+  <Accordion title="General Purpose Models" icon="microchip">
+    General purpose models offer the most balanced approach to LLM selection, providing solid performance across a wide range of tasks without extreme specialization in any particular area. These models are trained on diverse datasets and optimized for versatility rather than peak performance in specific domains.
+
+    The primary advantage of general purpose models is their reliability and predictability across different types of work. They handle most standard business tasks competently, from research and analysis to content creation and data processing. This makes them excellent choices for teams that need consistent performance across varied workflows.
+
+    While general purpose models may not achieve the peak performance of specialized alternatives in specific domains, they offer operational simplicity and reduced complexity in model management. They're often the best starting point for new projects, allowing teams to understand their specific needs before potentially optimizing with more specialized models.
+  </Accordion>
+  
+  <Accordion title="Fast & Efficient Models" icon="bolt">
+    Fast and efficient models prioritize speed, cost-effectiveness, and resource efficiency over sophisticated reasoning capabilities. These models are optimized for high-throughput scenarios where quick responses and low operational costs are more important than nuanced understanding or complex reasoning.
+
+    These models excel in scenarios involving routine operations, simple data processing, function calling, and high-volume tasks where the cognitive requirements are relatively straightforward. They're particularly valuable for applications that need to process many requests quickly or operate within tight budget constraints.
+
+    The key consideration with efficient models is ensuring that their capabilities align with your task requirements. While they can handle many routine operations effectively, they may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. They're best used for well-defined, routine operations where speed and cost matter more than sophistication.
+  </Accordion>
+  
+  <Accordion title="Creative Models" icon="pen">
+    Creative models are specifically optimized for content generation, writing quality, and creative thinking tasks. These models typically excel at understanding nuance, tone, and style while producing engaging, contextually appropriate content that feels natural and authentic.
+
+    The strength of creative models lies in their ability to adapt writing style to different audiences, maintain consistent voice and tone, and generate content that engages readers effectively. They often perform better on tasks involving storytelling, marketing copy, brand communications, and other content where creativity and engagement are primary goals.
+
+    When selecting creative models, consider not just their ability to generate text, but their understanding of audience, context, and purpose. The best creative models can adapt their output to match specific brand voices, target different audience segments, and maintain consistency across extended content pieces.
+  </Accordion>
+  
+  <Accordion title="Open Source Models" icon="code">
+    Open source models offer unique advantages in terms of cost control, customization potential, data privacy, and deployment flexibility. These models can be run locally or on private infrastructure, providing complete control over data handling and model behavior.
+
+    The primary benefits of open source models include elimination of per-token costs, ability to fine-tune for specific use cases, complete data privacy, and independence from external API providers. They're particularly valuable for organizations with strict data privacy requirements, budget constraints, or specific customization needs.
+
+    However, open source models require more technical expertise to deploy and maintain effectively. Teams need to consider infrastructure costs, model management complexity, and the ongoing effort required to keep models updated and optimized. The total cost of ownership may be higher than cloud-based alternatives when factoring in technical overhead.
+  </Accordion>
+</AccordionGroup>
+
+## Strategic Configuration Patterns
+
+### a. Multi-Model Approach
+
+<Tip>
+Use different models for different purposes within the same crew to optimize both performance and cost.
+</Tip>
+
+The most sophisticated CrewAI implementations often employ multiple models strategically, assigning different models to different agents based on their specific roles and requirements. This approach allows teams to optimize for both performance and cost by using the most appropriate model for each type of work.
+
+Planning agents benefit from reasoning models that can handle complex strategic thinking and multi-step analysis. These agents often serve as the "brain" of the operation, developing strategies and coordinating other agents' work. Content agents, on the other hand, perform best with creative models that excel at writing quality and audience engagement. Processing agents handling routine operations can use efficient models that prioritize speed and cost-effectiveness.
+
+**Example: Research and Analysis Crew**
+
+```python
+from crewai import Agent, Task, Crew, LLM
+
+# High-capability reasoning model for strategic planning
+manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1)
+
+# Creative model for content generation
+content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7)
+
+# Efficient model for data processing
+processing_llm = LLM(model="gpt-4o-mini", temperature=0)
+
+research_manager = Agent(
+    role="Research Strategy Manager",
+    goal="Develop comprehensive research strategies and coordinate team efforts",
+    backstory="Expert research strategist with deep analytical capabilities",
+    llm=manager_llm,  # High-capability model for complex reasoning
+    verbose=True
+)
+
+content_writer = Agent(
+    role="Research Content Writer",
+    goal="Transform research findings into compelling, well-structured reports",
+    backstory="Skilled writer who excels at making complex topics accessible",
+    llm=content_llm,  # Creative model for engaging content
+    verbose=True
+)
+
+data_processor = Agent(
+    role="Data Analysis Specialist", 
+    goal="Extract and organize key data points from research sources",
+    backstory="Detail-oriented analyst focused on accuracy and efficiency",
+    llm=processing_llm,  # Fast, cost-effective model for routine tasks
+    verbose=True
+)
+
+crew = Crew(
+    agents=[research_manager, content_writer, data_processor],
+    tasks=[...],  # Your specific tasks
+    manager_llm=manager_llm,  # Manager uses the reasoning model
+    verbose=True
+)
+```
+
+The key to successful multi-model implementation is understanding how different agents interact and ensuring that model capabilities align with agent responsibilities. This requires careful planning but can result in significant improvements in both output quality and operational efficiency.
+
+### b. Component-Specific Selection
+
+<Tabs>
+  <Tab title="Manager LLM">
+    The manager LLM plays a crucial role in hierarchical CrewAI processes, serving as the coordination point for multiple agents and tasks. This model needs to excel at delegation, task prioritization, and maintaining context across multiple concurrent operations.
+
+    Effective manager LLMs require strong reasoning capabilities to make good delegation decisions, consistent performance to ensure predictable coordination, and excellent context management to track the state of multiple agents simultaneously. The model needs to understand the capabilities and limitations of different agents while optimizing task allocation for efficiency and quality.
+
+    Cost considerations are particularly important for manager LLMs since they're involved in every operation. The model needs to provide sufficient capability for effective coordination while remaining cost-effective for frequent use. This often means finding models that offer good reasoning capabilities without the premium pricing of the most sophisticated options.
+  </Tab>
+  
+  <Tab title="Function Calling LLM">
+    Function calling LLMs handle tool usage across all agents, making them critical for crews that rely heavily on external tools and APIs. These models need to excel at understanding tool capabilities, extracting parameters accurately, and handling tool responses effectively.
+
+    The most important characteristics for function calling LLMs are precision and reliability rather than creativity or sophisticated reasoning. The model needs to consistently extract the correct parameters from natural language requests and handle tool responses appropriately. Speed is also important since tool usage often involves multiple round trips that can impact overall performance.
+
+    Many teams find that specialized function calling models or general purpose models with strong tool support work better than creative or reasoning-focused models for this role. The key is ensuring that the model can reliably bridge the gap between natural language instructions and structured tool calls.
+  </Tab>
+  
+  <Tab title="Agent-Specific Overrides">
+    Individual agents can override crew-level LLM settings when their specific needs differ significantly from the general crew requirements. This capability allows for fine-tuned optimization while maintaining operational simplicity for most agents.
+
+    Consider agent-specific overrides when an agent's role requires capabilities that differ substantially from other crew members. For example, a creative writing agent might benefit from a model optimized for content generation, while a data analysis agent might perform better with a reasoning-focused model.
+
+    The challenge with agent-specific overrides is balancing optimization with operational complexity. Each additional model adds complexity to deployment, monitoring, and cost management. Teams should focus overrides on agents where the performance improvement justifies the additional complexity.
+  </Tab>
+</Tabs>
+
+## Task Definition Framework
+
+### a. Focus on Clarity Over Complexity
+
+Effective task definition is often more important than model selection in determining the quality of CrewAI outputs. Well-defined tasks provide clear direction and context that enable even modest models to perform well, while poorly defined tasks can cause even sophisticated models to produce unsatisfactory results.
+
+<AccordionGroup>
+  <Accordion title="Effective Task Descriptions" icon="list-check">
+    The best task descriptions strike a balance between providing sufficient detail and maintaining clarity. They should define the specific objective clearly enough that there's no ambiguity about what success looks like, while explaining the approach or methodology in enough detail that the agent understands how to proceed.
+
+    Effective task descriptions include relevant context and constraints that help the agent understand the broader purpose and any limitations they need to work within. They break complex work into focused steps that can be executed systematically, rather than presenting overwhelming, multi-faceted objectives that are difficult to approach systematically.
+
+    Common mistakes include being too vague about objectives, failing to provide necessary context, setting unclear success criteria, or combining multiple unrelated tasks into a single description. The goal is to provide enough information for the agent to succeed while maintaining focus on a single, clear objective.
+  </Accordion>
+  
+  <Accordion title="Expected Output Guidelines" icon="bullseye">
+    Expected output guidelines serve as a contract between the task definition and the agent, clearly specifying what the deliverable should look like and how it will be evaluated. These guidelines should describe both the format and structure needed, as well as the key elements that must be included for the output to be considered complete.
+
+    The best output guidelines provide concrete examples of quality indicators and define completion criteria clearly enough that both the agent and human reviewers can assess whether the task has been completed successfully. This reduces ambiguity and helps ensure consistent results across multiple task executions.
+
+    Avoid generic output descriptions that could apply to any task, missing format specifications that leave agents guessing about structure, unclear quality standards that make evaluation difficult, or failing to provide examples or templates that help agents understand expectations.
+  </Accordion>
+</AccordionGroup>
+
+### b. Task Sequencing Strategy
+
+<Tabs>
+  <Tab title="Sequential Dependencies">
+    Sequential task dependencies are essential when tasks build upon previous outputs, information flows from one task to another, or quality depends on the completion of prerequisite work. This approach ensures that each task has access to the information and context it needs to succeed.
+
+    Implementing sequential dependencies effectively requires using the context parameter to chain related tasks, building complexity gradually through task progression, and ensuring that each task produces outputs that serve as meaningful inputs for subsequent tasks. The goal is to maintain logical flow between dependent tasks while avoiding unnecessary bottlenecks.
+
+    Sequential dependencies work best when there's a clear logical progression from one task to another and when the output of one task genuinely improves the quality or feasibility of subsequent tasks. However, they can create bottlenecks if not managed carefully, so it's important to identify which dependencies are truly necessary versus those that are merely convenient.
+  </Tab>
+  
+  <Tab title="Parallel Execution">
+    Parallel execution becomes valuable when tasks are independent of each other, time efficiency is important, or different expertise areas are involved that don't require coordination. This approach can significantly reduce overall execution time while allowing specialized agents to work on their areas of strength simultaneously.
+
+    Successful parallel execution requires identifying tasks that can truly run independently, grouping related but separate work streams effectively, and planning for result integration when parallel tasks need to be combined into a final deliverable. The key is ensuring that parallel tasks don't create conflicts or redundancies that reduce overall quality.
+
+    Consider parallel execution when you have multiple independent research streams, different types of analysis that don't depend on each other, or content creation tasks that can be developed simultaneously. However, be mindful of resource allocation and ensure that parallel execution doesn't overwhelm your available model capacity or budget.
+  </Tab>
+</Tabs>
+
+## Optimizing Agent Configuration for LLM Performance
+
+### a. Role-Driven LLM Selection
+
+<Warning>
+Generic agent roles make it impossible to select the right LLM. Specific roles enable targeted model optimization.
+</Warning>
+
+The specificity of your agent roles directly determines which LLM capabilities matter most for optimal performance. This creates a strategic opportunity to match precise model strengths with agent responsibilities.
+
+**Generic vs. Specific Role Impact on LLM Choice:**
+
+When defining roles, think about the specific domain knowledge, working style, and decision-making frameworks that would be most valuable for the tasks the agent will handle. The more specific and contextual the role definition, the better the model can embody that role effectively.
+```python
+# ✅ Specific role - clear LLM requirements
+specific_agent = Agent(
+    role="SaaS Revenue Operations Analyst",  # Clear domain expertise needed
+    goal="Analyze recurring revenue metrics and identify growth opportunities",
+    backstory="Specialist in SaaS business models with deep understanding of ARR, churn, and expansion revenue",
+    llm=LLM(model="gpt-4o")  # Reasoning model justified for complex analysis
+)
+```
+
+**Role-to-Model Mapping Strategy:**
+
+- **"Research Analyst"** → Reasoning model (GPT-4o, Claude Sonnet) for complex analysis
+- **"Content Editor"** → Creative model (Claude, GPT-4o) for writing quality
+- **"Data Processor"** → Efficient model (GPT-4o-mini, Gemini Flash) for structured tasks
+- **"API Coordinator"** → Function-calling optimized model (GPT-4o, Claude) for tool usage
+
+### b. Backstory as Model Context Amplifier
+
+<Info>
+Strategic backstories multiply your chosen LLM's effectiveness by providing domain-specific context that generic prompting cannot achieve.
+</Info>
+
+A well-crafted backstory transforms your LLM choice from generic capability to specialized expertise. This is especially crucial for cost optimization - a well-contextualized efficient model can outperform a premium model without proper context.
+
+**Context-Driven Performance Example:**
+
+```python
+# Context amplifies model effectiveness
+domain_expert = Agent(
+    role="B2B SaaS Marketing Strategist",
+    goal="Develop comprehensive go-to-market strategies for enterprise software",
+    backstory="""
+    You have 10+ years of experience scaling B2B SaaS companies from Series A to IPO. 
+    You understand the nuances of enterprise sales cycles, the importance of product-market 
+    fit in different verticals, and how to balance growth metrics with unit economics. 
+    You've worked with companies like Salesforce, HubSpot, and emerging unicorns, giving 
+    you perspective on both established and disruptive go-to-market strategies.
+    """,
+    llm=LLM(model="claude-3-5-sonnet", temperature=0.3)  # Balanced creativity with domain knowledge
+)
+
+# This context enables Claude to perform like a domain expert
+# Without it, even it would produce generic marketing advice
+```
+
+**Backstory Elements That Enhance LLM Performance:**
+- **Domain Experience**: "10+ years in enterprise SaaS sales"
+- **Specific Expertise**: "Specializes in technical due diligence for Series B+ rounds"
+- **Working Style**: "Prefers data-driven decisions with clear documentation"
+- **Quality Standards**: "Insists on citing sources and showing analytical work"
+
+### c. Holistic Agent-LLM Optimization
+
+The most effective agent configurations create synergy between role specificity, backstory depth, and LLM selection. Each element reinforces the others to maximize model performance.
+
+**Optimization Framework:**
+
+```python
+# Example: Technical Documentation Agent
+tech_writer = Agent(
+    role="API Documentation Specialist",  # Specific role for clear LLM requirements
+    goal="Create comprehensive, developer-friendly API documentation",
+    backstory="""
+    You're a technical writer with 8+ years documenting REST APIs, GraphQL endpoints, 
+    and SDK integration guides. You've worked with developer tools companies and 
+    understand what developers need: clear examples, comprehensive error handling, 
+    and practical use cases. You prioritize accuracy and usability over marketing fluff.
+    """,
+    llm=LLM(
+        model="claude-3-5-sonnet",  # Excellent for technical writing
+        temperature=0.1  # Low temperature for accuracy
+    ),
+    tools=[code_analyzer_tool, api_scanner_tool],
+    verbose=True 
+)
+```
+
+**Alignment Checklist:**
+- ✅ **Role Specificity**: Clear domain and responsibilities
+- ✅ **LLM Match**: Model strengths align with role requirements 
+- ✅ **Backstory Depth**: Provides domain context the LLM can leverage
+- ✅ **Tool Integration**: Tools support the agent's specialized function
+- ✅ **Parameter Tuning**: Temperature and settings optimize for role needs
+
+The key is creating agents where every configuration choice reinforces your LLM selection strategy, maximizing performance while optimizing costs.
+
+## Practical Implementation Checklist
+
+Rather than repeating the strategic framework, here's a tactical checklist for implementing your LLM selection decisions in CrewAI:
+
+<Steps>
+  <Step title="Audit Your Current Setup" icon="clipboard-check">
+    **What to Review:**
+    - Are all agents using the same LLM by default?
+    - Which agents handle the most complex reasoning tasks?
+    - Which agents primarily do data processing or formatting?
+    - Are any agents heavily tool-dependent?
+    
+    **Action**: Document current agent roles and identify optimization opportunities.
+  </Step>
+  
+  <Step title="Implement Crew-Level Strategy" icon="users-gear">
+    **Set Your Baseline:**
+    ```python
+    # Start with a reliable default for the crew
+    default_crew_llm = LLM(model="gpt-4o-mini")  # Cost-effective baseline
+    
+    crew = Crew(
+        agents=[...],
+        tasks=[...],
+        memory=True
+    )
+    ```
+    
+    **Action**: Establish your crew's default LLM before optimizing individual agents.
+  </Step>
+  
+  <Step title="Optimize High-Impact Agents" icon="star">
+    **Identify and Upgrade Key Agents:**
+    ```python
+    # Manager or coordination agents
+    manager_agent = Agent(
+        role="Project Manager",
+        llm=LLM(model="gemini-2.5-flash-preview-05-20"),  # Premium for coordination
+        # ... rest of config
+    )
+    
+    # Creative or customer-facing agents  
+    content_agent = Agent(
+        role="Content Creator",
+        llm=LLM(model="claude-3-5-sonnet"),  # Best for writing
+        # ... rest of config
+    )
+    ```
+    
+    **Action**: Upgrade 20% of your agents that handle 80% of the complexity.
+  </Step>
+  
+  <Step title="Validate with Enterprise Testing" icon="test-tube">
+    **Once you deploy your agents to production:**
+    - Use [CrewAI Enterprise platform](https://app.crewai.com) to A/B test your model selections
+    - Run multiple iterations with real inputs to measure consistency and performance
+    - Compare cost vs. performance across your optimized setup
+    - Share results with your team for collaborative decision-making
+    
+    **Action**: Replace guesswork with data-driven validation using the testing platform.
+  </Step>
+</Steps>
+
+### When to Use Different Model Types
+
+<Tabs>
+  <Tab title="Reasoning Models">
+    Reasoning models become essential when tasks require genuine multi-step logical thinking, strategic planning, or high-level decision making that benefits from systematic analysis. These models excel when problems need to be broken down into components and analyzed systematically rather than handled through pattern matching or simple instruction following.
+
+    Consider reasoning models for business strategy development, complex data analysis that requires drawing insights from multiple sources, multi-step problem solving where each step depends on previous analysis, and strategic planning tasks that require considering multiple variables and their interactions.
+
+    However, reasoning models often come with higher costs and slower response times, so they're best reserved for tasks where their sophisticated capabilities provide genuine value rather than being used for simple operations that don't require complex reasoning.
+  </Tab>
+  
+  <Tab title="Creative Models">
+    Creative models become valuable when content generation is the primary output and the quality, style, and engagement level of that content directly impact success. These models excel when writing quality and style matter significantly, creative ideation or brainstorming is needed, or brand voice and tone are important considerations.
+
+    Use creative models for blog post writing and article creation, marketing copy that needs to engage and persuade, creative storytelling and narrative development, and brand communications where voice and tone are crucial. These models often understand nuance and context better than general purpose alternatives.
+
+    Creative models may be less suitable for technical or analytical tasks where precision and factual accuracy are more important than engagement and style. They're best used when the creative and communicative aspects of the output are primary success factors.
+  </Tab>
+  
+  <Tab title="Efficient Models">
+    Efficient models are ideal for high-frequency, routine operations where speed and cost optimization are priorities. These models work best when tasks have clear, well-defined parameters and don't require sophisticated reasoning or creative capabilities.
+
+    Consider efficient models for data processing and transformation tasks, simple formatting and organization operations, function calling and tool usage where precision matters more than sophistication, and high-volume operations where cost per operation is a significant factor.
+
+    The key with efficient models is ensuring that their capabilities align with task requirements. They can handle many routine operations effectively but may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation.
+  </Tab>
+  
+  <Tab title="Open Source Models">
+    Open source models become attractive when budget constraints are significant, data privacy requirements exist, customization needs are important, or local deployment is required for operational or compliance reasons.
+
+    Consider open source models for internal company tools where data privacy is paramount, privacy-sensitive applications that can't use external APIs, cost-optimized deployments where per-token pricing is prohibitive, and situations requiring custom model modifications or fine-tuning.
+
+    However, open source models require more technical expertise to deploy and maintain effectively. Consider the total cost of ownership including infrastructure, technical overhead, and ongoing maintenance when evaluating open source options.
+  </Tab>
+</Tabs>
+
+## Common CrewAI Model Selection Pitfalls
+
+<AccordionGroup>
+  <Accordion title="The 'One Model Fits All' Trap" icon="triangle-exclamation">
+    **The Problem**: Using the same LLM for all agents in a crew, regardless of their specific roles and responsibilities. This is often the default approach but rarely optimal.
+
+    **Real Example**: Using GPT-4o for both a strategic planning manager and a data extraction agent. The manager needs reasoning capabilities worth the premium cost, but the data extractor could perform just as well with GPT-4o-mini at a fraction of the price.
+
+    **CrewAI Solution**: Leverage agent-specific LLM configuration to match model capabilities with agent roles:
+    ```python
+    # Strategic agent gets premium model
+    manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o"))
+    
+    # Processing agent gets efficient model  
+    processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini"))
+    ```
+  </Accordion>
+  
+  <Accordion title="Ignoring Crew-Level vs Agent-Level LLM Hierarchy" icon="shuffle">
+    **The Problem**: Not understanding how CrewAI's LLM hierarchy works - crew LLM, manager LLM, and agent LLM settings can conflict or be poorly coordinated.
+
+    **Real Example**: Setting a crew to use Claude, but having agents configured with GPT models, creating inconsistent behavior and unnecessary model switching overhead.
+
+    **CrewAI Solution**: Plan your LLM hierarchy strategically:
+    ```python
+    crew = Crew(
+        agents=[agent1, agent2],
+        tasks=[task1, task2],
+        manager_llm=LLM(model="gpt-4o"),  # For crew coordination
+        process=Process.hierarchical  # When using manager_llm
+    )
+    
+    # Agents inherit crew LLM unless specifically overridden
+    agent1 = Agent(llm=LLM(model="claude-3-5-sonnet"))  # Override for specific needs
+    ```
+  </Accordion>
+  
+  <Accordion title="Function Calling Model Mismatch" icon="screwdriver-wrench">
+    **The Problem**: Choosing models based on general capabilities while ignoring function calling performance for tool-heavy CrewAI workflows.
+
+    **Real Example**: Selecting a creative-focused model for an agent that primarily needs to call APIs, search tools, or process structured data. The agent struggles with tool parameter extraction and reliable function calls.
+
+    **CrewAI Solution**: Prioritize function calling capabilities for tool-heavy agents:
+    ```python
+    # For agents that use many tools
+    tool_agent = Agent(
+        role="API Integration Specialist",
+        tools=[search_tool, api_tool, data_tool],
+        llm=LLM(model="gpt-4o"),  # Excellent function calling
+        # OR
+        llm=LLM(model="claude-3-5-sonnet")  # Also strong with tools
+    )
+    ```
+  </Accordion>
+  
+  <Accordion title="Premature Optimization Without Testing" icon="gear">
+    **The Problem**: Making complex model selection decisions based on theoretical performance without validating with actual CrewAI workflows and tasks.
+
+    **Real Example**: Implementing elaborate model switching logic based on task types without testing if the performance gains justify the operational complexity.
+
+    **CrewAI Solution**: Start simple, then optimize based on real performance data:
+    ```python
+    # Start with this
+    crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini"))
+    
+    # Test performance, then optimize specific agents as needed
+    # Use Enterprise platform testing to validate improvements
+    ```
+  </Accordion>
+
+  <Accordion title="Overlooking Context and Memory Limitations" icon="brain">
+    **The Problem**: Not considering how model context windows interact with CrewAI's memory and context sharing between agents.
+
+    **Real Example**: Using a short-context model for agents that need to maintain conversation history across multiple task iterations, or in crews with extensive agent-to-agent communication.
+
+    **CrewAI Solution**: Match context capabilities to crew communication patterns.
+  </Accordion>
+</AccordionGroup>
+
+## Testing and Iteration Strategy
+
+<Steps>
+  <Step title="Start Simple" icon="play">
+    Begin with reliable, general-purpose models that are well-understood and widely supported. This provides a stable foundation for understanding your specific requirements and performance expectations before optimizing for specialized needs.
+  </Step>
+  <Step title="Measure What Matters" icon="chart-line">
+    Develop metrics that align with your specific use case and business requirements rather than relying solely on general benchmarks. Focus on measuring outcomes that directly impact your success rather than theoretical performance indicators.
+  </Step>
+  <Step title="Iterate Based on Results" icon="arrows-rotate">
+    Make model changes based on observed performance in your specific context rather than theoretical considerations or general recommendations. Real-world performance often differs significantly from benchmark results or general reputation.
+  </Step>
+  <Step title="Consider Total Cost" icon="calculator">
+    Evaluate the complete cost of ownership including model costs, development time, maintenance overhead, and operational complexity. The cheapest model per token may not be the most cost-effective choice when considering all factors.
+  </Step>
+</Steps>
+
+<Tip>
+Focus on understanding your requirements first, then select models that best match those needs. The best LLM choice is the one that consistently delivers the results you need within your operational constraints.
+</Tip>
+
+### Enterprise-Grade Model Validation
+
+For teams serious about optimizing their LLM selection, the **CrewAI Enterprise platform** provides sophisticated testing capabilities that go far beyond basic CLI testing. The platform enables comprehensive model evaluation that helps you make data-driven decisions about your LLM strategy.
+
+<Frame>
+  ![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png)
+</Frame>
+
+**Advanced Testing Features:**
+
+- **Multi-Model Comparison**: Test multiple LLMs simultaneously across the same tasks and inputs. Compare performance between GPT-4o, Claude, Llama, Groq, Cerebras, and other leading models in parallel to identify the best fit for your specific use case.
+
+- **Statistical Rigor**: Configure multiple iterations with consistent inputs to measure reliability and performance variance. This helps identify models that not only perform well but do so consistently across runs.
+
+- **Real-World Validation**: Use your actual crew inputs and scenarios rather than synthetic benchmarks. The platform allows you to test with your specific industry context, company information, and real use cases for more accurate evaluation.
+
+- **Comprehensive Analytics**: Access detailed performance metrics, execution times, and cost analysis across all tested models. This enables data-driven decision making rather than relying on general model reputation or theoretical capabilities.
+
+- **Team Collaboration**: Share testing results and model performance data across your team, enabling collaborative decision-making and consistent model selection strategies across projects.
+
+Go to [app.crewai.com](https://app.crewai.com) to get started!
+
+<Info>
+The Enterprise platform transforms model selection from guesswork into a data-driven process, enabling you to validate the principles in this guide with your actual use cases and requirements.
+</Info>
+
+## Key Principles Summary
+
+<CardGroup cols={2}>
+  <Card title="Task-Driven Selection" icon="bullseye">
+    Choose models based on what the task actually requires, not theoretical capabilities or general reputation.
+  </Card>
+  
+  <Card title="Capability Matching" icon="puzzle-piece">
+    Align model strengths with agent roles and responsibilities for optimal performance.
+  </Card>
+  
+  <Card title="Strategic Consistency" icon="link">
+    Maintain coherent model selection strategy across related components and workflows.
+  </Card>
+  
+  <Card title="Practical Testing" icon="flask">
+    Validate choices through real-world usage rather than benchmarks alone.
+  </Card>
+  
+  <Card title="Iterative Improvement" icon="arrow-up">
+    Start simple and optimize based on actual performance and needs.
+  </Card>
+  
+  <Card title="Operational Balance" icon="scale-balanced">
+    Balance performance requirements with cost and complexity constraints.
+  </Card>
+</CardGroup>
+
+<Check>
+Remember: The best LLM choice is the one that consistently delivers the results you need within your operational constraints. Focus on understanding your requirements first, then select models that best match those needs.
+</Check>
+
+## Current Model Landscape (June 2025)
+
+<Warning>
+**Snapshot in Time**: The following model rankings represent current leaderboard standings as of June 2025, compiled from [LMSys Arena](https://arena.lmsys.org/), [Artificial Analysis](https://artificialanalysis.ai/), and other leading benchmarks. LLM performance, availability, and pricing change rapidly. Always conduct your own evaluations with your specific use cases and data.
+</Warning>
+
+### Leading Models by Category
+
+The tables below show a representative sample of current top-performing models across different categories, with guidance on their suitability for CrewAI agents:
+
+<Note>
+These tables/metrics showcase selected leading models in each category and are not exhaustive. Many excellent models exist beyond those listed here. The goal is to illustrate the types of capabilities to look for rather than provide a complete catalog.
+</Note>
+
+<Tabs>
+  <Tab title="Reasoning & Planning">
+    **Best for Manager LLMs and Complex Analysis**
+    
+    | Model | Intelligence Score | Cost ($/M tokens) | Speed | Best Use in CrewAI |
+    |:------|:------------------|:------------------|:------|:------------------|
+    | **o3** | 70 | $17.50 | Fast | Manager LLM for complex multi-agent coordination |
+    | **Gemini 2.5 Pro** | 69 | $3.44 | Fast | Strategic planning agents, research coordination |
+    | **DeepSeek R1** | 68 | $0.96 | Moderate | Cost-effective reasoning for budget-conscious crews |
+    | **Claude 4 Sonnet** | 53 | $6.00 | Fast | Analysis agents requiring nuanced understanding |
+    | **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderate | Open-source alternative for reasoning tasks |
+
+    These models excel at multi-step reasoning and are ideal for agents that need to develop strategies, coordinate other agents, or analyze complex information.
+  </Tab>
+  
+  <Tab title="Coding & Technical">
+    **Best for Development and Tool-Heavy Workflows**
+    
+    | Model | Coding Performance | Tool Use Score | Cost ($/M tokens) | Best Use in CrewAI |
+    |:------|:------------------|:---------------|:------------------|:------------------|
+    | **Claude 4 Sonnet** | Excellent | 72.7% | $6.00 | Primary coding agent, technical documentation |
+    | **Claude 4 Opus** | Excellent | 72.5% | $30.00 | Complex software architecture, code review |
+    | **DeepSeek V3** | Very Good | High | $0.48 | Cost-effective coding for routine development |
+    | **Qwen2.5 Coder 32B** | Very Good | Medium | $0.15 | Budget-friendly coding agent |
+    | **Llama 3.1 405B** | Good | 81.1% | $3.50 | Function calling LLM for tool-heavy workflows |
+
+    These models are optimized for code generation, debugging, and technical problem-solving, making them ideal for development-focused crews.
+  </Tab>
+  
+  <Tab title="Speed & Efficiency">
+    **Best for High-Throughput and Real-Time Applications**
+    
+    | Model | Speed (tokens/s) | Latency (TTFT) | Cost ($/M tokens) | Best Use in CrewAI |
+    |:------|:-----------------|:---------------|:------------------|:------------------|
+    | **Llama 4 Scout** | 2,600 | 0.33s | $0.27 | High-volume processing agents |
+    | **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Real-time response agents |
+    | **DeepSeek R1 Distill** | 383 | Variable | $0.04 | Cost-optimized high-speed processing |
+    | **Llama 3.3 70B** | 2,500 | 0.52s | $0.60 | Balanced speed and capability |
+    | **Nova Micro** | High | 0.30s | $0.04 | Simple, fast task execution |
+
+    These models prioritize speed and efficiency, perfect for agents handling routine operations or requiring quick responses. **Pro tip**: Pairing these models with fast inference providers like Groq can achieve even better performance, especially for open-source models like Llama.
+  </Tab>
+  
+  <Tab title="Balanced Performance">
+    **Best All-Around Models for General Crews**
+    
+    | Model | Overall Score | Versatility | Cost ($/M tokens) | Best Use in CrewAI |
+    |:------|:--------------|:------------|:------------------|:------------------|
+    | **GPT-4.1** | 53 | Excellent | $3.50 | General-purpose crew LLM |
+    | **Claude 3.7 Sonnet** | 48 | Very Good | $6.00 | Balanced reasoning and creativity |
+    | **Gemini 2.0 Flash** | 48 | Good | $0.17 | Cost-effective general use |
+    | **Llama 4 Maverick** | 51 | Good | $0.37 | Open-source general purpose |
+    | **Qwen3 32B** | 44 | Good | $1.23 | Budget-friendly versatility |
+
+    These models offer good performance across multiple dimensions, suitable for crews with diverse task requirements.
+  </Tab>
+</Tabs>
+
+### Selection Framework for Current Models
+
+<AccordionGroup>
+  <Accordion title="High-Performance Crews" icon="rocket">
+    **When performance is the priority**: Use top-tier models like **o3**, **Gemini 2.5 Pro**, or **Claude 4 Sonnet** for manager LLMs and critical agents. These models excel at complex reasoning and coordination but come with higher costs.
+
+    **Strategy**: Implement a multi-model approach where premium models handle strategic thinking while efficient models handle routine operations.
+  </Accordion>
+  
+  <Accordion title="Cost-Conscious Crews" icon="dollar-sign">
+    **When budget is a primary constraint**: Focus on models like **DeepSeek R1**, **Llama 4 Scout**, or **Gemini 2.0 Flash**. These provide strong performance at significantly lower costs.
+
+    **Strategy**: Use cost-effective models for most agents, reserving premium models only for the most critical decision-making roles.
+  </Accordion>
+  
+  <Accordion title="Specialized Workflows" icon="screwdriver-wrench">
+    **For specific domain expertise**: Choose models optimized for your primary use case. **Claude 4** series for coding, **Gemini 2.5 Pro** for research, **Llama 405B** for function calling.
+
+    **Strategy**: Select models based on your crew's primary function, ensuring the core capability aligns with model strengths.
+  </Accordion>
+  
+  <Accordion title="Enterprise & Privacy" icon="shield">
+    **For data-sensitive operations**: Consider open-source models like **Llama 4** series, **DeepSeek V3**, or **Qwen3** that can be deployed locally while maintaining competitive performance.
+
+    **Strategy**: Deploy open-source models on private infrastructure, accepting potential performance trade-offs for data control.
+  </Accordion>
+  </AccordionGroup>
+
+### Key Considerations for Model Selection
+
+- **Performance Trends**: The current landscape shows strong competition between reasoning-focused models (o3, Gemini 2.5 Pro) and balanced models (Claude 4, GPT-4.1). Specialized models like DeepSeek R1 offer excellent cost-performance ratios.
+
+- **Speed vs. Intelligence Trade-offs**: Models like Llama 4 Scout prioritize speed (2,600 tokens/s) while maintaining reasonable intelligence, whereas models like o3 maximize reasoning capability at the cost of speed and price.
+
+- **Open Source Viability**: The gap between open-source and proprietary models continues to narrow, with models like Llama 4 Maverick and DeepSeek V3 offering competitive performance at attractive price points. Fast inference providers particularly shine with open-source models, often delivering better speed-to-cost ratios than proprietary alternatives.
+
+<Info>
+**Testing is Essential**: Leaderboard rankings provide general guidance, but your specific use case, prompting style, and evaluation criteria may produce different results. Always test candidate models with your actual tasks and data before making final decisions.
+</Info>
+
+### Practical Implementation Strategy
+
+<Steps>
+  <Step title="Start with Proven Models">
+    Begin with well-established models like **GPT-4.1**, **Claude 3.7 Sonnet**, or **Gemini 2.0 Flash** that offer good performance across multiple dimensions and have extensive real-world validation.
+  </Step>
+  
+  <Step title="Identify Specialized Needs">
+    Determine if your crew has specific requirements (coding, reasoning, speed) that would benefit from specialized models like **Claude 4 Sonnet** for development or **o3** for complex analysis. For speed-critical applications, consider fast inference providers like **Groq** alongside model selection.
+  </Step>
+  
+  <Step title="Implement Multi-Model Strategy">
+    Use different models for different agents based on their roles. High-capability models for managers and complex tasks, efficient models for routine operations.
+  </Step>
+  
+  <Step title="Monitor and Optimize">
+    Track performance metrics relevant to your use case and be prepared to adjust model selections as new models are released or pricing changes.
+  </Step>
+</Steps> 

docs/learn/overview.mdx

@@ -0,0 +1,158 @@
+---
+title: "Overview"
+description: "Learn how to build, customize, and optimize your CrewAI applications with comprehensive guides and tutorials"
+icon: "face-smile"
+---
+
+## Learn CrewAI
+
+This section provides comprehensive guides and tutorials to help you master CrewAI, from basic concepts to advanced techniques. Whether you're just getting started or looking to optimize your existing implementations, these resources will guide you through every aspect of building powerful AI agent workflows.
+
+## Getting Started Guides
+
+### Core Concepts
+<CardGroup cols={2}>
+  <Card title="Sequential Process" icon="list-ol" href="/learn/sequential-process">
+    Learn how to execute tasks in a sequential order for structured workflows.
+  </Card>
+
+  <Card title="Hierarchical Process" icon="sitemap" href="/learn/hierarchical-process">
+    Implement hierarchical task execution with manager agents overseeing workflows.
+  </Card>
+
+  <Card title="Conditional Tasks" icon="code-branch" href="/learn/conditional-tasks">
+    Create dynamic workflows with conditional task execution based on outcomes.
+  </Card>
+
+  <Card title="Async Kickoff" icon="bolt" href="/learn/kickoff-async">
+    Execute crews asynchronously for improved performance and concurrency.
+  </Card>
+</CardGroup>
+
+### Agent Development
+<CardGroup cols={2}>
+  <Card title="Customizing Agents" icon="user-gear" href="/learn/customizing-agents">
+    Learn how to customize agent behavior, roles, and capabilities.
+  </Card>
+
+  <Card title="Coding Agents" icon="code" href="/learn/coding-agents">
+    Build agents that can write, execute, and debug code automatically.
+  </Card>
+
+  <Card title="Multimodal Agents" icon="images" href="/learn/multimodal-agents">
+    Create agents that can process text, images, and other media types.
+  </Card>
+
+  <Card title="Custom Manager Agent" icon="user-tie" href="/learn/custom-manager-agent">
+    Implement custom manager agents for complex hierarchical workflows.
+  </Card>
+</CardGroup>
+
+## Advanced Features
+
+### Workflow Control
+<CardGroup cols={2}>
+  <Card title="Human in the Loop" icon="user-check" href="/learn/human-in-the-loop">
+    Integrate human oversight and intervention into agent workflows.
+  </Card>
+
+  <Card title="Human Input on Execution" icon="hand-paper" href="/learn/human-input-on-execution">
+    Allow human input during task execution for dynamic decision making.
+  </Card>
+
+  <Card title="Replay Tasks" icon="rotate-left" href="/learn/replay-tasks-from-latest-crew-kickoff">
+    Replay and resume tasks from previous crew executions.
+  </Card>
+
+  <Card title="Kickoff for Each" icon="repeat" href="/learn/kickoff-for-each">
+    Execute crews multiple times with different inputs efficiently.
+  </Card>
+</CardGroup>
+
+### Customization & Integration
+<CardGroup cols={2}>
+  <Card title="Custom LLM" icon="brain" href="/learn/custom-llm">
+    Integrate custom language models and providers with CrewAI.
+  </Card>
+
+  <Card title="LLM Connections" icon="link" href="/learn/llm-connections">
+    Configure and manage connections to various LLM providers.
+  </Card>
+
+  <Card title="Create Custom Tools" icon="wrench" href="/learn/create-custom-tools">
+    Build custom tools to extend agent capabilities.
+  </Card>
+
+  <Card title="Using Annotations" icon="at" href="/learn/using-annotations">
+    Use Python annotations for cleaner, more maintainable code.
+  </Card>
+</CardGroup>
+
+## Specialized Applications
+
+### Content & Media
+<CardGroup cols={2}>
+  <Card title="DALL-E Image Generation" icon="image" href="/learn/dalle-image-generation">
+    Generate images using DALL-E integration with your agents.
+  </Card>
+
+  <Card title="Bring Your Own Agent" icon="user-plus" href="/learn/bring-your-own-agent">
+    Integrate existing agents and models into CrewAI workflows.
+  </Card>
+</CardGroup>
+
+### Tool Management
+<CardGroup cols={2}>
+  <Card title="Force Tool Output as Result" icon="hammer" href="/learn/force-tool-output-as-result">
+    Configure tools to return their output directly as task results.
+  </Card>
+</CardGroup>
+
+## Learning Path Recommendations
+
+### For Beginners
+1. Start with **Sequential Process** to understand basic workflow execution
+2. Learn **Customizing Agents** to create effective agent configurations
+3. Explore **Create Custom Tools** to extend functionality
+4. Try **Human in the Loop** for interactive workflows
+
+### For Intermediate Users
+1. Master **Hierarchical Process** for complex multi-agent systems
+2. Implement **Conditional Tasks** for dynamic workflows
+3. Use **Async Kickoff** for performance optimization
+4. Integrate **Custom LLM** for specialized models
+
+### For Advanced Users
+1. Build **Multimodal Agents** for complex media processing
+2. Create **Custom Manager Agents** for sophisticated orchestration
+3. Implement **Bring Your Own Agent** for hybrid systems
+4. Use **Replay Tasks** for robust error recovery
+
+## Best Practices
+
+### Development
+- **Start Simple**: Begin with basic sequential workflows before adding complexity
+- **Test Incrementally**: Test each component before integrating into larger systems
+- **Use Annotations**: Leverage Python annotations for cleaner, more maintainable code
+- **Custom Tools**: Build reusable tools that can be shared across different agents
+
+### Production
+- **Error Handling**: Implement robust error handling and recovery mechanisms
+- **Performance**: Use async execution and optimize LLM calls for better performance
+- **Monitoring**: Integrate observability tools to track agent performance
+- **Human Oversight**: Include human checkpoints for critical decisions
+
+### Optimization
+- **Resource Management**: Monitor and optimize token usage and API costs
+- **Workflow Design**: Design workflows that minimize unnecessary LLM calls
+- **Tool Efficiency**: Create efficient tools that provide maximum value with minimal overhead
+- **Iterative Improvement**: Use feedback and metrics to continuously improve agent performance
+
+## Getting Help
+
+- **Documentation**: Each guide includes detailed examples and explanations
+- **Community**: Join the [CrewAI Forum](https://community.crewai.com) for discussions and support
+- **Examples**: Check the Examples section for complete working implementations
+- **Support**: Contact [support@crewai.com](mailto:support@crewai.com) for technical assistance
+
+Start with the guides that match your current needs and gradually explore more advanced topics as you become comfortable with the fundamentals. 

docs/learn/using-annotations.mdx

@@ -0,0 +1,141 @@
+---
+title: "Using Annotations in crew.py"
+description: "Learn how to use annotations to properly structure agents, tasks, and components in CrewAI"
+icon: "at"
+---
+
+This guide explains how to use annotations to properly reference **agents**, **tasks**, and other components in the `crew.py` file.
+
+## Introduction
+
+Annotations in the CrewAI framework are used to decorate classes and methods, providing metadata and functionality to various components of your crew. These annotations help in organizing and structuring your code, making it more readable and maintainable.
+
+## Available Annotations
+
+The CrewAI framework provides the following annotations:
+
+- `@CrewBase`: Used to decorate the main crew class.
+- `@agent`: Decorates methods that define and return Agent objects.
+- `@task`: Decorates methods that define and return Task objects.
+- `@crew`: Decorates the method that creates and returns the Crew object.
+- `@llm`: Decorates methods that initialize and return Language Model objects.
+- `@tool`: Decorates methods that initialize and return Tool objects.
+- `@callback`: Used for defining callback methods.
+- `@output_json`: Used for methods that output JSON data.
+- `@output_pydantic`: Used for methods that output Pydantic models.
+- `@cache_handler`: Used for defining cache handling methods.
+
+## Usage Examples
+
+Let's go through examples of how to use these annotations:
+
+### 1. Crew Base Class
+
+```python
+@CrewBase
+class LinkedinProfileCrew():
+    """LinkedinProfile crew"""
+    agents_config = 'config/agents.yaml'
+    tasks_config = 'config/tasks.yaml'
+```
+
+The `@CrewBase` annotation is used to decorate the main crew class. This class typically contains configurations and methods for creating agents, tasks, and the crew itself.
+
+### 2. Tool Definition
+
+```python
+@tool
+def myLinkedInProfileTool(self):
+    return LinkedInProfileTool()
+```
+
+The `@tool` annotation is used to decorate methods that return tool objects. These tools can be used by agents to perform specific tasks.
+
+### 3. LLM Definition
+
+```python
+@llm
+def groq_llm(self):
+    api_key = os.getenv('api_key')
+    return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")
+```
+
+The `@llm` annotation is used to decorate methods that initialize and return Language Model objects. These LLMs are used by agents for natural language processing tasks.
+
+### 4. Agent Definition
+
+```python
+@agent
+def researcher(self) -> Agent:
+    return Agent(
+        config=self.agents_config['researcher']
+    )
+```
+
+The `@agent` annotation is used to decorate methods that define and return Agent objects.
+
+### 5. Task Definition
+
+```python
+@task
+def research_task(self) -> Task:
+    return Task(
+        config=self.tasks_config['research_linkedin_task'],
+        agent=self.researcher()
+    )
+```
+
+The `@task` annotation is used to decorate methods that define and return Task objects. These methods specify the task configuration and the agent responsible for the task.
+
+### 6. Crew Creation
+
+```python
+@crew
+def crew(self) -> Crew:
+    """Creates the LinkedinProfile crew"""
+    return Crew(
+        agents=self.agents,
+        tasks=self.tasks,
+        process=Process.sequential,
+        verbose=True
+    )
+``` 
+
+The `@crew` annotation is used to decorate the method that creates and returns the `Crew` object. This method assembles all the components (agents and tasks) into a functional crew.
+
+## YAML Configuration
+
+The agent configurations are typically stored in a YAML file. Here's an example of how the `agents.yaml` file might look for the researcher agent:
+
+```yaml
+researcher:
+    role: >
+        LinkedIn Profile Senior Data Researcher
+    goal: >
+        Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
+        Generate a Dall-E image based on domain {domain}
+    backstory: >
+        You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
+        Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
+        professional information clearly and concisely.
+    allow_delegation: False
+    verbose: True
+    llm: groq_llm
+    tools:
+        - myLinkedInProfileTool
+        - mySerperDevTool
+        - myDallETool
+```
+
+This YAML configuration corresponds to the researcher agent defined in the `LinkedinProfileCrew` class. The configuration specifies the agent's role, goal, backstory, and other properties such as the LLM and tools it uses.
+
+Note how the `llm` and `tools` in the YAML file correspond to the methods decorated with `@llm` and `@tool` in the Python class.
+
+## Best Practices
+
+- **Consistent Naming**: Use clear and consistent naming conventions for your methods. For example, agent methods could be named after their roles (e.g., researcher, reporting_analyst).
+- **Environment Variables**: Use environment variables for sensitive information like API keys.
+- **Flexibility**: Design your crew to be flexible by allowing easy addition or removal of agents and tasks.
+- **YAML-Code Correspondence**: Ensure that the names and structures in your YAML files correspond correctly to the decorated methods in your Python code.
+
+By following these guidelines and properly using annotations, you can create well-structured and maintainable crews using the CrewAI framework. 

docs/mcp/crewai-mcp-integration.mdx

@@ -1,229 +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>
-
-## 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).