Workflows HITL

Human-In-The-Loop (HITL) é uma abordagem poderosa que combina inteligência artificial com expertise humana para aprimorar a tomada de decisão e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro do CrewAI Enterprise.

Abordagens HITL no CrewAI

CrewAI oferece duas abordagens para implementar workflows human-in-the-loop:

Abordagem	Melhor Para	Versão
Baseada em Flow (decorador `@human_feedback`)	Produção com UI Enterprise, workflows email-first, recursos completos da plataforma	1.8.0+
Baseada em Webhook	Integrações customizadas, sistemas externos (Slack, Teams, etc.), configurações legadas	Todas as versões

HITL Baseado em Flow com Plataforma Enterprise

Ao usar o decorador @human_feedback em seus Flows, o CrewAI Enterprise oferece um sistema HITL email-first que permite que qualquer pessoa com um endereço de email responda a solicitações de revisão:

Design Email-First

Respondentes recebem notificações por email e podem responder diretamente—nenhum login necessário.

Revisão no Dashboard

Revise e responda a solicitações HITL no dashboard Enterprise quando preferir.

Roteamento Flexível

Direcione solicitações para emails específicos com base em padrões de método ou obtenha do estado do flow.

Resposta Automática

Configure respostas automáticas de fallback quando nenhum humano responder dentro do timeout.

Principais Benefícios

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 do estado do flow (ex: account_owner_email)
Configuração simples: Roteamento baseado em email é mais fácil de configurar do que gerenciamento de usuários/funções
Fallback do criador do deployment: Se nenhuma regra de roteamento corresponder, o criador do deployment é notificado

Configurando Workflows HITL Baseados em Webhook

Para integrações customizadas com sistemas externos como Slack, Microsoft Teams ou suas próprias aplicações, você pode usar a abordagem baseada em webhook:

Configure Sua Tarefa

Configure sua tarefa com a entrada humana habilitada:
Forneça o URL do Webhook

Ao iniciar seu crew, inclua um URL de webhook para entrada humana:
Receba a Notificação do Webhook

Assim que o crew concluir a tarefa que requer entrada humana, você receberá uma notificação do webhook contendo:
- ID de Execução
- ID da Tarefa
- Saída da Tarefa
Revise a Saída da Tarefa

O sistema irá pausar no estado Pending Human Input. Revise cuidadosamente a saída da tarefa.
Envie o Feedback Humano

Chame o endpoint de retomada do seu crew com as seguintes informações:

Warning

Crítico: URLs de Webhook Devem Ser Fornecidas Novamente: Você deve fornecer as mesmas URLs de webhook (taskWebhookUrl, stepWebhookUrl, crewWebhookUrl) na chamada de resume que você usou na chamada de kickoff. As configurações de webhook NÃO são automaticamente transferidas do kickoff - elas devem ser explicitamente incluídas na solicitação de resume para continuar recebendo notificações de conclusão de tarefa, etapas do agente e conclusão do crew.

Exemplo de chamada resume com webhooks:
Terminal window
```
curl -X POST {BASE_URL}/resume \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "task_id": "research_task",
    "human_feedback": "Ótimo trabalho! Por favor, adicione mais detalhes.",
    "is_approve": true,
    "taskWebhookUrl": "https://your-server.com/webhooks/task",
    "stepWebhookUrl": "https://your-server.com/webhooks/step",
    "crewWebhookUrl": "https://your-server.com/webhooks/crew"
  }'
```
Warning

Impacto do Feedback na Execução da Tarefa: É crucial ter cuidado ao fornecer o feedback, pois todo o conteúdo do feedback será incorporado como contexto adicional para as próximas execuções da tarefa.

Isso significa:
- Todas as informações do seu feedback passam a fazer parte do contexto da tarefa.
- Detalhes irrelevantes podem prejudicar a execução.
- Feedbacks concisos e relevantes ajudam a manter o foco e a eficiência da tarefa.
- Sempre revise atentamente seu feedback antes de enviá-lo para garantir que ele contém apenas informações pertinentes que irão guiar positivamente a execução da tarefa.
Lide com Feedback Negativo

Se você fornecer um feedback negativo:
- O crew irá tentar executar novamente a tarefa com o contexto adicional do seu feedback.
- Você receberá uma nova notificação de webhook para nova revisão.
- Repita os passos 4-6 até estar satisfeito.
Continuação da Execução

Quando você enviar um feedback positivo, a execução prosseguirá para as próximas etapas.

Melhores Práticas

Seja Específico: Forneça feedback claro e acionável que trate diretamente da tarefa em questão
Mantenha a Relevância: Inclua apenas informações que possam ajudar a melhorar a execução da tarefa
Seja Ágil: Responda rapidamente aos prompts HITL para evitar atrasos no workflow
Revise Cuidadosamente: Verifique duas vezes o seu feedback antes de enviá-lo para garantir precisão

Casos de Uso Comuns

Workflows HITL são particularmente valiosos para:

Garantia de qualidade e validação
Cenários de tomada de decisão complexa
Operações sensíveis ou de alto risco
Tarefas criativas que exigem julgamento humano
Revisões de conformidade e regulatórias

Saiba Mais

Gerenciamento HITL para Flows

Explore os recursos completos da plataforma HITL para Flows, incluindo notificações por email, regras de roteamento, resposta automática e análises.

Feedback Humano em Flows

Guia de implementação para o decorador @human_feedback em seus Flows.