The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(langchain): add `respond` decision to HITL middleware (#37095)
Sydney Runkleba56ac6f03b4
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 acb81c58c6..ac1a01fa50 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@@ -39,7 +39,7 @@ class ActionRequest(TypedDict):"""The description of the action to be reviewed."""-DecisionType = Literal["approve", "edit", "reject"]+DecisionType = Literal["approve", "edit", "reject", "respond"]class ReviewConfig(TypedDict):@@ -95,7 +95,22 @@ class RejectDecision(TypedDict):"""The message sent to the model explaining why the action was rejected."""-Decision = ApproveDecision | EditDecision | RejectDecision+class RespondDecision(TypedDict):+ """Response when a human answers on behalf of the tool, skipping execution.++ Used for "ask user" style tools whose real implementation is the human's+ response. The tool is not executed; instead, a synthetic `ToolMessage` with+ `status="success"` and the provided `message` is returned to the model.+ """++ type: Literal["respond"]+ """The type of response when a human responds on behalf of the tool."""++ message: str+ """Content of the synthetic `ToolMessage` returned to the model."""+++Decision = ApproveDecision | EditDecision | RejectDecision | RespondDecisionclass HITLResponse(TypedDict):@@ -180,7 +195,8 @@ class HumanInTheLoopMiddleware(AgentMiddleware[StateT, ContextT, ResponseT]):If a tool doesn't have an entry, it's auto-approved by default.- * `True` indicates all decisions are allowed: approve, edit, and reject.+ * `True` indicates all decisions are allowed: approve, edit, reject,+ and respond.* `False` indicates that the tool is auto-approved.* `InterruptOnConfig` indicates the specific decisions allowed for thistool.@@ -200,7 +216,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware[StateT, ContextT, ResponseT]):if isinstance(tool_config, bool):if tool_config is True:resolved_configs[tool_name] = InterruptOnConfig(- allowed_decisions=["approve", "edit", "reject"]+ allowed_decisions=["approve", "edit", "reject", "respond"])elif tool_config.get("allowed_decisions"):resolved_configs[tool_name] = tool_config@@ -277,6 +293,15 @@ class HumanInTheLoopMiddleware(AgentMiddleware[StateT, ContextT, ResponseT]):status="error",)return tool_call, tool_message+ if decision["type"] == "respond" and "respond" in allowed_decisions:+ # Skip tool execution; the human answers on behalf of the tool.+ tool_message = ToolMessage(+ content=decision["message"],+ name=tool_call["name"],+ tool_call_id=tool_call["id"],+ status="success",+ )+ return tool_call, tool_messagemsg = (f"Unexpected human decision: {decision}. "f"Decision type '{decision.get('type')}' "diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_human_in_the_loop.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_human_in_the_loop.pyindex e9d3417aa4..5e03b0bed5 100644--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_human_in_the_loop.py+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_human_in_the_loop.py@@ -150,6 +150,136 @@ def test_human_in_the_loop_middleware_single_tool_response() -> None:assert result["messages"][1].tool_call_id == "1"+def test_human_in_the_loop_middleware_single_tool_respond() -> None:+ """Test HumanInTheLoopMiddleware with `respond` decision producing a success ToolMessage."""+ middleware = HumanInTheLoopMiddleware(+ interrupt_on={"ask_user": {"allowed_decisions": ["respond"]}}+ )++ ai_message = AIMessage(+ content="Let me ask the user.",+ tool_calls=[{"name": "ask_user", "args": {"question": "favorite color?"}, "id": "1"}],+ )+ state = AgentState[Any](messages=[HumanMessage(content="Hello"), ai_message])++ def mock_respond(_: Any) -> dict[str, Any]:+ return {"decisions": [{"type": "respond", "message": "blue"}]}++ with patch("langchain.agents.middleware.human_in_the_loop.interrupt", side_effect=mock_respond):+ result = middleware.after_model(state, Runtime())+ assert result is not None+ assert "messages" in result+ assert len(result["messages"]) == 2+ assert isinstance(result["messages"][0], AIMessage)+ # Tool call is preserved on the AI message (provider APIs require pairing).+ assert len(result["messages"][0].tool_calls) == 1+ assert result["messages"][0].tool_calls[0]["id"] == "1"++ tool_message = result["messages"][1]+ assert isinstance(tool_message, ToolMessage)+ assert tool_message.content == "blue"+ assert tool_message.name == "ask_user"+ assert tool_message.tool_call_id == "1"+ assert tool_message.status == "success"+++def test_human_in_the_loop_middleware_respond_disallowed() -> None:+ """Test that `respond` raises when not in `allowed_decisions`."""+ middleware = HumanInTheLoopMiddleware(+ interrupt_on={"test_tool": {"allowed_decisions": ["approve", "edit", "reject"]}}+ )++ ai_message = AIMessage(+ content="I'll help you",+ tool_calls=[{"name": "test_tool", "args": {"input": "test"}, "id": "1"}],+ )+ state = AgentState[Any](messages=[HumanMessage(content="Hello"), ai_message])++ def mock_respond(_: Any) -> dict[str, Any]:+ return {"decisions": [{"type": "respond", "message": "synthetic"}]}++ with (+ patch("langchain.agents.middleware.human_in_the_loop.interrupt", side_effect=mock_respond),+ pytest.raises(+ ValueError,+ match=re.escape(+ "Decision type 'respond' is not allowed for tool 'test_tool'. "+ "Expected one of ['approve', 'edit', 'reject'] based on the tool's "+ "configuration."+ ),+ ),+ ):+ middleware.after_model(state, Runtime())+++def test_human_in_the_loop_middleware_mixed_with_respond() -> None:+ """Test mixed decisions: one tool approved, one tool answered via `respond`."""+ middleware = HumanInTheLoopMiddleware(+ interrupt_on={+ "get_forecast": {"allowed_decisions": ["approve"]},+ "ask_user": {"allowed_decisions": ["respond"]},+ }+ )++ ai_message = AIMessage(+ content="Two things",+ tool_calls=[+ {"name": "get_forecast", "args": {"location": "SF"}, "id": "1"},+ {"name": "ask_user", "args": {"question": "favorite color?"}, "id": "2"},+ ],+ )+ state = AgentState[Any](messages=[HumanMessage(content="Hi"), ai_message])++ def mock_mixed(_: Any) -> dict[str, Any]:+ return {+ "decisions": [+ {"type": "approve"},+ {"type": "respond", "message": "blue"},+ ]+ }++ with patch("langchain.agents.middleware.human_in_the_loop.interrupt", side_effect=mock_mixed):+ result = middleware.after_model(state, Runtime())+ assert result is not None+ # AI message + 1 synthetic ToolMessage for the respond decision.+ assert len(result["messages"]) == 2++ updated_ai_message = result["messages"][0]+ assert len(updated_ai_message.tool_calls) == 2+ assert updated_ai_message.tool_calls[0]["name"] == "get_forecast"+ assert updated_ai_message.tool_calls[1]["name"] == "ask_user"++ tool_message = result["messages"][1]+ assert isinstance(tool_message, ToolMessage)+ assert tool_message.content == "blue"+ assert tool_message.name == "ask_user"+ assert tool_message.tool_call_id == "2"+ assert tool_message.status == "success"+++def test_human_in_the_loop_middleware_true_allows_respond() -> None:+ """Test that the `True` shortcut permits `respond` decisions."""+ middleware = HumanInTheLoopMiddleware(interrupt_on={"ask_user": True})++ ai_message = AIMessage(+ content="Asking",+ tool_calls=[{"name": "ask_user", "args": {"q": "?"}, "id": "1"}],+ )+ state = AgentState[Any](messages=[HumanMessage(content="Hi"), ai_message])++ with patch(+ "langchain.agents.middleware.human_in_the_loop.interrupt",+ return_value={"decisions": [{"type": "respond", "message": "answer"}]},+ ):+ result = middleware.after_model(state, Runtime())+ assert result is not None+ assert len(result["messages"]) == 2+ tool_message = result["messages"][1]+ assert isinstance(tool_message, ToolMessage)+ assert tool_message.content == "answer"+ assert tool_message.status == "success"++def test_human_in_the_loop_middleware_multiple_tools_mixed_responses() -> None:"""Test HumanInTheLoopMiddleware with multiple tools and mixed response types."""middleware = HumanInTheLoopMiddleware(