fix: migrate http clients to httpx2

[chenghao-mou]

Behavior: Upgrade OpenAI to 3, MCP to 2, and repository-owned HTTP transports to HTTPX2. Use one OpenAI client policy and test real MCP SSE and streamable HTTP requests.

Compatibility: Keep legacy httpx.Timeout inputs working through 1.x. Warnings point to application call sites. Remove support in 2.0. Keep HTTPX 1 adapters only for upstream SDKs that still require them.

Addresses AGT-3286

Initial prompt and agent context

Model: GPT-5.6

we need to add httpx because the new openai client dropped it and we did not declare it

change of plan, can we upgrade to httpx2 instead?

there is a migration guide: https://github.com/openai/openai-python/blob/main/httpx2.md as well, we should double check.

we need a backward compatible change for the entire code base, not just inference... we need to deprecate the httpx version and warn the user that we are dropping them in 2.0.

not just openai sdk, plain httpx usage should be updated too

then we can stick with DefaultAsyncHttpx2Client

i thought mcp can support httpx2 already?

yeah, we should fix all three

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

[longcw]

the plugins still depend on the httpx, should we add httpx to the agent instead?

[chenghao-mou]

the plugins still depend on the httpx, should we add httpx to the agent instead?

good point. Now it's upgrading the whole repo with deprecation warning and backward compatibility until 2.0.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 2 additional findings in Devin Review.

[devin-ai-integration]

🟡 New public helper functions ship without the documentation the project requires

The newly added HTTP-client compatibility helpers are published without any documentation (livekit-agents/livekit/agents/utils/httpx_compat.py:21-71), so the auto-generated API reference will list them with no explanation of what they do.
Impact: Users and maintainers reading the generated docs get undocumented public API surface.

Repository documentation rule and affected additions

CONTRIBUTING.md states: "If writing new methods/enums/classes, document them. This project uses pdoc3 for automatic API documentation generation, and every new addition has to be properly documented." AGENTS.md additionally requires Google-style docstrings.

The new module livekit-agents/livekit/agents/utils/httpx_compat.py adds four public functions with no docstrings: warn_on_legacy_timeout (line 21), to_httpx2_timeout (line 26), to_legacy_timeout (line 38) and legacy_async_client (line 50). The same applies to the new create_http_client helper exported from livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/utils.py:13-22, which is added to __all__.

Prompt for agents

CONTRIBUTING.md requires every new public method/class to be documented (pdoc3 generates the API reference from docstrings) and AGENTS.md asks for Google-style docstrings. The new module livekit-agents/livekit/agents/utils/httpx_compat.py adds four public functions (warn_on_legacy_timeout, to_httpx2_timeout, to_legacy_timeout, legacy_async_client) with no docstrings, and livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/utils.py adds create_http_client (exported in __all__) also without a docstring. Add Google-style docstrings explaining the httpx -> httpx2 migration semantics, when each helper should be used, the deprecation policy (legacy httpx.Timeout support removed in 2.0) and the return values.

---

Was this helpful? React with 👍 or 👎 to provide feedback.