crewAI/docs/pt-BR/enterprise/features/flow-hitl-management.mdx

---
title: "Gerenciamento HITL para Flows"
description: "Revisão humana de nível empresarial para Flows com notificações por email, regras de roteamento e capacidades de resposta automática"
icon: "users-gear"
mode: "wide"
---

<Note>
Os recursos de gerenciamento HITL para Flows requerem o decorador `@human_feedback`, disponível no **CrewAI versão 1.8.0 ou superior**. Estes recursos aplicam-se especificamente a **Flows**, não a Crews.
</Note>

O CrewAI Enterprise oferece um sistema abrangente de gerenciamento Human-in-the-Loop (HITL) para Flows que transforma fluxos de trabalho de IA em processos colaborativos humano-IA. A plataforma usa uma **arquitetura email-first** que permite que qualquer pessoa com um endereço de email responda a solicitações de revisão—sem necessidade de conta na plataforma.

## Visão Geral

<CardGroup cols={3}>
  <Card title="Design Email-First" icon="envelope">
    Respondentes podem responder diretamente aos emails de notificação para fornecer feedback
  </Card>
  <Card title="Roteamento Flexível" icon="route">
    Direcione solicitações para emails específicos com base em padrões de método ou estado do flow
  </Card>
  <Card title="Resposta Automática" icon="clock">
    Configure respostas automáticas de fallback quando nenhum humano responder a tempo
  </Card>
</CardGroup>

### Principais Benefícios

- **Modelo mental simples**: Endereços de email são universais; não é necessário gerenciar usuários ou funções da plataforma
- **Respondentes externos**: Qualquer pessoa com email pode responder, mesmo não sendo usuário da plataforma
- **Atribuição dinâmica**: Obtenha o email do responsável diretamente do estado do flow (ex: `sales_rep_email`)
- **Configuração reduzida**: Menos configurações para definir, tempo mais rápido para gerar valor
- **Email como canal principal**: A maioria dos usuários prefere responder via email do que fazer login em um dashboard

## Configurando Pontos de Revisão Humana em Flows

Configure checkpoints de revisão humana em seus Flows usando o decorador `@human_feedback`. Quando a execução atinge um ponto de revisão, o sistema pausa, notifica o responsável via email e aguarda uma resposta.

```python
from crewai.flow.flow import Flow, start, listen, or_
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult

class ContentApprovalFlow(Flow):
    @start()
    def generate_content(self):
        return "Texto de marketing gerado para campanha Q1..."

    @human_feedback(
        message="Por favor, revise este conteúdo para conformidade com a marca:",
        emit=["approved", "rejected", "needs_revision"],
    )
    @listen(or_("generate_content", "needs_revision"))
    def review_content(self):
        return "Texto de marketing para revisão..."

    @listen("approved")
    def publish_content(self, result: HumanFeedbackResult):
        print(f"Publicando conteúdo aprovado. Notas do revisor: {result.feedback}")

    @listen("rejected")
    def archive_content(self, result: HumanFeedbackResult):
        print(f"Conteúdo rejeitado. Motivo: {result.feedback}")
```

Para detalhes completos de implementação, consulte o guia [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows).

### Parâmetros do Decorador

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `message` | `str` | A mensagem exibida para o revisor humano |
| `emit` | `list[str]` | Opções de resposta válidas (exibidas como botões na UI) |

## Configuração da Plataforma

Acesse a configuração HITL em: **Deployment** → **Settings** → **Human in the Loop Configuration**

<Frame>
  <img src="/images/enterprise/hitl-settings-overview.png" alt="Configurações HITL" />
</Frame>

### Notificações por Email

Toggle para ativar ou desativar notificações por email para solicitações HITL.

| Configuração | Padrão | Descrição |
|--------------|--------|-----------|
| Notificações por Email | Ativado | Enviar emails quando feedback for solicitado |

<Note>
Quando desativado, os respondentes devem usar a UI do dashboard ou você deve configurar webhooks para sistemas de notificação personalizados.
</Note>

### Meta de SLA

Defina um tempo de resposta alvo para fins de rastreamento e métricas.

| Configuração | Descrição |
|--------------|-----------|
| Meta de SLA (minutos) | Tempo de resposta alvo. Usado para métricas do dashboard e rastreamento de SLA |

Deixe vazio para desativar o rastreamento de SLA.

## Notificações e Respostas por Email

O sistema HITL usa uma arquitetura email-first onde os respondentes podem responder diretamente aos emails de notificação.

### Como Funcionam as Respostas por Email

<Steps>
  <Step title="Notificação Enviada">
    Quando uma solicitação HITL é criada, um email é enviado ao respondente atribuído com o conteúdo e contexto da revisão.
  </Step>
  <Step title="Endereço Reply-To">
    O email inclui um endereço reply-to especial com um token assinado para autenticação.
  </Step>
  <Step title="Usuário Responde">
    O respondente simplesmente responde ao email com seu feedback—nenhum login necessário.
  </Step>
  <Step title="Validação do Token">
    A plataforma recebe a resposta, verifica o token assinado e corresponde o email do remetente.
  </Step>
  <Step title="Flow Continua">
    O feedback é registrado e o flow continua com a entrada humana.
  </Step>
</Steps>

### Formato de Resposta

Respondentes podem responder com:

- **Opção emit**: Se a resposta corresponder a uma opção `emit` (ex: "approved"), ela é usada diretamente
- **Texto livre**: Qualquer resposta de texto é passada para o flow como feedback
- **Texto simples**: A primeira linha do corpo da resposta é usada como feedback

### Emails de Confirmação

Após processar uma resposta, o respondente recebe um email de confirmação indicando se o feedback foi enviado com sucesso ou se ocorreu um erro.

### Segurança do Token de Email

- Tokens são assinados criptograficamente para segurança
- Tokens expiram após 7 dias
- Email do remetente deve corresponder ao email autorizado do token
- Emails de confirmação/erro são enviados após o processamento

## Regras de Roteamento

Direcione solicitações HITL para endereços de email específicos com base em padrões de método.

<Frame>
  <img src="/images/enterprise/hitl-settings-routing-rules.png" alt="Configuração de Regras de Roteamento HITL" />
</Frame>

### Estrutura da Regra

```json
{
  "name": "Aprovações para Financeiro",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "financeiro@empresa.com",
  "assign_from_input": "manager_email"
}
```

### Padrões de Correspondência

| Padrão | Descrição | Exemplo de Correspondência |
|--------|-----------|---------------------------|
| `approve_*` | Wildcard (qualquer caractere) | `approve_payment`, `approve_vendor` |
| `review_?` | Caractere único | `review_a`, `review_1` |
| `validate_payment` | Correspondência exata | apenas `validate_payment` |

### Prioridade de Atribuição

1. **Atribuição dinâmica** (`assign_from_input`): Se configurado, obtém email do estado do flow
2. **Email estático** (`assign_to_email`): Fallback para email configurado
3. **Criador do deployment**: Se nenhuma regra corresponder, o email do criador do deployment é usado

### Exemplo de Atribuição Dinâmica

Se seu estado do flow contém `{"sales_rep_email": "alice@empresa.com"}`, configure:

```json
{
  "name": "Direcionar para Representante de Vendas",
  "match": {
    "method_name": "review_*"
  },
  "assign_from_input": "sales_rep_email"
}
```

A solicitação será atribuída automaticamente para `alice@empresa.com`.

<Tip>
**Caso de Uso**: Obtenha o responsável do seu CRM, banco de dados ou etapa anterior do flow para direcionar revisões dinamicamente para a pessoa certa.
</Tip>

## Resposta Automática

Responda automaticamente a solicitações HITL se nenhum humano responder dentro do timeout. Isso garante que os flows não fiquem travados indefinidamente.

### Configuração

| Configuração | Descrição |
|--------------|-----------|
| Ativado | Toggle para ativar resposta automática |
| Timeout (minutos) | Tempo de espera antes de responder automaticamente |
| Resultado Padrão | O valor da resposta (deve corresponder a uma opção `emit`) |

<Frame>
  <img src="/images/enterprise/hitl-settings-auto-respond.png" alt="Configuração de Resposta Automática HITL" />
</Frame>

### Casos de Uso

- **Conformidade com SLA**: Garante que flows não fiquem travados indefinidamente
- **Aprovação padrão**: Aprove automaticamente solicitações de baixo risco após timeout
- **Degradação graciosa**: Continue com um padrão seguro quando revisores não estiverem disponíveis

<Warning>
Use resposta automática com cuidado. Ative apenas para revisões não críticas onde uma resposta padrão é aceitável.
</Warning>

## Processo de Revisão

### Interface do Dashboard

A interface de revisão HITL oferece uma experiência limpa e focada para revisores:

- **Renderização Markdown**: Formatação rica para conteúdo de revisão com destaque de sintaxe
- **Painel de Contexto**: Visualize estado do flow, histórico de execução e informações relacionadas
- **Entrada de Feedback**: Forneça feedback detalhado e comentários com sua decisão
- **Ações Rápidas**: Botões de opção emit com um clique com comentários opcionais

<Frame>
  <img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="Lista de Solicitações HITL Pendentes" />
</Frame>

### Métodos de Resposta

Revisores podem responder por três canais:

| Método | Descrição |
|--------|-----------|
| **Resposta por Email** | Responda diretamente ao email de notificação |
| **Dashboard** | Use a UI do dashboard Enterprise |
| **API/Webhook** | Resposta programática via API |

### Histórico e Trilha de Auditoria

Toda interação HITL é rastreada com uma linha do tempo completa:

- Histórico de decisões (aprovar/rejeitar/revisar)
- Identidade do revisor e timestamp
- Feedback e comentários fornecidos
- Método de resposta (email/dashboard/API)
- Métricas de tempo de resposta

## Análise e Monitoramento

Acompanhe o desempenho HITL com análises abrangentes.

### Dashboard de Desempenho

<Frame>
  <img src="/images/enterprise/hitl-metrics.png" alt="Dashboard de Métricas HITL" />
</Frame>

<CardGroup cols={2}>
  <Card title="Tempos de Resposta" icon="stopwatch">
    Monitore tempos de resposta médios e medianos por revisor ou flow.
  </Card>
  <Card title="Tendências de Volume" icon="chart-bar">
    Analise padrões de volume de revisão para otimizar capacidade da equipe.
  </Card>
  <Card title="Distribuição de Decisões" icon="chart-pie">
    Visualize taxas de aprovação/rejeição em diferentes tipos de revisão.
  </Card>
  <Card title="Rastreamento de SLA" icon="chart-line">
    Acompanhe a porcentagem de revisões concluídas dentro das metas de SLA.
  </Card>
</CardGroup>

### Auditoria e Conformidade

Capacidades de auditoria prontas para empresas para requisitos regulatórios:

- Histórico completo de decisões com timestamps
- Verificação de identidade do revisor
- Logs de auditoria imutáveis
- Capacidades de exportação para relatórios de conformidade

## Casos de Uso Comuns

<AccordionGroup>
  <Accordion title="Revisões de Segurança" icon="shield-halved">
    **Caso de Uso**: Automação de questionários de segurança internos com validação humana

    - IA gera respostas para questionários de segurança
    - Equipe de segurança revisa e valida precisão via email
    - Respostas aprovadas são compiladas na submissão final
    - Trilha de auditoria completa para conformidade
  </Accordion>

  <Accordion title="Aprovação de Conteúdo" icon="file-lines">
    **Caso de Uso**: Conteúdo de marketing que requer revisão legal/marca

    - IA gera texto de marketing ou conteúdo de mídia social
    - Roteie para email da equipe de marca para revisão de voz/tom
    - Publicação automática após aprovação
  </Accordion>

  <Accordion title="Aprovações Financeiras" icon="money-bill">
    **Caso de Uso**: Relatórios de despesas, termos de contrato, alocações de orçamento

    - IA pré-processa e categoriza solicitações financeiras
    - Roteie com base em limites de valor usando atribuição dinâmica
    - Mantenha trilha de auditoria completa para conformidade financeira
  </Accordion>

  <Accordion title="Atribuição Dinâmica do CRM" icon="database">
    **Caso de Uso**: Direcione revisões para proprietários de conta do seu CRM

    - Flow obtém email do proprietário da conta do CRM
    - Armazene email no estado do flow (ex: `account_owner_email`)
    - Use `assign_from_input` para direcionar automaticamente para a pessoa certa
  </Accordion>

  <Accordion title="Garantia de Qualidade" icon="magnifying-glass">
    **Caso de Uso**: Validação de saída de IA antes da entrega ao cliente

    - IA gera conteúdo ou respostas voltadas ao cliente
    - Equipe de QA revisa via notificação por email
    - Loops de feedback melhoram desempenho da IA ao longo do tempo
  </Accordion>
</AccordionGroup>

## API de Webhooks

Quando seus Flows pausam para feedback humano, você pode configurar webhooks para enviar dados da solicitação para sua própria aplicação. Isso permite:

- Construir UIs de aprovação personalizadas
- Integrar com ferramentas internas (Jira, ServiceNow, dashboards personalizados)
- Rotear aprovações para sistemas de terceiros
- Notificações em apps mobile
- Sistemas de decisão automatizados

<Frame>
  <img src="/images/enterprise/hitl-settings-webhook.png" alt="Configuração de Webhook HITL" />
</Frame>

### Configurando Webhooks

<Steps>
  <Step title="Navegue até Configurações">
    Vá para **Deployment** → **Settings** → **Human in the Loop**
  </Step>
  <Step title="Expanda a Seção Webhooks">
    Clique para expandir a configuração de **Webhooks**
  </Step>
  <Step title="Adicione sua URL de Webhook">
    Digite sua URL de webhook (deve ser HTTPS em produção)
  </Step>
  <Step title="Salve a Configuração">
    Clique em **Salvar Configuração** para ativar
  </Step>
</Steps>

Você pode configurar múltiplos webhooks. Cada webhook ativo recebe todos os eventos HITL.

### Eventos de Webhook

Seu endpoint receberá requisições HTTP POST para estes eventos:

| Tipo de Evento | Quando é Disparado |
|----------------|-------------------|
| `new_request` | Um flow pausa e solicita feedback humano |

### Payload do Webhook

Todos os webhooks recebem um payload JSON com esta estrutura:

```json
{
  "event": "new_request",
  "request": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_id": "flow_abc123",
    "method_name": "review_article",
    "message": "Por favor, revise este artigo para publicação.",
    "emit_options": ["approved", "rejected", "request_changes"],
    "state": {
      "article_id": 12345,
      "author": "john@example.com",
      "category": "technology"
    },
    "metadata": {},
    "created_at": "2026-01-14T12:00:00Z"
  },
  "deployment": {
    "id": 456,
    "name": "Content Review Flow",
    "organization_id": 789
  },
  "callback_url": "https://api.crewai.com/...",
  "assigned_to_email": "reviewer@company.com"
}
```

### Respondendo a Solicitações

Para enviar feedback, **faça POST para a `callback_url`** incluída no payload do webhook.

```http
POST {callback_url}
Content-Type: application/json

{
  "feedback": "Aprovado. Ótimo artigo!",
  "source": "my_custom_app"
}
```

### Segurança

<Info>
Todas as requisições de webhook são assinadas criptograficamente usando HMAC-SHA256 para garantir autenticidade e prevenir adulteração.
</Info>

#### Segurança do Webhook

- **Assinaturas HMAC-SHA256**: Todo webhook inclui uma assinatura criptográfica
- **Secrets por webhook**: Cada webhook tem seu próprio secret de assinatura único
- **Criptografado em repouso**: Os secrets de assinatura são criptografados no nosso banco de dados
- **Verificação de timestamp**: Previne ataques de replay

#### Headers de Assinatura

Cada requisição de webhook inclui estes headers:

| Header | Descrição |
|--------|-----------|
| `X-Signature` | Assinatura HMAC-SHA256: `sha256=<hex_digest>` |
| `X-Timestamp` | Timestamp Unix de quando a requisição foi assinada |

#### Verificação

Verifique computando:

```python
import hmac
import hashlib

expected = hmac.new(
    signing_secret.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected, signature):
    # Assinatura válida
```

### Tratamento de Erros

Seu endpoint de webhook deve retornar um código de status 2xx para confirmar o recebimento:

| Sua Resposta | Nosso Comportamento |
|--------------|---------------------|
| 2xx | Webhook entregue com sucesso |
| 4xx/5xx | Registrado como falha, sem retry |
| Timeout (30s) | Registrado como falha, sem retry |

## Segurança e RBAC

### Acesso ao Dashboard

O acesso HITL é controlado no nível do deployment:

| Permissão | Capacidade |
|-----------|------------|
| `manage_human_feedback` | Configurar settings HITL, ver todas as solicitações |
| `respond_to_human_feedback` | Responder a solicitações, ver solicitações atribuídas |

### Autorização de Resposta por Email

Para respostas por email:
1. O token reply-to codifica o email autorizado
2. Email do remetente deve corresponder ao email do token
3. Token não deve estar expirado (padrão 7 dias)
4. Solicitação ainda deve estar pendente

### Trilha de Auditoria

Todas as ações HITL são registradas:
- Criação de solicitação
- Mudanças de atribuição
- Submissão de resposta (com fonte: dashboard/email/API)
- Status de retomada do flow

## Solução de Problemas

### Emails Não Enviando

1. Verifique se "Notificações por Email" está ativado na configuração
2. Verifique se as regras de roteamento correspondem ao nome do método
3. Verifique se o email do responsável é válido
4. Verifique o fallback do criador do deployment se nenhuma regra de roteamento corresponder

### Respostas de Email Não Processando

1. Verifique se o token não expirou (padrão 7 dias)
2. Verifique se o email do remetente corresponde ao email atribuído
3. Garanta que a solicitação ainda está pendente (não respondida ainda)

### Flow Não Retomando

1. Verifique o status da solicitação no dashboard
2. Verifique se a URL de callback está acessível
3. Garanta que o deployment ainda está rodando

## Melhores Práticas

<Tip>
**Comece Simples**: Comece com notificações por email para o criador do deployment, depois adicione regras de roteamento conforme seus fluxos de trabalho amadurecem.
</Tip>

1. **Use Atribuição Dinâmica**: Obtenha emails de responsáveis do seu estado do flow para roteamento flexível.

2. **Configure Resposta Automática**: Defina um fallback para revisões não críticas para evitar que flows fiquem travados.

3. **Monitore Tempos de Resposta**: Use análises para identificar gargalos e otimizar seu processo de revisão.

4. **Mantenha Mensagens de Revisão Claras**: Escreva mensagens claras e acionáveis no decorador `@human_feedback`.

5. **Teste o Fluxo de Email**: Envie solicitações de teste para verificar a entrega de email antes de ir para produção.

## Recursos Relacionados

<CardGroup cols={2}>
  <Card title="Feedback Humano em Flows" icon="code" href="/pt-BR/learn/human-feedback-in-flows">
    Guia de implementação para o decorador `@human_feedback`
  </Card>
  <Card title="Guia de Workflow HITL para Flows" icon="route" href="/pt-BR/enterprise/guides/human-in-the-loop">
    Guia passo a passo para configurar workflows HITL
  </Card>
  <Card title="Configuração RBAC" icon="shield-check" href="/pt-BR/enterprise/features/rbac">
    Configure controle de acesso baseado em função para sua organização
  </Card>
  <Card title="Streaming de Webhook" icon="bolt" href="/pt-BR/enterprise/features/webhook-streaming">
    Configure notificações de eventos em tempo real
  </Card>
</CardGroup>