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: proactively summarize oversized LLM context (#8191)

Vidit Ostwal912f491b67c0
diff --git a/lib/crewai/src/crewai/events/__init__.py b/lib/crewai/src/crewai/events/__init__.py
index 6b44e988f..12770c72f 100644
--- a/lib/crewai/src/crewai/events/__init__.py
+++ b/lib/crewai/src/crewai/events/__init__.py
@@ -87,6 +87,9 @@ if TYPE_CHECKING:
KnowledgeSearchQueryFailedEvent,
)
from crewai.events.types.llm_events import (
+ ContextWindowSummarizationCompletedEvent,
+ ContextWindowSummarizationFailedEvent,
+ ContextWindowSummarizationStartedEvent,
LLMCallCompletedEvent,
LLMCallFailedEvent,
LLMCallStartedEvent,
@@ -211,6 +214,9 @@ _LAZY_EVENT_MAPPING: dict[str, str] = {
"KnowledgeRetrievalCompletedEvent": "crewai.events.types.knowledge_events",
"KnowledgeRetrievalStartedEvent": "crewai.events.types.knowledge_events",
"KnowledgeSearchQueryFailedEvent": "crewai.events.types.knowledge_events",
+ "ContextWindowSummarizationCompletedEvent": "crewai.events.types.llm_events",
+ "ContextWindowSummarizationFailedEvent": "crewai.events.types.llm_events",
+ "ContextWindowSummarizationStartedEvent": "crewai.events.types.llm_events",
"LLMCallCompletedEvent": "crewai.events.types.llm_events",
"LLMCallFailedEvent": "crewai.events.types.llm_events",
"LLMCallStartedEvent": "crewai.events.types.llm_events",
@@ -315,6 +321,9 @@ __all__ = [
"CheckpointRestoreStartedEvent",
"CheckpointStartedEvent",
"CircularDependencyError",
+ "ContextWindowSummarizationCompletedEvent",
+ "ContextWindowSummarizationFailedEvent",
+ "ContextWindowSummarizationStartedEvent",
"ConversationMessageAddedEvent",
"ConversationRouteSelectedEvent",
"ConversationTurnCompletedEvent",
diff --git a/lib/crewai/src/crewai/events/event_types.py b/lib/crewai/src/crewai/events/event_types.py
index abb5a3464..2fa4fed30 100644
--- a/lib/crewai/src/crewai/events/event_types.py
+++ b/lib/crewai/src/crewai/events/event_types.py
@@ -74,6 +74,9 @@ from crewai.events.types.knowledge_events import (
KnowledgeSearchQueryFailedEvent,
)
from crewai.events.types.llm_events import (
+ ContextWindowSummarizationCompletedEvent,
+ ContextWindowSummarizationFailedEvent,
+ ContextWindowSummarizationStartedEvent,
LLMCallCompletedEvent,
LLMCallFailedEvent,
LLMCallStartedEvent,
@@ -181,6 +184,9 @@ EventTypes = (
| ToolUsageErrorEvent
| ToolFailureDetectedEvent
| ToolUsageStartedEvent
+ | ContextWindowSummarizationStartedEvent
+ | ContextWindowSummarizationCompletedEvent
+ | ContextWindowSummarizationFailedEvent
| LLMCallStartedEvent
| LLMCallCompletedEvent
| LLMCallFailedEvent
diff --git a/lib/crewai/src/crewai/events/types/llm_events.py b/lib/crewai/src/crewai/events/types/llm_events.py
index b1be8c3d5..37bac3f12 100644
--- a/lib/crewai/src/crewai/events/types/llm_events.py
+++ b/lib/crewai/src/crewai/events/types/llm_events.py
@@ -121,6 +121,54 @@ class LLMCallFailedEvent(LLMEventBase):
type: Literal["llm_call_failed"] = "llm_call_failed"
+class ContextWindowSummarizationEvent(BaseEvent):
+ """Base event for proactive context-window summarization."""
+
+ from_task: Any | None = None
+ from_agent: Any | None = None
+ model: str | None = None
+
+ def __init__(self, **data: Any) -> None:
+ if data.get("from_task"):
+ task = data["from_task"]
+ data["task_id"] = str(task.id)
+ data["task_name"] = task.name or task.description
+ data["from_task"] = None
+
+ if data.get("from_agent"):
+ agent = data["from_agent"]
+ data["agent_id"] = str(agent.id)
+ data["agent_role"] = agent.role
+ data["from_agent"] = None
+
+ super().__init__(**data)
+
+
+class ContextWindowSummarizationStartedEvent(ContextWindowSummarizationEvent):
+ """Event emitted before proactively summarizing a pending request."""
+
+ type: Literal["context_window_summarization_started"] = (
+ "context_window_summarization_started"
+ )
+
+
+class ContextWindowSummarizationCompletedEvent(ContextWindowSummarizationEvent):
+ """Event emitted after proactively summarizing a pending request."""
+
+ type: Literal["context_window_summarization_completed"] = (
+ "context_window_summarization_completed"
+ )
+
+
+class ContextWindowSummarizationFailedEvent(ContextWindowSummarizationEvent):
+ """Event emitted when proactive context summarization fails."""
+
+ error: str
+ type: Literal["context_window_summarization_failed"] = (
+ "context_window_summarization_failed"
+ )
+
+
class FunctionCall(BaseModel):
arguments: str
name: str | None = None
diff --git a/lib/crewai/src/crewai/llms/base_llm.py b/lib/crewai/src/crewai/llms/base_llm.py
index 7a7c0cde0..ea4e0d470 100644
--- a/lib/crewai/src/crewai/llms/base_llm.py
+++ b/lib/crewai/src/crewai/llms/base_llm.py
@@ -424,6 +424,30 @@ class BaseLLM(BaseModel, ABC):
)
return tool_result_tokens > threshold, tool_result_tokens
+ def is_context_window_overflowing_threshold(
+ self,
+ messages: str | list[LLMMessage],
+ tools: list[dict[str, BaseTool]] | None = None,
+ response_model: type[BaseModel] | None = None,
+ ) -> bool:
+ """Check whether a pending request exceeds the usable context window.
+
+ ``get_context_window_size`` already reserves 15% of the raw model
+ window, so this preflight check triggers compaction once a request
+ reaches more than 85% of the provider's advertised limit.
+
+ Args:
+ messages: The messages that will be sent to the LLM.
+ tools: Optional tool schemas included in the request.
+ response_model: Optional structured-output model included in the
+ request.
+
+ Returns:
+ Whether the pending request exceeds the usable context window.
+ """
+ input_tokens = self.get_input_tokens_count(messages, tools, response_model)
+ return input_tokens > self.get_context_window_size()
+
@abstractmethod
def call(
self,
diff --git a/lib/crewai/src/crewai/llms/providers/bedrock/completion.py b/lib/crewai/src/crewai/llms/providers/bedrock/completion.py
index a6fe8bfd2..60d5819fb 100644
--- a/lib/crewai/src/crewai/llms/providers/bedrock/completion.py
+++ b/lib/crewai/src/crewai/llms/providers/bedrock/completion.py
@@ -407,7 +407,7 @@ class BedrockCompletion(BaseLLM):
modelId=self.model_id,
input={"converse": converse_input},
)
- except ClientError:
+ except (BotoCoreError, ClientError):
return super().get_input_tokens_count(messages, tools, response_model)
return int(response["inputTokens"])
diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.py
index f84d630b8..e5b93471a 100644
--- a/lib/crewai/src/crewai/utilities/agent_utils.py
+++ b/lib/crewai/src/crewai/utilities/agent_utils.py
@@ -9,6 +9,7 @@ from dataclasses import dataclass, field
from datetime import datetime
import inspect
import json
+import logging
import re
from typing import TYPE_CHECKING, Any, Final, Literal, cast
@@ -16,6 +17,7 @@ from crewai_core.printer import PRINTER, ColoredText, Printer
from crewai_core.settings import Settings
from pydantic import BaseModel
from rich.console import Console
+from rich.panel import Panel
from crewai.agents.constants import FINAL_ANSWER_AND_PARSABLE_ACTION_ERROR_MESSAGE
from crewai.agents.parser import (
@@ -24,6 +26,13 @@ from crewai.agents.parser import (
OutputParserError,
parse,
)
+from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.llm_events import (
+ ContextWindowSummarizationCompletedEvent,
+ ContextWindowSummarizationFailedEvent,
+ ContextWindowSummarizationStartedEvent,
+)
+from crewai.hooks.dispatch import HookAborted
from crewai.llms.base_llm import BaseLLM, LLMCallBlockedError, call_stop_override
from crewai.tools import BaseTool as CrewAITool
from crewai.tools.base_tool import BaseTool
@@ -63,6 +72,7 @@ if TYPE_CHECKING:
from crewai.task import Task
_create_plus_client_hook: Callable[[], Any] | None = None
+logger = logging.getLogger(__name__)
def resolve_plus_client(default: Callable[[], Any]) -> Any:
@@ -539,6 +549,119 @@ def _validate_and_finalize_llm_response(
)
+def _summarize_context_before_llm_call(
+ llm: LLM | BaseLLM,
+ messages: list[LLMMessage],
+ callbacks: list[TokenCalcHandler],
+ printer: Printer,
+ verbose: bool,
+ from_task: Task | None = None,
+ from_agent: BaseAgent | None = None,
+) -> None:
+ """Compact messages after a preflight context-window check."""
+ non_system_messages = [
+ message for message in messages if message.get("role") != "system"
+ ]
+ if len(non_system_messages) == 1 and non_system_messages[0].get("role") == "user":
+ return
+
+ model = getattr(llm, "model", None)
+ if not isinstance(model, str):
+ model = None
+
+ crewai_event_bus.emit(
+ llm,
+ event=ContextWindowSummarizationStartedEvent(
+ from_task=from_task,
+ from_agent=from_agent,
+ model=model,
+ ),
+ )
+ if verbose:
+ console.print(
+ Panel(
+ "The pending request is nearing the model context limit. "
+ "Compacting the conversation before the next model call.",
+ title="🧠 Context summarization triggered",
+ border_style="yellow",
+ padding=(1, 2),
+ )
+ )
+ try:
+ summarize_messages(
+ messages=messages, llm=llm, callbacks=callbacks, verbose=verbose
+ )
+ except Exception as error:
+ crewai_event_bus.emit(
+ llm,
+ event=ContextWindowSummarizationFailedEvent(
+ from_task=from_task,
+ from_agent=from_agent,
+ model=model,
+ error=str(error),
+ ),
+ )
+ if verbose:
+ console.print(
+ Panel(
+ "Conversation context could not be compacted. Continuing with the original request.",
+ title="⚠️ Context summarization failed",
+ border_style="red",
+ padding=(1, 2),
+ )
+ )
+ raise
+ crewai_event_bus.emit(
+ llm,
+ event=ContextWindowSummarizationCompletedEvent(
+ from_task=from_task,
+ from_agent=from_agent,
+ model=model,
+ ),
+ )
+ if verbose:
+ console.print(
+ Panel(
+ "Conversation context has been compacted and is ready for the next model call.",
+ title="✅ Context summarization completed",
+ border_style="green",
+ padding=(1, 2),
+ )
+ )
+
+
+def _proactively_summarize_context(
+ llm: LLM | BaseLLM,
+ messages: list[LLMMessage],
+ callbacks: list[TokenCalcHandler],
+ printer: Printer,
+ tools: list[dict[str, Any]] | None,
+ response_model: type[BaseModel] | None,
+ verbose: bool,
+ from_task: Task | None = None,
+ from_agent: BaseAgent | None = None,
+) -> None:
+ """Try to summarize oversized context without blocking a valid LLM call."""
+ try:
+ if llm.is_context_window_overflowing_threshold(messages, tools, response_model):
+ _summarize_context_before_llm_call(
+ llm=llm,
+ messages=messages,
+ callbacks=callbacks,
+ printer=printer,
+ verbose=verbose,
+ from_task=from_task,
+ from_agent=from_agent,
+ )
+ except (HookAborted, LLMCallBlockedError):
+ raise
+ except Exception:
+ logger.debug(
+ "Proactive context preflight or summarization failed; continuing with the LLM call.",
+ exc_info=True,
+ )
+
+
def get_llm_response(
llm: LLM | BaseLLM,
messages: list[LLMMessage],
@@ -578,6 +701,18 @@ def get_llm_response(
with _prepare_llm_call(
executor_context, messages, printer, verbose=verbose
) as prepared_messages:
+ if getattr(executor_context, "respect_context_window", False):
+ _proactively_summarize_context(
+ llm=llm,
+ messages=prepared_messages,
+ callbacks=callbacks,
+ printer=printer,
+ tools=tools,
+ response_model=response_model,
+ verbose=verbose,
+ from_task=from_task,
+ from_agent=from_agent,
+ )
answer = llm.call(
prepared_messages,
tools=tools,
@@ -632,6 +767,19 @@ async def aget_llm_response(
with _prepare_llm_call(
executor_context, messages, printer, verbose=verbose
) as prepared_messages:
+ if getattr(executor_context, "respect_context_window", False):
+ await asyncio.to_thread(
+ _proactively_summarize_context,
+ llm=llm,
+ messages=prepared_messages,
+ callbacks=callbacks,
+ printer=printer,
+ tools=tools,
+ response_model=response_model,
+ verbose=verbose,
+ from_task=from_task,
+ from_agent=from_agent,
+ )
answer = await llm.acall(
prepared_messages,
tools=tools,
diff --git a/lib/crewai/tests/agents/test_agent.py b/lib/crewai/tests/agents/test_agent.py
index 9e8fc2cac..94385dc13 100644
--- a/lib/crewai/tests/agents/test_agent.py
+++ b/lib/crewai/tests/agents/test_agent.py
@@ -3050,6 +3050,69 @@ class TestMaxIterationsForcedAnswer:
assert isinstance(result, AgentFinish)
assert result.output == "forced"
+ def test_react_loop_summarizes_before_calling_the_llm(self) -> None:
+ llm = MagicMock(spec=LLM)
+ llm.stop = []
+ llm.supports_stop_words.return_value = True
+ llm.supports_function_calling.return_value = False
+ llm.is_context_window_overflowing_threshold.return_value = True
+ llm.call.return_value = "Final Answer: done"
+ executor = self._make_executor(llm, original_tools=[])
+ executor.iterations = 0
+ executor.max_iter = 2
+ executor.respect_context_window = True
+ executor.messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ events: list[str] = []
+
+ with (
+ patch("crewai.utilities.agent_utils.summarize_messages") as summarize,
+ patch.object(executor, "_show_logs"),
+ ):
+ summarize.side_effect = lambda **_: events.append("summarize")
+ llm.call.side_effect = (
+ lambda *_args, **_kwargs: events.append("call") or "Final Answer: done"
+ )
+ executor._invoke_loop()
+
+ assert events == ["summarize", "call"]
+
+ def test_native_tool_loop_summarizes_before_calling_the_llm(self) -> None:
+ @tool
+ def search(query: str) -> str:
+ """Search for a result."""
+ return query
+
+ llm = MagicMock(spec=LLM)
+ llm.stop = []
+ llm.supports_stop_words.return_value = True
+ llm.supports_function_calling.return_value = True
+ llm.is_context_window_overflowing_threshold.return_value = True
+ llm.call.return_value = "done"
+ executor = self._make_executor(llm, original_tools=[search])
+ executor.iterations = 0
+ executor.max_iter = 2
+ executor.respect_context_window = True
+ executor.messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ events: list[str] = []
+
+ with (
+ patch("crewai.utilities.agent_utils.summarize_messages") as summarize,
+ patch.object(executor, "_show_logs"),
+ ):
+ summarize.side_effect = lambda **_: events.append("summarize")
+ llm.call.side_effect = lambda *_args, **_kwargs: events.append("call") or "done"
+ executor._invoke_loop()
+
+ assert events == ["summarize", "call"]
+
def test_native_tools_loop_forces_final_answer_with_user_turn(self) -> None:
from crewai.utilities.i18n import I18N_DEFAULT
diff --git a/lib/crewai/tests/agents/test_agent_executor.py b/lib/crewai/tests/agents/test_agent_executor.py
index 3583006c7..e810f56e8 100644
--- a/lib/crewai/tests/agents/test_agent_executor.py
+++ b/lib/crewai/tests/agents/test_agent_executor.py
@@ -493,6 +493,43 @@ class TestAgentExecutor:
assert result == "parsed"
assert get_llm_response_mock.call_args.kwargs["response_model"] is None
+ def test_call_llm_and_parse_summarizes_before_the_model_call(
+ self, mock_dependencies
+ ):
+ executor = _build_executor(**mock_dependencies, callbacks=[])
+ executor.respect_context_window = True
+ executor.task.id = "test-task-id"
+ executor.task.name = "Test task"
+ executor.state.messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ executor.llm.is_context_window_overflowing_threshold.return_value = True
+ executor.llm.call.return_value = "Final Answer: done"
+ events: list[str] = []
+
+ with patch("crewai.utilities.agent_utils.summarize_messages") as summarize:
+ summarize.side_effect = lambda **_: events.append("summarize")
+ executor.llm.call.side_effect = (
+ lambda *_args, **_kwargs: events.append("call") or "Final Answer: done"
+ )
+ assert executor.call_llm_and_parse() == "parsed"
+
+ assert events == ["summarize", "call"]
+
+ def test_call_llm_and_parse_skips_preflight_when_context_respect_is_disabled(
+ self, mock_dependencies
+ ):
+ executor = _build_executor(**mock_dependencies, callbacks=[])
+ executor.respect_context_window = False
+ executor.state.messages = [{"role": "user", "content": "large context"}]
+ executor.llm.call.return_value = "Final Answer: done"
+
+ assert executor.call_llm_and_parse() == "parsed"
+
+ executor.llm.is_context_window_overflowing_threshold.assert_not_called()
+
def test_call_llm_native_tools_does_not_pass_response_model_with_tools(
self, mock_dependencies
):
diff --git a/lib/crewai/tests/agents/test_lite_agent.py b/lib/crewai/tests/agents/test_lite_agent.py
index 79c7dc524..3a7c3393a 100644
--- a/lib/crewai/tests/agents/test_lite_agent.py
+++ b/lib/crewai/tests/agents/test_lite_agent.py
@@ -72,6 +72,7 @@ def test_agent_kickoff_preserves_parameters(verbose):
"""Test that Agent.kickoff() uses the correct parameters from the Agent."""
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Test response"
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
from crewai.types.usage_metrics import UsageMetrics
@@ -303,6 +304,7 @@ def test_sets_flow_context_when_inside_flow():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Test response"
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
from crewai.types.usage_metrics import UsageMetrics
@@ -597,6 +599,55 @@ def test_lite_agent_with_custom_llm_and_guardrails():
assert result2.raw == "Modified by guardrail"
+def test_lite_agent_summarizes_before_calling_the_llm():
+ llm = Mock(spec=LLM)
+ llm.stop = []
+ llm.supports_stop_words.return_value = True
+ llm.is_context_window_overflowing_threshold.return_value = True
+ agent = LiteAgent(
+ role="Test",
+ goal="Test goal",
+ backstory="Test backstory",
+ llm=llm,
+ verbose=False,
+ )
+ agent._messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ events: list[str] = []
+
+ with patch("crewai.utilities.agent_utils.summarize_messages") as summarize:
+ summarize.side_effect = lambda **_: events.append("summarize")
+ llm.call.side_effect = (
+ lambda *_args, **_kwargs: events.append("call") or "Final Answer: done"
+ )
+ agent._invoke_loop()
+
+ assert events == ["summarize", "call"]
+
+
+def test_lite_agent_skips_preflight_when_context_respect_is_disabled():
+ llm = Mock(spec=LLM)
+ llm.stop = []
+ llm.supports_stop_words.return_value = True
+ llm.call.return_value = "Final Answer: done"
+ agent = LiteAgent(
+ role="Test",
+ goal="Test goal",
+ backstory="Test backstory",
+ llm=llm,
+ respect_context_window=False,
+ verbose=False,
+ )
+ agent._messages = [{"role": "user", "content": "large context"}]
+
+ agent._invoke_loop()
+
+ llm.is_context_window_overflowing_threshold.assert_not_called()
+
+
@pytest.mark.vcr()
def test_lite_agent_with_invalid_llm():
"""Test that LiteAgent raises proper error when create_llm returns None."""
@@ -845,6 +896,7 @@ def test_agent_kickoff_with_files_parameter():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: I can see the file content."
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
@@ -891,6 +943,7 @@ def test_prepare_kickoff_extracts_files_from_messages():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Done."
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
@@ -931,6 +984,7 @@ def test_prepare_kickoff_merges_files_from_messages_and_parameter():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Done."
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
@@ -977,6 +1031,7 @@ def test_prepare_kickoff_param_files_override_message_files():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Done."
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
@@ -1017,6 +1072,7 @@ def test_lite_agent_verbose_false_suppresses_printer_output():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Hello!"
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
@@ -1052,6 +1108,7 @@ def test_lite_agent_memory_none_default():
"""With memory=None (default), _memory is None and no memory is used."""
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Ok"
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
total_tokens=10,
@@ -1078,6 +1135,7 @@ def test_lite_agent_memory_true_resolves_to_default_memory():
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: Ok"
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
total_tokens=10,
@@ -1104,6 +1162,7 @@ def test_lite_agent_memory_instance_recall_and_save_called():
"""With a custom memory instance, kickoff calls recall and then extract_memories/remember."""
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: The answer is 42."
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
@@ -1311,6 +1370,7 @@ def test_lite_agent_forces_final_answer_with_user_turn():
mock_llm = Mock(spec=LLM)
mock_llm.call.side_effect = record_request
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.get_token_usage_summary.return_value = UsageMetrics(
total_tokens=10,
diff --git a/lib/crewai/tests/llms/bedrock/test_bedrock.py b/lib/crewai/tests/llms/bedrock/test_bedrock.py
index a492a298e..d7011fcf5 100644
--- a/lib/crewai/tests/llms/bedrock/test_bedrock.py
+++ b/lib/crewai/tests/llms/bedrock/test_bedrock.py
@@ -763,6 +763,19 @@ def test_bedrock_input_token_count_uses_character_fallback_for_unsupported_model
assert llm.get_input_tokens_count("12345") == 2
+def test_bedrock_input_token_count_uses_character_fallback_for_transport_errors(
+ bedrock_mocks,
+):
+ """VCR transport failures do not prevent proactive context preflight."""
+ from botocore.exceptions import HTTPClientError
+
+ _, client = bedrock_mocks
+ llm = LLM(model="bedrock/us.anthropic.claude-sonnet-4-6")
+ client.count_tokens.side_effect = HTTPClientError(error=RuntimeError("VCR miss"))
+
+ assert llm.get_input_tokens_count("12345") == 2
+
+
def test_bedrock_tool_use_conversation_flow():
"""
Test that the Bedrock completion properly handles tool use conversation flow
diff --git a/lib/crewai/tests/memory/test_unified_memory.py b/lib/crewai/tests/memory/test_unified_memory.py
index a1c4e989d..daee76643 100644
--- a/lib/crewai/tests/memory/test_unified_memory.py
+++ b/lib/crewai/tests/memory/test_unified_memory.py
@@ -797,6 +797,7 @@ def test_agent_kickoff_memory_recall_and_save(tmp_path: Path, mock_embedder: Mag
mock_llm = Mock(spec=LLM)
mock_llm.call.return_value = "Final Answer: PostgreSQL is the database."
+ mock_llm.is_context_window_overflowing_threshold.return_value = False
mock_llm.stop = []
mock_llm.supports_stop_words.return_value = False
mock_llm.supports_function_calling.return_value = False
diff --git a/lib/crewai/tests/test_llm.py b/lib/crewai/tests/test_llm.py
index 50842c14a..e2cfd0a4c 100644
--- a/lib/crewai/tests/test_llm.py
+++ b/lib/crewai/tests/test_llm.py
@@ -85,6 +85,24 @@ def test_llm_call_with_message_list():
assert "Paris" in result
+def test_context_window_preflight_triggers_only_above_usable_limit():
+ """The proactive threshold preserves the 15% context-window headroom."""
+ llm = LLM(model="gpt-4o-mini")
+ messages = [{"role": "user", "content": "test"}]
+
+ with (
+ patch.object(llm, "get_context_window_size", return_value=850),
+ patch.object(llm, "get_input_tokens_count", return_value=850),
+ ):
+ assert llm.is_context_window_overflowing_threshold(messages) is False
+
+ with (
+ patch.object(llm, "get_context_window_size", return_value=850),
+ patch.object(llm, "get_input_tokens_count", return_value=851),
+ ):
+ assert llm.is_context_window_overflowing_threshold(messages) is True
+
+
@pytest.mark.vcr()
def test_llm_call_with_tool_and_string_input():
llm = LLM(model="gpt-4o-mini")
diff --git a/lib/crewai/tests/utilities/test_agent_utils.py b/lib/crewai/tests/utilities/test_agent_utils.py
index 20ac2a7f8..fe56de207 100644
--- a/lib/crewai/tests/utilities/test_agent_utils.py
+++ b/lib/crewai/tests/utilities/test_agent_utils.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import asyncio
import json
+from types import SimpleNamespace
from typing import Any, Literal, Optional
from unittest.mock import AsyncMock, MagicMock, patch
@@ -17,9 +18,20 @@ from crewai.hooks.tool_hooks import (
register_after_tool_call_hook,
)
from crewai.agents.parser import AgentFinish
+from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.llm_events import (
+ ContextWindowSummarizationCompletedEvent,
+ ContextWindowSummarizationFailedEvent,
+ ContextWindowSummarizationStartedEvent,
+)
+from crewai.hooks.dispatch import HookAborted
+from crewai.llms.base_llm import LLMCallBlockedError
from crewai.tools.base_tool import BaseTool
from crewai.llms.context_window import CONTEXT_WINDOW_USAGE_RATIO
from crewai.utilities.agent_utils import (
+ _summarize_context_before_llm_call,
+ aget_llm_response,
+ get_llm_response,
message_content_text,
format_message_for_llm,
LLMContextLengthExceededError,
@@ -33,6 +45,7 @@ from crewai.utilities.agent_utils import (
summarize_messages,
SummarizeMessages,
)
+from crewai_core.printer import Printer
from crewai.utilities.i18n import I18N_DEFAULT
_summarizer = SummarizeMessages()
@@ -42,6 +55,389 @@ _messages_ready_to_chunk = _summarizer._messages_ready_to_chunk
_chunk_messages = _summarizer._chunk_messages
+def test_summarizes_context_before_llm_call() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ llm = MagicMock()
+
+ with patch("crewai.utilities.agent_utils.summarize_messages") as summarize:
+ _summarize_context_before_llm_call(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ verbose=False,
+ )
+
+ summarize.assert_called_once_with(
+ messages=messages, llm=llm, callbacks=[], verbose=False
+ )
+
+
+def test_context_summarization_shows_triggered_and_completed_panels() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ llm = MagicMock()
+
+ with (
+ patch("crewai.utilities.agent_utils.summarize_messages"),
+ patch("crewai.utilities.agent_utils.console.print") as print_panel,
+ ):
+ _summarize_context_before_llm_call(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ verbose=True,
+ )
+
+ assert print_panel.call_count == 2
+ assert "triggered" in str(print_panel.call_args_list[0].args[0].title).lower()
+ assert "completed" in str(print_panel.call_args_list[1].args[0].title).lower()
+
+
+def test_context_summarization_emits_lifecycle_events_with_llm_agent_and_task() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ llm = MagicMock(model="gpt-4o-mini")
+ task = SimpleNamespace(id="task-id", name="Research", description="Research")
+ agent = SimpleNamespace(id="agent-id", role="Researcher")
+
+ with (
+ patch("crewai.utilities.agent_utils.summarize_messages"),
+ patch.object(crewai_event_bus, "emit") as emit,
+ ):
+ _summarize_context_before_llm_call(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ verbose=False,
+ from_task=task,
+ from_agent=agent,
+ )
+
+ events = [call.kwargs["event"] for call in emit.call_args_list]
+ assert len(events) == 2
+ assert isinstance(events[0], ContextWindowSummarizationStartedEvent)
+ assert isinstance(events[1], ContextWindowSummarizationCompletedEvent)
+ for event in events:
+ assert event.model == "gpt-4o-mini"
+ assert event.agent_id == "agent-id"
+ assert event.agent_role == "Researcher"
+ assert event.task_id == "task-id"
+ assert event.task_name == "Research"
+
+
+def test_context_summarization_emits_failed_event_when_compaction_fails() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ llm = MagicMock(model="gpt-4o-mini")
+
+ with (
+ patch(
+ "crewai.utilities.agent_utils.summarize_messages",
+ side_effect=RuntimeError("summarization failed"),
+ ),
+ patch.object(crewai_event_bus, "emit") as emit,
+ pytest.raises(RuntimeError, match="summarization failed"),
+ ):
+ _summarize_context_before_llm_call(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ verbose=False,
+ )
+
+ events = [call.kwargs["event"] for call in emit.call_args_list]
+ assert len(events) == 2
+ assert isinstance(events[0], ContextWindowSummarizationStartedEvent)
+ assert isinstance(events[1], ContextWindowSummarizationFailedEvent)
+ assert events[1].error == "summarization failed"
+
+
+def test_get_llm_response_summarizes_before_the_model_call() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=True,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.is_context_window_overflowing_threshold.return_value = True
+ llm.call.return_value = "response"
+ events: list[str] = []
+
+ with patch("crewai.utilities.agent_utils.summarize_messages") as summarize:
+ summarize.side_effect = lambda **_: events.append("summarize")
+ llm.call.side_effect = lambda *_args, **_kwargs: events.append("call") or "response"
+
+ assert (
+ get_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ assert events == ["summarize", "call"]
+
+
+def test_get_llm_response_preserves_a_single_pending_user_request() -> None:
+ messages = [
+ {"role": "system", "content": "You are helpful."},
+ {"role": "user", "content": "large context"},
+ ]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=True,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.is_context_window_overflowing_threshold.return_value = True
+ llm.call.return_value = "response"
+
+ with patch("crewai.utilities.agent_utils.summarize_messages") as summarize:
+ assert (
+ get_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ summarize.assert_not_called()
+ assert llm.call.call_args.args[0] == messages
+
+
+ "failure_source",
+ ["preflight", "summarization"],
+)
+def test_get_llm_response_continues_when_proactive_compaction_fails(
+ failure_source: str,
+) -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "pending request"},
+ ]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=True,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.call.return_value = "response"
+ if failure_source == "preflight":
+ llm.is_context_window_overflowing_threshold.side_effect = RuntimeError(
+ "token counting failed"
+ )
+ summarize = patch("crewai.utilities.agent_utils.summarize_messages")
+ else:
+ llm.is_context_window_overflowing_threshold.return_value = True
+ summarize = patch(
+ "crewai.utilities.agent_utils.summarize_messages",
+ side_effect=RuntimeError("summarization failed"),
+ )
+
+ with summarize:
+ assert (
+ get_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ llm.call.assert_called_once()
+
+
+ "error", [HookAborted("blocked"), LLMCallBlockedError("blocked")])
+def test_get_llm_response_propagates_explicit_proactive_compaction_blocks(
+ error: Exception,
+) -> None:
+ messages = [{"role": "user", "content": "pending request"}]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=True,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.is_context_window_overflowing_threshold.side_effect = error
+
+ with pytest.raises(type(error)):
+ get_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+
+ llm.call.assert_not_called()
+
+
+def test_get_llm_response_skips_preflight_when_context_respect_is_disabled() -> None:
+ messages = [{"role": "user", "content": "large context"}]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=False,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.call.return_value = "response"
+
+ assert (
+ get_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ llm.is_context_window_overflowing_threshold.assert_not_called()
+
+
+async def test_aget_llm_response_summarizes_before_the_model_call() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "large context"},
+ ]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=True,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.is_context_window_overflowing_threshold.return_value = True
+ llm.acall = AsyncMock(return_value="response")
+
+ with patch("crewai.utilities.agent_utils.summarize_messages") as summarize:
+ assert (
+ await aget_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ summarize.assert_called_once()
+ llm.acall.assert_awaited_once()
+
+
+async def test_aget_llm_response_offloads_proactive_compaction() -> None:
+ messages = [
+ {"role": "user", "content": "earlier context"},
+ {"role": "assistant", "content": "earlier response"},
+ {"role": "user", "content": "pending request"},
+ ]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=True,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.is_context_window_overflowing_threshold.return_value = False
+ llm.acall = AsyncMock(return_value="response")
+
+ with patch(
+ "crewai.utilities.agent_utils.asyncio.to_thread",
+ wraps=asyncio.to_thread,
+ ) as to_thread:
+ assert (
+ await aget_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ assert to_thread.await_count == 1
+ assert to_thread.call_args.args[0].__name__ == "_proactively_summarize_context"
+ llm.is_context_window_overflowing_threshold.assert_called_once()
+ llm.acall.assert_awaited_once()
+
+
+async def test_aget_llm_response_skips_preflight_when_context_respect_is_disabled() -> None:
+ messages = [{"role": "user", "content": "large context"}]
+ executor = SimpleNamespace(
+ messages=messages,
+ respect_context_window=False,
+ before_llm_call_hooks=[],
+ after_llm_call_hooks=[],
+ )
+ llm = MagicMock()
+ llm.acall = AsyncMock(return_value="response")
+
+ assert (
+ await aget_llm_response(
+ llm=llm,
+ messages=messages,
+ callbacks=[],
+ printer=Printer(),
+ executor_context=executor,
+ verbose=False,
+ )
+ == "response"
+ )
+
+ llm.is_context_window_overflowing_threshold.assert_not_called()
+
def _estimate_summarization_request_tokens(chunk: list[dict[str, Any]]) -> int:
"""Estimate tokens for the full summarization LLM request for one chunk."""
conversation_text = _conversation_text(chunk)