Migración a Claude Opus 5.5

Para conocer las diferencias de comportamiento y los patrones de prompting específicos del modelo, consulta Cómo escribir prompts para Claude Opus 5.5.

Claude Opus 5.5 cuesta menos que Claude Opus 5 ($4 / $20 USD por millón de tokens de entrada / salida, en comparación con $5 / $25; consulta precios de Claude). Además, mantiene la "context window" (ventana de contexto) de 1M de tokens de Claude Opus 5 y su máximo de 128k tokens de salida. Hay cuatro "breaking changes" (cambios incompatibles) para el código que ya se ejecuta en Claude Opus 5, que se describen en Cambios incompatibles. Para conocer la compatibilidad de funciones, consulta Novedades de Claude Opus 5.5.

Migración a Claude Opus 5.5 desde Claude Opus 5

Actualiza el nombre de tu modelo

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 es un ID de modelo fijo sin sufijo de fecha, con el mismo esquema que claude-opus-5. En Amazon Bedrock, Claude Platform on AWS, Google Cloud y Microsoft Foundry, usa el ID de modelo de esa plataforma; consulta Disponibilidad.

Cambios incompatibles

Cada cambio se explica en Novedades de Claude Opus 5.5. Esta sección muestra el cambio de código necesario para cada uno.

El pensamiento no se puede desactivar

Tanto thinking: {"type": "disabled"} como thinking: {"type": "enabled", "budget_tokens": N} devuelven un error 400 ("thinking.type.disabled" is not supported for this model. o "thinking.type.enabled" is not supported for this model.). Elimina el campo thinking y elige un nivel de "effort" (esfuerzo). Si desactivabas el "thinking" (pensamiento) para ahorrar tokens, usa un nivel más bajo. Las respuestas comenzarán entonces con bloques thinking, así que selecciona los bloques de contenido por type y devuelve los bloques thinking sin modificar junto con los resultados de las herramientas. Consulta El pensamiento no se puede desactivar.

Antes (aceptado en Claude Opus 5, rechazado en Claude Opus 5.5):

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

Después:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

El uso forzado de herramientas no es compatible

Los tipos any y tool de tool_choice devuelven un error 400 (tool_choice: type "tool" and "any" are not supported for this model.), incluso en el endpoint de conteo de tokens. Usa auto con "strict tool use" (uso estricto de herramientas) o "structured outputs" (salidas estructuradas), e indica en el prompt cuándo corresponde usar la herramienta. Consulta El uso forzado de herramientas no es compatible.

Antes:

client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

Después:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # uso estricto de herramientas: cada llamada coincide con el input_schema de la herramienta
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

Los bloques de pensamiento están vinculados al modelo y a la conversación

En la API de Claude, Claude Fable 5.1 y Claude Mythos 5.1 leen los bloques de pensamiento de Claude Opus 5.5; ningún otro modelo lo hace. Si un enrutador o un fallback traslada una conversación de Claude Opus 5.5 a cualquier otro modelo, esos turnos se ejecutan sin dichos bloques. En la dirección opuesta, Claude Opus 5.5 lee los bloques de pensamiento de Claude Opus 5 y de los modelos Opus, Sonnet y Haiku anteriores, pero no los de los modelos Claude Fable ni Claude Mythos.

Mantén la conversación en modo "append-only" (solo anexar), es decir, sin editar la indicación system, las tools ni los mensajes anteriores a mitad de la conversación, para que los bloques sigan siendo válidos. Claude Code, claude.ai, Claude Managed Agents y el Claude Agent SDK ya funcionan así. La aplicación de esta regla coincide con la de Claude Fable 5.1 en todas las plataformas: para las cuentas creadas a partir del 31 de agosto de 2026, 00:00 UTC, reenviar un bloque de pensamiento después de una edición de ese tipo devuelve un error 400 de forma predeterminada. Las integraciones que solo anexan no requieren cambios de código. Consulta Los bloques de pensamiento están vinculados al modelo y a la conversación y Pensamiento preservado.

La herramienta de uso de computadora computer_20251124 no es compatible en la API de Claude ni en Google Cloud

En la API de Claude y en Google Cloud, una entrada de tools de tipo computer_20251124 devuelve un error 400 ('claude-opus-5-5' does not support tool types: computer_20251124., seguido de los tipos de herramientas que acepta el modelo). En su lugar, declara el "toolset" (conjunto de herramientas) computer_toolset_20260801: elimina el encabezado beta y envía la entrada sin name ni dimensiones de pantalla.

En el bucle de tu agente, maneja los bloques tool_use de los miembros del conjunto (la acción es el name del bloque, no input.action), que pueden ser varios por turno, y repite toolset_name en cada resultado. El cambio en la solicitud se muestra a continuación; los cambios en el bucle del agente se enumeran en Migrar desde computer_20251124.

En Amazon Bedrock, la herramienta anterior computer_20251124 sigue funcionando en Claude Opus 5.5 igual que en Claude Opus 5, así que no necesitas hacer cambios allí. Para otras plataformas, consulta la sección Compatibilidad de la herramienta de uso de computadora. Consulta también La herramienta de uso de computadora computer_20251124 no es compatible en la API de Claude ni en Google Cloud.

Antes:

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        }
    ],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

Después:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # sin encabezado beta; la entrada del conjunto de herramientas no lleva nombre ni tamaño de pantalla
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

El texto entre llamadas a herramientas se devuelve en bloques de pensamiento

En Claude Opus 5, el texto que el modelo escribe entre llamadas a herramientas se devuelve como bloques text. En Claude Opus 5.5, al igual que en Claude Fable 5.1, esa narración se devuelve como bloques thinking de actualización de progreso, con un máximo de uno antes de cada llamada a herramienta. Con el valor predeterminado de thinking.display, que es "omitted", su campo thinking está vacío. Ninguna solicitud falla, pero una aplicación que hace streaming de ese texto a sus usuarios como actualizaciones de progreso se queda en silencio entre llamadas a herramientas.

Para restaurar las actualizaciones, léelas de los bloques thinking y establece un valor de display que devuelva su texto:

• "updates" (beta, encabezado thinking-display-updates-2026-08-18) devuelve las actualizaciones de progreso y mantiene oculto el razonamiento.
• "summarized" devuelve ambos, mezclados.

Luego, muestra cada bloque thinking no vacío antes del bloque tool_use al que precede, y devuelve los bloques sin cambios junto con el resto del turno del asistente. Consulta Actualizaciones de progreso para el usuario.

Clasificadores de seguridad y fallback

Claude Opus 5.5 puede devolver stop_reason: "refusal" con una categoría en stop_details. Sus clasificadores cubren un conjunto de categorías más amplio que los de Claude Opus 5, así que espera valores de stop_details.category como "bio" y "reasoning_extraction", además de "cyber"; consulta la tabla de categorías de rechazo.

Maneja los rechazos y configura el "fallback" (respaldo) del lado del servidor o tu propio mecanismo de reintento. El fallback del lado del servidor no reintenta las solicitudes rechazadas con "reasoning_extraction"; ese rechazo se te devuelve directamente. Consulta Rechazos y fallback y Rechazos de salvaguardas.

Cambios recomendados

1. Vuelve a ejecutar tu barrido de esfuerzo. El esfuerzo es el único control de pensamiento en Claude Opus 5.5. Su valor predeterminado es medium, mientras que en Claude Opus 5 es high, así que una solicitud que omite effort ahora se ejecuta en medium. Baja el nivel donde la calidad se mantenga y súbelo para el trabajo más exigente. Consulta Esfuerzo.
2. Vuelve a evaluar las instrucciones de prompt específicas del modelo. Es posible que las instrucciones ajustadas al comportamiento de Claude Opus 5 ya no sean necesarias; consulta Cómo escribir prompts para Claude Opus 5.5. Si ejecutabas con el pensamiento desactivado, consulta también Prompts escritos para el pensamiento desactivado.
3. Prueba en un entorno de desarrollo antes de cambiar el tráfico de producción.

Lista de verificación de migración

• Actualiza el ID del modelo a claude-opus-5-5.
• Elimina thinking: {"type": "disabled"} y thinking: {"type": "enabled", ...}, y elige un nivel de esfuerzo en su lugar.
• Establece effort de forma explícita: el valor predeterminado es medium, mientras que en Claude Opus 5 es high.
• Reemplaza los tipos any y tool de tool_choice por auto junto con uso estricto de herramientas o salidas estructuradas.
• Si usas la herramienta de uso de computadora en la API de Claude o en Google Cloud:
  • Declara computer_toolset_20260801 (sin encabezado beta) en lugar de computer_20251124.
  • Actualiza el bucle de tu agente para el conjunto de herramientas.
  • En Amazon Bedrock, mantén computer_20251124. Para otras plataformas, revisa la sección Compatibilidad de la herramienta de uso de computadora.
• Si un enrutador o un fallback puede trasladar una conversación de Claude Opus 5.5 a otro modelo, ten en cuenta que ese modelo se ejecutará sin los bloques de pensamiento de Claude Opus 5.5. La excepción son Claude Fable 5.1 y Claude Mythos 5.1 en la API de Claude, que sí los conservan. Por su parte, Claude Opus 5.5 lee el pensamiento de Claude Opus 5 y de los modelos Opus, Sonnet y Haiku anteriores, pero no el de los modelos Claude Fable ni Claude Mythos.
• Lee los bloques de contenido por type y devuelve los bloques thinking sin modificar en los bucles de uso de herramientas.
• Si tu interfaz muestra el texto entre llamadas a herramientas, establece display: "updates" (beta) o "summarized" y muestra los bloques thinking no vacíos.
• Si tu código edita turnos anteriores, la indicación system o las tools a mitad de la conversación, sigue las indicaciones de Pensamiento preservado.
• Maneja stop_reason: "refusal" y configura el fallback.
• Vuelve a establecer la línea base de costo y latencia con el nivel de esfuerzo que elijas.

Migración a Claude Opus 5.5 desde Claude Opus 4.8

Primero, sigue los pasos de Migración a Claude Opus 5 desde Claude Opus 4.8, que cubre el pensamiento activado de forma predeterminada y los cambios en la forma de las respuestas que lo acompañan. Luego, aplica Migración desde Claude Opus 5.

El segundo cambio incompatible de Claude Opus 5 descrito allí (el pensamiento solo se puede desactivar con esfuerzo high o inferior) no aplica: en Claude Opus 5.5, el pensamiento no se puede desactivar en absoluto.

Lista de verificación de migración

• Todo lo incluido en la lista de verificación de Claude Opus 4.8 → Claude Opus 5, excepto que thinking: {"type": "disabled"} no es una opción.
• Todo lo incluido en la lista de verificación de Claude Opus 5 → Claude Opus 5.5.

Migración a Claude Opus 5.5 desde Claude Opus 4.7 y modelos Opus anteriores

La guía de migración de Claude Opus 5 cubre los cambios incompatibles entre tu modelo actual y Claude Opus 5: el rechazo de los parámetros de muestreo, el rechazo del pensamiento extendido manual, la eliminación del prefill y el tokenizador más reciente. Sigue la sección correspondiente a tu modelo en esa guía, usando claude-opus-5-5 en lugar de claude-opus-5, y luego aplica Migración desde Claude Opus 5.

Ten en cuenta dos diferencias con respecto a esa guía:

• Donde indica que el pensamiento se puede desactivar con esfuerzo high o inferior, en Claude Opus 5.5 no es posible.
• Donde indica que las integraciones existentes de computer_20251124 siguen funcionando, en la API de Claude y en Google Cloud dejan de funcionar con Claude Opus 5.5, que en esas plataformas solo acepta el uso de computadora mediante el conjunto de herramientas computer_toolset_20260801 (consulta el cambio incompatible). En Amazon Bedrock siguen funcionando.

Migración a Claude Opus 5.5 desde Claude Sonnet 5

Consulta Migración a Claude Opus 5 desde Claude Sonnet 5 para saber qué cambia al pasar a una clase de modelo superior y, luego, aplica Migración desde Claude Opus 5.