Human in the Loop

O bloco Human in the Loop pausa uma execução e espera uma pessoa antes de continuar. Use para gates de aprovação, coletar feedback ou reunir entrada num ponto de decisão. A execução fica pausada — sem timeout — até alguém responder pelo portal de aprovação, pela API ou por um webhook.

Configuração

Display Data

O que o aprovador vê — o contexto mostrado no portal para ajudar a decidir. Monte campo a campo ou como JSON, referenciando saídas anteriores com <blockName.output>.

{
  "customerName": "<agent1.content.name>",
  "proposedAction": "<router1.selectedPath>",
  "confidenceScore": "<evaluator1.score>",
  "generatedEmail": "<agent2.content>"
}

Notification

Como os aprovadores são alertados de que uma decisão está esperando. Inclua a URL de aprovação (<blockId.url>) na mensagem para abrirem o portal. Canais disponíveis:

• Slack — uma mensagem para um canal ou DM
• Gmail — um e-mail com o link de aprovação
• Microsoft Teams — uma notificação de canal
• SMS — um alerta de texto via Twilio
• Webhook — uma request para o seu próprio sistema de notificação

Resume Form

Os campos que o aprovador preenche ao responder. Cada um fica disponível para blocos downstream quando a execução retoma.

{
  "approved": {
    "type": "boolean",
    "description": "Approve or reject this request"
  },
  "comments": {
    "type": "string",
    "description": "Optional feedback or explanation"
  }
}

Acesse dados de resume em blocos downstream com <blockId.fieldName>.

Métodos de aprovação

POST /api/resume/{workflowId}/{executionId}/{contextId}
Content-Type: application/json
X-API-Key: your-api-key

{
  "input": {
    "approved": true,
    "comments": "Looks good to proceed"
  }
}

{
  "success": true,
  "status": "completed",
  "executionId": "<resumeExecutionId>",
  "output": { ... },
  "metadata": { "duration": 1234, "startTime": "...", "endTime": "..." }
}

{
  "success": true,
  "async": true,
  "jobId": "<jobId>",
  "executionId": "<resumeExecutionId>",
  "message": "Resume execution queued",
  "statusUrl": "/api/jobs/<jobId>"
}

GET /api/jobs/{jobId}
X-API-Key: your-api-key

GET /api/resume/{workflowId}/{executionId}
X-API-Key: your-api-key

Comportamento do API Execute

Ao disparar um workflow via API execute (POST /api/workflows/{id}/execute), blocos HITL fazem a execução pausar e retornar os dados _resume na resposta:

{
  "success": true,
  "executionId": "<executionId>",
  "output": {
    "data": {
      "operation": "human",
      "_resume": {
        "apiUrl": "/api/resume/{workflowId}/{executionId}/{contextId}",
        "uiUrl": "/resume/{workflowId}/{executionId}",
        "contextId": "<contextId>",
        "executionId": "<executionId>",
        "workflowId": "<workflowId>"
      }
    }
  }
}

data: {"blockId":"agent1","chunk":"streamed content..."}
data: {"event":"final","data":{"success":true,"output":{...,"_resume":{...}},"status":"paused"}}
data: "[DONE]"

Exemplos

Aprovar conteúdo antes de publicar

A execução pausa no bloco Human in the Loop até alguém aprovar; no resume, a API publica. O mesmo gate funciona antes de qualquer ação, como enviar um e-mail ao cliente.

Encadear várias aprovações

Para uma mudança de alto risco, encadeie dois passos de aprovação — um manager e depois um director — antes do workflow executar.

Verificar dados extraídos

Um revisor checa os dados que um Agent extraiu antes de um Function processá-los.

Saídas

Leia-as downstream como <blockName.output> — para um bloco chamado approval, isso é <approval.approved>.

O portal de aprovação

Paused Output:

{
  "title": "<agent1.content.title>",
  "body": "<agent1.content.body>",
  "qualityScore": "<evaluator1.score>"
}

Resume Input:

{
  "approved": { "type": "boolean" },
  "feedback": { "type": "string" }
}

Uso downstream:

// Condition block
<approval1.approved> === true

O exemplo abaixo mostra um portal de aprovação como visto por um aprovador depois que o workflow é pausado. Aprovadores podem revisar os dados e fornecer entradas como parte da retomada do workflow. O portal de aprovação pode ser acessado diretamente pela URL única, <blockId.url>.

Blocos relacionados

• Condition - Ramifique com base em decisões de aprovação
• Variables - Armazene histórico de aprovação e metadados
• Response - Retorne resultados do workflow a callers de API