OpenAI migra su SDK Python a HTTPX2: qué cambia

Qué cambió exactamente: el SDK Python de OpenAI deja httpx por HTTPX2

El SDK de Python de OpenAI, una de las librerías más instaladas del ecosistema de IA, dejó de depender del paquete httpx y pasó a httpx2, según la guía de migración publicada en el repositorio oficial de openai/openai-python. El cambio ya está en producción: cualquier pip install openai instala httpx2 de forma automática y deja de instalar httpx. Para un founder que monta productos sobre GPT, esto significa revisar hoy mismo sus imports, su trust store TLS y sus mocks de tests antes del próximo deploy.

El cambio no es cosmético. La guía de OpenAI detalla cuatro áreas afectadas: el trust store TLS por defecto, los nombres de los clientes (DefaultHttpx2Client, DefaultAsyncHttpx2Client, DefaultAioHttpClient), los tipos de los objetos cuando se piden respuestas crudas, y los mocks de pruebas que parcheaban httpx. La promesa de compatibilidad es alta para quien usa el SDK con su cliente por defecto (timeouts numéricos, modelos parseados, streaming, autenticación y reintentos siguen funcionando igual), pero se rompe en cuanto tu código toca el cliente HTTP directamente o toca el sistema de certificados.

¿Qué es HTTPX2 y por qué Pydantic tomó el relevo?

HTTPX2 no es una librería nueva: según el repositorio pydantic/httpx2, es la continuación formal del proyecto original httpx, ahora bajo el mantenimiento de Pydantic. El cambio de nombre funciona como marcador de la nueva stewardship y como paquete nuevo en PyPI: el import pasa de import httpx a import httpx2, y el código, el diseño y la API se mantienen. Lo que cambia es quién responde por los parches de seguridad y la evolución de un cliente HTTP que vive en el camino crítico de la mayoría de sistemas productivos en Python.

🤖 La IA no es solo para leer sobre ella

En la comunidad la aplicamos: automatización, agentes IA y herramientas reales para emprender, no solo para informarte.

👥 Aplicarla en la comunidad

El comunicado en el repositorio explica que la mudanza responde a que httpx venía con "actividad de mantenimiento reducida". Pydantic asume la stewardship para garantizar "una ruta mantenida de forma fiable, incluyendo actualizaciones de seguridad oportunas", lo que tiene sentido porque la propia Pydantic usa el cliente HTTP en sus productos de IA. La base técnica sigue siendo la misma: httpcore2 como transporte subyacente, h11 para HTTP/1.1, anyio para concurrencia estructurada, truststore para verificación TLS, e idna para dominios internacionalizados. El soporte de HTTP/2 sigue siendo opcional vía httpx2[http2].

Para los fundadores, lo relevante es entender que HTTPX2 hereda todo lo bueno de httpx: clientes síncronos y asíncronos en la misma librería, timeouts estrictos por defecto, anotaciones de tipo completas, capacidad de llamar a apps ASGI/WSGI en proceso (lo que hace TestClient de FastAPI por debajo), y soporte de HTTP/2 con un flag. Lo nuevo es político y operativo: hay un responsable identificable y un camino de actualizaciones predecible.

TLS, timeouts y clientes: los cambios que rompen tu código

Cambio 1 — Trust store TLS. El SDK ya no usa certifi como bundle por defecto. En su lugar, HTTPX2 verifica los certificados contra el trust store del sistema operativo. Esto rompe en escenarios muy concretos que importan en producción: imágenes de contenedor minimalistas sin CA del sistema, proxies corporativos que interceptan TLS, y despliegues que dependían de un certifi modificado. La guía de OpenAI recomienda instalar las CA en el trust store del sistema operativo o configurar un bundle explícito con SSL_CERT_FILE o SSL_CERT_DIR. Quien necesite control fino puede pasar un ssl.SSLContext vía verify=:

import ssl
from openai import OpenAI, DefaultHttpx2Client
ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))

Cambio 2 — Objetos del cliente HTTP. Si inyectas tu propio cliente, los nombres cambian según esta tabla de migración:

Objeto anterior	Objeto nuevo
`httpx.Client`	`httpx2.Client`
`httpx.AsyncClient`	`httpx2.AsyncClient`
`httpx.Timeout`	`httpx2.Timeout`
`httpx.URL`	`httpx2.URL`
`httpx.Limits`	`httpx2.Limits`
`httpx.HTTPTransport`	`httpx2.HTTPTransport`
`httpx.MockTransport`	`httpx2.MockTransport`

Los timeouts numéricos y las URLs en formato string no cambian, pero cualquier subclase de transporte, integración de proxy o instrumentación de pool de conexiones debe apuntar a las interfaces de HTTPX2.

Cambio 3 — Respuestas crudas, streaming y excepciones. Los modelos parseados del SDK se mantienen. Lo que cambia son los objetos a nivel de transporte cuando usas un cliente nativo HTTPX2: response.http_response ahora es un httpx2.Response, y si pides respuesta sin parsear debes usar cast_to=httpx2.Response. Los hooks de autenticación y los event_hooks también reciben objetos httpx2.Request y httpx2.Response. La parte crítica: si inyectas un cliente httpx legacy (vía el escape hatch temporal con cast(Any, ...)), obtienes httpx.Response aunque pidas cast_to=httpx2.Response — los tipos no se convierten.

Cambio 4 — Mocks y tests. Según la guía, los mocks deben interceptar peticiones HTTPX2 y devolver respuestas HTTPX2. Si tu suite usa RESPX y todavía no migró a una versión compatible con HTTPX2, un RESPX que solo parchea httpx legacy no interceptará al cliente por defecto del SDK. La propia guía reconoce un escape hatch temporal: instalar httpx legacy e inyectar el cliente con cast(Any, httpx.Client()). Es un camino con fecha de caducidad: el soporte de httpx legacy es solo en tiempo de ejecución, falla el type checking con mypy y Pyright, y "puede ser discontinuado".

Cambio 5 — aiohttp. El extra openai[aiohttp] ya no instala httpx legacy ni el adaptador externo httpx-aiohttp: usa un transporte nativo HTTPX2. Para código nuevo, la guía recomienda DefaultAioHttpClient() y dejar la construcción del transporte al SDK.

¿Qué significa esto para tu startup?

Si tu producto hace from openai import OpenAI y nada más, no tienes que cambiar nada: el cliente por defecto sigue funcionando. Si en cambio tocas la capa HTTP — para proxies, timeouts personalizados, mocks de test, proxies de tracing corporativo, middlewares de auth custom o instrumentación de OpenTelemetry — esta migración te toca de lleno. La ventana de compatibilidad legacy existe, pero la propia OpenAI la marca como temporal.

Acción concreta 1 — Audita tus imports y mocks hoy mismo. Ejecuta grep -r "import httpx" . y grep -r "from httpx" . en tu repositorio. Cada aparición tiene tres posibles significados: (a) imports del SDK OpenAI que ahora rompen, (b) imports propios que tenías porque el SDK los arrastraba y que ya no necesitas a menos que los declares tú, (c) código que usa httpx directamente y debe migrar a httpx2. Revisa también requirements.txt y pyproject.toml: si httpx solo estaba como dependencia transitiva, reemplázalo por httpx2 (o decláralo tú si lo necesitas) y elimina certifi salvo que otra parte del sistema lo requiera.

Acción concreta 2 — Endurece tu TLS antes del próximo deploy. Añade truststore y las CA de tu entorno (corporativas, privadas) al Dockerfile de tus imágenes de producción: nada de :latest-slim sin un paso explícito que instale ca-certificates. Si usas un proxy MITM corporativo, configura SSL_CERT_FILE en tu despliegue en lugar de depender de certifi por defecto. Y donde tengas tests con RESPX, sube a una versión HTTPX2-compatible o prepara el fork antes de que la ventana de escape hatch se cierre.

Acción concreta 3 — Decide ahora qué hacer con los timeouts. Esta migración es una buena excusa para dejar de aceptar defaults vagos. Configura httpx2.Timeout(connect=5.0, read=30.0, write=10.0, pool=5.0) según el SLA real de tu producto, y pásalo al constructor del SDK. El coste de hacerlo mal (workers colgados en producción) lo has pagado antes o lo vas a pagar pronto.

Conclusión

La migración del SDK de Python de OpenAI a HTTPX2 es un movimiento silencioso pero real: cambia el cliente HTTP que vive bajo tu producto de IA, arrastra un trust store TLS distinto y redefine los tipos de los mocks. Para el 80% de las integraciones que usan el cliente por defecto, la promesa de compatibilidad se cumple. Para el 20% que toca la capa HTTP — proxies, timeouts, mocks, instrumentación — la acción es hoy: auditar imports, endurecer TLS y migrar mocks antes de que el escape hatch de httpx legacy desaparezca. Y si estás eligiendo cliente HTTP para un proyecto greenfield, la decisión de Pydantic de tomar el relevo de httpx consolida a HTTPX2 como el default sensato del ecosistema Python moderno.