langchain 1.2.3__py3-none-any.whl → 1.2.4__py3-none-any.whl

langchain/agents/middleware/types.py

@@ -78,9 +78,10 @@ class _ModelRequestOverrides(TypedDict, total=False):
     system_message: SystemMessage | None
     messages: list[AnyMessage]
     tool_choice: Any | None
-    tools: list[BaseTool | dict]
-    response_format: ResponseFormat | None
+    tools: list[BaseTool | dict[str, Any]]
+    response_format: ResponseFormat[Any] | None
     model_settings: dict[str, Any]
+    state: AgentState[Any]
 
 
 @dataclass(init=False)
@@ -91,9 +92,9 @@ class ModelRequest:
     messages: list[AnyMessage]  # excluding system message
     system_message: SystemMessage | None
     tool_choice: Any | None
-    tools: list[BaseTool | dict]
-    response_format: ResponseFormat | None
-    state: AgentState
+    tools: list[BaseTool | dict[str, Any]]
+    response_format: ResponseFormat[Any] | None
+    state: AgentState[Any]
     runtime: Runtime[ContextT]  # type: ignore[valid-type]
     model_settings: dict[str, Any] = field(default_factory=dict)
 
@@ -105,9 +106,9 @@ class ModelRequest:
         system_message: SystemMessage | None = None,
         system_prompt: str | None = None,
         tool_choice: Any | None = None,
-        tools: list[BaseTool | dict] | None = None,
-        response_format: ResponseFormat | None = None,
-        state: AgentState | None = None,
+        tools: list[BaseTool | dict[str, Any]] | None = None,
+        response_format: ResponseFormat[Any] | None = None,
+        state: AgentState[Any] | None = None,
         runtime: Runtime[ContextT] | None = None,
         model_settings: dict[str, Any] | None = None,
     ) -> None:
@@ -124,6 +125,9 @@ class ModelRequest:
             model_settings: Additional model settings.
             system_message: System message instance (preferred).
             system_prompt: System prompt string (deprecated, converted to SystemMessage).
+
+        Raises:
+            ValueError: If both `system_prompt` and `system_message` are provided.
         """
         # Handle system_prompt/system_message conversion and validation
         if system_prompt is not None and system_message is not None:
@@ -210,6 +214,7 @@ class ModelRequest:
                 - `tools`: `list` of available tools
                 - `response_format`: Response format specification
                 - `model_settings`: Additional model settings
+                - `state`: Agent state dictionary
 
         Returns:
             New `ModelRequest` instance with specified overrides applied.
@@ -239,6 +244,9 @@ class ModelRequest:
                     system_message=SystemMessage(content="New instructions"),
                 )
                 ```
+
+        Raises:
+            ValueError: If both `system_prompt` and `system_message` are provided.
         """
         # Handle system_prompt/system_message conversion
         if "system_prompt" in overrides and "system_message" in overrides:
@@ -246,7 +254,7 @@ class ModelRequest:
             raise ValueError(msg)
 
         if "system_prompt" in overrides:
-            system_prompt = cast("str", overrides.pop("system_prompt"))  # type: ignore[typeddict-item]
+            system_prompt = cast("str | None", overrides.pop("system_prompt"))  # type: ignore[typeddict-item]
             if system_prompt is None:
                 overrides["system_message"] = None
             else:
@@ -313,7 +321,7 @@ class AgentState(TypedDict, Generic[ResponseT]):
 class _InputAgentState(TypedDict):  # noqa: PYI049
     """Input state schema for the agent."""
 
-    messages: Required[Annotated[list[AnyMessage | dict], add_messages]]
+    messages: Required[Annotated[list[AnyMessage | dict[str, Any]], add_messages]]
 
 
 class _OutputAgentState(TypedDict, Generic[ResponseT]):  # noqa: PYI049
@@ -323,9 +331,13 @@ class _OutputAgentState(TypedDict, Generic[ResponseT]):  # noqa: PYI049
     structured_response: NotRequired[ResponseT]
 
 
-StateT = TypeVar("StateT", bound=AgentState, default=AgentState)
-StateT_co = TypeVar("StateT_co", bound=AgentState, default=AgentState, covariant=True)
-StateT_contra = TypeVar("StateT_contra", bound=AgentState, contravariant=True)
+StateT = TypeVar("StateT", bound=AgentState[Any], default=AgentState[Any])
+StateT_co = TypeVar("StateT_co", bound=AgentState[Any], default=AgentState[Any], covariant=True)
+StateT_contra = TypeVar("StateT_contra", bound=AgentState[Any], contravariant=True)
+
+
+class _DefaultAgentState(AgentState[Any]):
+    """AgentMiddleware default state."""
 
 
 class AgentMiddleware(Generic[StateT, ContextT]):
@@ -335,7 +347,7 @@ class AgentMiddleware(Generic[StateT, ContextT]):
     between steps in the main agent loop.
     """
 
-    state_schema: type[StateT] = cast("type[StateT]", AgentState)
+    state_schema: type[StateT] = cast("type[StateT]", _DefaultAgentState)
     """The schema for state passed to the middleware nodes."""
 
     tools: Sequence[BaseTool]
@@ -352,35 +364,74 @@ class AgentMiddleware(Generic[StateT, ContextT]):
     def before_agent(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
         """Logic to run before the agent execution starts.
 
-        Async version is `abefore_agent`
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply before agent execution.
         """
 
     async def abefore_agent(
         self, state: StateT, runtime: Runtime[ContextT]
     ) -> dict[str, Any] | None:
-        """Async logic to run before the agent execution starts."""
+        """Async logic to run before the agent execution starts.
+
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply before agent execution.
+        """
 
     def before_model(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
         """Logic to run before the model is called.
 
-        Async version is `abefore_model`
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply before model call.
         """
 
     async def abefore_model(
         self, state: StateT, runtime: Runtime[ContextT]
     ) -> dict[str, Any] | None:
-        """Async logic to run before the model is called."""
+        """Async logic to run before the model is called.
+
+        Args:
+            state: The agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply before model call.
+        """
 
     def after_model(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
         """Logic to run after the model is called.
 
-        Async version is `aafter_model`
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply after model call.
         """
 
     async def aafter_model(
         self, state: StateT, runtime: Runtime[ContextT]
     ) -> dict[str, Any] | None:
-        """Async logic to run after the model is called."""
+        """Async logic to run after the model is called.
+
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply after model call.
+        """
 
     def wrap_model_call(
         self,
@@ -408,7 +459,7 @@ class AgentMiddleware(Generic[StateT, ContextT]):
                 Can skip calling it to short-circuit.
 
         Returns:
-            `ModelCallResult`
+            The model call result.
 
         Examples:
             !!! example "Retry on error"
@@ -502,7 +553,7 @@ class AgentMiddleware(Generic[StateT, ContextT]):
                 Can skip calling it to short-circuit.
 
         Returns:
-            `ModelCallResult`
+            The model call result.
 
         Examples:
             !!! example "Retry on error"
@@ -530,18 +581,34 @@ class AgentMiddleware(Generic[StateT, ContextT]):
         raise NotImplementedError(msg)
 
     def after_agent(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
-        """Logic to run after the agent execution completes."""
+        """Logic to run after the agent execution completes.
+
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply after agent execution.
+        """
 
     async def aafter_agent(
         self, state: StateT, runtime: Runtime[ContextT]
     ) -> dict[str, Any] | None:
-        """Async logic to run after the agent execution completes."""
+        """Async logic to run after the agent execution completes.
+
+        Args:
+            state: The current agent state.
+            runtime: The runtime context.
+
+        Returns:
+            Agent state updates to apply after agent execution.
+        """
 
     def wrap_tool_call(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
         """Intercept tool execution for retries, monitoring, or modification.
 
         Async version is `awrap_tool_call`
@@ -622,8 +689,8 @@ class AgentMiddleware(Generic[StateT, ContextT]):
     async def awrap_tool_call(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-    ) -> ToolMessage | Command:
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
+    ) -> ToolMessage | Command[Any]:
         """Intercept and control async tool execution via handler callback.
 
         The handler callback executes the tool call and returns a `ToolMessage` or
@@ -694,7 +761,7 @@ class _CallableWithStateAndRuntime(Protocol[StateT_contra, ContextT]):
 
     def __call__(
         self, state: StateT_contra, runtime: Runtime[ContextT]
-    ) -> dict[str, Any] | Command | None | Awaitable[dict[str, Any] | Command | None]:
+    ) -> dict[str, Any] | Command[Any] | None | Awaitable[dict[str, Any] | Command[Any] | None]:
         """Perform some logic with the state and runtime."""
         ...
 
@@ -735,8 +802,8 @@ class _CallableReturningToolResponse(Protocol):
     def __call__(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
         """Intercept tool execution via handler callback."""
         ...
 
@@ -918,7 +985,7 @@ def before_model(
                 _self: AgentMiddleware[StateT, ContextT],
                 state: StateT,
                 runtime: Runtime[ContextT],
-            ) -> dict[str, Any] | Command | None:
+            ) -> dict[str, Any] | Command[Any] | None:
                 return await func(state, runtime)  # type: ignore[misc]
 
             # Preserve can_jump_to metadata on the wrapped function
@@ -943,7 +1010,7 @@ def before_model(
             _self: AgentMiddleware[StateT, ContextT],
             state: StateT,
             runtime: Runtime[ContextT],
-        ) -> dict[str, Any] | Command | None:
+        ) -> dict[str, Any] | Command[Any] | None:
             return func(state, runtime)  # type: ignore[return-value]
 
         # Preserve can_jump_to metadata on the wrapped function
@@ -1078,7 +1145,7 @@ def after_model(
                 _self: AgentMiddleware[StateT, ContextT],
                 state: StateT,
                 runtime: Runtime[ContextT],
-            ) -> dict[str, Any] | Command | None:
+            ) -> dict[str, Any] | Command[Any] | None:
                 return await func(state, runtime)  # type: ignore[misc]
 
             # Preserve can_jump_to metadata on the wrapped function
@@ -1101,7 +1168,7 @@ def after_model(
             _self: AgentMiddleware[StateT, ContextT],
             state: StateT,
             runtime: Runtime[ContextT],
-        ) -> dict[str, Any] | Command | None:
+        ) -> dict[str, Any] | Command[Any] | None:
             return func(state, runtime)  # type: ignore[return-value]
 
         # Preserve can_jump_to metadata on the wrapped function
@@ -1269,7 +1336,7 @@ def before_agent(
                 _self: AgentMiddleware[StateT, ContextT],
                 state: StateT,
                 runtime: Runtime[ContextT],
-            ) -> dict[str, Any] | Command | None:
+            ) -> dict[str, Any] | Command[Any] | None:
                 return await func(state, runtime)  # type: ignore[misc]
 
             # Preserve can_jump_to metadata on the wrapped function
@@ -1294,7 +1361,7 @@ def before_agent(
             _self: AgentMiddleware[StateT, ContextT],
             state: StateT,
             runtime: Runtime[ContextT],
-        ) -> dict[str, Any] | Command | None:
+        ) -> dict[str, Any] | Command[Any] | None:
             return func(state, runtime)  # type: ignore[return-value]
 
         # Preserve can_jump_to metadata on the wrapped function
@@ -1430,7 +1497,7 @@ def after_agent(
                 _self: AgentMiddleware[StateT, ContextT],
                 state: StateT,
                 runtime: Runtime[ContextT],
-            ) -> dict[str, Any] | Command | None:
+            ) -> dict[str, Any] | Command[Any] | None:
                 return await func(state, runtime)  # type: ignore[misc]
 
             # Preserve can_jump_to metadata on the wrapped function
@@ -1453,7 +1520,7 @@ def after_agent(
             _self: AgentMiddleware[StateT, ContextT],
             state: StateT,
             runtime: Runtime[ContextT],
-        ) -> dict[str, Any] | Command | None:
+        ) -> dict[str, Any] | Command[Any] | None:
             return func(state, runtime)  # type: ignore[return-value]
 
         # Preserve can_jump_to metadata on the wrapped function
@@ -1901,8 +1968,8 @@ def wrap_tool_call(
             async def async_wrapped(
                 _self: AgentMiddleware,
                 request: ToolCallRequest,
-                handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-            ) -> ToolMessage | Command:
+                handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
+            ) -> ToolMessage | Command[Any]:
                 return await func(request, handler)  # type: ignore[arg-type,misc]
 
             middleware_name = name or cast(
@@ -1922,8 +1989,8 @@ def wrap_tool_call(
         def wrapped(
             _self: AgentMiddleware,
             request: ToolCallRequest,
-            handler: Callable[[ToolCallRequest], ToolMessage | Command],
-        ) -> ToolMessage | Command:
+            handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+        ) -> ToolMessage | Command[Any]:
             return func(request, handler)
 
         middleware_name = name or cast("str", getattr(func, "__name__", "WrapToolCallMiddleware"))

langchain/agents/structured_output.py

@@ -75,7 +75,7 @@ class StructuredOutputValidationError(StructuredOutputError):
 
 
 def _parse_with_schema(
-    schema: type[SchemaT] | dict, schema_kind: SchemaKind, data: dict[str, Any]
+    schema: type[SchemaT] | dict[str, Any], schema_kind: SchemaKind, data: dict[str, Any]
 ) -> Any:
     """Parse data using for any supported schema type.
 
@@ -106,21 +106,21 @@ def _parse_with_schema(
 class _SchemaSpec(Generic[SchemaT]):
     """Describes a structured output schema."""
 
-    schema: type[SchemaT]
+    schema: type[SchemaT] | dict[str, Any]
     """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.
 
-    If not provided, the name will be the model name or `"response_format"` if it's a
-    JSON schema.
+    If not provided, the name will be the class name for models/dataclasses/TypedDicts,
+    or the `title` field for JSON schemas. Falls back to a generated name if unavailable.
     """
 
     description: str
     """Custom description of the schema.
 
-    If not provided, provided will use the model's docstring.
+    If not provided, will use the model's docstring.
     """
 
     schema_kind: SchemaKind
@@ -134,13 +134,23 @@ class _SchemaSpec(Generic[SchemaT]):
 
     def __init__(
         self,
-        schema: type[SchemaT],
+        schema: type[SchemaT] | dict[str, Any],
         *,
         name: str | None = None,
         description: str | None = None,
         strict: bool | None = None,
     ) -> None:
-        """Initialize SchemaSpec with schema and optional parameters."""
+        """Initialize `SchemaSpec` with schema and optional parameters.
+
+        Args:
+            schema: Schema to describe.
+            name: Optional name for the schema.
+            description: Optional description for the schema.
+            strict: Whether to enforce strict validation of the schema.
+
+        Raises:
+            ValueError: If the schema type is unsupported.
+        """
         self.schema = schema
 
         if name:
@@ -182,10 +192,10 @@ class _SchemaSpec(Generic[SchemaT]):
 class ToolStrategy(Generic[SchemaT]):
     """Use a tool calling strategy for model responses."""
 
-    schema: type[SchemaT]
+    schema: type[SchemaT] | UnionType | dict[str, Any]
     """Schema for the tool calls."""
 
-    schema_specs: list[_SchemaSpec[SchemaT]]
+    schema_specs: list[_SchemaSpec[Any]]
     """Schema specs for the tool calls."""
 
     tool_message_content: str | None
@@ -208,7 +218,7 @@ class ToolStrategy(Generic[SchemaT]):
 
     def __init__(
         self,
-        schema: type[SchemaT],
+        schema: type[SchemaT] | UnionType | dict[str, Any],
         *,
         tool_message_content: str | None = None,
         handle_errors: bool
@@ -247,7 +257,7 @@ class ToolStrategy(Generic[SchemaT]):
 class ProviderStrategy(Generic[SchemaT]):
     """Use the model provider's native structured output method."""
 
-    schema: type[SchemaT]
+    schema: type[SchemaT] | dict[str, Any]
     """Schema for native mode."""
 
     schema_spec: _SchemaSpec[SchemaT]
@@ -255,7 +265,7 @@ class ProviderStrategy(Generic[SchemaT]):
 
     def __init__(
         self,
-        schema: type[SchemaT],
+        schema: type[SchemaT] | dict[str, Any],
         *,
         strict: bool | None = None,
     ) -> None:
@@ -269,7 +279,11 @@ class ProviderStrategy(Generic[SchemaT]):
         self.schema_spec = _SchemaSpec(schema, strict=strict)
 
     def to_model_kwargs(self) -> dict[str, Any]:
-        """Convert to kwargs to bind to a model to force structured output."""
+        """Convert to kwargs to bind to a model to force structured output.
+
+        Returns:
+            The kwargs to bind to a model.
+        """
         # OpenAI:
         # - see https://platform.openai.com/docs/guides/structured-outputs
         json_schema: dict[str, Any] = {
@@ -295,7 +309,7 @@ class OutputToolBinding(Generic[SchemaT]):
     and the corresponding tool implementation used by the tools strategy.
     """
 
-    schema: type[SchemaT]
+    schema: type[SchemaT] | dict[str, Any]
     """The original schema provided for structured output
     (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
 
@@ -349,7 +363,7 @@ class ProviderStrategyBinding(Generic[SchemaT]):
     its type classification, and parsing logic for provider-enforced JSON.
     """
 
-    schema: type[SchemaT]
+    schema: type[SchemaT] | dict[str, Any]
     """The original schema provided for structured output
     (Pydantic model, `dataclass`, `TypedDict`, or JSON schema dict)."""
 
@@ -399,7 +413,8 @@ class ProviderStrategyBinding(Generic[SchemaT]):
         # Parse according to schema
         return _parse_with_schema(self.schema, self.schema_kind, data)
 
-    def _extract_text_content_from_message(self, message: AIMessage) -> str:
+    @staticmethod
+    def _extract_text_content_from_message(message: AIMessage) -> str:
         """Extract text content from an AIMessage.
 
         Args:
@@ -411,29 +426,27 @@ class ProviderStrategyBinding(Generic[SchemaT]):
         content = message.content
         if isinstance(content, str):
             return content
-        if isinstance(content, list):
-            parts: list[str] = []
-            for c in content:
-                if isinstance(c, dict):
-                    if c.get("type") == "text" and "text" in c:
-                        parts.append(str(c["text"]))
-                    elif "content" in c and isinstance(c["content"], str):
-                        parts.append(c["content"])
-                else:
-                    parts.append(str(c))
-            return "".join(parts)
-        return str(content)
+        parts: list[str] = []
+        for c in content:
+            if isinstance(c, dict):
+                if c.get("type") == "text" and "text" in c:
+                    parts.append(str(c["text"]))
+                elif "content" in c and isinstance(c["content"], str):
+                    parts.append(c["content"])
+            else:
+                parts.append(str(c))
+        return "".join(parts)
 
 
 class AutoStrategy(Generic[SchemaT]):
     """Automatically select the best strategy for structured output."""
 
-    schema: type[SchemaT]
+    schema: type[SchemaT] | dict[str, Any]
     """Schema for automatic mode."""
 
     def __init__(
         self,
-        schema: type[SchemaT],
+        schema: type[SchemaT] | dict[str, Any],
     ) -> None:
         """Initialize AutoStrategy with schema."""
         self.schema = schema