Anthropic Python SDK 1.0: migrar a mano o con Claude Code

Pasar un proyecto de Python de anthropic 0.x a 1.0 requiere un solo comando de instalación, pip install --upgrade "anthropic>=1,<2", y después una pasada por una lista fija de cambios incompatibles: la capa HTTP ahora corre sobre httpx2, los lectores asíncronos de .with_raw_response se convirtieron en corrutinas, Text Completions y los parámetros temperature/top_p/top_k desaparecieron, y AnthropicBedrock se niega a construirse sin una región.¹ Recorre esa lista a mano con la guía oficial de migración, o deja que Claude Code haga las ediciones con /claude-api upgrade python y revisa el diff.¹³ La nota de versión de Claude Code lo llama /claude-api upgrade; la guía de migración añade el argumento python, que es la forma que debes escribir.¹³ Ambas rutas terminan en el mismo lugar – la página que sigue cubre cada una, vigente a la fecha de anthropic 1.0.0 (publicado en PyPI el 20 de agosto de 2026; comprobado el 25 de agosto).² {.answer-block}

TL;DR

• Actualiza con pip install --upgrade "anthropic>=1,<2" y luego ejecuta pyright o mypy: la guía de migración señala que un verificador de tipos detecta casi todos los cambios incompatibles, lo que la convierte en una lista de verificación ya hecha.¹
• Python 3.10 es el nuevo mínimo. Nada más cambia en tu entorno; el SDK sigue siendo compatible con Pydantic v1 y v2.¹
• httpx pasó a ser httpx2. Los valores simples como timeout=30.0 siguen funcionando; los objetos httpx que le entregas al cliente deben venir de httpx2, y las bibliotecas que parchean httpx quedan ciegas hasta que llamas a httpx2.alias_httpx().¹
• Eliminados: Text Completions, los parámetros de muestreo y los diccionarios de esquema en output_format. client.completions.create(), temperature, top_p y top_k desaparecieron; los diccionarios de esquema pasan a output_config={"format": {...}}.¹
• Claude Code v2.1.239 (21 de agosto de 2026) añadió /claude-api upgrade para migrar proyectos de Python de anthropic 0.x a 1.x.³ Trata su salida como cualquier migración automatizada: lee el diff antes de confirmarlo.

¿Qué se rompe al actualizar a anthropic 1.0?

Seis cambios cargan con la mayor parte del peso; condenso la referencia rápida de la guía a esos seis, y las eliminaciones menores vienen después.¹ El más grande tiene una razón sencilla: la capa HTTP del SDK pasó de httpx, que ya no recibe mantenimiento activo, a httpx2, un fork compatible en API mantenido por el equipo de Pydantic, con las mismas clases, el mismo comportamiento y correcciones de seguridad incluidas.¹

Las eliminaciones menores y un cambio de comportamiento vienen en el mismo paquete, cada uno con su reemplazo:¹

La última fila muerde en silencio: default_headers={"USER-AGENT": "my-app/1.0"} ahora reemplaza el User-Agent propio del SDK en lugar de enviar ambos.¹

¿Cómo migro a mano?

Tres pasos, en orden: actualiza, deja que el verificador de tipos encuentre lo que se rompió y luego corrige por categoría.

pip install --upgrade "anthropic>=1,<2"
pyright   # or mypy

Corrige primero las importaciones de httpx, porque son las que fallan más ruidosamente. Las reexportaciones propias del SDK (anthropic.Timeout, anthropic.DefaultHttpxClient, anthropic.DefaultAsyncHttpxClient, anthropic.DefaultAioHttpClient) ya apuntan a httpx2 y siguen funcionando; solo los objetos que construyes directamente desde httpx necesitan el alias.¹

# Before
import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# After
import httpx2 as httpx  # or `import httpx2` and rename the references
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Si otro código de la aplicación sigue importando httpx y comparte clientes o tipos de excepción con el SDK, o si usas el HTTPXClientInstrumentor de OpenTelemetry, la integración de httpx de Sentry, respx, pytest-httpx o vcrpy, llama a httpx2.alias_httpx() una sola vez al inicio de tu punto de entrada. Debe ejecutarse antes de que cualquier cosa importe httpx (de lo contrario lanza RuntimeError), y la guía lo reserva para aplicaciones: una biblioteca nunca debería llamarlo en nombre de sus usuarios.¹ Bajo pytest, la opción menos intrusiva que propone la guía es un plugin temprano, un módulo tests/_alias_httpx.py que llama a httpx2.alias_httpx(), registrado en pyproject.toml para que cargue antes que respx, pytest-httpx y tus módulos de prueba:¹

# tests/_alias_httpx.py
import httpx2

httpx2.alias_httpx()  # makes `import httpx` / `import httpcore` resolve to httpx2 / httpcore2

# pyproject.toml
[tool.pytest.ini_options]
addopts = "-p tests._alias_httpx"
pythonpath = ["."]

Los objetos de respuesta y de error ahora son tipos de httpx2. El cambio de paquete aplica a lo que el SDK devuelve, no solo a lo que le pasas. APIStatusError.response, APIConnectionError.request, response.http_response / .headers / .url en las respuestas crudas y el argumento response= que reciben los event hooks de tu http_client personalizado son todos objetos httpx2. Conservan exactamente los mismos atributos que antes, así que solo las comprobaciones isinstance y las anotaciones de tipo que nombran httpx.Response / httpx.Request / httpx.Headers necesitan cambiar a httpx2.¹ El caso de isinstance merece una segunda mirada. La guía dice únicamente que esas comprobaciones deben cambiar;¹ la razón por la que importan es que, a menos que httpx2.alias_httpx() haya hecho que httpx resuelva a httpx2, una comprobación como isinstance(err.response, httpx.Response) contra el paquete antiguo devuelve False sin lanzar nada, y el manejador se salta su rama.

# Before
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx.Response = err.response
    print(response.status_code, response.headers.get("request-id"))


# After
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx2.Response = err.response
    print(response.status_code, response.headers.get("request-id"))

Luego los lectores de respuestas crudas. .with_raw_response antes devolvía LegacyAPIResponse para ambos clientes; ahora devuelve las mismas clases APIResponse / AsyncAPIResponse que .with_streaming_response ya usaba.¹

Luego los parámetros eliminados. Los modelos actuales no usan temperature, top_p ni top_k, así que los métodos generados ya no los aceptan. Un modelo anterior al cambio sigue respetándolos a través de extra_body, que el SDK fusiona tal cual en el JSON de la solicitud.¹

# Before
client.messages.create(..., model="claude-sonnet-4-6", temperature=0.2)

# After
client.messages.create(..., model="claude-sonnet-4-6", extra_body={"temperature": 0.2})

Los diccionarios de esquema se mueven de la misma manera: output_format={"type": "json_schema", "schema": ...} en beta.messages.create() se convierte en output_config={"format": {"type": "json_schema", "schema": ...}}; los helpers parse() / stream() / count_tokens() / tool_runner() conservan output_format=Order para una clase, y un diccionario de esquema ahí ahora lanza TypeError.¹

Termina con Bedrock. AnthropicBedrock y AsyncAnthropicBedrock antes registraban una advertencia y recurrían a us-east-1; ahora lanzan ValueError al construirse. La región se resuelve a partir de aws_region=, luego AWS_REGION / AWS_DEFAULT_REGION y por último la sesión de boto3 para el aws_profile indicado.¹ El SDK ahora también omite los eventos de streaming de Bedrock desconocidos que antes emitía; el único caso conocido es amazon-bedrock-invocationMetrics.¹

¿Cómo migro con Claude Code?

La propia guía de migración nombra el atajo: ejecuta /claude-api upgrade python en tu proyecto y revisa el diff.¹ Claude Code v2.1.239, publicado el 21 de agosto de 2026, es donde aterrizó el comando; la nota de versión dice, completa: “Added /claude-api upgrade to migrate Python projects from anthropic 0.x to 1.x, and updated the skill’s Python reference for 1.x (timeouts use anthropic.Timeout, not httpx.Timeout)” (es decir: se añadió /claude-api upgrade para migrar proyectos de Python de anthropic 0.x a 1.x y se actualizó la referencia de Python del skill para 1.x; los timeouts usan anthropic.Timeout, no httpx.Timeout).³

Esa frase es toda la superficie verificada: un comando del skill /claude-api que migra el uso de 0.x de un proyecto a 1.x. No he encontrado más documentación sobre cómo elige sus ediciones, así que trátalo exactamente como eso: una migración automatizada cuyo diff revisas tú. Actualiza a v2.1.239 o posterior (claude update, o la referencia de instalación y actualización), abre una sesión en la raíz del proyecto y ejecútalo:

/claude-api upgrade python

Después lee el diff hunk por hunk, ejecuta el verificador de tipos y corre la suite de pruebas – la misma revisión que le darías al PR de migración de un colaborador. El paso del verificador de tipos importa aquí más de lo habitual, porque casi todas las rupturas de 1.0 son errores de tipo, y a esa comprobación no le importa quién hizo las ediciones.¹ El único detalle que la nota de versión destaca, anthropic.Timeout en lugar de httpx.Timeout, coincide con la guía: esa reexportación ya apunta a httpx2.¹³

¿Nuevo en Claude Code? El inicio rápido cubre la primera sesión, y la guía completa cubre los skills incluidos y los comandos slash.

FAQ

¿anthropic 1.0 sigue siendo compatible con Pydantic v1?

Sí. El SDK sigue siendo compatible con Pydantic v1 y v2; el mínimo de Python 3.10 es el único cambio de entorno.¹

¿Por qué mi configuración de OpenTelemetry o respx deja de ver las solicitudes del SDK después de actualizar?

Esas bibliotecas parchean httpx, que el SDK ya no usa. Llama a httpx2.alias_httpx() antes de que cualquier cosa importe httpx; a partir de ahí, import httpx resuelve a httpx2 para todo el proceso.¹

¿Puedo seguir pasando temperature a un modelo antiguo?

Sí, a través de extra_body={"temperature": 0.2}, que el SDK fusiona en el JSON de la solicitud. Para messages.batches.create(), coloca la clave directamente en el diccionario params de la solicitud.¹

¿Qué reemplazó a la compactación del lado del cliente en tool_runner?

La compactación del lado del servidor: pasa betas=["compact-2026-01-12"] y context_management={"edits": [{"type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100_000}}]} a tool_runner(). En el ejemplo de la guía, ese par reemplaza a compaction_control={"enabled": True, "context_token_threshold": 100_000}; el umbral del trigger debe ser de al menos 50.000 tokens.¹

¿Necesito quitar httpx_aiohttp de requirements?

Sí. anthropic[aiohttp] y http_client=DefaultAioHttpClient() funcionan como antes, pero el extra ya no instala httpx_aiohttp porque ahora viene incluido dentro del SDK.¹

Puntos clave

Para desarrolladores de aplicaciones: - Fija "anthropic>=1,<2", ejecuta el verificador de tipos y corrige por categoría, en este orden: importaciones de httpx, awaits de respuestas crudas, parámetros eliminados, región de Bedrock.¹ - Coloca httpx2.alias_httpx() en las primeras líneas del punto de entrada si cualquier otra cosa en el proceso comparte objetos httpx con el SDK o instrumenta httpx.¹

Para mantenedores de bibliotecas: - Nunca llames a httpx2.alias_httpx() dentro de una biblioteca; en su lugar, crea un alias de la importación (import httpx2 as httpx).¹ - Abandona anthropic.Transport / ProxiesTypes a favor de httpx2.BaseTransport / httpx2.Proxy.¹

Para equipos que usan Claude Code: - Actualiza a v2.1.239 o posterior y ejecuta /claude-api upgrade python desde la raíz del proyecto; revisa el diff y luego ejecuta el verificador de tipos y las pruebas antes de confirmar.¹³

Referencias