Control de versiones del agente

El control de versiones del agente te permite experimentar con distintas configuraciones sin poner en riesgo tu configuración de producción. Crea ramas aisladas, prueba los cambios y despliega actualizaciones de forma gradual mediante la distribución porcentual del tráfico.

Resumen

El sistema de control de versiones ofrece:

• Instantáneas inmutables de la configuración de tu agente en cualquier momento
• Ramas aisladas para probar cambios antes de pasar a producción
• División del tráfico para desplegar cambios gradualmente a un porcentaje de usuarios
• Fusión para incorporar cambios de cualquier rama a cualquier otra rama
• Rebase para incorporar en una rama los últimos cambios de la rama principal

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 y 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 workflow con nodos y conexiones

Las versiones se crean automáticamente cuando guardas 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 con la rama principal.

• Cada agente con control de versiones tiene una rama Principal 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 la principal pueden hacer rebase sobre la principal para incorporar sus últimos cambios
• Cada rama tiene: ID (agtbrch_xxxx), nombre, descripción y una lista de versiones
• Los nombres de las ramas pueden contener: letras, números y () [] {} - / . (máximo 140 caracteres)

Despliegue de tráfico

El tráfico puede dividirse porcentualmente entre varias ramas, 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 las 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 versión nueva
• 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.

Activar al crear un agente

Activar en un agente existente

Al activar el control de versiones, se crea la rama inicial «Principal» 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. Opcionalmente, puedes incluir cambios de configuración que se aplicarán a la versión inicial de la nueva rama.

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}")

Enumerar ramas

branches = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

Obtener detalles de una rama

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)}")

Confirmar cambios

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

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

Distribuir tráfico

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

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

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 todas las sesiones.

Fusionar ramas

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

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
)

Al fusionar:

• Se crea una versión nueva en la rama de destino con la configuración de la rama de origen.
• Opcionalmente, se archiva la rama de origen (comportamiento predeterminado).
• El tráfico se transfiere automáticamente de la rama de origen a la rama de destino.

Resolver conflictos de fusión

Si un ajuste ha cambiado tanto en la rama de origen como en la de destino desde que se separaron, de forma predeterminada se conserva el valor de la rama actualizada 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:

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)

Rebasar ramas sobre main

El rebase incorpora los cambios más recientes de la rama principal a otra rama, de forma similar a un rebase de git. Esto mantiene actualizada con main una rama de larga duración sin fusionar todavía los cambios propios de esa rama.

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

Al rebasar:

• Se crea una versión nueva en la rama que incorpora los últimos cambios de main.
• Se conservan los cambios propios de la rama: si un ajuste se editó tanto en la rama como en main, siempre se conserva el valor de la rama.
• Se produce un error branch_already_up_to_date si la rama ya incluye todos los cambios de main.

Previsualiza el resultado de un rebase antes de confirmarlo:

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

Archivar ramas

Archiva las ramas que ya no necesites. Así mantendrás organizada la lista de ramas.

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

Puedes desarchivar ramas archivadas estableciendo archived=False.

Recuperar versiones específicas

Puedes recuperar un agente en una versión específica o en la punta de una rama.

Obtener un agente en una versión específica

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

Obtener un agente en la punta de una rama

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

Incluir cambios de borrador

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

Referencia de ajustes

Ajustes versionados

Estos ajustes pueden variar entre versiones y ramas:

Ajustes por agente

Estos ajustes se comparten entre todas las versiones:

Buenas prácticas

Siguientes pasos