Handoff é a transferência do atendimento da ClaudIA para um agente humano (N2). Na ClaudIA Agêntica, esse mecanismo funciona de forma diferente do que pode parecer intuitivo.
⚙️ Como funciona tecnicamente
O handoff não acontece automaticamente quando um Sub-agente detecta uma situação crítica. O único mecanismo de transferência.
Supervisor tem acesso a uma tool universal chamada handoff_to_human.
O Supervisor pode acionar essa tool a qualquer momento que achar que a conversa precisa ser escalada para um humano ou um especialista. Isso pode vir dele ou pode vir do sub-agent.
O fluxo completo:
-
O Sub-agente retorna uma sinalização para o Supervisor: "pedido em atraso — encaminhar para humano"
-
O Supervisor lê esse retorno
-
O Supervisor chama a tool
handoff_to_human -
A transferência é executada no sistema
-
O Supervisor informa o cliente sobre a transferência
⚠️ Regra crítica: descrever ≠ executar
Se o Sub-agente retornar "encaminhar para humano" em texto mas o Supervisor não reconhecer isso como gatilho para chamar a tool, o handoff não acontece. O ticket continua com a IA — mesmo que a resposta mencione uma transferência.
📋 Quando sinalizar handoff
Os Sub-agentes devem sinalizar handoff nas situações que você julgar necessarias.
O Supervisor pode também acionar essa tool por conta própria de acordo com as diretrizes globais da Cloud Humans (por exemplo frustração ou se não conseguir entender a dúvida do cliente).
Cada uma das situações deve estar explicitamente mapeada no system prompt do Sub-agente responsável — o "senso comum" da IA não é suficiente (apesar de ser um ótimo fallback).
✍️ Como configurar corretamente
No system prompt do Sub-agente
Mapeie cada cenário de escalação de forma explícita. Exemplo:
"Cenário: pedido com data de previsão vencida. Sempre que a data de previsão for anterior à data atual, sinalizar para o Supervisor encaminhar para humano — independente de o rastreio estar disponível ou não."
Não confie somente que a IA vai inferir que uma situação requer handoff. Se não está escrito, não acontece de forma 100% confiável.
A instrução deve ser inequívoca: a tool é chamada primeiro, a explicação vem depois.
🐛 Caso real: o que acontece quando o handoff falha
Situação: Um cliente consultou um pedido que estava em atraso. A ClaudIA identificou o atraso, respondeu com link de rastreio.
Causa:
- O system prompt do Sub-agente não tinha cenário específico para pedido em atraso — cobria um pedido em atraso da mesma forma que os outros, busca a informação e responde o cliente quer, se ajuste para caso de atraso.
Como foi corrigido:
- Sub-agente: adicionado cenário explícito — "pedido em atraso = sinalizar handoff, independente de rastreio disponível"
Aprendizado: prompts com contradições internas são especialmente perigosos em situações de handoff. Teste os cenários de escalação ativamente — não apenas os de resolução.
✅ Checklist de configuração do handoff
-
Cada cenário de escalação está explicitamente mapeado no system prompt do Sub-agente?
-
O handoff foi testado ativamente no Playground para os cenários críticos?