Skip to content

The agent engineering platform.

feat(core,langchain,standard-tests): read `tool-call-delta` in stream consumers (#41246)

Richard Scarrott560a5f2f8abd
diff --git a/libs/core/langchain_core/language_models/chat_model_stream.py b/libs/core/langchain_core/language_models/chat_model_stream.py
index 612a6faf34..21f5374870 100644
--- a/libs/core/langchain_core/language_models/chat_model_stream.py
+++ b/libs/core/langchain_core/language_models/chat_model_stream.py
@@ -29,6 +29,7 @@ if TYPE_CHECKING:
from langchain_protocol.protocol import (
ContentBlockDeltaData,
ContentBlockFinishData,
+ ContentBlockStartData,
FinalizedContentBlock,
InvalidToolCall,
MessageFinishData,
@@ -591,6 +592,8 @@ class _ChatModelStreamBase:
self._text_per_block: dict[int, str] = {}
self._reasoning_per_block: dict[int, str] = {}
self._tool_call_chunks: dict[int, dict[str, Any]] = {}
+ # Calls whose args stopped extending previous deltas; they yield no more deltas.
+ self._quiet_tool_calls: set[int] = set()
self._tool_calls_acc: list[ToolCall] = []
self._invalid_tool_calls_acc: list[InvalidToolCall] = []
self._server_tool_call_chunks: dict[int, dict[str, Any]] = {}
@@ -672,6 +675,8 @@ class _ChatModelStreamBase:
event_type = event.get("event")
if event_type == "message-start":
self._push_message_start(cast("MessageStartData", event))
+ elif event_type == "content-block-start":
+ self._push_content_block_start(cast("ContentBlockStartData", event))
elif event_type == "content-block-delta":
self._push_content_block_delta(cast("ContentBlockDeltaData", event))
elif event_type == "content-block-finish":
@@ -680,7 +685,6 @@ class _ChatModelStreamBase:
self._finish(cast("MessageFinishData", event))
elif event_type == "error":
self.fail(RuntimeError(event.get("message", "Unknown error")))
- # content-block-start is informational — no accumulation needed
# -- Internal push API (called by dispatch) ----------------------------
@@ -695,6 +699,53 @@ class _ChatModelStreamBase:
if message_id:
self._message_id = message_id
+ def _push_content_block_start(self, data: ContentBlockStartData) -> None:
+ """Process a `content-block-start` event.
+
+ Seeds the chunk stores for tool-call blocks. `tool-call-delta`
+ events don't repeat the call's `id` / `name`, or whether it is a
+ client or server call, so the start is the only place to learn
+ them. Other blocks need nothing from their start.
+ """
+ block = _event_content_block(data)
+ idx = data.get("index")
+ if block is None or idx is None:
+ return
+ btype = block.get("type")
+ if btype == "tool_call_chunk":
+ _merge_block_delta_into_store(self._tool_call_chunks, idx, dict(block))
+ args = block.get("args")
+ if isinstance(args, str) and args:
+ self._push_tool_call_chunk(idx, args)
+ elif btype == "server_tool_call_chunk":
+ _merge_block_delta_into_store(
+ self._server_tool_call_chunks, idx, dict(block)
+ )
+
+ def _push_tool_call_chunk(
+ self, idx: int, args: str, *, provider_index: int | str | None = None
+ ) -> None:
+ """Push a `ToolCallChunk` delta for the client tool call at `idx`.
+
+ Deltas don't always repeat `id` / `name`, so each item takes them
+ from the call's store, letting consumers tell parallel calls apart.
+ `provider_index` is the delta's own provider `index`, for deltas
+ that carry one without it being kept in the store.
+ """
+ if idx in self._quiet_tool_calls:
+ return
+ chunk = self._tool_call_chunks[idx]
+ item: ToolCallChunk = {
+ "type": "tool_call_chunk",
+ "id": chunk.get("id"),
+ "name": chunk.get("name"),
+ "args": args,
+ }
+ index = chunk.get("index", provider_index)
+ if index is not None:
+ item["index"] = index
+ self._tool_calls_proj.push(item)
+
def _push_content_block_delta(self, data: ContentBlockDeltaData) -> None:
"""Process a `content-block-delta` event."""
delta = _event_delta(data)
@@ -731,16 +782,16 @@ class _ChatModelStreamBase:
idx = data.get("index")
if idx is None:
idx = tcc.get("index", len(self._tool_call_chunks)) # type: ignore[unreachable]
+ held = self._tool_call_chunks.get(idx, {}).get("args") or ""
_merge_block_delta_into_store(self._tool_call_chunks, idx, dict(tcc))
- chunk_block: ToolCallChunk = {
- "type": "tool_call_chunk",
- "id": tcc.get("id"),
- "name": tcc.get("name"),
- "args": tcc.get("args"),
- }
- if "index" in tcc:
- chunk_block["index"] = tcc["index"]
- self._tool_calls_proj.push(chunk_block)
+ # `block-delta` replaces `args` with a snapshot (older
+ # cores); `.tool_calls` yields only the part it adds.
+ args = tcc.get("args")
+ if isinstance(args, str):
+ if not args.startswith(held):
+ self._quiet_tool_calls.add(idx)
+ elif len(args) > len(held):
+ self._push_tool_call_chunk(idx, args[len(held) :])
elif btype == "server_tool_call_chunk":
stcc = cast("ServerToolCallChunk", fields)
idx = data.get("index")
@@ -751,6 +802,23 @@ class _ChatModelStreamBase:
idx,
dict(stcc),
)
+ elif dtype == "tool-call-delta":
+ # Appends to the call's args. The call's start says
+ # whether it is a client or server call; a delta whose start
+ # this stream never saw (say, trimmed from a replay window)
+ # is left to `content-block-finish`, which carries the call.
+ delta_args = delta.get("args")
+ if event_idx is None or not isinstance(delta_args, str) or not delta_args:
+ return
+ if event_idx in self._tool_call_chunks:
+ _merge_chunk_into_store(
+ self._tool_call_chunks, event_idx, {"args": delta_args}
+ )
+ self._push_tool_call_chunk(event_idx, delta_args)
+ elif event_idx in self._server_tool_call_chunks:
+ _merge_chunk_into_store(
+ self._server_tool_call_chunks, event_idx, {"args": delta_args}
+ )
elif dtype == "legacy-block-delta":
fields = delta.get("fields")
if not isinstance(fields, dict):
@@ -762,15 +830,11 @@ class _ChatModelStreamBase:
if idx is None:
idx = tcc.get("index", len(self._tool_call_chunks)) # type: ignore[unreachable]
_merge_chunk_into_store(self._tool_call_chunks, idx, dict(tcc))
- legacy_chunk_block: ToolCallChunk = {
- "type": "tool_call_chunk",
- "id": tcc.get("id"),
- "name": tcc.get("name"),
- "args": tcc.get("args"),
- }
- if "index" in tcc:
- legacy_chunk_block["index"] = tcc["index"]
- self._tool_calls_proj.push(legacy_chunk_block)
+ legacy_args = tcc.get("args")
+ if legacy_args:
+ self._push_tool_call_chunk(
+ idx, legacy_args, provider_index=tcc.get("index")
+ )
elif btype == "server_tool_call_chunk":
stcc = cast("ServerToolCallChunk", fields)
idx = data.get("index")
@@ -786,9 +850,13 @@ class _ChatModelStreamBase:
# content-block finish event; there is no dedicated projection.
return
else:
- # Transitional legacy path for old `content_block` deltas that
- # should not be reachable after `_event_delta` conversion, kept
- # here for custom in-tree test fixtures or third-party emitters.
+ # Unknown delta variants land here and are ignored, as the
+ # protocol requires; `content-block-finish` still carries the
+ # complete block. The one exception is an event that also
+ # carries a legacy `content_block`: a transitional path for
+ # old deltas that should not be reachable after `_event_delta`
+ # conversion, kept for custom test fixtures or third-party
+ # emitters.
block = data.get("content_block")
if not isinstance(block, dict):
return
@@ -800,15 +868,11 @@ class _ChatModelStreamBase:
if idx is None:
idx = tcc.get("index", len(self._tool_call_chunks)) # type: ignore[unreachable]
_merge_chunk_into_store(self._tool_call_chunks, idx, dict(tcc))
- fallback_chunk_block: ToolCallChunk = {
- "type": "tool_call_chunk",
- "id": tcc.get("id"),
- "name": tcc.get("name"),
- "args": tcc.get("args"),
- }
- if "index" in tcc:
- fallback_chunk_block["index"] = tcc["index"]
- self._tool_calls_proj.push(fallback_chunk_block)
+ fallback_args = tcc.get("args")
+ if fallback_args:
+ self._push_tool_call_chunk(
+ idx, fallback_args, provider_index=tcc.get("index")
+ )
def _resolve_block_text(self, idx: int | None, full_text: str) -> str:
"""Return authoritative text for a single text block at `idx`.
diff --git a/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py b/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py
index 534623bc9b..527c3f0722 100644
--- a/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py
+++ b/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py
@@ -953,3 +953,329 @@ class TestAsyncChatModelStream:
await stream.text
with pytest.raises(RuntimeError, match="async fail"):
await stream
+
+
+# ---------------------------------------------------------------------------
+# Tool-call args: `tool-call-delta` slices and `block-delta` snapshots
+# ---------------------------------------------------------------------------
+
+_ARGS_PARTS = ['{"path": ', '"a.py", ', '"content": ', '"hi"}']
+
+
+def _start(index: int, block: dict[str, Any]) -> dict[str, Any]:
+ return {"event": "content-block-start", "index": index, "content": block}
+
+
+def _tool_call_start(
+ index: int, *, id_: str | None = "c1", name: str | None = "write_file"
+) -> dict[str, Any]:
+ return _start(
+ index, {"type": "tool_call_chunk", "id": id_, "name": name, "args": ""}
+ )
+
+
+def _tool_call_delta(index: int, args: str) -> dict[str, Any]:
+ return {
+ "event": "content-block-delta",
+ "index": index,
+ "delta": {"type": "tool-call-delta", "args": args},
+ }
+
+
+def _tool_call_finish(
+ index: int, args: dict[str, Any], *, id_: str = "c1", name: str = "write_file"
+) -> dict[str, Any]:
+ return {
+ "event": "content-block-finish",
+ "index": index,
+ "content": {"type": "tool_call", "id": id_, "name": name, "args": args},
+ }
+
+
+def _dispatch_all(stream: ChatModelStream, events: list[dict[str, Any]]) -> None:
+ for event in events:
+ stream.dispatch(event)
+
+
+def _block_delta(index: int, **fields: Any) -> dict[str, Any]:
+ return {
+ "event": "content-block-delta",
+ "index": index,
+ "delta": {
+ "type": "block-delta",
+ "fields": {"type": "tool_call_chunk", **fields},
+ },
+ }
+
+
+def _slice_events() -> list[dict[str, Any]]:
+ """One tool call streamed as `tool-call-delta` slices (emitting cores)."""
+ return [
+ {"event": "message-start", "role": "ai"},
+ _tool_call_start(0),
+ *[_tool_call_delta(0, part) for part in _ARGS_PARTS],
+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),
+ {"event": "message-finish"},
+ ]
+
+
+def _snapshot_events() -> list[dict[str, Any]]:
+ """The same tool call streamed as `block-delta` snapshots (older cores)."""
+ snapshots = ["".join(_ARGS_PARTS[: i + 1]) for i in range(len(_ARGS_PARTS))]
+ return [
+ {"event": "message-start", "role": "ai"},
+ _tool_call_start(0),
+ *[
+ _block_delta(0, id="c1", name="write_file", args=snapshot)
+ for snapshot in snapshots
+ ],
+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),
+ {"event": "message-finish"},
+ ]
+
+
+_EXPECTED_DELTAS = [
+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": '{"path": '},
+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": '"a.py", '},
+ {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": '"content": ',
+ },
+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": '"hi"}'},
+]
+
+
+class TestToolCallArgs:
+ """`.tool_calls` yields deltas whatever form the args arrive in."""
+
+ def test_slice_stream_yields_deltas_carrying_id_and_name(self) -> None:
+ stream = ChatModelStream()
+ _dispatch_all(stream, _slice_events())
+
+ assert list(stream.tool_calls) == _EXPECTED_DELTAS
+
+ def test_snapshot_stream_yields_the_same_deltas(self) -> None:
+ stream = ChatModelStream()
+ _dispatch_all(stream, _snapshot_events())
+
+ assert list(stream.tool_calls) == _EXPECTED_DELTAS
+
+ def test_both_forms_assemble_the_same_tool_calls(self) -> None:
+ from_slices = ChatModelStream()
+ _dispatch_all(from_slices, _slice_events())
+ from_snapshots = ChatModelStream()
+ _dispatch_all(from_snapshots, _snapshot_events())
+
+ expected = [
+ {
+ "type": "tool_call",
+ "id": "c1",
+ "name": "write_file",
+ "args": {"path": "a.py", "content": "hi"},
+ }
+ ]
+ assert from_slices.tool_calls.get() == expected
+ assert from_snapshots.tool_calls.get() == expected
+ assert from_slices.output == from_snapshots.output
+
+ def test_call_whose_args_stop_extending_goes_quiet_until_finish(self) -> None:
+ stream = ChatModelStream()
+ _dispatch_all(
+ stream,
+ [
+ {"event": "message-start", "role": "ai"},
+ _tool_call_start(0),
+ _block_delta(0, args='{"path": '),
+ # Doesn't extend '{"path": ', so no delta can express it.
+ _block_delta(0, args="{"),
+ # Lines up again, but the call stays quiet.
+ _block_delta(0, args='{"path": "a.py", '),
+ _tool_call_delta(0, '"content": "hi"}'),
+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),
+ {"event": "message-finish"},
+ ],
+ )
+
+ assert list(stream.tool_calls) == [
+ {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": '{"path": ',
+ },
+ ]
+ assert stream.output.tool_calls == [
+ {
+ "type": "tool_call",
+ "id": "c1",
+ "name": "write_file",
+ "args": {"path": "a.py", "content": "hi"},
+ }
+ ]
+
+ def test_block_delta_without_args_yields_nothing_and_updates_id_and_name(
+ self,
+ ) -> None:
+ stream = ChatModelStream()
+ _dispatch_all(
+ stream,
+ [
+ {"event": "message-start", "role": "ai"},
+ _tool_call_start(0, id_=None, name=None),
+ _tool_call_delta(0, '{"path": '),
+ _block_delta(0, id="c1", name="write_file"),
+ _tool_call_delta(0, '"a.py"}'),
+ _tool_call_finish(0, {"path": "a.py"}),
+ {"event": "message-finish"},
+ ],
+ )
+
+ assert list(stream.tool_calls) == [
+ {"type": "tool_call_chunk", "id": None, "name": None, "args": '{"path": '},
+ {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": '"a.py"}',
+ },
+ ]
+
+ def test_unknown_delta_variant_is_ignored(self) -> None:
+ stream = ChatModelStream()
+ unknown = {
+ "event": "content-block-delta",
+ "index": 0,
+ "delta": {"type": "future-delta", "args": "ignored"},
+ }
+ events = _slice_events()
+ events.insert(3, unknown)
+ _dispatch_all(stream, events)
+
+ assert list(stream.tool_calls) == _EXPECTED_DELTAS
+ assert stream.output.tool_calls[0]["args"] == {"path": "a.py", "content": "hi"}
+
+ def test_deltas_carry_the_provider_index_from_the_start(self) -> None:
+ stream = ChatModelStream()
+ start = _start(
+ 0,
+ {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": "",
+ "index": 3,
+ },
+ )
+ _dispatch_all(stream, [start, _tool_call_delta(0, "{}")])
+
+ assert list(stream.tool_calls) == [
+ {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": "{}",
+ "index": 3,
+ }
+ ]
+
+ def test_tool_call_delta_without_a_seen_start_is_left_to_finish(self) -> None:
+ stream = ChatModelStream()
+ _dispatch_all(
+ stream,
+ [
+ {"event": "message-start", "role": "ai"},
+ # The start was trimmed from the replay window.
+ *[_tool_call_delta(0, part) for part in _ARGS_PARTS],
+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),
+ {"event": "message-finish"},
+ ],
+ )
+
+ assert list(stream.tool_calls) == []
+ assert stream.output.tool_calls[0]["args"] == {"path": "a.py", "content": "hi"}
+
+ def test_tool_call_deltas_assemble_a_call_with_no_finish(self) -> None:
+ stream = ChatModelStream()
+ events = [e for e in _slice_events() if e["event"] != "content-block-finish"]
+ _dispatch_all(stream, events)
+
+ assert stream.output.tool_calls == [
+ {
+ "type": "tool_call",
+ "id": "c1",
+ "name": "write_file",
+ "args": {"path": "a.py", "content": "hi"},
+ }
+ ]
+
+ def test_server_tool_call_deltas_append_without_yielding(self) -> None:
+ stream = ChatModelStream()
+ _dispatch_all(
+ stream,
+ [
+ {"event": "message-start", "role": "ai"},
+ _start(
+ 0,
+ {
+ "type": "server_tool_call_chunk",
+ "id": "s1",
+ "name": "web_search",
+ "args": "",
+ },
+ ),
+ _tool_call_delta(0, '{"query": '),
+ _tool_call_delta(0, '"weather"}'),
+ # No content-block-finish: the message-finish sweep
+ # parses what the deltas appended.
+ {"event": "message-finish"},
+ ],
+ )
+
+ assert list(stream.tool_calls) == []
+ content = cast("list[dict[str, Any]]", stream.output.content)
+ assert content[0]["type"] == "server_tool_call"
+ assert content[0]["id"] == "s1"
+ assert content[0]["args"] == {"query": "weather"}
+
+ def test_args_on_the_start_are_the_first_delta(self) -> None:
+ stream = ChatModelStream()
+ start = _start(
+ 0,
+ {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": _ARGS_PARTS[0],
+ },
+ )
+ _dispatch_all(
+ stream, [start, *[_tool_call_delta(0, part) for part in _ARGS_PARTS[1:]]]
+ )
+
+ assert list(stream.tool_calls) == _EXPECTED_DELTAS
+
+ def test_legacy_content_block_deltas_carry_id_and_name(self) -> None:
+ stream = ChatModelStream()
+ legacy_parts = [
+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": ""},
+ *[{"type": "tool_call_chunk", "args": part} for part in _ARGS_PARTS],
+ ]
+ _dispatch_all(
+ stream,
+ [
+ {"event": "content-block-delta", "index": 0, "content_block": part}
+ for part in legacy_parts
+ ],
+ )
+
+ assert list(stream.tool_calls) == _EXPECTED_DELTAS
+
+ @pytest.mark.asyncio
+ async def test_async_stream_yields_the_same_deltas(self) -> None:
+ stream = AsyncChatModelStream()
+ for event in _slice_events():
+ stream.dispatch(event)
+
+ assert [d async for d in stream.tool_calls] == _EXPECTED_DELTAS
diff --git a/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py b/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py
index 9fccf8b26b..ebebd1c197 100644
--- a/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py
+++ b/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py
@@ -1365,6 +1365,76 @@ class TestBedrockConverseToolCallArgs:
assert text_blocks[0]["text"] == "Hello Boston!"
+class _StreamingToolCallModel(BaseChatModel):
+ """Fake model that streams one tool call's args across several chunks."""
+
+ @property
+ def _llm_type(self) -> str:
+ return "streaming-tool-call-fake"
+
+ def _generate(
+ self,
+ messages: list[BaseMessage],
+ stop: list[str] | None = None,
+ run_manager: CallbackManagerForLLMRun | None = None,
+ **kwargs: Any,
+ ) -> ChatResult:
+ del messages, stop, run_manager, kwargs
+ raise NotImplementedError
+
+ def _stream(
+ self,
+ messages: list[BaseMessage],
+ stop: list[str] | None = None,
+ run_manager: CallbackManagerForLLMRun | None = None,
+ **kwargs: Any,
+ ) -> Iterator[ChatGenerationChunk]:
+ del messages, stop, run_manager, kwargs
+ # Opener carries the id and name; the args follow in slices.
+ parts = ["", '{"path": ', '"a.py", ', '"content": ', '"hi"}']
+ for i, part in enumerate(parts):
+ yield ChatGenerationChunk(
+ message=AIMessageChunk(
+ content="",
+ tool_call_chunks=[
+ {
+ "name": "write_file" if i == 0 else None,
+ "args": part,
+ "id": "call_1" if i == 0 else None,
+ "index": 0,
+ }
+ ],
+ )
+ )
+
+
+_TOOL_CALL_DELTAS = [
+ {
+ "type": "tool_call_chunk",
+ "id": "call_1",
+ "name": "write_file",
+ "args": args,
+ "index": 0,
+ }
+ for args in ['{"path": ', '"a.py", ', '"content": ', '"hi"}']
+]
+
+
+class TestToolCallsYieldDeltas:
+ """`.tool_calls` yields args deltas, not the snapshots the bridge emits."""
+
+ def test_stream_events_v3_tool_calls_yield_deltas(self) -> None:
+ stream = _StreamingToolCallModel().stream_events("hi", version="v3")
+
+ assert list(stream.tool_calls) == _TOOL_CALL_DELTAS
+
+ @pytest.mark.asyncio
+ async def test_astream_events_v3_tool_calls_yield_deltas(self) -> None:
+ stream = await _StreamingToolCallModel().astream_events("hi", version="v3")
+
+ assert [d async for d in stream.tool_calls] == _TOOL_CALL_DELTAS
+
+
class _CachedUsageModel(BaseChatModel):
"""Replays an Anthropic-shaped usage split across stream chunks.
diff --git a/libs/langchain_v1/langchain/agents/middleware/pii.py b/libs/langchain_v1/langchain/agents/middleware/pii.py
index e4c7612731..84c6cf6445 100644
--- a/libs/langchain_v1/langchain/agents/middleware/pii.py
+++ b/libs/langchain_v1/langchain/agents/middleware/pii.py
@@ -48,14 +48,15 @@ are typically well under 100) while bounding first-token latency.
class _PIIStreamTransformer(StreamTransformer):
- """Mutates `content-block-delta` text on `messages` events in flight.
+ """Mutates `content-block-delta` text and tool-call args in flight.
Runs before built-in stream transformers so the redacted text is what
every downstream consumer sees — both the main protocol event log and
the `run.messages` projection that `MessagesTransformer` snapshots into.
- Holds a sliding buffer of the most recent text per (run_id, content
- block index) so PII patterns that straddle delta boundaries are caught.
+ Holds a sliding buffer of the most recent text or tool-call args per
+ (run_id, content block index) so PII patterns that straddle delta
+ boundaries are caught.
Anything older than `lookback` characters is redacted with the resolved
rule's strategy and emitted as the new delta text; the trailing tail
stays in the buffer until a later delta extends it past the cap or the
@@ -75,7 +76,8 @@ class _PIIStreamTransformer(StreamTransformer):
super().__init__(scope)
self._rule = rule
self._lookback = lookback
- # Text/reasoning deltas keyed by `(run_id, content_block_index)`.
+ # Text/reasoning/tool-call-args deltas keyed by
+ # `(run_id, content_block_index)`.
self._buffers: dict[tuple[str, int], str] = {}
# Tool-output-delta buffers keyed by `tool_call_id`. Held in a
# separate dict so `_drop_run` on the messages channel can't
@@ -335,13 +337,19 @@ class _PIIStreamTransformer(StreamTransformer):
# `(run_id, index)` naturally disjoint from text-delta keys.
self._mutate_string_field_delta(delta, payload, run_id, "reasoning")
return
+ if delta_type == "tool-call-delta":
+ # Tool-call args slices append, like text, so they get the
+ # same lookback buffer. The withheld tail surfaces on
+ # `content-block-finish`, whose parsed args are redacted.
+ self._mutate_string_field_delta(delta, payload, run_id, "args")
+ return
if delta_type == "block-delta":
fields = delta.get("fields")
if isinstance(fields, dict) and fields.get("type") in {
"tool_call_chunk",
"server_tool_call_chunk",
}:
- self._mutate_tool_call_chunk_delta(fields)
+ self._mutate_tool_call_chunk_delta(fields, payload, run_id)
# Other delta types (`data-delta`, vendor block types) pass
# through. The pre-streaming middleware scrubbed `.content` text
# on state messages only; binary payloads and provider-specific
@@ -356,8 +364,9 @@ class _PIIStreamTransformer(StreamTransformer):
) -> None:
"""Apply the lookback-buffer redaction to a string field on a delta.
- Shared by `text-delta` (`field="text"`) and `reasoning-delta`
- (`field="reasoning"`). Buffer is keyed by `(run_id, block_index)`;
+ Shared by `text-delta` (`field="text"`), `reasoning-delta`
+ (`field="reasoning"`) and `tool-call-delta` (`field="args"`).
+ Buffer is keyed by `(run_id, block_index)`;
block indices are unique within a message so different block
types share the same key space without collision.
"""
@@ -388,14 +397,19 @@ class _PIIStreamTransformer(StreamTransformer):
self._buffers[key] = combined[emit_end:]
delta[field] = combined[:emit_end]
- def _mutate_tool_call_chunk_delta(self, fields: dict[str, Any]) -> None:
+ def _mutate_tool_call_chunk_delta(
+ self,
+ fields: dict[str, Any],
+ payload: dict[str, Any],
+ run_id: str,
+ ) -> None:
"""Redact cumulative tool-call args with lookback withholding.
- Each `tool_call_chunk` `block-delta` event carries the full
- accumulated args string (verified against `_compat_bridge.py`
- — `delta_source = current` for these block types — and against
- the consumer-side `_merge_block_delta_into_store`, which
- replaces wholesale rather than appends).
+ Cores that predate `tool-call-delta` stream tool-call args as
+ `block-delta` events whose `args` carry the full accumulated
+ string, which consumers apply as a replacement. Cores that emit
+ `tool-call-delta` slices go through `_mutate_string_field_delta`
+ instead.
Detection runs on the full cumulative args so any complete PII
anywhere in the string is redacted before emission. Lookback
@@ -415,6 +429,10 @@ class _PIIStreamTransformer(StreamTransformer):
emit prefix — same residual exposure as PII longer than
the lookback window on the text path. The `content-block-finish`
snapshot redaction is the backstop.
+
+ A replacement becomes the prefix that later `tool-call-delta`
+ slices for the block append to, so the withheld tail is kept as
+ that block's lookback buffer.
"""
args = fields.get("args")
if not isinstance(args, str) or not args:
@@ -429,6 +447,9 @@ class _PIIStreamTransformer(StreamTransformer):
emit_end = max(0, len(args) - self._lookback)
fields["args"] = args[:emit_end]
+ index = payload.get("index")
+ if isinstance(index, int):
+ self._buffers[run_id, index] = args[emit_end:]
def _finalize_block(self, payload: dict[str, Any], run_id: str) -> None:
index = payload.get("index")
@@ -597,9 +618,10 @@ class PIIMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, ResponseT])
* Streamed AI text deltas (`content-block-delta` of type
`text-delta`)
* Streamed tool-call arguments (`content-block-delta`
- with `tool_call_chunk` / `server_tool_call_chunk`
- fields, plus the finalized `tool_call` content block
- on `content-block-finish`)
+ of type `tool-call-delta`, or `block-delta` with
+ `tool_call_chunk` / `server_tool_call_chunk` fields,
+ plus the finalized `tool_call` content block on
+ `content-block-finish`)
* Tool execution events on the `tools` channel
(`tool-started.input`, `tool-output-delta`,
`tool-finished.output`, `tool-error.message`)
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py
index dee46efc40..6055dc4a14 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py
@@ -7,6 +7,7 @@
# langgraph adds a `__getattr__` fallback (strict mode's `warn_unused_ignores`).
import re
+from collections.abc import Callable
from typing import Any
import pytest
@@ -885,6 +886,53 @@ def _emitted_text(events: list[ProtocolEvent]) -> tuple[str, dict[int, str]]:
return "".join(parts), final_by_index
+def _make_tool_call_delta_event(
+ delta: dict[str, Any], *, index: int = 0, run_id: str = "r1"
+) -> ProtocolEvent:
+ """Build a `messages` protocol event for a tool-call content-block delta."""
+ return {
+ "type": "event",
+ "method": "messages",
+ "params": {
+ "namespace": [],
+ "timestamp": 0,
+ "data": (
+ {"event": "content-block-delta", "index": index, "delta": delta},
+ {"run_id": run_id},
+ ),
+ },
+ }
+
+
+def _tool_call_slice(args: str) -> dict[str, Any]:
+ return {"type": "tool-call-delta", "args": args}
+
+
+def _tool_call_snapshot(args: str | None = None, **fields: Any) -> dict[str, Any]:
+ if args is not None:
+ fields["args"] = args
+ return {"type": "block-delta", "fields": {"type": "tool_call_chunk", **fields}}
+
+
+def _emitted_tool_call_args(events: list[ProtocolEvent]) -> str:
+ """Rebuild streamed tool-call args the way a consumer would.
+
+ `tool-call-delta` appends its slice; a `block-delta` carrying `args`
+ replaces them.
+ """
+ args = ""
+ for event in events:
+ payload = event["params"]["data"][0]
+ if payload.get("event") != "content-block-delta":
+ continue
+ delta = payload["delta"]
+ if delta.get("type") == "tool-call-delta":
+ args += delta["args"]
+ elif delta.get("type") == "block-delta" and "args" in delta["fields"]:
+ args = delta["fields"]["args"]
+ return args
+
+
def _run_transformer(transformer: Any, events: list[ProtocolEvent]) -> list[ProtocolEvent]:
"""Feed events through the transformer (mutates in place) and return them."""
for event in events:
@@ -1750,6 +1798,93 @@ class TestPIIStreamTransformer:
with pytest.raises(PIIDetectionError):
transformer.process(event)
+ @pytest.mark.parametrize(
+ "make_delta",
+ [
+ pytest.param(_tool_call_slice, id="slices"),
+ pytest.param(_tool_call_snapshot, id="snapshots"),
+ ],
+ )
+ def test_tool_call_pii_straddling_deltas_is_redacted(
+ self, make_delta: Callable[[str], dict[str, Any]]
+ ) -> None:
+ """PII split across tool-call deltas never reaches the wire, in either form.
+
+ `tool-call-delta` slices go through the same lookback buffer as
+ text; `block-delta` snapshots (older cores) are redacted whole.
+ Either way the consumer rebuilds the same args: the redacted args
+ minus the held-back tail that `content-block-finish` carries.
+ """
+ rule = RedactionRule(pii_type="email").resolve()
+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)
+
+ slices = ['{"to": "alice', '@example.com", ', '"subject": "hi"}']
+ args = ["".join(slices[: i + 1]) for i in range(len(slices))]
+ parts = slices if make_delta is _tool_call_slice else args
+ events = [_make_tool_call_delta_event(make_delta(p)) for p in parts]
+ _run_transformer(transformer, events)
+
+ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'
+
+ def test_unknown_delta_variant_passes_through(self) -> None:
+ """An unknown delta variant is left as is and doesn't disturb the buffer."""
+ rule = RedactionRule(pii_type="email").resolve()
+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)
+
+ unknown = {"type": "future-delta", "args": "x"}
+ events = [
+ _make_tool_call_delta_event(_tool_call_slice('{"to": "alice')),
+ _make_tool_call_delta_event(dict(unknown)),
+ _make_tool_call_delta_event(_tool_call_slice('@example.com", ')),
+ _make_tool_call_delta_event(_tool_call_slice('"subject": "hi"}')),
+ ]
+ _run_transformer(transformer, events)
+
+ assert events[1]["params"]["data"][0]["delta"] == unknown
+ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'
+
+ def test_tool_call_slices_after_a_snapshot_extend_what_it_emitted(self) -> None:
+ """A snapshot's withheld tail is the prefix later slices append to."""
+ rule = RedactionRule(pii_type="email").resolve()
+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)
+
+ events = [
+ _make_tool_call_delta_event(_tool_call_snapshot('{"to": "alice')),
+ _make_tool_call_delta_event(_tool_call_slice('@example.com", ')),
+ _make_tool_call_delta_event(_tool_call_slice('"subject": "hi"}')),
+ ]
+ _run_transformer(transformer, events)
+
+ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'
+
+ def test_tool_call_delta_block_strategy_raises(self) -> None:
+ """`block` raises as soon as PII completes across tool-call slices."""
+ rule = RedactionRule(pii_type="email", strategy="block").resolve()
+ transformer = _PIIStreamTransformer(rule=rule)
+
+ transformer.process(_make_tool_call_delta_event(_tool_call_slice('{"to": "alice')))
+ with pytest.raises(PIIDetectionError):
+ transformer.process(_make_tool_call_delta_event(_tool_call_slice('@example.com"}')))
+
+ def test_args_free_block_delta_between_slices_passes_through(self) -> None:
+ """A late `id` / `name` update leaves the slices' buffer intact."""
+ rule = RedactionRule(pii_type="email").resolve()
+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)
+
+ late_id = _tool_call_snapshot(id="c1", name="send_email")
+ events = [
+ _make_tool_call_delta_event(_tool_call_slice('{"to": "alice')),
+ _make_tool_call_delta_event(late_id),
+ _make_tool_call_delta_event(_tool_call_slice('@example.com", ')),
+ _make_tool_call_delta_event(_tool_call_slice('"subject": "hi"}')),
+ ]
+ _run_transformer(transformer, events)
+
+ assert events[1]["params"]["data"][0]["delta"] == _tool_call_snapshot(
+ id="c1", name="send_email"
+ )
+ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'
+
def test_pii_fully_inside_one_delta_is_redacted_on_finalize(self) -> None:
"""A delta shorter than `lookback` is held until finalize redacts the snapshot."""
rule = RedactionRule(pii_type="email").resolve()
@@ -2219,7 +2354,9 @@ class TestPIIStreamingEndToEnd:
surfaces.append(str(c.get("args")))
elif p.get("event") == "content-block-delta":
d = p.get("delta") or {}
- if d.get("type") == "block-delta":
+ if d.get("type") == "tool-call-delta":
+ surfaces.append(str(d.get("args", "")))
+ elif d.get("type") == "block-delta":
f = d.get("fields") or {}
if f.get("type") in {
"tool_call_chunk",
diff --git a/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py b/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py
index 7cf50be031..e7d9ce8da9 100644
--- a/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py
+++ b/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py
@@ -13,7 +13,11 @@ conforms to the protocol lifecycle rules:
starting at 0.
- For deltaable block types (`text`, `reasoning`, `tool_call_chunk`,
`server_tool_call_chunk`), accumulated delta content matches the
- final payload delivered on `content-block-finish`.
+ final payload delivered on `content-block-finish`. Tool-call args may
+ arrive as `tool-call-delta` slices, which append, or as `block-delta`
+ snapshots, which replace; `tool-call-delta` only targets tool-call
+ chunk blocks.
+- Unknown delta variants are accepted and ignored.
The validator accepts any iterable of protocol event dicts. It raises
`AssertionError` on the first violation with a descriptive message.
@@ -37,6 +41,8 @@ _DELTAABLE_TYPES = frozenset(
}
)
+_TOOL_CALL_CHUNK_TYPES = frozenset({"tool_call_chunk", "server_tool_call_chunk"})
+
def assert_valid_event_stream(events: Iterable[Any]) -> None:
"""Assert that a stream of protocol events obeys the lifecycle contract.
@@ -125,7 +131,13 @@ def assert_valid_event_stream(events: Iterable[Any]) -> None:
delta = event.get("delta")
if delta is None and "content_block" in event:
delta = _legacy_block_to_delta(event["content_block"])
- _accumulate_delta(delta_accum[idx], delta)
+ if delta is not None and delta.get("type") == "tool-call-delta":
+ start_type = start_events[idx].get("type")
+ assert start_type in _TOOL_CALL_CHUNK_TYPES, (
+ f"tool-call-delta at idx={idx} targets a {start_type!r} "
+ f"block, not a tool-call chunk (event {i})"
+ )
+ _accumulate_delta(delta_accum[idx], delta, start_events[idx])
elif ev == "content-block-finish":
idx = event["index"]
assert idx in open_indices, (
@@ -170,7 +182,11 @@ def _legacy_block_to_delta(block: dict[str, Any]) -> dict[str, Any]:
return {"type": "block-delta", "fields": block}
-def _accumulate_delta(accum: dict[str, Any], delta: dict[str, Any] | None) -> None:
+def _accumulate_delta(
+ accum: dict[str, Any],
+ delta: dict[str, Any] | None,
+ start: dict[str, Any],
+) -> None:
"""Fold a delta block into the running accumulator for its index."""
if delta is None:
return
@@ -181,6 +197,11 @@ def _accumulate_delta(accum: dict[str, Any], delta: dict[str, Any] | None) -> No
accum["reasoning"] = accum.get("reasoning", "") + delta.get("reasoning", "")
elif dtype == "data-delta":
accum["data"] = accum.get("data", "") + delta.get("data", "")
+ elif dtype == "tool-call-delta":
+ # Appends a slice to the args so far: the last `block-delta`
+ # snapshot's (older cores) or, before any, the start's.
+ args = accum["args"] if "args" in accum else start.get("args")
+ accum["args"] = (args or "") + (delta.get("args") or "")
elif dtype == "block-delta":
fields = delta.get("fields")
if not isinstance(fields, dict):
diff --git a/libs/standard-tests/tests/unit_tests/test_stream_lifecycle.py b/libs/standard-tests/tests/unit_tests/test_stream_lifecycle.py
new file mode 100644
index 0000000000..97e12f5db9
--- /dev/null
+++ b/libs/standard-tests/tests/unit_tests/test_stream_lifecycle.py
@@ -0,0 +1,137 @@
+"""Tests for the content-block protocol stream validator."""
+
+from typing import Any
+
+import pytest
+
+from langchain_tests.utils.stream_lifecycle import assert_valid_event_stream
+
+_ARGS_PARTS = ['{"path": ', '"a.py", ', '"content": ', '"hi"}']
+_ARGS = {"path": "a.py", "content": "hi"}
+
+
+def _tool_call_events(
+ deltas: list[dict[str, Any]],
+ *,
+ finish_args: dict[str, Any] | None = None,
+ start_args: str = "",
+) -> list[dict[str, Any]]:
+ """One tool call at index 0, with the given deltas between start and finish."""
+ return [
+ {"event": "message-start", "role": "ai"},
+ {
+ "event": "content-block-start",
+ "index": 0,
+ "content": {
+ "type": "tool_call_chunk",
+ "id": "c1",
+ "name": "write_file",
+ "args": start_args,
+ },
+ },
+ *[
+ {"event": "content-block-delta", "index": 0, "delta": delta}
+ for delta in deltas
+ ],
+ {
+ "event": "content-block-finish",
+ "index": 0,
+ "content": {
+ "type": "tool_call",
+ "id": "c1",
+ "name": "write_file",
+ "args": _ARGS if finish_args is None else finish_args,
+ },
+ },
+ {"event": "message-finish"},
+ ]
+
+
+def _slices(parts: list[str]) -> list[dict[str, Any]]:
+ return [{"type": "tool-call-delta", "args": part} for part in parts]
+
+
+def _snapshots(parts: list[str]) -> list[dict[str, Any]]:
+ return [
+ {
+ "type": "block-delta",
+ "fields": {
+ "type": "tool_call_chunk",
+ "args": "".join(parts[: i + 1]),
+ },
+ }
+ for i in range(len(parts))
+ ]
+
+
+def test_tool_call_delta_args_must_match_finish() -> None:
+ events = _tool_call_events(
+ _slices(_ARGS_PARTS), finish_args={"path": "b.py", "content": "hi"}
+ )
+
+ with pytest.raises(AssertionError, match="tool_call args mismatch"):
+ assert_valid_event_stream(events)
+
+
+ "deltas",
+ [
+ pytest.param(_slices(_ARGS_PARTS), id="slices"),
+ pytest.param(_snapshots(_ARGS_PARTS), id="snapshots"),
+ pytest.param(
+ [*_snapshots(_ARGS_PARTS[:2]), *_slices(_ARGS_PARTS[2:])],
+ id="snapshot then slices",
+ ),
+ ],
+)
+def test_tool_call_args_in_either_form_are_valid(deltas: list[dict[str, Any]]) -> None:
+ assert_valid_event_stream(_tool_call_events(deltas))
+
+
+ "deltas",
+ [
+ pytest.param(_slices(_ARGS_PARTS[:-1]), id="slices"),
+ pytest.param(_snapshots(_ARGS_PARTS)[:-1], id="snapshots"),
+ ],
+)
+def test_incomplete_tool_call_args_are_invalid(deltas: list[dict[str, Any]]) -> None:
+ with pytest.raises(AssertionError, match="tool_call args mismatch"):
+ assert_valid_event_stream(_tool_call_events(deltas))
+
+
+def test_unknown_delta_variant_is_accepted() -> None:
+ deltas = [{"type": "future-delta", "args": "ignored"}, *_slices(_ARGS_PARTS)]
+
+ assert_valid_event_stream(_tool_call_events(deltas))
+
+
+def test_tool_call_delta_appends_to_args_on_the_start() -> None:
+ events = _tool_call_events(_slices(_ARGS_PARTS[1:]), start_args=_ARGS_PARTS[0])
+
+ assert_valid_event_stream(events)
+
+
+def test_tool_call_delta_on_a_text_block_is_invalid() -> None:
+ events = [
+ {"event": "message-start", "role": "ai"},
+ {
+ "event": "content-block-start",
+ "index": 0,
+ "content": {"type": "text", "text": ""},
+ },
+ {
+ "event": "content-block-delta",
+ "index": 0,
+ "delta": {"type": "tool-call-delta", "args": "{}"},
+ },
+ {
+ "event": "content-block-finish",
+ "index": 0,
+ "content": {"type": "text", "text": ""},
+ },
+ {"event": "message-finish"},
+ ]
+
+ with pytest.raises(AssertionError, match="tool-call-delta"):
+ assert_valid_event_stream(events)