Agent versioning para agentes de IA: cómo desplegar prompt, tools y policy de forma segura

Idea en 30 segundos

Agent versioning es un control de runtime que fija exactamente qué versión del agente usa cada run: prompt, tools, policy y modelo.

Cuándo se necesita: cuando un agente se actualiza con frecuencia y producción necesita despliegues seguros sin perder reproducibilidad.

Problema

Sin versionado, los cambios de prompt, tools y policy se mezclan en un único "estado actual". En demo casi no se nota. En producción, deja de estar claro por qué un run funcionó y otro no.

Consecuencias típicas:

• no se puede reproducir un incidente con precisión
• cuesta identificar qué cambio rompió el comportamiento
• rollback se vuelve una operación manual y riesgosa

Y cada minuto sin una versión clara aumenta el tiempo de investigación del incidente.

Analogía: es como desplegar sin número de versión. Mientras todo funciona, el problema es invisible. Cuando algo falla, no está claro a qué volver.

Solución

La solución es guardar el agente como paquete versionado (version manifest) y arrancar runs solo con version_id pin. Cada release pasa verificaciones de compatibilidad de contratos y rollout gate antes de recibir tráfico.

Version policy layer devuelve una decisión técnica: allow o stop con razón explícita:

• contract_mismatch
• gate_failed
• rollback_required

Es una capa separada del sistema, no parte del prompt ni de la lógica del modelo.

Agent versioning ≠ rollback

Son roles distintos en el sistema:

• Versioning controla cambios antes y durante el rollout.
• Rollback devuelve una versión estable cuando la nueva ya causó regresión.

Uno sin el otro no alcanza:

• sin versioning, rollback puntual es difícil
• sin rollback, incluso un buen versioning no te salva de incidentes en producción

Ejemplo:

• versioning: support-agent@2.4.0 va a canary del 5%
• rollback: volver a support-agent@2.3.3 si sube el error rate

Componentes del control de versioning

Estos componentes trabajan juntos en cada arranque de run.

Ejemplo de alerta:

Slack: 🛑 Agent support@2.4.0 blocked: gate_failed on canary stage (error_rate > threshold).

Cómo se ve en la arquitectura

Version policy layer se ubica entre runtime y el inicio de una nueva versión del agente, y bloquea el inicio antes de arrancar el run. Cada decisión (allow o stop) se registra en audit log.

Cada arranque de run pasa por este flow antes de ejecutarse: runtime no inicia una nueva versión directamente, primero pide una decisión al policy layer.

Resumen del flow:

• Runtime prepara el arranque del run
• Policy verifica version_manifest, tool_contracts, rollout_stage, policy_version
• allow -> arranca agent_version con pin
• stop -> release bloqueado, se mantiene la versión estable activa
• ambas decisiones se escriben en audit log

Ejemplo

El equipo libera support-agent@2.4.0 con un nuevo adaptador de tool refund.create. El contract check detecta incompatibilidad de schema.

Resultado:

• policy devuelve stop (reason=contract_mismatch)
• canary no arranca
• support-agent@2.3.3 sigue en ejecución

Versioning detiene el release riesgoso antes del incidente, no después.

En código se ve así

El esquema simplificado de arriba muestra el flujo principal. Punto crítico: runtime debe iniciar runs solo con version_id pin, no tomar "latest" durante la ejecución.

Ejemplo de configuración de versioning:

agent_release:
  stable_version: support-agent@2.3.3
  candidate_version: support-agent@2.4.0
  canary_percent: 5
  rollback_on:
    error_rate_p95: 0.05
    tool_failure_p95: 0.03

release_cfg = load_release_config("support-agent")
candidate = registry.get(release_cfg.candidate_version)
decision = versioning.check(candidate, runtime_context)

if decision.outcome == "stop":
    audit.log(
        run_id,
        decision=decision.outcome,
        reason=decision.reason,
        version_id=candidate.version_id,
        rollout_stage=decision.rollout_stage,
    )
    alerts.notify_if_needed(candidate.version_id, decision.reason)
    return stop(decision.reason)

selected = versioning.select(candidate, stable=release_cfg.stable_version)
run = runtime.start(
    version_id=selected.version_id,
    prompt_hash=selected.prompt_hash,
    policy_version=selected.policy_version,
)
# Decision.allow — helper condicional para mantener un modelo único outcome/reason.
allow_decision = Decision.allow(reason=None)

audit.log(
    run.id,
    decision=allow_decision.outcome,
    reason=allow_decision.reason,
    version_id=selected.version_id,
    rollout_stage=selected.rollout_stage,
)

return run

Cómo se ve durante la ejecución

Escenario 1: bloqueo por contract mismatch

1. Runtime prepara el arranque de support-agent@2.4.0.
2. Policy verifica tool contracts.
3. Decisión: stop (reason=contract_mismatch).
4. La nueva versión no se inicia.
5. El evento se registra en audit log.

Escenario 2: canary rollout

1. Policy permite el candidate con canary_percent=5.
2. Parte de los runs va a 2.4.0, el resto a estable.
3. Métricas se siguen por version_id.
4. Si no se superan umbrales, la stage sube.
5. La versión pasa a un rollout más amplio.

Escenario 3: rollback required

1. Tras el rollout sube tool_failure_rate.
2. Policy devuelve stop (reason=rollback_required).
3. El tráfico vuelve a la versión estable.
4. Los runs con versión nueva dejan de arrancar.
5. El equipo analiza el incidente por version_id y audit trail.

Errores típicos

• iniciar runs desde "latest" en lugar de version_id con pin
• versionar solo prompt e ignorar contratos de tools/policy
• hacer full rollout sin canary gate
• no registrar version_id y rollout_stage en audit
• mezclar rollback y release nuevo en un solo paso sin stable fallback
• no tener umbrales explícitos que activen rollback

Resultado: los despliegues parecen controlados, pero bajo carga se vuelven impredecibles.

Autoevaluación

Chequeo rápido de agent versioning antes de lanzar a producción:

FAQ

P: ¿Por qué no actualizar simplemente la versión "actual" del agente?
R: Porque sin version_id con pin pierdes reproducibilidad de runs y no puedes localizar regresiones con precisión.

P: ¿Qué se debe versionar exactamente: solo prompt?
R: No. Mínimo: prompt, contratos de tools, policy/config y compatibilidad de runtime. Si no, la versión queda incompleta.

P: ¿Canary es obligatorio para cada cambio?
R: Para cambios high-risk, sí. Para low-risk se pueden acortar etapas, pero siempre con métricas explícitas y umbrales de stop.

P: ¿Cuándo iniciar rollback?
R: Cuando se rompen los umbrales acordados (error/tool failure/latency/cost). Debe ser una decisión de policy, no improvisación manual.

P: ¿Versioning reemplaza rollback?
R: No. Versioning evita caos en despliegues, rollback sigue siendo el mecanismo de emergencia para volver a stable.

Dónde encaja Agent Versioning en el sistema

Agent versioning es una de las capas de Agent Governance. Junto con RBAC, límites, presupuestos, approval y audit, forma un sistema unificado de cambios controlados en producción.

Páginas relacionadas

Siguiente sobre este tema:

• Resumen de Agent Governance — modelo general de control de agentes en producción.
• Estrategias de rollback — cómo volver con seguridad a una versión estable.
• Access Control (RBAC) — cómo limitar quién puede ejecutar qué.
• Budget Controls — cómo mantener el gasto bajo control durante rollout.
• Audit logs para agentes — cómo reconstruir cadenas de decisiones por version_id.