#Transferir uma conversa do seu agente de IA para uma pessoa

Transferir para uma pessoa é como um agente de IA passa uma conversa para alguém da sua equipe quando não deve, ou não consegue, resolver sozinho. Com a Vatio você declara isso no seu vatio.yml: handoff.when lista os casos com as suas palavras e after_turns define um piso. O horário de atendimento, que quem toca o negócio define na página Negócio do inbox, diz quando tem alguém de plantão. A conversa aparece como aguardando no inbox, quem responde assume, e o agente retoma quando a conversa é devolvida, no WhatsApp, no Instagram e na web do mesmo jeito.

#O que é a transferência e por que importa

Algumas conversas precisam de uma pessoa: uma entrega que chegou danificada, uma cobrança contestada, um cliente irritado, qualquer coisa que o negócio queira que alguém da equipe avalie. Um agente que segue em frente nesses momentos piora a situação; um que transfere tudo é um formulário de contato com passos a mais.

Na Vatio, a transferência é feita de duas metades. O julgamento do modelo segue as condições que você escreve. Os gatilhos determinísticos pegam o que o julgamento poderia deixar passar: um visitante que pede um humano, ou uma conversa que se arrastou demais. E o agente é honesto do começo ao fim. Ele diz com clareza que é um assistente, e quando transfere algo diz ao visitante que está consultando um colega e que vai voltar com uma resposta, sem inventar uma desculpa para encobrir isso. Várias jurisdições exigem informar que a pessoa está falando com uma máquina; confira o que a sua exige.

#Como funciona

1. Declarar handoff dá ao agente a tool de transferência. Sem o bloco, ele não tem como escalar.
2. O agente chama a tool quando uma condição de handoff.when se aplica e ele não consegue resolver o caso sozinho. Duas coisas disparam a transferência de qualquer forma: um visitante que pede um humano com todas as letras, e chegar a after_turns mensagens do visitante.
3. A conversa fica marcada como aguardando uma pessoa no inbox. A Vatio ainda não avisa ninguém.
4. O horário de atendimento decide o que o agente faz em seguida:

5. Quem responde assume a conversa, pelo inbox ou pelo app do WhatsApp Business no seu próprio número. O agente fica fora daquele chat.
6. A conversa volta quando alguém devolve, ou quando a intervenção expira.

Sem horário definido, considera-se que sempre tem alguém, então toda transferência deixa o agente em silêncio, às 3 da manhã também. Uma transferência que ninguém assume em uma hora volta para o agente, em vez de deixar o visitante com uma promessa e silêncio.

#Passo a passo

#1. Escreva o handoff.when com as suas palavras

Cada condição é uma frase curta que vai para o prompt. Escreva os casos que o negócio citou, tão específicos quanto ele citou:

handoff:
  when:
    - um móvel chegou danificado ou incompleto
    - o cliente pede reembolso ou contesta uma cobrança
    - um orçamento de mais de dez móveis, ou para uma empresa

“Uma reclamação sobre uma cobrança” é uma condição que um modelo consegue reconhecer. “Situações difíceis” não é.

#2. Defina o after_turns como piso

handoff:
  after_turns: 10

Passado esse número de mensagens do visitante, a transferência acontece mesmo que o modelo não tenha pedido. Ele conta as mensagens do visitante, não a troca inteira. Escolha um número acima do tamanho de uma conversa normal que dá certo, para que só as que travaram cheguem lá.

#3. Defina os horários em que realmente tem alguém

O horário não vai no vatio.yml. Ele é de quem atende, então quem toca o negócio o define na página Negócio do inbox: um fuso horário e um ou mais turnos por dia, como segunda das 9:00 às 12:00 e das 13:00 às 18:00, com o almoço no meio, e sábado das 9:00 às 13:00. Ou marca que sempre tem alguém disponível. Vale para todos os ambientes assim que é salvo.

Um dia sem turnos é um dia sem ninguém de plantão. O horário não decide quando o agente responde, porque ele responde a qualquer hora. Decide se uma transferência deixa o agente em silêncio. O agente também recebe a semana, então sabe dizer ao cliente quando vocês atendem. Os detalhes estão na documentação de horário de atendimento.

#4. Diga ao agente o que reunir antes

Quem assume a conversa não deveria ter que começar do zero. Uma linha nas instruções resolve: “Antes de transferir uma conversa sobre um pedido, peça o número do pedido.”

#5. Faça push e teste

vatio push
vatio chat "A mesa chegou com um pé quebrado"
vatio chat --new "Quero falar com uma pessoa"
vatio chat show

A primeira deveria terminar em uma chamada a handoff, que o chat show lista junto com as outras chamadas de tools do agente; a segunda é um pedido de pessoa, que sempre tem que terminar transferido. No inbox, com o ambiente preview selecionado, as duas deveriam aparecer como aguardando.

#Assumir a conversa e devolver

Os supervisores são convidados em Equipe no inbox. No inbox eles veem cada conversa e as chamadas de tools do agente, e responder é assumir a conversa: o agente para de responder naquele chat. No WhatsApp, uma resposta pelo app do WhatsApp Business no seu número conectado conta do mesmo jeito, então a equipe pode continuar usando o celular.

Quando terminam, Devolver ao agente no inbox devolve a conversa. Se ninguém fizer isso, a intervenção expira 8 horas depois da última mensagem do visitante, e o agente retoma na próxima vez que ele escrever. Cada resposta humana reinicia esse relógio, então uma conversa que alguém está atendendo nunca expira na mão dessa pessoa.

Enquanto leem, os supervisores também podem marcar uma resposta que deveria ter sido uma transferência e escrever o que o agente deveria ter feito. Essa nota vira um caso de eval, e a correção muitas vezes vai parar no handoff.when; veja Melhorar seu agente.

#Ninguém recebe aviso ainda

Diga isso com todas as letras a quem cuida do inbox: a Vatio não envia notificação quando uma conversa é transferida. Ela aparece como aguardando no inbox, e só. Por isso:

• Alguém precisa ficar de olho no inbox durante o horário definido na página Negócio.
• Se ninguém olha aos sábados, deixe o sábado de fora. Assim o agente continua ajudando em vez de ficar uma hora em silêncio enquanto ninguém aparece.

#Um exemplo completo

A Móveis Jacarandá vende móveis pela internet e atende no WhatsApp e no site. A equipe trabalha de segunda a sexta das 9:00 às 18:00 com uma hora de almoço ao meio-dia, até as 17:00 na sexta, e no sábado das 9:00 às 13:00; é isso que está na página Negócio do inbox. O vatio.yml:

workspace: moveis-jacaranda
agent:
  name: Móveis Jacarandá
  personality: Simpático e breve. Palavras simples.
  instructions: |
    Você ajuda os clientes da Móveis Jacarandá com produtos, prazos de
    entrega e o status dos pedidos.

    Pedidos: peça o número do pedido e o email usado na compra, e chame
    status_pedido. Só informe uma data de entrega que status_pedido
    tenha devolvido.

    Produtos, regiões de entrega, montagem e a política de trocas: busque
    primeiro em knowledge_lookup. Se não encontrar a resposta, diga isso
    e ofereça passar a pergunta para a equipe.

    Antes de transferir uma conversa sobre um pedido, peça o número do
    pedido para que quem assumir já tenha.

    Regras que você nunca quebra:
    - Nunca prometa reembolso, desconto ou troca.
    - Nunca diga que uma entrega foi reagendada se status_pedido não disser.
  tools: [status_pedido, knowledge_lookup]
  knowledge: [loja]
  handoff:
    after_turns: 10
    when:
      - um móvel chegou danificado ou incompleto
      - o cliente pede reembolso ou contesta uma cobrança
      - um orçamento de mais de dez móveis, ou para uma empresa
      - o cliente está irritado com uma entrega que não chegou

Em um sábado às 16h, fora do horário:

Cliente: a mesa chegou com um pé quebrado [foto]

Agente: Poxa, sinto muito, isso não deveria acontecer. Qual é o número do seu pedido?

Cliente: MJ-20931

Agente: Obrigado. Sou o assistente da Móveis Jacarandá, então estou consultando um colega, e a equipe vai te responder por aqui na segunda de manhã. Posso ajudar com mais alguma coisa enquanto isso?

O agente pediu o número do pedido, como mandam as instruções, e depois chamou handoff porque um móvel chegou danificado. Como estava fora do horário, continuou respondendo. Na segunda, alguém da equipe abre a conversa no inbox, responde, e a conversa fica com essa pessoa até ela devolver. A mesma mensagem numa terça às 11h teria deixado o agente em silêncio na hora, com alguém de plantão para responder.

#Erros comuns

• Um horário que não bate com a realidade. Dentro do horário de atendimento, uma transferência deixa o agente em silêncio. Se ninguém está olhando, o visitante espera até uma hora antes de o agente retomar a conversa.
• Nenhum horário na página Negócio. Toda transferência deixa o agente em silêncio, de madrugada também.
• Condições vagas. “Quando complicar” não é algo que um modelo consiga aplicar de forma consistente.
• Um after_turns baixo demais. Uma conversa longa mas saudável, como um orçamento cheio de detalhes, é transferida no meio do caminho.
• Uma intervenção esquecida. O agente fica fora daquele chat até alguém devolver ou passarem 8 horas da última mensagem do visitante. Se um agente “parou de responder” um chat, veja primeiro se alguém assumiu.
• Pedir ao agente que finja ser uma pessoa. Não escreva um nome humano e uma história nas instruções; o agente diz aos visitantes que é um assistente.
• Transferir em vez de corrigir. Se a mesma pergunta chega às pessoas toda hora, marque a resposta e dê ao agente o conhecimento ou a tool que faltava.

#Próximos passos

Para o que o agente nunca deve dizer, mesmo antes de transferir, leia Salvaguardas. Para os detalhes do WhatsApp, incluindo o app Business, veja Um agente de IA no WhatsApp. A referência está na documentação de transferência.

Atualizado: 11 de outubro de 2026