fix: handle running event loop in A2A sync wrappers (#4671)

execute_a2a_delegation() and fetch_agent_card() now use a ThreadPoolExecutor
to run async code in a separate thread when an event loop is already running
(e.g. Jupyter notebooks), instead of raising RuntimeError.

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

.env.test

@@ -21,7 +21,6 @@ OPENROUTER_API_KEY=fake-openrouter-key
 AWS_ACCESS_KEY_ID=fake-aws-access-key
 AWS_SECRET_ACCESS_KEY=fake-aws-secret-key
 AWS_DEFAULT_REGION=us-east-1
-AWS_REGION_NAME=us-east-1
 
 # -----------------------------------------------------------------------------
 # Azure OpenAI Configuration

.github/workflows/publish.yml

@@ -1,8 +1,6 @@
 name: Publish to PyPI
 
 on:
-  repository_dispatch:
-    types: [deployment-tests-passed]
   workflow_dispatch:
     inputs:
       release_tag:
@@ -20,11 +18,8 @@ jobs:
       - name: Determine release tag
         id: release
         run: |
-          # Priority: workflow_dispatch input > repository_dispatch payload > default branch
           if [ -n "${{ inputs.release_tag }}" ]; then
             echo "tag=${{ inputs.release_tag }}" >> $GITHUB_OUTPUT
-          elif [ -n "${{ github.event.client_payload.release_tag }}" ]; then
-            echo "tag=${{ github.event.client_payload.release_tag }}" >> $GITHUB_OUTPUT
           else
             echo "tag=" >> $GITHUB_OUTPUT
           fi

.github/workflows/trigger-deployment-tests.yml

@@ -1,18 +0,0 @@
-name: Trigger Deployment Tests
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  trigger:
-    name: Trigger deployment tests
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger deployment tests
-        uses: peter-evans/repository-dispatch@v3
-        with:
-          token: ${{ secrets.CREWAI_DEPLOYMENTS_PAT }}
-          repository: ${{ secrets.CREWAI_DEPLOYMENTS_REPOSITORY }}
-          event-type: crewai-release
-          client-payload: '{"release_tag": "${{ github.event.release.tag_name }}", "release_name": "${{ github.event.release.name }}"}'

docs/en/changelog.mdx

@@ -4,6 +4,106 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Feb 27, 2026">
+  ## v1.10.1a1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1a1)
+
+  ## What's Changed
+
+  ### Features
+  - Implement asynchronous invocation support in step callback methods
+  - Implement lazy loading for heavy dependencies in Memory module
+
+  ### Documentation
+  - Update changelog and version for v1.10.0
+
+  ### Refactoring
+  - Refactor step callback methods to support asynchronous invocation
+  - Refactor to implement lazy loading for heavy dependencies in Memory module
+
+  ### Bug Fixes
+  - Fix branch for release notes
+
+  ## Contributors
+
+  @greysonlalonde, @joaomdmoura
+
+</Update>
+
+<Update label="Feb 27, 2026">
+  ## v1.10.1a1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1a1)
+
+  ## What's Changed
+
+  ### Refactoring
+  - Refactor step callback methods to support asynchronous invocation
+  - Implement lazy loading for heavy dependencies in Memory module
+
+  ### Documentation
+  - Update changelog and version for v1.10.0
+
+  ### Bug Fixes
+  - Make branch for release notes
+
+  ## Contributors
+
+  @greysonlalonde, @joaomdmoura
+
+</Update>
+
+<Update label="Feb 26, 2026">
+  ## v1.10.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.0)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance MCP tool resolution and related events
+  - Update lancedb version and add lance-namespace packages
+  - Enhance JSON argument parsing and validation in CrewAgentExecutor and BaseTool
+  - Migrate CLI HTTP client from requests to httpx
+  - Add versioned documentation
+  - Add yanked detection for version notes
+  - Implement user input handling in Flows
+  - Enhance HITL self-loop functionality in human feedback integration tests
+  - Add started_event_id and set in eventbus
+  - Auto update tools.specs
+
+  ### Bug Fixes
+  - Validate tool kwargs even when empty to prevent cryptic TypeError
+  - Preserve null types in tool parameter schemas for LLM
+  - Map output_pydantic/output_json to native structured output
+  - Ensure callbacks are ran/awaited if promise
+  - Capture method name in exception context
+  - Preserve enum type in router result; improve types
+  - Fix cyclic flows silently breaking when persistence ID is passed in inputs
+  - Correct CLI flag format from --skip-provider to --skip_provider
+  - Ensure OpenAI tool call stream is finalized
+  - Resolve complex schema $ref pointers in MCP tools
+  - Enforce additionalProperties=false in schemas
+  - Reject reserved script names for crew folders
+  - Resolve race condition in guardrail event emission test
+
+  ### Documentation
+  - Add litellm dependency note for non-native LLM providers
+  - Clarify NL2SQL security model and hardening guidance
+  - Add 96 missing actions across 9 integrations
+
+  ### Refactoring
+  - Refactor crew to provider
+  - Extract HITL to provider pattern
+  - Improve hook typing and registration
+
+  ## Contributors
+
+  @dependabot[bot], @github-actions[bot], @github-code-quality[bot], @greysonlalonde, @heitorado, @hobostay, @joaomdmoura, @johnvan7, @jonathansampson, @lorenzejay, @lucasgomide, @mattatcha, @mplachta, @nicoferdi96, @theCyberTech, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="Jan 26, 2026">
   ## v1.9.0
 

docs/en/concepts/llms.mdx

@@ -106,6 +106,15 @@ There are different places in CrewAI code where you can specify the model to use
   </Tab>
 </Tabs>
 
+<Info>
+  CrewAI provides native SDK integrations for OpenAI, Anthropic, Google (Gemini API), Azure, and AWS Bedrock — no extra install needed beyond the provider-specific extras (e.g. `uv add "crewai[openai]"`).
+
+  All other providers are powered by **LiteLLM**. If you plan to use any of them, add it as a dependency to your project:
+  ```bash
+  uv add 'crewai[litellm]'
+  ```
+</Info>
+
 ## Provider Configuration Examples
 
 CrewAI supports a multitude of LLM providers, each offering unique features, authentication methods, and model capabilities.
@@ -275,6 +284,11 @@ In this section, you'll find detailed examples that help you select, configure,
     | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
     | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | Text | Text |
     | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | Text | Text |
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Anthropic">
@@ -470,7 +484,7 @@ In this section, you'll find detailed examples that help you select, configure,
       To get an Express mode API key:
       - New Google Cloud users: Get an [express mode API key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey)
       - Existing Google Cloud users: Get a [Google Cloud API key bound to a service account](https://cloud.google.com/docs/authentication/api-keys)
-      
+
       For more details, see the [Vertex AI Express mode documentation](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey).
     </Info>
 
@@ -571,6 +585,11 @@ In this section, you'll find detailed examples that help you select, configure,
     | gemini-1.5-flash               | 1M tokens      | Balanced multimodal model, good for most tasks                    |
     | gemini-1.5-flash-8B            | 1M tokens      | Fastest, most cost-efficient, good for high-frequency tasks       |
     | gemini-1.5-pro                 | 2M tokens      | Best performing, wide variety of reasoning tasks including logical reasoning, coding, and creative collaboration |
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Azure">
@@ -652,6 +671,7 @@ In this section, you'll find detailed examples that help you select, configure,
     # Optional
     AWS_SESSION_TOKEN=<your-session-token>  # For temporary credentials
     AWS_DEFAULT_REGION=<your-region>  # Defaults to us-east-1
+    AWS_REGION_NAME=<your-region>  # Alternative configuration for backwards compatibility with LiteLLM. Defaults to us-east-1
     ```
 
     **Basic Usage:**
@@ -695,6 +715,7 @@ In this section, you'll find detailed examples that help you select, configure,
     - `AWS_SECRET_ACCESS_KEY`: AWS secret key (required)
     - `AWS_SESSION_TOKEN`: AWS session token for temporary credentials (optional)
     - `AWS_DEFAULT_REGION`: AWS region (defaults to `us-east-1`)
+    - `AWS_REGION_NAME`: AWS region (defaults to `us-east-1`). Alternative configuration for backwards compatibility with LiteLLM
 
     **Features:**
     - Native tool calling support via Converse API
@@ -764,6 +785,11 @@ In this section, you'll find detailed examples that help you select, configure,
         model="sagemaker/<my-endpoint>"
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Mistral">
@@ -779,6 +805,11 @@ In this section, you'll find detailed examples that help you select, configure,
         temperature=0.7
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Nvidia NIM">
@@ -865,6 +896,11 @@ In this section, you'll find detailed examples that help you select, configure,
     | rakuten/rakutenai-7b-instruct                                     | 1,024 tokens   | Advanced state-of-the-art LLM with language understanding, superior reasoning, and text generation. |
     | rakuten/rakutenai-7b-chat                                         | 1,024 tokens   | Advanced state-of-the-art LLM with language understanding, superior reasoning, and text generation. |
     | baichuan-inc/baichuan2-13b-chat                                  | 4,096 tokens   | Support Chinese and English chat, coding, math, instruction following, solving quizzes |
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Local NVIDIA NIM Deployed using WSL2">
@@ -905,6 +941,11 @@ In this section, you'll find detailed examples that help you select, configure,
 
         # ...
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Groq">
@@ -926,6 +967,11 @@ In this section, you'll find detailed examples that help you select, configure,
     | Llama 3.1 70B/8B  | 131,072 tokens   | High-performance, large context tasks      |
     | Llama 3.2 Series  | 8,192 tokens     | General-purpose tasks                      |
     | Mixtral 8x7B      | 32,768 tokens    | Balanced performance and context           |
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="IBM watsonx.ai">
@@ -948,6 +994,11 @@ In this section, you'll find detailed examples that help you select, configure,
         base_url="https://api.watsonx.ai/v1"
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Ollama (Local LLMs)">
@@ -961,6 +1012,11 @@ In this section, you'll find detailed examples that help you select, configure,
         base_url="http://localhost:11434"
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Fireworks AI">
@@ -976,6 +1032,11 @@ In this section, you'll find detailed examples that help you select, configure,
         temperature=0.7
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Perplexity AI">
@@ -991,6 +1052,11 @@ In this section, you'll find detailed examples that help you select, configure,
         base_url="https://api.perplexity.ai/"
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Hugging Face">
@@ -1005,6 +1071,11 @@ In this section, you'll find detailed examples that help you select, configure,
         model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct"
     )
     ```
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="SambaNova">
@@ -1028,6 +1099,11 @@ In this section, you'll find detailed examples that help you select, configure,
     | Llama 3.2 Series   | 8,192 tokens           | General-purpose, multimodal tasks            |
     | Llama 3.3 70B      | Up to 131,072 tokens   | High-performance and output quality          |
     | Qwen2 familly      | 8,192 tokens           | High-performance and output quality          |
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Cerebras">
@@ -1053,6 +1129,11 @@ In this section, you'll find detailed examples that help you select, configure,
       - Good balance of speed and quality
       - Support for long context windows
     </Info>
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Open Router">
@@ -1075,6 +1156,11 @@ In this section, you'll find detailed examples that help you select, configure,
       - openrouter/deepseek/deepseek-r1
       - openrouter/deepseek/deepseek-chat
     </Info>
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Nebius AI Studio">
@@ -1097,6 +1183,11 @@ In this section, you'll find detailed examples that help you select, configure,
       - Competitive pricing
       - Good balance of speed and quality
     </Info>
+
+    **Note:** This provider uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 </AccordionGroup>
 

docs/en/enterprise/guides/deploy-to-amp.mdx

@@ -177,6 +177,11 @@ You need to push your crew to a GitHub repository. If you haven't created a crew
       ![Set Environment Variables](/images/enterprise/set-env-variables.png)
     </Frame>
 
+    <Info>
+      Using private Python packages? You'll need to add your registry credentials here too.
+      See [Private Package Registries](/en/enterprise/guides/private-package-registry) for the required variables.
+    </Info>
+
   </Step>
 
   <Step title="Deploy Your Crew">

docs/en/enterprise/guides/prepare-for-deployment.mdx

@@ -256,6 +256,12 @@ Before deployment, ensure you have:
 1. **LLM API keys** ready (OpenAI, Anthropic, Google, etc.)
 2. **Tool API keys** if using external tools (Serper, etc.)
 
+<Info>
+  If your project depends on packages from a **private PyPI registry**, you'll also need to configure
+  registry authentication credentials as environment variables. See the
+  [Private Package Registries](/en/enterprise/guides/private-package-registry) guide for details.
+</Info>
+
 <Tip>
   Test your project locally with the same environment variables before deploying
   to catch configuration issues early.

docs/en/enterprise/guides/private-package-registry.mdx

@@ -0,0 +1,263 @@
+---
+title: "Private Package Registries"
+description: "Install private Python packages from authenticated PyPI registries in CrewAI AMP"
+icon: "lock"
+mode: "wide"
+---
+
+<Note>
+  This guide covers how to configure your CrewAI project to install Python packages
+  from private PyPI registries (Azure DevOps Artifacts, GitHub Packages, GitLab, AWS CodeArtifact, etc.)
+  when deploying to CrewAI AMP.
+</Note>
+
+## When You Need This
+
+If your project depends on internal or proprietary Python packages hosted on a private registry
+rather than the public PyPI, you'll need to:
+
+1. Tell UV **where** to find the package (an index URL)
+2. Tell UV **which** packages come from that index (a source mapping)
+3. Provide **credentials** so UV can authenticate during install
+
+CrewAI AMP uses [UV](https://docs.astral.sh/uv/) for dependency resolution and installation.
+UV supports authenticated private registries through `pyproject.toml` configuration combined
+with environment variables for credentials.
+
+## Step 1: Configure pyproject.toml
+
+Three pieces work together in your `pyproject.toml`:
+
+### 1a. Declare the dependency
+
+Add the private package to your `[project.dependencies]` like any other dependency:
+
+```toml
+[project]
+dependencies = [
+    "crewai[tools]>=0.100.1,<1.0.0",
+    "my-private-package>=1.2.0",
+]
+```
+
+### 1b. Define the index
+
+Register your private registry as a named index under `[[tool.uv.index]]`:
+
+```toml
+[[tool.uv.index]]
+name = "my-private-registry"
+url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
+explicit = true
+```
+
+<Info>
+  The `name` field is important — UV uses it to construct the environment variable names
+  for authentication (see [Step 2](#step-2-set-authentication-credentials) below).
+
+  Setting `explicit = true` means UV won't search this index for every package — only the
+  ones you explicitly map to it in `[tool.uv.sources]`. This avoids unnecessary queries
+  against your private registry and protects against dependency confusion attacks.
+</Info>
+
+### 1c. Map the package to the index
+
+Tell UV which packages should be resolved from your private index using `[tool.uv.sources]`:
+
+```toml
+[tool.uv.sources]
+my-private-package = { index = "my-private-registry" }
+```
+
+### Complete example
+
+```toml
+[project]
+name = "my-crew-project"
+version = "0.1.0"
+requires-python = ">=3.10,<=3.13"
+dependencies = [
+    "crewai[tools]>=0.100.1,<1.0.0",
+    "my-private-package>=1.2.0",
+]
+
+[tool.crewai]
+type = "crew"
+
+[[tool.uv.index]]
+name = "my-private-registry"
+url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
+explicit = true
+
+[tool.uv.sources]
+my-private-package = { index = "my-private-registry" }
+```
+
+After updating `pyproject.toml`, regenerate your lock file:
+
+```bash
+uv lock
+```
+
+<Warning>
+  Always commit the updated `uv.lock` along with your `pyproject.toml` changes.
+  The lock file is required for deployment — see [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment).
+</Warning>
+
+## Step 2: Set Authentication Credentials
+
+UV authenticates against private indexes using environment variables that follow a naming convention
+based on the index name you defined in `pyproject.toml`:
+
+```
+UV_INDEX_{UPPER_NAME}_USERNAME
+UV_INDEX_{UPPER_NAME}_PASSWORD
+```
+
+Where `{UPPER_NAME}` is your index name converted to **uppercase** with **hyphens replaced by underscores**.
+
+For example, an index named `my-private-registry` uses:
+
+| Variable | Value |
+|----------|-------|
+| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | Your registry username or token name |
+| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | Your registry password or token/PAT |
+
+<Warning>
+  These environment variables **must** be added via the CrewAI AMP **Environment Variables** settings —
+  either globally or at the deployment level. They cannot be set in `.env` files or hardcoded in your project.
+
+  See [Setting Environment Variables in AMP](#setting-environment-variables-in-amp) below.
+</Warning>
+
+## Registry Provider Reference
+
+The table below shows the index URL format and credential values for common registry providers.
+Replace placeholder values with your actual organization and feed details.
+
+| Provider | Index URL | Username | Password |
+|----------|-----------|----------|----------|
+| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | Any non-empty string (e.g. `token`) | Personal Access Token (PAT) with Packaging Read scope |
+| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | GitHub username | Personal Access Token (classic) with `read:packages` scope |
+| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project or Personal Access Token with `read_api` scope |
+| **AWS CodeArtifact** | Use the URL from `aws codeartifact get-repository-endpoint` | `aws` | Token from `aws codeartifact get-authorization-token` |
+| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Base64-encoded service account key |
+| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | Username or email | API key or identity token |
+| **Self-hosted (devpi, Nexus, etc.)** | Your registry's simple API URL | Registry username | Registry password |
+
+<Tip>
+  For **AWS CodeArtifact**, the authorization token expires periodically.
+  You'll need to refresh the `UV_INDEX_*_PASSWORD` value when it expires.
+  Consider automating this in your CI/CD pipeline.
+</Tip>
+
+## Setting Environment Variables in AMP
+
+Private registry credentials must be configured as environment variables in CrewAI AMP.
+You have two options:
+
+<Tabs>
+  <Tab title="Web Interface">
+    1. Log in to [CrewAI AMP](https://app.crewai.com)
+    2. Navigate to your automation
+    3. Open the **Environment Variables** tab
+    4. Add each variable (`UV_INDEX_*_USERNAME` and `UV_INDEX_*_PASSWORD`) with its value
+
+    See the [Deploy to AMP — Set Environment Variables](/en/enterprise/guides/deploy-to-amp#set-environment-variables) step for details.
+  </Tab>
+  <Tab title="CLI Deployment">
+    Add the variables to your local `.env` file before running `crewai deploy create`.
+    The CLI will securely transfer them to the platform:
+
+    ```bash
+    # .env
+    OPENAI_API_KEY=sk-...
+    UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
+    UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here
+    ```
+
+    ```bash
+    crewai deploy create
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+  **Never** commit credentials to your repository. Use AMP environment variables for all secrets.
+  The `.env` file should be listed in `.gitignore`.
+</Warning>
+
+To update credentials on an existing deployment, see [Update Your Crew — Environment Variables](/en/enterprise/guides/update-crew).
+
+## How It All Fits Together
+
+When CrewAI AMP builds your automation, the resolution flow works like this:
+
+<Steps>
+  <Step title="Build starts">
+    AMP pulls your repository and reads `pyproject.toml` and `uv.lock`.
+  </Step>
+  <Step title="UV resolves dependencies">
+    UV reads `[tool.uv.sources]` to determine which index each package should come from.
+  </Step>
+  <Step title="UV authenticates">
+    For each private index, UV looks up `UV_INDEX_{NAME}_USERNAME` and `UV_INDEX_{NAME}_PASSWORD`
+    from the environment variables you configured in AMP.
+  </Step>
+  <Step title="Packages install">
+    UV downloads and installs all packages — both public (from PyPI) and private (from your registry).
+  </Step>
+  <Step title="Automation runs">
+    Your crew or flow starts with all dependencies available.
+  </Step>
+</Steps>
+
+## Troubleshooting
+
+### Authentication Errors During Build
+
+**Symptom**: Build fails with `401 Unauthorized` or `403 Forbidden` when resolving a private package.
+
+**Check**:
+- The `UV_INDEX_*` environment variable names match your index name exactly (uppercased, hyphens → underscores)
+- Credentials are set in AMP environment variables, not just in a local `.env`
+- Your token/PAT has the required read permissions for the package feed
+- The token hasn't expired (especially relevant for AWS CodeArtifact)
+
+### Package Not Found
+
+**Symptom**: `No matching distribution found for my-private-package`.
+
+**Check**:
+- The index URL in `pyproject.toml` ends with `/simple/`
+- The `[tool.uv.sources]` entry maps the correct package name to the correct index name
+- The package is actually published to your private registry
+- Run `uv lock` locally with the same credentials to verify resolution works
+
+### Lock File Conflicts
+
+**Symptom**: `uv lock` fails or produces unexpected results after adding a private index.
+
+**Solution**: Set the credentials locally and regenerate:
+
+```bash
+export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
+export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
+uv lock
+```
+
+Then commit the updated `uv.lock`.
+
+## Related Guides
+
+<CardGroup cols={3}>
+  <Card title="Prepare for Deployment" icon="clipboard-check" href="/en/enterprise/guides/prepare-for-deployment">
+    Verify project structure and dependencies before deploying.
+  </Card>
+  <Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
+    Deploy your crew or flow and configure environment variables.
+  </Card>
+  <Card title="Update Your Crew" icon="arrows-rotate" href="/en/enterprise/guides/update-crew">
+    Update environment variables and push changes to a running deployment.
+  </Card>
+</CardGroup>

docs/en/learn/llm-connections.mdx

@@ -7,7 +7,7 @@ mode: "wide"
 
 ## Connect CrewAI to LLMs
 
-CrewAI uses LiteLLM to connect to a wide variety of Language Models (LLMs). This integration provides extensive versatility, allowing you to use models from numerous providers with a simple, unified interface.
+CrewAI connects to LLMs through native SDK integrations for the most popular providers (OpenAI, Anthropic, Google Gemini, Azure, and AWS Bedrock), and uses LiteLLM as a flexible fallback for all other providers.
 
 <Note>
     By default, CrewAI uses the `gpt-4o-mini` model. This is determined by the `OPENAI_MODEL_NAME` environment variable, which defaults to "gpt-4o-mini" if not set.
@@ -41,6 +41,14 @@ LiteLLM supports a wide range of providers, including but not limited to:
 
 For a complete and up-to-date list of supported providers, please refer to the [LiteLLM Providers documentation](https://docs.litellm.ai/docs/providers).
 
+<Info>
+  To use any provider not covered by a native integration, add LiteLLM as a dependency to your project:
+  ```bash
+  uv add 'crewai[litellm]'
+  ```
+  Native providers (OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock) use their own SDK extras — see the [Provider Configuration Examples](/en/concepts/llms#provider-configuration-examples).
+</Info>
+
 ## Changing the LLM
 
 To use a different LLM with your CrewAI agents, you have several options:

docs/en/observability/tracing.mdx

@@ -35,7 +35,7 @@ Visit [app.crewai.com](https://app.crewai.com) and create your free account. Thi
 If you haven't already, install CrewAI with the CLI tools:
 
 ```bash
-uv add crewai[tools]
+uv add 'crewai[tools]'
 ```
 
 Then authenticate your CLI with your CrewAI AMP account:

docs/en/tools/automation/composiotool.mdx

@@ -18,77 +18,46 @@ Composio is an integration platform that allows you to connect your AI agents to
 To incorporate Composio tools into your project, follow the instructions below:
 
 ```shell
-pip install composio-crewai
+pip install composio composio-crewai
 pip install crewai
 ```
 
-After the installation is complete, either run `composio login` or export your composio API key as `COMPOSIO_API_KEY`. Get your Composio API key from [here](https://app.composio.dev)
+After the installation is complete, set your Composio API key as `COMPOSIO_API_KEY`. Get your Composio API key from [here](https://platform.composio.dev)
 
 ## Example
 
 The following example demonstrates how to initialize the tool and execute a github action:
 
-1. Initialize Composio toolset
+1. Initialize Composio with CrewAI Provider
 
 ```python Code
-from composio_crewai import ComposioToolSet, App, Action
+from composio_crewai import ComposioProvider
+from composio import Composio
 from crewai import Agent, Task, Crew
 
-toolset = ComposioToolSet()
+composio = Composio(provider=ComposioProvider())
 ```
 
-2. Connect your GitHub account
+2. Create a new Composio Session and retrieve the tools
 <CodeGroup>
-```shell CLI
-composio add github
-```
-```python Code
-request = toolset.initiate_connection(app=App.GITHUB)
-print(f"Open this URL to authenticate: {request.redirectUrl}")
+```python
+session = composio.create(
+    user_id="your-user-id",
+    toolkits=["gmail", "github"] # optional, default is all toolkits
+)
+tools = session.tools()
 ```
+Read more about sessions and user management [here](https://docs.composio.dev/docs/configuring-sessions)
 </CodeGroup>
 
-3. Get Tools
+3. Authenticating users manually
 
-- Retrieving all the tools from an app (not recommended for production):
+Composio automatically authenticates the users during the agent chat session. However, you can also authenticate the user manually by calling the `authorize` method.
 ```python Code
-tools = toolset.get_tools(apps=[App.GITHUB])
+connection_request = session.authorize("github")
+print(f"Open this URL to authenticate: {connection_request.redirect_url}")
 ```
 
-- Filtering tools based on tags:
-```python Code
-tag = "users"
-
-filtered_action_enums = toolset.find_actions_by_tags(
-    App.GITHUB,
-    tags=[tag], 
-)
-
-tools = toolset.get_tools(actions=filtered_action_enums)
-```
-
-- Filtering tools based on use case:
-```python Code
-use_case = "Star a repository on GitHub"
-
-filtered_action_enums = toolset.find_actions_by_use_case(
-    App.GITHUB, use_case=use_case, advanced=False
-)
-
-tools = toolset.get_tools(actions=filtered_action_enums)
-```
-<Tip>Set `advanced` to True to get actions for complex use cases</Tip>
-
-- Using specific tools:
-
-In this demo, we will use the `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` action from the GitHub app.
-```python Code
-tools = toolset.get_tools(
-    actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER]
-)
-```
-Learn more about filtering actions [here](https://docs.composio.dev/patterns/tools/use-tools/use-specific-actions)
-
 4. Define agent
 
 ```python Code
@@ -116,4 +85,4 @@ crew = Crew(agents=[crewai_agent], tasks=[task])
 crew.kickoff()
 ```
 
-* More detailed list of tools can be found [here](https://app.composio.dev)
+* More detailed list of tools can be found [here](https://docs.composio.dev/toolkits)

docs/ko/changelog.mdx

@@ -4,6 +4,106 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 2월 27일">
+  ## v1.10.1a1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1a1)
+
+  ## 변경 사항
+
+  ### 기능
+  - 단계 콜백 메서드에서 비동기 호출 지원 구현
+  - 메모리 모듈의 무거운 의존성에 대한 지연 로딩 구현
+
+  ### 문서
+  - v1.10.0에 대한 변경 로그 및 버전 업데이트
+
+  ### 리팩토링
+  - 비동기 호출을 지원하기 위해 단계 콜백 메서드 리팩토링
+  - 메모리 모듈의 무거운 의존성에 대한 지연 로딩을 구현하기 위해 리팩토링
+
+  ### 버그 수정
+  - 릴리스 노트의 분기 수정
+
+  ## 기여자
+
+  @greysonlalonde, @joaomdmoura
+
+</Update>
+
+<Update label="2026년 2월 27일">
+  ## v1.10.1a1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1a1)
+
+  ## 변경 사항
+
+  ### 리팩토링
+  - 비동기 호출을 지원하기 위해 단계 콜백 메서드 리팩토링
+  - 메모리 모듈의 무거운 의존성에 대해 지연 로딩 구현
+
+  ### 문서화
+  - v1.10.0에 대한 변경 로그 및 버전 업데이트
+
+  ### 버그 수정
+  - 릴리스 노트를 위한 브랜치 생성
+
+  ## 기여자
+
+  @greysonlalonde, @joaomdmoura
+
+</Update>
+
+<Update label="2026년 2월 26일">
+  ## v1.10.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.10.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - MCP 도구 해상도 및 관련 이벤트 개선
+  - lancedb 버전 업데이트 및 lance-namespace 패키지 추가
+  - CrewAgentExecutor 및 BaseTool에서 JSON 인수 파싱 및 검증 개선
+  - CLI HTTP 클라이언트를 requests에서 httpx로 마이그레이션
+  - 버전화된 문서 추가
+  - 버전 노트에 대한 yanked 감지 추가
+  - Flows에서 사용자 입력 처리 구현
+  - 인간 피드백 통합 테스트에서 HITL 자기 루프 기능 개선
+  - eventbus에 started_event_id 추가 및 설정
+  - tools.specs 자동 업데이트
+
+  ### 버그 수정
+  - 빈 경우에도 도구 kwargs를 검증하여 모호한 TypeError 방지
+  - LLM을 위한 도구 매개변수 스키마에서 null 타입 유지
+  - output_pydantic/output_json을 네이티브 구조화된 출력으로 매핑
+  - 약속이 있는 경우 콜백이 실행/대기되도록 보장
+  - 예외 컨텍스트에서 메서드 이름 캡처
+  - 라우터 결과에서 enum 타입 유지; 타입 개선
+  - 입력으로 지속성 ID가 전달될 때 조용히 깨지는 순환 흐름 수정
+  - CLI 플래그 형식을 --skip-provider에서 --skip_provider로 수정
+  - OpenAI 도구 호출 스트림이 완료되도록 보장
+  - MCP 도구에서 복잡한 스키마 $ref 포인터 해결
+  - 스키마에서 additionalProperties=false 강제 적용
+  - 크루 폴더에 대해 예약된 스크립트 이름 거부
+  - 가드레일 이벤트 방출 테스트에서 경쟁 조건 해결
+
+  ### 문서
+  - 비네이티브 LLM 공급자를 위한 litellm 종속성 노트 추가
+  - NL2SQL 보안 모델 및 강화 지침 명확화
+  - 9개 통합에서 96개의 누락된 작업 추가
+
+  ### 리팩토링
+  - crew를 provider로 리팩토링
+  - HITL을 provider 패턴으로 추출
+  - 훅 타이핑 및 등록 개선
+
+  ## 기여자
+
+  @dependabot[bot], @github-actions[bot], @github-code-quality[bot], @greysonlalonde, @heitorado, @hobostay, @joaomdmoura, @johnvan7, @jonathansampson, @lorenzejay, @lucasgomide, @mattatcha, @mplachta, @nicoferdi96, @theCyberTech, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="2026년 1월 26일">
   ## v1.9.0
 

docs/ko/concepts/llms.mdx

@@ -105,6 +105,15 @@ CrewAI 코드 내에는 사용할 모델을 지정할 수 있는 여러 위치
   </Tab>
 </Tabs>
 
+<Info>
+  CrewAI는 OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock에 대해 네이티브 SDK 통합을 제공합니다 — 제공자별 extras(예: `uv add "crewai[openai]"`) 외에 추가 설치가 필요하지 않습니다.
+
+  그 외 모든 제공자는 **LiteLLM**을 통해 지원됩니다. 이를 사용하려면 프로젝트에 의존성으로 추가하세요:
+  ```bash
+  uv add 'crewai[litellm]'
+  ```
+</Info>
+
 ## 공급자 구성 예시
 
 CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양한 LLM 공급자를 지원합니다.
@@ -214,6 +223,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | 텍스트, 이미지     | 텍스트           |
     | `meta_llama/Llama-3.3-70B-Instruct`               | 128k | 4028       | 텍스트            | 텍스트           |
     | `meta_llama/Llama-3.3-8B-Instruct`                | 128k | 4028       | 텍스트            | 텍스트           |
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Anthropic">
@@ -354,6 +368,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     | gemini-1.5-flash                 | 1M 토큰         | 밸런스 잡힌 멀티모달 모델, 대부분의 작업에 적합                         |
     | gemini-1.5-flash-8B              | 1M 토큰         | 가장 빠르고, 비용 효율적, 고빈도 작업에 적합                            |
     | gemini-1.5-pro                   | 2M 토큰         | 최고의 성능, 논리적 추론, 코딩, 창의적 협업 등 다양한 추론 작업에 적합   |
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Azure">
@@ -439,6 +458,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         model="sagemaker/<my-endpoint>"
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Mistral">
@@ -454,6 +478,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         temperature=0.7
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Nvidia NIM">
@@ -540,6 +569,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     | rakuten/rakutenai-7b-instruct                                          | 1,024 토큰     | 언어 이해, 추론, 텍스트 생성이 탁월한 최첨단 LLM                         |
     | rakuten/rakutenai-7b-chat                                              | 1,024 토큰     | 언어 이해, 추론, 텍스트 생성이 탁월한 최첨단 LLM                         |
     | baichuan-inc/baichuan2-13b-chat                                        | 4,096 토큰     | 중국어 및 영어 대화, 코딩, 수학, 지시 따르기, 퀴즈 풀이 지원             |
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Local NVIDIA NIM Deployed using WSL2">
@@ -580,6 +614,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
 
         # ...
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Groq">
@@ -601,6 +640,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     | Llama 3.1 70B/8B| 131,072 토큰      | 고성능, 대용량 문맥 작업         |
     | Llama 3.2 Series| 8,192 토큰        | 범용 작업                        |
     | Mixtral 8x7B    | 32,768 토큰       | 성능과 문맥의 균형               |
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="IBM watsonx.ai">
@@ -623,6 +667,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         base_url="https://api.watsonx.ai/v1"
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Ollama (Local LLMs)">
@@ -636,6 +685,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         base_url="http://localhost:11434"
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Fireworks AI">
@@ -651,6 +705,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         temperature=0.7
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Perplexity AI">
@@ -666,6 +725,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         base_url="https://api.perplexity.ai/"
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Hugging Face">
@@ -680,6 +744,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
         model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct"
     )
     ```
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="SambaNova">
@@ -703,6 +772,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     | Llama 3.2 Series| 8,192 토큰         | 범용, 멀티모달 작업                  |
     | Llama 3.3 70B   | 최대 131,072 토큰   | 고성능, 높은 출력 품질               |
     | Qwen2 familly   | 8,192 토큰         | 고성능, 높은 출력 품질               |
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Cerebras">
@@ -728,6 +802,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
       - 속도와 품질의 우수한 밸런스
       - 긴 컨텍스트 윈도우 지원
     </Info>
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Open Router">
@@ -750,6 +829,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
       - openrouter/deepseek/deepseek-r1
       - openrouter/deepseek/deepseek-chat
     </Info>
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Nebius AI Studio">
@@ -772,6 +856,11 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
       - 경쟁력 있는 가격
       - 속도와 품질의 우수한 밸런스
     </Info>
+
+    **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 </AccordionGroup>
 

docs/ko/enterprise/guides/deploy-to-amp.mdx

@@ -176,6 +176,11 @@ Crew를 GitHub 저장소에 푸시해야 합니다. 아직 Crew를 만들지 않
       ![Set Environment Variables](/images/enterprise/set-env-variables.png)
     </Frame>
 
+    <Info>
+      프라이빗 Python 패키지를 사용하시나요? 여기에 레지스트리 자격 증명도 추가해야 합니다.
+      필요한 변수는 [프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry)를 참조하세요.
+    </Info>
+
   </Step>
 
   <Step title="Crew 배포하기">

docs/ko/enterprise/guides/prepare-for-deployment.mdx

@@ -256,6 +256,12 @@ Crews와 Flows 모두 `src/project_name/main.py`에 진입점이 있습니다:
 1. **LLM API 키** (OpenAI, Anthropic, Google 등)
 2. **도구 API 키** - 외부 도구를 사용하는 경우 (Serper 등)
 
+<Info>
+  프로젝트가 **프라이빗 PyPI 레지스트리**의 패키지에 의존하는 경우, 레지스트리 인증 자격 증명도
+  환경 변수로 구성해야 합니다. 자세한 내용은
+  [프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry) 가이드를 참조하세요.
+</Info>
+
 <Tip>
   구성 문제를 조기에 발견하기 위해 배포 전에 동일한 환경 변수로
   로컬에서 프로젝트를 테스트하세요.

docs/ko/enterprise/guides/private-package-registry.mdx

@@ -0,0 +1,261 @@
+---
+title: "프라이빗 패키지 레지스트리"
+description: "CrewAI AMP에서 인증된 PyPI 레지스트리의 프라이빗 Python 패키지 설치하기"
+icon: "lock"
+mode: "wide"
+---
+
+<Note>
+  이 가이드는 CrewAI AMP에 배포할 때 프라이빗 PyPI 레지스트리(Azure DevOps Artifacts, GitHub Packages,
+  GitLab, AWS CodeArtifact 등)에서 Python 패키지를 설치하도록 CrewAI 프로젝트를 구성하는 방법을 다룹니다.
+</Note>
+
+## 이 가이드가 필요한 경우
+
+프로젝트가 공개 PyPI가 아닌 프라이빗 레지스트리에 호스팅된 내부 또는 독점 Python 패키지에
+의존하는 경우, 다음을 수행해야 합니다:
+
+1. UV에 패키지를 **어디서** 찾을지 알려줍니다 (index URL)
+2. UV에 **어떤** 패키지가 해당 index에서 오는지 알려줍니다 (source 매핑)
+3. UV가 설치 중에 인증할 수 있도록 **자격 증명**을 제공합니다
+
+CrewAI AMP는 의존성 해결 및 설치에 [UV](https://docs.astral.sh/uv/)를 사용합니다.
+UV는 `pyproject.toml` 구성과 자격 증명용 환경 변수를 결합하여 인증된 프라이빗 레지스트리를 지원합니다.
+
+## 1단계: pyproject.toml 구성
+
+`pyproject.toml`에서 세 가지 요소가 함께 작동합니다:
+
+### 1a. 의존성 선언
+
+프라이빗 패키지를 다른 의존성과 마찬가지로 `[project.dependencies]`에 추가합니다:
+
+```toml
+[project]
+dependencies = [
+    "crewai[tools]>=0.100.1,<1.0.0",
+    "my-private-package>=1.2.0",
+]
+```
+
+### 1b. index 정의
+
+프라이빗 레지스트리를 `[[tool.uv.index]]` 아래에 명명된 index로 등록합니다:
+
+```toml
+[[tool.uv.index]]
+name = "my-private-registry"
+url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
+explicit = true
+```
+
+<Info>
+  `name` 필드는 중요합니다 — UV는 이를 사용하여 인증을 위한 환경 변수 이름을
+  구성합니다 (아래 [2단계](#2단계-인증-자격-증명-설정)를 참조하세요).
+
+  `explicit = true`를 설정하면 UV가 모든 패키지에 대해 이 index를 검색하지 않습니다 —
+  `[tool.uv.sources]`에서 명시적으로 매핑한 패키지만 검색합니다. 이렇게 하면 프라이빗
+  레지스트리에 대한 불필요한 쿼리를 방지하고 의존성 혼동 공격을 차단할 수 있습니다.
+</Info>
+
+### 1c. 패키지를 index에 매핑
+
+`[tool.uv.sources]`를 사용하여 프라이빗 index에서 해결해야 할 패키지를 UV에 알려줍니다:
+
+```toml
+[tool.uv.sources]
+my-private-package = { index = "my-private-registry" }
+```
+
+### 전체 예시
+
+```toml
+[project]
+name = "my-crew-project"
+version = "0.1.0"
+requires-python = ">=3.10,<=3.13"
+dependencies = [
+    "crewai[tools]>=0.100.1,<1.0.0",
+    "my-private-package>=1.2.0",
+]
+
+[tool.crewai]
+type = "crew"
+
+[[tool.uv.index]]
+name = "my-private-registry"
+url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
+explicit = true
+
+[tool.uv.sources]
+my-private-package = { index = "my-private-registry" }
+```
+
+`pyproject.toml`을 업데이트한 후 lock 파일을 다시 생성합니다:
+
+```bash
+uv lock
+```
+
+<Warning>
+  업데이트된 `uv.lock`을 항상 `pyproject.toml` 변경 사항과 함께 커밋하세요.
+  lock 파일은 배포에 필수입니다 — [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요.
+</Warning>
+
+## 2단계: 인증 자격 증명 설정
+
+UV는 `pyproject.toml`에서 정의한 index 이름을 기반으로 한 명명 규칙을 따르는
+환경 변수를 사용하여 프라이빗 index에 인증합니다:
+
+```
+UV_INDEX_{UPPER_NAME}_USERNAME
+UV_INDEX_{UPPER_NAME}_PASSWORD
+```
+
+여기서 `{UPPER_NAME}`은 index 이름을 **대문자**로 변환하고 **하이픈을 언더스코어로 대체**한 것입니다.
+
+예를 들어, `my-private-registry`라는 이름의 index는 다음을 사용합니다:
+
+| 변수 | 값 |
+|------|-----|
+| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | 레지스트리 사용자 이름 또는 토큰 이름 |
+| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | 레지스트리 비밀번호 또는 토큰/PAT |
+
+<Warning>
+  이 환경 변수는 CrewAI AMP **환경 변수** 설정을 통해 **반드시** 추가해야 합니다 —
+  전역적으로 또는 배포 수준에서. `.env` 파일에 설정하거나 프로젝트에 하드코딩할 수 없습니다.
+
+  아래 [AMP에서 환경 변수 설정](#amp에서-환경-변수-설정)을 참조하세요.
+</Warning>
+
+## 레지스트리 제공업체 참조
+
+아래 표는 일반적인 레지스트리 제공업체의 index URL 형식과 자격 증명 값을 보여줍니다.
+자리 표시자 값을 실제 조직 및 피드 세부 정보로 대체하세요.
+
+| 제공업체 | Index URL | 사용자 이름 | 비밀번호 |
+|---------|-----------|-----------|---------|
+| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | 비어 있지 않은 임의의 문자열 (예: `token`) | Packaging Read 범위의 Personal Access Token (PAT) |
+| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | GitHub 사용자 이름 | `read:packages` 범위의 Personal Access Token (classic) |
+| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | `read_api` 범위의 Project 또는 Personal Access Token |
+| **AWS CodeArtifact** | `aws codeartifact get-repository-endpoint`의 URL 사용 | `aws` | `aws codeartifact get-authorization-token`의 토큰 |
+| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Base64로 인코딩된 서비스 계정 키 |
+| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | 사용자 이름 또는 이메일 | API 키 또는 ID 토큰 |
+| **자체 호스팅 (devpi, Nexus 등)** | 레지스트리의 simple API URL | 레지스트리 사용자 이름 | 레지스트리 비밀번호 |
+
+<Tip>
+  **AWS CodeArtifact**의 경우 인증 토큰이 주기적으로 만료됩니다.
+  만료되면 `UV_INDEX_*_PASSWORD` 값을 갱신해야 합니다.
+  CI/CD 파이프라인에서 이를 자동화하는 것을 고려하세요.
+</Tip>
+
+## AMP에서 환경 변수 설정
+
+프라이빗 레지스트리 자격 증명은 CrewAI AMP에서 환경 변수로 구성해야 합니다.
+두 가지 옵션이 있습니다:
+
+<Tabs>
+  <Tab title="웹 인터페이스">
+    1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다
+    2. 자동화로 이동합니다
+    3. **Environment Variables** 탭을 엽니다
+    4. 각 변수 (`UV_INDEX_*_USERNAME` 및 `UV_INDEX_*_PASSWORD`)에 값을 추가합니다
+
+    자세한 내용은 [AMP에 배포하기 — 환경 변수 설정하기](/ko/enterprise/guides/deploy-to-amp#환경-변수-설정하기) 단계를 참조하세요.
+  </Tab>
+  <Tab title="CLI 배포">
+    `crewai deploy create`를 실행하기 전에 로컬 `.env` 파일에 변수를 추가합니다.
+    CLI가 이를 안전하게 플랫폼으로 전송합니다:
+
+    ```bash
+    # .env
+    OPENAI_API_KEY=sk-...
+    UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
+    UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here
+    ```
+
+    ```bash
+    crewai deploy create
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+  자격 증명을 저장소에 **절대** 커밋하지 마세요. 모든 비밀 정보에는 AMP 환경 변수를 사용하세요.
+  `.env` 파일은 `.gitignore`에 포함되어야 합니다.
+</Warning>
+
+기존 배포의 자격 증명을 업데이트하려면 [Crew 업데이트하기 — 환경 변수](/ko/enterprise/guides/update-crew)를 참조하세요.
+
+## 전체 동작 흐름
+
+CrewAI AMP가 자동화를 빌드할 때, 해결 흐름은 다음과 같이 작동합니다:
+
+<Steps>
+  <Step title="빌드 시작">
+    AMP가 저장소를 가져오고 `pyproject.toml`과 `uv.lock`을 읽습니다.
+  </Step>
+  <Step title="UV가 의존성 해결">
+    UV가 `[tool.uv.sources]`를 읽어 각 패키지가 어떤 index에서 와야 하는지 결정합니다.
+  </Step>
+  <Step title="UV가 인증">
+    각 프라이빗 index에 대해 UV가 AMP에서 구성한 환경 변수에서
+    `UV_INDEX_{NAME}_USERNAME`과 `UV_INDEX_{NAME}_PASSWORD`를 조회합니다.
+  </Step>
+  <Step title="패키지 설치">
+    UV가 공개(PyPI) 및 프라이빗(레지스트리) 패키지를 모두 다운로드하고 설치합니다.
+  </Step>
+  <Step title="자동화 실행">
+    모든 의존성이 사용 가능한 상태에서 crew 또는 flow가 시작됩니다.
+  </Step>
+</Steps>
+
+## 문제 해결
+
+### 빌드 중 인증 오류
+
+**증상**: 프라이빗 패키지를 해결할 때 `401 Unauthorized` 또는 `403 Forbidden`으로 빌드가 실패합니다.
+
+**확인사항**:
+- `UV_INDEX_*` 환경 변수 이름이 index 이름과 정확히 일치하는지 확인합니다 (대문자, 하이픈 -> 언더스코어)
+- 자격 증명이 로컬 `.env`뿐만 아니라 AMP 환경 변수에 설정되어 있는지 확인합니다
+- 토큰/PAT에 패키지 피드에 필요한 읽기 권한이 있는지 확인합니다
+- 토큰이 만료되지 않았는지 확인합니다 (특히 AWS CodeArtifact의 경우)
+
+### 패키지를 찾을 수 없음
+
+**증상**: `No matching distribution found for my-private-package`.
+
+**확인사항**:
+- `pyproject.toml`의 index URL이 `/simple/`로 끝나는지 확인합니다
+- `[tool.uv.sources]` 항목이 올바른 패키지 이름을 올바른 index 이름에 매핑하는지 확인합니다
+- 패키지가 실제로 프라이빗 레지스트리에 게시되어 있는지 확인합니다
+- 동일한 자격 증명으로 로컬에서 `uv lock`을 실행하여 해결이 작동하는지 확인합니다
+
+### Lock 파일 충돌
+
+**증상**: 프라이빗 index를 추가한 후 `uv lock`이 실패하거나 예상치 못한 결과를 생성합니다.
+
+**해결책**: 로컬에서 자격 증명을 설정하고 다시 생성합니다:
+
+```bash
+export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
+export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
+uv lock
+```
+
+그런 다음 업데이트된 `uv.lock`을 커밋합니다.
+
+## 관련 가이드
+
+<CardGroup cols={3}>
+  <Card title="배포 준비하기" icon="clipboard-check" href="/ko/enterprise/guides/prepare-for-deployment">
+    배포 전에 프로젝트 구조와 의존성을 확인합니다.
+  </Card>
+  <Card title="AMP에 배포하기" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
+    crew 또는 flow를 배포하고 환경 변수를 구성합니다.
+  </Card>
+  <Card title="Crew 업데이트하기" icon="arrows-rotate" href="/ko/enterprise/guides/update-crew">
+    환경 변수를 업데이트하고 실행 중인 배포에 변경 사항을 푸시합니다.
+  </Card>
+</CardGroup>

docs/ko/learn/llm-connections.mdx

@@ -7,7 +7,7 @@ mode: "wide"
 
 ## CrewAI를 LLM에 연결하기
 
-CrewAI는 LiteLLM을 사용하여 다양한 언어 모델(LLM)에 연결합니다. 이 통합은 높은 다양성을 제공하여, 여러 공급자의 모델을 간단하고 통합된 인터페이스로 사용할 수 있게 해줍니다.
+CrewAI는 가장 인기 있는 제공자(OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock)에 대해 네이티브 SDK 통합을 통해 LLM에 연결하며, 그 외 모든 제공자에 대해서는 LiteLLM을 유연한 폴백으로 사용합니다.
 
 <Note>
     기본적으로 CrewAI는 `gpt-4o-mini` 모델을 사용합니다. 이는 `OPENAI_MODEL_NAME` 환경 변수에 의해 결정되며, 설정되지 않은 경우 기본값은 "gpt-4o-mini"입니다.
@@ -41,6 +41,14 @@ LiteLLM은 다음을 포함하되 이에 국한되지 않는 다양한 프로바
 
 지원되는 프로바이더의 전체 및 최신 목록은 [LiteLLM 프로바이더 문서](https://docs.litellm.ai/docs/providers)를 참조하세요.
 
+<Info>
+  네이티브 통합에서 지원하지 않는 제공자를 사용하려면 LiteLLM을 프로젝트에 의존성으로 추가하세요:
+  ```bash
+  uv add 'crewai[litellm]'
+  ```
+  네이티브 제공자(OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock)는 자체 SDK extras를 사용합니다 — [공급자 구성 예시](/ko/concepts/llms#공급자-구성-예시)를 참조하세요.
+</Info>
+
 ## LLM 변경하기
 
 CrewAI agent에서 다른 LLM을 사용하려면 여러 가지 방법이 있습니다:

docs/ko/observability/tracing.mdx

@@ -35,7 +35,7 @@ crewai login
 아직 설치하지 않았다면 CLI 도구와 함께 CrewAI를 설치하세요:
 
 ```bash
-uv add crewai[tools]
+uv add 'crewai[tools]'
 ```
 
 그런 다음 CrewAI AMP 계정으로 CLI를 인증하세요:

docs/ko/tools/automation/composiotool.mdx

@@ -18,77 +18,46 @@ Composio는 AI 에이전트를 250개 이상의 도구와 연결할 수 있는
 Composio 도구를 프로젝트에 통합하려면 아래 지침을 따르세요:
 
 ```shell
-pip install composio-crewai
+pip install composio composio-crewai
 pip install crewai
 ```
 
-설치가 완료된 후, `composio login`을 실행하거나 Composio API 키를 `COMPOSIO_API_KEY`로 export하세요. Composio API 키는 [여기](https://app.composio.dev)에서 받을 수 있습니다.
+설치가 완료되면 Composio API 키를 `COMPOSIO_API_KEY`로 설정하세요. Composio API 키는 [여기](https://platform.composio.dev)에서 받을 수 있습니다.
 
 ## 예시
 
-다음 예시는 도구를 초기화하고 github action을 실행하는 방법을 보여줍니다:
+다음 예시는 도구를 초기화하고 GitHub 액션을 실행하는 방법을 보여줍니다:
 
-1. Composio 도구 세트 초기화
+1. CrewAI Provider와 함께 Composio 초기화
 
 ```python Code
-from composio_crewai import ComposioToolSet, App, Action
+from composio_crewai import ComposioProvider
+from composio import Composio
 from crewai import Agent, Task, Crew
 
-toolset = ComposioToolSet()
+composio = Composio(provider=ComposioProvider())
 ```
 
-2. GitHub 계정 연결
+2. 새 Composio 세션을 만들고 도구 가져오기
 <CodeGroup>
-```shell CLI
-composio add github
-```
-```python Code
-request = toolset.initiate_connection(app=App.GITHUB)
-print(f"Open this URL to authenticate: {request.redirectUrl}")
+```python
+session = composio.create(
+    user_id="your-user-id",
+    toolkits=["gmail", "github"] # optional, default is all toolkits
+)
+tools = session.tools()
 ```
+세션 및 사용자 관리에 대한 자세한 내용은 [여기](https://docs.composio.dev/docs/configuring-sessions)를 참고하세요.
 </CodeGroup>
 
-3. 도구 가져오기
+3. 사용자 수동 인증하기
 
-- 앱에서 모든 도구를 가져오기 (프로덕션 환경에서는 권장하지 않음):
+Composio는 에이전트 채팅 세션 중에 사용자를 자동으로 인증합니다. 하지만 `authorize` 메서드를 호출해 사용자를 수동으로 인증할 수도 있습니다.
 ```python Code
-tools = toolset.get_tools(apps=[App.GITHUB])
+connection_request = session.authorize("github")
+print(f"Open this URL to authenticate: {connection_request.redirect_url}")
 ```
 
-- 태그를 기반으로 도구 필터링:
-```python Code
-tag = "users"
-
-filtered_action_enums = toolset.find_actions_by_tags(
-    App.GITHUB,
-    tags=[tag], 
-)
-
-tools = toolset.get_tools(actions=filtered_action_enums)
-```
-
-- 사용 사례를 기반으로 도구 필터링:
-```python Code
-use_case = "Star a repository on GitHub"
-
-filtered_action_enums = toolset.find_actions_by_use_case(
-    App.GITHUB, use_case=use_case, advanced=False
-)
-
-tools = toolset.get_tools(actions=filtered_action_enums)
-```
-<Tip>`advanced`를 True로 설정하면 복잡한 사용 사례를 위한 액션을 가져올 수 있습니다</Tip>
-
-- 특정 도구 사용하기:
-
-이 데모에서는 GitHub 앱의 `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` 액션을 사용합니다.
-```python Code
-tools = toolset.get_tools(
-    actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER]
-)
-```
-액션 필터링에 대해 더 자세한 내용을 보려면 [여기](https://docs.composio.dev/patterns/tools/use-tools/use-specific-actions)를 참고하세요.
-
 4. 에이전트 정의
 
 ```python Code
@@ -116,4 +85,4 @@ crew = Crew(agents=[crewai_agent], tasks=[task])
 crew.kickoff()
 ```
 
-* 더욱 자세한 도구 리스트는 [여기](https://app.composio.dev)에서 확인하실 수 있습니다.
+* 더욱 자세한 도구 목록은 [여기](https://docs.composio.dev/toolkits)에서 확인할 수 있습니다.

docs/pt-BR/changelog.mdx

@@ -4,6 +4,106 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="27 fev 2026">
+  ## v1.10.1a1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1a1)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Implementar suporte a invocação assíncrona em métodos de callback de etapas
+  - Implementar carregamento sob demanda para dependências pesadas no módulo de Memória
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.10.0
+
+  ### Refatoração
+  - Refatorar métodos de callback de etapas para suportar invocação assíncrona
+  - Refatorar para implementar carregamento sob demanda para dependências pesadas no módulo de Memória
+
+  ### Correções de Bugs
+  - Corrigir branch para notas de lançamento
+
+  ## Contribuidores
+
+  @greysonlalonde, @joaomdmoura
+
+</Update>
+
+<Update label="27 fev 2026">
+  ## v1.10.1a1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1a1)
+
+  ## O que Mudou
+
+  ### Refatoração
+  - Refatorar métodos de callback de etapas para suportar invocação assíncrona
+  - Implementar carregamento sob demanda para dependências pesadas no módulo de Memória
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.10.0
+
+  ### Correções de Bugs
+  - Criar branch para notas de lançamento
+
+  ## Contribuidores
+
+  @greysonlalonde, @joaomdmoura
+
+</Update>
+
+<Update label="26 fev 2026">
+  ## v1.10.0
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.0)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Aprimorar a resolução da ferramenta MCP e eventos relacionados
+  - Atualizar a versão do lancedb e adicionar pacotes lance-namespace
+  - Aprimorar a análise e validação de argumentos JSON no CrewAgentExecutor e BaseTool
+  - Migrar o cliente HTTP da CLI de requests para httpx
+  - Adicionar documentação versionada
+  - Adicionar detecção de versões removidas para notas de versão
+  - Implementar tratamento de entrada do usuário em Flows
+  - Aprimorar a funcionalidade de auto-loop HITL nos testes de integração de feedback humano
+  - Adicionar started_event_id e definir no eventbus
+  - Atualizar automaticamente tools.specs
+
+  ### Correções de Bugs
+  - Validar kwargs da ferramenta mesmo quando vazios para evitar TypeError crípticos
+  - Preservar tipos nulos nos esquemas de parâmetros da ferramenta para LLM
+  - Mapear output_pydantic/output_json para saída estruturada nativa
+  - Garantir que callbacks sejam executados/aguardados se forem promessas
+  - Capturar o nome do método no contexto da exceção
+  - Preservar tipo enum no resultado do roteador; melhorar tipos
+  - Corrigir fluxos cíclicos que quebram silenciosamente quando o ID de persistência é passado nas entradas
+  - Corrigir o formato da flag da CLI de --skip-provider para --skip_provider
+  - Garantir que o fluxo de chamada da ferramenta OpenAI seja finalizado
+  - Resolver ponteiros $ref de esquema complexos nas ferramentas MCP
+  - Impor additionalProperties=false nos esquemas
+  - Rejeitar nomes de scripts reservados para pastas de equipe
+  - Resolver condição de corrida no teste de emissão de eventos de guardrail
+
+  ### Documentação
+  - Adicionar nota de dependência litellm para provedores de LLM não nativos
+  - Esclarecer o modelo de segurança NL2SQL e orientações de fortalecimento
+  - Adicionar 96 ações ausentes em 9 integrações
+
+  ### Refatoração
+  - Refatorar crew para provider
+  - Extrair HITL para padrão de provider
+  - Melhorar tipagem e registro de hooks
+
+  ## Contribuidores
+
+  @dependabot[bot], @github-actions[bot], @github-code-quality[bot], @greysonlalonde, @heitorado, @hobostay, @joaomdmoura, @johnvan7, @jonathansampson, @lorenzejay, @lucasgomide, @mattatcha, @mplachta, @nicoferdi96, @theCyberTech, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="26 jan 2026">
   ## v1.9.0
 

docs/pt-BR/concepts/llms.mdx

@@ -105,6 +105,15 @@ Existem diferentes locais no código do CrewAI onde você pode especificar o mod
   </Tab>
 </Tabs>
 
+<Info>
+  O CrewAI oferece integrações nativas via SDK para OpenAI, Anthropic, Google (Gemini API), Azure e AWS Bedrock — sem necessidade de instalação extra além dos extras específicos do provedor (ex.: `uv add "crewai[openai]"`).
+
+  Todos os outros provedores são alimentados pelo **LiteLLM**. Se você planeja usar algum deles, adicione-o como dependência ao seu projeto:
+  ```bash
+  uv add 'crewai[litellm]'
+  ```
+</Info>
+
 ## Exemplos de Configuração de Provedores
 
 O CrewAI suporta uma grande variedade de provedores de LLM, cada um com recursos, métodos de autenticação e capacidades de modelo únicos.
@@ -214,6 +223,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
     | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Texto, Imagem | Texto |
     | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | Texto | Texto |
     | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | Texto | Texto |
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Anthropic">
@@ -354,6 +368,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
     | gemini-1.5-flash                 | 1M tokens          | Modelo multimodal equilibrado, bom para maioria das tarefas         |
     | gemini-1.5-flash-8B              | 1M tokens          | Mais rápido, mais eficiente em custo, adequado para tarefas de alta frequência |
     | gemini-1.5-pro                   | 2M tokens          | Melhor desempenho para uma ampla variedade de tarefas de raciocínio, incluindo lógica, codificação e colaboração criativa |
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Azure">
@@ -438,6 +457,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         model="sagemaker/<my-endpoint>"
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Mistral">
@@ -453,6 +477,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         temperature=0.7
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Nvidia NIM">
@@ -539,6 +568,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
     | rakuten/rakutenai-7b-instruct                                            | 1.024 tokens       | LLM topo de linha, compreensão, raciocínio e geração textual.|
     | rakuten/rakutenai-7b-chat                                                | 1.024 tokens       | LLM topo de linha, compreensão, raciocínio e geração textual.|
     | baichuan-inc/baichuan2-13b-chat                                          | 4.096 tokens       | Suporte a chat em chinês/inglês, programação, matemática, seguir instruções, resolver quizzes.|
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Local NVIDIA NIM Deployed using WSL2">
@@ -579,6 +613,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
 
         # ...
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Groq">
@@ -600,6 +639,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
     | Llama 3.1 70B/8B  | 131.072 tokens      | Alta performance e tarefas de contexto grande|
     | Llama 3.2 Série   | 8.192 tokens        | Tarefas gerais                          |
     | Mixtral 8x7B      | 32.768 tokens       | Equilíbrio entre performance e contexto  |
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="IBM watsonx.ai">
@@ -622,6 +666,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         base_url="https://api.watsonx.ai/v1"
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Ollama (LLMs Locais)">
@@ -635,6 +684,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         base_url="http://localhost:11434"
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Fireworks AI">
@@ -650,6 +704,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         temperature=0.7
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Perplexity AI">
@@ -665,6 +724,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         base_url="https://api.perplexity.ai/"
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Hugging Face">
@@ -679,6 +743,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
         model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct"
     )
     ```
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="SambaNova">
@@ -702,6 +771,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
     | Llama 3.2 Série   | 8.192 tokens              | Tarefas gerais e multimodais                 |
     | Llama 3.3 70B     | Até 131.072 tokens        | Desempenho e qualidade de saída elevada      |
     | Família Qwen2     | 8.192 tokens              | Desempenho e qualidade de saída elevada      |
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Cerebras">
@@ -727,6 +801,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
       - Equilíbrio entre velocidade e qualidade
       - Suporte a longas janelas de contexto
     </Info>
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 
   <Accordion title="Open Router">
@@ -749,6 +828,11 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
       - openrouter/deepseek/deepseek-r1
       - openrouter/deepseek/deepseek-chat
     </Info>
+
+    **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
   </Accordion>
 </AccordionGroup>
 

docs/pt-BR/enterprise/guides/deploy-to-amp.mdx

@@ -176,6 +176,11 @@ Você precisa enviar seu crew para um repositório do GitHub. Caso ainda não te
       ![Definir Variáveis de Ambiente](/images/enterprise/set-env-variables.png)
     </Frame>
 
+    <Info>
+      Usando pacotes Python privados? Você também precisará adicionar suas credenciais de registro aqui.
+      Consulte [Registros de Pacotes Privados](/pt-BR/enterprise/guides/private-package-registry) para as variáveis necessárias.
+    </Info>
+
   </Step>
 
   <Step title="Implante Seu Crew">

docs/pt-BR/enterprise/guides/prepare-for-deployment.mdx

@@ -256,6 +256,12 @@ Antes da implantação, certifique-se de ter:
 1. **Chaves de API de LLM** prontas (OpenAI, Anthropic, Google, etc.)
 2. **Chaves de API de ferramentas** se estiver usando ferramentas externas (Serper, etc.)
 
+<Info>
+  Se seu projeto depende de pacotes de um **registro PyPI privado**, você também precisará configurar
+  credenciais de autenticação do registro como variáveis de ambiente. Consulte o guia
+  [Registros de Pacotes Privados](/pt-BR/enterprise/guides/private-package-registry) para mais detalhes.
+</Info>
+
 <Tip>
   Teste seu projeto localmente com as mesmas variáveis de ambiente antes de implantar
   para detectar problemas de configuração antecipadamente.

docs/pt-BR/enterprise/guides/private-package-registry.mdx

@@ -0,0 +1,263 @@
+---
+title: "Registros de Pacotes Privados"
+description: "Instale pacotes Python privados de registros PyPI autenticados no CrewAI AMP"
+icon: "lock"
+mode: "wide"
+---
+
+<Note>
+  Este guia aborda como configurar seu projeto CrewAI para instalar pacotes Python
+  de registros PyPI privados (Azure DevOps Artifacts, GitHub Packages, GitLab, AWS CodeArtifact, etc.)
+  ao implantar no CrewAI AMP.
+</Note>
+
+## Quando Você Precisa Disso
+
+Se seu projeto depende de pacotes Python internos ou proprietários hospedados em um registro privado
+em vez do PyPI público, você precisará:
+
+1. Informar ao UV **onde** encontrar o pacote (uma URL de index)
+2. Informar ao UV **quais** pacotes vêm desse index (um mapeamento de source)
+3. Fornecer **credenciais** para que o UV possa autenticar durante a instalação
+
+O CrewAI AMP usa [UV](https://docs.astral.sh/uv/) para resolução e instalação de dependências.
+O UV suporta registros privados autenticados por meio da configuração do `pyproject.toml` combinada
+com variáveis de ambiente para credenciais.
+
+## Passo 1: Configurar o pyproject.toml
+
+Três elementos trabalham juntos no seu `pyproject.toml`:
+
+### 1a. Declarar a dependência
+
+Adicione o pacote privado ao seu `[project.dependencies]` como qualquer outra dependência:
+
+```toml
+[project]
+dependencies = [
+    "crewai[tools]>=0.100.1,<1.0.0",
+    "my-private-package>=1.2.0",
+]
+```
+
+### 1b. Definir o index
+
+Registre seu registro privado como um index nomeado em `[[tool.uv.index]]`:
+
+```toml
+[[tool.uv.index]]
+name = "my-private-registry"
+url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
+explicit = true
+```
+
+<Info>
+  O campo `name` é importante — o UV o utiliza para construir os nomes das variáveis de ambiente
+  para autenticação (veja o [Passo 2](#passo-2-configurar-credenciais-de-autenticação) abaixo).
+
+  Definir `explicit = true` significa que o UV não consultará esse index para todos os pacotes — apenas
+  os que você mapear explicitamente em `[tool.uv.sources]`. Isso evita consultas desnecessárias
+  ao seu registro privado e protege contra ataques de confusão de dependências.
+</Info>
+
+### 1c. Mapear o pacote para o index
+
+Informe ao UV quais pacotes devem ser resolvidos a partir do seu index privado usando `[tool.uv.sources]`:
+
+```toml
+[tool.uv.sources]
+my-private-package = { index = "my-private-registry" }
+```
+
+### Exemplo completo
+
+```toml
+[project]
+name = "my-crew-project"
+version = "0.1.0"
+requires-python = ">=3.10,<=3.13"
+dependencies = [
+    "crewai[tools]>=0.100.1,<1.0.0",
+    "my-private-package>=1.2.0",
+]
+
+[tool.crewai]
+type = "crew"
+
+[[tool.uv.index]]
+name = "my-private-registry"
+url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
+explicit = true
+
+[tool.uv.sources]
+my-private-package = { index = "my-private-registry" }
+```
+
+Após atualizar o `pyproject.toml`, regenere seu arquivo lock:
+
+```bash
+uv lock
+```
+
+<Warning>
+  Sempre faça commit do `uv.lock` atualizado junto com as alterações no `pyproject.toml`.
+  O arquivo lock é obrigatório para implantação — veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment).
+</Warning>
+
+## Passo 2: Configurar Credenciais de Autenticação
+
+O UV autentica em indexes privados usando variáveis de ambiente que seguem uma convenção de nomenclatura
+baseada no nome do index que você definiu no `pyproject.toml`:
+
+```
+UV_INDEX_{UPPER_NAME}_USERNAME
+UV_INDEX_{UPPER_NAME}_PASSWORD
+```
+
+Onde `{UPPER_NAME}` é o nome do seu index convertido para **maiúsculas** com **hifens substituídos por underscores**.
+
+Por exemplo, um index chamado `my-private-registry` usa:
+
+| Variável | Valor |
+|----------|-------|
+| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | Seu nome de usuário ou nome do token do registro |
+| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | Sua senha ou token/PAT do registro |
+
+<Warning>
+  Essas variáveis de ambiente **devem** ser adicionadas pelas configurações de **Variáveis de Ambiente** do CrewAI AMP —
+  globalmente ou no nível da implantação. Elas não podem ser definidas em arquivos `.env` ou codificadas no seu projeto.
+
+  Veja [Configurar Variáveis de Ambiente no AMP](#configurar-variáveis-de-ambiente-no-amp) abaixo.
+</Warning>
+
+## Referência de Provedores de Registro
+
+A tabela abaixo mostra o formato da URL de index e os valores de credenciais para provedores de registro comuns.
+Substitua os valores de exemplo pelos detalhes reais da sua organização e feed.
+
+| Provedor | URL do Index | Usuário | Senha |
+|----------|-------------|---------|-------|
+| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | Qualquer string não vazia (ex: `token`) | Personal Access Token (PAT) com escopo Packaging Read |
+| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | Nome de usuário do GitHub | Personal Access Token (classic) com escopo `read:packages` |
+| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project ou Personal Access Token com escopo `read_api` |
+| **AWS CodeArtifact** | Use a URL de `aws codeartifact get-repository-endpoint` | `aws` | Token de `aws codeartifact get-authorization-token` |
+| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Chave de conta de serviço codificada em Base64 |
+| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | Nome de usuário ou email | Chave API ou token de identidade |
+| **Auto-hospedado (devpi, Nexus, etc.)** | URL da API simple do seu registro | Nome de usuário do registro | Senha do registro |
+
+<Tip>
+  Para **AWS CodeArtifact**, o token de autorização expira periodicamente.
+  Você precisará atualizar o valor de `UV_INDEX_*_PASSWORD` quando ele expirar.
+  Considere automatizar isso no seu pipeline de CI/CD.
+</Tip>
+
+## Configurar Variáveis de Ambiente no AMP
+
+As credenciais do registro privado devem ser configuradas como variáveis de ambiente no CrewAI AMP.
+Você tem duas opções:
+
+<Tabs>
+  <Tab title="Interface Web">
+    1. Faça login no [CrewAI AMP](https://app.crewai.com)
+    2. Navegue até sua automação
+    3. Abra a aba **Environment Variables**
+    4. Adicione cada variável (`UV_INDEX_*_USERNAME` e `UV_INDEX_*_PASSWORD`) com seu valor
+
+    Veja o passo [Deploy para AMP — Definir Variáveis de Ambiente](/pt-BR/enterprise/guides/deploy-to-amp#definir-as-variáveis-de-ambiente) para detalhes.
+  </Tab>
+  <Tab title="Implantação via CLI">
+    Adicione as variáveis ao seu arquivo `.env` local antes de executar `crewai deploy create`.
+    A CLI as transferirá com segurança para a plataforma:
+
+    ```bash
+    # .env
+    OPENAI_API_KEY=sk-...
+    UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
+    UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here
+    ```
+
+    ```bash
+    crewai deploy create
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+  **Nunca** faça commit de credenciais no seu repositório. Use variáveis de ambiente do AMP para todos os segredos.
+  O arquivo `.env` deve estar listado no `.gitignore`.
+</Warning>
+
+Para atualizar credenciais em uma implantação existente, veja [Atualizar Seu Crew — Variáveis de Ambiente](/pt-BR/enterprise/guides/update-crew).
+
+## Como Tudo se Conecta
+
+Quando o CrewAI AMP faz o build da sua automação, o fluxo de resolução funciona assim:
+
+<Steps>
+  <Step title="Build inicia">
+    O AMP busca seu repositório e lê o `pyproject.toml` e o `uv.lock`.
+  </Step>
+  <Step title="UV resolve dependências">
+    O UV lê `[tool.uv.sources]` para determinar de qual index cada pacote deve vir.
+  </Step>
+  <Step title="UV autentica">
+    Para cada index privado, o UV busca `UV_INDEX_{NAME}_USERNAME` e `UV_INDEX_{NAME}_PASSWORD`
+    nas variáveis de ambiente que você configurou no AMP.
+  </Step>
+  <Step title="Pacotes são instalados">
+    O UV baixa e instala todos os pacotes — tanto públicos (do PyPI) quanto privados (do seu registro).
+  </Step>
+  <Step title="Automação executa">
+    Seu crew ou flow inicia com todas as dependências disponíveis.
+  </Step>
+</Steps>
+
+## Solução de Problemas
+
+### Erros de Autenticação Durante o Build
+
+**Sintoma**: Build falha com `401 Unauthorized` ou `403 Forbidden` ao resolver um pacote privado.
+
+**Verifique**:
+- Os nomes das variáveis de ambiente `UV_INDEX_*` correspondem exatamente ao nome do seu index (maiúsculas, hifens -> underscores)
+- As credenciais estão definidas nas variáveis de ambiente do AMP, não apenas em um `.env` local
+- Seu token/PAT tem as permissões de leitura necessárias para o feed de pacotes
+- O token não expirou (especialmente relevante para AWS CodeArtifact)
+
+### Pacote Não Encontrado
+
+**Sintoma**: `No matching distribution found for my-private-package`.
+
+**Verifique**:
+- A URL do index no `pyproject.toml` termina com `/simple/`
+- A entrada `[tool.uv.sources]` mapeia o nome correto do pacote para o nome correto do index
+- O pacote está realmente publicado no seu registro privado
+- Execute `uv lock` localmente com as mesmas credenciais para verificar se a resolução funciona
+
+### Conflitos no Arquivo Lock
+
+**Sintoma**: `uv lock` falha ou produz resultados inesperados após adicionar um index privado.
+
+**Solução**: Defina as credenciais localmente e regenere:
+
+```bash
+export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
+export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
+uv lock
+```
+
+Em seguida, faça commit do `uv.lock` atualizado.
+
+## Guias Relacionados
+
+<CardGroup cols={3}>
+  <Card title="Preparar para Implantação" icon="clipboard-check" href="/pt-BR/enterprise/guides/prepare-for-deployment">
+    Verifique a estrutura do projeto e as dependências antes de implantar.
+  </Card>
+  <Card title="Deploy para AMP" icon="rocket" href="/pt-BR/enterprise/guides/deploy-to-amp">
+    Implante seu crew ou flow e configure variáveis de ambiente.
+  </Card>
+  <Card title="Atualizar Seu Crew" icon="arrows-rotate" href="/pt-BR/enterprise/guides/update-crew">
+    Atualize variáveis de ambiente e envie alterações para uma implantação em execução.
+  </Card>
+</CardGroup>

docs/pt-BR/learn/llm-connections.mdx

@@ -7,7 +7,7 @@ mode: "wide"
 
 ## Conecte o CrewAI a LLMs
 
-O CrewAI utiliza o LiteLLM para conectar-se a uma grande variedade de Modelos de Linguagem (LLMs). Essa integração proporciona grande versatilidade, permitindo que você utilize modelos de inúmeros provedores por meio de uma interface simples e unificada.
+O CrewAI conecta-se a LLMs por meio de integrações nativas via SDK para os provedores mais populares (OpenAI, Anthropic, Google Gemini, Azure e AWS Bedrock), e usa o LiteLLM como alternativa flexível para todos os demais provedores.
 
 <Note>
     Por padrão, o CrewAI usa o modelo `gpt-4o-mini`. Isso é determinado pela variável de ambiente `OPENAI_MODEL_NAME`, que tem como padrão "gpt-4o-mini" se não for definida.
@@ -40,6 +40,14 @@ O LiteLLM oferece suporte a uma ampla gama de provedores, incluindo, mas não se
 
 Para uma lista completa e sempre atualizada dos provedores suportados, consulte a [documentação de Provedores do LiteLLM](https://docs.litellm.ai/docs/providers).
 
+<Info>
+  Para usar qualquer provedor não coberto por uma integração nativa, adicione o LiteLLM como dependência ao seu projeto:
+  ```bash
+  uv add 'crewai[litellm]'
+  ```
+  Provedores nativos (OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock) usam seus próprios extras de SDK — consulte os [Exemplos de Configuração de Provedores](/pt-BR/concepts/llms#exemplos-de-configuração-de-provedores).
+</Info>
+
 ## Alterando a LLM
 
 Para utilizar uma LLM diferente com seus agentes CrewAI, você tem várias opções:

docs/pt-BR/tools/automation/composiotool.mdx

@@ -11,84 +11,53 @@ mode: "wide"
 Composio é uma plataforma de integração que permite conectar seus agentes de IA a mais de 250 ferramentas. Os principais recursos incluem:
 
 - **Autenticação de Nível Empresarial**: Suporte integrado para OAuth, Chaves de API, JWT com atualização automática de token
-- **Observabilidade Completa**: Logs detalhados de uso das ferramentas, registros de execução, e muito mais
+- **Observabilidade Completa**: Logs detalhados de uso das ferramentas, carimbos de data/hora de execução e muito mais
 
 ## Instalação
 
 Para incorporar as ferramentas Composio em seu projeto, siga as instruções abaixo:
 
 ```shell
-pip install composio-crewai
+pip install composio composio-crewai
 pip install crewai
 ```
 
-Após a conclusão da instalação, execute `composio login` ou exporte sua chave de API do composio como `COMPOSIO_API_KEY`. Obtenha sua chave de API Composio [aqui](https://app.composio.dev)
+Após concluir a instalação, defina sua chave de API do Composio como `COMPOSIO_API_KEY`. Obtenha sua chave de API do Composio [aqui](https://platform.composio.dev)
 
 ## Exemplo
 
-O exemplo a seguir demonstra como inicializar a ferramenta e executar uma ação do github:
+O exemplo a seguir demonstra como inicializar a ferramenta e executar uma ação do GitHub:
 
-1. Inicialize o conjunto de ferramentas Composio
+1. Inicialize o Composio com o Provider do CrewAI
 
 ```python Code
-from composio_crewai import ComposioToolSet, App, Action
+from composio_crewai import ComposioProvider
+from composio import Composio
 from crewai import Agent, Task, Crew
 
-toolset = ComposioToolSet()
+composio = Composio(provider=ComposioProvider())
 ```
 
-2. Conecte sua conta do GitHub
+2. Crie uma nova sessão Composio e recupere as ferramentas
 <CodeGroup>
-```shell CLI
-composio add github
-```
-```python Code
-request = toolset.initiate_connection(app=App.GITHUB)
-print(f"Open this URL to authenticate: {request.redirectUrl}")
+```python
+session = composio.create(
+    user_id="your-user-id",
+    toolkits=["gmail", "github"] # optional, default is all toolkits
+)
+tools = session.tools()
 ```
+Leia mais sobre sessões e gerenciamento de usuários [aqui](https://docs.composio.dev/docs/configuring-sessions)
 </CodeGroup>
 
-3. Obtenha ferramentas
+3. Autenticação manual dos usuários
 
-- Recuperando todas as ferramentas de um app (não recomendado em produção):
+O Composio autentica automaticamente os usuários durante a sessão de chat do agente. No entanto, você também pode autenticar o usuário manualmente chamando o método `authorize`.
 ```python Code
-tools = toolset.get_tools(apps=[App.GITHUB])
+connection_request = session.authorize("github")
+print(f"Open this URL to authenticate: {connection_request.redirect_url}")
 ```
 
-- Filtrando ferramentas com base em tags:
-```python Code
-tag = "users"
-
-filtered_action_enums = toolset.find_actions_by_tags(
-    App.GITHUB,
-    tags=[tag], 
-)
-
-tools = toolset.get_tools(actions=filtered_action_enums)
-```
-
-- Filtrando ferramentas com base no caso de uso:
-```python Code
-use_case = "Star a repository on GitHub"
-
-filtered_action_enums = toolset.find_actions_by_use_case(
-    App.GITHUB, use_case=use_case, advanced=False
-)
-
-tools = toolset.get_tools(actions=filtered_action_enums)
-```
-<Tip>Defina `advanced` como True para obter ações para casos de uso complexos</Tip>
-
-- Usando ferramentas específicas:
-
-Neste exemplo, usaremos a ação `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` do app GitHub.
-```python Code
-tools = toolset.get_tools(
-    actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER]
-)
-```
-Saiba mais sobre como filtrar ações [aqui](https://docs.composio.dev/patterns/tools/use-tools/use-specific-actions)
-
 4. Defina o agente
 
 ```python Code
@@ -116,4 +85,4 @@ crew = Crew(agents=[crewai_agent], tasks=[task])
 crew.kickoff()
 ```
 
-* Uma lista mais detalhada de ferramentas pode ser encontrada [aqui](https://app.composio.dev)
+* Uma lista mais detalhada de ferramentas pode ser encontrada [aqui](https://docs.composio.dev/toolkits)

lib/crewai-files/pyproject.toml

@@ -8,8 +8,8 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "Pillow~=10.4.0",
-    "pypdf~=4.0.0",
+    "Pillow~=12.1.1",
+    "pypdf~=6.7.4",
     "python-magic>=0.4.27",
     "aiocache~=0.12.3",
     "aiofiles~=24.1.0",

lib/crewai-files/src/crewai_files/__init__.py

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.9.3"
+__version__ = "1.10.1a1"

lib/crewai-tools/pyproject.toml

@@ -8,12 +8,10 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "lancedb~=0.5.4",
     "pytube~=15.0.0",
     "requests~=2.32.5",
     "docker~=7.1.0",
-    "crewai==1.9.3",
-    "lancedb~=0.5.4",
+    "crewai==1.10.1a1",
     "tiktoken~=0.8.0",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -291,4 +291,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.9.3"
+__version__ = "1.10.1a1"

lib/crewai-tools/tool.specs.json

@@ -20117,18 +20117,6 @@
       "humanized_name": "Web Automation Tool",
       "init_params_schema": {
         "$defs": {
-          "AvailableModel": {
-            "enum": [
-              "gpt-4o",
-              "gpt-4o-mini",
-              "claude-3-5-sonnet-latest",
-              "claude-3-7-sonnet-latest",
-              "computer-use-preview",
-              "gemini-2.0-flash"
-            ],
-            "title": "AvailableModel",
-            "type": "string"
-          },
           "EnvVar": {
             "properties": {
               "default": {
@@ -20206,17 +20194,6 @@
             "default": null,
             "title": "Model Api Key"
           },
-          "model_name": {
-            "anyOf": [
-              {
-                "$ref": "#/$defs/AvailableModel"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": "claude-3-7-sonnet-latest"
-          },
           "project_id": {
             "anyOf": [
               {

lib/crewai/pyproject.toml

@@ -42,7 +42,7 @@ dependencies = [
     "mcp~=1.26.0",
     "uv~=0.9.13",
     "aiosqlite~=0.21.0",
-    "lancedb>=0.4.0",
+    "lancedb>=0.29.2",
 ]
 
 [project.urls]
@@ -53,7 +53,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.9.3",
+    "crewai-tools==1.10.1a1",
 ]
 embeddings = [
     "tiktoken~=0.8.0"
@@ -66,7 +66,7 @@ openpyxl = [
 ]
 mem0 = ["mem0ai~=0.1.94"]
 docling = [
-    "docling~=2.63.0",
+    "docling~=2.75.0",
 ]
 qdrant = [
     "qdrant-client[fastembed]~=1.14.3",

lib/crewai/src/crewai/__init__.py

@@ -4,14 +4,12 @@ import urllib.request
 import warnings
 
 from crewai.agent.core import Agent
-from crewai.agent.planning_config import PlanningConfig
 from crewai.crew import Crew
 from crewai.crews.crew_output import CrewOutput
 from crewai.flow.flow import Flow
 from crewai.knowledge.knowledge import Knowledge
 from crewai.llm import LLM
 from crewai.llms.base_llm import BaseLLM
-from crewai.memory.unified_memory import Memory
 from crewai.process import Process
 from crewai.task import Task
 from crewai.tasks.llm_guardrail import LLMGuardrail
@@ -42,7 +40,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.9.3"
+__version__ = "1.10.1a1"
 _telemetry_submitted = False
 
 
@@ -73,6 +71,25 @@ def _track_install_async() -> None:
 
 
 _track_install_async()
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "Memory": ("crewai.memory.unified_memory", "Memory"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import heavy modules (e.g. Memory → lancedb) on first access."""
+    if name in _LAZY_IMPORTS:
+        module_path, attr = _LAZY_IMPORTS[name]
+        import importlib
+
+        mod = importlib.import_module(module_path)
+        val = getattr(mod, attr)
+        globals()[name] = val
+        return val
+    raise AttributeError(f"module 'crewai' has no attribute {name!r}")
+
+
 __all__ = [
     "LLM",
     "Agent",
@@ -83,7 +100,6 @@ __all__ = [
     "Knowledge",
     "LLMGuardrail",
     "Memory",
-    "PlanningConfig",
     "Process",
     "Task",
     "TaskOutput",

lib/crewai/src/crewai/a2a/utils/agent_card.py

@@ -138,12 +138,24 @@ def fetch_agent_card(
         ttl_hash = int(time.time() // cache_ttl)
         return _fetch_agent_card_cached(endpoint, auth_hash, timeout, ttl_hash)
 
+    coro = afetch_agent_card(endpoint=endpoint, auth=auth, timeout=timeout)
+
+    try:
+        asyncio.get_running_loop()
+        # Already inside an event loop (e.g. Jupyter notebook) - run the
+        # coroutine in a separate thread with its own event loop.
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(asyncio.run, coro)
+            return future.result()
+    except RuntimeError:
+        pass
+
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
     try:
-        return loop.run_until_complete(
-            afetch_agent_card(endpoint=endpoint, auth=auth, timeout=timeout)
-        )
+        return loop.run_until_complete(coro)
     finally:
         loop.close()
 

lib/crewai/src/crewai/a2a/utils/delegation.py

@@ -158,13 +158,10 @@ def execute_a2a_delegation(
 ) -> TaskStateResult:
     """Execute a task delegation to a remote A2A agent synchronously.
 
-    WARNING: This function blocks the entire thread by creating and running a new
-    event loop. Prefer using 'await aexecute_a2a_delegation()' in async contexts
-    for better performance and resource efficiency.
-
-    This is a synchronous wrapper around aexecute_a2a_delegation that creates a
-    new event loop to run the async implementation. It is provided for compatibility
-    with synchronous code paths only.
+    This is a synchronous wrapper around aexecute_a2a_delegation. When no event
+    loop is running it creates a new one; when called from within an existing
+    event loop (e.g. Jupyter notebooks) it transparently runs the coroutine in
+    a separate thread to avoid "cannot run nested event loop" errors.
 
     Args:
         endpoint: A2A agent endpoint URL (AgentCard URL).
@@ -194,51 +191,51 @@ def execute_a2a_delegation(
 
     Returns:
         TaskStateResult with status, result/error, history, and agent_card.
-
-    Raises:
-        RuntimeError: If called from an async context with a running event loop.
     """
+    coro = aexecute_a2a_delegation(
+        endpoint=endpoint,
+        auth=auth,
+        timeout=timeout,
+        task_description=task_description,
+        context=context,
+        context_id=context_id,
+        task_id=task_id,
+        reference_task_ids=reference_task_ids,
+        metadata=metadata,
+        extensions=extensions,
+        conversation_history=conversation_history,
+        agent_id=agent_id,
+        agent_role=agent_role,
+        agent_branch=agent_branch,
+        response_model=response_model,
+        turn_number=turn_number,
+        updates=updates,
+        from_task=from_task,
+        from_agent=from_agent,
+        skill_id=skill_id,
+        client_extensions=client_extensions,
+        transport=transport,
+        accepted_output_modes=accepted_output_modes,
+        input_files=input_files,
+    )
+
     try:
         asyncio.get_running_loop()
-        raise RuntimeError(
-            "execute_a2a_delegation() cannot be called from an async context. "
-            "Use 'await aexecute_a2a_delegation()' instead."
-        )
-    except RuntimeError as e:
-        if "no running event loop" not in str(e).lower():
-            raise
+        # Already inside an event loop (e.g. Jupyter notebook) - run the
+        # coroutine in a separate thread with its own event loop so we don't
+        # block or conflict with the running one.
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(asyncio.run, coro)
+            return future.result()
+    except RuntimeError:
+        pass
 
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
     try:
-        return loop.run_until_complete(
-            aexecute_a2a_delegation(
-                endpoint=endpoint,
-                auth=auth,
-                timeout=timeout,
-                task_description=task_description,
-                context=context,
-                context_id=context_id,
-                task_id=task_id,
-                reference_task_ids=reference_task_ids,
-                metadata=metadata,
-                extensions=extensions,
-                conversation_history=conversation_history,
-                agent_id=agent_id,
-                agent_role=agent_role,
-                agent_branch=agent_branch,
-                response_model=response_model,
-                turn_number=turn_number,
-                updates=updates,
-                from_task=from_task,
-                from_agent=from_agent,
-                skill_id=skill_id,
-                client_extensions=client_extensions,
-                transport=transport,
-                accepted_output_modes=accepted_output_modes,
-                input_files=input_files,
-            )
-        )
+        return loop.run_until_complete(coro)
     finally:
         try:
             loop.run_until_complete(loop.shutdown_asyncgens())

lib/crewai/src/crewai/agent/core.py

@@ -8,11 +8,9 @@ import time
 from typing import (
     TYPE_CHECKING,
     Any,
-    Final,
     Literal,
     cast,
 )
-from urllib.parse import urlparse
 
 from pydantic import (
     BaseModel,
@@ -24,7 +22,6 @@ from pydantic import (
 )
 from typing_extensions import Self
 
-from crewai.agent.planning_config import PlanningConfig
 from crewai.agent.utils import (
     ahandle_knowledge_retrieval,
     apply_training_data,
@@ -62,16 +59,8 @@ from crewai.knowledge.knowledge import Knowledge
 from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
 from crewai.lite_agent_output import LiteAgentOutput
 from crewai.llms.base_llm import BaseLLM
-from crewai.mcp import (
-    MCPClient,
-    MCPServerConfig,
-    MCPServerHTTP,
-    MCPServerSSE,
-    MCPServerStdio,
-)
-from crewai.mcp.transports.http import HTTPTransport
-from crewai.mcp.transports.sse import SSETransport
-from crewai.mcp.transports.stdio import StdioTransport
+from crewai.mcp import MCPServerConfig
+from crewai.mcp.tool_resolver import MCPToolResolver
 from crewai.rag.embeddings.types import EmbedderConfig
 from crewai.security.fingerprint import Fingerprint
 from crewai.tools.agent_tools.agent_tools import AgentTools
@@ -112,18 +101,8 @@ if TYPE_CHECKING:
     from crewai.utilities.types import LLMMessage
 
 
-# MCP Connection timeout constants (in seconds)
-MCP_CONNECTION_TIMEOUT: Final[int] = 10
-MCP_TOOL_EXECUTION_TIMEOUT: Final[int] = 30
-MCP_DISCOVERY_TIMEOUT: Final[int] = 15
-MCP_MAX_RETRIES: Final[int] = 3
-
 _passthrough_exceptions: tuple[type[Exception], ...] = ()
 
-# Simple in-memory cache for MCP tool schemas (duration: 5 minutes)
-_mcp_schema_cache: dict[str, Any] = {}
-_cache_ttl: Final[int] = 300  # 5 minutes
-
 
 class Agent(BaseAgent):
     """Represents an agent in a system.
@@ -155,7 +134,7 @@ class Agent(BaseAgent):
     model_config = ConfigDict()
 
     _times_executed: int = PrivateAttr(default=0)
-    _mcp_clients: list[Any] = PrivateAttr(default_factory=list)
+    _mcp_resolver: MCPToolResolver | None = PrivateAttr(default=None)
     _last_messages: list[LLMMessage] = PrivateAttr(default_factory=list)
     max_execution_time: int | None = Field(
         default=None,
@@ -212,23 +191,13 @@ class Agent(BaseAgent):
         default="safe",
         description="Mode for code execution: 'safe' (using Docker) or 'unsafe' (direct execution).",
     )
-    planning_config: PlanningConfig | None = Field(
-        default=None,
-        description="Configuration for agent planning before task execution.",
-    )
-    planning: bool = Field(
+    reasoning: bool = Field(
         default=False,
         description="Whether the agent should reflect and create a plan before executing a task.",
     )
-    reasoning: bool = Field(
-        default=False,
-        description="[DEPRECATED: Use planning_config instead] Whether the agent should reflect and create a plan before executing a task.",
-        deprecated=True,
-    )
     max_reasoning_attempts: int | None = Field(
         default=None,
-        description="[DEPRECATED: Use planning_config.max_attempts instead] Maximum number of reasoning attempts before executing the task. If None, will try until ready.",
-        deprecated=True,
+        description="Maximum number of reasoning attempts before executing the task. If None, will try until ready.",
     )
     embedder: EmbedderConfig | None = Field(
         default=None,
@@ -295,26 +264,8 @@ class Agent(BaseAgent):
         if self.allow_code_execution:
             self._validate_docker_installation()
 
-        # Handle backward compatibility: convert reasoning=True to planning_config
-        if self.reasoning and self.planning_config is None:
-            import warnings
-
-            warnings.warn(
-                "The 'reasoning' parameter is deprecated. Use 'planning_config=PlanningConfig()' instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            self.planning_config = PlanningConfig(
-                max_attempts=self.max_reasoning_attempts,
-            )
-
         return self
 
-    @property
-    def planning_enabled(self) -> bool:
-        """Check if planning is enabled for this agent."""
-        return self.planning_config is not None or self.planning
-
     def _setup_agent_executor(self) -> None:
         if not self.cache_handler:
             self.cache_handler = CacheHandler()
@@ -383,11 +334,7 @@ class Agent(BaseAgent):
             ValueError: If the max execution time is not a positive integer.
             RuntimeError: If the agent execution fails for other reasons.
         """
-        # Only call handle_reasoning for legacy CrewAgentExecutor
-        # For AgentExecutor, planning is handled in AgentExecutor.generate_plan()
-        if self.executor_class is not AgentExecutor:
-            handle_reasoning(self, task)
-
+        handle_reasoning(self, task)
         self._inject_date_to_task(task)
 
         if self.tools_handler:
@@ -417,10 +364,10 @@ class Agent(BaseAgent):
                 )
                 if unified_memory is not None:
                     query = task.description
-                    matches = unified_memory.recall(query, limit=10)
+                    matches = unified_memory.recall(query, limit=5)
                     if matches:
                         memory = "Relevant memories:\n" + "\n".join(
-                            f"- {m.record.content}" for m in matches
+                            m.format() for m in matches
                         )
                 if memory.strip() != "":
                     task_prompt += self.i18n.slice("memory").format(memory=memory)
@@ -625,10 +572,7 @@ class Agent(BaseAgent):
             ValueError: If the max execution time is not a positive integer.
             RuntimeError: If the agent execution fails for other reasons.
         """
-        if self.executor_class is not AgentExecutor:
-            handle_reasoning(
-                self, task
-            )  # we need this till CrewAgentExecutor migrates to AgentExecutor
+        handle_reasoning(self, task)
         self._inject_date_to_task(task)
 
         if self.tools_handler:
@@ -658,10 +602,10 @@ class Agent(BaseAgent):
                 )
                 if unified_memory is not None:
                     query = task.description
-                    matches = unified_memory.recall(query, limit=10)
+                    matches = unified_memory.recall(query, limit=5)
                     if matches:
                         memory = "Relevant memories:\n" + "\n".join(
-                            f"- {m.record.content}" for m in matches
+                            m.format() for m in matches
                         )
                 if memory.strip() != "":
                     task_prompt += self.i18n.slice("memory").format(memory=memory)
@@ -900,7 +844,11 @@ class Agent(BaseAgent):
                 respect_context_window=self.respect_context_window,
                 request_within_rpm_limit=rpm_limit_fn,
                 callbacks=[TokenCalcHandler(self._token_process)],
-                response_model=task.response_model if task else None,
+                response_model=(
+                    task.response_model or task.output_pydantic or task.output_json
+                )
+                if task
+                else None,
             )
 
     def _update_executor_parameters(
@@ -929,7 +877,11 @@ class Agent(BaseAgent):
         self.agent_executor.stop = stop_words
         self.agent_executor.tools_names = get_tool_names(tools)
         self.agent_executor.tools_description = render_text_description_and_args(tools)
-        self.agent_executor.response_model = task.response_model if task else None
+        self.agent_executor.response_model = (
+            (task.response_model or task.output_pydantic or task.output_json)
+            if task
+            else None
+        )
 
         self.agent_executor.tools_handler = self.tools_handler
         self.agent_executor.request_within_rpm_limit = rpm_limit_fn
@@ -962,544 +914,17 @@ class Agent(BaseAgent):
     def get_mcp_tools(self, mcps: list[str | MCPServerConfig]) -> list[BaseTool]:
         """Convert MCP server references/configs to CrewAI tools.
 
-        Supports both string references (backwards compatible) and structured
-        configuration objects (MCPServerStdio, MCPServerHTTP, MCPServerSSE).
-
-        Args:
-            mcps: List of MCP server references (strings) or configurations.
-
-        Returns:
-            List of BaseTool instances from MCP servers.
+        Delegates to :class:`~crewai.mcp.tool_resolver.MCPToolResolver`.
         """
-        all_tools = []
-        clients = []
-
-        for mcp_config in mcps:
-            if isinstance(mcp_config, str):
-                tools = self._get_mcp_tools_from_string(mcp_config)
-            else:
-                tools, client = self._get_native_mcp_tools(mcp_config)
-                if client:
-                    clients.append(client)
-
-            all_tools.extend(tools)
-
-        # Store clients for cleanup
-        self._mcp_clients.extend(clients)
-        return all_tools
+        self._cleanup_mcp_clients()
+        self._mcp_resolver = MCPToolResolver(agent=self, logger=self._logger)
+        return self._mcp_resolver.resolve(mcps)
 
     def _cleanup_mcp_clients(self) -> None:
         """Cleanup MCP client connections after task execution."""
-        if not self._mcp_clients:
-            return
-
-        async def _disconnect_all() -> None:
-            for client in self._mcp_clients:
-                if client and hasattr(client, "connected") and client.connected:
-                    await client.disconnect()
-
-        try:
-            asyncio.run(_disconnect_all())
-        except Exception as e:
-            self._logger.log("error", f"Error during MCP client cleanup: {e}")
-        finally:
-            self._mcp_clients.clear()
-
-    def _get_mcp_tools_from_string(self, mcp_ref: str) -> list[BaseTool]:
-        """Get tools from legacy string-based MCP references.
-
-        This method maintains backwards compatibility with string-based
-        MCP references (https://... and crewai-amp:...).
-
-        Args:
-            mcp_ref: String reference to MCP server.
-
-        Returns:
-            List of BaseTool instances.
-        """
-        if mcp_ref.startswith("crewai-amp:"):
-            return self._get_amp_mcp_tools(mcp_ref)
-        if mcp_ref.startswith("https://"):
-            return self._get_external_mcp_tools(mcp_ref)
-        return []
-
-    def _get_external_mcp_tools(self, mcp_ref: str) -> list[BaseTool]:
-        """Get tools from external HTTPS MCP server with graceful error handling."""
-        from crewai.tools.mcp_tool_wrapper import MCPToolWrapper
-
-        # Parse server URL and optional tool name
-        if "#" in mcp_ref:
-            server_url, specific_tool = mcp_ref.split("#", 1)
-        else:
-            server_url, specific_tool = mcp_ref, None
-
-        server_params = {"url": server_url}
-        server_name = self._extract_server_name(server_url)
-
-        try:
-            # Get tool schemas with timeout and error handling
-            tool_schemas = self._get_mcp_tool_schemas(server_params)
-
-            if not tool_schemas:
-                self._logger.log(
-                    "warning", f"No tools discovered from MCP server: {server_url}"
-                )
-                return []
-
-            tools = []
-            for tool_name, schema in tool_schemas.items():
-                # Skip if specific tool requested and this isn't it
-                if specific_tool and tool_name != specific_tool:
-                    continue
-
-                try:
-                    wrapper = MCPToolWrapper(
-                        mcp_server_params=server_params,
-                        tool_name=tool_name,
-                        tool_schema=schema,
-                        server_name=server_name,
-                    )
-                    tools.append(wrapper)
-                except Exception as e:
-                    self._logger.log(
-                        "warning",
-                        f"Failed to create MCP tool wrapper for {tool_name}: {e}",
-                    )
-                    continue
-
-            if specific_tool and not tools:
-                self._logger.log(
-                    "warning",
-                    f"Specific tool '{specific_tool}' not found on MCP server: {server_url}",
-                )
-
-            return cast(list[BaseTool], tools)
-
-        except Exception as e:
-            self._logger.log(
-                "warning", f"Failed to connect to MCP server {server_url}: {e}"
-            )
-            return []
-
-    def _get_native_mcp_tools(
-        self, mcp_config: MCPServerConfig
-    ) -> tuple[list[BaseTool], Any | None]:
-        """Get tools from MCP server using structured configuration.
-
-        This method creates an MCP client based on the configuration type,
-        connects to the server, discovers tools, applies filtering, and
-        returns wrapped tools along with the client instance for cleanup.
-
-        Args:
-            mcp_config: MCP server configuration (MCPServerStdio, MCPServerHTTP, or MCPServerSSE).
-
-        Returns:
-            Tuple of (list of BaseTool instances, MCPClient instance for cleanup).
-        """
-        from crewai.tools.base_tool import BaseTool
-        from crewai.tools.mcp_native_tool import MCPNativeTool
-
-        transport: StdioTransport | HTTPTransport | SSETransport
-        if isinstance(mcp_config, MCPServerStdio):
-            transport = StdioTransport(
-                command=mcp_config.command,
-                args=mcp_config.args,
-                env=mcp_config.env,
-            )
-            server_name = f"{mcp_config.command}_{'_'.join(mcp_config.args)}"
-        elif isinstance(mcp_config, MCPServerHTTP):
-            transport = HTTPTransport(
-                url=mcp_config.url,
-                headers=mcp_config.headers,
-                streamable=mcp_config.streamable,
-            )
-            server_name = self._extract_server_name(mcp_config.url)
-        elif isinstance(mcp_config, MCPServerSSE):
-            transport = SSETransport(
-                url=mcp_config.url,
-                headers=mcp_config.headers,
-            )
-            server_name = self._extract_server_name(mcp_config.url)
-        else:
-            raise ValueError(f"Unsupported MCP server config type: {type(mcp_config)}")
-
-        client = MCPClient(
-            transport=transport,
-            cache_tools_list=mcp_config.cache_tools_list,
-        )
-
-        async def _setup_client_and_list_tools() -> list[dict[str, Any]]:
-            """Async helper to connect and list tools in same event loop."""
-
-            try:
-                if not client.connected:
-                    await client.connect()
-
-                tools_list = await client.list_tools()
-
-                try:
-                    await client.disconnect()
-                    # Small delay to allow background tasks to finish cleanup
-                    # This helps prevent "cancel scope in different task" errors
-                    # when asyncio.run() closes the event loop
-                    await asyncio.sleep(0.1)
-                except Exception as e:
-                    self._logger.log("error", f"Error during disconnect: {e}")
-
-                return tools_list
-            except Exception as e:
-                if client.connected:
-                    await client.disconnect()
-                    await asyncio.sleep(0.1)
-                raise RuntimeError(
-                    f"Error during setup client and list tools: {e}"
-                ) from e
-
-        try:
-            try:
-                asyncio.get_running_loop()
-                import concurrent.futures
-
-                with concurrent.futures.ThreadPoolExecutor() as executor:
-                    future = executor.submit(
-                        asyncio.run, _setup_client_and_list_tools()
-                    )
-                    tools_list = future.result()
-            except RuntimeError:
-                try:
-                    tools_list = asyncio.run(_setup_client_and_list_tools())
-                except RuntimeError as e:
-                    error_msg = str(e).lower()
-                    if "cancel scope" in error_msg or "task" in error_msg:
-                        raise ConnectionError(
-                            "MCP connection failed due to event loop cleanup issues. "
-                            "This may be due to authentication errors or server unavailability."
-                        ) from e
-                except asyncio.CancelledError as e:
-                    raise ConnectionError(
-                        "MCP connection was cancelled. This may indicate an authentication "
-                        "error or server unavailability."
-                    ) from e
-
-            if mcp_config.tool_filter:
-                filtered_tools = []
-                for tool in tools_list:
-                    if callable(mcp_config.tool_filter):
-                        try:
-                            from crewai.mcp.filters import ToolFilterContext
-
-                            context = ToolFilterContext(
-                                agent=self,
-                                server_name=server_name,
-                                run_context=None,
-                            )
-                            if mcp_config.tool_filter(context, tool):  # type: ignore[call-arg, arg-type]
-                                filtered_tools.append(tool)
-                        except (TypeError, AttributeError):
-                            if mcp_config.tool_filter(tool):  # type: ignore[call-arg, arg-type]
-                                filtered_tools.append(tool)
-                    else:
-                        # Not callable - include tool
-                        filtered_tools.append(tool)
-                tools_list = filtered_tools
-
-            tools = []
-            for tool_def in tools_list:
-                tool_name = tool_def.get("name", "")
-                if not tool_name:
-                    continue
-
-                # Convert inputSchema to Pydantic model if present
-                args_schema = None
-                if tool_def.get("inputSchema"):
-                    args_schema = self._json_schema_to_pydantic(
-                        tool_name, tool_def["inputSchema"]
-                    )
-
-                tool_schema = {
-                    "description": tool_def.get("description", ""),
-                    "args_schema": args_schema,
-                }
-
-                try:
-                    native_tool = MCPNativeTool(
-                        mcp_client=client,
-                        tool_name=tool_name,
-                        tool_schema=tool_schema,
-                        server_name=server_name,
-                    )
-                    tools.append(native_tool)
-                except Exception as e:
-                    self._logger.log("error", f"Failed to create native MCP tool: {e}")
-                    continue
-
-            return cast(list[BaseTool], tools), client
-        except Exception as e:
-            if client.connected:
-                asyncio.run(client.disconnect())
-
-            raise RuntimeError(f"Failed to get native MCP tools: {e}") from e
-
-    def _get_amp_mcp_tools(self, amp_ref: str) -> list[BaseTool]:
-        """Get tools from CrewAI AMP MCP marketplace."""
-        # Parse: "crewai-amp:mcp-name" or "crewai-amp:mcp-name#tool_name"
-        amp_part = amp_ref.replace("crewai-amp:", "")
-        if "#" in amp_part:
-            mcp_name, specific_tool = amp_part.split("#", 1)
-        else:
-            mcp_name, specific_tool = amp_part, None
-
-        # Call AMP API to get MCP server URLs
-        mcp_servers = self._fetch_amp_mcp_servers(mcp_name)
-
-        tools = []
-        for server_config in mcp_servers:
-            server_ref = server_config["url"]
-            if specific_tool:
-                server_ref += f"#{specific_tool}"
-            server_tools = self._get_external_mcp_tools(server_ref)
-            tools.extend(server_tools)
-
-        return tools
-
-    @staticmethod
-    def _extract_server_name(server_url: str) -> str:
-        """Extract clean server name from URL for tool prefixing."""
-
-        parsed = urlparse(server_url)
-        domain = parsed.netloc.replace(".", "_")
-        path = parsed.path.replace("/", "_").strip("_")
-        return f"{domain}_{path}" if path else domain
-
-    def _get_mcp_tool_schemas(
-        self, server_params: dict[str, Any]
-    ) -> dict[str, dict[str, Any]]:
-        """Get tool schemas from MCP server for wrapper creation with caching."""
-        server_url = server_params["url"]
-
-        # Check cache first
-        cache_key = server_url
-        current_time = time.time()
-
-        if cache_key in _mcp_schema_cache:
-            cached_data, cache_time = _mcp_schema_cache[cache_key]
-            if current_time - cache_time < _cache_ttl:
-                self._logger.log(
-                    "debug", f"Using cached MCP tool schemas for {server_url}"
-                )
-                return cached_data  # type: ignore[no-any-return]
-
-        try:
-            schemas = asyncio.run(self._get_mcp_tool_schemas_async(server_params))
-
-            # Cache successful results
-            _mcp_schema_cache[cache_key] = (schemas, current_time)
-
-            return schemas
-        except Exception as e:
-            # Log warning but don't raise - this allows graceful degradation
-            self._logger.log(
-                "warning", f"Failed to get MCP tool schemas from {server_url}: {e}"
-            )
-            return {}
-
-    async def _get_mcp_tool_schemas_async(
-        self, server_params: dict[str, Any]
-    ) -> dict[str, dict[str, Any]]:
-        """Async implementation of MCP tool schema retrieval with timeouts and retries."""
-        server_url = server_params["url"]
-        return await self._retry_mcp_discovery(
-            self._discover_mcp_tools_with_timeout, server_url
-        )
-
-    async def _retry_mcp_discovery(
-        self, operation_func: Any, server_url: str
-    ) -> dict[str, dict[str, Any]]:
-        """Retry MCP discovery operation with exponential backoff, avoiding try-except in loop."""
-        last_error = None
-
-        for attempt in range(MCP_MAX_RETRIES):
-            # Execute single attempt outside try-except loop structure
-            result, error, should_retry = await self._attempt_mcp_discovery(
-                operation_func, server_url
-            )
-
-            # Success case - return immediately
-            if result is not None:
-                return result
-
-            # Non-retryable error - raise immediately
-            if not should_retry:
-                raise RuntimeError(error)
-
-            # Retryable error - continue with backoff
-            last_error = error
-            if attempt < MCP_MAX_RETRIES - 1:
-                wait_time = 2**attempt  # Exponential backoff
-                await asyncio.sleep(wait_time)
-
-        raise RuntimeError(
-            f"Failed to discover MCP tools after {MCP_MAX_RETRIES} attempts: {last_error}"
-        )
-
-    @staticmethod
-    async def _attempt_mcp_discovery(
-        operation_func: Any, server_url: str
-    ) -> tuple[dict[str, dict[str, Any]] | None, str, bool]:
-        """Attempt single MCP discovery operation and return (result, error_message, should_retry)."""
-        try:
-            result = await operation_func(server_url)
-            return result, "", False
-
-        except ImportError:
-            return (
-                None,
-                "MCP library not available. Please install with: pip install mcp",
-                False,
-            )
-
-        except asyncio.TimeoutError:
-            return (
-                None,
-                f"MCP discovery timed out after {MCP_DISCOVERY_TIMEOUT} seconds",
-                True,
-            )
-
-        except Exception as e:
-            error_str = str(e).lower()
-
-            # Classify errors as retryable or non-retryable
-            if "authentication" in error_str or "unauthorized" in error_str:
-                return None, f"Authentication failed for MCP server: {e!s}", False
-            if "connection" in error_str or "network" in error_str:
-                return None, f"Network connection failed: {e!s}", True
-            if "json" in error_str or "parsing" in error_str:
-                return None, f"Server response parsing error: {e!s}", True
-            return None, f"MCP discovery error: {e!s}", False
-
-    async def _discover_mcp_tools_with_timeout(
-        self, server_url: str
-    ) -> dict[str, dict[str, Any]]:
-        """Discover MCP tools with timeout wrapper."""
-        return await asyncio.wait_for(
-            self._discover_mcp_tools(server_url), timeout=MCP_DISCOVERY_TIMEOUT
-        )
-
-    async def _discover_mcp_tools(self, server_url: str) -> dict[str, dict[str, Any]]:
-        """Discover tools from MCP server with proper timeout handling."""
-        from mcp import ClientSession
-        from mcp.client.streamable_http import streamablehttp_client
-
-        async with streamablehttp_client(server_url) as (read, write, _):
-            async with ClientSession(read, write) as session:
-                # Initialize the connection with timeout
-                await asyncio.wait_for(
-                    session.initialize(), timeout=MCP_CONNECTION_TIMEOUT
-                )
-
-                # List available tools with timeout
-                tools_result = await asyncio.wait_for(
-                    session.list_tools(),
-                    timeout=MCP_DISCOVERY_TIMEOUT - MCP_CONNECTION_TIMEOUT,
-                )
-
-                schemas = {}
-                for tool in tools_result.tools:
-                    args_schema = None
-                    if hasattr(tool, "inputSchema") and tool.inputSchema:
-                        args_schema = self._json_schema_to_pydantic(
-                            sanitize_tool_name(tool.name), tool.inputSchema
-                        )
-
-                    schemas[sanitize_tool_name(tool.name)] = {
-                        "description": getattr(tool, "description", ""),
-                        "args_schema": args_schema,
-                    }
-                return schemas
-
-    def _json_schema_to_pydantic(
-        self, tool_name: str, json_schema: dict[str, Any]
-    ) -> type:
-        """Convert JSON Schema to Pydantic model for tool arguments.
-
-        Args:
-            tool_name: Name of the tool (used for model naming)
-            json_schema: JSON Schema dict with 'properties', 'required', etc.
-
-        Returns:
-            Pydantic BaseModel class
-        """
-        from pydantic import Field, create_model
-
-        properties = json_schema.get("properties", {})
-        required_fields = json_schema.get("required", [])
-
-        field_definitions: dict[str, Any] = {}
-
-        for field_name, field_schema in properties.items():
-            field_type = self._json_type_to_python(field_schema)
-            field_description = field_schema.get("description", "")
-
-            is_required = field_name in required_fields
-
-            if is_required:
-                field_definitions[field_name] = (
-                    field_type,
-                    Field(..., description=field_description),
-                )
-            else:
-                field_definitions[field_name] = (
-                    field_type | None,
-                    Field(default=None, description=field_description),
-                )
-
-        model_name = f"{tool_name.replace('-', '_').replace(' ', '_')}Schema"
-        return create_model(model_name, **field_definitions)  # type: ignore[no-any-return]
-
-    def _json_type_to_python(self, field_schema: dict[str, Any]) -> type:
-        """Convert JSON Schema type to Python type.
-
-        Args:
-            field_schema: JSON Schema field definition
-
-        Returns:
-            Python type
-        """
-
-        json_type = field_schema.get("type")
-
-        if "anyOf" in field_schema:
-            types: list[type] = []
-            for option in field_schema["anyOf"]:
-                if "const" in option:
-                    types.append(str)
-                else:
-                    types.append(self._json_type_to_python(option))
-            unique_types = list(set(types))
-            if len(unique_types) > 1:
-                result: Any = unique_types[0]
-                for t in unique_types[1:]:
-                    result = result | t
-                return result  # type: ignore[no-any-return]
-            return unique_types[0]
-
-        type_mapping: dict[str | None, type] = {
-            "string": str,
-            "number": float,
-            "integer": int,
-            "boolean": bool,
-            "array": list,
-            "object": dict,
-        }
-
-        return type_mapping.get(json_type, Any)
-
-    @staticmethod
-    def _fetch_amp_mcp_servers(mcp_name: str) -> list[dict[str, Any]]:
-        """Fetch MCP server configurations from CrewAI AMP API."""
-        # TODO: Implement AMP API call to "integrations/mcps" endpoint
-        # Should return list of server configs with URLs
-        return []
+        if self._mcp_resolver is not None:
+            self._mcp_resolver.cleanup()
+            self._mcp_resolver = None
 
     @staticmethod
     def get_multimodal_tools() -> Sequence[BaseTool]:
@@ -1839,11 +1264,11 @@ class Agent(BaseAgent):
                     ),
                 )
                 start_time = time.time()
-                matches = agent_memory.recall(formatted_messages, limit=10)
+                matches = agent_memory.recall(formatted_messages, limit=5)
                 memory_block = ""
                 if matches:
                     memory_block = "Relevant memories:\n" + "\n".join(
-                        f"- {m.record.content}" for m in matches
+                        m.format() for m in matches
                     )
                 if memory_block:
                     formatted_messages += "\n\n" + self.i18n.slice("memory").format(
@@ -1989,19 +1414,17 @@ class Agent(BaseAgent):
         except Exception as e:
             self._logger.log("error", f"Failed to save kickoff result to memory: {e}")
 
-    def _build_output_from_result(
+    def _execute_and_build_output(
         self,
-        result: dict[str, Any],
         executor: AgentExecutor,
+        inputs: dict[str, str],
         response_format: type[Any] | None = None,
     ) -> LiteAgentOutput:
-        """Build a LiteAgentOutput from an executor result dict.
-
-        Shared logic used by both sync and async execution paths.
+        """Execute the agent and build the output object.
 
         Args:
-            result: The result dictionary from executor.invoke / invoke_async.
             executor: The executor instance.
+            inputs: Input dictionary for execution.
             response_format: Optional response format.
 
         Returns:
@@ -2009,6 +1432,8 @@ class Agent(BaseAgent):
         """
         import json
 
+        # Execute the agent (this is called from sync path, so invoke returns dict)
+        result = cast(dict[str, Any], executor.invoke(inputs))
         output = result.get("output", "")
 
         # Handle response format conversion
@@ -2056,39 +1481,91 @@ class Agent(BaseAgent):
             else str(raw_output)
         )
 
-        todo_results = LiteAgentOutput.from_todo_items(executor.state.todos.items)
-
         return LiteAgentOutput(
             raw=raw_str,
             pydantic=formatted_result,
             agent_role=self.role,
             usage_metrics=usage_metrics.model_dump() if usage_metrics else None,
-            messages=list(executor.state.messages),
-            plan=executor.state.plan,
-            todos=todo_results,
-            replan_count=executor.state.replan_count,
-            last_replan_reason=executor.state.last_replan_reason,
+            messages=executor.messages,
         )
 
-    def _execute_and_build_output(
-        self,
-        executor: AgentExecutor,
-        inputs: dict[str, str],
-        response_format: type[Any] | None = None,
-    ) -> LiteAgentOutput:
-        """Execute the agent synchronously and build the output object."""
-        result = cast(dict[str, Any], executor.invoke(inputs))
-        return self._build_output_from_result(result, executor, response_format)
-
     async def _execute_and_build_output_async(
         self,
         executor: AgentExecutor,
         inputs: dict[str, str],
         response_format: type[Any] | None = None,
     ) -> LiteAgentOutput:
-        """Execute the agent asynchronously and build the output object."""
+        """Execute the agent asynchronously and build the output object.
+
+        This is the async version of _execute_and_build_output that uses
+        invoke_async() for native async execution within event loops.
+
+        Args:
+            executor: The executor instance.
+            inputs: Input dictionary for execution.
+            response_format: Optional response format.
+
+        Returns:
+            LiteAgentOutput with raw output, formatted result, and metrics.
+        """
+        import json
+
+        # Execute the agent asynchronously
         result = await executor.invoke_async(inputs)
-        return self._build_output_from_result(result, executor, response_format)
+        output = result.get("output", "")
+
+        # Handle response format conversion
+        formatted_result: BaseModel | None = None
+        raw_output: str
+
+        if isinstance(output, BaseModel):
+            formatted_result = output
+            raw_output = output.model_dump_json()
+        elif response_format:
+            raw_output = str(output) if not isinstance(output, str) else output
+            try:
+                model_schema = generate_model_description(response_format)
+                schema = json.dumps(model_schema, indent=2)
+                instructions = self.i18n.slice("formatted_task_instructions").format(
+                    output_format=schema
+                )
+
+                converter = Converter(
+                    llm=self.llm,
+                    text=raw_output,
+                    model=response_format,
+                    instructions=instructions,
+                )
+
+                conversion_result = converter.to_pydantic()
+                if isinstance(conversion_result, BaseModel):
+                    formatted_result = conversion_result
+            except ConverterError:
+                pass  # Keep raw output if conversion fails
+        else:
+            raw_output = str(output) if not isinstance(output, str) else output
+
+        # Get token usage metrics
+        if isinstance(self.llm, BaseLLM):
+            usage_metrics = self.llm.get_token_usage_summary()
+        else:
+            usage_metrics = self._token_process.get_summary()
+
+        raw_str = (
+            raw_output
+            if isinstance(raw_output, str)
+            else raw_output.model_dump_json()
+            if isinstance(raw_output, BaseModel)
+            else str(raw_output)
+        )
+
+        return LiteAgentOutput(
+            raw=raw_str,
+            pydantic=formatted_result,
+            agent_role=self.role,
+            usage_metrics=usage_metrics.model_dump() if usage_metrics else None,
+            messages=executor.messages,
+        )
 
     def _process_kickoff_guardrail(
         self,

lib/crewai/src/crewai/agent/planning_config.py

@@ -1,115 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Literal
-
-from pydantic import BaseModel, Field
-
-
-class PlanningConfig(BaseModel):
-    """Configuration for agent planning/reasoning before task execution.
-
-    This allows users to customize the planning behavior including prompts,
-    iteration limits, the LLM used for planning, and the reasoning effort
-    level that controls post-step observation and replanning behavior.
-
-    Note: To disable planning, don't pass a planning_config or set planning=False
-    on the Agent. The presence of a PlanningConfig enables planning.
-
-    Attributes:
-        reasoning_effort: Controls observation and replanning after each step.
-            - "low": Observe each step (validates success), but skip the
-              decide/replan/refine pipeline. Steps are marked complete and
-              execution continues linearly. Fastest option.
-            - "medium": Observe each step. On failure, trigger replanning.
-              On success, skip refinement and continue. Balanced option.
-            - "high": Full observation pipeline — observe every step, then
-              route through decide_next_action which can trigger early goal
-              achievement, full replanning, or lightweight refinement.
-              Most adaptive but adds latency per step.
-        max_attempts: Maximum number of planning refinement attempts.
-            If None, will continue until the agent indicates readiness.
-        max_steps: Maximum number of steps in the generated plan.
-        system_prompt: Custom system prompt for planning. Uses default if None.
-        plan_prompt: Custom prompt for creating the initial plan.
-        refine_prompt: Custom prompt for refining the plan.
-        llm: LLM to use for planning. Uses agent's LLM if None.
-
-    Example:
-        ```python
-        from crewai import Agent
-        from crewai.agent.planning_config import PlanningConfig
-
-        # Simple usage — fast, linear execution (default)
-        agent = Agent(
-            role="Researcher",
-            goal="Research topics",
-            backstory="Expert researcher",
-            planning_config=PlanningConfig(),
-        )
-
-        # Balanced — replan only when steps fail
-        agent = Agent(
-            role="Researcher",
-            goal="Research topics",
-            backstory="Expert researcher",
-            planning_config=PlanningConfig(
-                reasoning_effort="medium",
-            ),
-        )
-
-        # Full adaptive planning with refinement and replanning
-        agent = Agent(
-            role="Researcher",
-            goal="Research topics",
-            backstory="Expert researcher",
-            planning_config=PlanningConfig(
-                reasoning_effort="high",
-                max_attempts=3,
-                max_steps=10,
-                plan_prompt="Create a focused plan for: {description}",
-                llm="gpt-4o-mini",  # Use cheaper model for planning
-            ),
-        )
-        ```
-    """
-
-    reasoning_effort: Literal["low", "medium", "high"] = Field(
-        default="low",
-        description=(
-            "Controls post-step observation and replanning behavior. "
-            "'low' observes steps but skips replanning/refinement (fastest). "
-            "'medium' observes and replans only on step failure (balanced). "
-            "'high' runs full observation pipeline with replanning, refinement, "
-            "and early goal detection (most adaptive, highest latency)."
-        ),
-    )
-    max_attempts: int | None = Field(
-        default=None,
-        description=(
-            "Maximum number of planning refinement attempts. "
-            "If None, will continue until the agent indicates readiness."
-        ),
-    )
-    max_steps: int = Field(
-        default=20,
-        description="Maximum number of steps in the generated plan.",
-        ge=1,
-    )
-    system_prompt: str | None = Field(
-        default=None,
-        description="Custom system prompt for planning. Uses default if None.",
-    )
-    plan_prompt: str | None = Field(
-        default=None,
-        description="Custom prompt for creating the initial plan.",
-    )
-    refine_prompt: str | None = Field(
-        default=None,
-        description="Custom prompt for refining the plan.",
-    )
-    llm: str | Any | None = Field(
-        default=None,
-        description="LLM to use for planning. Uses agent's LLM if None.",
-    )
-
-    model_config = {"arbitrary_types_allowed": True}

lib/crewai/src/crewai/agent/utils.py

@@ -28,20 +28,13 @@ if TYPE_CHECKING:
 
 
 def handle_reasoning(agent: Agent, task: Task) -> None:
-    """Handle the reasoning/planning process for an agent before task execution.
-
-    This function checks if planning is enabled for the agent and, if so,
-    creates a plan that gets appended to the task description.
-
-    Note: This function is used by CrewAgentExecutor (legacy path).
-    For AgentExecutor, planning is handled in AgentExecutor.generate_plan().
+    """Handle the reasoning process for an agent before task execution.
 
     Args:
         agent: The agent performing the task.
         task: The task to execute.
     """
-    # Check if planning is enabled using the planning_enabled property
-    if not getattr(agent, "planning_enabled", False):
+    if not agent.reasoning:
         return
 
     try:
@@ -50,13 +43,13 @@ def handle_reasoning(agent: Agent, task: Task) -> None:
             AgentReasoningOutput,
         )
 
-        planning_handler = AgentReasoning(agent=agent, task=task)
-        planning_output: AgentReasoningOutput = (
-            planning_handler.handle_agent_reasoning()
+        reasoning_handler = AgentReasoning(task=task, agent=agent)
+        reasoning_output: AgentReasoningOutput = (
+            reasoning_handler.handle_agent_reasoning()
         )
-        task.description += f"\n\nPlanning:\n{planning_output.plan.plan}"
+        task.description += f"\n\nReasoning Plan:\n{reasoning_output.plan.plan}"
     except Exception as e:
-        agent._logger.log("error", f"Error during planning: {e!s}")
+        agent._logger.log("error", f"Error during reasoning process: {e!s}")
 
 
 def build_task_prompt_with_schema(task: Task, task_prompt: str, i18n: I18N) -> str:

lib/crewai/src/crewai/agents/agent_builder/base_agent.py

@@ -4,7 +4,8 @@ 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, Literal
+import re
+from typing import Any, Final, Literal
 import uuid
 
 from pydantic import (
@@ -36,6 +37,11 @@ from crewai.utilities.rpm_controller import RPMController
 from crewai.utilities.string_utils import interpolate_only
 
 
+_SLUG_RE: Final[re.Pattern[str]] = re.compile(
+    r"^(?:crewai-amp:)?[a-zA-Z0-9][a-zA-Z0-9_-]*(?:#\w+)?$"
+)
+
+
 PlatformApp = Literal[
     "asana",
     "box",
@@ -197,7 +203,7 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
     )
     mcps: list[str | MCPServerConfig] | None = Field(
         default=None,
-        description="List of MCP server references. Supports 'https://server.com/path' for external servers and 'crewai-amp:mcp-name' for AMP marketplace. Use '#tool_name' suffix for specific tools.",
+        description="List of MCP server references. Supports 'https://server.com/path' for external servers and bare slugs like 'notion' for connected MCP integrations. Use '#tool_name' suffix for specific tools.",
     )
     memory: Any = Field(
         default=None,
@@ -276,14 +282,16 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
         validated_mcps: list[str | MCPServerConfig] = []
         for mcp in mcps:
             if isinstance(mcp, str):
-                if mcp.startswith(("https://", "crewai-amp:")):
+                if mcp.startswith("https://"):
+                    validated_mcps.append(mcp)
+                elif _SLUG_RE.match(mcp):
                     validated_mcps.append(mcp)
                 else:
                     raise ValueError(
-                        f"Invalid MCP reference: {mcp}. "
-                        "String references must start with 'https://' or 'crewai-amp:'"
+                        f"Invalid MCP reference: {mcp!r}. "
+                        "String references must be an 'https://' URL or a valid "
+                        "slug (e.g. 'notion', 'notion#search', 'crewai-amp:notion')."
                     )
-
             elif isinstance(mcp, (MCPServerConfig)):
                 validated_mcps.append(mcp)
             else:

lib/crewai/src/crewai/agents/agent_builder/base_agent_executor_mixin.py

@@ -30,7 +30,7 @@ class CrewAgentExecutorMixin:
         memory = getattr(self.agent, "memory", None) or (
             getattr(self.crew, "_memory", None) if self.crew else None
         )
-        if memory is None or not self.task:
+        if memory is None or not self.task or getattr(memory, "_read_only", False):
             return
         if (
             f"Action: {sanitize_tool_name('Delegate work to coworker')}"

lib/crewai/src/crewai/agents/crew_agent_executor.py

@@ -50,6 +50,7 @@ from crewai.utilities.agent_utils import (
     handle_unknown_error,
     has_reached_max_iterations,
     is_context_length_exceeded,
+    parse_tool_call_args,
     process_llm_response,
     track_delegation_if_needed,
 )
@@ -486,8 +487,8 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
             # No tools available, fall back to simple LLM call
             return self._invoke_loop_native_no_tools()
 
-        openai_tools, available_functions = convert_tools_to_openai_schema(
-            self.original_tools
+        openai_tools, available_functions, self._tool_name_mapping = (
+            convert_tools_to_openai_schema(self.original_tools)
         )
 
         while True:
@@ -699,9 +700,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
         if not parsed_calls:
             return None
 
-        original_tools_by_name: dict[str, Any] = {}
-        for tool in self.original_tools or []:
-            original_tools_by_name[sanitize_tool_name(tool.name)] = tool
+        original_tools_by_name: dict[str, Any] = dict(self._tool_name_mapping)
 
         if len(parsed_calls) > 1:
             has_result_as_answer_in_batch = any(
@@ -894,13 +893,9 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
             ToolUsageStartedEvent,
         )
 
-        if isinstance(func_args, str):
-            try:
-                args_dict = json.loads(func_args)
-            except json.JSONDecodeError:
-                args_dict = {}
-        else:
-            args_dict = func_args
+        args_dict, parse_error = parse_tool_call_args(func_args, func_name, call_id, original_tool)
+        if parse_error is not None:
+            return parse_error
 
         if original_tool is None:
             for tool in self.original_tools or []:
@@ -952,10 +947,16 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
         track_delegation_if_needed(func_name, args_dict, self.task)
 
         structured_tool: CrewStructuredTool | None = None
-        for structured in self.tools or []:
-            if sanitize_tool_name(structured.name) == func_name:
-                structured_tool = structured
-                break
+        if original_tool is not None:
+            for structured in self.tools or []:
+                if getattr(structured, "_original_tool", None) is original_tool:
+                    structured_tool = structured
+                    break
+        if structured_tool is None:
+            for structured in self.tools or []:
+                if sanitize_tool_name(structured.name) == func_name:
+                    structured_tool = structured
+                    break
 
         hook_blocked = False
         before_hook_context = ToolCallHookContext(
@@ -1262,7 +1263,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
                         formatted_answer, tool_result
                     )
 
-                self._invoke_step_callback(formatted_answer)  # type: ignore[arg-type]
+                await self._ainvoke_step_callback(formatted_answer)  # type: ignore[arg-type]
                 self._append_message(formatted_answer.text)  # type: ignore[union-attr]
 
             except OutputParserError as e:
@@ -1315,8 +1316,8 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
         if not self.original_tools:
             return await self._ainvoke_loop_native_no_tools()
 
-        openai_tools, available_functions = convert_tools_to_openai_schema(
-            self.original_tools
+        openai_tools, available_functions, self._tool_name_mapping = (
+            convert_tools_to_openai_schema(self.original_tools)
         )
 
         while True:
@@ -1377,7 +1378,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
                         output=answer,
                         text=answer,
                     )
-                    self._invoke_step_callback(formatted_answer)
+                    await self._ainvoke_step_callback(formatted_answer)
                     self._append_message(answer)  # Save final answer to messages
                     self._show_logs(formatted_answer)
                     return formatted_answer
@@ -1389,7 +1390,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
                         output=answer,
                         text=output_json,
                     )
-                    self._invoke_step_callback(formatted_answer)
+                    await self._ainvoke_step_callback(formatted_answer)
                     self._append_message(output_json)
                     self._show_logs(formatted_answer)
                     return formatted_answer
@@ -1400,7 +1401,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
                     output=str(answer),
                     text=str(answer),
                 )
-                self._invoke_step_callback(formatted_answer)
+                await self._ainvoke_step_callback(formatted_answer)
                 self._append_message(str(answer))  # Save final answer to messages
                 self._show_logs(formatted_answer)
                 return formatted_answer
@@ -1494,7 +1495,7 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
     def _invoke_step_callback(
         self, formatted_answer: AgentAction | AgentFinish
     ) -> None:
-        """Invoke step callback.
+        """Invoke step callback (sync context).
 
         Args:
             formatted_answer: Current agent response.
@@ -1504,6 +1505,19 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):
             if inspect.iscoroutine(cb_result):
                 asyncio.run(cb_result)
 
+    async def _ainvoke_step_callback(
+        self, formatted_answer: AgentAction | AgentFinish
+    ) -> None:
+        """Invoke step callback (async context).
+
+        Args:
+            formatted_answer: Current agent response.
+        """
+        if self.step_callback:
+            cb_result = self.step_callback(formatted_answer)
+            if inspect.iscoroutine(cb_result):
+                await cb_result
+
     def _append_message(
         self, text: str, role: Literal["user", "assistant", "system"] = "assistant"
     ) -> None:

lib/crewai/src/crewai/agents/planner_observer.py

@@ -1,309 +0,0 @@
-"""PlannerObserver: Observation phase after each step execution.
-
-Implements the "Observe" phase. After every step execution, the Planner
-analyzes what happened, what new information was learned, and whether the
-remaining plan is still valid.
-
-This is NOT an error detector — it runs on every step, including successes,
-to incorporate runtime observations into the remaining plan.
-
-Refinements are structured (StepRefinement objects) and applied directly
-from the observation result — no second LLM call required.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import TYPE_CHECKING, Any
-
-from crewai.events.event_bus import crewai_event_bus
-from crewai.events.types.observation_events import (
-    StepObservationCompletedEvent,
-    StepObservationFailedEvent,
-    StepObservationStartedEvent,
-)
-from crewai.utilities.i18n import I18N, get_i18n
-from crewai.utilities.llm_utils import create_llm
-from crewai.utilities.planning_types import StepObservation, TodoItem
-from crewai.utilities.types import LLMMessage
-
-
-if TYPE_CHECKING:
-    from crewai.agent import Agent
-    from crewai.task import Task
-
-logger = logging.getLogger(__name__)
-
-
-class PlannerObserver:
-    """Observes step execution results and decides on plan continuation.
-
-    After EVERY step execution, this class:
-    1. Analyzes what the step accomplished
-    2. Identifies new information learned
-    3. Decides if the remaining plan is still valid
-    4. Suggests lightweight refinements or triggers full replanning
-
-    LLM resolution (magical fallback):
-    - If ``agent.planning_config.llm`` is explicitly set → use that
-    - Otherwise → fall back to ``agent.llm`` (same LLM for everything)
-
-    Args:
-        agent: The agent instance (for LLM resolution and config).
-        task: Optional task context (for description and expected output).
-    """
-
-    def __init__(
-        self,
-        agent: Agent,
-        task: Task | None = None,
-        kickoff_input: str = "",
-    ) -> None:
-        self.agent = agent
-        self.task = task
-        self.kickoff_input = kickoff_input
-        self.llm = self._resolve_llm()
-        self._i18n: I18N = get_i18n()
-
-    def _resolve_llm(self) -> Any:
-        """Resolve which LLM to use for observation/planning.
-
-        Mirrors AgentReasoning._resolve_llm(): uses planning_config.llm
-        if explicitly set, otherwise falls back to agent.llm.
-
-        Returns:
-            The resolved LLM instance.
-        """
-        from crewai.llm import LLM
-
-        config = getattr(self.agent, "planning_config", None)
-        if config is not None and config.llm is not None:
-            if isinstance(config.llm, LLM):
-                return config.llm
-            return create_llm(config.llm)
-        return self.agent.llm
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def observe(
-        self,
-        completed_step: TodoItem,
-        result: str,
-        all_completed: list[TodoItem],
-        remaining_todos: list[TodoItem],
-    ) -> StepObservation:
-        """Observe a step's result and decide on plan continuation.
-
-        This runs after EVERY step execution — not just failures.
-
-        Args:
-            completed_step: The todo item that was just executed.
-            result: The final result string from the step.
-            all_completed: All previously completed todos (for context).
-            remaining_todos: The pending todos still in the plan.
-
-        Returns:
-            StepObservation with the Planner's analysis. Any suggested
-            refinements are structured StepRefinement objects ready for
-            direct application — no second LLM call needed.
-        """
-        agent_role = self.agent.role
-
-        crewai_event_bus.emit(
-            self.agent,
-            event=StepObservationStartedEvent(
-                agent_role=agent_role,
-                step_number=completed_step.step_number,
-                step_description=completed_step.description,
-                from_task=self.task,
-                from_agent=self.agent,
-            ),
-        )
-
-        messages = self._build_observation_messages(
-            completed_step, result, all_completed, remaining_todos
-        )
-
-        try:
-            response = self.llm.call(
-                messages,
-                response_model=StepObservation,
-                from_task=self.task,
-                from_agent=self.agent,
-            )
-
-            if isinstance(response, StepObservation):
-                observation = response
-            else:
-                observation = StepObservation(
-                    step_completed_successfully=True,
-                    key_information_learned=str(response) if response else "",
-                    remaining_plan_still_valid=True,
-                )
-
-            refinement_summaries = (
-                [
-                    f"Step {r.step_number}: {r.new_description}"
-                    for r in observation.suggested_refinements
-                ]
-                if observation.suggested_refinements
-                else None
-            )
-
-            crewai_event_bus.emit(
-                self.agent,
-                event=StepObservationCompletedEvent(
-                    agent_role=agent_role,
-                    step_number=completed_step.step_number,
-                    step_description=completed_step.description,
-                    step_completed_successfully=observation.step_completed_successfully,
-                    key_information_learned=observation.key_information_learned,
-                    remaining_plan_still_valid=observation.remaining_plan_still_valid,
-                    needs_full_replan=observation.needs_full_replan,
-                    replan_reason=observation.replan_reason,
-                    goal_already_achieved=observation.goal_already_achieved,
-                    suggested_refinements=refinement_summaries,
-                    from_task=self.task,
-                    from_agent=self.agent,
-                ),
-            )
-
-            return observation
-
-        except Exception as e:
-            logger.warning(
-                f"Observation LLM call failed: {e}. Defaulting to conservative replan."
-            )
-
-            crewai_event_bus.emit(
-                self.agent,
-                event=StepObservationFailedEvent(
-                    agent_role=agent_role,
-                    step_number=completed_step.step_number,
-                    step_description=completed_step.description,
-                    error=str(e),
-                    from_task=self.task,
-                    from_agent=self.agent,
-                ),
-            )
-
-            # Don't force a full replan — the step may have succeeded even if the
-            # observer LLM failed to parse the result. Defaulting to "continue" is
-            # far less disruptive than wiping the entire plan on every observer error.
-            return StepObservation(
-                step_completed_successfully=True,
-                key_information_learned="",
-                remaining_plan_still_valid=True,
-                needs_full_replan=False,
-            )
-
-    def _extract_task_section(self, text: str) -> str:
-        """Extract the ## Task body from a structured enriched instruction.
-
-        Falls back to the full text (capped at 2000 chars) for plain inputs.
-        """
-        for marker in ("\n## Task\n", "\n## Task:", "## Task\n"):
-            idx = text.find(marker)
-            if idx >= 0:
-                start = idx + len(marker)
-                for end_marker in ("\n---\n", "\n## "):
-                    end = text.find(end_marker, start)
-                    if end > 0:
-                        return text[start:end].strip()
-                return text[start : start + 2000].strip()
-        return text[:2000] if len(text) > 2000 else text
-
-    def apply_refinements(
-        self,
-        observation: StepObservation,
-        remaining_todos: list[TodoItem],
-    ) -> list[TodoItem]:
-        """Apply structured refinements from the observation directly to todo descriptions.
-
-        No LLM call needed — refinements are already structured StepRefinement
-        objects produced by the observation call. This is a pure in-memory update.
-
-        Args:
-            observation: The observation containing structured refinements.
-            remaining_todos: The pending todos to update in-place.
-
-        Returns:
-            The same todo list with updated descriptions where refinements applied.
-        """
-        if not observation.suggested_refinements:
-            return remaining_todos
-
-        todo_by_step: dict[int, TodoItem] = {t.step_number: t for t in remaining_todos}
-        for refinement in observation.suggested_refinements:
-            if refinement.step_number in todo_by_step and refinement.new_description:
-                todo_by_step[refinement.step_number].description = refinement.new_description
-
-        return remaining_todos
-
-    # ------------------------------------------------------------------
-    # Internal: Message building
-    # ------------------------------------------------------------------
-
-    def _build_observation_messages(
-        self,
-        completed_step: TodoItem,
-        result: str,
-        all_completed: list[TodoItem],
-        remaining_todos: list[TodoItem],
-    ) -> list[LLMMessage]:
-        """Build messages for the observation LLM call."""
-        task_desc = ""
-        task_goal = ""
-        if self.task:
-            task_desc = self.task.description or ""
-            task_goal = self.task.expected_output or ""
-        elif self.kickoff_input:
-            # Standalone kickoff path — no Task object, but we have the raw input.
-            # Extract just the ## Task section so the observer sees the actual goal,
-            # not the full enriched instruction with env/tools/verification noise.
-            task_desc = self._extract_task_section(self.kickoff_input)
-            task_goal = "Complete the task successfully"
-
-        system_prompt = self._i18n.retrieve("planning", "observation_system_prompt")
-
-        # Build context of what's been done
-        completed_summary = ""
-        if all_completed:
-            completed_lines = []
-            for todo in all_completed:
-                result_preview = (todo.result or "")[:200]
-                completed_lines.append(
-                    f"  Step {todo.step_number}: {todo.description}\n"
-                    f"    Result: {result_preview}"
-                )
-            completed_summary = "\n## Previously completed steps:\n" + "\n".join(
-                completed_lines
-            )
-
-        # Build remaining plan
-        remaining_summary = ""
-        if remaining_todos:
-            remaining_lines = [
-                f"  Step {todo.step_number}: {todo.description}"
-                for todo in remaining_todos
-            ]
-            remaining_summary = "\n## Remaining plan steps:\n" + "\n".join(
-                remaining_lines
-            )
-
-        user_prompt = self._i18n.retrieve("planning", "observation_user_prompt").format(
-            task_description=task_desc,
-            task_goal=task_goal,
-            completed_summary=completed_summary,
-            step_number=completed_step.step_number,
-            step_description=completed_step.description,
-            step_result=result,
-            remaining_summary=remaining_summary,
-        )
-
-        return [
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": user_prompt},
-        ]

lib/crewai/src/crewai/agents/step_executor.py

@@ -1,608 +0,0 @@
-"""StepExecutor: Isolated executor for a single plan step.
-
-Implements the direct-action execution pattern from Plan-and-Act
-(arxiv 2503.09572): the Executor receives one step description,
-makes a single LLM call, executes any tool call returned, and
-returns the result immediately.
-
-There is no inner loop. Recovery from failure (retry, replan) is
-the responsibility of PlannerObserver and AgentExecutor — keeping
-this class single-purpose and fast.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from datetime import datetime
-import json
-import time
-from typing import TYPE_CHECKING, Any
-
-from pydantic import BaseModel
-
-from crewai.agents.parser import AgentAction, AgentFinish
-from crewai.events.event_bus import crewai_event_bus
-from crewai.events.types.tool_usage_events import (
-    ToolUsageErrorEvent,
-    ToolUsageFinishedEvent,
-    ToolUsageStartedEvent,
-)
-from crewai.utilities.agent_utils import (
-    build_tool_calls_assistant_message,
-    check_native_tool_support,
-    enforce_rpm_limit,
-    execute_single_native_tool_call,
-    format_message_for_llm,
-    is_tool_call_list,
-    process_llm_response,
-    setup_native_tools,
-)
-from crewai.utilities.i18n import I18N, get_i18n
-from crewai.utilities.planning_types import TodoItem
-from crewai.utilities.printer import Printer
-from crewai.utilities.step_execution_context import StepExecutionContext, StepResult
-from crewai.utilities.string_utils import sanitize_tool_name
-from crewai.utilities.tool_utils import execute_tool_and_check_finality
-from crewai.utilities.types import LLMMessage
-
-
-if TYPE_CHECKING:
-    from crewai.agent import Agent
-    from crewai.agents.tools_handler import ToolsHandler
-    from crewai.crew import Crew
-    from crewai.llms.base_llm import BaseLLM
-    from crewai.task import Task
-    from crewai.tools.base_tool import BaseTool
-    from crewai.tools.structured_tool import CrewStructuredTool
-
-
-class StepExecutor:
-    """Executes a SINGLE todo item using direct-action execution.
-
-    The StepExecutor owns its own message list per invocation. It never reads
-    or writes the AgentExecutor's state. Results flow back via StepResult.
-
-    Execution pattern (per Plan-and-Act, arxiv 2503.09572):
-        1. Build messages from todo + context
-        2. Call LLM once (with or without native tools)
-        3. If tool call → execute it → return tool result
-        4. If text answer → return it directly
-        No inner loop — recovery is PlannerObserver's responsibility.
-
-    Args:
-        llm: The language model to use for execution.
-        tools: Structured tools available to the executor.
-        agent: The agent instance (for role/goal/verbose/config).
-        original_tools: Original BaseTool instances (needed for native tool schema).
-        tools_handler: Optional tools handler for caching and delegation tracking.
-        task: Optional task context.
-        crew: Optional crew context.
-        function_calling_llm: Optional separate LLM for function calling.
-        request_within_rpm_limit: Optional RPM limit function.
-        callbacks: Optional list of callbacks.
-        i18n: Optional i18n instance.
-    """
-
-    def __init__(
-        self,
-        llm: BaseLLM,
-        tools: list[CrewStructuredTool],
-        agent: Agent,
-        original_tools: list[BaseTool] | None = None,
-        tools_handler: ToolsHandler | None = None,
-        task: Task | None = None,
-        crew: Crew | None = None,
-        function_calling_llm: BaseLLM | Any | None = None,
-        request_within_rpm_limit: Callable[[], bool] | None = None,
-        callbacks: list[Any] | None = None,
-        i18n: I18N | None = None,
-    ) -> None:
-        self.llm = llm
-        self.tools = tools
-        self.agent = agent
-        self.original_tools = original_tools or []
-        self.tools_handler = tools_handler
-        self.task = task
-        self.crew = crew
-        self.function_calling_llm = function_calling_llm
-        self.request_within_rpm_limit = request_within_rpm_limit
-        self.callbacks = callbacks or []
-        self._i18n: I18N = i18n or get_i18n()
-        self._printer: Printer = Printer()
-
-        # Native tool support — set up once
-        self._use_native_tools = check_native_tool_support(self.llm, self.original_tools)
-        self._openai_tools: list[dict[str, Any]] = []
-        self._available_functions: dict[str, Callable[..., Any]] = {}
-        if self._use_native_tools and self.original_tools:
-            self._openai_tools, self._available_functions = setup_native_tools(
-                self.original_tools
-            )
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def execute(self, todo: TodoItem, context: StepExecutionContext) -> StepResult:
-        """Execute a single todo item using a multi-turn action loop.
-
-        Enforces the RPM limit, builds a fresh message list, then iterates
-        LLM call → tool execution → observation until the LLM signals it is
-        done (text answer) or max_step_iterations is reached.  Never touches
-        external AgentExecutor state.
-
-        Args:
-            todo: The todo item to execute.
-            context: Immutable context with task info and dependency results.
-
-        Returns:
-            StepResult with the outcome.
-        """
-        start_time = time.monotonic()
-        tool_calls_made: list[str] = []
-
-        try:
-            enforce_rpm_limit(self.request_within_rpm_limit)
-            messages = self._build_isolated_messages(todo, context)
-
-            if self._use_native_tools:
-                result_text = self._execute_native(messages, tool_calls_made)
-            else:
-                result_text = self._execute_text_parsed(messages, tool_calls_made)
-            self._validate_expected_tool_usage(todo, tool_calls_made)
-
-            elapsed = time.monotonic() - start_time
-            return StepResult(
-                success=True,
-                result=result_text,
-                tool_calls_made=tool_calls_made,
-                execution_time=elapsed,
-            )
-        except Exception as e:
-            elapsed = time.monotonic() - start_time
-            return StepResult(
-                success=False,
-                result="",
-                error=str(e),
-                tool_calls_made=tool_calls_made,
-                execution_time=elapsed,
-            )
-
-    # ------------------------------------------------------------------
-    # Internal: Message building
-    # ------------------------------------------------------------------
-
-    def _build_isolated_messages(
-        self, todo: TodoItem, context: StepExecutionContext
-    ) -> list[LLMMessage]:
-        """Build a fresh message list for this step's execution.
-
-        System prompt tells the LLM it is an Executor focused on one step.
-        User prompt provides the step description, dependencies, and tools.
-        """
-        system_prompt = self._build_system_prompt()
-        user_prompt = self._build_user_prompt(todo, context)
-
-        return [
-            format_message_for_llm(system_prompt, role="system"),
-            format_message_for_llm(user_prompt, role="user"),
-        ]
-
-    def _build_system_prompt(self) -> str:
-        """Build the Executor's system prompt."""
-        role = self.agent.role if self.agent else "Assistant"
-        goal = self.agent.goal if self.agent else "Complete tasks efficiently"
-        backstory = getattr(self.agent, "backstory", "") or ""
-
-        tools_section = ""
-        if self.tools and not self._use_native_tools:
-            tool_names = ", ".join(sanitize_tool_name(t.name) for t in self.tools)
-            tools_section = self._i18n.retrieve(
-                "planning", "step_executor_tools_section"
-            ).format(tool_names=tool_names)
-
-        return self._i18n.retrieve("planning", "step_executor_system_prompt").format(
-            role=role,
-            backstory=backstory,
-            goal=goal,
-            tools_section=tools_section,
-        )
-
-    def _extract_task_section(self, task_description: str) -> str:
-        """Extract the most relevant portion of the task description.
-
-        For structured descriptions (e.g. harbor_agent-style with ## Task
-        and ## Instructions sections), extracts just the task body so the
-        executor sees the requirements without duplicating tool/verification
-        instructions that are already in the system prompt.
-
-        For plain descriptions, returns the full text (up to 2000 chars).
-        """
-        # Try to extract between "## Task" and the next "---" separator
-        # or next "##" heading — this isolates the task spec from env/tool noise.
-        for marker in ("\n## Task\n", "\n## Task:", "## Task\n"):
-            idx = task_description.find(marker)
-            if idx >= 0:
-                start = idx + len(marker)
-                # End at the first horizontal rule or next top-level ## section
-                for end_marker in ("\n---\n", "\n## "):
-                    end = task_description.find(end_marker, start)
-                    if end > 0:
-                        return task_description[start:end].strip()
-                # No end marker — take up to 2000 chars
-                return task_description[start : start + 2000].strip()
-
-        # No structured format — use the full description, reasonably truncated
-        if len(task_description) > 2000:
-            return task_description[:2000] + "\n... [truncated]"
-        return task_description
-
-    def _build_user_prompt(self, todo: TodoItem, context: StepExecutionContext) -> str:
-        """Build the user prompt for this specific step."""
-        parts: list[str] = []
-
-        # Include overall task context so the executor knows the full goal and
-        # required output format/location — critical for knowing WHAT to produce.
-        # We extract only the task body (not tool instructions or verification
-        # sections) to avoid duplicating directives already in the system prompt.
-        if context.task_description:
-            task_section = self._extract_task_section(context.task_description)
-            if task_section:
-                parts.append(
-                    self._i18n.retrieve("planning", "step_executor_task_context").format(
-                        task_context=task_section,
-                    )
-                )
-
-        parts.append(
-            self._i18n.retrieve("planning", "step_executor_user_prompt").format(
-                step_description=todo.description,
-            )
-        )
-
-        if todo.tool_to_use:
-            parts.append(
-                self._i18n.retrieve("planning", "step_executor_suggested_tool").format(
-                    tool_to_use=todo.tool_to_use,
-                )
-            )
-
-        # Include dependency results (final results only, no traces)
-        if context.dependency_results:
-            parts.append(
-                self._i18n.retrieve("planning", "step_executor_context_header")
-            )
-            for step_num, result in sorted(context.dependency_results.items()):
-                parts.append(
-                    self._i18n.retrieve(
-                        "planning", "step_executor_context_entry"
-                    ).format(step_number=step_num, result=result)
-                )
-
-        parts.append(self._i18n.retrieve("planning", "step_executor_complete_step"))
-
-        return "\n".join(parts)
-
-    # ------------------------------------------------------------------
-    # Internal: Multi-turn execution loop
-    # ------------------------------------------------------------------
-
-    def _execute_text_parsed(
-        self,
-        messages: list[LLMMessage],
-        tool_calls_made: list[str],
-        max_step_iterations: int = 15,
-    ) -> str:
-        """Execute step using text-parsed tool calling with a multi-turn loop.
-
-        Iterates LLM call → tool execution → observation until the LLM
-        produces a Final Answer or max_step_iterations is reached.
-        This allows the agent to: run a command, see the output, adjust its
-        approach, and run another command — all within a single plan step.
-        """
-        use_stop_words = self.llm.supports_stop_words() if self.llm else False
-        last_tool_result = ""
-
-        for _ in range(max_step_iterations):
-            answer = self.llm.call(
-                messages,
-                callbacks=self.callbacks,
-                from_task=self.task,
-                from_agent=self.agent,
-            )
-
-            if not answer:
-                raise ValueError("Empty response from LLM")
-
-            answer_str = str(answer)
-            formatted = process_llm_response(answer_str, use_stop_words)
-
-            if isinstance(formatted, AgentFinish):
-                return str(formatted.output)
-
-            if isinstance(formatted, AgentAction):
-                tool_calls_made.append(formatted.tool)
-                tool_result = self._execute_text_tool_with_events(formatted)
-                last_tool_result = tool_result
-                # Append the assistant's reasoning + action, then the observation.
-                # _build_observation_message handles vision sentinels so the LLM
-                # receives an image content block instead of raw base64 text.
-                messages.append({"role": "assistant", "content": answer_str})
-                messages.append(self._build_observation_message(tool_result))
-                continue
-
-            # Raw text response with no Final Answer marker — treat as done
-            return answer_str
-
-        # Max iterations reached — return the last tool result we accumulated
-        return last_tool_result
-
-    def _execute_text_tool_with_events(self, formatted: AgentAction) -> str:
-        """Execute text-parsed tool calls with tool usage events."""
-        args_dict = self._parse_tool_args(formatted.tool_input)
-        agent_key = getattr(self.agent, "key", "unknown") if self.agent else "unknown"
-        started_at = datetime.now()
-        crewai_event_bus.emit(
-            self,
-            event=ToolUsageStartedEvent(
-                tool_name=formatted.tool,
-                tool_args=args_dict,
-                from_agent=self.agent,
-                from_task=self.task,
-                agent_key=agent_key,
-            ),
-        )
-
-        try:
-            fingerprint_context = {}
-            if (
-                self.agent
-                and hasattr(self.agent, "security_config")
-                and hasattr(self.agent.security_config, "fingerprint")
-            ):
-                fingerprint_context = {
-                    "agent_fingerprint": str(self.agent.security_config.fingerprint)
-                }
-
-            tool_result = execute_tool_and_check_finality(
-                agent_action=formatted,
-                fingerprint_context=fingerprint_context,
-                tools=self.tools,
-                i18n=self._i18n,
-                agent_key=self.agent.key if self.agent else None,
-                agent_role=self.agent.role if self.agent else None,
-                tools_handler=self.tools_handler,
-                task=self.task,
-                agent=self.agent,
-                function_calling_llm=self.function_calling_llm,
-                crew=self.crew,
-            )
-        except Exception as e:
-            crewai_event_bus.emit(
-                self,
-                event=ToolUsageErrorEvent(
-                    tool_name=formatted.tool,
-                    tool_args=args_dict,
-                    from_agent=self.agent,
-                    from_task=self.task,
-                    agent_key=agent_key,
-                    error=e,
-                ),
-            )
-            raise
-
-        crewai_event_bus.emit(
-            self,
-            event=ToolUsageFinishedEvent(
-                output=str(tool_result.result),
-                tool_name=formatted.tool,
-                tool_args=args_dict,
-                from_agent=self.agent,
-                from_task=self.task,
-                agent_key=agent_key,
-                started_at=started_at,
-                finished_at=datetime.now(),
-            ),
-        )
-        return str(tool_result.result)
-
-    def _parse_tool_args(self, tool_input: Any) -> dict[str, Any]:
-        """Parse tool args from the parser output into a dict payload for events."""
-        if isinstance(tool_input, dict):
-            return tool_input
-        if isinstance(tool_input, str):
-            stripped_input = tool_input.strip()
-            if not stripped_input:
-                return {}
-            try:
-                parsed = json.loads(stripped_input)
-                if isinstance(parsed, dict):
-                    return parsed
-                return {"input": parsed}
-            except json.JSONDecodeError:
-                return {"input": stripped_input}
-        return {"input": str(tool_input)}
-
-    # ------------------------------------------------------------------
-    # Internal: Vision support
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _parse_vision_sentinel(raw: str) -> tuple[str, str] | None:
-        """Parse a VISION_IMAGE sentinel into (media_type, base64_data), or None."""
-        _PREFIX = "VISION_IMAGE:"
-        if not raw.startswith(_PREFIX):
-            return None
-        rest = raw[len(_PREFIX):]
-        sep = rest.find(":")
-        if sep <= 0:
-            return None
-        return rest[:sep], rest[sep + 1:]
-
-    @staticmethod
-    def _build_observation_message(tool_result: str) -> LLMMessage:
-        """Build an observation message, converting vision sentinels to image blocks.
-
-        When a tool returns a VISION_IMAGE sentinel (e.g. from read_image),
-        we build a multimodal content block so the LLM can actually *see*
-        the image rather than receiving a wall of base64 text.
-
-        Uses the standard image_url / data-URI format so each LLM provider's
-        SDK (OpenAI, LiteLLM, etc.) handles the provider-specific conversion.
-
-        Format: ``VISION_IMAGE:<media_type>:<base64_data>``
-        """
-        parsed = StepExecutor._parse_vision_sentinel(tool_result)
-        if parsed:
-            media_type, b64_data = parsed
-            return {
-                "role": "user",
-                "content": [
-                    {"type": "text", "text": "Observation: Here is the image:"},
-                    {
-                        "type": "image_url",
-                        "image_url": {
-                            "url": f"data:{media_type};base64,{b64_data}",
-                        },
-                    },
-                ],
-            }
-        return {"role": "user", "content": f"Observation: {tool_result}"}
-
-    def _validate_expected_tool_usage(
-        self,
-        todo: TodoItem,
-        tool_calls_made: list[str],
-    ) -> None:
-        """Fail step execution when a required tool is configured but not called."""
-        expected_tool = getattr(todo, "tool_to_use", None)
-        if not expected_tool:
-            return
-        expected_tool_name = sanitize_tool_name(expected_tool)
-        available_tool_names = {
-            sanitize_tool_name(tool.name)
-            for tool in self.tools
-            if getattr(tool, "name", "")
-        } | set(self._available_functions.keys())
-        if expected_tool_name not in available_tool_names:
-            return
-        called_names = {sanitize_tool_name(name) for name in tool_calls_made}
-        if expected_tool_name not in called_names:
-            raise ValueError(
-                f"Expected tool '{expected_tool_name}' was not called "
-                f"for step {todo.step_number}."
-            )
-
-    def _execute_native(
-        self,
-        messages: list[LLMMessage],
-        tool_calls_made: list[str],
-        max_step_iterations: int = 15,
-    ) -> str:
-        """Execute step using native function calling with a multi-turn loop.
-
-        Iterates LLM call → tool execution → appended results until the LLM
-        returns a text answer (no more tool calls) or max_step_iterations is
-        reached.  This lets the agent run a shell command, observe the output,
-        correct mistakes, and issue follow-up commands — all within one step.
-        """
-        accumulated_results: list[str] = []
-
-        for _ in range(max_step_iterations):
-            answer = self.llm.call(
-                messages,
-                tools=self._openai_tools,
-                callbacks=self.callbacks,
-                from_task=self.task,
-                from_agent=self.agent,
-            )
-
-            if not answer:
-                raise ValueError("Empty response from LLM")
-
-            if isinstance(answer, BaseModel):
-                return answer.model_dump_json()
-
-            if isinstance(answer, list) and answer and is_tool_call_list(answer):
-                # _execute_native_tool_calls appends assistant + tool messages
-                # to `messages` as a side-effect, so the next LLM call will
-                # see the full conversation history including tool outputs.
-                result = self._execute_native_tool_calls(
-                    answer, messages, tool_calls_made
-                )
-                accumulated_results.append(result)
-                continue
-
-            # Text answer → LLM decided the step is done
-            return str(answer)
-
-        # Max iterations reached — return everything we accumulated
-        return "\n".join(filter(None, accumulated_results))
-
-    def _execute_native_tool_calls(
-        self,
-        tool_calls: list[Any],
-        messages: list[LLMMessage],
-        tool_calls_made: list[str],
-    ) -> str:
-        """Execute a batch of native tool calls and return their results.
-
-        Returns the result of the first tool marked result_as_answer if any,
-        otherwise returns all tool results concatenated.
-        """
-        assistant_message, _reports = build_tool_calls_assistant_message(tool_calls)
-        if assistant_message:
-            messages.append(assistant_message)
-
-        tool_results: list[str] = []
-        for tool_call in tool_calls:
-            call_result = execute_single_native_tool_call(
-                tool_call,
-                available_functions=self._available_functions,
-                original_tools=self.original_tools,
-                structured_tools=self.tools,
-                tools_handler=self.tools_handler,
-                agent=self.agent,
-                task=self.task,
-                crew=self.crew,
-                event_source=self,
-                printer=self._printer,
-                verbose=bool(self.agent and self.agent.verbose),
-            )
-
-            if call_result.func_name:
-                tool_calls_made.append(call_result.func_name)
-
-            if call_result.result_as_answer:
-                return str(call_result.result)
-
-            if call_result.tool_message:
-                raw_content = call_result.tool_message.get("content", "")
-                if isinstance(raw_content, str):
-                    parsed = self._parse_vision_sentinel(raw_content)
-                    if parsed:
-                        media_type, b64_data = parsed
-                        # Replace the sentinel with a standard image_url content block.
-                        # Each provider SDK (LiteLLM → Anthropic, OpenAI native, etc.)
-                        # converts the data-URI to its own wire format.
-                        modified = dict(call_result.tool_message)
-                        modified["content"] = [
-                            {
-                                "type": "image_url",
-                                "image_url": {
-                                    "url": f"data:{media_type};base64,{b64_data}",
-                                },
-                            }
-                        ]
-                        messages.append(modified)
-                        tool_results.append("[image]")
-                    else:
-                        messages.append(call_result.tool_message)
-                        if raw_content:
-                            tool_results.append(raw_content)
-                else:
-                    messages.append(call_result.tool_message)
-                    if raw_content:
-                        tool_results.append(str(raw_content))
-
-        return "\n".join(tool_results) if tool_results else ""

lib/crewai/src/crewai/cli/constants.py

@@ -69,7 +69,7 @@ ENV_VARS: dict[str, list[dict[str, Any]]] = {
         },
         {
             "prompt": "Enter your AWS Region Name (press Enter to skip)",
-            "key_name": "AWS_REGION_NAME",
+            "key_name": "AWS_DEFAULT_REGION",
         },
     ],
     "azure": [

lib/crewai/src/crewai/cli/memory_tui.py

@@ -290,13 +290,20 @@ class MemoryTUI(App[None]):
         if self._memory is None:
             panel.update(self._init_error or "No memory loaded.")
             return
+        display_limit = 1000
         info = self._memory.info(path)
         self._last_scope_info = info
-        self._entries = self._memory.list_records(scope=path, limit=200)
+        self._entries = self._memory.list_records(scope=path, limit=display_limit)
         panel.update(_format_scope_info(info))
         panel.border_title = "Detail"
         entry_list = self.query_one("#entry-list", OptionList)
-        entry_list.border_title = f"Entries ({len(self._entries)})"
+        capped = info.record_count > display_limit
+        count_label = (
+            f"Entries (showing {display_limit} of {info.record_count} — display limit)"
+            if capped
+            else f"Entries ({len(self._entries)})"
+        )
+        entry_list.border_title = count_label
         self._populate_entry_list()
 
     def on_option_list_option_highlighted(
@@ -376,6 +383,11 @@ class MemoryTUI(App[None]):
                 return
 
             info_lines: list[str] = []
+            info_lines.append(
+                "[dim italic]Searched the full dataset"
+                + (f" within [bold]{scope}[/]" if scope else "")
+                + " using the recall flow (semantic + recency + importance).[/]\n"
+            )
             if not self._custom_embedder:
                 info_lines.append(
                     "[dim italic]Note: Using default OpenAI embedder. "

lib/crewai/src/crewai/cli/plus_api.py

@@ -190,6 +190,15 @@ class PlusAPI:
             timeout=30,
         )
 
+    def get_mcp_configs(self, slugs: list[str]) -> httpx.Response:
+        """Get MCP server configurations for the given slugs."""
+        return self._make_request(
+            "GET",
+            f"{self.INTEGRATIONS_RESOURCE}/mcp_configs",
+            params={"slugs": ",".join(slugs)},
+            timeout=30,
+        )
+
     def get_triggers(self) -> httpx.Response:
         """Get all available triggers from integrations."""
         return self._make_request("GET", f"{self.INTEGRATIONS_RESOURCE}/apps")

lib/crewai/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]==1.9.3"
+    "crewai[tools]==1.10.1a1"
 ]
 
 [project.scripts]

lib/crewai/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]==1.9.3"
+    "crewai[tools]==1.10.1a1"
 ]
 
 [project.scripts]

lib/crewai/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.203.1"
+    "crewai[tools]==1.10.1a1"
 ]
 
 [tool.crewai]

lib/crewai/src/crewai/events/__init__.py

@@ -63,6 +63,7 @@ from crewai.events.types.logging_events import (
     AgentLogsStartedEvent,
 )
 from crewai.events.types.mcp_events import (
+    MCPConfigFetchFailedEvent,
     MCPConnectionCompletedEvent,
     MCPConnectionFailedEvent,
     MCPConnectionStartedEvent,
@@ -165,6 +166,7 @@ __all__ = [
     "LiteAgentExecutionCompletedEvent",
     "LiteAgentExecutionErrorEvent",
     "LiteAgentExecutionStartedEvent",
+    "MCPConfigFetchFailedEvent",
     "MCPConnectionCompletedEvent",
     "MCPConnectionFailedEvent",
     "MCPConnectionStartedEvent",

lib/crewai/src/crewai/events/event_listener.py

@@ -68,20 +68,13 @@ from crewai.events.types.logging_events import (
     AgentLogsStartedEvent,
 )
 from crewai.events.types.mcp_events import (
+    MCPConfigFetchFailedEvent,
     MCPConnectionCompletedEvent,
     MCPConnectionFailedEvent,
     MCPConnectionStartedEvent,
     MCPToolExecutionFailedEvent,
     MCPToolExecutionStartedEvent,
 )
-from crewai.events.types.observation_events import (
-    GoalAchievedEarlyEvent,
-    PlanRefinementEvent,
-    PlanReplanTriggeredEvent,
-    StepObservationCompletedEvent,
-    StepObservationFailedEvent,
-    StepObservationStartedEvent,
-)
 from crewai.events.types.reasoning_events import (
     AgentReasoningCompletedEvent,
     AgentReasoningFailedEvent,
@@ -542,64 +535,6 @@ class EventListener(BaseEventListener):
                 event.error,
             )
 
-        # ----------- OBSERVATION EVENTS (Plan-and-Execute) -----------
-
-        @crewai_event_bus.on(StepObservationStartedEvent)
-        def on_step_observation_started(
-            _: Any, event: StepObservationStartedEvent
-        ) -> None:
-            self.formatter.handle_observation_started(
-                event.agent_role,
-                event.step_number,
-                event.step_description,
-            )
-
-        @crewai_event_bus.on(StepObservationCompletedEvent)
-        def on_step_observation_completed(
-            _: Any, event: StepObservationCompletedEvent
-        ) -> None:
-            self.formatter.handle_observation_completed(
-                event.agent_role,
-                event.step_number,
-                event.step_completed_successfully,
-                event.remaining_plan_still_valid,
-                event.key_information_learned,
-                event.needs_full_replan,
-                event.goal_already_achieved,
-            )
-
-        @crewai_event_bus.on(StepObservationFailedEvent)
-        def on_step_observation_failed(
-            _: Any, event: StepObservationFailedEvent
-        ) -> None:
-            self.formatter.handle_observation_failed(
-                event.step_number,
-                event.error,
-            )
-
-        @crewai_event_bus.on(PlanRefinementEvent)
-        def on_plan_refinement(_: Any, event: PlanRefinementEvent) -> None:
-            self.formatter.handle_plan_refinement(
-                event.step_number,
-                event.refined_step_count,
-                event.refinements,
-            )
-
-        @crewai_event_bus.on(PlanReplanTriggeredEvent)
-        def on_plan_replan_triggered(_: Any, event: PlanReplanTriggeredEvent) -> None:
-            self.formatter.handle_plan_replan(
-                event.replan_reason,
-                event.replan_count,
-                event.completed_steps_preserved,
-            )
-
-        @crewai_event_bus.on(GoalAchievedEarlyEvent)
-        def on_goal_achieved_early(_: Any, event: GoalAchievedEarlyEvent) -> None:
-            self.formatter.handle_goal_achieved_early(
-                event.steps_completed,
-                event.steps_remaining,
-            )
-
         # ----------- AGENT LOGGING EVENTS -----------
 
         @crewai_event_bus.on(AgentLogsStartedEvent)
@@ -731,6 +666,16 @@ class EventListener(BaseEventListener):
                 event.error_type,
             )
 
+        @crewai_event_bus.on(MCPConfigFetchFailedEvent)
+        def on_mcp_config_fetch_failed(
+            _: Any, event: MCPConfigFetchFailedEvent
+        ) -> None:
+            self.formatter.handle_mcp_config_fetch_failed(
+                event.slug,
+                event.error,
+                event.error_type,
+            )
+
         @crewai_event_bus.on(MCPToolExecutionStartedEvent)
         def on_mcp_tool_execution_started(
             _: Any, event: MCPToolExecutionStartedEvent

lib/crewai/src/crewai/events/event_types.py

@@ -67,6 +67,7 @@ from crewai.events.types.llm_guardrail_events import (
     LLMGuardrailStartedEvent,
 )
 from crewai.events.types.mcp_events import (
+    MCPConfigFetchFailedEvent,
     MCPConnectionCompletedEvent,
     MCPConnectionFailedEvent,
     MCPConnectionStartedEvent,
@@ -181,4 +182,5 @@ EventTypes = (
     | MCPToolExecutionStartedEvent
     | MCPToolExecutionCompletedEvent
     | MCPToolExecutionFailedEvent
+    | MCPConfigFetchFailedEvent
 )

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

@@ -93,14 +93,6 @@ from crewai.events.types.memory_events import (
     MemorySaveFailedEvent,
     MemorySaveStartedEvent,
 )
-from crewai.events.types.observation_events import (
-    GoalAchievedEarlyEvent,
-    PlanRefinementEvent,
-    PlanReplanTriggeredEvent,
-    StepObservationCompletedEvent,
-    StepObservationFailedEvent,
-    StepObservationStartedEvent,
-)
 from crewai.events.types.reasoning_events import (
     AgentReasoningCompletedEvent,
     AgentReasoningFailedEvent,
@@ -445,39 +437,6 @@ class TraceCollectionListener(BaseEventListener):
         ) -> None:
             self._handle_action_event("agent_reasoning_failed", source, event)
 
-        # Observation events (Plan-and-Execute)
-        @event_bus.on(StepObservationStartedEvent)
-        def on_step_observation_started(
-            source: Any, event: StepObservationStartedEvent
-        ) -> None:
-            self._handle_action_event("step_observation_started", source, event)
-
-        @event_bus.on(StepObservationCompletedEvent)
-        def on_step_observation_completed(
-            source: Any, event: StepObservationCompletedEvent
-        ) -> None:
-            self._handle_action_event("step_observation_completed", source, event)
-
-        @event_bus.on(StepObservationFailedEvent)
-        def on_step_observation_failed(
-            source: Any, event: StepObservationFailedEvent
-        ) -> None:
-            self._handle_action_event("step_observation_failed", source, event)
-
-        @event_bus.on(PlanRefinementEvent)
-        def on_plan_refinement(source: Any, event: PlanRefinementEvent) -> None:
-            self._handle_action_event("plan_refinement", source, event)
-
-        @event_bus.on(PlanReplanTriggeredEvent)
-        def on_plan_replan_triggered(
-            source: Any, event: PlanReplanTriggeredEvent
-        ) -> None:
-            self._handle_action_event("plan_replan_triggered", source, event)
-
-        @event_bus.on(GoalAchievedEarlyEvent)
-        def on_goal_achieved_early(source: Any, event: GoalAchievedEarlyEvent) -> None:
-            self._handle_action_event("goal_achieved_early", source, event)
-
         @event_bus.on(KnowledgeRetrievalStartedEvent)
         def on_knowledge_retrieval_started(
             source: Any, event: KnowledgeRetrievalStartedEvent

lib/crewai/src/crewai/events/types/mcp_events.py

@@ -83,3 +83,16 @@ class MCPToolExecutionFailedEvent(MCPEvent):
     error_type: str | None = None  # "timeout", "validation", "server_error", etc.
     started_at: datetime | None = None
     failed_at: datetime | None = None
+
+
+class MCPConfigFetchFailedEvent(BaseEvent):
+    """Event emitted when fetching an AMP MCP server config fails.
+
+    This covers cases where the slug is not connected, the API call
+    failed, or native MCP resolution failed after config was fetched.
+    """
+
+    type: str = "mcp_config_fetch_failed"
+    slug: str
+    error: str
+    error_type: str | None = None  # "not_connected", "api_error", "connection_failed"

lib/crewai/src/crewai/events/types/observation_events.py

@@ -1,99 +0,0 @@
-"""Observation events for the Plan-and-Execute architecture.
-
-Emitted during the Observation phase (PLAN-AND-ACT Section 3.3) when the
-PlannerObserver analyzes step execution results and decides on plan
-continuation, refinement, or replanning.
-"""
-
-from typing import Any
-
-from crewai.events.base_events import BaseEvent
-
-
-class ObservationEvent(BaseEvent):
-    """Base event for observation phase events."""
-
-    type: str
-    agent_role: str
-    step_number: int
-    step_description: str = ""
-    from_task: Any | None = None
-    from_agent: Any | None = None
-
-    def __init__(self, **data: Any) -> None:
-        super().__init__(**data)
-        self._set_task_params(data)
-        self._set_agent_params(data)
-
-
-class StepObservationStartedEvent(ObservationEvent):
-    """Emitted when the Planner begins observing a step's result.
-
-    Fires after every step execution, before the observation LLM call.
-    """
-
-    type: str = "step_observation_started"
-
-
-class StepObservationCompletedEvent(ObservationEvent):
-    """Emitted when the Planner finishes observing a step's result.
-
-    Contains the full observation analysis: what was learned, whether
-    the plan is still valid, and what action to take next.
-    """
-
-    type: str = "step_observation_completed"
-    step_completed_successfully: bool = True
-    key_information_learned: str = ""
-    remaining_plan_still_valid: bool = True
-    needs_full_replan: bool = False
-    replan_reason: str | None = None
-    goal_already_achieved: bool = False
-    suggested_refinements: list[str] | None = None
-
-
-class StepObservationFailedEvent(ObservationEvent):
-    """Emitted when the observation LLM call itself fails.
-
-    The system defaults to continuing the plan when this happens,
-    but the event allows monitoring/alerting on observation failures.
-    """
-
-    type: str = "step_observation_failed"
-    error: str = ""
-
-
-class PlanRefinementEvent(ObservationEvent):
-    """Emitted when the Planner refines upcoming step descriptions.
-
-    This is the lightweight refinement path — no full replan, just
-    sharpening pending todo descriptions based on new information.
-    """
-
-    type: str = "plan_refinement"
-    refined_step_count: int = 0
-    refinements: list[str] | None = None
-
-
-class PlanReplanTriggeredEvent(ObservationEvent):
-    """Emitted when the Planner triggers a full replan.
-
-    The remaining plan was deemed fundamentally wrong and will be
-    regenerated from scratch, preserving completed step results.
-    """
-
-    type: str = "plan_replan_triggered"
-    replan_reason: str = ""
-    replan_count: int = 0
-    completed_steps_preserved: int = 0
-
-
-class GoalAchievedEarlyEvent(ObservationEvent):
-    """Emitted when the Planner detects the goal was achieved early.
-
-    Remaining steps will be skipped and execution will finalize.
-    """
-
-    type: str = "goal_achieved_early"
-    steps_remaining: int = 0
-    steps_completed: int = 0

lib/crewai/src/crewai/events/types/reasoning_events.py

@@ -9,7 +9,7 @@ class ReasoningEvent(BaseEvent):
     type: str
     attempt: int = 1
     agent_role: str
-    task_id: str | None = None
+    task_id: str
     task_name: str | None = None
     from_task: Any | None = None
     agent_id: str | None = None

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

@@ -936,152 +936,6 @@ To enable tracing, do any one of these:
         )
         self.print_panel(error_content, "❌ Reasoning Error", "red")
 
-    # ----------- OBSERVATION EVENTS (Plan-and-Execute) -----------
-
-    def handle_observation_started(
-        self,
-        agent_role: str,
-        step_number: int,
-        step_description: str,
-    ) -> None:
-        """Handle step observation started event."""
-        if not self.verbose:
-            return
-
-        content = Text()
-        content.append("Observation Started\n", style="cyan bold")
-        content.append("Agent: ", style="white")
-        content.append(f"{agent_role}\n", style="cyan")
-        content.append("Step: ", style="white")
-        content.append(f"{step_number}\n", style="cyan")
-        if step_description:
-            desc_preview = step_description[:80] + (
-                "..." if len(step_description) > 80 else ""
-            )
-            content.append("Description: ", style="white")
-            content.append(f"{desc_preview}\n", style="cyan")
-
-        self.print_panel(content, "🔍 Observing Step Result", "cyan")
-
-    def handle_observation_completed(
-        self,
-        agent_role: str,
-        step_number: int,
-        step_completed: bool,
-        plan_valid: bool,
-        key_info: str,
-        needs_replan: bool,
-        goal_achieved: bool,
-    ) -> None:
-        """Handle step observation completed event."""
-        if not self.verbose:
-            return
-
-        if goal_achieved:
-            style = "green"
-            status = "Goal Achieved Early"
-        elif needs_replan:
-            style = "yellow"
-            status = "Replan Needed"
-        elif plan_valid:
-            style = "green"
-            status = "Plan Valid — Continue"
-        else:
-            style = "red"
-            status = "Step Failed"
-
-        content = Text()
-        content.append("Observation Complete\n", style=f"{style} bold")
-        content.append("Step: ", style="white")
-        content.append(f"{step_number}\n", style=style)
-        content.append("Status: ", style="white")
-        content.append(f"{status}\n", style=style)
-        if key_info:
-            info_preview = key_info[:120] + ("..." if len(key_info) > 120 else "")
-            content.append("Learned: ", style="white")
-            content.append(f"{info_preview}\n", style=style)
-
-        self.print_panel(content, "🔍 Observation Result", style)
-
-    def handle_observation_failed(
-        self,
-        step_number: int,
-        error: str,
-    ) -> None:
-        """Handle step observation failure event."""
-        if not self.verbose:
-            return
-
-        error_content = self.create_status_content(
-            "Observation Failed",
-            "Error",
-            "red",
-            Step=str(step_number),
-            Error=error,
-        )
-        self.print_panel(error_content, "❌ Observation Error", "red")
-
-    def handle_plan_refinement(
-        self,
-        step_number: int,
-        refined_count: int,
-        refinements: list[str] | None,
-    ) -> None:
-        """Handle plan refinement event."""
-        if not self.verbose:
-            return
-
-        content = Text()
-        content.append("Plan Refined\n", style="cyan bold")
-        content.append("After Step: ", style="white")
-        content.append(f"{step_number}\n", style="cyan")
-        content.append("Steps Updated: ", style="white")
-        content.append(f"{refined_count}\n", style="cyan")
-        if refinements:
-            for r in refinements[:3]:
-                content.append(f"  • {r[:80]}\n", style="white")
-
-        self.print_panel(content, "✏️ Plan Refinement", "cyan")
-
-    def handle_plan_replan(
-        self,
-        reason: str,
-        replan_count: int,
-        preserved_count: int,
-    ) -> None:
-        """Handle plan replan triggered event."""
-        if not self.verbose:
-            return
-
-        content = Text()
-        content.append("Full Replan Triggered\n", style="yellow bold")
-        content.append("Reason: ", style="white")
-        content.append(f"{reason}\n", style="yellow")
-        content.append("Replan #: ", style="white")
-        content.append(f"{replan_count}\n", style="yellow")
-        content.append("Preserved Steps: ", style="white")
-        content.append(f"{preserved_count}\n", style="yellow")
-
-        self.print_panel(content, "🔄 Dynamic Replan", "yellow")
-
-    def handle_goal_achieved_early(
-        self,
-        steps_completed: int,
-        steps_remaining: int,
-    ) -> None:
-        """Handle goal achieved early event."""
-        if not self.verbose:
-            return
-
-        content = Text()
-        content.append("Goal Achieved Early!\n", style="green bold")
-        content.append("Completed: ", style="white")
-        content.append(f"{steps_completed} steps\n", style="green")
-        content.append("Skipped: ", style="white")
-        content.append(f"{steps_remaining} remaining steps\n", style="green")
-
-        self.print_panel(content, "🎯 Early Goal Achievement", "green")
-
     # ----------- AGENT LOGGING EVENTS -----------
 
     def handle_agent_logs_started(
@@ -1658,6 +1512,34 @@ To enable tracing, do any one of these:
         self.print(panel)
         self.print()
 
+    def handle_mcp_config_fetch_failed(
+        self,
+        slug: str,
+        error: str = "",
+        error_type: str | None = None,
+    ) -> None:
+        """Handle MCP config fetch failed event (AMP resolution failures)."""
+        if not self.verbose:
+            return
+
+        content = Text()
+        content.append("MCP Config Fetch Failed\n\n", style="red bold")
+        content.append("Server: ", style="white")
+        content.append(f"{slug}\n", style="red")
+
+        if error_type:
+            content.append("Error Type: ", style="white")
+            content.append(f"{error_type}\n", style="red")
+
+        if error:
+            content.append("\nError: ", style="white bold")
+            error_preview = error[:500] + "..." if len(error) > 500 else error
+            content.append(f"{error_preview}\n", style="red")
+
+        panel = self.create_panel(content, "❌ MCP Config Failed", "red")
+        self.print(panel)
+        self.print()
+
     def handle_mcp_tool_execution_started(
         self,
         server_name: str,

lib/crewai/src/crewai/flow/flow.py

@@ -16,7 +16,7 @@ from collections.abc import (
     Sequence,
     ValuesView,
 )
-from concurrent.futures import Future
+from concurrent.futures import Future, ThreadPoolExecutor
 import copy
 import enum
 import inspect
@@ -1739,7 +1739,12 @@ class Flow(Generic[T], metaclass=FlowMeta):
         async def _run_flow() -> Any:
             return await self.kickoff_async(inputs, input_files)
 
-        return asyncio.run(_run_flow())
+        try:
+            asyncio.get_running_loop()
+            with ThreadPoolExecutor(max_workers=1) as pool:
+                return pool.submit(asyncio.run, _run_flow()).result()
+        except RuntimeError:
+            return asyncio.run(_run_flow())
 
     async def kickoff_async(
         self,

lib/crewai/src/crewai/lite_agent.py

@@ -2,10 +2,10 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Callable
-import time
 from functools import wraps
 import inspect
 import json
+import time
 from types import MethodType
 from typing import (
     TYPE_CHECKING,
@@ -49,15 +49,20 @@ from crewai.events.types.agent_events import (
     LiteAgentExecutionErrorEvent,
     LiteAgentExecutionStartedEvent,
 )
+from crewai.events.types.logging_events import AgentLogsExecutionEvent
 from crewai.events.types.memory_events import (
     MemoryRetrievalCompletedEvent,
     MemoryRetrievalFailedEvent,
     MemoryRetrievalStartedEvent,
 )
-from crewai.events.types.logging_events import AgentLogsExecutionEvent
 from crewai.flow.flow_trackable import FlowTrackable
 from crewai.hooks.llm_hooks import get_after_llm_call_hooks, get_before_llm_call_hooks
-from crewai.hooks.types import AfterLLMCallHookType, BeforeLLMCallHookType
+from crewai.hooks.types import (
+    AfterLLMCallHookCallable,
+    AfterLLMCallHookType,
+    BeforeLLMCallHookCallable,
+    BeforeLLMCallHookType,
+)
 from crewai.lite_agent_output import LiteAgentOutput
 from crewai.llm import LLM
 from crewai.llms.base_llm import BaseLLM
@@ -270,11 +275,11 @@ class LiteAgent(FlowTrackable, BaseModel):
     _guardrail: GuardrailCallable | None = PrivateAttr(default=None)
     _guardrail_retry_count: int = PrivateAttr(default=0)
     _callbacks: list[TokenCalcHandler] = PrivateAttr(default_factory=list)
-    _before_llm_call_hooks: list[BeforeLLMCallHookType] = PrivateAttr(
-        default_factory=get_before_llm_call_hooks
+    _before_llm_call_hooks: list[BeforeLLMCallHookType | BeforeLLMCallHookCallable] = (
+        PrivateAttr(default_factory=get_before_llm_call_hooks)
     )
-    _after_llm_call_hooks: list[AfterLLMCallHookType] = PrivateAttr(
-        default_factory=get_after_llm_call_hooks
+    _after_llm_call_hooks: list[AfterLLMCallHookType | AfterLLMCallHookCallable] = (
+        PrivateAttr(default_factory=get_after_llm_call_hooks)
     )
     _memory: Any = PrivateAttr(default=None)
 
@@ -440,12 +445,16 @@ class LiteAgent(FlowTrackable, BaseModel):
         return self.role
 
     @property
-    def before_llm_call_hooks(self) -> list[BeforeLLMCallHookType]:
+    def before_llm_call_hooks(
+        self,
+    ) -> list[BeforeLLMCallHookType | BeforeLLMCallHookCallable]:
         """Get the before_llm_call hooks for this agent."""
         return self._before_llm_call_hooks
 
     @property
-    def after_llm_call_hooks(self) -> list[AfterLLMCallHookType]:
+    def after_llm_call_hooks(
+        self,
+    ) -> list[AfterLLMCallHookType | AfterLLMCallHookCallable]:
         """Get the after_llm_call hooks for this agent."""
         return self._after_llm_call_hooks
 
@@ -482,11 +491,12 @@ class LiteAgent(FlowTrackable, BaseModel):
         # Inject memory tools once if memory is configured (mirrors Agent._prepare_kickoff)
         if self._memory is not None:
             from crewai.tools.memory_tools import create_memory_tools
-            from crewai.utilities.agent_utils import sanitize_tool_name
+            from crewai.utilities.string_utils import sanitize_tool_name
 
             existing_names = {sanitize_tool_name(t.name) for t in self._parsed_tools}
             memory_tools = [
-                mt for mt in create_memory_tools(self._memory)
+                mt
+                for mt in create_memory_tools(self._memory)
                 if sanitize_tool_name(mt.name) not in existing_names
             ]
             if memory_tools:
@@ -565,9 +575,10 @@ class LiteAgent(FlowTrackable, BaseModel):
             if memory_block:
                 formatted = self.i18n.slice("memory").format(memory=memory_block)
                 if self._messages and self._messages[0].get("role") == "system":
-                    self._messages[0]["content"] = (
-                        self._messages[0].get("content", "") + "\n\n" + formatted
-                    )
+                    existing_content = self._messages[0].get("content", "")
+                    if not isinstance(existing_content, str):
+                        existing_content = ""
+                    self._messages[0]["content"] = existing_content + "\n\n" + formatted
             crewai_event_bus.emit(
                 self,
                 event=MemoryRetrievalCompletedEvent(
@@ -588,16 +599,12 @@ class LiteAgent(FlowTrackable, BaseModel):
             )
 
     def _save_to_memory(self, output_text: str) -> None:
-        """Extract discrete memories from the run and remember each. No-op if _memory is None."""
-        if self._memory is None:
+        """Extract discrete memories from the run and remember each. No-op if _memory is None or read-only."""
+        if self._memory is None or getattr(self._memory, "_read_only", False):
             return
         input_str = self._get_last_user_content() or "User request"
         try:
-            raw = (
-                f"Input: {input_str}\n"
-                f"Agent: {self.role}\n"
-                f"Result: {output_text}"
-            )
+            raw = f"Input: {input_str}\nAgent: {self.role}\nResult: {output_text}"
             extracted = self._memory.extract_memories(raw)
             if extracted:
                 self._memory.remember_many(extracted, agent_role=self.role)
@@ -622,13 +629,20 @@ class LiteAgent(FlowTrackable, BaseModel):
         )
 
         # Execute the agent using invoke loop
-        agent_finish = self._invoke_loop()
+        active_response_format = response_format or self.response_format
+        agent_finish = self._invoke_loop(response_model=active_response_format)
         if self._memory is not None:
-            self._save_to_memory(agent_finish.output)
+            output_text = (
+                agent_finish.output.model_dump_json()
+                if isinstance(agent_finish.output, BaseModel)
+                else agent_finish.output
+            )
+            self._save_to_memory(output_text)
         formatted_result: BaseModel | None = None
 
-        active_response_format = response_format or self.response_format
-        if active_response_format:
+        if isinstance(agent_finish.output, BaseModel):
+            formatted_result = agent_finish.output
+        elif active_response_format:
             try:
                 model_schema = generate_model_description(active_response_format)
                 schema = json.dumps(model_schema, indent=2)
@@ -660,8 +674,13 @@ class LiteAgent(FlowTrackable, BaseModel):
             usage_metrics = self._token_process.get_summary()
 
         # Create output
+        raw_output = (
+            agent_finish.output.model_dump_json()
+            if isinstance(agent_finish.output, BaseModel)
+            else agent_finish.output
+        )
         output = LiteAgentOutput(
-            raw=agent_finish.output,
+            raw=raw_output,
             pydantic=formatted_result,
             agent_role=self.role,
             usage_metrics=usage_metrics.model_dump() if usage_metrics else None,
@@ -838,10 +857,15 @@ class LiteAgent(FlowTrackable, BaseModel):
 
         return formatted_messages
 
-    def _invoke_loop(self) -> AgentFinish:
+    def _invoke_loop(
+        self, response_model: type[BaseModel] | None = None
+    ) -> AgentFinish:
         """
         Run the agent's thought process until it reaches a conclusion or max iterations.
 
+        Args:
+            response_model: Optional Pydantic model for native structured output.
+
         Returns:
             AgentFinish: The final result of the agent execution.
         """
@@ -870,12 +894,19 @@ class LiteAgent(FlowTrackable, BaseModel):
                         printer=self._printer,
                         from_agent=self,
                         executor_context=self,
+                        response_model=response_model,
                         verbose=self.verbose,
                     )
 
                 except Exception as e:
                     raise e
 
+                if isinstance(answer, BaseModel):
+                    formatted_answer = AgentFinish(
+                        thought="", output=answer, text=answer.model_dump_json()
+                    )
+                    break
+
                 formatted_answer = process_llm_response(
                     cast(str, answer), self.use_stop_words
                 )
@@ -901,7 +932,7 @@ class LiteAgent(FlowTrackable, BaseModel):
                     )
 
                 self._append_message(formatted_answer.text, role="assistant")
-            except OutputParserError as e:  # noqa: PERF203
+            except OutputParserError as e:
                 if self.verbose:
                     self._printer.print(
                         content="Failed to parse LLM output. Retrying...",

lib/crewai/src/crewai/lite_agent_output.py

@@ -6,27 +6,9 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-from crewai.utilities.planning_types import TodoItem
 from crewai.utilities.types import LLMMessage
 
 
-class TodoExecutionResult(BaseModel):
-    """Summary of a single todo execution."""
-
-    step_number: int = Field(description="Step number in the plan")
-    description: str = Field(description="What the todo was supposed to do")
-    tool_used: str | None = Field(
-        default=None, description="Tool that was used for this step"
-    )
-    status: str = Field(description="Final status: completed, failed, pending")
-    result: str | None = Field(
-        default=None, description="Result or error message from execution"
-    )
-    depends_on: list[int] = Field(
-        default_factory=list, description="Step numbers this depended on"
-    )
-
-
 class LiteAgentOutput(BaseModel):
     """Class that represents the result of a LiteAgent execution."""
 
@@ -42,75 +24,12 @@ class LiteAgentOutput(BaseModel):
     )
     messages: list[LLMMessage] = Field(description="Messages of the agent", default=[])
 
-    plan: str | None = Field(
-        default=None, description="The execution plan that was generated, if any"
-    )
-    todos: list[TodoExecutionResult] = Field(
-        default_factory=list,
-        description="List of todos that were executed with their results",
-    )
-    replan_count: int = Field(
-        default=0, description="Number of times the plan was regenerated"
-    )
-    last_replan_reason: str | None = Field(
-        default=None, description="Reason for the last replan, if any"
-    )
-
-    @classmethod
-    def from_todo_items(cls, todo_items: list[TodoItem]) -> list[TodoExecutionResult]:
-        """Convert TodoItem objects to TodoExecutionResult summaries.
-
-        Args:
-            todo_items: List of TodoItem objects from execution.
-
-        Returns:
-            List of TodoExecutionResult summaries.
-        """
-        return [
-            TodoExecutionResult(
-                step_number=item.step_number,
-                description=item.description,
-                tool_used=item.tool_to_use,
-                status=item.status,
-                result=item.result,
-                depends_on=item.depends_on,
-            )
-            for item in todo_items
-        ]
-
     def to_dict(self) -> dict[str, Any]:
         """Convert pydantic_output to a dictionary."""
         if self.pydantic:
             return self.pydantic.model_dump()
         return {}
 
-    @property
-    def completed_todos(self) -> list[TodoExecutionResult]:
-        """Get only the completed todos."""
-        return [t for t in self.todos if t.status == "completed"]
-
-    @property
-    def failed_todos(self) -> list[TodoExecutionResult]:
-        """Get only the failed todos."""
-        return [t for t in self.todos if t.status == "failed"]
-
-    @property
-    def had_plan(self) -> bool:
-        """Check if the agent executed with a plan."""
-        return self.plan is not None or len(self.todos) > 0
-
     def __str__(self) -> str:
         """Return the raw output as a string."""
         return self.raw
-
-    def __repr__(self) -> str:
-        """Return a detailed representation including todo summary."""
-        parts = [f"LiteAgentOutput(role={self.agent_role!r}"]
-        if self.todos:
-            completed = len(self.completed_todos)
-            total = len(self.todos)
-            parts.append(f", todos={completed}/{total} completed")
-        if self.replan_count > 0:
-            parts.append(f", replans={self.replan_count}")
-        parts.append(")")
-        return "".join(parts)

lib/crewai/src/crewai/llm.py

@@ -427,7 +427,7 @@ class LLM(BaseLLM):
                 f"installed.\n\n"
                 f"To fix this, either:\n"
                 f"  1. Install LiteLLM for broad model support: "
-                f"uv add litellm\n"
+                f"uv add 'crewai[litellm]'\n"
                 f"or\n"
                 f"pip install litellm\n\n"
                 f"For more details, see: "

lib/crewai/src/crewai/llms/providers/bedrock/completion.py

@@ -234,7 +234,7 @@ class BedrockCompletion(BaseLLM):
         aws_access_key_id: str | None = None,
         aws_secret_access_key: str | None = None,
         aws_session_token: str | None = None,
-        region_name: str = "us-east-1",
+        region_name: str | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
         top_p: float | None = None,
@@ -287,15 +287,6 @@ class BedrockCompletion(BaseLLM):
             **kwargs,
         )
 
-        # Initialize Bedrock client with proper configuration
-        session = Session(
-            aws_access_key_id=aws_access_key_id or os.getenv("AWS_ACCESS_KEY_ID"),
-            aws_secret_access_key=aws_secret_access_key
-            or os.getenv("AWS_SECRET_ACCESS_KEY"),
-            aws_session_token=aws_session_token or os.getenv("AWS_SESSION_TOKEN"),
-            region_name=region_name,
-        )
-
         # Configure client with timeouts and retries following AWS best practices
         config = Config(
             read_timeout=300,
@@ -306,8 +297,12 @@ class BedrockCompletion(BaseLLM):
             tcp_keepalive=True,
         )
 
-        self.client = session.client("bedrock-runtime", config=config)
-        self.region_name = region_name
+        self.region_name = (
+            region_name
+            or os.getenv("AWS_DEFAULT_REGION")
+            or os.getenv("AWS_REGION_NAME")
+            or "us-east-1"
+        )
 
         self.aws_access_key_id = aws_access_key_id or os.getenv("AWS_ACCESS_KEY_ID")
         self.aws_secret_access_key = aws_secret_access_key or os.getenv(
@@ -315,6 +310,16 @@ class BedrockCompletion(BaseLLM):
         )
         self.aws_session_token = aws_session_token or os.getenv("AWS_SESSION_TOKEN")
 
+        # Initialize Bedrock client with proper configuration
+        session = Session(
+            aws_access_key_id=self.aws_access_key_id,
+            aws_secret_access_key=self.aws_secret_access_key,
+            aws_session_token=self.aws_session_token,
+            region_name=self.region_name,
+        )
+
+        self.client = session.client("bedrock-runtime", config=config)
+
         self._async_exit_stack = AsyncExitStack() if AIOBOTOCORE_AVAILABLE else None
         self._async_client_initialized = False
 
@@ -1838,10 +1843,7 @@ class BedrockCompletion(BaseLLM):
                     )
 
         # CRITICAL: Handle model-specific conversation requirements
-        # Cohere and some other models require conversation to end with user message.
-        # Anthropic models on Bedrock also reject assistant messages in the final
-        # position when tools are present ("pre-filling the assistant response is
-        # not supported").
+        # Cohere and some other models require conversation to end with user message
         if converse_messages:
             last_message = converse_messages[-1]
             if last_message["role"] == "assistant":
@@ -1868,20 +1870,6 @@ class BedrockCompletion(BaseLLM):
                             "content": [{"text": "Continue your response."}],
                         }
                     )
-                # Anthropic (Claude) models reject assistant-last messages when
-                # tools are in the request. Append a user message so the
-                # Converse API accepts the payload.
-                elif "anthropic" in self.model.lower() or "claude" in self.model.lower():
-                    converse_messages.append(
-                        {
-                            "role": "user",
-                            "content": [
-                                {
-                                    "text": "Please continue and provide your final answer."
-                                }
-                            ],
-                        }
-                    )
 
         # Ensure first message is from user (required by Converse API)
         if not converse_messages:

lib/crewai/src/crewai/llms/providers/gemini/completion.py

@@ -894,7 +894,7 @@ class GeminiCompletion(BaseLLM):
         content = self._extract_text_from_response(response)
 
         effective_response_model = None if self.tools else response_model
-        if not effective_response_model:
+        if not response_model:
             content = self._apply_stop_words(content)
 
         return self._finalize_completion_response(

lib/crewai/src/crewai/mcp/__init__.py

@@ -18,6 +18,7 @@ from crewai.mcp.filters import (
     create_dynamic_tool_filter,
     create_static_tool_filter,
 )
+from crewai.mcp.tool_resolver import MCPToolResolver
 from crewai.mcp.transports.base import BaseTransport, TransportType
 
 
@@ -28,6 +29,7 @@ __all__ = [
     "MCPServerHTTP",
     "MCPServerSSE",
     "MCPServerStdio",
+    "MCPToolResolver",
     "StaticToolFilter",
     "ToolFilter",
     "ToolFilterContext",

lib/crewai/src/crewai/mcp/client.py

@@ -6,7 +6,7 @@ from contextlib import AsyncExitStack
 from datetime import datetime
 import logging
 import time
-from typing import Any
+from typing import Any, NamedTuple
 
 from typing_extensions import Self
 
@@ -34,6 +34,13 @@ from crewai.mcp.transports.stdio import StdioTransport
 from crewai.utilities.string_utils import sanitize_tool_name
 
 
+class _MCPToolResult(NamedTuple):
+    """Internal result from an MCP tool call, carrying the ``isError`` flag."""
+
+    content: str
+    is_error: bool
+
+
 # MCP Connection timeout constants (in seconds)
 MCP_CONNECTION_TIMEOUT = 30  # Increased for slow servers
 MCP_TOOL_EXECUTION_TIMEOUT = 30
@@ -420,6 +427,7 @@ class MCPClient:
         return [
             {
                 "name": sanitize_tool_name(tool.name),
+                "original_name": tool.name,
                 "description": getattr(tool, "description", ""),
                 "inputSchema": getattr(tool, "inputSchema", {}),
             }
@@ -461,29 +469,46 @@ class MCPClient:
         )
 
         try:
-            result = await self._retry_operation(
+            tool_result: _MCPToolResult = await self._retry_operation(
                 lambda: self._call_tool_impl(tool_name, cleaned_arguments),
                 timeout=self.execution_timeout,
             )
 
-            completed_at = datetime.now()
-            execution_duration_ms = (completed_at - started_at).total_seconds() * 1000
-            crewai_event_bus.emit(
-                self,
-                MCPToolExecutionCompletedEvent(
-                    server_name=server_name,
-                    server_url=server_url,
-                    transport_type=transport_type,
-                    tool_name=tool_name,
-                    tool_args=cleaned_arguments,
-                    result=result,
-                    started_at=started_at,
-                    completed_at=completed_at,
-                    execution_duration_ms=execution_duration_ms,
-                ),
-            )
+            finished_at = datetime.now()
+            execution_duration_ms = (finished_at - started_at).total_seconds() * 1000
 
-            return result
+            if tool_result.is_error:
+                crewai_event_bus.emit(
+                    self,
+                    MCPToolExecutionFailedEvent(
+                        server_name=server_name,
+                        server_url=server_url,
+                        transport_type=transport_type,
+                        tool_name=tool_name,
+                        tool_args=cleaned_arguments,
+                        error=tool_result.content,
+                        error_type="tool_error",
+                        started_at=started_at,
+                        failed_at=finished_at,
+                    ),
+                )
+            else:
+                crewai_event_bus.emit(
+                    self,
+                    MCPToolExecutionCompletedEvent(
+                        server_name=server_name,
+                        server_url=server_url,
+                        transport_type=transport_type,
+                        tool_name=tool_name,
+                        tool_args=cleaned_arguments,
+                        result=tool_result.content,
+                        started_at=started_at,
+                        completed_at=finished_at,
+                        execution_duration_ms=execution_duration_ms,
+                    ),
+                )
+
+            return tool_result.content
         except Exception as e:
             failed_at = datetime.now()
             error_type = (
@@ -564,23 +589,27 @@ class MCPClient:
 
         return cleaned
 
-    async def _call_tool_impl(self, tool_name: str, arguments: dict[str, Any]) -> Any:
+    async def _call_tool_impl(
+        self, tool_name: str, arguments: dict[str, Any]
+    ) -> _MCPToolResult:
         """Internal implementation of call_tool."""
         result = await asyncio.wait_for(
             self.session.call_tool(tool_name, arguments),
             timeout=self.execution_timeout,
         )
 
+        is_error = getattr(result, "isError", False) or False
+
         # Extract result content
         if hasattr(result, "content") and result.content:
             if isinstance(result.content, list) and len(result.content) > 0:
                 content_item = result.content[0]
                 if hasattr(content_item, "text"):
-                    return str(content_item.text)
-                return str(content_item)
-            return str(result.content)
+                    return _MCPToolResult(str(content_item.text), is_error)
+                return _MCPToolResult(str(content_item), is_error)
+            return _MCPToolResult(str(result.content), is_error)
 
-        return str(result)
+        return _MCPToolResult(str(result), is_error)
 
     async def list_prompts(self) -> list[dict[str, Any]]:
         """List available prompts from MCP server.

lib/crewai/src/crewai/mcp/tool_resolver.py

@@ -0,0 +1,592 @@
+"""MCP tool resolution for CrewAI agents.
+
+This module extracts all MCP-related tool resolution logic from the Agent class
+into a standalone MCPToolResolver. It handles three flavours of MCP reference:
+
+  1. Native configs:   MCPServerStdio / MCPServerHTTP / MCPServerSSE objects.
+  2. HTTPS URLs:       e.g. "https://mcp.example.com/api"
+  3. AMP references:   e.g. "notion" or "notion#search" (legacy "crewai-amp:" prefix also works)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any, Final, cast
+from urllib.parse import urlparse
+
+from crewai.mcp.client import MCPClient
+from crewai.mcp.config import (
+    MCPServerConfig,
+    MCPServerHTTP,
+    MCPServerSSE,
+    MCPServerStdio,
+)
+from crewai.mcp.transports.http import HTTPTransport
+from crewai.mcp.transports.sse import SSETransport
+from crewai.mcp.transports.stdio import StdioTransport
+
+
+if TYPE_CHECKING:
+    from crewai.tools.base_tool import BaseTool
+    from crewai.utilities.logger import Logger
+
+MCP_CONNECTION_TIMEOUT: Final[int] = 10
+MCP_TOOL_EXECUTION_TIMEOUT: Final[int] = 30
+MCP_DISCOVERY_TIMEOUT: Final[int] = 15
+MCP_MAX_RETRIES: Final[int] = 3
+
+_mcp_schema_cache: dict[str, Any] = {}
+_cache_ttl: Final[int] = 300  # 5 minutes
+
+
+class MCPToolResolver:
+    """Resolves MCP server references / configs into CrewAI ``BaseTool`` instances.
+
+    Typical lifecycle::
+
+        resolver = MCPToolResolver(agent=my_agent, logger=my_agent._logger)
+        tools = resolver.resolve(my_agent.mcps)
+        # … agent executes tasks using *tools* …
+        resolver.cleanup()
+
+    The resolver owns the MCP client connections it creates and is responsible
+    for tearing them down via :meth:`cleanup`.
+    """
+
+    def __init__(self, agent: Any, logger: Logger) -> None:
+        self._agent = agent
+        self._logger = logger
+        self._clients: list[Any] = []
+
+    @property
+    def clients(self) -> list[Any]:
+        return list(self._clients)
+
+    def resolve(self, mcps: list[str | MCPServerConfig]) -> list[BaseTool]:
+        """Convert MCP server references/configs to CrewAI tools."""
+        all_tools: list[BaseTool] = []
+        amp_refs: list[tuple[str, str | None]] = []
+
+        for mcp_config in mcps:
+            if isinstance(mcp_config, str) and mcp_config.startswith("https://"):
+                all_tools.extend(self._resolve_external(mcp_config))
+            elif isinstance(mcp_config, str):
+                amp_refs.append(self._parse_amp_ref(mcp_config))
+            else:
+                tools, client = self._resolve_native(mcp_config)
+                all_tools.extend(tools)
+                if client:
+                    self._clients.append(client)
+
+        if amp_refs:
+            tools, clients = self._resolve_amp(amp_refs)
+            all_tools.extend(tools)
+            self._clients.extend(clients)
+
+        return all_tools
+
+    def cleanup(self) -> None:
+        """Disconnect all MCP client connections."""
+        if not self._clients:
+            return
+
+        async def _disconnect_all() -> None:
+            for client in self._clients:
+                if client and hasattr(client, "connected") and client.connected:
+                    await client.disconnect()
+
+        try:
+            asyncio.run(_disconnect_all())
+        except Exception as e:
+            self._logger.log("error", f"Error during MCP client cleanup: {e}")
+        finally:
+            self._clients.clear()
+
+    @staticmethod
+    def _parse_amp_ref(mcp_config: str) -> tuple[str, str | None]:
+        """Parse an AMP reference into *(slug, optional tool name)*.
+
+        Accepts both bare slugs (``"notion"``, ``"notion#search"``) and the
+        legacy ``"crewai-amp:notion"`` form.
+        """
+        bare = mcp_config.removeprefix("crewai-amp:")
+        slug, _, specific_tool = bare.partition("#")
+        return slug, specific_tool or None
+
+    def _resolve_amp(
+        self, amp_refs: list[tuple[str, str | None]]
+    ) -> tuple[list[BaseTool], list[Any]]:
+        """Fetch AMP configs in bulk and return their tools and clients.
+
+        Resolves each unique slug only once (single connection per server),
+        then applies per-ref tool filters to select specific tools.
+        """
+        from crewai.events.event_bus import crewai_event_bus
+        from crewai.events.types.mcp_events import MCPConfigFetchFailedEvent
+
+        unique_slugs = list(dict.fromkeys(slug for slug, _ in amp_refs))
+        amp_configs_map = self._fetch_amp_mcp_configs(unique_slugs)
+
+        all_tools: list[BaseTool] = []
+        all_clients: list[Any] = []
+
+        resolved_cache: dict[str, tuple[list[BaseTool], Any | None]] = {}
+
+        for slug in unique_slugs:
+            config_dict = amp_configs_map.get(slug)
+            if not config_dict:
+                crewai_event_bus.emit(
+                    self,
+                    MCPConfigFetchFailedEvent(
+                        slug=slug,
+                        error=f"Config for '{slug}' not found. Make sure it is connected in your account.",
+                        error_type="not_connected",
+                    ),
+                )
+                continue
+
+            mcp_server_config = self._build_mcp_config_from_dict(config_dict)
+
+            try:
+                tools, client = self._resolve_native(mcp_server_config)
+                resolved_cache[slug] = (tools, client)
+                if client:
+                    all_clients.append(client)
+            except Exception as e:
+                crewai_event_bus.emit(
+                    self,
+                    MCPConfigFetchFailedEvent(
+                        slug=slug,
+                        error=str(e),
+                        error_type="connection_failed",
+                    ),
+                )
+
+        for slug, specific_tool in amp_refs:
+            cached = resolved_cache.get(slug)
+            if not cached:
+                continue
+
+            slug_tools, _ = cached
+            if specific_tool:
+                all_tools.extend(
+                    t for t in slug_tools if t.name.endswith(f"_{specific_tool}")
+                )
+            else:
+                all_tools.extend(slug_tools)
+
+        return all_tools, all_clients
+
+    def _fetch_amp_mcp_configs(self, slugs: list[str]) -> dict[str, dict[str, Any]]:
+        """Fetch MCP server configurations via CrewAI+ API.
+
+        Sends a GET request to the CrewAI+ mcps/configs endpoint with
+        comma-separated slugs. CrewAI+ proxies the request to crewai-oauth.
+
+        API-level failures return ``{}``; individual slugs will then
+        surface as ``MCPConfigFetchFailedEvent`` in :meth:`_resolve_amp`.
+        """
+        import httpx
+
+        try:
+            from crewai_tools.tools.crewai_platform_tools.misc import (
+                get_platform_integration_token,
+            )
+
+            from crewai.cli.plus_api import PlusAPI
+
+            plus_api = PlusAPI(api_key=get_platform_integration_token())
+            response = plus_api.get_mcp_configs(slugs)
+
+            if response.status_code == 200:
+                configs: dict[str, dict[str, Any]] = response.json().get("configs", {})
+                return configs
+
+            self._logger.log(
+                "debug",
+                f"Failed to fetch MCP configs: HTTP {response.status_code}",
+            )
+            return {}
+
+        except httpx.HTTPError as e:
+            self._logger.log("debug", f"Failed to fetch MCP configs: {e}")
+            return {}
+        except Exception as e:
+            self._logger.log("debug", f"Cannot fetch AMP MCP configs: {e}")
+            return {}
+
+    def _resolve_external(self, mcp_ref: str) -> list[BaseTool]:
+        """Resolve an HTTPS MCP server URL into tools."""
+        from crewai.tools.mcp_tool_wrapper import MCPToolWrapper
+
+        if "#" in mcp_ref:
+            server_url, specific_tool = mcp_ref.split("#", 1)
+        else:
+            server_url, specific_tool = mcp_ref, None
+
+        server_params = {"url": server_url}
+        server_name = self._extract_server_name(server_url)
+
+        try:
+            tool_schemas = self._get_mcp_tool_schemas(server_params)
+
+            if not tool_schemas:
+                self._logger.log(
+                    "warning", f"No tools discovered from MCP server: {server_url}"
+                )
+                return []
+
+            tools = []
+            for tool_name, schema in tool_schemas.items():
+                if specific_tool and tool_name != specific_tool:
+                    continue
+
+                try:
+                    wrapper = MCPToolWrapper(
+                        mcp_server_params=server_params,
+                        tool_name=tool_name,
+                        tool_schema=schema,
+                        server_name=server_name,
+                    )
+                    tools.append(wrapper)
+                except Exception as e:
+                    self._logger.log(
+                        "warning",
+                        f"Failed to create MCP tool wrapper for {tool_name}: {e}",
+                    )
+                    continue
+
+            if specific_tool and not tools:
+                self._logger.log(
+                    "warning",
+                    f"Specific tool '{specific_tool}' not found on MCP server: {server_url}",
+                )
+
+            return cast(list[BaseTool], tools)
+
+        except Exception as e:
+            self._logger.log(
+                "warning", f"Failed to connect to MCP server {server_url}: {e}"
+            )
+            return []
+
+    def _resolve_native(
+        self, mcp_config: MCPServerConfig
+    ) -> tuple[list[BaseTool], Any | None]:
+        """Resolve an ``MCPServerConfig`` into tools, returning the client for cleanup."""
+        from crewai.tools.base_tool import BaseTool
+        from crewai.tools.mcp_native_tool import MCPNativeTool
+
+        transport: StdioTransport | HTTPTransport | SSETransport
+        if isinstance(mcp_config, MCPServerStdio):
+            transport = StdioTransport(
+                command=mcp_config.command,
+                args=mcp_config.args,
+                env=mcp_config.env,
+            )
+            server_name = f"{mcp_config.command}_{'_'.join(mcp_config.args)}"
+        elif isinstance(mcp_config, MCPServerHTTP):
+            transport = HTTPTransport(
+                url=mcp_config.url,
+                headers=mcp_config.headers,
+                streamable=mcp_config.streamable,
+            )
+            server_name = self._extract_server_name(mcp_config.url)
+        elif isinstance(mcp_config, MCPServerSSE):
+            transport = SSETransport(
+                url=mcp_config.url,
+                headers=mcp_config.headers,
+            )
+            server_name = self._extract_server_name(mcp_config.url)
+        else:
+            raise ValueError(f"Unsupported MCP server config type: {type(mcp_config)}")
+
+        client = MCPClient(
+            transport=transport,
+            cache_tools_list=mcp_config.cache_tools_list,
+        )
+
+        async def _setup_client_and_list_tools() -> list[dict[str, Any]]:
+            try:
+                if not client.connected:
+                    await client.connect()
+
+                tools_list = await client.list_tools()
+
+                try:
+                    await client.disconnect()
+                    await asyncio.sleep(0.1)
+                except Exception as e:
+                    self._logger.log("error", f"Error during disconnect: {e}")
+
+                return tools_list
+            except Exception as e:
+                if client.connected:
+                    await client.disconnect()
+                    await asyncio.sleep(0.1)
+                raise RuntimeError(
+                    f"Error during setup client and list tools: {e}"
+                ) from e
+
+        try:
+            try:
+                asyncio.get_running_loop()
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(
+                        asyncio.run, _setup_client_and_list_tools()
+                    )
+                    tools_list = future.result()
+            except RuntimeError:
+                try:
+                    tools_list = asyncio.run(_setup_client_and_list_tools())
+                except RuntimeError as e:
+                    error_msg = str(e).lower()
+                    if "cancel scope" in error_msg or "task" in error_msg:
+                        raise ConnectionError(
+                            "MCP connection failed due to event loop cleanup issues. "
+                            "This may be due to authentication errors or server unavailability."
+                        ) from e
+                except asyncio.CancelledError as e:
+                    raise ConnectionError(
+                        "MCP connection was cancelled. This may indicate an authentication "
+                        "error or server unavailability."
+                    ) from e
+
+            if mcp_config.tool_filter:
+                filtered_tools = []
+                for tool in tools_list:
+                    if callable(mcp_config.tool_filter):
+                        try:
+                            from crewai.mcp.filters import ToolFilterContext
+
+                            context = ToolFilterContext(
+                                agent=self._agent,
+                                server_name=server_name,
+                                run_context=None,
+                            )
+                            if mcp_config.tool_filter(context, tool):  # type: ignore[call-arg, arg-type]
+                                filtered_tools.append(tool)
+                        except (TypeError, AttributeError):
+                            if mcp_config.tool_filter(tool):  # type: ignore[call-arg, arg-type]
+                                filtered_tools.append(tool)
+                    else:
+                        filtered_tools.append(tool)
+                tools_list = filtered_tools
+
+            tools = []
+            for tool_def in tools_list:
+                tool_name = tool_def.get("name", "")
+                original_tool_name = tool_def.get("original_name", tool_name)
+                if not tool_name:
+                    continue
+
+                args_schema = None
+                if tool_def.get("inputSchema"):
+                    args_schema = self._json_schema_to_pydantic(
+                        tool_name, tool_def["inputSchema"]
+                    )
+
+                tool_schema = {
+                    "description": tool_def.get("description", ""),
+                    "args_schema": args_schema,
+                }
+
+                try:
+                    native_tool = MCPNativeTool(
+                        mcp_client=client,
+                        tool_name=tool_name,
+                        tool_schema=tool_schema,
+                        server_name=server_name,
+                        original_tool_name=original_tool_name,
+                    )
+                    tools.append(native_tool)
+                except Exception as e:
+                    self._logger.log("error", f"Failed to create native MCP tool: {e}")
+                    continue
+
+            return cast(list[BaseTool], tools), client
+        except Exception as e:
+            if client.connected:
+                asyncio.run(client.disconnect())
+
+            raise RuntimeError(f"Failed to get native MCP tools: {e}") from e
+
+    @staticmethod
+    def _build_mcp_config_from_dict(
+        config_dict: dict[str, Any],
+    ) -> MCPServerConfig:
+        """Convert a config dict from crewai-oauth into an MCPServerConfig."""
+        config_type = config_dict.get("type", "http")
+
+        if config_type == "sse":
+            return MCPServerSSE(
+                url=config_dict["url"],
+                headers=config_dict.get("headers"),
+                cache_tools_list=config_dict.get("cache_tools_list", False),
+            )
+
+        return MCPServerHTTP(
+            url=config_dict["url"],
+            headers=config_dict.get("headers"),
+            streamable=config_dict.get("streamable", True),
+            cache_tools_list=config_dict.get("cache_tools_list", False),
+        )
+
+    @staticmethod
+    def _extract_server_name(server_url: str) -> str:
+        """Extract clean server name from URL for tool prefixing."""
+        parsed = urlparse(server_url)
+        domain = parsed.netloc.replace(".", "_")
+        path = parsed.path.replace("/", "_").strip("_")
+        return f"{domain}_{path}" if path else domain
+
+    def _get_mcp_tool_schemas(
+        self, server_params: dict[str, Any]
+    ) -> dict[str, dict[str, Any]]:
+        """Get tool schemas from MCP server with caching."""
+        server_url = server_params["url"]
+
+        cache_key = server_url
+        current_time = time.time()
+
+        if cache_key in _mcp_schema_cache:
+            cached_data, cache_time = _mcp_schema_cache[cache_key]
+            if current_time - cache_time < _cache_ttl:
+                self._logger.log(
+                    "debug", f"Using cached MCP tool schemas for {server_url}"
+                )
+                return cached_data  # type: ignore[no-any-return]
+
+        try:
+            schemas = asyncio.run(self._get_mcp_tool_schemas_async(server_params))
+            _mcp_schema_cache[cache_key] = (schemas, current_time)
+            return schemas
+        except Exception as e:
+            self._logger.log(
+                "warning", f"Failed to get MCP tool schemas from {server_url}: {e}"
+            )
+            return {}
+
+    async def _get_mcp_tool_schemas_async(
+        self, server_params: dict[str, Any]
+    ) -> dict[str, dict[str, Any]]:
+        """Async implementation of MCP tool schema retrieval."""
+        server_url = server_params["url"]
+        return await self._retry_mcp_discovery(
+            self._discover_mcp_tools_with_timeout, server_url
+        )
+
+    async def _retry_mcp_discovery(
+        self, operation_func: Any, server_url: str
+    ) -> dict[str, dict[str, Any]]:
+        """Retry MCP discovery with exponential backoff."""
+        last_error = None
+
+        for attempt in range(MCP_MAX_RETRIES):
+            result, error, should_retry = await self._attempt_mcp_discovery(
+                operation_func, server_url
+            )
+
+            if result is not None:
+                return result
+
+            if not should_retry:
+                raise RuntimeError(error)
+
+            last_error = error
+            if attempt < MCP_MAX_RETRIES - 1:
+                wait_time = 2**attempt
+                await asyncio.sleep(wait_time)
+
+        raise RuntimeError(
+            f"Failed to discover MCP tools after {MCP_MAX_RETRIES} attempts: {last_error}"
+        )
+
+    @staticmethod
+    async def _attempt_mcp_discovery(
+        operation_func: Any, server_url: str
+    ) -> tuple[dict[str, dict[str, Any]] | None, str, bool]:
+        """Attempt single MCP discovery; returns *(result, error_message, should_retry)*."""
+        try:
+            result = await operation_func(server_url)
+            return result, "", False
+
+        except ImportError:
+            return (
+                None,
+                "MCP library not available. Please install with: pip install mcp",
+                False,
+            )
+
+        except asyncio.TimeoutError:
+            return (
+                None,
+                f"MCP discovery timed out after {MCP_DISCOVERY_TIMEOUT} seconds",
+                True,
+            )
+
+        except Exception as e:
+            error_str = str(e).lower()
+
+            if "authentication" in error_str or "unauthorized" in error_str:
+                return None, f"Authentication failed for MCP server: {e!s}", False
+            if "connection" in error_str or "network" in error_str:
+                return None, f"Network connection failed: {e!s}", True
+            if "json" in error_str or "parsing" in error_str:
+                return None, f"Server response parsing error: {e!s}", True
+            return None, f"MCP discovery error: {e!s}", False
+
+    async def _discover_mcp_tools_with_timeout(
+        self, server_url: str
+    ) -> dict[str, dict[str, Any]]:
+        """Discover MCP tools with timeout wrapper."""
+        return await asyncio.wait_for(
+            self._discover_mcp_tools(server_url), timeout=MCP_DISCOVERY_TIMEOUT
+        )
+
+    async def _discover_mcp_tools(self, server_url: str) -> dict[str, dict[str, Any]]:
+        """Discover tools from an MCP server (HTTPS / streamable-HTTP path)."""
+        from mcp import ClientSession
+        from mcp.client.streamable_http import streamablehttp_client
+
+        from crewai.utilities.string_utils import sanitize_tool_name
+
+        async with streamablehttp_client(server_url) as (read, write, _):
+            async with ClientSession(read, write) as session:
+                await asyncio.wait_for(
+                    session.initialize(), timeout=MCP_CONNECTION_TIMEOUT
+                )
+
+                tools_result = await asyncio.wait_for(
+                    session.list_tools(),
+                    timeout=MCP_DISCOVERY_TIMEOUT - MCP_CONNECTION_TIMEOUT,
+                )
+
+                schemas = {}
+                for tool in tools_result.tools:
+                    args_schema = None
+                    if hasattr(tool, "inputSchema") and tool.inputSchema:
+                        args_schema = self._json_schema_to_pydantic(
+                            sanitize_tool_name(tool.name), tool.inputSchema
+                        )
+
+                    schemas[sanitize_tool_name(tool.name)] = {
+                        "description": getattr(tool, "description", ""),
+                        "args_schema": args_schema,
+                    }
+                return schemas
+
+    @staticmethod
+    def _json_schema_to_pydantic(tool_name: str, json_schema: dict[str, Any]) -> type:
+        """Convert JSON Schema to a Pydantic model for tool arguments."""
+        from crewai.utilities.pydantic_schema_utils import create_model_from_schema
+
+        model_name = f"{tool_name.replace('-', '_').replace(' ', '_')}Schema"
+        return create_model_from_schema(
+            json_schema,
+            model_name=model_name,
+            enrich_descriptions=True,
+        )

lib/crewai/src/crewai/memory/__init__.py

@@ -1,6 +1,14 @@
-"""Memory module: unified Memory with LLM analysis and pluggable storage."""
+"""Memory module: unified Memory with LLM analysis and pluggable storage.
+
+Heavy dependencies are lazily imported so that
+``import crewai`` does not initialise at runtime — critical for
+Celery pre-fork and similar deployment patterns.
+"""
+
+from __future__ import annotations
+
+from typing import Any
 
-from crewai.memory.encoding_flow import EncodingFlow
 from crewai.memory.memory_scope import MemoryScope, MemorySlice
 from crewai.memory.types import (
     MemoryMatch,
@@ -10,7 +18,24 @@ from crewai.memory.types import (
     embed_text,
     embed_texts,
 )
-from crewai.memory.unified_memory import Memory
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "Memory": ("crewai.memory.unified_memory", "Memory"),
+    "EncodingFlow": ("crewai.memory.encoding_flow", "EncodingFlow"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import Memory / EncodingFlow to avoid pulling in lancedb at import time."""
+    if name in _LAZY_IMPORTS:
+        import importlib
+
+        module_path, attr = _LAZY_IMPORTS[name]
+        mod = importlib.import_module(module_path)
+        val = getattr(mod, attr)
+        globals()[name] = val
+        return val
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 __all__ = [

lib/crewai/src/crewai/memory/memory_scope.py

@@ -145,7 +145,7 @@ class MemoryScope:
 
 
 class MemorySlice:
-    """View over multiple scopes: recall searches all, remember requires explicit scope unless read_only."""
+    """View over multiple scopes: recall searches all, remember is a no-op when read_only."""
 
     def __init__(
         self,
@@ -160,7 +160,7 @@ class MemorySlice:
             memory: The underlying Memory instance.
             scopes: List of scope paths to include.
             categories: Optional category filter for recall.
-            read_only: If True, remember() raises PermissionError.
+            read_only: If True, remember() is a silent no-op.
         """
         self._memory = memory
         self._scopes = [s.rstrip("/") or "/" for s in scopes]
@@ -176,10 +176,10 @@ class MemorySlice:
         importance: float | None = None,
         source: str | None = None,
         private: bool = False,
-    ) -> MemoryRecord:
-        """Remember into an explicit scope. Required when read_only=False."""
+    ) -> MemoryRecord | None:
+        """Remember into an explicit scope. No-op when read_only=True."""
         if self._read_only:
-            raise PermissionError("This MemorySlice is read-only")
+            return None
         return self._memory.remember(
             content,
             scope=scope,

lib/crewai/src/crewai/memory/storage/lancedb_storage.py

@@ -53,6 +53,7 @@ class LanceDBStorage:
         path: str | Path | None = None,
         table_name: str = "memories",
         vector_dim: int | None = None,
+        compact_every: int = 100,
     ) -> None:
         """Initialize LanceDB storage.
 
@@ -64,6 +65,10 @@ class LanceDBStorage:
             vector_dim: Dimensionality of the embedding vector. When ``None``
                   (default), the dimension is auto-detected from the existing
                   table schema or from the first saved embedding.
+            compact_every: Number of ``save()`` calls between automatic
+                  background compactions.  Each ``save()`` creates one new
+                  fragment file; compaction merges them, keeping query
+                  performance consistent.  Set to 0 to disable.
         """
         if path is None:
             storage_dir = os.environ.get("CREWAI_STORAGE_DIR")
@@ -78,6 +83,22 @@ class LanceDBStorage:
         self._table_name = table_name
         self._db = lancedb.connect(str(self._path))
 
+        # On macOS and Linux the default per-process open-file limit is 256.
+        # A LanceDB table stores one file per fragment (one fragment per save()
+        # call by default).  With hundreds of fragments, a single full-table
+        # scan opens all of them simultaneously, exhausting the limit.
+        # Raise it proactively so scans on large tables never hit OS error 24.
+        try:
+            import resource
+            soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
+            if soft < 4096:
+                resource.setrlimit(resource.RLIMIT_NOFILE, (min(hard, 4096), hard))
+        except Exception:  # noqa: S110
+            pass  # Windows or already at the max hard limit — safe to ignore
+
+        self._compact_every = compact_every
+        self._save_count = 0
+
         # Get or create a shared write lock for this database path.
         resolved = str(self._path.resolve())
         with LanceDBStorage._path_locks_guard:
@@ -91,6 +112,11 @@ class LanceDBStorage:
         try:
             self._table: lancedb.table.Table | None = self._db.open_table(self._table_name)
             self._vector_dim: int = self._infer_dim_from_table(self._table)
+            # Best-effort: create the scope index if it doesn't exist yet.
+            self._ensure_scope_index()
+            # Compact in the background if the table has accumulated many
+            # fragments from previous runs (each save() creates one).
+            self._compact_if_needed()
         except Exception:
             self._table = None
             self._vector_dim = vector_dim or 0  # 0 = not yet known
@@ -178,6 +204,56 @@ class LanceDBStorage:
         table.delete("id = '__schema_placeholder__'")
         return table
 
+    def _ensure_scope_index(self) -> None:
+        """Create a BTREE scalar index on the ``scope`` column if not present.
+
+        A scalar index lets LanceDB skip a full table scan when filtering by
+        scope prefix, which is the hot path for ``list_records``,
+        ``get_scope_info``, and ``list_scopes``.  The call is best-effort:
+        if the table is empty or the index already exists the exception is
+        swallowed silently.
+        """
+        if self._table is None:
+            return
+        try:
+            self._table.create_scalar_index("scope", index_type="BTREE", replace=False)
+        except Exception:  # noqa: S110
+            pass  # index already exists, table empty, or unsupported version
+
+    # ------------------------------------------------------------------
+    # Automatic background compaction
+    # ------------------------------------------------------------------
+
+    def _compact_if_needed(self) -> None:
+        """Spawn a background compaction on startup.
+
+        Called whenever an existing table is opened so that fragments
+        accumulated in previous sessions are silently merged before the
+        first query.  ``optimize()`` returns quickly when the table is
+        already compact, so the cost is negligible in the common case.
+        """
+        if self._table is None or self._compact_every <= 0:
+            return
+        self._compact_async()
+
+    def _compact_async(self) -> None:
+        """Fire-and-forget: compact the table in a daemon background thread."""
+        threading.Thread(
+            target=self._compact_safe,
+            daemon=True,
+            name="lancedb-compact",
+        ).start()
+
+    def _compact_safe(self) -> None:
+        """Run ``table.optimize()`` in a background thread, absorbing errors."""
+        try:
+            if self._table is not None:
+                self._table.optimize()
+                # Refresh the scope index so new fragments are covered.
+                self._ensure_scope_index()
+        except Exception:
+            _logger.debug("LanceDB background compaction failed", exc_info=True)
+
     def _ensure_table(self, vector_dim: int | None = None) -> lancedb.table.Table:
         """Return the table, creating it lazily if needed.
 
@@ -239,6 +315,7 @@ class LanceDBStorage:
             if r.embedding and len(r.embedding) > 0:
                 dim = len(r.embedding)
                 break
+        is_new_table = self._table is None
         with self._write_lock:
             self._ensure_table(vector_dim=dim)
             rows = [self._record_to_row(r) for r in records]
@@ -246,6 +323,13 @@ class LanceDBStorage:
                 if r["vector"] is None or len(r["vector"]) != self._vector_dim:
                     r["vector"] = [0.0] * self._vector_dim
             self._retry_write("add", rows)
+        # Create the scope index on the first save so it covers the initial dataset.
+        if is_new_table:
+            self._ensure_scope_index()
+        # Auto-compact every N saves so fragment files don't pile up.
+        self._save_count += 1
+        if self._compact_every > 0 and self._save_count % self._compact_every == 0:
+            self._compact_async()
 
     def update(self, record: MemoryRecord) -> None:
         """Update a record by ID. Preserves created_at, updates last_accessed."""
@@ -261,6 +345,10 @@ class LanceDBStorage:
     def touch_records(self, record_ids: list[str]) -> None:
         """Update last_accessed to now for the given record IDs.
 
+        Uses a single batch ``table.update()`` call instead of N
+        delete-and-re-add cycles, which is both faster and avoids
+        unnecessary write amplification.
+
         Args:
             record_ids: IDs of records to touch.
         """
@@ -268,25 +356,20 @@ class LanceDBStorage:
             return
         with self._write_lock:
             now = datetime.utcnow().isoformat()
-            for rid in record_ids:
-                safe_id = str(rid).replace("'", "''")
-                rows = (
-                    self._table.search([0.0] * self._vector_dim)
-                    .where(f"id = '{safe_id}'")
-                    .limit(1)
-                    .to_list()
-                )
-                if rows:
-                    rows[0]["last_accessed"] = now
-                    self._retry_write("delete", f"id = '{safe_id}'")
-                    self._retry_write("add", [rows[0]])
+            safe_ids = [str(rid).replace("'", "''") for rid in record_ids]
+            ids_expr = ", ".join(f"'{rid}'" for rid in safe_ids)
+            self._retry_write(
+                "update",
+                where=f"id IN ({ids_expr})",
+                values={"last_accessed": now},
+            )
 
     def get_record(self, record_id: str) -> MemoryRecord | None:
         """Return a single record by ID, or None if not found."""
         if self._table is None:
             return None
         safe_id = str(record_id).replace("'", "''")
-        rows = self._table.search([0.0] * self._vector_dim).where(f"id = '{safe_id}'").limit(1).to_list()
+        rows = self._table.search().where(f"id = '{safe_id}'").limit(1).to_list()
         if not rows:
             return None
         return self._row_to_record(rows[0])
@@ -374,13 +457,31 @@ class LanceDBStorage:
             self._retry_write("delete", where_expr)
             return before - self._table.count_rows()
 
-    def _scan_rows(self, scope_prefix: str | None = None, limit: int = _SCAN_ROWS_LIMIT) -> list[dict[str, Any]]:
-        """Scan rows optionally filtered by scope prefix."""
+    def _scan_rows(
+        self,
+        scope_prefix: str | None = None,
+        limit: int = _SCAN_ROWS_LIMIT,
+        columns: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Scan rows optionally filtered by scope prefix.
+
+        Uses a full table scan (no vector query) so the limit is applied after
+        the scope filter, not to ANN candidates before filtering.
+
+        Args:
+            scope_prefix: Optional scope path prefix to filter by.
+            limit: Maximum number of rows to return (applied after filtering).
+            columns: Optional list of column names to fetch.  Pass only the
+                columns you need for metadata operations to avoid reading the
+                heavy ``vector`` column unnecessarily.
+        """
         if self._table is None:
             return []
-        q = self._table.search([0.0] * self._vector_dim)
+        q = self._table.search()
         if scope_prefix is not None and scope_prefix.strip("/"):
             q = q.where(f"scope LIKE '{scope_prefix.rstrip('/')}%'")
+        if columns is not None:
+            q = q.select(columns)
         return q.limit(limit).to_list()
 
     def list_records(
@@ -406,7 +507,10 @@ class LanceDBStorage:
         prefix = scope if scope != "/" else ""
         if prefix and not prefix.startswith("/"):
             prefix = "/" + prefix
-        rows = self._scan_rows(prefix or None)
+        rows = self._scan_rows(
+            prefix or None,
+            columns=["scope", "categories_str", "created_at"],
+        )
         if not rows:
             return ScopeInfo(
                 path=scope or "/",
@@ -453,7 +557,7 @@ class LanceDBStorage:
     def list_scopes(self, parent: str = "/") -> list[str]:
         parent = parent.rstrip("/") or ""
         prefix = (parent + "/") if parent else "/"
-        rows = self._scan_rows(prefix if prefix != "/" else None)
+        rows = self._scan_rows(prefix if prefix != "/" else None, columns=["scope"])
         children: set[str] = set()
         for row in rows:
             sc = str(row.get("scope", ""))
@@ -465,7 +569,7 @@ class LanceDBStorage:
         return sorted(children)
 
     def list_categories(self, scope_prefix: str | None = None) -> dict[str, int]:
-        rows = self._scan_rows(scope_prefix)
+        rows = self._scan_rows(scope_prefix, columns=["categories_str"])
         counts: dict[str, int] = {}
         for row in rows:
             cat_str = row.get("categories_str") or "[]"
@@ -498,6 +602,21 @@ class LanceDBStorage:
         if prefix:
             self._table.delete(f"scope >= '{prefix}' AND scope < '{prefix}/\uFFFF'")
 
+    def optimize(self) -> None:
+        """Compact the table synchronously and refresh the scope index.
+
+        Under normal usage this is called automatically in the background
+        (every ``compact_every`` saves and on startup when the table is
+        fragmented).  Call this explicitly only when you need the compaction
+        to be complete before the next operation — for example immediately
+        after a large bulk import, before a latency-sensitive recall.
+        It is a no-op if the table does not exist.
+        """
+        if self._table is None:
+            return
+        self._table.optimize()
+        self._ensure_scope_index()
+
     async def asave(self, records: list[MemoryRecord]) -> None:
         self.save(records)
 

lib/crewai/src/crewai/memory/types.py

@@ -87,6 +87,22 @@ class MemoryMatch(BaseModel):
         description="Information the system looked for but could not find.",
     )
 
+    def format(self) -> str:
+        """Format this match as a human-readable string including metadata.
+
+        Returns:
+            A multi-line string with score, content, categories, and non-empty
+            metadata fields.
+        """
+        lines = [f"- (score={self.score:.2f}) {self.record.content}"]
+        if self.record.categories:
+            lines.append(f"  categories: {', '.join(self.record.categories)}")
+        if self.record.metadata:
+            for key, value in self.record.metadata.items():
+                if value is not None:
+                    lines.append(f"  {key}: {value}")
+        return "\n".join(lines)
+
 
 class ScopeInfo(BaseModel):
     """Information about a scope in the memory hierarchy."""
@@ -291,7 +307,7 @@ def embed_text(embedder: Any, text: str) -> list[float]:
         return []
     first = result[0]
     if hasattr(first, "tolist"):
-        return first.tolist()
+        return list(first.tolist())
     if isinstance(first, list):
         return [float(x) for x in first]
     return list(first)

lib/crewai/src/crewai/memory/unified_memory.py

@@ -6,7 +6,7 @@ from concurrent.futures import Future, ThreadPoolExecutor
 from datetime import datetime
 import threading
 import time
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.memory_events import (
@@ -21,7 +21,6 @@ from crewai.llms.base_llm import BaseLLM
 from crewai.memory.analyze import extract_memories_from_content
 from crewai.memory.recall_flow import RecallFlow
 from crewai.memory.storage.backend import StorageBackend
-from crewai.memory.storage.lancedb_storage import LanceDBStorage
 from crewai.memory.types import (
     MemoryConfig,
     MemoryMatch,
@@ -30,13 +29,20 @@ from crewai.memory.types import (
     compute_composite_score,
     embed_text,
 )
+from crewai.rag.embeddings.factory import build_embedder
+from crewai.rag.embeddings.providers.openai.types import OpenAIProviderSpec
 
 
-def _default_embedder() -> Any:
+if TYPE_CHECKING:
+    from chromadb.utils.embedding_functions.openai_embedding_function import (
+        OpenAIEmbeddingFunction,
+    )
+
+
+def _default_embedder() -> OpenAIEmbeddingFunction:
     """Build default OpenAI embedder for memory."""
-    from crewai.rag.embeddings.factory import build_embedder
-
-    return build_embedder({"provider": "openai", "config": {}})
+    spec: OpenAIProviderSpec = {"provider": "openai", "config": {}}
+    return build_embedder(spec)
 
 
 class Memory:
@@ -88,6 +94,10 @@ class Memory:
         # Queries shorter than this skip LLM analysis (saving ~1-3s).
         # Longer queries (full task descriptions) benefit from LLM distillation.
         query_analysis_threshold: int = 200,
+        # When True, all write operations (remember, remember_many) are silently
+        # skipped. Useful for sharing a read-only view of memory across agents
+        # without any of them persisting new memories.
+        read_only: bool = False,
     ) -> None:
         """Initialize Memory.
 
@@ -107,7 +117,9 @@ class Memory:
             complex_query_threshold: For complex queries, explore deeper below this confidence.
             exploration_budget: Number of LLM-driven exploration rounds during deep recall.
             query_analysis_threshold: Queries shorter than this skip LLM analysis during deep recall.
+            read_only: If True, remember() and remember_many() are silent no-ops.
         """
+        self._read_only = read_only
         self._config = MemoryConfig(
             recency_weight=recency_weight,
             semantic_weight=semantic_weight,
@@ -130,14 +142,15 @@ class Memory:
         self._llm_instance: BaseLLM | None = None if isinstance(llm, str) else llm
         self._embedder_config: Any = embedder
         self._embedder_instance: Any = (
-            embedder if (embedder is not None and not isinstance(embedder, dict)) else None
+            embedder
+            if (embedder is not None and not isinstance(embedder, dict))
+            else None
         )
 
-        # Storage is initialized eagerly (local, no API key needed).
-        if storage == "lancedb":
-            self._storage = LanceDBStorage()
-        elif isinstance(storage, str):
-            self._storage = LanceDBStorage(path=storage)
+        if isinstance(storage, str):
+            from crewai.memory.storage.lancedb_storage import LanceDBStorage
+
+            self._storage = LanceDBStorage() if storage == "lancedb" else LanceDBStorage(path=storage)
         else:
             self._storage = storage
 
@@ -160,12 +173,17 @@ class Memory:
             from crewai.llm import LLM
 
             try:
-                self._llm_instance = LLM(model=self._llm_config)
+                model_name = (
+                    self._llm_config
+                    if isinstance(self._llm_config, str)
+                    else str(self._llm_config)
+                )
+                self._llm_instance = LLM(model=model_name)
             except Exception as e:
                 raise RuntimeError(
                     f"Memory requires an LLM for analysis but initialization failed: {e}\n\n"
                     "To fix this, do one of the following:\n"
-                    '  - Set OPENAI_API_KEY for the default model (gpt-4o-mini)\n'
+                    "  - Set OPENAI_API_KEY for the default model (gpt-4o-mini)\n"
                     '  - Pass a different model: Memory(llm="anthropic/claude-3-haiku-20240307")\n'
                     '  - Pass any LLM instance: Memory(llm=LLM(model="your-model"))\n'
                     "  - To skip LLM analysis, pass all fields explicitly to remember()\n"
@@ -180,8 +198,6 @@ class Memory:
         if self._embedder_instance is None:
             try:
                 if isinstance(self._embedder_config, dict):
-                    from crewai.rag.embeddings.factory import build_embedder
-
                     self._embedder_instance = build_embedder(self._embedder_config)
                 else:
                     self._embedder_instance = _default_embedder()
@@ -317,7 +333,7 @@ class Memory:
         source: str | None = None,
         private: bool = False,
         agent_role: str | None = None,
-    ) -> MemoryRecord:
+    ) -> MemoryRecord | None:
         """Store a single item in memory (synchronous).
 
         Routes through the same serialized save pool as ``remember_many``
@@ -335,11 +351,13 @@ class Memory:
             agent_role: Optional agent role for event metadata.
 
         Returns:
-            The created MemoryRecord.
+            The created MemoryRecord, or None if this memory is read-only.
 
         Raises:
             Exception: On save failure (events emitted).
         """
+        if self._read_only:
+            return None
         _source_type = "unified_memory"
         try:
             crewai_event_bus.emit(
@@ -356,7 +374,13 @@ class Memory:
             # then immediately wait for the result.
             future = self._submit_save(
                 self._encode_batch,
-                [content], scope, categories, metadata, importance, source, private,
+                [content],
+                scope,
+                categories,
+                metadata,
+                importance,
+                source,
+                private,
             )
             records = future.result()
             record = records[0] if records else None
@@ -420,13 +444,19 @@ class Memory:
         Returns:
             Empty list (records are not available until the background save completes).
         """
-        if not contents:
+        if not contents or self._read_only:
             return []
 
         self._submit_save(
             self._background_encode_batch,
-            contents, scope, categories, metadata,
-            importance, source, private, agent_role,
+            contents,
+            scope,
+            categories,
+            metadata,
+            importance,
+            source,
+            private,
+            agent_role,
         )
         return []
 
@@ -566,14 +596,13 @@ class Memory:
                     # Privacy filter
                     if not include_private:
                         raw = [
-                            (r, s) for r, s in raw
+                            (r, s)
+                            for r, s in raw
                             if not r.private or r.source == source
                         ]
                     results = []
                     for r, s in raw:
-                        composite, reasons = compute_composite_score(
-                            r, s, self._config
-                        )
+                        composite, reasons = compute_composite_score(r, s, self._config)
                         results.append(
                             MemoryMatch(
                                 record=r,
@@ -739,7 +768,9 @@ class Memory:
             limit: Maximum number of records to return.
             offset: Number of records to skip (for pagination).
         """
-        return self._storage.list_records(scope_prefix=scope, limit=limit, offset=offset)
+        return self._storage.list_records(
+            scope_prefix=scope, limit=limit, offset=offset
+        )
 
     def info(self, path: str = "/") -> ScopeInfo:
         """Return scope info for path."""
@@ -781,7 +812,7 @@ class Memory:
         importance: float | None = None,
         source: str | None = None,
         private: bool = False,
-    ) -> MemoryRecord:
+    ) -> MemoryRecord | None:
         """Async remember: delegates to sync for now."""
         return self.remember(
             content,

lib/crewai/src/crewai/rag/embeddings/factory.py

@@ -216,6 +216,10 @@ def build_embedder_from_dict(
 def build_embedder_from_dict(spec: ONNXProviderSpec) -> ONNXMiniLM_L6_V2: ...
 
 
+@overload
+def build_embedder_from_dict(spec: dict[str, Any]) -> EmbeddingFunction[Any]: ...
+
+
 def build_embedder_from_dict(spec):  # type: ignore[no-untyped-def]
     """Build an embedding function instance from a dictionary specification.
 
@@ -341,6 +345,10 @@ def build_embedder(spec: Text2VecProviderSpec) -> Text2VecEmbeddingFunction: ...
 def build_embedder(spec: ONNXProviderSpec) -> ONNXMiniLM_L6_V2: ...
 
 
+@overload
+def build_embedder(spec: dict[str, Any]) -> EmbeddingFunction[Any]: ...
+
+
 def build_embedder(spec):  # type: ignore[no-untyped-def]
     """Build an embedding function from either a provider spec or a provider instance.
 

lib/crewai/src/crewai/task.py

@@ -586,16 +586,29 @@ class Task(BaseModel):
 
             self._post_agent_execution(agent)
 
-            if not self._guardrails and not self._guardrail:
+            if isinstance(result, BaseModel):
+                raw = result.model_dump_json()
+                if self.output_pydantic:
+                    pydantic_output = result
+                    json_output = None
+                elif self.output_json:
+                    pydantic_output = None
+                    json_output = result.model_dump()
+                else:
+                    pydantic_output = None
+                    json_output = None
+            elif not self._guardrails and not self._guardrail:
+                raw = result
                 pydantic_output, json_output = self._export_output(result)
             else:
+                raw = result
                 pydantic_output, json_output = None, None
 
             task_output = TaskOutput(
                 name=self.name or self.description,
                 description=self.description,
                 expected_output=self.expected_output,
-                raw=result,
+                raw=raw,
                 pydantic=pydantic_output,
                 json_dict=json_output,
                 agent=agent.role,
@@ -687,16 +700,29 @@ class Task(BaseModel):
 
             self._post_agent_execution(agent)
 
-            if not self._guardrails and not self._guardrail:
+            if isinstance(result, BaseModel):
+                raw = result.model_dump_json()
+                if self.output_pydantic:
+                    pydantic_output = result
+                    json_output = None
+                elif self.output_json:
+                    pydantic_output = None
+                    json_output = result.model_dump()
+                else:
+                    pydantic_output = None
+                    json_output = None
+            elif not self._guardrails and not self._guardrail:
+                raw = result
                 pydantic_output, json_output = self._export_output(result)
             else:
+                raw = result
                 pydantic_output, json_output = None, None
 
             task_output = TaskOutput(
                 name=self.name or self.description,
                 description=self.description,
                 expected_output=self.expected_output,
-                raw=result,
+                raw=raw,
                 pydantic=pydantic_output,
                 json_dict=json_output,
                 agent=agent.role,

lib/crewai/src/crewai/tools/base_tool.py

@@ -23,7 +23,7 @@ from pydantic import (
 )
 from typing_extensions import TypeIs
 
-from crewai.tools.structured_tool import CrewStructuredTool
+from crewai.tools.structured_tool import CrewStructuredTool, build_schema_hint
 from crewai.utilities.printer import Printer
 from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.string_utils import sanitize_tool_name
@@ -150,14 +150,39 @@ class BaseTool(BaseModel, ABC):
 
         super().model_post_init(__context)
 
+    def _validate_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Validate keyword arguments against args_schema if present.
+
+        Args:
+            kwargs: The keyword arguments to validate.
+
+        Returns:
+            Validated (and possibly coerced) keyword arguments.
+
+        Raises:
+            ValueError: If validation against args_schema fails.
+        """
+        if self.args_schema is not None and self.args_schema.model_fields:
+            try:
+                validated = self.args_schema.model_validate(kwargs)
+                return validated.model_dump()
+            except Exception as e:
+                hint = build_schema_hint(self.args_schema)
+                raise ValueError(
+                    f"Tool '{self.name}' arguments validation failed: {e}{hint}"
+                ) from e
+        return kwargs
+
     def run(
         self,
         *args: Any,
         **kwargs: Any,
     ) -> Any:
+        if not args:
+            kwargs = self._validate_kwargs(kwargs)
+
         result = self._run(*args, **kwargs)
 
-        # If _run is async, we safely run it
         if asyncio.iscoroutine(result):
             result = asyncio.run(result)
 
@@ -179,6 +204,8 @@ class BaseTool(BaseModel, ABC):
         Returns:
             The result of the tool execution.
         """
+        if not args:
+            kwargs = self._validate_kwargs(kwargs)
         result = await self._arun(*args, **kwargs)
         self.current_usage_count += 1
         return result
@@ -331,6 +358,9 @@ class Tool(BaseTool, Generic[P, R]):
         Returns:
             The result of the tool execution.
         """
+        if not args:
+            kwargs = self._validate_kwargs(kwargs)  # type: ignore[assignment]
+
         result = self.func(*args, **kwargs)
 
         if asyncio.iscoroutine(result):
@@ -361,6 +391,8 @@ class Tool(BaseTool, Generic[P, R]):
         Returns:
             The result of the tool execution.
         """
+        if not args:
+            kwargs = self._validate_kwargs(kwargs)  # type: ignore[assignment]
         result = await self._arun(*args, **kwargs)
         self.current_usage_count += 1
         return result

lib/crewai/src/crewai/tools/mcp_native_tool.py

@@ -27,14 +27,16 @@ class MCPNativeTool(BaseTool):
         tool_name: str,
         tool_schema: dict[str, Any],
         server_name: str,
+        original_tool_name: str | None = None,
     ) -> None:
         """Initialize native MCP tool.
 
         Args:
             mcp_client: MCPClient instance with active session.
-            tool_name: Original name of the tool on the MCP server.
+            tool_name: Name of the tool (may be prefixed).
             tool_schema: Schema information for the tool.
             server_name: Name of the MCP server for prefixing.
+            original_tool_name: Original name of the tool on the MCP server.
         """
         # Create tool name with server prefix to avoid conflicts
         prefixed_name = f"{server_name}_{tool_name}"
@@ -57,7 +59,7 @@ class MCPNativeTool(BaseTool):
 
         # Set instance attributes after super().__init__
         self._mcp_client = mcp_client
-        self._original_tool_name = tool_name
+        self._original_tool_name = original_tool_name or tool_name
         self._server_name = server_name
         # self._logger = logging.getLogger(__name__)
 

lib/crewai/src/crewai/tools/memory_tools.py

@@ -20,14 +20,6 @@ class RecallMemorySchema(BaseModel):
             "or multiple items to search for several things at once."
         ),
     )
-    scope: str | None = Field(
-        default=None,
-        description="Optional scope to narrow the search (e.g. /project/alpha)",
-    )
-    depth: str = Field(
-        default="shallow",
-        description="'shallow' for fast vector search, 'deep' for LLM-analyzed retrieval",
-    )
 
 
 class RecallMemoryTool(BaseTool):
@@ -41,32 +33,27 @@ class RecallMemoryTool(BaseTool):
     def _run(
         self,
         queries: list[str] | str,
-        scope: str | None = None,
-        depth: str = "shallow",
         **kwargs: Any,
     ) -> str:
         """Search memory for relevant information.
 
         Args:
             queries: One or more search queries (string or list of strings).
-            scope: Optional scope prefix to narrow the search.
-            depth: "shallow" for fast vector search, "deep" for LLM-analyzed retrieval.
 
         Returns:
             Formatted string of matching memories, or a message if none found.
         """
         if isinstance(queries, str):
             queries = [queries]
-        actual_depth = depth if depth in ("shallow", "deep") else "shallow"
 
         all_lines: list[str] = []
         seen_ids: set[str] = set()
         for query in queries:
-            matches = self.memory.recall(query, scope=scope, limit=5, depth=actual_depth)
+            matches = self.memory.recall(query)
             for m in matches:
                 if m.record.id not in seen_ids:
                     seen_ids.add(m.record.id)
-                    all_lines.append(f"- (score={m.score:.2f}) {m.record.content}")
+                    all_lines.append(m.format())
 
         if not all_lines:
             return "No relevant memories found."
@@ -117,20 +104,28 @@ class RememberTool(BaseTool):
 def create_memory_tools(memory: Any) -> list[BaseTool]:
     """Create Recall and Remember tools for the given memory instance.
 
+    When memory is read-only (``_read_only=True``), only the RecallMemoryTool
+    is returned — the RememberTool is omitted so agents are never offered a
+    save capability they cannot use.
+
     Args:
         memory: A Memory, MemoryScope, or MemorySlice instance.
 
     Returns:
-        List containing a RecallMemoryTool and a RememberTool.
+        List containing a RecallMemoryTool and, if not read-only, a RememberTool.
     """
     i18n = get_i18n()
-    return [
+    tools: list[BaseTool] = [
         RecallMemoryTool(
             memory=memory,
             description=i18n.tools("recall_memory"),
         ),
-        RememberTool(
-            memory=memory,
-            description=i18n.tools("save_to_memory"),
-        ),
     ]
+    if not getattr(memory, "_read_only", False):
+        tools.append(
+            RememberTool(
+                memory=memory,
+                description=i18n.tools("save_to_memory"),
+            )
+        )
+    return tools

lib/crewai/src/crewai/tools/structured_tool.py

@@ -17,6 +17,27 @@ if TYPE_CHECKING:
     from crewai.tools.base_tool import BaseTool
 
 
+def build_schema_hint(args_schema: type[BaseModel]) -> str:
+    """Build a human-readable hint from a Pydantic model's JSON schema.
+
+    Args:
+        args_schema: The Pydantic model class to extract schema from.
+
+    Returns:
+        A formatted string with expected arguments and required fields,
+        or empty string if schema extraction fails.
+    """
+    try:
+        schema = args_schema.model_json_schema()
+        return (
+            f"\nExpected arguments: "
+            f"{json.dumps(schema.get('properties', {}))}"
+            f"\nRequired: {json.dumps(schema.get('required', []))}"
+        )
+    except Exception:
+        return ""
+
+
 class ToolUsageLimitExceededError(Exception):
     """Exception raised when a tool has reached its maximum usage limit."""
 
@@ -208,7 +229,8 @@ class CrewStructuredTool:
             validated_args = self.args_schema.model_validate(raw_args)
             return validated_args.model_dump()
         except Exception as e:
-            raise ValueError(f"Arguments validation failed: {e}") from e
+            hint = build_schema_hint(self.args_schema)
+            raise ValueError(f"Arguments validation failed: {e}{hint}") from e
 
     async def ainvoke(
         self,

lib/crewai/src/crewai/translations/en.json

@@ -74,28 +74,9 @@
     "consolidation_user": "New content to consider storing:\n{new_content}\n\nExisting similar memories:\n{records_summary}\n\nReturn the consolidation plan as structured output."
   },
   "reasoning": {
-    "initial_plan": "You are {role}. Create a focused execution plan using only the essential steps needed.",
-    "refine_plan": "You are {role}. Refine your plan to address the specific gap while keeping it minimal.",
-    "create_plan_prompt": "You are {role}.\n\nTask: {description}\n\nExpected output: {expected_output}\n\nAvailable tools: {tools}\n\nCreate a focused plan with ONLY the essential steps needed. Most tasks require just 2-5 steps. Do NOT pad with unnecessary steps like \"review\", \"verify\", \"document\", or \"finalize\" unless explicitly required.\n\nFor each step, specify the action and which tool to use (if any).\n\nConclude with:\n- \"READY: I am ready to execute the task.\"\n- \"NOT READY: I need to refine my plan because [specific reason].\"",
-    "refine_plan_prompt": "Your plan:\n{current_plan}\n\nYou indicated you're not ready. Address the specific gap while keeping the plan minimal.\n\nConclude with READY or NOT READY."
-  },
-  "planning": {
-    "system_prompt": "You are a strategic planning assistant. Create concrete, executable plans where every step produces a verifiable result.",
-    "create_plan_prompt": "Create an execution plan for the following task:\n\n## Task\n{description}\n\n## Expected Output\n{expected_output}\n\n## Available Tools\n{tools}\n\n## Planning Principles\nFocus on CONCRETE, EXECUTABLE steps. Each step must clearly state WHAT ACTION to take and HOW to verify it succeeded. The number of steps should match the task complexity. Hard limit: {max_steps} steps.\n\n## Rules:\n- Each step must have a clear DONE criterion\n- Do NOT group unrelated actions: if steps can fail independently, keep them separate\n- NO standalone \"thinking\" or \"planning\" steps — act, don't just observe\n- The last step must produce the required output\n\nAfter your plan, state READY or NOT READY.",
-    "refine_plan_prompt": "Your previous plan:\n{current_plan}\n\nYou indicated you weren't ready. Refine your plan to address the specific gap.\n\nKeep the plan minimal - only add steps that directly address the issue.\n\nConclude with READY or NOT READY as before.",
-    "observation_system_prompt": "You are a Planning Agent observing execution progress. After each step completes, you analyze what happened and decide whether the remaining plan is still valid.\n\nReason step-by-step about:\n1. Did this step produce a concrete, verifiable result? (file created, command succeeded, service running, etc.) — or did it only explore without acting?\n2. What new information was learned from this step's result?\n3. Whether the remaining steps still make sense given this new information\n4. What refinements, if any, are needed for upcoming steps\n5. Whether the overall goal has already been achieved\n\nCritical: mark `step_completed_successfully=false` if:\n- The step result is only exploratory (ls, pwd, cat) without producing the required artifact or action\n- A command returned a non-zero exit code and the error was not recovered\n- The step description required creating/building/starting something and the result shows it was not done\n\nBe conservative about triggering full replans — only do so when the remaining plan is fundamentally wrong, not just suboptimal.\n\nIMPORTANT: Set step_completed_successfully=false if:\n- The step's stated goal was NOT achieved (even if other things were done)\n- The first meaningful action returned an error (file not found, command not found, etc.)\n- The result is exploration/discovery output rather than the concrete action the step required\n- The step ran out of attempts without producing the required output\nSet needs_full_replan=true if the current plan's remaining steps reference paths or state that don't exist yet and need to be created first.",
-    "observation_user_prompt": "## Original task\n{task_description}\n\n## Expected output\n{task_goal}\n{completed_summary}\n\n## Just completed step {step_number}\nDescription: {step_description}\nResult: {step_result}\n{remaining_summary}\n\nAnalyze this step's result and provide your observation.",
-    "step_executor_system_prompt": "You are {role}. {backstory}\n\nYour goal: {goal}\n\nYou are executing ONE specific step in a larger plan. Your ONLY job is to fully complete this step — not to plan ahead.\n\nKey rules:\n- **ACT FIRST.** Execute the primary action of this step immediately. Do NOT read or explore files before attempting the main action unless exploration IS the step's goal.\n- If the step says 'run X', run X NOW. If it says 'write file Y', write Y NOW.\n- If the step requires producing an output file (e.g. /app/move.txt, report.jsonl, summary.csv), you MUST write that file using a tool call — do NOT just state the answer in text.\n- You may use tools MULTIPLE TIMES. After each tool use, check the result. If it failed, try a different approach.\n- Only output your Final Answer AFTER the concrete outcome is verified (file written, build succeeded, command exited 0).\n- If a command is not found or a path does not exist, fix it (different PATH, install missing deps, use absolute paths).\n- Do NOT spend more than 3 tool calls on exploration/analysis before attempting the primary action.{tools_section}",
-    "step_executor_tools_section": "\n\nAvailable tools: {tool_names}\n\nYou may call tools multiple times in sequence. Use this format for EACH tool call:\nThought: <what you observed and what you will try next>\nAction: <tool_name>\nAction Input: <input>\n\nAfter observing each result, decide: is the step complete? If yes:\nThought: The step is done because <evidence>\nFinal Answer: <concise summary of what was accomplished and the key result>",
-    "step_executor_user_prompt": "## Current Step\n{step_description}",
-    "step_executor_suggested_tool": "\nSuggested tool: {tool_to_use}",
-    "step_executor_context_header": "\n## Context from previous steps:",
-    "step_executor_context_entry": "Step {step_number} result: {result}",
-    "step_executor_complete_step": "\n**Execute the primary action of this step NOW.** If the step requires writing a file, write it. If it requires running a command, run it. Verify the outcome with a follow-up tool call, then give your Final Answer. Your Final Answer must confirm what was DONE (file created at path X, command succeeded), not just what should be done.",
-    "todo_system_prompt": "You are {role}. Your goal: {goal}\n\nYou are executing a specific step in a multi-step plan. Focus only on completing the current step. Use the suggested tool if one is provided. Be concise and provide clear results that can be used by subsequent steps.",
-    "synthesis_system_prompt": "You are {role}. You have completed a multi-step task. Synthesize the results from all steps into a single, coherent final response that directly addresses the original task. Do NOT list step numbers or say 'Step 1 result'. Produce a clean, polished answer as if you did it all at once.",
-    "synthesis_user_prompt": "## Original Task\n{task_description}\n\n## Results from each step\n{combined_steps}\n\nSynthesize these results into a single, coherent final answer.",
-    "replan_enhancement_prompt": "\n\nIMPORTANT: Previous execution attempt did not fully succeed. Please create a revised plan that accounts for the following context from the previous attempt:\n\n{previous_context}\n\nConsider:\n1. What steps succeeded and can be built upon\n2. What steps failed and why they might have failed\n3. Alternative approaches that might work better\n4. Whether dependencies need to be restructured",
-    "step_executor_task_context": "## Task Context\nThe following is the full task you are helping complete. Keep this in mind — especially any required output files, exact filenames, and expected formats.\n\n{task_context}\n\n---\n"
+    "initial_plan": "You are {role}, a professional with the following background: {backstory}\n\nYour primary goal is: {goal}\n\nAs {role}, you are creating a strategic plan for a task that requires your expertise and unique perspective.",
+    "refine_plan": "You are {role}, a professional with the following background: {backstory}\n\nYour primary goal is: {goal}\n\nAs {role}, you are refining a strategic plan for a task that requires your expertise and unique perspective.",
+    "create_plan_prompt": "You are {role} with this background: {backstory}\n\nYour primary goal is: {goal}\n\nYou have been assigned the following task:\n{description}\n\nExpected output:\n{expected_output}\n\nAvailable tools: {tools}\n\nBefore executing this task, create a detailed plan that leverages your expertise as {role} and outlines:\n1. Your understanding of the task from your professional perspective\n2. The key steps you'll take to complete it, drawing on your background and skills\n3. How you'll approach any challenges that might arise, considering your expertise\n4. How you'll strategically use the available tools based on your experience, exactly what tools to use and how to use them\n5. The expected outcome and how it aligns with your goal\n\nAfter creating your plan, assess whether you feel ready to execute the task or if you could do better.\nConclude with one of these statements:\n- \"READY: I am ready to execute the task.\"\n- \"NOT READY: I need to refine my plan because [specific reason].\"",
+    "refine_plan_prompt": "You are {role} with this background: {backstory}\n\nYour primary goal is: {goal}\n\nYou created the following plan for this task:\n{current_plan}\n\nHowever, you indicated that you're not ready to execute the task yet.\n\nPlease refine your plan further, drawing on your expertise as {role} to address any gaps or uncertainties. As you refine your plan, be specific about which available tools you will use, how you will use them, and why they are the best choices for each step. Clearly outline your tool usage strategy as part of your improved plan.\n\nAfter refining your plan, assess whether you feel ready to execute the task.\nConclude with one of these statements:\n- \"READY: I am ready to execute the task.\"\n- \"NOT READY: I need to refine my plan further because [specific reason].\""
   }
-}
+}

lib/crewai/src/crewai/utilities/agent_utils.py

@@ -3,8 +3,6 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Callable, Sequence
 import concurrent.futures
-from dataclasses import dataclass, field
-from datetime import datetime
 import inspect
 import json
 import re
@@ -41,7 +39,6 @@ from crewai.utilities.types import LLMMessage
 if TYPE_CHECKING:
     from crewai.agent import Agent
     from crewai.agents.crew_agent_executor import CrewAgentExecutor
-    from crewai.agents.tools_handler import ToolsHandler
     from crewai.experimental.agent_executor import AgentExecutor
     from crewai.lite_agent import LiteAgent
     from crewai.llm import LLM
@@ -142,7 +139,11 @@ def render_text_description_and_args(
 
 def convert_tools_to_openai_schema(
     tools: Sequence[BaseTool | CrewStructuredTool],
-) -> tuple[list[dict[str, Any]], dict[str, Callable[..., Any]]]:
+) -> tuple[
+    list[dict[str, Any]],
+    dict[str, Callable[..., Any]],
+    dict[str, BaseTool | CrewStructuredTool],
+]:
     """Convert CrewAI tools to OpenAI function calling format.
 
     This function converts CrewAI BaseTool and CrewStructuredTool objects
@@ -155,23 +156,21 @@ def convert_tools_to_openai_schema(
     Returns:
         Tuple containing:
         - List of OpenAI-format tool schema dictionaries
-        - Dict mapping tool names to their callable run() methods
-
-    Example:
-        >>> tools = [CalculatorTool(), SearchTool()]
-        >>> schemas, functions = convert_tools_to_openai_schema(tools)
-        >>> # schemas can be passed to llm.call(tools=schemas)
-        >>> # functions can be passed to llm.call(available_functions=functions)
+        - Dict mapping sanitized tool names to their callable run() methods
+        - Dict mapping sanitized tool names to their original tool objects
     """
     openai_tools: list[dict[str, Any]] = []
     available_functions: dict[str, Callable[..., Any]] = {}
+    tool_name_mapping: dict[str, BaseTool | CrewStructuredTool] = {}
 
     for tool in tools:
         # Get the JSON schema for tool parameters
         parameters: dict[str, Any] = {}
         if hasattr(tool, "args_schema") and tool.args_schema is not None:
             try:
-                schema_output = generate_model_description(tool.args_schema)
+                schema_output = generate_model_description(
+                    tool.args_schema, strip_null_types=False
+                )
                 parameters = schema_output.get("json_schema", {}).get("schema", {})
                 # Remove title and description from schema root as they're redundant
                 parameters.pop("title", None)
@@ -187,6 +186,14 @@ def convert_tools_to_openai_schema(
 
         sanitized_name = sanitize_tool_name(tool.name)
 
+        if sanitized_name in available_functions:
+            counter = 2
+            candidate = sanitize_tool_name(f"{sanitized_name}_{counter}")
+            while candidate in available_functions:
+                counter += 1
+                candidate = sanitize_tool_name(f"{sanitized_name}_{counter}")
+            sanitized_name = candidate
+
         schema: dict[str, Any] = {
             "type": "function",
             "function": {
@@ -198,8 +205,9 @@ def convert_tools_to_openai_schema(
         }
         openai_tools.append(schema)
         available_functions[sanitized_name] = tool.run  # type: ignore[union-attr]
+        tool_name_mapping[sanitized_name] = tool
 
-    return openai_tools, available_functions
+    return openai_tools, available_functions, tool_name_mapping
 
 
 def has_reached_max_iterations(iterations: int, max_iterations: int) -> bool:
@@ -327,66 +335,6 @@ def enforce_rpm_limit(
         request_within_rpm_limit()
 
 
-def _prepare_llm_call(
-    executor_context: CrewAgentExecutor | AgentExecutor | LiteAgent | None,
-    messages: list[LLMMessage],
-    printer: Printer,
-    verbose: bool = True,
-) -> list[LLMMessage]:
-    """Shared pre-call logic: run before hooks and resolve messages.
-
-    Args:
-        executor_context: Optional executor context for hook invocation.
-        messages: The messages to send to the LLM.
-        printer: Printer instance for output.
-        verbose: Whether to print output.
-
-    Returns:
-        The resolved messages list (may come from executor_context).
-
-    Raises:
-        ValueError: If a before hook blocks the call.
-    """
-    if executor_context is not None:
-        if not _setup_before_llm_call_hooks(executor_context, printer, verbose=verbose):
-            raise ValueError("LLM call blocked by before_llm_call hook")
-        messages = executor_context.messages
-    return messages
-
-
-def _validate_and_finalize_llm_response(
-    answer: Any,
-    executor_context: CrewAgentExecutor | AgentExecutor | LiteAgent | None,
-    printer: Printer,
-    verbose: bool = True,
-) -> str | BaseModel | Any:
-    """Shared post-call logic: validate response and run after hooks.
-
-    Args:
-        answer: The raw LLM response.
-        executor_context: Optional executor context for hook invocation.
-        printer: Printer instance for output.
-        verbose: Whether to print output.
-
-    Returns:
-        The potentially modified response.
-
-    Raises:
-        ValueError: If the response is None or empty.
-    """
-    if not answer:
-        if verbose:
-            printer.print(
-                content="Received None or empty response from LLM call.",
-                color="red",
-            )
-        raise ValueError("Invalid response from LLM call - None or empty.")
-
-    return _setup_after_llm_call_hooks(
-        executor_context, answer, printer, verbose=verbose
-    )
-
-
 def get_llm_response(
     llm: LLM | BaseLLM,
     messages: list[LLMMessage],
@@ -423,7 +371,11 @@ def get_llm_response(
         Exception: If an error occurs.
         ValueError: If the response is None or empty.
     """
-    messages = _prepare_llm_call(executor_context, messages, printer, verbose=verbose)
+
+    if executor_context is not None:
+        if not _setup_before_llm_call_hooks(executor_context, printer, verbose=verbose):
+            raise ValueError("LLM call blocked by before_llm_call hook")
+        messages = executor_context.messages
 
     try:
         answer = llm.call(
@@ -437,9 +389,16 @@ def get_llm_response(
         )
     except Exception as e:
         raise e
+    if not answer:
+        if verbose:
+            printer.print(
+                content="Received None or empty response from LLM call.",
+                color="red",
+            )
+        raise ValueError("Invalid response from LLM call - None or empty.")
 
-    return _validate_and_finalize_llm_response(
-        answer, executor_context, printer, verbose=verbose
+    return _setup_after_llm_call_hooks(
+        executor_context, answer, printer, verbose=verbose
     )
 
 
@@ -469,7 +428,6 @@ async def aget_llm_response(
         from_agent: Optional agent context for the LLM call.
         response_model: Optional Pydantic model for structured outputs.
         executor_context: Optional executor context for hook invocation.
-        verbose: Whether to print output.
 
     Returns:
         The response from the LLM as a string, Pydantic model (when response_model is provided),
@@ -479,7 +437,10 @@ async def aget_llm_response(
         Exception: If an error occurs.
         ValueError: If the response is None or empty.
     """
-    messages = _prepare_llm_call(executor_context, messages, printer, verbose=verbose)
+    if executor_context is not None:
+        if not _setup_before_llm_call_hooks(executor_context, printer, verbose=verbose):
+            raise ValueError("LLM call blocked by before_llm_call hook")
+        messages = executor_context.messages
 
     try:
         answer = await llm.acall(
@@ -493,9 +454,16 @@ async def aget_llm_response(
         )
     except Exception as e:
         raise e
+    if not answer:
+        if verbose:
+            printer.print(
+                content="Received None or empty response from LLM call.",
+                color="red",
+            )
+        raise ValueError("Invalid response from LLM call - None or empty.")
 
-    return _validate_and_finalize_llm_response(
-        answer, executor_context, printer, verbose=verbose
+    return _setup_after_llm_call_hooks(
+        executor_context, answer, printer, verbose=verbose
     )
 
 
@@ -1189,380 +1157,34 @@ def extract_tool_call_info(
     return None
 
 
-def is_tool_call_list(response: list[Any]) -> bool:
-    """Check if a response from the LLM is a list of tool calls.
-
-    Supports OpenAI, Anthropic, Bedrock, and Gemini formats.
-
-    Args:
-        response: The response to check.
+def parse_tool_call_args(
+    func_args: dict[str, Any] | str,
+    func_name: str,
+    call_id: str,
+    original_tool: Any = None,
+) -> tuple[dict[str, Any], None] | tuple[None, dict[str, Any]]:
+    """Parse tool call arguments from a JSON string or dict.
 
     Returns:
-        True if the response appears to be a list of tool calls.
+        ``(args_dict, None)`` on success, or ``(None, error_result)`` on
+        JSON parse failure where ``error_result`` is a ready-to-return dict
+        with the same shape as ``_execute_single_native_tool_call`` return values.
     """
-    if not response:
-        return False
-    first_item = response[0]
-    # OpenAI-style
-    if hasattr(first_item, "function") or (
-        isinstance(first_item, dict) and "function" in first_item
-    ):
-        return True
-    # Anthropic-style (ToolUseBlock)
-    if hasattr(first_item, "type") and getattr(first_item, "type", None) == "tool_use":
-        return True
-    if hasattr(first_item, "name") and hasattr(first_item, "input"):
-        return True
-    # Bedrock-style
-    if isinstance(first_item, dict) and "name" in first_item and "input" in first_item:
-        return True
-    # Gemini-style
-    if hasattr(first_item, "function_call") and first_item.function_call:
-        return True
-    return False
-
-
-def check_native_tool_support(llm: Any, original_tools: list[BaseTool] | None) -> bool:
-    """Check if the LLM supports native function calling and tools are available.
-
-    Args:
-        llm: The LLM instance.
-        original_tools: Original BaseTool instances.
-
-    Returns:
-        True if native function calling is supported and tools exist.
-    """
-    return (
-        hasattr(llm, "supports_function_calling")
-        and callable(getattr(llm, "supports_function_calling", None))
-        and llm.supports_function_calling()
-        and bool(original_tools)
-    )
-
-
-def setup_native_tools(
-    original_tools: list[BaseTool],
-) -> tuple[list[dict[str, Any]], dict[str, Callable[..., Any]]]:
-    """Convert tools to OpenAI schema format for native function calling.
-
-    Args:
-        original_tools: Original BaseTool instances.
-
-    Returns:
-        Tuple of (openai_tools_schema, available_functions_dict).
-    """
-    return convert_tools_to_openai_schema(original_tools)
-
-
-def build_tool_calls_assistant_message(
-    tool_calls: list[Any],
-) -> tuple[LLMMessage | None, list[dict[str, Any]]]:
-    """Build an assistant message containing tool call reports.
-
-    Extracts info from each tool call, builds the standard assistant message
-    format, and preserves raw Gemini parts when applicable.
-
-    Args:
-        tool_calls: Raw tool call objects from the LLM response.
-
-    Returns:
-        Tuple of (assistant_message, tool_calls_to_report).
-        assistant_message is None if no valid tool calls found.
-    """
-    tool_calls_to_report: list[dict[str, Any]] = []
-    for tool_call in tool_calls:
-        info = extract_tool_call_info(tool_call)
-        if not info:
-            continue
-        call_id, func_name, func_args = info
-        tool_calls_to_report.append(
-            {
-                "id": call_id,
-                "type": "function",
-                "function": {
-                    "name": func_name,
-                    "arguments": func_args
-                    if isinstance(func_args, str)
-                    else json.dumps(func_args),
-                },
-            }
-        )
-
-    if not tool_calls_to_report:
-        return None, []
-
-    assistant_message: LLMMessage = {
-        "role": "assistant",
-        "content": None,
-        "tool_calls": tool_calls_to_report,
-    }
-    # Preserve raw parts for Gemini compatibility
-    if all(type(tc).__qualname__ == "Part" for tc in tool_calls):
-        assistant_message["raw_tool_call_parts"] = list(tool_calls)
-
-    return assistant_message, tool_calls_to_report
-
-
-@dataclass
-class NativeToolCallResult:
-    """Result from executing a single native tool call."""
-
-    call_id: str
-    func_name: str
-    result: str
-    from_cache: bool = False
-    result_as_answer: bool = False
-    tool_message: LLMMessage = field(default_factory=dict)  # type: ignore[assignment]
-
-
-def execute_single_native_tool_call(
-    tool_call: Any,
-    *,
-    available_functions: dict[str, Callable[..., Any]],
-    original_tools: list[BaseTool],
-    structured_tools: list[CrewStructuredTool] | None,
-    tools_handler: ToolsHandler | None,
-    agent: Agent | None,
-    task: Task | None,
-    crew: Any | None,
-    event_source: Any,
-    printer: Printer | None = None,
-    verbose: bool = False,
-) -> NativeToolCallResult:
-    """Execute a single native tool call with full lifecycle management.
-
-    Handles: arg parsing, tool lookup, max-usage check, cache read/write,
-    before/after hooks, event emission, and result_as_answer detection.
-
-    Args:
-        tool_call: Raw tool call object from the LLM.
-        available_functions: Map of sanitized tool name -> callable.
-        original_tools: Original BaseTool list (for cache_function, result_as_answer).
-        structured_tools: Structured tools list (for hook context).
-        tools_handler: Optional handler with cache.
-        agent: The agent instance.
-        task: The current task.
-        crew: The crew instance.
-        event_source: The object to use as event emitter source.
-        printer: Optional printer for verbose logging.
-        verbose: Whether to print verbose output.
-
-    Returns:
-        NativeToolCallResult with all execution details.
-    """
-    from crewai.events.event_bus import crewai_event_bus
-    from crewai.events.types.tool_usage_events import (
-        ToolUsageErrorEvent,
-        ToolUsageFinishedEvent,
-        ToolUsageStartedEvent,
-    )
-    from crewai.hooks.tool_hooks import (
-        ToolCallHookContext,
-        get_after_tool_call_hooks,
-        get_before_tool_call_hooks,
-    )
-
-    info = extract_tool_call_info(tool_call)
-    if not info:
-        return NativeToolCallResult(
-            call_id="", func_name="", result="Unrecognized tool call format"
-        )
-
-    call_id, func_name, func_args = info
-
-    # Parse arguments
     if isinstance(func_args, str):
         try:
-            args_dict = json.loads(func_args)
-        except json.JSONDecodeError:
-            args_dict = {}
-    else:
-        args_dict = func_args
-
-    agent_key = getattr(agent, "key", "unknown") if agent else "unknown"
-
-    # Find original tool for cache_function and result_as_answer
-    original_tool: BaseTool | None = None
-    for tool in original_tools:
-        if sanitize_tool_name(tool.name) == func_name:
-            original_tool = tool
-            break
-
-    # Check max usage count
-    max_usage_reached = False
-    if (
-        original_tool
-        and original_tool.max_usage_count is not None
-        and original_tool.current_usage_count >= original_tool.max_usage_count
-    ):
-        max_usage_reached = True
-
-    # Check cache
-    from_cache = False
-    input_str = json.dumps(args_dict) if args_dict else ""
-    result = "Tool not found"
-
-    if tools_handler and tools_handler.cache:
-        cached_result = tools_handler.cache.read(tool=func_name, input=input_str)
-        if cached_result is not None:
-            result = (
-                str(cached_result)
-                if not isinstance(cached_result, str)
-                else cached_result
-            )
-            from_cache = True
-
-    # Emit tool started event
-    started_at = datetime.now()
-    crewai_event_bus.emit(
-        event_source,
-        event=ToolUsageStartedEvent(
-            tool_name=func_name,
-            tool_args=args_dict,
-            from_agent=agent,
-            from_task=task,
-            agent_key=agent_key,
-        ),
-    )
-
-    track_delegation_if_needed(func_name, args_dict, task)
-
-    # Find structured tool for hooks
-    structured_tool: CrewStructuredTool | None = None
-    for structured in structured_tools or []:
-        if sanitize_tool_name(structured.name) == func_name:
-            structured_tool = structured
-            break
-
-    # Before hooks
-    hook_blocked = False
-    before_hook_context = ToolCallHookContext(
-        tool_name=func_name,
-        tool_input=args_dict,
-        tool=structured_tool,  # type: ignore[arg-type]
-        agent=agent,
-        task=task,
-        crew=crew,
-    )
-    try:
-        for hook in get_before_tool_call_hooks():
-            if hook(before_hook_context) is False:
-                hook_blocked = True
-                break
-    except Exception:  # noqa: S110
-        pass
-
-    error_event_emitted = False
-    if hook_blocked:
-        result = f"Tool execution blocked by hook. Tool: {func_name}"
-    elif not from_cache and not max_usage_reached:
-        if func_name in available_functions:
-            try:
-                tool_func = available_functions[func_name]
-                raw_result = tool_func(**args_dict)
-
-                # Cache result
-                if tools_handler and tools_handler.cache:
-                    should_cache = True
-                    if original_tool:
-                        should_cache = original_tool.cache_function(
-                            args_dict, raw_result
-                        )
-                    if should_cache:
-                        tools_handler.cache.add(
-                            tool=func_name, input=input_str, output=raw_result
-                        )
-
-                result = (
-                    str(raw_result) if not isinstance(raw_result, str) else raw_result
-                )
-            except Exception as e:
-                result = f"Error executing tool: {e}"
-                if task:
-                    task.increment_tools_errors()
-                crewai_event_bus.emit(
-                    event_source,
-                    event=ToolUsageErrorEvent(
-                        tool_name=func_name,
-                        tool_args=args_dict,
-                        from_agent=agent,
-                        from_task=task,
-                        agent_key=agent_key,
-                        error=e,
-                    ),
-                )
-                error_event_emitted = True
-    elif max_usage_reached and original_tool:
-        result = (
-            f"Tool '{func_name}' has reached its usage limit of "
-            f"{original_tool.max_usage_count} times and cannot be used anymore."
-        )
-
-    # After hooks
-    after_hook_context = ToolCallHookContext(
-        tool_name=func_name,
-        tool_input=args_dict,
-        tool=structured_tool,  # type: ignore[arg-type]
-        agent=agent,
-        task=task,
-        crew=crew,
-        tool_result=result,
-    )
-    try:
-        for after_hook in get_after_tool_call_hooks():
-            hook_result = after_hook(after_hook_context)
-            if hook_result is not None:
-                result = hook_result
-                after_hook_context.tool_result = result
-    except Exception:  # noqa: S110
-        pass
-
-    # Emit tool finished event (only if error event wasn't already emitted)
-    if not error_event_emitted:
-        crewai_event_bus.emit(
-            event_source,
-            event=ToolUsageFinishedEvent(
-                output=result,
-                tool_name=func_name,
-                tool_args=args_dict,
-                from_agent=agent,
-                from_task=task,
-                agent_key=agent_key,
-                started_at=started_at,
-                finished_at=datetime.now(),
-            ),
-        )
-
-    # Build tool result message
-    tool_message: LLMMessage = {
-        "role": "tool",
-        "tool_call_id": call_id,
-        "name": func_name,
-        "content": result,
-    }
-
-    if verbose and printer:
-        cache_info = " (from cache)" if from_cache else ""
-        printer.print(
-            content=f"Tool {func_name} executed with result{cache_info}: {result[:200]}...",
-            color="green",
-        )
-
-    # Check result_as_answer
-    is_result_as_answer = bool(
-        original_tool
-        and hasattr(original_tool, "result_as_answer")
-        and original_tool.result_as_answer
-    )
-
-    return NativeToolCallResult(
-        call_id=call_id,
-        func_name=func_name,
-        result=result,
-        from_cache=from_cache,
-        result_as_answer=is_result_as_answer,
-        tool_message=tool_message,
-    )
+            return json.loads(func_args), None
+        except json.JSONDecodeError as e:
+            return None, {
+                "call_id": call_id,
+                "func_name": func_name,
+                "result": (
+                    f"Error: Failed to parse tool arguments as JSON: {e}. "
+                    f"Please provide valid JSON arguments for the '{func_name}' tool."
+                ),
+                "from_cache": False,
+                "original_tool": original_tool,
+            }
+    return func_args, None
 
 
 def _setup_before_llm_call_hooks(

lib/crewai/src/crewai/utilities/i18n.py

@@ -100,13 +100,7 @@ class I18N(BaseModel):
     def retrieve(
         self,
         kind: Literal[
-            "slices",
-            "errors",
-            "tools",
-            "reasoning",
-            "planning",
-            "hierarchical_manager_agent",
-            "memory",
+            "slices", "errors", "tools", "reasoning", "hierarchical_manager_agent", "memory"
         ],
         key: str,
     ) -> str:

lib/crewai/src/crewai/utilities/llm_utils.py

@@ -69,7 +69,7 @@ def create_llm(
 UNACCEPTED_ATTRIBUTES: Final[list[str]] = [
     "AWS_ACCESS_KEY_ID",
     "AWS_SECRET_ACCESS_KEY",
-    "AWS_REGION_NAME",
+    "AWS_DEFAULT_REGION",
 ]
 
 
@@ -146,7 +146,7 @@ def _llm_via_environment_or_fallback() -> LLM | None:
     unaccepted_attributes = [
         "AWS_ACCESS_KEY_ID",
         "AWS_SECRET_ACCESS_KEY",
-        "AWS_REGION_NAME",
+        "AWS_DEFAULT_REGION",
     ]
     set_provider = model_name.partition("/")[0] if "/" in model_name else "openai"
 

lib/crewai/src/crewai/utilities/planning_types.py

@@ -1,256 +0,0 @@
-"""Types for agent planning and todo tracking."""
-
-from __future__ import annotations
-
-from typing import Literal
-from uuid import uuid4
-
-from pydantic import BaseModel, Field, field_validator
-
-
-# Todo status type
-TodoStatus = Literal["pending", "running", "completed"]
-
-
-class PlanStep(BaseModel):
-    """A single step in the reasoning plan."""
-
-    step_number: int = Field(description="Step number (1-based)")
-    description: str = Field(description="What to do in this step")
-    tool_to_use: str | None = Field(
-        default=None, description="Tool to use for this step, if any"
-    )
-    depends_on: list[int] = Field(
-        default_factory=list, description="Step numbers this step depends on"
-    )
-
-
-class TodoItem(BaseModel):
-    """A single todo item representing a step in the execution plan."""
-
-    id: str = Field(default_factory=lambda: str(uuid4()))
-    step_number: int = Field(description="Order of this step in the plan (1-based)")
-    description: str = Field(description="What needs to be done")
-    tool_to_use: str | None = Field(
-        default=None, description="Tool to use for this step, if any"
-    )
-    status: TodoStatus = Field(default="pending", description="Current status")
-    depends_on: list[int] = Field(
-        default_factory=list, description="Step numbers this depends on"
-    )
-    result: str | None = Field(
-        default=None, description="Result after completion, if any"
-    )
-
-
-class TodoList(BaseModel):
-    """Collection of todos for tracking plan execution."""
-
-    items: list[TodoItem] = Field(default_factory=list)
-
-    @property
-    def current_todo(self) -> TodoItem | None:
-        """Get the currently running todo item."""
-        for item in self.items:
-            if item.status == "running":
-                return item
-        return None
-
-    @property
-    def next_pending(self) -> TodoItem | None:
-        """Get the next pending todo item."""
-        for item in self.items:
-            if item.status == "pending":
-                return item
-        return None
-
-    @property
-    def is_complete(self) -> bool:
-        """Check if all todos are completed."""
-        return len(self.items) > 0 and all(
-            item.status == "completed" for item in self.items
-        )
-
-    @property
-    def pending_count(self) -> int:
-        """Count of pending todos."""
-        return sum(1 for item in self.items if item.status == "pending")
-
-    @property
-    def completed_count(self) -> int:
-        """Count of completed todos."""
-        return sum(1 for item in self.items if item.status == "completed")
-
-    def get_by_step_number(self, step_number: int) -> TodoItem | None:
-        """Get a todo by its step number."""
-        for item in self.items:
-            if item.step_number == step_number:
-                return item
-        return None
-
-    def mark_running(self, step_number: int) -> None:
-        """Mark a todo as running by step number."""
-        item = self.get_by_step_number(step_number)
-        if item:
-            item.status = "running"
-
-    def mark_completed(self, step_number: int, result: str | None = None) -> None:
-        """Mark a todo as completed by step number."""
-        item = self.get_by_step_number(step_number)
-        if item:
-            item.status = "completed"
-            if result:
-                item.result = result
-
-    def _dependencies_satisfied(self, item: TodoItem) -> bool:
-        """Check if all dependencies for a todo item are completed.
-
-        Args:
-            item: The todo item to check dependencies for.
-
-        Returns:
-            True if all dependencies are completed, False otherwise.
-        """
-        for dep_num in item.depends_on:
-            dep = self.get_by_step_number(dep_num)
-            if dep is None or dep.status != "completed":
-                return False
-        return True
-
-    def get_ready_todos(self) -> list[TodoItem]:
-        """Get all todos that are ready to execute (pending with satisfied dependencies).
-
-        Returns:
-            List of TodoItem objects that can be executed now.
-        """
-        ready: list[TodoItem] = []
-        for item in self.items:
-            if item.status != "pending":
-                continue
-            if self._dependencies_satisfied(item):
-                ready.append(item)
-        return ready
-
-    @property
-    def can_parallelize(self) -> bool:
-        """Check if multiple todos can run in parallel.
-
-        Returns:
-            True if more than one todo is ready to execute.
-        """
-        return len(self.get_ready_todos()) > 1
-
-    @property
-    def running_count(self) -> int:
-        """Count of currently running todos."""
-        return sum(1 for item in self.items if item.status == "running")
-
-    def get_completed_todos(self) -> list[TodoItem]:
-        """Get all completed todos.
-
-        Returns:
-            List of completed TodoItem objects.
-        """
-        return [item for item in self.items if item.status == "completed"]
-
-    def get_pending_todos(self) -> list[TodoItem]:
-        """Get all pending todos.
-
-        Returns:
-            List of pending TodoItem objects.
-        """
-        return [item for item in self.items if item.status == "pending"]
-
-    def replace_pending_todos(self, new_items: list[TodoItem]) -> None:
-        """Replace all pending todos with new items.
-
-        Preserves completed and running todos, replaces only pending ones.
-        Used during replanning to swap in a new plan for remaining work.
-
-        Args:
-            new_items: The new todo items to replace pending ones.
-        """
-        non_pending = [item for item in self.items if item.status != "pending"]
-        self.items = non_pending + new_items
-
-
-class StepRefinement(BaseModel):
-    """A structured in-place update for a single pending step.
-
-    Returned as part of StepObservation when the Planner learns new
-    information that makes a pending step description more specific.
-    Applied directly — no second LLM call required.
-    """
-
-    step_number: int = Field(description="The step number to update (1-based)")
-    new_description: str = Field(
-        description="The updated, more specific description for this step"
-    )
-
-
-class StepObservation(BaseModel):
-    """Planner's observation after a step execution completes.
-
-    Returned by the PlannerObserver after EVERY step — not just failures.
-    The Planner uses this to decide whether to continue, refine, or replan.
-
-    Based on PLAN-AND-ACT (Section 3.3): the Planner observes what the Executor
-    did and incorporates new information into the remaining plan.
-
-    Attributes:
-        step_completed_successfully: Whether the step achieved its objective.
-        key_information_learned: New information revealed by this step
-            (e.g., "Found 3 products: A, B, C"). Used to refine upcoming steps.
-        remaining_plan_still_valid: Whether pending todos still make sense
-            given the new information. True does NOT mean no refinement needed.
-        suggested_refinements: Structured in-place updates to pending step
-            descriptions. Each entry targets a specific step by number. These
-            are applied directly without a second LLM call.
-            Example: [{"step_number": 3, "new_description": "Select product B (highest rated)"}]
-        needs_full_replan: The remaining plan is fundamentally wrong and must
-            be regenerated from scratch. Mutually exclusive with
-            remaining_plan_still_valid (if this is True, that should be False).
-        replan_reason: Explanation of why a full replan is needed (None if not).
-        goal_already_achieved: The overall task goal has been satisfied early.
-            No more steps needed — skip remaining todos and finalize.
-    """
-
-    step_completed_successfully: bool = Field(
-        description="Whether the step achieved what it was asked to do"
-    )
-    key_information_learned: str = Field(
-        default="",
-        description="What new information this step revealed",
-    )
-    remaining_plan_still_valid: bool = Field(
-        default=True,
-        description="Whether the remaining pending todos still make sense given new information",
-    )
-    suggested_refinements: list[StepRefinement] | None = Field(
-        default=None,
-        description=(
-            "Structured updates to pending step descriptions based on new information. "
-            "Each entry specifies a step_number and new_description. "
-            "Applied directly — no separate replan needed."
-        ),
-    )
-
-    @field_validator("suggested_refinements", mode="before")
-    @classmethod
-    def coerce_single_refinement_to_list(cls, v):
-        """Coerce a single dict refinement into a list to handle LLM returning a single object."""
-        if isinstance(v, dict):
-            return [v]
-        return v
-    needs_full_replan: bool = Field(
-        default=False,
-        description="The remaining plan is fundamentally wrong and must be regenerated",
-    )
-    replan_reason: str | None = Field(
-        default=None,
-        description="Explanation of why a full replan is needed",
-    )
-    goal_already_achieved: bool = Field(
-        default=False,
-        description="The overall task goal has been satisfied early; no more steps needed",
-    )

lib/crewai/src/crewai/utilities/pydantic_schema_utils.py

@@ -417,7 +417,11 @@ def strip_null_from_types(schema: dict[str, Any]) -> dict[str, Any]:
     return schema
 
 
-def generate_model_description(model: type[BaseModel]) -> ModelDescription:
+def generate_model_description(
+    model: type[BaseModel],
+    *,
+    strip_null_types: bool = True,
+) -> ModelDescription:
     """Generate JSON schema description of a Pydantic model.
 
     This function takes a Pydantic model class and returns its JSON schema,
@@ -426,6 +430,9 @@ def generate_model_description(model: type[BaseModel]) -> ModelDescription:
 
     Args:
         model: A Pydantic model class.
+        strip_null_types: When ``True`` (default), remove ``null`` from
+            ``anyOf`` / ``type`` arrays.  Set to ``False`` to allow sending ``null`` for
+            optional fields.
 
     Returns:
         A ModelDescription with JSON schema representation of the model.
@@ -442,7 +449,9 @@ def generate_model_description(model: type[BaseModel]) -> ModelDescription:
     json_schema = fix_discriminator_mappings(json_schema)
     json_schema = convert_oneof_to_anyof(json_schema)
     json_schema = ensure_all_properties_required(json_schema)
-    json_schema = strip_null_from_types(json_schema)
+
+    if strip_null_types:
+        json_schema = strip_null_from_types(json_schema)
 
     return {
         "type": "json_schema",
@@ -482,10 +491,66 @@ FORMAT_TYPE_MAP: dict[str, type[Any]] = {
 }
 
 
+def build_rich_field_description(prop_schema: dict[str, Any]) -> str:
+    """Build a comprehensive field description including constraints.
+
+    Embeds format, enum, pattern, min/max, and example constraints into the
+    description text so that LLMs can understand tool parameter requirements
+    without inspecting the raw JSON Schema.
+
+    Args:
+        prop_schema: Property schema with description and constraints.
+
+    Returns:
+        Enhanced description with format, enum, and other constraints.
+    """
+    parts: list[str] = []
+
+    description = prop_schema.get("description", "")
+    if description:
+        parts.append(description)
+
+    format_type = prop_schema.get("format")
+    if format_type:
+        parts.append(f"Format: {format_type}")
+
+    enum_values = prop_schema.get("enum")
+    if enum_values:
+        enum_str = ", ".join(repr(v) for v in enum_values)
+        parts.append(f"Allowed values: [{enum_str}]")
+
+    pattern = prop_schema.get("pattern")
+    if pattern:
+        parts.append(f"Pattern: {pattern}")
+
+    minimum = prop_schema.get("minimum")
+    maximum = prop_schema.get("maximum")
+    if minimum is not None:
+        parts.append(f"Minimum: {minimum}")
+    if maximum is not None:
+        parts.append(f"Maximum: {maximum}")
+
+    min_length = prop_schema.get("minLength")
+    max_length = prop_schema.get("maxLength")
+    if min_length is not None:
+        parts.append(f"Min length: {min_length}")
+    if max_length is not None:
+        parts.append(f"Max length: {max_length}")
+
+    examples = prop_schema.get("examples")
+    if examples:
+        examples_str = ", ".join(repr(e) for e in examples[:3])
+        parts.append(f"Examples: {examples_str}")
+
+    return ". ".join(parts) if parts else ""
+
+
 def create_model_from_schema(  # type: ignore[no-any-unimported]
     json_schema: dict[str, Any],
     *,
     root_schema: dict[str, Any] | None = None,
+    model_name: str | None = None,
+    enrich_descriptions: bool = False,
     __config__: ConfigDict | None = None,
     __base__: type[BaseModel] | None = None,
     __module__: str = __name__,
@@ -503,6 +568,13 @@ def create_model_from_schema(  # type: ignore[no-any-unimported]
         json_schema: A dictionary representing the JSON schema.
         root_schema: The root schema containing $defs. If not provided, the
             current schema is treated as the root schema.
+        model_name: Override for the model name. If not provided, the schema
+            ``title`` field is used, falling back to ``"DynamicModel"``.
+        enrich_descriptions: When True, augment field descriptions with
+            constraint info (format, enum, pattern, min/max, examples) via
+            :func:`build_rich_field_description`.  Useful for LLM-facing tool
+            schemas where constraints in the description help the model
+            understand parameter requirements.
         __config__: Pydantic configuration for the generated model.
         __base__: Base class for the generated model. Defaults to BaseModel.
         __module__: Module name for the generated model class.
@@ -539,10 +611,14 @@ def create_model_from_schema(  # type: ignore[no-any-unimported]
         if "title" not in json_schema and "title" in (root_schema or {}):
             json_schema["title"] = (root_schema or {}).get("title")
 
-    model_name = json_schema.get("title") or "DynamicModel"
+    effective_name = model_name or json_schema.get("title") or "DynamicModel"
     field_definitions = {
         name: _json_schema_to_pydantic_field(
-            name, prop, json_schema.get("required", []), effective_root
+            name,
+            prop,
+            json_schema.get("required", []),
+            effective_root,
+            enrich_descriptions=enrich_descriptions,
         )
         for name, prop in (json_schema.get("properties", {}) or {}).items()
     }
@@ -550,7 +626,7 @@ def create_model_from_schema(  # type: ignore[no-any-unimported]
     effective_config = __config__ or ConfigDict(extra="forbid")
 
     return create_model_base(
-        model_name,
+        effective_name,
         __config__=effective_config,
         __base__=__base__,
         __module__=__module__,
@@ -565,6 +641,8 @@ def _json_schema_to_pydantic_field(
     json_schema: dict[str, Any],
     required: list[str],
     root_schema: dict[str, Any],
+    *,
+    enrich_descriptions: bool = False,
 ) -> Any:
     """Convert a JSON schema property to a Pydantic field definition.
 
@@ -573,20 +651,29 @@ def _json_schema_to_pydantic_field(
         json_schema: The JSON schema for this field.
         required: List of required field names.
         root_schema: The root schema for resolving $ref.
+        enrich_descriptions: When True, embed constraints in the description.
 
     Returns:
         A tuple of (type, Field) for use with create_model.
     """
-    type_ = _json_schema_to_pydantic_type(json_schema, root_schema, name_=name.title())
-    description = json_schema.get("description")
-    examples = json_schema.get("examples")
+    type_ = _json_schema_to_pydantic_type(
+        json_schema, root_schema, name_=name.title(), enrich_descriptions=enrich_descriptions
+    )
     is_required = name in required
 
     field_params: dict[str, Any] = {}
     schema_extra: dict[str, Any] = {}
 
-    if description:
-        field_params["description"] = description
+    if enrich_descriptions:
+        rich_desc = build_rich_field_description(json_schema)
+        if rich_desc:
+            field_params["description"] = rich_desc
+    else:
+        description = json_schema.get("description")
+        if description:
+            field_params["description"] = description
+
+    examples = json_schema.get("examples")
     if examples:
         schema_extra["examples"] = examples
 
@@ -702,6 +789,7 @@ def _json_schema_to_pydantic_type(
     root_schema: dict[str, Any],
     *,
     name_: str | None = None,
+    enrich_descriptions: bool = False,
 ) -> Any:
     """Convert a JSON schema to a Python/Pydantic type.
 
@@ -709,6 +797,7 @@ def _json_schema_to_pydantic_type(
         json_schema: The JSON schema to convert.
         root_schema: The root schema for resolving $ref.
         name_: Optional name for nested models.
+        enrich_descriptions: Propagated to nested model creation.
 
     Returns:
         A Python type corresponding to the JSON schema.
@@ -716,7 +805,9 @@ def _json_schema_to_pydantic_type(
     ref = json_schema.get("$ref")
     if ref:
         ref_schema = _resolve_ref(ref, root_schema)
-        return _json_schema_to_pydantic_type(ref_schema, root_schema, name_=name_)
+        return _json_schema_to_pydantic_type(
+            ref_schema, root_schema, name_=name_, enrich_descriptions=enrich_descriptions
+        )
 
     enum_values = json_schema.get("enum")
     if enum_values:
@@ -731,7 +822,10 @@ def _json_schema_to_pydantic_type(
     if any_of_schemas:
         any_of_types = [
             _json_schema_to_pydantic_type(
-                schema, root_schema, name_=f"{name_ or 'Union'}Option{i}"
+                schema,
+                root_schema,
+                name_=f"{name_ or 'Union'}Option{i}",
+                enrich_descriptions=enrich_descriptions,
             )
             for i, schema in enumerate(any_of_schemas)
         ]
@@ -741,10 +835,14 @@ def _json_schema_to_pydantic_type(
     if all_of_schemas:
         if len(all_of_schemas) == 1:
             return _json_schema_to_pydantic_type(
-                all_of_schemas[0], root_schema, name_=name_
+                all_of_schemas[0], root_schema, name_=name_,
+                enrich_descriptions=enrich_descriptions,
             )
         merged = _merge_all_of_schemas(all_of_schemas, root_schema)
-        return _json_schema_to_pydantic_type(merged, root_schema, name_=name_)
+        return _json_schema_to_pydantic_type(
+            merged, root_schema, name_=name_,
+            enrich_descriptions=enrich_descriptions,
+        )
 
     type_ = json_schema.get("type")
 
@@ -760,7 +858,8 @@ def _json_schema_to_pydantic_type(
         items_schema = json_schema.get("items")
         if items_schema:
             item_type = _json_schema_to_pydantic_type(
-                items_schema, root_schema, name_=name_
+                items_schema, root_schema, name_=name_,
+                enrich_descriptions=enrich_descriptions,
             )
             return list[item_type]  # type: ignore[valid-type]
         return list
@@ -770,7 +869,10 @@ def _json_schema_to_pydantic_type(
             json_schema_ = json_schema.copy()
             if json_schema_.get("title") is None:
                 json_schema_["title"] = name_ or "DynamicModel"
-            return create_model_from_schema(json_schema_, root_schema=root_schema)
+            return create_model_from_schema(
+                json_schema_, root_schema=root_schema,
+                enrich_descriptions=enrich_descriptions,
+            )
         return dict
     if type_ == "null":
         return None

lib/crewai/src/crewai/utilities/reasoning_handler.py

@@ -1,13 +1,10 @@
-"""Handles planning/reasoning for agents before task execution."""
-
-from __future__ import annotations
-
 import json
 import logging
-from typing import TYPE_CHECKING, Any, Final, Literal, cast
+from typing import Any, Final, Literal, cast
 
 from pydantic import BaseModel, Field
 
+from crewai.agent import Agent
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.reasoning_events import (
     AgentReasoningCompletedEvent,
@@ -15,24 +12,14 @@ from crewai.events.types.reasoning_events import (
     AgentReasoningStartedEvent,
 )
 from crewai.llm import LLM
-from crewai.utilities.llm_utils import create_llm
-from crewai.utilities.planning_types import PlanStep
+from crewai.task import Task
 from crewai.utilities.string_utils import sanitize_tool_name
 
 
-if TYPE_CHECKING:
-    from crewai.agent import Agent
-    from crewai.agent.planning_config import PlanningConfig
-    from crewai.task import Task
-
-
 class ReasoningPlan(BaseModel):
     """Model representing a reasoning plan for a task."""
 
     plan: str = Field(description="The detailed reasoning plan for the task.")
-    steps: list[PlanStep] = Field(
-        default_factory=list, description="Structured steps to execute"
-    )
     ready: bool = Field(description="Whether the agent is ready to execute the task.")
 
 
@@ -42,63 +29,24 @@ class AgentReasoningOutput(BaseModel):
     plan: ReasoningPlan = Field(description="The reasoning plan for the task.")
 
 
-# Aliases for backward compatibility
-PlanningPlan = ReasoningPlan
-AgentPlanningOutput = AgentReasoningOutput
-
-
 FUNCTION_SCHEMA: Final[dict[str, Any]] = {
     "type": "function",
     "function": {
         "name": "create_reasoning_plan",
-        "description": "Create or refine a reasoning plan for a task with structured steps",
+        "description": "Create or refine a reasoning plan for a task",
         "parameters": {
             "type": "object",
             "properties": {
                 "plan": {
                     "type": "string",
-                    "description": "A brief summary of the overall plan.",
-                },
-                "steps": {
-                    "type": "array",
-                    "description": "List of discrete steps to execute the plan",
-                    "items": {
-                        "type": "object",
-                        "properties": {
-                            "step_number": {
-                                "type": "integer",
-                                "description": "Step number (1-based)",
-                            },
-                            "description": {
-                                "type": "string",
-                                "description": "What to do in this step",
-                            },
-                            "tool_to_use": {
-                                "type": ["string", "null"],
-                                "description": "Tool to use for this step, or null if no tool needed",
-                            },
-                            "depends_on": {
-                                "type": "array",
-                                "items": {"type": "integer"},
-                                "description": "Step numbers this step depends on (empty array if none)",
-                            },
-                        },
-                        "required": [
-                            "step_number",
-                            "description",
-                            "tool_to_use",
-                            "depends_on",
-                        ],
-                        "additionalProperties": False,
-                    },
+                    "description": "The detailed reasoning plan for the task.",
                 },
                 "ready": {
                     "type": "boolean",
                     "description": "Whether the agent is ready to execute the task.",
                 },
             },
-            "required": ["plan", "steps", "ready"],
-            "additionalProperties": False,
+            "required": ["plan", "ready"],
         },
     },
 }
@@ -106,101 +54,41 @@ FUNCTION_SCHEMA: Final[dict[str, Any]] = {
 
 class AgentReasoning:
     """
-    Handles the agent planning/reasoning process, enabling an agent to reflect
-    and create a plan before executing a task.
+    Handles the agent reasoning process, enabling an agent to reflect and create a plan
+    before executing a task.
 
     Attributes:
-        task: The task for which the agent is planning (optional).
-        agent: The agent performing the planning.
-        config: The planning configuration.
-        llm: The language model used for planning.
+        task: The task for which the agent is reasoning.
+        agent: The agent performing the reasoning.
+        llm: The language model used for reasoning.
         logger: Logger for logging events and errors.
-        description: Task description or input text for planning.
-        expected_output: Expected output description.
     """
 
-    def __init__(
-        self,
-        agent: Agent,
-        task: Task | None = None,
-        *,
-        description: str | None = None,
-        expected_output: str | None = None,
-    ) -> None:
-        """Initialize the AgentReasoning with an agent and optional task.
+    def __init__(self, task: Task, agent: Agent) -> None:
+        """Initialize the AgentReasoning with a task and an agent.
 
         Args:
-            agent: The agent performing the planning.
-            task: The task for which the agent is planning (optional).
-            description: Task description or input text (used if task is None).
-            expected_output: Expected output (used if task is None).
+            task: The task for which the agent is reasoning.
+            agent: The agent performing the reasoning.
         """
-        self.agent = agent
         self.task = task
-        # Use task attributes if available, otherwise use provided values
-        self._description = description or (
-            task.description if task else "Complete the requested task"
-        )
-        self._expected_output = expected_output or (
-            task.expected_output if task else "Complete the task successfully"
-        )
-        self.config = self._get_planning_config()
-        self.llm = self._resolve_llm()
+        self.agent = agent
+        self.llm = cast(LLM, agent.llm)
         self.logger = logging.getLogger(__name__)
 
-    @property
-    def description(self) -> str:
-        """Get the task/input description."""
-        return self._description
-
-    @property
-    def expected_output(self) -> str:
-        """Get the expected output."""
-        return self._expected_output
-
-    def _get_planning_config(self) -> PlanningConfig:
-        """Get the planning configuration from the agent.
-
-        Returns:
-            The planning configuration, using defaults if not set.
-        """
-        from crewai.agent.planning_config import PlanningConfig
-
-        if self.agent.planning_config is not None:
-            return self.agent.planning_config
-        # Fallback for backward compatibility
-        return PlanningConfig(
-            max_attempts=getattr(self.agent, "max_reasoning_attempts", None),
-        )
-
-    def _resolve_llm(self) -> LLM:
-        """Resolve which LLM to use for planning.
-
-        Returns:
-            The LLM to use - either from config or the agent's LLM.
-        """
-        if self.config.llm is not None:
-            if isinstance(self.config.llm, LLM):
-                return self.config.llm
-            return create_llm(self.config.llm)
-        return cast(LLM, self.agent.llm)
-
     def handle_agent_reasoning(self) -> AgentReasoningOutput:
-        """Public method for the planning process that creates and refines a plan
-        for the task until the agent is ready to execute it.
+        """Public method for the reasoning process that creates and refines a plan for the task until the agent is ready to execute it.
 
         Returns:
-            AgentReasoningOutput: The output of the agent planning process.
+            AgentReasoningOutput: The output of the agent reasoning process.
         """
-        task_id = str(self.task.id) if self.task else "kickoff"
-
-        # Emit a planning started event (attempt 1)
+        # Emit a reasoning started event (attempt 1)
         try:
             crewai_event_bus.emit(
                 self.agent,
                 AgentReasoningStartedEvent(
                     agent_role=self.agent.role,
-                    task_id=task_id,
+                    task_id=str(self.task.id),
                     attempt=1,
                     from_task=self.task,
                 ),
@@ -210,13 +98,13 @@ class AgentReasoning:
             pass
 
         try:
-            output = self._execute_planning()
+            output = self.__handle_agent_reasoning()
 
             crewai_event_bus.emit(
                 self.agent,
                 AgentReasoningCompletedEvent(
                     agent_role=self.agent.role,
-                    task_id=task_id,
+                    task_id=str(self.task.id),
                     plan=output.plan.plan,
                     ready=output.plan.ready,
                     attempt=1,
@@ -227,76 +115,71 @@ class AgentReasoning:
 
             return output
         except Exception as e:
-            # Emit planning failed event
+            # Emit reasoning failed event
             try:
                 crewai_event_bus.emit(
                     self.agent,
                     AgentReasoningFailedEvent(
                         agent_role=self.agent.role,
-                        task_id=task_id,
+                        task_id=str(self.task.id),
                         error=str(e),
                         attempt=1,
                         from_task=self.task,
                         from_agent=self.agent,
                     ),
                 )
-            except Exception as event_error:
-                logging.error(f"Error emitting planning failed event: {event_error}")
+            except Exception as e:
+                logging.error(f"Error emitting reasoning failed event: {e}")
 
             raise
 
-    def _execute_planning(self) -> AgentReasoningOutput:
-        """Execute the planning process.
+    def __handle_agent_reasoning(self) -> AgentReasoningOutput:
+        """Private method that handles the agent reasoning process.
 
         Returns:
-            The output of the agent planning process.
+            The output of the agent reasoning process.
         """
-        plan, steps, ready = self._create_initial_plan()
-        plan, steps, ready = self._refine_plan_if_needed(plan, steps, ready)
+        plan, ready = self.__create_initial_plan()
 
-        reasoning_plan = ReasoningPlan(plan=plan, steps=steps, ready=ready)
+        plan, ready = self.__refine_plan_if_needed(plan, ready)
+
+        reasoning_plan = ReasoningPlan(plan=plan, ready=ready)
         return AgentReasoningOutput(plan=reasoning_plan)
 
-    def _create_initial_plan(self) -> tuple[str, list[PlanStep], bool]:
-        """Creates the initial plan for the task.
+    def __create_initial_plan(self) -> tuple[str, bool]:
+        """Creates the initial reasoning plan for the task.
 
         Returns:
-            A tuple of the plan summary, list of steps, and whether the agent is ready.
+            The initial plan and whether the agent is ready to execute the task.
         """
-        planning_prompt = self._create_planning_prompt()
+        reasoning_prompt = self.__create_reasoning_prompt()
 
         if self.llm.supports_function_calling():
-            plan, steps, ready = self._call_with_function(
-                planning_prompt, "create_plan"
-            )
-            return plan, steps, ready
-
-        response = self._call_llm_with_prompt(
-            prompt=planning_prompt,
-            plan_type="create_plan",
+            plan, ready = self.__call_with_function(reasoning_prompt, "initial_plan")
+            return plan, ready
+        response = _call_llm_with_reasoning_prompt(
+            llm=self.llm,
+            prompt=reasoning_prompt,
+            task=self.task,
+            reasoning_agent=self.agent,
+            backstory=self.__get_agent_backstory(),
+            plan_type="initial_plan",
         )
 
-        plan, ready = self._parse_planning_response(str(response))
-        return plan, [], ready  # No structured steps from text parsing
+        return self.__parse_reasoning_response(str(response))
 
-    def _refine_plan_if_needed(
-        self, plan: str, steps: list[PlanStep], ready: bool
-    ) -> tuple[str, list[PlanStep], bool]:
-        """Refines the plan if the agent is not ready to execute the task.
+    def __refine_plan_if_needed(self, plan: str, ready: bool) -> tuple[str, bool]:
+        """Refines the reasoning plan if the agent is not ready to execute the task.
 
         Args:
-            plan: The current plan.
-            steps: The current list of steps.
+            plan: The current reasoning plan.
             ready: Whether the agent is ready to execute the task.
 
         Returns:
-            The refined plan, steps, and whether the agent is ready to execute.
+            The refined plan and whether the agent is ready to execute the task.
         """
-
         attempt = 1
-        max_attempts = self.config.max_attempts
-        task_id = str(self.task.id) if self.task else "kickoff"
-        current_attempt = attempt + 1
+        max_attempts = self.agent.max_reasoning_attempts
 
         while not ready and (max_attempts is None or attempt < max_attempts):
             # Emit event for each refinement attempt
@@ -305,81 +188,62 @@ class AgentReasoning:
                     self.agent,
                     AgentReasoningStartedEvent(
                         agent_role=self.agent.role,
-                        task_id=task_id,
-                        attempt=current_attempt,
+                        task_id=str(self.task.id),
+                        attempt=attempt + 1,
                         from_task=self.task,
                     ),
                 )
             except Exception:  # noqa: S110
                 pass
 
-            refine_prompt = self._create_refine_prompt(plan)
+            refine_prompt = self.__create_refine_prompt(plan)
 
             if self.llm.supports_function_calling():
-                plan, steps, ready = self._call_with_function(
-                    refine_prompt, "refine_plan"
-                )
+                plan, ready = self.__call_with_function(refine_prompt, "refine_plan")
             else:
-                response = self._call_llm_with_prompt(
+                response = _call_llm_with_reasoning_prompt(
+                    llm=self.llm,
                     prompt=refine_prompt,
+                    task=self.task,
+                    reasoning_agent=self.agent,
+                    backstory=self.__get_agent_backstory(),
                     plan_type="refine_plan",
                 )
-                plan, ready = self._parse_planning_response(str(response))
-                steps = []  # No structured steps from text parsing
-
-            # Emit completed event for this refinement attempt
-            try:
-                crewai_event_bus.emit(
-                    self.agent,
-                    AgentReasoningCompletedEvent(
-                        agent_role=self.agent.role,
-                        task_id=task_id,
-                        plan=plan,
-                        ready=ready,
-                        attempt=current_attempt,
-                        from_task=self.task,
-                        from_agent=self.agent,
-                    ),
-                )
-            except Exception:  # noqa: S110
-                pass
+                plan, ready = self.__parse_reasoning_response(str(response))
 
             attempt += 1
 
             if max_attempts is not None and attempt >= max_attempts:
                 self.logger.warning(
-                    f"Agent planning reached maximum attempts ({max_attempts}) "
-                    "without being ready. Proceeding with current plan."
+                    f"Agent reasoning reached maximum attempts ({max_attempts}) without being ready. Proceeding with current plan."
                 )
                 break
 
-        return plan, steps, ready
+        return plan, ready
 
-    def _call_with_function(
-        self, prompt: str, plan_type: Literal["create_plan", "refine_plan"]
-    ) -> tuple[str, list[PlanStep], bool]:
-        """Calls the LLM with function calling to get a plan.
+    def __call_with_function(self, prompt: str, prompt_type: str) -> tuple[str, bool]:
+        """Calls the LLM with function calling to get a reasoning plan.
 
         Args:
             prompt: The prompt to send to the LLM.
-            plan_type: The type of plan being created.
+            prompt_type: The type of prompt (initial_plan or refine_plan).
 
         Returns:
-            A tuple containing the plan summary, list of steps, and whether the agent is ready.
+            A tuple containing the plan and whether the agent is ready.
         """
-        self.logger.debug(f"Using function calling for {plan_type} planning")
+        self.logger.debug(f"Using function calling for {prompt_type} reasoning")
 
         try:
-            system_prompt = self._get_system_prompt()
+            system_prompt = self.agent.i18n.retrieve("reasoning", prompt_type).format(
+                role=self.agent.role,
+                goal=self.agent.goal,
+                backstory=self.__get_agent_backstory(),
+            )
 
             # Prepare a simple callable that just returns the tool arguments as JSON
-            def _create_reasoning_plan(
-                plan: str,
-                steps: list[dict[str, Any]] | None = None,
-                ready: bool = True,
-            ) -> str:
-                """Return the planning result in JSON string form."""
-                return json.dumps({"plan": plan, "steps": steps or [], "ready": ready})
+            def _create_reasoning_plan(plan: str, ready: bool = True) -> str:
+                """Return the reasoning plan result in JSON string form."""
+                return json.dumps({"plan": plan, "ready": ready})
 
             response = self.llm.call(
                 [
@@ -391,33 +255,19 @@ class AgentReasoning:
                 from_task=self.task,
                 from_agent=self.agent,
             )
+
+            self.logger.debug(f"Function calling response: {response[:100]}...")
+
             try:
                 result = json.loads(response)
                 if "plan" in result and "ready" in result:
-                    # Parse steps from the response
-                    steps: list[PlanStep] = []
-                    raw_steps = result.get("steps", [])
-                    try:
-                        for step_data in raw_steps:
-                            step = PlanStep(
-                                step_number=step_data.get("step_number", 0),
-                                description=step_data.get("description", ""),
-                                tool_to_use=step_data.get("tool_to_use"),
-                                depends_on=step_data.get("depends_on", []),
-                            )
-                            steps.append(step)
-                    except Exception as step_error:
-                        self.logger.warning(
-                            f"Failed to parse step: {step_data}, error: {step_error}"
-                        )
-                    return result["plan"], steps, result["ready"]
+                    return result["plan"], result["ready"]
             except (json.JSONDecodeError, KeyError):
                 pass
 
             response_str = str(response)
             return (
                 response_str,
-                [],
                 "READY: I am ready to execute the task." in response_str,
             )
 
@@ -427,7 +277,13 @@ class AgentReasoning:
             )
 
             try:
-                system_prompt = self._get_system_prompt()
+                system_prompt = self.agent.i18n.retrieve(
+                    "reasoning", prompt_type
+                ).format(
+                    role=self.agent.role,
+                    goal=self.agent.goal,
+                    backstory=self.__get_agent_backstory(),
+                )
 
                 fallback_response = self.llm.call(
                     [
@@ -441,165 +297,78 @@ class AgentReasoning:
                 fallback_str = str(fallback_response)
                 return (
                     fallback_str,
-                    [],
                     "READY: I am ready to execute the task." in fallback_str,
                 )
             except Exception as inner_e:
                 self.logger.error(f"Error during fallback text parsing: {inner_e!s}")
                 return (
                     "Failed to generate a plan due to an error.",
-                    [],
                     True,
                 )  # Default to ready to avoid getting stuck
 
-    def _call_llm_with_prompt(
-        self,
-        prompt: str,
-        plan_type: Literal["create_plan", "refine_plan"],
-    ) -> str:
-        """Calls the LLM with the planning prompt.
-
-        Args:
-            prompt: The prompt to send to the LLM.
-            plan_type: The type of plan being created.
-
-        Returns:
-            The LLM response.
+    def __get_agent_backstory(self) -> str:
         """
-        system_prompt = self._get_system_prompt()
-
-        response = self.llm.call(
-            [
-                {"role": "system", "content": system_prompt},
-                {"role": "user", "content": prompt},
-            ],
-            from_task=self.task,
-            from_agent=self.agent,
-        )
-        return str(response)
-
-    def _get_system_prompt(self) -> str:
-        """Get the system prompt for planning.
+        Safely gets the agent's backstory, providing a default if not available.
 
         Returns:
-            The system prompt, either custom or from i18n.
-        """
-        if self.config.system_prompt is not None:
-            return self.config.system_prompt
-
-        # Try new "planning" section first, fall back to "reasoning" for compatibility
-        try:
-            return self.agent.i18n.retrieve("planning", "system_prompt")
-        except (KeyError, AttributeError):
-            # Fallback to reasoning section for backward compatibility
-            return self.agent.i18n.retrieve("reasoning", "initial_plan").format(
-                role=self.agent.role,
-                goal=self.agent.goal,
-                backstory=self._get_agent_backstory(),
-            )
-
-    def _get_agent_backstory(self) -> str:
-        """Safely gets the agent's backstory, providing a default if not available.
-
-        Returns:
-            The agent's backstory or a default value.
+            str: The agent's backstory or a default value.
         """
         return getattr(self.agent, "backstory", "No backstory provided")
 
-    def _create_planning_prompt(self) -> str:
-        """Creates a prompt for the agent to plan the task.
+    def __create_reasoning_prompt(self) -> str:
+        """
+        Creates a prompt for the agent to reason about the task.
 
         Returns:
-            The planning prompt.
+            str: The reasoning prompt.
         """
-        available_tools = self._format_available_tools()
+        available_tools = self.__format_available_tools()
 
-        # Use custom prompt if provided
-        if self.config.plan_prompt is not None:
-            return self.config.plan_prompt.format(
-                role=self.agent.role,
-                goal=self.agent.goal,
-                backstory=self._get_agent_backstory(),
-                description=self.description,
-                expected_output=self.expected_output,
-                tools=available_tools,
-                max_steps=self.config.max_steps,
-            )
+        return self.agent.i18n.retrieve("reasoning", "create_plan_prompt").format(
+            role=self.agent.role,
+            goal=self.agent.goal,
+            backstory=self.__get_agent_backstory(),
+            description=self.task.description,
+            expected_output=self.task.expected_output,
+            tools=available_tools,
+        )
 
-        # Try new "planning" section first
-        try:
-            return self.agent.i18n.retrieve("planning", "create_plan_prompt").format(
-                description=self.description,
-                expected_output=self.expected_output,
-                tools=available_tools,
-                max_steps=self.config.max_steps,
-            )
-        except (KeyError, AttributeError):
-            # Fallback to reasoning section for backward compatibility
-            return self.agent.i18n.retrieve("reasoning", "create_plan_prompt").format(
-                role=self.agent.role,
-                goal=self.agent.goal,
-                backstory=self._get_agent_backstory(),
-                description=self.description,
-                expected_output=self.expected_output,
-                tools=available_tools,
-            )
-
-    def _format_available_tools(self) -> str:
-        """Formats the available tools for inclusion in the prompt.
+    def __format_available_tools(self) -> str:
+        """
+        Formats the available tools for inclusion in the prompt.
 
         Returns:
-            Comma-separated list of tool names.
+            str: Comma-separated list of tool names.
         """
         try:
-            # Try task tools first, then agent tools
-            tools = []
-            if self.task:
-                tools = self.task.tools or []
-            if not tools:
-                tools = getattr(self.agent, "tools", []) or []
-            if not tools:
-                return "No tools available"
-            return ", ".join([sanitize_tool_name(tool.name) for tool in tools])
+            return ", ".join(
+                [sanitize_tool_name(tool.name) for tool in (self.task.tools or [])]
+            )
         except (AttributeError, TypeError):
             return "No tools available"
 
-    def _create_refine_prompt(self, current_plan: str) -> str:
-        """Creates a prompt for the agent to refine its plan.
+    def __create_refine_prompt(self, current_plan: str) -> str:
+        """
+        Creates a prompt for the agent to refine its reasoning plan.
 
         Args:
-            current_plan: The current plan.
+            current_plan: The current reasoning plan.
 
         Returns:
-            The refine prompt.
+            str: The refine prompt.
         """
-        # Use custom prompt if provided
-        if self.config.refine_prompt is not None:
-            return self.config.refine_prompt.format(
-                role=self.agent.role,
-                goal=self.agent.goal,
-                backstory=self._get_agent_backstory(),
-                current_plan=current_plan,
-                max_steps=self.config.max_steps,
-            )
-
-        # Try new "planning" section first
-        try:
-            return self.agent.i18n.retrieve("planning", "refine_plan_prompt").format(
-                current_plan=current_plan,
-            )
-        except (KeyError, AttributeError):
-            # Fallback to reasoning section for backward compatibility
-            return self.agent.i18n.retrieve("reasoning", "refine_plan_prompt").format(
-                role=self.agent.role,
-                goal=self.agent.goal,
-                backstory=self._get_agent_backstory(),
-                current_plan=current_plan,
-            )
+        return self.agent.i18n.retrieve("reasoning", "refine_plan_prompt").format(
+            role=self.agent.role,
+            goal=self.agent.goal,
+            backstory=self.__get_agent_backstory(),
+            current_plan=current_plan,
+        )
 
     @staticmethod
-    def _parse_planning_response(response: str) -> tuple[str, bool]:
-        """Parses the planning response to extract the plan and readiness.
+    def __parse_reasoning_response(response: str) -> tuple[str, bool]:
+        """
+        Parses the reasoning response to extract the plan and whether
+        the agent is ready to execute the task.
 
         Args:
             response: The LLM response.
@@ -611,13 +380,25 @@ class AgentReasoning:
             return "No plan was generated.", False
 
         plan = response
-        ready = "READY: I am ready to execute the task." in response
+        ready = False
+
+        if "READY: I am ready to execute the task." in response:
+            ready = True
 
         return plan, ready
 
+    def _handle_agent_reasoning(self) -> AgentReasoningOutput:
+        """
+        Deprecated method for backward compatibility.
+        Use handle_agent_reasoning() instead.
 
-# Alias for backward compatibility
-AgentPlanning = AgentReasoning
+        Returns:
+            AgentReasoningOutput: The output of the agent reasoning process.
+        """
+        self.logger.warning(
+            "The _handle_agent_reasoning method is deprecated. Use handle_agent_reasoning instead."
+        )
+        return self.handle_agent_reasoning()
 
 
 def _call_llm_with_reasoning_prompt(
@@ -628,9 +409,7 @@ def _call_llm_with_reasoning_prompt(
     backstory: str,
     plan_type: Literal["initial_plan", "refine_plan"],
 ) -> str:
-    """Deprecated: Calls the LLM with the reasoning prompt.
-
-    This function is kept for backward compatibility.
+    """Calls the LLM with the reasoning prompt.
 
     Args:
         llm: The language model to use.
@@ -638,7 +417,7 @@ def _call_llm_with_reasoning_prompt(
         task: The task for which the agent is reasoning.
         reasoning_agent: The agent performing the reasoning.
         backstory: The agent's backstory.
-        plan_type: The type of plan being created.
+        plan_type: The type of plan being created ("initial_plan" or "refine_plan").
 
     Returns:
         The LLM response.

lib/crewai/src/crewai/utilities/step_execution_context.py

@@ -1,64 +0,0 @@
-"""Context and result types for isolated step execution in Plan-and-Execute architecture.
-
-These types mediate between the AgentExecutor (orchestrator) and StepExecutor (per-step worker).
-StepExecutionContext carries only final results from dependencies — never LLM message histories.
-StepResult carries only the outcome of a step — never internal execution traces.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-
-@dataclass(frozen=True)
-class StepExecutionContext:
-    """Immutable context passed to a StepExecutor for a single todo.
-
-    Contains only the information the Executor needs to complete one step:
-    the task description, goal, and final results from dependency steps.
-    No LLM message history, no execution traces, no shared mutable state.
-
-    Attributes:
-        task_description: The original task description (from Task or kickoff input).
-        task_goal: The expected output / goal of the overall task.
-        dependency_results: Mapping of step_number → final result string
-            for all completed dependencies of the current step.
-    """
-
-    task_description: str
-    task_goal: str
-    dependency_results: dict[int, str] = field(default_factory=dict)
-
-    def get_dependency_result(self, step_number: int) -> str | None:
-        """Get the final result of a dependency step.
-
-        Args:
-            step_number: The step number to look up.
-
-        Returns:
-            The result string if available, None otherwise.
-        """
-        return self.dependency_results.get(step_number)
-
-
-@dataclass
-class StepResult:
-    """Result returned by a StepExecutor after executing a single todo.
-
-    Contains the final outcome and metadata for debugging/metrics.
-    Tool call details are for audit logging only — they are NOT passed
-    to subsequent steps or the Planner.
-
-    Attributes:
-        success: Whether the step completed successfully.
-        result: The final output string from the step.
-        error: Error message if the step failed (None on success).
-        tool_calls_made: List of tool names invoked (for debugging/logging only).
-        execution_time: Wall-clock time in seconds for the step execution.
-    """
-
-    success: bool
-    result: str
-    error: str | None = None
-    tool_calls_made: list[str] = field(default_factory=list)
-    execution_time: float = 0.0

lib/crewai/src/crewai/utilities/string_utils.py

@@ -2,6 +2,7 @@
 # https://github.com/un33k/python-slugify
 # MIT License
 
+import hashlib
 import re
 from typing import Any, Final
 import unicodedata
@@ -40,7 +41,9 @@ def sanitize_tool_name(name: str, max_length: int = _MAX_TOOL_NAME_LENGTH) -> st
     name = name.strip("_")
 
     if len(name) > max_length:
-        name = name[:max_length].rstrip("_")
+        name_hash = hashlib.sha256(name.encode()).hexdigest()[:8]
+        suffix = f"_{name_hash}"
+        name = name[: max_length - len(suffix)].rstrip("_") + suffix
 
     return name
 

lib/crewai/tests/a2a/utils/test_agent_card_event_loop.py

@@ -0,0 +1,110 @@
+"""Tests for fetch_agent_card sync wrapper when a running event loop exists.
+
+Covers the same class of issue as #4671 — ``fetch_agent_card()`` must work
+even when called from within an already-running event loop (e.g. Jupyter).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from a2a.types import AgentCapabilities, AgentCard
+
+from crewai.a2a.utils.agent_card import fetch_agent_card
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _mock_agent_card() -> AgentCard:
+    """Return a minimal ``AgentCard`` for mocking."""
+    return AgentCard(
+        name="Test Agent",
+        description="A test agent",
+        url="http://localhost:9999",
+        version="1.0.0",
+        capabilities=AgentCapabilities(streaming=False),
+        default_input_modes=["text"],
+        default_output_modes=["text"],
+        skills=[],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestFetchAgentCardEventLoop:
+    """Verify fetch_agent_card works with and without a running loop."""
+
+    @patch("crewai.a2a.utils.agent_card.afetch_agent_card")
+    def test_works_without_running_event_loop(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Normal case: no running event loop, should succeed directly."""
+        expected = _mock_agent_card()
+        mock_async_fn.return_value = expected
+
+        result = fetch_agent_card(
+            endpoint="http://localhost:9999",
+            use_cache=False,
+        )
+
+        assert result.name == "Test Agent"
+        mock_async_fn.assert_called_once()
+
+    @patch("crewai.a2a.utils.agent_card.afetch_agent_card")
+    def test_works_inside_running_event_loop(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Regression test: must not raise when a loop is already running."""
+        expected = _mock_agent_card()
+        mock_async_fn.return_value = expected
+
+        result_holder: list[Any] = []
+        error_holder: list[Exception] = []
+
+        async def _call_sync_from_async() -> None:
+            try:
+                res = fetch_agent_card(
+                    endpoint="http://localhost:9999",
+                    use_cache=False,
+                )
+                result_holder.append(res)
+            except Exception as exc:
+                error_holder.append(exc)
+
+        asyncio.run(_call_sync_from_async())
+
+        assert not error_holder, f"Unexpected error: {error_holder[0]}"
+        assert len(result_holder) == 1
+        assert result_holder[0].name == "Test Agent"
+
+    @patch("crewai.a2a.utils.agent_card.afetch_agent_card")
+    def test_propagates_errors_inside_running_event_loop(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Errors should propagate even when called from a running loop."""
+        mock_async_fn.side_effect = ConnectionError("cannot reach agent")
+
+        error_holder: list[Exception] = []
+
+        async def _call_sync_from_async() -> None:
+            try:
+                fetch_agent_card(
+                    endpoint="http://localhost:9999",
+                    use_cache=False,
+                )
+            except Exception as exc:
+                error_holder.append(exc)
+
+        asyncio.run(_call_sync_from_async())
+
+        assert len(error_holder) == 1
+        assert isinstance(error_holder[0], ConnectionError)
+        assert "cannot reach agent" in str(error_holder[0])

lib/crewai/tests/a2a/utils/test_delegation_event_loop.py

@@ -0,0 +1,129 @@
+"""Tests for A2A delegation sync wrappers when a running event loop exists.
+
+Covers the fix for https://github.com/crewAIInc/crewAI/issues/4671 where
+``execute_a2a_delegation()`` raised ``RuntimeError`` when called from an
+environment that already has a running event loop (e.g. Jupyter notebooks).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from crewai.a2a.task_helpers import TaskStateResult
+from crewai.a2a.utils.delegation import execute_a2a_delegation
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _minimal_task_state_result(**overrides: Any) -> TaskStateResult:
+    """Return a minimal ``TaskStateResult`` dict for mocking."""
+    base: TaskStateResult = {
+        "status": "completed",
+        "result": "mocked result",
+        "error": None,
+        "history": [],
+        "agent_card": None,
+    }
+    base.update(overrides)  # type: ignore[typeddict-item]
+    return base
+
+
+_DELEGATION_KWARGS: dict[str, Any] = dict(
+    endpoint="http://localhost:9999/.well-known/agent-card.json",
+    auth=None,
+    timeout=30,
+    task_description="test task",
+)
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestExecuteA2ADelegationEventLoop:
+    """Verify execute_a2a_delegation works with and without a running loop."""
+
+    @patch("crewai.a2a.utils.delegation.aexecute_a2a_delegation")
+    def test_works_without_running_event_loop(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Normal case: no running event loop, should succeed directly."""
+        expected = _minimal_task_state_result()
+        mock_async_fn.return_value = expected
+
+        result = execute_a2a_delegation(**_DELEGATION_KWARGS)
+
+        assert result["status"] == "completed"
+        assert result["result"] == "mocked result"
+        mock_async_fn.assert_called_once()
+
+    @patch("crewai.a2a.utils.delegation.aexecute_a2a_delegation")
+    def test_works_inside_running_event_loop(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Regression test for #4671: must not raise when a loop is running.
+
+        Simulates the Jupyter notebook environment by calling the sync wrapper
+        from within an already-running event loop.
+        """
+        expected = _minimal_task_state_result()
+        mock_async_fn.return_value = expected
+
+        result_holder: list[Any] = []
+        error_holder: list[Exception] = []
+
+        async def _call_sync_from_async() -> None:
+            """Call the sync function from within a running event loop."""
+            try:
+                # This must NOT raise RuntimeError anymore
+                res = execute_a2a_delegation(**_DELEGATION_KWARGS)
+                result_holder.append(res)
+            except Exception as exc:
+                error_holder.append(exc)
+
+        # Run inside an event loop, simulating a Jupyter notebook
+        asyncio.run(_call_sync_from_async())
+
+        assert not error_holder, f"Unexpected error: {error_holder[0]}"
+        assert len(result_holder) == 1
+        assert result_holder[0]["status"] == "completed"
+        assert result_holder[0]["result"] == "mocked result"
+
+    @patch("crewai.a2a.utils.delegation.aexecute_a2a_delegation")
+    def test_propagates_errors_from_async_fn(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Errors from the underlying async function should propagate."""
+        mock_async_fn.side_effect = ConnectionError("remote agent down")
+
+        with pytest.raises(ConnectionError, match="remote agent down"):
+            execute_a2a_delegation(**_DELEGATION_KWARGS)
+
+    @patch("crewai.a2a.utils.delegation.aexecute_a2a_delegation")
+    def test_propagates_errors_inside_running_event_loop(
+        self, mock_async_fn: AsyncMock
+    ) -> None:
+        """Errors should propagate even when called from a running loop."""
+        mock_async_fn.side_effect = ConnectionError("remote agent down")
+
+        error_holder: list[Exception] = []
+
+        async def _call_sync_from_async() -> None:
+            try:
+                execute_a2a_delegation(**_DELEGATION_KWARGS)
+            except Exception as exc:
+                error_holder.append(exc)
+
+        asyncio.run(_call_sync_from_async())
+
+        assert len(error_holder) == 1
+        assert isinstance(error_holder[0], ConnectionError)
+        assert "remote agent down" in str(error_holder[0])

lib/crewai/tests/agents/test_agent.py

@@ -1456,7 +1456,7 @@ def test_agent_execute_task_with_tool():
     )
 
     result = agent.execute_task(task)
-    assert "test query" in result
+    assert "you should always think about what to do" in result
 
 
 @pytest.mark.vcr()
@@ -1475,9 +1475,9 @@ def test_agent_execute_task_with_custom_llm():
     )
 
     result = agent.execute_task(task)
-    assert "Artificial minds" in result
-    assert "Code and circuits" in result
-    assert "Future undefined" in result
+    assert "In circuits they thrive" in result
+    assert "Artificial minds awake" in result
+    assert "Future's coded drive" in result
 
 
 @pytest.mark.vcr()

lib/crewai/tests/agents/test_agent_executor.py

@@ -4,27 +4,16 @@ Tests the Flow-based agent executor implementation including state management,
 flow methods, routing logic, and error handling.
 """
 
-import asyncio
 import time
-from unittest.mock import AsyncMock, Mock, patch
+from unittest.mock import Mock, patch
 
 import pytest
 
-from crewai.agents.step_executor import StepExecutor
-from crewai.agents.planner_observer import PlannerObserver
 from crewai.experimental.agent_executor import (
     AgentReActState,
     AgentExecutor,
 )
 from crewai.agents.parser import AgentAction, AgentFinish
-from crewai.events.event_bus import crewai_event_bus
-from crewai.events.types.tool_usage_events import (
-    ToolUsageFinishedEvent,
-    ToolUsageStartedEvent,
-)
-from crewai.tools.tool_types import ToolResult
-from crewai.utilities.step_execution_context import StepExecutionContext
-from crewai.utilities.planning_types import TodoItem
 
 class TestAgentReActState:
     """Test AgentReActState Pydantic model."""
@@ -37,18 +26,6 @@ class TestAgentReActState:
         assert state.current_answer is None
         assert state.is_finished is False
         assert state.ask_for_human_input is False
-        # Planning state fields
-        assert state.plan is None
-        assert state.plan_ready is False
-
-    def test_state_with_plan(self):
-        """Test AgentReActState initialization with planning fields."""
-        state = AgentReActState(
-            plan="Step 1: Do X\nStep 2: Do Y",
-            plan_ready=True,
-        )
-        assert state.plan == "Step 1: Do X\nStep 2: Do Y"
-        assert state.plan_ready is True
 
     def test_state_with_values(self):
         """Test AgentReActState initialization with values."""
@@ -203,88 +180,6 @@ class TestAgentExecutor:
         assert result == "skipped"
         assert executor.state.is_finished is False
 
-    def test_finalize_skips_synthesis_for_strong_last_todo_result(
-        self, mock_dependencies
-    ):
-        """Finalize should skip synthesis when last todo is already a complete answer."""
-        with patch.object(AgentExecutor, "_show_logs") as mock_show_logs:
-            executor = AgentExecutor(**mock_dependencies)
-            executor.state.todos.items = [
-                TodoItem(
-                    step_number=1,
-                    description="Gather source details",
-                    tool_to_use="search_tool",
-                    status="completed",
-                    result="Source A and Source B identified.",
-                ),
-                TodoItem(
-                    step_number=2,
-                    description="Write final response",
-                    tool_to_use=None,
-                    status="completed",
-                    result=(
-                        "The final recommendation is to adopt a phased rollout plan with "
-                        "weekly checkpoints, explicit ownership, and a rollback path for "
-                        "each milestone. This approach keeps risk controlled while still "
-                        "moving quickly, and it aligns delivery metrics with stakeholder "
-                        "communication and operational readiness."
-                    ),
-                ),
-            ]
-
-            with patch.object(
-                executor, "_synthesize_final_answer_from_todos"
-            ) as mock_synthesize:
-                result = executor.finalize()
-
-            assert result == "completed"
-            assert isinstance(executor.state.current_answer, AgentFinish)
-            assert (
-                executor.state.current_answer.output
-                == executor.state.todos.items[1].result
-            )
-            assert executor.state.is_finished is True
-            mock_synthesize.assert_not_called()
-            mock_show_logs.assert_called_once()
-
-    def test_finalize_keeps_synthesis_when_response_model_is_set(
-        self, mock_dependencies
-    ):
-        """Finalize should still synthesize when response_model is configured."""
-        with patch.object(AgentExecutor, "_show_logs"):
-            executor = AgentExecutor(**mock_dependencies)
-            executor.response_model = Mock()
-            executor.state.todos.items = [
-                TodoItem(
-                    step_number=1,
-                    description="Write final response",
-                    tool_to_use=None,
-                    status="completed",
-                    result=(
-                        "This is already detailed prose with multiple sentences. "
-                        "It should still run synthesis because structured output "
-                        "was requested via response_model."
-                    ),
-                )
-            ]
-
-            def _set_current_answer() -> None:
-                executor.state.current_answer = AgentFinish(
-                    thought="Synthesized",
-                    output="structured-like-answer",
-                    text="structured-like-answer",
-                )
-
-            with patch.object(
-                executor,
-                "_synthesize_final_answer_from_todos",
-                side_effect=_set_current_answer,
-            ) as mock_synthesize:
-                result = executor.finalize()
-
-            assert result == "completed"
-            mock_synthesize.assert_called_once()
-
     def test_format_prompt(self, mock_dependencies):
         """Test prompt formatting."""
         executor = AgentExecutor(**mock_dependencies)
@@ -339,113 +234,6 @@ class TestAgentExecutor:
             AgentFinish(thought="thinking", output="test", text="final")
         )
 
-    @pytest.mark.asyncio
-    async def test_invoke_step_callback_async_inside_running_loop(
-        self, mock_dependencies
-    ):
-        """Test async step callback scheduling when already in an event loop."""
-        callback = AsyncMock()
-        mock_dependencies["step_callback"] = callback
-        executor = AgentExecutor(**mock_dependencies)
-
-        answer = AgentFinish(thought="thinking", output="test", text="final")
-        with patch("crewai.experimental.agent_executor.asyncio.run") as mock_run:
-            executor._invoke_step_callback(answer)
-            await asyncio.sleep(0)
-
-        callback.assert_awaited_once_with(answer)
-        mock_run.assert_not_called()
-
-
-class TestStepExecutorCriticalFixes:
-    """Regression tests for critical plan-and-execute issues."""
-
-    @pytest.fixture
-    def step_executor(self):
-        llm = Mock()
-        llm.supports_stop_words.return_value = True
-
-        agent = Mock()
-        agent.role = "Test Agent"
-        agent.goal = "Execute tasks"
-        agent.verbose = False
-        agent.key = "test-agent-key"
-
-        tool = Mock()
-        tool.name = "count_words"
-        task = Mock()
-        task.name = "test-task"
-        task.description = "test task description"
-
-        return StepExecutor(
-            llm=llm,
-            tools=[tool],
-            agent=agent,
-            original_tools=[],
-            tools_handler=Mock(),
-            task=task,
-            crew=Mock(),
-            function_calling_llm=None,
-            request_within_rpm_limit=None,
-            callbacks=[],
-        )
-
-    def test_step_executor_fails_when_expected_tool_is_not_called(self, step_executor):
-        """Step should fail if a configured expected tool is not actually invoked."""
-        todo = TodoItem(
-            step_number=1,
-            description="Count words in input text.",
-            tool_to_use="count_words",
-            depends_on=[],
-            status="pending",
-        )
-        context = StepExecutionContext(task_description="task", task_goal="goal")
-
-        with patch.object(step_executor, "_build_isolated_messages", return_value=[]):
-            with patch.object(
-                step_executor, "_execute_text_parsed", return_value="No tool used."
-            ):
-                result = step_executor.execute(todo, context)
-
-        assert result.success is False
-        assert result.error is not None
-        assert "Expected tool 'count_words' was not called" in result.error
-
-    def test_step_executor_text_tool_emits_usage_events(self, step_executor):
-        """Text-parsed tool execution should emit started and finished events."""
-        started_events: list[ToolUsageStartedEvent] = []
-        finished_events: list[ToolUsageFinishedEvent] = []
-
-        tool_name = "count_words"
-        action = AgentAction(
-            thought="Need a tool",
-            tool=tool_name,
-            tool_input='{"text":"hello world"}',
-            text="Action: count_words",
-        )
-
-        @crewai_event_bus.on(ToolUsageStartedEvent)
-        def _on_started(_source, event):
-            if event.tool_name == tool_name:
-                started_events.append(event)
-
-        @crewai_event_bus.on(ToolUsageFinishedEvent)
-        def _on_finished(_source, event):
-            if event.tool_name == tool_name:
-                finished_events.append(event)
-
-        with patch(
-            "crewai.agents.step_executor.execute_tool_and_check_finality",
-            return_value=ToolResult(result="2", result_as_answer=False),
-        ):
-            output = step_executor._execute_text_tool_with_events(action)
-
-        crewai_event_bus.flush()
-
-        assert output == "2"
-        assert len(started_events) >= 1
-        assert len(finished_events) >= 1
-
     @patch("crewai.experimental.agent_executor.handle_output_parser_exception")
     def test_recover_from_parser_error(
         self, mock_handle_exception, mock_dependencies
@@ -848,696 +636,3 @@ class TestNativeToolExecution:
         tool_messages = [m for m in executor.state.messages if m.get("role") == "tool"]
         assert len(tool_messages) == 1
         assert tool_messages[0]["tool_call_id"] == "call_1"
-
-    def test_check_native_todo_completion_requires_expected_tool_match(
-        self, mock_dependencies
-    ):
-        from crewai.utilities.planning_types import TodoList
-
-        executor = AgentExecutor(**mock_dependencies)
-        running = TodoItem(
-            step_number=1,
-            description="Use the expected tool",
-            tool_to_use="expected_tool",
-            status="running",
-        )
-        executor.state.todos = TodoList(items=[running])
-
-        executor.state.last_native_tools_executed = ["other_tool"]
-        assert executor.check_native_todo_completion() == "todo_not_satisfied"
-
-        executor.state.last_native_tools_executed = ["expected_tool"]
-        assert executor.check_native_todo_completion() == "todo_satisfied"
-
-        running.tool_to_use = None
-        executor.state.last_native_tools_executed = ["any_tool"]
-        assert executor.check_native_todo_completion() == "todo_not_satisfied"
-
-
-class TestPlannerObserver:
-    def test_observe_fallback_is_conservative_on_llm_error(self):
-        llm = Mock()
-        llm.call.side_effect = RuntimeError("llm unavailable")
-
-        agent = Mock()
-        agent.role = "Observer Test Agent"
-        agent.llm = llm
-        agent.planning_config = None
-
-        task = Mock()
-        task.description = "Test task"
-        task.expected_output = "Expected result"
-
-        observer = PlannerObserver(agent=agent, task=task)
-
-        completed_step = TodoItem(
-            step_number=1,
-            description="Do something",
-            status="running",
-        )
-        observation = observer.observe(
-            completed_step=completed_step,
-            result="Error: tool timeout",
-            all_completed=[],
-            remaining_todos=[],
-        )
-
-        assert observation.step_completed_successfully is False
-        assert observation.remaining_plan_still_valid is False
-        assert observation.needs_full_replan is True
-        assert observation.replan_reason == "Observer failed to evaluate step result safely"
-
-
-class TestAgentExecutorPlanning:
-    """Test planning functionality in AgentExecutor with real agent kickoff."""
-
-    @pytest.mark.vcr()
-    def test_agent_kickoff_with_planning_stores_plan_in_state(self):
-        """Test that Agent.kickoff() with planning enabled stores plan in executor state."""
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Assistant",
-            goal="Help solve simple math problems",
-            backstory="A helpful assistant that solves math problems step by step",
-            llm=llm,
-            planning_config=PlanningConfig(max_attempts=1),
-            verbose=False,
-        )
-
-        # Execute kickoff with a simple task
-        result = agent.kickoff("What is 2 + 2?")
-
-        # Verify result
-        assert result is not None
-        assert "4" in str(result)
-
-    @pytest.mark.vcr()
-    def test_agent_kickoff_without_planning_skips_plan_generation(self):
-        """Test that Agent.kickoff() without planning skips planning phase."""
-        from crewai import Agent
-        from crewai.llm import LLM
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Assistant",
-            goal="Help solve simple math problems",
-            backstory="A helpful assistant",
-            llm=llm,
-            # No planning_config = no planning
-            verbose=False,
-        )
-
-        # Execute kickoff
-        result = agent.kickoff("What is 3 + 3?")
-
-        # Verify we get a result
-        assert result is not None
-        assert "6" in str(result)
-
-    @pytest.mark.vcr()
-    def test_planning_disabled_skips_planning(self):
-        """Test that planning=False skips planning."""
-        from crewai import Agent
-        from crewai.llm import LLM
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Assistant",
-            goal="Help solve simple math problems",
-            backstory="A helpful assistant",
-            llm=llm,
-            planning=False,  # Explicitly disable planning
-            verbose=False,
-        )
-
-        result = agent.kickoff("What is 5 + 5?")
-
-        # Should still complete successfully
-        assert result is not None
-        assert "10" in str(result)
-
-    def test_backward_compat_reasoning_true_enables_planning(self):
-        """Test that reasoning=True (deprecated) still enables planning."""
-        import warnings
-        from crewai import Agent
-        from crewai.llm import LLM
-
-        llm = LLM("gpt-4o-mini")
-
-        with warnings.catch_warnings(record=True):
-            warnings.simplefilter("always")
-            agent = Agent(
-                role="Test Agent",
-                goal="Complete tasks",
-                backstory="A helpful agent",
-                llm=llm,
-                reasoning=True,  # Deprecated but should still work
-                verbose=False,
-            )
-
-        # Should have planning_config created from reasoning=True
-        assert agent.planning_config is not None
-        assert agent.planning_enabled is True
-
-    @pytest.mark.vcr()
-    def test_executor_state_contains_plan_after_planning(self):
-        """Test that executor state contains plan after planning phase."""
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-        from crewai.experimental.agent_executor import AgentExecutor
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Assistant",
-            goal="Help solve simple math problems",
-            backstory="A helpful assistant that solves math problems step by step",
-            llm=llm,
-            planning_config=PlanningConfig(max_attempts=1),
-            verbose=False,
-        )
-
-        # Track executor for inspection
-        executor_ref = [None]
-        original_invoke = AgentExecutor.invoke
-
-        def capture_executor(self, inputs):
-            executor_ref[0] = self
-            return original_invoke(self, inputs)
-
-        with patch.object(AgentExecutor, "invoke", capture_executor):
-            result = agent.kickoff("What is 7 + 7?")
-
-        # Verify result
-        assert result is not None
-
-        # If we captured an executor, check its state
-        if executor_ref[0] is not None:
-            # After planning, state should have plan info
-            assert hasattr(executor_ref[0].state, "plan")
-            assert hasattr(executor_ref[0].state, "plan_ready")
-
-    @pytest.mark.vcr()
-    def test_planning_creates_minimal_steps_for_multi_step_task(self):
-        """Test that planning creates steps and executes them for a multi-step task.
-
-        This task requires multiple dependent steps:
-        1. Identify the first 3 prime numbers (2, 3, 5)
-        2. Sum them (2 + 3 + 5 = 10)
-        3. Multiply by 2 (10 * 2 = 20)
-
-        The plan-and-execute architecture should produce step results.
-        """
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-        from crewai.experimental.agent_executor import AgentExecutor
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Tutor",
-            goal="Solve multi-step math problems accurately",
-            backstory="An expert math tutor who breaks down problems step by step",
-            llm=llm,
-            planning_config=PlanningConfig(max_attempts=1, max_steps=10),
-            verbose=False,
-        )
-
-        # Track the plan that gets generated
-        captured_plan = [None]
-        original_invoke = AgentExecutor.invoke
-
-        def capture_plan(self, inputs):
-            result = original_invoke(self, inputs)
-            captured_plan[0] = self.state.plan
-            return result
-
-        with patch.object(AgentExecutor, "invoke", capture_plan):
-            result = agent.kickoff(
-                "Calculate the sum of the first 3 prime numbers, then multiply that result by 2. "
-                "Show your work for each step."
-            )
-
-        # Verify we got a result with step outputs
-        assert result is not None
-        result_str = str(result)
-        # Should contain at least some mathematical content from the steps
-        assert "prime" in result_str.lower() or "2" in result_str or "10" in result_str
-
-        # Verify a plan was generated
-        assert captured_plan[0] is not None
-
-    @pytest.mark.vcr()
-    def test_planning_handles_sequential_dependency_task(self):
-        """Test planning for a task where step N depends on step N-1.
-
-        Task: Convert 100 Celsius to Fahrenheit, then round to nearest 10.
-        Step 1: Apply formula (C * 9/5 + 32) = 212
-        Step 2: Round 212 to nearest 10 = 210
-
-        This tests that the planner creates a plan and executes steps.
-        """
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-        from crewai.experimental.agent_executor import AgentExecutor
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Unit Converter",
-            goal="Accurately convert between units and apply transformations",
-            backstory="A precise unit conversion specialist",
-            llm=llm,
-            planning_config=PlanningConfig(max_attempts=1, max_steps=10),
-            verbose=False,
-        )
-
-        captured_plan = [None]
-        original_invoke = AgentExecutor.invoke
-
-        def capture_plan(self, inputs):
-            result = original_invoke(self, inputs)
-            captured_plan[0] = self.state.plan
-            return result
-
-        with patch.object(AgentExecutor, "invoke", capture_plan):
-            result = agent.kickoff(
-                "Convert 100 degrees Celsius to Fahrenheit, then round the result to the nearest 10."
-            )
-
-        assert result is not None
-        result_str = str(result)
-        # Should contain conversion-related content
-        assert "212" in result_str or "210" in result_str or "Fahrenheit" in result_str or "celsius" in result_str.lower()
-
-        # Plan should exist
-        assert captured_plan[0] is not None
-
-
-class TestResponseFormatWithKickoff:
-    """Test that Agent.kickoff(response_format=MyModel) returns structured output.
-
-    Real LLM calls via VCR cassettes. Tests both with and without planning,
-    using real tools for the planning case to exercise the full Plan-and-Execute
-    path including synthesis with response_model.
-    """
-
-    @pytest.mark.vcr()
-    def test_kickoff_response_format_without_planning(self):
-        """Test that kickoff(response_format) returns structured output without planning."""
-        from pydantic import BaseModel, Field
-        from crewai import Agent
-        from crewai.llm import LLM
-
-        class MathResult(BaseModel):
-            answer: int = Field(description="The numeric answer")
-            explanation: str = Field(description="Brief explanation of the solution")
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Assistant",
-            goal="Solve math problems and return structured results",
-            backstory="A precise math assistant that always returns structured data",
-            llm=llm,
-            verbose=False,
-        )
-
-        result = agent.kickoff("What is 15 + 27?", response_format=MathResult)
-
-        assert result is not None
-        assert result.pydantic is not None
-        assert isinstance(result.pydantic, MathResult)
-        assert result.pydantic.answer == 42
-        assert len(result.pydantic.explanation) > 0
-
-    @pytest.mark.vcr()
-    def test_kickoff_response_format_with_planning_and_tools(self):
-        """Test response_format with planning + tools (multi-step research).
-
-        This is the key test for _synthesize_final_answer_from_todos:
-        1. Planning generates steps that use the EXA search tool
-        2. StepExecutor runs each step in isolation with tool calls
-        3. The synthesis step produces a structured BaseModel output
-
-        The response_format should be respected by the synthesis LLM call,
-        NOT by intermediate step executions.
-        """
-        from pydantic import BaseModel, Field
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-        from crewai_tools import EXASearchTool
-
-        class ResearchSummary(BaseModel):
-            topic: str = Field(description="The research topic")
-            key_findings: list[str] = Field(description="List of 3-5 key findings")
-            conclusion: str = Field(description="A brief conclusion paragraph")
-
-        llm = LLM("gpt-4o-mini")
-        exa = EXASearchTool()
-
-        agent = Agent(
-            role="Research Analyst",
-            goal="Research topics using search tools and produce structured summaries",
-            backstory=(
-                "You are a research analyst who searches the web for information, "
-                "identifies key findings, and produces structured research summaries."
-            ),
-            llm=llm,
-            planning_config=PlanningConfig(max_attempts=1, max_steps=5),
-            tools=[exa],
-            verbose=False,
-        )
-
-        result = agent.kickoff(
-            "Research the current state of autonomous AI agents in 2025. "
-            "Search for recent developments, then summarize the key findings.",
-            response_format=ResearchSummary,
-        )
-
-        assert result is not None
-        # The synthesis step should have produced structured output
-        assert result.pydantic is not None
-        assert isinstance(result.pydantic, ResearchSummary)
-        # Verify the structured fields are populated
-        assert len(result.pydantic.topic) > 0
-        assert len(result.pydantic.key_findings) >= 1
-        assert len(result.pydantic.conclusion) > 0
-
-    @pytest.mark.vcr()
-    def test_kickoff_no_response_format_returns_raw_text(self):
-        """Test that kickoff without response_format returns plain text."""
-        from crewai import Agent
-        from crewai.llm import LLM
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Assistant",
-            goal="Solve math problems",
-            backstory="A helpful math assistant",
-            llm=llm,
-            verbose=False,
-        )
-
-        result = agent.kickoff("What is 10 + 10?")
-
-        assert result is not None
-        assert result.pydantic is None
-        assert "20" in str(result)
-
-
-class TestReasoningEffort:
-    """Test reasoning_effort levels in PlanningConfig.
-
-    - low:  observe() runs (validates step success), but skip decide/replan/refine
-    - medium: observe() runs, replan on failure only (mocked)
-    - high: full observation pipeline with decide/replan/refine/goal-achieved
-    """
-
-    @pytest.mark.vcr()
-    def test_reasoning_effort_low_skips_decide_and_replan(self):
-        """Low effort: observe runs but decide/replan/refine are never called.
-
-        Verifies that with reasoning_effort='low':
-        1. The agent produces a correct result
-        2. The observation phase still runs (observations are stored)
-        3. The decide_next_action/refine/replan pipeline is bypassed
-        """
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-        from crewai.experimental.agent_executor import AgentExecutor
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Tutor",
-            goal="Solve multi-step math problems accurately",
-            backstory="An expert math tutor who breaks down problems step by step",
-            llm=llm,
-            planning_config=PlanningConfig(
-                reasoning_effort="low",
-                max_attempts=1,
-                max_steps=10,
-            ),
-            verbose=False,
-        )
-
-        # Capture the executor to inspect state after execution
-        executor_ref = [None]
-        original_invoke = AgentExecutor.invoke
-
-        def capture_executor(self, inputs):
-            result = original_invoke(self, inputs)
-            executor_ref[0] = self
-            return result
-
-        with patch.object(AgentExecutor, "invoke", capture_executor):
-            result = agent.kickoff(
-                "What is the sum of the first 3 prime numbers (2, 3, 5)?"
-            )
-
-        assert result is not None
-        assert "10" in str(result)
-
-        # Verify observations were still collected (observe() ran)
-        executor = executor_ref[0]
-        if executor is not None and executor.state.todos.items:
-            assert len(executor.state.observations) > 0, (
-                "Low effort should still run observe() to validate steps"
-            )
-
-            # Verify no replan was triggered
-            assert executor.state.replan_count == 0, (
-                "Low effort should never trigger replanning"
-            )
-
-            # Check execution log for reasoning_effort annotation
-            observation_logs = [
-                log for log in executor.state.execution_log
-                if log.get("type") == "observation"
-            ]
-            for log in observation_logs:
-                assert log.get("reasoning_effort") == "low"
-
-    @pytest.mark.vcr()
-    def test_reasoning_effort_high_runs_full_observation_pipeline(self):
-        """High effort: full observation pipeline with decide/replan/refine.
-
-        Verifies that with reasoning_effort='high':
-        1. The agent produces a correct result
-        2. Observations are stored
-        3. The full decide_next_action pipeline runs (the observation-driven
-           routing is exercised, even if it just routes to continue_plan)
-        """
-        from crewai import Agent, PlanningConfig
-        from crewai.llm import LLM
-        from crewai.experimental.agent_executor import AgentExecutor
-
-        llm = LLM("gpt-4o-mini")
-
-        agent = Agent(
-            role="Math Tutor",
-            goal="Solve multi-step math problems accurately",
-            backstory="An expert math tutor who breaks down problems step by step",
-            llm=llm,
-            planning_config=PlanningConfig(
-                reasoning_effort="high",
-                max_attempts=1,
-                max_steps=10,
-            ),
-            verbose=False,
-        )
-
-        executor_ref = [None]
-        original_invoke = AgentExecutor.invoke
-
-        def capture_executor(self, inputs):
-            result = original_invoke(self, inputs)
-            executor_ref[0] = self
-            return result
-
-        with patch.object(AgentExecutor, "invoke", capture_executor):
-            result = agent.kickoff(
-                "What is the sum of the first 3 prime numbers (2, 3, 5)?"
-            )
-
-        assert result is not None
-        assert "10" in str(result)
-
-        # Verify observations were collected
-        executor = executor_ref[0]
-        if executor is not None and executor.state.todos.items:
-            assert len(executor.state.observations) > 0, (
-                "High effort should run observe() on every step"
-            )
-
-            # Check execution log shows high reasoning_effort
-            observation_logs = [
-                log for log in executor.state.execution_log
-                if log.get("type") == "observation"
-            ]
-            for log in observation_logs:
-                assert log.get("reasoning_effort") == "high"
-
-    def test_reasoning_effort_medium_replans_on_failure(self):
-        """Medium effort: replan triggered when observation reports failure.
-
-        This test mocks the PlannerObserver to simulate a failed step,
-        verifying that medium effort routes to replan_now on failure
-        but continues on success.
-        """
-        from crewai.experimental.agent_executor import AgentExecutor
-        from crewai.utilities.planning_types import (
-            StepObservation,
-            TodoItem,
-            TodoList,
-        )
-
-        # --- Build a minimal mock executor with medium effort ---
-        executor = Mock(spec=AgentExecutor)
-        executor.agent = Mock()
-        executor.agent.verbose = False
-        executor.agent.planning_config = Mock()
-        executor.agent.planning_config.reasoning_effort = "medium"
-
-        # Provide the real method under test (bound to our mock)
-        executor.handle_step_observed_medium = (
-            AgentExecutor.handle_step_observed_medium.__get__(executor)
-        )
-        executor._printer = Mock()
-
-        # --- Case 1: step succeeded → should return "continue_plan" ---
-        success_todo = TodoItem(
-            step_number=1,
-            description="Calculate something",
-            status="running",
-            result="42",
-        )
-        success_observation = StepObservation(
-            step_completed_successfully=True,
-            key_information_learned="Got the answer",
-            remaining_plan_still_valid=True,
-        )
-
-        # Set up state
-        todo_list = TodoList(items=[success_todo])
-        executor.state = Mock()
-        executor.state.todos = todo_list
-        executor.state.observations = {1: success_observation}
-
-        route = executor.handle_step_observed_medium()
-        assert route == "continue_plan", (
-            "Medium effort should continue on successful step"
-        )
-        assert success_todo.status == "completed"
-
-        # --- Case 2: step failed → should return "replan_now" ---
-        failed_todo = TodoItem(
-            step_number=2,
-            description="Divide by zero",
-            status="running",
-            result="Error: division by zero",
-        )
-        failed_observation = StepObservation(
-            step_completed_successfully=False,
-            key_information_learned="Division failed",
-            remaining_plan_still_valid=False,
-            needs_full_replan=True,
-            replan_reason="Step failed with error",
-        )
-
-        todo_list_2 = TodoList(items=[failed_todo])
-        executor.state.todos = todo_list_2
-        executor.state.observations = {2: failed_observation}
-        executor.state.last_replan_reason = None
-
-        route = executor.handle_step_observed_medium()
-        assert route == "replan_now", (
-            "Medium effort should trigger replan on failed step"
-        )
-        assert executor.state.last_replan_reason == "Step did not complete successfully"
-
-    def test_reasoning_effort_low_marks_complete_without_deciding(self):
-        """Low effort: mark_completed is called, decide_next_action is not.
-
-        Unit test verifying the low handler's behavior directly.
-        """
-        from crewai.experimental.agent_executor import AgentExecutor
-        from crewai.utilities.planning_types import TodoItem, TodoList
-
-        executor = Mock(spec=AgentExecutor)
-        executor.agent = Mock()
-        executor.agent.verbose = False
-        executor.agent.planning_config = Mock()
-        executor.agent.planning_config.reasoning_effort = "low"
-
-        # Bind the real method
-        executor.handle_step_observed_low = (
-            AgentExecutor.handle_step_observed_low.__get__(executor)
-        )
-        executor._printer = Mock()
-
-        todo = TodoItem(
-            step_number=1,
-            description="Do something",
-            status="running",
-            result="Done successfully",
-        )
-        todo_list = TodoList(items=[todo])
-        executor.state = Mock()
-        executor.state.todos = todo_list
-
-        route = executor.handle_step_observed_low()
-        assert route == "continue_plan"
-        assert todo.status == "completed"
-        assert todo.result == "Done successfully"
-
-    def test_planning_config_reasoning_effort_default_is_low(self):
-        """Verify PlanningConfig defaults reasoning_effort to 'low'."""
-        from crewai.agent.planning_config import PlanningConfig
-
-        config = PlanningConfig()
-        assert config.reasoning_effort == "low"
-
-    def test_planning_config_reasoning_effort_validation(self):
-        """Verify PlanningConfig rejects invalid reasoning_effort values."""
-        from pydantic import ValidationError
-        from crewai.agent.planning_config import PlanningConfig
-
-        with pytest.raises(ValidationError):
-            PlanningConfig(reasoning_effort="ultra")
-
-        # Valid values should work
-        for level in ("low", "medium", "high"):
-            config = PlanningConfig(reasoning_effort=level)
-            assert config.reasoning_effort == level
-
-    def test_get_reasoning_effort_reads_from_config(self):
-        """Verify _get_reasoning_effort reads from agent.planning_config."""
-        from crewai.experimental.agent_executor import AgentExecutor
-
-        executor = Mock(spec=AgentExecutor)
-        executor._get_reasoning_effort = (
-            AgentExecutor._get_reasoning_effort.__get__(executor)
-        )
-
-        # Case 1: planning_config with reasoning_effort set
-        executor.agent = Mock()
-        executor.agent.planning_config = Mock()
-        executor.agent.planning_config.reasoning_effort = "high"
-        assert executor._get_reasoning_effort() == "high"
-
-        # Case 2: no planning_config → defaults to "low"
-        executor.agent.planning_config = None
-        assert executor._get_reasoning_effort() == "low"
-
-        # Case 3: planning_config without reasoning_effort attr → defaults to "low"
-        executor.agent.planning_config = Mock(spec=[])
-        assert executor._get_reasoning_effort() == "low"

lib/crewai/tests/agents/test_agent_reasoning.py

@@ -1,345 +1,240 @@
-"""Tests for planning/reasoning in agents."""
+"""Tests for reasoning in agents."""
 
-import warnings
+import json
 
 import pytest
 
-from crewai import Agent, PlanningConfig, Task
+from crewai import Agent, Task
 from crewai.llm import LLM
 
 
-# =============================================================================
-# Tests for PlanningConfig configuration (no LLM calls needed)
-# =============================================================================
+@pytest.fixture
+def mock_llm_responses():
+    """Fixture for mock LLM responses."""
+    return {
+        "ready": "I'll solve this simple math problem.\n\nREADY: I am ready to execute the task.\n\n",
+        "not_ready": "I need to think about derivatives.\n\nNOT READY: I need to refine my plan because I'm not sure about the derivative rules.",
+        "ready_after_refine": "I'll use the power rule for derivatives where d/dx(x^n) = n*x^(n-1).\n\nREADY: I am ready to execute the task.",
+        "execution": "4",
+    }
 
 
-def test_planning_config_default_values():
-    """Test PlanningConfig default values."""
-    config = PlanningConfig()
-
-    assert config.max_attempts is None
-    assert config.max_steps == 20
-    assert config.system_prompt is None
-    assert config.plan_prompt is None
-    assert config.refine_prompt is None
-    assert config.llm is None
-
-
-def test_planning_config_custom_values():
-    """Test PlanningConfig with custom values."""
-    config = PlanningConfig(
-        max_attempts=5,
-        max_steps=15,
-        system_prompt="Custom system",
-        plan_prompt="Custom plan: {description}",
-        refine_prompt="Custom refine: {current_plan}",
-        llm="gpt-4",
-    )
-
-    assert config.max_attempts == 5
-    assert config.max_steps == 15
-    assert config.system_prompt == "Custom system"
-    assert config.plan_prompt == "Custom plan: {description}"
-    assert config.refine_prompt == "Custom refine: {current_plan}"
-    assert config.llm == "gpt-4"
-
-
-def test_agent_with_planning_config_custom_prompts():
-    """Test agent with PlanningConfig using custom prompts."""
-    llm = LLM("gpt-4o-mini")
-
-    custom_system_prompt = "You are a specialized planner."
-    custom_plan_prompt = "Plan this task: {description}"
-
-    agent = Agent(
-        role="Test Agent",
-        goal="To test custom prompts",
-        backstory="I am a test agent.",
-        llm=llm,
-        planning_config=PlanningConfig(
-            system_prompt=custom_system_prompt,
-            plan_prompt=custom_plan_prompt,
-            max_steps=10,
-        ),
-        verbose=False,
-    )
-
-    # Just test that the agent is created properly
-    assert agent.planning_config is not None
-    assert agent.planning_config.system_prompt == custom_system_prompt
-    assert agent.planning_config.plan_prompt == custom_plan_prompt
-    assert agent.planning_config.max_steps == 10
-
-
-def test_agent_with_planning_config_disabled():
-    """Test agent with PlanningConfig disabled."""
-    llm = LLM("gpt-4o-mini")
-
-    agent = Agent(
-        role="Test Agent",
-        goal="To test disabled planning",
-        backstory="I am a test agent.",
-        llm=llm,
-        planning=False,
-        verbose=False,
-    )
-
-    # Planning should be disabled
-    assert agent.planning_enabled is False
-
-
-def test_planning_enabled_property():
-    """Test the planning_enabled property on Agent."""
-    llm = LLM("gpt-4o-mini")
-
-    # With planning_config enabled
-    agent_with_planning = Agent(
-        role="Test Agent",
-        goal="Test",
-        backstory="Test",
-        llm=llm,
-        planning=True,
-    )
-    assert agent_with_planning.planning_enabled is True
-
-    # With planning_config disabled
-    agent_disabled = Agent(
-        role="Test Agent",
-        goal="Test",
-        backstory="Test",
-        llm=llm,
-        planning=False,
-    )
-    assert agent_disabled.planning_enabled is False
-
-    # Without planning_config
-    agent_no_planning = Agent(
-        role="Test Agent",
-        goal="Test",
-        backstory="Test",
-        llm=llm,
-    )
-    assert agent_no_planning.planning_enabled is False
-
-
-# =============================================================================
-# Tests for backward compatibility with reasoning=True (no LLM calls)
-# =============================================================================
-
-
-def test_agent_with_reasoning_backward_compat():
-    """Test agent with reasoning=True (backward compatibility)."""
-    llm = LLM("gpt-4o-mini")
-
-    # This should emit a deprecation warning
-    with warnings.catch_warnings(record=True):
-        warnings.simplefilter("always")
-        agent = Agent(
-            role="Test Agent",
-            goal="To test the reasoning feature",
-            backstory="I am a test agent created to verify the reasoning feature works correctly.",
-            llm=llm,
-            reasoning=True,
-            verbose=False,
-        )
-
-    # Should have created a PlanningConfig internally
-    assert agent.planning_config is not None
-    assert agent.planning_enabled is True
-
-
-def test_agent_with_reasoning_and_max_attempts_backward_compat():
-    """Test agent with reasoning=True and max_reasoning_attempts (backward compatibility)."""
-    llm = LLM("gpt-4o-mini")
+def test_agent_with_reasoning(mock_llm_responses):
+    """Test agent with reasoning."""
+    llm = LLM("gpt-3.5-turbo")
 
     agent = Agent(
         role="Test Agent",
         goal="To test the reasoning feature",
-        backstory="I am a test agent.",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
         llm=llm,
         reasoning=True,
-        max_reasoning_attempts=5,
-        verbose=False,
-    )
-
-    # Should have created a PlanningConfig with max_attempts
-    assert agent.planning_config is not None
-    assert agent.planning_config.max_attempts == 5
-
-
-# =============================================================================
-# Tests for Agent.kickoff() with planning (uses AgentExecutor)
-# =============================================================================
-
-
-@pytest.mark.vcr()
-def test_agent_kickoff_with_planning():
-    """Test Agent.kickoff() with planning enabled generates a plan."""
-    llm = LLM("gpt-4o-mini")
-
-    agent = Agent(
-        role="Math Assistant",
-        goal="Help solve math problems step by step",
-        backstory="A helpful math tutor",
-        llm=llm,
-        planning_config=PlanningConfig(max_attempts=1),
-        verbose=False,
-    )
-
-    result = agent.kickoff("What is 15 + 27?")
-
-    assert result is not None
-    assert "42" in str(result)
-
-
-@pytest.mark.vcr()
-def test_agent_kickoff_without_planning():
-    """Test Agent.kickoff() without planning skips plan generation."""
-    llm = LLM("gpt-4o-mini")
-
-    agent = Agent(
-        role="Math Assistant",
-        goal="Help solve math problems",
-        backstory="A helpful assistant",
-        llm=llm,
-        # No planning_config = no planning
-        verbose=False,
-    )
-
-    result = agent.kickoff("What is 8 * 7?")
-
-    assert result is not None
-    assert "56" in str(result)
-
-
-@pytest.mark.vcr()
-def test_agent_kickoff_with_planning_disabled():
-    """Test Agent.kickoff() with planning explicitly disabled via planning=False."""
-    llm = LLM("gpt-4o-mini")
-
-    agent = Agent(
-        role="Math Assistant",
-        goal="Help solve math problems",
-        backstory="A helpful assistant",
-        llm=llm,
-        planning=False,  # Explicitly disable planning
-        verbose=False,
-    )
-
-    result = agent.kickoff("What is 100 / 4?")
-
-    assert result is not None
-    assert "25" in str(result)
-
-
-@pytest.mark.vcr()
-def test_agent_kickoff_multi_step_task_with_planning():
-    """Test Agent.kickoff() with a multi-step task that benefits from planning."""
-    llm = LLM("gpt-4o-mini")
-
-    agent = Agent(
-        role="Math Tutor",
-        goal="Solve multi-step math problems",
-        backstory="An expert tutor who explains step by step",
-        llm=llm,
-        planning_config=PlanningConfig(max_attempts=1, max_steps=5),
-        verbose=False,
-    )
-
-    # Task requires: find primes, sum them, then double
-    result = agent.kickoff(
-        "Find the first 3 prime numbers, add them together, then multiply by 2."
-    )
-
-    assert result is not None
-    # First 3 primes: 2, 3, 5 -> sum = 10 -> doubled = 20
-    assert "20" in str(result)
-
-
-# =============================================================================
-# Tests for Agent.execute_task() with planning (uses CrewAgentExecutor)
-# These test the legacy path via handle_reasoning()
-# =============================================================================
-
-
-@pytest.mark.vcr()
-def test_agent_execute_task_with_planning():
-    """Test Agent.execute_task() with planning via CrewAgentExecutor."""
-    llm = LLM("gpt-4o-mini")
-
-    agent = Agent(
-        role="Math Assistant",
-        goal="Help solve math problems",
-        backstory="A helpful math tutor",
-        llm=llm,
-        planning_config=PlanningConfig(max_attempts=1),
-        verbose=False,
+        verbose=True,
     )
 
     task = Task(
-        description="What is 9 + 11?",
-        expected_output="A number",
+        description="Simple math task: What's 2+2?",
+        expected_output="The answer should be a number.",
         agent=agent,
     )
 
+    agent.llm.call = lambda messages, *args, **kwargs: (
+        mock_llm_responses["ready"]
+        if any("create a detailed plan" in msg.get("content", "") for msg in messages)
+        else mock_llm_responses["execution"]
+    )
+
     result = agent.execute_task(task)
 
-    assert result is not None
-    assert "20" in str(result)
-    # Planning should be appended to task description
-    assert "Planning:" in task.description
+    assert result == mock_llm_responses["execution"]
+    assert "Reasoning Plan:" in task.description
 
 
-@pytest.mark.vcr()
-def test_agent_execute_task_without_planning():
-    """Test Agent.execute_task() without planning."""
-    llm = LLM("gpt-4o-mini")
+def test_agent_with_reasoning_not_ready_initially(mock_llm_responses):
+    """Test agent with reasoning that requires refinement."""
+    llm = LLM("gpt-3.5-turbo")
 
     agent = Agent(
-        role="Math Assistant",
-        goal="Help solve math problems",
-        backstory="A helpful assistant",
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
         llm=llm,
-        verbose=False,
+        reasoning=True,
+        max_reasoning_attempts=2,
+        verbose=True,
     )
 
     task = Task(
-        description="What is 12 * 3?",
-        expected_output="A number",
+        description="Complex math task: What's the derivative of x²?",
+        expected_output="The answer should be a mathematical expression.",
         agent=agent,
     )
 
+    call_count = [0]
+
+    def mock_llm_call(messages, *args, **kwargs):
+        if any(
+            "create a detailed plan" in msg.get("content", "") for msg in messages
+        ) or any("refine your plan" in msg.get("content", "") for msg in messages):
+            call_count[0] += 1
+            if call_count[0] == 1:
+                return mock_llm_responses["not_ready"]
+            return mock_llm_responses["ready_after_refine"]
+        return "2x"
+
+    agent.llm.call = mock_llm_call
+
     result = agent.execute_task(task)
 
-    assert result is not None
-    assert "36" in str(result)
-    # No planning should be added
-    assert "Planning:" not in task.description
+    assert result == "2x"
+    assert call_count[0] == 2  # Should have made 2 reasoning calls
+    assert "Reasoning Plan:" in task.description
 
 
-@pytest.mark.vcr()
-def test_agent_execute_task_with_planning_refine():
-    """Test Agent.execute_task() with planning that requires refinement."""
-    llm = LLM("gpt-4o-mini")
+def test_agent_with_reasoning_max_attempts_reached():
+    """Test agent with reasoning that reaches max attempts without being ready."""
+    llm = LLM("gpt-3.5-turbo")
 
     agent = Agent(
-        role="Math Tutor",
-        goal="Solve complex math problems step by step",
-        backstory="An expert tutor",
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
         llm=llm,
-        planning_config=PlanningConfig(max_attempts=2),
-        verbose=False,
+        reasoning=True,
+        max_reasoning_attempts=2,
+        verbose=True,
     )
 
     task = Task(
-        description="Calculate the area of a circle with radius 5 (use pi = 3.14)",
-        expected_output="The area as a number",
+        description="Complex math task: Solve the Riemann hypothesis.",
+        expected_output="A proof or disproof of the hypothesis.",
         agent=agent,
     )
 
+    call_count = [0]
+
+    def mock_llm_call(messages, *args, **kwargs):
+        if any(
+            "create a detailed plan" in msg.get("content", "") for msg in messages
+        ) or any("refine your plan" in msg.get("content", "") for msg in messages):
+            call_count[0] += 1
+            return f"Attempt {call_count[0]}: I need more time to think.\n\nNOT READY: I need to refine my plan further."
+        return "This is an unsolved problem in mathematics."
+
+    agent.llm.call = mock_llm_call
+
     result = agent.execute_task(task)
 
-    assert result is not None
-    # Area = pi * r^2 = 3.14 * 25 = 78.5
-    assert "78" in str(result) or "79" in str(result)
-    assert "Planning:" in task.description
+    assert result == "This is an unsolved problem in mathematics."
+    assert (
+        call_count[0] == 2
+    )  # Should have made exactly 2 reasoning calls (max_attempts)
+    assert "Reasoning Plan:" in task.description
+
+
+def test_agent_reasoning_error_handling():
+    """Test error handling during the reasoning process."""
+    llm = LLM("gpt-3.5-turbo")
+
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+    )
+
+    task = Task(
+        description="Task that will cause an error",
+        expected_output="Output that will never be generated",
+        agent=agent,
+    )
+
+    call_count = [0]
+
+    def mock_llm_call_error(*args, **kwargs):
+        call_count[0] += 1
+        if call_count[0] <= 2:  # First calls are for reasoning
+            raise Exception("LLM error during reasoning")
+        return "Fallback execution result"  # Return a value for task execution
+
+    agent.llm.call = mock_llm_call_error
+
+    result = agent.execute_task(task)
+
+    assert result == "Fallback execution result"
+    assert call_count[0] > 2  # Ensure we called the mock multiple times
+
+
+@pytest.mark.skip(reason="Test requires updates for native tool calling changes")
+def test_agent_with_function_calling():
+    """Test agent with reasoning using function calling."""
+    llm = LLM("gpt-3.5-turbo")
+
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        verbose=True,
+    )
+
+    task = Task(
+        description="Simple math task: What's 2+2?",
+        expected_output="The answer should be a number.",
+        agent=agent,
+    )
+
+    agent.llm.supports_function_calling = lambda: True
+
+    def mock_function_call(messages, *args, **kwargs):
+        if "tools" in kwargs:
+            return json.dumps(
+                {"plan": "I'll solve this simple math problem: 2+2=4.", "ready": True}
+            )
+        return "4"
+
+    agent.llm.call = mock_function_call
+
+    result = agent.execute_task(task)
+
+    assert result == "4"
+    assert "Reasoning Plan:" in task.description
+    assert "I'll solve this simple math problem: 2+2=4." in task.description
+
+
+@pytest.mark.skip(reason="Test requires updates for native tool calling changes")
+def test_agent_with_function_calling_fallback():
+    """Test agent with reasoning using function calling that falls back to text parsing."""
+    llm = LLM("gpt-3.5-turbo")
+
+    agent = Agent(
+        role="Test Agent",
+        goal="To test the reasoning feature",
+        backstory="I am a test agent created to verify the reasoning feature works correctly.",
+        llm=llm,
+        reasoning=True,
+        verbose=True,
+    )
+
+    task = Task(
+        description="Simple math task: What's 2+2?",
+        expected_output="The answer should be a number.",
+        agent=agent,
+    )
+
+    agent.llm.supports_function_calling = lambda: True
+
+    def mock_function_call(messages, *args, **kwargs):
+        if "tools" in kwargs:
+            return "Invalid JSON that will trigger fallback. READY: I am ready to execute the task."
+        return "4"
+
+    agent.llm.call = mock_function_call
+
+    result = agent.execute_task(task)
+
+    assert result == "4"
+    assert "Reasoning Plan:" in task.description
+    assert "Invalid JSON that will trigger fallback" in task.description

lib/crewai/tests/agents/test_lite_agent.py

@@ -359,34 +359,17 @@ def test_sets_flow_context_when_inside_flow():
 
 @pytest.mark.vcr()
 def test_guardrail_is_called_using_string():
-    """Test that a string guardrail triggers events and retries correctly.
-
-    Uses a callable guardrail that deterministically fails on the first
-    attempt and passes on the second. This tests the guardrail event
-    machinery (started/completed events, retry loop) without depending
-    on the LLM to comply with contradictory constraints.
-    """
     guardrail_events: dict[str, list] = defaultdict(list)
     from crewai.events.event_types import (
         LLMGuardrailCompletedEvent,
         LLMGuardrailStartedEvent,
     )
 
-    # Deterministic guardrail: fail first call, pass second
-    call_count = {"n": 0}
-
-    def fail_then_pass_guardrail(output):
-        call_count["n"] += 1
-        if call_count["n"] == 1:
-            return (False, "Missing required format — please use a numbered list")
-        return (True, output)
-
     agent = Agent(
         role="Sports Analyst",
-        goal="List the best soccer players",
-        backstory="You are an expert at gathering and organizing information.",
-        guardrail=fail_then_pass_guardrail,
-        guardrail_max_retries=3,
+        goal="Gather information about the best soccer players",
+        backstory="""You are an expert at gathering and organizing information. You carefully collect details and present them in a structured way.""",
+        guardrail="""Only include Brazilian players, both women and men""",
     )
 
     condition = threading.Condition()
@@ -405,7 +388,7 @@ def test_guardrail_is_called_using_string():
             guardrail_events["completed"].append(event)
             condition.notify()
 
-    result = agent.kickoff(messages="Top 5 best soccer players in the world?")
+    result = agent.kickoff(messages="Top 10 best players in the world?")
 
     with condition:
         success = condition.wait_for(
@@ -676,7 +659,7 @@ def test_agent_kickoff_with_platform_tools(mock_get, mock_post):
 
 
 @patch.dict("os.environ", {"EXA_API_KEY": "test_exa_key"})
-@patch("crewai.agent.Agent._get_external_mcp_tools")
+@patch("crewai.agent.Agent.get_mcp_tools")
 @pytest.mark.vcr()
 def test_agent_kickoff_with_mcp_tools(mock_get_mcp_tools):
     """Test that Agent.kickoff() properly integrates MCP tools with LiteAgent"""
@@ -708,7 +691,7 @@ def test_agent_kickoff_with_mcp_tools(mock_get_mcp_tools):
     assert result.raw is not None
 
     # Verify MCP tools were retrieved
-    mock_get_mcp_tools.assert_called_once_with("https://mcp.exa.ai/mcp?api_key=test_exa_key&profile=research")
+    mock_get_mcp_tools.assert_called_once_with(["https://mcp.exa.ai/mcp?api_key=test_exa_key&profile=research"])
 
 
 # ============================================================================
@@ -1153,6 +1136,7 @@ def test_lite_agent_memory_instance_recall_and_save_called():
         successful_requests=1,
     )
     mock_memory = Mock()
+    mock_memory._read_only = False
     mock_memory.recall.return_value = []
     mock_memory.extract_memories.return_value = ["Fact one.", "Fact two."]
 

lib/crewai/tests/agents/test_native_tool_calling.py

@@ -11,7 +11,7 @@ import os
 import threading
 import time
 from collections import Counter
-from unittest.mock import patch
+from unittest.mock import Mock, patch
 
 import pytest
 from pydantic import BaseModel, Field
@@ -1129,3 +1129,150 @@ class TestMaxUsageCountWithNativeToolCalling:
         # Verify the requested calls occurred while keeping usage bounded.
         assert tool.current_usage_count >= 2
         assert tool.current_usage_count <= tool.max_usage_count
+
+
+# =============================================================================
+# JSON Parse Error Handling Tests
+# =============================================================================
+
+
+class TestNativeToolCallingJsonParseError:
+    """Tests that malformed JSON tool arguments produce clear errors
+    instead of silently dropping all arguments."""
+
+    def _make_executor(self, tools: list[BaseTool]) -> "CrewAgentExecutor":
+        """Create a minimal CrewAgentExecutor with mocked dependencies."""
+        from crewai.agents.crew_agent_executor import CrewAgentExecutor
+        from crewai.tools.base_tool import to_langchain
+
+        structured_tools = to_langchain(tools)
+        mock_agent = Mock()
+        mock_agent.key = "test_agent"
+        mock_agent.role = "tester"
+        mock_agent.verbose = False
+        mock_agent.fingerprint = None
+        mock_agent.tools_results = []
+
+        mock_task = Mock()
+        mock_task.name = "test"
+        mock_task.description = "test"
+        mock_task.id = "test-id"
+
+        executor = object.__new__(CrewAgentExecutor)
+        executor.agent = mock_agent
+        executor.task = mock_task
+        executor.crew = Mock()
+        executor.tools = structured_tools
+        executor.original_tools = tools
+        executor.tools_handler = None
+        executor._printer = Mock()
+        executor.messages = []
+
+        return executor
+
+    def test_malformed_json_returns_parse_error(self) -> None:
+        """Malformed JSON args must return a descriptive error, not silently become {}."""
+
+        class CodeTool(BaseTool):
+            name: str = "execute_code"
+            description: str = "Run code"
+
+            def _run(self, code: str) -> str:
+                return f"ran: {code}"
+
+        tool = CodeTool()
+        executor = self._make_executor([tool])
+
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        malformed_json = '{"code": "print("hello")"}'
+
+        result = executor._execute_single_native_tool_call(
+            call_id="call_123",
+            func_name="execute_code",
+            func_args=malformed_json,
+            available_functions=available_functions,
+        )
+
+        assert "Failed to parse tool arguments as JSON" in result["result"]
+        assert tool.current_usage_count == 0
+
+    def test_valid_json_still_executes_normally(self) -> None:
+        """Valid JSON args should execute the tool as before."""
+
+        class CodeTool(BaseTool):
+            name: str = "execute_code"
+            description: str = "Run code"
+
+            def _run(self, code: str) -> str:
+                return f"ran: {code}"
+
+        tool = CodeTool()
+        executor = self._make_executor([tool])
+
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        valid_json = '{"code": "print(1)"}'
+
+        result = executor._execute_single_native_tool_call(
+            call_id="call_456",
+            func_name="execute_code",
+            func_args=valid_json,
+            available_functions=available_functions,
+        )
+
+        assert result["result"] == "ran: print(1)"
+
+    def test_dict_args_bypass_json_parsing(self) -> None:
+        """When func_args is already a dict, no JSON parsing occurs."""
+
+        class CodeTool(BaseTool):
+            name: str = "execute_code"
+            description: str = "Run code"
+
+            def _run(self, code: str) -> str:
+                return f"ran: {code}"
+
+        tool = CodeTool()
+        executor = self._make_executor([tool])
+
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        result = executor._execute_single_native_tool_call(
+            call_id="call_789",
+            func_name="execute_code",
+            func_args={"code": "x = 42"},
+            available_functions=available_functions,
+        )
+
+        assert result["result"] == "ran: x = 42"
+
+    def test_schema_validation_catches_missing_args_on_native_path(self) -> None:
+        """The native function calling path should now enforce args_schema,
+        catching missing required fields before _run is called."""
+
+        class StrictTool(BaseTool):
+            name: str = "strict_tool"
+            description: str = "A tool with required args"
+
+            def _run(self, code: str, language: str) -> str:
+                return f"{language}: {code}"
+
+        tool = StrictTool()
+        executor = self._make_executor([tool])
+
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        result = executor._execute_single_native_tool_call(
+            call_id="call_schema",
+            func_name="strict_tool",
+            func_args={"code": "print(1)"},
+            available_functions=available_functions,
+        )
+
+        assert "Error" in result["result"]
+        assert "validation failed" in result["result"].lower() or "missing" in result["result"].lower()

lib/crewai/tests/cassettes/TestAgentMultimodalAnthropic.test_pdf_file[anthropic-claude-3-5-haiku-20241022].yaml

@@ -1,9 +1,15 @@
 interactions:
 - request:
     body: '{"max_tokens":4096,"messages":[{"role":"user","content":[{"type":"text","text":"\nCurrent
-      Task: What type of document is this?\n\nProvide your complete response:"},{"type":"document","source":{"type":"base64","media_type":"application/pdf","data":"JVBERi0xLjQKMSAwIG9iaiA8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4gZW5kb2JqCjIgMCBvYmogPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4gZW5kb2JqCjMgMCBvYmogPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSA+PiBlbmRvYmoKeHJlZgowIDQKMDAwMDAwMDAwMCA2NTUzNSBmCjAwMDAwMDAwMDkgMDAwMDAgbgowMDAwMDAwMDU4IDAwMDAwIG4KMDAwMDAwMDExNSAwMDAwMCBuCnRyYWlsZXIgPDwgL1NpemUgNCAvUm9vdCAxIDAgUiA+PgpzdGFydHhyZWYKMTk2CiUlRU9GCg=="},"cache_control":{"type":"ephemeral"}}]}],"model":"claude-3-5-haiku-20241022","stop_sequences":["\nObservation:"],"stream":false,"system":"You
+      Task: What type of document is this?\n\nBegin! This is VERY important to you,
+      use the tools available and give your best Final Answer, your job depends on
+      it!\n\nThought:"},{"type":"document","source":{"type":"base64","media_type":"application/pdf","data":"JVBERi0xLjQKMSAwIG9iaiA8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4gZW5kb2JqCjIgMCBvYmogPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4gZW5kb2JqCjMgMCBvYmogPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSA+PiBlbmRvYmoKeHJlZgowIDQKMDAwMDAwMDAwMCA2NTUzNSBmCjAwMDAwMDAwMDkgMDAwMDAgbgowMDAwMDAwMDU4IDAwMDAwIG4KMDAwMDAwMDExNSAwMDAwMCBuCnRyYWlsZXIgPDwgL1NpemUgNCAvUm9vdCAxIDAgUiA+PgpzdGFydHhyZWYKMTk2CiUlRU9GCg=="},"cache_control":{"type":"ephemeral"}}]}],"model":"claude-3-5-haiku-20241022","stop_sequences":["\nObservation:"],"stream":false,"system":"You
       are File Analyst. Expert at analyzing various file types.\nYour personal goal
-      is: Analyze and describe files accurately"}'
+      is: Analyze and describe files accurately\nTo give my best complete final answer
+      to the task respond using the exact following format:\n\nThought: I now can
+      give a great answer\nFinal Answer: Your final answer must be the great and the
+      most complete as possible, it must be outcome described.\n\nI MUST use these
+      formats, my job depends on it!"}'
     headers:
       User-Agent:
       - X-USER-AGENT-XXX
@@ -16,7 +22,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '950'
+      - '1351'
       content-type:
       - application/json
       host:
@@ -32,35 +38,35 @@ interactions:
       x-stainless-os:
       - X-STAINLESS-OS-XXX
       x-stainless-package-version:
-      - 0.73.0
+      - 0.71.1
       x-stainless-retry-count:
       - '0'
       x-stainless-runtime:
       - CPython
       x-stainless-runtime-version:
-      - 3.13.3
+      - 3.12.10
       x-stainless-timeout:
       - NOT_GIVEN
     method: POST
     uri: https://api.anthropic.com/v1/messages
   response:
     body:
-      string: '{"model":"claude-3-5-haiku-20241022","id":"msg_01C8ZkZMunUVDUDd8mh1r1We","type":"message","role":"assistant","content":[{"type":"text","text":"I
-        apologize, but the image appears to be completely blank or white. Without
-        any visible text, graphics, or distinguishing features, I cannot determine
-        the type of document. The file is a PDF, but the content page seems to be
-        empty or failed to render properly."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":1658,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":58,"service_tier":"standard","inference_geo":"not_available"}}'
+      string: '{"model":"claude-3-5-haiku-20241022","id":"msg_01AcygCF93tRhc7A3bfXMqe7","type":"message","role":"assistant","content":[{"type":"text","text":"Thought:
+        I can see this is a PDF document, but the image appears to be completely white
+        or blank. Without any visible content, I cannot definitively determine the
+        specific type of document.\n\nFinal Answer: The document is a PDF file, but
+        the provided image shows a blank white page with no discernible content or
+        text. More information or a clearer image would be needed to identify the
+        precise type of document."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":1750,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":89,"service_tier":"standard"}}'
     headers:
       CF-RAY:
       - CF-RAY-XXX
       Connection:
       - keep-alive
-      Content-Security-Policy:
-      - CSP-FILTERED
       Content-Type:
       - application/json
       Date:
-      - Thu, 12 Feb 2026 19:30:55 GMT
+      - Fri, 23 Jan 2026 19:08:04 GMT
       Server:
       - cloudflare
       Transfer-Encoding:
@@ -86,7 +92,7 @@ interactions:
       anthropic-ratelimit-requests-remaining:
       - '3999'
       anthropic-ratelimit-requests-reset:
-      - '2026-02-12T19:30:53Z'
+      - '2026-01-23T19:08:01Z'
       anthropic-ratelimit-tokens-limit:
       - ANTHROPIC-RATELIMIT-TOKENS-LIMIT-XXX
       anthropic-ratelimit-tokens-remaining:
@@ -100,112 +106,7 @@ interactions:
       strict-transport-security:
       - STS-XXX
       x-envoy-upstream-service-time:
-      - '2129'
-    status:
-      code: 200
-      message: OK
-- request:
-    body: '{"max_tokens":4096,"messages":[{"role":"user","content":[{"type":"text","text":"\nCurrent
-      Task: What type of document is this?\n\nProvide your complete response:"},{"type":"document","source":{"type":"base64","media_type":"application/pdf","data":"JVBERi0xLjQKMSAwIG9iaiA8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4gZW5kb2JqCjIgMCBvYmogPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4gZW5kb2JqCjMgMCBvYmogPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSA+PiBlbmRvYmoKeHJlZgowIDQKMDAwMDAwMDAwMCA2NTUzNSBmCjAwMDAwMDAwMDkgMDAwMDAgbgowMDAwMDAwMDU4IDAwMDAwIG4KMDAwMDAwMDExNSAwMDAwMCBuCnRyYWlsZXIgPDwgL1NpemUgNCAvUm9vdCAxIDAgUiA+PgpzdGFydHhyZWYKMTk2CiUlRU9GCg=="},"cache_control":{"type":"ephemeral"}}]}],"model":"claude-3-5-haiku-20241022","stop_sequences":["\nObservation:"],"stream":false,"system":"You
-      are File Analyst. Expert at analyzing various file types.\nYour personal goal
-      is: Analyze and describe files accurately"}'
-    headers:
-      User-Agent:
-      - X-USER-AGENT-XXX
-      accept:
-      - application/json
-      accept-encoding:
-      - ACCEPT-ENCODING-XXX
-      anthropic-version:
-      - '2023-06-01'
-      connection:
-      - keep-alive
-      content-length:
-      - '950'
-      content-type:
-      - application/json
-      host:
-      - api.anthropic.com
-      x-api-key:
-      - X-API-KEY-XXX
-      x-stainless-arch:
-      - X-STAINLESS-ARCH-XXX
-      x-stainless-async:
-      - 'false'
-      x-stainless-lang:
-      - python
-      x-stainless-os:
-      - X-STAINLESS-OS-XXX
-      x-stainless-package-version:
-      - 0.73.0
-      x-stainless-retry-count:
-      - '0'
-      x-stainless-runtime:
-      - CPython
-      x-stainless-runtime-version:
-      - 3.13.3
-      x-stainless-timeout:
-      - NOT_GIVEN
-    method: POST
-    uri: https://api.anthropic.com/v1/messages
-  response:
-    body:
-      string: '{"model":"claude-3-5-haiku-20241022","id":"msg_013jb7edagayZxqGs6ioACyU","type":"message","role":"assistant","content":[{"type":"text","text":"I
-        apologize, but the image appears to be completely blank or white. There are
-        no visible contents or text that I can analyze to determine the type of document.
-        Without any discernible information, I cannot definitively state what type
-        of document this is."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":1658,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":55,"service_tier":"standard","inference_geo":"not_available"}}'
-    headers:
-      CF-RAY:
-      - CF-RAY-XXX
-      Connection:
-      - keep-alive
-      Content-Security-Policy:
-      - CSP-FILTERED
-      Content-Type:
-      - application/json
-      Date:
-      - Thu, 12 Feb 2026 19:30:58 GMT
-      Server:
-      - cloudflare
-      Transfer-Encoding:
-      - chunked
-      X-Robots-Tag:
-      - none
-      anthropic-organization-id:
-      - ANTHROPIC-ORGANIZATION-ID-XXX
-      anthropic-ratelimit-input-tokens-limit:
-      - ANTHROPIC-RATELIMIT-INPUT-TOKENS-LIMIT-XXX
-      anthropic-ratelimit-input-tokens-remaining:
-      - ANTHROPIC-RATELIMIT-INPUT-TOKENS-REMAINING-XXX
-      anthropic-ratelimit-input-tokens-reset:
-      - ANTHROPIC-RATELIMIT-INPUT-TOKENS-RESET-XXX
-      anthropic-ratelimit-output-tokens-limit:
-      - ANTHROPIC-RATELIMIT-OUTPUT-TOKENS-LIMIT-XXX
-      anthropic-ratelimit-output-tokens-remaining:
-      - ANTHROPIC-RATELIMIT-OUTPUT-TOKENS-REMAINING-XXX
-      anthropic-ratelimit-output-tokens-reset:
-      - ANTHROPIC-RATELIMIT-OUTPUT-TOKENS-RESET-XXX
-      anthropic-ratelimit-requests-limit:
-      - '4000'
-      anthropic-ratelimit-requests-remaining:
-      - '3999'
-      anthropic-ratelimit-requests-reset:
-      - '2026-02-12T19:30:56Z'
-      anthropic-ratelimit-tokens-limit:
-      - ANTHROPIC-RATELIMIT-TOKENS-LIMIT-XXX
-      anthropic-ratelimit-tokens-remaining:
-      - ANTHROPIC-RATELIMIT-TOKENS-REMAINING-XXX
-      anthropic-ratelimit-tokens-reset:
-      - ANTHROPIC-RATELIMIT-TOKENS-RESET-XXX
-      cf-cache-status:
-      - DYNAMIC
-      request-id:
-      - REQUEST-ID-XXX
-      strict-transport-security:
-      - STS-XXX
-      x-envoy-upstream-service-time:
-      - '2005'
+      - '2837'
     status:
       code: 200
       message: OK