The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(langchain_v1): Implement Context Editing Middleware (#33267)
Nuno Camposf30813928354
diff --git a/libs/langchain_v1/langchain/agents/middleware/__init__.py b/libs/langchain_v1/langchain/agents/middleware/__init__.pyindex 5915b75164..ffbc2b932d 100644--- a/libs/langchain_v1/langchain/agents/middleware/__init__.py+++ b/libs/langchain_v1/langchain/agents/middleware/__init__.py@@ -1,5 +1,10 @@"""Middleware plugins for agents."""+from .call_tracking import ModelCallLimitMiddleware+from .context_editing import (+ ClearToolUsesEdit,+ ContextEditingMiddleware,+)from .human_in_the_loop import HumanInTheLoopMiddlewarefrom .model_fallback import ModelFallbackMiddlewarefrom .pii import PIIDetectionError, PIIMiddleware@@ -24,8 +29,11 @@ __all__ = ["AgentState",# should move to langchain-anthropic if we decide to keep it"AnthropicPromptCachingMiddleware",+ "ClearToolUsesEdit",+ "ContextEditingMiddleware","HumanInTheLoopMiddleware","LLMToolSelectorMiddleware",+ "ModelCallLimitMiddleware","ModelFallbackMiddleware","ModelRequest","PIIDetectionError",diff --git a/libs/langchain_v1/langchain/agents/middleware/context_editing.py b/libs/langchain_v1/langchain/agents/middleware/context_editing.pynew file mode 100644index 0000000000..017c460083--- /dev/null+++ b/libs/langchain_v1/langchain/agents/middleware/context_editing.py@@ -0,0 +1,245 @@+"""Context editing middleware.++This middleware mirrors Anthropic's context editing capabilities by clearing+older tool results once the conversation grows beyond a configurable token+threshold. The implementation is intentionally model-agnostic so it can be used+with any LangChain chat model.+"""++from __future__ import annotations++from collections.abc import Callable, Iterable, Sequence+from dataclasses import dataclass+from typing import TYPE_CHECKING, Literal++from langchain_core.messages import (+ AIMessage,+ AnyMessage,+ BaseMessage,+ SystemMessage,+ ToolMessage,+)+from langchain_core.messages.utils import count_tokens_approximately+from typing_extensions import Protocol++from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest++if TYPE_CHECKING:+ from langgraph.runtime import Runtime++DEFAULT_TOOL_PLACEHOLDER = "[cleared]"+++TokenCounter = Callable[+ [Sequence[BaseMessage]],+ int,+]+++class ContextEdit(Protocol):+ """Protocol describing a context editing strategy."""++ def apply(+ self,+ messages: list[AnyMessage],+ *,+ count_tokens: TokenCounter,+ ) -> None:+ """Apply an edit to the message list in place."""+ ...+++@dataclass(slots=True)+class ClearToolUsesEdit(ContextEdit):+ """Configuration for clearing tool outputs when token limits are exceeded."""++ trigger: int = 100_000+ """Token count that triggers the edit."""++ clear_at_least: int = 0+ """Minimum number of tokens to reclaim when the edit runs."""++ keep: int = 3+ """Number of most recent tool results that must be preserved."""++ clear_tool_inputs: bool = False+ """Whether to clear the originating tool call parameters on the AI message."""++ exclude_tools: Sequence[str] = ()+ """List of tool names to exclude from clearing."""++ placeholder: str = DEFAULT_TOOL_PLACEHOLDER+ """Placeholder text inserted for cleared tool outputs."""++ def apply(+ self,+ messages: list[AnyMessage],+ *,+ count_tokens: TokenCounter,+ ) -> None:+ """Apply the clear-tool-uses strategy."""+ tokens = count_tokens(messages)++ if tokens <= self.trigger:+ return++ candidates = [+ (idx, msg) for idx, msg in enumerate(messages) if isinstance(msg, ToolMessage)+ ]++ if self.keep >= len(candidates):+ candidates = []+ elif self.keep:+ candidates = candidates[: -self.keep]++ cleared_tokens = 0+ excluded_tools = set(self.exclude_tools)++ for idx, tool_message in candidates:+ if tool_message.response_metadata.get("context_editing", {}).get("cleared"):+ continue++ ai_message = next(+ (m for m in reversed(messages[:idx]) if isinstance(m, AIMessage)), None+ )++ if ai_message is None:+ continue++ tool_call = next(+ (+ call+ for call in ai_message.tool_calls+ if call.get("id") == tool_message.tool_call_id+ ),+ None,+ )++ if tool_call is None:+ continue++ if (tool_message.name or tool_call["name"]) in excluded_tools:+ continue++ messages[idx] = tool_message.model_copy(+ update={+ "artifact": None,+ "content": self.placeholder,+ "response_metadata": {+ **tool_message.response_metadata,+ "context_editing": {+ "cleared": True,+ "strategy": "clear_tool_uses",+ },+ },+ }+ )++ if self.clear_tool_inputs:+ messages[messages.index(ai_message)] = self._build_cleared_tool_input_message(+ ai_message,+ tool_message.tool_call_id,+ )++ if self.clear_at_least > 0:+ new_token_count = count_tokens(messages)+ cleared_tokens = max(0, tokens - new_token_count)+ if cleared_tokens >= self.clear_at_least:+ break++ return++ def _build_cleared_tool_input_message(+ self,+ message: AIMessage,+ tool_call_id: str,+ ) -> AIMessage:+ updated_tool_calls = []+ cleared_any = False+ for tool_call in message.tool_calls:+ updated_call = dict(tool_call)+ if updated_call.get("id") == tool_call_id:+ updated_call["args"] = {}+ cleared_any = True+ updated_tool_calls.append(updated_call)++ metadata = dict(getattr(message, "response_metadata", {}))+ context_entry = dict(metadata.get("context_editing", {}))+ if cleared_any:+ cleared_ids = set(context_entry.get("cleared_tool_inputs", []))+ cleared_ids.add(tool_call_id)+ context_entry["cleared_tool_inputs"] = sorted(cleared_ids)+ metadata["context_editing"] = context_entry++ return message.model_copy(+ update={+ "tool_calls": updated_tool_calls,+ "response_metadata": metadata,+ }+ )+++class ContextEditingMiddleware(AgentMiddleware):+ """Middleware that automatically prunes tool results to manage context size.++ The middleware applies a sequence of edits when the total input token count+ exceeds configured thresholds. Currently the ``ClearToolUsesEdit`` strategy is+ supported, aligning with Anthropic's ``clear_tool_uses_20250919`` behaviour.+ """++ edits: list[ContextEdit]+ token_count_method: Literal["approximate", "model"]++ def __init__(+ self,+ *,+ edits: Iterable[ContextEdit] | None = None,+ token_count_method: Literal["approximate", "model"] = "approximate", # noqa: S107+ ) -> None:+ """Initialise a context editing middleware instance.++ Args:+ edits: Sequence of edit strategies to apply. Defaults to a single+ `ClearToolUsesEdit` mirroring Anthropic defaults.+ token_count_method: Whether to use approximate token counting+ (faster, less accurate) or exact counting implemented by the+ chat model (potentially slower, more accurate).+ """+ super().__init__()+ self.edits = list(edits or (ClearToolUsesEdit(),))+ self.token_count_method = token_count_method++ def modify_model_request(+ self,+ request: ModelRequest,+ state: AgentState, # noqa: ARG002+ runtime: Runtime, # noqa: ARG002+ ) -> ModelRequest:+ """Modify the model request by applying context edits before invocation."""+ if not request.messages:+ return request++ if self.token_count_method == "approximate": # noqa: S105++ def count_tokens(messages: Sequence[BaseMessage]) -> int:+ return count_tokens_approximately(messages)+ else:+ system_msg = (+ [SystemMessage(content=request.system_prompt)] if request.system_prompt else []+ )++ def count_tokens(messages: Sequence[BaseMessage]) -> int:+ return request.model.get_num_tokens_from_messages(+ system_msg + list(messages), request.tools+ )++ for edit in self.edits:+ edit.apply(request.messages, count_tokens=count_tokens)++ return request+++__all__ = [+ "ClearToolUsesEdit",+ "ContextEditingMiddleware",+]diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_context_editing_middleware.py b/libs/langchain_v1/tests/unit_tests/agents/test_context_editing_middleware.pynew file mode 100644index 0000000000..ca612fe572--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_context_editing_middleware.py@@ -0,0 +1,216 @@+"""Tests for the ContextEditingMiddleware."""++from __future__ import annotations++from typing import Iterable, cast++from langchain.agents.middleware.context_editing import (+ ClearToolUsesEdit,+ ContextEditingMiddleware,+)+from langchain.agents.middleware.types import AgentState, ModelRequest+from langchain_core.language_models.fake_chat_models import FakeChatModel+from langchain_core.messages import (+ AIMessage,+ MessageLikeRepresentation,+ ToolMessage,+)+from langgraph.runtime import Runtime+++class _TokenCountingChatModel(FakeChatModel):+ """Fake chat model that counts tokens deterministically for tests."""++ def get_num_tokens_from_messages(+ self,+ messages: list[MessageLikeRepresentation],+ tools: Iterable | None = None, # noqa: ARG002+ ) -> int:+ return sum(_count_message_tokens(message) for message in messages)+++def _count_message_tokens(message: MessageLikeRepresentation) -> int:+ if isinstance(message, (AIMessage, ToolMessage)):+ return _count_content(message.content)+ if isinstance(message, str):+ return len(message)+ return len(str(message))+++def _count_content(content: MessageLikeRepresentation) -> int:+ if isinstance(content, str):+ return len(content)+ if isinstance(content, list):+ return sum(_count_content(block) for block in content) # type: ignore[arg-type]+ if isinstance(content, dict):+ return len(str(content))+ return len(str(content))+++def _make_state_and_request(+ messages: list[AIMessage | ToolMessage],+ *,+ system_prompt: str | None = None,+) -> tuple[AgentState, ModelRequest]:+ model = _TokenCountingChatModel()+ conversation = list(messages)+ state = cast(AgentState, {"messages": conversation})+ request = ModelRequest(+ model=model,+ system_prompt=system_prompt,+ messages=conversation,+ tool_choice=None,+ tools=[],+ response_format=None,+ model_settings={},+ )+ return state, request+++def test_no_edit_when_below_trigger() -> None:+ tool_call_id = "call-1"+ ai_message = AIMessage(+ content="",+ tool_calls=[{"id": tool_call_id, "name": "search", "args": {}}],+ )+ tool_message = ToolMessage(content="12345", tool_call_id=tool_call_id)++ state, request = _make_state_and_request([ai_message, tool_message])+ middleware = ContextEditingMiddleware(+ edits=[ClearToolUsesEdit(trigger=50)],+ )++ result = middleware.modify_model_request(request, state, _fake_runtime())++ assert result.messages[0].content == ""+ assert result.messages[1].content == "12345"+ assert state["messages"] == result.messages+++def test_clear_tool_outputs_and_inputs() -> None:+ tool_call_id = "call-2"+ ai_message = AIMessage(+ content=[+ {"type": "tool_call", "id": tool_call_id, "name": "search", "args": {"query": "foo"}}+ ],+ tool_calls=[{"id": tool_call_id, "name": "search", "args": {"query": "foo"}}],+ )+ tool_message = ToolMessage(content="x" * 200, tool_call_id=tool_call_id)++ state, request = _make_state_and_request([ai_message, tool_message])++ edit = ClearToolUsesEdit(+ trigger=50,+ clear_at_least=10,+ clear_tool_inputs=True,+ keep=0,+ placeholder="[cleared output]",+ )+ middleware = ContextEditingMiddleware(edits=[edit])++ result = middleware.modify_model_request(request, state, _fake_runtime())++ cleared_ai = result.messages[0]+ cleared_tool = result.messages[1]++ assert isinstance(cleared_tool, ToolMessage)+ assert cleared_tool.content == "[cleared output]"+ assert cleared_tool.response_metadata["context_editing"]["cleared"] is True++ assert isinstance(cleared_ai, AIMessage)+ assert cleared_ai.tool_calls[0]["args"] == {}+ context_meta = cleared_ai.response_metadata.get("context_editing")+ assert context_meta is not None+ assert context_meta["cleared_tool_inputs"] == [tool_call_id]++ assert state["messages"] == result.messages+++def test_respects_keep_last_tool_results() -> None:+ conversation: list[AIMessage | ToolMessage] = []+ edits = [+ ("call-a", "tool-output-a" * 5),+ ("call-b", "tool-output-b" * 5),+ ("call-c", "tool-output-c" * 5),+ ]++ for call_id, text in edits:+ conversation.append(+ AIMessage(+ content="",+ tool_calls=[{"id": call_id, "name": "tool", "args": {"input": call_id}}],+ )+ )+ conversation.append(ToolMessage(content=text, tool_call_id=call_id))++ state, request = _make_state_and_request(conversation)++ middleware = ContextEditingMiddleware(+ edits=[+ ClearToolUsesEdit(+ trigger=50,+ keep=1,+ placeholder="[cleared]",+ )+ ],+ token_count_method="model",+ )++ result = middleware.modify_model_request(request, state, _fake_runtime())++ cleared_messages = [+ msg+ for msg in result.messages+ if isinstance(msg, ToolMessage) and msg.content == "[cleared]"+ ]++ assert len(cleared_messages) == 2+ assert isinstance(result.messages[-1], ToolMessage)+ assert result.messages[-1].content != "[cleared]"+++def test_exclude_tools_prevents_clearing() -> None:+ search_call = "call-search"+ calc_call = "call-calc"++ state, request = _make_state_and_request(+ [+ AIMessage(+ content="",+ tool_calls=[{"id": search_call, "name": "search", "args": {"query": "foo"}}],+ ),+ ToolMessage(content="search-results" * 20, tool_call_id=search_call),+ AIMessage(+ content="",+ tool_calls=[{"id": calc_call, "name": "calculator", "args": {"a": 1, "b": 2}}],+ ),+ ToolMessage(content="42", tool_call_id=calc_call),+ ]+ )++ middleware = ContextEditingMiddleware(+ edits=[+ ClearToolUsesEdit(+ trigger=50,+ clear_at_least=10,+ keep=0,+ exclude_tools=("search",),+ placeholder="[cleared]",+ )+ ],+ )++ result = middleware.modify_model_request(request, state, _fake_runtime())++ search_tool = result.messages[1]+ calc_tool = result.messages[3]++ assert isinstance(search_tool, ToolMessage)+ assert search_tool.content == "search-results" * 20++ assert isinstance(calc_tool, ToolMessage)+ assert calc_tool.content == "[cleared]"+++def _fake_runtime() -> Runtime:+ return cast(Runtime, object())