> Construa um agente de IA que rastreia encomendas, remarca entregas, indica pontos de retirada e abre reclamações no WhatsApp, com checagens no seu backend. # 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](https://vatio.ai/docs/api/messages) 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` ```yaml 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: ```bash vatio secrets set TUCANO_API https://api.tucano-entregas.example vatio secrets set TUCANO_API_KEY sk_live_... ``` `tools/rastrear_envio.yml`: ```yaml 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`: ```yaml 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 ```bash 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: ```markdown # 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 ```bash 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](/pt/guias/agente-ia-para-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](/pt/guias/melhorar-seu-agente-de-ia). ## Publicar ```bash 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. ## Perguntas frequentes ### Um agente de IA consegue rastrear encomendas pelo WhatsApp? Sim. O cliente envia o código de rastreio e o agente chama a sua API de rastreamento por uma tool que você descreve em YAML. Ele responde com o status, a última leitura e a janela de entrega que o seu sistema devolveu, e nunca chuta um horário que não recebeu. ### Como o agente sabe que quem está remarcando a entrega é o destinatário? Ele pede duas coisas: o código de rastreio e o CEP do endereço de entrega. O seu backend confere se os dois batem antes de mudar qualquer coisa. Só com o código de rastreio, o máximo que se vê é o status. ### Os clientes podem mandar fotos de uma encomenda danificada? Sim. O agente lê imagens de até 8 MB, descreve o dano que vê, abre uma reclamação pela sua API e transfere a conversa para uma pessoa. A foto fica na conversa, onde quem assume a vê no inbox, e uma pessoa decide sobre a indenização. ### O agente envia as notificações de entrega? Sim, quando o seu sistema pede. Quando um pacote sai para entrega ou uma entrega falha, o seu sistema chama a Messages API da Vatio e a conversa se abre no WhatsApp: o seu próprio texto, um brief a partir do qual o agente escreve, ou um modelo aprovado quando já passaram 24 horas desde a última mensagem do cliente. O agente cuida da resposta sabendo de qual pacote falou. ### O agente pode mudar o endereço de entrega? Só se você der uma tool para isso, e este guia não dá. Uma mudança de endereço é onde um código de rastreio roubado faz mais estrago, então ela está no handoff e uma pessoa resolve.