Skip to content

The agent engineering platform.

style: more refs polishing (#33601)

Mason Daughertya47386f6dce4
diff --git a/libs/core/langchain_core/caches.py b/libs/core/langchain_core/caches.py
index 16878faba0..a2a90eadc6 100644
--- a/libs/core/langchain_core/caches.py
+++ b/libs/core/langchain_core/caches.py
@@ -1,4 +1,6 @@
-"""`caches` provides an optional caching layer for language models.
+"""Optional caching layer for language models.
+
+Distinct from provider-based [prompt caching](https://docs.langchain.com/oss/python/langchain/models#prompt-caching).
!!! warning
This is a beta feature! Please be wary of deploying experimental code to production
diff --git a/libs/core/langchain_core/tools/base.py b/libs/core/langchain_core/tools/base.py
index 845b4e3857..def3b22708 100644
--- a/libs/core/langchain_core/tools/base.py
+++ b/libs/core/langchain_core/tools/base.py
@@ -483,7 +483,7 @@ class ChildTool(BaseTool):
"""The tool response format.
If `"content"` then the output of the tool is interpreted as the contents of a
- ToolMessage. If `"content_and_artifact"` then the output is expected to be a
+ `ToolMessage`. If `"content_and_artifact"` then the output is expected to be a
two-tuple corresponding to the (content, artifact) of a `ToolMessage`.
"""
diff --git a/libs/core/langchain_core/utils/json_schema.py b/libs/core/langchain_core/utils/json_schema.py
index 6118bd95dc..68b04beb8c 100644
--- a/libs/core/langchain_core/utils/json_schema.py
+++ b/libs/core/langchain_core/utils/json_schema.py
@@ -226,7 +226,7 @@ def dereference_refs(
... }
>>> result = dereference_refs(schema) # Won't cause infinite recursion
- Note:
+ !!! note
- Circular references are handled gracefully by breaking cycles
- Mixed $ref objects (with both $ref and other properties) are supported
- Additional properties in mixed $refs override resolved properties
diff --git a/libs/langchain/langchain_classic/embeddings/base.py b/libs/langchain/langchain_classic/embeddings/base.py
index e409f2216a..2eea84f965 100644
--- a/libs/langchain/langchain_classic/embeddings/base.py
+++ b/libs/langchain/langchain_classic/embeddings/base.py
@@ -137,20 +137,34 @@ def init_embeddings(
installed.
Args:
- model: Name of the model to use. Can be either:
+ model: Name of the model to use.
+
+ Can be either:
+
- A model string like `"openai:text-embedding-3-small"`
- - Just the model name if provider is specified
- provider: Optional explicit provider name. If not specified,
- will attempt to parse from the model string. Supported providers
- and their required packages:
+ - Just the model name if the provider is specified separately or can be
+ inferred.
+
+ See supported providers under the `provider` arg description.
+ provider: Optional explicit provider name. If not specified, will attempt to
+ parse from the model string in the `model` arg.
+
+ Supported providers:
- {_get_provider_list()}
+ - `openai` -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+ - `azure_openai` -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+ - `bedrock` -> [`langchain-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+ - `cohere` -> [`langchain-cohere`](https://docs.langchain.com/oss/python/integrations/providers/cohere)
+ - `google_vertexai` -> [`langchain-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+ - `huggingface` -> [`langchain-huggingface`](https://docs.langchain.com/oss/python/integrations/providers/huggingface)
+ - `mistraiai` -> [`langchain-mistralai`](https://docs.langchain.com/oss/python/integrations/providers/mistralai)
+ - `ollama` -> [`langchain-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
**kwargs: Additional model-specific parameters passed to the embedding model.
These vary by provider, see the provider-specific documentation for details.
Returns:
- An Embeddings instance that can generate embeddings for text.
+ An `Embeddings` instance that can generate embeddings for text.
Raises:
ValueError: If the model provider is not supported or cannot be determined
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.py
index abe83db46b..2f9962759f 100644
--- a/libs/langchain_v1/langchain/agents/factory.py
+++ b/libs/langchain_v1/langchain/agents/factory.py
@@ -525,7 +525,7 @@ def create_agent( # noqa: PLR0915
"""Creates an agent graph that calls tools in a loop until a stopping condition is met.
For more details on using `create_agent`,
- visit [Agents](https://docs.langchain.com/oss/python/langchain/agents) documentation.
+ visit the [Agents](https://docs.langchain.com/oss/python/langchain/agents) docs.
Args:
model: The language model for the agent. Can be a string identifier
diff --git a/libs/langchain_v1/langchain/embeddings/base.py b/libs/langchain_v1/langchain/embeddings/base.py
index 08e4e6a538..2793c02df7 100644
--- a/libs/langchain_v1/langchain/embeddings/base.py
+++ b/libs/langchain_v1/langchain/embeddings/base.py
@@ -133,20 +133,34 @@ def init_embeddings(
installed.
Args:
- model: Name of the model to use. Can be either:
+ model: Name of the model to use.
+
+ Can be either:
+
- A model string like `"openai:text-embedding-3-small"`
- - Just the model name if provider is specified
- provider: Optional explicit provider name. If not specified,
- will attempt to parse from the model string. Supported providers
- and their required packages:
+ - Just the model name if the provider is specified separately or can be
+ inferred.
+
+ See supported providers under the `provider` arg description.
+ provider: Optional explicit provider name. If not specified, will attempt to
+ parse from the model string in the `model` arg.
+
+ Supported providers:
- {_get_provider_list()}
+ - `openai` -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+ - `azure_openai` -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+ - `bedrock` -> [`langchain-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+ - `cohere` -> [`langchain-cohere`](https://docs.langchain.com/oss/python/integrations/providers/cohere)
+ - `google_vertexai` -> [`langchain-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+ - `huggingface` -> [`langchain-huggingface`](https://docs.langchain.com/oss/python/integrations/providers/huggingface)
+ - `mistraiai` -> [`langchain-mistralai`](https://docs.langchain.com/oss/python/integrations/providers/mistralai)
+ - `ollama` -> [`langchain-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
**kwargs: Additional model-specific parameters passed to the embedding model.
These vary by provider, see the provider-specific documentation for details.
Returns:
- An Embeddings instance that can generate embeddings for text.
+ An `Embeddings` instance that can generate embeddings for text.
Raises:
ValueError: If the model provider is not supported or cannot be determined
diff --git a/libs/langchain_v1/langchain/tools/tool_node.py b/libs/langchain_v1/langchain/tools/tool_node.py
index bd17127438..0a9118be05 100644
--- a/libs/langchain_v1/langchain/tools/tool_node.py
+++ b/libs/langchain_v1/langchain/tools/tool_node.py
@@ -13,10 +13,10 @@ The module implements design patterns for:
- Command-based state updates for advanced control flow
Key Components:
- ToolNode: Main class for executing tools in LangGraph workflows
- InjectedState: Annotation for injecting graph state into tools
- InjectedStore: Annotation for injecting persistent store into tools
- tools_condition: Utility function for conditional routing based on tool calls
+ `ToolNode`: Main class for executing tools in LangGraph workflows
+ `InjectedState`: Annotation for injecting graph state into tools
+ `InjectedStore`: Annotation for injecting persistent store into tools
+ `tools_condition`: Utility function for conditional routing based on tool calls
Typical Usage:
```python
@@ -123,11 +123,11 @@ class ToolCallRequest:
Attributes:
tool_call: Tool call dict with name, args, and id from model output.
tool: BaseTool instance to be invoked, or None if tool is not
- registered with the ToolNode. When tool is None, interceptors can
- handle the request without validation. If the interceptor calls execute(),
+ registered with the `ToolNode`. When tool is `None`, interceptors can
+ handle the request without validation. If the interceptor calls `execute()`,
validation will occur and raise an error for unregistered tools.
- state: Agent state (dict, list, or BaseModel).
- runtime: LangGraph runtime context (optional, None if outside graph).
+ state: Agent state (`dict`, `list`, or `BaseModel`).
+ runtime: LangGraph runtime context (optional, `None` if outside graph).
"""
tool_call: ToolCall
@@ -178,7 +178,7 @@ The execute callable can be invoked multiple times for retry logic,
with potentially modified requests each time. Each call to execute
is independent and stateless.
-Note:
+!!! note
When implementing middleware for `create_agent`, use
`AgentMiddleware.wrap_tool_call` which provides properly typed
state parameter for better type safety.
@@ -247,7 +247,7 @@ AsyncToolCallWrapper = Callable[
class ToolCallWithContext(TypedDict):
"""ToolCall with additional context for graph state.
- This is an internal data structure meant to help the ToolNode accept
+ This is an internal data structure meant to help the `ToolNode` accept
tool calls with additional context (e.g. state) when dispatched using the
Send API.
@@ -268,16 +268,16 @@ class ToolCallWithContext(TypedDict):
def msg_content_output(output: Any) -> str | list[dict]:
- """Convert tool output to ToolMessage content format.
+ """Convert tool output to `ToolMessage` content format.
- Handles str, list[dict] (content blocks), and arbitrary objects by attempting
+ Handles `str`, `list[dict]` (content blocks), and arbitrary objects by attempting
JSON serialization with fallback to str().
Args:
output: Tool execution output of any type.
Returns:
- String or list of content blocks suitable for ToolMessage.content.
+ String or list of content blocks suitable for `ToolMessage.content`.
"""
if isinstance(output, str) or (
isinstance(output, list)
@@ -297,7 +297,7 @@ def msg_content_output(output: Any) -> str | list[dict]:
class ToolInvocationError(ToolException):
"""An error occurred while invoking a tool due to invalid arguments.
- This exception is only raised when invoking a tool using the ToolNode!
+ This exception is only raised when invoking a tool using the `ToolNode`!
"""
def __init__(
@@ -338,7 +338,7 @@ def _handle_tool_error(
"""Generate error message content based on exception handling configuration.
This function centralizes error message generation logic, supporting different
- error handling strategies configured via the ToolNode's handle_tool_errors
+ error handling strategies configured via the `ToolNode`'s `handle_tool_errors`
parameter.
Args:
@@ -350,12 +350,12 @@ def _handle_tool_error(
- tuple: Not used in this context (handled by caller)
Returns:
- A string containing the error message to include in the ToolMessage.
+ A string containing the error message to include in the `ToolMessage`.
Raises:
ValueError: If flag is not one of the supported types.
- Note:
+ !!! note
The tuple case is handled by the caller through exception type checking,
not by this function directly.
"""
@@ -392,9 +392,9 @@ def _infer_handled_types(handler: Callable[..., str]) -> tuple[type[Exception],
Raises:
ValueError: If the handler's annotation contains non-Exception types or
- if Union types contain non-Exception types.
+ if Union types contain non-Exception types.
- Note:
+ !!! note
This function supports both single exception types and Union types for
handlers that need to handle multiple exception types differently.
"""
@@ -560,7 +560,7 @@ class _ToolNode(RunnableCallable):
wrap_tool_call: ToolCallWrapper | None = None,
awrap_tool_call: AsyncToolCallWrapper | None = None,
) -> None:
- """Initialize ToolNode with tools and configuration.
+ """Initialize `ToolNode` with tools and configuration.
Args:
tools: Sequence of tools to make available for execution.
@@ -1181,11 +1181,11 @@ class _ToolNode(RunnableCallable):
Raises:
ValueError: If a tool requires store injection but no store is provided,
- or if state injection requirements cannot be satisfied.
+ or if state injection requirements cannot be satisfied.
- Note:
+ !!! note
This method is called automatically during tool execution. It should not
- be called from outside the ToolNode.
+ be called from outside the `ToolNode`.
"""
if tool_call["name"] not in self.tools_by_name:
return tool_call
@@ -1329,9 +1329,9 @@ def tools_condition(
return tools_condition(state, messages_key="chat_history")
```
- Note:
- This function is designed to work seamlessly with ToolNode and standard
- LangGraph patterns. It expects the last message to be an AIMessage when
+ !!! note
+ This function is designed to work seamlessly with `ToolNode` and standard
+ LangGraph patterns. It expects the last message to be an `AIMessage` when
tool calls are present, which is the standard output format for tool-calling
language models.
"""
@@ -1353,16 +1353,16 @@ def tools_condition(
class ToolRuntime(_DirectlyInjectedToolArg, Generic[ContextT, StateT]):
"""Runtime context automatically injected into tools.
- When a tool function has a parameter named 'tool_runtime' with type hint
- 'ToolRuntime', the tool execution system will automatically inject
- an instance containing:
+ When a tool function has a parameter named `tool_runtime` with type hint
+ `ToolRuntime`, the tool execution system will automatically inject an instance
+ containing:
- - state: The current graph state
- - tool_call_id: The ID of the current tool call
- - config: RunnableConfig for the current execution
- - context: Runtime context (from langgraph Runtime)
- - store: BaseStore instance for persistent storage (from langgraph Runtime)
- - stream_writer: StreamWriter for streaming output (from langgraph Runtime)
+ - `state`: The current graph state
+ - `tool_call_id`: The ID of the current tool call
+ - `config`: `RunnableConfig` for the current execution
+ - `context`: Runtime context (from langgraph `Runtime`)
+ - `store`: `BaseStore` instance for persistent storage (from langgraph `Runtime`)
+ - `stream_writer`: `StreamWriter` for streaming output (from langgraph `Runtime`)
No `Annotated` wrapper is needed - just use `runtime: ToolRuntime`
as a parameter.
@@ -1396,7 +1396,7 @@ class ToolRuntime(_DirectlyInjectedToolArg, Generic[ContextT, StateT]):
return f"Processed {x}"
```
- Note:
+ !!! note
This is a marker class used for type checking and detection.
The actual runtime object will be constructed during tool execution.
"""
@@ -1470,7 +1470,7 @@ class InjectedState(InjectedToolArg):
]
```
- Note:
+ !!! note
- `InjectedState` arguments are automatically excluded from tool schemas
presented to language models
- `ToolNode` handles the injection process during execution
@@ -1550,7 +1550,7 @@ class InjectedStore(InjectedToolArg):
result2 = graph.invoke({"messages": [HumanMessage("What's my favorite color?")]})
```
- Note:
+ !!! note
- `InjectedStore` arguments are automatically excluded from tool schemas
presented to language models
- The store instance is automatically injected by `ToolNode` during execution