fix: Prevent callback validation ValueError from being suppressed

- Move signature parameter count validation outside try-except block
- Only catch exceptions from inspect.signature(), not validation errors
- Ensures invalid callbacks properly raise ValueError instead of passing silently
- Addresses final Cursor Bugbot issue with callback validation bypass

This resolves the remaining CI issue where the try-except block was too broad
and caught the ValueError that should propagate for invalid callback signatures.

Co-Authored-By: João <joao@crewai.com>

.github/workflows/codeql.yml

@@ -0,0 +1,102 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+    paths-ignore:
+      - "src/crewai/cli/templates/**"
+  pull_request:
+    branches: [ "main" ]
+    paths-ignore:
+      - "src/crewai/cli/templates/**"
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/tests.yml

@@ -22,6 +22,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for proper diff
 
       - name: Restore global uv cache
         id: cache-restore
@@ -45,14 +47,41 @@ jobs:
       - name: Install the project
         run: uv sync --all-groups --all-extras
 
+      - name: Restore test durations
+        uses: actions/cache/restore@v4
+        with:
+          path: .test_durations_py*
+          key: test-durations-py${{ matrix.python-version }}
+
       - name: Run tests (group ${{ matrix.group }} of 8)
         run: |
+          PYTHON_VERSION_SAFE=$(echo "${{ matrix.python-version }}" | tr '.' '_')
+          DURATION_FILE=".test_durations_py${PYTHON_VERSION_SAFE}"
+          
+          # Temporarily always skip cached durations to fix test splitting
+          # When durations don't match, pytest-split runs duplicate tests instead of splitting
+          echo "Using even test splitting (duration cache disabled until fix merged)"
+          DURATIONS_ARG=""
+          
+          # Original logic (disabled temporarily):
+          # if [ ! -f "$DURATION_FILE" ]; then
+          #   echo "No cached durations found, tests will be split evenly"
+          #   DURATIONS_ARG=""
+          # elif git diff origin/${{ github.base_ref }}...HEAD --name-only 2>/dev/null | grep -q "^tests/.*\.py$"; then
+          #   echo "Test files have changed, skipping cached durations to avoid mismatches"
+          #   DURATIONS_ARG=""
+          # else
+          #   echo "No test changes detected, using cached test durations for optimal splitting"
+          #   DURATIONS_ARG="--durations-path=${DURATION_FILE}"
+          # fi
+          
           uv run pytest \
             --block-network \
             --timeout=30 \
             -vv \
             --splits 8 \
             --group ${{ matrix.group }} \
+            $DURATIONS_ARG \
             --durations=10 \
             -n auto \
             --maxfail=3

.github/workflows/update-test-durations.yml

@@ -0,0 +1,71 @@
+name: Update Test Durations
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'tests/**/*.py'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  update-durations:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    env:
+      OPENAI_API_KEY: fake-api-key
+      PYTHONUNBUFFERED: 1
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Restore global uv cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-main-py${{ matrix.python-version }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.4"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
+
+      - name: Install the project
+        run: uv sync --all-groups --all-extras
+
+      - name: Run all tests and store durations
+        run: |
+          PYTHON_VERSION_SAFE=$(echo "${{ matrix.python-version }}" | tr '.' '_')
+          uv run pytest --store-durations --durations-path=.test_durations_py${PYTHON_VERSION_SAFE} -n auto
+        continue-on-error: true
+
+      - name: Save durations to cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .test_durations_py*
+          key: test-durations-py${{ matrix.python-version }}
+
+      - name: Save uv caches
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}

docs/en/changelog.mdx

@@ -5,6 +5,82 @@ icon: "clock"
 mode: "wide"
 ---
 
+<Update label="Sep 20, 2025">
+  ## v0.193.2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.193.2)
+
+  ## What's Changed
+
+  - Updated pyproject templates to use the right version
+
+</Update>
+
+<Update label="Sep 20, 2025">
+  ## v0.193.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.193.1)
+
+  ## What's Changed
+
+  - Series of minor fixes and linter improvements
+
+</Update>
+
+<Update label="Sep 19, 2025">
+  ## v0.193.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.193.0)
+
+  ## Core Improvements & Fixes
+  
+  - Fixed handling of the `model` parameter during OpenAI adapter initialization  
+  - Resolved test duration cache issues in CI workflows  
+  - Fixed flaky test related to repeated tool usage by agents  
+  - Added missing event exports to `__init__.py` for consistent module behavior  
+  - Dropped message storage from metadata in Mem0 to reduce bloat  
+  - Fixed L2 distance metric support for backward compatibility in vector search  
+
+  ## New Features & Enhancements
+  
+  - Introduced thread-safe platform context management  
+  - Added test duration caching for optimized `pytest-split` runs  
+  - Added ephemeral trace improvements for better trace control  
+  - Made search parameters for RAG, knowledge, and memory fully configurable  
+  - Enabled ChromaDB to use OpenAI API for embedding functions  
+  - Added deeper observability tools for user-level insights  
+  - Unified RAG storage system with instance-specific client support  
+
+  ## Documentation & Guides
+  
+  - Updated `RagTool` references to reflect CrewAI native RAG implementation  
+  - Improved internal docs for `langgraph` and `openai` agent adapters with type annotations and docstrings  
+
+</Update>
+
+<Update label="Sep 11, 2025">
+  ## v0.186.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.186.1)
+
+  ## What's Changed
+
+  - Fixed version not being found and silently failing reversion  
+  - Bumped CrewAI version to 0.186.1 and updated dependencies in the CLI  
+
+</Update>
+
+<Update label="Sep 10, 2025">
+  ## v0.186.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.186.0)
+
+  ## What's Changed
+
+  - Refer to the GitHub release notes for detailed changes
+
+</Update>
+
 <Update label="Sep 04, 2025">
   ## v0.177.0
 

docs/en/concepts/cli.mdx

@@ -404,6 +404,10 @@ crewai config reset
 After resetting configuration, re-run `crewai login` to authenticate again.
 </Tip>
 
+<Tip>
+CrewAI CLI handles authentication to the Tool Repository automatically when adding packages to your project. Just append `crewai` before any `uv` command to use it. E.g. `crewai uv add requests`. For more information, see [Tool Repository](https://docs.crewai.com/enterprise/features/tool-repository) docs.
+</Tip>
+
 <Note>
 Configuration settings are stored in `~/.config/crewai/settings.json`. Some settings like organization name and UUID are read-only and managed through authentication and organization commands. Tool repository related settings are hidden and cannot be set directly by users.
 </Note>

docs/en/enterprise/features/tool-repository.mdx

@@ -52,6 +52,36 @@ researcher = Agent(
 )
 ```
 
+## Adding other packages after installing a tool
+
+After installing a tool from the CrewAI Enterprise Tool Repository, you need to use the `crewai uv` command to add other packages to your project.
+Using pure `uv` commands will fail due to authentication to tool repository being handled by the CLI. By using the `crewai uv` command, you can add other packages to your project without having to worry about authentication.
+Any `uv` command can be used with the `crewai uv` command, making it a powerful tool for managing your project's dependencies without the hassle of managing authentication through environment variables or other methods.
+
+Say that you have installed a custom tool from the CrewAI Enterprise Tool Repository called "my-tool":
+
+```bash
+crewai tool install my-tool
+```
+
+And now you want to add another package to your project, you can use the following command:
+
+```bash
+crewai uv add requests
+```
+
+Other commands like `uv sync` or `uv remove` can also be used with the `crewai uv` command:
+
+```bash
+crewai uv sync
+```
+
+```bash
+crewai uv remove requests
+```
+
+This will add the package to your project and update `pyproject.toml` accordingly.
+
 ## Creating and Publishing Tools
 
 To create a new tool project:

docs/en/quickstart.mdx

@@ -27,7 +27,7 @@ Follow the steps below to get Crewing! 🚣‍♂️
   <Step title="Navigate to your new crew project">
     <CodeGroup>
       ```shell Terminal
-      cd latest-ai-development
+      cd latest_ai_development
       ```
     </CodeGroup>
   </Step>

docs/en/tools/ai-ml/ragtool.mdx

@@ -9,7 +9,7 @@ mode: "wide"
 
 ## Description
 
-The `RagTool` is designed to answer questions by leveraging the power of Retrieval-Augmented Generation (RAG) through EmbedChain.
+The `RagTool` is designed to answer questions by leveraging the power of Retrieval-Augmented Generation (RAG) through CrewAI's native RAG system.
 It provides a dynamic knowledge base that can be queried to retrieve relevant information from various data sources.
 This tool is particularly useful for applications that require access to a vast array of information and need to provide contextually relevant answers.
 
@@ -76,8 +76,8 @@ The `RagTool` can be used with a wide variety of data sources, including:
 The `RagTool` accepts the following parameters:
 
 - **summarize**: Optional. Whether to summarize the retrieved content. Default is `False`.
-- **adapter**: Optional. A custom adapter for the knowledge base. If not provided, an EmbedchainAdapter will be used.
-- **config**: Optional. Configuration for the underlying EmbedChain App.
+- **adapter**: Optional. A custom adapter for the knowledge base. If not provided, a CrewAIRagAdapter will be used.
+- **config**: Optional. Configuration for the underlying CrewAI RAG system.
 
 ## Adding Content
 
@@ -130,44 +130,23 @@ from crewai_tools import RagTool
 
 # Create a RAG tool with custom configuration
 config = {
-    "app": {
-        "name": "custom_app",
-    },
-    "llm": {
-        "provider": "openai",
+    "vectordb": {
+        "provider": "qdrant",
         "config": {
-            "model": "gpt-4",
+            "collection_name": "my-collection"
         }
     },
     "embedding_model": {
         "provider": "openai",
         "config": {
-            "model": "text-embedding-ada-002"
+            "model": "text-embedding-3-small"
         }
-    },
-    "vectordb": {
-        "provider": "elasticsearch",
-        "config": {
-            "collection_name": "my-collection",
-            "cloud_id": "deployment-name:xxxx",
-            "api_key": "your-key",
-            "verify_certs": False
-        }
-    },
-    "chunker": {
-        "chunk_size": 400,
-        "chunk_overlap": 100,
-        "length_function": "len",
-        "min_chunk_size": 0
     }
 }
 
 rag_tool = RagTool(config=config, summarize=True)
 ```
 
-The internal RAG tool utilizes the Embedchain adapter, allowing you to pass any configuration options that are supported by Embedchain.
-You can refer to the [Embedchain documentation](https://docs.embedchain.ai/components/introduction) for details.
-Make sure to review the configuration options available in the .yaml file.
 
 ## Conclusion
 The `RagTool` provides a powerful way to create and query knowledge bases from various data sources. By leveraging Retrieval-Augmented Generation, it enables agents to access and retrieve relevant information efficiently, enhancing their ability to provide accurate and contextually appropriate responses.

docs/ko/changelog.mdx

@@ -5,6 +5,82 @@ icon: "clock"
 mode: "wide"
 ---
 
+<Update label="2025년 9월 20일">
+  ## v0.193.2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.193.2)
+
+  ## 변경 사항
+  
+  - 올바른 버전을 사용하도록 pyproject 템플릿 업데이트
+
+</Update>
+
+<Update label="2025년 9월 20일">
+  ## v0.193.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.193.1)
+
+  ## 변경 사항
+  
+  - 일련의 사소한 수정 및 린터 개선
+
+</Update>
+
+<Update label="2025년 9월 19일">
+  ## v0.193.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.193.0)
+
+  ## 핵심 개선 사항 및 수정 사항
+  
+  - OpenAI 어댑터 초기화 중 `model` 매개변수 처리 수정  
+  - CI 워크플로에서 테스트 소요 시간 캐시 문제 해결  
+  - 에이전트의 반복 도구 사용과 관련된 불안정한 테스트 수정  
+  - 일관된 모듈 동작을 위해 누락된 이벤트 내보내기를 `__init__.py`에 추가  
+  - 메타데이터 부하를 줄이기 위해 Mem0에서 메시지 저장 제거  
+  - 벡터 검색의 하위 호환성을 위해 L2 거리 메트릭 지원 수정  
+
+  ## 새로운 기능 및 향상 사항
+  
+  - 스레드 안전한 플랫폼 컨텍스트 관리 도입  
+  - `pytest-split` 실행 최적화를 위한 테스트 소요 시간 캐싱 추가  
+  - 더 나은 추적 제어를 위한 일시적(trace) 개선  
+  - RAG, 지식, 메모리 검색 매개변수를 완전 구성 가능하게 변경  
+  - ChromaDB가 임베딩 함수에 OpenAI API를 사용할 수 있도록 지원  
+  - 사용자 수준 인사이트를 위한 심화된 관찰 가능성 도구 추가  
+  - 인스턴스별 클라이언트를 지원하는 통합 RAG 스토리지 시스템  
+
+  ## 문서 및 가이드
+  
+  - CrewAI 네이티브 RAG 구현을 반영하도록 `RagTool` 참조 업데이트  
+  - 타입 주석과 도크스트링을 포함해 `langgraph` 및 `openai` 에이전트 어댑터 내부 문서 개선  
+
+</Update>
+
+<Update label="2025년 9월 11일">
+  ## v0.186.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.186.1)
+
+  ## 변경 사항
+  
+  - 버전을 찾지 못해 조용히 되돌리는(reversion) 문제 수정  
+  - CLI에서 CrewAI 버전을 0.186.1로 올리고 의존성 업데이트  
+
+</Update>
+
+<Update label="2025년 9월 10일">
+  ## v0.186.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.186.0)
+
+  ## 변경 사항
+  
+  - 자세한 변경 사항은 GitHub 릴리스 노트를 참조하세요
+
+</Update>
+
 <Update label="2025년 9월 4일">
   ## v0.177.0
 

docs/ko/quickstart.mdx

@@ -27,7 +27,7 @@ mode: "wide"
   <Step title="새로운 crew 프로젝트로 이동하기">
     <CodeGroup>
       ```shell Terminal
-      cd latest-ai-development
+      cd latest_ai_development
       ```
     </CodeGroup>
   </Step>

docs/pt-BR/changelog.mdx

@@ -5,6 +5,82 @@ icon: "clock"
 mode: "wide"
 ---
 
+<Update label="20 set 2025">
+  ## v0.193.2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.193.2)
+
+  ## O que Mudou
+
+  - Atualizados templates do pyproject para usar a versão correta
+
+</Update>
+
+<Update label="20 set 2025">
+  ## v0.193.1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.193.1)
+
+  ## O que Mudou
+
+  - Série de pequenas correções e melhorias de linter
+
+</Update>
+
+<Update label="19 set 2025">
+  ## v0.193.0
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.193.0)
+
+  ## Melhorias e Correções Principais
+  
+  - Corrigido manuseio do parâmetro `model` durante a inicialização do adaptador OpenAI  
+  - Resolvidos problemas de cache da duração de testes nos fluxos de CI  
+  - Corrigido teste instável relacionado ao uso repetido de ferramentas pelos agentes  
+  - Adicionadas exportações de eventos ausentes no `__init__.py` para comportamento consistente do módulo  
+  - Removido armazenamento de mensagem dos metadados no Mem0 para reduzir inchaço  
+  - Corrigido suporte à métrica de distância L2 para compatibilidade retroativa na busca vetorial  
+
+  ## Novos Recursos e Melhorias
+  
+  - Introduzida gestão de contexto de plataforma com segurança de threads  
+  - Adicionado cache da duração de testes para execuções otimizadas do `pytest-split`  
+  - Melhorias de traces efêmeros para melhor controle de rastreamento  
+  - Parâmetros de busca para RAG, conhecimento e memória totalmente configuráveis  
+  - Habilitado ChromaDB para usar a OpenAI API para funções de embedding  
+  - Adicionadas ferramentas de observabilidade mais profundas para insights ao nível do usuário  
+  - Sistema de armazenamento RAG unificado com suporte a cliente específico por instância  
+
+  ## Documentação e Guias
+  
+  - Atualizadas referências do `RagTool` para refletir a implementação nativa de RAG do CrewAI  
+  - Melhorada documentação interna para adaptadores de agente `langgraph` e `openai` com anotações de tipo e docstrings  
+
+</Update>
+
+<Update label="11 set 2025">
+  ## v0.186.1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.186.1)
+
+  ## O que Mudou
+
+  - Corrigida falha silenciosa de reversão quando a versão não era encontrada  
+  - Versão do CrewAI atualizada para 0.186.1 e dependências do CLI atualizadas  
+
+</Update>
+
+<Update label="10 set 2025">
+  ## v0.186.0
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.186.0)
+
+  ## O que Mudou
+
+  - Consulte as notas de lançamento no GitHub para detalhes completos
+
+</Update>
+
 <Update label="04 set 2025">
   ## v0.177.0
 

docs/pt-BR/quickstart.mdx

@@ -27,7 +27,7 @@ Siga os passos abaixo para começar a tripular! 🚣‍♂️
   <Step title="Navegue até o novo projeto da sua tripulação">
     <CodeGroup>
       ```shell Terminal
-      cd latest-ai-development
+      cd latest_ai_development
       ```
     </CodeGroup>
   </Step>

examples/dynamic_task_ordering_example.py

@@ -0,0 +1,113 @@
+"""
+Example demonstrating dynamic task ordering in CrewAI.
+
+This example shows how to use the task_ordering_callback to dynamically
+determine the execution order of tasks based on runtime conditions.
+"""
+
+from crewai import Agent, Crew, Task
+from crewai.process import Process
+
+
+def priority_based_ordering(all_tasks, completed_outputs, current_index):
+    """
+    Order tasks by priority (lower number = higher priority).
+
+    Args:
+        all_tasks: List of all tasks in the crew
+        completed_outputs: List of TaskOutput objects for completed tasks
+        current_index: Current task index (for default ordering)
+
+    Returns:
+        int: Index of next task to execute
+        Task: Task object to execute next
+        None: Use default ordering
+    """
+    completed_tasks = {id(task) for task in all_tasks if task.output is not None}
+    
+    remaining_tasks = [
+        (i, task) for i, task in enumerate(all_tasks)
+        if id(task) not in completed_tasks
+    ]
+    
+    if not remaining_tasks:
+        return None
+    
+    remaining_tasks.sort(key=lambda x: getattr(x[1], 'priority', 999))
+    
+    return remaining_tasks[0][0]
+
+
+def conditional_ordering(all_tasks, completed_outputs, current_index):
+    """
+    Order tasks based on previous task outputs.
+
+    This example shows how to make task ordering decisions based on
+    the results of previously completed tasks.
+    """
+    if len(completed_outputs) == 0:
+        return 0
+    
+    last_output = completed_outputs[-1]
+    
+    if "urgent" in last_output.raw.lower():
+        completed_tasks = {id(task) for task in all_tasks if task.output is not None}
+        for i, task in enumerate(all_tasks):
+            if (hasattr(task, 'priority') and task.priority == 1 and 
+                id(task) not in completed_tasks):
+                return i
+    
+    return None
+
+
+researcher = Agent(
+    role="Research Analyst",
+    goal="Gather and analyze information",
+    backstory="Expert at finding and synthesizing information"
+)
+
+writer = Agent(
+    role="Content Writer", 
+    goal="Create compelling content",
+    backstory="Skilled at crafting engaging narratives"
+)
+
+reviewer = Agent(
+    role="Quality Reviewer",
+    goal="Ensure content quality",
+    backstory="Meticulous attention to detail"
+)
+
+research_task = Task(
+    description="Research the latest trends in AI",
+    expected_output="Comprehensive research report",
+    agent=researcher
+)
+research_task.priority = 2
+
+urgent_task = Task(
+    description="Write urgent press release",
+    expected_output="Press release draft", 
+    agent=writer
+)
+urgent_task.priority = 1
+
+review_task = Task(
+    description="Review and edit content",
+    expected_output="Polished final content",
+    agent=reviewer
+)
+review_task.priority = 3
+
+crew = Crew(
+    agents=[researcher, writer, reviewer],
+    tasks=[research_task, urgent_task, review_task],
+    process=Process.sequential,
+    task_ordering_callback=priority_based_ordering,
+    verbose=True
+)
+
+if __name__ == "__main__":
+    print("Starting crew with dynamic task ordering...")
+    result = crew.kickoff()
+    print(f"Completed {len(result.tasks_output)} tasks")

pyproject.toml

@@ -9,7 +9,7 @@ authors = [
 ]
 dependencies = [
     # Core Dependencies
-    "pydantic>=2.4.2",
+    "pydantic>=2.11.9",
     "openai>=1.13.3",
     "litellm==1.74.9",
     "instructor>=1.3.3",
@@ -21,13 +21,12 @@ dependencies = [
     "opentelemetry-sdk>=1.30.0",
     "opentelemetry-exporter-otlp-proto-http>=1.30.0",
     # Data Handling
-    "chromadb>=0.5.23",
+    "chromadb~=1.1.0",
     "tokenizers>=0.20.3",
-    "onnxruntime==1.22.0",
     "openpyxl>=3.1.5",
     "pyvis>=0.3.2",
     # Authentication and Security
-    "python-dotenv>=1.0.0",
+    "python-dotenv>=1.1.1",
     "pyjwt>=2.9.0",
     # Configuration and Utils
     "click>=8.1.7",
@@ -40,6 +39,7 @@ dependencies = [
     "blinker>=1.9.0",
     "json5>=0.10.0",
     "portalocker==2.7.0",
+    "pydantic-settings>=2.10.1",
 ]
 
 [project.urls]
@@ -48,7 +48,9 @@ Documentation = "https://docs.crewai.com"
 Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
-tools = ["crewai-tools~=0.71.0"]
+tools = [
+    "crewai-tools>=0.74.0",
+]
 embeddings = [
     "tiktoken~=0.8.0"
 ]
@@ -71,24 +73,30 @@ aisuite = [
 qdrant = [
     "qdrant-client[fastembed]>=1.14.3",
 ]
+aws = [
+    "boto3>=1.40.38",
+]
+watson = [
+    "ibm-watsonx-ai>=1.3.39",
+]
+voyageai = [
+    "voyageai>=0.3.5",
+]
 
-[tool.uv]
-dev-dependencies = [
-    "ruff>=0.12.11",
-    "mypy>=1.17.1",
+[dependency-groups]
+dev = [
+    "ruff>=0.13.1",
+    "mypy>=1.18.2",
     "pre-commit>=4.3.0",
     "bandit>=1.8.6",
-    "pillow>=10.2.0",
-    "cairosvg>=2.7.1",
-    "pytest>=8.0.0",
-    "python-dotenv>=1.0.0",
-    "pytest-asyncio>=0.23.7",
-    "pytest-subprocess>=1.5.2",
-    "pytest-recording>=0.13.2",
-    "pytest-randomly>=3.16.0",
-    "pytest-timeout>=2.3.1",
-    "pytest-xdist>=3.6.1",
-    "pytest-split>=0.9.0",
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "pytest-subprocess>=1.5.3",
+    "pytest-recording>=0.13.4",
+    "pytest-randomly>=4.0.1",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "pytest-split>=0.10.0",
     "types-requests==2.32.*",
     "types-pyyaml==6.0.*",
     "types-regex==2024.11.6.*",
@@ -131,13 +139,15 @@ select = [
     "I001",   # sort imports
     "I002",   # remove unused imports
 ]
-ignore = ["E501"]  # ignore line too long
+ignore = ["E501"]  # ignore line too long globally
 
 [tool.ruff.lint.per-file-ignores]
-"tests/**/*.py" = ["S101"]  # Allow assert statements in tests
+"tests/**/*.py" = ["S101", "RET504"]  # Allow assert statements and unnecessary assignments before return in tests
 
 [tool.mypy]
-exclude = ["src/crewai/cli/templates", "tests"]
+exclude = ["src/crewai/cli/templates", "tests/"]
+plugins = ["pydantic.mypy"]
+
 
 [tool.bandit]
 exclude_dirs = ["src/crewai/cli/templates"]

src/crewai/__init__.py

@@ -40,7 +40,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-
+__version__ = "0.201.1"
 _telemetry_submitted = False
 
 
@@ -51,13 +51,16 @@ def _track_install() -> None:
     if _telemetry_submitted or Telemetry._is_telemetry_disabled():
         return
 
-    pixel_url = "https://api.scarf.sh/v2/packages/CrewAI/crewai/docs/00f2dad1-8334-4a39-934e-003b2e1146db"
+    try:
+        pixel_url = "https://api.scarf.sh/v2/packages/CrewAI/crewai/docs/00f2dad1-8334-4a39-934e-003b2e1146db"
 
-    req = urllib.request.Request(pixel_url)  # noqa: S310
-    req.add_header("User-Agent", f"CrewAI-Python/{__version__}")
+        req = urllib.request.Request(pixel_url)  # noqa: S310
+        req.add_header("User-Agent", f"CrewAI-Python/{__version__}")
 
-    with urllib.request.urlopen(req, timeout=2):  # noqa: S310
-        _telemetry_submitted = True
+        with urllib.request.urlopen(req, timeout=2):  # noqa: S310
+            _telemetry_submitted = True
+    except Exception:  # noqa: S110
+        pass
 
 
 def _track_install_async() -> None:
@@ -68,8 +71,6 @@ def _track_install_async() -> None:
 
 
 _track_install_async()
-
-__version__ = "0.186.0"
 __all__ = [
     "LLM",
     "Agent",

src/crewai/agent.py

@@ -1,17 +1,10 @@
 import shutil
 import subprocess
 import time
+from collections.abc import Callable, Sequence
 from typing import (
     Any,
-    Callable,
-    Dict,
-    List,
     Literal,
-    Optional,
-    Sequence,
-    Tuple,
-    Type,
-    Union,
 )
 
 from pydantic import Field, InstanceOf, PrivateAttr, model_validator
@@ -19,12 +12,31 @@ from pydantic import Field, InstanceOf, PrivateAttr, model_validator
 from crewai.agents import CacheHandler
 from crewai.agents.agent_builder.base_agent import BaseAgent
 from crewai.agents.crew_agent_executor import CrewAgentExecutor
+from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.agent_events import (
+    AgentExecutionCompletedEvent,
+    AgentExecutionErrorEvent,
+    AgentExecutionStartedEvent,
+)
+from crewai.events.types.knowledge_events import (
+    KnowledgeQueryCompletedEvent,
+    KnowledgeQueryFailedEvent,
+    KnowledgeQueryStartedEvent,
+    KnowledgeRetrievalCompletedEvent,
+    KnowledgeRetrievalStartedEvent,
+    KnowledgeSearchQueryFailedEvent,
+)
+from crewai.events.types.memory_events import (
+    MemoryRetrievalCompletedEvent,
+    MemoryRetrievalStartedEvent,
+)
 from crewai.knowledge.knowledge import Knowledge
 from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
 from crewai.knowledge.utils.knowledge_utils import extract_knowledge_context
 from crewai.lite_agent import LiteAgent, LiteAgentOutput
 from crewai.llm import BaseLLM
 from crewai.memory.contextual.contextual_memory import ContextualMemory
+from crewai.rag.embeddings.types import EmbedderConfig
 from crewai.security import Fingerprint
 from crewai.task import Task
 from crewai.tools import BaseTool
@@ -38,24 +50,6 @@ from crewai.utilities.agent_utils import (
 )
 from crewai.utilities.constants import TRAINED_AGENTS_DATA_FILE, TRAINING_DATA_FILE
 from crewai.utilities.converter import generate_model_description
-from crewai.events.types.agent_events import (
-    AgentExecutionCompletedEvent,
-    AgentExecutionErrorEvent,
-    AgentExecutionStartedEvent,
-)
-from crewai.events.event_bus import crewai_event_bus
-from crewai.events.types.memory_events import (
-    MemoryRetrievalStartedEvent,
-    MemoryRetrievalCompletedEvent,
-)
-from crewai.events.types.knowledge_events import (
-    KnowledgeQueryCompletedEvent,
-    KnowledgeQueryFailedEvent,
-    KnowledgeQueryStartedEvent,
-    KnowledgeRetrievalCompletedEvent,
-    KnowledgeRetrievalStartedEvent,
-    KnowledgeSearchQueryFailedEvent,
-)
 from crewai.utilities.llm_utils import create_llm
 from crewai.utilities.token_counter_callback import TokenCalcHandler
 from crewai.utilities.training_handler import CrewTrainingHandler
@@ -87,36 +81,36 @@ class Agent(BaseAgent):
     """
 
     _times_executed: int = PrivateAttr(default=0)
-    max_execution_time: Optional[int] = Field(
+    max_execution_time: int | None = Field(
         default=None,
         description="Maximum execution time for an agent to execute a task",
     )
     agent_ops_agent_name: str = None  # type: ignore # Incompatible types in assignment (expression has type "None", variable has type "str")
     agent_ops_agent_id: str = None  # type: ignore # Incompatible types in assignment (expression has type "None", variable has type "str")
-    step_callback: Optional[Any] = Field(
+    step_callback: Any | None = Field(
         default=None,
         description="Callback to be executed after each step of the agent execution.",
     )
-    use_system_prompt: Optional[bool] = Field(
+    use_system_prompt: bool | None = Field(
         default=True,
         description="Use system prompt for the agent.",
     )
-    llm: Union[str, InstanceOf[BaseLLM], Any] = Field(
+    llm: str | InstanceOf[BaseLLM] | Any = Field(
         description="Language model that will run the agent.", default=None
     )
-    function_calling_llm: Optional[Union[str, InstanceOf[BaseLLM], Any]] = Field(
+    function_calling_llm: str | InstanceOf[BaseLLM] | Any | None = Field(
         description="Language model that will run the agent.", default=None
     )
-    system_template: Optional[str] = Field(
+    system_template: str | None = Field(
         default=None, description="System format for the agent."
     )
-    prompt_template: Optional[str] = Field(
+    prompt_template: str | None = Field(
         default=None, description="Prompt format for the agent."
     )
-    response_template: Optional[str] = Field(
+    response_template: str | None = Field(
         default=None, description="Response format for the agent."
     )
-    allow_code_execution: Optional[bool] = Field(
+    allow_code_execution: bool | None = Field(
         default=False, description="Enable code execution for the agent."
     )
     respect_context_window: bool = Field(
@@ -147,31 +141,31 @@ class Agent(BaseAgent):
         default=False,
         description="Whether the agent should reflect and create a plan before executing a task.",
     )
-    max_reasoning_attempts: Optional[int] = Field(
+    max_reasoning_attempts: int | None = Field(
         default=None,
         description="Maximum number of reasoning attempts before executing the task. If None, will try until ready.",
     )
-    embedder: Optional[Dict[str, Any]] = Field(
+    embedder: EmbedderConfig | None = Field(
         default=None,
         description="Embedder configuration for the agent.",
     )
-    agent_knowledge_context: Optional[str] = Field(
+    agent_knowledge_context: str | None = Field(
         default=None,
         description="Knowledge context for the agent.",
     )
-    crew_knowledge_context: Optional[str] = Field(
+    crew_knowledge_context: str | None = Field(
         default=None,
         description="Knowledge context for the crew.",
     )
-    knowledge_search_query: Optional[str] = Field(
+    knowledge_search_query: str | None = Field(
         default=None,
         description="Knowledge search query for the agent dynamically generated by the agent.",
     )
-    from_repository: Optional[str] = Field(
+    from_repository: str | None = Field(
         default=None,
         description="The Agent's role to be used from your repository.",
     )
-    guardrail: Optional[Union[Callable[[Any], Tuple[bool, Any]], str]] = Field(
+    guardrail: Callable[[Any], tuple[bool, Any]] | str | None = Field(
         default=None,
         description="Function or string description of a guardrail to validate agent output",
     )
@@ -180,7 +174,7 @@ class Agent(BaseAgent):
     )
 
     @model_validator(mode="before")
-    def validate_from_repository(cls, v):
+    def validate_from_repository(cls, v): # noqa: N805
         if v is not None and (from_repository := v.get("from_repository")):
             return load_agent_from_repository(from_repository) | v
         return v
@@ -208,7 +202,7 @@ class Agent(BaseAgent):
             self.cache_handler = CacheHandler()
         self.set_cache_handler(self.cache_handler)
 
-    def set_knowledge(self, crew_embedder: Optional[Dict[str, Any]] = None):
+    def set_knowledge(self, crew_embedder: EmbedderConfig | None = None):
         try:
             if self.embedder is None and crew_embedder:
                 self.embedder = crew_embedder
@@ -224,7 +218,7 @@ class Agent(BaseAgent):
                     )
                     self.knowledge.add_sources()
         except (TypeError, ValueError) as e:
-            raise ValueError(f"Invalid Knowledge Configuration: {str(e)}")
+            raise ValueError(f"Invalid Knowledge Configuration: {e!s}") from e
 
     def _is_any_available_memory(self) -> bool:
         """Check if any memory is available."""
@@ -244,8 +238,8 @@ class Agent(BaseAgent):
     def execute_task(
         self,
         task: Task,
-        context: Optional[str] = None,
-        tools: Optional[List[BaseTool]] = None,
+        context: str | None = None,
+        tools: list[BaseTool] | None = None,
     ) -> str:
         """Execute a task with the agent.
 
@@ -278,11 +272,9 @@ class Agent(BaseAgent):
                 task.description += f"\n\nReasoning Plan:\n{reasoning_output.plan.plan}"
             except Exception as e:
                 if hasattr(self, "_logger"):
-                    self._logger.log(
-                        "error", f"Error during reasoning process: {str(e)}"
-                    )
+                    self._logger.log("error", f"Error during reasoning process: {e!s}")
                 else:
-                    print(f"Error during reasoning process: {str(e)}")
+                    print(f"Error during reasoning process: {e!s}")
 
         self._inject_date_to_task(task)
 
@@ -335,7 +327,7 @@ class Agent(BaseAgent):
                 agent=self,
                 task=task,
             )
-            memory = contextual_memory.build_context_for_task(task, context)
+            memory = contextual_memory.build_context_for_task(task, context)  # type: ignore[arg-type]
             if memory.strip() != "":
                 task_prompt += self.i18n.slice("memory").format(memory=memory)
 
@@ -525,14 +517,14 @@ class Agent(BaseAgent):
 
             try:
                 return future.result(timeout=timeout)
-            except concurrent.futures.TimeoutError:
+            except concurrent.futures.TimeoutError as e:
                 future.cancel()
                 raise TimeoutError(
                     f"Task '{task.description}' execution timed out after {timeout} seconds. Consider increasing max_execution_time or optimizing the task."
-                )
+                ) from e
             except Exception as e:
                 future.cancel()
-                raise RuntimeError(f"Task execution failed: {str(e)}")
+                raise RuntimeError(f"Task execution failed: {e!s}") from e
 
     def _execute_without_timeout(self, task_prompt: str, task: Task) -> str:
         """Execute a task without a timeout.
@@ -554,14 +546,14 @@ class Agent(BaseAgent):
         )["output"]
 
     def create_agent_executor(
-        self, tools: Optional[List[BaseTool]] = None, task=None
+        self, tools: list[BaseTool] | None = None, task=None
     ) -> None:
         """Create an agent executor for the agent.
 
         Returns:
             An instance of the CrewAgentExecutor class.
         """
-        raw_tools: List[BaseTool] = tools or self.tools or []
+        raw_tools: list[BaseTool] = tools or self.tools or []
         parsed_tools = parse_tools(raw_tools)
 
         prompt = Prompts(
@@ -587,7 +579,7 @@ class Agent(BaseAgent):
             agent=self,
             crew=self.crew,
             tools=parsed_tools,
-            prompt=prompt,
+            prompt=prompt,  # type: ignore[arg-type]
             original_tools=raw_tools,
             stop_words=stop_words,
             max_iter=self.max_iter,
@@ -603,10 +595,9 @@ class Agent(BaseAgent):
             callbacks=[TokenCalcHandler(self._token_process)],
         )
 
-    def get_delegation_tools(self, agents: List[BaseAgent]):
+    def get_delegation_tools(self, agents: list[BaseAgent]):
         agent_tools = AgentTools(agents=agents)
-        tools = agent_tools.tools()
-        return tools
+        return agent_tools.tools()
 
     def get_multimodal_tools(self) -> Sequence[BaseTool]:
         from crewai.tools.agent_tools.add_image_tool import AddImageTool
@@ -654,7 +645,7 @@ class Agent(BaseAgent):
                 )
         return task_prompt
 
-    def _render_text_description(self, tools: List[Any]) -> str:
+    def _render_text_description(self, tools: list[Any]) -> str:
         """Render the tool name and description in plain text.
 
         Output will be in the format of:
@@ -664,15 +655,13 @@ class Agent(BaseAgent):
             search: This tool is used for search
             calculator: This tool is used for math
         """
-        description = "\n".join(
+        return "\n".join(
             [
                 f"Tool name: {tool.name}\nTool description:\n{tool.description}"
                 for tool in tools
             ]
         )
 
-        return description
-
     def _inject_date_to_task(self, task):
         """Inject the current date into the task description if inject_date is enabled."""
         if self.inject_date:
@@ -696,13 +685,13 @@ class Agent(BaseAgent):
                 if not is_valid:
                     raise ValueError(f"Invalid date format: {self.date_format}")
 
-                current_date: str = datetime.now().strftime(self.date_format)
+                current_date = datetime.now().strftime(self.date_format)
                 task.description += f"\n\nCurrent Date: {current_date}"
             except Exception as e:
                 if hasattr(self, "_logger"):
-                    self._logger.log("warning", f"Failed to inject date: {str(e)}")
+                    self._logger.log("warning", f"Failed to inject date: {e!s}")
                 else:
-                    print(f"Warning: Failed to inject date: {str(e)}")
+                    print(f"Warning: Failed to inject date: {e!s}")
 
     def _validate_docker_installation(self) -> None:
         """Check if Docker is installed and running."""
@@ -713,15 +702,15 @@ class Agent(BaseAgent):
 
         try:
             subprocess.run(
-                ["docker", "info"],
+                ["/usr/bin/docker", "info"],
                 check=True,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
             )
-        except subprocess.CalledProcessError:
+        except subprocess.CalledProcessError as e:
             raise RuntimeError(
                 f"Docker is not running. Please start Docker to use code execution with agent: {self.role}"
-            )
+            ) from e
 
     def __repr__(self):
         return f"Agent(role={self.role}, goal={self.goal}, backstory={self.backstory})"
@@ -796,8 +785,8 @@ class Agent(BaseAgent):
 
     def kickoff(
         self,
-        messages: Union[str, List[Dict[str, str]]],
-        response_format: Optional[Type[Any]] = None,
+        messages: str | list[dict[str, str]],
+        response_format: type[Any] | None = None,
     ) -> LiteAgentOutput:
         """
         Execute the agent with the given messages using a LiteAgent instance.
@@ -836,8 +825,8 @@ class Agent(BaseAgent):
 
     async def kickoff_async(
         self,
-        messages: Union[str, List[Dict[str, str]]],
-        response_format: Optional[Type[Any]] = None,
+        messages: str | list[dict[str, str]],
+        response_format: type[Any] | None = None,
     ) -> LiteAgentOutput:
         """
         Execute the agent asynchronously with the given messages using a LiteAgent instance.

src/crewai/agents/__init__.py

@@ -1,5 +1,12 @@
 from crewai.agents.cache.cache_handler import CacheHandler
-from crewai.agents.parser import parse, AgentAction, AgentFinish, OutputParserException
+from crewai.agents.parser import AgentAction, AgentFinish, OutputParserError, parse
 from crewai.agents.tools_handler import ToolsHandler
 
-__all__ = ["CacheHandler", "parse", "AgentAction", "AgentFinish", "OutputParserException", "ToolsHandler"]
+__all__ = [
+    "AgentAction",
+    "AgentFinish",
+    "CacheHandler",
+    "OutputParserError",
+    "ToolsHandler",
+    "parse",
+]

src/crewai/agents/agent_adapters/base_agent_adapter.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional
+from typing import Any
 
-from pydantic import PrivateAttr
+from pydantic import ConfigDict, PrivateAttr
 
 from crewai.agent import BaseAgent
 from crewai.tools import BaseTool
@@ -16,22 +16,21 @@ class BaseAgentAdapter(BaseAgent, ABC):
     """
 
     adapted_structured_output: bool = False
-    _agent_config: Optional[Dict[str, Any]] = PrivateAttr(default=None)
+    _agent_config: dict[str, Any] | None = PrivateAttr(default=None)
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any):
+    def __init__(self, agent_config: dict[str, Any] | None = None, **kwargs: Any):
         super().__init__(adapted_agent=True, **kwargs)
         self._agent_config = agent_config
 
     @abstractmethod
-    def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
+    def configure_tools(self, tools: list[BaseTool] | None = None) -> None:
         """Configure and adapt tools for the specific agent implementation.
 
         Args:
             tools: Optional list of BaseTool instances to be configured
         """
-        pass
 
     def configure_structured_output(self, structured_output: Any) -> None:
         """Configure the structured output for the specific agent implementation.
@@ -39,4 +38,3 @@ class BaseAgentAdapter(BaseAgent, ABC):
         Args:
             structured_output: The structured output to be configured
         """
-        pass

src/crewai/agents/agent_adapters/base_tool_adapter.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Any, List, Optional
+from typing import Any
 
 from crewai.tools.base_tool import BaseTool
 
@@ -12,23 +12,22 @@ class BaseToolAdapter(ABC):
     different frameworks and platforms.
     """
 
-    original_tools: List[BaseTool]
-    converted_tools: List[Any]
+    original_tools: list[BaseTool]
+    converted_tools: list[Any]
 
-    def __init__(self, tools: Optional[List[BaseTool]] = None):
+    def __init__(self, tools: list[BaseTool] | None = None):
         self.original_tools = tools or []
         self.converted_tools = []
 
     @abstractmethod
-    def configure_tools(self, tools: List[BaseTool]) -> None:
+    def configure_tools(self, tools: list[BaseTool]) -> None:
         """Configure and convert tools for the specific implementation.
 
         Args:
             tools: List of BaseTool instances to be configured and converted
         """
-        pass
 
-    def tools(self) -> List[Any]:
+    def tools(self) -> list[Any]:
         """Return all converted tools."""
         return self.converted_tools
 

src/crewai/agents/agent_adapters/langgraph/langgraph_adapter.py

@@ -1,47 +1,56 @@
-from typing import Any, Dict, List, Optional
+"""LangGraph agent adapter for CrewAI integration.
 
-from pydantic import Field, PrivateAttr
+This module contains the LangGraphAgentAdapter class that integrates LangGraph ReAct agents
+with CrewAI's agent system. Provides memory persistence, tool integration, and structured
+output functionality.
+"""
+
+from collections.abc import Callable
+from typing import Any, cast
+
+from pydantic import ConfigDict, Field, PrivateAttr
 
 from crewai.agents.agent_adapters.base_agent_adapter import BaseAgentAdapter
 from crewai.agents.agent_adapters.langgraph.langgraph_tool_adapter import (
     LangGraphToolAdapter,
 )
+from crewai.agents.agent_adapters.langgraph.protocols import (
+    LangGraphCheckPointMemoryModule,
+    LangGraphPrebuiltModule,
+)
 from crewai.agents.agent_adapters.langgraph.structured_output_converter import (
     LangGraphConverterAdapter,
 )
 from crewai.agents.agent_builder.base_agent import BaseAgent
-from crewai.tools.agent_tools.agent_tools import AgentTools
-from crewai.tools.base_tool import BaseTool
-from crewai.utilities import Logger
-from crewai.utilities.converter import Converter
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.agent_events import (
     AgentExecutionCompletedEvent,
     AgentExecutionErrorEvent,
     AgentExecutionStartedEvent,
 )
-
-try:
-    from langgraph.checkpoint.memory import MemorySaver
-    from langgraph.prebuilt import create_react_agent
-
-    LANGGRAPH_AVAILABLE = True
-except ImportError:
-    LANGGRAPH_AVAILABLE = False
+from crewai.tools.agent_tools.agent_tools import AgentTools
+from crewai.tools.base_tool import BaseTool
+from crewai.utilities import Logger
+from crewai.utilities.converter import Converter
+from crewai.utilities.import_utils import require
 
 
 class LangGraphAgentAdapter(BaseAgentAdapter):
-    """Adapter for LangGraph agents to work with CrewAI."""
+    """Adapter for LangGraph agents to work with CrewAI.
 
-    model_config = {"arbitrary_types_allowed": True}
+    This adapter integrates LangGraph's ReAct agents with CrewAI's agent system,
+    providing memory persistence, tool integration, and structured output support.
+    """
 
-    _logger: Logger = PrivateAttr(default_factory=lambda: Logger())
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    _logger: Logger = PrivateAttr(default_factory=Logger)
     _tool_adapter: LangGraphToolAdapter = PrivateAttr()
     _graph: Any = PrivateAttr(default=None)
     _memory: Any = PrivateAttr(default=None)
     _max_iterations: int = PrivateAttr(default=10)
     function_calling_llm: Any = Field(default=None)
-    step_callback: Any = Field(default=None)
+    step_callback: Callable[..., Any] | None = Field(default=None)
 
     model: str = Field(default="gpt-4o")
     verbose: bool = Field(default=False)
@@ -51,17 +60,24 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
         role: str,
         goal: str,
         backstory: str,
-        tools: Optional[List[BaseTool]] = None,
+        tools: list[BaseTool] | None = None,
         llm: Any = None,
         max_iterations: int = 10,
-        agent_config: Optional[Dict[str, Any]] = None,
+        agent_config: dict[str, Any] | None = None,
         **kwargs,
-    ):
-        """Initialize the LangGraph agent adapter."""
-        if not LANGGRAPH_AVAILABLE:
-            raise ImportError(
-                "LangGraph Agent Dependencies are not installed. Please install it using `uv add langchain-core langgraph`"
-            )
+    ) -> None:
+        """Initialize the LangGraph agent adapter.
+
+        Args:
+            role: The role description for the agent.
+            goal: The primary goal the agent should achieve.
+            backstory: Background information about the agent.
+            tools: Optional list of tools available to the agent.
+            llm: Language model to use, defaults to gpt-4o.
+            max_iterations: Maximum number of iterations for task execution.
+            agent_config: Additional configuration for the LangGraph agent.
+            **kwargs: Additional arguments passed to the base adapter.
+        """
         super().__init__(
             role=role,
             goal=goal,
@@ -72,46 +88,65 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
             **kwargs,
         )
         self._tool_adapter = LangGraphToolAdapter(tools=tools)
-        self._converter_adapter = LangGraphConverterAdapter(self)
+        self._converter_adapter: LangGraphConverterAdapter = LangGraphConverterAdapter(
+            self
+        )
         self._max_iterations = max_iterations
         self._setup_graph()
 
     def _setup_graph(self) -> None:
-        """Set up the LangGraph workflow graph."""
-        try:
-            self._memory = MemorySaver()
+        """Set up the LangGraph workflow graph.
 
-            converted_tools: List[Any] = self._tool_adapter.tools()
-            if self._agent_config:
-                self._graph = create_react_agent(
-                    model=self.llm,
-                    tools=converted_tools,
-                    checkpointer=self._memory,
-                    debug=self.verbose,
-                    **self._agent_config,
-                )
-            else:
-                self._graph = create_react_agent(
-                    model=self.llm,
-                    tools=converted_tools or [],
-                    checkpointer=self._memory,
-                    debug=self.verbose,
-                )
+        Initializes the memory saver and creates a ReAct agent with the configured
+        tools, memory checkpointer, and debug settings.
+        """
 
-        except ImportError as e:
-            self._logger.log(
-                "error", f"Failed to import LangGraph dependencies: {str(e)}"
+        memory_saver: type[Any] = cast(
+            LangGraphCheckPointMemoryModule,
+            require(
+                "langgraph.checkpoint.memory",
+                purpose="LangGraph core functionality",
+            ),
+        ).MemorySaver
+        create_react_agent: Callable[..., Any] = cast(
+            LangGraphPrebuiltModule,
+            require(
+                "langgraph.prebuilt",
+                purpose="LangGraph core functionality",
+            ),
+        ).create_react_agent
+
+        self._memory = memory_saver()
+
+        converted_tools: list[Any] = self._tool_adapter.tools()
+        if self._agent_config:
+            self._graph = create_react_agent(
+                model=self.llm,
+                tools=converted_tools,
+                checkpointer=self._memory,
+                debug=self.verbose,
+                **self._agent_config,
+            )
+        else:
+            self._graph = create_react_agent(
+                model=self.llm,
+                tools=converted_tools or [],
+                checkpointer=self._memory,
+                debug=self.verbose,
             )
-            raise
-        except Exception as e:
-            self._logger.log("error", f"Error setting up LangGraph agent: {str(e)}")
-            raise
 
     def _build_system_prompt(self) -> str:
-        """Build a system prompt for the LangGraph agent."""
+        """Build a system prompt for the LangGraph agent.
+
+        Creates a prompt that includes the agent's role, goal, and backstory,
+        then enhances it through the converter adapter for structured output.
+
+        Returns:
+            The complete system prompt string.
+        """
         base_prompt = f"""
             You are {self.role}.
-        
+
             Your goal is: {self.goal}
 
             Your backstory: {self.backstory}
@@ -123,10 +158,25 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
     def execute_task(
         self,
         task: Any,
-        context: Optional[str] = None,
-        tools: Optional[List[BaseTool]] = None,
+        context: str | None = None,
+        tools: list[BaseTool] | None = None,
     ) -> str:
-        """Execute a task using the LangGraph workflow."""
+        """Execute a task using the LangGraph workflow.
+
+        Configures the agent, processes the task through the LangGraph workflow,
+        and handles event emission for execution tracking.
+
+        Args:
+            task: The task object to execute.
+            context: Optional context information for the task.
+            tools: Optional additional tools for this specific execution.
+
+        Returns:
+            The final answer from the task execution.
+
+        Raises:
+            Exception: If task execution fails.
+        """
         self.create_agent_executor(tools)
 
         self.configure_structured_output(task)
@@ -151,9 +201,11 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
 
             session_id = f"task_{id(task)}"
 
-            config = {"configurable": {"thread_id": session_id}}
+            config: dict[str, dict[str, str]] = {
+                "configurable": {"thread_id": session_id}
+            }
 
-            result = self._graph.invoke(
+            result: dict[str, Any] = self._graph.invoke(
                 {
                     "messages": [
                         ("system", self._build_system_prompt()),
@@ -163,10 +215,10 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
                 config,
             )
 
-            messages = result.get("messages", [])
-            last_message = messages[-1] if messages else None
+            messages: list[Any] = result.get("messages", [])
+            last_message: Any = messages[-1] if messages else None
 
-            final_answer = ""
+            final_answer: str = ""
             if isinstance(last_message, dict):
                 final_answer = last_message.get("content", "")
             elif hasattr(last_message, "content"):
@@ -186,7 +238,7 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
             return final_answer
 
         except Exception as e:
-            self._logger.log("error", f"Error executing LangGraph task: {str(e)}")
+            self._logger.log("error", f"Error executing LangGraph task: {e!s}")
             crewai_event_bus.emit(
                 self,
                 event=AgentExecutionErrorEvent(
@@ -197,29 +249,67 @@ class LangGraphAgentAdapter(BaseAgentAdapter):
             )
             raise
 
-    def create_agent_executor(self, tools: Optional[List[BaseTool]] = None) -> None:
-        """Configure the LangGraph agent for execution."""
+    def create_agent_executor(self, tools: list[BaseTool] | None = None) -> None:
+        """Configure the LangGraph agent for execution.
+
+        Args:
+            tools: Optional tools to configure for the agent.
+        """
         self.configure_tools(tools)
 
-    def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
-        """Configure tools for the LangGraph agent."""
+    def configure_tools(self, tools: list[BaseTool] | None = None) -> None:
+        """Configure tools for the LangGraph agent.
+
+        Merges additional tools with existing ones and updates the graph's
+        available tools through the tool adapter.
+
+        Args:
+            tools: Optional additional tools to configure.
+        """
         if tools:
-            all_tools = list(self.tools or []) + list(tools or [])
+            all_tools: list[BaseTool] = list(self.tools or []) + list(tools or [])
             self._tool_adapter.configure_tools(all_tools)
-            available_tools = self._tool_adapter.tools()
+            available_tools: list[Any] = self._tool_adapter.tools()
             self._graph.tools = available_tools
 
-    def get_delegation_tools(self, agents: List[BaseAgent]) -> List[BaseTool]:
-        """Implement delegation tools support for LangGraph."""
-        agent_tools = AgentTools(agents=agents)
+    def get_delegation_tools(self, agents: list[BaseAgent]) -> list[BaseTool]:
+        """Implement delegation tools support for LangGraph.
+
+        Creates delegation tools that allow this agent to delegate tasks to other agents.
+
+        Args:
+            agents: List of agents available for delegation.
+
+        Returns:
+            List of delegation tools.
+        """
+        agent_tools: AgentTools = AgentTools(agents=agents)
         return agent_tools.tools()
 
+    @staticmethod
     def get_output_converter(
-        self, llm: Any, text: str, model: Any, instructions: str
-    ) -> Any:
-        """Convert output format if needed."""
+        llm: Any, text: str, model: Any, instructions: str
+    ) -> Converter:
+        """Convert output format if needed.
+
+        Args:
+            llm: Language model instance.
+            text: Text to convert.
+            model: Model configuration.
+            instructions: Conversion instructions.
+
+        Returns:
+            Converter instance for output transformation.
+        """
         return Converter(llm=llm, text=text, model=model, instructions=instructions)
 
-    def configure_structured_output(self, task) -> None:
-        """Configure the structured output for LangGraph."""
+    def configure_structured_output(self, task: Any) -> None:
+        """Configure the structured output for LangGraph.
+
+        Uses the converter adapter to set up structured output formatting
+        based on the task requirements.
+
+        Args:
+            task: Task object containing output requirements.
+        """
         self._converter_adapter.configure_structured_output(task)

src/crewai/agents/agent_adapters/langgraph/langgraph_tool_adapter.py

@@ -1,38 +1,72 @@
+"""LangGraph tool adapter for CrewAI tool integration.
+
+This module contains the LangGraphToolAdapter class that converts CrewAI tools
+to LangGraph-compatible format using langchain_core.tools.
+"""
+
 import inspect
-from typing import Any, List, Optional
+from collections.abc import Awaitable
+from typing import Any
 
 from crewai.agents.agent_adapters.base_tool_adapter import BaseToolAdapter
 from crewai.tools.base_tool import BaseTool
 
 
 class LangGraphToolAdapter(BaseToolAdapter):
-    """Adapts CrewAI tools to LangGraph agent tool compatible format"""
+    """Adapts CrewAI tools to LangGraph agent tool compatible format.
 
-    def __init__(self, tools: Optional[List[BaseTool]] = None):
-        self.original_tools = tools or []
-        self.converted_tools = []
+    Converts CrewAI BaseTool instances to langchain_core.tools format
+    that can be used by LangGraph agents.
+    """
 
-    def configure_tools(self, tools: List[BaseTool]) -> None:
+    def __init__(self, tools: list[BaseTool] | None = None) -> None:
+        """Initialize the tool adapter.
+
+        Args:
+            tools: Optional list of CrewAI tools to adapt.
         """
-        Configure and convert CrewAI tools to LangGraph-compatible format.
-        LangGraph expects tools in langchain_core.tools format.
-        """
-        from langchain_core.tools import BaseTool, StructuredTool
+        super().__init__()
+        self.original_tools: list[BaseTool] = tools or []
+        self.converted_tools: list[Any] = []
 
-        converted_tools = []
+    def configure_tools(self, tools: list[BaseTool]) -> None:
+        """Configure and convert CrewAI tools to LangGraph-compatible format.
+
+        LangGraph expects tools in langchain_core.tools format. This method
+        converts CrewAI BaseTool instances to StructuredTool instances.
+
+        Args:
+            tools: List of CrewAI tools to convert.
+        """
+        from langchain_core.tools import BaseTool as LangChainBaseTool
+        from langchain_core.tools import StructuredTool
+
+        converted_tools: list[Any] = []
         if self.original_tools:
-            all_tools = tools + self.original_tools
+            all_tools: list[BaseTool] = tools + self.original_tools
         else:
             all_tools = tools
         for tool in all_tools:
-            if isinstance(tool, BaseTool):
+            if isinstance(tool, LangChainBaseTool):
                 converted_tools.append(tool)
                 continue
 
-            sanitized_name = self.sanitize_tool_name(tool.name)
+            sanitized_name: str = self.sanitize_tool_name(tool.name)
 
-            async def tool_wrapper(*args, tool=tool, **kwargs):
-                output = None
+            async def tool_wrapper(
+                *args: Any, tool: BaseTool = tool, **kwargs: Any
+            ) -> Any:
+                """Wrapper function to adapt CrewAI tool calls to LangGraph format.
+
+                Args:
+                    *args: Positional arguments for the tool.
+                    tool: The CrewAI tool to wrap.
+                    **kwargs: Keyword arguments for the tool.
+
+                Returns:
+                    The result from the tool execution.
+                """
+                output: Any | Awaitable[Any]
                 if len(args) > 0 and isinstance(args[0], str):
                     output = tool.run(args[0])
                 elif "input" in kwargs:
@@ -41,12 +75,12 @@ class LangGraphToolAdapter(BaseToolAdapter):
                     output = tool.run(**kwargs)
 
                 if inspect.isawaitable(output):
-                    result = await output
+                    result: Any = await output
                 else:
                     result = output
                 return result
 
-            converted_tool = StructuredTool(
+            converted_tool: StructuredTool = StructuredTool(
                 name=sanitized_name,
                 description=tool.description,
                 func=tool_wrapper,
@@ -57,5 +91,10 @@ class LangGraphToolAdapter(BaseToolAdapter):
 
         self.converted_tools = converted_tools
 
-    def tools(self) -> List[Any]:
+    def tools(self) -> list[Any]:
+        """Get the list of converted tools.
+
+        Returns:
+            List of LangGraph-compatible tools.
+        """
         return self.converted_tools or []

src/crewai/agents/agent_adapters/langgraph/protocols.py

@@ -0,0 +1,55 @@
+"""Type protocols for LangGraph modules."""
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LangGraphMemorySaver(Protocol):
+    """Protocol for LangGraph MemorySaver.
+
+    Defines the interface for LangGraph's memory persistence mechanism.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the memory saver."""
+        ...
+
+
+@runtime_checkable
+class LangGraphCheckPointMemoryModule(Protocol):
+    """Protocol for LangGraph checkpoint memory module.
+
+    Defines the interface for modules containing memory checkpoint functionality.
+    """
+
+    MemorySaver: type[LangGraphMemorySaver]
+
+
+@runtime_checkable
+class LangGraphPrebuiltModule(Protocol):
+    """Protocol for LangGraph prebuilt module.
+
+    Defines the interface for modules containing prebuilt agent factories.
+    """
+
+    def create_react_agent(
+        self,
+        model: Any,
+        tools: list[Any],
+        checkpointer: Any,
+        debug: bool = False,
+        **kwargs: Any,
+    ) -> Any:
+        """Create a ReAct agent with the given configuration.
+
+        Args:
+            model: The language model to use for the agent.
+            tools: List of tools available to the agent.
+            checkpointer: Memory checkpointer for state persistence.
+            debug: Whether to enable debug mode.
+            **kwargs: Additional configuration options.
+
+        Returns:
+            The configured ReAct agent instance.
+        """
+        ...

src/crewai/agents/agent_adapters/langgraph/structured_output_converter.py

@@ -1,21 +1,45 @@
+"""LangGraph structured output converter for CrewAI task integration.
+
+This module contains the LangGraphConverterAdapter class that handles structured
+output conversion for LangGraph agents, supporting JSON and Pydantic model formats.
+"""
+
 import json
+import re
+from typing import Any, Literal
 
 from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter
 from crewai.utilities.converter import generate_model_description
 
 
 class LangGraphConverterAdapter(BaseConverterAdapter):
-    """Adapter for handling structured output conversion in LangGraph agents"""
+    """Adapter for handling structured output conversion in LangGraph agents.
 
-    def __init__(self, agent_adapter):
-        """Initialize the converter adapter with a reference to the agent adapter"""
-        self.agent_adapter = agent_adapter
-        self._output_format = None
-        self._schema = None
-        self._system_prompt_appendix = None
+    Converts task output requirements into system prompt modifications and
+    post-processing logic to ensure agents return properly structured outputs.
+    """
 
-    def configure_structured_output(self, task) -> None:
-        """Configure the structured output for LangGraph."""
+    def __init__(self, agent_adapter: Any) -> None:
+        """Initialize the converter adapter with a reference to the agent adapter.
+
+        Args:
+            agent_adapter: The LangGraph agent adapter instance.
+        """
+        super().__init__(agent_adapter=agent_adapter)
+        self.agent_adapter: Any = agent_adapter
+        self._output_format: Literal["json", "pydantic"] | None = None
+        self._schema: str | None = None
+        self._system_prompt_appendix: str | None = None
+
+    def configure_structured_output(self, task: Any) -> None:
+        """Configure the structured output for LangGraph.
+
+        Analyzes the task's output requirements and sets up the necessary
+        formatting and validation logic.
+
+        Args:
+            task: The task object containing output format specifications.
+        """
         if not (task.output_json or task.output_pydantic):
             self._output_format = None
             self._schema = None
@@ -32,7 +56,14 @@ class LangGraphConverterAdapter(BaseConverterAdapter):
         self._system_prompt_appendix = self._generate_system_prompt_appendix()
 
     def _generate_system_prompt_appendix(self) -> str:
-        """Generate an appendix for the system prompt to enforce structured output"""
+        """Generate an appendix for the system prompt to enforce structured output.
+
+        Creates instructions that are appended to the system prompt to guide
+        the agent in producing properly formatted output.
+
+        Returns:
+            System prompt appendix string, or empty string if no structured output.
+        """
         if not self._output_format or not self._schema:
             return ""
 
@@ -41,19 +72,36 @@ Important: Your final answer MUST be provided in the following structured format
 
 {self._schema}
 
-DO NOT include any markdown code blocks, backticks, or other formatting around your response. 
+DO NOT include any markdown code blocks, backticks, or other formatting around your response.
 The output should be raw JSON that exactly matches the specified schema.
 """
 
     def enhance_system_prompt(self, original_prompt: str) -> str:
-        """Add structured output instructions to the system prompt if needed"""
+        """Add structured output instructions to the system prompt if needed.
+
+        Args:
+            original_prompt: The base system prompt.
+
+        Returns:
+            Enhanced system prompt with structured output instructions.
+        """
         if not self._system_prompt_appendix:
             return original_prompt
 
         return f"{original_prompt}\n{self._system_prompt_appendix}"
 
     def post_process_result(self, result: str) -> str:
-        """Post-process the result to ensure it matches the expected format"""
+        """Post-process the result to ensure it matches the expected format.
+
+        Attempts to extract and validate JSON content from agent responses,
+        handling cases where JSON may be wrapped in markdown or other formatting.
+
+        Args:
+            result: The raw result string from the agent.
+
+        Returns:
+            Processed result string, ideally in valid JSON format.
+        """
         if not self._output_format:
             return result
 
@@ -65,16 +113,16 @@ The output should be raw JSON that exactly matches the specified schema.
                 return result
             except json.JSONDecodeError:
                 # Try to extract JSON from the text
-                import re
-
-                json_match = re.search(r"(\{.*\})", result, re.DOTALL)
+                json_match: re.Match[str] | None = re.search(
+                    r"(\{.*})", result, re.DOTALL
+                )
                 if json_match:
                     try:
-                        extracted = json_match.group(1)
+                        extracted: str = json_match.group(1)
                         # Validate it's proper JSON
                         json.loads(extracted)
                         return extracted
-                    except:
+                    except json.JSONDecodeError:
                         pass
 
         return result

src/crewai/agents/agent_adapters/openai_agents/openai_adapter.py

@@ -1,78 +1,99 @@
-from typing import Any, List, Optional
+"""OpenAI agents adapter for CrewAI integration.
 
-from pydantic import Field, PrivateAttr
+This module contains the OpenAIAgentAdapter class that integrates OpenAI Assistants
+with CrewAI's agent system, providing tool integration and structured output support.
+"""
+
+from typing import Any, cast
+
+from pydantic import ConfigDict, Field, PrivateAttr
+from typing_extensions import Unpack
 
 from crewai.agents.agent_adapters.base_agent_adapter import BaseAgentAdapter
+from crewai.agents.agent_adapters.openai_agents.openai_agent_tool_adapter import (
+    OpenAIAgentToolAdapter,
+)
+from crewai.agents.agent_adapters.openai_agents.protocols import (
+    AgentKwargs,
+    OpenAIAgentsModule,
+)
+from crewai.agents.agent_adapters.openai_agents.protocols import (
+    OpenAIAgent as OpenAIAgentProtocol,
+)
 from crewai.agents.agent_adapters.openai_agents.structured_output_converter import (
     OpenAIConverterAdapter,
 )
 from crewai.agents.agent_builder.base_agent import BaseAgent
-from crewai.tools import BaseTool
-from crewai.tools.agent_tools.agent_tools import AgentTools
-from crewai.utilities import Logger
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.agent_events import (
     AgentExecutionCompletedEvent,
     AgentExecutionErrorEvent,
     AgentExecutionStartedEvent,
 )
+from crewai.tools import BaseTool
+from crewai.tools.agent_tools.agent_tools import AgentTools
+from crewai.utilities import Logger
+from crewai.utilities.import_utils import require
 
-try:
-    from agents import Agent as OpenAIAgent  # type: ignore
-    from agents import Runner, enable_verbose_stdout_logging  # type: ignore
-
-    from .openai_agent_tool_adapter import OpenAIAgentToolAdapter
-
-    OPENAI_AVAILABLE = True
-except ImportError:
-    OPENAI_AVAILABLE = False
+openai_agents_module = cast(
+    OpenAIAgentsModule,
+    require(
+        "agents",
+        purpose="OpenAI agents functionality",
+    ),
+)
+OpenAIAgent = openai_agents_module.Agent
+Runner = openai_agents_module.Runner
+enable_verbose_stdout_logging = openai_agents_module.enable_verbose_stdout_logging
 
 
 class OpenAIAgentAdapter(BaseAgentAdapter):
-    """Adapter for OpenAI Assistants"""
+    """Adapter for OpenAI Assistants.
 
-    model_config = {"arbitrary_types_allowed": True}
+    Integrates OpenAI Assistants API with CrewAI's agent system, providing
+    tool configuration, structured output handling, and task execution.
+    """
 
-    _openai_agent: "OpenAIAgent" = PrivateAttr()
-    _logger: Logger = PrivateAttr(default_factory=lambda: Logger())
-    _active_thread: Optional[str] = PrivateAttr(default=None)
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    _openai_agent: OpenAIAgentProtocol = PrivateAttr()
+    _logger: Logger = PrivateAttr(default_factory=Logger)
+    _active_thread: str | None = PrivateAttr(default=None)
     function_calling_llm: Any = Field(default=None)
     step_callback: Any = Field(default=None)
-    _tool_adapter: "OpenAIAgentToolAdapter" = PrivateAttr()
+    _tool_adapter: OpenAIAgentToolAdapter = PrivateAttr()
     _converter_adapter: OpenAIConverterAdapter = PrivateAttr()
 
     def __init__(
         self,
-        model: str = "gpt-4o-mini",
-        tools: Optional[List[BaseTool]] = None,
-        agent_config: Optional[dict] = None,
-        **kwargs,
-    ):
-        if not OPENAI_AVAILABLE:
-            raise ImportError(
-                "OpenAI Agent Dependencies are not installed. Please install it using `uv add openai-agents`"
-            )
-        else:
-            role = kwargs.pop("role", None)
-            goal = kwargs.pop("goal", None)
-            backstory = kwargs.pop("backstory", None)
-            super().__init__(
-                role=role,
-                goal=goal,
-                backstory=backstory,
-                tools=tools,
-                agent_config=agent_config,
-                **kwargs,
-            )
-            self._tool_adapter = OpenAIAgentToolAdapter(tools=tools)
-            self.llm = model
-            self._converter_adapter = OpenAIConverterAdapter(self)
+        **kwargs: Unpack[AgentKwargs],
+    ) -> None:
+        """Initialize the OpenAI agent adapter.
+
+        Args:
+            **kwargs: All initialization arguments including role, goal, backstory,
+                     model, tools, and agent_config.
+
+        Raises:
+            ImportError: If OpenAI agent dependencies are not installed.
+        """
+        self.llm = kwargs.pop("model", "gpt-4o-mini")
+        super().__init__(**kwargs)
+        self._tool_adapter = OpenAIAgentToolAdapter(tools=kwargs.get("tools"))
+        self._converter_adapter = OpenAIConverterAdapter(agent_adapter=self)
 
     def _build_system_prompt(self) -> str:
-        """Build a system prompt for the OpenAI agent."""
+        """Build a system prompt for the OpenAI agent.
+
+        Creates a prompt containing the agent's role, goal, and backstory,
+        then enhances it with structured output instructions if needed.
+
+        Returns:
+            The complete system prompt string.
+        """
         base_prompt = f"""
             You are {self.role}.
-        
+
             Your goal is: {self.goal}
 
             Your backstory: {self.backstory}
@@ -84,10 +105,25 @@ class OpenAIAgentAdapter(BaseAgentAdapter):
     def execute_task(
         self,
         task: Any,
-        context: Optional[str] = None,
-        tools: Optional[List[BaseTool]] = None,
+        context: str | None = None,
+        tools: list[BaseTool] | None = None,
     ) -> str:
-        """Execute a task using the OpenAI Assistant"""
+        """Execute a task using the OpenAI Assistant.
+
+        Configures the assistant, processes the task, and handles event emission
+        for execution tracking.
+
+        Args:
+            task: The task object to execute.
+            context: Optional context information for the task.
+            tools: Optional additional tools for this execution.
+
+        Returns:
+            The final answer from the task execution.
+
+        Raises:
+            Exception: If task execution fails.
+        """
         self._converter_adapter.configure_structured_output(task)
         self.create_agent_executor(tools)
 
@@ -95,7 +131,7 @@ class OpenAIAgentAdapter(BaseAgentAdapter):
             enable_verbose_stdout_logging()
 
         try:
-            task_prompt = task.prompt()
+            task_prompt: str = task.prompt()
             if context:
                 task_prompt = self.i18n.slice("task_with_context").format(
                     task=task_prompt, context=context
@@ -109,8 +145,8 @@ class OpenAIAgentAdapter(BaseAgentAdapter):
                     task=task,
                 ),
             )
-            result = self.agent_executor.run_sync(self._openai_agent, task_prompt)
-            final_answer = self.handle_execution_result(result)
+            result: Any = self.agent_executor.run_sync(self._openai_agent, task_prompt)
+            final_answer: str = self.handle_execution_result(result)
             crewai_event_bus.emit(
                 self,
                 event=AgentExecutionCompletedEvent(
@@ -120,7 +156,7 @@ class OpenAIAgentAdapter(BaseAgentAdapter):
             return final_answer
 
         except Exception as e:
-            self._logger.log("error", f"Error executing OpenAI task: {str(e)}")
+            self._logger.log("error", f"Error executing OpenAI task: {e!s}")
             crewai_event_bus.emit(
                 self,
                 event=AgentExecutionErrorEvent(
@@ -131,15 +167,22 @@ class OpenAIAgentAdapter(BaseAgentAdapter):
             )
             raise
 
-    def create_agent_executor(self, tools: Optional[List[BaseTool]] = None) -> None:
-        """
-        Configure the OpenAI agent for execution.
-        While OpenAI handles execution differently through Runner,
-        we can use this method to set up tools and configurations.
-        """
-        all_tools = list(self.tools or []) + list(tools or [])
+    def create_agent_executor(self, tools: list[BaseTool] | None = None) -> None:
+        """Configure the OpenAI agent for execution.
 
-        instructions = self._build_system_prompt()
+        While OpenAI handles execution differently through Runner,
+        this method sets up tools and agent configuration.
+
+        Args:
+            tools: Optional tools to configure for the agent.
+
+        Notes:
+            TODO: Properly type agent_executor in BaseAgent to avoid type issues
+            when assigning Runner class to this attribute.
+        """
+        all_tools: list[BaseTool] = list(self.tools or []) + list(tools or [])
+
+        instructions: str = self._build_system_prompt()
         self._openai_agent = OpenAIAgent(
             name=self.role,
             instructions=instructions,
@@ -152,27 +195,48 @@ class OpenAIAgentAdapter(BaseAgentAdapter):
 
         self.agent_executor = Runner
 
-    def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
-        """Configure tools for the OpenAI Assistant"""
+    def configure_tools(self, tools: list[BaseTool] | None = None) -> None:
+        """Configure tools for the OpenAI Assistant.
+
+        Args:
+            tools: Optional tools to configure for the assistant.
+        """
         if tools:
             self._tool_adapter.configure_tools(tools)
             if self._tool_adapter.converted_tools:
                 self._openai_agent.tools = self._tool_adapter.converted_tools
 
     def handle_execution_result(self, result: Any) -> str:
-        """Process OpenAI Assistant execution result converting any structured output to a string"""
+        """Process OpenAI Assistant execution result.
+
+        Converts any structured output to a string through the converter adapter.
+
+        Args:
+            result: The execution result from the OpenAI assistant.
+
+        Returns:
+            Processed result as a string.
+        """
         return self._converter_adapter.post_process_result(result.final_output)
 
-    def get_delegation_tools(self, agents: List[BaseAgent]) -> List[BaseTool]:
-        """Implement delegation tools support"""
-        agent_tools = AgentTools(agents=agents)
-        tools = agent_tools.tools()
-        return tools
+    def get_delegation_tools(self, agents: list[BaseAgent]) -> list[BaseTool]:
+        """Implement delegation tools support.
 
-    def configure_structured_output(self, task) -> None:
+        Creates delegation tools that allow this agent to delegate tasks to other agents.
+
+        Args:
+            agents: List of agents available for delegation.
+
+        Returns:
+            List of delegation tools.
+        """
+        agent_tools: AgentTools = AgentTools(agents=agents)
+        return agent_tools.tools()
+
+    def configure_structured_output(self, task: Any) -> None:
         """Configure the structured output for the specific agent implementation.
 
         Args:
-            structured_output: The structured output to be configured
+            task: The task object containing output format specifications.
         """
         self._converter_adapter.configure_structured_output(task)

src/crewai/agents/agent_adapters/openai_agents/openai_agent_tool_adapter.py

@@ -1,57 +1,125 @@
-import inspect
-from typing import Any, List, Optional
+"""OpenAI agent tool adapter for CrewAI tool integration.
 
-from agents import FunctionTool, Tool
+This module contains the OpenAIAgentToolAdapter class that converts CrewAI tools
+to OpenAI Assistant-compatible format using the agents library.
+"""
+
+import inspect
+import json
+import re
+from collections.abc import Awaitable
+from typing import Any, cast
 
 from crewai.agents.agent_adapters.base_tool_adapter import BaseToolAdapter
+from crewai.agents.agent_adapters.openai_agents.protocols import (
+    OpenAIFunctionTool,
+    OpenAITool,
+)
 from crewai.tools import BaseTool
+from crewai.utilities.import_utils import require
+
+agents_module = cast(
+    Any,
+    require(
+        "agents",
+        purpose="OpenAI agents functionality",
+    ),
+)
+FunctionTool = agents_module.FunctionTool
+Tool = agents_module.Tool
 
 
 class OpenAIAgentToolAdapter(BaseToolAdapter):
-    """Adapter for OpenAI Assistant tools"""
+    """Adapter for OpenAI Assistant tools.
 
-    def __init__(self, tools: Optional[List[BaseTool]] = None):
-        self.original_tools = tools or []
+    Converts CrewAI BaseTool instances to OpenAI Assistant FunctionTool format
+    that can be used by OpenAI agents.
+    """
 
-    def configure_tools(self, tools: List[BaseTool]) -> None:
-        """Configure tools for the OpenAI Assistant"""
+    def __init__(self, tools: list[BaseTool] | None = None) -> None:
+        """Initialize the tool adapter.
+
+        Args:
+            tools: Optional list of CrewAI tools to adapt.
+        """
+        super().__init__()
+        self.original_tools: list[BaseTool] = tools or []
+        self.converted_tools: list[OpenAITool] = []
+
+    def configure_tools(self, tools: list[BaseTool]) -> None:
+        """Configure tools for the OpenAI Assistant.
+
+        Merges provided tools with original tools and converts them to
+        OpenAI Assistant format.
+
+        Args:
+            tools: List of CrewAI tools to configure.
+        """
         if self.original_tools:
-            all_tools = tools + self.original_tools
+            all_tools: list[BaseTool] = tools + self.original_tools
         else:
             all_tools = tools
         if all_tools:
             self.converted_tools = self._convert_tools_to_openai_format(all_tools)
 
+    @staticmethod
     def _convert_tools_to_openai_format(
-        self, tools: Optional[List[BaseTool]]
-    ) -> List[Tool]:
-        """Convert CrewAI tools to OpenAI Assistant tool format"""
+        tools: list[BaseTool] | None,
+    ) -> list[OpenAITool]:
+        """Convert CrewAI tools to OpenAI Assistant tool format.
+
+        Args:
+            tools: List of CrewAI tools to convert.
+
+        Returns:
+            List of OpenAI Assistant FunctionTool instances.
+        """
         if not tools:
             return []
 
         def sanitize_tool_name(name: str) -> str:
-            """Convert tool name to match OpenAI's required pattern"""
-            import re
+            """Convert tool name to match OpenAI's required pattern.
 
-            sanitized = re.sub(r"[^a-zA-Z0-9_-]", "_", name).lower()
-            return sanitized
+            Args:
+                name: Original tool name.
 
-        def create_tool_wrapper(tool: BaseTool):
-            """Create a wrapper function that handles the OpenAI function tool interface"""
+            Returns:
+                Sanitized tool name matching OpenAI requirements.
+            """
+
+            return re.sub(r"[^a-zA-Z0-9_-]", "_", name).lower()
+
+        def create_tool_wrapper(tool: BaseTool) -> Any:
+            """Create a wrapper function that handles the OpenAI function tool interface.
+
+            Args:
+                tool: The CrewAI tool to wrap.
+
+            Returns:
+                Async wrapper function for OpenAI agent integration.
+            """
 
             async def wrapper(context_wrapper: Any, arguments: Any) -> Any:
+                """Wrapper function to adapt CrewAI tool calls to OpenAI format.
+
+                Args:
+                    context_wrapper: OpenAI context wrapper.
+                    arguments: Tool arguments from OpenAI.
+
+                Returns:
+                    Tool execution result.
+                """
                 # Get the parameter name from the schema
-                param_name = list(
-                    tool.args_schema.model_json_schema()["properties"].keys()
-                )[0]
+                param_name: str = next(
+                    iter(tool.args_schema.model_json_schema()["properties"].keys())
+                )
 
                 # Handle different argument types
+                args_dict: dict[str, Any]
                 if isinstance(arguments, dict):
                     args_dict = arguments
                 elif isinstance(arguments, str):
                     try:
-                        import json
-
                         args_dict = json.loads(arguments)
                     except json.JSONDecodeError:
                         args_dict = {param_name: arguments}
@@ -59,11 +127,11 @@ class OpenAIAgentToolAdapter(BaseToolAdapter):
                     args_dict = {param_name: str(arguments)}
 
                 # Run the tool with the processed arguments
-                output = tool._run(**args_dict)
+                output: Any | Awaitable[Any] = tool._run(**args_dict)
 
                 # Await if the tool returned a coroutine
                 if inspect.isawaitable(output):
-                    result = await output
+                    result: Any = await output
                 else:
                     result = output
 
@@ -74,17 +142,20 @@ class OpenAIAgentToolAdapter(BaseToolAdapter):
 
             return wrapper
 
-        openai_tools = []
+        openai_tools: list[OpenAITool] = []
         for tool in tools:
-            schema = tool.args_schema.model_json_schema()
+            schema: dict[str, Any] = tool.args_schema.model_json_schema()
 
             schema.update({"additionalProperties": False, "type": "object"})
 
-            openai_tool = FunctionTool(
-                name=sanitize_tool_name(tool.name),
-                description=tool.description,
-                params_json_schema=schema,
-                on_invoke_tool=create_tool_wrapper(tool),
+            openai_tool: OpenAIFunctionTool = cast(
+                OpenAIFunctionTool,
+                FunctionTool(
+                    name=sanitize_tool_name(tool.name),
+                    description=tool.description,
+                    params_json_schema=schema,
+                    on_invoke_tool=create_tool_wrapper(tool),
+                ),
             )
             openai_tools.append(openai_tool)
 

src/crewai/agents/agent_adapters/openai_agents/protocols.py

@@ -0,0 +1,74 @@
+"""Type protocols for OpenAI agents modules."""
+
+from collections.abc import Callable
+from typing import Any, Protocol, TypedDict, runtime_checkable
+
+from crewai.tools.base_tool import BaseTool
+
+
+class AgentKwargs(TypedDict, total=False):
+    """Typed dict for agent initialization kwargs."""
+
+    role: str
+    goal: str
+    backstory: str
+    model: str
+    tools: list[BaseTool] | None
+    agent_config: dict[str, Any] | None
+
+
+@runtime_checkable
+class OpenAIAgent(Protocol):
+    """Protocol for OpenAI Agent."""
+
+    def __init__(
+        self,
+        name: str,
+        instructions: str,
+        model: str,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the OpenAI agent."""
+        ...
+
+    tools: list[Any]
+    output_type: Any
+
+
+@runtime_checkable
+class OpenAIRunner(Protocol):
+    """Protocol for OpenAI Runner."""
+
+    @classmethod
+    def run_sync(cls, agent: OpenAIAgent, message: str) -> Any:
+        """Run agent synchronously with a message."""
+        ...
+
+
+@runtime_checkable
+class OpenAIAgentsModule(Protocol):
+    """Protocol for OpenAI agents module."""
+
+    Agent: type[OpenAIAgent]
+    Runner: type[OpenAIRunner]
+    enable_verbose_stdout_logging: Callable[[], None]
+
+
+@runtime_checkable
+class OpenAITool(Protocol):
+    """Protocol for OpenAI Tool."""
+
+
+@runtime_checkable
+class OpenAIFunctionTool(Protocol):
+    """Protocol for OpenAI FunctionTool."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        params_json_schema: dict[str, Any],
+        on_invoke_tool: Any,
+    ) -> None:
+        """Initialize the function tool."""
+        ...

src/crewai/agents/agent_adapters/openai_agents/structured_output_converter.py

@@ -1,5 +1,12 @@
+"""OpenAI structured output converter for CrewAI task integration.
+
+This module contains the OpenAIConverterAdapter class that handles structured
+output conversion for OpenAI agents, supporting JSON and Pydantic model formats.
+"""
+
 import json
 import re
+from typing import Any, Literal
 
 from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter
 from crewai.utilities.converter import generate_model_description
@@ -7,8 +14,7 @@ from crewai.utilities.i18n import I18N
 
 
 class OpenAIConverterAdapter(BaseConverterAdapter):
-    """
-    Adapter for handling structured output conversion in OpenAI agents.
+    """Adapter for handling structured output conversion in OpenAI agents.
 
     This adapter enhances the OpenAI agent to handle structured output formats
     and post-processes the results when needed.
@@ -19,19 +25,23 @@ class OpenAIConverterAdapter(BaseConverterAdapter):
         _output_model: The Pydantic model for the output
     """
 
-    def __init__(self, agent_adapter):
-        """Initialize the converter adapter with a reference to the agent adapter"""
-        self.agent_adapter = agent_adapter
-        self._output_format = None
-        self._schema = None
-        self._output_model = None
-
-    def configure_structured_output(self, task) -> None:
-        """
-        Configure the structured output for OpenAI agent based on task requirements.
+    def __init__(self, agent_adapter: Any) -> None:
+        """Initialize the converter adapter with a reference to the agent adapter.
 
         Args:
-            task: The task containing output format requirements
+            agent_adapter: The OpenAI agent adapter instance.
+        """
+        super().__init__(agent_adapter=agent_adapter)
+        self.agent_adapter: Any = agent_adapter
+        self._output_format: Literal["json", "pydantic"] | None = None
+        self._schema: str | None = None
+        self._output_model: Any = None
+
+    def configure_structured_output(self, task: Any) -> None:
+        """Configure the structured output for OpenAI agent based on task requirements.
+
+        Args:
+            task: The task containing output format requirements.
         """
         # Reset configuration
         self._output_format = None
@@ -55,19 +65,18 @@ class OpenAIConverterAdapter(BaseConverterAdapter):
             self._output_model = task.output_pydantic
 
     def enhance_system_prompt(self, base_prompt: str) -> str:
-        """
-        Enhance the base system prompt with structured output requirements if needed.
+        """Enhance the base system prompt with structured output requirements if needed.
 
         Args:
-            base_prompt: The original system prompt
+            base_prompt: The original system prompt.
 
         Returns:
-            Enhanced system prompt with output format instructions if needed
+            Enhanced system prompt with output format instructions if needed.
         """
         if not self._output_format:
             return base_prompt
 
-        output_schema = (
+        output_schema: str = (
             I18N()
             .slice("formatted_task_instructions")
             .format(output_format=self._schema)
@@ -76,16 +85,15 @@ class OpenAIConverterAdapter(BaseConverterAdapter):
         return f"{base_prompt}\n\n{output_schema}"
 
     def post_process_result(self, result: str) -> str:
-        """
-        Post-process the result to ensure it matches the expected format.
+        """Post-process the result to ensure it matches the expected format.
 
         This method attempts to extract valid JSON from the result if necessary.
 
         Args:
-            result: The raw result from the agent
+            result: The raw result from the agent.
 
         Returns:
-            Processed result conforming to the expected output format
+            Processed result conforming to the expected output format.
         """
         if not self._output_format:
             return result
@@ -97,26 +105,30 @@ class OpenAIConverterAdapter(BaseConverterAdapter):
                 return result
             except json.JSONDecodeError:
                 # Try to extract JSON from markdown code blocks
-                code_block_pattern = r"```(?:json)?\s*([\s\S]*?)```"
-                code_blocks = re.findall(code_block_pattern, result)
+                code_block_pattern: str = r"```(?:json)?\s*([\s\S]*?)```"
+                code_blocks: list[str] = re.findall(code_block_pattern, result)
 
                 for block in code_blocks:
+                    stripped_block = block.strip()
                     try:
-                        json.loads(block.strip())
-                        return block.strip()
+                        json.loads(stripped_block)
+                        return stripped_block
                     except json.JSONDecodeError:
-                        continue
+                        pass
 
                 # Try to extract any JSON-like structure
-                json_pattern = r"(\{[\s\S]*\})"
-                json_matches = re.findall(json_pattern, result, re.DOTALL)
+                json_pattern: str = r"(\{[\s\S]*\})"
+                json_matches: list[str] = re.findall(json_pattern, result, re.DOTALL)
 
                 for match in json_matches:
+                    is_valid = True
                     try:
                         json.loads(match)
-                        return match
                     except json.JSONDecodeError:
-                        continue
+                        is_valid = False
+
+                    if is_valid:
+                        return match
 
         # If all extraction attempts fail, return the original
         return str(result)

src/crewai/agents/agent_builder/base_agent.py

@@ -1,8 +1,9 @@
 import uuid
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from copy import copy as shallow_copy
 from hashlib import md5
-from typing import Any, Callable, Dict, List, Optional, TypeVar
+from typing import Any, TypeVar
 
 from pydantic import (
     UUID4,
@@ -21,11 +22,11 @@ from crewai.agents.tools_handler import ToolsHandler
 from crewai.knowledge.knowledge import Knowledge
 from crewai.knowledge.knowledge_config import KnowledgeConfig
 from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
+from crewai.rag.embeddings.types import EmbedderConfig
 from crewai.security.security_config import SecurityConfig
 from crewai.tools.base_tool import BaseTool, Tool
 from crewai.utilities import I18N, Logger, RPMController
 from crewai.utilities.config import process_config
-from crewai.utilities.converter import Converter
 from crewai.utilities.string_utils import interpolate_only
 
 T = TypeVar("T", bound="BaseAgent")
@@ -81,17 +82,17 @@ class BaseAgent(ABC, BaseModel):
 
     __hash__ = object.__hash__  # type: ignore
     _logger: Logger = PrivateAttr(default_factory=lambda: Logger(verbose=False))
-    _rpm_controller: Optional[RPMController] = PrivateAttr(default=None)
+    _rpm_controller: RPMController | None = PrivateAttr(default=None)
     _request_within_rpm_limit: Any = PrivateAttr(default=None)
-    _original_role: Optional[str] = PrivateAttr(default=None)
-    _original_goal: Optional[str] = PrivateAttr(default=None)
-    _original_backstory: Optional[str] = PrivateAttr(default=None)
+    _original_role: str | None = PrivateAttr(default=None)
+    _original_goal: str | None = PrivateAttr(default=None)
+    _original_backstory: str | None = PrivateAttr(default=None)
     _token_process: TokenProcess = PrivateAttr(default_factory=TokenProcess)
     id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True)
     role: str = Field(description="Role of the agent")
     goal: str = Field(description="Objective of the agent")
     backstory: str = Field(description="Backstory of the agent")
-    config: Optional[Dict[str, Any]] = Field(
+    config: dict[str, Any] | None = Field(
         description="Configuration for the agent", default=None, exclude=True
     )
     cache: bool = Field(
@@ -100,7 +101,7 @@ class BaseAgent(ABC, BaseModel):
     verbose: bool = Field(
         default=False, description="Verbose mode for the Agent Execution"
     )
-    max_rpm: Optional[int] = Field(
+    max_rpm: int | None = Field(
         default=None,
         description="Maximum number of requests per minute for the agent execution to be respected.",
     )
@@ -108,7 +109,7 @@ class BaseAgent(ABC, BaseModel):
         default=False,
         description="Enable agent to delegate and ask questions among each other.",
     )
-    tools: Optional[List[BaseTool]] = Field(
+    tools: list[BaseTool] | None = Field(
         default_factory=list, description="Tools at agents' disposal"
     )
     max_iter: int = Field(
@@ -122,27 +123,27 @@ class BaseAgent(ABC, BaseModel):
     )
     crew: Any = Field(default=None, description="Crew to which the agent belongs.")
     i18n: I18N = Field(default=I18N(), description="Internationalization settings.")
-    cache_handler: Optional[InstanceOf[CacheHandler]] = Field(
+    cache_handler: InstanceOf[CacheHandler] | None = Field(
         default=None, description="An instance of the CacheHandler class."
     )
     tools_handler: InstanceOf[ToolsHandler] = Field(
         default_factory=ToolsHandler,
         description="An instance of the ToolsHandler class.",
     )
-    tools_results: List[Dict[str, Any]] = Field(
+    tools_results: list[dict[str, Any]] = Field(
         default=[], description="Results of the tools used by the agent."
     )
-    max_tokens: Optional[int] = Field(
+    max_tokens: int | None = Field(
         default=None, description="Maximum number of tokens for the agent's execution."
     )
-    knowledge: Optional[Knowledge] = Field(
+    knowledge: Knowledge | None = Field(
         default=None, description="Knowledge for the agent."
     )
-    knowledge_sources: Optional[List[BaseKnowledgeSource]] = Field(
+    knowledge_sources: list[BaseKnowledgeSource] | None = Field(
         default=None,
         description="Knowledge sources for the agent.",
     )
-    knowledge_storage: Optional[Any] = Field(
+    knowledge_storage: Any | None = Field(
         default=None,
         description="Custom knowledge storage for the agent.",
     )
@@ -150,13 +151,13 @@ class BaseAgent(ABC, BaseModel):
         default_factory=SecurityConfig,
         description="Security configuration for the agent, including fingerprinting.",
     )
-    callbacks: List[Callable] = Field(
+    callbacks: list[Callable] = Field(
         default=[], description="Callbacks to be used for the agent"
     )
     adapted_agent: bool = Field(
         default=False, description="Whether the agent is adapted"
     )
-    knowledge_config: Optional[KnowledgeConfig] = Field(
+    knowledge_config: KnowledgeConfig | None = Field(
         default=None,
         description="Knowledge configuration for the agent such as limits and threshold",
     )
@@ -168,7 +169,7 @@ class BaseAgent(ABC, BaseModel):
 
     @field_validator("tools")
     @classmethod
-    def validate_tools(cls, tools: List[Any]) -> List[BaseTool]:
+    def validate_tools(cls, tools: list[Any]) -> list[BaseTool]:
         """Validate and process the tools provided to the agent.
 
         This method ensures that each tool is either an instance of BaseTool
@@ -221,7 +222,7 @@ class BaseAgent(ABC, BaseModel):
 
     @field_validator("id", mode="before")
     @classmethod
-    def _deny_user_set_id(cls, v: Optional[UUID4]) -> None:
+    def _deny_user_set_id(cls, v: UUID4 | None) -> None:
         if v:
             raise PydanticCustomError(
                 "may_not_set_field", "This field is not to be set by the user.", {}
@@ -252,8 +253,8 @@ class BaseAgent(ABC, BaseModel):
     def execute_task(
         self,
         task: Any,
-        context: Optional[str] = None,
-        tools: Optional[List[BaseTool]] = None,
+        context: str | None = None,
+        tools: list[BaseTool] | None = None,
     ) -> str:
         pass
 
@@ -262,9 +263,8 @@ class BaseAgent(ABC, BaseModel):
         pass
 
     @abstractmethod
-    def get_delegation_tools(self, agents: List["BaseAgent"]) -> List[BaseTool]:
+    def get_delegation_tools(self, agents: list["BaseAgent"]) -> list[BaseTool]:
         """Set the task tools that init BaseAgenTools class."""
-        pass
 
     def copy(self: T) -> T:  # type: ignore # Signature of "copy" incompatible with supertype "BaseModel"
         """Create a deep copy of the Agent."""
@@ -309,7 +309,7 @@ class BaseAgent(ABC, BaseModel):
 
         copied_data = self.model_dump(exclude=exclude)
         copied_data = {k: v for k, v in copied_data.items() if v is not None}
-        copied_agent = type(self)(
+        return type(self)(
             **copied_data,
             llm=existing_llm,
             tools=self.tools,
@@ -318,9 +318,7 @@ class BaseAgent(ABC, BaseModel):
             knowledge_storage=copied_knowledge_storage,
         )
 
-        return copied_agent
-
-    def interpolate_inputs(self, inputs: Dict[str, Any]) -> None:
+    def interpolate_inputs(self, inputs: dict[str, Any]) -> None:
         """Interpolate inputs into the agent description and backstory."""
         if self._original_role is None:
             self._original_role = self.role
@@ -362,5 +360,5 @@ class BaseAgent(ABC, BaseModel):
             self._rpm_controller = rpm_controller
             self.create_agent_executor()
 
-    def set_knowledge(self, crew_embedder: Optional[Dict[str, Any]] = None):
+    def set_knowledge(self, crew_embedder: EmbedderConfig | None = None):
         pass

src/crewai/agents/agent_builder/base_agent_executor_mixin.py

@@ -1,13 +1,13 @@
 import time
-from typing import TYPE_CHECKING, Dict, List
+from typing import TYPE_CHECKING
 
+from crewai.events.event_listener import event_listener
 from crewai.memory.entity.entity_memory_item import EntityMemoryItem
 from crewai.memory.long_term.long_term_memory_item import LongTermMemoryItem
 from crewai.utilities import I18N
 from crewai.utilities.converter import ConverterError
 from crewai.utilities.evaluators.task_evaluator import TaskEvaluator
 from crewai.utilities.printer import Printer
-from crewai.events.event_listener import event_listener
 
 if TYPE_CHECKING:
     from crewai.agents.agent_builder.base_agent import BaseAgent
@@ -21,7 +21,7 @@ class CrewAgentExecutorMixin:
     task: "Task"
     iterations: int
     max_iter: int
-    messages: List[Dict[str, str]]
+    messages: list[dict[str, str]]
     _i18n: I18N
     _printer: Printer = Printer()
 
@@ -46,7 +46,6 @@ class CrewAgentExecutorMixin:
                     )
             except Exception as e:
                 print(f"Failed to add to short term memory: {e}")
-                pass
 
     def _create_external_memory(self, output) -> None:
         """Create and save a external-term memory item if conditions are met."""
@@ -67,7 +66,6 @@ class CrewAgentExecutorMixin:
                 )
             except Exception as e:
                 print(f"Failed to add to external memory: {e}")
-                pass
 
     def _create_long_term_memory(self, output) -> None:
         """Create and save long-term and entity memory items based on evaluation."""
@@ -113,10 +111,8 @@ class CrewAgentExecutorMixin:
                     self.crew._entity_memory.save(entity_memories)
             except AttributeError as e:
                 print(f"Missing attributes for long term memory: {e}")
-                pass
             except Exception as e:
                 print(f"Failed to add to long term memory: {e}")
-                pass
         elif (
             self.crew
             and self.crew._long_term_memory

src/crewai/agents/crew_agent_executor.py

@@ -12,7 +12,7 @@ from crewai.agents.agent_builder.base_agent_executor_mixin import CrewAgentExecu
 from crewai.agents.parser import (
     AgentAction,
     AgentFinish,
-    OutputParserException,
+    OutputParserError,
 )
 from crewai.agents.tools_handler import ToolsHandler
 from crewai.events.event_bus import crewai_event_bus
@@ -228,7 +228,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
                 self._invoke_step_callback(formatted_answer)
                 self._append_message(formatted_answer.text)
 
-            except OutputParserException as e:
+            except OutputParserError as e:  # noqa: PERF203
                 formatted_answer = handle_output_parser_exception(
                     e=e,
                     messages=self.messages,
@@ -251,17 +251,20 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
                         i18n=self._i18n,
                     )
                     continue
-                else:
-                    handle_unknown_error(self._printer, e)
-                    raise e
+                handle_unknown_error(self._printer, e)
+                raise e
             finally:
                 self.iterations += 1
 
         # During the invoke loop, formatted_answer alternates between AgentAction
         # (when the agent is using tools) and eventually becomes AgentFinish
-        # (when the agent reaches a final answer). This assertion confirms we've
+        # (when the agent reaches a final answer). This check confirms we've
         # reached a final answer and helps type checking understand this transition.
-        assert isinstance(formatted_answer, AgentFinish)
+        if not isinstance(formatted_answer, AgentFinish):
+            raise RuntimeError(
+                "Agent execution ended without reaching a final answer. "
+                f"Got {type(formatted_answer).__name__} instead of AgentFinish."
+            )
         self._show_logs(formatted_answer)
         return formatted_answer
 
@@ -324,9 +327,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
             self.agent,
             AgentLogsStartedEvent(
                 agent_role=self.agent.role,
-                task_description=(
-                    getattr(self.task, "description") if self.task else "Not Found"
-                ),
+                task_description=(self.task.description if self.task else "Not Found"),
                 verbose=self.agent.verbose
                 or (hasattr(self, "crew") and getattr(self.crew, "verbose", False)),
             ),
@@ -415,8 +416,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
         """
         prompt = prompt.replace("{input}", inputs["input"])
         prompt = prompt.replace("{tool_names}", inputs["tool_names"])
-        prompt = prompt.replace("{tools}", inputs["tools"])
-        return prompt
+        return prompt.replace("{tools}", inputs["tools"])
 
     def _handle_human_feedback(self, formatted_answer: AgentFinish) -> AgentFinish:
         """Process human feedback.

src/crewai/agents/parser.py

@@ -7,18 +7,18 @@ AgentAction or AgentFinish objects.
 
 from dataclasses import dataclass
 
-from json_repair import repair_json
+from json_repair import repair_json  # type: ignore[import-untyped]
 
 from crewai.agents.constants import (
+    ACTION_INPUT_ONLY_REGEX,
     ACTION_INPUT_REGEX,
     ACTION_REGEX,
-    ACTION_INPUT_ONLY_REGEX,
     FINAL_ANSWER_ACTION,
     MISSING_ACTION_AFTER_THOUGHT_ERROR_MESSAGE,
     MISSING_ACTION_INPUT_AFTER_ACTION_ERROR_MESSAGE,
     UNABLE_TO_REPAIR_JSON_RESULTS,
 )
-from crewai.utilities import I18N
+from crewai.utilities.i18n import I18N
 
 _I18N = I18N()
 
@@ -43,7 +43,7 @@ class AgentFinish:
     text: str
 
 
-class OutputParserException(Exception):
+class OutputParserError(Exception):
     """Exception raised when output parsing fails.
 
     Attributes:
@@ -51,7 +51,7 @@ class OutputParserException(Exception):
     """
 
     def __init__(self, error: str) -> None:
-        """Initialize OutputParserException.
+        """Initialize OutputParserError.
 
         Args:
             error: The error message.
@@ -87,7 +87,7 @@ def parse(text: str) -> AgentAction | AgentFinish:
         AgentAction or AgentFinish based on the content.
 
     Raises:
-        OutputParserException: If the text format is invalid.
+        OutputParserError: If the text format is invalid.
     """
     thought = _extract_thought(text)
     includes_answer = FINAL_ANSWER_ACTION in text
@@ -104,7 +104,7 @@ def parse(text: str) -> AgentAction | AgentFinish:
                 final_answer = final_answer[:-3].rstrip()
         return AgentFinish(thought=thought, output=final_answer, text=text)
 
-    elif action_match:
+    if action_match:
         action = action_match.group(1)
         clean_action = _clean_action(action)
 
@@ -118,19 +118,18 @@ def parse(text: str) -> AgentAction | AgentFinish:
         )
 
     if not ACTION_REGEX.search(text):
-        raise OutputParserException(
+        raise OutputParserError(
             f"{MISSING_ACTION_AFTER_THOUGHT_ERROR_MESSAGE}\n{_I18N.slice('final_answer_format')}",
         )
-    elif not ACTION_INPUT_ONLY_REGEX.search(text):
-        raise OutputParserException(
+    if not ACTION_INPUT_ONLY_REGEX.search(text):
+        raise OutputParserError(
             MISSING_ACTION_INPUT_AFTER_ACTION_ERROR_MESSAGE,
         )
-    else:
-        err_format = _I18N.slice("format_without_tools")
-        error = f"{err_format}"
-        raise OutputParserException(
-            error,
-        )
+    err_format = _I18N.slice("format_without_tools")
+    error = f"{err_format}"
+    raise OutputParserError(
+        error,
+    )
 
 
 def _extract_thought(text: str) -> str:
@@ -149,8 +148,7 @@ def _extract_thought(text: str) -> str:
         return ""
     thought = text[:thought_index].strip()
     # Remove any triple backticks from the thought string
-    thought = thought.replace("```", "").strip()
-    return thought
+    return thought.replace("```", "").strip()
 
 
 def _clean_action(text: str) -> str:

src/crewai/agents/tools_handler.py

@@ -1,8 +1,10 @@
 """Tools handler for managing tool execution and caching."""
 
+import json
+
+from crewai.agents.cache.cache_handler import CacheHandler
 from crewai.tools.cache_tools.cache_tools import CacheTools
 from crewai.tools.tool_calling import InstructorToolCalling, ToolCalling
-from crewai.agents.cache.cache_handler import CacheHandler
 
 
 class ToolsHandler:
@@ -37,8 +39,16 @@ class ToolsHandler:
         """
         self.last_used_tool = calling
         if self.cache and should_cache and calling.tool_name != CacheTools().name:
+            # Convert arguments to string for cache
+            input_str = ""
+            if calling.arguments:
+                if isinstance(calling.arguments, dict):
+                    input_str = json.dumps(calling.arguments)
+                else:
+                    input_str = str(calling.arguments)
+
             self.cache.add(
                 tool=calling.tool_name,
-                input=calling.arguments,
+                input=input_str,
                 output=output,
             )

src/crewai/cli/authentication/providers/auth0.py

@@ -1,5 +1,6 @@
 from crewai.cli.authentication.providers.base_provider import BaseProvider
 
+
 class Auth0Provider(BaseProvider):
     def get_authorize_url(self) -> str:
         return f"https://{self._get_domain()}/oauth/device/code"
@@ -14,13 +15,20 @@ class Auth0Provider(BaseProvider):
         return f"https://{self._get_domain()}/"
 
     def get_audience(self) -> str:
-        assert self.settings.audience is not None, "Audience is required"
+        if self.settings.audience is None:
+            raise ValueError(
+                "Audience is required. Please set it in the configuration."
+            )
         return self.settings.audience
 
     def get_client_id(self) -> str:
-        assert self.settings.client_id is not None, "Client ID is required"
+        if self.settings.client_id is None:
+            raise ValueError(
+                "Client ID is required. Please set it in the configuration."
+            )
         return self.settings.client_id
 
     def _get_domain(self) -> str:
-        assert self.settings.domain is not None, "Domain is required"
+        if self.settings.domain is None:
+            raise ValueError("Domain is required. Please set it in the configuration.")
         return self.settings.domain

src/crewai/cli/authentication/providers/base_provider.py

@@ -1,30 +1,26 @@
 from abc import ABC, abstractmethod
+
 from crewai.cli.authentication.main import Oauth2Settings
 
+
 class BaseProvider(ABC):
     def __init__(self, settings: Oauth2Settings):
         self.settings = settings
 
     @abstractmethod
-    def get_authorize_url(self) -> str:
-        ...
+    def get_authorize_url(self) -> str: ...
 
     @abstractmethod
-    def get_token_url(self) -> str:
-        ...
+    def get_token_url(self) -> str: ...
 
     @abstractmethod
-    def get_jwks_url(self) -> str:
-        ...
+    def get_jwks_url(self) -> str: ...
 
     @abstractmethod
-    def get_issuer(self) -> str:
-        ...
+    def get_issuer(self) -> str: ...
 
     @abstractmethod
-    def get_audience(self) -> str:
-        ...
+    def get_audience(self) -> str: ...
 
     @abstractmethod
-    def get_client_id(self) -> str:
-        ...
+    def get_client_id(self) -> str: ...

src/crewai/cli/authentication/providers/okta.py

@@ -1,5 +1,6 @@
 from crewai.cli.authentication.providers.base_provider import BaseProvider
 
+
 class OktaProvider(BaseProvider):
     def get_authorize_url(self) -> str:
         return f"https://{self.settings.domain}/oauth2/default/v1/device/authorize"
@@ -14,9 +15,15 @@ class OktaProvider(BaseProvider):
         return f"https://{self.settings.domain}/oauth2/default"
 
     def get_audience(self) -> str:
-        assert self.settings.audience is not None
+        if self.settings.audience is None:
+            raise ValueError(
+                "Audience is required. Please set it in the configuration."
+            )
         return self.settings.audience
 
     def get_client_id(self) -> str:
-        assert self.settings.client_id is not None
+        if self.settings.client_id is None:
+            raise ValueError(
+                "Client ID is required. Please set it in the configuration."
+            )
         return self.settings.client_id

src/crewai/cli/authentication/providers/workos.py

@@ -1,5 +1,6 @@
 from crewai.cli.authentication.providers.base_provider import BaseProvider
 
+
 class WorkosProvider(BaseProvider):
     def get_authorize_url(self) -> str:
         return f"https://{self._get_domain()}/oauth2/device_authorization"
@@ -17,9 +18,13 @@ class WorkosProvider(BaseProvider):
         return self.settings.audience or ""
 
     def get_client_id(self) -> str:
-        assert self.settings.client_id is not None, "Client ID is required"
+        if self.settings.client_id is None:
+            raise ValueError(
+                "Client ID is required. Please set it in the configuration."
+            )
         return self.settings.client_id
 
     def _get_domain(self) -> str:
-        assert self.settings.domain is not None, "Domain is required"
+        if self.settings.domain is None:
+            raise ValueError("Domain is required. Please set it in the configuration.")
         return self.settings.domain

src/crewai/cli/authentication/utils.py

@@ -17,8 +17,6 @@ def validate_jwt_token(
                        missing required claims).
     """
 
-    decoded_token = None
-
     try:
         jwk_client = PyJWKClient(jwks_url)
         signing_key = jwk_client.get_signing_key_from_jwt(jwt_token)
@@ -26,7 +24,7 @@ def validate_jwt_token(
         _unverified_decoded_token = jwt.decode(
             jwt_token, options={"verify_signature": False}
         )
-        decoded_token = jwt.decode(
+        return jwt.decode(
             jwt_token,
             signing_key.key,
             algorithms=["RS256"],
@@ -40,23 +38,22 @@ def validate_jwt_token(
                 "require": ["exp", "iat", "iss", "aud", "sub"],
             },
         )
-        return decoded_token
 
-    except jwt.ExpiredSignatureError:
-        raise Exception("Token has expired.")
-    except jwt.InvalidAudienceError:
+    except jwt.ExpiredSignatureError as e:
+        raise Exception("Token has expired.") from e
+    except jwt.InvalidAudienceError as e:
         actual_audience = _unverified_decoded_token.get("aud", "[no audience found]")
         raise Exception(
             f"Invalid token audience. Got: '{actual_audience}'. Expected: '{audience}'"
-        )
-    except jwt.InvalidIssuerError:
+        ) from e
+    except jwt.InvalidIssuerError as e:
         actual_issuer = _unverified_decoded_token.get("iss", "[no issuer found]")
         raise Exception(
             f"Invalid token issuer. Got: '{actual_issuer}'. Expected: '{issuer}'"
-        )
+        ) from e
     except jwt.MissingRequiredClaimError as e:
-        raise Exception(f"Token is missing required claims: {str(e)}")
+        raise Exception(f"Token is missing required claims: {e!s}") from e
     except jwt.exceptions.PyJWKClientError as e:
-        raise Exception(f"JWKS or key processing error: {str(e)}")
+        raise Exception(f"JWKS or key processing error: {e!s}") from e
     except jwt.InvalidTokenError as e:
-        raise Exception(f"Invalid token: {str(e)}")
+        raise Exception(f"Invalid token: {e!s}") from e

src/crewai/cli/cli.py

@@ -1,13 +1,16 @@
+import os
+import subprocess
 from importlib.metadata import version as get_version
-from typing import Optional
 
 import click
-from crewai.cli.config import Settings
-from crewai.cli.settings.main import SettingsCommand
+
 from crewai.cli.add_crew_to_flow import add_crew_to_flow
+from crewai.cli.config import Settings
 from crewai.cli.create_crew import create_crew
 from crewai.cli.create_flow import create_flow
 from crewai.cli.crew_chat import run_chat
+from crewai.cli.settings.main import SettingsCommand
+from crewai.cli.utils import build_env_with_tool_repository_credentials, read_toml
 from crewai.memory.storage.kickoff_task_outputs_storage import (
     KickoffTaskOutputsSQLiteStorage,
 )
@@ -34,6 +37,46 @@ def crewai():
     """Top-level command group for crewai."""
 
 
+@crewai.command(
+    name="uv",
+    context_settings=dict(
+        ignore_unknown_options=True,
+    ),
+)
+@click.argument("uv_args", nargs=-1, type=click.UNPROCESSED)
+def uv(uv_args):
+    """A wrapper around uv commands that adds custom tool authentication through env vars."""
+    env = os.environ.copy()
+    try:
+        pyproject_data = read_toml()
+        sources = pyproject_data.get("tool", {}).get("uv", {}).get("sources", {})
+
+        for source_config in sources.values():
+            if isinstance(source_config, dict):
+                index = source_config.get("index")
+                if index:
+                    index_env = build_env_with_tool_repository_credentials(index)
+                    env.update(index_env)
+    except (FileNotFoundError, KeyError) as e:
+        raise SystemExit(
+            "Error. A valid pyproject.toml file is required. Check that a valid pyproject.toml file exists in the current directory."
+        ) from e
+    except Exception as e:
+        raise SystemExit(f"Error: {e}") from e
+
+    try:
+        subprocess.run(  # noqa: S603
+            ["uv", *uv_args],  # noqa: S607
+            capture_output=False,
+            env=env,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as e:
+        click.secho(f"uv command failed with exit code {e.returncode}", fg="red")
+        raise SystemExit(e.returncode) from e
+
+
 @crewai.command()
 @click.argument("type", type=click.Choice(["crew", "flow"]))
 @click.argument("name")
@@ -237,13 +280,6 @@ def login():
 @crewai.group()
 def deploy():
     """Deploy the Crew CLI group."""
-    pass
-
-
-@crewai.group()
-def tool():
-    """Tool Repository related commands."""
-    pass
 
 
 @deploy.command(name="create")
@@ -263,7 +299,7 @@ def deploy_list():
 
 @deploy.command(name="push")
 @click.option("-u", "--uuid", type=str, help="Crew UUID parameter")
-def deploy_push(uuid: Optional[str]):
+def deploy_push(uuid: str | None):
     """Deploy the Crew."""
     deploy_cmd = DeployCommand()
     deploy_cmd.deploy(uuid=uuid)
@@ -271,7 +307,7 @@ def deploy_push(uuid: Optional[str]):
 
 @deploy.command(name="status")
 @click.option("-u", "--uuid", type=str, help="Crew UUID parameter")
-def deply_status(uuid: Optional[str]):
+def deply_status(uuid: str | None):
     """Get the status of a deployment."""
     deploy_cmd = DeployCommand()
     deploy_cmd.get_crew_status(uuid=uuid)
@@ -279,7 +315,7 @@ def deply_status(uuid: Optional[str]):
 
 @deploy.command(name="logs")
 @click.option("-u", "--uuid", type=str, help="Crew UUID parameter")
-def deploy_logs(uuid: Optional[str]):
+def deploy_logs(uuid: str | None):
     """Get the logs of a deployment."""
     deploy_cmd = DeployCommand()
     deploy_cmd.get_crew_logs(uuid=uuid)
@@ -287,12 +323,17 @@ def deploy_logs(uuid: Optional[str]):
 
 @deploy.command(name="remove")
 @click.option("-u", "--uuid", type=str, help="Crew UUID parameter")
-def deploy_remove(uuid: Optional[str]):
+def deploy_remove(uuid: str | None):
     """Remove a deployment."""
     deploy_cmd = DeployCommand()
     deploy_cmd.remove_crew(uuid=uuid)
 
 
+@crewai.group()
+def tool():
+    """Tool Repository related commands."""
+
+
 @tool.command(name="create")
 @click.argument("handle")
 def tool_create(handle: str):
@@ -327,7 +368,6 @@ def tool_publish(is_public: bool, force: bool):
 @crewai.group()
 def flow():
     """Flow related commands."""
-    pass
 
 
 @flow.command(name="kickoff")
@@ -359,7 +399,7 @@ def chat():
     and using the Chat LLM to generate responses.
     """
     click.secho(
-        "\nStarting a conversation with the Crew\n" "Type 'exit' or Ctrl+C to quit.\n",
+        "\nStarting a conversation with the Crew\nType 'exit' or Ctrl+C to quit.\n",
     )
 
     run_chat()
@@ -368,7 +408,6 @@ def chat():
 @crewai.group(invoke_without_command=True)
 def org():
     """Organization management commands."""
-    pass
 
 
 @org.command("list")
@@ -396,7 +435,6 @@ def current():
 @crewai.group()
 def enterprise():
     """Enterprise Configuration commands."""
-    pass
 
 
 @enterprise.command("configure")
@@ -410,7 +448,6 @@ def enterprise_configure(enterprise_url: str):
 @crewai.group()
 def config():
     """CLI Configuration commands."""
-    pass
 
 
 @config.command("list")

src/crewai/cli/config.py

@@ -1,20 +1,61 @@
 import json
+import tempfile
+from logging import getLogger
 from pathlib import Path
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
 from crewai.cli.constants import (
-    DEFAULT_CREWAI_ENTERPRISE_URL,
-    CREWAI_ENTERPRISE_DEFAULT_OAUTH2_PROVIDER,
     CREWAI_ENTERPRISE_DEFAULT_OAUTH2_AUDIENCE,
     CREWAI_ENTERPRISE_DEFAULT_OAUTH2_CLIENT_ID,
     CREWAI_ENTERPRISE_DEFAULT_OAUTH2_DOMAIN,
+    CREWAI_ENTERPRISE_DEFAULT_OAUTH2_PROVIDER,
+    DEFAULT_CREWAI_ENTERPRISE_URL,
 )
 from crewai.cli.shared.token_manager import TokenManager
 
+logger = getLogger(__name__)
+
 DEFAULT_CONFIG_PATH = Path.home() / ".config" / "crewai" / "settings.json"
 
+
+def get_writable_config_path() -> Path | None:
+    """
+    Find a writable location for the config file with fallback options.
+
+    Tries in order:
+    1. Default: ~/.config/crewai/settings.json
+    2. Temp directory: /tmp/crewai_settings.json (or OS equivalent)
+    3. Current directory: ./crewai_settings.json
+    4. In-memory only (returns None)
+
+    Returns:
+        Path object for writable config location, or None if no writable location found
+    """
+    fallback_paths = [
+        DEFAULT_CONFIG_PATH,  # Default location
+        Path(tempfile.gettempdir()) / "crewai_settings.json",  # Temporary directory
+        Path.cwd() / "crewai_settings.json",  # Current working directory
+    ]
+
+    for config_path in fallback_paths:
+        try:
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+            test_file = config_path.parent / ".crewai_write_test"
+            try:
+                test_file.write_text("test")
+                test_file.unlink()  # Clean up test file
+                logger.info(f"Using config path: {config_path}")
+                return config_path
+            except Exception:  # noqa: S112
+                continue
+
+        except Exception:  # noqa: S112
+            continue
+
+    return None
+
+
 # Settings that are related to the user's account
 USER_SETTINGS_KEYS = [
     "tool_repository_username",
@@ -56,20 +97,20 @@ HIDDEN_SETTINGS_KEYS = [
 
 
 class Settings(BaseModel):
-    enterprise_base_url: Optional[str] = Field(
+    enterprise_base_url: str | None = Field(
         default=DEFAULT_CLI_SETTINGS["enterprise_base_url"],
         description="Base URL of the CrewAI Enterprise instance",
     )
-    tool_repository_username: Optional[str] = Field(
+    tool_repository_username: str | None = Field(
         None, description="Username for interacting with the Tool Repository"
     )
-    tool_repository_password: Optional[str] = Field(
+    tool_repository_password: str | None = Field(
         None, description="Password for interacting with the Tool Repository"
     )
-    org_name: Optional[str] = Field(
+    org_name: str | None = Field(
         None, description="Name of the currently active organization"
     )
-    org_uuid: Optional[str] = Field(
+    org_uuid: str | None = Field(
         None, description="UUID of the currently active organization"
     )
     config_path: Path = Field(default=DEFAULT_CONFIG_PATH, frozen=True, exclude=True)
@@ -79,7 +120,7 @@ class Settings(BaseModel):
         default=DEFAULT_CLI_SETTINGS["oauth2_provider"],
     )
 
-    oauth2_audience: Optional[str] = Field(
+    oauth2_audience: str | None = Field(
         description="OAuth2 audience value, typically used to identify the target API or resource.",
         default=DEFAULT_CLI_SETTINGS["oauth2_audience"],
     )
@@ -94,16 +135,32 @@ class Settings(BaseModel):
         default=DEFAULT_CLI_SETTINGS["oauth2_domain"],
     )
 
-    def __init__(self, config_path: Path = DEFAULT_CONFIG_PATH, **data):
-        """Load Settings from config path"""
-        config_path.parent.mkdir(parents=True, exist_ok=True)
+    def __init__(self, config_path: Path | None = None, **data):
+        """Load Settings from config path with fallback support"""
+        if config_path is None:
+            config_path = get_writable_config_path()
+
+        # If config_path is None, we're in memory-only mode
+        if config_path is None:
+            merged_data = {**data}
+            # Dummy path for memory-only mode
+            super().__init__(config_path=Path("/dev/null"), **merged_data)
+            return
+
+        try:
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+        except Exception:
+            merged_data = {**data}
+            # Dummy path for memory-only mode
+            super().__init__(config_path=Path("/dev/null"), **merged_data)
+            return
 
         file_data = {}
         if config_path.is_file():
             try:
                 with config_path.open("r") as f:
                     file_data = json.load(f)
-            except json.JSONDecodeError:
+            except Exception:
                 file_data = {}
 
         merged_data = {**file_data, **data}
@@ -123,15 +180,22 @@ class Settings(BaseModel):
 
     def dump(self) -> None:
         """Save current settings to settings.json"""
-        if self.config_path.is_file():
-            with self.config_path.open("r") as f:
-                existing_data = json.load(f)
-        else:
-            existing_data = {}
+        if str(self.config_path) == "/dev/null":
+            return
 
-        updated_data = {**existing_data, **self.model_dump(exclude_unset=True)}
-        with self.config_path.open("w") as f:
-            json.dump(updated_data, f, indent=4)
+        try:
+            if self.config_path.is_file():
+                with self.config_path.open("r") as f:
+                    existing_data = json.load(f)
+            else:
+                existing_data = {}
+
+            updated_data = {**existing_data, **self.model_dump(exclude_unset=True)}
+            with self.config_path.open("w") as f:
+                json.dump(updated_data, f, indent=4)
+
+        except Exception:  # noqa: S110
+            pass
 
     def _reset_user_settings(self) -> None:
         """Reset all user settings to default values"""

src/crewai/cli/create_crew.py

@@ -16,48 +16,72 @@ from crewai.cli.utils import copy_template, load_env_vars, write_env_file
 def create_folder_structure(name, parent_folder=None):
     import keyword
     import re
-    
-    name = name.rstrip('/')
-    
+
+    name = name.rstrip("/")
+
     if not name.strip():
         raise ValueError("Project name cannot be empty or contain only whitespace")
-    
+
     folder_name = name.replace(" ", "_").replace("-", "_").lower()
-    folder_name = re.sub(r'[^a-zA-Z0-9_]', '', folder_name)
-    
+    folder_name = re.sub(r"[^a-zA-Z0-9_]", "", folder_name)
+
     # Check if the name starts with invalid characters or is primarily invalid
-    if re.match(r'^[^a-zA-Z0-9_-]+', name):
-        raise ValueError(f"Project name '{name}' contains no valid characters for a Python module name")
-    
+    if re.match(r"^[^a-zA-Z0-9_-]+", name):
+        raise ValueError(
+            f"Project name '{name}' contains no valid characters for a Python module name"
+        )
+
     if not folder_name:
-        raise ValueError(f"Project name '{name}' contains no valid characters for a Python module name")
-    
+        raise ValueError(
+            f"Project name '{name}' contains no valid characters for a Python module name"
+        )
+
     if folder_name[0].isdigit():
-        raise ValueError(f"Project name '{name}' would generate folder name '{folder_name}' which cannot start with a digit (invalid Python module name)")
-    
+        raise ValueError(
+            f"Project name '{name}' would generate folder name '{folder_name}' which cannot start with a digit (invalid Python module name)"
+        )
+
     if keyword.iskeyword(folder_name):
-        raise ValueError(f"Project name '{name}' would generate folder name '{folder_name}' which is a reserved Python keyword")
-    
+        raise ValueError(
+            f"Project name '{name}' would generate folder name '{folder_name}' which is a reserved Python keyword"
+        )
+
     if not folder_name.isidentifier():
-        raise ValueError(f"Project name '{name}' would generate invalid Python module name '{folder_name}'")
-    
+        raise ValueError(
+            f"Project name '{name}' would generate invalid Python module name '{folder_name}'"
+        )
+
     class_name = name.replace("_", " ").replace("-", " ").title().replace(" ", "")
-    
-    class_name = re.sub(r'[^a-zA-Z0-9_]', '', class_name)
-    
+
+    class_name = re.sub(r"[^a-zA-Z0-9_]", "", class_name)
+
     if not class_name:
-        raise ValueError(f"Project name '{name}' contains no valid characters for a Python class name")
-    
+        raise ValueError(
+            f"Project name '{name}' contains no valid characters for a Python class name"
+        )
+
     if class_name[0].isdigit():
-        raise ValueError(f"Project name '{name}' would generate class name '{class_name}' which cannot start with a digit")
-    
+        raise ValueError(
+            f"Project name '{name}' would generate class name '{class_name}' which cannot start with a digit"
+        )
+
     # Check if the original name (before title casing) is a keyword
-    original_name_clean = re.sub(r'[^a-zA-Z0-9_]', '', name.replace("_", "").replace("-", "").lower())
-    if keyword.iskeyword(original_name_clean) or keyword.iskeyword(class_name) or class_name in ('True', 'False', 'None'):
-        raise ValueError(f"Project name '{name}' would generate class name '{class_name}' which is a reserved Python keyword")
-    
+    original_name_clean = re.sub(
+        r"[^a-zA-Z0-9_]", "", name.replace("_", "").replace("-", "").lower()
+    )
+    if (
+        keyword.iskeyword(original_name_clean)
+        or keyword.iskeyword(class_name)
+        or class_name in ("True", "False", "None")
+    ):
+        raise ValueError(
+            f"Project name '{name}' would generate class name '{class_name}' which is a reserved Python keyword"
+        )
+
     if not class_name.isidentifier():
-        raise ValueError(f"Project name '{name}' would generate invalid Python class name '{class_name}'")
+        raise ValueError(
+            f"Project name '{name}' would generate invalid Python class name '{class_name}'"
+        )
 
     if parent_folder:
         folder_path = Path(parent_folder) / folder_name
@@ -172,7 +196,7 @@ def create_crew(name, provider=None, skip_provider=False, parent_folder=None):
             )
 
         # Check if the selected provider has predefined models
-        if selected_provider in MODELS and MODELS[selected_provider]:
+        if MODELS.get(selected_provider):
             while True:
                 selected_model = select_model(selected_provider, provider_models)
                 if selected_model is None:  # User typed 'q'

src/crewai/cli/crew_chat.py

@@ -5,7 +5,7 @@ import sys
 import threading
 import time
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Set, Tuple
+from typing import Any
 
 import click
 import tomli
@@ -116,7 +116,7 @@ def show_loading(event: threading.Event):
     print()
 
 
-def initialize_chat_llm(crew: Crew) -> Optional[LLM | BaseLLM]:
+def initialize_chat_llm(crew: Crew) -> LLM | BaseLLM | None:
     """Initializes the chat LLM and handles exceptions."""
     try:
         return create_llm(crew.chat_llm)
@@ -157,7 +157,7 @@ def build_system_message(crew_chat_inputs: ChatInputs) -> str:
     )
 
 
-def create_tool_function(crew: Crew, messages: List[Dict[str, str]]) -> Any:
+def create_tool_function(crew: Crew, messages: list[dict[str, str]]) -> Any:
     """Creates a wrapper function for running the crew tool with messages."""
 
     def run_crew_tool_with_messages(**kwargs):
@@ -193,7 +193,7 @@ def chat_loop(chat_llm, messages, crew_tool_schema, available_functions):
                 user_input, chat_llm, messages, crew_tool_schema, available_functions
             )
 
-        except KeyboardInterrupt:
+        except KeyboardInterrupt:  # noqa: PERF203
             click.echo("\nExiting chat. Goodbye!")
             break
         except Exception as e:
@@ -221,9 +221,9 @@ def get_user_input() -> str:
 def handle_user_input(
     user_input: str,
     chat_llm: LLM,
-    messages: List[Dict[str, str]],
-    crew_tool_schema: Dict[str, Any],
-    available_functions: Dict[str, Any],
+    messages: list[dict[str, str]],
+    crew_tool_schema: dict[str, Any],
+    available_functions: dict[str, Any],
 ) -> None:
     if user_input.strip().lower() == "exit":
         click.echo("Exiting chat. Goodbye!")
@@ -281,7 +281,7 @@ def generate_crew_tool_schema(crew_inputs: ChatInputs) -> dict:
     }
 
 
-def run_crew_tool(crew: Crew, messages: List[Dict[str, str]], **kwargs):
+def run_crew_tool(crew: Crew, messages: list[dict[str, str]], **kwargs):
     """
     Runs the crew using crew.kickoff(inputs=kwargs) and returns the output.
 
@@ -304,9 +304,8 @@ def run_crew_tool(crew: Crew, messages: List[Dict[str, str]], **kwargs):
         crew_output = crew.kickoff(inputs=kwargs)
 
         # Convert CrewOutput to a string to send back to the user
-        result = str(crew_output)
+        return str(crew_output)
 
-        return result
     except Exception as e:
         # Exit the chat and show the error message
         click.secho("An error occurred while running the crew:", fg="red")
@@ -314,7 +313,7 @@ def run_crew_tool(crew: Crew, messages: List[Dict[str, str]], **kwargs):
         sys.exit(1)
 
 
-def load_crew_and_name() -> Tuple[Crew, str]:
+def load_crew_and_name() -> tuple[Crew, str]:
     """
     Loads the crew by importing the crew class from the user's project.
 
@@ -351,15 +350,17 @@ def load_crew_and_name() -> Tuple[Crew, str]:
     try:
         crew_module = __import__(crew_module_name, fromlist=[crew_class_name])
     except ImportError as e:
-        raise ImportError(f"Failed to import crew module {crew_module_name}: {e}")
+        raise ImportError(
+            f"Failed to import crew module {crew_module_name}: {e}"
+        ) from e
 
     # Get the crew class from the module
     try:
         crew_class = getattr(crew_module, crew_class_name)
-    except AttributeError:
+    except AttributeError as e:
         raise AttributeError(
             f"Crew class {crew_class_name} not found in module {crew_module_name}"
-        )
+        ) from e
 
     # Instantiate the crew
     crew_instance = crew_class().crew()
@@ -395,7 +396,7 @@ def generate_crew_chat_inputs(crew: Crew, crew_name: str, chat_llm) -> ChatInput
     )
 
 
-def fetch_required_inputs(crew: Crew) -> Set[str]:
+def fetch_required_inputs(crew: Crew) -> set[str]:
     """
     Extracts placeholders from the crew's tasks and agents.
 
@@ -405,8 +406,8 @@ def fetch_required_inputs(crew: Crew) -> Set[str]:
     Returns:
         Set[str]: A set of placeholder names.
     """
-    placeholder_pattern = re.compile(r"\{(.+?)\}")
-    required_inputs: Set[str] = set()
+    placeholder_pattern = re.compile(r"\{(.+?)}")
+    required_inputs: set[str] = set()
 
     # Scan tasks
     for task in crew.tasks:
@@ -435,7 +436,7 @@ def generate_input_description_with_ai(input_name: str, crew: Crew, chat_llm) ->
     """
     # Gather context from tasks and agents where the input is used
     context_texts = []
-    placeholder_pattern = re.compile(r"\{(.+?)\}")
+    placeholder_pattern = re.compile(r"\{(.+?)}")
 
     for task in crew.tasks:
         if (
@@ -479,9 +480,7 @@ def generate_input_description_with_ai(input_name: str, crew: Crew, chat_llm) ->
         f"{context}"
     )
     response = chat_llm.call(messages=[{"role": "user", "content": prompt}])
-    description = response.strip()
-
-    return description
+    return response.strip()
 
 
 def generate_crew_description_with_ai(crew: Crew, chat_llm) -> str:
@@ -497,7 +496,7 @@ def generate_crew_description_with_ai(crew: Crew, chat_llm) -> str:
     """
     # Gather context from tasks and agents
     context_texts = []
-    placeholder_pattern = re.compile(r"\{(.+?)\}")
+    placeholder_pattern = re.compile(r"\{(.+?)}")
 
     for task in crew.tasks:
         # Replace placeholders with input names
@@ -531,6 +530,4 @@ def generate_crew_description_with_ai(crew: Crew, chat_llm) -> str:
         f"{context}"
     )
     response = chat_llm.call(messages=[{"role": "user", "content": prompt}])
-    crew_description = response.strip()
-
-    return crew_description
+    return response.strip()

src/crewai/cli/git.py

@@ -14,11 +14,15 @@ class Repository:
 
         self.fetch()
 
-    def is_git_installed(self) -> bool:
+    @staticmethod
+    def is_git_installed() -> bool:
         """Check if Git is installed and available in the system."""
         try:
             subprocess.run(
-                ["git", "--version"], capture_output=True, check=True, text=True
+                ["git", "--version"],  # noqa: S607
+                capture_output=True,
+                check=True,
+                text=True,
             )
             return True
         except (subprocess.CalledProcessError, FileNotFoundError):
@@ -26,22 +30,26 @@ class Repository:
 
     def fetch(self) -> None:
         """Fetch latest updates from the remote."""
-        subprocess.run(["git", "fetch"], cwd=self.path, check=True)
+        subprocess.run(["git", "fetch"], cwd=self.path, check=True)  # noqa: S607
 
     def status(self) -> str:
         """Get the git status in porcelain format."""
         return subprocess.check_output(
-            ["git", "status", "--branch", "--porcelain"],
+            ["git", "status", "--branch", "--porcelain"],  # noqa: S607
             cwd=self.path,
             encoding="utf-8",
         ).strip()
 
-    @lru_cache(maxsize=None)
+    @lru_cache(maxsize=None)  # noqa: B019
     def is_git_repo(self) -> bool:
-        """Check if the current directory is a git repository."""
+        """Check if the current directory is a git repository.
+
+        Notes:
+          - TODO: This method is cached to avoid redundant checks, but using lru_cache on methods can lead to memory leaks
+        """
         try:
             subprocess.check_output(
-                ["git", "rev-parse", "--is-inside-work-tree"],
+                ["git", "rev-parse", "--is-inside-work-tree"],  # noqa: S607
                 cwd=self.path,
                 encoding="utf-8",
             )
@@ -64,14 +72,13 @@ class Repository:
         """Return True if the Git repository is fully synced with the remote, False otherwise."""
         if self.has_uncommitted_changes() or self.is_ahead_or_behind():
             return False
-        else:
-            return True
+        return True
 
     def origin_url(self) -> str | None:
         """Get the Git repository's remote URL."""
         try:
             result = subprocess.run(
-                ["git", "remote", "get-url", "origin"],
+                ["git", "remote", "get-url", "origin"],  # noqa: S607
                 cwd=self.path,
                 capture_output=True,
                 text=True,

src/crewai/cli/install_crew.py

@@ -12,8 +12,8 @@ def install_crew(proxy_options: list[str]) -> None:
     Install the crew by running the UV command to lock and install.
     """
     try:
-        command = ["uv", "sync"] + proxy_options
-        subprocess.run(command, check=True, capture_output=False, text=True)
+        command = ["uv", "sync", *proxy_options]
+        subprocess.run(command, check=True, capture_output=False, text=True)  # noqa: S603
 
     except subprocess.CalledProcessError as e:
         click.echo(f"An error occurred while running the crew: {e}", err=True)

src/crewai/cli/plus_api.py

@@ -1,11 +1,10 @@
-from typing import List, Optional
 from urllib.parse import urljoin
 
 import requests
 
 from crewai.cli.config import Settings
-from crewai.cli.version import get_crewai_version
 from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
+from crewai.cli.version import get_crewai_version
 
 
 class PlusAPI:
@@ -56,9 +55,9 @@ class PlusAPI:
         handle: str,
         is_public: bool,
         version: str,
-        description: Optional[str],
+        description: str | None,
         encoded_file: str,
-        available_exports: Optional[List[str]] = None,
+        available_exports: list[str] | None = None,
     ):
         params = {
             "handle": handle,
@@ -167,3 +166,13 @@ class PlusAPI:
             json=payload,
             timeout=30,
         )
+
+    def mark_trace_batch_as_failed(
+        self, trace_batch_id: str, error_message: str
+    ) -> requests.Response:
+        return self._make_request(
+            "PATCH",
+            f"{self.TRACING_RESOURCE}/batches/{trace_batch_id}",
+            json={"status": "failed", "failure_reason": error_message},
+            timeout=30,
+        )

src/crewai/cli/provider.py

@@ -1,10 +1,10 @@
-import os
-import certifi
 import json
+import os
 import time
 from collections import defaultdict
 from pathlib import Path
 
+import certifi
 import click
 import requests
 
@@ -25,7 +25,7 @@ def select_choice(prompt_message, choices):
 
     provider_models = get_provider_data()
     if not provider_models:
-        return
+        return None
     click.secho(prompt_message, fg="cyan")
     for idx, choice in enumerate(choices, start=1):
         click.secho(f"{idx}. {choice}", fg="cyan")
@@ -67,7 +67,7 @@ def select_provider(provider_models):
     all_providers = sorted(set(predefined_providers + list(provider_models.keys())))
 
     provider = select_choice(
-        "Select a provider to set up:", predefined_providers + ["other"]
+        "Select a provider to set up:", [*predefined_providers, "other"]
     )
     if provider is None:  # User typed 'q'
         return None
@@ -102,10 +102,9 @@ def select_model(provider, provider_models):
         click.secho(f"No models available for provider '{provider}'.", fg="red")
         return None
 
-    selected_model = select_choice(
+    return select_choice(
         f"Select a model to use for {provider.capitalize()}:", available_models
     )
-    return selected_model
 
 
 def load_provider_data(cache_file, cache_expiry):
@@ -165,7 +164,7 @@ def fetch_provider_data(cache_file):
     Returns:
     - dict or None: The fetched provider data or None if the operation fails.
     """
-    ssl_config = os.environ['SSL_CERT_FILE'] = certifi.where()
+    ssl_config = os.environ["SSL_CERT_FILE"] = certifi.where()
 
     try:
         response = requests.get(JSON_URL, stream=True, timeout=60, verify=ssl_config)

src/crewai/cli/run_crew.py

@@ -1,6 +1,5 @@
 import subprocess
 from enum import Enum
-from typing import List, Optional
 
 import click
 from packaging import version
@@ -57,7 +56,7 @@ def execute_command(crew_type: CrewType) -> None:
     command = ["uv", "run", "kickoff" if crew_type == CrewType.FLOW else "run_crew"]
 
     try:
-        subprocess.run(command, capture_output=False, text=True, check=True)
+        subprocess.run(command, capture_output=False, text=True, check=True)  # noqa: S603
 
     except subprocess.CalledProcessError as e:
         handle_error(e, crew_type)

src/crewai/cli/shared/token_manager.py

@@ -3,7 +3,7 @@ import os
 import sys
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+
 from cryptography.fernet import Fernet
 
 
@@ -49,7 +49,7 @@ class TokenManager:
         encrypted_data = self.fernet.encrypt(json.dumps(data).encode())
         self.save_secure_file(self.file_path, encrypted_data)
 
-    def get_token(self) -> Optional[str]:
+    def get_token(self) -> str | None:
         """
         Get the access token if it is valid and not expired.
 
@@ -113,7 +113,7 @@ class TokenManager:
         # Set appropriate permissions (read/write for owner only)
         os.chmod(file_path, 0o600)
 
-    def read_secure_file(self, filename: str) -> Optional[bytes]:
+    def read_secure_file(self, filename: str) -> bytes | None:
         """
         Read the content of a secure file.
 

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

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

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

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

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

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

src/crewai/cli/tools/main.py

@@ -12,6 +12,7 @@ from crewai.cli import git
 from crewai.cli.command import BaseCommand, PlusAPIMixin
 from crewai.cli.config import Settings
 from crewai.cli.utils import (
+    build_env_with_tool_repository_credentials,
     extract_available_exports,
     get_project_description,
     get_project_name,
@@ -42,8 +43,7 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         if project_root.exists():
             click.secho(f"Folder {folder_name} already exists.", fg="red")
             raise SystemExit
-        else:
-            os.makedirs(project_root)
+        os.makedirs(project_root)
 
         click.secho(f"Creating custom tool {folder_name}...", fg="green", bold=True)
 
@@ -56,7 +56,7 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         os.chdir(project_root)
         try:
             self.login()
-            subprocess.run(["git", "init"], check=True)
+            subprocess.run(["git", "init"], check=True)  # noqa: S607
             console.print(
                 f"[green]Created custom tool [bold]{folder_name}[/bold]. Run [bold]cd {project_root}[/bold] to start working.[/green]"
             )
@@ -76,10 +76,10 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
             raise SystemExit()
 
         project_name = get_project_name(require=True)
-        assert isinstance(project_name, str)
+        assert isinstance(project_name, str)  # noqa: S101
 
         project_version = get_project_version(require=True)
-        assert isinstance(project_version, str)
+        assert isinstance(project_version, str)  # noqa: S101
 
         project_description = get_project_description(require=False)
         encoded_tarball = None
@@ -94,8 +94,8 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         self._print_current_organization()
 
         with tempfile.TemporaryDirectory() as temp_build_dir:
-            subprocess.run(
-                ["uv", "build", "--sdist", "--out-dir", temp_build_dir],
+            subprocess.run(  # noqa: S603
+                ["uv", "build", "--sdist", "--out-dir", temp_build_dir],  # noqa: S607
                 check=True,
                 capture_output=False,
             )
@@ -146,7 +146,7 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
                 style="bold red",
             )
             raise SystemExit
-        elif get_response.status_code != 200:
+        if get_response.status_code != 200:
             console.print(
                 "Failed to get tool details. Please try again later.", style="bold red"
             )
@@ -196,10 +196,10 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         else:
             add_package_command.extend(["--index", index, tool_handle])
 
-        add_package_result = subprocess.run(
+        add_package_result = subprocess.run(  # noqa: S603
             add_package_command,
             capture_output=False,
-            env=self._build_env_with_credentials(repository_handle),
+            env=build_env_with_tool_repository_credentials(repository_handle),
             text=True,
             check=True,
         )
@@ -221,20 +221,6 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
             )
             raise SystemExit
 
-    def _build_env_with_credentials(self, repository_handle: str):
-        repository_handle = repository_handle.upper().replace("-", "_")
-        settings = Settings()
-
-        env = os.environ.copy()
-        env[f"UV_INDEX_{repository_handle}_USERNAME"] = str(
-            settings.tool_repository_username or ""
-        )
-        env[f"UV_INDEX_{repository_handle}_PASSWORD"] = str(
-            settings.tool_repository_password or ""
-        )
-
-        return env
-
     def _print_current_organization(self) -> None:
         settings = Settings()
         if settings.org_uuid:

src/crewai/cli/utils.py

@@ -5,12 +5,13 @@ import sys
 from functools import reduce
 from inspect import getmro, isclass, isfunction, ismethod
 from pathlib import Path
-from typing import Any, Dict, List, get_type_hints
+from typing import Any, get_type_hints
 
 import click
 import tomli
 from rich.console import Console
 
+from crewai.cli.config import Settings
 from crewai.cli.constants import ENV_VARS
 from crewai.crew import Crew
 from crewai.flow import Flow
@@ -41,8 +42,7 @@ def copy_template(src, dst, name, class_name, folder_name):
 def read_toml(file_path: str = "pyproject.toml"):
     """Read the content of a TOML file and return it as a dictionary."""
     with open(file_path, "rb") as f:
-        toml_dict = tomli.load(f)
-    return toml_dict
+        return tomli.load(f)
 
 
 def parse_toml(content):
@@ -77,7 +77,7 @@ def get_project_description(
 
 
 def _get_project_attribute(
-    pyproject_path: str, keys: List[str], require: bool
+    pyproject_path: str, keys: list[str], require: bool
 ) -> Any | None:
     """Get an attribute from the pyproject.toml file."""
     attribute = None
@@ -96,16 +96,20 @@ def _get_project_attribute(
     except FileNotFoundError:
         console.print(f"Error: {pyproject_path} not found.", style="bold red")
     except KeyError:
-        console.print(f"Error: {pyproject_path} is not a valid pyproject.toml file.", style="bold red")
-    except tomllib.TOMLDecodeError if sys.version_info >= (3, 11) else Exception as e:  # type: ignore
         console.print(
-            f"Error: {pyproject_path} is not a valid TOML file."
-            if sys.version_info >= (3, 11)
-            else f"Error reading the pyproject.toml file: {e}",
+            f"Error: {pyproject_path} is not a valid pyproject.toml file.",
             style="bold red",
         )
     except Exception as e:
-        console.print(f"Error reading the pyproject.toml file: {e}", style="bold red")
+        # Handle TOML decode errors for Python 3.11+
+        if sys.version_info >= (3, 11) and isinstance(e, tomllib.TOMLDecodeError):  # type: ignore
+            console.print(
+                f"Error: {pyproject_path} is not a valid TOML file.", style="bold red"
+            )
+        else:
+            console.print(
+                f"Error reading the pyproject.toml file: {e}", style="bold red"
+            )
 
     if require and not attribute:
         console.print(
@@ -117,7 +121,7 @@ def _get_project_attribute(
     return attribute
 
 
-def _get_nested_value(data: Dict[str, Any], keys: List[str]) -> Any:
+def _get_nested_value(data: dict[str, Any], keys: list[str]) -> Any:
     return reduce(dict.__getitem__, keys, data)
 
 
@@ -296,7 +300,10 @@ def get_crews(crew_path: str = "crew.py", require: bool = False) -> list[Crew]:
                                 try:
                                     crew_instances.extend(fetch_crews(module_attr))
                                 except Exception as e:
-                                    console.print(f"Error processing attribute {attr_name}: {e}", style="bold red")
+                                    console.print(
+                                        f"Error processing attribute {attr_name}: {e}",
+                                        style="bold red",
+                                    )
                                     continue
 
                             # If we found crew instances, break out of the loop
@@ -304,12 +311,15 @@ def get_crews(crew_path: str = "crew.py", require: bool = False) -> list[Crew]:
                                 break
 
                         except Exception as exec_error:
-                            console.print(f"Error executing module: {exec_error}", style="bold red")
+                            console.print(
+                                f"Error executing module: {exec_error}",
+                                style="bold red",
+                            )
 
                     except (ImportError, AttributeError) as e:
                         if require:
                             console.print(
-                                f"Error importing crew from {crew_path}: {str(e)}",
+                                f"Error importing crew from {crew_path}: {e!s}",
                                 style="bold red",
                             )
                         continue
@@ -325,9 +335,9 @@ def get_crews(crew_path: str = "crew.py", require: bool = False) -> list[Crew]:
     except Exception as e:
         if require:
             console.print(
-                f"Unexpected error while loading crew: {str(e)}", style="bold red"
+                f"Unexpected error while loading crew: {e!s}", style="bold red"
             )
-            raise SystemExit
+            raise SystemExit from e
     return crew_instances
 
 
@@ -348,8 +358,7 @@ def get_crew_instance(module_attr) -> Crew | None:
 
     if isinstance(module_attr, Crew):
         return module_attr
-    else:
-        return None
+    return None
 
 
 def fetch_crews(module_attr) -> list[Crew]:
@@ -402,11 +411,26 @@ def extract_available_exports(dir_path: str = "src"):
         return available_exports
 
     except Exception as e:
-        console.print(f"[red]Error: Could not extract tool classes: {str(e)}[/red]")
+        console.print(f"[red]Error: Could not extract tool classes: {e!s}[/red]")
         console.print(
             "Please ensure your project contains valid tools (classes inheriting from BaseTool or functions with @tool decorator)."
         )
-        raise SystemExit(1)
+        raise SystemExit(1) from e
+
+
+def build_env_with_tool_repository_credentials(repository_handle: str):
+    repository_handle = repository_handle.upper().replace("-", "_")
+    settings = Settings()
+
+    env = os.environ.copy()
+    env[f"UV_INDEX_{repository_handle}_USERNAME"] = str(
+        settings.tool_repository_username or ""
+    )
+    env[f"UV_INDEX_{repository_handle}_PASSWORD"] = str(
+        settings.tool_repository_password or ""
+    )
+
+    return env
 
 
 def _load_tools_from_init(init_file: Path) -> list[dict[str, Any]]:
@@ -440,8 +464,8 @@ def _load_tools_from_init(init_file: Path) -> list[dict[str, Any]]:
         ]
 
     except Exception as e:
-        console.print(f"[red]Warning: Could not load {init_file}: {str(e)}[/red]")
-        raise SystemExit(1)
+        console.print(f"[red]Warning: Could not load {init_file}: {e!s}[/red]")
+        raise SystemExit(1) from e
 
     finally:
         sys.modules.pop("temp_module", None)

src/crewai/context.py

@@ -0,0 +1,25 @@
+import os
+import contextvars
+from typing import Optional
+from contextlib import contextmanager
+
+_platform_integration_token: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "platform_integration_token", default=None
+)
+
+def set_platform_integration_token(integration_token: str) -> None:
+    _platform_integration_token.set(integration_token)
+
+def get_platform_integration_token() -> Optional[str]:
+    token = _platform_integration_token.get()
+    if token is None:
+        token = os.getenv("CREWAI_PLATFORM_INTEGRATION_TOKEN")
+    return token
+
+@contextmanager
+def platform_context(integration_token: str):
+    token = _platform_integration_token.set(integration_token)
+    try:
+        yield
+    finally:
+        _platform_integration_token.reset(token)

src/crewai/crews/crew_output.py

@@ -1,5 +1,5 @@
 import json
-from typing import Any, Dict, Optional
+from typing import Any
 
 from pydantic import BaseModel, Field
 
@@ -12,19 +12,21 @@ class CrewOutput(BaseModel):
     """Class that represents the result of a crew."""
 
     raw: str = Field(description="Raw output of crew", default="")
-    pydantic: Optional[BaseModel] = Field(
+    pydantic: BaseModel | None = Field(
         description="Pydantic output of Crew", default=None
     )
-    json_dict: Optional[Dict[str, Any]] = Field(
+    json_dict: dict[str, Any] | None = Field(
         description="JSON dict output of Crew", default=None
     )
     tasks_output: list[TaskOutput] = Field(
         description="Output of each task", default=[]
     )
-    token_usage: UsageMetrics = Field(description="Processed token summary", default={})
+    token_usage: UsageMetrics = Field(
+        description="Processed token summary", default_factory=UsageMetrics
+    )
 
     @property
-    def json(self) -> Optional[str]:
+    def json(self) -> str | None:  # type: ignore[override]
         if self.tasks_output[-1].output_format != OutputFormat.JSON:
             raise ValueError(
                 "No JSON output found in the final task. Please make sure to set the output_json property in the final task in your crew."
@@ -32,7 +34,7 @@ class CrewOutput(BaseModel):
 
         return json.dumps(self.json_dict)
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """Convert json_output and pydantic_output to a dictionary."""
         output_dict = {}
         if self.json_dict:
@@ -44,10 +46,9 @@ class CrewOutput(BaseModel):
     def __getitem__(self, key):
         if self.pydantic and hasattr(self.pydantic, key):
             return getattr(self.pydantic, key)
-        elif self.json_dict and key in self.json_dict:
+        if self.json_dict and key in self.json_dict:
             return self.json_dict[key]
-        else:
-            raise KeyError(f"Key '{key}' not found in CrewOutput.")
+        raise KeyError(f"Key '{key}' not found in CrewOutput.")
 
     def __str__(self):
         if self.pydantic:

src/crewai/events/__init__.py

@@ -9,48 +9,158 @@ This module provides the event infrastructure that allows users to:
 
 from crewai.events.base_event_listener import BaseEventListener
 from crewai.events.event_bus import crewai_event_bus
-
+from crewai.events.types.agent_events import (
+    AgentEvaluationCompletedEvent,
+    AgentEvaluationFailedEvent,
+    AgentEvaluationStartedEvent,
+    AgentExecutionCompletedEvent,
+    AgentExecutionErrorEvent,
+    AgentExecutionStartedEvent,
+    LiteAgentExecutionCompletedEvent,
+    LiteAgentExecutionErrorEvent,
+    LiteAgentExecutionStartedEvent,
+)
+from crewai.events.types.crew_events import (
+    CrewKickoffCompletedEvent,
+    CrewKickoffFailedEvent,
+    CrewKickoffStartedEvent,
+    CrewTestCompletedEvent,
+    CrewTestFailedEvent,
+    CrewTestResultEvent,
+    CrewTestStartedEvent,
+    CrewTrainCompletedEvent,
+    CrewTrainFailedEvent,
+    CrewTrainStartedEvent,
+)
+from crewai.events.types.flow_events import (
+    FlowCreatedEvent,
+    FlowEvent,
+    FlowFinishedEvent,
+    FlowPlotEvent,
+    FlowStartedEvent,
+    MethodExecutionFailedEvent,
+    MethodExecutionFinishedEvent,
+    MethodExecutionStartedEvent,
+)
+from crewai.events.types.knowledge_events import (
+    KnowledgeQueryCompletedEvent,
+    KnowledgeQueryFailedEvent,
+    KnowledgeQueryStartedEvent,
+    KnowledgeRetrievalCompletedEvent,
+    KnowledgeRetrievalStartedEvent,
+    KnowledgeSearchQueryFailedEvent,
+)
+from crewai.events.types.llm_events import (
+    LLMCallCompletedEvent,
+    LLMCallFailedEvent,
+    LLMCallStartedEvent,
+    LLMStreamChunkEvent,
+)
+from crewai.events.types.llm_guardrail_events import (
+    LLMGuardrailCompletedEvent,
+    LLMGuardrailStartedEvent,
+)
+from crewai.events.types.logging_events import (
+    AgentLogsExecutionEvent,
+    AgentLogsStartedEvent,
+)
 from crewai.events.types.memory_events import (
     MemoryQueryCompletedEvent,
-    MemorySaveCompletedEvent,
-    MemorySaveStartedEvent,
+    MemoryQueryFailedEvent,
     MemoryQueryStartedEvent,
     MemoryRetrievalCompletedEvent,
+    MemoryRetrievalStartedEvent,
+    MemorySaveCompletedEvent,
     MemorySaveFailedEvent,
-    MemoryQueryFailedEvent,
+    MemorySaveStartedEvent,
 )
-
-from crewai.events.types.knowledge_events import (
-    KnowledgeRetrievalStartedEvent,
-    KnowledgeRetrievalCompletedEvent,
+from crewai.events.types.reasoning_events import (
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+    AgentReasoningStartedEvent,
+    ReasoningEvent,
 )
-
-from crewai.events.types.crew_events import (
-    CrewKickoffStartedEvent,
-    CrewKickoffCompletedEvent,
+from crewai.events.types.task_events import (
+    TaskCompletedEvent,
+    TaskEvaluationEvent,
+    TaskFailedEvent,
+    TaskStartedEvent,
 )
-from crewai.events.types.agent_events import (
-    AgentExecutionCompletedEvent,
-)
-
-from crewai.events.types.llm_events import (
-    LLMStreamChunkEvent,
+from crewai.events.types.tool_usage_events import (
+    ToolExecutionErrorEvent,
+    ToolSelectionErrorEvent,
+    ToolUsageErrorEvent,
+    ToolUsageEvent,
+    ToolUsageFinishedEvent,
+    ToolUsageStartedEvent,
+    ToolValidateInputErrorEvent,
 )
 
 __all__ = [
+    "AgentEvaluationCompletedEvent",
+    "AgentEvaluationFailedEvent",
+    "AgentEvaluationStartedEvent",
+    "AgentExecutionCompletedEvent",
+    "AgentExecutionErrorEvent",
+    "AgentExecutionStartedEvent",
+    "AgentLogsExecutionEvent",
+    "AgentLogsStartedEvent",
+    "AgentReasoningCompletedEvent",
+    "AgentReasoningFailedEvent",
+    "AgentReasoningStartedEvent",
     "BaseEventListener",
-    "crewai_event_bus",
+    "CrewKickoffCompletedEvent",
+    "CrewKickoffFailedEvent",
+    "CrewKickoffStartedEvent",
+    "CrewTestCompletedEvent",
+    "CrewTestFailedEvent",
+    "CrewTestResultEvent",
+    "CrewTestStartedEvent",
+    "CrewTrainCompletedEvent",
+    "CrewTrainFailedEvent",
+    "CrewTrainStartedEvent",
+    "FlowCreatedEvent",
+    "FlowEvent",
+    "FlowFinishedEvent",
+    "FlowPlotEvent",
+    "FlowStartedEvent",
+    "KnowledgeQueryCompletedEvent",
+    "KnowledgeQueryFailedEvent",
+    "KnowledgeQueryStartedEvent",
+    "KnowledgeRetrievalCompletedEvent",
+    "KnowledgeRetrievalStartedEvent",
+    "KnowledgeSearchQueryFailedEvent",
+    "LLMCallCompletedEvent",
+    "LLMCallFailedEvent",
+    "LLMCallStartedEvent",
+    "LLMGuardrailCompletedEvent",
+    "LLMGuardrailStartedEvent",
+    "LLMStreamChunkEvent",
+    "LiteAgentExecutionCompletedEvent",
+    "LiteAgentExecutionErrorEvent",
+    "LiteAgentExecutionStartedEvent",
     "MemoryQueryCompletedEvent",
-    "MemorySaveCompletedEvent",
-    "MemorySaveStartedEvent",
+    "MemoryQueryFailedEvent",
     "MemoryQueryStartedEvent",
     "MemoryRetrievalCompletedEvent",
+    "MemoryRetrievalStartedEvent",
+    "MemorySaveCompletedEvent",
     "MemorySaveFailedEvent",
-    "MemoryQueryFailedEvent",
-    "KnowledgeRetrievalStartedEvent",
-    "KnowledgeRetrievalCompletedEvent",
-    "CrewKickoffStartedEvent",
-    "CrewKickoffCompletedEvent",
-    "AgentExecutionCompletedEvent",
-    "LLMStreamChunkEvent",
-]
+    "MemorySaveStartedEvent",
+    "MethodExecutionFailedEvent",
+    "MethodExecutionFinishedEvent",
+    "MethodExecutionStartedEvent",
+    "ReasoningEvent",
+    "TaskCompletedEvent",
+    "TaskEvaluationEvent",
+    "TaskFailedEvent",
+    "TaskStartedEvent",
+    "ToolExecutionErrorEvent",
+    "ToolSelectionErrorEvent",
+    "ToolUsageErrorEvent",
+    "ToolUsageEvent",
+    "ToolUsageFinishedEvent",
+    "ToolUsageStartedEvent",
+    "ToolValidateInputErrorEvent",
+    "crewai_event_bus",
+]

src/crewai/events/base_events.py

@@ -1,5 +1,6 @@
 from datetime import datetime, timezone
-from typing import Any, Dict, Optional
+from typing import Any
+
 from pydantic import BaseModel, Field
 
 from crewai.utilities.serialization import to_serializable
@@ -10,11 +11,11 @@ class BaseEvent(BaseModel):
 
     timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
     type: str
-    source_fingerprint: Optional[str] = None  # UUID string of the source entity
-    source_type: Optional[str] = (
+    source_fingerprint: str | None = None  # UUID string of the source entity
+    source_type: str | None = (
         None  # "agent", "task", "crew", "memory", "entity_memory", "short_term_memory", "long_term_memory", "external_memory"
     )
-    fingerprint_metadata: Optional[Dict[str, Any]] = None  # Any relevant metadata
+    fingerprint_metadata: dict[str, Any] | None = None  # Any relevant metadata
 
     def to_json(self, exclude: set[str] | None = None):
         """
@@ -28,13 +29,13 @@ class BaseEvent(BaseModel):
         """
         return to_serializable(self, exclude=exclude)
 
-    def _set_task_params(self, data: Dict[str, Any]):
+    def _set_task_params(self, data: dict[str, Any]):
         if "from_task" in data and (task := data["from_task"]):
             self.task_id = task.id
             self.task_name = task.name or task.description
             self.from_task = None
 
-    def _set_agent_params(self, data: Dict[str, Any]):
+    def _set_agent_params(self, data: dict[str, Any]):
         task = data.get("from_task", None)
         agent = task.agent if task else data.get("from_agent", None)
 

src/crewai/events/event_bus.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import threading
+from collections.abc import Callable
 from contextlib import contextmanager
-from typing import Any, Callable, Dict, List, Type, TypeVar, cast
+from typing import Any, TypeVar, cast
 
 from blinker import Signal
 
@@ -25,17 +26,17 @@ class CrewAIEventsBus:
         if cls._instance is None:
             with cls._lock:
                 if cls._instance is None:  # prevent race condition
-                    cls._instance = super(CrewAIEventsBus, cls).__new__(cls)
+                    cls._instance = super().__new__(cls)
                     cls._instance._initialize()
         return cls._instance
 
     def _initialize(self) -> None:
         """Initialize the event bus internal state"""
         self._signal = Signal("crewai_event_bus")
-        self._handlers: Dict[Type[BaseEvent], List[Callable]] = {}
+        self._handlers: dict[type[BaseEvent], list[Callable]] = {}
 
     def on(
-        self, event_type: Type[EventT]
+        self, event_type: type[EventT]
     ) -> Callable[[Callable[[Any, EventT], None]], Callable[[Any, EventT], None]]:
         """
         Decorator to register an event handler for a specific event type.
@@ -61,6 +62,18 @@ class CrewAIEventsBus:
 
         return decorator
 
+    @staticmethod
+    def _call_handler(
+        handler: Callable, source: Any, event: BaseEvent, event_type: type
+    ) -> None:
+        """Call a single handler with error handling."""
+        try:
+            handler(source, event)
+        except Exception as e:
+            print(
+                f"[EventBus Error] Handler '{handler.__name__}' failed for event '{event_type.__name__}': {e}"
+            )
+
     def emit(self, source: Any, event: BaseEvent) -> None:
         """
         Emit an event to all registered handlers
@@ -72,17 +85,12 @@ class CrewAIEventsBus:
         for event_type, handlers in self._handlers.items():
             if isinstance(event, event_type):
                 for handler in handlers:
-                    try:
-                        handler(source, event)
-                    except Exception as e:
-                        print(
-                            f"[EventBus Error] Handler '{handler.__name__}' failed for event '{event_type.__name__}': {e}"
-                        )
+                    self._call_handler(handler, source, event, event_type)
 
         self._signal.send(source, event=event)
 
     def register_handler(
-        self, event_type: Type[EventTypes], handler: Callable[[Any, EventTypes], None]
+        self, event_type: type[EventTypes], handler: Callable[[Any, EventTypes], None]
     ) -> None:
         """Register an event handler for a specific event type"""
         if event_type not in self._handlers:

src/crewai/events/event_listener.py

@@ -1,15 +1,30 @@
 from __future__ import annotations
 
 from io import StringIO
-from typing import Any, Dict
+from typing import Any
 
 from pydantic import Field, PrivateAttr
-from crewai.llm import LLM
-from crewai.task import Task
-from crewai.telemetry.telemetry import Telemetry
-from crewai.utilities import Logger
-from crewai.utilities.constants import EMITTER_COLOR
+
 from crewai.events.base_event_listener import BaseEventListener
+from crewai.events.types.agent_events import (
+    AgentExecutionCompletedEvent,
+    AgentExecutionStartedEvent,
+    LiteAgentExecutionCompletedEvent,
+    LiteAgentExecutionErrorEvent,
+    LiteAgentExecutionStartedEvent,
+)
+from crewai.events.types.crew_events import (
+    CrewKickoffCompletedEvent,
+    CrewKickoffFailedEvent,
+    CrewKickoffStartedEvent,
+    CrewTestCompletedEvent,
+    CrewTestFailedEvent,
+    CrewTestResultEvent,
+    CrewTestStartedEvent,
+    CrewTrainCompletedEvent,
+    CrewTrainFailedEvent,
+    CrewTrainStartedEvent,
+)
 from crewai.events.types.knowledge_events import (
     KnowledgeQueryCompletedEvent,
     KnowledgeQueryFailedEvent,
@@ -25,34 +40,21 @@ from crewai.events.types.llm_events import (
     LLMStreamChunkEvent,
 )
 from crewai.events.types.llm_guardrail_events import (
-    LLMGuardrailStartedEvent,
     LLMGuardrailCompletedEvent,
-)
-from crewai.events.utils.console_formatter import ConsoleFormatter
-
-from crewai.events.types.agent_events import (
-    AgentExecutionCompletedEvent,
-    AgentExecutionStartedEvent,
-    LiteAgentExecutionCompletedEvent,
-    LiteAgentExecutionErrorEvent,
-    LiteAgentExecutionStartedEvent,
+    LLMGuardrailStartedEvent,
 )
 from crewai.events.types.logging_events import (
-    AgentLogsStartedEvent,
     AgentLogsExecutionEvent,
+    AgentLogsStartedEvent,
 )
-from crewai.events.types.crew_events import (
-    CrewKickoffCompletedEvent,
-    CrewKickoffFailedEvent,
-    CrewKickoffStartedEvent,
-    CrewTestCompletedEvent,
-    CrewTestFailedEvent,
-    CrewTestResultEvent,
-    CrewTestStartedEvent,
-    CrewTrainCompletedEvent,
-    CrewTrainFailedEvent,
-    CrewTrainStartedEvent,
-)
+from crewai.events.utils.console_formatter import ConsoleFormatter
+from crewai.llm import LLM
+from crewai.task import Task
+from crewai.telemetry.telemetry import Telemetry
+from crewai.utilities import Logger
+from crewai.utilities.constants import EMITTER_COLOR
+
+from .listeners.memory_listener import MemoryListener
 from .types.flow_events import (
     FlowCreatedEvent,
     FlowFinishedEvent,
@@ -61,26 +63,24 @@ from .types.flow_events import (
     MethodExecutionFinishedEvent,
     MethodExecutionStartedEvent,
 )
+from .types.reasoning_events import (
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+    AgentReasoningStartedEvent,
+)
 from .types.task_events import TaskCompletedEvent, TaskFailedEvent, TaskStartedEvent
 from .types.tool_usage_events import (
     ToolUsageErrorEvent,
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
-from .types.reasoning_events import (
-    AgentReasoningStartedEvent,
-    AgentReasoningCompletedEvent,
-    AgentReasoningFailedEvent,
-)
-
-from .listeners.memory_listener import MemoryListener
 
 
 class EventListener(BaseEventListener):
     _instance = None
     _telemetry: Telemetry = PrivateAttr(default_factory=lambda: Telemetry())
     logger = Logger(verbose=True, default_color=EMITTER_COLOR)
-    execution_spans: Dict[Task, Any] = Field(default_factory=dict)
+    execution_spans: dict[Task, Any] = Field(default_factory=dict)
     next_chunk = 0
     text_stream = StringIO()
     knowledge_retrieval_in_progress = False

src/crewai/events/event_types.py

@@ -1,11 +1,10 @@
-from typing import Union
-
 from crewai.events.types.agent_events import (
     AgentExecutionCompletedEvent,
     AgentExecutionErrorEvent,
     AgentExecutionStartedEvent,
     LiteAgentExecutionCompletedEvent,
 )
+
 from .types.crew_events import (
     CrewKickoffCompletedEvent,
     CrewKickoffFailedEvent,
@@ -24,6 +23,14 @@ from .types.flow_events import (
     MethodExecutionFinishedEvent,
     MethodExecutionStartedEvent,
 )
+from .types.knowledge_events import (
+    KnowledgeQueryCompletedEvent,
+    KnowledgeQueryFailedEvent,
+    KnowledgeQueryStartedEvent,
+    KnowledgeRetrievalCompletedEvent,
+    KnowledgeRetrievalStartedEvent,
+    KnowledgeSearchQueryFailedEvent,
+)
 from .types.llm_events import (
     LLMCallCompletedEvent,
     LLMCallFailedEvent,
@@ -34,6 +41,21 @@ from .types.llm_guardrail_events import (
     LLMGuardrailCompletedEvent,
     LLMGuardrailStartedEvent,
 )
+from .types.memory_events import (
+    MemoryQueryCompletedEvent,
+    MemoryQueryFailedEvent,
+    MemoryQueryStartedEvent,
+    MemoryRetrievalCompletedEvent,
+    MemoryRetrievalStartedEvent,
+    MemorySaveCompletedEvent,
+    MemorySaveFailedEvent,
+    MemorySaveStartedEvent,
+)
+from .types.reasoning_events import (
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+    AgentReasoningStartedEvent,
+)
 from .types.task_events import (
     TaskCompletedEvent,
     TaskFailedEvent,
@@ -44,77 +66,53 @@ from .types.tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
-from .types.reasoning_events import (
-    AgentReasoningStartedEvent,
-    AgentReasoningCompletedEvent,
-    AgentReasoningFailedEvent,
-)
-from .types.knowledge_events import (
-    KnowledgeRetrievalStartedEvent,
-    KnowledgeRetrievalCompletedEvent,
-    KnowledgeQueryStartedEvent,
-    KnowledgeQueryCompletedEvent,
-    KnowledgeQueryFailedEvent,
-    KnowledgeSearchQueryFailedEvent,
-)
 
-from .types.memory_events import (
-    MemorySaveStartedEvent,
-    MemorySaveCompletedEvent,
-    MemorySaveFailedEvent,
-    MemoryQueryStartedEvent,
-    MemoryQueryCompletedEvent,
-    MemoryQueryFailedEvent,
-    MemoryRetrievalStartedEvent,
-    MemoryRetrievalCompletedEvent,
+EventTypes = (
+    CrewKickoffStartedEvent
+    | CrewKickoffCompletedEvent
+    | CrewKickoffFailedEvent
+    | CrewTestStartedEvent
+    | CrewTestCompletedEvent
+    | CrewTestFailedEvent
+    | CrewTrainStartedEvent
+    | CrewTrainCompletedEvent
+    | CrewTrainFailedEvent
+    | AgentExecutionStartedEvent
+    | AgentExecutionCompletedEvent
+    | LiteAgentExecutionCompletedEvent
+    | TaskStartedEvent
+    | TaskCompletedEvent
+    | TaskFailedEvent
+    | FlowStartedEvent
+    | FlowFinishedEvent
+    | MethodExecutionStartedEvent
+    | MethodExecutionFinishedEvent
+    | MethodExecutionFailedEvent
+    | AgentExecutionErrorEvent
+    | ToolUsageFinishedEvent
+    | ToolUsageErrorEvent
+    | ToolUsageStartedEvent
+    | LLMCallStartedEvent
+    | LLMCallCompletedEvent
+    | LLMCallFailedEvent
+    | LLMStreamChunkEvent
+    | LLMGuardrailStartedEvent
+    | LLMGuardrailCompletedEvent
+    | AgentReasoningStartedEvent
+    | AgentReasoningCompletedEvent
+    | AgentReasoningFailedEvent
+    | KnowledgeRetrievalStartedEvent
+    | KnowledgeRetrievalCompletedEvent
+    | KnowledgeQueryStartedEvent
+    | KnowledgeQueryCompletedEvent
+    | KnowledgeQueryFailedEvent
+    | KnowledgeSearchQueryFailedEvent
+    | MemorySaveStartedEvent
+    | MemorySaveCompletedEvent
+    | MemorySaveFailedEvent
+    | MemoryQueryStartedEvent
+    | MemoryQueryCompletedEvent
+    | MemoryQueryFailedEvent
+    | MemoryRetrievalStartedEvent
+    | MemoryRetrievalCompletedEvent
 )
-
-EventTypes = Union[
-    CrewKickoffStartedEvent,
-    CrewKickoffCompletedEvent,
-    CrewKickoffFailedEvent,
-    CrewTestStartedEvent,
-    CrewTestCompletedEvent,
-    CrewTestFailedEvent,
-    CrewTrainStartedEvent,
-    CrewTrainCompletedEvent,
-    CrewTrainFailedEvent,
-    AgentExecutionStartedEvent,
-    AgentExecutionCompletedEvent,
-    LiteAgentExecutionCompletedEvent,
-    TaskStartedEvent,
-    TaskCompletedEvent,
-    TaskFailedEvent,
-    FlowStartedEvent,
-    FlowFinishedEvent,
-    MethodExecutionStartedEvent,
-    MethodExecutionFinishedEvent,
-    MethodExecutionFailedEvent,
-    AgentExecutionErrorEvent,
-    ToolUsageFinishedEvent,
-    ToolUsageErrorEvent,
-    ToolUsageStartedEvent,
-    LLMCallStartedEvent,
-    LLMCallCompletedEvent,
-    LLMCallFailedEvent,
-    LLMStreamChunkEvent,
-    LLMGuardrailStartedEvent,
-    LLMGuardrailCompletedEvent,
-    AgentReasoningStartedEvent,
-    AgentReasoningCompletedEvent,
-    AgentReasoningFailedEvent,
-    KnowledgeRetrievalStartedEvent,
-    KnowledgeRetrievalCompletedEvent,
-    KnowledgeQueryStartedEvent,
-    KnowledgeQueryCompletedEvent,
-    KnowledgeQueryFailedEvent,
-    KnowledgeSearchQueryFailedEvent,
-    MemorySaveStartedEvent,
-    MemorySaveCompletedEvent,
-    MemorySaveFailedEvent,
-    MemoryQueryStartedEvent,
-    MemoryQueryCompletedEvent,
-    MemoryQueryFailedEvent,
-    MemoryRetrievalStartedEvent,
-    MemoryRetrievalCompletedEvent,
-]

src/crewai/events/listeners/__init__.py

@@ -2,4 +2,4 @@
 
 This module contains various event listener implementations
 for handling memory, tracing, and other event-driven functionality.
-"""
+"""

src/crewai/events/listeners/memory_listener.py

@@ -1,12 +1,12 @@
 from crewai.events.base_event_listener import BaseEventListener
 from crewai.events.types.memory_events import (
+    MemoryQueryCompletedEvent,
+    MemoryQueryFailedEvent,
     MemoryRetrievalCompletedEvent,
     MemoryRetrievalStartedEvent,
-    MemoryQueryFailedEvent,
-    MemoryQueryCompletedEvent,
-    MemorySaveStartedEvent,
     MemorySaveCompletedEvent,
     MemorySaveFailedEvent,
+    MemorySaveStartedEvent,
 )
 
 

src/crewai/events/listeners/tracing/first_time_trace_handler.py

@@ -0,0 +1,229 @@
+import logging
+import uuid
+import webbrowser
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+
+from crewai.events.listeners.tracing.trace_batch_manager import TraceBatchManager
+from crewai.events.listeners.tracing.utils import (
+    mark_first_execution_completed,
+    prompt_user_for_trace_viewing,
+    should_auto_collect_first_time_traces,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _update_or_create_env_file():
+    """Update or create .env file with CREWAI_TRACING_ENABLED=true."""
+    env_path = Path(".env")
+    env_content = ""
+    variable_name = "CREWAI_TRACING_ENABLED"
+    variable_value = "true"
+
+    # Read existing content if file exists
+    if env_path.exists():
+        with open(env_path, "r") as f:
+            env_content = f.read()
+
+    # Check if CREWAI_TRACING_ENABLED is already set
+    lines = env_content.splitlines()
+    variable_exists = False
+    updated_lines = []
+
+    for line in lines:
+        if line.strip().startswith(f"{variable_name}="):
+            # Update existing variable
+            updated_lines.append(f"{variable_name}={variable_value}")
+            variable_exists = True
+        else:
+            updated_lines.append(line)
+
+    # Add variable if it doesn't exist
+    if not variable_exists:
+        if updated_lines and not updated_lines[-1].strip():
+            # If last line is empty, replace it
+            updated_lines[-1] = f"{variable_name}={variable_value}"
+        else:
+            # Add new line and then the variable
+            updated_lines.append(f"{variable_name}={variable_value}")
+
+    # Write updated content
+    with open(env_path, "w") as f:
+        f.write("\n".join(updated_lines))
+        if updated_lines:  # Add final newline if there's content
+            f.write("\n")
+
+
+class FirstTimeTraceHandler:
+    """Handles the first-time user trace collection and display flow."""
+
+    def __init__(self):
+        self.is_first_time: bool = False
+        self.collected_events: bool = False
+        self.trace_batch_id: str | None = None
+        self.ephemeral_url: str | None = None
+        self.batch_manager: TraceBatchManager | None = None
+
+    def initialize_for_first_time_user(self) -> bool:
+        """Check if this is first time and initialize collection."""
+        self.is_first_time = should_auto_collect_first_time_traces()
+        return self.is_first_time
+
+    def set_batch_manager(self, batch_manager: TraceBatchManager):
+        """Set reference to batch manager for sending events."""
+        self.batch_manager = batch_manager
+
+    def mark_events_collected(self):
+        """Mark that events have been collected during execution."""
+        self.collected_events = True
+
+    def handle_execution_completion(self):
+        """Handle the completion flow as shown in your diagram."""
+        if not self.is_first_time or not self.collected_events:
+            return
+
+        try:
+            user_wants_traces = prompt_user_for_trace_viewing(timeout_seconds=20)
+
+            if user_wants_traces:
+                self._initialize_backend_and_send_events()
+
+                # Enable tracing for future runs by updating .env file
+                try:
+                    _update_or_create_env_file()
+                except Exception:  # noqa: S110
+                    pass
+
+                if self.ephemeral_url:
+                    self._display_ephemeral_trace_link()
+
+            mark_first_execution_completed()
+
+        except Exception as e:
+            self._gracefully_fail(f"Error in trace handling: {e}")
+            mark_first_execution_completed()
+
+    def _initialize_backend_and_send_events(self):
+        """Initialize backend batch and send collected events."""
+        if not self.batch_manager:
+            return
+
+        try:
+            if not self.batch_manager.backend_initialized:
+                original_metadata = (
+                    self.batch_manager.current_batch.execution_metadata
+                    if self.batch_manager.current_batch
+                    else {}
+                )
+
+                user_context = {
+                    "privacy_level": "standard",
+                    "user_id": "first_time_user",
+                    "session_id": str(uuid.uuid4()),
+                    "trace_id": self.batch_manager.trace_batch_id,
+                }
+
+                execution_metadata = {
+                    "execution_type": original_metadata.get("execution_type", "crew"),
+                    "crew_name": original_metadata.get(
+                        "crew_name", "First Time Execution"
+                    ),
+                    "flow_name": original_metadata.get("flow_name"),
+                    "agent_count": original_metadata.get("agent_count", 1),
+                    "task_count": original_metadata.get("task_count", 1),
+                    "crewai_version": original_metadata.get("crewai_version"),
+                }
+
+                self.batch_manager._initialize_backend_batch(
+                    user_context=user_context,
+                    execution_metadata=execution_metadata,
+                    use_ephemeral=True,
+                )
+                self.batch_manager.backend_initialized = True
+
+            if self.batch_manager.event_buffer:
+                self.batch_manager._send_events_to_backend()
+
+            self.batch_manager.finalize_batch()
+            self.ephemeral_url = self.batch_manager.ephemeral_trace_url
+
+            if not self.ephemeral_url:
+                self._show_local_trace_message()
+
+        except Exception as e:
+            self._gracefully_fail(f"Backend initialization failed: {e}")
+
+    def _display_ephemeral_trace_link(self):
+        """Display the ephemeral trace link to the user and automatically open browser."""
+        console = Console()
+
+        try:
+            webbrowser.open(self.ephemeral_url)
+        except Exception:  # noqa: S110
+            pass
+
+        panel_content = f"""
+🎉 Your First CrewAI Execution Trace is Ready!
+
+View your execution details here:
+{self.ephemeral_url}
+
+This trace shows:
+• Agent decisions and interactions
+• Task execution timeline
+• Tool usage and results
+• LLM calls and responses
+
+✅ Tracing has been enabled for future runs! (CREWAI_TRACING_ENABLED=true added to .env)
+You can also add tracing=True to your Crew(tracing=True) / Flow(tracing=True) for more control.
+
+📝 Note: This link will expire in 24 hours.
+        """.strip()
+
+        panel = Panel(
+            panel_content,
+            title="🔍 Execution Trace Generated",
+            border_style="bright_green",
+            padding=(1, 2),
+        )
+
+        console.print("\n")
+        console.print(panel)
+        console.print()
+
+    def _gracefully_fail(self, error_message: str):
+        """Handle errors gracefully without disrupting user experience."""
+        console = Console()
+        console.print(f"[yellow]Note: {error_message}[/yellow]")
+
+        logger.debug(f"First-time trace error: {error_message}")
+
+    def _show_local_trace_message(self):
+        """Show message when traces were collected locally but couldn't be uploaded."""
+        console = Console()
+
+        panel_content = f"""
+📊 Your execution traces were collected locally!
+
+Unfortunately, we couldn't upload them to the server right now, but here's what we captured:
+• {len(self.batch_manager.event_buffer)} trace events
+• Execution duration: {self.batch_manager.calculate_duration("execution")}ms
+• Batch ID: {self.batch_manager.trace_batch_id}
+
+Tracing has been enabled for future runs! (CREWAI_TRACING_ENABLED=true added to .env)
+The traces include agent decisions, task execution, and tool usage.
+    """.strip()
+
+        panel = Panel(
+            panel_content,
+            title="🔍 Local Traces Collected",
+            border_style="yellow",
+            padding=(1, 2),
+        )
+
+        console.print("\n")
+        console.print(panel)
+        console.print()

src/crewai/events/listeners/tracing/trace_batch_manager.py

@@ -1,18 +1,18 @@
 import uuid
-from datetime import datetime, timezone
-from typing import Dict, List, Any, Optional
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from logging import getLogger
+from typing import Any
 
-from crewai.utilities.constants import CREWAI_BASE_URL
-from crewai.cli.authentication.token import AuthError, get_auth_token
-
-from crewai.cli.version import get_crewai_version
-from crewai.cli.plus_api import PlusAPI
 from rich.console import Console
 from rich.panel import Panel
 
+from crewai.cli.authentication.token import AuthError, get_auth_token
+from crewai.cli.plus_api import PlusAPI
+from crewai.cli.version import get_crewai_version
 from crewai.events.listeners.tracing.types import TraceEvent
-from logging import getLogger
+from crewai.events.listeners.tracing.utils import should_auto_collect_first_time_traces
+from crewai.utilities.constants import CREWAI_BASE_URL
 
 logger = getLogger(__name__)
 
@@ -23,11 +23,11 @@ class TraceBatch:
 
     version: str = field(default_factory=get_crewai_version)
     batch_id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    user_context: Dict[str, str] = field(default_factory=dict)
-    execution_metadata: Dict[str, Any] = field(default_factory=dict)
-    events: List[TraceEvent] = field(default_factory=list)
+    user_context: dict[str, str] = field(default_factory=dict)
+    execution_metadata: dict[str, Any] = field(default_factory=dict)
+    events: list[TraceEvent] = field(default_factory=list)
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         return {
             "version": self.version,
             "batch_id": self.batch_id,
@@ -40,26 +40,28 @@ class TraceBatch:
 class TraceBatchManager:
     """Single responsibility: Manage batches and event buffering"""
 
-    is_current_batch_ephemeral: bool = False
-    trace_batch_id: Optional[str] = None
-    current_batch: Optional[TraceBatch] = None
-    event_buffer: List[TraceEvent] = []
-    execution_start_times: Dict[str, datetime] = {}
-    batch_owner_type: Optional[str] = None
-    batch_owner_id: Optional[str] = None
-
     def __init__(self):
+        self.is_current_batch_ephemeral: bool = False
+        self.trace_batch_id: str | None = None
+        self.current_batch: TraceBatch | None = None
+        self.event_buffer: list[TraceEvent] = []
+        self.execution_start_times: dict[str, datetime] = {}
+        self.batch_owner_type: str | None = None
+        self.batch_owner_id: str | None = None
+        self.backend_initialized: bool = False
+        self.ephemeral_trace_url: str | None = None
         try:
             self.plus_api = PlusAPI(
                 api_key=get_auth_token(),
             )
         except AuthError:
             self.plus_api = PlusAPI(api_key="")
+        self.ephemeral_trace_url = None
 
     def initialize_batch(
         self,
-        user_context: Dict[str, str],
-        execution_metadata: Dict[str, Any],
+        user_context: dict[str, str],
+        execution_metadata: dict[str, Any],
         use_ephemeral: bool = False,
     ) -> TraceBatch:
         """Initialize a new trace batch"""
@@ -70,14 +72,21 @@ class TraceBatchManager:
         self.is_current_batch_ephemeral = use_ephemeral
 
         self.record_start_time("execution")
-        self._initialize_backend_batch(user_context, execution_metadata, use_ephemeral)
+
+        if should_auto_collect_first_time_traces():
+            self.trace_batch_id = self.current_batch.batch_id
+        else:
+            self._initialize_backend_batch(
+                user_context, execution_metadata, use_ephemeral
+            )
+            self.backend_initialized = True
 
         return self.current_batch
 
     def _initialize_backend_batch(
         self,
-        user_context: Dict[str, str],
-        execution_metadata: Dict[str, Any],
+        user_context: dict[str, str],
+        execution_metadata: dict[str, Any],
         use_ephemeral: bool = False,
     ):
         """Send batch initialization to backend"""
@@ -129,13 +138,6 @@ class TraceBatchManager:
                     if not use_ephemeral
                     else response_data["ephemeral_trace_id"]
                 )
-                console = Console()
-                panel = Panel(
-                    f"✅ Trace batch initialized with session ID: {self.trace_batch_id}",
-                    title="Trace Batch Initialization",
-                    border_style="green",
-                )
-                console.print(panel)
             else:
                 logger.warning(
                     f"Trace batch initialization returned status {response.status_code}. Continuing without tracing."
@@ -143,7 +145,7 @@ class TraceBatchManager:
 
         except Exception as e:
             logger.warning(
-                f"Error initializing trace batch: {str(e)}. Continuing without tracing."
+                f"Error initializing trace batch: {e}. Continuing without tracing."
             )
 
     def add_event(self, trace_event: TraceEvent):
@@ -154,7 +156,6 @@ class TraceBatchManager:
         """Send buffered events to backend with graceful failure handling"""
         if not self.plus_api or not self.trace_batch_id or not self.event_buffer:
             return 500
-
         try:
             payload = {
                 "events": [event.to_dict() for event in self.event_buffer],
@@ -178,19 +179,19 @@ class TraceBatchManager:
             if response.status_code in [200, 201]:
                 self.event_buffer.clear()
                 return 200
-            else:
-                logger.warning(
-                    f"Failed to send events: {response.status_code}. Events will be lost."
-                )
-                return 500
 
-        except Exception as e:
             logger.warning(
-                f"Error sending events to backend: {str(e)}. Events will be lost."
+                f"Failed to send events: {response.status_code}. Events will be lost."
             )
             return 500
 
-    def finalize_batch(self) -> Optional[TraceBatch]:
+        except Exception as e:
+            logger.warning(
+                f"Error sending events to backend: {e}. Events will be lost."
+            )
+            return 500
+
+    def finalize_batch(self) -> TraceBatch | None:
         """Finalize batch and return it for sending"""
         if not self.current_batch:
             return None
@@ -199,6 +200,9 @@ class TraceBatchManager:
         if self.event_buffer:
             events_sent_to_backend_status = self._send_events_to_backend()
             if events_sent_to_backend_status == 500:
+                self.plus_api.mark_trace_batch_as_failed(
+                    self.trace_batch_id, "Error sending events to backend"
+                )
                 return None
         self._finalize_backend_batch()
 
@@ -246,21 +250,39 @@ class TraceBatchManager:
                     if not self.is_current_batch_ephemeral and access_code is None
                     else f"{CREWAI_BASE_URL}/crewai_plus/ephemeral_trace_batches/{self.trace_batch_id}?access_code={access_code}"
                 )
+
+                if self.is_current_batch_ephemeral:
+                    self.ephemeral_trace_url = return_link
+
+                # Create a properly formatted message with URL on its own line
+                message_parts = [
+                    f"✅ Trace batch finalized with session ID: {self.trace_batch_id}",
+                    "",
+                    f"🔗 View here: {return_link}",
+                ]
+
+                if access_code:
+                    message_parts.append(f"🔑 Access Code: {access_code}")
+
                 panel = Panel(
-                    f"✅ Trace batch finalized with session ID: {self.trace_batch_id}. View here: {return_link} {f', Access Code: {access_code}' if access_code else ''}",
+                    "\n".join(message_parts),
                     title="Trace Batch Finalization",
                     border_style="green",
                 )
-                console.print(panel)
+                if not should_auto_collect_first_time_traces():
+                    console.print(panel)
 
             else:
                 logger.error(
                     f"❌ Failed to finalize trace batch: {response.status_code} - {response.text}"
                 )
+                self.plus_api.mark_trace_batch_as_failed(
+                    self.trace_batch_id, response.text
+                )
 
         except Exception as e:
-            logger.error(f"❌ Error finalizing trace batch: {str(e)}")
-            # TODO: send error to app
+            logger.error(f"❌ Error finalizing trace batch: {e}")
+            self.plus_api.mark_trace_batch_as_failed(self.trace_batch_id, str(e))
 
     def _cleanup_batch_data(self):
         """Clean up batch data after successful finalization to free memory"""
@@ -277,7 +299,7 @@ class TraceBatchManager:
                 self.batch_sequence = 0
 
         except Exception as e:
-            logger.error(f"Warning: Error during cleanup: {str(e)}")
+            logger.error(f"Warning: Error during cleanup: {e}")
 
     def has_events(self) -> bool:
         """Check if there are events in the buffer"""
@@ -306,7 +328,7 @@ class TraceBatchManager:
             return duration_ms
         return 0
 
-    def get_trace_id(self) -> Optional[str]:
+    def get_trace_id(self) -> str | None:
         """Get current trace ID"""
         if self.current_batch:
             return self.current_batch.user_context.get("trace_id")

src/crewai/events/listeners/tracing/trace_listener.py

@@ -1,28 +1,59 @@
 import os
 import uuid
+from typing import Any, ClassVar
 
-from typing import Dict, Any, Optional
-
+from crewai.cli.authentication.token import AuthError, get_auth_token
+from crewai.cli.version import get_crewai_version
 from crewai.events.base_event_listener import BaseEventListener
-from crewai.events.types.agent_events import (
-    AgentExecutionCompletedEvent,
-    AgentExecutionStartedEvent,
-    LiteAgentExecutionStartedEvent,
-    LiteAgentExecutionCompletedEvent,
-    LiteAgentExecutionErrorEvent,
-    AgentExecutionErrorEvent,
+from crewai.events.listeners.tracing.first_time_trace_handler import (
+    FirstTimeTraceHandler,
 )
 from crewai.events.listeners.tracing.types import TraceEvent
-from crewai.events.types.reasoning_events import (
-    AgentReasoningStartedEvent,
-    AgentReasoningCompletedEvent,
-    AgentReasoningFailedEvent,
+from crewai.events.listeners.tracing.utils import safe_serialize_to_dict
+from crewai.events.types.agent_events import (
+    AgentExecutionCompletedEvent,
+    AgentExecutionErrorEvent,
+    AgentExecutionStartedEvent,
+    LiteAgentExecutionCompletedEvent,
+    LiteAgentExecutionErrorEvent,
+    LiteAgentExecutionStartedEvent,
 )
 from crewai.events.types.crew_events import (
     CrewKickoffCompletedEvent,
     CrewKickoffFailedEvent,
     CrewKickoffStartedEvent,
 )
+from crewai.events.types.flow_events import (
+    FlowCreatedEvent,
+    FlowFinishedEvent,
+    FlowPlotEvent,
+    FlowStartedEvent,
+    MethodExecutionFailedEvent,
+    MethodExecutionFinishedEvent,
+    MethodExecutionStartedEvent,
+)
+from crewai.events.types.llm_events import (
+    LLMCallCompletedEvent,
+    LLMCallFailedEvent,
+    LLMCallStartedEvent,
+)
+from crewai.events.types.llm_guardrail_events import (
+    LLMGuardrailCompletedEvent,
+    LLMGuardrailStartedEvent,
+)
+from crewai.events.types.memory_events import (
+    MemoryQueryCompletedEvent,
+    MemoryQueryFailedEvent,
+    MemoryQueryStartedEvent,
+    MemorySaveCompletedEvent,
+    MemorySaveFailedEvent,
+    MemorySaveStartedEvent,
+)
+from crewai.events.types.reasoning_events import (
+    AgentReasoningCompletedEvent,
+    AgentReasoningFailedEvent,
+    AgentReasoningStartedEvent,
+)
 from crewai.events.types.task_events import (
     TaskCompletedEvent,
     TaskFailedEvent,
@@ -33,49 +64,16 @@ from crewai.events.types.tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
-from crewai.events.types.llm_events import (
-    LLMCallCompletedEvent,
-    LLMCallFailedEvent,
-    LLMCallStartedEvent,
-)
-
-from crewai.events.types.flow_events import (
-    FlowCreatedEvent,
-    FlowStartedEvent,
-    FlowFinishedEvent,
-    MethodExecutionStartedEvent,
-    MethodExecutionFinishedEvent,
-    MethodExecutionFailedEvent,
-    FlowPlotEvent,
-)
-from crewai.events.types.llm_guardrail_events import (
-    LLMGuardrailStartedEvent,
-    LLMGuardrailCompletedEvent,
-)
-from crewai.utilities.serialization import to_serializable
-
 
 from .trace_batch_manager import TraceBatchManager
 
-from crewai.events.types.memory_events import (
-    MemoryQueryStartedEvent,
-    MemoryQueryCompletedEvent,
-    MemoryQueryFailedEvent,
-    MemorySaveStartedEvent,
-    MemorySaveCompletedEvent,
-    MemorySaveFailedEvent,
-)
-
-from crewai.cli.authentication.token import AuthError, get_auth_token
-from crewai.cli.version import get_crewai_version
-
 
 class TraceCollectionListener(BaseEventListener):
     """
     Trace collection listener that orchestrates trace collection
     """
 
-    complex_events = [
+    complex_events: ClassVar[list[str]] = [
         "task_started",
         "task_completed",
         "llm_call_started",
@@ -88,14 +86,14 @@ class TraceCollectionListener(BaseEventListener):
     _initialized = False
     _listeners_setup = False
 
-    def __new__(cls, batch_manager=None):
+    def __new__(cls, batch_manager: TraceBatchManager | None = None):
         if cls._instance is None:
             cls._instance = super().__new__(cls)
         return cls._instance
 
     def __init__(
         self,
-        batch_manager: Optional[TraceBatchManager] = None,
+        batch_manager: TraceBatchManager | None = None,
     ):
         if self._initialized:
             return
@@ -103,16 +101,19 @@ class TraceCollectionListener(BaseEventListener):
         super().__init__()
         self.batch_manager = batch_manager or TraceBatchManager()
         self._initialized = True
+        self.first_time_handler = FirstTimeTraceHandler()
+
+        if self.first_time_handler.initialize_for_first_time_user():
+            self.first_time_handler.set_batch_manager(self.batch_manager)
 
     def _check_authenticated(self) -> bool:
         """Check if tracing should be enabled"""
         try:
-            res = bool(get_auth_token())
-            return res
+            return bool(get_auth_token())
         except AuthError:
             return False
 
-    def _get_user_context(self) -> Dict[str, str]:
+    def _get_user_context(self) -> dict[str, str]:
         """Extract user context for tracing"""
         return {
             "user_id": os.getenv("CREWAI_USER_ID", "anonymous"),
@@ -161,8 +162,14 @@ class TraceCollectionListener(BaseEventListener):
         @event_bus.on(FlowFinishedEvent)
         def on_flow_finished(source, event):
             self._handle_trace_event("flow_finished", source, event)
+
             if self.batch_manager.batch_owner_type == "flow":
-                self.batch_manager.finalize_batch()
+                if self.first_time_handler.is_first_time:
+                    self.first_time_handler.mark_events_collected()
+                    self.first_time_handler.handle_execution_completion()
+                else:
+                    # Normal flow finalization
+                    self.batch_manager.finalize_batch()
 
         @event_bus.on(FlowPlotEvent)
         def on_flow_plot(source, event):
@@ -181,12 +188,20 @@ class TraceCollectionListener(BaseEventListener):
         def on_crew_completed(source, event):
             self._handle_trace_event("crew_kickoff_completed", source, event)
             if self.batch_manager.batch_owner_type == "crew":
-                self.batch_manager.finalize_batch()
+                if self.first_time_handler.is_first_time:
+                    self.first_time_handler.mark_events_collected()
+                    self.first_time_handler.handle_execution_completion()
+                else:
+                    self.batch_manager.finalize_batch()
 
         @event_bus.on(CrewKickoffFailedEvent)
         def on_crew_failed(source, event):
             self._handle_trace_event("crew_kickoff_failed", source, event)
-            self.batch_manager.finalize_batch()
+            if self.first_time_handler.is_first_time:
+                self.first_time_handler.mark_events_collected()
+                self.first_time_handler.handle_execution_completion()
+            else:
+                self.batch_manager.finalize_batch()
 
         @event_bus.on(TaskStartedEvent)
         def on_task_started(source, event):
@@ -325,17 +340,19 @@ class TraceCollectionListener(BaseEventListener):
         self._initialize_batch(user_context, execution_metadata)
 
     def _initialize_batch(
-        self, user_context: Dict[str, str], execution_metadata: Dict[str, Any]
+        self, user_context: dict[str, str], execution_metadata: dict[str, Any]
     ):
-        """Initialize trace batch if ephemeral"""
-        if not self._check_authenticated():
-            self.batch_manager.initialize_batch(
+        """Initialize trace batch - auto-enable ephemeral for first-time users."""
+
+        if self.first_time_handler.is_first_time:
+            return self.batch_manager.initialize_batch(
                 user_context, execution_metadata, use_ephemeral=True
             )
-        else:
-            self.batch_manager.initialize_batch(
-                user_context, execution_metadata, use_ephemeral=False
-            )
+
+        use_ephemeral = not self._check_authenticated()
+        return self.batch_manager.initialize_batch(
+            user_context, execution_metadata, use_ephemeral=use_ephemeral
+        )
 
     def _handle_trace_event(self, event_type: str, source: Any, event: Any):
         """Generic handler for context end events"""
@@ -371,11 +388,11 @@ class TraceCollectionListener(BaseEventListener):
 
     def _build_event_data(
         self, event_type: str, event: Any, source: Any
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Build event data"""
         if event_type not in self.complex_events:
-            return self._safe_serialize_to_dict(event)
-        elif event_type == "task_started":
+            return safe_serialize_to_dict(event)
+        if event_type == "task_started":
             return {
                 "task_description": event.task.description,
                 "expected_output": event.task.expected_output,
@@ -384,7 +401,7 @@ class TraceCollectionListener(BaseEventListener):
                 "agent_role": source.agent.role,
                 "task_id": str(event.task.id),
             }
-        elif event_type == "task_completed":
+        if event_type == "task_completed":
             return {
                 "task_description": event.task.description if event.task else None,
                 "task_name": event.task.name or event.task.description
@@ -397,63 +414,31 @@ class TraceCollectionListener(BaseEventListener):
                 else None,
                 "agent_role": event.output.agent if event.output else None,
             }
-        elif event_type == "agent_execution_started":
+        if event_type == "agent_execution_started":
             return {
                 "agent_role": event.agent.role,
                 "agent_goal": event.agent.goal,
                 "agent_backstory": event.agent.backstory,
             }
-        elif event_type == "agent_execution_completed":
+        if event_type == "agent_execution_completed":
             return {
                 "agent_role": event.agent.role,
                 "agent_goal": event.agent.goal,
                 "agent_backstory": event.agent.backstory,
             }
-        elif event_type == "llm_call_started":
-            event_data = self._safe_serialize_to_dict(event)
+        if event_type == "llm_call_started":
+            event_data = safe_serialize_to_dict(event)
             event_data["task_name"] = (
                 event.task_name or event.task_description
                 if hasattr(event, "task_name") and event.task_name
                 else None
             )
             return event_data
-        elif event_type == "llm_call_completed":
-            return self._safe_serialize_to_dict(event)
-        else:
-            return {
-                "event_type": event_type,
-                "event": self._safe_serialize_to_dict(event),
-                "source": source,
-            }
+        if event_type == "llm_call_completed":
+            return safe_serialize_to_dict(event)
 
-    # TODO: move to utils
-    def _safe_serialize_to_dict(
-        self, obj, exclude: set[str] | None = None
-    ) -> Dict[str, Any]:
-        """Safely serialize an object to a dictionary for event data."""
-        try:
-            serialized = to_serializable(obj, exclude)
-            if isinstance(serialized, dict):
-                return serialized
-            else:
-                return {"serialized_data": serialized}
-        except Exception as e:
-            return {"serialization_error": str(e), "object_type": type(obj).__name__}
-
-    # TODO: move to utils
-    def _truncate_messages(self, messages, max_content_length=500, max_messages=5):
-        """Truncate message content and limit number of messages"""
-        if not messages or not isinstance(messages, list):
-            return messages
-
-        # Limit number of messages
-        limited_messages = messages[:max_messages]
-
-        # Truncate each message content
-        for msg in limited_messages:
-            if isinstance(msg, dict) and "content" in msg:
-                content = msg["content"]
-                if len(content) > max_content_length:
-                    msg["content"] = content[:max_content_length] + "..."
-
-        return limited_messages
+        return {
+            "event_type": event_type,
+            "event": safe_serialize_to_dict(event),
+            "source": source,
+        }

src/crewai/events/listeners/tracing/types.py

@@ -1,7 +1,7 @@
-from dataclasses import dataclass, field, asdict
-from datetime import datetime, timezone
-from typing import Dict, Any
 import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
 
 
 @dataclass
@@ -13,7 +13,7 @@ class TraceEvent:
         default_factory=lambda: datetime.now(timezone.utc).isoformat()
     )
     type: str = ""
-    event_data: Dict[str, Any] = field(default_factory=dict)
+    event_data: dict[str, Any] = field(default_factory=dict)
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         return asdict(self)

src/crewai/events/listeners/tracing/utils.py

@@ -1,17 +1,25 @@
+import getpass
+import hashlib
+import json
+import logging
 import os
 import platform
-import uuid
-import hashlib
-import subprocess
-import getpass
-from pathlib import Path
-from datetime import datetime
 import re
-import json
+import subprocess
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
 
 import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
 
 from crewai.utilities.paths import db_storage_path
+from crewai.utilities.serialization import to_serializable
+
+logger = logging.getLogger(__name__)
 
 
 def is_tracing_enabled() -> bool:
@@ -43,49 +51,167 @@ def _get_machine_id() -> str:
 
     try:
         mac = ":".join(
-            ["{:02x}".format((uuid.getnode() >> b) & 0xFF) for b in range(0, 12, 2)][
-                ::-1
-            ]
+            [f"{(uuid.getnode() >> b) & 0xFF:02x}" for b in range(0, 12, 2)][::-1]
         )
         parts.append(mac)
-    except Exception:
+    except Exception:  # noqa: S110
         pass
 
-    sysname = platform.system()
-    parts.append(sysname)
+    try:
+        sysname = platform.system()
+        parts.append(sysname)
+    except Exception:
+        sysname = "unknown"
+        parts.append(sysname)
 
     try:
         if sysname == "Darwin":
-            res = subprocess.run(
-                ["system_profiler", "SPHardwareDataType"],
-                capture_output=True,
-                text=True,
-                timeout=2,
-            )
-            m = re.search(r"Hardware UUID:\s*([A-Fa-f0-9\-]+)", res.stdout)
-            if m:
-                parts.append(m.group(1))
-        elif sysname == "Linux":
             try:
-                parts.append(Path("/etc/machine-id").read_text().strip())
-            except Exception:
-                parts.append(Path("/sys/class/dmi/id/product_uuid").read_text().strip())
+                res = subprocess.run(
+                    ["/usr/sbin/system_profiler", "SPHardwareDataType"],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                )
+                m = re.search(r"Hardware UUID:\s*([A-Fa-f0-9\-]+)", res.stdout)
+                if m:
+                    parts.append(m.group(1))
+            except Exception:  # noqa: S110
+                pass
+
+        elif sysname == "Linux":
+            linux_id = _get_linux_machine_id()
+            if linux_id:
+                parts.append(linux_id)
+
         elif sysname == "Windows":
-            res = subprocess.run(
-                ["wmic", "csproduct", "get", "UUID"],
-                capture_output=True,
-                text=True,
-                timeout=2,
-            )
-            lines = [line.strip() for line in res.stdout.splitlines() if line.strip()]
-            if len(lines) >= 2:
-                parts.append(lines[1])
-    except Exception:
+            try:
+                res = subprocess.run(
+                    [
+                        "C:\\Windows\\System32\\wbem\\wmic.exe",
+                        "csproduct",
+                        "get",
+                        "UUID",
+                    ],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                )
+                lines = [
+                    line.strip() for line in res.stdout.splitlines() if line.strip()
+                ]
+                if len(lines) >= 2:
+                    parts.append(lines[1])
+            except Exception:  # noqa: S110
+                pass
+        else:
+            generic_id = _get_generic_system_id()
+            if generic_id:
+                parts.append(generic_id)
+
+    except Exception:  # noqa: S110
         pass
 
+    if len(parts) <= 1:
+        try:
+            import socket
+
+            parts.append(socket.gethostname())
+        except Exception:  # noqa: S110
+            pass
+
+        try:
+            parts.append(getpass.getuser())
+        except Exception:  # noqa: S110
+            pass
+
+        try:
+            parts.append(platform.machine())
+            parts.append(platform.processor())
+        except Exception:  # noqa: S110
+            pass
+
+    if not parts:
+        parts.append("unknown-system")
+        parts.append(str(uuid.uuid4()))
+
     return hashlib.sha256("".join(parts).encode()).hexdigest()
 
 
+def _get_linux_machine_id() -> str | None:
+    linux_id_sources = [
+        "/etc/machine-id",
+        "/sys/class/dmi/id/product_uuid",
+        "/proc/sys/kernel/random/boot_id",
+        "/sys/class/dmi/id/board_serial",
+        "/sys/class/dmi/id/chassis_serial",
+    ]
+
+    for source in linux_id_sources:
+        try:
+            path = Path(source)
+            if path.exists() and path.is_file():
+                content = path.read_text().strip()
+                if content and content.lower() not in [
+                    "unknown",
+                    "to be filled by o.e.m.",
+                    "",
+                ]:
+                    return content
+        except Exception:  # noqa: S112, PERF203
+            continue
+
+    try:
+        import socket
+
+        hostname = socket.gethostname()
+        arch = platform.machine()
+        if hostname and arch:
+            return f"{hostname}-{arch}"
+    except Exception:  # noqa: S110
+        pass
+
+    return None
+
+
+def _get_generic_system_id() -> str | None:
+    try:
+        parts = []
+
+        try:
+            import socket
+
+            hostname = socket.gethostname()
+            if hostname:
+                parts.append(hostname)
+        except Exception:  # noqa: S110
+            pass
+
+        try:
+            parts.append(platform.machine())
+            parts.append(platform.processor())
+            parts.append(platform.architecture()[0])
+        except Exception:  # noqa: S110
+            pass
+
+        try:
+            container_id = os.environ.get(
+                "HOSTNAME", os.environ.get("CONTAINER_ID", "")
+            )
+            if container_id:
+                parts.append(container_id)
+        except Exception:  # noqa: S110
+            pass
+
+        if parts:
+            return "-".join(filter(None, parts))
+
+    except Exception:  # noqa: S110
+        pass
+
+    return None
+
+
 def _user_data_file() -> Path:
     base = Path(db_storage_path())
     base.mkdir(parents=True, exist_ok=True)
@@ -97,8 +223,8 @@ def _load_user_data() -> dict:
     if p.exists():
         try:
             return json.loads(p.read_text())
-        except Exception:
-            pass
+        except (json.JSONDecodeError, OSError, PermissionError) as e:
+            logger.warning(f"Failed to load user data: {e}")
     return {}
 
 
@@ -106,8 +232,8 @@ def _save_user_data(data: dict) -> None:
     try:
         p = _user_data_file()
         p.write_text(json.dumps(data, indent=2))
-    except Exception:
-        pass
+    except (OSError, PermissionError) as e:
+        logger.warning(f"Failed to save user data: {e}")
 
 
 def get_user_id() -> str:
@@ -151,3 +277,103 @@ def mark_first_execution_done() -> None:
         }
     )
     _save_user_data(data)
+
+
+def safe_serialize_to_dict(obj, exclude: set[str] | None = None) -> dict[str, Any]:
+    """Safely serialize an object to a dictionary for event data."""
+    try:
+        serialized = to_serializable(obj, exclude)
+        if isinstance(serialized, dict):
+            return serialized
+        return {"serialized_data": serialized}
+    except Exception as e:
+        return {"serialization_error": str(e), "object_type": type(obj).__name__}
+
+
+def truncate_messages(messages, max_content_length=500, max_messages=5):
+    """Truncate message content and limit number of messages"""
+    if not messages or not isinstance(messages, list):
+        return messages
+
+    limited_messages = messages[:max_messages]
+
+    for msg in limited_messages:
+        if isinstance(msg, dict) and "content" in msg:
+            content = msg["content"]
+            if len(content) > max_content_length:
+                msg["content"] = content[:max_content_length] + "..."
+
+    return limited_messages
+
+
+def should_auto_collect_first_time_traces() -> bool:
+    """True if we should auto-collect traces for first-time user."""
+    if _is_test_environment():
+        return False
+    return is_first_execution()
+
+
+def prompt_user_for_trace_viewing(timeout_seconds: int = 20) -> bool:
+    """
+    Prompt user if they want to see their traces with timeout.
+    Returns True if user wants to see traces, False otherwise.
+    """
+    if _is_test_environment():
+        return False
+
+    try:
+        import threading
+
+        console = Console()
+
+        content = Text()
+        content.append("🔍 ", style="cyan bold")
+        content.append(
+            "Detailed execution traces are available!\n\n", style="cyan bold"
+        )
+        content.append("View insights including:\n", style="white")
+        content.append("  • Agent decision-making process\n", style="bright_blue")
+        content.append("  • Task execution flow and timing\n", style="bright_blue")
+        content.append("  • Tool usage details", style="bright_blue")
+
+        panel = Panel(
+            content,
+            title="[bold cyan]Execution Traces[/bold cyan]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+        console.print("\n")
+        console.print(panel)
+
+        prompt_text = click.style(
+            f"Would you like to view your execution traces? [y/N] ({timeout_seconds}s timeout): ",
+            fg="white",
+            bold=True,
+        )
+        click.echo(prompt_text, nl=False)
+
+        result = [False]
+
+        def get_input():
+            try:
+                response = input().strip().lower()
+                result[0] = response in ["y", "yes"]
+            except (EOFError, KeyboardInterrupt):
+                result[0] = False
+
+        input_thread = threading.Thread(target=get_input, daemon=True)
+        input_thread.start()
+        input_thread.join(timeout=timeout_seconds)
+
+        if input_thread.is_alive():
+            return False
+
+        return result[0]
+
+    except Exception:
+        return False
+
+
+def mark_first_execution_completed() -> None:
+    """Mark first execution as completed (called after trace prompt)."""
+    mark_first_execution_done()

src/crewai/events/types/__init__.py

@@ -2,4 +2,4 @@
 
 This module contains all event types used throughout the CrewAI system
 for monitoring and extending agent, crew, task, and tool execution.
-"""
+"""

src/crewai/events/types/agent_events.py

@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional, Sequence, Union
+from collections.abc import Sequence
+from typing import Any
 
-from pydantic import model_validator
+from pydantic import ConfigDict, model_validator
 
 from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.events.base_events import BaseEvent
 from crewai.tools.base_tool import BaseTool
 from crewai.tools.structured_tool import CrewStructuredTool
-from crewai.events.base_events import BaseEvent
 
 
 class AgentExecutionStartedEvent(BaseEvent):
@@ -17,11 +18,11 @@ class AgentExecutionStartedEvent(BaseEvent):
 
     agent: BaseAgent
     task: Any
-    tools: Optional[Sequence[Union[BaseTool, CrewStructuredTool]]]
+    tools: Sequence[BaseTool | CrewStructuredTool] | None
     task_prompt: str
     type: str = "agent_execution_started"
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
     @model_validator(mode="after")
     def set_fingerprint_data(self):
@@ -45,7 +46,7 @@ class AgentExecutionCompletedEvent(BaseEvent):
     output: str
     type: str = "agent_execution_completed"
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
     @model_validator(mode="after")
     def set_fingerprint_data(self):
@@ -69,7 +70,7 @@ class AgentExecutionErrorEvent(BaseEvent):
     error: str
     type: str = "agent_execution_error"
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
     @model_validator(mode="after")
     def set_fingerprint_data(self):
@@ -89,18 +90,18 @@ class AgentExecutionErrorEvent(BaseEvent):
 class LiteAgentExecutionStartedEvent(BaseEvent):
     """Event emitted when a LiteAgent starts executing"""
 
-    agent_info: Dict[str, Any]
-    tools: Optional[Sequence[Union[BaseTool, CrewStructuredTool]]]
-    messages: Union[str, List[Dict[str, str]]]
+    agent_info: dict[str, Any]
+    tools: Sequence[BaseTool | CrewStructuredTool] | None
+    messages: str | list[dict[str, str]]
     type: str = "lite_agent_execution_started"
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
 
 class LiteAgentExecutionCompletedEvent(BaseEvent):
     """Event emitted when a LiteAgent completes execution"""
 
-    agent_info: Dict[str, Any]
+    agent_info: dict[str, Any]
     output: str
     type: str = "lite_agent_execution_completed"
 
@@ -108,7 +109,7 @@ class LiteAgentExecutionCompletedEvent(BaseEvent):
 class LiteAgentExecutionErrorEvent(BaseEvent):
     """Event emitted when a LiteAgent encounters an error during execution"""
 
-    agent_info: Dict[str, Any]
+    agent_info: dict[str, Any]
     error: str
     type: str = "lite_agent_execution_error"
 

src/crewai/events/types/crew_events.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Any, Dict, Optional, Union
+from typing import TYPE_CHECKING, Any
 
 from crewai.events.base_events import BaseEvent
 
@@ -11,8 +11,8 @@ else:
 class CrewBaseEvent(BaseEvent):
     """Base class for crew events with fingerprint handling"""
 
-    crew_name: Optional[str]
-    crew: Optional[Crew] = None
+    crew_name: str | None
+    crew: Crew | None = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -38,7 +38,7 @@ class CrewBaseEvent(BaseEvent):
 class CrewKickoffStartedEvent(CrewBaseEvent):
     """Event emitted when a crew starts execution"""
 
-    inputs: Optional[Dict[str, Any]]
+    inputs: dict[str, Any] | None
     type: str = "crew_kickoff_started"
 
 
@@ -62,7 +62,7 @@ class CrewTrainStartedEvent(CrewBaseEvent):
 
     n_iterations: int
     filename: str
-    inputs: Optional[Dict[str, Any]]
+    inputs: dict[str, Any] | None
     type: str = "crew_train_started"
 
 
@@ -85,8 +85,8 @@ class CrewTestStartedEvent(CrewBaseEvent):
     """Event emitted when a crew starts testing"""
 
     n_iterations: int
-    eval_llm: Optional[Union[str, Any]]
-    inputs: Optional[Dict[str, Any]]
+    eval_llm: str | Any | None
+    inputs: dict[str, Any] | None
     type: str = "crew_test_started"
 
 

src/crewai/events/types/flow_events.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Optional, Union
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict
 
@@ -16,7 +16,7 @@ class FlowStartedEvent(FlowEvent):
     """Event emitted when a flow starts execution"""
 
     flow_name: str
-    inputs: Optional[Dict[str, Any]] = None
+    inputs: dict[str, Any] | None = None
     type: str = "flow_started"
 
 
@@ -32,8 +32,8 @@ class MethodExecutionStartedEvent(FlowEvent):
 
     flow_name: str
     method_name: str
-    state: Union[Dict[str, Any], BaseModel]
-    params: Optional[Dict[str, Any]] = None
+    state: dict[str, Any] | BaseModel
+    params: dict[str, Any] | None = None
     type: str = "method_execution_started"
 
 
@@ -43,7 +43,7 @@ class MethodExecutionFinishedEvent(FlowEvent):
     flow_name: str
     method_name: str
     result: Any = None
-    state: Union[Dict[str, Any], BaseModel]
+    state: dict[str, Any] | BaseModel
     type: str = "method_execution_finished"
 
 
@@ -62,7 +62,7 @@ class FlowFinishedEvent(FlowEvent):
     """Event emitted when a flow completes execution"""
 
     flow_name: str
-    result: Optional[Any] = None
+    result: Any | None = None
     type: str = "flow_finished"
 
 

src/crewai/events/types/knowledge_events.py

@@ -1,6 +1,5 @@
-from crewai.events.base_events import BaseEvent
-
 from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.events.base_events import BaseEvent
 
 
 class KnowledgeRetrievalStartedEvent(BaseEvent):

src/crewai/events/types/llm_events.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any
 
 from pydantic import BaseModel
 
@@ -7,14 +7,14 @@ from crewai.events.base_events import BaseEvent
 
 
 class LLMEventBase(BaseEvent):
-    task_name: Optional[str] = None
-    task_id: Optional[str] = None
+    task_name: str | None = None
+    task_id: str | None = None
 
-    agent_id: Optional[str] = None
-    agent_role: Optional[str] = None
+    agent_id: str | None = None
+    agent_role: str | None = None
 
-    from_task: Optional[Any] = None
-    from_agent: Optional[Any] = None
+    from_task: Any | None = None
+    from_agent: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -38,11 +38,11 @@ class LLMCallStartedEvent(LLMEventBase):
     """
 
     type: str = "llm_call_started"
-    model: Optional[str] = None
-    messages: Optional[Union[str, List[Dict[str, Any]]]] = None
-    tools: Optional[List[dict[str, Any]]] = None
-    callbacks: Optional[List[Any]] = None
-    available_functions: Optional[Dict[str, Any]] = None
+    model: str | None = None
+    messages: str | list[dict[str, Any]] | None = None
+    tools: list[dict[str, Any]] | None = None
+    callbacks: list[Any] | None = None
+    available_functions: dict[str, Any] | None = None
 
 
 class LLMCallCompletedEvent(LLMEventBase):
@@ -52,7 +52,7 @@ class LLMCallCompletedEvent(LLMEventBase):
     messages: str | list[dict[str, Any]] | None = None
     response: Any
     call_type: LLMCallType
-    model: Optional[str] = None
+    model: str | None = None
 
 
 class LLMCallFailedEvent(LLMEventBase):
@@ -64,13 +64,13 @@ class LLMCallFailedEvent(LLMEventBase):
 
 class FunctionCall(BaseModel):
     arguments: str
-    name: Optional[str] = None
+    name: str | None = None
 
 
 class ToolCall(BaseModel):
-    id: Optional[str] = None
+    id: str | None = None
     function: FunctionCall
-    type: Optional[str] = None
+    type: str | None = None
     index: int
 
 
@@ -79,4 +79,4 @@ class LLMStreamChunkEvent(LLMEventBase):
 
     type: str = "llm_stream_chunk"
     chunk: str
-    tool_call: Optional[ToolCall] = None
+    tool_call: ToolCall | None = None

src/crewai/events/types/llm_guardrail_events.py

@@ -1,5 +1,6 @@
+from collections.abc import Callable
 from inspect import getsource
-from typing import Any, Callable, Optional, Union
+from typing import Any
 
 from crewai.events.base_events import BaseEvent
 
@@ -13,12 +14,12 @@ class LLMGuardrailStartedEvent(BaseEvent):
     """
 
     type: str = "llm_guardrail_started"
-    guardrail: Union[str, Callable]
+    guardrail: str | Callable
     retry_count: int
 
     def __init__(self, **data):
-        from crewai.tasks.llm_guardrail import LLMGuardrail
         from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
+        from crewai.tasks.llm_guardrail import LLMGuardrail
 
         super().__init__(**data)
 
@@ -41,5 +42,5 @@ class LLMGuardrailCompletedEvent(BaseEvent):
     type: str = "llm_guardrail_completed"
     success: bool
     result: Any
-    error: Optional[str] = None
+    error: str | None = None
     retry_count: int

src/crewai/events/types/logging_events.py

@@ -1,6 +1,8 @@
 """Agent logging events that don't reference BaseAgent to avoid circular imports."""
 
-from typing import Any, Optional
+from typing import Any
+
+from pydantic import ConfigDict
 
 from crewai.events.base_events import BaseEvent
 
@@ -9,7 +11,7 @@ class AgentLogsStartedEvent(BaseEvent):
     """Event emitted when agent logs should be shown at start"""
 
     agent_role: str
-    task_description: Optional[str] = None
+    task_description: str | None = None
     verbose: bool = False
     type: str = "agent_logs_started"
 
@@ -22,4 +24,4 @@ class AgentLogsExecutionEvent(BaseEvent):
     verbose: bool = False
     type: str = "agent_logs_execution"
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)

src/crewai/events/types/memory_events.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Optional
+from typing import Any
 
 from crewai.events.base_events import BaseEvent
 
@@ -7,12 +7,12 @@ class MemoryBaseEvent(BaseEvent):
     """Base event for memory operations"""
 
     type: str
-    task_id: Optional[str] = None
-    task_name: Optional[str] = None
-    from_task: Optional[Any] = None
-    from_agent: Optional[Any] = None
-    agent_role: Optional[str] = None
-    agent_id: Optional[str] = None
+    task_id: str | None = None
+    task_name: str | None = None
+    from_task: Any | None = None
+    from_agent: Any | None = None
+    agent_role: str | None = None
+    agent_id: str | None = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -26,7 +26,7 @@ class MemoryQueryStartedEvent(MemoryBaseEvent):
     type: str = "memory_query_started"
     query: str
     limit: int
-    score_threshold: Optional[float] = None
+    score_threshold: float | None = None
 
 
 class MemoryQueryCompletedEvent(MemoryBaseEvent):
@@ -36,7 +36,7 @@ class MemoryQueryCompletedEvent(MemoryBaseEvent):
     query: str
     results: Any
     limit: int
-    score_threshold: Optional[float] = None
+    score_threshold: float | None = None
     query_time_ms: float
 
 
@@ -46,7 +46,7 @@ class MemoryQueryFailedEvent(MemoryBaseEvent):
     type: str = "memory_query_failed"
     query: str
     limit: int
-    score_threshold: Optional[float] = None
+    score_threshold: float | None = None
     error: str
 
 
@@ -54,9 +54,9 @@ class MemorySaveStartedEvent(MemoryBaseEvent):
     """Event emitted when a memory save operation is started"""
 
     type: str = "memory_save_started"
-    value: Optional[str] = None
-    metadata: Optional[Dict[str, Any]] = None
-    agent_role: Optional[str] = None
+    value: str | None = None
+    metadata: dict[str, Any] | None = None
+    agent_role: str | None = None
 
 
 class MemorySaveCompletedEvent(MemoryBaseEvent):
@@ -64,8 +64,8 @@ class MemorySaveCompletedEvent(MemoryBaseEvent):
 
     type: str = "memory_save_completed"
     value: str
-    metadata: Optional[Dict[str, Any]] = None
-    agent_role: Optional[str] = None
+    metadata: dict[str, Any] | None = None
+    agent_role: str | None = None
     save_time_ms: float
 
 
@@ -73,9 +73,9 @@ class MemorySaveFailedEvent(MemoryBaseEvent):
     """Event emitted when a memory save operation fails"""
 
     type: str = "memory_save_failed"
-    value: Optional[str] = None
-    metadata: Optional[Dict[str, Any]] = None
-    agent_role: Optional[str] = None
+    value: str | None = None
+    metadata: dict[str, Any] | None = None
+    agent_role: str | None = None
     error: str
 
 
@@ -83,13 +83,13 @@ class MemoryRetrievalStartedEvent(MemoryBaseEvent):
     """Event emitted when memory retrieval for a task prompt starts"""
 
     type: str = "memory_retrieval_started"
-    task_id: Optional[str] = None
+    task_id: str | None = None
 
 
 class MemoryRetrievalCompletedEvent(MemoryBaseEvent):
     """Event emitted when memory retrieval for a task prompt completes successfully"""
 
     type: str = "memory_retrieval_completed"
-    task_id: Optional[str] = None
+    task_id: str | None = None
     memory_content: str
     retrieval_time_ms: float

src/crewai/events/types/reasoning_events.py

@@ -1,5 +1,6 @@
+from typing import Any
+
 from crewai.events.base_events import BaseEvent
-from typing import Any, Optional
 
 
 class ReasoningEvent(BaseEvent):
@@ -9,10 +10,10 @@ class ReasoningEvent(BaseEvent):
     attempt: int = 1
     agent_role: str
     task_id: str
-    task_name: Optional[str] = None
-    from_task: Optional[Any] = None
-    agent_id: Optional[str] = None
-    from_agent: Optional[Any] = None
+    task_name: str | None = None
+    from_task: Any | None = None
+    agent_id: str | None = None
+    from_agent: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)

src/crewai/events/types/task_events.py

@@ -1,15 +1,15 @@
-from typing import Any, Optional
+from typing import Any
 
-from crewai.tasks.task_output import TaskOutput
 from crewai.events.base_events import BaseEvent
+from crewai.tasks.task_output import TaskOutput
 
 
 class TaskStartedEvent(BaseEvent):
     """Event emitted when a task starts"""
 
     type: str = "task_started"
-    context: Optional[str]
-    task: Optional[Any] = None
+    context: str | None
+    task: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -29,7 +29,7 @@ class TaskCompletedEvent(BaseEvent):
 
     output: TaskOutput
     type: str = "task_completed"
-    task: Optional[Any] = None
+    task: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -49,7 +49,7 @@ class TaskFailedEvent(BaseEvent):
 
     error: str
     type: str = "task_failed"
-    task: Optional[Any] = None
+    task: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -69,7 +69,7 @@ class TaskEvaluationEvent(BaseEvent):
 
     type: str = "task_evaluation"
     evaluation_type: str
-    task: Optional[Any] = None
+    task: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)

src/crewai/events/types/tool_usage_events.py

@@ -1,5 +1,8 @@
+from collections.abc import Callable
 from datetime import datetime
-from typing import Any, Callable, Dict, Optional
+from typing import Any
+
+from pydantic import ConfigDict
 
 from crewai.events.base_events import BaseEvent
 
@@ -7,21 +10,21 @@ from crewai.events.base_events import BaseEvent
 class ToolUsageEvent(BaseEvent):
     """Base event for tool usage tracking"""
 
-    agent_key: Optional[str] = None
-    agent_role: Optional[str] = None
-    agent_id: Optional[str] = None
+    agent_key: str | None = None
+    agent_role: str | None = None
+    agent_id: str | None = None
     tool_name: str
-    tool_args: Dict[str, Any] | str
-    tool_class: Optional[str] = None
+    tool_args: dict[str, Any] | str
+    tool_class: str | None = None
     run_attempts: int | None = None
     delegations: int | None = None
-    agent: Optional[Any] = None
-    task_name: Optional[str] = None
-    task_id: Optional[str] = None
-    from_task: Optional[Any] = None
-    from_agent: Optional[Any] = None
+    agent: Any | None = None
+    task_name: str | None = None
+    task_id: str | None = None
+    from_task: Any | None = None
+    from_agent: Any | None = None
 
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -81,9 +84,9 @@ class ToolExecutionErrorEvent(BaseEvent):
     error: Any
     type: str = "tool_execution_error"
     tool_name: str
-    tool_args: Dict[str, Any]
+    tool_args: dict[str, Any]
     tool_class: Callable
-    agent: Optional[Any] = None
+    agent: Any | None = None
 
     def __init__(self, **data):
         super().__init__(**data)

src/crewai/events/utils/console_formatter.py

@@ -1,25 +1,25 @@
-from typing import Any, Dict, Optional
+from typing import Any, ClassVar
 
 from rich.console import Console
+from rich.live import Live
 from rich.panel import Panel
+from rich.syntax import Syntax
 from rich.text import Text
 from rich.tree import Tree
-from rich.live import Live
-from rich.syntax import Syntax
 
 
 class ConsoleFormatter:
-    current_crew_tree: Optional[Tree] = None
-    current_task_branch: Optional[Tree] = None
-    current_agent_branch: Optional[Tree] = None
-    current_tool_branch: Optional[Tree] = None
-    current_flow_tree: Optional[Tree] = None
-    current_method_branch: Optional[Tree] = None
-    current_lite_agent_branch: Optional[Tree] = None
-    tool_usage_counts: Dict[str, int] = {}
-    current_reasoning_branch: Optional[Tree] = None  # Track reasoning status
+    current_crew_tree: Tree | None = None
+    current_task_branch: Tree | None = None
+    current_agent_branch: Tree | None = None
+    current_tool_branch: Tree | None = None
+    current_flow_tree: Tree | None = None
+    current_method_branch: Tree | None = None
+    current_lite_agent_branch: Tree | None = None
+    tool_usage_counts: ClassVar[dict[str, int]] = {}
+    current_reasoning_branch: Tree | None = None  # Track reasoning status
     _live_paused: bool = False
-    current_llm_tool_tree: Optional[Tree] = None
+    current_llm_tool_tree: Tree | None = None
 
     def __init__(self, verbose: bool = False):
         self.console = Console(width=None)
@@ -29,7 +29,7 @@ class ConsoleFormatter:
         # instance so the previous render is replaced instead of writing a new one.
         # Once any non-Tree renderable is printed we stop the Live session so the
         # final Tree persists on the terminal.
-        self._live: Optional[Live] = None
+        self._live: Live | None = None
 
     def create_panel(self, content: Text, title: str, style: str = "blue") -> Panel:
         """Create a standardized panel with consistent styling."""
@@ -45,7 +45,7 @@ class ConsoleFormatter:
         title: str,
         name: str,
         status_style: str = "blue",
-        tool_args: Dict[str, Any] | str = "",
+        tool_args: dict[str, Any] | str = "",
         **fields,
     ) -> Text:
         """Create standardized status content with consistent formatting."""
@@ -70,7 +70,7 @@ class ConsoleFormatter:
         prefix: str,
         name: str,
         style: str = "blue",
-        status: Optional[str] = None,
+        status: str | None = None,
     ) -> None:
         """Update tree label with consistent formatting."""
         label = Text()
@@ -115,7 +115,7 @@ class ConsoleFormatter:
                 self._live.update(tree, refresh=True)
             return  # Nothing else to do
 
-        # Case 2: blank line while a live session is running – ignore so we
+        # Case 2: blank line while a live session is running - ignore so we
         # don't break the in-place rendering behaviour
         if len(args) == 0 and self._live:
             return
@@ -156,7 +156,7 @@ class ConsoleFormatter:
 
     def update_crew_tree(
         self,
-        tree: Optional[Tree],
+        tree: Tree | None,
         crew_name: str,
         source_id: str,
         status: str = "completed",
@@ -196,7 +196,7 @@ class ConsoleFormatter:
 
         self.print_panel(content, title, style)
 
-    def create_crew_tree(self, crew_name: str, source_id: str) -> Optional[Tree]:
+    def create_crew_tree(self, crew_name: str, source_id: str) -> Tree | None:
         """Create and initialize a new crew tree with initial status."""
         if not self.verbose:
             return None
@@ -220,8 +220,8 @@ class ConsoleFormatter:
         return tree
 
     def create_task_branch(
-        self, crew_tree: Optional[Tree], task_id: str, task_name: Optional[str] = None
-    ) -> Optional[Tree]:
+        self, crew_tree: Tree | None, task_id: str, task_name: str | None = None
+    ) -> Tree | None:
         """Create and initialize a task branch."""
         if not self.verbose:
             return None
@@ -255,11 +255,11 @@ class ConsoleFormatter:
 
     def update_task_status(
         self,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
         task_id: str,
         agent_role: str,
         status: str = "completed",
-        task_name: Optional[str] = None,
+        task_name: str | None = None,
     ) -> None:
         """Update task status in the tree."""
         if not self.verbose or crew_tree is None:
@@ -306,8 +306,8 @@ class ConsoleFormatter:
         self.print_panel(content, panel_title, style)
 
     def create_agent_branch(
-        self, task_branch: Optional[Tree], agent_role: str, crew_tree: Optional[Tree]
-    ) -> Optional[Tree]:
+        self, task_branch: Tree | None, agent_role: str, crew_tree: Tree | None
+    ) -> Tree | None:
         """Create and initialize an agent branch."""
         if not self.verbose or not task_branch or not crew_tree:
             return None
@@ -325,9 +325,9 @@ class ConsoleFormatter:
 
     def update_agent_status(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         agent_role: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
         status: str = "completed",
     ) -> None:
         """Update agent status in the tree."""
@@ -336,7 +336,7 @@ class ConsoleFormatter:
         # altering the tree. Keeping it a no-op avoids duplicate status lines.
         return
 
-    def create_flow_tree(self, flow_name: str, flow_id: str) -> Optional[Tree]:
+    def create_flow_tree(self, flow_name: str, flow_id: str) -> Tree | None:
         """Create and initialize a flow tree."""
         content = self.create_status_content(
             "Starting Flow Execution", flow_name, "blue", ID=flow_id
@@ -356,7 +356,7 @@ class ConsoleFormatter:
 
         return flow_tree
 
-    def start_flow(self, flow_name: str, flow_id: str) -> Optional[Tree]:
+    def start_flow(self, flow_name: str, flow_id: str) -> Tree | None:
         """Initialize a flow execution tree."""
         flow_tree = Tree("")
         flow_label = Text()
@@ -376,7 +376,7 @@ class ConsoleFormatter:
 
     def update_flow_status(
         self,
-        flow_tree: Optional[Tree],
+        flow_tree: Tree | None,
         flow_name: str,
         flow_id: str,
         status: str = "completed",
@@ -423,11 +423,11 @@ class ConsoleFormatter:
 
     def update_method_status(
         self,
-        method_branch: Optional[Tree],
-        flow_tree: Optional[Tree],
+        method_branch: Tree | None,
+        flow_tree: Tree | None,
         method_name: str,
         status: str = "running",
-    ) -> Optional[Tree]:
+    ) -> Tree | None:
         """Update method status in the flow tree."""
         if not flow_tree:
             return None
@@ -480,7 +480,7 @@ class ConsoleFormatter:
     def handle_llm_tool_usage_started(
         self,
         tool_name: str,
-        tool_args: Dict[str, Any] | str,
+        tool_args: dict[str, Any] | str,
     ):
         # Create status content for the tool usage
         content = self.create_status_content(
@@ -520,11 +520,11 @@ class ConsoleFormatter:
 
     def handle_tool_usage_started(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         tool_name: str,
-        crew_tree: Optional[Tree],
-        tool_args: Dict[str, Any] | str = "",
-    ) -> Optional[Tree]:
+        crew_tree: Tree | None,
+        tool_args: dict[str, Any] | str = "",
+    ) -> Tree | None:
         """Handle tool usage started event."""
         if not self.verbose:
             return None
@@ -569,9 +569,9 @@ class ConsoleFormatter:
 
     def handle_tool_usage_finished(
         self,
-        tool_branch: Optional[Tree],
+        tool_branch: Tree | None,
         tool_name: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle tool usage finished event."""
         if not self.verbose or tool_branch is None:
@@ -600,10 +600,10 @@ class ConsoleFormatter:
 
     def handle_tool_usage_error(
         self,
-        tool_branch: Optional[Tree],
+        tool_branch: Tree | None,
         tool_name: str,
         error: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle tool usage error event."""
         if not self.verbose:
@@ -631,9 +631,9 @@ class ConsoleFormatter:
 
     def handle_llm_call_started(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
-    ) -> Optional[Tree]:
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
+    ) -> Tree | None:
         """Handle LLM call started event."""
         if not self.verbose:
             return None
@@ -672,9 +672,9 @@ class ConsoleFormatter:
 
     def handle_llm_call_completed(
         self,
-        tool_branch: Optional[Tree],
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
+        tool_branch: Tree | None,
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
     ) -> None:
         """Handle LLM call completed event."""
         if not self.verbose:
@@ -736,7 +736,7 @@ class ConsoleFormatter:
                 self.print()
 
     def handle_llm_call_failed(
-        self, tool_branch: Optional[Tree], error: str, crew_tree: Optional[Tree]
+        self, tool_branch: Tree | None, error: str, crew_tree: Tree | None
     ) -> None:
         """Handle LLM call failed event."""
         if not self.verbose:
@@ -789,7 +789,7 @@ class ConsoleFormatter:
 
     def handle_crew_test_started(
         self, crew_name: str, source_id: str, n_iterations: int
-    ) -> Optional[Tree]:
+    ) -> Tree | None:
         """Handle crew test started event."""
         if not self.verbose:
             return None
@@ -823,7 +823,7 @@ class ConsoleFormatter:
         return test_tree
 
     def handle_crew_test_completed(
-        self, flow_tree: Optional[Tree], crew_name: str
+        self, flow_tree: Tree | None, crew_name: str
     ) -> None:
         """Handle crew test completed event."""
         if not self.verbose:
@@ -913,7 +913,7 @@ class ConsoleFormatter:
         self.print_panel(failure_content, "Test Failure", "red")
         self.print()
 
-    def create_lite_agent_branch(self, lite_agent_role: str) -> Optional[Tree]:
+    def create_lite_agent_branch(self, lite_agent_role: str) -> Tree | None:
         """Create and initialize a lite agent branch."""
         if not self.verbose:
             return None
@@ -935,10 +935,10 @@ class ConsoleFormatter:
 
     def update_lite_agent_status(
         self,
-        lite_agent_branch: Optional[Tree],
+        lite_agent_branch: Tree | None,
         lite_agent_role: str,
         status: str = "completed",
-        **fields: Dict[str, Any],
+        **fields: dict[str, Any],
     ) -> None:
         """Update lite agent status in the tree."""
         if not self.verbose or lite_agent_branch is None:
@@ -981,7 +981,7 @@ class ConsoleFormatter:
         lite_agent_role: str,
         status: str = "started",
         error: Any = None,
-        **fields: Dict[str, Any],
+        **fields: dict[str, Any],
     ) -> None:
         """Handle lite agent execution events with consistent formatting."""
         if not self.verbose:
@@ -1006,9 +1006,9 @@ class ConsoleFormatter:
 
     def handle_knowledge_retrieval_started(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
-    ) -> Optional[Tree]:
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
+    ) -> Tree | None:
         """Handle knowledge retrieval started event."""
         if not self.verbose:
             return None
@@ -1034,13 +1034,13 @@ class ConsoleFormatter:
 
     def handle_knowledge_retrieval_completed(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
         retrieved_knowledge: Any,
     ) -> None:
         """Handle knowledge retrieval completed event."""
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = self.current_lite_agent_branch or agent_branch
         tree_to_use = branch_to_use or crew_tree
@@ -1062,7 +1062,7 @@ class ConsoleFormatter:
                 )
                 self.print(knowledge_panel)
                 self.print()
-            return None
+            return
 
         knowledge_branch_found = False
         for child in branch_to_use.children:
@@ -1111,18 +1111,18 @@ class ConsoleFormatter:
 
     def handle_knowledge_query_started(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         task_prompt: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle knowledge query generated event."""
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = self.current_lite_agent_branch or agent_branch
         tree_to_use = branch_to_use or crew_tree
         if branch_to_use is None or tree_to_use is None:
-            return None
+            return
 
         query_branch = branch_to_use.add("")
         self.update_tree_label(
@@ -1134,9 +1134,9 @@ class ConsoleFormatter:
 
     def handle_knowledge_query_failed(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         error: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle knowledge query failed event."""
         if not self.verbose:
@@ -1159,18 +1159,18 @@ class ConsoleFormatter:
 
     def handle_knowledge_query_completed(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
     ) -> None:
         """Handle knowledge query completed event."""
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = self.current_lite_agent_branch or agent_branch
         tree_to_use = branch_to_use or crew_tree
 
         if branch_to_use is None or tree_to_use is None:
-            return None
+            return
 
         query_branch = branch_to_use.add("")
         self.update_tree_label(query_branch, "✅", "Knowledge Query Completed", "green")
@@ -1180,9 +1180,9 @@ class ConsoleFormatter:
 
     def handle_knowledge_search_query_failed(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         error: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle knowledge search query failed event."""
         if not self.verbose:
@@ -1207,10 +1207,10 @@ class ConsoleFormatter:
 
     def handle_reasoning_started(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         attempt: int,
-        crew_tree: Optional[Tree],
-    ) -> Optional[Tree]:
+        crew_tree: Tree | None,
+    ) -> Tree | None:
         """Handle agent reasoning started (or refinement) event."""
         if not self.verbose:
             return None
@@ -1249,7 +1249,7 @@ class ConsoleFormatter:
         self,
         plan: str,
         ready: bool,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle agent reasoning completed event."""
         if not self.verbose:
@@ -1292,7 +1292,7 @@ class ConsoleFormatter:
     def handle_reasoning_failed(
         self,
         error: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         """Handle agent reasoning failure event."""
         if not self.verbose:
@@ -1329,7 +1329,7 @@ class ConsoleFormatter:
     def handle_agent_logs_started(
         self,
         agent_role: str,
-        task_description: Optional[str] = None,
+        task_description: str | None = None,
         verbose: bool = False,
     ) -> None:
         """Handle agent logs started event."""
@@ -1367,10 +1367,11 @@ class ConsoleFormatter:
         if not verbose:
             return
 
-        from crewai.agents.parser import AgentAction, AgentFinish
         import json
         import re
 
+        from crewai.agents.parser import AgentAction, AgentFinish
+
         agent_role = agent_role.partition("\n")[0]
 
         if isinstance(formatted_answer, AgentAction):
@@ -1473,9 +1474,9 @@ class ConsoleFormatter:
 
     def handle_memory_retrieval_started(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
-    ) -> Optional[Tree]:
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
+    ) -> Tree | None:
         if not self.verbose:
             return None
 
@@ -1497,13 +1498,13 @@ class ConsoleFormatter:
 
     def handle_memory_retrieval_completed(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
         memory_content: str,
         retrieval_time_ms: float,
     ) -> None:
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = self.current_lite_agent_branch or agent_branch
         tree_to_use = branch_to_use or crew_tree
@@ -1528,7 +1529,7 @@ class ConsoleFormatter:
 
         if branch_to_use is None or tree_to_use is None:
             add_panel()
-            return None
+            return
 
         memory_branch_found = False
         for child in branch_to_use.children:
@@ -1565,13 +1566,13 @@ class ConsoleFormatter:
 
     def handle_memory_query_completed(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         source_type: str,
         query_time_ms: float,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = self.current_lite_agent_branch or agent_branch
         tree_to_use = branch_to_use or crew_tree
@@ -1580,15 +1581,15 @@ class ConsoleFormatter:
             branch_to_use = tree_to_use
 
         if branch_to_use is None:
-            return None
+            return
 
         memory_type = source_type.replace("_", " ").title()
 
         for child in branch_to_use.children:
             if "Memory Retrieval" in str(child.label):
-                for child in child.children:
-                    sources_branch = child
-                    if "Sources Used" in str(child.label):
+                for inner_child in child.children:
+                    sources_branch = inner_child
+                    if "Sources Used" in str(inner_child.label):
                         sources_branch.add(f"✅ {memory_type} ({query_time_ms:.2f}ms)")
                         break
                 else:
@@ -1598,13 +1599,13 @@ class ConsoleFormatter:
 
     def handle_memory_query_failed(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
         error: str,
         source_type: str,
     ) -> None:
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = self.current_lite_agent_branch or agent_branch
         tree_to_use = branch_to_use or crew_tree
@@ -1613,15 +1614,15 @@ class ConsoleFormatter:
             branch_to_use = tree_to_use
 
         if branch_to_use is None:
-            return None
+            return
 
         memory_type = source_type.replace("_", " ").title()
 
         for child in branch_to_use.children:
             if "Memory Retrieval" in str(child.label):
-                for child in child.children:
-                    sources_branch = child
-                    if "Sources Used" in str(child.label):
+                for inner_child in child.children:
+                    sources_branch = inner_child
+                    if "Sources Used" in str(inner_child.label):
                         sources_branch.add(f"❌ {memory_type} - Error: {error}")
                         break
                 else:
@@ -1630,16 +1631,16 @@ class ConsoleFormatter:
                     break
 
     def handle_memory_save_started(
-        self, agent_branch: Optional[Tree], crew_tree: Optional[Tree]
+        self, agent_branch: Tree | None, crew_tree: Tree | None
     ) -> None:
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = agent_branch or self.current_lite_agent_branch
         tree_to_use = branch_to_use or crew_tree
 
         if tree_to_use is None:
-            return None
+            return
 
         for child in tree_to_use.children:
             if "Memory Update" in str(child.label):
@@ -1655,19 +1656,19 @@ class ConsoleFormatter:
 
     def handle_memory_save_completed(
         self,
-        agent_branch: Optional[Tree],
-        crew_tree: Optional[Tree],
+        agent_branch: Tree | None,
+        crew_tree: Tree | None,
         save_time_ms: float,
         source_type: str,
     ) -> None:
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = agent_branch or self.current_lite_agent_branch
         tree_to_use = branch_to_use or crew_tree
 
         if tree_to_use is None:
-            return None
+            return
 
         memory_type = source_type.replace("_", " ").title()
         content = f"✅ {memory_type} Memory Saved ({save_time_ms:.2f}ms)"
@@ -1685,19 +1686,19 @@ class ConsoleFormatter:
 
     def handle_memory_save_failed(
         self,
-        agent_branch: Optional[Tree],
+        agent_branch: Tree | None,
         error: str,
         source_type: str,
-        crew_tree: Optional[Tree],
+        crew_tree: Tree | None,
     ) -> None:
         if not self.verbose:
-            return None
+            return
 
         branch_to_use = agent_branch or self.current_lite_agent_branch
         tree_to_use = branch_to_use or crew_tree
 
         if branch_to_use is None or tree_to_use is None:
-            return None
+            return
 
         memory_type = source_type.replace("_", " ").title()
         content = f"❌ {memory_type} Memory Save Failed"
@@ -1738,7 +1739,7 @@ class ConsoleFormatter:
     def handle_guardrail_completed(
         self,
         success: bool,
-        error: Optional[str],
+        error: str | None,
         retry_count: int,
     ) -> None:
         """Display guardrail evaluation result.

src/crewai/experimental/__init__.py

@@ -1,40 +1,39 @@
 from crewai.experimental.evaluation import (
+    AgentEvaluationResult,
+    AgentEvaluator,
     BaseEvaluator,
     EvaluationScore,
-    MetricCategory,
-    AgentEvaluationResult,
-    SemanticQualityEvaluator,
-    GoalAlignmentEvaluator,
-    ReasoningEfficiencyEvaluator,
-    ToolSelectionEvaluator,
-    ParameterExtractionEvaluator,
-    ToolInvocationEvaluator,
     EvaluationTraceCallback,
-    create_evaluation_callbacks,
-    AgentEvaluator,
-    create_default_evaluator,
-    ExperimentRunner,
-    ExperimentResults,
     ExperimentResult,
+    ExperimentResults,
+    ExperimentRunner,
+    GoalAlignmentEvaluator,
+    MetricCategory,
+    ParameterExtractionEvaluator,
+    ReasoningEfficiencyEvaluator,
+    SemanticQualityEvaluator,
+    ToolInvocationEvaluator,
+    ToolSelectionEvaluator,
+    create_default_evaluator,
+    create_evaluation_callbacks,
 )
 
-
 __all__ = [
+    "AgentEvaluationResult",
+    "AgentEvaluator",
     "BaseEvaluator",
     "EvaluationScore",
-    "MetricCategory",
-    "AgentEvaluationResult",
-    "SemanticQualityEvaluator",
-    "GoalAlignmentEvaluator",
-    "ReasoningEfficiencyEvaluator",
-    "ToolSelectionEvaluator",
-    "ParameterExtractionEvaluator",
-    "ToolInvocationEvaluator",
     "EvaluationTraceCallback",
-    "create_evaluation_callbacks",
-    "AgentEvaluator",
-    "create_default_evaluator",
-    "ExperimentRunner",
+    "ExperimentResult",
     "ExperimentResults",
-    "ExperimentResult"
-]
+    "ExperimentRunner",
+    "GoalAlignmentEvaluator",
+    "MetricCategory",
+    "ParameterExtractionEvaluator",
+    "ReasoningEfficiencyEvaluator",
+    "SemanticQualityEvaluator",
+    "ToolInvocationEvaluator",
+    "ToolSelectionEvaluator",
+    "create_default_evaluator",
+    "create_evaluation_callbacks",
+]

src/crewai/experimental/evaluation/__init__.py

@@ -1,51 +1,47 @@
+from crewai.experimental.evaluation.agent_evaluator import (
+    AgentEvaluator,
+    create_default_evaluator,
+)
 from crewai.experimental.evaluation.base_evaluator import (
+    AgentEvaluationResult,
     BaseEvaluator,
     EvaluationScore,
     MetricCategory,
-    AgentEvaluationResult
 )
-
-from crewai.experimental.evaluation.metrics import (
-    SemanticQualityEvaluator,
-    GoalAlignmentEvaluator,
-    ReasoningEfficiencyEvaluator,
-    ToolSelectionEvaluator,
-    ParameterExtractionEvaluator,
-    ToolInvocationEvaluator
-)
-
 from crewai.experimental.evaluation.evaluation_listener import (
     EvaluationTraceCallback,
-    create_evaluation_callbacks
+    create_evaluation_callbacks,
 )
-
-from crewai.experimental.evaluation.agent_evaluator import (
-    AgentEvaluator,
-    create_default_evaluator
-)
-
 from crewai.experimental.evaluation.experiment import (
-    ExperimentRunner,
+    ExperimentResult,
     ExperimentResults,
-    ExperimentResult
+    ExperimentRunner,
+)
+from crewai.experimental.evaluation.metrics import (
+    GoalAlignmentEvaluator,
+    ParameterExtractionEvaluator,
+    ReasoningEfficiencyEvaluator,
+    SemanticQualityEvaluator,
+    ToolInvocationEvaluator,
+    ToolSelectionEvaluator,
 )
 
 __all__ = [
+    "AgentEvaluationResult",
+    "AgentEvaluator",
     "BaseEvaluator",
     "EvaluationScore",
-    "MetricCategory",
-    "AgentEvaluationResult",
-    "SemanticQualityEvaluator",
-    "GoalAlignmentEvaluator",
-    "ReasoningEfficiencyEvaluator",
-    "ToolSelectionEvaluator",
-    "ParameterExtractionEvaluator",
-    "ToolInvocationEvaluator",
     "EvaluationTraceCallback",
-    "create_evaluation_callbacks",
-    "AgentEvaluator",
-    "create_default_evaluator",
-    "ExperimentRunner",
+    "ExperimentResult",
     "ExperimentResults",
-    "ExperimentResult"
+    "ExperimentRunner",
+    "GoalAlignmentEvaluator",
+    "MetricCategory",
+    "ParameterExtractionEvaluator",
+    "ReasoningEfficiencyEvaluator",
+    "SemanticQualityEvaluator",
+    "ToolInvocationEvaluator",
+    "ToolSelectionEvaluator",
+    "create_default_evaluator",
+    "create_evaluation_callbacks",
 ]

src/crewai/experimental/evaluation/agent_evaluator.py

@@ -1,34 +1,36 @@
 import threading
-from typing import Any, Optional
+from collections.abc import Sequence
+from typing import Any
 
-from crewai.experimental.evaluation.base_evaluator import (
-    AgentEvaluationResult,
-    AggregationStrategy,
-)
 from crewai.agent import Agent
-from crewai.task import Task
-from crewai.experimental.evaluation.evaluation_display import EvaluationDisplayFormatter
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.agent_events import (
-    AgentEvaluationStartedEvent,
     AgentEvaluationCompletedEvent,
     AgentEvaluationFailedEvent,
+    AgentEvaluationStartedEvent,
+    LiteAgentExecutionCompletedEvent,
 )
-from crewai.experimental.evaluation import BaseEvaluator, create_evaluation_callbacks
-from collections.abc import Sequence
-from crewai.events.event_bus import crewai_event_bus
-from crewai.events.utils.console_formatter import ConsoleFormatter
 from crewai.events.types.task_events import TaskCompletedEvent
-from crewai.events.types.agent_events import LiteAgentExecutionCompletedEvent
+from crewai.events.utils.console_formatter import ConsoleFormatter
 from crewai.experimental.evaluation.base_evaluator import (
     AgentAggregatedEvaluationResult,
+    AgentEvaluationResult,
+    AggregationStrategy,
+    BaseEvaluator,
     EvaluationScore,
     MetricCategory,
 )
+from crewai.experimental.evaluation.evaluation_display import EvaluationDisplayFormatter
+from crewai.experimental.evaluation.evaluation_listener import (
+    create_evaluation_callbacks,
+)
+from crewai.task import Task
 
 
 class ExecutionState:
-    current_agent_id: Optional[str] = None
-    current_task_id: Optional[str] = None
+    current_agent_id: str | None = None
+    current_task_id: str | None = None
 
     def __init__(self):
         self.traces = {}
@@ -40,10 +42,10 @@ class ExecutionState:
 class AgentEvaluator:
     def __init__(
         self,
-        agents: list[Agent],
+        agents: list[Agent] | list[BaseAgent],
         evaluators: Sequence[BaseEvaluator] | None = None,
     ):
-        self.agents: list[Agent] = agents
+        self.agents: list[Agent] | list[BaseAgent] = agents
         self.evaluators: Sequence[BaseEvaluator] | None = evaluators
 
         self.callback = create_evaluation_callbacks()
@@ -75,7 +77,8 @@ class AgentEvaluator:
         )
 
     def _handle_task_completed(self, source: Any, event: TaskCompletedEvent) -> None:
-        assert event.task is not None
+        if event.task is None:
+            raise ValueError("TaskCompletedEvent must have a task")
         agent = event.task.agent
         if (
             agent
@@ -92,9 +95,8 @@ class AgentEvaluator:
             state.current_agent_id = str(agent.id)
             state.current_task_id = str(event.task.id)
 
-            assert (
-                state.current_agent_id is not None and state.current_task_id is not None
-            )
+            if state.current_agent_id is None or state.current_task_id is None:
+                raise ValueError("Agent ID and Task ID must not be None")
             trace = self.callback.get_trace(
                 state.current_agent_id, state.current_task_id
             )
@@ -146,9 +148,8 @@ class AgentEvaluator:
             if not target_agent:
                 return
 
-            assert (
-                state.current_agent_id is not None and state.current_task_id is not None
-            )
+            if state.current_agent_id is None or state.current_task_id is None:
+                raise ValueError("Agent ID and Task ID must not be None")
             trace = self.callback.get_trace(
                 state.current_agent_id, state.current_task_id
             )
@@ -244,7 +245,7 @@ class AgentEvaluator:
 
     def evaluate(
         self,
-        agent: Agent,
+        agent: Agent | BaseAgent,
         execution_trace: dict[str, Any],
         final_output: Any,
         state: ExecutionState,
@@ -255,7 +256,8 @@ class AgentEvaluator:
             task_id=state.current_task_id or (str(task.id) if task else "unknown_task"),
         )
 
-        assert self.evaluators is not None
+        if self.evaluators is None:
+            raise ValueError("Evaluators must be initialized")
         task_id = str(task.id) if task else None
         for evaluator in self.evaluators:
             try:
@@ -276,7 +278,7 @@ class AgentEvaluator:
                     metric_category=evaluator.metric_category,
                     score=score,
                 )
-            except Exception as e:
+            except Exception as e:  # noqa: PERF203
                 self.emit_evaluation_failed_event(
                     agent_role=agent.role,
                     agent_id=str(agent.id),
@@ -284,7 +286,7 @@ class AgentEvaluator:
                     error=str(e),
                 )
                 self.console_formatter.print(
-                    f"Error in {evaluator.metric_category.value} evaluator: {str(e)}"
+                    f"Error in {evaluator.metric_category.value} evaluator: {e!s}"
                 )
 
         return result
@@ -337,14 +339,14 @@ class AgentEvaluator:
         )
 
 
-def create_default_evaluator(agents: list[Agent], llm: None = None):
+def create_default_evaluator(agents: list[Agent] | list[BaseAgent], llm: None = None):
     from crewai.experimental.evaluation import (
         GoalAlignmentEvaluator,
-        SemanticQualityEvaluator,
-        ToolSelectionEvaluator,
         ParameterExtractionEvaluator,
-        ToolInvocationEvaluator,
         ReasoningEfficiencyEvaluator,
+        SemanticQualityEvaluator,
+        ToolInvocationEvaluator,
+        ToolSelectionEvaluator,
     )
 
     evaluators = [

src/crewai/experimental/evaluation/base_evaluator.py

@@ -1,15 +1,17 @@
 import abc
 import enum
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 from pydantic import BaseModel, Field
 
 from crewai.agent import Agent
-from crewai.task import Task
+from crewai.agents.agent_builder.base_agent import BaseAgent
 from crewai.llm import BaseLLM
+from crewai.task import Task
 from crewai.utilities.llm_utils import create_llm
 
+
 class MetricCategory(enum.Enum):
     GOAL_ALIGNMENT = "goal_alignment"
     SEMANTIC_QUALITY = "semantic_quality"
@@ -19,7 +21,7 @@ class MetricCategory(enum.Enum):
     TOOL_INVOCATION = "tool_invocation"
 
     def title(self):
-        return self.value.replace('_', ' ').title()
+        return self.value.replace("_", " ").title()
 
 
 class EvaluationScore(BaseModel):
@@ -27,15 +29,13 @@ class EvaluationScore(BaseModel):
         default=5.0,
         description="Numeric score from 0-10 where 0 is worst and 10 is best, None if not applicable",
         ge=0.0,
-        le=10.0
+        le=10.0,
     )
     feedback: str = Field(
-        default="",
-        description="Detailed feedback explaining the evaluation score"
+        default="", description="Detailed feedback explaining the evaluation score"
     )
     raw_response: str | None = Field(
-        default=None,
-        description="Raw response from the evaluator (e.g., LLM)"
+        default=None, description="Raw response from the evaluator (e.g., LLM)"
     )
 
     def __str__(self) -> str:
@@ -56,8 +56,8 @@ class BaseEvaluator(abc.ABC):
     @abc.abstractmethod
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: Any,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -67,9 +67,8 @@ class BaseEvaluator(abc.ABC):
 class AgentEvaluationResult(BaseModel):
     agent_id: str = Field(description="ID of the evaluated agent")
     task_id: str = Field(description="ID of the task that was executed")
-    metrics: Dict[MetricCategory, EvaluationScore] = Field(
-        default_factory=dict,
-        description="Evaluation scores for each metric category"
+    metrics: dict[MetricCategory, EvaluationScore] = Field(
+        default_factory=dict, description="Evaluation scores for each metric category"
     )
 
 
@@ -81,33 +80,23 @@ class AggregationStrategy(Enum):
 
 
 class AgentAggregatedEvaluationResult(BaseModel):
-    agent_id: str = Field(
-        default="",
-        description="ID of the agent"
-    )
-    agent_role: str = Field(
-        default="",
-        description="Role of the agent"
-    )
+    agent_id: str = Field(default="", description="ID of the agent")
+    agent_role: str = Field(default="", description="Role of the agent")
     task_count: int = Field(
-        default=0,
-        description="Number of tasks included in this aggregation"
+        default=0, description="Number of tasks included in this aggregation"
     )
     aggregation_strategy: AggregationStrategy = Field(
         default=AggregationStrategy.SIMPLE_AVERAGE,
-        description="Strategy used for aggregation"
+        description="Strategy used for aggregation",
     )
-    metrics: Dict[MetricCategory, EvaluationScore] = Field(
-        default_factory=dict,
-        description="Aggregated metrics across all tasks"
+    metrics: dict[MetricCategory, EvaluationScore] = Field(
+        default_factory=dict, description="Aggregated metrics across all tasks"
     )
-    task_results: List[str] = Field(
-        default_factory=list,
-        description="IDs of tasks included in this aggregation"
+    task_results: list[str] = Field(
+        default_factory=list, description="IDs of tasks included in this aggregation"
     )
-    overall_score: Optional[float] = Field(
-        default=None,
-        description="Overall score for this agent"
+    overall_score: float | None = Field(
+        default=None, description="Overall score for this agent"
     )
 
     def __str__(self) -> str:
@@ -119,7 +108,7 @@ class AgentAggregatedEvaluationResult(BaseModel):
             result += f"\n\n- {category.value.upper()}: {score.score}/10\n"
 
             if score.feedback:
-                detailed_feedback = "\n  ".join(score.feedback.split('\n'))
+                detailed_feedback = "\n  ".join(score.feedback.split("\n"))
                 result += f"  {detailed_feedback}\n"
 
-        return result
+        return result

src/crewai/experimental/evaluation/evaluation_display.py

@@ -1,16 +1,18 @@
 from collections import defaultdict
-from typing import Dict, Any, List
-from rich.table import Table
-from rich.box import HEAVY_EDGE, ROUNDED
 from collections.abc import Sequence
+from typing import Any
+
+from rich.box import HEAVY_EDGE, ROUNDED
+from rich.table import Table
+
+from crewai.events.utils.console_formatter import ConsoleFormatter
 from crewai.experimental.evaluation.base_evaluator import (
     AgentAggregatedEvaluationResult,
-    AggregationStrategy,
     AgentEvaluationResult,
+    AggregationStrategy,
+    EvaluationScore,
     MetricCategory,
 )
-from crewai.experimental.evaluation import EvaluationScore
-from crewai.events.utils.console_formatter import ConsoleFormatter
 from crewai.utilities.llm_utils import create_llm
 
 
@@ -19,7 +21,7 @@ class EvaluationDisplayFormatter:
         self.console_formatter = ConsoleFormatter()
 
     def display_evaluation_with_feedback(
-        self, iterations_results: Dict[int, Dict[str, List[Any]]]
+        self, iterations_results: dict[int, dict[str, list[Any]]]
     ):
         if not iterations_results:
             self.console_formatter.print(
@@ -99,7 +101,7 @@ class EvaluationDisplayFormatter:
 
     def display_summary_results(
         self,
-        iterations_results: Dict[int, Dict[str, List[AgentAggregatedEvaluationResult]]],
+        iterations_results: dict[int, dict[str, list[AgentEvaluationResult]]],
     ):
         if not iterations_results:
             self.console_formatter.print(
@@ -280,7 +282,7 @@ class EvaluationDisplayFormatter:
                     feedback_summary = feedbacks[0]
 
             aggregated_metrics[category] = EvaluationScore(
-                score=avg_score, feedback=feedback_summary
+                score=avg_score, feedback=feedback_summary or ""
             )
 
         overall_score = None
@@ -304,25 +306,25 @@ class EvaluationDisplayFormatter:
         self,
         agent_role: str,
         metric: str,
-        feedbacks: List[str],
-        scores: List[float | None],
+        feedbacks: list[str],
+        scores: list[float | None],
         strategy: AggregationStrategy,
     ) -> str:
         if len(feedbacks) <= 2 and all(len(fb) < 200 for fb in feedbacks):
             return "\n\n".join(
-                [f"Feedback {i+1}: {fb}" for i, fb in enumerate(feedbacks)]
+                [f"Feedback {i + 1}: {fb}" for i, fb in enumerate(feedbacks)]
             )
 
         try:
             llm = create_llm()
 
             formatted_feedbacks = []
-            for i, (feedback, score) in enumerate(zip(feedbacks, scores)):
+            for i, (feedback, score) in enumerate(zip(feedbacks, scores, strict=False)):
                 if len(feedback) > 500:
                     feedback = feedback[:500] + "..."
                 score_text = f"{score:.1f}" if score is not None else "N/A"
                 formatted_feedbacks.append(
-                    f"Feedback #{i+1} (Score: {score_text}):\n{feedback}"
+                    f"Feedback #{i + 1} (Score: {score_text}):\n{feedback}"
                 )
 
             all_feedbacks = "\n\n" + "\n\n---\n\n".join(formatted_feedbacks)
@@ -365,10 +367,9 @@ class EvaluationDisplayFormatter:
                 """,
                 },
             ]
-            assert llm is not None
-            response = llm.call(prompt)
-
-            return response
+            if llm is None:
+                raise ValueError("LLM must be initialized")
+            return llm.call(prompt)
 
         except Exception:
             return "Synthesized from multiple tasks: " + "\n\n".join(

src/crewai/experimental/evaluation/evaluation_listener.py

@@ -1,26 +1,25 @@
-from datetime import datetime
-from typing import Any, Dict, Optional
-
 from collections.abc import Sequence
+from datetime import datetime
+from typing import Any
 
-from crewai.agent import Agent
-from crewai.task import Task
+from crewai.agents.agent_builder.base_agent import BaseAgent
 from crewai.events.base_event_listener import BaseEventListener
 from crewai.events.event_bus import CrewAIEventsBus
 from crewai.events.types.agent_events import (
-    AgentExecutionStartedEvent,
     AgentExecutionCompletedEvent,
-    LiteAgentExecutionStartedEvent,
+    AgentExecutionStartedEvent,
     LiteAgentExecutionCompletedEvent,
+    LiteAgentExecutionStartedEvent,
 )
+from crewai.events.types.llm_events import LLMCallCompletedEvent, LLMCallStartedEvent
 from crewai.events.types.tool_usage_events import (
-    ToolUsageFinishedEvent,
-    ToolUsageErrorEvent,
     ToolExecutionErrorEvent,
     ToolSelectionErrorEvent,
+    ToolUsageErrorEvent,
+    ToolUsageFinishedEvent,
     ToolValidateInputErrorEvent,
 )
-from crewai.events.types.llm_events import LLMCallStartedEvent, LLMCallCompletedEvent
+from crewai.task import Task
 
 
 class EvaluationTraceCallback(BaseEventListener):
@@ -136,7 +135,7 @@ class EvaluationTraceCallback(BaseEventListener):
     def _init_trace(self, trace_key: str, **kwargs: Any):
         self.traces[trace_key] = kwargs
 
-    def on_agent_start(self, agent: Agent, task: Task):
+    def on_agent_start(self, agent: BaseAgent, task: Task):
         self.current_agent_id = agent.id
         self.current_task_id = task.id
 
@@ -151,7 +150,7 @@ class EvaluationTraceCallback(BaseEventListener):
             final_output=None,
         )
 
-    def on_agent_finish(self, agent: Agent, task: Task, output: Any):
+    def on_agent_finish(self, agent: BaseAgent, task: Task, output: Any):
         trace_key = f"{agent.id}_{task.id}"
         if trace_key in self.traces:
             self.traces[trace_key]["final_output"] = output
@@ -253,7 +252,7 @@ class EvaluationTraceCallback(BaseEventListener):
         if hasattr(self, "current_llm_call"):
             self.current_llm_call = {}
 
-    def get_trace(self, agent_id: str, task_id: str) -> Optional[Dict[str, Any]]:
+    def get_trace(self, agent_id: str, task_id: str) -> dict[str, Any] | None:
         trace_key = f"{agent_id}_{task_id}"
         return self.traces.get(trace_key)
 

src/crewai/experimental/evaluation/experiment/__init__.py

@@ -1,8 +1,7 @@
+from crewai.experimental.evaluation.experiment.result import (
+    ExperimentResult,
+    ExperimentResults,
+)
 from crewai.experimental.evaluation.experiment.runner import ExperimentRunner
-from crewai.experimental.evaluation.experiment.result import ExperimentResults, ExperimentResult
 
-__all__ = [
-    "ExperimentRunner",
-    "ExperimentResults",
-    "ExperimentResult"
-]
+__all__ = ["ExperimentResult", "ExperimentResults", "ExperimentRunner"]

src/crewai/experimental/evaluation/experiment/result.py

@@ -2,45 +2,60 @@ import json
 import os
 from datetime import datetime, timezone
 from typing import Any
+
 from pydantic import BaseModel
 
+
 class ExperimentResult(BaseModel):
     identifier: str
     inputs: dict[str, Any]
-    score: int | dict[str, int | float]
-    expected_score: int | dict[str, int | float]
+    score: float | dict[str, float]
+    expected_score: float | dict[str, float]
     passed: bool
     agent_evaluations: dict[str, Any] | None = None
 
+
 class ExperimentResults:
-    def __init__(self, results: list[ExperimentResult], metadata: dict[str, Any] | None = None):
+    def __init__(
+        self, results: list[ExperimentResult], metadata: dict[str, Any] | None = None
+    ):
         self.results = results
         self.metadata = metadata or {}
         self.timestamp = datetime.now(timezone.utc)
 
-        from crewai.experimental.evaluation.experiment.result_display import ExperimentResultsDisplay
+        from crewai.experimental.evaluation.experiment.result_display import (
+            ExperimentResultsDisplay,
+        )
+
         self.display = ExperimentResultsDisplay()
 
     def to_json(self, filepath: str | None = None) -> dict[str, Any]:
         data = {
             "timestamp": self.timestamp.isoformat(),
             "metadata": self.metadata,
-            "results": [r.model_dump(exclude={"agent_evaluations"}) for r in self.results]
+            "results": [
+                r.model_dump(exclude={"agent_evaluations"}) for r in self.results
+            ],
         }
 
         if filepath:
-            with open(filepath, 'w') as f:
+            with open(filepath, "w") as f:
                 json.dump(data, f, indent=2)
             self.display.console.print(f"[green]Results saved to {filepath}[/green]")
 
         return data
 
-    def compare_with_baseline(self, baseline_filepath: str, save_current: bool = True, print_summary: bool = False) -> dict[str, Any]:
+    def compare_with_baseline(
+        self,
+        baseline_filepath: str,
+        save_current: bool = True,
+        print_summary: bool = False,
+    ) -> dict[str, Any]:
         baseline_runs = []
 
         if os.path.exists(baseline_filepath) and os.path.getsize(baseline_filepath) > 0:
             try:
-                with open(baseline_filepath, 'r') as f:
+                with open(baseline_filepath, "r") as f:
                     baseline_data = json.load(f)
 
                 if isinstance(baseline_data, dict) and "timestamp" in baseline_data:
@@ -48,14 +63,18 @@ class ExperimentResults:
                 elif isinstance(baseline_data, list):
                     baseline_runs = baseline_data
             except (json.JSONDecodeError, FileNotFoundError) as e:
-                self.display.console.print(f"[yellow]Warning: Could not load baseline file: {str(e)}[/yellow]")
+                self.display.console.print(
+                    f"[yellow]Warning: Could not load baseline file: {e!s}[/yellow]"
+                )
 
         if not baseline_runs:
             if save_current:
                 current_data = self.to_json()
-                with open(baseline_filepath, 'w') as f:
+                with open(baseline_filepath, "w") as f:
                     json.dump([current_data], f, indent=2)
-                self.display.console.print(f"[green]Saved current results as new baseline to {baseline_filepath}[/green]")
+                self.display.console.print(
+                    f"[green]Saved current results as new baseline to {baseline_filepath}[/green]"
+                )
             return {"is_baseline": True, "changes": {}}
 
         baseline_runs.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
@@ -69,9 +88,11 @@ class ExperimentResults:
         if save_current:
             current_data = self.to_json()
             baseline_runs.append(current_data)
-            with open(baseline_filepath, 'w') as f:
+            with open(baseline_filepath, "w") as f:
                 json.dump(baseline_runs, f, indent=2)
-            self.display.console.print(f"[green]Added current results to baseline file {baseline_filepath}[/green]")
+            self.display.console.print(
+                f"[green]Added current results to baseline file {baseline_filepath}[/green]"
+            )
 
         return comparison
 
@@ -118,5 +139,5 @@ class ExperimentResults:
             "new_tests": new_tests,
             "missing_tests": missing_tests,
             "total_compared": len(improved) + len(regressed) + len(unchanged),
-            "baseline_timestamp": baseline_run.get("timestamp", "unknown")
+            "baseline_timestamp": baseline_run.get("timestamp", "unknown"),
         }

src/crewai/experimental/evaluation/experiment/result_display.py

@@ -1,9 +1,12 @@
-from typing import Dict, Any
+from typing import Any
+
 from rich.console import Console
-from rich.table import Table
 from rich.panel import Panel
+from rich.table import Table
+
 from crewai.experimental.evaluation.experiment.result import ExperimentResults
 
+
 class ExperimentResultsDisplay:
     def __init__(self):
         self.console = Console()
@@ -19,13 +22,19 @@ class ExperimentResultsDisplay:
         table.add_row("Total Test Cases", str(total))
         table.add_row("Passed", str(passed))
         table.add_row("Failed", str(total - passed))
-        table.add_row("Success Rate", f"{(passed / total * 100):.1f}%" if total > 0 else "N/A")
+        table.add_row(
+            "Success Rate", f"{(passed / total * 100):.1f}%" if total > 0 else "N/A"
+        )
 
         self.console.print(table)
 
-    def comparison_summary(self, comparison: Dict[str, Any], baseline_timestamp: str):
-        self.console.print(Panel(f"[bold]Comparison with baseline run from {baseline_timestamp}[/bold]",
-                                 expand=False))
+    def comparison_summary(self, comparison: dict[str, Any], baseline_timestamp: str):
+        self.console.print(
+            Panel(
+                f"[bold]Comparison with baseline run from {baseline_timestamp}[/bold]",
+                expand=False,
+            )
+        )
 
         table = Table(title="Results Comparison")
         table.add_column("Metric", style="cyan")
@@ -34,7 +43,9 @@ class ExperimentResultsDisplay:
 
         improved = comparison.get("improved", [])
         if improved:
-            details = ", ".join([f"{test_identifier}" for test_identifier in improved[:3]])
+            details = ", ".join(
+                [f"{test_identifier}" for test_identifier in improved[:3]]
+            )
             if len(improved) > 3:
                 details += f" and {len(improved) - 3} more"
             table.add_row("✅ Improved", str(len(improved)), details)
@@ -43,7 +54,9 @@ class ExperimentResultsDisplay:
 
         regressed = comparison.get("regressed", [])
         if regressed:
-            details = ", ".join([f"{test_identifier}" for test_identifier in regressed[:3]])
+            details = ", ".join(
+                [f"{test_identifier}" for test_identifier in regressed[:3]]
+            )
             if len(regressed) > 3:
                 details += f" and {len(regressed) - 3} more"
             table.add_row("❌ Regressed", str(len(regressed)), details, style="red")
@@ -58,13 +71,13 @@ class ExperimentResultsDisplay:
             details = ", ".join(new_tests[:3])
             if len(new_tests) > 3:
                 details += f" and {len(new_tests) - 3} more"
-            table.add_row("➕ New Tests", str(len(new_tests)), details)
+            table.add_row("+ New Tests", str(len(new_tests)), details)
 
         missing_tests = comparison.get("missing_tests", [])
         if missing_tests:
             details = ", ".join(missing_tests[:3])
             if len(missing_tests) > 3:
                 details += f" and {len(missing_tests) - 3} more"
-            table.add_row("➖ Missing Tests", str(len(missing_tests)), details)
+            table.add_row("- Missing Tests", str(len(missing_tests)), details)
 
         self.console.print(table)

src/crewai/experimental/evaluation/experiment/runner.py

@@ -2,11 +2,20 @@ from collections import defaultdict
 from hashlib import md5
 from typing import Any
 
-from crewai import Crew, Agent
+from crewai import Agent, Crew
+from crewai.agents.agent_builder.base_agent import BaseAgent
 from crewai.experimental.evaluation import AgentEvaluator, create_default_evaluator
-from crewai.experimental.evaluation.experiment.result_display import ExperimentResultsDisplay
-from crewai.experimental.evaluation.experiment.result import ExperimentResults, ExperimentResult
-from crewai.experimental.evaluation.evaluation_display import AgentAggregatedEvaluationResult
+from crewai.experimental.evaluation.evaluation_display import (
+    AgentAggregatedEvaluationResult,
+)
+from crewai.experimental.evaluation.experiment.result import (
+    ExperimentResult,
+    ExperimentResults,
+)
+from crewai.experimental.evaluation.experiment.result_display import (
+    ExperimentResultsDisplay,
+)
+
 
 class ExperimentRunner:
     def __init__(self, dataset: list[dict[str, Any]]):
@@ -14,11 +23,17 @@ class ExperimentRunner:
         self.evaluator: AgentEvaluator | None = None
         self.display = ExperimentResultsDisplay()
 
-    def run(self, crew: Crew | None = None, agents: list[Agent] | None = None, print_summary: bool = False) -> ExperimentResults:
+    def run(
+        self,
+        crew: Crew | None = None,
+        agents: list[Agent] | list[BaseAgent] | None = None,
+        print_summary: bool = False,
+    ) -> ExperimentResults:
         if crew and not agents:
             agents = crew.agents
 
-        assert agents is not None
+        if agents is None:
+            raise ValueError("Agents must be provided either directly or via a crew")
         self.evaluator = create_default_evaluator(agents=agents)
 
         results = []
@@ -35,21 +50,37 @@ class ExperimentRunner:
 
         return experiment_results
 
-    def _run_test_case(self, test_case: dict[str, Any], agents: list[Agent], crew: Crew | None = None) -> ExperimentResult:
+    def _run_test_case(
+        self,
+        test_case: dict[str, Any],
+        agents: list[Agent] | list[BaseAgent],
+        crew: Crew | None = None,
+    ) -> ExperimentResult:
         inputs = test_case["inputs"]
         expected_score = test_case["expected_score"]
-        identifier = test_case.get("identifier") or md5(str(test_case).encode(), usedforsecurity=False).hexdigest()
+        identifier = (
+            test_case.get("identifier")
+            or md5(str(test_case).encode(), usedforsecurity=False).hexdigest()
+        )
 
         try:
-            self.display.console.print(f"[dim]Running crew with input: {str(inputs)[:50]}...[/dim]")
+            self.display.console.print(
+                f"[dim]Running crew with input: {str(inputs)[:50]}...[/dim]"
+            )
             self.display.console.print("\n")
             if crew:
                 crew.kickoff(inputs=inputs)
             else:
                 for agent in agents:
-                    agent.kickoff(**inputs)
+                    if isinstance(agent, Agent):
+                        agent.kickoff(**inputs)
+                    else:
+                        raise TypeError(
+                            f"Agent {agent} is not an instance of Agent and cannot be kicked off directly"
+                        )
 
-            assert self.evaluator is not None
+            if self.evaluator is None:
+                raise ValueError("Evaluator must be initialized")
             agent_evaluations = self.evaluator.get_agent_evaluation()
 
             actual_score = self._extract_scores(agent_evaluations)
@@ -61,35 +92,38 @@ class ExperimentRunner:
                 score=actual_score,
                 expected_score=expected_score,
                 passed=passed,
-                agent_evaluations=agent_evaluations
+                agent_evaluations=agent_evaluations,
             )
 
         except Exception as e:
-            self.display.console.print(f"[red]Error running test case: {str(e)}[/red]")
+            self.display.console.print(f"[red]Error running test case: {e!s}[/red]")
             return ExperimentResult(
                 identifier=identifier,
                 inputs=inputs,
-                score=0,
+                score=0.0,
                 expected_score=expected_score,
-                passed=False
+                passed=False,
             )
 
-    def _extract_scores(self, agent_evaluations: dict[str, AgentAggregatedEvaluationResult]) -> float | dict[str,  float]:
+    def _extract_scores(
+        self, agent_evaluations: dict[str, AgentAggregatedEvaluationResult]
+    ) -> float | dict[str, float]:
         all_scores: dict[str, list[float]] = defaultdict(list)
         for evaluation in agent_evaluations.values():
             for metric_name, score in evaluation.metrics.items():
                 if score.score is not None:
                     all_scores[metric_name.value].append(score.score)
 
-        avg_scores = {m: sum(s)/len(s) for m, s in all_scores.items()}
+        avg_scores = {m: sum(s) / len(s) for m, s in all_scores.items()}
 
         if len(avg_scores) == 1:
-            return list(avg_scores.values())[0]
+            return next(iter(avg_scores.values()))
 
         return avg_scores
 
-    def _assert_scores(self, expected: float | dict[str, float],
-                        actual: float | dict[str, float]) -> bool:
+    def _assert_scores(
+        self, expected: float | dict[str, float], actual: float | dict[str, float]
+    ) -> bool:
         """
         Compare expected and actual scores, and return whether the test case passed.
 
@@ -122,4 +156,4 @@ class ExperimentRunner:
             # All matching keys must have actual >= expected
             return all(actual[key] >= expected[key] for key in matching_keys)
 
-        return False
+        return False

src/crewai/experimental/evaluation/json_parser.py

@@ -13,11 +13,11 @@ def extract_json_from_llm_response(text: str) -> dict[str, Any]:
 
     json_patterns = [
         # Standard markdown code blocks with json
-        r'```json\s*([\s\S]*?)\s*```',
+        r"```json\s*([\s\S]*?)\s*```",
         # Code blocks without language specifier
-        r'```\s*([\s\S]*?)\s*```',
+        r"```\s*([\s\S]*?)\s*```",
         # Inline code with JSON
-        r'`([{\\[].*[}\]])`',
+        r"`([{\\[].*[}\]])`",
     ]
 
     for pattern in json_patterns:
@@ -25,6 +25,6 @@ def extract_json_from_llm_response(text: str) -> dict[str, Any]:
         for match in matches:
             try:
                 return json.loads(match.strip())
-            except json.JSONDecodeError:
+            except json.JSONDecodeError:  # noqa: PERF203
                 continue
     raise ValueError("No valid JSON found in the response")

src/crewai/experimental/evaluation/metrics/__init__.py

@@ -1,26 +1,21 @@
+from crewai.experimental.evaluation.metrics.goal_metrics import GoalAlignmentEvaluator
 from crewai.experimental.evaluation.metrics.reasoning_metrics import (
-    ReasoningEfficiencyEvaluator
+    ReasoningEfficiencyEvaluator,
 )
-
-from crewai.experimental.evaluation.metrics.tools_metrics import (
-    ToolSelectionEvaluator,
-    ParameterExtractionEvaluator,
-    ToolInvocationEvaluator
-)
-
-from crewai.experimental.evaluation.metrics.goal_metrics import (
-    GoalAlignmentEvaluator
-)
-
 from crewai.experimental.evaluation.metrics.semantic_quality_metrics import (
-    SemanticQualityEvaluator
+    SemanticQualityEvaluator,
+)
+from crewai.experimental.evaluation.metrics.tools_metrics import (
+    ParameterExtractionEvaluator,
+    ToolInvocationEvaluator,
+    ToolSelectionEvaluator,
 )
 
 __all__ = [
-    "ReasoningEfficiencyEvaluator",
-    "ToolSelectionEvaluator",
-    "ParameterExtractionEvaluator",
-    "ToolInvocationEvaluator",
     "GoalAlignmentEvaluator",
-    "SemanticQualityEvaluator"
-]
+    "ParameterExtractionEvaluator",
+    "ReasoningEfficiencyEvaluator",
+    "SemanticQualityEvaluator",
+    "ToolInvocationEvaluator",
+    "ToolSelectionEvaluator",
+]

src/crewai/experimental/evaluation/metrics/goal_metrics.py

@@ -1,10 +1,15 @@
-from typing import Any, Dict
+from typing import Any
 
 from crewai.agent import Agent
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.experimental.evaluation.base_evaluator import (
+    BaseEvaluator,
+    EvaluationScore,
+    MetricCategory,
+)
+from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
 from crewai.task import Task
 
-from crewai.experimental.evaluation.base_evaluator import BaseEvaluator, EvaluationScore, MetricCategory
-from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
 
 class GoalAlignmentEvaluator(BaseEvaluator):
     @property
@@ -13,8 +18,8 @@ class GoalAlignmentEvaluator(BaseEvaluator):
 
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: Any,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -23,7 +28,9 @@ class GoalAlignmentEvaluator(BaseEvaluator):
             task_context = f"Task description: {task.description}\nExpected output: {task.expected_output}\n"
 
         prompt = [
-            {"role": "system", "content": """You are an expert evaluator assessing how well an AI agent's output aligns with its assigned task goal.
+            {
+                "role": "system",
+                "content": """You are an expert evaluator assessing how well an AI agent's output aligns with its assigned task goal.
 
 Score the agent's goal alignment on a scale from 0-10 where:
 - 0: Complete misalignment, agent did not understand or attempt the task goal
@@ -37,8 +44,11 @@ Consider:
 4. Did the agent provide all requested information or deliverables?
 
 Return your evaluation as JSON with fields 'score' (number) and 'feedback' (string).
-"""},
-            {"role": "user", "content": f"""
+""",
+            },
+            {
+                "role": "user",
+                "content": f"""
 Agent role: {agent.role}
 Agent goal: {agent.goal}
 {task_context}
@@ -47,23 +57,26 @@ Agent's final output:
 {final_output}
 
 Evaluate how well the agent's output aligns with the assigned task goal.
-"""}
+""",
+            },
         ]
-        assert self.llm is not None
+        if self.llm is None:
+            raise ValueError("LLM must be initialized")
         response = self.llm.call(prompt)
 
         try:
             evaluation_data: dict[str, Any] = extract_json_from_llm_response(response)
-            assert evaluation_data is not None
+            if evaluation_data is None:
+                raise ValueError("Failed to extract evaluation data from LLM response")
 
             return EvaluationScore(
                 score=evaluation_data.get("score", 0),
                 feedback=evaluation_data.get("feedback", response),
-                raw_response=response
+                raw_response=response,
             )
         except Exception:
             return EvaluationScore(
                 score=None,
                 feedback=f"Failed to parse evaluation. Raw response: {response}",
-                raw_response=response
+                raw_response=response,
             )

src/crewai/experimental/evaluation/metrics/reasoning_metrics.py

@@ -8,18 +8,24 @@ This module provides evaluator implementations for:
 
 import logging
 import re
-from enum import Enum
-from typing import Any, Dict, List, Tuple
-import numpy as np
 from collections.abc import Sequence
+from enum import Enum
+from typing import Any
+
+import numpy as np
 
 from crewai.agent import Agent
-from crewai.task import Task
-
-from crewai.experimental.evaluation.base_evaluator import BaseEvaluator, EvaluationScore, MetricCategory
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.experimental.evaluation.base_evaluator import (
+    BaseEvaluator,
+    EvaluationScore,
+    MetricCategory,
+)
 from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
+from crewai.task import Task
 from crewai.tasks.task_output import TaskOutput
 
+
 class ReasoningPatternType(Enum):
     EFFICIENT = "efficient"  # Good reasoning flow
     LOOP = "loop"  # Agent is stuck in a loop
@@ -35,8 +41,8 @@ class ReasoningEfficiencyEvaluator(BaseEvaluator):
 
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: TaskOutput | str,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -49,7 +55,7 @@ class ReasoningEfficiencyEvaluator(BaseEvaluator):
         if not llm_calls or len(llm_calls) < 2:
             return EvaluationScore(
                 score=None,
-                feedback="Insufficient LLM calls to evaluate reasoning efficiency."
+                feedback="Insufficient LLM calls to evaluate reasoning efficiency.",
             )
 
         total_calls = len(llm_calls)
@@ -58,12 +64,16 @@ class ReasoningEfficiencyEvaluator(BaseEvaluator):
         time_intervals = []
         has_reliable_timing = True
         for i in range(1, len(llm_calls)):
-            start_time = llm_calls[i-1].get("end_time")
+            start_time = llm_calls[i - 1].get("end_time")
             end_time = llm_calls[i].get("start_time")
             if start_time and end_time and start_time != end_time:
                 try:
                     interval = end_time - start_time
-                    time_intervals.append(interval.total_seconds() if hasattr(interval, 'total_seconds') else 0)
+                    time_intervals.append(
+                        interval.total_seconds()
+                        if hasattr(interval, "total_seconds")
+                        else 0
+                    )
                 except Exception:
                     has_reliable_timing = False
             else:
@@ -83,14 +93,22 @@ class ReasoningEfficiencyEvaluator(BaseEvaluator):
         if has_reliable_timing and time_intervals:
             efficiency_metrics["avg_time_between_calls"] = np.mean(time_intervals)
 
-        loop_info = f"Detected {len(loop_details)} potential reasoning loops." if loop_detected else "No significant reasoning loops detected."
+        loop_info = (
+            f"Detected {len(loop_details)} potential reasoning loops."
+            if loop_detected
+            else "No significant reasoning loops detected."
+        )
 
         call_samples = self._get_call_samples(llm_calls)
 
-        final_output = final_output.raw if isinstance(final_output, TaskOutput) else final_output
+        final_output = (
+            final_output.raw if isinstance(final_output, TaskOutput) else final_output
+        )
 
         prompt = [
-            {"role": "system", "content": """You are an expert evaluator assessing the reasoning efficiency of an AI agent's thought process.
+            {
+                "role": "system",
+                "content": """You are an expert evaluator assessing the reasoning efficiency of an AI agent's thought process.
 
 Evaluate the agent's reasoning efficiency across these five key subcategories:
 
@@ -120,8 +138,11 @@ Return your evaluation as JSON with the following structure:
     "feedback": string (general feedback about overall reasoning efficiency),
     "optimization_suggestions": string (concrete suggestions for improving reasoning efficiency),
     "detected_patterns": string (describe any inefficient reasoning patterns you observe)
-}"""},
-            {"role": "user", "content": f"""
+}""",
+            },
+            {
+                "role": "user",
+                "content": f"""
 Agent role: {agent.role}
 {task_context}
 
@@ -140,10 +161,12 @@ Agent's final output:
 
 Evaluate the reasoning efficiency of this agent based on these interaction patterns.
 Identify any inefficient reasoning patterns and provide specific suggestions for optimization.
-"""}
+""",
+            },
         ]
 
-        assert self.llm is not None
+        if self.llm is None:
+            raise ValueError("LLM must be initialized")
         response = self.llm.call(prompt)
 
         try:
@@ -156,34 +179,46 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
             conciseness = scores.get("conciseness", 5.0)
             loop_avoidance = scores.get("loop_avoidance", 5.0)
 
-            overall_score = evaluation_data.get("overall_score", evaluation_data.get("score", 5.0))
+            overall_score = evaluation_data.get(
+                "overall_score", evaluation_data.get("score", 5.0)
+            )
             feedback = evaluation_data.get("feedback", "No detailed feedback provided.")
-            optimization_suggestions = evaluation_data.get("optimization_suggestions", "No specific suggestions provided.")
+            optimization_suggestions = evaluation_data.get(
+                "optimization_suggestions", "No specific suggestions provided."
+            )
 
             detailed_feedback = "Reasoning Efficiency Evaluation:\n"
-            detailed_feedback += f"• Focus: {focus}/10 - Staying on topic without tangents\n"
-            detailed_feedback += f"• Progression: {progression}/10 - Building on previous thinking\n"
+            detailed_feedback += (
+                f"• Focus: {focus}/10 - Staying on topic without tangents\n"
+            )
+            detailed_feedback += (
+                f"• Progression: {progression}/10 - Building on previous thinking\n"
+            )
             detailed_feedback += f"• Decision Quality: {decision_quality}/10 - Making appropriate decisions\n"
-            detailed_feedback += f"• Conciseness: {conciseness}/10 - Communicating efficiently\n"
+            detailed_feedback += (
+                f"• Conciseness: {conciseness}/10 - Communicating efficiently\n"
+            )
             detailed_feedback += f"• Loop Avoidance: {loop_avoidance}/10 - Avoiding repetitive patterns\n\n"
 
             detailed_feedback += f"Feedback:\n{feedback}\n\n"
-            detailed_feedback += f"Optimization Suggestions:\n{optimization_suggestions}"
+            detailed_feedback += (
+                f"Optimization Suggestions:\n{optimization_suggestions}"
+            )
 
             return EvaluationScore(
                 score=float(overall_score),
                 feedback=detailed_feedback,
-                raw_response=response
+                raw_response=response,
             )
         except Exception as e:
             logging.warning(f"Failed to parse reasoning efficiency evaluation: {e}")
             return EvaluationScore(
                 score=None,
                 feedback=f"Failed to parse reasoning efficiency evaluation. Raw response: {response[:200]}...",
-                raw_response=response
+                raw_response=response,
             )
 
-    def _detect_loops(self, llm_calls: List[Dict]) -> Tuple[bool, List[Dict]]:
+    def _detect_loops(self, llm_calls: list[dict]) -> tuple[bool, list[dict]]:
         loop_details = []
 
         messages = []
@@ -193,9 +228,11 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
                 messages.append(content)
             elif isinstance(content, list) and len(content) > 0:
                 # Handle message list format
-                for msg in content:
-                    if isinstance(msg, dict) and "content" in msg:
-                        messages.append(msg["content"])
+                messages.extend(
+                    msg["content"]
+                    for msg in content
+                    if isinstance(msg, dict) and "content" in msg
+                )
 
         # Simple n-gram based similarity detection
         # For a more robust implementation, consider using embedding-based similarity
@@ -205,18 +242,20 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
                 # A more sophisticated approach would use semantic similarity
                 similarity = self._calculate_text_similarity(messages[i], messages[j])
                 if similarity > 0.7:  # Arbitrary threshold
-                    loop_details.append({
-                        "first_occurrence": i,
-                        "second_occurrence": j,
-                        "similarity": similarity,
-                        "snippet": messages[i][:100] + "..."
-                    })
+                    loop_details.append(
+                        {
+                            "first_occurrence": i,
+                            "second_occurrence": j,
+                            "similarity": similarity,
+                            "snippet": messages[i][:100] + "...",
+                        }
+                    )
 
         return len(loop_details) > 0, loop_details
 
     def _calculate_text_similarity(self, text1: str, text2: str) -> float:
-        text1 = re.sub(r'\s+', ' ', text1.lower()).strip()
-        text2 = re.sub(r'\s+', ' ', text2.lower()).strip()
+        text1 = re.sub(r"\s+", " ", text1.lower()).strip()
+        text2 = re.sub(r"\s+", " ", text2.lower()).strip()
 
         # Simple Jaccard similarity on word sets
         words1 = set(text1.split())
@@ -227,7 +266,7 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
 
         return intersection / union if union > 0 else 0.0
 
-    def _analyze_reasoning_patterns(self, llm_calls: List[Dict]) -> Dict[str, Any]:
+    def _analyze_reasoning_patterns(self, llm_calls: list[dict]) -> dict[str, Any]:
         call_lengths = []
         response_times = []
 
@@ -248,8 +287,8 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
             if start_time and end_time:
                 try:
                     response_times.append(end_time - start_time)
-                except Exception:
-                    pass
+                except Exception as e:
+                    logging.debug(f"Failed to calculate response time: {e}")
 
         avg_length = np.mean(call_lengths) if call_lengths else 0
         std_length = np.std(call_lengths) if call_lengths else 0
@@ -267,7 +306,9 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
             details = "Agent is consistently verbose across interactions."
         elif len(llm_calls) > 10 and length_trend > 0.5:
             primary_pattern = ReasoningPatternType.INDECISIVE
-            details = "Agent shows signs of indecisiveness with increasing message lengths."
+            details = (
+                "Agent shows signs of indecisiveness with increasing message lengths."
+            )
         elif std_length / avg_length > 0.8:
             primary_pattern = ReasoningPatternType.SCATTERED
             details = "Agent shows inconsistent reasoning flow with highly variable responses."
@@ -279,8 +320,8 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
                 "avg_length": avg_length,
                 "std_length": std_length,
                 "length_trend": length_trend,
-                "loop_score": loop_score
-            }
+                "loop_score": loop_score,
+            },
         }
 
     def _calculate_trend(self, values: Sequence[float | int]) -> float:
@@ -303,7 +344,9 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
         except Exception:
             return 0.0
 
-    def _calculate_loop_likelihood(self, call_lengths: Sequence[float], response_times: Sequence[float]) -> float:
+    def _calculate_loop_likelihood(
+        self, call_lengths: Sequence[float], response_times: Sequence[float]
+    ) -> float:
         if not call_lengths or len(call_lengths) < 3:
             return 0.0
 
@@ -312,7 +355,11 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
         if len(call_lengths) >= 4:
             repeated_lengths = 0
             for i in range(len(call_lengths) - 2):
-                ratio = call_lengths[i] / call_lengths[i + 2] if call_lengths[i + 2] > 0 else 0
+                ratio = (
+                    call_lengths[i] / call_lengths[i + 2]
+                    if call_lengths[i + 2] > 0
+                    else 0
+                )
                 if 0.85 <= ratio <= 1.15:
                     repeated_lengths += 1
 
@@ -324,21 +371,27 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
                 std_time = np.std(response_times)
                 mean_time = np.mean(response_times)
                 if mean_time > 0:
-                    time_consistency = 1.0 - (std_time / mean_time)
-                    indicators.append(max(0, time_consistency - 0.3) * 1.5)
-            except Exception:
-                pass
+                    time_consistency = 1.0 - (float(std_time) / float(mean_time))
+                    indicators.append(max(0.0, float(time_consistency - 0.3)) * 1.5)
+            except Exception as e:
+                logging.debug(f"Time consistency calculation failed: {e}")
 
-        return np.mean(indicators) if indicators else 0.0
+        return float(np.mean(indicators)) if indicators else 0.0
 
-    def _get_call_samples(self, llm_calls: List[Dict]) -> str:
+    def _get_call_samples(self, llm_calls: list[dict]) -> str:
         samples = []
 
         if len(llm_calls) <= 6:
             sample_indices = list(range(len(llm_calls)))
         else:
-            sample_indices = [0, 1, len(llm_calls) // 2 - 1, len(llm_calls) // 2,
-                             len(llm_calls) - 2, len(llm_calls) - 1]
+            sample_indices = [
+                0,
+                1,
+                len(llm_calls) // 2 - 1,
+                len(llm_calls) // 2,
+                len(llm_calls) - 2,
+                len(llm_calls) - 1,
+            ]
 
         for idx in sample_indices:
             call = llm_calls[idx]
@@ -347,10 +400,11 @@ Identify any inefficient reasoning patterns and provide specific suggestions for
             if isinstance(content, str):
                 sample = content
             elif isinstance(content, list) and len(content) > 0:
-                sample_parts = []
-                for msg in content:
-                    if isinstance(msg, dict) and "content" in msg:
-                        sample_parts.append(msg["content"])
+                sample_parts = [
+                    msg["content"]
+                    for msg in content
+                    if isinstance(msg, dict) and "content" in msg
+                ]
                 sample = "\n".join(sample_parts)
             else:
                 sample = str(content)

src/crewai/experimental/evaluation/metrics/semantic_quality_metrics.py

@@ -1,10 +1,15 @@
-from typing import Any, Dict
+from typing import Any
 
 from crewai.agent import Agent
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.experimental.evaluation.base_evaluator import (
+    BaseEvaluator,
+    EvaluationScore,
+    MetricCategory,
+)
+from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
 from crewai.task import Task
 
-from crewai.experimental.evaluation.base_evaluator import BaseEvaluator, EvaluationScore, MetricCategory
-from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
 
 class SemanticQualityEvaluator(BaseEvaluator):
     @property
@@ -13,8 +18,8 @@ class SemanticQualityEvaluator(BaseEvaluator):
 
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: Any,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -22,7 +27,9 @@ class SemanticQualityEvaluator(BaseEvaluator):
         if task is not None:
             task_context = f"Task description: {task.description}"
         prompt = [
-            {"role": "system", "content": """You are an expert evaluator assessing the semantic quality of an AI agent's output.
+            {
+                "role": "system",
+                "content": """You are an expert evaluator assessing the semantic quality of an AI agent's output.
 
 Score the semantic quality on a scale from 0-10 where:
 - 0: Completely incoherent, confusing, or logically flawed output
@@ -37,8 +44,11 @@ Consider:
 5. Is the output free from contradictions and logical fallacies?
 
 Return your evaluation as JSON with fields 'score' (number) and 'feedback' (string).
-"""},
-            {"role": "user", "content": f"""
+""",
+            },
+            {
+                "role": "user",
+                "content": f"""
 Agent role: {agent.role}
 {task_context}
 
@@ -46,23 +56,28 @@ Agent's final output:
 {final_output}
 
 Evaluate the semantic quality and reasoning of this output.
-"""}
+""",
+            },
         ]
 
-        assert self.llm is not None
+        if self.llm is None:
+            raise ValueError("LLM must be initialized")
         response = self.llm.call(prompt)
 
         try:
             evaluation_data: dict[str, Any] = extract_json_from_llm_response(response)
-            assert evaluation_data is not None
+            if evaluation_data is None:
+                raise ValueError("Failed to extract evaluation data from LLM response")
             return EvaluationScore(
-                score=float(evaluation_data["score"]) if evaluation_data.get("score") is not None else None,
+                score=float(evaluation_data["score"])
+                if evaluation_data.get("score") is not None
+                else None,
                 feedback=evaluation_data.get("feedback", response),
-                raw_response=response
+                raw_response=response,
             )
         except Exception:
             return EvaluationScore(
                 score=None,
                 feedback=f"Failed to parse evaluation. Raw response: {response}",
-                raw_response=response
-            )
+                raw_response=response,
+            )

src/crewai/experimental/evaluation/metrics/tools_metrics.py

@@ -1,22 +1,26 @@
 import json
-from typing import Dict, Any
+from typing import Any
 
-from crewai.experimental.evaluation.base_evaluator import BaseEvaluator, EvaluationScore, MetricCategory
-from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
 from crewai.agent import Agent
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.experimental.evaluation.base_evaluator import (
+    BaseEvaluator,
+    EvaluationScore,
+    MetricCategory,
+)
+from crewai.experimental.evaluation.json_parser import extract_json_from_llm_response
 from crewai.task import Task
 
 
 class ToolSelectionEvaluator(BaseEvaluator):
-
     @property
     def metric_category(self) -> MetricCategory:
         return MetricCategory.TOOL_SELECTION
 
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: str,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -26,19 +30,18 @@ class ToolSelectionEvaluator(BaseEvaluator):
 
         tool_uses = execution_trace.get("tool_uses", [])
         tool_count = len(tool_uses)
-        unique_tool_types = set([tool.get("tool", "Unknown tool") for tool in tool_uses])
+        unique_tool_types = set(
+            [tool.get("tool", "Unknown tool") for tool in tool_uses]
+        )
 
         if tool_count == 0:
             if not agent.tools:
                 return EvaluationScore(
-                    score=None,
-                    feedback="Agent had no tools available to use."
-                )
-            else:
-                return EvaluationScore(
-                    score=None,
-                    feedback="Agent had tools available but didn't use any."
+                    score=None, feedback="Agent had no tools available to use."
                 )
+            return EvaluationScore(
+                score=None, feedback="Agent had tools available but didn't use any."
+            )
 
         available_tools_info = ""
         if agent.tools:
@@ -52,7 +55,9 @@ class ToolSelectionEvaluator(BaseEvaluator):
             tool_types_summary += f"- {tool_type}\n"
 
         prompt = [
-            {"role": "system", "content": """You are an expert evaluator assessing if an AI agent selected the most appropriate tools for a given task.
+            {
+                "role": "system",
+                "content": """You are an expert evaluator assessing if an AI agent selected the most appropriate tools for a given task.
 
 You must evaluate based on these 2 criteria:
 1. Relevance (0-10): Were the tools chosen directly aligned with the task's goals?
@@ -73,8 +78,11 @@ Return your evaluation as JSON with these fields:
 - overall_score: number (average of all scores, 0-10)
 - feedback: string (focused ONLY on tool selection decisions from available tools)
 - improvement_suggestions: string (ONLY suggest better selection from the AVAILABLE tools list, NOT new tools)
-"""},
-            {"role": "user", "content": f"""
+""",
+            },
+            {
+                "role": "user",
+                "content": f"""
 Agent role: {agent.role}
 {task_context}
 
@@ -89,14 +97,17 @@ IMPORTANT:
 - ONLY evaluate selection from tools listed as available
 - DO NOT suggest new tools that aren't in the available tools list
 - DO NOT evaluate tool usage or results
-"""}
+""",
+            },
         ]
-        assert self.llm is not None
+        if self.llm is None:
+            raise ValueError("LLM must be initialized")
         response = self.llm.call(prompt)
 
         try:
             evaluation_data = extract_json_from_llm_response(response)
-            assert evaluation_data is not None
+            if evaluation_data is None:
+                raise ValueError("Failed to extract evaluation data from LLM response")
 
             scores = evaluation_data.get("scores", {})
             relevance = scores.get("relevance", 5.0)
@@ -105,22 +116,24 @@ IMPORTANT:
 
             feedback = "Tool Selection Evaluation:\n"
             feedback += f"• Relevance: {relevance}/10 - Selection of appropriate tool types for the task\n"
-            feedback += f"• Coverage: {coverage}/10 - Selection of all necessary tool types\n"
+            feedback += (
+                f"• Coverage: {coverage}/10 - Selection of all necessary tool types\n"
+            )
             if "improvement_suggestions" in evaluation_data:
                 feedback += f"Improvement Suggestions:\n{evaluation_data['improvement_suggestions']}"
             else:
-                feedback += evaluation_data.get("feedback", "No detailed feedback available.")
+                feedback += evaluation_data.get(
+                    "feedback", "No detailed feedback available."
+                )
 
             return EvaluationScore(
-                score=overall_score,
-                feedback=feedback,
-                raw_response=response
+                score=overall_score, feedback=feedback, raw_response=response
             )
         except Exception as e:
             return EvaluationScore(
                 score=None,
                 feedback=f"Error evaluating tool selection: {e}",
-                raw_response=response
+                raw_response=response,
             )
 
 
@@ -131,8 +144,8 @@ class ParameterExtractionEvaluator(BaseEvaluator):
 
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: str,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -145,19 +158,23 @@ class ParameterExtractionEvaluator(BaseEvaluator):
         if tool_count == 0:
             return EvaluationScore(
                 score=None,
-                feedback="No tool usage detected. Cannot evaluate parameter extraction."
+                feedback="No tool usage detected. Cannot evaluate parameter extraction.",
             )
 
-        validation_errors = []
-        for tool_use in tool_uses:
-            if not tool_use.get("success", True) and tool_use.get("error_type") == "validation_error":
-                validation_errors.append({
-                    "tool": tool_use.get("tool", "Unknown tool"),
-                    "error": tool_use.get("result"),
-                    "args": tool_use.get("args", {})
-                })
+        validation_errors = [
+            {
+                "tool": tool_use.get("tool", "Unknown tool"),
+                "error": tool_use.get("result"),
+                "args": tool_use.get("args", {}),
+            }
+            for tool_use in tool_uses
+            if not tool_use.get("success", True)
+            and tool_use.get("error_type") == "validation_error"
+        ]
 
-        validation_error_rate = len(validation_errors) / tool_count if tool_count > 0 else 0
+        validation_error_rate = (
+            len(validation_errors) / tool_count if tool_count > 0 else 0
+        )
 
         param_samples = []
         for i, tool_use in enumerate(tool_uses[:5]):
@@ -168,7 +185,7 @@ class ParameterExtractionEvaluator(BaseEvaluator):
 
             is_validation_error = error_type == "validation_error"
 
-            sample = f"Tool use #{i+1} - {tool_name}:\n"
+            sample = f"Tool use #{i + 1} - {tool_name}:\n"
             sample += f"- Parameters: {json.dumps(tool_args, indent=2)}\n"
             sample += f"- Success: {'No' if not success else 'Yes'}"
 
@@ -187,13 +204,17 @@ class ParameterExtractionEvaluator(BaseEvaluator):
                 tool_name = err.get("tool", "Unknown tool")
                 error_msg = err.get("error", "Unknown error")
                 args = err.get("args", {})
-                validation_errors_info += f"\nValidation Error #{i+1}:\n- Tool: {tool_name}\n- Args: {json.dumps(args, indent=2)}\n- Error: {error_msg}"
+                validation_errors_info += f"\nValidation Error #{i + 1}:\n- Tool: {tool_name}\n- Args: {json.dumps(args, indent=2)}\n- Error: {error_msg}"
 
             if len(validation_errors) > 3:
-                validation_errors_info += f"\n...and {len(validation_errors) - 3} more validation errors."
+                validation_errors_info += (
+                    f"\n...and {len(validation_errors) - 3} more validation errors."
+                )
         param_samples_text = "\n\n".join(param_samples)
         prompt = [
-            {"role": "system", "content": """You are an expert evaluator assessing how well an AI agent extracts and formats PARAMETER VALUES for tool calls.
+            {
+                "role": "system",
+                "content": """You are an expert evaluator assessing how well an AI agent extracts and formats PARAMETER VALUES for tool calls.
 
 Your job is to evaluate ONLY whether the agent used the correct parameter VALUES, not whether the right tools were selected or how the tools were invoked.
 
@@ -216,8 +237,11 @@ Return your evaluation as JSON with these fields:
 - overall_score: number (average of all scores, 0-10)
 - feedback: string (focused ONLY on parameter value extraction quality)
 - improvement_suggestions: string (concrete suggestions for better parameter VALUE extraction)
-"""},
-            {"role": "user", "content": f"""
+""",
+            },
+            {
+                "role": "user",
+                "content": f"""
 Agent role: {agent.role}
 {task_context}
 
@@ -226,15 +250,18 @@ Parameter extraction examples:
 {validation_errors_info}
 
 Evaluate the quality of the agent's parameter extraction for this task.
-"""}
+""",
+            },
         ]
 
-        assert self.llm is not None
+        if self.llm is None:
+            raise ValueError("LLM must be initialized")
         response = self.llm.call(prompt)
 
         try:
             evaluation_data = extract_json_from_llm_response(response)
-            assert evaluation_data is not None
+            if evaluation_data is None:
+                raise ValueError("Failed to extract evaluation data from LLM response")
 
             scores = evaluation_data.get("scores", {})
             accuracy = scores.get("accuracy", 5.0)
@@ -251,18 +278,18 @@ Evaluate the quality of the agent's parameter extraction for this task.
             if "improvement_suggestions" in evaluation_data:
                 feedback += f"Improvement Suggestions:\n{evaluation_data['improvement_suggestions']}"
             else:
-                feedback += evaluation_data.get("feedback", "No detailed feedback available.")
+                feedback += evaluation_data.get(
+                    "feedback", "No detailed feedback available."
+                )
 
             return EvaluationScore(
-                score=overall_score,
-                feedback=feedback,
-                raw_response=response
+                score=overall_score, feedback=feedback, raw_response=response
             )
         except Exception as e:
             return EvaluationScore(
                 score=None,
                 feedback=f"Error evaluating parameter extraction: {e}",
-                raw_response=response
+                raw_response=response,
             )
 
 
@@ -273,8 +300,8 @@ class ToolInvocationEvaluator(BaseEvaluator):
 
     def evaluate(
         self,
-        agent: Agent,
-        execution_trace: Dict[str, Any],
+        agent: Agent | BaseAgent,
+        execution_trace: dict[str, Any],
         final_output: str,
         task: Task | None = None,
     ) -> EvaluationScore:
@@ -288,7 +315,7 @@ class ToolInvocationEvaluator(BaseEvaluator):
         if tool_count == 0:
             return EvaluationScore(
                 score=None,
-                feedback="No tool usage detected. Cannot evaluate tool invocation."
+                feedback="No tool usage detected. Cannot evaluate tool invocation.",
             )
 
         for tool_use in tool_uses:
@@ -296,7 +323,7 @@ class ToolInvocationEvaluator(BaseEvaluator):
                 error_info = {
                     "tool": tool_use.get("tool", "Unknown tool"),
                     "error": tool_use.get("result"),
-                    "error_type": tool_use.get("error_type", "unknown_error")
+                    "error_type": tool_use.get("error_type", "unknown_error"),
                 }
                 tool_errors.append(error_info)
 
@@ -315,9 +342,11 @@ class ToolInvocationEvaluator(BaseEvaluator):
             tool_args = tool_use.get("args", {})
             success = tool_use.get("success", True) and not tool_use.get("error", False)
             error_type = tool_use.get("error_type", "") if not success else ""
-            error_msg = tool_use.get("result", "No error") if not success else "No error"
+            error_msg = (
+                tool_use.get("result", "No error") if not success else "No error"
+            )
 
-            sample = f"Tool invocation #{i+1}:\n"
+            sample = f"Tool invocation #{i + 1}:\n"
             sample += f"- Tool: {tool_name}\n"
             sample += f"- Parameters: {json.dumps(tool_args, indent=2)}\n"
             sample += f"- Success: {'No' if not success else 'Yes'}\n"
@@ -330,11 +359,13 @@ class ToolInvocationEvaluator(BaseEvaluator):
         if error_types:
             error_type_summary = "Error type breakdown:\n"
             for error_type, count in error_types.items():
-                error_type_summary += f"- {error_type}: {count} occurrences ({(count/tool_count):.1%})\n"
+                error_type_summary += f"- {error_type}: {count} occurrences ({(count / tool_count):.1%})\n"
 
         invocation_samples_text = "\n\n".join(invocation_samples)
         prompt = [
-            {"role": "system", "content": """You are an expert evaluator assessing how correctly an AI agent's tool invocations are STRUCTURED.
+            {
+                "role": "system",
+                "content": """You are an expert evaluator assessing how correctly an AI agent's tool invocations are STRUCTURED.
 
 Your job is to evaluate ONLY the structural and syntactical aspects of how the agent called tools, NOT which tools were selected or what parameter values were used.
 
@@ -359,8 +390,11 @@ Return your evaluation as JSON with these fields:
 - overall_score: number (average of all scores, 0-10)
 - feedback: string (focused ONLY on structural aspects of tool invocation)
 - improvement_suggestions: string (concrete suggestions for better structuring of tool calls)
-"""},
-            {"role": "user", "content": f"""
+""",
+            },
+            {
+                "role": "user",
+                "content": f"""
 Agent role: {agent.role}
 {task_context}
 
@@ -371,15 +405,18 @@ Tool error rate: {error_rate:.2%} ({len(tool_errors)} errors out of {tool_count}
 {error_type_summary}
 
 Evaluate the quality of the agent's tool invocation structure during this task.
-"""}
+""",
+            },
         ]
 
-        assert self.llm is not None
+        if self.llm is None:
+            raise ValueError("LLM must be initialized")
         response = self.llm.call(prompt)
 
         try:
             evaluation_data = extract_json_from_llm_response(response)
-            assert evaluation_data is not None
+            if evaluation_data is None:
+                raise ValueError("Failed to extract evaluation data from LLM response")
             scores = evaluation_data.get("scores", {})
             structure = scores.get("structure", 5.0)
             error_handling = scores.get("error_handling", 5.0)
@@ -388,23 +425,25 @@ Evaluate the quality of the agent's tool invocation structure during this task.
             overall_score = float(evaluation_data.get("overall_score", 5.0))
 
             feedback = "Tool Invocation Evaluation:\n"
-            feedback += f"• Structure: {structure}/10 - Following proper syntax and format\n"
+            feedback += (
+                f"• Structure: {structure}/10 - Following proper syntax and format\n"
+            )
             feedback += f"• Error Handling: {error_handling}/10 - Appropriately handling tool errors\n"
             feedback += f"• Invocation Patterns: {invocation_patterns}/10 - Proper sequencing and management of calls\n\n"
 
             if "improvement_suggestions" in evaluation_data:
                 feedback += f"Improvement Suggestions:\n{evaluation_data['improvement_suggestions']}"
             else:
-                feedback += evaluation_data.get("feedback", "No detailed feedback available.")
+                feedback += evaluation_data.get(
+                    "feedback", "No detailed feedback available."
+                )
 
             return EvaluationScore(
-                score=overall_score,
-                feedback=feedback,
-                raw_response=response
+                score=overall_score, feedback=feedback, raw_response=response
             )
         except Exception as e:
             return EvaluationScore(
                 score=None,
                 feedback=f"Error evaluating tool invocation: {e}",
-                raw_response=response
+                raw_response=response,
             )

src/crewai/experimental/evaluation/testing.py

@@ -1,12 +1,21 @@
 import inspect
+import warnings
 
 from typing_extensions import Any
-import warnings
-from crewai.experimental.evaluation.experiment import ExperimentResults, ExperimentRunner
-from crewai import Crew, Agent
 
-def assert_experiment_successfully(experiment_results: ExperimentResults, baseline_filepath: str | None = None) -> None:
-    failed_tests = [result for result in experiment_results.results if not result.passed]
+from crewai import Agent, Crew
+from crewai.experimental.evaluation.experiment import (
+    ExperimentResults,
+    ExperimentRunner,
+)
+
+
+def assert_experiment_successfully(
+    experiment_results: ExperimentResults, baseline_filepath: str | None = None
+) -> None:
+    failed_tests = [
+        result for result in experiment_results.results if not result.passed
+    ]
 
     if failed_tests:
         detailed_failures: list[str] = []
@@ -14,39 +23,54 @@ def assert_experiment_successfully(experiment_results: ExperimentResults, baseli
         for result in failed_tests:
             expected = result.expected_score
             actual = result.score
-            detailed_failures.append(f"- {result.identifier}: expected {expected}, got {actual}")
+            detailed_failures.append(
+                f"- {result.identifier}: expected {expected}, got {actual}"
+            )
 
         failure_details = "\n".join(detailed_failures)
         raise AssertionError(f"The following test cases failed:\n{failure_details}")
 
     baseline_filepath = baseline_filepath or _get_baseline_filepath_fallback()
-    comparison = experiment_results.compare_with_baseline(baseline_filepath=baseline_filepath)
+    comparison = experiment_results.compare_with_baseline(
+        baseline_filepath=baseline_filepath
+    )
     assert_experiment_no_regression(comparison)
 
+
 def assert_experiment_no_regression(comparison_result: dict[str, list[str]]) -> None:
     regressed = comparison_result.get("regressed", [])
     if regressed:
-        raise AssertionError(f"Regression detected! The following tests that previously passed now fail: {regressed}")
+        raise AssertionError(
+            f"Regression detected! The following tests that previously passed now fail: {regressed}"
+        )
 
     missing_tests = comparison_result.get("missing_tests", [])
     if missing_tests:
         warnings.warn(
             f"Warning: {len(missing_tests)} tests from the baseline are missing in the current run: {missing_tests}",
-            UserWarning
+            UserWarning,
+            stacklevel=2,
         )
 
-def run_experiment(dataset: list[dict[str, Any]], crew: Crew | None = None, agents: list[Agent] | None = None, verbose: bool = False) -> ExperimentResults:
+
+def run_experiment(
+    dataset: list[dict[str, Any]],
+    crew: Crew | None = None,
+    agents: list[Agent] | None = None,
+    verbose: bool = False,
+) -> ExperimentResults:
     runner = ExperimentRunner(dataset=dataset)
 
     return runner.run(agents=agents, crew=crew, print_summary=verbose)
 
+
 def _get_baseline_filepath_fallback() -> str:
     test_func_name = "experiment_fallback"
 
     try:
         current_frame = inspect.currentframe()
         if current_frame is not None:
-            test_func_name = current_frame.f_back.f_back.f_code.co_name # type: ignore[union-attr]
+            test_func_name = current_frame.f_back.f_back.f_code.co_name  # type: ignore[union-attr]
     except Exception:
         ...
-    return f"{test_func_name}_results.json"
+    return f"{test_func_name}_results.json"

src/crewai/flow/__init__.py

@@ -1,5 +1,4 @@
-from crewai.flow.flow import Flow, start, listen, or_, and_, router
+from crewai.flow.flow import Flow, and_, listen, or_, router, start
 from crewai.flow.persistence import persist
 
-__all__ = ["Flow", "start", "listen", "or_", "and_", "router", "persist"]
-
+__all__ = ["Flow", "and_", "listen", "or_", "persist", "router", "start"]

src/crewai/flow/flow.py

@@ -2,30 +2,22 @@ import asyncio
 import copy
 import inspect
 import logging
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    Generic,
-    List,
-    Optional,
-    Set,
-    Type,
-    TypeVar,
-    Union,
-    cast,
-)
+from collections.abc import Callable
+from typing import Any, ClassVar, Generic, TypeVar, cast
 from uuid import uuid4
 
 from opentelemetry import baggage
 from opentelemetry.context import attach, detach
 from pydantic import BaseModel, Field, ValidationError
 
-from crewai.flow.flow_visualizer import plot_flow
-from crewai.flow.persistence.base import FlowPersistence
-from crewai.flow.types import FlowExecutionData
-from crewai.flow.utils import get_possible_return_constants
 from crewai.events.event_bus import crewai_event_bus
+from crewai.events.listeners.tracing.trace_listener import (
+    TraceCollectionListener,
+)
+from crewai.events.listeners.tracing.utils import (
+    is_tracing_enabled,
+    should_auto_collect_first_time_traces,
+)
 from crewai.events.types.flow_events import (
     FlowCreatedEvent,
     FlowFinishedEvent,
@@ -35,12 +27,10 @@ from crewai.events.types.flow_events import (
     MethodExecutionFinishedEvent,
     MethodExecutionStartedEvent,
 )
-from crewai.events.listeners.tracing.trace_listener import (
-    TraceCollectionListener,
-)
-from crewai.events.listeners.tracing.utils import (
-    is_tracing_enabled,
-)
+from crewai.flow.flow_visualizer import plot_flow
+from crewai.flow.persistence.base import FlowPersistence
+from crewai.flow.types import FlowExecutionData
+from crewai.flow.utils import get_possible_return_constants
 from crewai.utilities.printer import Printer
 
 logger = logging.getLogger(__name__)
@@ -55,16 +45,14 @@ class FlowState(BaseModel):
     )
 
 
-# Type variables with explicit bounds
-T = TypeVar(
-    "T", bound=Union[Dict[str, Any], BaseModel]
-)  # Generic flow state type parameter
+# type variables with explicit bounds
+T = TypeVar("T", bound=dict[str, Any] | BaseModel)  # Generic flow state type parameter
 StateT = TypeVar(
-    "StateT", bound=Union[Dict[str, Any], BaseModel]
+    "StateT", bound=dict[str, Any] | BaseModel
 )  # State validation type parameter
 
 
-def ensure_state_type(state: Any, expected_type: Type[StateT]) -> StateT:
+def ensure_state_type(state: Any, expected_type: type[StateT]) -> StateT:
     """Ensure state matches expected type with proper validation.
 
     Args:
@@ -104,7 +92,7 @@ def ensure_state_type(state: Any, expected_type: Type[StateT]) -> StateT:
     raise TypeError(f"Invalid expected_type: {expected_type}")
 
 
-def start(condition: Optional[Union[str, dict, Callable]] = None) -> Callable:
+def start(condition: str | dict | Callable | None = None) -> Callable:
     """
     Marks a method as a flow's starting point.
 
@@ -171,7 +159,7 @@ def start(condition: Optional[Union[str, dict, Callable]] = None) -> Callable:
     return decorator
 
 
-def listen(condition: Union[str, dict, Callable]) -> Callable:
+def listen(condition: str | dict | Callable) -> Callable:
     """
     Creates a listener that executes when specified conditions are met.
 
@@ -231,7 +219,7 @@ def listen(condition: Union[str, dict, Callable]) -> Callable:
     return decorator
 
 
-def router(condition: Union[str, dict, Callable]) -> Callable:
+def router(condition: str | dict | Callable) -> Callable:
     """
     Creates a routing method that directs flow execution based on conditions.
 
@@ -297,7 +285,7 @@ def router(condition: Union[str, dict, Callable]) -> Callable:
     return decorator
 
 
-def or_(*conditions: Union[str, dict, Callable]) -> dict:
+def or_(*conditions: str | dict | Callable) -> dict:
     """
     Combines multiple conditions with OR logic for flow control.
 
@@ -343,7 +331,7 @@ def or_(*conditions: Union[str, dict, Callable]) -> dict:
     return {"type": "OR", "methods": methods}
 
 
-def and_(*conditions: Union[str, dict, Callable]) -> dict:
+def and_(*conditions: str | dict | Callable) -> dict:
     """
     Combines multiple conditions with AND logic for flow control.
 
@@ -425,10 +413,10 @@ class FlowMeta(type):
                         if possible_returns:
                             router_paths[attr_name] = possible_returns
 
-        setattr(cls, "_start_methods", start_methods)
-        setattr(cls, "_listeners", listeners)
-        setattr(cls, "_routers", routers)
-        setattr(cls, "_router_paths", router_paths)
+        cls._start_methods = start_methods
+        cls._listeners = listeners
+        cls._routers = routers
+        cls._router_paths = router_paths
 
         return cls
 
@@ -436,29 +424,29 @@ class FlowMeta(type):
 class Flow(Generic[T], metaclass=FlowMeta):
     """Base class for all flows.
 
-    Type parameter T must be either Dict[str, Any] or a subclass of BaseModel."""
+    type parameter T must be either dict[str, Any] or a subclass of BaseModel."""
 
     _printer = Printer()
 
-    _start_methods: List[str] = []
-    _listeners: Dict[str, tuple[str, List[str]]] = {}
-    _routers: Set[str] = set()
-    _router_paths: Dict[str, List[str]] = {}
-    initial_state: Union[Type[T], T, None] = None
-    name: Optional[str] = None
-    tracing: Optional[bool] = False
+    _start_methods: ClassVar[list[str]] = []
+    _listeners: ClassVar[dict[str, tuple[str, list[str]]]] = {}
+    _routers: ClassVar[set[str]] = set()
+    _router_paths: ClassVar[dict[str, list[str]]] = {}
+    initial_state: type[T] | T | None = None
+    name: str | None = None
+    tracing: bool | None = False
 
-    def __class_getitem__(cls: Type["Flow"], item: Type[T]) -> Type["Flow"]:
+    def __class_getitem__(cls: type["Flow"], item: type[T]) -> type["Flow"]:
         class _FlowGeneric(cls):  # type: ignore
-            _initial_state_T = item  # type: ignore
+            _initial_state_t = item  # type: ignore
 
         _FlowGeneric.__name__ = f"{cls.__name__}[{item.__name__}]"
         return _FlowGeneric
 
     def __init__(
         self,
-        persistence: Optional[FlowPersistence] = None,
-        tracing: Optional[bool] = False,
+        persistence: FlowPersistence | None = None,
+        tracing: bool | None = False,
         **kwargs: Any,
     ) -> None:
         """Initialize a new Flow instance.
@@ -468,18 +456,22 @@ class Flow(Generic[T], metaclass=FlowMeta):
             **kwargs: Additional state values to initialize or override
         """
         # Initialize basic instance attributes
-        self._methods: Dict[str, Callable] = {}
-        self._method_execution_counts: Dict[str, int] = {}
-        self._pending_and_listeners: Dict[str, Set[str]] = {}
-        self._method_outputs: List[Any] = []  # List to store all method outputs
-        self._completed_methods: Set[str] = set()  # Track completed methods for reload
-        self._persistence: Optional[FlowPersistence] = persistence
+        self._methods: dict[str, Callable] = {}
+        self._method_execution_counts: dict[str, int] = {}
+        self._pending_and_listeners: dict[str, set[str]] = {}
+        self._method_outputs: list[Any] = []  # list to store all method outputs
+        self._completed_methods: set[str] = set()  # Track completed methods for reload
+        self._persistence: FlowPersistence | None = persistence
         self._is_execution_resuming: bool = False
 
         # Initialize state with initial values
         self._state = self._create_initial_state()
         self.tracing = tracing
-        if is_tracing_enabled() or self.tracing:
+        if (
+            is_tracing_enabled()
+            or self.tracing
+            or should_auto_collect_first_time_traces()
+        ):
             trace_listener = TraceCollectionListener()
             trace_listener.setup_listeners(crewai_event_bus)
         # Apply any additional kwargs
@@ -521,25 +513,25 @@ class Flow(Generic[T], metaclass=FlowMeta):
             TypeError: If state is neither BaseModel nor dictionary
         """
         # Handle case where initial_state is None but we have a type parameter
-        if self.initial_state is None and hasattr(self, "_initial_state_T"):
-            state_type = getattr(self, "_initial_state_T")
+        if self.initial_state is None and hasattr(self, "_initial_state_t"):
+            state_type = self._initial_state_t
             if isinstance(state_type, type):
                 if issubclass(state_type, FlowState):
                     # Create instance without id, then set it
                     instance = state_type()
                     if not hasattr(instance, "id"):
-                        setattr(instance, "id", str(uuid4()))
+                        instance.id = str(uuid4())
                     return cast(T, instance)
-                elif issubclass(state_type, BaseModel):
+                if issubclass(state_type, BaseModel):
                     # Create a new type that includes the ID field
                     class StateWithId(state_type, FlowState):  # type: ignore
                         pass
 
                     instance = StateWithId()
                     if not hasattr(instance, "id"):
-                        setattr(instance, "id", str(uuid4()))
+                        instance.id = str(uuid4())
                     return cast(T, instance)
-                elif state_type is dict:
+                if state_type is dict:
                     return cast(T, {"id": str(uuid4())})
 
         # Handle case where no initial state is provided
@@ -550,13 +542,13 @@ class Flow(Generic[T], metaclass=FlowMeta):
         if isinstance(self.initial_state, type):
             if issubclass(self.initial_state, FlowState):
                 return cast(T, self.initial_state())  # Uses model defaults
-            elif issubclass(self.initial_state, BaseModel):
+            if issubclass(self.initial_state, BaseModel):
                 # Validate that the model has an id field
                 model_fields = getattr(self.initial_state, "model_fields", None)
                 if not model_fields or "id" not in model_fields:
                     raise ValueError("Flow state model must have an 'id' field")
                 return cast(T, self.initial_state())  # Uses model defaults
-            elif self.initial_state is dict:
+            if self.initial_state is dict:
                 return cast(T, {"id": str(uuid4())})
 
         # Handle dictionary instance case
@@ -600,7 +592,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
         return self._state
 
     @property
-    def method_outputs(self) -> List[Any]:
+    def method_outputs(self) -> list[Any]:
         """Returns the list of all outputs from executed methods."""
         return self._method_outputs
 
@@ -631,13 +623,13 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
             if isinstance(self._state, dict):
                 return str(self._state.get("id", ""))
-            elif isinstance(self._state, BaseModel):
+            if isinstance(self._state, BaseModel):
                 return str(getattr(self._state, "id", ""))
             return ""
         except (AttributeError, TypeError):
             return ""  # Safely handle any unexpected attribute access issues
 
-    def _initialize_state(self, inputs: Dict[str, Any]) -> None:
+    def _initialize_state(self, inputs: dict[str, Any]) -> None:
         """Initialize or update flow state with new inputs.
 
         Args:
@@ -691,7 +683,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
         else:
             raise TypeError("State must be a BaseModel instance or a dictionary.")
 
-    def _restore_state(self, stored_state: Dict[str, Any]) -> None:
+    def _restore_state(self, stored_state: dict[str, Any]) -> None:
         """Restore flow state from persistence.
 
         Args:
@@ -735,7 +727,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
             execution_data: Flow execution data containing:
                 - id: Flow execution ID
                 - flow: Flow structure
-                - completed_methods: List of successfully completed methods
+                - completed_methods: list of successfully completed methods
                 - execution_methods: All execution methods with their status
         """
         flow_id = execution_data.get("id")
@@ -771,7 +763,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
         if state_to_apply:
             self._apply_state_updates(state_to_apply)
 
-        for i, method in enumerate(sorted_methods[:-1]):
+        for method in sorted_methods[:-1]:
             method_name = method.get("flow_method", {}).get("name")
             if method_name:
                 self._completed_methods.add(method_name)
@@ -783,7 +775,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
         elif hasattr(self._state, field_name):
             object.__setattr__(self._state, field_name, value)
 
-    def _apply_state_updates(self, updates: Dict[str, Any]) -> None:
+    def _apply_state_updates(self, updates: dict[str, Any]) -> None:
         """Apply multiple state updates efficiently."""
         if isinstance(self._state, dict):
             self._state.update(updates)
@@ -792,7 +784,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 if hasattr(self._state, key):
                     object.__setattr__(self._state, key, value)
 
-    def kickoff(self, inputs: Optional[Dict[str, Any]] = None) -> Any:
+    def kickoff(self, inputs: dict[str, Any] | None = None) -> Any:
         """
         Start the flow execution in a synchronous context.
 
@@ -805,7 +797,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
         return asyncio.run(run_flow())
 
-    async def kickoff_async(self, inputs: Optional[Dict[str, Any]] = None) -> Any:
+    async def kickoff_async(self, inputs: dict[str, Any] | None = None) -> Any:
         """
         Start the flow execution asynchronously.
 
@@ -840,7 +832,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
                     if isinstance(self._state, dict):
                         self._state["id"] = inputs["id"]
                     elif isinstance(self._state, BaseModel):
-                        setattr(self._state, "id", inputs["id"])
+                        setattr(self._state, "id", inputs["id"])  # noqa: B010
 
                 # If persistence is enabled, attempt to restore the stored state using the provided id.
                 if "id" in inputs and self._persistence is not None:
@@ -1075,7 +1067,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 )
 
         # Now execute normal listeners for all router results and the original trigger
-        all_triggers = [trigger_method] + router_results
+        all_triggers = [trigger_method, *router_results]
 
         for current_trigger in all_triggers:
             if current_trigger:  # Skip None results
@@ -1109,7 +1101,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
     def _find_triggered_methods(
         self, trigger_method: str, router_only: bool
-    ) -> List[str]:
+    ) -> list[str]:
         """
         Finds all methods that should be triggered based on conditions.
 
@@ -1126,7 +1118,7 @@ class Flow(Generic[T], metaclass=FlowMeta):
 
         Returns
         -------
-        List[str]
+        list[str]
             Names of methods that should be triggered.
 
         Notes