Principal Primeiros passos Como funciona o handoff para humano na ClaudIA Agêntica

Como funciona o handoff para humano na ClaudIA Agêntica

Última atualização em May 21, 2026

Quando usar

  • Você precisa entender por que o handoff falhou num caso específico

  • Você está configurando os cenários de escalação no system prompt do Sub-agente

  • Você quer evitar o erro de descrever sem executar o handoff

Pré-requisitos

  • Sub-agente já criado com system prompt configurado

  • Acesso ao Playground para testar cenários de handoff

Sobre este artigo

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 é a tool handoff_to_human.

O Supervisor tem acesso a uma tool universal chamada handoff_to_human. Ele pode acioná-la quando achar que a conversa precisa ser escalada (por iniciativa própria ou por sinalização do Sub-agente).

Fluxo completo

  1. O Sub-agente retorna sinalização para o Supervisor: "pedido em atraso — encaminhar para humano"

  2. O Supervisor lê esse retorno

  3. O Supervisor chama a tool handoff_to_human

  4. A transferência é executada no sistema

  5. 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, o handoff não acontece. O ticket continua com a IA — mesmo que a resposta mencione transferência.

Quando sinalizar handoff

Os Sub-agentes devem sinalizar handoff nas situações que você julgar necessárias.

O Supervisor também pode acionar a tool por conta própria de acordo com diretrizes globais (ex: frustração ou se não conseguir entender a dúvida).

Cada situação deve estar explicitamente mapeada no system prompt do Sub-agente — o "senso comum" da IA não é suficiente (apesar de ser um bom fallback).

Como configurar corretamente

No system prompt do Sub-agente

Mapeie cada cenário de escalação de forma explícita:

"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 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 — quando o handoff falha

Situação: cliente consultou um pedido em atraso. A ClaudIA identificou o atraso, mas respondeu apenas com link de rastreio em vez de escalar.

Causa: o system prompt do Sub-agente não tinha cenário específico para pedido em atraso — cobria pedido em atraso da mesma forma que os outros (busca info e responde o que o cliente quer, sem ajuste para o 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

  • 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?

Observações