From 0b99ca4fcd8c9bf22d65914f9ad02fcbdda7c86e Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Mon, 12 Jan 2026 15:50:28 -0500 Subject: [PATCH] docs(core): enhance docstrings for `ToolCall` and `ToolCallChunk` (#34719) --- libs/core/langchain_core/messages/tool.py | 43 ++++++-- .../prompts/__snapshots__/test_chat.ambr | 26 ++++- .../runnables/__snapshots__/test_graph.ambr | 13 ++- .../__snapshots__/test_runnable.ambr | 104 ++++++++++++++---- 4 files changed, 142 insertions(+), 44 deletions(-) diff --git a/libs/core/langchain_core/messages/tool.py b/libs/core/langchain_core/messages/tool.py index e54953ff0dd..a83d4e6eb9e 100644 --- a/libs/core/langchain_core/messages/tool.py +++ b/libs/core/langchain_core/messages/tool.py @@ -214,20 +214,29 @@ class ToolCall(TypedDict): This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time """ name: str """The name of the tool to be called.""" + args: dict[str, Any] - """The arguments to the tool call.""" + """The arguments to the tool call as a dictionary.""" + id: str | None """An identifier associated with the tool call. An identifier is needed to associate a tool call request with a tool call result in events when multiple concurrent tool calls are made. - """ + type: NotRequired[Literal["tool_call"]] + """Used for discrimination.""" def tool_call( @@ -240,7 +249,7 @@ def tool_call( Args: name: The name of the tool to be called. - args: The arguments to the tool call. + args: The arguments to the tool call as a dictionary. id: An identifier associated with the tool call. Returns: @@ -252,9 +261,9 @@ def tool_call( class ToolCallChunk(TypedDict): """A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -270,13 +279,25 @@ class ToolCallChunk(TypedDict): name: str | None """The name of the tool to be called.""" + args: str | None - """The arguments to the tool call.""" + """The arguments to the tool call as a JSON-parseable string.""" + id: str | None - """An identifier associated with the tool call.""" + """An identifier associated with the tool call. + + An identifier is needed to associate a tool call request with a tool + call result in events when multiple concurrent tool calls are made. + """ + index: int | None - """The index of the tool call in a sequence.""" + """The index of the tool call in a sequence. + + Used for merging chunks. + """ + type: NotRequired[Literal["tool_call_chunk"]] + """Used for discrimination.""" def tool_call_chunk( @@ -290,7 +311,7 @@ def tool_call_chunk( Args: name: The name of the tool to be called. - args: The arguments to the tool call. + args: The arguments to the tool call as a JSON string. id: An identifier associated with the tool call. index: The index of the tool call in a sequence. @@ -313,7 +334,7 @@ def invalid_tool_call( Args: name: The name of the tool to be called. - args: The arguments to the tool call. + args: The arguments to the tool call as a JSON string. id: An identifier associated with the tool call. error: An error message associated with the tool call. diff --git a/libs/core/tests/unit_tests/prompts/__snapshots__/test_chat.ambr b/libs/core/tests/unit_tests/prompts/__snapshots__/test_chat.ambr index 3aa0d385040..89e39a59eb7 100644 --- a/libs/core/tests/unit_tests/prompts/__snapshots__/test_chat.ambr +++ b/libs/core/tests/unit_tests/prompts/__snapshots__/test_chat.ambr @@ -972,6 +972,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -1011,9 +1018,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -2380,6 +2387,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -2419,9 +2433,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python diff --git a/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr b/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr index af758665935..a455975d208 100644 --- a/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr +++ b/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr @@ -1396,6 +1396,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -1435,9 +1442,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python diff --git a/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr b/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr index da03e505204..0f04a93366a 100644 --- a/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr +++ b/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr @@ -2916,6 +2916,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -2954,9 +2961,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -4386,6 +4393,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -4424,9 +4438,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -5868,6 +5882,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -5906,9 +5927,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -7206,6 +7227,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -7244,9 +7272,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -8718,6 +8746,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -8756,9 +8791,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -10101,6 +10136,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -10139,9 +10181,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -11532,6 +11574,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -11570,9 +11619,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python @@ -12964,6 +13013,13 @@ This represents a request to call the tool named `'foo'` with arguments `{"a": 1}` and an identifier of `'123'`. + + !!! note "Factory function" + + `tool_call` may also be used as a factory to create a `ToolCall`. Benefits + include: + + * Required arguments strictly validated at creation time ''', 'properties': dict({ 'args': dict({ @@ -13002,9 +13058,9 @@ 'description': ''' A chunk of a tool call (yielded when streaming). - When merging `ToolCallChunk`s (e.g., via `AIMessageChunk.__add__`), - all string attributes are concatenated. Chunks are only merged if their - values of `index` are equal and not None. + When merging `ToolCallChunk` objects (e.g., via `AIMessageChunk.__add__`), all + string attributes are concatenated. Chunks are only merged if their values of + `index` are equal and not `None`. Example: ```python