Cinco líneas de código que rompen al migrar a Claude Sonnet 5.5 u Opus 5.5, y cómo arreglarlas antes de que fallen en producción

El código pasa la revisión de tipos y falla igualmente

Migrar a un modelo nuevo dentro de la misma familia suele tratarse como cambiar una cadena de texto: el identificador del modelo, y listo. Con Claude Sonnet 5.5 y Claude Opus 5.5, la documentación oficial de Anthropic advierte de que no es tan sencillo. El SDK sigue aceptando los mismos campos que antes por compatibilidad, así que el código que los usa pasa la comprobación de tipos sin ninguna advertencia; el problema aparece después, cuando la API rechaza la solicitud en el servidor con un error 400. Son fallos silenciosos en el momento de escribir el código y muy ruidosos en producción, y Anthropic los documenta con precisión en sus guías de migración.

El primero: el pensamiento ya no se puede apagar

En Claude Opus 5, una solicitud podía desactivar el razonamiento con thinking: {"type": "disabled"}, siempre que el nivel de esfuerzo fuera high o inferior. En Opus 5.5 y en Sonnet 5.5, ese mismo campo devuelve un error 400 cuyo mensaje remite directamente a la solución: usar thinking.type.adaptive junto con output_config.effort para controlar cuánto piensa el modelo, en lugar de intentar apagarlo del todo. En Sonnet 5.5 hay además una opción intermedia pensada para el caso de uso más habitual detrás de la desactivación del pensamiento —evitar el coste de razonar antes de una respuesta puramente conversacional—: thinking: {"type": "between_tools"}, compatible con esfuerzo high o inferior, que deja la respuesta como texto puro cuando no hay herramientas de por medio y solo activa el razonamiento entre llamadas a herramientas cuando la tarea las necesita.

El segundo: ya no se puede obligar a Claude a usar una herramienta concreta

El patrón tool_choice: {"type": "any"} o {"type": "tool", "name": "..."}, muy habitual para garantizar que una respuesta llegue siempre a través de una herramienta específica, deja de funcionar en Opus 5.5, Sonnet 5.5, Fable 5.1 y Mythos 5.1: cualquiera de los dos devuelve el mismo error 400, incluso en el endpoint de conteo de tokens. La razón técnica que da Anthropic es coherente con el primer cambio: en un modelo con el pensamiento siempre activo, forzar una herramienta concreta obliga a Claude a saltarse ese razonamiento y comprimir su proceso de decisión dentro de los propios argumentos de la llamada, lo que degrada la calidad de esos argumentos. La sustitución recomendada tiene dos partes: mantener tool_choice en {"type": "auto"}, que es el valor por defecto, y añadir strict: true a la definición de la herramienta para garantizar que los argumentos cumplen el esquema exacto cuando Claude decide usarla; si lo que se buscaba con la herramienta forzada era en realidad una salida JSON con una forma concreta, la alternativa más directa es Structured Outputs, que impone el esquema sin necesitar ninguna herramienta de por medio. En ambos casos, conviene indicar en el propio prompt cuándo corresponde usar esa herramienta, en lugar de dejar que la elección dependa solo del esquema.

El tercero: los bloques de pensamiento quedan firmados y atados a su conversación

Cada bloque de pensamiento que genera Sonnet 5.5 queda firmado sobre el estado de la conversación en el momento en que se creó. En la práctica, esto significa que si se edita el historial anterior a un bloque de pensamiento —se reescribe un mensaje, se recorta el contexto, se reordenan turnos— y después se reenvía ese bloque tal cual en una llamada posterior, la API devuelve un error 400 en lugar de aceptarlo silenciosamente. La recomendación de Anthropic es tratar los bloques de pensamiento como un dato de solo lectura ligado a su punto exacto en la conversación: se reenvían completos y sin modificar en los bucles de uso de herramientas, incluidos los bloques cuyo campo de pensamiento está vacío, y cualquier cambio de contexto que sea necesario se aplica con las herramientas pensadas para ello —mensajes de sistema intermedios, cambios de herramientas entre turnos— en lugar de editar directamente los turnos que ya contienen pensamiento firmado.

El cuarto y el quinto: la herramienta de uso del ordenador cambia de versión, y el asesor tiene sus propias reglas

En la API de Claude y en Google Cloud, declarar la herramienta de uso del ordenador con el identificador anterior, computer_20251124, devuelve ahora un error 400 que indica qué tipos de herramienta acepta el modelo en su lugar: computer_toolset_20260801. Amazon Bedrock, en cambio, sigue aceptando el identificador anterior, así que este cambio concreto depende de la plataforma sobre la que corra la integración, no es universal. El quinto ajuste es más de nicho pero igual de silencioso si no se conoce: la herramienta de asesor (advisor) rechaza a Claude Opus 4.8, Claude Opus 4.7 y Claude Sonnet 5 como modelos ejecutores cuando se combinan con un modelo Sonnet 5.5 en el resto de la solicitud, devolviendo también un error 400; quien use esa herramienta en un flujo mixto de modelos de distintas generaciones necesita revisar esa combinación concreta antes de desplegarla.

Cómo abordar la migración sin sorpresas

La forma más eficiente de encontrar estos cinco puntos antes de que fallen en producción es buscar en el código y en las trazas de solicitudes reales cada uno de los campos implicados —thinking con disabled o budget_tokens, tool_choice con any o tool, temperature, top_p o top_k con valores distintos del predeterminado, mensajes de asistente precompletados, y declaraciones de computer_20251124— y probar cada ruta encontrada contra el modelo nuevo en un entorno de pruebas antes de mover tráfico real. Anthropic mantiene guías de migración específicas para cada modelo de origen, así que conviene partir de la que corresponde al modelo que se está dejando atrás, no de una guía genérica.

Por qué importa hoy

Ninguno de estos cinco cambios aparece como advertencia en tiempo de compilación, lo que los convierte en la clase de error que se descubre en un cliente real, no en una prueba local rápida. Para cualquier equipo que esté planificando el salto a Sonnet 5.5 u Opus 5.5 esta semana, el ejercicio previo más rentable es una búsqueda de texto en el propio repositorio por estos cinco patrones concretos, antes de cambiar un solo identificador de modelo en producción.