HumanInTheLoopMiddleware — frame custom rejection reasons

What it does

HumanInTheLoopMiddleware pauses an agent before a sensitive tool runs and asks a human to approve, edit, reject, or respond. When a human rejects a tool call, the middleware feeds a ToolMessage back to the model explaining what happened. Before this fix, if you supplied a custom RejectDecision.message, that message replaced all the rejection framing — the model got your raw text with no context that the tool was rejected rather than executed. Now the middleware wraps your reason in a consistent frame: "User rejected the tool call for '<tool>' with reason: <your message>". If you omit the message, it falls back to the bare-rejection text (tool not executed, don't retry unless the user asks). Either way, the model now reliably understands the tool was rejected by a human, without the middleware prescribing whether it should retry.

Why it matters

In real agent deployments, human-in-the-loop gates protect irreversible or costly actions — sending emails, transferring money, deleting data, calling external APIs. When a human rejects such an action, the model's next decision depends entirely on understanding why. If your custom rejection reason ("the amount is wrong", "wrong recipient", "this is a test account") is passed through without framing, the model may think the tool ran and returned that text, then behave incorrectly. This fix makes rejection feedback unambiguous and consistent across all your tools, so the agent reliably stops, learns the reason, and only retries when the human actually asks. It's a small change with a big impact on agent reliability and safety.

Example

$ Gate a send_payment tool and simulate a human rejection with a custom reason

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def send_payment(amount: int, recipient: str) -> str:
    """Send a payment to a recipient."""
    return f"Paid {amount} to {recipient}"

hitl = HumanInTheLoopMiddleware(
    interrupt_on={
        "send_payment": {
            "allowed_decisions": ["approve", "edit", "reject"],
        }
    }
)

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o", temperature=0),
    tools=[send_payment],
    middleware=[hitl],
)

# Simulate the human rejecting with a custom reason.
rejection = {"type": "reject", "message": "Amount is too high"}

# The ToolMessage the model now receives is framed as a user rejection:
print(
    "User rejected the tool call for `send_payment` "
    f"with reason: {rejection['message']}"
)

Common flags

RejectDecision

TypedDict for a human rejection; optional message is now framed as a user rejection reason

ApproveDecision

TypedDict signalling the tool call should proceed unchanged

EditDecision

TypedDict carrying an edited_action (new name/args) to run instead

interrupt()

The runtime call that pauses the agent and returns the human's decisions