The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
style: more refs polishing (#33601)
Mason Daughertya47386f6dce4
diff --git a/libs/core/langchain_core/caches.py b/libs/core/langchain_core/caches.pyindex 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).!!! warningThis is a beta feature! Please be wary of deploying experimental code to productiondiff --git a/libs/core/langchain_core/tools/base.py b/libs/core/langchain_core/tools/base.pyindex 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 atwo-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.pyindex 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 propertiesdiff --git a/libs/langchain/langchain_classic/embeddings/base.py b/libs/langchain/langchain_classic/embeddings/base.pyindex 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 determineddiff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.pyindex 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 identifierdiff --git a/libs/langchain_v1/langchain/embeddings/base.py b/libs/langchain_v1/langchain/embeddings/base.pyindex 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 determineddiff --git a/libs/langchain_v1/langchain/tools/tool_node.py b/libs/langchain_v1/langchain/tools/tool_node.pyindex 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 flowKey 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 callsTypical 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 executeis independent and stateless.-Note:+!!! noteWhen implementing middleware for `create_agent`, use`AgentMiddleware.wrap_tool_call` which provides properly typedstate 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` accepttool calls with additional context (e.g. state) when dispatched using theSend 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 attemptingJSON 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:+ !!! noteThe 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:+ !!! noteThis function supports both single exception types and Union types forhandlers 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:+ !!! noteThis 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` whentool calls are present, which is the standard output format for tool-callinglanguage 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:+ !!! noteThis 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 schemaspresented 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 schemaspresented to language models- The store instance is automatically injected by `ToolNode` during execution