The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
docs(core): enhance docstrings for `ToolCall` and `ToolCallChunk` (#34719)
Mason Daugherty0b99ca4fcd8c
diff --git a/libs/core/langchain_core/messages/tool.py b/libs/core/langchain_core/messages/tool.pyindex e54953ff0d..a83d4e6eb9 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 toolcall 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.ambrindex 3aa0d38504..89e39a59eb 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:```pythondiff --git a/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr b/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambrindex af75866593..a455975d20 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:```pythondiff --git a/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr b/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambrindex da03e50520..0f04a93366 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