The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(core): emit `tool-call-delta` for streamed tool-call args (#41257)
Richard Scarrottb84fa61edd48
diff --git a/libs/core/langchain_core/language_models/_compat_bridge.py b/libs/core/langchain_core/language_models/_compat_bridge.pyindex 11a6fcbe6e..11863a29df 100644--- a/libs/core/langchain_core/language_models/_compat_bridge.py+++ b/libs/core/langchain_core/language_models/_compat_bridge.py@@ -61,12 +61,11 @@ if TYPE_CHECKING:from collections.abc import AsyncIterator, Iteratorfrom langchain_protocol.protocol import (- BlockDelta,- BlockDeltaFields,ContentBlockDelta,DataDelta,ReasoningDelta,TextDelta,+ ToolCallDelta,)from langchain_core.messages.ai import UsageMetadata@@ -110,38 +109,6 @@ def _to_finalized_block(block: CompatBlock) -> FinalizedContentBlock:return cast("FinalizedContentBlock", block)-def _to_block_delta_fields(block: CompatBlock) -> BlockDeltaFields:- """Narrow an internal working dict to protocol block-delta fields."""- return cast("BlockDeltaFields", block)---def _to_content_delta(block: CompatBlock) -> ContentBlockDelta:- """Convert a content-block slice/snapshot to an explicit protocol delta."""- btype = block.get("type")- if btype == "text":- return cast("TextDelta", {"type": "text-delta", "text": block.get("text", "")})- if btype == "reasoning":- return cast(- "ReasoningDelta",- {- "type": "reasoning-delta",- "reasoning": block.get("reasoning", ""),- },- )- if "data" in block:- delta = cast("DataDelta", {"type": "data-delta", "data": block.get("data", "")})- if block.get("encoding") == "base64":- delta["encoding"] = "base64"- return delta- return cast(- "BlockDelta",- {- "type": "block-delta",- "fields": _to_block_delta_fields(block),- },- )--# ---------------------------------------------------------------------------# Block iteration# ---------------------------------------------------------------------------@@ -230,13 +197,17 @@ def _iter_protocol_blocks(msg: BaseMessage) -> list[tuple[Any, CompatBlock]]:# of being serialized twice on the wire._HEAVY_FIELDS = frozenset({"args", "data", "output", "transcript", "value"})+_TOOL_CALL_CHUNK_TYPES = frozenset({"tool_call_chunk", "server_tool_call_chunk"})+def _start_skeleton(block: CompatBlock) -> ContentBlock:"""Empty-content placeholder for the `content-block-start` event.Deltaable block types (text, reasoning, the `_chunk` tool variants)get an empty payload so the lifecycle's "start" signal is distinct- from the first incremental delta. Self-contained types (image,+ from the first incremental delta. The `_chunk` tool variants also+ carry the call's `id`, `name` and provider `index`, because+ `tool-call-delta` carries only args. Self-contained types (image,audio, video, file, non_standard, finalized tool calls) drop theirheavy payload fields; those are carried by `content-block-finish`.Correlation fields (id, name, toolCallId) and small metadata@@ -256,12 +227,15 @@ def _start_skeleton(block: CompatBlock) -> ContentBlock:r_skel["reasoning"] = ""return _to_protocol_block(r_skel)if btype == "tool_call_chunk":- return ToolCallChunk(+ skel = ToolCallChunk(type="tool_call_chunk",id=block.get("id"),name=block.get("name"),args="",)+ if block.get("index") is not None:+ skel["index"] = block["index"]+ return skelif btype == "server_tool_call_chunk":s_skel = ServerToolCallChunk(type="server_tool_call_chunk",@@ -271,6 +245,8 @@ def _start_skeleton(block: CompatBlock) -> ContentBlock:s_skel["id"] = block["id"]if block.get("name") is not None:s_skel["name"] = block["name"]+ if block.get("index") is not None:+ s_skel["index"] = block["index"]return s_skelstripped: CompatBlock = {k: v for k, v in block.items() if k not in _HEAVY_FIELDS}@@ -283,8 +259,8 @@ def _start_skeleton(block: CompatBlock) -> ContentBlock:return _to_protocol_block(stripped)-def _should_emit_delta(block: CompatBlock) -> bool:- """Whether a per-chunk block carries content worth a delta event.+def _to_content_delta(block: CompatBlock) -> ContentBlockDelta | None:+ """Convert a content-block slice to a protocol delta, or `None` if it has none.Deltaable types emit only when they have fresh content. Self-contained/ already-finalized types skip the delta entirely — the `finish`@@ -292,16 +268,29 @@ def _should_emit_delta(block: CompatBlock) -> bool:"""btype = block.get("type")if btype == "text":- return bool(block.get("text"))+ if not block.get("text"):+ return None+ return cast("TextDelta", {"type": "text-delta", "text": block["text"]})if btype == "reasoning":- return bool(block.get("reasoning"))- if btype in {"tool_call_chunk", "server_tool_call_chunk"}:- return bool(- block.get("args") or block.get("id") or block.get("name"),+ if not block.get("reasoning"):+ return None+ return cast(+ "ReasoningDelta",+ {"type": "reasoning-delta", "reasoning": block["reasoning"]},)- if "data" in block:- return bool(block.get("data"))- return False+ if btype in _TOOL_CALL_CHUNK_TYPES:+ # Only the args: the call's `id`, `name` and `index` went on its+ # start. `extras`, and an `id` or `name` arriving after the+ # start, reach consumers on `content-block-finish`.+ if not block.get("args"):+ return None+ return cast("ToolCallDelta", {"type": "tool-call-delta", "args": block["args"]})+ if block.get("data"):+ delta = cast("DataDelta", {"type": "data-delta", "data": block["data"]})+ if block.get("encoding") == "base64":+ delta["encoding"] = "base64"+ return delta+ return Nonedef _accumulate(state: CompatBlock | None, delta: CompatBlock) -> CompatBlock:@@ -340,7 +329,7 @@ def _accumulate(state: CompatBlock | None, delta: CompatBlock) -> CompatBlock:state["extras"] = {**(state.get("extras") or {}), **value}else:state[key] = value- elif btype in {"tool_call_chunk", "server_tool_call_chunk"} and dtype == btype:+ elif btype in _TOOL_CALL_CHUNK_TYPES and dtype == btype:state["args"] = (state.get("args", "") or "") + (delta.get("args") or "")if delta.get("id") is not None:state["id"] = delta["id"]@@ -438,7 +427,7 @@ def _finalize_block(block: CompatBlock) -> FinalizedContentBlock:their terminal shape."""btype = block.get("type")- if btype in {"tool_call_chunk", "server_tool_call_chunk"}:+ if btype in _TOOL_CALL_CHUNK_TYPES:# Carry provider-specific fields from the accumulated chunk onto# the finalized block. Drop the chunk-only keys we rewrite# explicitly. `index` is stripped on client-side@@ -670,17 +659,12 @@ def chunks_to_events(else:wire_idx, existing = blocks[key]blocks[key] = (wire_idx, _accumulate(existing, block))- if _should_emit_delta(block):- wire_idx, current = blocks[key]- is_block_delta = block.get("type") in {- "tool_call_chunk",- "server_tool_call_chunk",- }- delta_source = current if is_block_delta else block+ delta = _to_content_delta(block)+ if delta is not None:yield ContentBlockDeltaData(event="content-block-delta",index=wire_idx,- delta=_to_content_delta(delta_source or block),+ delta=delta,)if msg.usage_metadata:@@ -750,17 +734,12 @@ async def achunks_to_events(else:wire_idx, existing = blocks[key]blocks[key] = (wire_idx, _accumulate(existing, block))- if _should_emit_delta(block):- wire_idx, current = blocks[key]- is_block_delta = block.get("type") in {- "tool_call_chunk",- "server_tool_call_chunk",- }- delta_source = current if is_block_delta else block+ delta = _to_content_delta(block)+ if delta is not None:yield ContentBlockDeltaData(event="content-block-delta",index=wire_idx,- delta=_to_content_delta(delta_source or block),+ delta=delta,)if msg.usage_metadata:@@ -792,9 +771,10 @@ def message_to_events(downstream see a uniform event shape regardless of source.Text and reasoning blocks emit a single `content-block-delta` with- the full accumulated content. Already-finalized blocks (tool_call,- server_tool_call, image, etc.) skip the delta and rely on the- `content-block-finish` event alone.+ the full accumulated content, and tool-call chunk blocks a single+ `tool-call-delta` with their full args. Already-finalized blocks+ (tool_call, server_tool_call, image, etc.) skip the delta and rely+ on the `content-block-finish` event alone.Args:msg: The finalized message — typically an `AIMessage`.@@ -812,11 +792,12 @@ def message_to_events(index=wire_idx,content=_start_skeleton(block),)- if _should_emit_delta(block):+ delta = _to_content_delta(block)+ if delta is not None:yield ContentBlockDeltaData(event="content-block-delta",index=wire_idx,- delta=_to_content_delta(block),+ delta=delta,)yield ContentBlockFinishData(event="content-block-finish",diff --git a/libs/core/pyproject.toml b/libs/core/pyproject.tomlindex 755b88466f..55bea5ba70 100644--- a/libs/core/pyproject.toml+++ b/libs/core/pyproject.toml@@ -33,7 +33,7 @@ dependencies = ["packaging>=23.2.0","pydantic>=2.7.4,<3.0.0","uuid-utils>=0.12.0,<1.0",- "langchain-protocol>=0.0.17",+ "langchain-protocol>=0.0.20",][project.urls]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.pyindex ebebd1c197..be83537e63 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,9 @@ class TestBedrockConverseToolCallArgs:assert text_blocks[0]["text"] == "Hello Boston!"+_ARGS_SLICES = ['{"path": ', '"a.py", ', '"content": ', '"hi"}']++class _StreamingToolCallModel(BaseChatModel):"""Fake model that streams one tool call's args across several chunks."""@@ -1391,8 +1394,7 @@ class _StreamingToolCallModel(BaseChatModel):) -> 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):+ for i, part in enumerate(["", *_ARGS_SLICES]):yield ChatGenerationChunk(message=AIMessageChunk(content="",@@ -1416,12 +1418,12 @@ _TOOL_CALL_DELTAS = ["args": args,"index": 0,}- for args in ['{"path": ', '"a.py", ', '"content": ', '"hi"}']+ for args in _ARGS_SLICES]class TestToolCallsYieldDeltas:- """`.tool_calls` yields args deltas, not the snapshots the bridge emits."""+ """`.tool_calls` yields args deltas, as the bridge emits them."""def test_stream_events_v3_tool_calls_yield_deltas(self) -> None:stream = _StreamingToolCallModel().stream_events("hi", version="v3")@@ -1434,6 +1436,16 @@ class TestToolCallsYieldDeltas:assert [d async for d in stream.tool_calls] == _TOOL_CALL_DELTAS+ def test_replayed_events_carry_each_args_slice(self) -> None:+ stream = _StreamingToolCallModel().stream_events("hi", version="v3")+ assert stream.output.tool_calls[0]["args"] == {"path": "a.py", "content": "hi"}++ replayed = [e["delta"] for e in stream if e["event"] == "content-block-delta"]++ assert replayed == [+ {"type": "tool-call-delta", "args": args} for args in _ARGS_SLICES+ ]+class _CachedUsageModel(BaseChatModel):"""Replays an Anthropic-shaped usage split across stream chunks.diff --git a/libs/core/tests/unit_tests/language_models/test_compat_bridge.py b/libs/core/tests/unit_tests/language_models/test_compat_bridge.pyindex 2332ab39f6..46d21448c8 100644--- a/libs/core/tests/unit_tests/language_models/test_compat_bridge.py+++ b/libs/core/tests/unit_tests/language_models/test_compat_bridge.py@@ -446,6 +446,361 @@ def _assert_interleaved_parallel_tool_call_events(events: list[Any]) -> None:}+def _tool_call_chunk(+ args: str,+ *,+ id_: str | None = None,+ name: str | None = None,+ index: int = 0,+) -> ChatGenerationChunk:+ return ChatGenerationChunk(+ message=AIMessageChunk(+ content="",+ id="msg-1",+ tool_call_chunks=[+ {+ "type": "tool_call_chunk",+ "index": index,+ "id": id_,+ "name": name,+ "args": args,+ }+ ],+ )+ )+++def _sliced_tool_call_chunks() -> list[ChatGenerationChunk]:+ # Like OpenAI, the opener has the `id` and `name` but no args.+ return [+ _tool_call_chunk("", id_="call_1", name="write_file"),+ _tool_call_chunk('{"path": '),+ _tool_call_chunk('"a.py"}'),+ ]+++def test_chunks_to_events_tool_call_streams_args_as_slices() -> None:+ """Each chunk's new args go out as a `tool-call-delta` carrying only them.++ The call's `id`, `name` and provider `index` go on its start. An+ opener with no args sends no delta.+ """+ events = list(+ chunks_to_events(iter(_sliced_tool_call_chunks()), message_id="msg-1")+ )++ _assert_tool_call_streamed_as_slices(events)+++async def test_achunks_to_events_tool_call_streams_args_as_slices() -> None:+ """Async bridge streams tool-call args as slices too."""+ events = [+ event+ async for event in achunks_to_events(+ _aiter_chunks(_sliced_tool_call_chunks()), message_id="msg-1"+ )+ ]++ _assert_tool_call_streamed_as_slices(events)+++def _assert_tool_call_streamed_as_slices(events: list[Any]) -> None:+ assert_valid_event_stream(events)+ assert events[1:-1] == [+ {+ "event": "content-block-start",+ "index": 0,+ "content": {+ "type": "tool_call_chunk",+ "id": "call_1",+ "name": "write_file",+ "args": "",+ "index": 0,+ },+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '{"path": '},+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '"a.py"}'},+ },+ {+ "event": "content-block-finish",+ "index": 0,+ "content": {+ "type": "tool_call",+ "id": "call_1",+ "name": "write_file",+ "args": {"path": "a.py"},+ },+ },+ ]+++def _anthropic_server_tool_call_chunks() -> list[ChatGenerationChunk]:+ blocks: list[dict[str, Any]] = [+ {+ "type": "server_tool_use",+ "id": "srvtoolu_1",+ "name": "web_search",+ "input": {},+ },+ {"type": "input_json_delta", "partial_json": '{"query": '},+ {"type": "input_json_delta", "partial_json": '"weather"}'},+ ]+ return [+ ChatGenerationChunk(+ message=AIMessageChunk(+ content=[{"index": 0, **block}],+ id="msg-1",+ response_metadata={"model_provider": "anthropic"},+ )+ )+ for block in blocks+ ]+++def test_chunks_to_events_server_tool_call_streams_args_as_slices() -> None:+ """Anthropic server-tool `partial_json` streams as `tool-call-delta` too."""+ events = list(+ chunks_to_events(iter(_anthropic_server_tool_call_chunks()), message_id="msg-1")+ )++ _assert_server_tool_call_streamed_as_slices(events)+++async def test_achunks_to_events_server_tool_call_streams_args_as_slices() -> None:+ """Async bridge streams server-tool args as slices too."""+ events = [+ event+ async for event in achunks_to_events(+ _aiter_chunks(_anthropic_server_tool_call_chunks()), message_id="msg-1"+ )+ ]++ _assert_server_tool_call_streamed_as_slices(events)+++def _assert_server_tool_call_streamed_as_slices(events: list[Any]) -> None:+ assert_valid_event_stream(events)+ assert events[1:-1] == [+ {+ "event": "content-block-start",+ "index": 0,+ "content": {+ "type": "server_tool_call_chunk",+ "id": "srvtoolu_1",+ "name": "web_search",+ "args": "",+ "index": 0,+ },+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '{"query": '},+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '"weather"}'},+ },+ {+ "event": "content-block-finish",+ "index": 0,+ "content": {+ "type": "server_tool_call",+ "id": "srvtoolu_1",+ "name": "web_search",+ "args": {"query": "weather"},+ "index": 0,+ },+ },+ ]+++def test_chunks_to_events_late_tool_call_id_and_name_arrive_on_finish() -> None:+ """A call's `id` and `name` aren't updated after its start.++ `tool-call-delta` carries only args. An `id` or `name` the start+ didn't have reaches consumers on `content-block-finish`.+ """+ chunks = [+ _tool_call_chunk('{"q": '),+ _tool_call_chunk('"x"}', id_="c1", name="search"),+ ]++ events = list(chunks_to_events(iter(chunks), message_id="msg-1"))++ assert_valid_event_stream(events)+ assert events[1:-1] == [+ {+ "event": "content-block-start",+ "index": 0,+ "content": {+ "type": "tool_call_chunk",+ "id": None,+ "name": None,+ "args": "",+ "index": 0,+ },+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '{"q": '},+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '"x"}'},+ },+ {+ "event": "content-block-finish",+ "index": 0,+ "content": {+ "type": "tool_call",+ "id": "c1",+ "name": "search",+ "args": {"q": "x"},+ },+ },+ ]+++def test_chunks_to_events_tool_call_extras_only_on_finish() -> None:+ """Provider `extras` are for round-tripping, which reads the finished block."""+ chunks = [+ ChatGenerationChunk(+ message=AIMessageChunk(+ content=[+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "search",+ "args": '{"q": "x"}',+ "index": 0,+ "extras": {"item_id": "fc_1"},+ }+ ],+ response_metadata={"output_version": "v1"},+ )+ )+ ]++ events: list[Any] = list(chunks_to_events(iter(chunks), message_id="msg-1"))++ start, delta, finish = events[1:-1]+ assert start["content"] == {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "search",+ "args": "",+ "index": 0,+ }+ assert delta["delta"] == {"type": "tool-call-delta", "args": '{"q": "x"}'}+ assert finish["content"] == {+ "type": "tool_call",+ "id": "c1",+ "name": "search",+ "args": {"q": "x"},+ "extras": {"item_id": "fc_1"},+ }+++def _blank_args(event: Any) -> Any:+ """Blank a delta's args in place, as a stream transformer might."""+ if event["event"] == "content-block-delta":+ # Also reaches `block-delta` snapshots, whose `fields` were the+ # bridge's own running copy of the args, so going back to them+ # fails these tests.+ delta = event["delta"]+ delta.get("fields", delta)["args"] = ""+ return event+++def test_chunks_to_events_tool_call_deltas_are_independent_of_the_call() -> None:+ """Editing a delta in place can't corrupt the call.++ Each delta is a new object, not the bridge's running copy of the+ args, so the finished call doesn't see the edit.+ """+ events = [+ _blank_args(event)+ for event in chunks_to_events(iter(_sliced_tool_call_chunks()))+ ]++ finishes = [e for e in events if e["event"] == "content-block-finish"]+ assert finishes[0]["content"]["args"] == {"path": "a.py"}+++async def test_achunks_to_events_tool_call_deltas_are_independent_of_the_call() -> None:+ """Editing a delta in place can't corrupt the call in the async bridge either."""+ events = [+ _blank_args(event)+ async for event in achunks_to_events(_aiter_chunks(_sliced_tool_call_chunks()))+ ]++ finishes = [e for e in events if e["event"] == "content-block-finish"]+ assert finishes[0]["content"]["args"] == {"path": "a.py"}+++def test_message_to_events_tool_call_chunk_sends_its_args_as_one_slice() -> None:+ """Replaying an unfinished chunk sends its args as a single `tool-call-delta`."""+ msg = AIMessageChunk(+ content="",+ id="msg-1",+ tool_call_chunks=[+ {+ "type": "tool_call_chunk",+ "index": 0,+ "id": "c1",+ "name": "search",+ "args": '{"q": "x"}',+ }+ ],+ )++ events = list(message_to_events(msg))++ assert_valid_event_stream(events)+ assert events[1:-1] == [+ {+ "event": "content-block-start",+ "index": 0,+ "content": {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "search",+ "args": "",+ "index": 0,+ },+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": '{"q": "x"}'},+ },+ {+ "event": "content-block-finish",+ "index": 0,+ "content": {+ "type": "tool_call",+ "id": "c1",+ "name": "search",+ "args": {"q": "x"},+ },+ },+ ]++def test_chunks_to_events_invalid_tool_call_keeps_stop_reason() -> None:"""Malformed tool-args become invalid_tool_call; finish_reason stays `stop`."""chunks = [diff --git a/libs/core/uv.lock b/libs/core/uv.lockindex 45dccaec33..a866c76795 100644--- a/libs/core/uv.lock+++ b/libs/core/uv.lock@@ -1183,7 +1183,7 @@ typing = [requires-dist = [{ name = "httpx", specifier = ">=0.23.0,<1.0.0" },{ name = "jsonpatch", specifier = ">=1.33.0,<2.0.0" },- { name = "langchain-protocol", specifier = ">=0.0.17" },+ { name = "langchain-protocol", specifier = ">=0.0.20" },{ name = "langsmith", specifier = ">=0.14.9,<1.0.0" },{ name = "packaging", specifier = ">=23.2.0" },{ name = "pydantic", specifier = ">=2.7.4,<3.0.0" },@@ -1228,14 +1228,14 @@ typing = [[[package]]name = "langchain-protocol"-version = "0.0.18"+version = "0.0.20"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/d2/59/b5959aea96faa9146e2e49a7a22882b3528c62efafe9a6a95beab30c2305/langchain_protocol-0.0.18.tar.gz", hash = "sha256:ec3e11782f1ed0c9db38e5a9ed01b0e7a0d3fba406faa8aef6594b73c56a63e6", size = 6150, upload-time = "2026-06-18T17:08:26.959Z" }+sdist = { url = "https://files.pythonhosted.org/packages/cb/8b/d908d082c3cf5368ddd1816ed114de79c873f979ba7f98b95fab0e841643/langchain_protocol-0.0.20.tar.gz", hash = "sha256:0f5bd002474265648e91161771a9e0438fe9480bd55a416e51af0f60070637ec", size = 6280, upload-time = "2026-10-20T11:13:50.84Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/99/2e/d82db9eec13ad0f72e7aaad5c4bc730ab111934fdc83c85523206eb9b0a0/langchain_protocol-0.0.18-py3-none-any.whl", hash = "sha256:70b53a86fbf9cedc863555effe44da192ab02d556ddbf2cf95b8873adcf41b5a", size = 7221, upload-time = "2026-06-18T17:08:25.996Z" },+ { url = "https://files.pythonhosted.org/packages/02/4b/f1c99a0b27c5ff8b4b131c0d6e62012c17cc424089efe213767db927afd2/langchain_protocol-0.0.20-py3-none-any.whl", hash = "sha256:3c935e5e46b0f6f9cb52f45ba7cfa53d1b9fa80c82c4a277d47f03e07f7385b1", size = 7347, upload-time = "2026-10-20T11:13:49.566Z" },][[package]]