langchain 1.0.0a14__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.0a13"
+__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,19 +536,27 @@ 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. If provided as a string,
-            it will be converted to a SystemMessage and added to the beginning
-            of the message list.
+        system_prompt: An optional system prompt for the LLM. Prompts are converted to a
+            `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.
-            Can be a ToolStrategy, ProviderStrategy, or a Pydantic model class.
+            Can be a `ToolStrategy`, `ProviderStrategy`, or a Pydantic model class.
             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
@@ -554,24 +564,27 @@ 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.
-        name: An optional name for the CompiledStateGraph.
+        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
             multi-agent systems.
-        cache: An optional BaseCache instance to enable caching of graph execution.
+        cache: An optional `BaseCache` instance to enable caching of graph execution.
 
     Returns:
-        A compiled StateGraph that can be used for chat interactions.
+        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.
@@ -587,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",
         )
@@ -757,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")
 
@@ -767,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,
@@ -879,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
@@ -986,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)
@@ -1032,16 +1048,14 @@ def create_agent(  # noqa: PLR0915
         if response.structured_response is not None:
             state_updates["structured_response"] = response.structured_response
 
-        return {
-            "thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
-            "run_model_call_count": state.get("run_model_call_count", 0) + 1,
-            **state_updates,
-        }
+        return state_updates
 
     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)
@@ -1087,11 +1101,7 @@ def create_agent(  # noqa: PLR0915
         if response.structured_response is not None:
             state_updates["structured_response"] = response.structured_response
 
-        return {
-            "thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
-            "run_model_call_count": state.get("run_model_call_count", 0) + 1,
-            **state_updates,
-        }
+        return state_updates
 
     # Use sync or async based on model capabilities
     graph.add_node("model", RunnableCallable(model_node, amodel_node, trace=False))
@@ -1119,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
@@ -1138,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
@@ -1157,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
@@ -1176,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:
@@ -1209,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(
@@ -1217,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,
@@ -11,16 +17,17 @@ from .human_in_the_loop import (
 from .model_call_limit import ModelCallLimitMiddleware
 from .model_fallback import ModelFallbackMiddleware
 from .pii import PIIDetectionError, PIIMiddleware
-from .planning import PlanningMiddleware
-from .prompt_caching import AnthropicPromptCachingMiddleware
 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,
     AgentState,
     ModelRequest,
+    ModelResponse,
     after_agent,
     after_model,
     before_agent,
@@ -28,13 +35,12 @@ from .types import (
     dynamic_prompt,
     hook_config,
     wrap_model_call,
+    wrap_tool_call,
 )
 
 __all__ = [
     "AgentMiddleware",
     "AgentState",
-    # should move to langchain-anthropic if we decide to keep it
-    "AnthropicPromptCachingMiddleware",
     "ClearToolUsesEdit",
     "ContextEditingMiddleware",
     "HumanInTheLoopMiddleware",
@@ -44,11 +50,13 @@ __all__ = [
     "ModelCallLimitMiddleware",
     "ModelFallbackMiddleware",
     "ModelRequest",
+    "ModelResponse",
     "PIIDetectionError",
     "PIIMiddleware",
-    "PlanningMiddleware",
     "SummarizationMiddleware",
+    "TodoListMiddleware",
     "ToolCallLimitMiddleware",
+    "ToolRetryMiddleware",
     "after_agent",
     "after_model",
     "before_agent",
@@ -56,4 +64,5 @@ __all__ = [
     "dynamic_prompt",
     "hook_config",
     "wrap_model_call",
+    "wrap_tool_call",
 ]

langchain/agents/middleware/context_editing.py

@@ -8,7 +8,7 @@ with any LangChain chat model.
 
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable, Sequence
+from collections.abc import Awaitable, Callable, Iterable, Sequence
 from dataclasses import dataclass
 from typing import Literal
 
@@ -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
@@ -239,6 +239,34 @@ class ContextEditingMiddleware(AgentMiddleware):
 
         return handler(request)
 
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        """Apply context edits before invoking the model via handler (async version)."""
+        if not request.messages:
+            return await handler(request)
+
+        if self.token_count_method == "approximate":  # noqa: S105
+
+            def count_tokens(messages: Sequence[BaseMessage]) -> int:
+                return count_tokens_approximately(messages)
+        else:
+            system_msg = (
+                [SystemMessage(content=request.system_prompt)] if request.system_prompt else []
+            )
+
+            def count_tokens(messages: Sequence[BaseMessage]) -> int:
+                return request.model.get_num_tokens_from_messages(
+                    system_msg + list(messages), request.tools
+                )
+
+        for edit in self.edits:
+            edit.apply(request.messages, count_tokens=count_tokens)
+
+        return await handler(request)
+
 
 __all__ = [
     "ClearToolUsesEdit",

langchain/agents/middleware/human_in_the_loop.py

@@ -11,23 +11,23 @@ from langchain.agents.middleware.types import AgentMiddleware, AgentState
 
 
 class Action(TypedDict):
-    """Represents an action with a name and arguments."""
+    """Represents an action with a name and args."""
 
     name: str
     """The type or name of action being requested (e.g., "add_numbers")."""
 
-    arguments: dict[str, Any]
-    """Key-value pairs of arguments needed for the action (e.g., {"a": 1, "b": 2})."""
+    args: dict[str, Any]
+    """Key-value pairs of args needed for the action (e.g., {"a": 1, "b": 2})."""
 
 
 class ActionRequest(TypedDict):
-    """Represents an action request with a name, arguments, and description."""
+    """Represents an action request with a name, args, and description."""
 
     name: str
     """The name of the action being requested."""
 
-    arguments: dict[str, Any]
-    """Key-value pairs of arguments needed for the action (e.g., {"a": 1, "b": 2})."""
+    args: dict[str, Any]
+    """Key-value pairs of args needed for the action (e.g., {"a": 1, "b": 2})."""
 
     description: NotRequired[str]
     """The description of the action to be reviewed."""
@@ -45,8 +45,8 @@ class ReviewConfig(TypedDict):
     allowed_decisions: list[DecisionType]
     """The decisions that are allowed for this request."""
 
-    arguments_schema: NotRequired[dict[str, Any]]
-    """JSON schema for the arguments associated with the action, if edits are allowed."""
+    args_schema: NotRequired[dict[str, Any]]
+    """JSON schema for the args associated with the action, if edits are allowed."""
 
 
 class HITLRequest(TypedDict):
@@ -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
@@ -150,8 +152,8 @@ class InterruptOnConfig(TypedDict):
         )
         ```
     """
-    arguments_schema: NotRequired[dict[str, Any]]
-    """JSON schema for the arguments associated with the action, if edits are allowed."""
+    args_schema: NotRequired[dict[str, Any]]
+    """JSON schema for the args associated with the action, if edits are allowed."""
 
 
 class HumanInTheLoopMiddleware(AgentMiddleware):
@@ -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] = {}
@@ -214,12 +218,12 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
         # Create ActionRequest with description
         action_request = ActionRequest(
             name=tool_name,
-            arguments=tool_args,
+            args=tool_args,
             description=description,
         )
 
         # Create ReviewConfig
-        # eventually can get tool information and populate arguments_schema from there
+        # eventually can get tool information and populate args_schema from there
         review_config = ReviewConfig(
             action_name=tool_name,
             allowed_decisions=config["allowed_decisions"],
@@ -244,7 +248,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
                 ToolCall(
                     type="tool_call",
                     name=edited_action["name"],
-                    args=edited_action["arguments"],
+                    args=edited_action["args"],
                     id=tool_call["id"],
                 ),
                 None,
@@ -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