Gerenciamento HITL para Flows

​

Visão Geral

​

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

from crewai.flow.flow import Flow, start, listen
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult

class ContentApprovalFlow(Flow):
    @start()
    def generate_content(self):
        # IA gera conteúdo
        return "Texto de marketing gerado para campanha Q1..."

    @listen(generate_content)
    @human_feedback(
        message="Por favor, revise este conteúdo para conformidade com a marca:",
        emit=["approved", "rejected", "needs_revision"],
    )
    def review_content(self, content):
        return content

    @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}")

    @listen("needs_revision")
    def revise_content(self, result: HumanFeedbackResult):
        print(f"Revisão solicitada: {result.feedback}")

​

Parâmetros do Decorador

​

Configuração da Plataforma

​

Notificações por Email

​

Meta de SLA

​

Notificações e Respostas por Email

​

Como Funcionam as Respostas por Email

​

Formato de Resposta

• 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

​

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

​

Estrutura da Regra

{
  "name": "Aprovações para Financeiro",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "[email protected]",
  "assign_from_input": "manager_email"
}

​

Padrões de Correspondência

​

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

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

​

Resposta Automática

​

Configuração

​

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

​

Processo de Revisão

​

Interface do Dashboard

• 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

​

Métodos de Resposta

​

Histórico e Trilha de Auditoria

• 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

​

Dashboard de Desempenho

​

Auditoria e Conformidade

• 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

​

API de Webhooks

• 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

​

Configurando Webhooks

​

Eventos de Webhook

​

Payload do Webhook

{
  "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": "[email protected]",
      "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": "[email protected]"
}

​

Respondendo a Solicitações

POST {callback_url}
Content-Type: application/json

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

​

Segurança

​

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

​

Verificação

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

​

Segurança e RBAC

​

Acesso ao Dashboard

​

Autorização de Resposta 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

• 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

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