langchain 1.0.0a3__py3-none-any.whl → 1.0.0a5__py3-none-any.whl

langchain/agents/react_agent.py

@@ -1,3 +1,5 @@
+"""React agent implementation."""
+
 from __future__ import annotations
 
 import inspect
@@ -9,7 +11,6 @@ from typing import (
     Any,
     Generic,
     Literal,
-    Union,
     cast,
     get_type_hints,
 )
@@ -43,6 +44,7 @@ from langgraph.typing import ContextT, StateT
 from pydantic import BaseModel
 from typing_extensions import NotRequired, TypedDict, TypeVar
 
+from langchain.agents.middleware_agent import create_agent as create_middleware_agent
 from langchain.agents.structured_output import (
     MultipleStructuredOutputsError,
     OutputToolBinding,
@@ -64,6 +66,7 @@ if TYPE_CHECKING:
     from langchain.agents._internal._typing import (
         SyncOrAsync,
     )
+    from langchain.agents.types import AgentMiddleware
 
 StructuredResponseT = TypeVar("StructuredResponseT", default=None)
 
@@ -100,12 +103,12 @@ class AgentStateWithStructuredResponsePydantic(AgentStatePydantic, Generic[Struc
 
 PROMPT_RUNNABLE_NAME = "Prompt"
 
-Prompt = Union[
-    SystemMessage,
-    str,
-    Callable[[StateT], LanguageModelInput],
-    Runnable[StateT, LanguageModelInput],
-]
+Prompt = (
+    SystemMessage
+    | str
+    | Callable[[StateT], LanguageModelInput]
+    | Runnable[StateT, LanguageModelInput]
+)
 
 
 def _get_state_value(state: StateT, key: str, default: Any = None) -> Any:
@@ -173,8 +176,9 @@ def _validate_chat_history(
     error_message = create_error_message(
         message="Found AIMessages with tool_calls that do not have a corresponding ToolMessage. "
         f"Here are the first few of those tool calls: {tool_calls_without_results[:3]}.\n\n"
-        "Every tool call (LLM requesting to call a tool) in the message history MUST have a corresponding ToolMessage "
-        "(result of a tool invocation to return to the LLM) - this is required by most LLM providers.",
+        "Every tool call (LLM requesting to call a tool) in the message history "
+        "MUST have a corresponding ToolMessage (result of a tool invocation to return to the LLM) -"
+        " this is required by most LLM providers.",
         error_code=ErrorCode.INVALID_CHAT_HISTORY,
     )
     raise ValueError(error_message)
@@ -185,12 +189,8 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
 
     def __init__(
         self,
-        model: Union[
-            str,
-            BaseChatModel,
-            SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],
-        ],
-        tools: Union[Sequence[Union[BaseTool, Callable, dict[str, Any]]], ToolNode],
+        model: str | BaseChatModel | SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],
+        tools: Sequence[BaseTool | Callable | dict[str, Any]] | ToolNode,
         *,
         prompt: Prompt | None = None,
         response_format: ResponseFormat[StructuredResponseT] | None = None,
@@ -217,7 +217,8 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
         if isinstance(model, Runnable) and not isinstance(model, BaseChatModel):
             msg = (
                 "Expected `model` to be a BaseChatModel or a string, got {type(model)}."
-                "The `model` parameter should not have pre-bound tools, simply pass the model and tools separately."
+                "The `model` parameter should not have pre-bound tools, "
+                "simply pass the model and tools separately."
             )
             raise ValueError(msg)
 
@@ -309,7 +310,8 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
             Command with structured response update if found, None otherwise
 
         Raises:
-            MultipleStructuredOutputsError: If multiple structured responses are returned and error handling is disabled
+            MultipleStructuredOutputsError: If multiple structured responses are returned
+                and error handling is disabled
             StructuredOutputParsingError: If parsing fails and error handling is disabled
         """
         if not isinstance(self.response_format, ToolStrategy) or not response.tool_calls:
@@ -453,7 +455,11 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
         return model.bind(**kwargs)
 
     def _handle_structured_response_native(self, response: AIMessage) -> Command | None:
-        """If native output is configured and there are no tool calls, parse using ProviderStrategyBinding."""
+        """Handle structured output using the native output.
+
+        If native output is configured and there are no tool calls,
+        parse using ProviderStrategyBinding.
+        """
         if self.native_output_binding is None:
             return None
         if response.tool_calls:
@@ -687,10 +693,10 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
             return CallModelInputSchema
         return self._final_state_schema
 
-    def create_model_router(self) -> Callable[[StateT], Union[str, list[Send]]]:
+    def create_model_router(self) -> Callable[[StateT], str | list[Send]]:
         """Create routing function for model node conditional edges."""
 
-        def should_continue(state: StateT) -> Union[str, list[Send]]:
+        def should_continue(state: StateT) -> str | list[Send]:
             messages = _get_state_value(state, "messages")
             last_message = messages[-1]
 
@@ -727,10 +733,10 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
 
     def create_post_model_hook_router(
         self,
-    ) -> Callable[[StateT], Union[str, list[Send]]]:
+    ) -> Callable[[StateT], str | list[Send]]:
         """Create a routing function for post_model_hook node conditional edges."""
 
-        def post_model_hook_router(state: StateT) -> Union[str, list[Send]]:
+        def post_model_hook_router(state: StateT) -> str | list[Send]:
             messages = _get_state_value(state, "messages")
 
             # Check if the last message is a ToolMessage from a structured tool.
@@ -878,7 +884,7 @@ class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):
 
 
 def _supports_native_structured_output(
-    model: Union[str, BaseChatModel, SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel]],
+    model: str | BaseChatModel | SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],
 ) -> bool:
     """Check if a model supports native structured output.
 
@@ -899,19 +905,14 @@ def _supports_native_structured_output(
 
 
 def create_agent(  # noqa: D417
-    model: Union[
-        str,
-        BaseChatModel,
-        SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],
-    ],
-    tools: Union[Sequence[Union[BaseTool, Callable, dict[str, Any]]], ToolNode],
+    model: str | BaseChatModel | SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],
+    tools: Sequence[BaseTool | Callable | dict[str, Any]] | ToolNode,
     *,
+    middleware: Sequence[AgentMiddleware] = (),
     prompt: Prompt | None = None,
-    response_format: Union[
-        ToolStrategy[StructuredResponseT],
-        ProviderStrategy[StructuredResponseT],
-        type[StructuredResponseT],
-    ]
+    response_format: ToolStrategy[StructuredResponseT]
+    | ProviderStrategy[StructuredResponseT]
+    | type[StructuredResponseT]
     | None = None,
     pre_model_hook: RunnableLike | None = None,
     post_model_hook: RunnableLike | None = None,
@@ -928,7 +929,8 @@ def create_agent(  # noqa: D417
 ) -> CompiledStateGraph[StateT, ContextT]:
     """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://langchain-ai.github.io/langgraph/agents/overview/) documentation.
+    For more details on using `create_agent`,
+    visit [Agents](https://langchain-ai.github.io/langgraph/agents/overview/) documentation.
 
     Args:
         model: The language model for the agent. Supports static and dynamic
@@ -952,14 +954,17 @@ def create_agent(  # noqa: D417
             ```python
             from dataclasses import dataclass
 
+
             @dataclass
             class ModelContext:
                 model_name: str = "gpt-3.5-turbo"
 
+
             # Instantiate models globally
             gpt4_model = ChatOpenAI(model="gpt-4")
             gpt35_model = ChatOpenAI(model="gpt-3.5-turbo")
 
+
             def select_model(state: AgentState, runtime: Runtime[ModelContext]) -> ChatOpenAI:
                 model_name = runtime.context.model_name
                 model = gpt4_model if model_name == "gpt-4" else gpt35_model
@@ -972,25 +977,35 @@ def create_agent(  # noqa: D417
                 must be a subset of those specified in the `tools` parameter.
 
         tools: A list of tools or a ToolNode instance.
-            If an empty list is provided, the agent will consist of a single LLM node without tool calling.
+            If an empty list is provided, the agent will consist of a single LLM node
+            without tool calling.
         prompt: An optional prompt for the LLM. Can take a few different forms:
 
-            - str: This is converted to a SystemMessage and added to the beginning of the list of messages in state["messages"].
-            - SystemMessage: this is added to the beginning of the list of messages in state["messages"].
-            - Callable: This function should take in full graph state and the output is then passed to the language model.
-            - Runnable: This runnable should take in full graph state and the output is then passed to the language model.
+            - str: This is converted to a SystemMessage and added to the beginning
+              of the list of messages in state["messages"].
+            - SystemMessage: this is added to the beginning of the list of messages
+              in state["messages"].
+            - Callable: This function should take in full graph state and the output is then passed
+              to the language model.
+            - Runnable: This runnable should take in full graph state and the output is then passed
+              to the language model.
 
         response_format: An optional UsingToolStrategy configuration for structured responses.
 
-            If provided, the agent will handle structured output via tool calls during the normal conversation flow.
-            When the model calls a structured output tool, the response will be captured and returned in the 'structured_response' state key.
+            If provided, the agent will handle structured output via tool calls
+            during the normal conversation flow.
+            When the model calls a structured output tool, the response will be captured
+            and returned in the 'structured_response' state key.
             If not provided, `structured_response` will not be present in the output state.
 
             The UsingToolStrategy should contain:
-                - schemas: A sequence of ResponseSchema objects that define the structured output format
+
+                - schemas: A sequence of ResponseSchema objects that define
+                  the structured output format
                 - tool_choice: Either "required" or "auto" to control when structured output is used
 
             Each ResponseSchema contains:
+
                 - schema: A Pydantic model that defines the structure
                 - name: Optional custom name for the tool (defaults to model name)
                 - description: Optional custom description (defaults to model docstring)
@@ -1000,11 +1015,15 @@ def create_agent(  # noqa: D417
                 `response_format` requires the model to support tool calling
 
             !!! Note
-                Structured responses are handled directly in the model call node via tool calls, eliminating the need for separate structured response nodes.
-
-        pre_model_hook: An optional node to add before the `agent` node (i.e., the node that calls the LLM).
-            Useful for managing long message histories (e.g., message trimming, summarization, etc.).
-            Pre-model hook must be a callable or a runnable that takes in current graph state and returns a state update in the form of
+                Structured responses are handled directly in the model call node via tool calls,
+                eliminating the need for separate structured response nodes.
+
+        pre_model_hook: An optional node to add before the `agent` node
+            (i.e., the node that calls the LLM).
+            Useful for managing long message histories
+            (e.g., message trimming, summarization, etc.).
+            Pre-model hook must be a callable or a runnable that takes in current
+            graph state and returns a state update in the form of
                 ```python
                 # At least one of `messages` or `llm_input_messages` MUST be provided
                 {
@@ -1019,11 +1038,13 @@ def create_agent(  # noqa: D417
                 ```
 
             !!! Important
-                At least one of `messages` or `llm_input_messages` MUST be provided and will be used as an input to the `agent` node.
+                At least one of `messages` or `llm_input_messages` MUST be provided
+                and will be used as an input to the `agent` node.
                 The rest of the keys will be added to the graph state.
 
             !!! Warning
-                If you are returning `messages` in the pre-model hook, you should OVERWRITE the `messages` key by doing the following:
+                If you are returning `messages` in the pre-model hook,
+                you should OVERWRITE the `messages` key by doing the following:
 
                 ```python
                 {
@@ -1031,9 +1052,12 @@ def create_agent(  # noqa: D417
                     ...
                 }
                 ```
-        post_model_hook: An optional node to add after the `agent` node (i.e., the node that calls the LLM).
-            Useful for implementing human-in-the-loop, guardrails, validation, or other post-processing.
-            Post-model hook must be a callable or a runnable that takes in current graph state and returns a state update.
+        post_model_hook: An optional node to add after the `agent` node
+            (i.e., the node that calls the LLM).
+            Useful for implementing human-in-the-loop, guardrails, validation,
+            or other post-processing.
+            Post-model hook must be a callable or a runnable that takes in
+            current graph state and returns a state update.
 
             !!! Note
                 Only available with `version="v2"`.
@@ -1042,12 +1066,14 @@ def create_agent(  # noqa: D417
             Defaults to `AgentState` that defines those two keys.
         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 (e.g., a single conversation).
+            the state of the graph (e.g., as chat memory) for a single thread
+            (e.g., a single conversation).
         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.
             Should be one of the following: "agent", "tools".
-            This is useful if you want to add a user confirmation or other interrupt before taking an action.
+            This is 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.
             Should be one of the following: "agent", "tools".
             This is useful if you want to return directly or run additional processing on an output.
@@ -1062,7 +1088,8 @@ def create_agent(  # noqa: D417
                 node using the [Send](https://langchain-ai.github.io/langgraph/concepts/low_level/#send)
                 API.
         name: An optional name for the CompiledStateGraph.
-            This name will be automatically used when adding ReAct agent graph to another graph as a subgraph node -
+            This name will be automatically used when adding ReAct agent graph to
+            another graph as a subgraph node -
             particularly useful for building multi-agent systems.
 
     !!! warning "`config_schema` Deprecated"
@@ -1074,9 +1101,11 @@ def create_agent(  # noqa: D417
         A compiled LangChain runnable that can be used for chat interactions.
 
     The "agent" node calls the language model with the messages list (after applying the prompt).
-    If the resulting AIMessage contains `tool_calls`, the graph will then call the ["tools"][langgraph.prebuilt.tool_node.ToolNode].
-    The "tools" node executes the tools (1 tool per `tool_call`) and adds the responses to the messages list
-    as `ToolMessage` objects. The agent node then calls the language model again.
+    If the resulting AIMessage contains `tool_calls`,
+    the graph will then call the ["tools"][langgraph.prebuilt.tool_node.ToolNode].
+    The "tools" node executes the tools (1 tool per `tool_call`)
+    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 as a dictionary containing the key "messages".
 
@@ -1112,10 +1141,34 @@ def create_agent(  # noqa: D417
             print(chunk)
         ```
     """
+    if middleware:
+        assert isinstance(model, str | BaseChatModel)  # noqa: S101
+        assert isinstance(prompt, str | None)  # noqa: S101
+        assert not isinstance(response_format, tuple)  # noqa: S101
+        assert pre_model_hook is None  # noqa: S101
+        assert post_model_hook is None  # noqa: S101
+        assert state_schema is None  # noqa: S101
+        return create_middleware_agent(  # type: ignore[return-value]
+            model=model,
+            tools=tools,
+            system_prompt=prompt,
+            middleware=middleware,
+            response_format=response_format,
+            context_schema=context_schema,
+        ).compile(
+            checkpointer=checkpointer,
+            store=store,
+            name=name,
+            interrupt_after=interrupt_after,
+            interrupt_before=interrupt_before,
+            debug=debug,
+        )
+
     # Handle deprecated config_schema parameter
     if (config_schema := deprecated_kwargs.pop("config_schema", MISSING)) is not MISSING:
         warn(
-            "`config_schema` is deprecated and will be removed. Please use `context_schema` instead.",
+            "`config_schema` is deprecated and will be removed. "
+            "Please use `context_schema` instead.",
             category=DeprecationWarning,
             stacklevel=2,
         )
@@ -1144,7 +1197,7 @@ def create_agent(  # noqa: D417
         model=model,
         tools=tools,
         prompt=prompt,
-        response_format=cast("Union[ResponseFormat[StructuredResponseT], None]", response_format),
+        response_format=cast("ResponseFormat[StructuredResponseT] | None", response_format),
         pre_model_hook=pre_model_hook,
         post_model_hook=post_model_hook,
         state_schema=state_schema,

langchain/agents/structured_output.py

@@ -47,7 +47,8 @@ class MultipleStructuredOutputsError(StructuredOutputError):
         self.tool_names = tool_names
 
         super().__init__(
-            f"Model incorrectly returned multiple structured responses ({', '.join(tool_names)}) when only one is expected."
+            "Model incorrectly returned multiple structured responses "
+            f"({', '.join(tool_names)}) when only one is expected."
         )
 
 
@@ -67,7 +68,7 @@ class StructuredOutputValidationError(StructuredOutputError):
 
 
 def _parse_with_schema(
-    schema: Union[type[SchemaT], dict], schema_kind: SchemaKind, data: dict[str, Any]
+    schema: type[SchemaT] | dict, schema_kind: SchemaKind, data: dict[str, Any]
 ) -> Any:
     """Parse data using for any supported schema type.
 
@@ -98,7 +99,8 @@ class _SchemaSpec(Generic[SchemaT]):
     """Describes a structured output schema."""
 
     schema: type[SchemaT]
-    """The schema for the response, can be a Pydantic model, dataclass, TypedDict, or JSON schema dict."""
+    """The schema for the response, can be a Pydantic model, dataclass, TypedDict,
+    or JSON schema dict."""
 
     name: str
     """Name of the schema, used for tool calling.
@@ -178,15 +180,12 @@ class ToolStrategy(Generic[SchemaT]):
     """Schema specs for the tool calls."""
 
     tool_message_content: str | None
-    """The content of the tool message to be returned when the model calls an artificial structured output tool."""
-
-    handle_errors: Union[
-        bool,
-        str,
-        type[Exception],
-        tuple[type[Exception], ...],
-        Callable[[Exception], str],
-    ]
+    """The content of the tool message to be returned when the model calls
+    an artificial structured output tool."""
+
+    handle_errors: (
+        bool | str | type[Exception] | tuple[type[Exception], ...] | Callable[[Exception], str]
+    )
     """Error handling strategy for structured output via ToolStrategy. Default is True.
 
     - True: Catch all errors with default error template
@@ -202,15 +201,16 @@ class ToolStrategy(Generic[SchemaT]):
         schema: type[SchemaT],
         *,
         tool_message_content: str | None = None,
-        handle_errors: Union[
-            bool,
-            str,
-            type[Exception],
-            tuple[type[Exception], ...],
-            Callable[[Exception], str],
-        ] = True,
+        handle_errors: bool
+        | str
+        | type[Exception]
+        | tuple[type[Exception], ...]
+        | Callable[[Exception], str] = True,
     ) -> None:
-        """Initialize ToolStrategy with schemas, tool message content, and error handling strategy."""
+        """Initialize ToolStrategy.
+
+        Initialize ToolStrategy with schemas, tool message content, and error handling strategy.
+        """
         self.schema = schema
         self.tool_message_content = tool_message_content
         self.handle_errors = handle_errors
@@ -274,7 +274,8 @@ class OutputToolBinding(Generic[SchemaT]):
     """
 
     schema: type[SchemaT]
-    """The original schema provided for structured output (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
+    """The original schema provided for structured output
+    (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
 
     schema_kind: SchemaKind
     """Classification of the schema type for proper response construction."""
@@ -327,7 +328,8 @@ class ProviderStrategyBinding(Generic[SchemaT]):
     """
 
     schema: type[SchemaT]
-    """The original schema provided for structured output (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
+    """The original schema provided for structured output
+    (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
 
     schema_kind: SchemaKind
     """Classification of the schema type for proper response construction."""
@@ -368,7 +370,10 @@ class ProviderStrategyBinding(Generic[SchemaT]):
             data = json.loads(raw_text)
         except Exception as e:
             schema_name = getattr(self.schema, "__name__", "response_format")
-            msg = f"Native structured output expected valid JSON for {schema_name}, but parsing failed: {e}."
+            msg = (
+                f"Native structured output expected valid JSON for {schema_name}, "
+                f"but parsing failed: {e}."
+            )
             raise ValueError(msg) from e
 
         # Parse according to schema
@@ -400,4 +405,4 @@ class ProviderStrategyBinding(Generic[SchemaT]):
         return str(content)
 
 
-ResponseFormat = Union[ToolStrategy[SchemaT], ProviderStrategy[SchemaT]]
+ResponseFormat = ToolStrategy[SchemaT] | ProviderStrategy[SchemaT]