langchain 1.0.0a15__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

langchain/__init__.py

@@ -1,3 +1,3 @@
 """Main entrypoint into LangChain."""
 
-__version__ = "1.0.0a14"
+__version__ = "1.0.0rc1"

langchain/agents/__init__.py

@@ -1,4 +1,10 @@
-"""langgraph.prebuilt exposes a higher-level API for creating and executing agents and tools."""
+"""Entrypoint to building [Agents](https://docs.langchain.com/oss/python/langchain/agents) with LangChain.
+
+!!! warning "Reference docs"
+    This page contains **reference documentation** for Agents. See
+    [the docs](https://docs.langchain.com/oss/python/langchain/agents) for conceptual
+    guides, tutorials, and examples on using Agents.
+"""  # noqa: E501
 
 from langchain.agents.factory import create_agent
 from langchain.agents.middleware.types import AgentState

langchain/agents/factory.py

@@ -92,7 +92,7 @@ def _chain_model_call_handlers(
         handlers: List of handlers. First handler wraps all others.
 
     Returns:
-        Composed handler, or None if handlers empty.
+        Composed handler, or `None` if handlers empty.
 
     Example:
         ```python
@@ -195,13 +195,13 @@ def _chain_async_model_call_handlers(
     ]
     | None
 ):
-    """Compose multiple async wrap_model_call handlers into single middleware stack.
+    """Compose multiple async `wrap_model_call` handlers into single middleware stack.
 
     Args:
         handlers: List of async handlers. First handler wraps all others.
 
     Returns:
-        Composed async handler, or None if handlers empty.
+        Composed async handler, or `None` if handlers empty.
     """
     if not handlers:
         return None
@@ -267,12 +267,13 @@ def _chain_async_model_call_handlers(
 
 
 def _resolve_schema(schemas: set[type], schema_name: str, omit_flag: str | None = None) -> type:
-    """Resolve schema by merging schemas and optionally respecting OmitFromSchema annotations.
+    """Resolve schema by merging schemas and optionally respecting `OmitFromSchema` annotations.
 
     Args:
         schemas: List of schema types to merge
-        schema_name: Name for the generated TypedDict
-        omit_flag: If specified, omit fields with this flag set ('input' or 'output')
+        schema_name: Name for the generated `TypedDict`
+        omit_flag: If specified, omit fields with this flag set (`'input'` or
+            `'output'`)
     """
     all_annotations = {}
 
@@ -312,11 +313,11 @@ def _extract_metadata(type_: type) -> list:
 
 
 def _get_can_jump_to(middleware: AgentMiddleware[Any, Any], hook_name: str) -> list[JumpTo]:
-    """Get the can_jump_to list from either sync or async hook methods.
+    """Get the `can_jump_to` list from either sync or async hook methods.
 
     Args:
         middleware: The middleware instance to inspect.
-        hook_name: The name of the hook ('before_model' or 'after_model').
+        hook_name: The name of the hook (`'before_model'` or `'after_model'`).
 
     Returns:
         List of jump destinations, or empty list if not configured.
@@ -350,7 +351,7 @@ def _supports_provider_strategy(model: str | BaseChatModel) -> bool:
     """Check if a model supports provider-specific structured output.
 
     Args:
-        model: Model name string or BaseChatModel instance.
+        model: Model name string or `BaseChatModel` instance.
 
     Returns:
         `True` if the model supports provider-specific structured output, `False` otherwise.
@@ -373,7 +374,7 @@ def _handle_structured_output_error(
     exception: Exception,
     response_format: ResponseFormat,
 ) -> tuple[bool, str]:
-    """Handle structured output error. Returns (should_retry, retry_tool_message)."""
+    """Handle structured output error. Returns `(should_retry, retry_tool_message)`."""
     if not isinstance(response_format, ToolStrategy):
         return False, ""
 
@@ -408,7 +409,7 @@ def _chain_tool_call_wrappers(
         wrappers: Wrappers in middleware order.
 
     Returns:
-        Composed wrapper, or None if empty.
+        Composed wrapper, or `None` if empty.
 
     Example:
         wrapper = _chain_tool_call_wrappers([auth, cache, retry])
@@ -465,7 +466,7 @@ def _chain_async_tool_call_wrappers(
         wrappers: Async wrappers in middleware order.
 
     Returns:
-        Composed async wrapper, or None if empty.
+        Composed async wrapper, or `None` if empty.
     """
     if not wrappers:
         return None
@@ -516,6 +517,7 @@ def create_agent(  # noqa: PLR0915
     system_prompt: str | None = None,
     middleware: Sequence[AgentMiddleware[AgentState[ResponseT], ContextT]] = (),
     response_format: ResponseFormat[ResponseT] | type[ResponseT] | None = None,
+    state_schema: type[AgentState[ResponseT]] | None = None,
     context_schema: type[ContextT] | None = None,
     checkpointer: Checkpointer | None = None,
     store: BaseStore | None = None,
@@ -534,11 +536,13 @@ def create_agent(  # noqa: PLR0915
 
     Args:
         model: The language model for the agent. Can be a string identifier
-            (e.g., `"openai:gpt-4"`), a chat model instance (e.g., `ChatOpenAI()`).
-        tools: A list of tools, dicts, or callables. If `None` or an empty list,
+            (e.g., `"openai:gpt-4"`) or a chat model instance (e.g., `ChatOpenAI()`).
+            For a full list of supported model strings, see
+            [`init_chat_model`][langchain.chat_models.init_chat_model(model_provider)].
+        tools: A list of tools, `dicts`, or `Callable`. If `None` or an empty list,
             the agent will consist of a model node without a tool calling loop.
         system_prompt: An optional system prompt for the LLM. Prompts are converted to a
-        `SystemMessage` and added to the beginning of the message list.
+            `SystemMessage` and added to the beginning of the message list.
         middleware: A sequence of middleware instances to apply to the agent.
             Middleware can intercept and modify agent behavior at various stages.
         response_format: An optional configuration for structured responses.
@@ -546,6 +550,13 @@ def create_agent(  # noqa: PLR0915
             If provided, the agent will handle structured output during the
             conversation flow. Raw schemas will be wrapped in an appropriate strategy
             based on model capabilities.
+        state_schema: An optional `TypedDict` schema that extends `AgentState`.
+            When provided, this schema is used instead of `AgentState` as the base
+            schema for merging with middleware state schemas. This allows users to
+            add custom state fields without needing to create custom middleware.
+            Generally, it's recommended to use state_schema extensions via middleware
+            to keep relevant extensions scoped to corresponding hooks / tools.
+            The schema must be a subclass of `AgentState[ResponseT]`.
         context_schema: An optional schema for runtime context.
         checkpointer: An optional checkpoint saver object. This is used for persisting
             the state of the graph (e.g., as chat memory) for a single thread
@@ -553,12 +564,15 @@ def create_agent(  # noqa: PLR0915
         store: An optional store object. This is used for persisting data
             across multiple threads (e.g., multiple conversations / users).
         interrupt_before: An optional list of node names to interrupt before.
-            This is useful if you want to add a user confirmation or other interrupt
+            Useful if you want to add a user confirmation or other interrupt
             before taking an action.
         interrupt_after: An optional list of node names to interrupt after.
-            This is useful if you want to return directly or run additional processing
+            Useful if you want to return directly or run additional processing
             on an output.
-        debug: A flag indicating whether to enable debug mode.
+        debug: Whether to enable verbose logging for graph execution. When enabled,
+            prints detailed information about each node execution, state updates,
+            and transitions during agent runtime. Useful for debugging middleware
+            behavior and understanding agent execution flow.
         name: An optional name for the `CompiledStateGraph`.
             This name will be automatically used when adding the agent graph to
             another graph as a subgraph node - particularly useful for building
@@ -569,8 +583,8 @@ def create_agent(  # noqa: PLR0915
         A compiled `StateGraph` that can be used for chat interactions.
 
     The agent node calls the language model with the messages list (after applying
-    the system prompt). If the resulting AIMessage contains `tool_calls`, the graph will
-    then call the tools. The tools node executes the tools and adds the responses
+    the system prompt). If the resulting `AIMessage` contains `tool_calls`, the graph
+    will then call the tools. The tools node executes the tools and adds the responses
     to the messages list as `ToolMessage` objects. The agent node then calls the
     language model again. The process repeats until no more `tool_calls` are
     present in the response. The agent then returns the full list of messages.
@@ -586,7 +600,7 @@ def create_agent(  # noqa: PLR0915
 
 
         graph = create_agent(
-            model="anthropic:claude-3-7-sonnet-latest",
+            model="anthropic:claude-sonnet-4-5-20250929",
             tools=[check_weather],
             system_prompt="You are a helpful assistant",
         )
@@ -756,9 +770,11 @@ def create_agent(  # noqa: PLR0915
         awrap_model_call_handler = _chain_async_model_call_handlers(async_handlers)
 
     state_schemas = {m.state_schema for m in middleware}
-    state_schemas.add(AgentState)
+    # Use provided state_schema if available, otherwise use base AgentState
+    base_state = state_schema if state_schema is not None else AgentState
+    state_schemas.add(base_state)
 
-    state_schema = _resolve_schema(state_schemas, "StateSchema", None)
+    resolved_state_schema = _resolve_schema(state_schemas, "StateSchema", None)
     input_schema = _resolve_schema(state_schemas, "InputSchema", "input")
     output_schema = _resolve_schema(state_schemas, "OutputSchema", "output")
 
@@ -766,7 +782,7 @@ def create_agent(  # noqa: PLR0915
     graph: StateGraph[
         AgentState[ResponseT], ContextT, PublicAgentState[ResponseT], PublicAgentState[ResponseT]
     ] = StateGraph(
-        state_schema=state_schema,
+        state_schema=resolved_state_schema,
         input_schema=input_schema,
         output_schema=output_schema,
         context_schema=context_schema,
@@ -878,8 +894,9 @@ def create_agent(  # noqa: PLR0915
             request: The model request containing model, tools, and response format.
 
         Returns:
-            Tuple of (bound_model, effective_response_format) where `effective_response_format`
-            is the actual strategy used (may differ from initial if auto-detected).
+            Tuple of `(bound_model, effective_response_format)` where
+            `effective_response_format` is the actual strategy used (may differ from
+            initial if auto-detected).
         """
         # Validate ONLY client-side tools that need to exist in tool_node
         # Build map of available client-side tools from the ToolNode
@@ -985,7 +1002,7 @@ def create_agent(  # noqa: PLR0915
     def _execute_model_sync(request: ModelRequest) -> ModelResponse:
         """Execute model and return response.
 
-        This is the core model execution logic wrapped by wrap_model_call handlers.
+        This is the core model execution logic wrapped by `wrap_model_call` handlers.
         Raises any exceptions that occur during model invocation.
         """
         # Get the bound model (with auto-detection if needed)
@@ -1036,7 +1053,9 @@ def create_agent(  # noqa: PLR0915
     async def _execute_model_async(request: ModelRequest) -> ModelResponse:
         """Execute model asynchronously and return response.
 
-        This is the core async model execution logic wrapped by wrap_model_call handlers.
+        This is the core async model execution logic wrapped by `wrap_model_call`
+        handlers.
+
         Raises any exceptions that occur during model invocation.
         """
         # Get the bound model (with auto-detection if needed)
@@ -1110,7 +1129,9 @@ def create_agent(  # noqa: PLR0915
                 else None
             )
             before_agent_node = RunnableCallable(sync_before_agent, async_before_agent, trace=False)
-            graph.add_node(f"{m.name}.before_agent", before_agent_node, input_schema=state_schema)
+            graph.add_node(
+                f"{m.name}.before_agent", before_agent_node, input_schema=resolved_state_schema
+            )
 
         if (
             m.__class__.before_model is not AgentMiddleware.before_model
@@ -1129,7 +1150,9 @@ def create_agent(  # noqa: PLR0915
                 else None
             )
             before_node = RunnableCallable(sync_before, async_before, trace=False)
-            graph.add_node(f"{m.name}.before_model", before_node, input_schema=state_schema)
+            graph.add_node(
+                f"{m.name}.before_model", before_node, input_schema=resolved_state_schema
+            )
 
         if (
             m.__class__.after_model is not AgentMiddleware.after_model
@@ -1148,7 +1171,7 @@ def create_agent(  # noqa: PLR0915
                 else None
             )
             after_node = RunnableCallable(sync_after, async_after, trace=False)
-            graph.add_node(f"{m.name}.after_model", after_node, input_schema=state_schema)
+            graph.add_node(f"{m.name}.after_model", after_node, input_schema=resolved_state_schema)
 
         if (
             m.__class__.after_agent is not AgentMiddleware.after_agent
@@ -1167,7 +1190,9 @@ def create_agent(  # noqa: PLR0915
                 else None
             )
             after_agent_node = RunnableCallable(sync_after_agent, async_after_agent, trace=False)
-            graph.add_node(f"{m.name}.after_agent", after_agent_node, input_schema=state_schema)
+            graph.add_node(
+                f"{m.name}.after_agent", after_agent_node, input_schema=resolved_state_schema
+            )
 
     # Determine the entry node (runs once at start): before_agent -> before_model -> model
     if middleware_w_before_agent:
@@ -1200,6 +1225,15 @@ def create_agent(  # noqa: PLR0915
     graph.add_edge(START, entry_node)
     # add conditional edges only if tools exist
     if tool_node is not None:
+        # Only include exit_node in destinations if any tool has return_direct=True
+        # or if there are structured output tools
+        tools_to_model_destinations = [loop_entry_node]
+        if (
+            any(tool.return_direct for tool in tool_node.tools_by_name.values())
+            or structured_output_tools
+        ):
+            tools_to_model_destinations.append(exit_node)
+
         graph.add_conditional_edges(
             "tools",
             _make_tools_to_model_edge(
@@ -1208,7 +1242,7 @@ def create_agent(  # noqa: PLR0915
                 structured_output_tools=structured_output_tools,
                 end_destination=exit_node,
             ),
-            [loop_entry_node, exit_node],
+            tools_to_model_destinations,
         )
 
         # base destinations are tools and exit_node

langchain/agents/middleware/__init__.py

@@ -1,4 +1,10 @@
-"""Middleware plugins for agents."""
+"""Entrypoint to using [Middleware](https://docs.langchain.com/oss/python/langchain/middleware) plugins with [Agents](https://docs.langchain.com/oss/python/langchain/agents).
+
+!!! warning "Reference docs"
+    This page contains **reference documentation** for Middleware. See
+    [the docs](https://docs.langchain.com/oss/python/langchain/middleware) for conceptual
+    guides, tutorials, and examples on using Middleware.
+"""  # noqa: E501
 
 from .context_editing import (
     ClearToolUsesEdit,
@@ -15,6 +21,7 @@ from .summarization import SummarizationMiddleware
 from .todo import TodoListMiddleware
 from .tool_call_limit import ToolCallLimitMiddleware
 from .tool_emulator import LLMToolEmulator
+from .tool_retry import ToolRetryMiddleware
 from .tool_selection import LLMToolSelectorMiddleware
 from .types import (
     AgentMiddleware,
@@ -49,6 +56,7 @@ __all__ = [
     "SummarizationMiddleware",
     "TodoListMiddleware",
     "ToolCallLimitMiddleware",
+    "ToolRetryMiddleware",
     "after_agent",
     "after_model",
     "before_agent",

langchain/agents/middleware/context_editing.py

@@ -198,7 +198,7 @@ class ContextEditingMiddleware(AgentMiddleware):
         edits: Iterable[ContextEdit] | None = None,
         token_count_method: Literal["approximate", "model"] = "approximate",  # noqa: S107
     ) -> None:
-        """Initialise a context editing middleware instance.
+        """Initializes a context editing middleware instance.
 
         Args:
             edits: Sequence of edit strategies to apply. Defaults to a single

langchain/agents/middleware/human_in_the_loop.py

@@ -110,7 +110,8 @@ class _DescriptionFactory(Protocol):
 class InterruptOnConfig(TypedDict):
     """Configuration for an action requiring human in the loop.
 
-    This is the configuration format used in the `HumanInTheLoopMiddleware.__init__` method.
+    This is the configuration format used in the `HumanInTheLoopMiddleware.__init__`
+    method.
     """
 
     allowed_decisions: list[DecisionType]
@@ -120,6 +121,7 @@ class InterruptOnConfig(TypedDict):
     """The description attached to the request for human input.
 
     Can be either:
+
     - A static string describing the approval request
     - A callable that dynamically generates the description based on agent state,
         runtime, and tool call information
@@ -171,12 +173,14 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
 
                 * `True` indicates all decisions are allowed: approve, edit, and reject.
                 * `False` indicates that the tool is auto-approved.
-                * `InterruptOnConfig` indicates the specific decisions allowed for this tool.
-                    The InterruptOnConfig can include a `description` field (str or callable) for
-                    custom formatting of the interrupt description.
+                * `InterruptOnConfig` indicates the specific decisions allowed for this
+                    tool.
+                    The InterruptOnConfig can include a `description` field (`str` or
+                    `Callable`) for custom formatting of the interrupt description.
             description_prefix: The prefix to use when constructing action requests.
-                This is used to provide context about the tool call and the action being requested.
-                Not used if a tool has a `description` in its InterruptOnConfig.
+                This is used to provide context about the tool call and the action being
+                requested. Not used if a tool has a `description` in its
+                `InterruptOnConfig`.
         """
         super().__init__()
         resolved_configs: dict[str, InterruptOnConfig] = {}
@@ -270,7 +274,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
         raise ValueError(msg)
 
     def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
-        """Trigger interrupt flows for relevant tool calls after an AIMessage."""
+        """Trigger interrupt flows for relevant tool calls after an `AIMessage`."""
         messages = state["messages"]
         if not messages:
             return None

langchain/agents/middleware/model_call_limit.py

@@ -127,17 +127,16 @@ class ModelCallLimitMiddleware(AgentMiddleware[ModelCallLimitState, Any]):
 
         Args:
             thread_limit: Maximum number of model calls allowed per thread.
-                None means no limit. Defaults to `None`.
+                None means no limit.
             run_limit: Maximum number of model calls allowed per run.
-                None means no limit. Defaults to `None`.
+                None means no limit.
             exit_behavior: What to do when limits are exceeded.
                 - "end": Jump to the end of the agent execution and
                     inject an artificial AI message indicating that the limit was exceeded.
-                - "error": Raise a ModelCallLimitExceededError
-                Defaults to "end".
+                - "error": Raise a `ModelCallLimitExceededError`
 
         Raises:
-            ValueError: If both limits are None or if exit_behavior is invalid.
+            ValueError: If both limits are `None` or if `exit_behavior` is invalid.
         """
         super().__init__()
 

langchain/agents/middleware/model_fallback.py

@@ -75,8 +75,6 @@ class ModelFallbackMiddleware(AgentMiddleware):
 
         Args:
             request: Initial model request.
-            state: Current agent state.
-            runtime: LangGraph runtime.
             handler: Callback to execute the model.
 
         Returns:

langchain/agents/middleware/pii.py

@@ -421,7 +421,7 @@ class PIIMiddleware(AgentMiddleware):
         - `credit_card`: Credit card numbers (validated with Luhn algorithm)
         - `ip`: IP addresses (validated with stdlib)
         - `mac_address`: MAC addresses
-        - `url`: URLs (both http/https and bare URLs)
+        - `url`: URLs (both `http`/`https` and bare URLs)
 
     Strategies:
         - `block`: Raise an exception when PII is detected
@@ -431,12 +431,12 @@ class PIIMiddleware(AgentMiddleware):
 
     Strategy Selection Guide:
 
-        | Strategy | Preserves Identity? | Best For                                |
-        | -------- | ------------------- | --------------------------------------- |
-        | `block`  | N/A                 | Avoid PII completely                    |
-        | `redact` | No                  | General compliance, log sanitization    |
-        | `mask`   | No                  | Human readability, customer service UIs |
-        | `hash`   | Yes (pseudonymous)  | Analytics, debugging                    |
+    | Strategy | Preserves Identity? | Best For                                |
+    | -------- | ------------------- | --------------------------------------- |
+    | `block`  | N/A                 | Avoid PII completely                    |
+    | `redact` | No                  | General compliance, log sanitization    |
+    | `mask`   | No                  | Human readability, customer service UIs |
+    | `hash`   | Yes (pseudonymous)  | Analytics, debugging                    |
 
     Example:
         ```python

langchain/agents/middleware/tool_call_limit.py

@@ -204,7 +204,7 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState, Any]):
                 Defaults to "end".
 
         Raises:
-            ValueError: If both limits are None or if exit_behavior is invalid.
+            ValueError: If both limits are `None` or if `exit_behavior` is invalid.
         """
         super().__init__()
 

langchain/agents/middleware/tool_emulator.py

@@ -123,7 +123,7 @@ class LLMToolEmulator(AgentMiddleware):
 
         # Extract tool information for emulation
         tool_args = request.tool_call["args"]
-        tool_description = request.tool.description
+        tool_description = request.tool.description if request.tool else "No description available"
 
         # Build prompt for emulator LLM
         prompt = (
@@ -175,7 +175,7 @@ class LLMToolEmulator(AgentMiddleware):
 
         # Extract tool information for emulation
         tool_args = request.tool_call["args"]
-        tool_description = request.tool.description
+        tool_description = request.tool.description if request.tool else "No description available"
 
         # Build prompt for emulator LLM
         prompt = (