Skip to content

The agent engineering platform.

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.py
index 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 traceable
from typing_extensions import NotRequired, Required, TypedDict, overload
from 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 = None
if 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 = None
if 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 = None
if 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 = None
if 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 -> model
diff --git a/libs/langchain_v1/langchain/agents/middleware/__init__.py b/libs/langchain_v1/langchain/agents/middleware/__init__.py
index 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_policy
from langchain.agents.middleware.context_editing import ClearToolUsesEdit, ContextEditingMiddleware
from langchain.agents.middleware.file_search import FilesystemFileSearchMiddleware
from 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.py
new file mode 100644
index 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.py
index 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 EphemeralValue
from langgraph.graph.message import add_messages
from langgraph.prebuilt.tool_node import ToolCallRequest, ToolCallWrapper
from langgraph.runtime import Runtime
-from langgraph.types import Command
+from langgraph.types import Command, TracePolicy, omit_payload
from langgraph.typing import ContextT
from 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.toml
index 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.py
new file mode 100644
index 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.lock
index 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]]