Agentes e a Amivu

As três formas de dar a um agente o que ele precisa para integrar — e qual usar em cada caso.

Quem integra a Amivu hoje quase sempre tem um assistente ao lado. Estas páginas são sobre dar a ele o contexto certo — e sobre o que ele não deveria fazer sem você.

Três formas, três momentos

Skill para agentesSKILL.mdUm procedimento que carrega sozinho quando o assunto aparece: o modelo, as rotas, as armadilhas e o que fazer em que ordem. É o mais completo, e o único que ensina o que a especificação não diz.llms.txttextoO índice da documentação sem a moldura de HTML: o modelo, as quarenta rotas com alcance, os eventos e o link de cada página. Serve qualquer agente, sem instalar nada.Especificação OpenAPIJSONPara gerar cliente tipado ou alimentar uma ferramenta que já fala OpenAPI. Descreve a forma de tudo — e nada sobre a ordem das coisas.

Qual usar

Se o seu assistente aceita skills — Claude Code, por exemplo —, use a skill. Ela é a única das três que carrega procedimento: a especificação diz que POST /v1/messages existe, e a skill diz também que não existe /whatsapp/send, que status pode ser null, e que confirmar envio pela resposta do POST é a origem mais comum de “o cliente não recebeu”.

Se não aceita, cole o llms.txt no contexto. Ele cabe numa janela pequena e cobre o que um agente erra por falta de índice: o nome exato da rota, o alcance que ela exige e o evento que corresponde a ela.

O que um agente não deveria fazer sozinho

Disparar com chave de produção. Toda mensagem enviada com amivu_live_… chega a um cliente de verdade. A skill instrui a perguntar antes de qualquer escrita, mas a garantia é você criar uma chave de sandbox para o agente.
Guardar o segredo no repositório. Variável de ambiente, sempre — e a chave nunca em código que roda no navegador ou no celular.
Criar chave com todos os alcances. Uma chave que só lê não consegue enviar mensagem, e é o que transforma um erro de agente em um erro sem consequência.

Alcance é o freio que funciona

Instrução em texto é sugestão; alcance é regra. Se o agente não precisa enviar, não dê messages:write — assim a pior coisa que ele consegue fazer é ler.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.