Human-in-the-Loop Agent Execution

Overview

Human-in-the-loop (HITL) execution allows an agent to pause mid-run and wait for a human to review its work before continuing. When an agent calls a human-review tool defined in the agent code, it suspends the execution, surfaces context for a reviewer, and resumes only after the reviewer submits a decision.

On the MongoDB Atlas Agent Engine, HITL is built into the execution pipeline. The suspend, review, and resume execution pipeline lifecycle applies whether you invoke the agent from the Atlas Agent Engine API, the agentengine CLI, or the Atlas Agent Engine UI. This guide explains the stages of the HITL lifecycle and how to submit decisions about the suspended execution.

Suspend, Review, and Resume Lifecycle

An agent enters human review when it calls a human-review tool during an execution. To enable human review, add this tool to the agent code by using the LangGraph adapter's interrupt() function.

Then, the Atlas Agent Engine moves the execution through the following lifecycle:

1. Suspend: The agent calls a human-review tool, which pauses the run. The agent sandbox saves a checkpoint of the agent's state and reports the suspended status to the Orchestration Engine (OE).

2. Notify: The UI surfaces the paused execution and notifies a human reviewer. The suspended execution carries the context that the agent provided at the interruption point.

3. Review: A reviewer inspects the surfaced context and submits a decision, such as an approval or a rejection. The decision travels through the API Gateway to the OE.

4. Resume: The OE sends the execution back to the agent sandbox with the reviewer's decision. The outcome of the decision depends on the agent code. Either way, the agent sandbox restores the agent from its checkpoint and re-runs the graph.

5. Complete: After the agent finishes any remaining work, the OE marks the execution as completed. An execution can suspend and resume multiple times before it reaches a terminal status.

Review the Suspend Context

When an agent suspends, it provides a suspend_context object that describes what to review. The agent defines the fields in this object at the interruption point, so the exact contents vary by agent. For example, a refund approval agent might surface a claim ID and a description of the requested action.

The suspend_context object might also include an allowed_decisions list that constrains which decisions a reviewer can submit. If this list is present and non-empty, the OE rejects any decision that is not in the list.

Resume a Suspended Execution

You can resume a suspended execution from the Atlas Agent Engine API, the agentengine CLI, or the Atlas Agent Engine UI.

curl -X POST "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/executions/$EXECUTION_ID/resume?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Mdb-Agent-Engine-Custom-Authorization: my-user-id" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve", "reviewer_notes": "optional context"}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/executions/{execution_id}/resume",
    params={"workspace_id": workspace_id},
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Mdb-Agent-Engine-Custom-Authorization": "my-user-id",
        "Content-Type": "application/json",
    },
    json={"decision": "approve", "reviewer_notes": "optional context"},
)

{"decision": "approve", "reviewer_notes": "approved after verifying customer identity"}

--- Execution suspended for human review ---
  claim_id: CLM-4821
  task_description: Approve refund of $240 for order #98765
Select a decision:
  1) approve
  2) reject
Select [1-2]:

Reviewer notes (optional): [default: ]

Learn More

To learn more about resuming an execution, see the API documentation.

To learn more about invoking agents, see the Invoke an Agent guide.