Agentes de IA
Un agente que respondedonde el cliente ya escribe.
Prompt, modelo, herramientas y base de conocimiento son un mismo objeto. Créalo por la API, conecta los senders donde debe responder y córrelo contra un mensaje antes de entregar nada.
- openai · anthropic · google · mistral · zavu
- un agente, varios senders
- prueba en seco antes de publicar
El loop
Mira cómo se arma una respuesta.
Un mensaje entrante, recuperación, una herramienta que eligió el modelo, una respuesta. Cambia entre la prueba en seco y el camino real y el registro de abajo cambia con eso.
Pregúntale al agente
POST /v1/agents/{agentId}/test. No se entrega nada, no se cobra nada, no se guarda ninguna ejecución.
Elige una pregunta y corre el loop.
La recuperación devuelve como máximo 5 fragmentos por encima de un umbral de similitud. Una respuesta sin fundamento se ve igual que una correcta — por eso el conteo va en el registro.
Constrúyelo
Cuatro llamadas y ya responde.
Los agentes se configuran por REST, desde el CLI, o se declaran en código con @zavudev/functions. @zavudev/sdk todavía no genera un recurso de agentes, así que nada acá finge que sí.
# 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}'Canales
Un agente. Los canales que le des.
triggerOnChannels se revisa antes que cualquier otra cosa. Arma la lista a la izquierda y mira si el mensaje entrante llega siquiera al modelo.
El mensaje llega por
triggerOnChannels
Vacío significa que el agente no responde nada. El comodín cubre todos los canales que el sender realmente puede recibir.
config del agente
{
"triggerOnChannels": ["whatsapp", "sms", "email"]
}processed — el agente responde
¿Envían a Chile?
Sí. Chile son unos seis días hábiles, con impuestos pagados al comprar.
Mismo prompt, misma base de conocimiento, mismas herramientas. El canal solo decide por dónde sale la respuesta.
Anatomía
De qué está hecho un agente.
Prompt y modelo
openai, anthropic, google o mistral con tu propia key — o zavu, para los modelos que Zavu hospeda, donde no hace falta key.
- Prompt ≤ 10.000 caracteres
- Contexto de 1 a 50 mensajes
- Temperatura 0–2
Bases de conocimiento
Los documentos se fragmentan y se convierten en embeddings al guardarlos. La recuperación que corre antes de cada respuesta trae los fragmentos más cercanos al prompt.
- ≤ 100.000 caracteres por documento
- ≤ 5 fragmentos por respuesta
- knowledgeChunksUsed en cada corrida
Herramientas
Un endpoint HTTPS tuyo, descrito con un JSON Schema. Zavu firma cada llamada para que tu handler pueda rechazar lo que no envió.
- X-Zavu-Signature: HMAC-SHA256
- Dispara una a mano con /test
- Corridas recientes en /test-runs
Flows
Una secuencia guionada que corre antes del modelo cuando coincide una palabra clave, o en cada mensaje. Los pasos recogen datos, ramifican, llaman una herramienta o devuelven el turno al LLM.
- Triggers keyword y always
- message · collect · condition
- pasos tool · llm
Senders
Un agente responde en tantos senders como conectes. Un sender responde con un solo agente — conectar uno ya tomado devuelve 400 nombrando al agente que lo tiene.
- POST /v1/agents/{id}/senders
- senderIds en el agente
- Se permiten agentes sin sender
Ejecuciones
Cada respuesta queda guardada: tokens, latencia, costo, los fragmentos que recuperó y las herramientas que llamó. Trae una para leer el mensaje de error detrás de una falla.
- knowledgeChunksUsed · toolCalls
- success · error · filtered
- rate_limited · balance_insufficient
Preguntas
Las que deciden.
¿Puedo probar un agente sin escribirle a nadie?
Sí. POST /v1/agents/{agentId}/test — o npx zavudev agents test — corre el prompt, el modelo y la base de conocimiento reales y devuelve lo que el agente diría, con tokens, latencia y knowledgeChunksUsed. No se entrega nada, no se cobra nada, no se guarda ninguna ejecución. Pasa executeTools cuando quieras que los handlers de las herramientas corran de verdad.
¿Qué proveedores de modelo puedo usar?
openai, anthropic, google y mistral con tu propia API key, o zavu para los modelos que Zavu hospeda, que no necesita key tuya. El proveedor es un campo del agente, así que cambiarlo es un PATCH.
¿Cómo llega una llamada de herramienta a mi código?
Como un POST HTTPS a la URL que registraste, con el nombre de la herramienta, los argumentos que eligió el modelo, contexto de la conversación y un timestamp. Llega con X-Zavu-Tool, X-Zavu-Timestamp y X-Zavu-Signature — el HMAC-SHA256 del cuerpo, firmado con el secreto de la herramienta. Verifica la firma antes de confiar en la llamada.
¿Un agente puede atender varios números?
Sí. Conecta senders con POST /v1/agents/{agentId}/senders y todos resuelven al mismo prompt, herramientas y bases de conocimiento. Al revés hay tope: un sender responde con un solo agente.
¿Hay un método del SDK para agentes?
Todavía no. @zavudev/sdk genera messages, senders, contacts, templates, broadcasts, números y más, pero ningún recurso de agentes. Configura agentes por REST, con el CLI npx zavudev, o decláralos en código con @zavudev/functions y publícalos.
¿Cuánto cuesta operarlo?
Los tokens del modelo y el canal por el que sale la respuesta. No hay tarifa por agente ni tope de cuántos creas. Cada ejecución guarda su propio costo, así que la cuenta queda desglosada por respuesta.
Lectura
Guías para construir agentes
El loop, los canales y las decisiones que van antes del código.
Publica uno esta tarde.
Crea el agente, conecta un sender, córrelo en seco hasta que la respuesta sea la correcta. Después déjalo responder.