The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
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.pyindex 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, Protocolfrom langchain_core.messages import AIMessage, ToolCall, ToolMessagefrom 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_configsself.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.pyindex 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 AnthropicPromptCachingMiddlewaredef test_anthropic_prompt_caching_middleware_initialization() -> None:"""Test AnthropicPromptCachingMiddleware initialization."""