The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(langchain): filter internal middleware model calls from `messages` projection (#39252)
Nishitha M89cc9c5cbb23
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.pyindex a66b027387..8ca411fce8 100644--- a/libs/langchain_v1/langchain/agents/factory.py+++ b/libs/langchain_v1/langchain/agents/factory.py@@ -77,7 +77,7 @@ class _ComposedExtendedModelResponse(Generic[ResponseT]):if TYPE_CHECKING:- from collections.abc import Awaitable, Callable, Sequence+ from collections.abc import Awaitable, Callable, Iterable, Sequencefrom langchain_core.runnables import Runnable, RunnableConfigfrom langgraph.cache.base import BaseCache@@ -1796,6 +1796,9 @@ def create_agent(if name:config["metadata"]["lc_agent_name"] = name+ # Middleware that makes internal model calls (e.g. `SummarizationMiddleware`)+ # each declare `InternalCallTransformer` on their own `transformers` tuple so+ # it's only registered when one of them is actually in use.middleware_transformers = [t for m in middleware for t in getattr(m, "transformers", ())]return graph.compile(@@ -1806,15 +1809,44 @@ def create_agent(debug=debug,name=name,cache=cache,- transformers=[- ToolCallTransformer,- SubagentTransformer,- *middleware_transformers,- *(transformers or ()),- ],+ transformers=_dedupe_transformers(+ [+ ToolCallTransformer,+ SubagentTransformer,+ *middleware_transformers,+ *(transformers or ()),+ ]+ ),).with_config(config)+def _dedupe_transformers(+ factories: Iterable[TransformerFactory],+) -> list[TransformerFactory]:+ """Order-preserving de-dup of transformer factories, by identity.++ `AgentMiddleware.transformers` accepts any scope-aware callable, and+ callables aren't required to be hashable (e.g. a dataclass-based factory+ with `__hash__ = None`), so this can't use a `set`/`dict` keyed on the+ factories themselves. Combining several middleware that each declare the+ same shared transformer class (e.g. `InternalCallTransformer`) would+ otherwise register it once per middleware.++ Args:+ factories: Transformer factories to de-dup, in registration order.++ Returns:+ The same factories with exact repeats (by `is`) removed, order kept.+ """+ seen_ids: set[int] = set()+ deduped: list[TransformerFactory] = []+ for factory in factories:+ if id(factory) not in seen_ids:+ seen_ids.add(id(factory))+ deduped.append(factory)+ return deduped++def _resolve_jump(jump_to: JumpTo | None,*,diff --git a/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.py b/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.pynew file mode 100644index 0000000000..bb8933e98f--- /dev/null+++ b/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.py@@ -0,0 +1,141 @@+"""Tag and filter middleware-internal model calls.++Middleware may make bookkeeping model calls (e.g. summarization or tool+selection) in the same graph namespace as the main agent call, causing their+tokens to appear in `run.messages`.++Tag these calls with `internal_call_metadata()` and declare+`transformers = (InternalCallTransformer,)` on the middleware class so it's+only registered on agents that actually use it — see `AgentMiddleware.transformers`.+Both are public so third-party middleware can adopt the same pattern.+"""++from __future__ import annotations++import secrets+from typing import TYPE_CHECKING, Any, ClassVar++from langchain_core.messages import BaseMessage+from langgraph.stream import StreamTransformer++if TYPE_CHECKING:+ from langgraph.stream._types import ProtocolEvent++INTERNAL_CALL_METADATA_KEY = "lc_internal_call"+"""`RunnableConfig` metadata key marking a model call as internal to middleware.++Kept separate from `lc_source` (used by `SummarizationMiddleware` to advertise+that a summarization call is in flight) so tagging a call for filtering here+never changes what other consumers observe via that key.+"""++_INTERNAL_CALL_TOKEN = secrets.token_hex(16)+"""Unguessable marker value, regenerated on import.++`config["metadata"]` ultimately comes from a `RunnableConfig`, which callers+of `invoke`/`stream_events` can populate with arbitrary values — including+the main agent turn's own call, since it goes through the same ambient+config. If the marker were a fixed value like `True`, a caller who can+influence invocation metadata (e.g. an API layer that forwards user-supplied+metadata) could set `lc_internal_call` themselves and hide the agent's real+answer from `run.messages`. Comparing against this process-local secret+instead of truthiness means a caller can't forge it without already being+able to run code in this process.+"""+++def internal_call_metadata() -> dict[str, Any]:+ """Return metadata that marks a model call as internal to middleware.++ Returns:+ A mapping to merge into a model call's `config["metadata"]`.+ """+ return {INTERNAL_CALL_METADATA_KEY: _INTERNAL_CALL_TOKEN}+++class InternalCallTransformer(StreamTransformer):+ """Keep internal model calls out of `run.messages` and the raw event log.++ Declared on `transformers` by middleware that makes internal calls (e.g.+ `SummarizationMiddleware`), so it's only registered on agents using one of+ those, and runs before built-in transformers.++ `messages`-mode events come in two shapes, and influencing+ `MessagesTransformer`'s built-in exclusion rules for either one requires+ mutating the event in place (there's no metadata hook it consults). That+ mutation would misrepresent the call if it also reached raw event+ consumers — a real AI response reported as `role: "tool"`, or a payload+ replaced with `None`, neither a real messages-mode shape — so tagged+ events are dropped from the raw log entirely rather than published in a+ mutated form:++ - Streamed protocol events (`message-start` / `content-block-*` /+ `message-finish`): `message-start`'s `role` is rewritten to `"tool"`,+ reusing `MessagesTransformer`'s existing tool-result exclusion, then+ the event is dropped.+ - Whole-`AIMessage` events — the fallback `MessagesTransformer` uses when+ a chat model doesn't stream (notably, streaming context isn't+ propagated on Python 3.10) or when a node returns a finalized message+ as state: the payload is cleared so `MessagesTransformer` has nothing+ left to route, then the event is dropped.++ Only events in this transformer's own scope are touched — nested+ subgraphs get their own scoped instance (if the offending middleware runs+ there too), and `MessagesTransformer` itself ignores events outside its+ scope, so mutating them here would be both unnecessary and unsafe.+ """++ before_builtins: ClassVar[bool] = True+ required_stream_modes: ClassVar[tuple[str, ...]] = ("messages",)++ def __init__(self, scope: tuple[str, ...] = ()) -> None:+ """Initialize the transformer, scoped to a single mux/namespace.++ Args:+ scope: The namespace tuple the owning mux is scoped to.+ """+ super().__init__(scope)+ self._scope_list: list[str] = list(scope)++ def init(self) -> dict[str, Any]:+ """Return an empty projection — this transformer only suppresses events.++ Returns:+ An empty mapping; no `run.<key>` projection is added.+ """+ return {}++ def process(self, event: ProtocolEvent) -> bool:+ """Drop tagged `messages` events after nudging `MessagesTransformer` to ignore them.++ Args:+ event: The protocol event to observe, and possibly mutate.++ Returns:+ `False` to drop a tagged internal call from the raw event log and+ `run.messages`; `True` otherwise.+ """+ if event["method"] != "messages":+ return True++ params = event["params"]+ if params["namespace"] != self._scope_list:+ return True++ payload, metadata = params["data"]+ is_internal = (+ bool(metadata) and metadata.get(INTERNAL_CALL_METADATA_KEY) == _INTERNAL_CALL_TOKEN+ )+ if not is_internal:+ return True++ # Only `message-start` needs mutating: once MessagesTransformer sees its+ # `role` spoofed as "tool", its own tool-result bookkeeping ignores every+ # later event for this run_id, so content-block-*/message-finish need no+ # action here, the whole run gets dropped below regardless.+ if isinstance(payload, dict) and payload.get("event") == "message-start":+ payload["role"] = "tool"+ elif isinstance(payload, BaseMessage):+ params["data"] = (None, metadata)++ return Falsediff --git a/libs/langchain_v1/langchain/agents/middleware/summarization.py b/libs/langchain_v1/langchain/agents/middleware/summarization.pyindex a68c051b4f..0695693a84 100644--- a/libs/langchain_v1/langchain/agents/middleware/summarization.py+++ b/libs/langchain_v1/langchain/agents/middleware/summarization.py@@ -25,6 +25,10 @@ from langgraph.graph.message import (from langgraph.runtime import Runtimefrom typing_extensions import override+from langchain.agents.middleware.internal_call_transformer import (+ InternalCallTransformer,+ internal_call_metadata,+)from langchain.agents.middleware.types import AgentMiddleware, AgentState, ContextT, ResponseTfrom langchain.chat_models import BaseChatModel, init_chat_model@@ -230,6 +234,13 @@ class SummarizationMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Rcontext continuity by ensuring AI/Tool message pairs remain together."""+ transformers = (InternalCallTransformer,)+ """Keeps the summarization model call's tokens out of `run.messages`.++ Registered only when this middleware is used — see+ `InternalCallTransformer` for why the call needs tagging and filtering.+ """+def __init__(self,model: str | BaseChatModel,@@ -821,7 +832,7 @@ class SummarizationMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Rtry:response = self.model.invoke(self.summary_prompt.format(messages=formatted_messages).rstrip(),- config={"metadata": {"lc_source": "summarization"}},+ config={"metadata": {"lc_source": "summarization", **internal_call_metadata()}},)return response.text.strip()except Exception as e:@@ -847,7 +858,7 @@ class SummarizationMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Rtry:response = await self.model.ainvoke(self.summary_prompt.format(messages=formatted_messages).rstrip(),- config={"metadata": {"lc_source": "summarization"}},+ config={"metadata": {"lc_source": "summarization", **internal_call_metadata()}},)return response.text.strip()except Exception as e:diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_emulator.py b/libs/langchain_v1/langchain/agents/middleware/tool_emulator.pyindex 61dfcb7e11..fe0b1766ea 100644--- a/libs/langchain_v1/langchain/agents/middleware/tool_emulator.py+++ b/libs/langchain_v1/langchain/agents/middleware/tool_emulator.py@@ -7,6 +7,10 @@ from typing import TYPE_CHECKING, Any, Genericfrom langchain_core.language_models.chat_models import BaseChatModelfrom langchain_core.messages import HumanMessage, ToolMessage+from langchain.agents.middleware.internal_call_transformer import (+ InternalCallTransformer,+ internal_call_metadata,+)from langchain.agents.middleware.types import AgentMiddleware, AgentState, ContextTfrom langchain.chat_models.base import init_chat_model@@ -63,6 +67,13 @@ class LLMToolEmulator(AgentMiddleware[AgentState[Any], ContextT], Generic[Contex```"""+ transformers = (InternalCallTransformer,)+ """Keeps the emulation model call's tokens out of `run.messages`.++ Registered only when this middleware is used — see+ `InternalCallTransformer` for why the call needs tagging and filtering.+ """+def __init__(self,*,@@ -147,7 +158,10 @@ class LLMToolEmulator(AgentMiddleware[AgentState[Any], ContextT], Generic[Contex)# Get emulated response from LLM- response = self.model.invoke([HumanMessage(prompt)])+ response = self.model.invoke(+ [HumanMessage(prompt)],+ config={"metadata": {"lc_source": "tool_emulation", **internal_call_metadata()}},+ )# Short-circuit: return emulated result without executing real toolreturn ToolMessage(@@ -199,7 +213,10 @@ class LLMToolEmulator(AgentMiddleware[AgentState[Any], ContextT], Generic[Contex)# Get emulated response from LLM (using async invoke)- response = await self.model.ainvoke([HumanMessage(prompt)])+ response = await self.model.ainvoke(+ [HumanMessage(prompt)],+ config={"metadata": {"lc_source": "tool_emulation", **internal_call_metadata()}},+ )# Short-circuit: return emulated result without executing real toolreturn ToolMessage(diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_selection.py b/libs/langchain_v1/langchain/agents/middleware/tool_selection.pyindex e55e267f10..abee5a24a9 100644--- a/libs/langchain_v1/langchain/agents/middleware/tool_selection.py+++ b/libs/langchain_v1/langchain/agents/middleware/tool_selection.py@@ -12,6 +12,10 @@ from langchain_core.messages import AIMessage, BaseMessage, HumanMessagefrom pydantic import Field, TypeAdapterfrom typing_extensions import TypedDict+from langchain.agents.middleware.internal_call_transformer import (+ InternalCallTransformer,+ internal_call_metadata,+)from langchain.agents.middleware.types import (AgentMiddleware,AgentState,@@ -145,6 +149,13 @@ class LLMToolSelectorMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT,```"""+ transformers = (InternalCallTransformer,)+ """Keeps the tool-selection model call's tokens out of `run.messages`.++ Registered only when this middleware is used — see+ `InternalCallTransformer` for why the call needs tagging and filtering.+ """+def __init__(self,*,@@ -401,7 +412,9 @@ class LLMToolSelectorMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT,{"role": "system", "content": selection_request.system_message},selection_request.last_user_message,]- config: RunnableConfig = {"metadata": {"lc_source": "tool_selection"}}+ config: RunnableConfig = {+ "metadata": {"lc_source": "tool_selection", **internal_call_metadata()}+ }response = structured_model.invoke(messages, config=config)attempts = 0@@ -466,7 +479,9 @@ class LLMToolSelectorMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT,{"role": "system", "content": selection_request.system_message},selection_request.last_user_message,]- config: RunnableConfig = {"metadata": {"lc_source": "tool_selection"}}+ config: RunnableConfig = {+ "metadata": {"lc_source": "tool_selection", **internal_call_metadata()}+ }response = await structured_model.ainvoke(messages, config=config)attempts = 0diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_internal_call_transformer.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_internal_call_transformer.pynew file mode 100644index 0000000000..d5f5d37e57--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_internal_call_transformer.py@@ -0,0 +1,386 @@+"""Tests for `InternalCallTransformer` filtering middleware-internal model calls."""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from langchain_core.language_models.fake_chat_models import GenericFakeChatModel+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage+from langgraph.stream.transformers import MessagesTransformer++from langchain.agents.factory import create_agent+from langchain.agents.middleware import AgentMiddleware+from langchain.agents.middleware import (+ internal_call_transformer as internal_call_transformer_module,+)+from langchain.agents.middleware.internal_call_transformer import (+ INTERNAL_CALL_METADATA_KEY,+ InternalCallTransformer,+ internal_call_metadata,+)+from langchain.agents.middleware.summarization import SummarizationMiddleware+from tests.unit_tests.agents.model import FakeToolCallingModel++if TYPE_CHECKING:+ from collections.abc import Awaitable, Callable++ from langchain.agents.middleware.types import ModelRequest, ModelResponse+++class _InternalCallMiddleware(AgentMiddleware):+ """Calls a side model tagged as internal before letting the main turn run."""++ transformers = (InternalCallTransformer,)++ def __init__(self, internal_model: GenericFakeChatModel) -> None:+ super().__init__()+ self.internal_model = internal_model++ def wrap_model_call(+ self,+ request: ModelRequest[Any],+ handler: Callable[[ModelRequest[Any]], ModelResponse[Any]],+ ) -> ModelResponse[Any]:+ self.internal_model.invoke(+ [HumanMessage("internal check")],+ config={"metadata": internal_call_metadata()},+ )+ return handler(request)++ async def awrap_model_call(+ self,+ request: ModelRequest[Any],+ handler: Callable[[ModelRequest[Any]], Awaitable[ModelResponse[Any]]],+ ) -> ModelResponse[Any]:+ await self.internal_model.ainvoke(+ [HumanMessage("internal check")],+ config={"metadata": internal_call_metadata()},+ )+ return await handler(request)+++class _InternalWholeMessageMiddleware(AgentMiddleware):+ """Calls a non-streaming internal model that surfaces via `on_chain_end`.++ A model with no `_stream`/`_astream` override reports its output as a+ whole `AIMessage` `messages`-mode event rather than streamed protocol+ events — the shape `MessagesTransformer` falls back to on Python 3.10,+ or for any model/provider that doesn't stream.+ """++ transformers = (InternalCallTransformer,)++ def __init__(self, internal_model: FakeToolCallingModel) -> None:+ super().__init__()+ self.internal_model = internal_model++ def before_model(self, state: Any, runtime: Any) -> None: # noqa: ARG002+ self.internal_model.invoke(+ [HumanMessage("internal check")],+ config={"metadata": internal_call_metadata()},+ )++ async def abefore_model(self, state: Any, runtime: Any) -> None: # noqa: ARG002+ await self.internal_model.ainvoke(+ [HumanMessage("internal check")],+ config={"metadata": internal_call_metadata()},+ )+++def test_internal_call_transformer_not_registered_without_offending_middleware() -> None:+ """A plain agent with no internal-call middleware doesn't pay for the filter."""+ agent = create_agent(model=FakeToolCallingModel(), tools=[])++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")+ transformers = run._mux._transformers++ assert not any(isinstance(t, InternalCallTransformer) for t in transformers)++ # Drain to close cleanly.+ list(run.tool_calls)+++def test_internal_call_transformer_registered_before_messages_transformer() -> None:+ """Middleware declaring `transformers` registers it, ahead of built-ins."""+ agent = create_agent(+ model=FakeToolCallingModel(),+ tools=[],+ middleware=[+ _InternalCallMiddleware(+ GenericFakeChatModel(messages=iter([AIMessage(content="internal")]))+ )+ ],+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")+ transformers = run._mux._transformers++ internal_idx = next(+ i for i, t in enumerate(transformers) if isinstance(t, InternalCallTransformer)+ )+ messages_idx = next(i for i, t in enumerate(transformers) if isinstance(t, MessagesTransformer))+ assert internal_idx < messages_idx, (+ "InternalCallTransformer must be registered before MessagesTransformer "+ "so tagged events never reach the messages projection"+ )++ # Drain to close cleanly.+ list(run.tool_calls)+++def test_internal_call_transformer_deduped_across_middleware() -> None:+ """Combining two internal-call middleware doesn't double-register the transformer."""+ agent = create_agent(+ model=FakeToolCallingModel(),+ tools=[],+ middleware=[+ _InternalCallMiddleware(+ GenericFakeChatModel(messages=iter([AIMessage(content="internal")]))+ ),+ _InternalWholeMessageMiddleware(FakeToolCallingModel(index=1000)),+ ],+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")+ transformers = run._mux._transformers++ assert sum(isinstance(t, InternalCallTransformer) for t in transformers) == 1++ # Drain to close cleanly.+ list(run.tool_calls)+++def test_internal_call_transformer_deduped_alongside_builtins() -> None:+ """Dedup covers the whole transformer list, not just middleware-supplied ones."""+ agent = create_agent(+ model=FakeToolCallingModel(),+ tools=[],+ middleware=[+ _InternalCallMiddleware(+ GenericFakeChatModel(messages=iter([AIMessage(content="internal")]))+ )+ ],+ # Re-supplying a built-in explicitly should still collapse to one instance.+ transformers=[InternalCallTransformer],+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")+ transformers = run._mux._transformers++ assert sum(isinstance(t, InternalCallTransformer) for t in transformers) == 1++ # Drain to close cleanly.+ list(run.tool_calls)+++def test_internal_call_transformer_dedup_accepts_unhashable_factories() -> None:+ """De-dup must not require transformer factories to be hashable."""++ class _UnhashableFactory:+ """A callable factory with hashing disabled, like an `eq`-only dataclass."""++ __hash__ = None # type: ignore[assignment]++ def __call__(self, scope: tuple[str, ...]) -> InternalCallTransformer:+ return InternalCallTransformer(scope)++ class _UnhashableTransformerMiddleware(AgentMiddleware):+ transformers = (_UnhashableFactory(),)++ # Must not raise `TypeError: unhashable type`.+ agent = create_agent(+ model=FakeToolCallingModel(), tools=[], middleware=[_UnhashableTransformerMiddleware()]+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")+ list(run.tool_calls)+++def test_internal_model_calls_excluded_from_messages_projection_sync() -> None:+ """Sync `stream_events` should also exclude internal middleware calls."""+ main_model = GenericFakeChatModel(messages=iter([AIMessage(content="final answer")]))+ internal_model = GenericFakeChatModel(messages=iter([AIMessage(content="internal check")]))+ agent = create_agent(+ model=main_model, tools=[], middleware=[_InternalCallMiddleware(internal_model)]+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")++ streams = list(run.messages)+ assert len(streams) == 1++ # Drain the surviving stream so the run closes cleanly.+ list(streams[0].text)+++async def test_internal_model_calls_excluded_from_messages_projection() -> None:+ """`run.messages` should only surface the main turn, not internal middleware calls."""+ main_model = GenericFakeChatModel(messages=iter([AIMessage(content="final answer")]))+ internal_model = GenericFakeChatModel(messages=iter([AIMessage(content="internal check")]))+ agent = create_agent(+ model=main_model, tools=[], middleware=[_InternalCallMiddleware(internal_model)]+ )++ run = await agent.astream_events({"messages": [HumanMessage("hi")]}, version="v3")++ streams = [msg async for msg in run.messages]+ assert len(streams) == 1++ # Drain the surviving stream so the run closes cleanly.+ async for _ in streams[0].text:+ pass+++async def test_internal_model_calls_excluded_from_raw_event_log() -> None:+ """Internal calls must not leak into the raw protocol event stream either.++ Mutating an event to influence `MessagesTransformer` (there's no metadata+ hook it consults, so mutation is the only lever) would misrepresent the+ call to any consumer that also sees the raw log — a real AI response+ reported as `role: "tool"`, for instance. So tagged calls are dropped+ from the raw log entirely rather than published in a mutated form.+ """+ main_model = GenericFakeChatModel(messages=iter([AIMessage(content="final answer")]))+ internal_model = GenericFakeChatModel(messages=iter([AIMessage(content="internal check")]))+ agent = create_agent(+ model=main_model, tools=[], middleware=[_InternalCallMiddleware(internal_model)]+ )++ run = await agent.astream_events({"messages": [HumanMessage("hi")]}, version="v3")++ seen_text: list[str] = []+ async for event in run:+ if event.get("method") != "messages":+ continue+ data = event["params"].get("data")+ if not isinstance(data, tuple) or len(data) != 2:+ continue+ payload = data[0]+ if isinstance(payload, dict):+ delta = payload.get("delta") or {}+ if text := delta.get("text"):+ seen_text.append(text)+ elif isinstance(payload, BaseMessage):+ seen_text.append(payload.text)++ combined = "".join(seen_text)+ assert "internal check" not in combined+ assert "final answer" in combined+++async def test_internal_whole_message_excluded_from_messages_projection() -> None:+ """A non-streaming internal call's whole-`AIMessage` event is filtered too."""+ main_model = FakeToolCallingModel()+ # Offset so the two fake models don't both mint id="0" (FakeToolCallingModel+ # ids messages from a per-instance counter starting at 0), which would make+ # `MessagesTransformer`'s own id-based dedupe hide the main turn regardless+ # of this transformer.+ internal_model = FakeToolCallingModel(index=1000)+ agent = create_agent(+ model=main_model, tools=[], middleware=[_InternalWholeMessageMiddleware(internal_model)]+ )++ run = await agent.astream_events({"messages": [HumanMessage("hi")]}, version="v3")++ texts: list[str] = []+ async for msg in run.messages:+ text = ""+ async for chunk in msg.text:+ text += chunk+ texts.append(text)++ assert texts == ["hi"]+++async def test_internal_whole_message_excluded_from_raw_event_log() -> None:+ """A non-streaming internal call's whole-`AIMessage` event never hits the raw log."""+ main_model = FakeToolCallingModel()+ internal_model = FakeToolCallingModel(index=1000)+ agent = create_agent(+ model=main_model, tools=[], middleware=[_InternalWholeMessageMiddleware(internal_model)]+ )++ run = await agent.astream_events({"messages": [HumanMessage("hi")]}, version="v3")++ payloads: list[Any] = []+ async for event in run:+ if event.get("method") != "messages":+ continue+ data = event["params"].get("data")+ if isinstance(data, tuple) and len(data) == 2:+ payloads.append(data[0])++ # Only the main turn's message made it to the raw log.+ assert len(payloads) == 1+ assert isinstance(payloads[0], BaseMessage)+ assert payloads[0].text == "hi"+++async def test_caller_supplied_metadata_cannot_forge_internal_marker() -> None:+ """A caller can't hide the agent's real answer by guessing the marker's value.++ `config["metadata"]` on the top-level `invoke`/`stream_events` call flows+ into every model call made during the run, including the main agent+ turn's own — so if the marker were a predictable value (e.g. `True`), an+ attacker-controlled caller (or an API layer forwarding user-supplied+ metadata) could set `lc_internal_call` themselves and make the agent's+ real answer disappear from `run.messages`.+ """+ main_model = GenericFakeChatModel(messages=iter([AIMessage(content="final answer")]))+ summarizer_model = GenericFakeChatModel(messages=iter([AIMessage(content="summary")]))+ middleware = SummarizationMiddleware(model=summarizer_model, trigger=("messages", 1))+ agent = create_agent(model=main_model, tools=[], middleware=[middleware])++ forged_metadata = {INTERNAL_CALL_METADATA_KEY: True}+ assert forged_metadata != internal_call_metadata(), (+ "the real marker must not be a guessable value like `True`"+ )++ run = await agent.astream_events(+ {"messages": [HumanMessage("hi"), HumanMessage("there"), HumanMessage("again")]},+ config={"metadata": forged_metadata},+ version="v3",+ )++ texts: list[str] = []+ async for msg in run.messages:+ text = ""+ async for chunk in msg.text:+ text += chunk+ texts.append(text)++ assert texts == ["final answer"]+++def test_internal_call_token_is_not_a_predictable_value() -> None:+ """The marker's value must not be something a caller could plausibly guess."""+ token = internal_call_transformer_module._INTERNAL_CALL_TOKEN+ assert token not in (True, False, None, "", "true", "internal", INTERNAL_CALL_METADATA_KEY)+ assert len(str(token)) >= 16+++def test_process_ignores_events_outside_its_own_scope() -> None:+ """A root-scoped transformer must not touch a nested subgraph's events.++ `MessagesTransformer` itself ignores events whose namespace doesn't+ match its own scope, and a correctly-scoped `InternalCallTransformer`+ instance (if the offending middleware runs inside that subgraph too)+ would already handle them — so mutating or dropping them here would be+ both unnecessary and would corrupt a namespace this instance doesn't own.+ """+ transformer = InternalCallTransformer(())+ payload = {"event": "message-start", "role": "ai", "id": "msg-1"}+ metadata = {**internal_call_metadata(), "run_id": "run-1"}+ event: Any = {+ "type": "event",+ "method": "messages",+ "params": {+ "namespace": ["some-subgraph"],+ "timestamp": 0,+ "data": (payload, metadata),+ },+ }++ assert transformer.process(event) is True+ assert event["params"]["data"] == (payload, metadata)+ assert payload["role"] == "ai"diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_summarization.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_summarization.pyindex e1fad4e0f8..a01b94e327 100644--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_summarization.py+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_summarization.py@@ -11,6 +11,7 @@ from langchain_core.language_models.base import (LanguageModelInput,)from langchain_core.language_models.chat_models import BaseChatModel+from langchain_core.language_models.fake_chat_models import GenericFakeChatModelfrom langchain_core.messages import (AIMessage,AnyMessage,@@ -28,7 +29,11 @@ from langgraph.runtime import Runtimefrom pydantic import Fieldfrom typing_extensions import override-from langchain.agents import AgentState+from langchain.agents import AgentState, create_agent+from langchain.agents.middleware.internal_call_transformer import (+ INTERNAL_CALL_METADATA_KEY,+ internal_call_metadata,+)from langchain.agents.middleware.summarization import (ContextSize,SummarizationMiddleware,@@ -2107,3 +2112,47 @@ async def test_create_summary_passes_lc_source_metadata(use_async: bool) -> Noneassert config is not Noneassert "metadata" in configassert config["metadata"]["lc_source"] == "summarization"+ assert (+ config["metadata"][INTERNAL_CALL_METADATA_KEY]+ == internal_call_metadata()[INTERNAL_CALL_METADATA_KEY]+ )+++class TestSummarizationStreamingEndToEnd:+ """End-to-end: a real summarization call must not leak into `run.messages`."""++ async def test_summarization_call_excluded_from_messages_projection(self) -> None:+ """Drives `create_agent` with a triggered summarization mid-run.++ Uses `GenericFakeChatModel` for both the main agent and the+ summarizer (it actually streams via `_astream`, unlike+ `FakeToolCallingModel`), then asserts `run.messages` surfaces only+ the agent's real answer.+ """+ main_model = GenericFakeChatModel(messages=iter([AIMessage(content="Final answer.")]))+ summarizer_model = GenericFakeChatModel(+ messages=iter([AIMessage(content="Summary of prior turns.")])+ )+ middleware = SummarizationMiddleware(model=summarizer_model, trigger=("messages", 1))++ agent = create_agent(model=main_model, tools=[], middleware=[middleware])++ run = await agent.astream_events(+ {+ "messages": [+ HumanMessage("hi"),+ HumanMessage("there"),+ HumanMessage("again"),+ ]+ },+ version="v3",+ )++ texts: list[str] = []+ async for msg in run.messages:+ text = ""+ async for chunk in msg.text:+ text += chunk+ texts.append(text)++ assert texts == ["Final answer."]diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_emulator.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_emulator.pyindex 5f434c63b5..d2a28c975f 100644--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_emulator.py+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_emulator.py@@ -9,14 +9,19 @@ from langchain_core.language_models.chat_models import BaseChatModelfrom langchain_core.language_models.fake_chat_models import GenericFakeChatModelfrom langchain_core.messages import BaseMessage, HumanMessagefrom langchain_core.outputs import ChatGeneration, ChatResult-from langchain_core.runnables import Runnable+from langchain_core.runnables import Runnable, RunnableConfigfrom langchain_core.tools import BaseTool, tool-from pydantic import BaseModel+from pydantic import BaseModel, Fieldfrom typing_extensions import overridefrom langchain.agents import create_agentfrom langchain.agents.middleware import LLMToolEmulator+from langchain.agents.middleware.internal_call_transformer import (+ INTERNAL_CALL_METADATA_KEY,+ internal_call_metadata,+)from langchain.messages import AIMessage+from tests.unit_tests.agents.model import FakeToolCallingModel@tool@@ -119,6 +124,52 @@ class FakeEmulatorModel(BaseChatModel):return "fake_emulator"+class ConfigCapturingEmulatorModel(BaseChatModel):+ """Fake model that captures the config passed to invoke/ainvoke."""++ captured_configs: list[RunnableConfig | None] = Field(default_factory=list, exclude=True)++ @override+ def invoke(+ self,+ input: LanguageModelInput,+ config: RunnableConfig | None = None,+ *,+ stop: list[str] | None = None,+ **kwargs: Any,+ ) -> AIMessage:+ self.captured_configs.append(config)+ return AIMessage(content="Emulated response")++ @override+ async def ainvoke(+ self,+ input: LanguageModelInput,+ config: RunnableConfig | None = None,+ *,+ stop: list[str] | None = None,+ **kwargs: Any,+ ) -> AIMessage:+ self.captured_configs.append(config)+ return AIMessage(content="Emulated response")++ @override+ def _generate(+ self,+ messages: list[BaseMessage],+ stop: list[str] | None = None,+ run_manager: Any = None,+ **kwargs: Any,+ ) -> ChatResult:+ return ChatResult(+ generations=[ChatGeneration(message=AIMessage(content="Emulated response"))]+ )++ @property+ def _llm_type(self) -> str:+ return "config-capturing-emulator"++class TestLLMToolEmulatorBasic:"""Test basic tool emulator functionality."""@@ -625,3 +676,104 @@ class TestLLMToolEmulatorAsync:calc_messages = [msg for msg in tool_messages if msg.name == "calculator"]assert len(calc_messages) > 0assert "Result: 20" in calc_messages[0].content+++class TestLLMToolEmulatorInternalCallMetadata:+ """Test that emulation calls are tagged as internal for stream filtering."""++ def test_wrap_tool_call_marks_internal_call(self) -> None:+ """`wrap_tool_call` should tag its model call as internal to middleware."""+ model = ConfigCapturingEmulatorModel()+ emulator = LLMToolEmulator(tools=["get_weather"], model=model)++ agent_model = FakeModel(+ messages=cycle(+ [+ AIMessage(+ content="",+ tool_calls=[+ {"name": "get_weather", "id": "1", "args": {"location": "NYC"}}+ ],+ ),+ AIMessage(content="Done."),+ ]+ )+ )+ agent = create_agent(model=agent_model, tools=[get_weather], middleware=[emulator])+ agent.invoke({"messages": [HumanMessage("Weather in NYC")]})++ assert len(model.captured_configs) == 1+ config = model.captured_configs[0]+ assert config is not None+ assert config["metadata"]["lc_source"] == "tool_emulation"+ assert (+ config["metadata"][INTERNAL_CALL_METADATA_KEY]+ == internal_call_metadata()[INTERNAL_CALL_METADATA_KEY]+ )++ async def test_awrap_tool_call_marks_internal_call(self) -> None:+ """`awrap_tool_call` should tag its model call as internal to middleware."""+ model = ConfigCapturingEmulatorModel()+ emulator = LLMToolEmulator(tools=["get_weather"], model=model)++ agent_model = FakeModel(+ messages=cycle(+ [+ AIMessage(+ content="",+ tool_calls=[+ {"name": "get_weather", "id": "1", "args": {"location": "NYC"}}+ ],+ ),+ AIMessage(content="Done."),+ ]+ )+ )+ agent = create_agent(model=agent_model, tools=[get_weather], middleware=[emulator])+ await agent.ainvoke({"messages": [HumanMessage("Weather in NYC")]})++ assert len(model.captured_configs) == 1+ config = model.captured_configs[0]+ assert config is not None+ assert config["metadata"]["lc_source"] == "tool_emulation"+ assert (+ config["metadata"][INTERNAL_CALL_METADATA_KEY]+ == internal_call_metadata()[INTERNAL_CALL_METADATA_KEY]+ )+++class TestLLMToolEmulatorStreamingEndToEnd:+ """End-to-end: a real emulation call must not leak into `run.messages`."""++ async def test_emulated_tool_call_excluded_from_messages_projection(self) -> None:+ """Drives `create_agent` with a real streaming emulator model.++ `GenericFakeChatModel` (unlike `FakeEmulatorModel`) actually streams+ via `_astream`, so this exercises the same token-leak path as a real+ provider. The agent's own two model turns (deciding to call the+ tool, then answering) always surface in `run.messages`, so a leak+ would show up as a *third* stream carrying the emulator's content.+ """+ agent_model = FakeToolCallingModel(+ tool_calls=[[{"name": "get_weather", "args": {"location": "NYC"}, "id": "tc1"}], []]+ )+ emulator_model = GenericFakeChatModel(messages=iter([AIMessage(content="XEMULATEDX")]))+ emulator = LLMToolEmulator(tools=["get_weather"], model=emulator_model)++ agent = create_agent(model=agent_model, tools=[get_weather], middleware=[emulator])++ run = await agent.astream_events(+ {"messages": [HumanMessage("Weather in NYC?")]}, version="v3"+ )++ texts: list[str] = []+ async for msg in run.messages:+ text = ""+ async for chunk in msg.text:+ text += chunk+ texts.append(text)++ # Exactly the agent's two real turns — no separate stream for the+ # emulator's own call, and its content is never on its own.+ assert len(texts) == 2+ assert "XEMULATEDX" not in textsdiff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_selection.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_selection.pyindex a2eecf82e2..b196ece0ec 100644--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_selection.py+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_selection.py@@ -8,9 +8,9 @@ import pytestfrom langchain_core.language_models import LanguageModelInputfrom langchain_core.language_models.fake_chat_models import GenericFakeChatModelfrom langchain_core.messages import HumanMessage-from langchain_core.runnables import Runnable+from langchain_core.runnables import Runnable, RunnableConfigfrom langchain_core.tools import BaseTool, tool-from pydantic import BaseModel+from pydantic import BaseModel, Fieldfrom typing_extensions import overridefrom langchain.agents import create_agent@@ -20,6 +20,10 @@ from langchain.agents.middleware import (ModelResponse,wrap_model_call,)+from langchain.agents.middleware.internal_call_transformer import (+ INTERNAL_CALL_METADATA_KEY,+ internal_call_metadata,+)from langchain.agents.middleware.tool_selection import _create_tool_selection_responsefrom langchain.messages import AIMessage@@ -862,3 +866,111 @@ class TestMalformedSelectionResponse:assert tool_names == ["search_web"]assert len(received) == 1assert received[0] == {"oops": True}+++class ConfigCapturingSelectionModel(FakeModel):+ """`FakeModel` that records the config passed to invoke/ainvoke."""++ captured_configs: list[RunnableConfig | None] = Field(default_factory=list, exclude=True)++ @override+ def invoke(+ self,+ input: LanguageModelInput,+ config: RunnableConfig | None = None,+ *,+ stop: list[str] | None = None,+ **kwargs: Any,+ ) -> AIMessage:+ self.captured_configs.append(config)+ return super().invoke(input, config, stop=stop, **kwargs)++ @override+ async def ainvoke(+ self,+ input: LanguageModelInput,+ config: RunnableConfig | None = None,+ *,+ stop: list[str] | None = None,+ **kwargs: Any,+ ) -> AIMessage:+ self.captured_configs.append(config)+ return await super().ainvoke(input, config, stop=stop, **kwargs)+++class TestLLMToolSelectorInternalCallMetadata:+ """Test that selection calls are tagged as internal for stream filtering."""++ def test_wrap_model_call_marks_internal_call(self) -> None:+ """`wrap_model_call` should tag its model call as internal to middleware."""+ tool_selection_model = ConfigCapturingSelectionModel(+ messages=cycle(+ [+ AIMessage(+ content="",+ tool_calls=[+ {+ "name": "ToolSelectionResponse",+ "id": "1",+ "args": {"tools": ["get_weather"]},+ }+ ],+ ),+ ]+ )+ )+ model = FakeModel(messages=iter([AIMessage(content="Done")]))+ tool_selector = LLMToolSelectorMiddleware(model=tool_selection_model)++ agent = create_agent(+ model=model,+ tools=[get_weather, search_web],+ middleware=[tool_selector],+ )+ agent.invoke({"messages": [HumanMessage("What's the weather?")]})++ assert len(tool_selection_model.captured_configs) == 1+ config = tool_selection_model.captured_configs[0]+ assert config is not None+ assert config["metadata"]["lc_source"] == "tool_selection"+ assert (+ config["metadata"][INTERNAL_CALL_METADATA_KEY]+ == internal_call_metadata()[INTERNAL_CALL_METADATA_KEY]+ )++ async def test_awrap_model_call_marks_internal_call(self) -> None:+ """`awrap_model_call` should tag its model call as internal to middleware."""+ tool_selection_model = ConfigCapturingSelectionModel(+ messages=cycle(+ [+ AIMessage(+ content="",+ tool_calls=[+ {+ "name": "ToolSelectionResponse",+ "id": "1",+ "args": {"tools": ["get_weather"]},+ }+ ],+ ),+ ]+ )+ )+ model = FakeModel(messages=iter([AIMessage(content="Done")]))+ tool_selector = LLMToolSelectorMiddleware(model=tool_selection_model)++ agent = create_agent(+ model=model,+ tools=[get_weather, search_web],+ middleware=[tool_selector],+ )+ await agent.ainvoke({"messages": [HumanMessage("What's the weather?")]})++ assert len(tool_selection_model.captured_configs) == 1+ config = tool_selection_model.captured_configs[0]+ assert config is not None+ assert config["metadata"]["lc_source"] == "tool_selection"+ assert (+ config["metadata"][INTERNAL_CALL_METADATA_KEY]+ == internal_call_metadata()[INTERNAL_CALL_METADATA_KEY]+ )