feat(langchain_v1): description generator for HITL middleware (#33195)

Need to decide - what information should we feed to this description
factory? Right now, feeding:
* state
* runtime
* tool call (so the developer doesn't have to search through the state's
messages for the corresponding tool call)

I can see a case for just passing tool call. But again, this abstraction
is semi-bound to interrupts for tools... though we pretend it's more
abstract than that.

Right now:

```py
def custom_description(state: AgentState, runtime: Runtime, tool_call: ToolCall) -> str:
        """Generate a custom description."""
        return f"Custom: {tool_call['name']} with args {tool_call['args']}"

middleware = HumanInTheLoopMiddleware(
    interrupt_on={
        "tool_with_callable": {"allow_accept": True, "description": custom_description},
        "tool_with_string": {"allow_accept": True, "description": "Static description"},
    }
)
```

Author: sydney-runkle

libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py

@@ -1,6 +1,6 @@
 """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
@@ -95,6 +95,14 @@ class EditPayload(TypedDict):
 """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."""
 
@@ -104,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):
@@ -122,12 +162,15 @@ def __init__(
         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] = {}
@@ -146,7 +189,7 @@ def __init__(
         self.interrupt_on = resolved_tool_configs
         self.description_prefix = description_prefix
 
-    def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:  # noqa: ARG002
+    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:
@@ -179,10 +222,15 @@ def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | N
             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(

libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py

@@ -892,6 +892,51 @@ def test_human_in_the_loop_middleware_sequence_mismatch() -> None:
             middleware.after_model(state, None)
 
 
+def test_human_in_the_loop_middleware_description_as_callable() -> None:
+    """Test that description field accepts both string and callable."""
+
+    def custom_description(tool_call: ToolCall, state: AgentState, runtime: Runtime) -> str:
+        """Generate a custom description."""
+        return f"Custom: {tool_call['name']} with args {tool_call['args']}"
+
+    middleware = HumanInTheLoopMiddleware(
+        interrupt_on={
+            "tool_with_callable": {"allow_accept": True, "description": custom_description},
+            "tool_with_string": {"allow_accept": True, "description": "Static description"},
+        }
+    )
+
+    ai_message = AIMessage(
+        content="I'll help you",
+        tool_calls=[
+            {"name": "tool_with_callable", "args": {"x": 1}, "id": "1"},
+            {"name": "tool_with_string", "args": {"y": 2}, "id": "2"},
+        ],
+    )
+    state = {"messages": [HumanMessage(content="Hello"), ai_message]}
+
+    captured_requests = []
+
+    def mock_capture_requests(requests):
+        captured_requests.extend(requests)
+        return [{"type": "accept"}, {"type": "accept"}]
+
+    with patch(
+        "langchain.agents.middleware.human_in_the_loop.interrupt", side_effect=mock_capture_requests
+    ):
+        middleware.after_model(state, None)
+
+        assert len(captured_requests) == 2
+
+        # Check callable description
+        assert (
+            captured_requests[0]["description"] == "Custom: tool_with_callable with args {'x': 1}"
+        )
+
+        # Check string description
+        assert captured_requests[1]["description"] == "Static description"
+
+
 # Tests for AnthropicPromptCachingMiddleware
 def test_anthropic_prompt_caching_middleware_initialization() -> None:
     """Test AnthropicPromptCachingMiddleware initialization."""