feat(openai): support openai 3.0 SDK

[ccurme (ccurme)]

Supports openai 3.x in langchain-openai.

The major change associated with openai 3.0 is a migration from httpx to httpx2: https://github.com/openai/openai-python/releases/tag/v3.0.0.

Here we support openai 2.x and 3.x simultaneously in langchain-openai. httpx is already a dependency of langchain-core and the langsmith sdk, so all environments running a langchain package install it.

We add a _compat.py that re-exports whatever httpx library the openai SDK uses. For any use of httpx that feeds into the openai SDK, we import from _compat. httpx continues to be used elsewhere in langchain-openai (langchain-core exports an SSRF-safe httpx client that we use for image token counting).

Manual specification of httpx clients remains supported via OpenAI's legacy escape hatch (langchain passes through), but support for this may be removed in a future release.

[open-swe]

✅ Open SWE Review: No issues found

Open SWE reviewed this PR and found no potential bugs to report.

Open in Web • View Open SWE trace

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	openai@​3.0.0

View full report

[Mason Daugherty (mdrxy)]

for CI do we really need to be running both? or can we conditionally run only the newest in CI?

[Mason Daugherty (mdrxy)]

I think we'll need to preserve the public custom HTTP-client contract

openai>=3 validates http_client / http_async_client against httpx2 types, while our public fields are documented for ordinary httpx.Client and httpx.AsyncClient. As a result, constructing ChatOpenAI, embeddings, or Azure models with an existing custom client now fails at runtime.

Since supporting OpenAI v3 is required, we'll probably want to accept httpx clients and adapt them internally to httpx2 clients (while continuing to accept native httpx2 clients).

[Mason Daugherty (mdrxy)]

I think we'll still need to keep httpx as a declared runtime dep as well (since we're keeping compat for both) ? Since we're importing it unconditionally still

Otherwise we can keep removed but import conditionally

[Mason Daugherty (mdrxy)]

Unreachable try/except ImportError — embeddings/base.py:423-431, 440-448. _compat is imported eagerly at package import via chat_models → _client_utils, so the from-import cannot raise; if it could, import langchain_openai would already have failed. The new "reinstall with pip install openai" advice is also wrong under openai 3, which doesn't ship httpx.

[ccurme (ccurme)]

I think we'll need to preserve the public custom HTTP-client contract

openai>=3 validates http_client / http_async_client against httpx2 types, while our public fields are documented for ordinary httpx.Client and httpx.AsyncClient. As a result, constructing ChatOpenAI, embeddings, or Azure models with an existing custom client now fails at runtime.

Since supporting OpenAI v3 is required, we'll probably want to accept httpx clients and adapt them internally to httpx2 clients (while continuing to accept native httpx2 clients).

I think this works already:

import httpx
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-5.6-luna",
    http_client=httpx.Client(timeout=httpx.Timeout(30.0)),
)
model.invoke("Hello")

I mentioned this in the last line of the PR summary. lmk if I misunderstood the issue.

[ccurme (ccurme)]

for CI do we really need to be running both? or can we conditionally run only the newest in CI?

We don't need to run both. I just added two invoke calls to integration tests (one with openai 2.x and another with 3.x) so the cost seemed small.

[ccurme (ccurme)]

I think we'll still need to keep httpx as a declared runtime dep as well (since we're keeping compat for both) ? Since we're importing it unconditionally still

Otherwise we can keep removed but import conditionally

I moved it to langchain-core, I think it's OK to keep it implicit (it just depends on what we use in langchain-core). Open to changing this.

[Mason Daugherty (mdrxy)]

If a user passes a Timeout from httpx, it gets stored as-is inside the OpenAI 3.0 SDK's httpx2 client. But httpx.Timeout and httpx2.Timeout are different classes, and httpx2 doesn't know what to do with the foreign one. The first time anything reads or prints that timeout (e.g. a log line, retry, or per-request timeout merge) you'll get TypeError: unhashable type: 'Timeout'.

import httpx
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="some-model",
    timeout=httpx.Timeout(60.0, connect=5.0),
)

llm.invoke("Say hello")  # works — nothing has read the timeout yet
# later, the first code path that reads it raises
# TypeError: unhashable type: 'Timeout'

Should consider fixing this for correctness: before building the client, convert a plain httpx.Timeout into whichever Timeout class the active HTTP module uses. That way the object stored in the SDK is always the right type. This applies to the chat, embeddings, and LLM client paths.

[ccurme (ccurme)]

The first time anything reads or prints that timeout (e.g. a log line, retry, or per-request timeout merge) you'll get TypeError: unhashable type: 'Timeout'.

Do you have a repro for this? afaict the openai SDK normalizes the timeouts to httpx2: https://github.com/openai/openai-python/blob/a1eeab58db02de46717ccebaf1eb83e314fa86ff/src/openai/_httpx2.py#L65-L69