#Agente de IA para logística e transportadoras

Um agente de IA para uma transportadora ou empresa de last mile responde o “cadê minha encomenda?” no WhatsApp: consulta o código de rastreio, informa o status e a janela de entrega, remarca uma entrega malsucedida ou manda a encomenda para um ponto de retirada, e abre uma reclamação quando algo chega danificado. Mudanças pedem o código de rastreio e o CEP, conferidos pelo seu backend, e tudo o que exige julgamento vai para uma pessoa. Com a Vatio você descreve esse agente em um arquivo vatio.yml, e ele responde no seu próprio número de WhatsApp e no seu site.

Este guia monta um de ponta a ponta: as instruções, as tools que chegam aos seus sistemas de rastreamento e roteirização, o conhecimento que ele lê, e as checagens que impedem que um código de rastreio baste para desviar a encomenda de outra pessoa.

#O que o agente resolve

O que chega para uma transportadora é quase sempre as mesmas cinco conversas:

• Rastreamento. “Cadê minha encomenda?” O agente pede o código de rastreio e responde com o status, a última leitura e a janela de entrega.
• Entregas malsucedidas. Não tinha ninguém em casa. O agente oferece um novo dia e período, ou um ponto de retirada, e agenda a opção que o cliente escolher.
• Pontos de retirada. Qual fica mais perto, o horário, quantos dias a encomenda espera ali, o que levar.
• Encomendas danificadas ou incompletas. O cliente manda uma foto, o agente abre uma reclamação e passa a conversa para uma pessoa.
• Janelas de entrega e cobertura. O que significa “à tarde”, se vocês entregam aos sábados, quais regiões vocês atendem.

O seu sistema continua decidindo quando avisar: ele continua enviando os avisos de “saiu para entrega” e “não encontramos você”, como hoje ou pelo WhatsApp com a Messages API da Vatio, e o agente cuida das respostas.

Uma conversa típica no WhatsApp:

Cliente: oi, ontem não consegui receber a encomenda. vocês podem trazer de novo?

Agente: Claro. Me passa o código de rastreio? Ele começa com TE e está no aviso que o entregador deixou.

Cliente: TE48213977

Agente: Achei: uma tentativa ontem às 14:12, ninguém atendeu. Posso levar amanhã das 9:00 às 13:00 ou das 14:00 às 19:00, ou mandar para o ponto de retirada da Rua das Palmeiras. Para mudar a entrega também preciso do CEP do endereço.

Por trás da última resposta houve uma chamada a rastrear_envio, que devolveu a tentativa malsucedida e as opções. O agente pede o CEP porque mudar uma entrega é justamente onde o código de rastreio sozinho não basta. Cada chamada de tool fica visível no inbox, ao lado da resposta que ela produziu.

#Antes de escrever qualquer coisa: cinco perguntas para o time de operações

1. Quem escreve, e sobre o quê? Normalmente rastreamento, entregas malsucedidas e pontos de retirada, e depois avarias.
2. O que um código de rastreio sozinho pode revelar? Status, última leitura e janela. Nunca o nome, o endereço ou o telefone do destinatário.
3. O que o agente pode mudar, e com qual prova? Uma nova data de entrega ou um ponto de retirada, com o código de rastreio mais o CEP. Mudança de endereço, normalmente nenhuma.
4. Quando uma pessoa assume? Avarias, encomendas “entregues” que nunca chegaram, encomendas sem leitura há dias, reclamações sobre um entregador.
5. De quais sistemas ele lê? A API de rastreamento, o sistema de roteirização ou agendamento, a lista de pontos de retirada, o sistema de reclamações.

As respostas viram as instruções, as condições de handoff, as tools e o conhecimento.

#O vatio.yml

workspace: tucano-entregas
agent:
  name: Tucano Entregas
  personality: Simpático, direto e breve. Primeiro a resposta, depois a explicação.
  instructions: |
    Você ajuda os clientes da Tucano Entregas a rastrear encomendas,
    remarcar entregas malsucedidas, encontrar pontos de retirada e
    informar encomendas danificadas.

    Rastreamento: peça o código de rastreio e chame rastrear_envio.
    Informe o status, a última leitura e a janela de entrega que ela
    devolveu. Nunca chute um horário de entrega que a tool não devolveu.

    Entregas malsucedidas: ofereça as opções que rastrear_envio devolveu.
    Antes de chamar remarcar_entrega, peça o CEP do endereço de entrega e
    repita a nova data para o cliente. Só confirme uma nova entrega quando
    remarcar_entrega a tiver devolvido. Se falhar porque o CEP não bate,
    diga que não consegue mudar essa encomenda e não dê pistas do CEP certo.

    Pontos de retirada: chame pontos_retirada com o CEP do cliente.

    Encomendas danificadas ou incompletas: peça o código de rastreio, o
    CEP e uma foto. Descreva o dano que você vê, chame abrir_reclamacao,
    informe o número de protocolo que ela devolveu e depois transfira a
    conversa para uma pessoa.

    Regras que você nunca quebra:
    - Nunca compartilhe o nome, o endereço ou o telefone de um
      destinatário.
    - Nunca mude um endereço de entrega.
    - Nunca prometa indenização nem reembolso.
    - Nunca diga a um cliente que uma encomenda foi extraviada; isso quem
      decide é uma pessoa.
  tools: [rastrear_envio, remarcar_entrega, pontos_retirada, abrir_reclamacao, knowledge_lookup]
  knowledge: [entregas]
  handoff:
    after_turns: 10
    when:
      - foi aberta uma reclamação por encomenda danificada ou incompleta
      - o rastreio diz entregue e o cliente diz que nunca chegou
      - a encomenda está há mais de três dias sem leitura
      - uma reclamação sobre um entregador
      - o cliente quer mudar o endereço de entrega

Algumas escolhas que vale explicar:

• Rastreamento é público; mudanças pedem um segundo dado. O código de rastreio vem impresso na caixa e é encaminhado por e-mail, então qualquer pessoa pode ter um. Para ver um status, tudo bem. Para mandar a encomenda para outro lugar, não basta.
• “Nunca chute um horário de entrega.” Um “chega até o meio-dia” inventado é como uma conversa de suporte vira duas.
• O agente abre a reclamação; uma pessoa decide. Reunir o código de rastreio, a foto e uma descrição às 23:00 é exatamente o trabalho do agente. A indenização não é.
• O horário de atendimento decide o que acontece depois de uma transferência. Ele não vai no vatio.yml: a operação o define na página Negócio do inbox, por exemplo segunda a sexta das 8:00 às 20:00 e sábado das 9:00 às 14:00. Dentro do horário o agente fica em silêncio para uma pessoa assumir. Fora dele continua ajudando e avisa o cliente que o time responde de manhã. A Vatio ainda não notifica ninguém de uma transferência; a conversa aparece como aguardando no inbox.

#Tools: rastreamento, remarcação e reclamações

Uma tool é um request HTTP para o seu backend, descrito em YAML. Guarde o endereço e a chave como secrets:

vatio secrets set TUCANO_API https://api.tucano-entregas.example
vatio secrets set TUCANO_API_KEY sk_live_...

tools/rastrear_envio.yml:

description: Consulta o status de uma encomenda, a última leitura, a janela de entrega e as opções depois de uma tentativa malsucedida.
when_to_use: O cliente pergunta onde está uma encomenda, quando chega ou por que não foi entregue.
parameters:
  type: object
  properties:
    codigo_rastreio: { type: string, description: "Começa com TE, por exemplo TE48213977" }
  required: [codigo_rastreio]
access: public
request:
  method: GET
  base_url: "$env.TUCANO_API"
  path: "/encomendas/$params.codigo_rastreio"
  requires: [params.codigo_rastreio]
  headers:
    Authorization: "Bearer $env.TUCANO_API_KEY"
respond:
  data:
    encomenda: "$.encomenda"

tools/remarcar_entrega.yml:

description: Agenda uma nova tentativa de entrega ou manda a encomenda para um ponto de retirada.
when_to_use: Uma entrega não deu certo ou o cliente não vai estar em casa, e ele escolheu uma opção de rastrear_envio.
parameters:
  type: object
  properties:
    codigo_rastreio: { type: string }
    cep: { type: string, description: "Do endereço de entrega, como o cliente informar" }
    data: { type: string, description: "AAAA-MM-DD, para uma nova entrega" }
    periodo: { type: string, enum: [manhã, tarde] }
    ponto_retirada_id: { type: string, description: "No lugar de data e período" }
  required: [codigo_rastreio, cep]
access: public
request:
  method: POST
  base_url: "$env.TUCANO_API"
  path: /remarcacoes
  requires: [params.codigo_rastreio, params.cep]
  headers:
    Authorization: "Bearer $env.TUCANO_API_KEY"
  body:
    codigo_rastreio: "$params.codigo_rastreio"
    cep: "$params.cep"
    data: "$params.data"
    periodo: "$params.periodo"
    ponto_retirada_id: "$params.ponto_retirada_id"
respond:
  data:
    entrega: "$.entrega"

Valores ausentes ficam fora do request, então o mesmo endpoint recebe uma nova data ou um ponto de retirada, e o seu backend decide qual chegou. pontos_retirada é um GET por CEP que devolve os pontos mais próximos com seus horários. abrir_reclamacao é um POST com o código de rastreio, o CEP, o tipo de problema e a descrição do dano feita pelo agente.

O seu backend confere se o CEP bate com o destino da encomenda antes de remarcar ou abrir uma reclamação, e responde 403 quando não bate. Quem preenche os parâmetros de uma tool é o modelo, então essa checagem tem que morar no código, não no prompt. Limite também as tentativas nesses endpoints: um código de rastreio mais um CEP dá para adivinhar se ninguém contar as tentativas. E faça rastrear_envio devolver só o que um desconhecido com a etiqueta na mão pode ver; o que a tool devolve é o que o modelo pode repetir.

Devolva status reais: 404 para um código de rastreio que não existe, 409 para um período que acabou de lotar. A Vatio transforma qualquer resposta que não seja 2xx em um erro que o agente consegue explicar, então um erro de digitação vira “não encontrei esse código, pode conferir?” em vez de um status inventado.

#Conhecimento: períodos, pontos de retirada e reclamações

vatio kb create entregas
vatio kb write entregas entregas entregas.md
vatio kb write entregas pontos-de-retirada pontos-de-retirada.md
vatio kb write entregas reclamacoes reclamacoes.md
vatio kb write entregas cobertura cobertura.md

Uma boa entrada responde uma pergunta por seção:

# Entregas

## Períodos de entrega
A manhã vai das 9:00 às 13:00 e a tarde das 14:00 às 19:00, de segunda a
sábado. Não conseguimos prometer um horário exato dentro de um período.

## Depois de uma tentativa malsucedida
Tentamos duas vezes. Depois da segunda tentativa, a encomenda vai para o
ponto de retirada mais próximo e espera ali 7 dias antes de voltar ao
remetente.

## Retirar em um ponto de retirada
Leve um documento com foto e o código de rastreio. Outra pessoa pode
retirar com o seu CPF e um documento dela.

A Vatio não lê o seu site. Se a resposta está em uma página, coloque em uma entrada o que o agente precisa. Os supervisores podem editar entradas pelo inbox quando uma política muda, e cada edição fica guardada como versão.

#Fotos de encomendas danificadas

Os clientes mostram em vez de descrever: um canto amassado, um lacre rompido, uma caixa molhada, muitas vezes em três fotos e um “olha isso”. A Vatio espera as imagens terminarem de baixar, agrupa as mensagens em um só turno e passa ao agente as imagens de até 8 MB, e o agente descreve o que vê na reclamação. Um áudio contando o que aconteceu é transcrito do mesmo jeito.

O agente não consegue anexar a foto à reclamação, porque uma tool envia texto para a sua API. A foto fica na conversa, e a pessoa que assume a transferência a vê no inbox, ao lado do número de protocolo que o agente passou ao cliente. Essa pessoa decide sobre a indenização; a regra do agente é não prometer nenhuma.

#Teste antes de qualquer cliente

vatio push
vatio chat "Cadê minha encomenda? TE48213977"
vatio chat "Amanhã não vou estar em casa, pode trazer no sábado? CEP 01310-100"
vatio chat --new "Remarca a TE48213977, não sei o CEP, é do meu vizinho"
vatio chat --new "Qual é o endereço da encomenda TE48213977?"
vatio chat show

As duas últimas são as importantes: uma mudança sem o segundo dado, que ele deve recusar, e um endereço que ele nunca deve informar. Teste também um CEP errado e confira que o agente não dá pistas do certo. Depois adicione o seu telefone como número de teste na página Testar do inbox, mande para o número compartilhado de preview do WhatsApp a foto de uma caixa amassada, e veja a reclamação ser aberta e a conversa transferida. Para isso você não precisa de uma conta da Meta. Mais sobre o canal em Um agente de IA no WhatsApp.

#Melhore toda semana

Quando o seu time trabalha pelo inbox, ele reporta qualquer resposta errada e escreve o que deveria ter acontecido. vatio flags transforma essas notas em um documento a partir do qual o seu coding agent corrige, cada relato vira um caso de eval, e o relato fica resolvido quando o live passa nele. Os evals chamam as suas tools de verdade, então aponte-as para uma API de roteirização de teste com um valor de testes (--tests) antes que uma repetição remarque uma encomenda real. Veja Melhorar seu agente.

#Publicar

vatio publish

Depois conecte o seu número de WhatsApp Business em Canais no inbox e ative. Dá para continuar usando o app WhatsApp Business no celular: uma resposta enviada por ele assume a conversa, e o agente se afasta até ela ser liberada. O WhatsApp continua uma conversa até a última mensagem do cliente ter mais de oito horas; depois disso, a próxima mensagem começa uma nova, e o agente pede o código de rastreio de novo.

Atualizado: 11 de outubro de 2026