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.pyindex 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 HookAbortedfrom crewai.knowledge.knowledge import Knowledgefrom crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSourcefrom 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_forfrom crewai.llms.base_llm import BaseLLMfrom crewai.mcp.config import MCPServerConfigfrom crewai.rag.embeddings.types import EmbedderConfig@@ -114,7 +114,7 @@ from crewai.utilities.env import get_env_contextfrom crewai.utilities.guardrail import process_guardrail, serialize_guardrail_for_jsonfrom crewai.utilities.guardrail_types import GuardrailCallable, GuardrailTypefrom crewai.utilities.i18n import I18N_DEFAULT-from crewai.utilities.llm_utils import create_llm+from crewai.utilities.llm_utils import create_llm, create_llm_likefrom crewai.utilities.prompts import Prompts, StandardPromptResult, SystemPromptResultfrom crewai.utilities.pydantic_schema_utils import generate_model_descriptionfrom 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 = Trueif 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.pyindex 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.pyindex 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_jsonfrom crewai.utilities.guardrail_types import GuardrailCallable, GuardrailTypefrom crewai.utilities.i18n import I18N_DEFAULT-from crewai.utilities.llm_utils import create_llm+from crewai.utilities.llm_utils import create_llm, create_llm_likefrom 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.pyindex 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"] = Truereturn 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)+@classmethoddef _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 OpenAICompletiondiff --git a/lib/crewai/src/crewai/llm_overlay.py b/lib/crewai/src/crewai/llm_overlay.pyindex 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 builtwith the mapped model instead of its declared ``llm``. Roles that are notkeys, 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 callingcontext, not the process. A plain ``threading.Thread`` started inside theblock does not see it: callers that run agents in their own threads mustpropagate 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 annotationsdiff --git a/lib/crewai/src/crewai/utilities/llm_utils.py b/lib/crewai/src/crewai/utilities/llm_utils.pyindex 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 loggingimport osfrom typing import Any, Final+from pydantic import ValidationError+from crewai.constants import DEFAULT_LLM_MODEL, ENV_VARS, LITELLM_PARAMSfrom crewai.llm import LLMfrom 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.pyindex 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 modelsdiff --git a/lib/crewai/tests/test_llm_overlay.py b/lib/crewai/tests/test_llm_overlay.pyindex 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 stripsthe `openai/` prefix, so the resolved model reads `"gpt-4o"`.@@ -12,20 +14,45 @@ from __future__ import annotationsimport contextvarsimport threading+from typing import Any-from crewai import Agent+from crewai import Agent, Crew, Taskfrom crewai.lite_agent import LiteAgent+from crewai.llm import LLMfrom crewai.llm_overlay import active, llm_overlay, overlay_model_for+from crewai.llms.base_llm import BaseLLMimport 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() -> Noneassert seen["plain"] is Noneassert 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 swappeddiff --git a/lib/crewai/tests/utilities/test_create_llm_like.py b/lib/crewai/tests/utilities/test_create_llm_like.pynew file mode 100644index 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