Guía de migración a Claude Opus 5.5

Esta página enumera los cambios de código necesarios para pasar a Claude Opus 5.5 desde Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y modelos Opus anteriores o Claude Sonnet 5. Todos los lectores necesitan Lo que debe cumplir cada solicitud a Claude Opus 5.5 y Gestiona el pensamiento en cada respuesta. Después, ve a la sección de tu modelo actual: su primera oración indica las demás secciones que te corresponden. La lista de verificación de migración enumera cada cambio según el modelo de partida.

Claude Opus 5.5 cuesta menos que Claude Opus 5 ($4 / $20 USD por millón de tokens de entrada / salida, frente a $5 / $25; consulta Precios de Claude). Para conocer la compatibilidad de funciones, consulta Novedades de 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.

Lo que debe cumplir cada solicitud a Claude Opus 5.5

Sin importar de qué modelo vengas, una solicitud a claude-opus-5-5 debe cumplir lo siguiente. Cuando un elemento indica que un ajuste se rechaza, la API devuelve un error 400.

• ID del modelo: Usa claude-opus-5-5, un ID de modelo fijo sin sufijo de fecha. En Amazon Bedrock, Claude Platform on AWS, Google Cloud y Microsoft Foundry, usa el ID de modelo de esa plataforma; consulta Disponibilidad.
• Pensamiento: No envíes ningún campo thinking, o envía thinking: {"type": "adaptive"}, que es equivalente: el "adaptive thinking" (pensamiento adaptativo) siempre está activado. thinking: {"type": "disabled"} y los presupuestos de pensamiento manuales (thinking: {"type": "enabled", "budget_tokens": N}) se rechazan. Consulta el antes y después para el pensamiento.
• Esfuerzo: Controla la profundidad del pensamiento con el parámetro "effort" (esfuerzo), el único parámetro de solicitud que la controla. Se admiten los cinco niveles (low, medium, high, xhigh, max), y el valor predeterminado es medium. Consulta Niveles de esfuerzo recomendados para Claude Opus 5.5.
• Elección de herramienta: Usa tool_choice {"type": "auto"} (el valor predeterminado) o {"type": "none"}. Forzar una llamada a herramienta con {"type": "any"} o {"type": "tool", "name": "..."} se rechaza. Consulta el antes y después para la elección de herramienta.
• Parámetros de muestreo: Omite temperature, top_p y top_k, o déjalos en sus valores predeterminados: cualquier otro valor se rechaza. Usa el prompting para guiar el comportamiento del modelo.
• Prefill: No termines messages con un turno de asistente con "prefill" (prellenado): se rechaza. Usa salidas estructuradas o instrucciones en la indicación del sistema en su lugar. En Amazon Bedrock, las salidas estructuradas no están disponibles para Claude Opus 5.5, así que usa allí instrucciones en la indicación del sistema.
• Uso de computadora: En la Claude API y Google Cloud, declara el uso de computadora como el conjunto de herramientas computer_toolset_20260801; la herramienta anterior computer_20251124 se rechaza allí. Consulta el cambio incompatible del uso de computadora.
• Ventana de contexto: No se necesita ningún encabezado beta de "context window" (ventana de contexto). La ventana de contexto de 1M de tokens es la predeterminada, y un encabezado enviado para modelos anteriores no tiene efecto.

La siguiente solicitud cumple todos los elementos de la lista: el esfuerzo está establecido y no hay ningún campo thinking. Las pestañas de SDK que imprimen texto lo seleccionan por tipo de bloque, porque los bloques thinking aparecen primero.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Gestiona el pensamiento en cada respuesta

El pensamiento se ejecuta en cada solicitud a Claude Opus 5.5, por lo que cada respuesta puede comenzar con bloques thinking, y max_tokens abarca el pensamiento más el texto. Si tu código ya se ejecuta con el pensamiento activado, es probable que los elementos 1 a 3 ya estén resueltos: revisa los elementos 4 y 5. Si se ejecutaba sin pensamiento, en cualquier modelo anterior, cada elemento es un cambio.

1. max_tokens abarca el pensamiento más el texto: En Claude Opus 4.8 y modelos Opus anteriores, las solicitudes sin un campo thinking se ejecutan sin pensamiento. Claude Opus 5 y Claude Sonnet 5 aceptan thinking: {"type": "disabled"}. En Claude Opus 5.5, cada solicitud se ejecuta con pensamiento adaptativo. max_tokens sigue siendo un límite estricto sobre la salida total, pensamiento más texto de respuesta, así que revísalo para las cargas de trabajo que se ejecutaban sin pensamiento. Los tokens de pensamiento se facturan como tokens de salida incluso cuando el texto del pensamiento no se te devuelve, por lo que una carga de trabajo así puede producir más tokens de salida por solicitud. Consulta Control de costos. Para gastar menos tokens en pensamiento, reduce el nivel de esfuerzo. Si ejecutas con esfuerzo xhigh o max, establece un max_tokens grande para que el modelo tenga espacio para pensar y actuar; comienza con 64k tokens y ajusta a partir de ahí. Si tus prompts estaban ajustados para ejecutarse sin pensamiento, consulta Prompts escritos para el pensamiento desactivado.

2. Las respuestas comienzan con bloques de pensamiento: Una respuesta puede comenzar con uno o más bloques thinking antes del primer bloque text. El código que lee la respuesta por posición, como content[0].text o un manejador de streaming que trata el primer evento content_block_start como texto, falla con estas respuestas. En su lugar, selecciona los bloques de contenido por su campo type: lee text de los bloques cuyo type es "text", y ramifica según el tipo de bloque al manejar los eventos de streaming.

3. Devuelve los bloques de pensamiento sin modificar en los bucles de uso de herramientas: Si ejecutas un bucle de "tool use" (uso de herramientas), devuelve a la API los bloques thinking de cada respuesta del asistente completos y sin modificar cuando devuelvas los resultados de las herramientas, incluidos los bloques cuyo campo thinking está vacío. Reenvía el mensaje del asistente tal como lo recibiste en lugar de filtrar sus bloques de contenido por tipo o reconstruirlo: la API rechaza con un error 400 los bloques de pensamiento editados, reordenados o eliminados parcialmente. Consulta Preservar los bloques de pensamiento.

4. El texto del pensamiento se omite de forma predeterminada: thinking.display tiene como valor predeterminado "omitted", por lo que los bloques thinking llegan con un campo thinking vacío junto con su signature. Trata el campo thinking solo como texto para mostrar. Para recibir resúmenes legibles en su lugar, establece thinking.display en "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

   Si tu producto transmite el razonamiento a los usuarios mediante streaming, el valor predeterminado aparece como una pausa larga antes de que comience la salida; establece display: "summarized" para restaurar el progreso visible durante el pensamiento. Consulta Controlar la visualización del pensamiento.

5. El texto entre llamadas a herramientas llega en bloques de pensamiento: Las notas breves que el modelo escribe entre llamadas a herramientas se devuelven como bloques thinking, que están vacíos con la visualización predeterminada. Consulta El texto entre llamadas a herramientas se devuelve en bloques de pensamiento.

Lista de verificación de migración por modelo de partida

Recorre los grupos en orden y detente después del que nombra tu modelo actual: todos los elementos hasta ese punto te corresponden. Si estás en Claude Opus 5, el primer grupo es la lista completa. Si estás en Claude Sonnet 5, aplica el primer grupo y el último.

Todos los modelos de partida

• Actualiza el ID del modelo a claude-opus-5-5.
• Elimina thinking: {"type": "disabled"} y thinking: {"type": "enabled", ...}; elige un nivel de esfuerzo en su lugar.
• Configura effort explícitamente: el valor predeterminado es medium, mientras que el de Claude Opus 5 es high.
• Reemplaza los tipos de tool_choice any y tool por auto más uso estricto de herramientas o salidas estructuradas, o solo por auto en Amazon Bedrock.
• Si usas el uso de computadora en la Claude API o Google Cloud, declara computer_toolset_20260801 (sin encabezado beta) en lugar de computer_20251124 y actualiza tu bucle de agente para el conjunto de herramientas. En Amazon Bedrock, mantén computer_20251124; consulta la sección Compatibilidad de la herramienta de uso de computadora para otras plataformas.
• Si un enrutador o un fallback puede mover una conversación de Claude Opus 5.5 a otro modelo, espera que ese modelo se ejecute sin los bloques de pensamiento de Claude Opus 5.5 (Claude Fable 5.1 y Claude Mythos 5.1 en la Claude API son la excepción y los conservan). Claude Opus 5.5 en sí lee el pensamiento de Claude Opus 5, de modelos Opus, Sonnet y Haiku anteriores y, en la Claude API y Google Cloud, de Claude Sonnet 5.5 y Claude Haiku 5.5, pero no de los modelos Claude Fable ni Claude Mythos.
• Lee los bloques de contenido por type y pasa los bloques thinking de vuelta sin modificar en los bucles de uso de herramientas.
• Si tu interfaz muestra el texto entre llamadas a herramientas, configura display: "updates" (beta) o "summarized" y muestra los bloques thinking que no estén vacíos.
• Si tu código edita turnos anteriores, la indicación system o tools a mitad de la conversación, sigue Pensamiento preservado.
• Gestiona stop_reason: "refusal" y configura el fallback.
• Vuelve a establecer la línea base de costo y latencia en el nivel de esfuerzo que elijas.
• Si tu código desactivaba el pensamiento, revisa max_tokens, que cubre el pensamiento más el texto de respuesta; con esfuerzo xhigh o max, comienza con 64k. Consulta Gestiona el pensamiento en cada respuesta.

Claude Opus 4.8 o anterior

• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: en Claude Opus 5.5 se ejecutan con pensamiento, y el pensamiento no se puede desactivar. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), y reduce effort donde quieras menos pensamiento. Los tokens de pensamiento se facturan como tokens de salida, por lo que estas cargas de trabajo pueden producir más tokens de salida por solicitud.
• Verifica que cualquier código que analice el campo thinking lo trate solo como texto para mostrar. Establece display: "summarized" para recibir resúmenes legibles.
• Revisa los prompts cercanos al mínimo de caché: los prompts de 512 tokens o más pueden crear entradas de caché.
• Si tu organización tiene un compromiso de Priority Tier, planifica la capacidad por separado: Priority Tier no es compatible con Claude Opus 5.5.
• Si ejecutas con esfuerzo xhigh o max, aumenta max_tokens a al menos 64k como punto de partida.
• Para cargas de trabajo agénticas, considera los presupuestos de tareas (beta) y los cambios de herramientas a mitad de la conversación (beta).

Claude Opus 4.7 o anterior

• Ejecuta un nuevo barrido de esfuerzo con tus propias evaluaciones en lugar de trasladar una configuración ajustada para un modelo anterior.
• Elimina cualquier encabezado beta de ventana de contexto.
• Si reconstruyes el historial de la conversación para actualizar instrucciones, considera cambiar a un mensaje del sistema a mitad de la conversación para preservar los aciertos de la caché de prompts.
• Verifica que tu manejo de motivos de detención lea stop_details en los rechazos.
• Si quieres el modo rápido, que Claude Opus 4.7 rechaza, establece speed: "fast" en tus solicitudes a la Claude API. Claude Opus 5.5 no necesita un encabezado beta.

Claude Opus 4.6 o anterior

• Elimina temperature, top_p y top_k de los cuerpos de las solicitudes.
• Reemplaza thinking: {"type": "enabled", "budget_tokens": N} por thinking: {"type": "adaptive"} más el parámetro effort, o elimina por completo el campo thinking; el pensamiento adaptativo siempre está activado.
• Si tu interfaz muestra el contenido del pensamiento, activa explícitamente el resumen del pensamiento.
• Vuelve a medir el costo y la latencia de extremo a extremo con la tokenización actualizada.
• Vuelve a ajustar max_tokens para tener en cuenta la tokenización actualizada, incluidos los disparadores de compactación.
• Vuelve a probar cualquier estimación de conteo de tokens del lado del cliente.
• Si tu aplicación envía imágenes, vuelve a presupuestar para la compatibilidad con imágenes de alta resolución (hasta aproximadamente 3 veces más tokens de imagen por imagen a resolución completa). Reduce la resolución antes de enviar si no necesitas la fidelidad adicional.
• Si consumes coordenadas de señalamiento o de cuadros delimitadores del modelo, elimina cualquier conversión por factor de escala; las coordenadas son 1:1 con los píxeles reales de la imagen en Claude Opus 4.7 y modelos posteriores.
• Revisa los cambios de comportamiento que comenzaron en Claude Opus 4.7.
• Si tu producto realiza trabajo legítimo de seguridad, solicita acceso al Cyber Verification Program para obtener restricciones menores sobre contenido cibernético.

Claude Opus 4.5 o anterior

• Elimina cualquier prefill de mensajes del asistente; Claude Opus 4.6 ya los rechaza.
• Verifica que el análisis del JSON de las llamadas a herramientas use un analizador JSON estándar.
• Pasa de client.beta.messages.create() a client.messages.create(): el pensamiento adaptativo y el esfuerzo no necesitan un espacio de nombres beta.
• Elimina el encabezado beta effort-2025-11-24 (el parámetro effort no lo requiere).
• Elimina el encabezado beta fine-grained-tool-streaming-2025-05-14.
• Elimina el encabezado beta interleaved-thinking-2025-05-14 (el pensamiento adaptativo habilita automáticamente el pensamiento intercalado).
• Migra output_format a output_config.format (si corresponde).

Claude 4.1 o anterior

• Actualiza las versiones de las herramientas (text_editor_20250728, code_execution_20260521).
• Gestiona el motivo de detención refusal.
• Gestiona el motivo de detención model_context_window_exceeded.
• Verifica el manejo de los parámetros de cadena de las herramientas en cuanto a saltos de línea finales.
• Elimina los encabezados beta heredados (token-efficient-tools-2025-02-19, output-128k-2025-02-19).
• Revisa y actualiza los prompts siguiendo las mejores prácticas de prompting.

Solo Claude Sonnet 5

• Si reconstruyes el historial de la conversación para actualizar instrucciones, considera cambiar a un mensaje del sistema a mitad de la conversación para preservar los aciertos de la caché de prompts.
• Revisa los prompts cercanos al mínimo de caché: los prompts de 512 tokens o más pueden crear entradas de caché.

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

Primero revisa Lo que debe cumplir cada solicitud a Claude Opus 5.5 y Gestiona el pensamiento en cada respuesta. Todos los modelos de partida necesitan los cambios de esta sección. Son las configuraciones de solicitud que Claude Opus 5.5 rechaza y los cambios en las respuestas que lo acompañan. La lista de verificación de esta sección es el primer grupo de la lista de verificación de migración.

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, 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 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 esfuerzo; donde desactivabas el pensamiento para ahorrar tokens, usa uno más bajo. Las respuestas comienzan 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. Claude Opus 5 acepta esta solicitud, y Claude Opus 5.5 la rechaza con un error 400:

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 de tool_choice any y tool 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 uso estricto de herramientas o salidas estructuradas, e indica en el prompt cuándo se aplica la herramienta. El uso estricto de herramientas acepta un subconjunto de JSON Schema, así que revisa el input_schema de cada herramienta antes de agregar strict: true. Cada objeto del esquema debe establecer additionalProperties: false; consulta Limitaciones de JSON Schema. En Amazon Bedrock, las salidas estructuradas, que incluyen el uso estricto de herramientas, no están disponibles para Claude Opus 5.5. Allí, envía auto sin strict, indica en el prompt cuándo se aplica la herramienta y valida la entrada de la herramienta en tu código. Consulta El uso forzado de herramientas no es compatible.

Antes. Claude Opus 5 acepta esta solicitud, y Claude Opus 5.5 la rechaza con un error 400:

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 de herramientas estricto: 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 Claude API, 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. Un enrutador o un fallback que mueve una conversación de Claude Opus 5.5 a cualquier otro modelo ejecuta esos turnos sin ellos. En la otra dirección, Claude Opus 5.5 lee los bloques de pensamiento de Claude Opus 5, de modelos Opus, Sonnet y Haiku anteriores y, en la Claude API y Google Cloud, de Claude Sonnet 5.5 y Claude Haiku 5.5, pero no de los modelos Claude Fable ni Claude Mythos. Mantén la conversación en modo de solo anexar (sin ediciones a la indicación system, a tools ni a 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 lo hacen. La aplicación de esta regla coincide con 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 así devuelve un error 400 de forma predeterminada. No hay cambio de código para las integraciones de solo anexar. 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 Claude API ni en Google Cloud

En la Claude API y 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 herramienta que acepta el modelo). Declara en su lugar el conjunto de herramientas computer_toolset_20260801: elimina el encabezado beta y envía la entrada sin name ni dimensiones de pantalla. En tu bucle de agente, gestiona los bloques tool_use de los miembros (la acción es el name del bloque, no input.action), varios de ellos por turno, y reenvía toolset_name en cada resultado. El cambio en la solicitud se muestra a continuación; los cambios en el bucle de 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, por lo que no se necesita ningún cambio allí; para otras plataformas, consulta la sección Compatibilidad de la herramienta de uso de computadora. Consulta La herramienta de uso de computadora computer_20251124 no es compatible en la Claude API ni en Google Cloud.

Antes. Claude Opus 5 acepta esta solicitud, y en la Claude API y Google Cloud, Claude Opus 5.5 la rechaza con un error 400:

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 toolset 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" además de "cyber" y "reasoning_extraction"; consulta la tabla de categorías de rechazo. Gestiona los rechazos y configura el fallback del lado del servidor o tu propio reintento (el fallback del lado del servidor no reintenta las solicitudes rechazadas con "reasoning_extraction"; ese rechazo se te devuelve); consulta Rechazos y fallback y Rechazos de salvaguardas.

Cambios recomendados

1. Vuelve a ejecutar tu barrido de esfuerzo. El esfuerzo es el único control del pensamiento en Claude Opus 5.5, y su valor predeterminado es medium, mientras que el de Claude Opus 5 es high, por lo 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.

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

Primero revisa Lo que debe cumplir cada solicitud a Claude Opus 5.5, Gestiona el pensamiento en cada respuesta y Migración a Claude Opus 5.5 desde Claude Opus 5. Usa claude-opus-4-8 como el ID de modelo que reemplazas. Esa última sección se aplica tal cual al código en Claude Opus 4.8, porque Claude Opus 4.8, al igual que Claude Opus 5:

• Acepta thinking: {"type": "disabled"}, la elección forzada de herramienta y la herramienta computer_20251124.
• Devuelve el texto entre llamadas a herramientas como bloques text.
• Usa el esfuerzo high de forma predeterminada.

Esta sección agrega lo que cambió entre Claude Opus 4.8 y Claude Opus 5. Para una lista de verificación, consulta los dos primeros grupos de la lista de verificación de migración.

Qué cambió

1. El pensamiento se ejecuta en las solicitudes que lo omitían: En Claude Opus 4.8, el pensamiento está desactivado a menos que lo solicites. En Claude Opus 5.5, una solicitud sin campo thinking se ejecuta con pensamiento, por lo que cada elemento de Gestiona el pensamiento en cada respuesta es un cambio para ese código. Si tu código nunca envió un campo thinking, no hay nada que eliminar según el antes y después para el pensamiento.

2. Mínimo más bajo para el almacenamiento en caché de prompts: La longitud mínima de prompt almacenable en caché en Claude Opus 5.5 es de 512 tokens, frente a 1,024 tokens en Claude Opus 4.8. Los prompts que eran demasiado cortos para almacenarse en caché en Claude Opus 4.8 pueden crear entradas de caché, sin necesidad de cambios de código. Consulta Almacenamiento en caché de prompts para conocer los mínimos por modelo.

3. Priority Tier no es compatible: Priority Tier no es compatible con Claude Opus 5.5, mientras que Claude Opus 4.8 lo mantiene. Si tu organización tiene un compromiso de Priority Tier, planifica la capacidad por separado.

Cambios recomendados

No son obligatorios, pero mejorarán tu experiencia:

1. Considera los presupuestos de tareas (beta): En cargas de trabajo agénticas, los presupuestos de tareas le indican al modelo cuántos tokens tiene disponibles para un bucle agéntico completo. Requieren el encabezado beta task-budgets-2026-03-13.

2. Considera los cambios de herramientas a mitad de la conversación (beta): Los cambios de herramientas a mitad de la conversación te permiten agregar o quitar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en los turnos anteriores. Modificar directamente el arreglo tools invalida el prefijo almacenado en caché. En la Claude API, envía el encabezado beta inline-tools-2026-09-15. El encabezado anterior mid-conversation-tool-changes-2026-07-01 sigue funcionando para los cambios que hacen referencia a una herramienta por su nombre, en la Claude API, Amazon Bedrock y Google Cloud.

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

Primero revisa Lo que debe cumplir cada solicitud a Claude Opus 5.5, Gestiona el pensamiento en cada respuesta, Migración a Claude Opus 5.5 desde Claude Opus 5 y Migración a Claude Opus 5.5 desde Claude Opus 4.8. Usa claude-opus-4-7 como el ID de modelo que reemplazas. Esas secciones se aplican tal cual al código en Claude Opus 4.7. Al igual que Claude Opus 4.8, acepta thinking: {"type": "disabled"}, la elección forzada de herramienta y la herramienta computer_20251124. Usa el esfuerzo high de forma predeterminada y se ejecuta sin pensamiento a menos que lo solicites.

Esta sección agrega lo que cambió después de Claude Opus 4.7. Si tu código está en Claude Opus 4.6 o anterior, continúa con Migración a Claude Opus 5.5 desde Claude Opus 4.6 y modelos Opus anteriores después de esta sección. Esa sección agrega los cambios incompatibles que entraron en vigor en Claude Opus 4.7. Para una lista de verificación, consulta los tres primeros grupos de la lista de verificación de migración.

Qué cambió

Ninguno de estos elementos agrega un cambio incompatible a los de las secciones anteriores; vale la pena revisarlos después de cambiar el ID del modelo.

1. Niveles de esfuerzo recalibrados: La asignación de tokens detrás de cada nivel de esfuerzo cambia en Claude Opus 5.5 en comparación con Claude Opus 4.7. El valor predeterminado es medium, mientras que el de Claude Opus 4.7 es high. Ejecuta un nuevo barrido de esfuerzo con tus propias evaluaciones en lugar de trasladar una configuración ajustada para Claude Opus 4.7. Consulta Esfuerzo.

2. La ventana de contexto de 1M es la predeterminada: Claude Opus 5.5 ofrece la ventana de contexto completa de 1M de tokens de forma predeterminada, sin encabezado beta. Si tu cliente envía un encabezado beta de ventana de contexto por compatibilidad con modelos anteriores, elimínalo.

3. Mensajes del sistema a mitad de la conversación: En la Claude API, Amazon Bedrock y Google Cloud, Claude Opus 5.5 acepta mensajes role: "system" inmediatamente después de un turno de usuario en el arreglo messages (sujeto a las reglas de ubicación). Usa el campo system de nivel superior para las instrucciones que se aplican desde el inicio. Claude Opus 4.7 rechaza role: "system" en messages con un error 400. Si mantienes rutas de código que reconstruyen el historial completo de mensajes para actualizar instrucciones, puedes simplificarlas y preservar los aciertos de la caché de prompts en turnos anteriores.

4. Detalles de detención por rechazo: Cuando el modelo rechaza una solicitud, Claude Opus 5.5 devuelve un objeto stop_details que nombra la categoría del rechazo, junto con el motivo de detención refusal. Claude Opus 4.7 devuelve el mismo objeto, así que esto solo importa si tu manejo de motivos de detención aún no lo lee. No se requiere ningún encabezado beta y no hay forma de desactivarlo. Si tu manejo de motivos de detención aún no lo lee, consulta Gestionar los motivos de detención. Claude Opus 5.5 rechaza en más categorías; consulta Clasificadores de seguridad y fallback.

5. Modo rápido: Claude Opus 5.5 admite el modo rápido en la Claude API. El modo rápido no está disponible en Claude Opus 4.7, donde las solicitudes con speed: "fast" devuelven un error. Establece speed: "fast" en tus solicitudes. Claude Opus 5.5 no necesita un encabezado beta.

6. Conjunto de herramientas de uso de computadora y herramienta de uso del navegador: En la Claude API y Google Cloud, Claude Opus 5.5 admite el uso de computadora como el conjunto de herramientas computer_toolset_20260801 y la herramienta de uso del navegador para tareas dentro de páginas web. Claude Opus 4.7 no admite ninguno de los dos. En esas plataformas, Claude Opus 5.5 no acepta la herramienta anterior computer_20251124; consulta el cambio incompatible del uso de computadora.

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

Primero revisa todas las secciones anteriores, en el orden de la página. Son Lo que debe cumplir cada solicitud a Claude Opus 5.5, Gestiona el pensamiento en cada respuesta y las secciones de Claude Opus 5, Claude Opus 4.8 y Claude Opus 4.7. Esas secciones se aplican tal cual al código en Claude Opus 4.6. Al igual que Claude Opus 4.7, acepta thinking: {"type": "disabled"}, la elección forzada de herramienta y la herramienta computer_20251124. Usa el esfuerzo high de forma predeterminada y se ejecuta sin pensamiento a menos que lo solicites. Claude Opus 4.5 y los modelos Opus anteriores también aceptan thinking: {"type": "disabled"} y la elección forzada de herramienta, y se ejecutan sin pensamiento a menos que lo solicites, por lo que esas secciones también se aplican a ellos.

Esta sección agrega lo que cambió en Claude Opus 4.7, con claude-opus-4-6 como el ID de modelo que reemplazas. Sus dos subsecciones agregan lo que cambió antes de eso, para los lectores en Claude Opus 4.5 o anterior y Claude 4.1 o anterior. Para una lista de verificación, consulta la lista de verificación de migración hasta el grupo que nombra tu modelo.

Cambios incompatibles

1. Pensamiento extendido eliminado: thinking: {"type": "enabled", "budget_tokens": N} ya no es compatible con Claude Opus 4.7 y modelos posteriores, y devuelve un error 400. Cambia a pensamiento adaptativo (thinking: {"type": "adaptive"}) y usa el parámetro effort para controlar la profundidad del pensamiento. En Claude Opus 5.5, el pensamiento adaptativo siempre está activado: thinking: {"type": "adaptive"} es válido y equivale a omitir por completo el campo thinking.

   Antes (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client.messages.create(
       model="claude-opus-4-6",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[{"role": "user", "content": "..."}],
   )

   Después (Claude Opus 5.5), donde difieren el ID del modelo y las líneas thinking y output_config:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client.messages.create(
       model="claude-opus-5-5",
       max_tokens=16000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
       messages=[{"role": "user", "content": "..."}],
   )

   El pensamiento adaptativo se puede orientar mediante prompts y el parámetro effort, que reemplaza al presupuesto de pensamiento como la forma de controlar cuánto razona el modelo. Ejecuta un barrido de esfuerzo en tus propias evaluaciones en lugar de traducir un valor de budget_tokens. La tabla de niveles de esfuerzo describe cuándo usar cada nivel, y Niveles de esfuerzo recomendados para Claude Opus 5.5 cubre este modelo.

2. Parámetros de muestreo eliminados: Establecer temperature, top_p o top_k en cualquier valor distinto del predeterminado en Claude Opus 4.7 y modelos posteriores, incluido Claude Opus 5.5, devuelve un error 400. El SDK de Python (v1.0 y posteriores) no los define, y pasarlos genera un TypeError. La ruta de migración más segura es omitir por completo estos parámetros de las cargas útiles de las solicitudes. Los prompts son la forma recomendada de guiar el comportamiento del modelo en Claude Opus 5.5. Si usabas temperature = 0 para obtener determinismo, ten en cuenta que nunca garantizó salidas idénticas en modelos anteriores.

3. Contenido de pensamiento omitido de forma predeterminada: Los bloques de pensamiento siguen apareciendo en el flujo de respuesta en Claude Opus 4.7 y modelos posteriores, pero su campo thinking está vacío a menos que lo habilites explícitamente. Este es un cambio silencioso respecto a Claude Opus 4.6, donde el comportamiento predeterminado era devolver texto de pensamiento resumido. Para restaurarlo, consulta el punto 4 de Gestiona el pensamiento en cada respuesta.

4. Conteo de tokens actualizado: Claude Opus 4.7 introdujo un nuevo tokenizador, que también usan los modelos Opus posteriores, incluido Claude Opus 5.5. Contribuye a un mejor rendimiento en una amplia variedad de tareas, y puede usar aproximadamente entre 1x y 1.35x tokens al procesar texto en comparación con los modelos anteriores a Claude Opus 4.7 (hasta ~35% más, según el contenido).

   /v1/messages/count_tokens devuelve un número de tokens para Claude Opus 5.5 diferente del que devolvía para Claude Opus 4.6. La eficiencia de tokens puede variar según la forma de la carga de trabajo.

   Actualiza tus parámetros max_tokens para dar margen adicional, incluidos los disparadores de compactación, y vuelve a probar cualquier ruta de código que estime tokens del lado del cliente o que asuma una proporción fija de tokens por carácter. Usa el endpoint de conteo de tokens para verificarlo. Las intervenciones en los prompts, task_budget y effort pueden ayudar a controlar los costos; estos controles pueden implicar una compensación en la inteligencia del modelo.

5. Eliminación del prefill (ya vigente en Claude Opus 4.6): Prellenar mensajes del asistente devuelve un error 400 en Claude Opus 4.6 y modelos Opus posteriores, incluido Claude Opus 5.5, por lo que esto solo es un cambio si vienes de Claude Opus 4.5 o anterior. Usa salidas estructuradas o instrucciones en la indicación del sistema en su lugar. En Amazon Bedrock, las salidas estructuradas no están disponibles para Claude Opus 5.5, así que usa instrucciones en la indicación del sistema allí.

Cambios de comportamiento

Claude Opus 4.7 introdujo diferencias de comportamiento respecto a Claude Opus 4.6 que no son cambios incompatibles de la API. Estas tres afectan al código o al andamiaje:

1. Actualizaciones de progreso integradas en trazas agénticas: Claude Opus 4.7 proporciona al usuario actualizaciones más regulares y de mayor calidad a lo largo de trazas agénticas largas. Si agregaste andamiaje para forzar mensajes de estado intermedios ("Después de cada 3 llamadas a herramientas, resume el progreso"), intenta eliminarlo. En Claude Opus 5.5, estas actualizaciones llegan en bloques thinking, que están vacíos con el valor predeterminado de thinking.display. Para recibirlas, consulta El texto entre llamadas a herramientas se devuelve en bloques de pensamiento. Para ajustar su longitud y contenido, consulta Actualizaciones de progreso para el usuario.

2. Salvaguardas de ciberseguridad en tiempo real: Con estas salvaguardas, añadidas en Claude Opus 4.7, las solicitudes que involucran temas prohibidos o de alto riesgo pueden dar lugar a rechazos. Para trabajo de seguridad legítimo, como pruebas de penetración, investigación de vulnerabilidades o red-teaming, solicita acceso al Cyber Verification Program para pedir restricciones reducidas. La vía de solicitud depende de cómo accedas a Claude.

3. Compatibilidad con imágenes de alta resolución: Claude Opus 4.7 es el primer modelo de Claude compatible con imágenes de alta resolución. La resolución máxima de imagen es de 2,576 píxeles en el lado largo, frente a 1,568 píxeles en modelos anteriores. Esto permite mejoras en cargas de trabajo con mucho contenido visual y es especialmente valioso para el uso de computadora, la comprensión de capturas de pantalla y el análisis de documentos.

   La compatibilidad con alta resolución es automática y no requiere ningún encabezado beta ni activación del lado del cliente. Hay dos aspectos que debes planificar:

   • Las imágenes a resolución completa pueden usar hasta aproximadamente 3 veces más tokens de imagen que en modelos anteriores (hasta 4,784 tokens por imagen, en comparación con el límite anterior de aproximadamente 1,600 tokens por imagen). Vuelve a calcular el presupuesto de max_tokens y las expectativas de costo para cargas de trabajo con muchas imágenes, o reduce la resolución antes de enviarlas si no necesitas la fidelidad adicional.
   • Las coordenadas de señalamiento y de cuadros delimitadores que devuelve el modelo corresponden 1:1 con los píxeles reales de la imagen en Claude Opus 4.7, por lo que no se requiere ninguna conversión de factor de escala.

   Consulta Compatibilidad con imágenes de alta resolución en Claude Opus 4.7 para obtener más detalles.

Para las diferencias relacionadas con los prompts, consulta Cómo escribir prompts para Claude Opus 5.5 y Mejores prácticas de prompting.

Migrar desde Claude Opus 4.5 o anterior

Si estás migrando desde Claude Opus 4.5, Claude Opus 4.1 o un modelo anterior directamente a Claude Opus 5.5, lee esta página desde el principio: primero revisa cada una de las secciones anteriores, en el orden de la página. Luego revisa los cambios incompatibles al migrar desde Claude Opus 4.6, que aparecen antes en esta sección. Después aplica los siguientes cambios acumulativos, que entraron en vigor entre Claude Opus 4.5 y Claude Opus 4.7. Si usas Claude Opus 4.1 o anterior, continúa con Migrar desde Claude 4.1 o anterior después de esta subsección.

Cambios incompatibles

1. La eliminación del prefill se trata en los cambios incompatibles al migrar desde Claude Opus 4.6.

2. Entrecomillado de parámetros de herramientas: Claude Opus 4.6 y los modelos posteriores pueden producir un escape de cadenas JSON ligeramente diferente en los argumentos de las llamadas a herramientas (por ejemplo, un manejo diferente de los escapes Unicode o del escape de barras diagonales). Si analizas el input de las llamadas a herramientas como una cadena sin procesar en lugar de usar un analizador JSON, verifica tu lógica de análisis. Los analizadores JSON estándar (como json.loads() o JSON.parse()) manejan estas diferencias automáticamente.

Cambios recomendados

El primer punto es obligatorio en Claude Opus 5.5; el resto son recomendados.

1. Migra al pensamiento adaptativo (obligatorio): thinking: {"type": "enabled", "budget_tokens": N} devuelve un error 400 en Claude Opus 4.7 y modelos posteriores. El antes y el después se encuentran en el punto 1 de los cambios incompatibles para migrar desde Claude Opus 4.6. La migración también pasa de client.beta.messages.create() a client.messages.create(): el pensamiento adaptativo y el esfuerzo no requieren el espacio de nombres beta del SDK ni ningún encabezado beta.

2. Elimina el encabezado beta de effort: El parámetro effort no requiere un encabezado beta. Elimina la beta effort-2025-11-24 de tus solicitudes.

3. Elimina el encabezado beta de streaming de herramientas detallado: El streaming de herramientas detallado no requiere un encabezado beta. Elimina la beta fine-grained-tool-streaming-2025-05-14 de tus solicitudes.

4. Elimina el encabezado beta de pensamiento intercalado: Con el pensamiento adaptativo, el pensamiento intercalado es automático en todos los modelos compatibles con el pensamiento adaptativo. Elimina la beta interleaved-thinking-2025-05-14 de tus solicitudes.

5. Migra a output_config.format: Si usas salidas estructuradas, actualiza output_format={...} a output_config={"format": {...}}. El parámetro output_format está obsoleto y se eliminará en el futuro. Para usarlo de todos modos, agrega el encabezado beta structured-outputs-2025-11-13. Sin él, la API devuelve un error 400. El SDK de Python (v1.0 y posteriores) no acepta output_format={...} en client.beta.messages.create() ni en count_tokens(). El argumento output_format=Model de los helpers parse() y stream() no cambia.

Migrar desde Claude 4.1 o anterior

Si estás migrando desde Claude Opus 4.1 o modelos anteriores directamente a Claude Opus 5.5, primero aplica todo lo indicado en Migrar desde Claude Opus 4.5 o anterior. Esa subsección comienza con todas las secciones anteriores, así que, en la práctica, lees esta página desde el principio. Luego aplica los cambios adicionales de esta subsección.

Cambios incompatibles adicionales

1. Elimina los parámetros de muestreo: Se trata en Se eliminaron los parámetros de muestreo.

2. Actualiza las versiones de las herramientas

   Actualiza a las versiones actuales de las herramientas. Elimina cualquier código que use el comando undo_edit.

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # Antes
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # Después
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

   • Editor de texto: Usa text_editor_20250728 y str_replace_based_edit_tool. Consulta la documentación de la herramienta de editor de texto para obtener más detalles.
   • Ejecución de código: Actualiza a code_execution_20260521. Consulta la documentación de la herramienta de ejecución de código para ver las instrucciones de migración.
   • Uso de computadora: En la API de Claude y Google Cloud, Claude Opus 5.5 acepta el uso de computadora solo como el conjunto de herramientas computer_toolset_20260801: las herramientas anteriores computer_20250124 y computer_20251124 se rechazan en esas plataformas. Consulta el cambio incompatible del uso de computadora.

3. Gestiona el motivo de detención refusal

   Actualiza tu aplicación para gestionar los motivos de detención refusal:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # Maneja el rechazo de forma adecuada
       pass

4. Gestiona el motivo de detención model_context_window_exceeded

   Los modelos Claude 4.5 y posteriores devuelven un motivo de detención model_context_window_exceeded cuando la generación se detiene por alcanzar el límite de la ventana de contexto, en lugar del límite max_tokens solicitado. Actualiza tu aplicación para gestionar este nuevo motivo de detención:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # Gestiona adecuadamente el límite de la ventana de contexto
       pass

5. Verifica el manejo de parámetros de herramientas (saltos de línea finales)

   Los modelos Claude 4.5 y posteriores conservan los saltos de línea finales en los parámetros de cadena de las llamadas a herramientas, que antes se eliminaban. Si tus herramientas dependen de la coincidencia exacta de cadenas con los parámetros de las llamadas a herramientas, verifica que tu lógica maneje correctamente los saltos de línea finales.

6. Actualiza tus prompts para los cambios de comportamiento

   Los modelos Claude 4 y posteriores tienen un estilo de comunicación más conciso y directo, y requieren instrucciones explícitas. Revisa las mejores prácticas de prompting para obtener orientación sobre optimización.

Cambios recomendados adicionales

• Elimina los encabezados beta heredados: Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19. Todos los modelos Claude 4 y posteriores tienen integrado un uso de herramientas eficiente en tokens, y estos encabezados no tienen ningún efecto.

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

Revisa Lo que debe cumplir cada solicitud a Claude Opus 5.5, Gestiona el pensamiento en cada respuesta y Migración a Claude Opus 5.5 desde Claude Opus 5. Usa claude-sonnet-5 como el ID de modelo que reemplazas. Esa última sección se aplica al código en Claude Sonnet 5 tal como está escrito, porque Claude Sonnet 5, al igual que Claude Opus 5:

• Se ejecuta con el pensamiento activado de forma predeterminada y acepta thinking: {"type": "disabled"}, en su caso con cualquier nivel de esfuerzo.
• Acepta la elección forzada de herramientas y la herramienta computer_20251124.
• Devuelve el texto entre llamadas a herramientas como bloques text.
• Usa el esfuerzo high de forma predeterminada.

El pensamiento extendido manual, los parámetros de muestreo con valores no predeterminados y el prefill del asistente devuelven un error 400 en ambos modelos, así que nada cambia en ese aspecto. Ninguno de los cambios obligatorios de las secciones para Claude Opus 4.8, Claude Opus 4.7 y Claude Opus 4.6 se aplica a tu caso.

Qué cambió

1. Mensajes del sistema a mitad de la conversación: En la API de Claude, Amazon Bedrock y Google Cloud, Claude Opus 5.5 acepta mensajes role: "system" inmediatamente después de un turno del usuario en el arreglo messages (sujeto a las reglas de ubicación). Esta función no está disponible en Claude Sonnet 5. Si mantienes rutas de código que reconstruyen el historial completo de mensajes para actualizar instrucciones, puedes simplificarlas y conservar los aciertos de la caché de prompts en turnos anteriores.

2. Mínimo más bajo para el almacenamiento en caché de prompts: La longitud mínima de prompt que admite el almacenamiento en caché de prompts en Claude Opus 5.5 es de 512 tokens, frente a 1,024 tokens en Claude Sonnet 5. Los prompts que eran demasiado cortos para almacenarse en caché en Claude Sonnet 5 ahora pueden crear entradas de caché, sin necesidad de cambios en el código. Consulta Almacenamiento en caché de prompts para ver los mínimos por modelo.