Skip to content

The agent engineering platform.

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.py
index 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 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 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:
```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 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:
```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 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