Migración a Claude Opus 5

Claude Opus 5 es una mejora sustancial respecto a Claude Opus 4.8, fuerte en razonamiento profundo, tareas agénticas y de horizonte largo, y escalado de cómputo en tiempo de prueba. Para conocer las diferencias de comportamiento y los patrones de prompting específicos del modelo, consulta Prompting de Claude Opus 5.

Claude Opus 5 es una actualización directa para Claude Opus 4.8 al mismo precio de $5 USD por millón de tokens de entrada y $25 USD por millón de tokens de salida; consulta Precios de Claude. Hay dos cambios incompatibles para el código que ya se ejecuta en Claude Opus 4.8, cubiertos en Cambios incompatibles. Claude Opus 5 admite el mismo conjunto de funciones que Claude Opus 4.8, incluida la "context window" (ventana de contexto) de 1M de tokens (la predeterminada, sin encabezado beta), 128k tokens de salida máximos, pensamiento adaptativo, "prompt caching" (almacenamiento en caché de prompts), procesamiento por lotes, la Files API, soporte de PDF, visión y herramientas del lado del servidor y del lado del cliente, con dos excepciones: web fetch no está disponible en Claude Opus 5, y Priority Tier no es compatible con Claude Opus 5. Consulta la página de cada herramienta para conocer la disponibilidad por modelo.

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

Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-8"  # Before
model = "claude-opus-5"  # After

claude-opus-5 es un ID de modelo fijo sin sufijo de fecha, el mismo esquema que claude-opus-4-8 y claude-sonnet-5.

Cambios incompatibles

1. Pensamiento activado por defecto: En Claude Opus 4.8, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Opus 5, las mismas solicitudes se ejecutan 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 en Claude Opus 4.8. Los tokens de pensamiento se facturan como tokens de salida incluso cuando el texto del pensamiento no se te devuelve, por lo que, aunque el precio por token no cambia, una carga de trabajo que se ejecutaba sin pensamiento en Claude Opus 4.8 puede producir más tokens de salida por solicitud en Claude Opus 5; consulta Control de costos. Para conservar el comportamiento anterior, pasa thinking: {type: "disabled"}, sujeto al límite de esfuerzo del siguiente punto; ten en cuenta que con el pensamiento desactivado el modelo puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible, así que prefiere niveles de esfuerzo más bajos con el pensamiento activado cuando puedas, y consulta Ejecución con el pensamiento desactivado para conocer mitigaciones cuando no puedas.

   La forma de la respuesta cambia con ello. Con el pensamiento activado, una respuesta puede comenzar con uno o más bloques thinking antes del primer bloque text, y como thinking.display tiene como valor predeterminado "omitted" en Claude Opus 5, esos bloques llegan con un campo thinking vacío junto a su signature. El código que lee la respuesta por posición, como content[0].text o un manejador de stream 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 eventos de stream. Para recibir resúmenes de pensamiento legibles en lugar de un campo thinking vacío, establece display: "summarized"; consulta Control de la visualización del pensamiento.

   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 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 parcialmente eliminados. Consulta Preservación de los bloques de pensamiento.

2. Desactivar el pensamiento está limitado al esfuerzo high: Aún puedes desactivar el pensamiento con thinking: {type: "disabled"}, pero solo con un nivel de esfuerzo de high o inferior. Una solicitud que combine thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400. Claude Opus 4.8 acepta esta combinación, así que audita las solicitudes que desactivan el pensamiento antes de migrar.

   La verificación se aplica en cada solicitud: la configuración de esfuerzo y pensamiento de cada solicitud se valida de forma independiente, por lo que una solicitud que eleve el esfuerzo a xhigh o max mientras el pensamiento está desactivado se rechaza incluso si se aceptaron solicitudes anteriores en la conversación.

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

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

   

   Después (Claude Opus 5), elimina el campo thinking para volver a activar el pensamiento:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   o mantén el pensamiento desactivado y reduce el esfuerzo:

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

   

Cambios recomendados

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

1. Prueba el esfuerzo max para trabajo crítico en capacidad: Claude Opus 5 admite el conjunto completo de niveles de esfuerzo (low, medium, high, xhigh, max). Donde la capacidad máxima importe más que el gasto de tokens, prueba el esfuerzo max. Puede ofrecer mejoras en las tareas más exigentes, pero puede mostrar rendimientos decrecientes por el mayor uso de tokens y puede ser propenso a pensar en exceso en las más simples. 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í.

2. Considera los fallbacks automáticos: Claude Opus 5 se lanza con clasificadores de seguridad de ciberseguridad cuyos rechazos de categoría cibernética pueden recurrir a Claude Opus 4.8. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro fallbacks con el modo "default" (fallbacks: "default"), que selecciona un modelo de fallback recomendado según la categoría del rechazo en lugar de una lista de modelos mantenida manualmente. El fallback del lado del servidor está en beta; el modo "default" requiere el encabezado beta server-side-fallback-2026-07-01. Consulta Rechazos y fallback.

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

4. Cambia herramientas a mitad de conversación (beta): Puedes agregar o quitar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Envía el encabezado beta mid-conversation-tool-changes-2026-07-01. Esto es útil para cargas de trabajo agénticas que exponen herramientas progresivamente o las retiran a medida que avanza una tarea; sin él, una lista de herramientas modificada invalida el prefijo almacenado en caché.

5. Reajusta los prompts de longitud y verbosidad: Las respuestas visibles predeterminadas y los entregables escritos son más largos en Claude Opus 5 que en Claude Opus 4.8, y reducir el esfuerzo disminuye el volumen de pensamiento sin acortar de forma confiable la respuesta visible. En su lugar, pide explícitamente concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad y Longitud de entregables escritos.

6. Elimina las instrucciones de verificación heredadas y restringe el alcance: Claude Opus 5 verifica su propio trabajo sin que se le indique, así que elimina las instrucciones explícitas de verificación o autocomprobación heredadas de prompts ajustados para modelos anteriores; dejarlas provoca sobreverificación. Para tareas acotadas, restringe explícitamente el alcance de la tarea. En frameworks multiagente, da orientación explícita sobre qué escenarios justifican la delegación o limita el número de subagentes, porque Claude Opus 5 delega con más facilidad que los modelos anteriores. Consulta Alcance de la tarea y sobreverificación y Control de la creación de subagentes.

Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-4-8 a claude-opus-5.
• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: se ejecutan con pensamiento en Claude Opus 5. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), o pasa thinking: {type: "disabled"} con esfuerzo high o inferior para conservar el comportamiento anterior. Si desactivas el pensamiento, revisa Ejecución con el pensamiento desactivado para conocer los artefactos de salida que pueden aparecer y sus mitigaciones mediante prompting.
• Actualiza el análisis de respuestas que lee el contenido por posición, como content[0].text o un manejador de stream que asume que el primer bloque de contenido es texto: con el pensamiento activado, los bloques thinking llegan antes de los bloques text. En su lugar, selecciona los bloques de contenido por type.
• Si ejecutas un bucle de uso de herramientas, devuelve los bloques thinking completos y sin modificar cuando devuelvas los resultados de herramientas; los bloques modificados devuelven un error 400. Consulta Preservación de los bloques de pensamiento.
• Verifica que cualquier código que analice el campo thinking lo trate únicamente como texto de visualización. thinking.display tiene como valor predeterminado "omitted" en Claude Opus 5, igual que en Claude Opus 4.8, por lo que los bloques de pensamiento llegan con un campo thinking vacío; establece display: "summarized" para recibir resúmenes legibles. Consulta Control de la visualización del pensamiento.
• Audita las solicitudes que desactivan el pensamiento: thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400, aplicado en cada solicitud. Vuelve a activar el pensamiento o reduce el esfuerzo a high o inferior.
• Reevalúa tu configuración de effort: ejecuta un nuevo barrido de esfuerzo en tus propias evaluaciones en lugar de heredar una configuración ajustada para un modelo anterior. Vale la pena probar los esfuerzos low y medium como controles de costo y latencia, y prueba el esfuerzo max donde la capacidad máxima importe más que el gasto de tokens. Si ejecutas con esfuerzo xhigh o max, eleva max_tokens a al menos 64k como punto de partida.
• Revisa los prompts cercanos al mínimo de caché: los prompts de 512 tokens o más ahora pueden crear entradas de caché, frente a los 1,024 tokens de Claude Opus 4.8.
• Maneja stop_reason: "refusal", y considera fallbacks: "default" (beta) para volver a ejecutar automáticamente las solicitudes rechazadas en un modelo de fallback recomendado.
• Si tu organización tiene un compromiso de Priority Tier, planifica la capacidad por separado: Priority Tier no es compatible con Claude Opus 5, mientras que Claude Opus 4.8 lo conserva.
• Para cargas de trabajo agénticas, considera los presupuestos de tareas (beta) y los cambios de herramientas a mitad de conversación (beta).
• Reajusta los prompts de longitud y verbosidad: las respuestas visibles predeterminadas y los entregables escritos son más largos en Claude Opus 5, y reducir el esfuerzo disminuye el volumen de pensamiento sin acortar de forma confiable la respuesta visible. Pide explícitamente concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad y Longitud de entregables escritos.
• Elimina las instrucciones de verificación y autocomprobación heredadas de prompts ajustados para modelos anteriores (provocan sobreverificación en Claude Opus 5), restringe explícitamente el alcance de la tarea para tareas acotadas y, en frameworks multiagente, orienta o limita la delegación a subagentes. Consulta Alcance de la tarea y sobreverificación y Control de la creación de subagentes.
• Vuelve a establecer la línea base de costo y latencia en tus propias cargas de trabajo. El precio por token no cambia respecto a Claude Opus 4.8, pero los tokens de pensamiento se facturan como tokens de salida, por lo que las cargas de trabajo que se ejecutaban sin pensamiento pueden producir más tokens de salida por solicitud.

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

Claude Opus 5 debería tener un rendimiento sólido desde el primer momento con los prompts y evaluaciones existentes de Claude Opus 4.7, al mismo precio de $5 USD por millón de tokens de entrada y $25 USD por millón de tokens de salida. Admite el mismo conjunto de funciones que Claude Opus 4.7, incluida la ventana de contexto de 1M de tokens, 128k tokens de salida máximos, pensamiento adaptativo, almacenamiento en caché de prompts, procesamiento por lotes, la Files API, soporte de PDF, visión y herramientas del lado del servidor y del lado del cliente, con dos excepciones: web fetch no está disponible en Claude Opus 5, y Priority Tier no es compatible con Claude Opus 5. También agrega mensajes de sistema a mitad de conversación y documenta públicamente los detalles de parada por rechazo. En la Claude API y Google Cloud, Claude Opus 5 también admite computer use como el conjunto de herramientas estable computer_toolset_20260801 y la herramienta browser use para tareas dentro de páginas web, ninguna de las cuales admite Claude Opus 4.7; las integraciones existentes en la versión anterior computer_20251124 siguen funcionando sin cambios en ambos modelos. Para actualizar una integración existente, consulta Migrar desde computer_20251124.

Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-7"  # Before
model = "claude-opus-5"  # After

Cambios incompatibles

1. Pensamiento activado por defecto: En Claude Opus 4.7, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Opus 5, las mismas solicitudes se ejecutan 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 en Claude Opus 4.7. Los tokens de pensamiento se facturan como tokens de salida incluso cuando el texto del pensamiento no se te devuelve, por lo que, aunque el precio por token no cambia, una carga de trabajo que se ejecutaba sin pensamiento en Claude Opus 4.7 puede producir más tokens de salida por solicitud en Claude Opus 5; consulta Control de costos. Para conservar el comportamiento anterior, pasa thinking: {type: "disabled"}, sujeto al límite de esfuerzo del siguiente punto; ten en cuenta que con el pensamiento desactivado el modelo puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible, así que prefiere niveles de esfuerzo más bajos con el pensamiento activado cuando puedas, y consulta Ejecución con el pensamiento desactivado para conocer mitigaciones cuando no puedas.

   La forma de la respuesta cambia con ello. Con el pensamiento activado, una respuesta puede comenzar con uno o más bloques thinking antes del primer bloque text, y como thinking.display tiene como valor predeterminado "omitted" en Claude Opus 5, esos bloques llegan con un campo thinking vacío junto a su signature. El código que lee la respuesta por posición, como content[0].text o un manejador de stream 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 eventos de stream. Para recibir resúmenes de pensamiento legibles en lugar de un campo thinking vacío, establece display: "summarized"; consulta Control de la visualización del pensamiento.

   Si ejecutas un bucle de uso de herramientas, devuelve a la API los bloques thinking de cada respuesta del asistente completos y sin modificar cuando devuelvas los 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 con un error 400 los bloques de pensamiento editados, reordenados o parcialmente eliminados. Consulta Preservación de los bloques de pensamiento.

2. Desactivar el pensamiento está limitado al esfuerzo high: Puedes desactivar el pensamiento con thinking: {type: "disabled"}, pero solo con un nivel de esfuerzo de high o inferior. Una solicitud que combine thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400. Claude Opus 4.7 acepta esta combinación, así que audita las solicitudes que desactivan el pensamiento antes de migrar.

   La verificación se aplica en cada solicitud: la configuración de esfuerzo y pensamiento de cada solicitud se valida de forma independiente, por lo que una solicitud que eleve el esfuerzo a xhigh o max mientras el pensamiento está desactivado se rechaza incluso si se aceptaron solicitudes anteriores en la conversación.

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

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

   

   Después (Claude Opus 5), elimina el campo thinking para ejecutar con pensamiento:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   o mantén el pensamiento desactivado y reduce el esfuerzo:

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

   

Qué cambió

Los siguientes puntos no son cambios incompatibles; describen diferencias de comportamiento que vale la pena verificar después de cambiar el ID del modelo.

1. Parámetros de muestreo (sin cambios): Establecer temperature, top_p o top_k en un valor no predeterminado devuelve un error 400 en Claude Opus 5, igual que en Claude Opus 4.7. La mayoría de los SDK aún definen estos campos por compatibilidad con modelos anteriores, por lo que el código que los establece pasa la verificación de tipos aunque la API rechace la solicitud. El SDK de Python (v1.0 y posteriores) no los define, y pasarlos genera un TypeError. Si eliminaste estos parámetros al migrar a Opus 4.7, no se necesitan más cambios.

2. El esfuerzo predeterminado es high: El valor predeterminado del parámetro effort en Claude Opus 5 es high en la Claude API y Claude Code. Si ya estableces el esfuerzo explícitamente, tu configuración no cambia.

3. Niveles de esfuerzo recalibrados: La asignación de tokens detrás de cada nivel de esfuerzo cambia en Claude Opus 5 en comparación con Claude Opus 4.7, y Claude Opus 5 admite el conjunto completo de niveles de esfuerzo (low, medium, high, xhigh, max). Ejecuta un nuevo barrido de esfuerzo en tus propias evaluaciones en lugar de heredar una configuración ajustada para Claude Opus 4.7. Vale la pena probar los esfuerzos low y medium como controles de costo y latencia, y prueba el esfuerzo max donde la capacidad máxima importe más que el gasto de tokens. 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í. Consulta Esfuerzo.

4. La ventana de contexto de 1M es la predeterminada: Claude Opus 5 ofrece la ventana de contexto completa de 1M de tokens por defecto, sin encabezado beta y sin recargo por contexto largo. Si tu cliente pasa un encabezado beta de ventana de contexto por compatibilidad con modelos más antiguos, puedes eliminarlo en Claude Opus 5.

5. Mensajes de sistema a mitad de conversación: Claude Opus 5 acepta mensajes role: "system" inmediatamente después de un turno de usuario en el array messages (sujeto a las reglas de ubicación). Usa el campo system de nivel superior para las instrucciones que 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 conservar los aciertos de la caché de prompts en turnos anteriores.

6. Detalles de parada por rechazo: El objeto stop_details en las respuestas de rechazo (disponible desde Claude Opus 4.7) ahora está documentado públicamente. Cuando el modelo rechaza una solicitud, identifica la categoría del rechazo, además del motivo de parada refusal existente. No se requiere encabezado beta y no hay opción de exclusión. Consulta Manejo de motivos de parada.

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

8. Modo rápido: Claude Opus 5 admite el modo rápido (vista previa de investigación); el modo rápido no está disponible en Claude Opus 4.7, donde las solicitudes con speed: "fast" devuelven un error. El parámetro speed: "fast" y el encabezado beta fast-mode-2026-02-01 funcionan sin cambios en Claude Opus 5.

Cambios recomendados

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

1. Considera los fallbacks automáticos: Claude Opus 5 se lanza con clasificadores de seguridad de ciberseguridad cuyos rechazos de categoría cibernética pueden recurrir a Claude Opus 4.8. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro fallbacks con el modo "default" (fallbacks: "default"), que selecciona un modelo de fallback recomendado según la categoría del rechazo en lugar de una lista de modelos mantenida manualmente. El fallback del lado del servidor está en beta; el modo "default" requiere el encabezado beta server-side-fallback-2026-07-01. Consulta Rechazos y fallback.

2. Cambia herramientas a mitad de conversación (beta): Puedes agregar o quitar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Envía el encabezado beta mid-conversation-tool-changes-2026-07-01. Esto es útil para cargas de trabajo agénticas que exponen herramientas progresivamente o las retiran a medida que avanza una tarea; sin él, una lista de herramientas modificada invalida el prefijo almacenado en caché.

3. Reajusta los prompts de longitud y verbosidad: Las respuestas visibles predeterminadas y los entregables escritos son más largos en Claude Opus 5 que en los modelos Opus anteriores, y reducir el esfuerzo disminuye el volumen de pensamiento sin acortar de forma confiable la respuesta visible. En su lugar, pide explícitamente concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad y Longitud de entregables escritos.

4. Elimina las instrucciones de verificación heredadas y restringe el alcance: Claude Opus 5 verifica su propio trabajo sin que se le indique, así que elimina las instrucciones explícitas de verificación o autocomprobación heredadas de prompts ajustados para modelos anteriores; dejarlas provoca sobreverificación. Para tareas acotadas, restringe explícitamente el alcance de la tarea. En frameworks multiagente, da orientación explícita sobre qué escenarios justifican la delegación o limita el número de subagentes, porque Claude Opus 5 delega con más facilidad que los modelos anteriores. Consulta Alcance de la tarea y sobreverificación y Control de la creación de subagentes.

Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-4-7 a claude-opus-5 (o actualiza los alias).
• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: se ejecutan con pensamiento en Claude Opus 5. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), o pasa thinking: {type: "disabled"} con esfuerzo high o inferior para conservar el comportamiento anterior. Si desactivas el pensamiento, revisa Ejecución con el pensamiento desactivado para conocer los artefactos de salida que pueden aparecer y sus mitigaciones mediante prompting.
• Actualiza el análisis de respuestas que lee el contenido por posición, como content[0].text o un manejador de stream que asume que el primer bloque de contenido es texto: con el pensamiento activado, los bloques thinking llegan antes de los bloques text. En su lugar, selecciona los bloques de contenido por type.
• Si ejecutas un bucle de uso de herramientas, devuelve los bloques thinking completos y sin modificar cuando devuelvas los resultados de herramientas; los bloques modificados devuelven un error 400. Consulta Preservación de los bloques de pensamiento.
• Verifica que cualquier código que analice el campo thinking lo trate únicamente como texto de visualización. thinking.display tiene como valor predeterminado "omitted" en Claude Opus 5, igual que en Claude Opus 4.7, por lo que los bloques de pensamiento llegan con un campo thinking vacío; establece display: "summarized" para recibir resúmenes legibles. Consulta Control de la visualización del pensamiento.
• Audita las solicitudes que desactivan el pensamiento: thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400, aplicado en cada solicitud. Vuelve a activar el pensamiento o reduce el esfuerzo a high o inferior.
• Si eliminaste los parámetros de muestreo durante la migración a Opus 4.7, no se necesita ninguna acción. Si los volviste a agregar con una ruta de reintento ante 400, elimina esa ruta de reintento.
• Reevalúa tu configuración de effort: ejecuta un nuevo barrido de esfuerzo en tus propias evaluaciones en lugar de heredar una configuración ajustada para Claude Opus 4.7. Prueba los esfuerzos low y medium como controles de costo y latencia, y el esfuerzo max donde la capacidad máxima importe más que el gasto de tokens. Si ejecutas con esfuerzo xhigh o max, eleva max_tokens a al menos 64k como punto de partida.
• Elimina cualquier encabezado beta de ventana de contexto. La ventana de contexto de 1M es la predeterminada en la Claude API, Amazon Bedrock, Google Cloud y Microsoft Foundry.
• Si reconstruyes el historial de la conversación para actualizar instrucciones, considera cambiar a un mensaje de sistema a mitad de conversación para conservar los aciertos de la caché de prompts.
• Verifica que tu manejo de motivos de parada lea stop_details en los rechazos (disponible desde Claude Opus 4.7; ahora documentado públicamente), y considera fallbacks: "default" (beta) para volver a ejecutar automáticamente las solicitudes rechazadas en un modelo de fallback recomendado.
• Revisa los prompts cercanos al mínimo de caché: los prompts de 512 tokens o más ahora pueden crear entradas de caché.
• Si usas web fetch, planifica una alternativa: no está disponible en Claude Opus 5.
• Si tu organización tiene un compromiso de Priority Tier, ten en cuenta que Priority Tier no es compatible con Claude Opus 5.
• Si usabas el modo rápido en Claude Opus 4.7, no se necesitan cambios en las solicitudes más allá del ID del modelo: speed: "fast" y el encabezado beta fast-mode-2026-02-01 funcionan sin cambios en Claude Opus 5.
• Para cargas de trabajo agénticas, considera los presupuestos de tareas (beta) y los cambios de herramientas a mitad de conversación (beta).
• Reajusta los prompts de longitud y verbosidad, y elimina las instrucciones de verificación y autocomprobación heredadas de prompts ajustados para modelos anteriores.
• Vuelve a establecer la línea base de costo y latencia en el nivel de esfuerzo que elijas. El precio por token no cambia respecto a Claude Opus 4.7, pero los tokens de pensamiento se facturan como tokens de salida, por lo que las cargas de trabajo que se ejecutaban sin pensamiento pueden producir más tokens de salida por solicitud.

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

Claude Opus 5 debería tener un rendimiento sólido desde el primer momento con los prompts y evaluaciones existentes de Claude Opus 4.6 al mismo precio, pero hay un puñado de cambios de comportamiento y de API que vale la pena conocer al migrar. La mayoría de estos cambios entraron en vigor en Claude Opus 4.7; dos más, el pensamiento activado por defecto y un límite de esfuerzo para desactivar el pensamiento, entran en vigor en Claude Opus 5. Todos ellos se cubren en esta sección, por lo que es completa para el código que viene directamente de Claude Opus 4.6. Claude Opus 5 admite el mismo conjunto de funciones que Claude Opus 4.6, incluidas:

• Ventana de contexto de 1M de tokens al precio estándar de la API sin recargo por contexto largo
• 128k tokens de salida máximos
• Pensamiento adaptativo
• Almacenamiento en caché de prompts
• Procesamiento por lotes
• Files API
• Soporte de PDF
• Visión
• Herramientas del lado del servidor y del lado del cliente (bash, ejecución de código, computer use, editor de texto, búsqueda web, conector MCP, memoria)

Dos excepciones: web fetch no está disponible en Claude Opus 5, y Priority Tier no es compatible con Claude Opus 5. En la Claude API y Google Cloud, Claude Opus 5 también admite computer use como el conjunto de herramientas estable computer_toolset_20260801 y la herramienta browser use para tareas dentro de páginas web, ninguna de las cuales admiten Claude Opus 4.6 ni los modelos Opus anteriores; las integraciones existentes en la versión anterior computer_20251124 siguen funcionando sin cambios en Claude Opus 5. Para actualizar una integración existente, consulta Migrar desde computer_20251124.

Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After

Cambios incompatibles

1. Pensamiento extendido eliminado: thinking: {type: "enabled", budget_tokens: N} ya no es compatible con Claude Opus 4.7 ni con 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, el pensamiento adaptativo está activado de forma predeterminada: thinking: {type: "adaptive"} es válido y equivalente a omitir por completo el campo thinking (consulta el siguiente punto).

   Antes (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   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):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-opus-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 dirigir mediante prompts y el parámetro effort; consulta Elegir un nivel de esfuerzo.

2. Pensamiento activado de forma predeterminada: En Claude Opus 4.6 y Claude Opus 4.7, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Opus 5, las mismas solicitudes se ejecutan 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, aunque el precio por token no cambia, una carga de trabajo que se ejecutaba sin pensamiento puede producir más tokens de salida por solicitud en Claude Opus 5; consulta Control de costos. Para conservar el comportamiento anterior, pasa thinking: {type: "disabled"}, sujeto al límite de esfuerzo del siguiente punto; ten en cuenta que, con el pensamiento desactivado, el modelo puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible, así que prefiere niveles de esfuerzo más bajos con el pensamiento activado cuando puedas, y consulta Ejecutar con el pensamiento desactivado para ver mitigaciones cuando no puedas.

   La forma de la respuesta cambia junto con esto. Con el pensamiento activado, una respuesta puede comenzar con uno o más bloques thinking antes del primer bloque text, y como el contenido del pensamiento se omite de forma predeterminada en Claude Opus 5 (punto 5 de esta lista), esos bloques llegan con un campo thinking vacío junto con su signature. El código que lee la respuesta por posición, como content[0].text o un manejador de stream 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 sea "text", y ramifica según el tipo de bloque al manejar eventos de stream.

   Si ejecutas un bucle de 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 parcialmente eliminados. Consulta Preservar los bloques de pensamiento.

3. Desactivar el pensamiento está limitado al esfuerzo high: Puedes desactivar el pensamiento con thinking: {type: "disabled"}, pero solo con un nivel de esfuerzo de high o inferior. Una solicitud que combine thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400 en Claude Opus 5, lo cual se aplica en cada solicitud. Audita las solicitudes que desactivan el pensamiento antes de migrar: vuelve a activar el pensamiento o reduce el esfuerzo a high o inferior.

4. Parámetros de muestreo eliminados: Establecer temperature, top_p o top_k en cualquier valor no predeterminado en Claude Opus 4.7 o modelos posteriores, incluido Claude Opus 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 de las solicitudes. El uso de prompts es la forma recomendada de guiar el comportamiento del modelo en Claude Opus 5. Si usabas temperature = 0 para obtener determinismo, ten en cuenta que nunca garantizó salidas idénticas en modelos anteriores.

5. Contenido del pensamiento omitido de forma predeterminada: Los bloques de pensamiento siguen apareciendo en el stream 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 valor predeterminado era devolver texto de pensamiento resumido. Para restaurar el contenido de pensamiento resumido, establece thinking.display en "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   

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

   El valor predeterminado es "omitted" en Claude Opus 4.7 y modelos posteriores. Si tu producto transmite el razonamiento a los usuarios mediante streaming, el nuevo valor predeterminado se manifiesta 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 para más detalles.

6. Conteo de tokens actualizado: Claude Opus 4.7 introdujo un nuevo tokenizador, que los modelos Opus posteriores, incluido Claude Opus 5, también usan. Contribuye a un mejor rendimiento en una amplia gama de tareas, y puede usar aproximadamente entre 1x y 1.35x la cantidad de 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 diferente para Claude Opus 5 que el que devolvía para Claude Opus 4.6. La eficiencia de tokens puede variar según la forma de la carga de trabajo.

   Las intervenciones mediante prompts, task_budget y effort pueden ayudar a controlar los costos y garantizar un uso adecuado de tokens. Estos controles pueden implicar una compensación con la inteligencia del modelo. Actualiza tus parámetros max_tokens para dar margen adicional, incluidos los disparadores de compactación. Claude Opus 5 ofrece una ventana de contexto de 1M al precio estándar de la API sin recargo por contexto largo.

7. Eliminación del prefill (heredado de Opus 4.6): Rellenar previamente los mensajes del asistente devuelve un error 400 en Claude Opus 4.7 y modelos posteriores, incluido Claude Opus 5. Usa en su lugar salidas estructuradas, instrucciones en la indicación del sistema o output_config.format.

Elegir un nivel de esfuerzo

El parámetro effort te permite ajustar la inteligencia de Claude frente al gasto de tokens, intercambiando capacidad por mayor velocidad y menores costos. Claude Opus 5 admite el conjunto completo de niveles de esfuerzo y usa high de forma predeterminada. Ejecuta un nuevo barrido de esfuerzo en tus propias evaluaciones en lugar de heredar una configuración ajustada para un modelo anterior:

• max: Puede ofrecer mejoras en las tareas más exigentes, pero puede mostrar rendimientos decrecientes por el mayor uso de tokens y puede ser propenso a pensar en exceso en las más simples. Pruébalo donde la capacidad máxima importe más que el gasto de tokens.
• xhigh: Capacidad extendida para trabajo agéntico y de programación de larga duración que necesita más profundidad que el valor predeterminado.
• high: El valor predeterminado. Equilibra el uso de tokens y la inteligencia para la mayoría de las tareas.
• medium: Un escalón por debajo del valor predeterminado para ahorrar costos; vale la pena probarlo como control de costos y latencia.
• low: El más eficiente. Resérvalo para tareas cortas y acotadas y para cargas de trabajo sensibles a la latencia.

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í. El esfuerzo es más importante para este modelo que para cualquier Opus anterior. Experimenta activamente con él cuando actualices.

Cambios de comportamiento

Claude Opus 4.7 introdujo varias diferencias de comportamiento respecto a Claude Opus 4.6 que no son cambios incompatibles de la API, pero que pueden requerir actualizaciones de prompts o la eliminación de andamiaje. Se mantienen en Claude Opus 5, con los ajustes indicados en esta lista.

1. La longitud de la respuesta varía según el caso de uso: Claude Opus 4.7 calibra la longitud de la respuesta según lo compleja que juzgue la tarea, en lugar de usar una verbosidad fija de forma predeterminada. Esto normalmente significa respuestas más cortas en consultas simples y mucho más largas en análisis abiertos.

   Si tu producto depende de un cierto estilo o verbosidad de salida, es posible que necesites ajustar tus prompts. Por ejemplo, para reducir la verbosidad, agrega: "Proporciona respuestas concisas y enfocadas. Omite el contexto no esencial y mantén los ejemplos al mínimo." Si observas tipos específicos de sobreexplicación, agrega instrucciones dirigidas en tu prompt para evitarlos.

   Los ejemplos positivos que muestran cómo Claude puede comunicarse con el nivel adecuado de concisión tienden a ser más efectivos que los ejemplos negativos o las instrucciones que le dicen al modelo qué no hacer. En Claude Opus 5, las respuestas visibles predeterminadas y los entregables escritos son más largos que en los modelos Opus anteriores, y reducir el esfuerzo disminuye el volumen de pensamiento sin acortar de forma confiable la respuesta visible; indica explícitamente en el prompt la concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad.

2. Seguimiento de instrucciones más literal: Claude Opus 4.7 interpreta los prompts de forma más literal y explícita que Claude Opus 4.6, particularmente en niveles de esfuerzo más bajos. No generaliza silenciosamente una instrucción de un elemento a otro, y no infiere solicitudes que no hiciste. La ventaja de esta literalidad es la precisión y menos vaivenes. Generalmente funciona mejor para casos de uso de la API con prompts cuidadosamente ajustados, extracción estructurada y pipelines donde quieres un comportamiento predecible. Una revisión de prompts y del harness puede ser especialmente útil para la migración a Claude Opus 5.

3. Tono más directo: Como con cualquier modelo nuevo, el estilo de prosa en la escritura de formato largo puede cambiar. Claude Opus 4.7 es más directo y tiene opiniones más marcadas, con menos frases orientadas a la validación y menos emojis que el estilo más cálido de Claude Opus 4.6. Si tu producto depende de una voz específica, vuelve a evaluar los prompts de estilo frente a la nueva línea base.

4. 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 agregaste andamiaje para forzar mensajes de estado intermedios ("Después de cada 3 llamadas a herramientas, resume el progreso"), prueba a eliminarlo. Si encuentras que la longitud o el contenido de las actualizaciones de Claude Opus 4.7 dirigidas al usuario no están bien calibrados para tu caso de uso, describe explícitamente en el prompt cómo deberían ser estas actualizaciones y proporciona ejemplos.

5. Cambios en la creación de subagentes: Claude Opus 4.7 tiende a crear menos subagentes de forma predeterminada que Claude Opus 4.6, mientras que Claude Opus 5 delega en subagentes con más facilidad que los modelos anteriores. El comportamiento se puede dirigir mediante prompts en cualquier dirección; da orientación explícita sobre cuándo son deseables los subagentes, o limita el número de subagentes. Consulta Controlar la creación de subagentes.

6. Calibración de esfuerzo más estricta: Con un cambio significativo respecto a Claude Opus 4.6, Claude Opus 4.7 respeta estrictamente los niveles de esfuerzo, especialmente en el extremo bajo. En low y medium, el modelo acota su trabajo a lo que se pidió en lugar de hacer más de lo solicitado.

   Esto es bueno para la latencia y el costo, pero en tareas moderadamente complejas ejecutadas con esfuerzo low existe cierto riesgo de pensar de menos. Si observas razonamiento superficial en problemas complejos, sube el esfuerzo a high o xhigh en lugar de intentar compensarlo con prompts.

   Si necesitas mantener el esfuerzo en low por latencia, agrega orientación dirigida: "Esta tarea implica razonamiento de varios pasos. Piensa cuidadosamente en el problema antes de responder." Consulta Niveles de esfuerzo recomendados para Claude Opus 4.7.

7. Menos llamadas a herramientas de forma predeterminada: Claude Opus 4.7 tiende a usar herramientas con menos frecuencia que Claude Opus 4.6 y a usar más el razonamiento. Esto produce mejores resultados en la mayoría de los casos.

   Para aumentar el uso de herramientas, sube la configuración de esfuerzo. Las configuraciones de esfuerzo high o xhigh muestran sustancialmente más uso de herramientas en búsqueda agéntica y programación. También puedes ajustar tu prompt para instruir explícitamente al modelo sobre cuándo y cómo usar correctamente sus herramientas.

8. Salvaguardas de ciberseguridad en tiempo real: Recién agregadas 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 el ingreso al Cyber Verification Program para pedir restricciones reducidas. La vía de solicitud depende de cómo accedes a Claude.

9. Compatibilidad con imágenes de alta resolución: Claude Opus 4.7 es el primer modelo Claude con compatibilidad 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 los 1,568 píxeles de los modelos anteriores. Esto desbloquea mejoras en cargas de trabajo con uso intensivo de visión y es particularmente 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 habilitación del lado del cliente. Dos cosas a planificar:

   • Las imágenes a resolución completa pueden usar hasta aproximadamente 3x 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 por imagen). 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 devueltas por 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 más detalles.

Cambios recomendados

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

1. Vuelve a evaluar max_tokens: Dado que el mismo texto produce un conteo de tokens más alto en Claude Opus 4.7 y modelos posteriores, actualiza tus parámetros max_tokens para dar margen adicional, incluidos los disparadores de compactación. Las intervenciones mediante prompts, task_budget y effort pueden ayudar a controlar los costos y garantizar un uso adecuado de tokens.

2. Audita las expectativas de conteo de tokens: Cualquier ruta de código que estime tokens del lado del cliente o asuma una proporción fija de tokens por carácter debe volver a probarse con Claude Opus 5. Usa el endpoint de conteo de tokens para verificar.

3. Adopta los presupuestos de tarea (beta): Claude Opus 4.7 introduce los presupuestos de tarea. Estos presupuestos te permiten informar a Claude cuántos tokens tiene para un bucle agéntico completo, incluidos el pensamiento, las llamadas a herramientas, los resultados de herramientas y la salida final. El modelo ve una cuenta regresiva en curso y la usa para priorizar el trabajo y terminar la tarea de forma ordenada a medida que se consume el presupuesto. Para usarlo, establece el encabezado beta task-budgets-2026-03-13 y agrega lo siguiente a tu configuración de salida:

   PythonTypeScriptC#GoJavaPHPRuby

   

   output_config = {
       "effort": "high",
       "task_budget": {"type": "tokens", "total": 128000},
   }

   Es posible que necesites experimentar con diferentes presupuestos de tarea para tu caso de uso. Si al modelo se le da un presupuesto de tarea demasiado restrictivo, puede completar la tarea de forma menos exhaustiva, haciendo referencia a su presupuesto como la restricción.

   Para tareas agénticas abiertas donde la calidad importa más que la velocidad, no establezcas un presupuesto de tarea. Reserva los presupuestos de tarea para cargas de trabajo donde necesites que el modelo acote su trabajo a una asignación de tokens. El valor mínimo para un presupuesto de tarea es de 20k tokens.

   Un presupuesto de tarea no es un límite estricto; es una sugerencia de la que el modelo es consciente. Se diferencia de max_tokens:

   • task_budget: un límite orientativo a lo largo de todo el bucle agéntico. El modelo lo ve y lo usa para regular su ritmo.
   • max_tokens: un techo estricto por solicitud sobre los tokens generados. No se pasa al modelo, por lo que el modelo no es consciente de él.

   Usa task_budget cuando quieras que el modelo se automodere, y max_tokens como techo estricto para limitar el uso.

4. Establece un max_tokens grande con esfuerzo max o xhigh: Si ejecutas Claude Opus 4.7 o un modelo posterior con esfuerzo max o xhigh, establece un presupuesto grande de tokens de salida máximos para que el modelo tenga espacio para pensar y actuar a través de sus subagentes y llamadas a herramientas. Comienza con 64k tokens y ajusta a partir de ahí.

5. Reduce la resolución de las imágenes si la alta resolución es innecesaria: Claude Opus 4.7 y los modelos posteriores admiten imágenes de hasta 2576px / 3.75MP. Las imágenes de alta resolución usan más tokens. Si la fidelidad de imagen adicional es innecesaria, reduce la resolución de las imágenes antes de enviarlas a Claude para evitar aumentos en el uso de tokens. Consulta Imágenes y visión.

6. Considera los fallbacks automáticos: Claude Opus 5 se lanza con clasificadores de seguridad de ciberseguridad cuyos rechazos de categoría cibernética pueden recurrir a Claude Opus 4.8 como fallback. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro fallbacks con el modo "default" (fallbacks: "default"), que selecciona un modelo de fallback recomendado según la categoría del rechazo en lugar de una lista de modelos mantenida manualmente. El fallback del lado del servidor está en beta; el modo "default" requiere el encabezado beta server-side-fallback-2026-07-01. Consulta Rechazos y fallback.

7. Almacena en caché prompts más cortos: La longitud mínima de prompt almacenable en caché en Claude Opus 5 es de 512 tokens, menor que en los modelos Opus anteriores. Los prompts que eran demasiado cortos para almacenarse en caché 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.

8. Cambia herramientas a mitad de conversación (beta): Puedes agregar o quitar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Envía el encabezado beta mid-conversation-tool-changes-2026-07-01. Esto es útil para cargas de trabajo agénticas que exponen herramientas progresivamente o las retiran a medida que avanza una tarea; sin él, una lista de herramientas modificada invalida el prefijo almacenado en caché.

9. Elimina las instrucciones de verificación heredadas y restringe el alcance: Claude Opus 5 verifica su propio trabajo sin que se le indique, así que elimina las instrucciones explícitas de verificación o autocomprobación heredadas de prompts ajustados para modelos anteriores; dejarlas provoca sobreverificación. Para tareas acotadas, restringe explícitamente el alcance de la tarea. Consulta Alcance de la tarea y sobreverificación.

Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-4-6 a claude-opus-5 (o actualiza los alias).
• Elimina temperature, top_p y top_k de las cargas 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 está activado de forma predeterminada en Claude Opus 5.
• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: se ejecutan con pensamiento en Claude Opus 5. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), o pasa thinking: {type: "disabled"} con esfuerzo high o inferior para conservar el comportamiento anterior.
• Actualiza el análisis de respuestas que lee el contenido por posición, como content[0].text o un manejador de stream que asume que el primer bloque de contenido es texto: con el pensamiento activado, los bloques thinking llegan antes que los bloques text. En su lugar, selecciona los bloques de contenido por type.
• Si ejecutas un bucle de uso de herramientas, devuelve los bloques thinking completos y sin modificar cuando devuelvas los resultados de las herramientas; los bloques modificados devuelven un error 400. Consulta Preservar los bloques de pensamiento.
• Audita las solicitudes que desactivan el pensamiento: thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400, lo cual se aplica en cada solicitud. Vuelve a activar el pensamiento o reduce el esfuerzo a high o inferior.
• Elimina cualquier prefill de mensajes del asistente.
• Si tu interfaz muestra contenido de pensamiento, habilita explícitamente el resumen del pensamiento.
• Vuelve a medir el costo y la latencia de extremo a extremo con la tokenización actualizada; los tokens de pensamiento se facturan como tokens de salida, por lo que las cargas de trabajo que se ejecutaban sin pensamiento también pueden producir más tokens de salida por solicitud.
• Vuelve a ajustar max_tokens para tener en cuenta la tokenización actualizada.
• 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 3x más tokens de imagen por imagen a resolución completa). Reduce la resolución antes de enviarlas 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 prompts en función de los cambios de comportamiento (longitud de respuesta, literalidad, tono, actualizaciones de progreso, subagentes, calibración de esfuerzo, activación de herramientas, salvaguardas cibernéticas, manejo de imágenes de alta resolución).
• Vuelve a establecer la línea base de la longitud de respuesta con los prompts de control de longitud existentes eliminados, y luego ajusta explícitamente.
• Si usas esfuerzo xhigh o max, sube max_tokens a al menos 64k como punto de partida.
• Considera adoptar los presupuestos de tarea (beta) y los cambios de herramientas a mitad de conversación (beta) para flujos de trabajo agénticos.
• Maneja stop_reason: "refusal", y considera fallbacks: "default" (beta) para volver a ejecutar automáticamente las solicitudes rechazadas en un modelo de fallback recomendado.
• Revisa los prompts cercanos al mínimo de caché: los prompts de 512 tokens o más ahora pueden crear entradas de caché en Claude Opus 5.
• Si usas web fetch, planifica una alternativa: no está disponible en Claude Opus 5.
• Si tu organización tiene un compromiso de Priority Tier, ten en cuenta que Priority Tier no es compatible con Claude Opus 5.
• Elimina las instrucciones de verificación y autocomprobación heredadas de prompts ajustados para modelos anteriores; provocan sobreverificación en Claude Opus 5.
• Si tu producto realiza trabajo de seguridad legítimo, solicita el ingreso al Cyber Verification Program para acceder a restricciones más bajas sobre contenido cibernético.

Migrar desde Claude Opus 4.5 o anterior

Si estás migrando desde Claude Opus 4.5, Opus 4.1 o un modelo anterior directamente a Claude Opus 5, aplica todos los cambios anteriores de esta sección más los siguientes cambios acumulativos, que entraron en vigor entre Opus 4.5 y Opus 4.7. Si estás migrando desde Opus 4.6, los cambios anteriores de esta sección son todo lo que necesitas.

Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

Cambios incompatibles

1. La eliminación del prefill se cubre en los cambios incompatibles para 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

Estos cambios mejoran tu experiencia en Claude Opus 4.7 y modelos posteriores. Los elementos marcados como (obligatorio en Opus 4.7) eran recomendaciones opcionales cuando se lanzó Opus 4.6, pero ahora son obligatorios; el resto siguen siendo recomendados.

1. Migra al pensamiento adaptativo (obligatorio en Opus 4.7): thinking: {type: "enabled", budget_tokens: N} devuelve un error 400 en Claude Opus 4.7 y modelos posteriores. Cambia a thinking: {type: "adaptive"} y usa el parámetro effort para controlar la profundidad del pensamiento; en Claude Opus 5, thinking: {type: "adaptive"} es equivalente a omitir el campo thinking, lo que se ejecuta con pensamiento adaptativo de forma predeterminada. Consulta Pensamiento.

   cURLBeforeAfterCLITypeScriptC#GoJavaPHPRuby

   

   response = client.beta.messages.create(
       model="claude-opus-4-5",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       betas=["interleaved-thinking-2025-05-14"],
       messages=[{"role": "user", "content": "Your prompt here"}],
   )

   Ten en cuenta que 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 betas=["effort-2025-11-24"] de tus solicitudes.

3. Elimina el encabezado beta de streaming de herramientas de grano fino: El streaming de herramientas de grano fino no requiere un encabezado beta. Elimina betas=["fine-grained-tool-streaming-2025-05-14"] de tus solicitudes.

4. Elimina el encabezado beta de pensamiento intercalado: El pensamiento adaptativo habilita automáticamente el pensamiento intercalado en Claude Opus 4.7, Opus 4.6 y Sonnet 4.6. Elimina betas=["interleaved-thinking-2025-05-14"] de tus solicitudes. El encabezado sigue funcionando en Sonnet 4.6 con pensamiento extendido manual, pero el modo manual está obsoleto.

5. Migra a output_config.format: Si usas salidas estructuradas, actualiza output_format={...} a output_config={"format": {...}}. La API todavía acepta el parámetro obsoleto output_format, pero se eliminará en un futuro lanzamiento de modelo. 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 Opus 4.1 o modelos anteriores directamente a Claude Opus 5, aplica todos los cambios anteriores de esta sección, más los cambios adicionales de esta subsección.

# Desde Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# Desde Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

Cambios incompatibles adicionales

1. Elimina los parámetros de muestreo

   A partir de Claude Opus 4.7, establecer temperature, top_p o top_k en cualquier valor no predeterminado 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 solicitudes y usar prompts para guiar el comportamiento del modelo. Si usabas temperature = 0 para obtener determinismo, ten en cuenta que nunca garantizó salidas idénticas.

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Antes - Esto generará un error en los modelos Claude 4+
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # Non-default sampling params return 400 on Opus 4.7
       # ...
   )
   
   # Después
   response = client.messages.create(
       model="claude-opus-5",
       # ...
   )

2. Actualiza las versiones de las herramientas

   Actualiza a las versiones más recientes de las herramientas. Elimina cualquier código que use el comando undo_edit.

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 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 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.

3. Maneja el motivo de detención refusal

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

   PythonTypeScriptC#GoJavaPHPRuby

   

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

4. Maneja el motivo de detención model_context_window_exceeded

   Los modelos Claude 4.5+ 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:

   PythonTypeScriptC#GoJavaPHPRuby

   

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

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

   Los modelos Claude 4.5+ 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 una 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+ tienen un estilo de comunicación más conciso y directo y requieren indicaciones 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+ tienen uso de herramientas eficiente en tokens integrado y estos encabezados no tienen ningún efecto.

Lista de verificación de migración (desde Claude Opus 4.5 o anterior)

• Actualiza el ID del modelo a claude-opus-5
• Aplica todos los cambios incompatibles para migrar desde Claude Opus 4.6 (pensamiento extendido eliminado, pensamiento activado por defecto, límite de esfuerzo al deshabilitar el pensamiento, parámetros de muestreo eliminados, visualización del pensamiento omitida por defecto, tokenización actualizada)
• INCOMPATIBLE: Elimina los prefills de mensajes del asistente (devuelve un error 400); usa salidas estructuradas o output_config.format en su lugar
• INCOMPATIBLE en Opus 4.7: Reemplaza thinking: {type: "enabled", budget_tokens: N} por thinking: {type: "adaptive"} más el parámetro effort (devuelve 400 en Opus 4.7)
• Verifica que el análisis del JSON de las llamadas a herramientas use un analizador JSON estándar
• 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 aplica)
• Si migras desde Claude 4.1 o anterior: elimina temperature, top_p y top_k (los valores no predeterminados devuelven 400 en Opus 4.7)
• Si migras desde Claude 4.1 o anterior: actualiza las versiones de las herramientas (text_editor_20250728, code_execution_20260521)
• Si migras desde Claude 4.1 o anterior: maneja el motivo de detención refusal
• Si migras desde Claude 4.1 o anterior: maneja el motivo de detención model_context_window_exceeded
• Si migras desde Claude 4.1 o anterior: verifica el manejo de los parámetros de cadena de las herramientas en cuanto a saltos de línea finales
• Si migras desde Claude 4.1 o anterior: 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
• Prueba en un entorno de desarrollo antes del despliegue en producción

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

Claude Opus 5 y Claude Sonnet 5 comparten la misma superficie de API: ambos se ejecutan con pensamiento adaptativo activado por defecto, ambos establecen por defecto el parámetro effort en high en la Claude API y Claude Code, ambos ofrecen una ventana de contexto de 1M de tokens por defecto con 128k tokens máximos de salida, y ninguno admite Priority Tier. El pensamiento extendido manual y los parámetros de muestreo no predeterminados devuelven un error 400 en ambos modelos, al igual que el prefill del asistente.

Actualiza el nombre de tu modelo

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

Qué cambió

1. Precios: Claude Opus 5 tiene un precio de $5 USD por millón de tokens de entrada y $25 USD por millón de tokens de salida. Claude Sonnet 5 tiene un precio de $2/$10 USD por millón de tokens de entrada/salida. Consulta los precios de Claude para ver los precios completos.

2. Deshabilitar el pensamiento está limitado al esfuerzo high: En Claude Sonnet 5, thinking: {type: "disabled"} se acepta en cualquier nivel de esfuerzo. En Claude Opus 5, solo se acepta con un nivel de esfuerzo de high o inferior; una solicitud que combine thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400, lo cual se aplica en cada solicitud. Audita las solicitudes que deshabilitan el pensamiento antes de migrar.

3. Mensajes del sistema a mitad de conversación: Claude Opus 5 acepta mensajes con 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 las instrucciones, puedes simplificarlas y conservar los aciertos del almacenamiento en caché de prompts en turnos anteriores.

4. Web fetch no está disponible: La herramienta web fetch está disponible en Claude Sonnet 5 pero no en Claude Opus 5.

Lista de verificación de migración

• Actualiza el nombre del modelo de claude-sonnet-5 a claude-opus-5.
• Audita las solicitudes que deshabilitan el pensamiento: thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400 en Claude Opus 5. Vuelve a habilitar el pensamiento o reduce el esfuerzo a high o inferior.
• Si usas web fetch, planifica una alternativa: no está disponible en Claude Opus 5.
• Vuelve a ejecutar el conteo de tokens contra Claude Opus 5 en lugar de reutilizar los conteos medidos contra Claude Sonnet 5, y vuelve a establecer la línea base de costo y latencia en tus propias cargas de trabajo; el precio por token difiere.