Claude Opus 5.5: cómo migrar un agente sin romperlo

Una integración de agentes contiene más contrato que el nombre del modelo: forma de la solicitud, bloques de respuesta, selección de herramientas, señales de progreso, límites de salida, caché y rutas de recuperación. Si el equipo reemplaza un ID y la primera demostración responde bien, todavía puede haber fallos silenciosos en tareas largas, interfaces en streaming o acciones que dependían de forzar una herramienta.

Anthropic anunció Claude Opus 5.5 el 22 de septiembre de 2026 y lo declaró disponible ese día. Esta publicación del 23 de septiembre en Lima analiza el contrato documentado, no valida las cifras promocionales. El anuncio afirma menor coste y mayor velocidad que Opus 5, pero la propia página advierte que márgenes de benchmark estrechos explican cada vez menos las diferencias reales. La decisión responsable empieza con tareas propias y resultados verificables.

La guía técnica enumera cuatro cambios incompatibles con ciertos clientes de Opus 5. El pensamiento adaptativo queda siempre activo y ya no acepta los modos disabled ni enabled con presupuesto manual. tool_choice deja de aceptar any o una herramienta nombrada. Una versión anterior de computer use no se admite en Claude API y Google Cloud. Además, el texto entre llamadas puede llegar en bloques thinking vacíos bajo la visualización predeterminada, aunque la solicitud no falle.

La consecuencia es doble. Algunos problemas son duros y visibles, como un error 400; otros degradan la experiencia sin activar alertas, como un panel que parece congelado mientras el agente sigue usando herramientas. Por eso la migración necesita pruebas de contrato además de evaluación semántica. Las primeras comprueban que el sistema habla el protocolo correcto; la segunda comprueba que el trabajo terminado mantiene la calidad que el negocio necesita.

Captura solicitudes representativas antes de migrar, eliminando secretos y datos personales. Registra modelo, plataforma, versión del SDK, thinking, output_config.effort, max_tokens, herramientas y betas. Después ejecuta validaciones estructurales contra Opus 5.5: ninguna configuración obsoleta, contenido seleccionado por type y espacio suficiente para pensamiento más respuesta. No conviertas automáticamente un error de configuración en un reintento con parámetros distintos, porque ocultaría una incompatibilidad.

Incluye conversaciones de varios turnos y bucles de herramientas. La documentación pide devolver los bloques thinking sin modificarlos cuando corresponda; un normalizador que conserva solo texto puede romper continuidad. Comprueba serialización, persistencia, colas y recuperación tras una pausa. El gate se aprueba cuando el mismo artefacto tipado atraviesa todo el recorrido y los errores esperados llegan clasificados a observabilidad, no cuando una llamada aislada devuelve HTTP 200.

Si un flujo usaba tool_choice any o una herramienta nombrada para obligar una acción, el reemplazo no es simplemente auto. Define schemas estrictos, instrucciones que delimiten cuándo llamar y una comprobación de aplicación que decida si el resultado es suficiente. Cuando una operación sea obligatoria por reglas de negocio, el orquestador debe detectar que no ocurrió y detenerse o solicitar revisión; el modelo no debe ser la única capa que impone el proceso.

Ejemplo hipotético: un agente prepara el alta de un proveedor y debe consultar sanciones antes de crear el registro. Prueba tres casos: coincidencia clara, servicio de sanciones no disponible y respuesta ambigua. El resultado correcto no es siempre crear. Puede ser bloquear, pedir evidencia o escalar. Verifica que el agente no sustituya la consulta por una frase plausible y que un reintento no duplique el alta. Esa semántica pertenece a tu sistema.

Una aplicación puede seguir ejecutando correctamente y parecer rota si deja de mostrar actividad entre herramientas. Instrumenta eventos independientes del texto del modelo: llamada iniciada, herramienta completada, espera de aprobación, reintento y finalización. Si decides mostrar bloques de progreso del proveedor, manéjalos por tipo y configuración explícita. No conviertas razonamiento interno en telemetría de negocio ni prometas al usuario un paso que la aplicación no observó realmente.

Prueba la interfaz con conexiones lentas, herramientas que tardan y respuestas que terminan en rechazo. Define un umbral para informar espera y otro para considerar la sesión estancada; ambos deben apoyarse en eventos observables. En móvil, valida que los cambios no empujen controles críticos fuera de pantalla. El gate se aprueba cuando soporte puede distinguir ejecución activa, espera deliberada, fallo recuperable y tarea abandonada sin leer logs privados del proveedor.

Opus 5.5 usa medium por defecto, mientras Opus 5 usaba high. Los nombres de esfuerzo no representan una cantidad idéntica de razonamiento entre modelos. Construye una matriz con low, medium y high para cada familia de trabajo; reserva xhigh o max para casos donde demuestres una mejora. Mantén constantes dataset, herramientas, límites y grader. Repite cada caso para observar variabilidad y separa errores del modelo de fallos del entorno.

Mide coste y latencia por tarea aceptada, no solo por llamada. Incluye reintentos, herramientas, correcciones humanas y sesiones abandonadas. Una respuesta barata que obliga a rehacer el trabajo puede costar más que una ejecución cara que termina bien; una mejora promedio tampoco compensa una regresión en una operación crítica. La guía oficial recomienda barrer esfuerzo con evaluaciones propias y advierte que cambiarlo en el nivel superior puede invalidar la caché de prompt.

Empieza con tráfico de sombra o casos reproducibles sin efectos laterales. Luego habilita una cohorte pequeña por tipo de tarea, no una fracción aleatoria que mezcle riesgos distintos. Versiona modelo, prompt, herramientas, esfuerzo y grader en cada resultado. Define antes del despliegue qué regresión detiene la expansión: error de contrato, acción incorrecta, caída de calidad, latencia límite, coste por caso o pérdida de señal de progreso.

Conserva durante la ventana de observación una ruta probada al modelo anterior o a una operación manual. El rollback debe restaurar configuración compatible, no solo cambiar el ID; un cliente modificado para thinking o herramientas puede no funcionar simétricamente hacia atrás. Ensaya la reversión con una tarea en curso y una nueva. Registra quién autoriza el cambio y cómo se protegen sesiones que ya contienen estado ligado al modelo.

Los límites importan. No ejecutamos Opus 5.5 ni reproducimos los benchmarks publicados; tampoco afirmamos que un esfuerzo funcione mejor para tu carga. Las cifras de precio, velocidad y desempeño pertenecen al proveedor y pueden depender de su harness. Esta guía transforma cambios documentados en criterios de ingeniería. Tu piloto debe incluir datos permitidos, revisión de seguridad y las restricciones particulares de la plataforma donde despliegas.

Aprueba la migración cuando los cinco gates dejan evidencia: solicitudes compatibles, herramientas gobernadas por la aplicación, progreso observable, esfuerzo calibrado y rollback ensayado. Si necesitas diseñar ese piloto para un proceso real, el servicio a medida de Wasyra puede convertir el flujo, sus permisos y sus casos dorados en una implementación evaluable. Ese servicio es distinto del producto Agents alojado en agents.wasyra.com.