The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(langchain): expose `trace_policy` on `AgentMiddleware` (#38910)
ccurme1925966dc66c
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.pyindex afda461d9f..32818171ed 100644--- a/libs/langchain_v1/langchain/agents/factory.py+++ b/libs/langchain_v1/langchain/agents/factory.py@@ -31,6 +31,10 @@ from langsmith import traceablefrom typing_extensions import NotRequired, Required, TypedDict, overloadfrom langchain.agents._subagent_transformer import SubagentTransformer+from langchain.agents.middleware._trace_policy import (+ _node_trace_policy,+ _resolved_transform,+)from langchain.agents.middleware.types import (AgentMiddleware,AgentState,@@ -151,6 +155,22 @@ def _scrub_inputs(inputs: dict[str, Any]) -> dict[str, Any]:return filtered+def _wrap_trace_kwargs(middleware: AgentMiddleware[Any, Any]) -> dict[str, Any]:+ """`traceable` kwargs for a middleware's `wrap_*` hook spans.++ The `_scrub_inputs` baseline (strip the unserializable `handler`/`runtime`) always+ runs first; the effective `TracePolicy` (the middleware's own, else the process-wide+ default) composes on top. The effective policy is resolved at call time, so a+ `configure_trace_policy` call after `create_agent` still applies.+ """+ process_inputs = _resolved_transform(middleware.trace_policy, "process_inputs")+ process_outputs = _resolved_transform(middleware.trace_policy, "process_outputs")+ return {+ "process_inputs": lambda inputs: process_inputs(_scrub_inputs(inputs)),+ "process_outputs": process_outputs,+ }++FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT = [# If model profile data are not available, model names matching these patterns# are assumed to support provider-native structured output. These are regexes@@ -1026,9 +1046,7 @@ def create_agent(wrap_tool_call_wrapper = Noneif middleware_w_wrap_tool_call:wrappers = [- traceable(name=f"{m.name}.wrap_tool_call", process_inputs=_scrub_inputs)(- m.wrap_tool_call- )+ traceable(name=f"{m.name}.wrap_tool_call", **_wrap_trace_kwargs(m))(m.wrap_tool_call)for m in middleware_w_wrap_tool_call]wrap_tool_call_wrapper = _chain_tool_call_wrappers(wrappers)@@ -1047,9 +1065,7 @@ def create_agent(awrap_tool_call_wrapper = Noneif middleware_w_awrap_tool_call:async_wrappers = [- traceable(name=f"{m.name}.awrap_tool_call", process_inputs=_scrub_inputs)(- m.awrap_tool_call- )+ traceable(name=f"{m.name}.awrap_tool_call", **_wrap_trace_kwargs(m))(m.awrap_tool_call)for m in middleware_w_awrap_tool_call]awrap_tool_call_wrapper = _chain_async_tool_call_wrappers(async_wrappers)@@ -1135,9 +1151,7 @@ def create_agent(wrap_model_call_handler = Noneif middleware_w_wrap_model_call:sync_handlers = [- traceable(name=f"{m.name}.wrap_model_call", process_inputs=_scrub_inputs)(- m.wrap_model_call- )+ traceable(name=f"{m.name}.wrap_model_call", **_wrap_trace_kwargs(m))(m.wrap_model_call)for m in middleware_w_wrap_model_call]wrap_model_call_handler = _chain_model_call_handlers(sync_handlers)@@ -1146,7 +1160,7 @@ def create_agent(awrap_model_call_handler = Noneif middleware_w_awrap_model_call:async_handlers = [- traceable(name=f"{m.name}.awrap_model_call", process_inputs=_scrub_inputs)(+ traceable(name=f"{m.name}.awrap_model_call", **_wrap_trace_kwargs(m))(m.awrap_model_call)for m in middleware_w_awrap_model_call@@ -1548,7 +1562,10 @@ def create_agent()before_agent_node = RunnableCallable(sync_before_agent, async_before_agent, trace=False)graph.add_node(- f"{m.name}.before_agent", before_agent_node, input_schema=resolved_state_schema+ f"{m.name}.before_agent",+ before_agent_node,+ input_schema=resolved_state_schema,+ trace_policy=_node_trace_policy(m.trace_policy),)if (@@ -1569,7 +1586,10 @@ def create_agent()before_node = RunnableCallable(sync_before, async_before, trace=False)graph.add_node(- f"{m.name}.before_model", before_node, input_schema=resolved_state_schema+ f"{m.name}.before_model",+ before_node,+ input_schema=resolved_state_schema,+ trace_policy=_node_trace_policy(m.trace_policy),)if (@@ -1589,7 +1609,12 @@ def create_agent(else None)after_node = RunnableCallable(sync_after, async_after, trace=False)- graph.add_node(f"{m.name}.after_model", after_node, input_schema=resolved_state_schema)+ graph.add_node(+ f"{m.name}.after_model",+ after_node,+ input_schema=resolved_state_schema,+ trace_policy=_node_trace_policy(m.trace_policy),+ )if (m.__class__.after_agent is not AgentMiddleware.after_agent@@ -1609,7 +1634,10 @@ def create_agent()after_agent_node = RunnableCallable(sync_after_agent, async_after_agent, trace=False)graph.add_node(- f"{m.name}.after_agent", after_agent_node, input_schema=resolved_state_schema+ f"{m.name}.after_agent",+ after_agent_node,+ input_schema=resolved_state_schema,+ trace_policy=_node_trace_policy(m.trace_policy),)# Determine the entry node (runs once at start): before_agent -> before_model -> modeldiff --git a/libs/langchain_v1/langchain/agents/middleware/__init__.py b/libs/langchain_v1/langchain/agents/middleware/__init__.pyindex 3b642e5398..988992a501 100644--- a/libs/langchain_v1/langchain/agents/middleware/__init__.py+++ b/libs/langchain_v1/langchain/agents/middleware/__init__.py@@ -2,6 +2,7 @@from langgraph.runtime import Runtime+from langchain.agents.middleware._trace_policy import configure_trace_policyfrom langchain.agents.middleware.context_editing import ClearToolUsesEdit, ContextEditingMiddlewarefrom langchain.agents.middleware.file_search import FilesystemFileSearchMiddlewarefrom langchain.agents.middleware.human_in_the_loop import (@@ -37,12 +38,14 @@ from langchain.agents.middleware.types import (ModelResponse,OutputAgentState,ToolCallRequest,+ TracePolicy,after_agent,after_model,before_agent,before_model,dynamic_prompt,hook_config,+ omit_payload,wrap_model_call,wrap_tool_call,)@@ -82,13 +85,16 @@ __all__ = ["ToolCallRequest","ToolErrorMiddleware","ToolRetryMiddleware",+ "TracePolicy","TriggerClause","after_agent","after_model","before_agent","before_model",+ "configure_trace_policy","dynamic_prompt","hook_config",+ "omit_payload","wrap_model_call","wrap_tool_call",]diff --git a/libs/langchain_v1/langchain/agents/middleware/_trace_policy.py b/libs/langchain_v1/langchain/agents/middleware/_trace_policy.pynew file mode 100644index 0000000000..f07d79c285--- /dev/null+++ b/libs/langchain_v1/langchain/agents/middleware/_trace_policy.py@@ -0,0 +1,61 @@+"""Process-global default `TracePolicy` for agent middleware.++`TracePolicy` (from langgraph) shapes what a middleware hook span records. This module+adds a process-wide default that individual middleware override via their own+`trace_policy` attribute. Set it once at startup with `configure_trace_policy`; the+default is read at span-creation time, so it applies to agents built before or after+the call.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any, Literal++from langgraph.types import TracePolicy++if TYPE_CHECKING:+ from collections.abc import Callable++_DEFAULT_TRACE_POLICY: TracePolicy | None = None+++def configure_trace_policy(policy: TracePolicy | None) -> None:+ """Set the process-wide default `TracePolicy` for agent middleware hook spans.++ Call once at startup. A middleware's own `trace_policy` overrides this wholesale+ (no field-level merge). Pass `None` to clear the default.+ """+ global _DEFAULT_TRACE_POLICY # noqa: PLW0603 - process-wide default, set once at startup+ _DEFAULT_TRACE_POLICY = policy+++def _resolve(mw_policy: TracePolicy | None) -> TracePolicy | None:+ """The effective policy: the middleware's own if set, else the global default."""+ return mw_policy if mw_policy is not None else _DEFAULT_TRACE_POLICY+++def _resolved_transform(+ mw_policy: TracePolicy | None,+ field: Literal["process_inputs", "process_outputs"],+) -> Callable[[Any], Any]:+ """A trace processor that resolves the effective policy at call time.++ Reading the global at call time (not build time) means `configure_trace_policy` can+ run after `create_agent` and still apply. Passes the value through unchanged when no+ effective policy defines `field`.+ """++ def process(value: Any) -> Any:+ effective = _resolve(mw_policy)+ fn = getattr(effective, field) if effective is not None else None+ return fn(value) if fn is not None else value++ return process+++def _node_trace_policy(mw_policy: TracePolicy | None) -> TracePolicy:+ """Build the resolver-backed `TracePolicy` for a middleware's node hook."""+ return TracePolicy(+ process_inputs=_resolved_transform(mw_policy, "process_inputs"),+ process_outputs=_resolved_transform(mw_policy, "process_outputs"),+ )diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.pyindex 0fa145bfdf..b7d5b8050a 100644--- a/libs/langchain_v1/langchain/agents/middleware/types.py+++ b/libs/langchain_v1/langchain/agents/middleware/types.py@@ -28,7 +28,7 @@ from langgraph.channels.ephemeral_value import EphemeralValuefrom langgraph.graph.message import add_messagesfrom langgraph.prebuilt.tool_node import ToolCallRequest, ToolCallWrapperfrom langgraph.runtime import Runtime-from langgraph.types import Command+from langgraph.types import Command, TracePolicy, omit_payloadfrom langgraph.typing import ContextTfrom typing_extensions import NotRequired, Required, TypedDict, TypeVar, Unpack@@ -54,12 +54,14 @@ __all__ = ["StateT_co","ToolCallRequest","ToolCallWrapper",+ "TracePolicy","after_agent","after_model","before_agent","before_model","dynamic_prompt","hook_config",+ "omit_payload","wrap_tool_call",]@@ -398,6 +400,16 @@ class AgentMiddleware(Generic[StateT, ContextT, ResponseT]):tools: Sequence[BaseTool]"""Additional tools registered by the middleware."""+ trace_policy: TracePolicy | None = None+ """Optional trace policy for this middleware's hook spans (`wrap_model_call`/+ `wrap_tool_call` and the `before_*`/`after_*` node hooks).++ By default (`None`), hook spans are traced normally. Set a `TracePolicy` to shape+ what they record -- e.g. `TracePolicy(process_inputs=omit_payload)` to drop the+ conversation `messages`/`state` payload while keeping the span and its timing.+ Messages are still captured on the inner model-call span.+ """+transformers: Sequence[TransformerFactory] = ()"""Stream transformer factories registered by the middleware.diff --git a/libs/langchain_v1/pyproject.toml b/libs/langchain_v1/pyproject.tomlindex 54f36c91f8..0f9c472f97 100644--- a/libs/langchain_v1/pyproject.toml+++ b/libs/langchain_v1/pyproject.toml@@ -25,7 +25,7 @@ version = "1.3.14"requires-python = ">=3.10.0,<4.0.0"dependencies = ["langchain-core>=1.5.3,<2.0.0",- "langgraph>=1.2.5,<1.3.0",+ "langgraph>=1.2.11,<1.3.0","pydantic>=2.7.4,<3.0.0",]diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_tracing.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_tracing.pynew file mode 100644index 0000000000..7e5a084b8e--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_tracing.py@@ -0,0 +1,159 @@+"""End-to-end tests for `AgentMiddleware.trace_policy` and the global default."""++from collections.abc import Iterator+from typing import Any++import pytest+from langchain_core.messages import HumanMessage+from langchain_core.tracers import BaseTracer, Run+from langgraph.runtime import Runtime+from typing_extensions import override++from langchain.agents.factory import _wrap_trace_kwargs, create_agent+from langchain.agents.middleware import (+ AgentMiddleware,+ TracePolicy,+ configure_trace_policy,+ omit_payload,+)+from langchain.agents.middleware.types import AgentState+from tests.unit_tests.agents.model import FakeToolCallingModel++[email protected](autouse=True)+def _reset_global_trace_policy() -> Iterator[None]:+ """Keep the process-global default from leaking across tests."""+ configure_trace_policy(None)+ yield+ configure_trace_policy(None)+++class _CaptureInputs(BaseTracer):+ """Tracer that records the inputs each run reports, keyed by run name.++ A real tracer (not a plain callback) so `TracePolicy` processors, which run only+ when a tracer is attached, actually fire.+ """++ def __init__(self) -> None:+ super().__init__()+ self.inputs_by_name: dict[str, Any] = {}++ def _persist_run(self, run: Run) -> None:+ pass++ def _on_chain_start(self, run: Run) -> None:+ self.inputs_by_name.setdefault(run.name, run.inputs)+++def _recorded_before_model_inputs(middleware: AgentMiddleware) -> Any:+ """Run the agent and return what the middleware's before_model node recorded."""+ agent = create_agent(model=FakeToolCallingModel(), middleware=[middleware])+ capture = _CaptureInputs()+ agent.invoke({"messages": [HumanMessage("hi")]}, {"callbacks": [capture]})+ return capture.inputs_by_name[f"{middleware.name}.before_model"]+++class _NoopBeforeModel(AgentMiddleware):+ """Middleware with a before_model hook and no `trace_policy`."""++ @override+ def before_model(self, state: AgentState[Any], runtime: Runtime) -> None:+ return None+++def test_tracing_records_hook_inputs_by_default() -> None:+ # no `trace_policy`, no global -> hooks trace normally; real state is recorded+ recorded = _recorded_before_model_inputs(_NoopBeforeModel())+ assert "messages" in recorded+ assert [m.content for m in recorded["messages"]] == ["hi"]+++def test_tracing_omits_hook_inputs_with_omit_payload() -> None:+ class Scrubbed(AgentMiddleware):+ trace_policy = TracePolicy(process_inputs=omit_payload)++ @override+ def before_model(self, state: AgentState[Any], runtime: Runtime) -> None:+ return None++ # opt in via omit_payload -> the before_model node records an empty payload+ assert _recorded_before_model_inputs(Scrubbed()) == {}+++def test_global_default_applies_when_middleware_unset() -> None:+ configure_trace_policy(TracePolicy(process_inputs=omit_payload))++ # middleware leaves trace_policy=None -> inherits the global default+ assert _recorded_before_model_inputs(_NoopBeforeModel()) == {}+++def test_middleware_overrides_global_no_merge() -> None:+ configure_trace_policy(TracePolicy(process_inputs=omit_payload))++ class Override(AgentMiddleware):+ # sets only process_outputs; per override-not-merge this replaces the global+ # wholesale, so the global's input scrub does NOT apply -> inputs recorded raw+ trace_policy = TracePolicy(process_outputs=omit_payload)++ @override+ def before_model(self, state: AgentState[Any], runtime: Runtime) -> None:+ return None++ recorded = _recorded_before_model_inputs(Override())+ assert "messages" in recorded+++def test_configure_after_create_agent_applies() -> None:+ mw = _NoopBeforeModel()+ agent = create_agent(model=FakeToolCallingModel(), middleware=[mw])+ # configure AFTER the graph is built; the resolver reads the global at trace time+ configure_trace_policy(TracePolicy(process_inputs=omit_payload))+ capture = _CaptureInputs()+ agent.invoke({"messages": [HumanMessage("hi")]}, {"callbacks": [capture]})+ assert capture.inputs_by_name[f"{mw.name}.before_model"] == {}+++def test_configure_none_clears_global() -> None:+ configure_trace_policy(TracePolicy(process_inputs=omit_payload))+ configure_trace_policy(None)++ recorded = _recorded_before_model_inputs(_NoopBeforeModel())+ assert "messages" in recorded+++def test_wrap_trace_kwargs_composes_scrub_baseline() -> None:+ seen: dict[str, Any] = {}++ def process_inputs(inp: Any) -> Any:+ seen["inputs"] = inp+ return inp++ class MW(AgentMiddleware):+ trace_policy = TracePolicy(process_inputs=process_inputs)++ process = _wrap_trace_kwargs(MW())["process_inputs"]+ result = process({"request": {"x": 1}, "handler": lambda: None})+ # the baseline (`_scrub_inputs`) strips `handler` before the policy callable runs+ assert "handler" not in seen["inputs"]+ assert seen["inputs"] == {"request": {"x": 1}}+ assert result == {"request": {"x": 1}}+++def test_wrap_trace_kwargs_omit_drops_everything() -> None:+ class MW(AgentMiddleware):+ trace_policy = TracePolicy(process_inputs=omit_payload)++ process = _wrap_trace_kwargs(MW())["process_inputs"]+ assert process({"request": {"x": 1}, "handler": lambda: None}) == {}+++def test_wrap_trace_kwargs_inherits_global() -> None:+ configure_trace_policy(TracePolicy(process_inputs=omit_payload))++ class MW(AgentMiddleware):+ pass++ # no middleware policy -> wrap hook inherits the global, still after the baseline+ process = _wrap_trace_kwargs(MW())["process_inputs"]+ assert process({"request": {"x": 1}, "handler": lambda: None}) == {}diff --git a/libs/langchain_v1/uv.lock b/libs/langchain_v1/uv.lockindex 4713c979c4..bac73de1ff 100644--- a/libs/langchain_v1/uv.lock+++ b/libs/langchain_v1/uv.lock@@ -2084,7 +2084,7 @@ requires-dist = [{ name = "langchain-perplexity", marker = "extra == 'perplexity'" },{ name = "langchain-together", marker = "extra == 'together'" },{ name = "langchain-xai", marker = "extra == 'xai'" },- { name = "langgraph", specifier = ">=1.2.5,<1.3.0" },+ { name = "langgraph", specifier = ">=1.2.11,<1.3.0" },{ name = "pydantic", specifier = ">=2.7.4,<3.0.0" },]provides-extras = ["community", "anthropic", "openai", "azure-ai", "google-vertexai", "google-genai", "fireworks", "ollama", "together", "mistralai", "huggingface", "groq", "aws", "baseten", "deepseek", "xai", "perplexity", "meta"]@@ -2682,15 +2682,15 @@ wheels = [[[package]]name = "langgraph-checkpoint"-version = "4.1.1"+version = "4.2.0"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "langchain-core" },{ name = "ormsgpack" },]-sdist = { url = "https://files.pythonhosted.org/packages/83/47/886af6f886f0bff2273164a45f008694e48a96ff3cd25ff0228f2aa9480e/langgraph_checkpoint-4.1.1.tar.gz", hash = "sha256:6c2bdb530c91f91d7d9c1bd100925d0fc4f498d418c17f3587d1526279482a25", size = 184020, upload-time = "2026-05-22T16:57:38.503Z" }+sdist = { url = "https://files.pythonhosted.org/packages/dc/e1/089c4c9e0a2fec7f883f82ae8e6a727138d50074cfeb6644bc2d13b1019b/langgraph_checkpoint-4.2.0.tar.gz", hash = "sha256:51a593b6bee684b0818e5d6e58e28ab340c6db7794575056ce7bd1b746a84ed7", size = 180239, upload-time = "2026-08-07T20:05:03.756Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/bd/b4/71425e3e38be92611300b9cc5e46a5bf98ab23f5ea8a75b73d02a2f1413c/langgraph_checkpoint-4.1.1-py3-none-any.whl", hash = "sha256:25d29144b082827218e7bc3f1e9b0566a4bb007895cd6cc26f66a8428739f56e", size = 56212, upload-time = "2026-05-22T16:57:37.203Z" },+ { url = "https://files.pythonhosted.org/packages/05/71/3b475f09bd57d3a5649792c66353312b4432afd843f301739dfcebd157f0/langgraph_checkpoint-4.2.0-py3-none-any.whl", hash = "sha256:0547fd228935a0b758865de3a3d6d7a2537c308895d0f9ab092ce9151b5da942", size = 56833, upload-time = "2026-08-07T20:05:02.655Z" },][[package]]