langchain 1.0.0a9__py3-none-any.whl → 1.0.0a11__py3-none-any.whl

langchain/agents/middleware/__init__.py

@@ -1,16 +1,53 @@
 """Middleware plugins for agents."""
 
+from .context_editing import (
+    ClearToolUsesEdit,
+    ContextEditingMiddleware,
+)
 from .human_in_the_loop import HumanInTheLoopMiddleware
+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 .types import AgentMiddleware, AgentState, ModelRequest
+from .tool_call_limit import ToolCallLimitMiddleware
+from .tool_selection import LLMToolSelectorMiddleware
+from .types import (
+    AgentMiddleware,
+    AgentState,
+    ModelRequest,
+    after_agent,
+    after_model,
+    before_agent,
+    before_model,
+    dynamic_prompt,
+    hook_config,
+    modify_model_request,
+)
 
 __all__ = [
     "AgentMiddleware",
     "AgentState",
     # should move to langchain-anthropic if we decide to keep it
     "AnthropicPromptCachingMiddleware",
+    "ClearToolUsesEdit",
+    "ContextEditingMiddleware",
     "HumanInTheLoopMiddleware",
+    "LLMToolSelectorMiddleware",
+    "ModelCallLimitMiddleware",
+    "ModelFallbackMiddleware",
     "ModelRequest",
+    "PIIDetectionError",
+    "PIIMiddleware",
+    "PlanningMiddleware",
     "SummarizationMiddleware",
+    "ToolCallLimitMiddleware",
+    "after_agent",
+    "after_model",
+    "before_agent",
+    "before_model",
+    "dynamic_prompt",
+    "hook_config",
+    "modify_model_request",
 ]

langchain/agents/middleware/context_editing.py

@@ -0,0 +1,245 @@
+"""Context editing middleware.
+
+This middleware mirrors Anthropic's context editing capabilities by clearing
+older tool results once the conversation grows beyond a configurable token
+threshold. The implementation is intentionally model-agnostic so it can be used
+with any LangChain chat model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from langchain_core.messages import (
+    AIMessage,
+    AnyMessage,
+    BaseMessage,
+    SystemMessage,
+    ToolMessage,
+)
+from langchain_core.messages.utils import count_tokens_approximately
+from typing_extensions import Protocol
+
+from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+
+if TYPE_CHECKING:
+    from langgraph.runtime import Runtime
+
+DEFAULT_TOOL_PLACEHOLDER = "[cleared]"
+
+
+TokenCounter = Callable[
+    [Sequence[BaseMessage]],
+    int,
+]
+
+
+class ContextEdit(Protocol):
+    """Protocol describing a context editing strategy."""
+
+    def apply(
+        self,
+        messages: list[AnyMessage],
+        *,
+        count_tokens: TokenCounter,
+    ) -> None:
+        """Apply an edit to the message list in place."""
+        ...
+
+
+@dataclass(slots=True)
+class ClearToolUsesEdit(ContextEdit):
+    """Configuration for clearing tool outputs when token limits are exceeded."""
+
+    trigger: int = 100_000
+    """Token count that triggers the edit."""
+
+    clear_at_least: int = 0
+    """Minimum number of tokens to reclaim when the edit runs."""
+
+    keep: int = 3
+    """Number of most recent tool results that must be preserved."""
+
+    clear_tool_inputs: bool = False
+    """Whether to clear the originating tool call parameters on the AI message."""
+
+    exclude_tools: Sequence[str] = ()
+    """List of tool names to exclude from clearing."""
+
+    placeholder: str = DEFAULT_TOOL_PLACEHOLDER
+    """Placeholder text inserted for cleared tool outputs."""
+
+    def apply(
+        self,
+        messages: list[AnyMessage],
+        *,
+        count_tokens: TokenCounter,
+    ) -> None:
+        """Apply the clear-tool-uses strategy."""
+        tokens = count_tokens(messages)
+
+        if tokens <= self.trigger:
+            return
+
+        candidates = [
+            (idx, msg) for idx, msg in enumerate(messages) if isinstance(msg, ToolMessage)
+        ]
+
+        if self.keep >= len(candidates):
+            candidates = []
+        elif self.keep:
+            candidates = candidates[: -self.keep]
+
+        cleared_tokens = 0
+        excluded_tools = set(self.exclude_tools)
+
+        for idx, tool_message in candidates:
+            if tool_message.response_metadata.get("context_editing", {}).get("cleared"):
+                continue
+
+            ai_message = next(
+                (m for m in reversed(messages[:idx]) if isinstance(m, AIMessage)), None
+            )
+
+            if ai_message is None:
+                continue
+
+            tool_call = next(
+                (
+                    call
+                    for call in ai_message.tool_calls
+                    if call.get("id") == tool_message.tool_call_id
+                ),
+                None,
+            )
+
+            if tool_call is None:
+                continue
+
+            if (tool_message.name or tool_call["name"]) in excluded_tools:
+                continue
+
+            messages[idx] = tool_message.model_copy(
+                update={
+                    "artifact": None,
+                    "content": self.placeholder,
+                    "response_metadata": {
+                        **tool_message.response_metadata,
+                        "context_editing": {
+                            "cleared": True,
+                            "strategy": "clear_tool_uses",
+                        },
+                    },
+                }
+            )
+
+            if self.clear_tool_inputs:
+                messages[messages.index(ai_message)] = self._build_cleared_tool_input_message(
+                    ai_message,
+                    tool_message.tool_call_id,
+                )
+
+            if self.clear_at_least > 0:
+                new_token_count = count_tokens(messages)
+                cleared_tokens = max(0, tokens - new_token_count)
+                if cleared_tokens >= self.clear_at_least:
+                    break
+
+        return
+
+    def _build_cleared_tool_input_message(
+        self,
+        message: AIMessage,
+        tool_call_id: str,
+    ) -> AIMessage:
+        updated_tool_calls = []
+        cleared_any = False
+        for tool_call in message.tool_calls:
+            updated_call = dict(tool_call)
+            if updated_call.get("id") == tool_call_id:
+                updated_call["args"] = {}
+                cleared_any = True
+            updated_tool_calls.append(updated_call)
+
+        metadata = dict(getattr(message, "response_metadata", {}))
+        context_entry = dict(metadata.get("context_editing", {}))
+        if cleared_any:
+            cleared_ids = set(context_entry.get("cleared_tool_inputs", []))
+            cleared_ids.add(tool_call_id)
+            context_entry["cleared_tool_inputs"] = sorted(cleared_ids)
+            metadata["context_editing"] = context_entry
+
+        return message.model_copy(
+            update={
+                "tool_calls": updated_tool_calls,
+                "response_metadata": metadata,
+            }
+        )
+
+
+class ContextEditingMiddleware(AgentMiddleware):
+    """Middleware that automatically prunes tool results to manage context size.
+
+    The middleware applies a sequence of edits when the total input token count
+    exceeds configured thresholds. Currently the ``ClearToolUsesEdit`` strategy is
+    supported, aligning with Anthropic's ``clear_tool_uses_20250919`` behaviour.
+    """
+
+    edits: list[ContextEdit]
+    token_count_method: Literal["approximate", "model"]
+
+    def __init__(
+        self,
+        *,
+        edits: Iterable[ContextEdit] | None = None,
+        token_count_method: Literal["approximate", "model"] = "approximate",  # noqa: S107
+    ) -> None:
+        """Initialise a context editing middleware instance.
+
+        Args:
+            edits: Sequence of edit strategies to apply. Defaults to a single
+                `ClearToolUsesEdit` mirroring Anthropic defaults.
+            token_count_method: Whether to use approximate token counting
+                (faster, less accurate) or exact counting implemented by the
+                chat model (potentially slower, more accurate).
+        """
+        super().__init__()
+        self.edits = list(edits or (ClearToolUsesEdit(),))
+        self.token_count_method = token_count_method
+
+    def modify_model_request(
+        self,
+        request: ModelRequest,
+        state: AgentState,  # noqa: ARG002
+        runtime: Runtime,  # noqa: ARG002
+    ) -> ModelRequest:
+        """Modify the model request by applying context edits before invocation."""
+        if not request.messages:
+            return 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 request
+
+
+__all__ = [
+    "ClearToolUsesEdit",
+    "ContextEditingMiddleware",
+]

langchain/agents/middleware/human_in_the_loop.py

@@ -1,8 +1,9 @@
 """Human in the loop middleware."""
 
-from typing import Any, Literal
+from typing import Any, Literal, Protocol
 
 from langchain_core.messages import AIMessage, ToolCall, ToolMessage
+from langgraph.runtime import Runtime
 from langgraph.types import interrupt
 from typing_extensions import NotRequired, TypedDict
 
@@ -94,6 +95,14 @@ HumanInTheLoopResponse = AcceptPayload | ResponsePayload | EditPayload
 """Aggregated response type for all possible human in the loop responses."""
 
 
+class _DescriptionFactory(Protocol):
+    """Callable that generates a description for a tool call."""
+
+    def __call__(self, tool_call: ToolCall, state: AgentState, runtime: Runtime) -> str:
+        """Generate a description for a tool call."""
+        ...
+
+
 class ToolConfig(TypedDict):
     """Configuration for a tool requiring human in the loop."""
 
@@ -103,8 +112,40 @@ class ToolConfig(TypedDict):
     """Whether the human can approve the current action with edited content."""
     allow_respond: NotRequired[bool]
     """Whether the human can reject the current action with feedback."""
-    description: NotRequired[str]
-    """The description attached to the request for human input."""
+    description: NotRequired[str | _DescriptionFactory]
+    """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
+
+    Example:
+        .. code-block:: python
+
+            # Static string description
+            config = ToolConfig(
+                allow_accept=True,
+                description="Please review this tool execution"
+            )
+
+            # Dynamic callable description
+            def format_tool_description(
+                tool_call: ToolCall,
+                state: AgentState,
+                runtime: Runtime
+            ) -> str:
+                import json
+                return (
+                    f"Tool: {tool_call['name']}\\n"
+                    f"Arguments:\\n{json.dumps(tool_call['args'], indent=2)}"
+                )
+
+            config = ToolConfig(
+                allow_accept=True,
+                description=format_tool_description
+            )
+    """
 
 
 class HumanInTheLoopMiddleware(AgentMiddleware):
@@ -121,12 +162,15 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
         Args:
             interrupt_on: Mapping of tool name to allowed actions.
                 If a tool doesn't have an entry, it's auto-approved by default.
-                * `True` indicates all actions are allowed: accept, edit, and respond.
-                * `False` indicates that the tool is auto-approved.
-                * ToolConfig indicates the specific actions allowed for this tool.
+
+                * ``True`` indicates all actions are allowed: accept, edit, and respond.
+                * ``False`` indicates that the tool is auto-approved.
+                * ``ToolConfig`` indicates the specific actions allowed for this tool.
+                  The ToolConfig 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 ToolConfig.
+                Not used if a tool has a ``description`` in its ToolConfig.
         """
         super().__init__()
         resolved_tool_configs: dict[str, ToolConfig] = {}
@@ -145,7 +189,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
         self.interrupt_on = resolved_tool_configs
         self.description_prefix = description_prefix
 
-    def after_model(self, state: AgentState) -> dict[str, Any] | None:  # type: ignore[override]
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
         """Trigger interrupt flows for relevant tool calls after an AIMessage."""
         messages = state["messages"]
         if not messages:
@@ -169,7 +213,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
             return None
 
         # Process all tool calls that require interrupts
-        approved_tool_calls: list[ToolCall] = auto_approved_tool_calls.copy()
+        revised_tool_calls: list[ToolCall] = auto_approved_tool_calls.copy()
         artificial_tool_messages: list[ToolMessage] = []
 
         # Create interrupt requests for all tools that need approval
@@ -178,10 +222,15 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
             tool_name = tool_call["name"]
             tool_args = tool_call["args"]
             config = self.interrupt_on[tool_name]
-            description = (
-                config.get("description")
-                or f"{self.description_prefix}\n\nTool: {tool_name}\nArgs: {tool_args}"
-            )
+
+            # Generate description using the description field (str or callable)
+            description_value = config.get("description")
+            if callable(description_value):
+                description = description_value(tool_call, state, runtime)
+            elif description_value is not None:
+                description = description_value
+            else:
+                description = f"{self.description_prefix}\n\nTool: {tool_name}\nArgs: {tool_args}"
 
             request: HumanInTheLoopRequest = {
                 "action_request": ActionRequest(
@@ -210,10 +259,10 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
             config = self.interrupt_on[tool_call["name"]]
 
             if response["type"] == "accept" and config.get("allow_accept"):
-                approved_tool_calls.append(tool_call)
+                revised_tool_calls.append(tool_call)
             elif response["type"] == "edit" and config.get("allow_edit"):
                 edited_action = response["args"]
-                approved_tool_calls.append(
+                revised_tool_calls.append(
                     ToolCall(
                         type="tool_call",
                         name=edited_action["action"],
@@ -233,6 +282,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
                     tool_call_id=tool_call["id"],
                     status="error",
                 )
+                revised_tool_calls.append(tool_call)
                 artificial_tool_messages.append(tool_message)
             else:
                 allowed_actions = [
@@ -249,9 +299,6 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
                 raise ValueError(msg)
 
         # Update the AI message to only include approved tool calls
-        last_ai_msg.tool_calls = approved_tool_calls
-
-        if len(approved_tool_calls) > 0:
-            return {"messages": [last_ai_msg, *artificial_tool_messages]}
+        last_ai_msg.tool_calls = revised_tool_calls
 
-        return {"jump_to": "model", "messages": artificial_tool_messages}
+        return {"messages": [last_ai_msg, *artificial_tool_messages]}

langchain/agents/middleware/model_call_limit.py

@@ -0,0 +1,177 @@
+"""Call tracking middleware for agents."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from langchain_core.messages import AIMessage
+
+from langchain.agents.middleware.types import AgentMiddleware, AgentState, hook_config
+
+if TYPE_CHECKING:
+    from langgraph.runtime import Runtime
+
+
+def _build_limit_exceeded_message(
+    thread_count: int,
+    run_count: int,
+    thread_limit: int | None,
+    run_limit: int | None,
+) -> str:
+    """Build a message indicating which limits were exceeded.
+
+    Args:
+        thread_count: Current thread model call count.
+        run_count: Current run model call count.
+        thread_limit: Thread model call limit (if set).
+        run_limit: Run model call limit (if set).
+
+    Returns:
+        A formatted message describing which limits were exceeded.
+    """
+    exceeded_limits = []
+    if thread_limit is not None and thread_count >= thread_limit:
+        exceeded_limits.append(f"thread limit ({thread_count}/{thread_limit})")
+    if run_limit is not None and run_count >= run_limit:
+        exceeded_limits.append(f"run limit ({run_count}/{run_limit})")
+
+    return f"Model call limits exceeded: {', '.join(exceeded_limits)}"
+
+
+class ModelCallLimitExceededError(Exception):
+    """Exception raised when model call limits are exceeded.
+
+    This exception is raised when the configured exit behavior is 'error'
+    and either the thread or run model call limit has been exceeded.
+    """
+
+    def __init__(
+        self,
+        thread_count: int,
+        run_count: int,
+        thread_limit: int | None,
+        run_limit: int | None,
+    ) -> None:
+        """Initialize the exception with call count information.
+
+        Args:
+            thread_count: Current thread model call count.
+            run_count: Current run model call count.
+            thread_limit: Thread model call limit (if set).
+            run_limit: Run model call limit (if set).
+        """
+        self.thread_count = thread_count
+        self.run_count = run_count
+        self.thread_limit = thread_limit
+        self.run_limit = run_limit
+
+        msg = _build_limit_exceeded_message(thread_count, run_count, thread_limit, run_limit)
+        super().__init__(msg)
+
+
+class ModelCallLimitMiddleware(AgentMiddleware):
+    """Middleware that tracks model call counts and enforces limits.
+
+    This middleware monitors the number of model calls made during agent execution
+    and can terminate the agent when specified limits are reached. It supports
+    both thread-level and run-level call counting with configurable exit behaviors.
+
+    Thread-level: The middleware tracks the number of model calls and persists
+    call count across multiple runs (invocations) of the agent.
+
+    Run-level: The middleware tracks the number of model calls made during a single
+    run (invocation) of the agent.
+
+    Example:
+        ```python
+        from langchain.agents.middleware.call_tracking import ModelCallLimitMiddleware
+        from langchain.agents import create_agent
+
+        # Create middleware with limits
+        call_tracker = ModelCallLimitMiddleware(thread_limit=10, run_limit=5, exit_behavior="end")
+
+        agent = create_agent("openai:gpt-4o", middleware=[call_tracker])
+
+        # Agent will automatically jump to end when limits are exceeded
+        result = await agent.invoke({"messages": [HumanMessage("Help me with a task")]})
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        thread_limit: int | None = None,
+        run_limit: int | None = None,
+        exit_behavior: Literal["end", "error"] = "end",
+    ) -> None:
+        """Initialize the call tracking middleware.
+
+        Args:
+            thread_limit: Maximum number of model calls allowed per thread.
+                None means no limit. Defaults to None.
+            run_limit: Maximum number of model calls allowed per run.
+                None means no limit. Defaults to None.
+            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".
+
+        Raises:
+            ValueError: If both limits are None or if exit_behavior is invalid.
+        """
+        super().__init__()
+
+        if thread_limit is None and run_limit is None:
+            msg = "At least one limit must be specified (thread_limit or run_limit)"
+            raise ValueError(msg)
+
+        if exit_behavior not in ("end", "error"):
+            msg = f"Invalid exit_behavior: {exit_behavior}. Must be 'end' or 'error'"
+            raise ValueError(msg)
+
+        self.thread_limit = thread_limit
+        self.run_limit = run_limit
+        self.exit_behavior = exit_behavior
+
+    @hook_config(can_jump_to=["end"])
+    def before_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:  # noqa: ARG002
+        """Check model call limits before making a model call.
+
+        Args:
+            state: The current agent state containing call counts.
+            runtime: The langgraph runtime.
+
+        Returns:
+            If limits are exceeded and exit_behavior is "end", returns
+            a Command to jump to the end with a limit exceeded message. Otherwise returns None.
+
+        Raises:
+            ModelCallLimitExceededError: If limits are exceeded and exit_behavior
+                is "error".
+        """
+        thread_count = state.get("thread_model_call_count", 0)
+        run_count = state.get("run_model_call_count", 0)
+
+        # Check if any limits will be exceeded after the next call
+        thread_limit_exceeded = self.thread_limit is not None and thread_count >= self.thread_limit
+        run_limit_exceeded = self.run_limit is not None and run_count >= self.run_limit
+
+        if thread_limit_exceeded or run_limit_exceeded:
+            if self.exit_behavior == "error":
+                raise ModelCallLimitExceededError(
+                    thread_count=thread_count,
+                    run_count=run_count,
+                    thread_limit=self.thread_limit,
+                    run_limit=self.run_limit,
+                )
+            if self.exit_behavior == "end":
+                # Create a message indicating the limit was exceeded
+                limit_message = _build_limit_exceeded_message(
+                    thread_count, run_count, self.thread_limit, self.run_limit
+                )
+                limit_ai_message = AIMessage(content=limit_message)
+
+                return {"jump_to": "end", "messages": [limit_ai_message]}
+
+        return None