> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelto.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Versiones de agentes
> Identifica la versión desplegada que atendió cada llamada para que los experimentos comparen las versiones correctas.
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](/es/docs/experiments) 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.
```json theme={null}
{
"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](/es/docs/integrations/livekit#enviar-una-sesión)
y el [contrato de carga de llamadas](/es/docs/integrations/api-call-upload).
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:
```bash theme={null}
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
```
```json title="version.json" theme={null}
{
"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": "",
"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
1. 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.
2. Espera al procesamiento. HTTP `200` con `{ "received": true }` confirma
aceptación; no significa que la llamada y versión ya estén visibles.
3. Abre **Versiones** del agente. Confirma las etiquetas y las llamadas
asignadas a cada una. Revisa las capturas cuando estén disponibles.
4. Abre **Experimentos → Nuevo experimento** y selecciona ese agente y las dos
versiones. Revisa las diferencias capturadas y el tráfico reciente.
5. Elige monitores configurados y comprueba el tráfico reciente. Las llamadas
históricas verifican la configuración; no rellenan los resultados nuevos.
6. 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. |