The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
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.pyindex 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 ProtocolEventINTERNAL_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):