Repository navigation
Description
Problem
Description
Add a timeout: float | None = None parameter to the three high-level OpenAI client classes:
OpenAIChatClientOpenAIChatCompletionClientOpenAIEmbeddingClient
This provides consistent HTTP timeout control across all OpenAI integrations in the Agent Framework.
Related: #9698 added timeout to FoundryChatClient.
Proposal
Expose the existing timeout capability from the raw clients (RawOpenAIChatClient, RawOpenAIChatCompletionClient, RawOpenAIEmbeddingClient) on the developer-facing client classes.
Behavior:
- Single
timeoutvalue applies to all request phases (connect, read, write, pool) - Default
Nonepreserves OpenAI SDK defaults (connect: 5s, read/write/pool: 600s) - Ignored when
async_clientis provided — configure timeout on that client instead - Works for both OpenAI and Azure OpenAI routing
Example usage:
from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(
model="gpt-4o",
api_key="sk-...",
timeout=30.0,
)Language
Python
Context
The raw OpenAI client classes already support a timeout parameter, but the high-level classes exposed to developers (OpenAIChatClient, OpenAIChatCompletionClient, OpenAIEmbeddingClient) do not. This forces developers to either accept the SDK default timeout or manually construct an async_client just to set a custom timeout, an inconsistent experience compared to using the OpenAI package directly.
This is a small quality-of-life improvement (not a blocker) that makes the framework’s OpenAI clients feel more familiar to developers adopting them from the OpenAI package.
Use Case and Evidence
Example usage:
from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(
model="gpt-4o",
api_key="sk-...",
timeout=30.0,
)Desired Outcome
The desired outcome is to give developers consistent, easy‑to‑use control over HTTP timeouts for all OpenAI API requests (chat, chat completions, and embeddings) by exposing a timeout parameter on the framework’s high‑level client classes, so they can set a single timeout value that applies to connect, read, write, and pool phases matching the experience they already have with the raw OpenAI clients.
Alternatives Considered
Currently the workaround to define custom timeout is by constructing the classes with async_client.
Proposed Direction
To be consistent with OpenAI package. I think to a certain level the compatibility is met in the RawOpenAI*Clients however it is not exposed to the agentic framework developers. I also found this is not available in .NET package too.
Scope and Non-Goals
No response
Language
Python
Contribution Intent
I am willing to implement this
Acknowledgements
- I searched existing issues and did not find a duplicate.
- I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.
Metadata
Metadata
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
eavanvalkenburg commentedon Nov 2, 2026
Thanks for the proposal. Consistent timeout control on these high-level OpenAI clients is in scope for MAF, and the team will consider it. This is not a commitment to implementation or timing. We first need to plan the public parameter contract across the three clients, OpenAI/Azure routing, SDK defaults, and caller-supplied async_client precedence. The supported configured-client alternative remains available. We will account for #9924 in planning; accepting the issue scope does not approve that implementation or authorize further implementation before explicit agreement on the plan.
eavanvalkenburg commentedon Nov 2, 2026
/plan Plan explicit timeout control on OpenAIChatClient, OpenAIChatCompletionClient, and OpenAIEmbeddingClient as an accepted core feature, coordinating existing #9924 rather than starting a parallel implementation. Reuse the raw-client/settings mechanism and establish exact omitted/None/value behavior from the actual SDK and existing raw-client contract instead of assuming None preserves SDK defaults. Keep caller-supplied async_client as-is with its transport/auth/timeout configuration authoritative. Cover OpenAI and Azure routing, overload/runtime/docstring consistency, supported timeout types, default preservation, and focused constructor/forwarding tests for all three clients. Resolve the maintainer question in #9924 (comment): determine whether invalid/non-positive values should be rejected by the framework or delegated to the SDK, and avoid duplicate inconsistent validation. Keep scope limited to this timeout request, not retries or a general transport abstraction. This planning request is not implementation approval for the existing PR.
IshamMohamed commentedon Nov 2, 2026
Thank you.
eavanvalkenburg commentedon Nov 12, 2026
/plan Plan explicit timeout control on OpenAIChatClient, OpenAIChatCompletionClient, and OpenAIEmbeddingClient as an accepted core feature, coordinating existing #9924 rather than starting a parallel implementation. Reuse the raw-client/settings mechanism and establish exact omitted/None/value behavior from the actual SDK and existing raw-client contract instead of assuming None preserves SDK defaults. Keep caller-supplied async_client as-is with its transport/auth/timeout configuration authoritative. Cover OpenAI and Azure routing, overload/runtime/docstring consistency, supported timeout types, default preservation, and focused constructor/forwarding tests for all three clients. Resolve the maintainer question in #9924 (comment): determine whether invalid/non-positive values should be rejected by the framework or delegated to the SDK, and avoid duplicate inconsistent validation. Keep scope limited to this timeout request, not retries or a general transport abstraction. This planning request is not implementation approval for the existing PR.
github-actions commentedon Nov 12, 2026
Summary
You asked for a plan to add a
timeoutsetting toOpenAIChatClient,OpenAIChatCompletionClientandOpenAIEmbeddingClient. It should reuse the existing raw-client mechanism, work with both OpenAI and Azure, leave a caller-suppliedasync_clientuntouched, and settle the validation question from the PR thread. I did not look at the open PR #9924 for solution evidence. I could not open the PR thread you linked, so the validation answer below comes from the code and is a proposal for you to confirm. I also could not read the installedopenaiSDK in this run. SDK behavior below is from my general knowledge of it and needs a check against the pinned version.What the code shows today (confirmed)
The issue says all three raw clients already support
timeout. That is only partly true. OnlyRawOpenAIChatClienthas it (_chat_client.pyaround line 755 and 826). I found notimeoutinRawOpenAIChatCompletionClient,RawOpenAIEmbeddingClient, or any of the three high-level classes.The shared helper
load_openai_service_settingsin_shared.pyalready takestimeout. It sets it on the SDK client only whentimeout is not None, in three places:/openai/v1bridge clientAsyncAzureOpenAIclientWhen a client is injected (
async_client), the helper returns it before any timeout is applied, in both the OpenAI and Azure branches. So an injected client's own timeout, transport and auth are already left alone.The
timeoutdocstring on the raw chat client says "SDK default is used", but only the chat raw client documents it, and the high-level classes do not.Recommendation
Code changes are warranted. This is a small feature that finishes work the shared helper already does, and it is already accepted as in scope. The workaround (build your own
async_client) works but loses framework routing, header and env handling. I recommend one shared contract for all three clients.Omitted,
Noneand value behaviortimeoutto the SDK, so the SDK default applies. I believe that default is about 600s total with a 5s connect time.None: today the helper treatsNoneas "omitted". In the SDK itself,Nonenormally means "no timeout", which is different. KeepingNoneas "use default" is safest for compatibility, and the issue asks for it, but the docstrings must say so. PassingNonecannot mean "disable timeouts". Disabling needs a customasync_client.float | None, as in the raw chat client. Acceptinghttpx.Timeoutfor per-phase control would be a separate, larger decision and is out of scope here. I'd suggest not adding it in this change.Invalid or non-positive values
I propose delegating to the SDK and adding no framework check. Reasons:
httpxdo, and could drift from them.Please confirm that the SDK and
httpxreject or handle0and negative values acceptably for the pinned SDK version. If they do not, add a single check insideload_openai_service_settings, so all three clients share it and no per-class copies exist.Proposed plan
No changes have been made. This is a proposal, and it is not approval of PR #9924. That PR should be reconciled with this plan before anything else starts.
Raw completion and embedding clients. Add
timeout: float | None = Noneto every overload and the runtime signature ofRawOpenAIChatCompletionClientandRawOpenAIEmbeddingClient, and pass it toload_openai_service_settings. Use the same docstring as the raw chat client.High-level clients. Add the same parameter to all overloads and the runtime signature of
OpenAIChatClient,OpenAIChatCompletionClientandOpenAIEmbeddingClient. Forward it to the raw class'ssuper().__init__. Include docstring text that says it is ignored whenasync_clientis given, and thatNoneand omitted both mean the SDK default.Helper. Leave
_shared.pylogic as it is. Only change it if the SDK check above shows validation is needed.Tests in
python/packages/openai/tests, for each of the three clients:AsyncAzureOpenAIpath and the/openai/v1bridge path.Noneleave the SDK default.async_clientkeeps its own timeout, and the framework value does not overwrite it.Docs. Update the package
AGENTS.mdonly if it lists constructor options. Do not touchCHANGELOG.md, because release preparation handles it.Scope. No retries and no transport abstraction.
Done when: all three clients accept
timeout, the tests above pass, and the docstrings match the runtime behavior.Questions for maintainers
Nonemeaning "SDK default" rather than "no timeout"?