Construir un agente — Manual del operador | AI Agent Builder

Capítulo 3

Construir un agente

Las formas de crear un agente, cómo se ejecuta un workflow paso a paso, y cómo funcionan las versiones y la aprobación humana.

9 min de lectura · Actualizado 10 de noviembre de 2026

Este capítulo en video · 2:52 · en inglés, con subtítulos · Todos los videos del manual

Un agente es un grafo de pasos que la plataforma recorre cada vez que llega un mensaje. Lo podés dibujar vos en el editor, lo puede generar un formulario o lo puede armar el AI Builder a partir de una descripción, pero lo que se ejecuta es siempre lo mismo: nodos conectados por aristas. Este capítulo explica cómo se arma ese grafo, cómo corre y qué controles tenés sobre él.

Cuatro formas de empezar

Desde una plantilla. El botón Nuevo workflow abre la galería de plantillas: atención al cliente, calificación de leads, mesa de ayuda interna y otras. Elegís una, la aplicás y el agente queda creado con un workflow que ya funciona. Es el camino más corto cuando el caso es habitual.

En blanco. La primera tarjeta de la galería crea un agente vacío y te lleva directo al editor.

Con el AI Builder. La pestaña AI Builder es un chat: describís lo que necesitás y el asistente del admin arma el agente con las mismas herramientas que usarías vos, mostrándote el resultado a medida que lo construye. El agente que crea nace como borrador, así que podés revisarlo antes de que responda a nadie.

Importando un artefacto. Cada agente se puede exportar como un archivo .artifact.json que contiene su definición completa. Importarlo en otro tenant recrea el agente tal cual. Es la forma de llevar un agente de un tenant de pruebas al del cliente, de guardar una copia antes de un cambio grande o de versionar agentes en Git.

En todos los casos la creación descuenta del límite de agentes del tenant; si está lleno, la plataforma lo rechaza con un error de cuota.

Agentes del tenant de Clínica del Sol, con su estado y accesos directos
Agentes del tenant de Clínica del Sol, con su estado y accesos directos

Asistente o workflow

Para la clínica, Nortelink arrancó con un asistente: un formulario donde se cargan las instrucciones, el conocimiento y las herramientas. Al guardar, un compilador convierte ese formulario en un grafo. Con una base de conocimiento y sin herramientas, el grafo que produce el asistente simple es este:

contexto de conversación → guardrail de entrada → búsqueda en conocimiento → respuesta del modelo

El guardrail de entrada revisa intentos de inyección de instrucciones y de jailbreak antes de que el mensaje llegue al modelo. Si el asistente tiene herramientas, el compilador agrega un ciclo de uso de herramientas. La compilación ocurre al guardar, no en cada mensaje: lo que se ejecuta es el grafo guardado.

Cuando el caso crece —derivar a un humano, pedir confirmación antes de reservar un turno, clasificar la consulta antes de responder— el asistente se puede expulsar a workflow. La plataforma conserva el grafo compilado y descarta el formulario, y a partir de ahí lo editás nodo por nodo. Es un camino de ida: un workflow no vuelve a ser asistente.

Los nodos

El editor ofrece diecinueve tipos de nodo. No hace falta conocerlos todos para empezar; estos son los que aparecen en casi cualquier agente:

NodoQué hace
Contexto de conversaciónReúne el historial y el resumen de la sesión para los pasos siguientes
GuardrailRevisa la entrada o la salida contra reglas: inyección, temas prohibidos, datos personales
BúsquedaTrae fragmentos de las bases de conocimiento (capítulo 4)
Tarea de modeloUna llamada al modelo con instrucciones y datos del estado
Router de herramientasDeja que el modelo decida qué herramientas usar, en un ciclo, hasta resolver (capítulo 5)
Si / entonces y ClasificadorBifurcan el flujo por una condición o por la categoría del mensaje
Responder y Plantilla de contenidoArman la respuesta final, en texto o como tarjeta estructurada
AgenteDelega una tarea a otro agente del mismo tenant
Compuerta de aprobaciónPausa la ejecución hasta que una persona decida
GrupoRepite un conjunto de nodos hasta que se cumple una condición

Hay nodos que dependen de funcionalidades del tenant: generación de imágenes, la compuerta de aprobación y la herramienta directa, y el nodo de código. Si no los ves en la paleta, no están habilitados para ese tenant.

Editor de workflow con el agente de turnos de la clínica
Editor de workflow con el agente de turnos de la clínica

Cómo corre un mensaje

Cuando llega un mensaje, la plataforma valida la topología del grafo y lo recorre desde el nodo de entrada:

  • Las aristas definen el orden. Si un nodo tiene varias aristas de salida, los nodos siguientes corren en paralelo. Así, buscar en el conocimiento y clasificar la consulta pueden pasar al mismo tiempo.
  • Las bifurcaciones eligen un camino. Si / entonces, Clasificador y la compuerta de aprobación mandan el flujo por una sola salida según el resultado.
  • Un nodo sin salidas termina la ejecución.
  • Cada paso queda registrado: qué modelo usó, cuánto tardó, cuántos tokens consumió, qué entró y qué salió. Es lo que vas a ver en el historial (capítulo 7).

Hay límites que protegen de un agente que se descontrola:

  • El router de herramientas corta a las 10 llamadas a herramientas por defecto. El límite se puede ajustar por nodo, y la profundidad del ciclo crece en proporción.
  • Un grupo repite como máximo 10 vueltas salvo que configures otro máximo.
  • Un subagente se puede anidar hasta 5 niveles, tiene 120 segundos por defecto para responder, tiene que ser del mismo tenant y tener una versión activa. Las referencias circulares se rechazan. Si un subagente falla, el error vuelve como resultado del paso y el agente que lo llamó sigue.
  • A nivel de ejecución completa se pueden fijar topes de llamadas al modelo, de costo y de llamadas a herramientas.

Probar en el playground

El playground es un chat con el agente, con la línea de tiempo de cada ejecución al lado: qué nodos corrieron, en qué orden, con qué modelo y qué devolvió cada uno. Es la forma más rápida de entender por qué el agente respondió lo que respondió.

El playground ejecuta la versión activa del agente. Un borrador recién creado por el AI Builder hay que activarlo antes de poder probarlo ahí.

Versiones: qué pasa al guardar

El capítulo 1 explica los estados de una versión y la activación de versiones de la cuenta. En la práctica de construir un agente, lo que importa es:

  • En el editor de workflow, guardar un nodo guarda todo el workflow: el nodo, las conexiones, el punto de entrada, las posiciones y las variables. El panel del nodo queda abierto y no hace falta un segundo guardado. Si el guardado falla, los cambios quedan en pantalla para reintentar.
  • Con activación automática, guardar un formulario crea una versión nueva y la activa en el momento, y guardar en el editor de workflow escribe sobre la versión en vivo.
  • Con activación manual, todo guardado va a una única versión pendiente; nada cambia para los usuarios hasta que la activás. Guardar varias veces no crea varias versiones.
  • Si otra persona cambió el workflow mientras lo editabas, el guardado se rechaza con un aviso de conflicto. Copiá tus cambios antes de recargar.
  • Restaurar una versión es activarla desde el historial: todas las demás pasan a inactivas y esa vuelve a responder.

Con activación automática, antes de tocar el workflow de un agente en producción, exportalo: es tu punto de retorno. Con activación manual, el punto de retorno es la versión en vivo, que sigue respondiendo hasta que actives la pendiente.

Aprobación humana

La compuerta de aprobación pausa el workflow y guarda su estado hasta que alguien decida. Tiene dos audiencias:

  • Usuario. La pregunta aparece en la misma conversación: "¿Confirmás el turno del martes a las 10 con la Dra. Paz?", con botones para aprobar o rechazar. Sirve para que el usuario confirme una acción antes de que el agente la ejecute.
  • Supervisor. La solicitud aparece en Monitoreo → Aprobaciones del admin, donde alguien del equipo la aprueba o la rechaza. Sirve para acciones que no debería decidir el usuario final: un reembolso, una excepción a una política.

La compuerta admite aprobar/rechazar, botones, texto libre, aprobar con comentario y selección múltiple. Si nadie decide, la solicitud vence a los 60 minutos por defecto, y una solicitud vencida ya no se puede aprobar.

Aprobaciones pendientes de supervisor en el admin
Aprobaciones pendientes de supervisor en el admin

Ejecuciones programadas

Un agente también puede correr sin que nadie le escriba: con una programación en formato cron y una zona horaria, recibe un mensaje de entrada fijo a la hora indicada. La clínica lo usa para que el agente revise cada mañana los turnos del día y avise los cambios.

Por defecto, cada programación corre una ejecución a la vez y la corta a los 2 minutos; se puede llevar hasta 10 simultáneas y 5 minutos. Si llega la hora y ya hay tantas ejecuciones en curso como el máximo, la nueva espera en cola: no se pierde.

Cada ejecución empieza una conversación nueva —no recuerda la anterior— y recibe el mensaje fijo, los datos de disparo que hayas definido y la hora para la que estaba programada. Con Reintentar una vez si falla, una ejecución fallida se intenta otra vez. Si falla varias veces seguidas —5 por defecto— la programación se pausa sola, para no seguir consumiendo con un error que no se va a resolver solo. Editar o desactivar una programación cancela las ejecuciones que todavía estaban en cola.

El resultado de cada ejecución —también las fallidas, con su error— se ve en la pestaña Programación del agente y en Monitoreo → Ejecuciones de programa.

Dónde termina

  • Con activación automática no hay revisión antes de publicar, y el editor de workflow no deja versión anterior al guardar. La revisión previa existe solo si la cuenta usa activación manual.
  • El router de herramientas limita la cantidad de llamadas, no detecta llamadas repetidas. Un agente que llama diez veces a la misma herramienta con los mismos datos llega al tope antes de cortar.
  • Subagentes: 5 niveles, 120 segundos, mismo tenant y solo versiones activas.
  • Programaciones: hasta 10 ejecuciones simultáneas y 5 minutos por ejecución; cada una empieza sin memoria de la anterior.
  • Las aprobaciones de usuario solo se responden en la conversación; el admin solo decide las de supervisor.

Para revisar

  • La cuenta usa la activación de versiones que corresponde: manual para clientes en producción, automática solo donde un cambio sin revisar no le llega a nadie.
  • Cada agente en producción tiene una exportación reciente guardada fuera de la plataforma.
  • Los routers de herramientas tienen un tope de llamadas acorde a lo que el agente realmente necesita, no el valor por defecto por inercia.
  • Las acciones con efecto real —reservar, cobrar, cancelar— pasan por una compuerta de aprobación.
  • Las compuertas de supervisor tienen a alguien mirando Aprobaciones dentro de la hora.
  • Los subagentes que usás tienen versión activa: si alguien desactiva uno, el agente que lo llama empieza a recibir errores en ese paso.