Execução do agente humano-in-the-loop

Visão geral

A execução do ser humano no loop (HITL) permite que um agente faça uma pausa no meio da execução e espere que um ser humano revise seu trabalho antes de continuar. Quando um agente chama uma ferramenta de revisão humana definida no código do agente , ele suspende a execução, apresenta o contexto para um revisor e retoma somente após o revisor enviar uma decisão.

No MongoDB Atlas Agent Engine, o HITL está embutido no pipeline de execução. O ciclo de vida do pipeline de suspensão, revisão e retomada da execução se aplica se você invoca o agente a partir da API do Atlas Agent Engine, da CLI agentengine ou da interface do usuário do Atlas Agent Engine. Este guia explica as etapas do ciclo de vida do HITL e como enviar decisões sobre a execução suspensa.

Suspender, revisar e retomar o ciclo de vida

Um agente entra na revisão humana quando chama uma ferramenta de revisão humana durante uma execução. Para habilitar a revisão humana, adicione essa ferramenta ao código do agente usando a função interrupt() do adaptador LangGraph.

Em seguida, o Mecanismo do Agente do Atlas move a execução através do seguinte ciclo de vida:

1. Suspender: o agente chama uma ferramenta de revisão por humanos, que pausa a execução. A sandbox do agente salva um checkpoint do estado do agente e relata o status suspended ao Mecanismo de Orquestração (OE).

2. Notificar: a interface do usuário apresenta a execução pausada e notifica um revisor humano. A execução suspensa carrega o contexto que o agente forneceu no ponto de interrupção.

3. Revise: um revisor inspeciona o contexto exibido e envia uma decisão, como uma aprovação ou uma rejeitação. A decisão passa pelo API Gateway até o OE.

4. Retomar: a OE envia a execução de volta para a sandbox do agente com a decisão do revisor. O resultado da decisão depende do código do agente . De qualquer forma, a sandbox do agente restaura o agente de seu checkpoint e executa novamente o gráfico.

5. Concluído: depois que o agente termina qualquer trabalho restante, o OE marca a execução como completed. Uma execução pode ser suspensa e retomada várias vezes antes de atingir um status terminal.

Revise o contexto de suspensão

Quando um agente suspende, ele fornece um objeto suspend_context que descreve o que deve ser analisado. O agente define os campos nesse objeto no ponto de interrupção , portanto o conteúdo exato varia de acordo com o agente. Por exemplo, um agente de aprovação de reembolsos pode exibir um ID de reivindicação e uma descrição da ação solicitada .

O objeto suspend_context também pode incluir uma lista allowed_decisions que restringe quais decisões um revisor pode enviar. Se esta lista estiver presente e não vazia, a OE rejeita qualquer decisão que não esteja na lista.

Retomar uma execução suspensa

Você pode retomar uma execução suspensa a partir da API do Atlas Agent Engine, da CLI agentengine ou da interface do usuário do Atlas Agent Engine.

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

Saiba mais

Para saber mais sobre como retomar uma execução, consulte a documentação da API.

Para saber mais sobre como invocar agentes, consulte o guia Invoke an Agent .