Workflows HITL

Aprenda como implementar workflows Human-In-The-Loop no CrewAI para decisões aprimoradas

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

O decorador @human_feedback requer CrewAI versão 1.8.0 ou superior.

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

Para detalhes de implementação do decorador @human_feedback, consulte o guia Feedback Humano em Flows.

​

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:

1. Configure Sua Tarefa

   Configure sua tarefa com a entrada humana habilitada:

   
2. Forneça o URL do Webhook

   Ao iniciar seu crew, inclua um URL de webhook para entrada humana:

   
3. 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
4. Revise a Saída da Tarefa

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

5. Envie o Feedback Humano

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

   

   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:

   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"
     }'
   

   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.
6. 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.
7. 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.