Versiones de agentes

Una versión de agente identifica una versión desplegada del agente. Puede cambiar su prompt, modelo, voz, transcripción, herramientas o flujo de trabajo. Dos versiones pueden tener prompts idénticos y pipelines diferentes. Los Experimentos comparan llamadas de exactamente dos versiones desplegadas del mismo agente. La atribución correcta determina la validez de la comparación: Zelto utiliza la versión indicada para cada llamada, no una suposición basada en su transcripción o en la configuración actual.

Tres identificadores con funciones diferentes

Campo	Qué identifica	Cuándo cambia
`agent.externalId`	El agente entre despliegues, dentro de tu organización y proveedor. También puedes enviar un `agentId` de Zelto existente.	Cuando es otro agente, no otra versión o sesión.
`version`, en el nivel superior	La versión desplegada que atendió la llamada.	Al desplegar un cambio de prompt o pipeline que quieras distinguir.
`call.externalId`	Una llamada o sesión.	Para cada llamada nueva. Reutilízalo al reintentar esa llamada.

Por ejemplo, support-agent puede recibir llamadas de support-2026-09-a y support-2026-09-b. Mantén el mismo agent.externalId para ambas. Si asignas un ID de agente diferente a cada versión, crearás agentes separados que no se pueden seleccionar como las dos versiones de un experimento.

Declarar versiones en LiveKit o una integración propia

Envía version en el nivel superior de cada carga a POST https://ingest.zelto.ai/webhooks/calls. El campo se llama version, no prompt_version, agent.version ni metadata.version. La API acepta una cadena de 1 a 255 caracteres después de eliminar los espacios de los extremos. Distingue mayúsculas: release-a y Release-A son versiones diferentes. Puedes usar una etiqueta de despliegue, un ID de compilación inmutable o un hash de toda la configuración versionada. Un hash solo del prompt no distingue cambios exclusivos del pipeline.

{
  "agent": {
    "externalId": "support-agent",
    "name": "Atención al cliente"
  },
  "version": "support-2026-09-a",
  "call": {
    "externalId": "session-001",
    "startedAt": "2026-09-09T10:00:00Z"
  },
  "endUserId": "customer-123",
  "systemPrompt": "Eres un agente de soporte. Confirma el siguiente paso antes de finalizar la llamada.",
  "transcript": {
    "turns": [
      {
        "role": "user",
        "content": "¿Cuándo llegará mi pedido?"
      },
      {
        "role": "assistant",
        "content": "Voy a consultar la fecha estimada de entrega."
      }
    ]
  },
  "versionConfig": {
    "llm": {
      "provider": "your-llm-provider",
      "model": "your-model-id",
      "temperature": 0.2
    },
    "stt": {
      "provider": "your-stt-provider",
      "model": "your-stt-model"
    },
    "tts": {
      "provider": "your-tts-provider",
      "model": "your-tts-model",
      "voice": "your-voice-id"
    },
    "tools": [
      {
        "name": "lookup_order",
        "timeoutMs": 3000
      }
    ],
    "workflow": {
      "entry": "greeting",
      "steps": [
        "greeting",
        "lookup",
        "resolution"
      ]
    },
    "runtime": {
      "releaseCommit": "abc123",
      "region": "your-region"
    }
  }
}

Usa Authorization: Bearer $ZELTO_API_KEY, Content-Type: application/json y X-Zelto-Provider: livekit para LiveKit, o zelto para cargas propias. Consulta el ejemplo de LiveKit y el contrato de carga de llamadas. Puedes registrar una versión antes de enviar llamadas. De lo contrario, la primera llamada procesada con una etiqueta nueva crea la versión declarada; las siguientes con el mismo agente y etiqueta la reutilizan. No hace falta otra solicitud para crear la versión. Zelto también asigna un número como v1 o v2 según el orden de primera aparición. Ese número es independiente de tu etiqueta: envía la etiqueta del despliegue, no un número deducido del panel.

version es opcional para la ingesta general. En integraciones destinadas a experimentos, envía una versión explícita en cada llamada para atribuirla al despliegue que realmente la atendió.

Mantener cada etiqueta ligada a un despliegue

Cambia la etiqueta al modificar el prompt, modelo, voz, transcripción, herramientas o flujo de trabajo que quieras identificar por separado.
Mantenla estable entre las llamadas de esa versión. No uses un ID de sala, cliente, marca de tiempo por llamada ni UUID aleatorio como etiqueta.
Captura la etiqueta y configuración de la sesión que atendió la llamada. Puede haber un despliegue mientras está en curso: no etiquetes una carga tardía con la versión vigente en el momento de enviarla.
En los reintentos, conserva el ID de llamada, versión y capturas originales. No cambies la etiqueta de llamadas antiguas para moverlas a otro lado.
Al volver a un despliegue sin cambios, reutiliza su etiqueta. Si necesitas distinguir dos despliegues de código idéntico, usa etiquetas diferentes de forma consistente.

Reutilizar una etiqueta después de cambiar la configuración mezcla las llamadas de ambos despliegues en una sola versión. Tu integración proporciona la etiqueta; Zelto no verifica que todas sus llamadas usaran una compilación idéntica.

Registrar una versión en Zelto

Los propietarios y administradores pueden abrir Agentes → tu agente → Versiones → Registrar versión. Introduce la etiqueta, el prompt opcional y los proveedores/modelos de LLM, STT y TTS. TTS incluye un campo de ID de voz. En Configuración adicional (JSON) puedes describir herramientas, flujos, bases de conocimiento, ejecución y contexto propio. También admite ajustes como llm.temperature; los campos de proveedor/modelo anteriores tienen prioridad. Registrar guarda contexto, no despliega ni ejecuta la configuración. Los candidatos de prompt en borrador siguen siendo independientes.

Registrar una versión mediante la API

Usa una clave de la organización cuyo propietario sea dueño o administrador. El agente debe existir en esa organización. Envía POST /v1/agents/{id}/versions al host de la API de la plataforma, con el UUID del agente en Zelto:

curl -X POST "https://api.zelto.ai/v1/agents/$AGENT_ID/versions" \
  -H "Authorization: Bearer $ZELTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @version.json

version.json

{
  "version": "support-2026-09-a",
  "systemPrompt": "Eres un agente de soporte. Confirma el siguiente paso antes de finalizar la llamada.",
  "config": {
    "llm": { "provider": "your-llm-provider", "model": "your-model-id", "temperature": 0.2 },
    "stt": { "provider": "your-stt-provider", "model": "your-stt-model" },
    "tts": { "provider": "your-tts-provider", "model": "your-tts-model", "voice": "your-voice-id" },
    "tools": [{ "name": "lookup_order", "timeoutMs": 3000 }],
    "workflow": { "entry": "greeting", "steps": ["greeting", "lookup", "resolution"] },
    "runtime": { "releaseCommit": "abc123", "region": "your-region" }
  }
}

Un registro nuevo devuelve HTTP 201 con { "id": "<UUID de versión>", "created": true }. Repetir la misma etiqueta y configuración devuelve HTTP 200 con created: false. Un prompt o configuración diferentes para una versión existente devuelven 409 Conflict: usa otra etiqueta. Los campos omitidos en un reintento no cambian los valores existentes. Los prefijos draft: y generated: están reservados. La carga de llamadas permanece en https://ingest.zelto.ai/webhooks/calls. Registrar una versión no la convierte en la opción de respaldo para llamadas sin versión. Se considera observada cuando una llamada procesada informa explícitamente su etiqueta. El registro utiliza config; la carga utiliza versionConfig, junto con version. Ambos guardan la misma configuración de versión. Después de registrar, envía la etiqueta en cada llamada, no el UUID devuelto ni el número del panel.

La identidad y la configuración son independientes

version asigna llamadas a un despliegue. Tu organización proporciona su configuración: proveedores, modelos, voz, herramientas, recuperación de datos, flujos, ejecución y componentes propios. Se conservan todos los campos JSON y se muestran en el detalle y comparación, incluida la creación de experimentos. Envía un objeto JSON, de hasta 64 KiB serializado en UTF-8. llm, stt y tts son convenciones del formulario, no una lista cerrada. Se admiten otras claves y objetos/listas anidados. Incluye configuración, no claves ni credenciales. Este contexto es descriptivo: Zelto no ejecuta flujos, configura proveedores ni descubre los ajustes que falten. Envía el prompt real como systemPrompt o como turno inicial system en cargas de llamadas. La etiqueta por sí sola no proporciona un prompt. La primera llamada puede crear la versión con versionConfig. Las cargas posteriores no reemplazan capturas existentes; pueden completar una ausente. Envía configuración completa desde el principio y usa otra etiqueta al cambiarla. Una captura antigua de metadatos también cuenta como existente: una carga posterior no combina versionConfig con ella. En versiones antiguas sin configuración explícita, Zelto solo muestra modelo, transcripción y voz capturados de los metadatos. Una captura ausente no prueba que los pipelines sean idénticos. El contexto completo de herramientas y flujos está disponible cuando lo proporciona tu integración o formulario; no se recopila automáticamente.

Versiones del proveedor y versiones automáticas

Integración	Cómo proporciona la identidad
LiveKit o carga propia	Envía `version` en cada llamada. Tu worker proporciona la etiqueta y las capturas.
Vapi	Las etiquetas de versión de asistente publicadas e incluidas en los webhooks identifican el despliegue. El webhook puede aportar modelo, voz y transcripción. Sin etiqueta se usa la alternativa automática.
Retell	Se usa `agent_version` de la llamada, incluido `0`. Identifica la versión; el prompt actual no sustituye una captura histórica no disponible.

Sin version explícito en LiveKit o cargas propias, Zelto crea una versión generada inicial si hace falta y asigna las siguientes llamadas a la última versión desplegada. Un proceso semanal puede crear otra cuando cambia el prompt generalizado. No detecta cambios exclusivos del pipeline ni distingue inmediatamente dos despliegues simultáneos. Usa etiquetas explícitas para experimentos. Un candidato en borrador creado en Zelto sirve para simulaciones. No ha atendido llamadas reales y no se puede seleccionar como lado de un experimento. Despliega la versión en tu plataforma y envía llamadas con su etiqueta.

Verificar antes de lanzar un experimento

Envía una llamada de A y otra de B con el mismo ID de agente, IDs de llamada distintos y etiquetas de versión diferentes.
Espera al procesamiento. HTTP 200 con { "received": true } confirma aceptación; no significa que la llamada y versión ya estén visibles.
Abre Versiones del agente. Confirma las etiquetas y las llamadas asignadas a cada una. Revisa las capturas cuando estén disponibles.
Abre Experimentos → Nuevo experimento y selecciona ese agente y las dos versiones. Revisa las diferencias capturadas y el tráfico reciente.
Elige monitores configurados y comprueba el tráfico reciente. Las llamadas históricas verifican la configuración; no rellenan los resultados nuevos.
Introduce un nombre y lanza el experimento. Sigue indicando la versión real en cada llamada futura y enruta a las personas de forma consistente en tu plataforma. Envía un endUserId estable cuando esté disponible.

Las versiones elegidas quedan fijas al lanzar. Un tercer despliegue no sustituye a A o B automáticamente: necesita un experimento nuevo. Zelto observa el tráfico; no despliega versiones ni enruta llamadas.

Resolver problemas

Síntoma	Qué comprobar
Dos despliegues aparecen como una versión	Envía valores `version` distintos en el nivel superior. Comprueba si falta la etiqueta o se reutilizó.
Cada llamada crea una versión	No uses valores por sesión en `version`; el campo único debe ser `call.externalId`.
No puedes seleccionar las dos versiones juntas	Deben ser versiones desplegadas del mismo agente. Conserva el ID del agente y comprueba que no sean borradores.
La versión existe sin prompt o configuración	Envía las capturas reales del worker. La etiqueta por sí sola no contiene configuración.
Cambiar el modelo no crea una versión	La detección automática se basa en el prompt. Envía otra etiqueta explícita.
Hay llamadas recientes pero no resultados	La vista previa incluye llamadas históricas; los resultados utilizan llamadas elegibles dentro de la ventana del experimento y requieren procesamiento de evaluación.

Primeros pasos

Conceptos principales

Integraciones

Guías

Cuenta y configuración

Legal

Versiones de agentes

Tres identificadores con funciones diferentes

Declarar versiones en LiveKit o una integración propia

Mantener cada etiqueta ligada a un despliegue

Registrar una versión en Zelto

Registrar una versión mediante la API

La identidad y la configuración son independientes

Versiones del proveedor y versiones automáticas

Verificar antes de lanzar un experimento

Resolver problemas

​Tres identificadores con funciones diferentes

​Declarar versiones en LiveKit o una integración propia

​Mantener cada etiqueta ligada a un despliegue

​Registrar una versión en Zelto

​Registrar una versión mediante la API

​La identidad y la configuración son independientes

​Versiones del proveedor y versiones automáticas

​Verificar antes de lanzar un experimento

​Resolver problemas

Tres identificadores con funciones diferentes

Declarar versiones en LiveKit o una integración propia

Mantener cada etiqueta ligada a un despliegue

Registrar una versión en Zelto

Registrar una versión mediante la API

La identidad y la configuración son independientes

Versiones del proveedor y versiones automáticas

Verificar antes de lanzar un experimento

Resolver problemas