Skip to content

The agent engineering platform.

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__.py
index 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 HumanInTheLoopMiddleware
from .model_fallback import ModelFallbackMiddleware
from .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.py
new file mode 100644
index 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.py
new file mode 100644
index 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())