human-in-the-loop

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: resume-curl, resume-python -->

Human-in-the-Loop Agent Execution

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

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.

Tip:

To learn more about the interrupt() function, see the LangGraph documentation.

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.

Execution Status Lifecycle

The Atlas Agent Engine reports the current status in the status field of each execution API response. An execution that does not require human review moves through the following statuses:

• pending

• running

• completed or error

When an execution suspends for human review, it moves through the following statuses:

• pending

• running

• suspended

• resuming

• completed or error

Replay Guarantee

When the OE resumes an execution, it returns cached results for every step that completed before the suspend. The agent re-runs the same code path, but the OE serves stored results instead of running previous steps again. Only steps that come after the review point run for the first time.

This replay guarantee prevents duplicate actions. For example, if an agent sends an email before it suspends for review, the resumed execution does not send that email a second time.

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.

Reviewer Decisions

After the agent suspends, a reviewer submits a decision about the suspended execution. To submit this decision, provide the following inputs:

The [following section](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-hitl-resume describes the different ways you can provide these inputs.

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.

Important:

To resume a suspended execution, you must have the PROJECT_OWNER role.

Use the API

To resume a suspended execution by using the API, send a POST request to the /api/v1/projects/{project_id}/executions/{execution_id}/resume?workspace_id={workspace_id} API endpoint. The request body includes the reviewer decision, as shown in [Resume Request Body](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-resume-request-body. The execution endpoints are scoped to a project. Replace the project ID, execution ID, and workspace ID placeholders with your own values.

Note:

The Atlas Agent Engine does not persist custom headers across a suspended execution. Resend any X-Mdb-Agent-Engine-Custom- headers on the resume request, or the agent does not receive them. To learn more, see [Forward Custom Headers.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-forward-custom-headers

Select the tab for your preferred tool to see an example POST request that resumes a suspended execution. The X-Mdb-Agent-Engine-Custom-Authorization header in each example shows how to resend a custom header:

cURL

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"}'

Resume Request Body

The resume request body is a JSON object that includes the decision field and an optional reviewer_notes field. The request body resembles the following example:

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

The valid decision values come from the allowed_decisions list that the agent declares when it suspends, not from a fixed set. If the decision you send is not in that list, the OE returns a 400 error message that includes the allowed values.

Important:

The API Gateway accepts only the flat request body shown in the preceding example. If you nest the decision inside a human_review object, the API Gateway rejects the request by returning a 400 error message.

Use the CLI

When you run the agentengine invoke command without a message in an interactive terminal, the CLI starts a streaming chat session. In this interactive mode, the CLI automatically presents an inline review prompt when the agent suspends an invocation for human review.

The CLI prints the suspend context that the agent provided and a numbered list of allowed decisions. The CLI output resembles the following example:

--- 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]:

After you select a decision, the CLI prompts for optional reviewer notes, as shown in the following example:

Reviewer notes (optional): [default: ]

Then, the CLI resumes the execution and prints Execution resumed. The session stays open, and you can send a follow-up message to retrieve the agent's post-resume output.

Note:

Interactive HITL review is available only in interactive mode. It does not work if you use the --json flag, the piped stdin operator, or the --file flag.

To learn more about the agentengine invoke command, see [Invoke an Agent from the CLI.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-cli

Use the UI

The Atlas Agent Engine UI displays suspended executions on the Pending Reviews page, where you can inspect a paused execution and submit a decision. To resume a suspended execution from the UI, complete the following steps:

1. Open the Pending Reviews page.

The Pending Reviews page lists the executions that are awaiting review. If no executions are suspended, the page shows a message that no pending reviews exist.

1. Open the review for a suspended execution.

The Review Request window displays details about the suspended execution, including the execution ID, the time it was submitted, the original message, the suspend reason, and the context that the agent provided for review.

1. Select a decision.

From the Decision list, select a decision. The available decisions come from the allowed_decisions values that the agent provided for the suspended execution.

1. Add optional reviewer notes.

In the Reviewer Notes field, add any context about your decision. This step is optional.

1. Submit the decision.

Click Submit Decision to resume the execution with your decision.

Learn More

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

To learn more about invoking agents, see the [Invoke an Agent](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent guide.