Skip to content

The agent engineering platform.

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

Sydney Runkle2671fee2c644
diff --git a/libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py b/libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py
index f9b1e4d31e..681041f267 100644
--- a/libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py
+++ b/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 @@ 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."""
@@ -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 @@ 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] = {}
@@ -146,7 +189,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
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 @@ 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(
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py b/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py
index 67aa085e54..2716d5c473 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py
+++ b/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."""