#Glosario de agentes de IA
Este glosario explica los términos que aparecen cuando construyes un agente de IA que atiende clientes, desde tool calling y RAG hasta derivación a una persona, evals y preview. Cada entrada da primero el significado general y después, cuando aplica, lo que el término significa en Vatio, donde describes un agente en un archivo vatio.yml y responde en WhatsApp, Instagram, la web y apps de iOS.
Los términos están agrupados por tema y ordenados alfabéticamente dentro de cada grupo.
#Agentes y cómo se construyen
#Agente de IA
Software que usa un modelo de lenguaje para mantener una conversación y decidir, turno a turno, si responde, busca algo o actúa con una tool. En Vatio, un workspace corre exactamente un agente, definido bajo agent: en vatio.yml, y el mismo agente responde en todos los canales. Construir un agente de IA arma uno desde una carpeta vacía.
#Builder no-code de chatbots
Un producto alojado donde dibujas las conversaciones como flujos en un editor visual y conectas canales desde una pantalla de configuración. Sirve para equipos sin desarrolladores y conversaciones mayormente fijas, como menús o formularios; el agente vive en el editor del builder y no en un repositorio.
#Coding agent
Un asistente de IA que trabaja en tu repositorio y tu terminal: lee código, edita archivos y corre comandos, como Claude Code, Codex o Cursor. En Vatio el agente son archivos y una CLI, así que un coding agent puede escribirlo, probarlo y corregirlo: vatio init agrega una sección de Vatio a AGENTS.md, y la documentación es un solo archivo Markdown en https://vatio.ai/docs/docs.md.
#Framework de agentes
Una librería que importas en tu propio backend para construir un agente en código, con abstracciones para llamar al modelo, definir tools, manejar memoria y encadenar pasos. Lo corres tú, junto con todo lo que un agente frente a clientes necesita alrededor: webhooks de canales, estado de la conversación, un inbox, despliegues y pruebas. Vatio vs. frameworks y builders no-code compara los tres enfoques.
#Fulfillment conversacional
El nombre que Vatio le da a todo lo que pasa entre el mensaje de un cliente y la respuesta que recibe, por analogía con el fulfillment del ecommerce. Tú decides qué puede hacer el agente; Vatio recibe los mensajes, los agrupa, espera los archivos, da ritmo a la respuesta y suma a una persona cuando hace falta. Mira Conversaciones fluidas.
#Instrucciones (system prompt)
El texto que le dice a un modelo qué trabajo hace y qué reglas sigue, también llamado system prompt. En Vatio es agent.instructions, el único campo obligatorio del agente, y Vatio agrega a su alrededor el contexto del negocio, el estado del contacto, la descripción de las tools y sus propias instrucciones de plataforma. Escribe lo que el agente nunca debe hacer como reglas explícitas; Buenas prácticas muestra cómo.
#Manifiesto (vatio.yml)
El archivo que define un workspace de Vatio, guardado en tu repositorio junto a un archivo YAML por tool en tools/. Sus únicas claves de primer nivel son workspace, agent y auth, y una clave desconocida hace fallar la validación. La referencia del manifiesto describe cada una.
#Personalidad
La voz y el tono de un agente, separados de lo que hace. En Vatio es el campo opcional agent.personality, que por defecto es cálido, breve y claro.
#Runtime de agentes
Un servicio alojado que corre un agente a partir de una definición que tú escribes y opera la maquinaria alrededor. Vatio es un runtime: escribes vatio.yml y un archivo YAML por tool, y Vatio opera los canales, la agrupación de mensajes, la verificación de identidad, las salvaguardas, el inbox y los despliegues.
#Workspace
En Vatio, el contenedor de un agente y sus conversaciones, contactos, conocimiento, secrets y conexiones de canales. Su slug es la clave workspace de vatio.yml, y cada comando de la CLI lo lee del vatio.yml más cercano.
#Tools, identidad y datos
#Contacto
La persona detrás de una conversación, con nombre, email y teléfono cuando se conocen. En Vatio, un contacto se completa con identify_contact, con el número desde el que llega un mensaje de WhatsApp o con los claims de un token firmado, y las tools lo leen como $contact.name, $contact.email y $contact.phone_number.
#JWT (identidad del visitante)
Un JSON Web Token: un conjunto compacto y firmado de claims, que se usa a menudo para decir quién es un usuario. En Vatio, tu backend firma un JWT RS256 con sub (el id de tu usuario), aud (el slug del workspace) y exp, y Vatio lo verifica con tu llave pública; nunca guarda la llave privada, así que puede verificar una identidad pero nunca crearla. El widget y los SDK lo pasan como visitor token: mira Conectar tu backend.
#Memoria (remember y recall)
Lo que un agente sabe de una persona por conversaciones anteriores. En Vatio, una conversación con un contacto conocido se resume cuando lleva 30 minutos en silencio, y los datos duraderos se guardan como notas; con las tools incluidas remember y recall activadas, el agente ve hasta 20 notas en cada conversación, guarda notas nuevas con remember y busca en resúmenes y notas con recall. Los contactos de preview y de live nunca ven la memoria de los otros.
#Token de desarrollador
En Vatio, el token vat_… que usa la CLI, creado cuando autorizas una máquina con vatio login. Con él se puede hacer deploy, leer secrets y crear tokens publicables, así que va en tu máquina o en un secret de CI como VATIO_TOKEN, nunca en una página web, una app ni un repositorio.
#Token publicable
En Vatio, el token vatpub_… que lleva una página web o una app para hablar con un workspace y un entorno. Solo funciona desde sus orígenes permitidos, valores exactos scheme://host[:port] o ios-app://BUNDLE_ID, que lo mantienen en tu sitio o tu app pero no dicen nada sobre quién es el visitante. Mira Un chat con IA para tu sitio web y Un agente de IA en tu app iOS.
#Tool (function calling)
Una acción que un modelo puede pedir que se ejecute, descrita con un nombre, una descripción y parámetros: el modelo llena los parámetros, el runtime hace la llamada y el modelo responde a partir del resultado. También se le dice function calling o tool use. En Vatio una tool es un request HTTP a tu API, descrito en tools/<key>.yml y activado en agent.tools, y cualquier lógica con ramas va detrás de un endpoint en tu backend.
#Tool privada
En Vatio, una tool marcada access: private: corre solo para un visitante cuyo JWT fue verificado, y llega a sus datos con $auth.subject o $auth.token. No puede recibir user_id, customer_id, account_id, member_id, patient_id ni subject como parámetro, porque los parámetros los llena el modelo; si lo hace, el deploy falla. Las tools privadas corren en la web, en apps, y en WhatsApp e Instagram una vez que el contacto inicia sesión.
#Tool pública
En Vatio, una tool con access: public, o sin access, que corre para cualquiera, incluidos los contactos de WhatsApp e Instagram que no han iniciado sesión. Todo lo que revele sobre una persona necesita una verificación en tu backend, como un número de referencia más un segundo dato que deben coincidir.
#Tools incluidas
Las tools que trae Vatio, para las que no escribes YAML: knowledge_lookup, identify_contact (guarda un nombre que da el visitante), request_contact_info (le pide a un visitante de WhatsApp que comparta su número), remember y recall. Se activan en agent.tools; handoff, en cambio, se agrega al declarar agent.handoff.
#Conocimiento y precisión
#Alucinación
Cuando un modelo de lenguaje afirma algo plausible que no es cierto: un precio, una política, un stock, un link. En Vatio, las salvaguardas quitan cualquier URL que no se le dio al agente; el resto se previene con lo que construyes tú: reglas como «nunca inventes un precio», tools para los datos que cambian, una base de conocimiento para las políticas y evals a partir de respuestas marcadas. Cada llamada a tools queda visible en el inbox, así que una respuesta equivocada se puede rastrear hasta su origen.
#Base de conocimiento
Un conjunto de documentos que un agente lee en vez de memorizar. En Vatio, una base de conocimiento guarda entradas en Markdown que escribes desde la CLI o el inbox, se crea con vatio kb create y se declara en agent.knowledge; Vatio no lee sitios web. Mira Base de conocimiento.
#Entrada de conocimiento
Un documento Markdown dentro de una base de conocimiento, escrito con vatio kb write BASE ENTRADA archivo.md. Sus títulos la dividen en secciones que se buscan por separado, así que cada sección debería responder una pregunta por sí sola. Cada cambio queda guardado como una versión numerada, y los supervisores pueden editar entradas en el inbox.
#knowledge_lookup
La tool incluida de Vatio que busca en las bases de conocimiento que el agente declara en knowledge. La activas en agent.tools y le dices al agente en sus instrucciones cuándo buscar; cada búsqueda aparece junto a las demás llamadas a tools del turno.
#Lista de links permitidos
La lista de URL que un agente tiene permitido enviar, también llamada allowlist. En Vatio es agent.links, donde cada link es una URL o { url, when, values }, con placeholders que se expanden al desplegar. Una respuesta solo puede llevar una URL que se le dio al agente, en links, en otra parte de su prompt o en el resultado de una tool, y las salvaguardas quitan cualquier otra.
#RAG (generación aumentada por recuperación)
Una técnica en la que se recuperan de un repositorio de documentos los fragmentos relevantes para una pregunta y se agregan al contexto del modelo, para que responda desde tu texto y no de memoria. En Vatio, lo más cercano es knowledge_lookup: el agente la llama cuando necesita tu contenido, y busca en las secciones de las entradas que escribiste, que Vatio indexa en segundo plano después de cada escritura. Busca solo en esas entradas; Vatio no recorre sitios web ni se conecta a otros repositorios de documentos.
#Salvaguardas
Controles que pasa cada respuesta antes de enviarse. En Vatio detectan respuestas vacías, medios generados y links que no se le dieron al agente; un control fallido dispara un intento de corrección, y no se pueden desactivar. Lo que el agente nunca debe decir lo escribes tú en las instrucciones: mira Salvaguardas.
#Conversaciones y canales
#Agrupación de mensajes (buffering)
Tratar varios mensajes que alguien manda seguidos como una sola pregunta. En WhatsApp e Instagram, Vatio agrupa los fragmentos que llegan juntos y espera un momento de silencio, y también los archivos que todavía se descargan o procesan, antes de que el agente responda, y mantiene los mensajes en el orden en que se enviaron. Una espera que se adapte a cada persona está en desarrollo y todavía no está disponible; mira Conversaciones fluidas.
#Canal
Un lugar donde los clientes hablan con el agente. Los canales de Vatio son el widget web y el SDK de navegador, WhatsApp, los DM de Instagram, el SDK de iOS y la CLI para probar; es el mismo agente en todos, y solo cambia la forma de entrega.
#Derivación a una persona (handoff)
Cuando un agente le pasa una conversación a una persona. En Vatio, declarar agent.handoff le da esa tool al agente, con tus propias condiciones en when y un piso en after_turns, y un visitante que pide hablar con una persona siempre dispara una derivación. El chat queda en espera en el inbox; Vatio todavía no le avisa a nadie. Mira Derivar a una persona.
#Horario de atención
En Vatio, cuándo hay una persona de turno: una zona horaria y uno o más turnos por día, que quien lleva el negocio configura en la página Negocio del inbox, no en vatio.yml. El agente lo recibe para decir cuándo atienden, pero no decide cuándo responde el agente, solo qué pasa después de una derivación: dentro del horario el agente se queda en silencio, fuera de él sigue ayudando, y una derivación que nadie toma en una hora vuelve al agente.
#Número de preview de WhatsApp
El número de WhatsApp compartido de Vatio para pruebas, con el que hablas con tu agente en WhatsApp real sin una cuenta de Meta. Agregas tu teléfono como teléfono de prueba escaneando un código QR y enviando el mensaje que te deja escrito, y después le escribes al número; los clientes llegan a tu propio número de negocio cuando lo conectas y activas En vivo. Mira Un agente de IA en WhatsApp.
#Ritmo de respuesta (pacing)
Cómo se entrega una respuesta en cada canal. En WhatsApp e Instagram, Vatio envía una respuesta como mensajes cortos con pausas e indicadores de escritura; en la web, como una sola respuesta que se muestra de forma progresiva. Los SDK lo eligen con replyStyle: stream, paced o instant.
#Teléfono y cuenta de prueba
Un teléfono o una cuenta de Instagram que conectas desde la página Probar del inbox, enviándole al preview compartido el código que muestra, para hablar con tu agente antes de que esté en live. Cada workspace puede tener hasta cinco teléfonos de prueba en el número de preview compartido de WhatsApp y hasta cinco cuentas de prueba en la cuenta de preview compartida de Instagram. Mira Un agente de IA en Instagram.
#Tomar la conversación (takeover)
Cuando una persona responde en una conversación en lugar del agente. En Vatio, una respuesta desde el inbox, o desde la app de WhatsApp Business en tu propio número, pausa al agente en ese chat hasta que alguien se lo devuelve, o hasta 8 horas después del último mensaje del cliente.
#Ventana de conversación
Cuánto tiempo sigue abierta una conversación antes de que el siguiente mensaje empiece una nueva. En WhatsApp e Instagram, Vatio continúa una conversación hasta que el último mensaje del visitante tiene más de ocho horas. En los SDK web y de iOS, una conversación guardada se puede retomar mientras duran sus credenciales de chat, que son 12 horas.
#Supervisar y mejorar
#Digest
En Vatio, el documento Markdown que imprime vatio flags para un coding agent: cada flag abierto con la conversación hasta la respuesta, las llamadas a tools de ese turno con lo que respondió tu backend, y la nota del supervisor. Cuando hay flags nuevos, también sale un correo diario a las 08:00 de America/Santiago al dueño y a los developers del workspace, con cuántos siguen abiertos y el prompt /vatio:vatio-improve; no cita ninguna conversación.
#Eval y caso de eval
Un eval es una prueba automática de un agente: conversaciones que se repiten contra él y cuyos resultados se califican. En Vatio, cada flag con nota, hecho en live o en preview, se vuelve un caso de eval, con los turnos del visitante como entrada y la nota como resultado esperado, y vatio eval repite todos los casos contra preview y sale con código 1 si alguno falla. Los evals llaman a tus tools de verdad, así que primero apúntalas a un sandbox con un valor de pruebas; mira Mejorar tu agente.
#Flag
En Vatio, la marca que pone un supervisor en una respuesta equivocada, con Reportar esta respuesta en el inbox, junto con una nota de lo que debió pasar: otra respuesta, una acción o una tool que el agente debió usar. Un flag con nota se vuelve un caso de eval, y su estado se ve en la misma respuesta: abierto, arreglado en preview o resuelto, con la versión que lo arregló. Editar la nota lo reabre.
#Inbox
Donde un equipo lee las conversaciones de un agente. El inbox de Vatio muestra cada conversación con cada llamada a tools, encuentra cualquiera por un nombre, un número o algo que se dijo, y es donde los supervisores toman una conversación, marcan respuestas con un flag y editan el conocimiento.
#Juez (judge)
Un modelo que califica la respuesta de un agente contra un resultado esperado, un enfoque que se conoce como LLM-as-a-judge. En vatio eval, el juez es de una familia de modelos distinta a la de tu agente y responde aprobado o reprobado con una frase de razonamiento, que vatio eval --show RUN_ID imprime.
#Regresión
Un cambio que rompe algo que antes funcionaba. En vatio eval, un caso que pasa en live y falla en preview es una regresión, y aparece primero en la lista. vatio publish no publica esa versión, salvo con --force.
#Supervisor
Una persona del negocio que revisa las conversaciones del agente. En Vatio, a los supervisores se les invita desde Equipo en el inbox y entran con un código que les llega por email; ven el inbox y el conocimiento, y no pueden hacer deploy ni cambiar tools.
#Despliegue y entornos
#Borrador
En Vatio, un workspace que nunca se ha publicado. Mientras está en borrador, preview es el agente: un flag queda resuelto cuando preview lo pasa, y la primera publicación no pasa por ningún control. Desde el primer vatio publish, el workspace está publicado y los flags se resuelven cuando live los pasa.
#Entorno
Un lugar con nombre al que se despliega un agente. En Vatio hay dos, y cada uno apunta a un deployment, un snapshot guardado de la configuración: preview para probar cambios y live para los clientes.
#Live
El entorno con el que hablan los clientes. En Vatio, live cambia con vatio publish o con el botón Publicar de la página Probar del inbox, y los clientes llegan a él por el widget de tu sitio, WhatsApp, Instagram o los SDKs.
#Preview
El entorno para probar un agente antes de que lo vean los clientes. En Vatio, vatio push actualiza preview sin correr pruebas, vatio eval lo prueba contra cada flag, y los teléfonos y cuentas de prueba llegan a preview.
#Publicar
Pasar una versión a live. En Vatio, vatio publish promueve preview a live junto con sus cambios de conocimiento. Una vez publicado el workspace, se rechaza si la versión de preview no se probó con vatio eval, si sus pruebas siguen corriendo o si rompe un flag que live pasa; --force publica igual. Al publicar, los resultados de preview pasan a live y cada flag que pasó queda resuelto con la versión. Mira Mejorar tu agente.
#Reversión (rollback)
Volver a la versión anterior de live. En Vatio, vatio rollback restaura el snapshot anterior de live, configuración y conocimiento juntos; no restaura valores de secrets ni deshace lo que una tool ya hizo.
Preguntas frecuentes
¿Cuál es la diferencia entre un agente de IA y un chatbot?
Un chatbot tradicional sigue flujos que alguien dibujó: menús, botones y respuestas fijas. Un agente de IA usa un modelo de lenguaje para entender texto libre y decide en cada turno si responder, buscar algo o actuar con una tool, como revisar stock o agendar una hora. Muchos productos llaman chatbot a los dos, así que pregunta qué pasa cuando una pregunta se sale del guion.
¿Qué es el tool calling en un agente de IA?
El tool calling, también llamado function calling, es la forma en que un agente actúa. El modelo elige una tool y llena sus parámetros, el runtime hace la llamada y el modelo responde a partir del resultado. En Vatio cada tool es un request HTTP a tu API, descrito en un archivo YAML.
¿Qué es la derivación a una persona en un agente de IA?
Es el agente pasándole la conversación a una persona, porque se cumplió una condición que definiste o porque el cliente lo pidió. En Vatio escribes las condiciones en handoff dentro de vatio.yml, un cliente que pide hablar con una persona siempre dispara una derivación, y la conversación aparece en espera en el inbox hasta que alguien responde.
¿Qué es un eval de un agente de IA?
Un eval es una prueba automática: conversaciones que se repiten contra el agente y cuyas respuestas se califican, muchas veces con otro modelo que hace de juez. En Vatio cada respuesta reportada con una nota se vuelve un caso de eval, y vatio eval repite los casos contra preview antes de que el cambio llegue a live.
¿Cómo evitar que un agente de IA alucine?
No hay una opción que lo elimine, pero puedes dejarle poco espacio: tools para los datos que cambian, una base de conocimiento para las políticas, reglas explícitas como nunca inventar un precio, y pruebas armadas a partir de errores reales. Vatio además quita cualquier link que no se le dio al agente, y muestra cada llamada a tools para que veas de dónde salió una respuesta equivocada.
Actualizado: