The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(langchain): register stream transformers on middleware (#37591)
Nick Hollon1aa4496fb4ec
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.pyindex a245a4d4be..de69ef505c 100644--- a/libs/langchain_v1/langchain/agents/factory.py+++ b/libs/langchain_v1/langchain/agents/factory.py@@ -81,6 +81,7 @@ if TYPE_CHECKING:from langgraph.graph.state import CompiledStateGraphfrom langgraph.runtime import Runtimefrom langgraph.store.base import BaseStore+ from langgraph.stream._mux import TransformerFactoryfrom langgraph.types import Checkpointerfrom langchain.agents.middleware.types import ToolCallWrapper@@ -708,7 +709,7 @@ def create_agent(debug: bool = False,name: str | None = None,cache: BaseCache[Any] | None = None,- transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,+ transformers: Sequence[TransformerFactory] | None = None,) -> CompiledStateGraph[AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]]:@@ -806,9 +807,11 @@ def create_agent(cache: An optional `BaseCache` instance to enable caching of graph execution.transformers: Optional sequence of scope-aware `StreamTransformer`factories to register on the compiled graph in addition to- the agent defaults. Each factory is invoked per-scope- (`factory(scope)`) so subgraph mini-muxes get fresh- instances. Appended after the built-in `ToolCallTransformer`.+ the agent defaults. Each factory is invoked as `factory(scope)`+ so every invocation receives a fresh instance. The final order+ on the compiled graph is: `ToolCallTransformer`, then any+ factories declared by middleware via+ `AgentMiddleware.transformers`, then any factories supplied here.Returns:A compiled `StateGraph` that can be used for chat interactions.@@ -1662,6 +1665,8 @@ def create_agent(if name:config["metadata"]["lc_agent_name"] = name+ middleware_transformers = [t for m in middleware for t in getattr(m, "transformers", ())]+return graph.compile(checkpointer=checkpointer,store=store,@@ -1670,7 +1675,11 @@ def create_agent(debug=debug,name=name,cache=cache,- transformers=[ToolCallTransformer, *(transformers or ())],+ transformers=[+ ToolCallTransformer,+ *middleware_transformers,+ *(transformers or ()),+ ],).with_config(config)diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.pyindex c249d17465..1570ebd940 100644--- a/libs/langchain_v1/langchain/agents/middleware/types.py+++ b/libs/langchain_v1/langchain/agents/middleware/types.py@@ -40,6 +40,7 @@ if TYPE_CHECKING:from langchain_core.language_models.chat_models import BaseChatModelfrom langchain_core.tools import BaseToolfrom langgraph.runtime import Runtime+ from langgraph.stream._mux import TransformerFactoryfrom langgraph.types import Commandfrom langchain.agents.structured_output import ResponseFormat@@ -397,6 +398,16 @@ class AgentMiddleware(Generic[StateT, ContextT, ResponseT]):tools: Sequence[BaseTool]"""Additional tools registered by the middleware."""+ transformers: Sequence[TransformerFactory] = ()+ """Stream transformer factories registered by the middleware.++ Each entry is a scope-aware factory invoked as `factory(scope)` so every+ invocation receives a fresh instance. Factories are merged with the+ `transformers` argument of [`create_agent`][langchain.agents.create_agent]+ at graph compile time, after the `ToolCallTransformer` and before any+ user-supplied entries.+ """+@propertydef name(self) -> str:"""The name of the middleware instance.diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_transformers.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_transformers.pynew file mode 100644index 0000000000..c660b8bb13--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_transformers.py@@ -0,0 +1,143 @@+"""Tests for middleware-registered stream transformers."""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from langchain_core.messages import HumanMessage+from langgraph.prebuilt import ToolCallTransformer+from langgraph.stream import StreamChannel, StreamTransformer++from langchain.agents.factory import create_agent+from langchain.agents.middleware.types import AgentMiddleware+from tests.unit_tests.agents.model import FakeToolCallingModel++if TYPE_CHECKING:+ from langgraph.stream._types import ProtocolEvent+++class _MiddlewareMarker(StreamTransformer):+ """Marker transformer used to assert registration order."""++ required_stream_modes = ()++ def __init__(self, scope: tuple[str, ...] = ()) -> None:+ super().__init__(scope)+ self._log: StreamChannel[int] = StreamChannel()++ def init(self) -> dict[str, Any]:+ return {"middleware_marker": self._log}++ def process(self, event: ProtocolEvent) -> bool:+ del event+ return True+++class _UserMarker(StreamTransformer):+ """Second marker to verify user-supplied transformers append last."""++ required_stream_modes = ()++ def __init__(self, scope: tuple[str, ...] = ()) -> None:+ super().__init__(scope)+ self._log: StreamChannel[int] = StreamChannel()++ def init(self) -> dict[str, Any]:+ return {"user_marker": self._log}++ def process(self, event: ProtocolEvent) -> bool:+ del event+ return True+++def test_middleware_transformer_registered_on_compiled_graph() -> None:+ """A `transformers` factory declared on middleware is wired into the run mux."""++ class _Middleware(AgentMiddleware):+ transformers = (_MiddlewareMarker,)++ agent = create_agent(model=FakeToolCallingModel(), tools=[], middleware=[_Middleware()])++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")++ assert "middleware_marker" in run._mux.extensions # type: ignore[attr-defined]+ # Drain to close the run cleanly.+ list(run.tool_calls)+++def test_middleware_and_user_transformers_compose_in_order() -> None:+ """Order is: built-in `ToolCallTransformer` → middleware → user-supplied."""++ class _Middleware(AgentMiddleware):+ transformers = (_MiddlewareMarker,)++ agent = create_agent(+ model=FakeToolCallingModel(),+ tools=[],+ middleware=[_Middleware()],+ transformers=[_UserMarker],+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")++ transformers = run._mux._transformers # type: ignore[attr-defined]+ tool_call_idx = next(+ i for i, t in enumerate(transformers) if isinstance(t, ToolCallTransformer)+ )+ middleware_idx = next(i for i, t in enumerate(transformers) if isinstance(t, _MiddlewareMarker))+ user_idx = next(i for i, t in enumerate(transformers) if isinstance(t, _UserMarker))++ assert tool_call_idx < middleware_idx < user_idx, (+ "transformers must register as: built-in, then middleware, then user-supplied"+ )++ list(run.tool_calls)+++def test_transformers_from_multiple_middleware_preserve_middleware_order() -> None:+ """Transformers across middleware register in middleware-list order."""++ class _MarkerA(_MiddlewareMarker):+ def init(self) -> dict[str, Any]:+ return {"marker_a": self._log}++ class _MarkerB(_MiddlewareMarker):+ def init(self) -> dict[str, Any]:+ return {"marker_b": self._log}++ class _MwA(AgentMiddleware):+ transformers = (_MarkerA,)++ class _MwB(AgentMiddleware):+ transformers = (_MarkerB,)++ agent = create_agent(+ model=FakeToolCallingModel(),+ tools=[],+ middleware=[_MwA(), _MwB()],+ )++ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")++ transformers = run._mux._transformers # type: ignore[attr-defined]+ idx_a = next(i for i, t in enumerate(transformers) if isinstance(t, _MarkerA))+ idx_b = next(i for i, t in enumerate(transformers) if isinstance(t, _MarkerB))+ assert idx_a < idx_b++ list(run.tool_calls)+++def test_middleware_without_transformers_does_not_affect_registry() -> None:+ """Middleware that omits `transformers` leaves the default registry intact."""++ class _Middleware(AgentMiddleware):+ pass++ agent = create_agent(model=FakeToolCallingModel(), tools=[], middleware=[_Middleware()])+ run = agent.stream_events({"messages": [HumanMessage("hi")]}, version="v3")++ transformers = run._mux._transformers # type: ignore[attr-defined]+ assert any(isinstance(t, ToolCallTransformer) for t in transformers)+ assert not any(isinstance(t, _MiddlewareMarker) for t in transformers)++ list(run.tool_calls)