Agentes de IA
Um agente que respondeonde o cliente já escreve.
Prompt, modelo, ferramentas e base de conhecimento são um único objeto. Crie pela API, conecte os senders onde ele deve responder e rode contra uma mensagem antes de entregar qualquer coisa.
- openai · anthropic · google · mistral · zavu
- um agente, vários senders
- teste a seco antes de publicar
O loop
Veja uma resposta ser montada.
Uma mensagem recebida, recuperação, uma ferramenta que o modelo escolheu, uma resposta. Alterne entre o teste a seco e o caminho real e o registro embaixo muda junto.
Pergunte ao agente
POST /v1/agents/{agentId}/test. Nada é entregue, nada é cobrado, nenhuma execução é gravada.
Escolha uma pergunta e rode o loop.
A recuperação devolve no máximo 5 trechos acima de um limiar de similaridade. Uma resposta sem fundamento parece igual a uma correta — por isso a contagem fica no registro.
Construa
Quatro chamadas e ele já responde.
Agentes são configurados por REST, pelo CLI, ou declarados em código com @zavudev/functions. O @zavudev/sdk ainda não gera um recurso de agentes, então nada aqui finge que gera.
# Create a standalone agent — no sender needed yet.
AGENT=$(curl -s -X POST https://api.zavu.dev/v1/agents \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support",
"provider": "zavu",
"model": "openai/gpt-4o-mini",
"systemPrompt": "You answer order questions. Be brief.",
"triggerOnChannels": ["whatsapp", "sms", "email"]
}' | jq -r .agent.id)
# Point it at the number it should answer on, then turn it on.
curl -X POST https://api.zavu.dev/v1/agents/$AGENT/senders \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-d "{\"senderId\":\"$SENDER_ID\"}"
curl -X PATCH https://api.zavu.dev/v1/agents/$AGENT \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-d '{"enabled": true}'Canais
Um agente. Os canais que você der a ele.
triggerOnChannels é verificado antes de qualquer outra coisa. Monte a lista à esquerda e veja se a mensagem recebida chega sequer ao modelo.
A mensagem chega por
triggerOnChannels
Vazio significa que o agente não responde nada. O curinga cobre todos os canais que o sender realmente consegue receber.
config do agente
{
"triggerOnChannels": ["whatsapp", "sms", "email"]
}processed — o agente responde
Vocês enviam para o Chile?
Enviamos. Chile leva cerca de seis dias úteis, com impostos pagos na compra.
Mesmo prompt, mesma base de conhecimento, mesmas ferramentas. O canal só decide por onde a resposta sai.
Anatomia
Do que um agente é feito.
Prompt e modelo
openai, anthropic, google ou mistral com a sua própria key — ou zavu, para os modelos que a Zavu hospeda, onde nenhuma key é necessária.
- Prompt ≤ 10.000 caracteres
- Contexto de 1 a 50 mensagens
- Temperatura 0–2
Bases de conhecimento
Os documentos são fragmentados e viram embeddings na gravação. A recuperação que roda antes de cada resposta traz os trechos mais próximos para o prompt.
- ≤ 100.000 caracteres por documento
- ≤ 5 trechos por resposta
- knowledgeChunksUsed em cada rodada
Ferramentas
Um endpoint HTTPS seu, descrito com um JSON Schema. A Zavu assina cada chamada para o seu handler poder recusar o que não foi enviado por ela.
- X-Zavu-Signature: HMAC-SHA256
- Dispare uma na mão com /test
- Rodadas recentes em /test-runs
Flows
Uma sequência roteirizada que roda antes do modelo quando uma palavra-chave casa, ou em toda mensagem. Os passos coletam dados, ramificam, chamam uma ferramenta ou devolvem a vez ao LLM.
- Triggers keyword e always
- message · collect · condition
- passos tool · llm
Senders
Um agente responde em quantos senders você conectar. Um sender responde com no máximo um agente — conectar um já ocupado devolve 400 nomeando o agente que o tem.
- POST /v1/agents/{id}/senders
- senderIds no agente
- Agentes sem sender são permitidos
Execuções
Toda resposta fica gravada: tokens, latência, custo, os trechos que recuperou e as ferramentas que chamou. Busque uma para ler a mensagem de erro por trás de uma falha.
- knowledgeChunksUsed · toolCalls
- success · error · filtered
- rate_limited · balance_insufficient
Perguntas
As que decidem.
Posso testar um agente sem escrever para ninguém?
Pode. POST /v1/agents/{agentId}/test — ou npx zavudev agents test — roda o prompt, o modelo e a base de conhecimento reais e devolve o que o agente diria, com tokens, latência e knowledgeChunksUsed. Nada é entregue, nada é cobrado, nenhuma execução é gravada. Passe executeTools quando quiser que os handlers das ferramentas rodem de verdade.
Quais provedores de modelo posso usar?
openai, anthropic, google e mistral com a sua própria API key, ou zavu para os modelos que a Zavu hospeda, que não precisa de key sua. O provedor é um campo do agente, então trocar é um PATCH.
Como uma chamada de ferramenta chega ao meu código?
Como um POST HTTPS para a URL que você registrou, levando o nome da ferramenta, os argumentos que o modelo escolheu, contexto da conversa e um timestamp. Chega com X-Zavu-Tool, X-Zavu-Timestamp e X-Zavu-Signature — o HMAC-SHA256 do corpo, assinado com o segredo da ferramenta. Verifique a assinatura antes de confiar na chamada.
Um agente pode atender vários números?
Pode. Conecte senders com POST /v1/agents/{agentId}/senders e todos resolvem para o mesmo prompt, ferramentas e bases de conhecimento. O contrário tem limite: um sender responde com no máximo um agente.
Existe um método do SDK para agentes?
Ainda não. O @zavudev/sdk gera messages, senders, contacts, templates, broadcasts, números e mais, mas nenhum recurso de agentes. Configure agentes por REST, com o CLI npx zavudev, ou declare-os em código com @zavudev/functions e publique.
Quanto custa manter isso rodando?
Os tokens do modelo e o canal por onde a resposta sai. Não há taxa por agente nem limite de quantos você cria. Cada execução guarda o próprio custo, então a conta fica detalhada por resposta.
Leitura
Guias para construir agentes
O loop, os canais e as decisões que vêm antes do código.
Publique um hoje à tarde.
Crie o agente, conecte um sender, rode a seco até a resposta ficar certa. Depois deixe ele responder.