Overview
人机交互 (HITL) 执行允许代理在运行中暂停，等待人工查看后再继续执行工作。当代理调用代理代码中定义的人工审核工具时，它会暂停执行，为审核者显示上下文，并仅在审核者提交决策后才恢复。
在MongoDB Atlas Agent Engine 上，HITL 内置于执行管道中。无论您是通过Atlas Agent Engine API、agentengine CLI还是Atlas Agent Engine 用户用户界面调用代理，暂停、查看和恢复执行管道生命周期都适用。本指南解释了 HITL 生命周期的各个阶段以及如何提交有关暂停执行的决策。
暂停、查看和恢复生命周期
代理在执行期间调用人工审核工具时会进入人工查看。要启用人工查看，请使用 LangGraph 适配器的 interrupt() 函数将此工具添加到代理代码中。
提示
要学习；了解有关 interrupt() 函数的更多信息，请参阅 LangGraph 文档。
然后， Atlas助手引擎将执行移动到以下生命周期：
暂停：代理调用人工审核工具，暂停运行。代理沙箱会保存代理状态的检查点，并向编排引擎 (OE) 报告
suspended状态。通知：用户界面显示暂停的执行并通知人工审核者。暂停的执行带有代理在中点提供的上下文。
审核：审核者检查显示的上下文并提交决定，例如批准或拒绝。该决策通过API网关传递给 OE。
恢复：OE 将执行操作与审核者的决定一起发送回代理沙箱。决策结果取决于代理代码。无论哪种方式，代理沙箱都会从其检查点恢复代理并重新运行图表。
完成：代理完成所有剩余工作后，操作环境将执行标记为
completed。在达到终端状态之前，执行可以多次挂起和恢复。
执行状态生命周期
Atlas Agent Engine 在每个执行API响应的 status字段中报告当前状态。不需要人工查看的执行会经历以下状态：
pendingrunningcompletedorerror
当执行暂停以进行人工查看时，它会经历以下状态：
pendingrunningsuspendedresumingcompletedorerror
重放保证
当操作环境恢复执行时，它会返回暂停之前完成的每个步骤的缓存结果。代理会重新运行相同的代码路径，但操作环境会提供存储的结果，而不是再次运行之前的步骤。仅首次运行查看点之后的步骤。
这种重放保证可以防止重复操作。示例，如果代理在暂停以进行查看之前发送了一封电子邮件，则恢复执行后不会再次发送该电子邮件。
查看挂起上下文
当代理挂起时，它会提供一个 suspend_context对象，用于描述要查看的内容。代理在中点定义此对象中的字段，因此确切内容因代理而异。示例，退款批准代理可能会显示声明ID和所请求动作的描述。
suspend_context对象还可能包括一个 allowed_decisions 列表，用于限制审核者可以提交的决定。如果此列表存在且非空，则 OE 将拒绝不在列表中的任何决策。
审核者决策
代理暂停后，审核者提交有关暂停执行的决定。要提交此决定，请提供以下信息：
输入 | 必需 | 说明 |
|---|---|---|
决定 | 是 | 审核者对暂停执行的决定，例如 |
审阅者注释 | No | 决策附带的自由格式上下文。 |
恢复暂停的执行
您可以从Atlas Agent Engine API、agentengine CLI或Atlas Agent Engine 用户用户界面恢复暂停的执行。
重要
要恢复暂停的执行，您必须具有 PROJECT_OWNER角色。
使用API
要使用API恢复暂停的执行，请向 /api/v1/projects/{project_id}/executions/{execution_id}/resume?workspace_id={workspace_id} API端点发送 POST请求。请求正文包括审核者决定，如恢复请求正文中所示。执行端点的作用域为项目。将项目ID、执行ID和工作区ID占位符替换为您自己的值。
注意
Atlas Agent Engine 不会在暂停执行期间保留自定义标头。重新发送恢复请求中的任何 X-Mdb-Agent-Engine-Custom- 标头，或者代理不会收到这些标头。要学习；了解更多信息，请参阅转发自定义标头。
选择您首选工具的标签页，查看恢复暂停执行的示例POST请求。每个示例中的 X-Mdb-Agent-Engine-Custom-Authorization 标头显示了如何重新发送自定义标头：
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"}, )
恢复请求正文
恢复请求正文是一个JSON对象，其中包括 decision字段和可选的 reviewer_notes字段。请求正文类似于以下示例：
{"decision": "approve", "reviewer_notes": "approved after verifying customer identity"}
有效的 decision 值来自代理在挂起时声明的 allowed_decisions 列表，而不是来自固定设立。如果您发送的决策不在该列表中，OE 将返回一条 400 错误消息，其中包括允许的值。
重要
API网关仅接受上示例所示的平面请求正文。如果您将决策嵌套在 human_review对象内，则API Gateway 将通过返回 400 错误消息来拒绝请求。
使用CLI
当您在交互式终端中运行agentengine invoke 命令而不显示消息时， CLI将启动流媒体聊天会话。在此交互模式下，当代理暂停调用以供人工查看时， CLI会自动显示内联查看提示。
CLI会打印代理提供的挂起上下文以及允许的决策的编号列表。 CLI输出类似于以下示例：
--- 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]:
选择决策后， CLI会提示输入可选的审阅者注释，如以下示例所示：
Reviewer notes (optional): [default: ]
然后， CLI恢复执行并打印 Execution resumed. The session keep open, and you can send a final-up message 检索 Agent's post-resume output.
注意
交互式 HITL查看仅在交互模式下可用。如果使用 --json 标志、管道 stdin操作符或 --file 标志，则该方法不起作用。
要学习；了解有关 agentengine invoke 命令的更多信息，请参阅从CLI调用代理。
使用用户界面
Atlas Agent Engine 用户用户界面在 Pending Reviews 页面上显示暂停的执行，您可以在其中检查暂停的执行并提交决策。要从用户界面恢复暂停的执行，请完成以下步骤：