Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

feat(llm): re-resolve llm_overlay after input interpolation rewrites an agent's role (#7518)

João Mourac3f83cd86660
diff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.py
index 60a0dc2db..3a43cee93 100644
--- a/lib/crewai/src/crewai/agent/core.py
+++ b/lib/crewai/src/crewai/agent/core.py
@@ -79,7 +79,7 @@ from crewai.hooks.dispatch import HookAborted
from crewai.knowledge.knowledge import Knowledge
from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
from crewai.lite_agent_output import LiteAgentOutput
-from crewai.llm_overlay import overlay_model_for
+from crewai.llm_overlay import active as overlay_active, overlay_model_for
from crewai.llms.base_llm import BaseLLM
from crewai.mcp.config import MCPServerConfig
from crewai.rag.embeddings.types import EmbedderConfig
@@ -114,7 +114,7 @@ from crewai.utilities.env import get_env_context
from crewai.utilities.guardrail import process_guardrail, serialize_guardrail_for_json
from crewai.utilities.guardrail_types import GuardrailCallable, GuardrailType
from crewai.utilities.i18n import I18N_DEFAULT
-from crewai.utilities.llm_utils import create_llm
+from crewai.utilities.llm_utils import create_llm, create_llm_like
from crewai.utilities.prompts import Prompts, StandardPromptResult, SystemPromptResult
from crewai.utilities.pydantic_schema_utils import generate_model_description
from crewai.utilities.string_utils import sanitize_tool_name
@@ -245,6 +245,14 @@ class Agent(BaseAgent):
model_config = ConfigDict()
_times_executed: int = PrivateAttr(default=0)
+ # The construction-time ``llm_overlay`` read happened; see post_init_setup.
+ _overlay_read: bool = PrivateAttr(default=False)
+ # The llm the agent was declared with, resolved before any overlay read: what
+ # an overlay swap is configured like, and what a role outside it runs on.
+ _declared_llm: BaseLLM | None = PrivateAttr(default=None)
+ # The instance the overlay built and put on ``llm``; any other ``llm`` found
+ # there later was assigned by the caller and is the declared one from then on.
+ _overlay_built: BaseLLM | None = PrivateAttr(default=None)
_mcp_resolver: MCPToolResolver | None = PrivateAttr(default=None)
_last_messages: list[LLMMessage] = PrivateAttr(default_factory=list)
max_execution_time: int | None = Field(
@@ -401,7 +409,25 @@ class Agent(BaseAgent):
@model_validator(mode="after")
def post_init_setup(self) -> Self:
"""Initialize LLM, executor, code tools, and skills after model creation."""
- self.llm = create_llm(overlay_model_for(self.role) or self.llm)
+ if self._overlay_read:
+ # A re-validation of an existing instance — the event bus registers
+ # an agent in its RuntimeState the first time it emits, which runs
+ # this validator again on the same object. The overlay was read when
+ # the agent was built (and again by interpolate_inputs if its role
+ # changed); reading it once more here would replace an llm the agent
+ # already runs on, and drop state set on it such as ``stream``.
+ self.llm = create_llm(self.llm)
+ else:
+ declared = create_llm(self.llm)
+ self._declared_llm = declared
+ overlay_model = overlay_model_for(self.role)
+ if overlay_model:
+ self.llm = self._overlay_built = create_llm_like(
+ overlay_model, declared
+ )
+ else:
+ self.llm = declared
+ self._overlay_read = True
if self.function_calling_llm and not isinstance(
self.function_calling_llm, BaseLLM
):
@@ -447,6 +473,78 @@ class Agent(BaseAgent):
"""Check if planning is enabled for this agent."""
return self.planning_config is not None or self.planning
+ def _llm_for_copy(self) -> Any:
+ """Inside an ``llm_overlay`` block a copy is built from the declared llm.
+
+ ``Crew.copy`` — ``kickoff_for_each``, ``train``, ``test`` — copies every
+ agent before its input is interpolated. Built from the llm this agent
+ currently runs on, a copy would record a model the overlay mapped as its
+ declared one and never revert on a miss; built from the declared llm, its
+ construction resolves the overlay for its own role like any agent built
+ inside the block. Outside any block a copy keeps the llm this agent runs
+ on.
+ """
+ if overlay_active.get() is not None:
+ declared = self._declared_now()
+ if declared is not None:
+ return declared
+ return self.llm
+
+ def interpolate_inputs(self, inputs: dict[str, Any]) -> None:
+ """Interpolate inputs, then re-resolve the ``llm_overlay`` if the role changed.
+
+ A role declared as a template (``"Researcher for {repo}"``) is not a
+ key of an overlay written for the text a trace records until a kickoff
+ fills the placeholders in, and that happens after ``post_init_setup``
+ resolved ``llm``. So when interpolation rewrites the role inside an
+ active overlay, the overlay is looked up again with the new text: a
+ key sets ``llm`` to the mapped model, built with the declared llm's
+ configuration (``create_llm_like``); a miss puts the declared ``llm``
+ instance back, so a ``Crew`` reused for another input never keeps a
+ previous role's model. Outside any block the rewrite changes nothing.
+ A role the rewrite did not change is not looked up again —
+ construction's resolution stands, and its ``llm`` instance is kept.
+
+ The ``llm`` the agent ends up on inherits the streaming flag of the
+ one it replaces: ``Crew.kickoff(stream=True)`` sets ``agent.llm.stream``
+ before it interpolates. Two things resolved from ``llm`` before kickoff
+ do NOT follow the swap — a task's string guardrail LLM (built with the
+ Task) and the crew_creation telemetry span; a crew ``Memory`` built at
+ kickoff does.
+
+ The executor sees the new ``llm`` because it binds ``self.llm`` when a
+ task runs, after kickoff has interpolated: ``execute_task`` ->
+ ``_finalize_task_prompt`` -> ``prepare_tools`` ->
+ ``create_agent_executor``, which assigns ``self.llm`` to the executor
+ on every task (``_update_executor_parameters`` once it exists).
+ """
+ role_before = self.role
+ super().interpolate_inputs(inputs)
+ if self.role == role_before or overlay_active.get() is None:
+ return
+ previous = self.llm
+ declared = self._declared_now()
+ overlay_model = overlay_model_for(self.role)
+ if overlay_model:
+ self.llm = self._overlay_built = create_llm_like(overlay_model, declared)
+ else:
+ self.llm = declared
+ if isinstance(previous, BaseLLM) and isinstance(self.llm, BaseLLM):
+ self.llm.stream = previous.stream
+
+ def _declared_now(self) -> BaseLLM | None:
+ """The llm this agent is declared with, as of now.
+
+ Construction's ``create_llm(self.llm)`` unless the caller assigned
+ another ``llm`` since: whatever is on ``llm`` that the overlay did not
+ put there is the caller's, and a miss reverts to it. ``llm`` is a plain
+ field, so what the caller assigned may be a model string or ``None``;
+ it is resolved the way construction resolves it.
+ """
+ if self.llm is None or self.llm is not self._overlay_built:
+ self._declared_llm = create_llm(self.llm)
+ return self._declared_llm
+
def _setup_agent_executor(self) -> None:
"""Initialize the agent's tools handler and optional tool cache.
diff --git a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py b/lib/crewai/src/crewai/agents/agent_builder/base_agent.py
index a4b0e6675..46d858287 100644
--- a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py
+++ b/lib/crewai/src/crewai/agents/agent_builder/base_agent.py
@@ -720,7 +720,7 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
"actions",
}
- existing_llm = shallow_copy(self.llm)
+ existing_llm = shallow_copy(self._llm_for_copy())
copied_knowledge = shallow_copy(self.knowledge)
copied_knowledge_storage = shallow_copy(self.knowledge_storage)
existing_knowledge_sources = None
@@ -763,6 +763,10 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
knowledge_storage=copied_knowledge_storage,
)
+ def _llm_for_copy(self) -> Any:
+ """The llm a copy is built with; ``Agent`` overrides it for ``llm_overlay``."""
+ return self.llm
+
def interpolate_inputs(self, inputs: dict[str, Any]) -> None:
"""Interpolate inputs into the agent description and backstory."""
if self._original_role is None:
diff --git a/lib/crewai/src/crewai/lite_agent.py b/lib/crewai/src/crewai/lite_agent.py
index 3f3d40266..0fa370a9c 100644
--- a/lib/crewai/src/crewai/lite_agent.py
+++ b/lib/crewai/src/crewai/lite_agent.py
@@ -102,7 +102,7 @@ from crewai.utilities.converter import (
from crewai.utilities.guardrail import process_guardrail, serialize_guardrail_for_json
from crewai.utilities.guardrail_types import GuardrailCallable, GuardrailType
from crewai.utilities.i18n import I18N_DEFAULT
-from crewai.utilities.llm_utils import create_llm
+from crewai.utilities.llm_utils import create_llm, create_llm_like
from crewai.utilities.pydantic_schema_utils import (
generate_model_description,
serialize_model_class,
@@ -320,7 +320,11 @@ class LiteAgent(FlowTrackable, BaseModel):
@model_validator(mode="after")
def setup_llm(self) -> Self:
"""Set up the LLM and other components after initialization."""
- self.llm = create_llm(overlay_model_for(self.role) or self.llm)
+ declared = create_llm(self.llm)
+ overlay_model = overlay_model_for(self.role)
+ self.llm = (
+ create_llm_like(overlay_model, declared) if overlay_model else declared
+ )
if not isinstance(self.llm, BaseLLM):
raise ValueError(
f"Expected LLM instance of type BaseLLM, got {type(self.llm).__name__}"
diff --git a/lib/crewai/src/crewai/llm.py b/lib/crewai/src/crewai/llm.py
index 64d86403e..678055e89 100644
--- a/lib/crewai/src/crewai/llm.py
+++ b/lib/crewai/src/crewai/llm.py
@@ -11,6 +11,7 @@ from typing import (
Any,
Final,
Literal,
+ NamedTuple,
TypedDict,
cast,
)
@@ -369,6 +370,15 @@ class AccumulatedToolArgs(BaseModel):
function: FunctionArgs = Field(default_factory=FunctionArgs)
+class _Route(NamedTuple):
+ """Where ``LLM(model, **kwargs)`` goes; see :meth:`LLM._resolve_route`."""
+
+ provider: str
+ model: str
+ native_class: type[BaseLLM] | None
+ custom_openai: bool
+
+
class LLM(BaseLLM):
llm_type: Literal["litellm"] = "litellm"
completion_cost: float | None = None
@@ -412,84 +422,23 @@ class LLM(BaseLLM):
if not model or not isinstance(model, str):
raise ValueError("Model must be a non-empty string")
- custom_openai = bool(kwargs.pop("custom_openai", False))
- custom_openai_route = custom_openai
- explicit_provider = kwargs.get("provider")
-
- if custom_openai:
- if not cls._has_custom_openai_endpoint(kwargs):
- raise ValueError(
- "custom_openai=True requires base_url, api_base, "
- "OPENAI_BASE_URL, or OPENAI_API_BASE"
- )
- provider = "openai"
- use_native = True
- prefix, separator, model_part = model.partition("/")
- model_string = (
- model_part if separator and prefix.lower() == "openai" else model
- )
- elif explicit_provider:
- provider = explicit_provider
- use_native = True
- model_string = model
- elif "/" in model:
- prefix, _, model_part = model.partition("/")
-
- provider_mapping = {
- "openai": "openai",
- "anthropic": "anthropic",
- "claude": "anthropic",
- "azure": "azure",
- "azure_openai": "azure",
- "google": "gemini",
- "gemini": "gemini",
- "bedrock": "bedrock",
- "aws": "bedrock",
- "openrouter": "openrouter",
- "deepseek": "deepseek",
- "ollama": "ollama",
- "ollama_chat": "ollama_chat",
- "hosted_vllm": "hosted_vllm",
- "cerebras": "cerebras",
- "dashscope": "dashscope",
- "snowflake": "snowflake",
- }
-
- canonical_provider = provider_mapping.get(prefix.lower())
-
- valid_native_model = bool(
- canonical_provider
- and cls._validate_model_in_constants(model_part, canonical_provider)
- )
- custom_openai_route = bool(
- canonical_provider == "openai"
- and not valid_native_model
- and cls._has_custom_openai_base_url(kwargs)
- )
-
- if canonical_provider and (valid_native_model or custom_openai_route):
- provider = canonical_provider
- use_native = True
- model_string = model_part
- else:
- provider = prefix
- use_native = False
- model_string = model_part
- else:
- provider = cls._infer_provider_from_model(model)
- use_native = True
- model_string = model
-
- native_class = cls._get_native_provider(provider) if use_native else None
- if native_class and not is_litellm and provider in SUPPORTED_NATIVE_PROVIDERS:
+ route = cls._resolve_route(model, kwargs)
+ if route.native_class is not None and not is_litellm:
try:
- # Remove 'provider' from kwargs if it exists to avoid duplicate keyword argument
- kwargs_copy = {k: v for k, v in kwargs.items() if k != "provider"}
- if custom_openai_route:
+ # The route decided 'provider' and 'custom_openai'; the caller's
+ # values must not reach the native class a second time.
+ kwargs_copy = {
+ k: v
+ for k, v in kwargs.items()
+ if k not in ("provider", "custom_openai")
+ }
+ if route.custom_openai:
kwargs_copy["custom_openai"] = True
return cast(
Self,
- native_class(model=model_string, provider=provider, **kwargs_copy),
+ route.native_class(
+ model=route.model, provider=route.provider, **kwargs_copy
+ ),
)
except NotImplementedError:
raise
@@ -588,6 +537,91 @@ class LLM(BaseLLM):
return False
+ @classmethod
+ def _resolve_route(cls, model: str, kwargs: dict[str, Any]) -> _Route:
+ """Decide which class ``LLM(model, **kwargs)`` constructs, without building it.
+
+ The routing ``__new__`` applies, in its priority order: ``custom_openai``
+ forces the native OpenAI provider; an explicit ``provider`` names one;
+ a ``<prefix>/<model>`` string goes native when the prefix is a native
+ provider and the model is one it knows (or, for ``openai/``, when a
+ custom endpoint is configured); a bare model name infers its provider.
+ ``native_class`` is ``None`` when the call falls back to LiteLLM.
+ ``kwargs`` is read, never mutated.
+ """
+ custom_openai = bool(kwargs.get("custom_openai", False))
+ custom_openai_route = custom_openai
+ explicit_provider = kwargs.get("provider")
+
+ if custom_openai:
+ if not cls._has_custom_openai_endpoint(kwargs):
+ raise ValueError(
+ "custom_openai=True requires base_url, api_base, "
+ "OPENAI_BASE_URL, or OPENAI_API_BASE"
+ )
+ provider = "openai"
+ use_native = True
+ prefix, separator, model_part = model.partition("/")
+ model_string = (
+ model_part if separator and prefix.lower() == "openai" else model
+ )
+ elif explicit_provider:
+ provider = explicit_provider
+ use_native = True
+ model_string = model
+ elif "/" in model:
+ prefix, _, model_part = model.partition("/")
+
+ provider_mapping = {
+ "openai": "openai",
+ "anthropic": "anthropic",
+ "claude": "anthropic",
+ "azure": "azure",
+ "azure_openai": "azure",
+ "google": "gemini",
+ "gemini": "gemini",
+ "bedrock": "bedrock",
+ "aws": "bedrock",
+ "openrouter": "openrouter",
+ "deepseek": "deepseek",
+ "ollama": "ollama",
+ "ollama_chat": "ollama_chat",
+ "hosted_vllm": "hosted_vllm",
+ "cerebras": "cerebras",
+ "dashscope": "dashscope",
+ "snowflake": "snowflake",
+ }
+
+ canonical_provider = provider_mapping.get(prefix.lower())
+
+ valid_native_model = bool(
+ canonical_provider
+ and cls._validate_model_in_constants(model_part, canonical_provider)
+ )
+ custom_openai_route = bool(
+ canonical_provider == "openai"
+ and not valid_native_model
+ and cls._has_custom_openai_base_url(kwargs)
+ )
+
+ if canonical_provider and (valid_native_model or custom_openai_route):
+ provider = canonical_provider
+ use_native = True
+ model_string = model_part
+ else:
+ provider = prefix
+ use_native = False
+ model_string = model_part
+ else:
+ provider = cls._infer_provider_from_model(model)
+ use_native = True
+ model_string = model
+
+ native_class = cls._get_native_provider(provider) if use_native else None
+ if provider not in SUPPORTED_NATIVE_PROVIDERS:
+ native_class = None
+ return _Route(provider, model_string, native_class, custom_openai_route)
+
@classmethod
def _validate_model_in_constants(cls, model: str, provider: str) -> bool:
"""Validate if a model name exists in the provider's constants or matches provider patterns.
@@ -682,7 +716,7 @@ class LLM(BaseLLM):
return "openai"
@classmethod
- def _get_native_provider(cls, provider: str) -> type | None:
+ def _get_native_provider(cls, provider: str) -> type[BaseLLM] | None:
"""Get native provider class if available."""
if provider == "openai":
from crewai.llms.providers.openai.completion import OpenAICompletion
diff --git a/lib/crewai/src/crewai/llm_overlay.py b/lib/crewai/src/crewai/llm_overlay.py
index f077f23cf..1397052c7 100644
--- a/lib/crewai/src/crewai/llm_overlay.py
+++ b/lib/crewai/src/crewai/llm_overlay.py
@@ -6,16 +6,51 @@ an ``Agent`` or ``LiteAgent`` whose ``role`` is a key of the mapping is built
with the mapped model instead of its declared ``llm``. Roles that are not
keys, and every agent built outside the block, keep their own model.
+Roles are matched exactly, by the text they have when the overlay is read.
+An ``Agent`` is read when it is built, with its declared role, and read
+again when ``crew.kickoff(inputs=...)`` interpolates the inputs into that
+role and the text changes. The second read is what lets a role declared as
+a template (``"Researcher for {repo}"``, the YAML form of a ``CrewBase``
+crew) match a key written for the interpolated text, which is the role
+every trace records; the template itself is not a key at construction. A
+role the interpolation leaves unchanged is not read again. Inside a block,
+an agent runs on the model its current role maps to, and on its declared
+``llm`` when that role is not a key: a kickoff that interpolates to a role
+outside the mapping puts the declared ``llm`` instance back, so a ``Crew``
+reused across kickoffs with different inputs never bills a previous role's
+provider. Outside any block an interpolation changes nothing.
+
+A mapped model is built with the settings a caller configured on the
+declared ``llm`` (``crewai.utilities.llm_utils.create_llm_like``): generation
+and runtime settings — temperature, timeouts, token limits, stop sequences —
+when the new model's class has the field and accepts the value; credentials,
+endpoints and provider-specific settings only when the mapped model is on the
+same provider — another provider gets its own defaults and environment. What a
+provider derived from the model rather than took from the caller is derived
+again for the new model.
+
The overlay is a :class:`contextvars.ContextVar`, so it follows the calling
context, not the process. A plain ``threading.Thread`` started inside the
block does not see it: callers that run agents in their own threads must
propagate the context themselves, e.g.
-``contextvars.copy_context().run(build_and_run_agents)``.
+``contextvars.copy_context().run(build_and_run_agents)``. With
+``Crew(stream=True)``, ``kickoff`` returns a stream and runs the crew — and the
+kickoff-time read — when that stream is first iterated, in a copy of the
+context taken then: iterate it inside the block.
+
+Each ``Agent`` reads the overlay once when built and once more only if a
+kickoff rewrites its role; a re-validation of an existing agent (the event bus
+registers an agent when it first emits) does not read it again, so an agent
+built outside a block keeps its model through a kickoff inside one.
Example:
>>> with llm_overlay({"Researcher": "openai/gpt-4o"}):
... crew = build_crew() # the Researcher agent is built on gpt-4o
... crew.kickoff()
+
+ >>> with llm_overlay({"Researcher for crewAIInc/x": "openai/gpt-4o"}):
+ ... crew = build_crew() # role "Researcher for {repo}": declared llm
+ ... crew.kickoff(inputs={"repo": "crewAIInc/x"}) # now runs on gpt-4o
"""
from __future__ import annotations
diff --git a/lib/crewai/src/crewai/utilities/llm_utils.py b/lib/crewai/src/crewai/utilities/llm_utils.py
index 09507157c..57509bd67 100644
--- a/lib/crewai/src/crewai/utilities/llm_utils.py
+++ b/lib/crewai/src/crewai/utilities/llm_utils.py
@@ -2,6 +2,8 @@ import logging
import os
from typing import Any, Final
+from pydantic import ValidationError
+
from crewai.constants import DEFAULT_LLM_MODEL, ENV_VARS, LITELLM_PARAMS
from crewai.llm import LLM
from crewai.llms.base_llm import BaseLLM
@@ -87,6 +89,274 @@ def create_llm(
raise e
+# Generation and runtime settings: carried to any target whose class has the
+# field. Every one of them means the same thing on every provider that has it.
+GENERATION_SETTINGS: Final[tuple[str, ...]] = (
+ "temperature",
+ "top_p",
+ "top_k",
+ "max_tokens",
+ "max_completion_tokens",
+ "max_output_tokens",
+ "stop",
+ "seed",
+ "n",
+ "timeout",
+ "presence_penalty",
+ "frequency_penalty",
+ "logit_bias",
+ "logprobs",
+ "top_logprobs",
+ "reasoning_effort",
+ "callbacks",
+ "stream",
+ "prefer_upload",
+)
+
+# Carried only to a target on the same provider: credentials and endpoints,
+# how the SDK client is built, and settings whose type or meaning is the
+# provider's own. Another provider gets its own defaults and environment.
+PROVIDER_SETTINGS: Final[tuple[str, ...]] = (
+ # credentials and endpoints
+ "api_key",
+ "base_url",
+ "api_base",
+ "api_version",
+ "organization",
+ "project",
+ "endpoint",
+ "credential_scopes",
+ "location",
+ "use_vertexai",
+ "aws_access_key_id",
+ "aws_secret_access_key",
+ "aws_session_token",
+ "region_name",
+ # client construction
+ "max_retries",
+ "default_headers",
+ "default_query",
+ "client_params",
+ "interceptor",
+ # provider-typed settings
+ "response_format",
+ "thinking",
+ "tool_search",
+ "safety_settings",
+ "guardrail_config",
+ "additional_model_request_fields",
+ "additional_model_response_field_paths",
+ "tools",
+ "api",
+ "instructions",
+ "store",
+ "include",
+ "builtin_tools",
+ "parse_tool_outputs",
+ "auto_chain",
+ "auto_chain_reasoning",
+ "additional_params",
+)
+
+# Settings a provider fills from the model when the caller did not: Anthropic
+# sets ``max_tokens`` to the model's output cap. The new model derives its own.
+_MODEL_DERIVED: Final[frozenset[str]] = frozenset({"max_tokens"})
+
+# The names providers give the output-token cap. A cap configured under one
+# keeps its meaning under another when the target only has that one.
+_CAP_NAMES: Final[tuple[str, ...]] = (
+ "max_tokens",
+ "max_completion_tokens",
+ "max_output_tokens",
+)
+
+# Azure bakes the declared model's deployment into the endpoint at construction
+# (``https://<r>.openai.azure.com/openai/deployments/<model>``). The new model
+# must get its own deployment, so only the resource root is carried.
+_AZURE_DEPLOYMENT_PATH: Final[str] = "/openai/deployments/"
+
+# The declared endpoint, under the names the classes give it.
+_ENDPOINT_NAMES: Final[tuple[str, ...]] = ("base_url", "api_base")
+
+
+def create_llm_like(model: str, base: BaseLLM | None) -> BaseLLM:
+ """Build ``model`` configured like ``base``.
+
+ The instance is built through :class:`LLM`, so provider routing and every
+ setting derived from the model (context window, reasoning flags, the SDK
+ client, Azure's deployment path) are computed for the new model; what comes
+ from ``base`` is the configuration a caller put on it. :data:`GENERATION_SETTINGS`
+ go to any target whose class has the field. :data:`PROVIDER_SETTINGS` —
+ credentials, endpoints, client construction, provider-typed settings — go
+ only to a target on the same provider as ``base`` (:func:`_same_provider`):
+ a swap across providers must not send, say, an OpenAI key and proxy URL to
+ Anthropic. A value ``base``'s provider derived from its model rather than
+ took from the caller is not carried either (see :data:`_MODEL_DERIVED`), nor
+ are ``additional_params`` across classes (they are the class's own extra
+ kwargs). A declared llm that runs through LiteLLM swaps to LiteLLM, whatever
+ the new model's native class would be. An output-token cap keeps its meaning under the name the target has,
+ and a target on Anthropic gets ``temperature`` or ``top_p``, not both, which
+ current Claude models reject. A setting the target's field type refuses is
+ left off with a warning rather than raised: a swap happens inside a kickoff.
+
+ Args:
+ model: The model string for the new instance, as ``LLM(model=...)``
+ takes it.
+ base: The instance whose configuration to carry. ``None`` (or anything
+ that is not a :class:`BaseLLM`) contributes nothing.
+
+ Returns:
+ A new instance for ``model``; never ``base`` itself.
+ """
+ if not isinstance(base, BaseLLM):
+ return LLM(model=model)
+
+ # The declared endpoint decides where an unknown ``openai/`` model routes (a
+ # custom OpenAI-compatible endpoint), so the same-provider question is asked
+ # with it: a self-hosted model mapped to another model on the same endpoint
+ # must keep that endpoint.
+ route = LLM._resolve_route(model, _configured_settings(base, _ENDPOINT_NAMES))
+ carried = _configured_settings(base, GENERATION_SETTINGS)
+ if _same_provider(base, route):
+ carried.update(_configured_settings(base, PROVIDER_SETTINGS))
+ target = LLM._resolve_route(model, carried).native_class or LLM
+ if type(base) is LLM and base.is_litellm:
+ # The declared llm runs through LiteLLM — by the caller's choice or
+ # because no native class knew its model; either way that is the
+ # environment its callbacks and extra kwargs were written for.
+ target = LLM
+ carried["is_litellm"] = True
+ accepted = {
+ k: v
+ for k, v in carried.items()
+ if k in target.model_fields or k == "is_litellm"
+ }
+ if type(base) is not target:
+ accepted.pop("additional_params", None)
+ _carry_cap_under_the_targets_name(carried, accepted, target)
+ if route.provider == "anthropic" and "temperature" in accepted:
+ accepted.pop("top_p", None)
+ return _build(model, accepted)
+
+
+def _same_provider(base: BaseLLM, route: Any) -> bool:
+ """Whether ``route`` lands where ``base``'s credentials and endpoint belong.
+
+ A native class compares by class: an explicit ``provider=`` alias
+ (``azure_openai``, ``claude``, ``google``) names the same class, and a
+ user-defined :class:`BaseLLM` subclass is never a native one whatever
+ ``provider`` string it defaulted to. A LiteLLM :class:`LLM` compares by the
+ provider it resolved — to another LiteLLM route by the string, to a native
+ route by the class that string names.
+ """
+ if route.native_class is not None:
+ if type(base) is route.native_class:
+ # One class serves every OpenAI-compatible provider (OpenRouter,
+ # DeepSeek, Ollama, vLLM, …); each is its own vendor with its own
+ # endpoint and key, so there the provider string decides.
+ return not _serves_several_providers(route.native_class) or (
+ route.provider == base.provider
+ )
+ return (
+ type(base) is LLM
+ and LLM._get_native_provider(base.provider or "") is route.native_class
+ and (
+ not _serves_several_providers(route.native_class)
+ or route.provider == base.provider
+ )
+ )
+ return type(base) is LLM and route.provider == base.provider
+
+
+def _serves_several_providers(native_class: type[BaseLLM]) -> bool:
+ from crewai.llms.providers.openai_compatible.completion import (
+ OpenAICompatibleCompletion,
+ )
+
+ return native_class is OpenAICompatibleCompletion
+
+
+def _carry_cap_under_the_targets_name(
+ carried: dict[str, Any], accepted: dict[str, Any], target: type[BaseLLM]
+) -> None:
+ """Give a configured output-token cap the name ``target`` has for it."""
+ if any(name in accepted for name in _CAP_NAMES):
+ return
+ value = next((carried[name] for name in _CAP_NAMES if name in carried), None)
+ if value is None:
+ return
+ for name in _CAP_NAMES:
+ if name in target.model_fields:
+ accepted[name] = value
+ return
+
+
+def _build(model: str, settings: dict[str, Any]) -> BaseLLM:
+ """``LLM(model=..., **settings)``, without a setting the class refuses.
+
+ A name the target has can still reject the value (LiteLLM's ``logprobs`` is
+ an int, the OpenAI class's a bool). Such a setting is dropped, with a warning
+ naming it, and the build retried; anything but a validation error propagates.
+ """
+ try:
+ return LLM(model=model, **settings)
+ except (ValidationError, ImportError) as exc:
+ cause = exc if isinstance(exc, ValidationError) else exc.__cause__
+ if not isinstance(cause, ValidationError):
+ raise
+ rejected = {
+ str(err["loc"][0]) for err in cause.errors() if err.get("loc")
+ } & set(settings)
+ if not rejected:
+ raise
+ logger.warning(
+ "llm_overlay: %s does not accept %s from the declared llm; built without",
+ model,
+ ", ".join(sorted(rejected)),
+ )
+ return _build(model, {k: v for k, v in settings.items() if k not in rejected})
+
+
+def _configured_settings(base: BaseLLM, names: tuple[str, ...]) -> dict[str, Any]:
+ """The values of ``names`` a caller configured on ``base``.
+
+ Skips what is unset (``None``, an empty list or dict) and what ``base``'s
+ class derived from its model; an Azure endpoint is carried as its resource
+ root, without the deployment path the class appended for ``base``'s model.
+ """
+ settings: dict[str, Any] = {}
+ for name in names:
+ value = getattr(base, name, None)
+ if value is None or (isinstance(value, (list, dict)) and not value):
+ continue
+ if name in _MODEL_DERIVED and _derived_from_model(base, name):
+ continue
+ if name == "endpoint" and isinstance(value, str):
+ value = value.split(_AZURE_DEPLOYMENT_PATH)[0]
+ settings[name] = value
+ return settings
+
+
+def _derived_from_model(base: BaseLLM, name: str) -> bool:
+ """Whether ``base``'s class filled ``name`` from the model, not the caller.
+
+ Only a class that gives the field a default of its own can have derived it
+ (Anthropic's ``max_tokens``; elsewhere the default is ``None`` and the value
+ is the caller's, whatever the class's ``to_config_dict`` chooses to emit).
+ For such a class, ``to_config_dict`` is its own account of what was
+ configured: Anthropic leaves ``max_tokens`` out of it when the value is the
+ cap it derived for the model at construction — so a caller's value that
+ happens to equal that cap counts as derived, and the new model derives its
+ own; the conservative side.
+ """
+ field = type(base).model_fields.get(name)
+ if field is None or field.default is None:
+ return False
+ if type(base).to_config_dict is BaseLLM.to_config_dict:
+ return False
+ return name not in base.to_config_dict()
+
+
UNACCEPTED_ATTRIBUTES: Final[list[str]] = [
"AWS_ACCESS_KEY_ID",
"AWS_SECRET_ACCESS_KEY",
diff --git a/lib/crewai/tests/test_llm.py b/lib/crewai/tests/test_llm.py
index dde38fb9d..f90665cd3 100644
--- a/lib/crewai/tests/test_llm.py
+++ b/lib/crewai/tests/test_llm.py
@@ -1102,6 +1102,44 @@ def test_explicit_provider_kwarg_takes_priority():
assert llm2.provider == "openai"
+def test_resolve_route_decides_what_new_constructs():
+ """`LLM._resolve_route` is `__new__`'s routing, callable without building anything."""
+ from crewai.llms.providers.anthropic.completion import AnthropicCompletion
+ from crewai.llms.providers.openai.completion import OpenAICompletion
+
+ route = LLM._resolve_route("openai/gpt-4o", {})
+ assert (route.provider, route.model, route.native_class, route.custom_openai) == (
+ "openai",
+ "gpt-4o",
+ OpenAICompletion,
+ False,
+ )
+ assert (
+ LLM._resolve_route("claude/claude-haiku-4-5", {}).native_class
+ is AnthropicCompletion
+ )
+ assert LLM._resolve_route("claude/claude-haiku-4-5", {}).provider == "anthropic"
+
+ # An unknown openai/ model is LiteLLM's — unless a custom endpoint is configured.
+ plain = LLM._resolve_route("openai/not-a-known-model", {})
+ assert (plain.provider, plain.native_class) == ("openai", None)
+ custom = LLM._resolve_route(
+ "openai/not-a-known-model", {"base_url": "http://localhost:1/v1"}
+ )
+ assert (custom.native_class, custom.custom_openai) == (OpenAICompletion, True)
+
+ litellm_route = LLM._resolve_route("groq/llama-3.1-8b-instant", {})
+ assert (
+ litellm_route.provider,
+ litellm_route.model,
+ litellm_route.native_class,
+ ) == ("groq", "llama-3.1-8b-instant", None)
+ assert LLM._resolve_route("gpt-4o", {}).native_class is OpenAICompletion
+ kwargs = {"provider": "anthropic"}
+ assert LLM._resolve_route("some-model", kwargs).native_class is AnthropicCompletion
+ assert kwargs == {"provider": "anthropic"}
+
+
def test_validate_model_in_constants():
"""Test the _validate_model_in_constants method."""
# OpenAI models
diff --git a/lib/crewai/tests/test_llm_overlay.py b/lib/crewai/tests/test_llm_overlay.py
index 708ed89af..9a91a15a7 100644
--- a/lib/crewai/tests/test_llm_overlay.py
+++ b/lib/crewai/tests/test_llm_overlay.py
@@ -1,8 +1,10 @@
"""`llm_overlay` swaps an agent's model by role, for the calling context only.
-The overlay is read in exactly two places, the validators where `Agent` and
-`LiteAgent` resolve their `llm`, so these tests build agents and look at the
-model they end up with. No LLM is ever called.
+The overlay is read in exactly three places: the validators where `Agent` and
+`LiteAgent` resolve their `llm`, and `Agent.interpolate_inputs`, which looks the
+interpolated role up again because a templated role only becomes a key once a
+kickoff fills its placeholders in. So these tests build agents, interpolate
+them, and look at the model they end up with. No LLM is ever called.
`create_llm("openai/gpt-4o")` returns the native OpenAI provider, which strips
the `openai/` prefix, so the resolved model reads `"gpt-4o"`.
@@ -12,20 +14,45 @@ from __future__ import annotations
import contextvars
import threading
+from typing import Any
-from crewai import Agent
+from crewai import Agent, Crew, Task
from crewai.lite_agent import LiteAgent
+from crewai.llm import LLM
from crewai.llm_overlay import active, llm_overlay, overlay_model_for
+from crewai.llms.base_llm import BaseLLM
import pytest
+# Provider classes are compared by name: tests/llms/*/test_*.py delete a provider
+# module from sys.modules and re-import it, so a class object imported here can
+# be stale by the time a test in the same worker runs.
OVERLAY = {"Researcher": "openai/gpt-4o"}
+TEMPLATE_OVERLAY = {"Researcher for crewAIInc/x": "openai/gpt-4o"}
+
+# What a declared LLM carries beyond its model: an endpoint, a key, and
+# generation settings. `create_llm("<mapped model>")` would have none of them.
+CONFIGURATION: dict[str, Any] = {
+ "base_url": "http://localhost:9999/v1",
+ "api_key": "k",
+ "timeout": 42,
+ "temperature": 0.1,
+ "max_tokens": 77,
+}
def _agent(role: str) -> Agent:
return Agent(role=role, goal="g", backstory="b", llm="openai/gpt-4o-mini")
+def _configured_llm() -> LLM:
+ return LLM(model="openai/gpt-4o-mini", **CONFIGURATION)
+
+
+def _configuration_of(llm: Any) -> dict[str, Any]:
+ return {name: getattr(llm, name) for name in CONFIGURATION}
+
+
def test_matching_role_gets_the_overlay_model_others_keep_their_own() -> None:
with llm_overlay(OVERLAY):
researcher = _agent("Researcher")
@@ -87,3 +114,397 @@ def test_overlay_does_not_cross_plain_threads_unless_context_is_copied() -> None
assert seen["plain"] is None
assert seen["copied"] == OVERLAY
+
+
+def test_templated_role_matches_once_its_inputs_are_interpolated() -> None:
+ """The template is not a key at construction; the interpolated role is."""
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ assert agent.llm.model == "gpt-4o-mini"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+
+ assert agent.role == "Researcher for crewAIInc/x"
+ assert agent.llm.model == "gpt-4o"
+
+
+def test_interpolating_to_a_role_that_is_not_a_key_leaves_the_llm_alone() -> None:
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ declared = agent.llm
+ agent.interpolate_inputs({"repo": "crewAIInc/other"})
+
+ assert agent.role == "Researcher for crewAIInc/other"
+ assert agent.llm is declared and agent.llm.model == "gpt-4o-mini"
+
+
+def test_interpolating_outside_any_block_leaves_the_llm_alone() -> None:
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+
+ assert agent.role == "Researcher for crewAIInc/x"
+ assert agent.llm.model == "gpt-4o-mini"
+
+
+def test_a_template_role_that_is_itself_a_key_still_matches_at_construction() -> None:
+ with llm_overlay({"Researcher for {repo}": "openai/gpt-4o"}):
+ agent = _agent("Researcher for {repo}")
+
+ assert agent.llm.model == "gpt-4o"
+
+
+def test_each_interpolation_resolves_from_the_template() -> None:
+ """Each kickoff re-interpolates the original template; the model follows the role.
+
+ While the new role is a key it gets that key's model; when it is not, the
+ agent is back on the llm it was declared with — not on the previous
+ role's model.
+ """
+ mapping = {
+ "Researcher for crewAIInc/x": "openai/gpt-4o",
+ "Researcher for crewAIInc/y": "openai/gpt-4.1",
+ }
+ with llm_overlay(mapping):
+ agent = _agent("Researcher for {repo}")
+ declared = agent.llm
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/y"})
+ assert agent.role == "Researcher for crewAIInc/y"
+ assert agent.llm.model == "gpt-4.1"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/z"})
+ assert agent.role == "Researcher for crewAIInc/z"
+ assert agent.llm is declared and agent.llm.model == "gpt-4o-mini"
+
+
+def test_a_reused_crew_kicked_off_for_another_input_reverts_to_the_declared_llm() -> (
+ None
+):
+ """One `Crew` object, several kickoffs with different inputs, one block.
+
+ The mapped model applies while the interpolated role is a key. An input
+ that interpolates to a role the overlay says nothing about puts the very
+ declared instance back — the crew must not keep billing the previous
+ input's provider — and the next input that is a key maps again.
+ """
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ declared = agent.llm
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/y"})
+ assert agent.role == "Researcher for crewAIInc/y"
+ assert agent.llm is declared and agent.llm.model == "gpt-4o-mini"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o"
+
+
+def test_a_template_key_stops_matching_once_the_role_is_interpolated() -> None:
+ """The overlay maps the role's current text: the template is a key, the
+ interpolated text is not, so a kickoff inside the block puts the declared
+ llm back. Keys are written for the interpolated role — the one traces record."""
+ with llm_overlay({"Researcher for {repo}": "openai/gpt-4o"}):
+ agent = _agent("Researcher for {repo}")
+ assert agent.llm.model == "gpt-4o"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+
+ assert agent.role == "Researcher for crewAIInc/x"
+ assert agent.llm.model == "gpt-4o-mini"
+
+
+def test_outside_any_block_an_interpolation_that_changes_the_role_changes_nothing() -> (
+ None
+):
+ """Block semantics: with no overlay active there is nothing to re-resolve
+ against, so an agent built inside a block keeps the model it got there."""
+ with llm_overlay({"Researcher for {repo}": "openai/gpt-4o"}):
+ agent = _agent("Researcher for {repo}")
+ mapped = agent.llm
+ assert mapped.model == "gpt-4o"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+
+ assert agent.role == "Researcher for crewAIInc/x"
+ assert agent.llm is mapped
+
+
+def test_interpolating_with_no_inputs_does_not_touch_the_llm() -> None:
+ """`interpolate_inputs({})` rewrites nothing, so the overlay is not consulted."""
+ with llm_overlay({"Researcher for {repo}": "openai/gpt-4o"}):
+ agent = _agent("Writer for {repo}")
+ agent.interpolate_inputs({})
+
+ assert agent.role == "Writer for {repo}"
+ assert agent.llm.model == "gpt-4o-mini"
+
+
+def test_a_role_the_interpolation_leaves_unchanged_is_not_resolved_again() -> None:
+ """Construction's resolution stands: same model, same llm instance.
+
+ Without this an agent built OUTSIDE the block would pick the mapped model
+ up at a kickoff with inputs, and one built inside would lose the state set
+ on its llm between construction and kickoff.
+ """
+ with llm_overlay(OVERLAY):
+ inside = _agent("Researcher")
+ outside = _agent("Researcher")
+ with llm_overlay(OVERLAY):
+ inside_llm, outside_llm = inside.llm, outside.llm
+ inside.interpolate_inputs({"topic": "ai"})
+ outside.interpolate_inputs({"topic": "ai"})
+
+ assert inside.llm is inside_llm and inside.llm.model == "gpt-4o"
+ assert outside.llm is outside_llm and outside.llm.model == "gpt-4o-mini"
+
+
+def test_the_streaming_flag_survives_the_kickoff_time_swap() -> None:
+ """`Crew.kickoff(stream=True)` sets `agent.llm.stream` before it interpolates."""
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ agent.llm.stream = True
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+
+ assert agent.llm.model == "gpt-4o" and agent.llm.stream is True
+
+
+def test_the_streaming_flag_of_the_replaced_instance_follows_swap_and_revert() -> None:
+ """`Crew.kickoff(stream=True)` flags the instance the agent runs on at that
+ moment; whatever the interpolation then puts in its place must carry it."""
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ declared = agent.llm
+
+ # Kickoff 1 does not stream.
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o" and agent.llm.stream is False
+
+ # Kickoff 2 streams — the flag lands on the gpt-4o instance — and its
+ # input interpolates to a role that is not a key.
+ agent.llm.stream = True
+ agent.interpolate_inputs({"repo": "crewAIInc/y"})
+ assert agent.llm is declared and declared.stream is True
+
+ # Kickoff 3 is back on the key.
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o" and agent.llm.stream is True
+
+
+def test_a_same_provider_swap_keeps_the_declared_configuration() -> None:
+ """The mapped model is built like the declared llm, not from a bare string.
+
+ A new instance of the same class, so everything derived from the model is
+ computed for the new one; the endpoint, key and generation settings the
+ caller put on the declared llm come along, all the way into the SDK client.
+ """
+ declared = _configured_llm()
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = Agent(
+ role="Researcher for {repo}", goal="g", backstory="b", llm=declared
+ )
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+
+ swapped = agent.llm
+ assert swapped is not declared and type(swapped).__name__ == "OpenAICompletion"
+ assert swapped.model == "gpt-4o" and declared.model == "gpt-4o-mini"
+ assert _configuration_of(swapped) == CONFIGURATION
+ assert str(swapped._client.base_url) == "http://localhost:9999/v1/"
+ assert swapped._client.timeout == 42
+
+
+def test_a_cross_provider_swap_carries_settings_but_not_credentials() -> None:
+ """Generation settings mean the same thing everywhere; an endpoint and a
+ key belong to the provider they were issued for. The Anthropic instance
+ gets Anthropic's own defaults and environment for those."""
+ declared = _configured_llm()
+ with llm_overlay({"Researcher": "anthropic/claude-haiku-4-5"}):
+ agent = Agent(role="Researcher", goal="g", backstory="b", llm=declared)
+
+ swapped = agent.llm
+ assert type(swapped).__name__ == "AnthropicCompletion"
+ assert swapped.model == "claude-haiku-4-5"
+ assert swapped.timeout == 42 and swapped.temperature == 0.1
+ assert swapped.max_tokens == 77
+ assert swapped.api_key != "k" and swapped.base_url is None
+ assert swapped.additional_params == {}
+
+
+def test_a_setting_the_provider_derived_from_the_model_is_not_carried() -> None:
+ """Anthropic fills `max_tokens` with the model's output cap when the caller
+ did not set it; pinning one model's cap on another is a 400 waiting to
+ happen. The new model derives its own — a cap the caller did set is kept."""
+ with llm_overlay({"Researcher": "anthropic/claude-haiku-4-5"}):
+ derived = Agent(
+ role="Researcher",
+ goal="g",
+ backstory="b",
+ llm="anthropic/claude-sonnet-4-6",
+ )
+ explicit = Agent(
+ role="Researcher",
+ goal="g",
+ backstory="b",
+ llm=LLM(model="anthropic/claude-sonnet-4-6", max_tokens=500),
+ )
+ haiku = LLM(model="anthropic/claude-haiku-4-5")
+ sonnet = LLM(model="anthropic/claude-sonnet-4-6")
+ assert sonnet.max_tokens != haiku.max_tokens
+
+ assert derived.llm.model == "claude-haiku-4-5"
+ assert derived.llm.max_tokens == haiku.max_tokens
+ assert explicit.llm.max_tokens == 500
+
+
[email protected]("ignore:LiteAgent is deprecated")
+def test_the_construction_time_overlay_keeps_the_declared_configuration_too() -> None:
+ """The #7500 path — the agent is built inside the block with its role a key —
+ goes through the same construction as the kickoff-time swap."""
+ with llm_overlay(OVERLAY):
+ agent = Agent(role="Researcher", goal="g", backstory="b", llm=_configured_llm())
+ lite = LiteAgent(
+ role="Researcher", goal="g", backstory="b", llm=_configured_llm()
+ )
+
+ for built in (agent.llm, lite.llm):
+ assert type(built).__name__ == "OpenAICompletion" and built.model == "gpt-4o"
+ assert _configuration_of(built) == CONFIGURATION
+
+
+def test_an_llm_the_caller_assigns_later_is_the_declared_one_from_then_on() -> None:
+ """`Agent.llm` is a plain field; a caller may set it after construction.
+ A miss reverts to what the caller last put there, not to construction's."""
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ replacement = LLM(model="openai/gpt-4.1")
+ agent.llm = replacement
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/y"})
+ assert agent.llm is replacement
+
+
+def test_a_model_string_or_none_the_caller_assigns_is_resolved_like_construction(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """`Agent.llm` takes a string or `None` as well as an instance, and nothing
+ validates an assignment. Both are resolved the way construction resolves
+ them before they become the declared llm."""
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ agent.llm = "openai/gpt-4.1"
+
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o"
+ agent.interpolate_inputs({"repo": "crewAIInc/y"})
+ assert isinstance(agent.llm, BaseLLM) and agent.llm.model == "gpt-4.1"
+
+ monkeypatch.setenv("OPENAI_MODEL_NAME", "gpt-4.1-mini")
+ agent.llm = None
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert agent.llm.model == "gpt-4o"
+ agent.interpolate_inputs({"repo": "crewAIInc/z"})
+ assert isinstance(agent.llm, BaseLLM) and agent.llm.model == "gpt-4.1-mini"
+
+
+def test_a_crew_copy_made_inside_the_block_is_built_from_the_declared_llm() -> None:
+ """`Crew.copy()` — the `kickoff_for_each` path — copies every agent before its
+ input is interpolated. A template that is itself a key maps at construction;
+ a copy built from that mapped llm would record it as its declared one and
+ never revert, so the copy is built from the declared llm and resolves the
+ overlay for its own role."""
+ with llm_overlay({"Researcher for {repo}": "openai/gpt-4o"}):
+ agent = _agent("Researcher for {repo}")
+ task = Task(description="d", expected_output="e", agent=agent)
+ crew = Crew(agents=[agent], tasks=[task])
+ assert agent.llm.model == "gpt-4o"
+
+ copy = crew.copy().agents[0]
+ assert copy is not agent and copy.llm.model == "gpt-4o"
+
+ copy.interpolate_inputs({"repo": "crewAIInc/x"})
+ assert copy.role == "Researcher for crewAIInc/x"
+ assert copy.llm.model == "gpt-4o-mini"
+
+ # Outside any block a copy keeps the llm the agent runs on.
+ with llm_overlay(OVERLAY):
+ mapped = _agent("Researcher")
+ assert mapped.copy().llm.model == "gpt-4o"
+
+
+def test_prepare_kickoff_binds_the_executor_to_the_re_resolved_llm() -> None:
+ """The real kickoff ordering: interpolate, then set up the agents' executors."""
+ from crewai.crews.utils import prepare_kickoff
+
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ task = Task(description="Map {repo}", expected_output="a map", agent=agent)
+ crew = Crew(agents=[agent], tasks=[task])
+ prepare_kickoff(crew, {"repo": "crewAIInc/x"})
+
+ assert agent.role == "Researcher for crewAIInc/x"
+ assert agent.llm.model == "gpt-4o"
+ assert agent.agent_executor is not None and agent.agent_executor.llm is agent.llm
+ # Every task re-binds the executor to agent.llm (`_update_executor_parameters`).
+ agent.create_agent_executor()
+ assert agent.agent_executor.llm is agent.llm
+
+
+def test_crew_input_interpolation_routes_the_templated_role() -> None:
+ """The kickoff path: Crew._interpolate_inputs is what rewrites agent roles."""
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ task = Task(description="Map {repo}", expected_output="a map", agent=agent)
+ crew = Crew(agents=[agent], tasks=[task])
+
+ crew._interpolate_inputs({"repo": "crewAIInc/x"})
+
+ assert agent.role == "Researcher for crewAIInc/x"
+ assert agent.llm.model == "gpt-4o"
+
+
+def test_re_validation_of_an_existing_agent_does_not_read_the_overlay_again() -> None:
+ """The event bus registers an agent in its RuntimeState the first time it
+ emits, which re-runs `post_init_setup` on the same object. Inside a block
+ that maps the agent's role that used to replace an llm the agent already
+ ran on — an agent built OUTSIDE the block picked the mapped model up on its
+ first standalone kickoff inside one, and lost `stream=True` with it."""
+ from crewai import RuntimeState
+
+ outside = _agent("Researcher")
+ outside.llm.stream = True
+ outside_llm = outside.llm
+ with llm_overlay(OVERLAY):
+ inside = _agent("Researcher")
+ inside_llm = inside.llm
+ state = RuntimeState(root=[outside, inside])
+
+ assert state.root[0] is outside and state.root[1] is inside
+ assert (
+ outside.llm is outside_llm
+ and outside.llm.model == "gpt-4o-mini"
+ and outside.llm.stream is True
+ )
+ assert inside.llm is inside_llm and inside.llm.model == "gpt-4o"
+
+
+def test_re_validation_keeps_the_llm_a_kickoff_time_swap_set() -> None:
+ from crewai import RuntimeState
+
+ with llm_overlay(TEMPLATE_OVERLAY):
+ agent = _agent("Researcher for {repo}")
+ agent.interpolate_inputs({"repo": "crewAIInc/x"})
+ swapped = agent.llm
+ assert swapped.model == "gpt-4o"
+ RuntimeState(root=[agent])
+
+ assert agent.llm is swapped
diff --git a/lib/crewai/tests/utilities/test_create_llm_like.py b/lib/crewai/tests/utilities/test_create_llm_like.py
new file mode 100644
index 000000000..b24ad3aaa
--- /dev/null
+++ b/lib/crewai/tests/utilities/test_create_llm_like.py
@@ -0,0 +1,194 @@
+"""`create_llm_like`: what an `llm_overlay` swap carries from the declared llm.
+
+Zero-cost: instances are built, nothing is called. The provider classes that
+need an SDK this environment may not have (Azure, Gemini) are stood in for by
+minimal `BaseLLM` subclasses that reproduce the one behaviour under test.
+Provider classes are compared by name: the provider test files delete a module
+from sys.modules and re-import it, so a class imported here can be stale.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from crewai.llm import LLM
+from crewai.llms.base_llm import BaseLLM
+from crewai.llms.providers.openai.completion import OpenAICompletion
+from crewai.utilities.llm_utils import (
+ GENERATION_SETTINGS,
+ PROVIDER_SETTINGS,
+ _build,
+ _configured_settings,
+ create_llm_like,
+)
+
+
+class _BakesTheDeploymentIntoTheEndpoint(BaseLLM):
+ """Azure's shape: the endpoint carries the declared model's deployment."""
+
+ endpoint: str | None = None
+
+ def call(self, *args: Any, **kwargs: Any) -> Any: # pragma: no cover
+ raise NotImplementedError
+
+
+class _OmitsTheCapFromItsConfig(BaseLLM):
+ """Gemini's shape: `to_config_dict` never emits `max_tokens`, yet a caller's
+ value is honoured — the default is `None`, so nothing was derived."""
+
+ def to_config_dict(self) -> dict[str, Any]:
+ config = super().to_config_dict()
+ config.pop("max_tokens", None)
+ return config
+
+ def call(self, *args: Any, **kwargs: Any) -> Any: # pragma: no cover
+ raise NotImplementedError
+
+
+class _UserDefined(BaseLLM):
+ """A subclass of the user's own, whose `provider` defaulted to openai."""
+
+ def call(self, *args: Any, **kwargs: Any) -> Any: # pragma: no cover
+ raise NotImplementedError
+
+
+def test_an_azure_endpoint_is_carried_as_its_resource_root() -> None:
+ base = _BakesTheDeploymentIntoTheEndpoint(
+ model="gpt-4o",
+ provider="azure",
+ endpoint="https://r.openai.azure.com/openai/deployments/gpt-4o",
+ )
+ carried = _configured_settings(base, PROVIDER_SETTINGS)
+ assert carried["endpoint"] == "https://r.openai.azure.com"
+
+
+def test_a_cap_the_caller_set_is_carried_even_when_the_class_does_not_emit_it() -> None:
+ base = _OmitsTheCapFromItsConfig(model="gemini-2.5-flash", max_tokens=1000)
+ assert "max_tokens" not in base.to_config_dict()
+ assert _configured_settings(base, GENERATION_SETTINGS)["max_tokens"] == 1000
+
+
+def test_a_value_the_targets_field_type_refuses_is_dropped_with_a_warning(
+ caplog: Any,
+) -> None:
+ """A name the target has can still refuse the value (`logprobs` is an int on
+ the LiteLLM class, a bool on the OpenAI one). The build must not raise inside
+ a kickoff; it goes ahead without the one setting and says so."""
+ with caplog.at_level(logging.WARNING, logger="crewai.utilities.llm_utils"):
+ built = _build(
+ "openai/gpt-4o", {"logprobs": 2, "temperature": 0.4, "api_key": "k"}
+ )
+ assert type(built).__name__ == "OpenAICompletion" and built.model == "gpt-4o"
+ assert built.logprobs is None and built.temperature == 0.4
+ assert any("logprobs" in rec.getMessage() for rec in caplog.records)
+
+
+def test_extra_kwargs_travel_within_a_class() -> None:
+ """`additional_params` are the class's own extra kwargs: the native SDK's on
+ a native class, LiteLLM's on the LiteLLM one. They follow a swap that stays
+ in the class — and a LiteLLM base always does."""
+ native = OpenAICompletion(model="gpt-4o-mini", api_key="k", extra_body={"a": 1})
+ assert native.additional_params == {"extra_body": {"a": 1}}
+ assert create_llm_like("openai/gpt-4o", native).additional_params == {
+ "extra_body": {"a": 1}
+ }
+
+ litellm = LLM(model="openai/not-a-known-model", drop_params=True)
+ assert type(litellm) is LLM and litellm.additional_params == {"drop_params": True}
+ swapped = create_llm_like("openai/gpt-4o", litellm)
+ assert type(swapped) is LLM and swapped.additional_params == {"drop_params": True}
+
+
+def test_credentials_follow_the_class_not_the_provider_string() -> None:
+ aliased = LLM(model="claude-haiku-4-5", provider="claude", api_key="k")
+ assert (
+ type(aliased).__name__ == "AnthropicCompletion" and aliased.provider == "claude"
+ )
+ assert create_llm_like("anthropic/claude-sonnet-4-5", aliased).api_key == "k"
+
+ litellm_openai = LLM(model="openai/not-a-known-model", api_key="k")
+ assert type(litellm_openai) is LLM
+ swapped = create_llm_like("openai/gpt-4o", litellm_openai)
+ assert type(swapped) is LLM and swapped.api_key == "k"
+
+ user_defined = _UserDefined(model="gpt-x", api_key="k")
+ assert user_defined.provider == "openai"
+ assert create_llm_like("openai/gpt-4o", user_defined).api_key != "k"
+
+
+def test_an_output_cap_keeps_its_meaning_under_the_targets_name() -> None:
+ base = OpenAICompletion(model="gpt-4o-mini", api_key="k", max_completion_tokens=300)
+ swapped = create_llm_like("anthropic/claude-haiku-4-5", base)
+ assert type(swapped).__name__ == "AnthropicCompletion" and swapped.max_tokens == 300
+
+
+def test_anthropic_gets_temperature_or_top_p_not_both() -> None:
+ base = OpenAICompletion(
+ model="gpt-4o-mini", api_key="k", temperature=0.7, top_p=0.9
+ )
+ swapped = create_llm_like("anthropic/claude-haiku-4-5", base)
+ assert type(swapped).__name__ == "AnthropicCompletion"
+ assert swapped.temperature == 0.7 and swapped.top_p is None
+ only_top_p = OpenAICompletion(model="gpt-4o-mini", api_key="k", top_p=0.9)
+ assert create_llm_like("anthropic/claude-haiku-4-5", only_top_p).top_p == 0.9
+
+
+def test_a_custom_endpoint_is_kept_when_the_mapped_model_is_unknown_too(
+ monkeypatch: Any,
+) -> None:
+ """A self-hosted OpenAI-compatible endpoint serves models no constants table
+ knows; mapping one of them to another must stay on that endpoint, with its
+ key — the same-provider question is asked with the declared endpoint."""
+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+ base = LLM(
+ model="openai/local-model-a",
+ base_url="http://localhost:1234/v1",
+ api_key="local-key",
+ )
+ assert type(base).__name__ == "OpenAICompletion"
+ swapped = create_llm_like("openai/local-model-b", base)
+ assert type(swapped).__name__ == "OpenAICompletion"
+ assert swapped.model == "local-model-b"
+ assert swapped.base_url == "http://localhost:1234/v1"
+ assert swapped.api_key == "local-key"
+
+
+def test_openai_compatible_providers_are_not_one_provider(monkeypatch: Any) -> None:
+ """OpenRouter, DeepSeek, Ollama and the rest share one class; each is its own
+ vendor, so an OpenRouter key and endpoint must not travel to DeepSeek."""
+ monkeypatch.setenv("DEEPSEEK_API_KEY", "ds-env-key")
+ base = LLM(model="openrouter/meta-llama/llama-3-8b", api_key="or-explicit-key")
+ assert type(base).__name__ == "OpenAICompatibleCompletion"
+ swapped = create_llm_like("deepseek/deepseek-chat", base)
+ assert type(swapped).__name__ == "OpenAICompatibleCompletion"
+ assert swapped.provider == "deepseek" and swapped.model == "deepseek-chat"
+ assert swapped.api_key == "ds-env-key"
+ assert "openrouter" not in str(swapped.base_url)
+
+ same_vendor = create_llm_like("openrouter/meta-llama/llama-3-70b", base)
+ assert same_vendor.api_key == "or-explicit-key"
+
+ # The same through LiteLLM: a base the caller routed there carries its
+ # OpenRouter endpoint and key to another OpenRouter model, not to DeepSeek.
+ litellm_base = LLM(
+ model="openrouter/meta-llama/llama-3-8b",
+ is_litellm=True,
+ api_key="or-explicit-key",
+ base_url="https://openrouter.ai/api/v1",
+ )
+ assert type(litellm_base) is LLM and litellm_base.provider == "openrouter"
+ to_deepseek = create_llm_like("deepseek/deepseek-chat", litellm_base)
+ assert type(to_deepseek) is LLM and to_deepseek.provider == "deepseek"
+ assert to_deepseek.api_key != "or-explicit-key" and to_deepseek.base_url is None
+ to_openrouter = create_llm_like("openrouter/meta-llama/llama-3-70b", litellm_base)
+ assert to_openrouter.api_key == "or-explicit-key"
+ assert to_openrouter.base_url == "https://openrouter.ai/api/v1"
+
+
+def test_a_caller_who_chose_litellm_keeps_litellm() -> None:
+ base = LLM(model="gpt-4o", is_litellm=True, api_key="k", temperature=0.2)
+ assert type(base) is LLM
+ swapped = create_llm_like("gpt-4o-mini", base)
+ assert type(swapped) is LLM and swapped.is_litellm
+ assert swapped.model == "gpt-4o-mini" and swapped.temperature == 0.2