Skip to content

The agent engineering platform.

refactor(langchain): update doc strings (#39305)

Nishitha Mea52f5b409a3
diff --git a/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.py b/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.py
index bb8933e98f..cac55b98ed 100644
--- a/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.py
+++ b/libs/langchain_v1/langchain/agents/middleware/internal_call_transformer.py
@@ -1,13 +1,8 @@
"""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.
+Tag internal calls with `internal_call_metadata()` and declare
+`transformers = (InternalCallTransformer,)` on the middleware class to keep
+them out of `run.messages`. Both APIs are public for third-party middleware.
"""
from __future__ import annotations
@@ -22,25 +17,17 @@ 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.
+"""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.
+Kept separate from `lc_source` so filtering doesn't affect its existing
+semantics.
"""
_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.
+"""Process-local marker used to prevent callers from spoofing internal calls.
+
+A random token prevents user-supplied metadata from hiding real model calls
+from `run.messages`.
"""
@@ -56,33 +43,14 @@ def internal_call_metadata() -> dict[str, Any]:
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.
+ Used by middleware that makes internal model calls and runs before built-in
+ transformers.
+
+ For tagged events, streamed `message-start` events are marked as tool-role and
+ whole-`AIMessage` payloads are cleared so `MessagesTransformer` ignores them.
+ The mutated events are then dropped from the raw log.
+
+ Only events within this transformer's scope are modified.
"""
before_builtins: ClassVar[bool] = True
@@ -129,10 +97,9 @@ class InternalCallTransformer(StreamTransformer):
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.
+ # Only `message-start` needs mutation: marking it as `"tool"` makes
+ # `MessagesTransformer` ignore the rest of that run. All events are still
+ # dropped from the raw log below.
if isinstance(payload, dict) and payload.get("event") == "message-start":
payload["role"] = "tool"
elif isinstance(payload, BaseMessage):