Skip to content

The agent engineering platform.

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.py
index 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, Sequence
from langchain_core.runnables import Runnable, RunnableConfig
from 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.py
new file mode 100644
index 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 False
diff --git a/libs/langchain_v1/langchain/agents/middleware/summarization.py b/libs/langchain_v1/langchain/agents/middleware/summarization.py
index 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 Runtime
from 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, ResponseT
from langchain.chat_models import BaseChatModel, init_chat_model
@@ -230,6 +234,13 @@ class SummarizationMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, R
context 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, R
try:
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, R
try:
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.py
index 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, Generic
from langchain_core.language_models.chat_models import BaseChatModel
from 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, ContextT
from 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 tool
return 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 tool
return ToolMessage(
diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_selection.py b/libs/langchain_v1/langchain/agents/middleware/tool_selection.py
index 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, HumanMessage
from pydantic import Field, TypeAdapter
from 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 = 0
diff --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.py
new file mode 100644
index 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.py
index 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 GenericFakeChatModel
from langchain_core.messages import (
AIMessage,
AnyMessage,
@@ -28,7 +29,11 @@ from langgraph.runtime import Runtime
from pydantic import Field
from 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) -> None
assert config is not None
assert "metadata" in config
assert 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.py
index 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 BaseChatModel
from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_core.outputs import ChatGeneration, ChatResult
-from langchain_core.runnables import Runnable
+from langchain_core.runnables import Runnable, RunnableConfig
from langchain_core.tools import BaseTool, tool
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
from typing_extensions import override
from langchain.agents import create_agent
from 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) > 0
assert "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 texts
diff --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.py
index 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 pytest
from langchain_core.language_models import LanguageModelInput
from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
from langchain_core.messages import HumanMessage
-from langchain_core.runnables import Runnable
+from langchain_core.runnables import Runnable, RunnableConfig
from langchain_core.tools import BaseTool, tool
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
from typing_extensions import override
from 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_response
from langchain.messages import AIMessage
@@ -862,3 +866,111 @@ class TestMalformedSelectionResponse:
assert tool_names == ["search_web"]
assert len(received) == 1
assert 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]
+ )