> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Control de versiones de agentes

El control de versiones de agentes te permite experimentar con distintas configuraciones de tu agente sin poner en riesgo tu configuración de producción. Crea ramas aisladas, prueba cambios y despliega actualizaciones gradualmente mediante porcentajes de tráfico.

> **Note**
>
> ¿Quieres realizar pruebas A/B? Consulta [Experimentos](/docs/es/eleven-agents/operate/experiments) para conocer el flujo de trabajo recomendado para probar cambios en agentes con tráfico real.

## Descripción general

El sistema de control de versiones proporciona:

* **Instantáneas inmutables** de la configuración de tu agente en cualquier momento
* **Ramas aisladas** para probar cambios antes de publicarlos
* **División del tráfico** para desplegar cambios gradualmente a un porcentaje de usuarios
* **Fusión** para incorporar cambios de cualquier rama en cualquier otra rama
* **Rebase** para incorporar los cambios más recientes de la rama principal en una rama

> **Note**
>
> Una vez que se activa el control de versiones en un agente, no se puede desactivar. Tenlo en cuenta antes de activar
> el control de versiones en agentes existentes.

## Conceptos básicos

### Versiones

Una versión es una instantánea inmutable de la configuración de un agente en un momento concreto. Cada versión tiene un ID único (formato: `agtvrsn_xxxx`) y contiene:

* `conversation_config` - Prompt del sistema, ajustes del LLM, configuración de voz, herramientas, base de conocimientos
* `platform_settings` - Subconjunto versionado que incluye ajustes de evaluación, widget, recopilación de datos y seguridad
* `workflow` - Definición completa del flujo de trabajo con nodos y conexiones

Las versiones se crean automáticamente al guardar cambios en un agente con control de versiones. Una vez creada, una versión no se puede modificar.

### Ramas

Las ramas son líneas de desarrollo con nombre, similares a las ramas de git. Te permiten trabajar en cambios de forma aislada antes de fusionarlos de nuevo en la rama principal.

* Cada agente con control de versiones tiene una rama **Main** que no se puede eliminar ni archivar
* Se pueden crear ramas adicionales desde cualquier versión de cualquier rama existente, no solo desde la principal
* Las ramas se pueden fusionar en cualquier otra rama, y las ramas que no son principales pueden hacer rebase sobre la principal para incorporar sus cambios más recientes
* Cada rama tiene: ID (`agtbrch_xxxx`), nombre, descripción y una lista de versiones
* Los nombres de rama pueden contener: letras, números y `() [] {} - / .` (máximo 140 caracteres)

### Despliegue de tráfico

El tráfico se puede dividir entre varias ramas por porcentaje, lo que permite despliegues graduales y pruebas A/B.

* Los porcentajes siempre deben sumar exactamente **100%**
* El enrutamiento del tráfico es **determinista** según el ID de conversación (el mismo usuario siempre se dirige a la misma rama)
* Solo se pueden archivar ramas no archivadas con un 0 % de tráfico

### Borradores

Los cambios sin guardar se almacenan como borradores, lo que te permite trabajar en cambios sin crear inmediatamente una versión nueva.

* Los borradores son **por usuario y por rama** (cada miembro del equipo tiene su propio borrador)
* Los borradores se descartan automáticamente al confirmar una nueva versión
* Los borradores también se descartan al fusionar en una rama

## Activar el control de versiones

El control de versiones es opcional y debe activarse explícitamente. Puedes activarlo al crear un agente nuevo o en un agente existente.

> **Warning**
>
> Una vez activado, el control de versiones no se puede desactivar. Es un cambio permanente en tu agente.

### Activar al crear un agente

#### Activar desde el panel de control

Abre tu agente en el panel de control, ve a **Ajustes** y activa el control de versiones. Una vez activado, la pestaña **Control de versiones** estará disponible para gestionar ramas, borradores, versiones y el despliegue de tráfico.

#### Activar mediante la API

```python
from elevenlabs.client import ElevenLabs
from elevenlabs.types import *

client = ElevenLabs(api_key="your-api-key")

agent = client.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hello! How can I help you today?",
            prompt={"prompt": "You are a helpful assistant."},
        )
    ),
    enable_versioning=True
)

print(f"Agent created with versioning: {agent.agent_id}")
```

```javascript
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

const client = new ElevenLabsClient({ apiKey: 'your-api-key' });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: 'Hello! How can I help you today?',
      prompt: {
        prompt: 'You are a helpful assistant.',
      },
    },
  },
  enableVersioning: true,
});

console.log(`Agent created with versioning: ${agent.agentId}`);
```

### Activar en un agente existente

#### Activar desde el panel de control

Abre tu agente en el panel de control, ve a **Ajustes** y activa el control de versiones.

#### Activar mediante la API

```python
agent = client.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    enable_versioning_if_not_enabled=True
)
```

```javascript
const agent = await client.conversationalAi.agents.update('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  enableVersioningIfNotEnabled: true,
});
```

Al activar el control de versiones se crea la rama inicial "Main" con la primera versión, que contiene la configuración actual del agente.

## Trabajar con ramas

### Crear una rama

Las ramas se pueden crear desde cualquier versión de cualquier rama, no solo desde la principal. También puedes incluir cambios de configuración que se aplicarán a la versión inicial de la nueva rama.

```python
branch = client.conversational_ai.agents.branches.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    parent_version_id="agtvrsn_xxxx",
    name="experiment-v2",
    description="Testing new prompt and voice settings"
)

print(f"Created branch: {branch.created_branch_id}")
print(f"Initial version: {branch.created_version_id}")
```

```javascript
const branch = await client.conversationalAi.agents.branches.create('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  parentVersionId: 'agtvrsn_xxxx',
  name: 'experiment-v2',
  description: 'Testing new prompt and voice settings',
});

console.log(`Created branch: ${branch.createdBranchId}`);
console.log(`Initial version: ${branch.createdVersionId}`);

```

### Listar ramas

```python
branches = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)

for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

```

```javascript
const branches = await client.conversationalAi.agents.branches.list('agent_7101k5zvyjhmfg983brhmhkd98n6');

for (const branch of branches.branches) {
  console.log(`${branch.name}: ${branch.id}`);
}

```

### Obtener detalles de una rama

```python
branch = client.conversational_ai.agents.branches.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

print(f"Branch: {branch.name}")
print(f"Versions: {len(branch.versions)}")

```

```javascript
const branch = await client.conversationalAi.agents.branches.get('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx');

console.log(`Branch: ${branch.name}`);
console.log(`Versions: ${branch.versions.length}`);

```

## Confirmar cambios

Al actualizar un agente con el control de versiones activado, especifica `branch_id` para crear una nueva versión en esa rama.

#### Actualizar desde el panel de control

Abre la pestaña **Control de versiones** de tu agente, cambia a la rama de destino, edita la configuración y guarda los cambios para crear una nueva versión.

#### Actualizar mediante la CLI

Pasa la marca `--branch` para enviar cambios a una rama concreta por nombre o ID. La rama ya debe existir.

```bash
elevenlabs agents push --agent "<agent-name>" --branch "<branch-name>"
```

#### Actualizar mediante la API

```python
agent = client.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt={"prompt": "You are a friendly customer support agent."},
        )
    )
)
```

```javascript
const agent = await client.conversationalAi.agents.update(
  'agent_7101k5zvyjhmfg983brhmhkd98n6',
  {
    conversationConfig: {
      agent: {
        prompt: {
          prompt: 'You are a friendly customer support agent.',
        },
      },
    },
  },
  { branchId: 'agtbrch_xxxx' }
);
```

Se crea automáticamente una nueva versión en la rama especificada y se descarta cualquier borrador existente de ese usuario en esa rama.

## Desplegar tráfico

Usa la ruta de API de despliegues para distribuir el tráfico entre ramas. Esto permite realizar despliegues graduales y pruebas A/B.

```python
deployment = client.conversational_ai.agents.deployments.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    deployments=[
        {"branch_id": "agtbrch_main", "percentage": 90},
        {"branch_id": "agtbrch_xxxx", "percentage": 10}
    ]
)
```

```javascript
const deployment = await client.conversationalAi.agents.deployments.create('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  deployments: [
    { branchId: 'agtbrch_main', percentage: 90 },
    { branchId: 'agtbrch_xxxx', percentage: 10 },
  ],
});
```

> **Warning**
>
> Todos los porcentajes deben sumar exactamente el 100 %. El despliegue fallará si no lo hacen.

El enrutamiento del tráfico es determinista según el ID de conversación, lo que garantiza que el mismo usuario llegue siempre a la misma rama en distintas sesiones.

## Fusionar ramas

Cuando estés satisfecho con los cambios de una rama, fusiónalos en otra. Cualquier rama no archivada puede fusionarse en cualquier otra rama no archivada, no solo en la principal.

> **Note**
>
> Para que se revisen los cambios de una rama antes de fusionarlos, o para llegar a una rama a la que no tienes
> acceso de escritura, abre una [propuesta de fusión](/docs/es/eleven-agents/operate/merge-proposals) en lugar de
> fusionar directamente.

```python
merge = client.conversational_ai.agents.branches.merge(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    source_branch_id="agtbrch_xxxx",
    target_branch_id="agtbrch_main",
    archive_source_branch=True,  # Default: true
    force=False  # Default: false
)
```

```javascript
const merge = await client.conversationalAi.agents.branches.merge('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', {
  targetBranchId: 'agtbrch_main',
  archiveSourceBranch: true, // Default: true
  force: false, // Default: false
});
```

La fusión:

* Crea una nueva versión en la rama de destino con la configuración de la rama de origen
* Opcionalmente archiva la rama de origen (comportamiento predeterminado)
* Transfiere automáticamente el tráfico de la rama de origen a la rama de destino

> **Note**
>
> La fusión falla con `no_new_changes_to_merge` si la rama de origen se creó a partir de la rama de destino (y no tiene
> confirmaciones nuevas posteriores), y con `branch_already_merged` si ya se había fusionado
> en ese destino.

### Resolver conflictos de fusión

Si un ajuste se ha modificado tanto en la rama de origen como en la de destino desde que se separaron, se conserva de forma predeterminada el valor de la rama que se actualizó más recientemente. Establece `force=True` para usar siempre el valor de la rama de origen, independientemente de las marcas de tiempo.

Previsualiza el resultado de una fusión, incluidos los campos que se sobrescribirían, antes de confirmarla:

```python
preview = client.conversational_ai.agents.branches.preview_merge(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    source_branch_id="agtbrch_xxxx",
    target_branch_id="agtbrch_main",
    force=False
)

print(preview.overridden_fields)
print(preview.conflicts)
```

```javascript
const preview = await client.conversationalAi.agents.branches.previewMerge('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', {
  targetBranchId: 'agtbrch_main',
  force: false,
});

console.log(preview.overriddenFields);
console.log(preview.conflicts);
```

## Hacer rebase de ramas sobre la principal

El rebase incorpora los últimos cambios de la rama principal en otra rama, de forma similar a un rebase de git. Esto mantiene actualizada una rama de larga duración con la principal sin fusionar todavía los cambios propios de la rama.

```python
client.conversational_ai.agents.branches.rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
```

```javascript
await client.conversationalAi.agents.branches.rebase('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx');
```

El rebase:

* Crea una nueva versión en la rama que incorpora los últimos cambios de la principal
* Conserva los cambios propios de la rama: si un ajuste se editó tanto en la rama como en la principal, siempre se conserva el valor de la rama
* Falla con `branch_already_up_to_date` si la rama ya incluye todos los cambios de la principal

> **Note**
>
> Solo las ramas que no son principales pueden hacer rebase, y únicamente sobre la principal. Hacer rebase de la propia rama principal
> devuelve un error `cannot_rebase_main`.

Previsualiza el resultado de un rebase antes de confirmarlo:

```python
preview = client.conversational_ai.agents.branches.preview_rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

print(preview.overridden_fields)
```

```javascript
const preview = await client.conversationalAi.agents.branches.previewRebase('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx');

console.log(preview.overriddenFields);
```

## Archivar ramas

Archiva las ramas que ya no necesites. Esto te ayuda a mantener organizada la lista de ramas.

```python
client.conversational_ai.agents.branches.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    archived=True
)
```

```javascript
await client.conversationalAi.agents.branches.update('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', {
  archived: true,
});
```

> **Warning**
>
> No puedes archivar una rama que tenga tráfico asignado. Elimina todo el tráfico antes de archivarla.

Puedes desarchivar ramas archivadas estableciendo `archived=False`.

## Duplicar un agente con control de versiones

Al duplicar un agente se crea un agente nuevo que contiene una copia de cada rama no archivada del agente de origen, no solo de la rama principal.

```python
duplicate = client.conversational_ai.agents.duplicate(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    name="Copy of my agent"
)

print(duplicate.agent_id)
```

```javascript
const duplicate = await client.conversationalAi.agents.duplicate('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  name: 'Copy of my agent',
});

console.log(duplicate.agentId);
```

En el agente duplicado:

* La rama principal se crea a partir de la versión más reciente de la rama principal del agente de origen
* Cada una de las demás ramas no archivadas se vuelve a crear con el mismo nombre y descripción, a partir de la versión más reciente de esa rama
* Cada rama comienza con una única versión, ya que el historial de versiones no se copia
* Las ramas archivadas y los borradores no se copian
* Los despliegues de tráfico no se copian, por lo que todo el tráfico va a la rama principal hasta que [despliegues tráfico](#deploying-traffic) en otras ramas

Los ID de rama y de versión del duplicado son nuevos, así que actualiza cualquier referencia a los ID del agente de origen.

## Recuperar versiones específicas

Puedes recuperar un agente en una versión específica o en la versión más reciente de una rama.

### Obtener un agente en una versión específica

```python
agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    version_id="agtvrsn_xxxx"
)
```

```javascript
const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  versionId: 'agtvrsn_xxxx',
});
```

### Obtener un agente en la versión más reciente de una rama

```python
agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
```

```javascript
const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  branchId: 'agtbrch_xxxx',
});
```

### Incluir cambios del borrador

```python
agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    include_draft=True
)
```

```javascript
const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  branchId: 'agtbrch_xxxx',
  includeDraft: true,
});
```

## Referencia de ajustes

### Ajustes versionados

Estos ajustes pueden diferir entre versiones y ramas:

| Categoría                             | Ajustes                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configuración de conversación**     | Prompt del sistema, personalidad del agente, selección y parámetros del LLM, ajustes de voz (modelo TTS, ID de voz), configuración de herramientas, base de conocimientos, primer mensaje, ajustes de idioma, detección de turnos, ajustes de interrupción                                                                                          |
| **Ajustes de plataforma versionados** | `evaluation` - criterios de evaluación, `widget` - aspecto y comportamiento del widget, `data_collection` - extracción de datos estructurados, `overrides` - anulaciones de inicio de conversación, `workspace_overrides` - configuración de webhooks, `testing` - configuraciones de prueba, `safety` - medidas de protección (ajustes IVC/no IVC) |
| **Flujo de trabajo**                  | Definición completa del flujo de trabajo (nodos y conexiones)                                                                                                                                                                                                                                                                                       |

### Ajustes por agente

Estos ajustes pertenecen al agente en lugar de a una versión, por lo que todas las ramas los comparten:

| Ajuste                                  | Descripción                                                                                     |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `name`, `tags`                          | Nombre y etiquetas del agente                                                                   |
| `auth`                                  | Ajustes de autenticación y lista de permitidos                                                  |
| `call_limits`                           | Límites de concurrencia y diarios                                                               |
| `queueing_config`                       | Cola de espera y audio de espera para quienes llaman cuando se supera el límite de concurrencia |
| `privacy`                               | Ajustes de retención, modo sin retención y memorias de usuarios                                 |
| `analysis_llm`                          | LLM utilizado para el análisis posterior a la llamada                                           |
| `topic_discovery`, `sentiment_analysis` | Ajustes de análisis a nivel de agente                                                           |
| `simulation_library`                    | Ajustes de la biblioteca de simulaciones                                                        |
| `alerting`                              | Webhooks de alertas y umbrales de monitorización                                                |
| `ban`                                   | Estado de bloqueo (solo administradores)                                                        |

> **Warning**
>
> Los ajustes por agente solo se pueden cambiar en la rama principal. En otras ramas, el panel de control los muestra
> como de solo lectura, y publicar una versión en una rama no principal descarta cualquier cambio en ellos.
> Fusionar después la rama en la principal tampoco los aplica. Cambia a la rama principal para
> modificarlos; una vez publicados allí, el cambio se aplica a todas las ramas.

## Buenas prácticas

#### Crea pruebas antes de crear una rama

Configura [pruebas automatizadas](/docs/es/eleven-agents/customization/agent-testing) que reflejen
el comportamiento esperado antes de crear una rama nueva. Esto establece una referencia y ayuda a detectar
regresiones al principio mientras iteras en tu experimento.

#### Usa nombres de rama descriptivos

Elige nombres de rama que comuniquen claramente el objetivo del experimento. Incluye el nombre de la función,
la hipótesis o el número de incidencia para consultarlos fácilmente (por ejemplo, `feature/new-greeting-flow` o
`experiment/shorter-responses`).

#### Documenta el propósito de las ramas

Usa el campo de descripción de la rama para explicar qué hipótesis estás probando, qué métricas definen
el éxito y cualquier dependencia o consideración. Esto ayuda a los miembros del equipo a entender los
experimentos activos.

#### Usa borradores para el trabajo en curso

Guarda borradores con frecuencia mientras iteras en los cambios. Así conservas tu trabajo sin crear
versiones innecesarias. Confirma cambios solo cuando estés listo para probar o desplegar.

#### Empieza con porcentajes de tráfico pequeños

Al desplegar una rama nueva, empieza con el 5-10 % del tráfico. Esto limita la exposición si surgen problemas
y, al mismo tiempo, proporciona datos relevantes.

#### Supervisa las métricas clave antes de aumentar el tráfico

Usa el [panel de analíticas](/docs/es/eleven-agents/dashboard) para comparar el rendimiento de las ramas.
Revisa las tasas de finalización de llamadas, la duración media de las conversaciones, las puntuaciones de evaluación de éxito y las
tasas de ejecución de herramientas. Aumenta el tráfico solo cuando las métricas igualen o superen la referencia
de tu rama principal.

#### Aumenta el tráfico gradualmente

Aumenta el tráfico por incrementos (10 % → 25 % → 50 % → 100 %) a medida que ganes confianza. Este enfoque
minimiza el riesgo y valida el rendimiento en cada fase.

#### Mantén las ramas activas durante poco tiempo

Fusiona rápidamente los experimentos exitosos para evitar que la configuración se desvíe. Para las ramas que necesiten
permanecer abiertas más tiempo, hazles rebase periódicamente sobre la principal para que no se alejen demasiado y sean
más difíciles de fusionar.

## Próximos pasos

#### [Experimentos](/docs/es/eleven-agents/operate/experiments)

Realiza pruebas A/B mediante ramas y despliegue de tráfico

#### [Pruebas](/docs/es/eleven-agents/customization/agent-testing)

Configura pruebas automatizadas para las versiones de tu agente

#### [Analíticas](/docs/es/eleven-agents/dashboard)

Supervisa el rendimiento en distintas ramas

#### [CLI](/docs/es/eleven-agents/operate/cli)

Gestiona el control de versiones desde la línea de comandos