Modelos de lenguaje — Manual del operador | AI Agent Builder

Capítulo 2

Modelos de lenguaje

Cómo se conecta un proveedor, cómo elige el runtime el modelo de cada paso y qué pasa cuando un proveedor falla.

8 min de lectura · Actualizado 10 de noviembre de 2026

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

Un agente no tiene "un modelo". Cada paso de un workflow le pide a la plataforma un modelo para una tarea, y la plataforma decide cuál usar con reglas que vos configurás una vez por tenant. Entender esas reglas es lo que permite cambiar de proveedor sin tocar los agentes, controlar el costo y saber exactamente qué va a pasar el día que un proveedor se caiga.

Una conexión es una credencial y una lista de modelos permitidos

Una conexión representa una cuenta con un proveedor. Guarda el proveedor, la credencial, opcionalmente una URL base, la lista de modelos habilitados y, si querés, un precio propio por modelo.

El editor ofrece OpenAI, Anthropic, Google, DeepSeek, Deepgram y cualquier proveedor compatible con OpenAI (vLLM, Ollama, Azure OpenAI, OpenRouter y similares). Para los proveedores conocidos la plataforma completa sola cómo va la credencial en el pedido: vos solo pegás la clave.

Cuando guardás, pasan tres cosas:

  1. La clave sale del registro de la conexión. Se cifra y se guarda aparte, y la conexión se queda solo con una referencia. Lo que viaja de vuelta al admin dice "hay un secreto configurado", nunca la clave.
  2. La plataforma prueba la clave contra el proveedor. Si falla, la conexión igual se guarda, pero vuelve con una advertencia. Así podés cargar una conexión antes de tener la clave definitiva, y no perdés el resto del formulario por un error de tipeo.
  3. Los modelos habilitados pasan a ser una lista blanca. Cada llamada al proveedor se controla contra esa lista en el momento de hacerse. Si la lista está vacía, se permite cualquier modelo.

Así se ve la credencial antes y después de guardar:

lo que cargás      →  apiKey: "sk-proj-…"
lo que se guarda   →  valueSource: { kind: "secret_ref", secretRef: "sec_9f2c…" }
lo que ves después →  secreto configurado ✓

Crear conexiones requiere que el tenant tenga habilitada la funcionalidad de traer tu propia clave. Sin ella, el tenant usa las conexiones que hereda.

Proveedores IA: conexiones del tenant, su estado de salud y los modelos por defecto
Proveedores IA: conexiones del tenant, su estado de salud y los modelos por defecto

Los niveles de razonamiento separan al agente del modelo

Si cada nodo de cada agente nombrara un modelo concreto, cambiar de proveedor implicaría editar todos los agentes. Por eso la plataforma trabaja con niveles: el nodo dice qué tipo de tarea es, y el tenant define qué modelo atiende cada tipo.

NivelPara qué se usa
lowTareas simples y baratas: clasificar, extraer un dato
normalLa conversación habitual
highRazonamiento largo o delicado
decisionDecisiones de enrutamiento dentro del workflow
voiceReconocimiento de voz: el dictado del widget y las llamadas por Asterisk
ttsTexto a voz en las llamadas por Asterisk
embeddingIndexar y buscar en bases de conocimiento
image_generationGenerar imágenes

Cada nivel tiene un modelo principal y hasta tres alternativas en orden. Al guardar, la plataforma valida cada entrada: que la conexión sea visible para el tenant y esté activa, que el modelo esté entre los habilitados y que tenga la capacidad que el nivel necesita. No te va a dejar poner un modelo sin soporte de embeddings en embedding.

Para embedding hay una regla adicional: las alternativas tienen que usar el mismo modelo que el principal, aunque sea a través de otra conexión. Los vectores de dos modelos distintos no son comparables, así que un fallback a otro modelo devolvería resultados sin sentido. Y si cambiás el modelo de embedding, la plataforma encola sola la reindexación de las bases de conocimiento.

Cómo elige el runtime el modelo de un paso

Cuando un paso necesita un modelo, el runtime resuelve en este orden:

  1. Si el nodo tiene un modelo explícito, usa ese.
  2. Si no, usa la cadena del nivel del nodo. Un nivel desconocido cae en normal.
  3. Si no hay nada configurado, degrada: la conexión del nodo, si tiene; si no, el nivel normal; si no, la primera conexión activa con su primer modelo habilitado.

El paso 3 existe para que un tenant recién creado funcione sin configurar nada. En producción conviene no depender de él: si el modelo que responde depende del orden en que se crearon las conexiones, el comportamiento del agente cambia cuando alguien agrega una.

Qué pasa cuando un proveedor falla

Cada combinación de conexión y modelo tiene su propio circuit breaker: un contador que mira la tasa de error en una ventana móvil de 60 segundos.

  • Con al menos 5 llamadas en la ventana y 50 % o más de errores, el circuito se abre: esa combinación deja de recibir tráfico.
  • A los 30 segundos pasa a semiabierto y deja pasar llamadas de prueba. Si responden bien, se cierra.
  • Cada llamada tiene un tiempo máximo de 45 segundos.
  • Entre "sano" y "abierto" hay un estado degradado que se muestra en el admin como aviso, pero no corta el tráfico.

Cuando el circuito del principal está abierto, el siguiente pedido lo atiende la primera alternativa disponible del nivel, y queda registrado un evento de failover con qué modelo reemplazó a cuál y por qué.

Seguimos con la clínica. Su nivel normal apunta a gpt-4.1 por la conexión de OpenAI, con Claude como alternativa:

  1. OpenAI empieza a devolver errores. En un minuto, 4 de 7 llamadas fallan.
  2. El circuito de OpenAI + gpt-4.1 se abre.
  3. La siguiente conversación de un paciente la responde Claude. En Monitoreo → Historial de failover aparece el evento con motivo "circuito abierto".
  4. A los 30 segundos la plataforma vuelve a probar OpenAI. Si responde, el tráfico regresa.
  5. Si Claude también estuviera caído, la conversación falla con un error explícito de "todas las alternativas no disponibles".

La regla de fondo es que el failover solo recorre la cadena que configuraste. La plataforma nunca elige por su cuenta un modelo que no pusiste. Es preferible un error claro a que el agente de la clínica responda con un modelo que nadie evaluó.

Historial de failover: qué modelo reemplazó a cuál, cuándo y por qué
Historial de failover: qué modelo reemplazó a cuál, cuándo y por qué

Desde el admin también podés forzar el failover de una conexión (por ejemplo, ante un incidente anunciado por el proveedor) y restaurar el principal cuando pase. Las dos acciones quedan auditadas en el mismo historial.

Herencia: el hijo usa las del padre hasta que tiene propias

Clínica del Sol no tiene conexiones propias. Tiene activada la herencia, así que usa las de Nortelink, y la pantalla de proveedores lo muestra con un aviso que indica de qué tenant vienen.

El día que alguien en la clínica crea su propia conexión, por ejemplo para probar un modelo nuevo, la herencia se corta entera: los agentes de la clínica ven solo esa conexión. Si los niveles por defecto de la clínica apuntaban a conexiones de Nortelink, esos niveles ya no resuelven. La plataforma no mezcla conexiones propias y heredadas, justamente para que no haya ambigüedad sobre quién paga cada llamada.

Si un tenant no tiene conexiones propias, no tiene la herencia activada o ningún ancestro tiene conexiones, sus agentes fallan con un error que dice cuál de esos casos es.

Borrar una conexión

No se puede borrar una conexión que algún agente usa: la plataforma lo rechaza y te dice que hay referencias. Si solo la referencian los niveles por defecto, esas referencias se limpian primero. Al borrarla también se purgan sus eventos de failover.

Dónde termina

  • Los parámetros del circuit breaker son fijos. Los umbrales de arriba (5 llamadas, 50 %, 30 s, 45 s) son los mismos para todos los tenants y no se ajustan desde el admin.
  • Cada instancia del runtime lleva su propio circuito. Con varias instancias, cada una detecta la falla por su cuenta; puede haber unos segundos en que una ya hizo failover y otra todavía no.
  • El failover forzado no sobrevive a un reinicio del runtime: después de un reinicio, el circuito vuelve a su estado natural.
  • Hasta tres alternativas por nivel.
  • El descubrimiento automático de modelos funciona con los proveedores principales. Para los compatibles con OpenAI que no publican su lista, los modelos se cargan a mano.
  • El estado de salud aparece como "desconocido" si el admin no logra consultar al runtime en 5 segundos. No significa que la conexión esté caída.

Para revisar

  • Cada nivel que usan tus agentes en producción tiene principal y al menos una alternativa de otro proveedor.
  • Las alternativas de embedding usan el mismo modelo que el principal.
  • Las conexiones tienen la lista de modelos habilitados cargada. Una lista vacía permite cualquier modelo, incluidos los más caros.
  • Si un cliente hereda modelos, no tiene conexiones propias olvidadas.
  • Si cargaste precios propios por modelo, coinciden con tu contrato con el proveedor: son los que usa la plataforma para calcular el costo de cada llamada.