Build a Bounded LangGraph Tool-Calling Agent with Human Review
A practical pattern for evaluating a LangGraph tool-calling agent with explicit step limits, human approval for risky actions, and repeatable test cases.
Summary · TL;DR
Use a graph step limit to bound execution, HumanInTheLoopMiddleware to pause risky tool calls, and a small fixed test set to check approval, rejection, and limit behavior. Treat the examples as a starting point: model and tool behavior must be tested in your own environment.
Key Takeaways
- A graph recursion limit gives an agent a clear execution boundary; it does not guarantee that the agent completes its task.
- Human review can pause tool execution and resume it later when the graph has a checkpointer and a thread ID.
- Keep evaluations repeatable by fixing test inputs, expected outcomes, tool fixtures, and the execution limit.
- Test rejected actions and limit exhaustion explicitly; neither is the same as successful recovery.
On this page (6)
A tool-calling agent needs more than a good prompt: it needs a stopping boundary, a plan for risky actions, and tests that make its behavior reproducible. In LangGraph, you can combine a graph recursion limit with human-in-the-loop (HITL) review for selected tools. Then evaluate the workflow with fixed cases rather than relying on a few successful runs.
The example below is illustrative, not a tested configuration. It assumes a Python environment with compatible LangChain and LangGraph packages, a chat model that supports tool calling, and a tool you have implemented. Check the versions and model-provider parameters in your own environment.
Choose the boundary before adding tools
A recursion limit bounds graph execution steps. It is a safety boundary, not a promise that the agent will finish, nor a precise limit on the number of tool calls: graph structure affects how steps are counted. If execution reaches the limit, expect a graph recursion error and handle it as an incomplete run. Do not treat it as a successful answer.
Start with a small limit during evaluation, then raise it only when a test case demonstrates that the workflow needs more steps. Also keep tool operations narrowly scoped. A graph-level limit cannot undo a side effect that a tool already performed.
Configure a tool call that can pause for review
This example uses create_agent with HITL middleware. The write_file tool is interrupted for approval or rejection; read_data is not. The tool implementations and model name are placeholders. Confirm that your chosen model and endpoint support the parameters and tool-calling behavior your agent uses.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver is suitable for a prototype or a test that runs in one process; it is not durable across process restarts. For a deployed workflow, use a persistent checkpointer. The LangChain HITL guide explains that a checkpointer and thread ID are required to pause and resume an execution. Source: Human-in-the-loop.
When the run returns an interrupt, show the requested action and its arguments to a reviewer. Resume the same thread with a decision. The decision order must match the action order in the interrupt. Reject an action you are denying; respond is for returning a human answer as a tool result, not for denying a side effect.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
Make the evaluation repeatable
Keep a compact test set in version control. Each case should specify the user request, expected tool behavior, whether review is required, and the expected final status. Use harmless fixtures or mocked tools for tests; do not let evaluation cases write to real files or change production data.
| Case | Setup | Expected result |
|---|---|---|
| Safe read | Request information through read_data | No HITL interrupt; tool result is returned |
| Reviewed write | Request a permitted write | Interrupt appears before the write runs; approval permits execution |
| Rejected write | Request a write, then reject it | The write tool is not executed; rejection feedback returns to the agent |
| Step-limit boundary | Use a fixture that keeps the workflow from completing | Run stops at the configured boundary and is recorded as incomplete |
For each run, record the case ID, configured limit, tool calls, interrupt decisions, completion status, and any error. Compare those fields against expectations. Avoid judging only the final natural-language response: an agent can produce a plausible answer after taking the wrong action.
Failure handling: pause, reject, or stop
HITL is a controlled pause, not a general retry mechanism. A reviewer can approve, edit, reject, or respond according to the configured policy. Rejection skips the requested tool call and returns rejection feedback to the agent. Whether the agent then finishes, asks for another action, or fails depends on its subsequent behavior, so test that path.
If the graph reaches its recursion limit, record the run as a limit failure and inspect its state and tool history. Do not automatically replay a run that may already have performed side effects. Make tools idempotent where practical, or require a separate check before repeating an operation. The supplied documentation describes checkpointed pause and resume; it does not establish automatic recovery from arbitrary tool or model failures.
Troubleshooting checklist
- No interrupt appears: Check that the tool name matches the
interrupt_onmapping and that its policy enables review. - Resume cannot find the paused run: Confirm that the same checkpointer and thread ID are used.
- The run stops early: Inspect the configured recursion limit and graph path; raise the limit only when a test case justifies it.
- A rejected action seems to have happened: Verify that the tool was not invoked before review and that the reviewer used
reject, notrespond. - Tests vary between runs: Fix tool fixtures and test inputs, and control or stub model responses where your setup allows it. A fixed input alone does not make model output deterministic.
The practical rule
Use the recursion limit to bound graph work, HITL to gate consequential tool calls, and a small explicit test set to verify both the happy path and failure paths. Treat interrupted, rejected, and limit-exhausted runs as distinct outcomes. That distinction makes an agent easier to evaluate—and safer to change.
FAQ
Does LangGraph’s recursion limit cap the number of tool calls?
Not exactly. It limits graph execution steps, and the number of tool calls that fit depends on the graph structure. Treat limit exhaustion as an incomplete run and test the boundary.
What is required to resume a human-reviewed tool call?
Configure a checkpointer, provide a thread ID, and resume using the same thread and persistence context. The reviewer supplies a decision for each interrupted action.
Does HITL automatically retry a failed tool call?
No. The documented HITL workflow pauses for a human decision and then executes or skips the reviewed action. It does not establish automatic retries for arbitrary tool or model failures.
How should I test a rejected tool call?
Use a harmless or mocked tool, trigger the interrupt, reject the action, and assert that the tool was not executed and that the run records rejection feedback.
Related articles
Guides
Build a Privacy-Aware LangGraph Agent with Tool Approval and Recovery
A practical pattern for using LangGraph human review, checkpointing, bounded runs, and credential-safe tools in an agent that handles sensitive data.
Guides
LangGraph Tool Calling with Bounded Execution and Failure Recovery
Build a LangGraph production-operations agent that uses tool calling, retry budgets, human approval, and explicit recovery paths instead of unbounded execution.
Guides
Build a Bounded LangGraph Agent for API Incident Diagnosis
Build a LangGraph incident-diagnosis agent that calls read-only diagnostic tools, limits execution, surfaces failures, and pauses before risky actions.
Guides
Build a LangGraph Customer Support Agent with Tool Calling, Human Approval, and Execution Limits
A practical LangGraph pattern for customer-support triage: route requests, call lookup tools, pause refunds for human approval, and bound graph execution.