Migrar a Opus 5.5 y Sonnet 5.5 sin romper nada

Cambiar claude-opus-5 por claude-opus-5-5 parece una línea de código, pero puede tumbar tu integración con un error 400 si la petición arrastra parámetros que los modelos nuevos ya no aceptan. Esta guía resume, a partir de las guías oficiales de migración de Opus 5.5 y Sonnet 5.5, qué rompe, cómo sustituirlo y qué revisar aunque no dé error. En 10 minutos tendrás tu checklist.

Antes de empezar

• Código que ya llama a la Messages API con el SDK oficial (los ejemplos son en Python).
• Saber qué modelo usas hoy: la lista de cambios depende de desde dónde vienes.
• Un pequeño juego de pruebas (10 o 20 peticiones reales con su resultado esperado) para comparar antes y después.
• Si usas Claude Managed Agents, basta con cambiar el nombre del modelo: lo que sigue es para código de la Messages API.

1. Deja que Claude Code haga el trabajo pesado

Las dos guías oficiales recomiendan empezar por la skill de la API de Claude que viene con Claude Code. Cambia el ID, corrige los parámetros que rompen, sustituye los prefill, ajusta el effort y te deja una lista de lo que debes verificar a mano. Antes de tocar nada te pregunta el alcance (todo el directorio, una carpeta o unos archivos).

$ claude
$ /claude-api migrate this project to claude-opus-5-5
# Para Sonnet: /claude-api migrate this project to claude-sonnet-5-5
Claude confirma el alcance, aplica los cambios y genera la checklist de verificación manual

Aunque uses la skill, conviene entender qué cambia. Estos son los puntos.

2. Lo que devuelve un 400

Los IDs son fijos y sin fecha: claude-opus-5-5 y claude-sonnet-5-5. Y ambos modelos rechazan lo siguiente:

• temperature, top_p y top_k con valores distintos de los por defecto. Quítalos y guía el comportamiento con el prompt.
• Prefill: terminar messages con un turno de assistant a medio escribir (el truco de empezar la respuesta con {). Usa structured outputs o instrucciones en el prompt de sistema.
• Uso forzado de herramientas: tool_choice de tipo any o tool. Solo valen auto (por defecto) y none.
• Apagar el pensamiento: thinking: {"type": "disabled"} y los presupuestos manuales {"type": "enabled", "budget_tokens": N}.
• Computer use antiguo: en la API de Claude y Google Cloud hay que declarar computer_toolset_20260801 en lugar de computer_20251124.

Un caso típico: extraer un pedido de un correo forzando la herramienta y con temperatura cero.

# Antes: tres errores 400 en Opus 5.5 o Sonnet 5.5
client.messages.create(
    model="claude-opus-5",
    temperature=0,
    tool_choice={"type": "tool", "name": "registrar_pedido"},
    tools=[registrar_pedido],
    messages=[{"role": "user", "content": correo}],
    max_tokens=1024,
)

# Después
registrar_pedido["strict"] = True  # la entrada cumplirá el esquema
client.messages.create(
    model="claude-opus-5-5",
    output_config={"effort": "medium"},
    system="Cuando el correo contenga un pedido, llama siempre a registrar_pedido.",
    tools=[registrar_pedido],
    messages=[{"role": "user", "content": correo}],
    max_tokens=4096,
)

Como auto permite que Claude conteste sin llamar a la herramienta, el prompt tiene que decir cuándo usarla. Las herramientas strict exigen additionalProperties: false en cada objeto del esquema.

3. Lo que no da error pero rompe igual

El pensamiento adaptativo está activo por defecto en los dos modelos. Eso cambia la forma de la respuesta y el coste:

Revisa en tu código:

• Lectura por posición. La respuesta puede empezar con bloques thinking. content[0].text falla: filtra por block.type == "text".
• max_tokens. Cubre pensamiento más texto. Si antes trabajabas sin pensamiento, súbelo; con effort xhigh o max, empieza en 64.000.
• Bucles de herramientas. Devuelve los bloques thinking tal cual, incluso vacíos. Editarlos, reordenarlos o quitarlos da 400.
• Texto del pensamiento. Llega vacío por defecto (display: "omitted"). Si tu interfaz lo mostraba, pide display: "summarized".
• Effort. Fíjalo de forma explícita y haz un barrido con tus pruebas, no copies el valor del modelo anterior.

4. Según de dónde vengas

Las guías oficiales ordenan la checklist por modelo de origen: aplicas todo lo anterior y bajas hasta tu grupo. Lo más habitual:

• Desde Opus 4.6, Sonnet 4.6 o anteriores: quitar temperature, top_p y top_k; cambiar presupuestos de pensamiento por effort; recalcular tokens (la tokenización cambió) y el presupuesto de imágenes.
• Desde Opus 4.5, Sonnet 4.5 o anteriores: además, eliminar los prefill, pasar de client.beta.messages.create a client.messages.create si solo usabas la beta por effort o pensamiento, retirar cabeceras beta antiguas como interleaved-thinking-2025-05-14 y mover output_format a output_config.format.
• Desde Haiku 4.5 a Sonnet 5.5: cambiar el ID y recalcular el coste, porque el precio por token es mayor.

Si lo tuyo es un proyecto con SAP, la estrategia es la misma: prueba primero en desarrollo con peticiones reales anonimizadas y promueve después, igual que harías con un transporte.

Si algo falla

• 400 que menciona tool_choice: sigues forzando una herramienta. Pasa a auto con strict: true y dilo en el prompt.
• 400 con thinking.type.disabled: en Opus 5.5 quita el campo thinking; en Sonnet 5.5 usa between_tools si no quieres pensamiento previo.
• Respuestas cortadas (stop_reason: "max_tokens"): el pensamiento se comió el presupuesto. Sube max_tokens o baja el effort.
• 400 en un bucle de herramientas: estás reconstruyendo el mensaje del asistente. Reenvíalo tal y como llegó.

La lista completa está en las guías oficiales de Opus 5.5 y Sonnet 5.5.