Claude Platform Docs
Modelos y preciosClaude Opus 5.5

Guía de migración a Claude Opus 5.5

Cambia a Claude Opus 5.5 desde modelos Opus anteriores o desde Claude Sonnet 5 con esta guía de migración. La guía para habilitar Claude Opus 5.5 incluye la configuración de solicitudes que devuelve errores, los bloques de pensamiento en cada respuesta y una lista de verificación para cada modelo de partida.

Claude Code

Deja que Claude Code migre tu código por ti

/claude-api migrate este proyecto a claude-opus-5-5

Esta página enumera los cambios de código 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. Luego ve a la sección de tu modelo actual: su primera oración nombra las demás secciones que se aplican a ti. 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, en comparación con $5 / $25 USD; 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 Prompting 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 dice que una configuración se rechaza, la API devuelve un error 400.

  • ID de modelo: Usa claude-opus-5-5, un ID de modelo fijo sin sufijo de fecha. En Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) 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 thinking.
  • Esfuerzo: Controla la profundidad del pensamiento con el parámetro “effort” (esfuerzo), el único parámetro de solicitud que lo 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. Usa prompts para guiar el comportamiento del modelo.
  • Prellenado: No termines messages con un turno de asistente prellenado (“prefill”): se rechaza. Usa “structured outputs” (salidas estructuradas) o instrucciones en la indicación del sistema en su lugar.
  • Uso de computadora: Declara el “computer use” (uso de computadora) como el conjunto de herramientas computer_toolset_20260801. En Amazon Bedrock, computer_20251124 también funciona. Consulta el cambio incompatible de computer use.
  • Ventana de contexto: No se necesita ningún encabezado beta de ventana de contexto. La “context window” (ventana de contexto) de 1M tokens es la predeterminada, y un encabezado enviado para modelos anteriores no tiene efecto.

La siguiente solicitud cumple con todos los elementos de la lista: se establece el esfuerzo y no hay ningún campo thinking. Cuando el ejemplo imprime texto, encuentra el bloque de texto por su tipo, porque los bloques thinking vienen 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 cubre 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 cubre 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 esa carga de trabajo 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 se ajustaron 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 bifurca según el tipo de bloque al manejar eventos de streaming.

  3. Devuelve los bloques de pensamiento sin modificar en los bucles de uso de herramientas: Si ejecutas un bucle de uso de herramientas, pasa los bloques thinking de cada respuesta del asistente de vuelta a la API completos y sin modificar cuando devuelvas resultados de 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 los bloques de pensamiento editados, reordenados o eliminados parcialmente con un error 400. 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 a su signature. Trata el campo thinking solo como texto de visualización. Para recibir resúmenes legibles en su lugar, establece thinking.display en "summarized":

    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 regresan 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: cada elemento hasta ese punto se aplica a ti. Si usas Claude Opus 5, el primer grupo es la lista completa. Si usas Claude Sonnet 5, aplica el primer grupo y el último.

Todos los modelos de partida

  • Actualiza el ID de modelo a claude-opus-5-5.
  • Elimina thinking: {"type": "disabled"} y thinking: {"type": "enabled", ...}; elige un nivel de esfuerzo en su lugar.
  • Establece 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 junto con uso estricto de herramientas o salidas estructuradas.
  • Si usas una versión anterior de la herramienta de uso de computadora, declara computer_toolset_20260801 (sin encabezado beta) en su lugar y actualiza tu bucle de agente para el conjunto de herramientas. En Amazon Bedrock, computer_20251124 también funciona.
  • Si un enrutador o mecanismo de respaldo 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 Claude Models on Google Cloud (Google managed), 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 devuelve los bloques thinking sin modificar en los bucles de uso de herramientas.
  • Si tu interfaz muestra texto entre llamadas a herramientas, establece 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.
  • Maneja stop_reason: "refusal" y configura un respaldo.
  • 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 en 64k. Consulta Maneja 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 de visualización. Establece display: "summarized" para recibir resúmenes legibles.
  • Revisa los prompts cercanos al mínimo de almacenamiento en 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

  • Realiza un nuevo barrido de esfuerzo con tus propias evaluaciones en lugar de conservar 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 conservar los aciertos de 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 las cargas de las solicitudes.
  • Reemplaza thinking: {"type": "enabled", "budget_tokens": N} por thinking: {"type": "adaptive"} junto con el parámetro effort, o elimina el campo thinking por completo; 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 activadores de compactación.
  • Vuelve a probar cualquier estimación del recuento 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 de 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 de 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 el 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 el pensamiento intercalado automáticamente).
  • 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 para los saltos de línea finales.
  • Elimina los encabezados beta token-efficient-tools-2025-02-19 y output-128k-2025-02-19.
  • Revisa y actualiza los prompts siguiendo las prácticas recomendadas 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 conservar los aciertos de caché de prompts.
  • Revisa los prompts cercanos al mínimo de almacenamiento en caché: los prompts de 512 tokens o más pueden crear entradas de caché.

Migrar 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 de respuesta 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, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) y Microsoft Foundry, usa el ID de modelo de esa plataforma; consulta Disponibilidad.

Cambios incompatibles

Cada cambio se explica en Cambios incompatibles en Novedades de Claude Opus 5.5; esta sección proporciona 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 pasa los bloques thinking de vuelta sin modificar 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 recuento de tokens. Usa auto con el 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. 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 mecanismo de respaldo que mueva una conversación de Claude Opus 5.5 a cualquier otro modelo ejecuta esos turnos sin ellos. En la dirección opuesta, Claude Opus 5.5 lee bloques de pensamiento de Claude Opus 5, de modelos Opus, Sonnet y Haiku anteriores y, en la Claude API y en Claude Models on Google Cloud (Google managed), 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 del sistema 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. En cuentas creadas a partir del 31 de agosto de 2026, 00:00 UTC, en la Claude API y en plataformas en la nube, una solicitud que reproduce un bloque de pensamiento después de una edición de ese tipo y deja thinking.block_binding.prefix_mismatch_behavior sin establecer recibe un error 400. No se requiere ningún 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.

Algunas versiones de la herramienta de uso de computadora no son compatibles

Claude Opus 5.5 admite el uso de computadora a través del conjunto de herramientas computer_toolset_20260801. En Amazon Bedrock, Claude Opus 5.5 también acepta la herramienta computer_20251124 con el encabezado beta computer-use-2025-11-24. Claude Opus 5.5 devuelve un error 400 para cualquier versión de la herramienta de uso de computadora que no acepte, como computer_20251124 en la Claude API. No acepta computer_20250124 en ninguna plataforma. En la Claude API, el mensaje de error comienza con 'claude-opus-5-5' does not support tool types: computer_20251124. y luego enumera los tipos de herramientas que acepta el modelo.

Las integraciones que usan el conjunto de herramientas no necesitan ningún cambio. Para migrar una integración de computer_20251124 al conjunto de herramientas, elimina el encabezado beta y envía la entrada computer_toolset_20260801 sin name ni dimensiones de pantalla. En tu bucle de agente, maneja cada bloque tool_use miembro en un turno y repite toolset_name en cada resultado. Lee la acción del name de cada bloque, no de input.action. Migrar desde computer_20251124 enumera los cambios del bucle de agente.

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

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 regresa como bloques text. En Claude Opus 5.5, al igual que en Claude Fable 5.1, esa narración regresa como bloques thinking de actualización de progreso, como máximo uno antes de cada llamada a herramienta. Con el thinking.display predeterminado de "omitted", su campo thinking está vacío. Ninguna solicitud falla, pero una aplicación que transmite ese texto a sus usuarios mediante streaming 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 mientras el razonamiento permanece oculto, y "summarized" devuelve ambos, mezclados. Luego muestra cada bloque thinking no vacío antes del bloque tool_use al que precede, y pasa los bloques de vuelta sin cambios con el resto del turno del asistente. Consulta Actualizaciones de progreso para el usuario.

Clasificadores de seguridad y respaldo

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 respaldo del lado del servidor o tu propio reintento (el respaldo del lado del servidor no reintenta las solicitudes rechazadas con "reasoning_extraction"; ese rechazo se te devuelve); consulta Rechazos y respaldo y Rechazos de las salvaguardas.

  1. Vuelve a realizar tu barrido de esfuerzo. El esfuerzo es el único control de 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 donde la calidad se mantenga y sube 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 para el comportamiento de Claude Opus 5 ya no sean necesarias; consulta Prompting 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.

Migrar 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 Migrar 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.
  • Tiene como valor predeterminado el esfuerzo high.

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 de almacenamiento en caché de prompts más bajo: 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 conserva. Si tu organización tiene un compromiso de Priority Tier, planifica la capacidad por separado.

Estos cambios no son obligatorios, pero mejorarán tu experiencia:

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

  2. Considera los cambios de herramientas a mitad de conversación (beta): Los cambios de herramientas a mitad de conversación te permiten agregar o quitar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Cambiar el propio arreglo tools invalida el prefijo almacenado en caché. En la Claude API, Claude Platform on AWS y Claude Models on Google Cloud (Anthropic managed), envía el encabezado beta inline-tools-2026-09-15. El encabezado mid-conversation-tool-changes-2026-07-01 funciona para los cambios que nombran una herramienta por referencia, en la Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) y Claude Models on Google Cloud (Google managed).

Migrar 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, Migrar a Claude Opus 5.5 desde Claude Opus 5 y Migrar 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. Tiene como valor predeterminado el esfuerzo high 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 Migrar 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 “context window” (ventana de contexto) completa de 1M tokens de forma predeterminada, sin encabezado beta. Si tu cliente pasa un encabezado beta de ventana de contexto por compatibilidad con modelos anteriores, elimínalo.

  3. Mensajes del sistema a mitad de conversación: En la Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) y Claude Models on Google Cloud (Google managed), 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). 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 todo el historial de mensajes para actualizar las instrucciones, puedes simplificarlas y conservar los aciertos de la caché de prompts en turnos anteriores.

  4. Detalles de la detención por rechazo: Cuando el modelo rechaza una solicitud, Claude Opus 5.5 devuelve un objeto stop_details que indica la categoría del rechazo, junto con el motivo de detención refusal. Claude Opus 4.7 devuelve el mismo objeto, por lo 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 Manejo de motivos de detención. Claude Opus 5.5 rechaza solicitudes en más categorías; consulta Clasificadores de seguridad y alternativa.

  5. Modo rápido: Claude Opus 5.5 admite el “fast mode” (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: Claude Opus 5.5 admite el “computer use” (uso de computadora) como el conjunto de herramientas computer_toolset_20260801 y la “browser use tool” (herramienta de uso del navegador) para tareas dentro de páginas web. Claude Opus 4.7 no admite ninguno de los dos. Para migrar una integración de computer_20251124 al conjunto de herramientas, consulta el cambio incompatible de uso de computadora.

Migrar a Claude Opus 5.5 desde Claude Opus 4.6 y modelos Opus anteriores

Primero, revisa cada sección anterior, 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 como están escritas al código en Claude Opus 4.6. Al igual que Claude Opus 4.7, acepta thinking: {"type": "disabled"}, la elección forzada de herramientas 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 herramientas, y se ejecutan sin pensamiento a menos que lo solicites, así que esas secciones también se aplican a ellos.

Esta sección añade lo que cambió en Claude Opus 4.7, con claude-opus-4-6 como el ID de modelo que reemplazas. Sus dos subsecciones añaden lo que cambió antes de eso, para quienes usan 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 menciona tu modelo.

Cambios incompatibles

  1. Se eliminó el pensamiento extendido: 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 adaptive thinking (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):

    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:

    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 forma de controlar cuánto razona el modelo. Ejecuta un barrido de esfuerzo con 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: Omite temperature, top_p y top_k. 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 los modelos anteriores.

  3. El contenido del pensamiento se omite 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 lo 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 “tokenizer” (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 podría usar aproximadamente entre 1x y 1.35x tokens al procesar texto en comparación con los modelos anteriores a Claude Opus 4.7 (hasta aproximadamente un 35 por ciento más, según el contenido).

    /v1/messages/count_tokens devuelve un número de tokens diferente para Claude Opus 5.5 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 activadores 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 podrían sacrificar parte de la inteligencia del modelo.

  5. Eliminación del prefill (ya vigente en Claude Opus 4.6): Hacer “prefill” (prellenado) de mensajes del asistente devuelve un error 400 en Claude Opus 4.6 y modelos Opus posteriores, incluido Claude Opus 5.5, así que esto solo es un cambio si vienes de Claude Opus 4.5 o anterior. En su lugar, usa salidas estructuradas o instrucciones en la indicación del sistema.

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 actualizaciones más regulares y de mayor calidad al usuario a lo largo de trazas agénticas largas. Si añadiste andamiaje para forzar mensajes de estado intermedios (“Después de cada 3 llamadas a herramientas, resume el progreso”), prueba a 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: Estas salvaguardas son nuevas en Claude Opus 4.7: las solicitudes que involucran temas prohibidos o de alto riesgo podrían 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 los modelos anteriores. Esto desbloquea 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 encabezado beta ni habilitación del lado del cliente. Dos cosas que debes planificar:

    • Las imágenes a resolución completa pueden usar hasta aproximadamente 3 veces más tokens de imagen que en los modelos anteriores (hasta 4,784 tokens por imagen, en comparación con el límite anterior de aproximadamente 1,600 tokens). Vuelve a presupuestar 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 son 1:1 con los píxeles reales de la imagen en Claude Opus 4.7, por lo que no se requiere 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 Prompts para Claude Opus 5.5 y Mejores prácticas de prompts.

Migrar desde Claude Opus 4.5 o anterior

Si migras 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 sección anterior, en el orden de la página. Luego revisa los cambios incompatibles para 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 para migrar desde Claude Opus 4.6.

  2. Uso de comillas en parámetros de herramientas: Claude Opus 4.6 y modelos posteriores podrían 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, revisa tu lógica de análisis. Los analizadores JSON estándar (como json.loads() o JSON.parse()) manejan estas diferencias automáticamente.

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 está 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 esfuerzo: 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 detallado de herramientas: El “fine-grained tool streaming” (streaming detallado de herramientas) 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 “interleaved thinking” (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. Si aun así quieres usarlo, añade 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 migras desde Claude Opus 4.1 o modelos anteriores directamente a Claude Opus 5.5, primero aplica todo lo que aparece en Migrar desde Claude Opus 4.5 o anterior. Esa subsección comienza con cada sección anterior, 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 Parámetros de muestreo eliminados.

  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.

    # 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 obtener instrucciones de migración.
    • Uso de computadora: Usa el conjunto de herramientas computer_toolset_20260801 en lugar de computer_20250124, que Claude Opus 5.5 no acepta. En Amazon Bedrock, computer_20251124 también funciona. Consulta el cambio incompatible de uso de computadora.

  3. Maneja el motivo de detención refusal

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

    response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Gestiona el rechazo de forma adecuada
    pass

  4. Maneja 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 de max_tokens solicitado. Actualiza tu aplicación para manejar este nuevo motivo de detención:

    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.

  • Encabezados beta: Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19. Todos los modelos Claude 4 y posteriores tienen un “tool use” (uso de herramientas) eficiente en tokens integrado, y estos encabezados no tienen efecto.

Migrar 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 Migrar 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 tal como está escrita al código en Claude Sonnet 5, 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 y el prellenado del asistente devuelven un error 400 en ambos modelos, así que nada cambia en ese aspecto. Ninguno de los cambios obligatorios de las secciones de 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 conversación: En la Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) y Claude Models on Google Cloud (Google managed), 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 todo el historial de mensajes para actualizar las instrucciones, puedes simplificarlas y conservar los aciertos de la caché de prompts en turnos anteriores.

  2. Mínimo de almacenamiento en caché de prompts más bajo: La longitud mínima de prompt que se puede almacenar en caché 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 pueden crear entradas de caché, sin necesidad de cambios en el código. Consulta “Prompt caching” (almacenamiento en caché de prompts) para conocer los mínimos por modelo.

¿Te resultó útil esta página?