Human in the Loop

Portal de aprovação

Cada block gera uma URL de portal única (<blockId.url>) com uma interface visual que mostra todos os dados de saída pausados e os campos do formulário de retomada. É responsivo em dispositivos móveis e seguro.

Compartilhe essa URL nas notificações para que as pessoas aprovadoras revisem e respondam.

API REST

Retome workflows programaticamente pelo recurso de run da v2. O contextId está disponível na saída resumeEndpoint do block ou no objeto _resume da resposta da execução pausada.

POST /api/v2/workflows/{workflowId}/runs/{runId}/resume
Content-Type: application/json
X-API-Key: your-api-key

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

O endpoint de retomada respeita automaticamente o modo de execução usado na chamada original de execute:

• Modo sync (padrão) — a resposta espera o restante do workflow terminar e retorna o resultado completo:

{
  "data": {
    "runId": "<resumeRunId>",
    "workflowId": "<workflowId>",
    "status": "completed",
    "output": { ... },
    "error": null,
    "startedAt": "...",
    "endedAt": "...",
    "durationMs": 1234
  }
}

Se o workflow retomado encontrar outro block HITL, a resposta retorna "status": "paused" com novas URLs _resume na saída.

• Modo stream (stream: true na chamada original de execute) — a resposta da retomada envia eventos SSE com chunks de selectedOutputs, igual à execução inicial.

• Modo async (async: true na chamada original de execute da v2) — a retomada despacha a execução para um worker em segundo plano e retorna imediatamente com 202, incluindo o runId da tentativa de retomada e a statusUrl da v2 para polling:

{
  "data": {
    "runId": "<resumeRunId>",
    "statusUrl": "/api/v2/workflows/<workflowId>/runs/<resumeRunId>"
  }
}

Consultar o status da execução

Faça polling na statusUrl da resposta async para saber quando a retomada termina:

GET /api/v2/workflows/{workflowId}/runs/{resumeRunId}?includeOutput=true
X-API-Key: your-api-key

Retorna o status da execução e, quando concluída, a saída completa do workflow.

O endpoint legado continua disponível sem mudanças de comportamento para integrações existentes:

POST /api/resume/{workflowId}/{executionId}/{contextId}

A resposta async dele continua expondo jobId e a URL legada de polling /api/jobs/{jobId}.

Para verificar os pontos de pausa e os links de retomada de uma execução pausada:

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

Retorna o detalhe da execução pausada com todos os pontos de pausa, seus status e os links de retomada. Retorna 404 quando a execução já terminou e não está mais pausada.

Webhook

Adicione uma ferramenta de webhook à seção Notification para enviar pedidos de aprovação a sistemas externos. Integre com sistemas de tickets como Jira ou ServiceNow.

A resposta inclui todos os dados da pausa, com as URLs de retomada:

{
  "data": {
    "runId": "<runId>",
    "workflowId": "<workflowId>",
    "status": "paused",
    "output": {
      "data": {
        "operation": "human",
        "_resume": {
          "apiUrl": "/api/resume/{workflowId}/{executionId}/{contextId}",
          "uiUrl": "/resume/{workflowId}/{executionId}",
          "contextId": "<contextId>",
          "executionId": "<executionId>",
          "workflowId": "<workflowId>"
        }
      }
    },
    "error": null
  }
}

Os blocks antes do HITL enviam seus selectedOutputs normalmente. Quando a execução pausa, o evento SSE final inclui status: "paused" e os dados de _resume:

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

Na retomada, os blocks depois do HITL enviam seus selectedOutputs da mesma forma.

Retorna 202 imediatamente. Use o endpoint de polling para saber quando a execução pausa.