OpenAI Client Retries

Turn on the OpenAI SDK’s built-in Retry-After + backoff for the native client path

OpenAI client retries turn on the OpenAI SDK’s built-in retry engine so transient 429s and network blips on the native client path are retried automatically.

Quick Start

1. Turn it on with one env var (zero code change)

   # export OPENAI_MAX_RETRIES=5
   
   from praisonaiagents import Agent
   
   agent = Agent(
       name="Assistant",
       instructions="You are a helpful assistant.",
   )
   agent.start("Summarise today's news.")
   # Transient 429s and network blips are now retried automatically.
   

   The user runs an agent; transient rate limits and network blips retry automatically on the native OpenAI client path.

2. Pass max_retries through the client factory

   from praisonaiagents.llm import get_openai_client
   
   client = get_openai_client(max_retries=5)
   
3. Construct the client directly

   from praisonaiagents.llm import OpenAIClient
   
   client = OpenAIClient(max_retries=5)
   

---

How It Works

The value is forwarded into the underlying openai SDK, which honours Retry-After on 429s and applies exponential backoff for transient errors.

Behaviour	Detail
Applies to	The native OpenAIClient / get_openai_client path (used internally by AutoAgents and, since PR for #2963, by the OpenAI fallback leg of praisonai --auto / AutoGenerator), plus any direct callers.
Not affected	The LiteLLM leg of praisonai --auto (LiteLLM runs first; OPENAI_MAX_RETRIES only kicks in when the OpenAI fallback runs). The LiteLLM-backed LLM class and agent-loop resilience engine also live in a separate layer — see Agent Retry.
When unset	Behaviour is byte-identical to before — max_retries is only forwarded when it is not None.
Cache	get_openai_client() caches on max_retries, so changing it mid-process rebuilds the SDK client.

praisonai --auto uses LiteLLM first and only falls back to OpenAI on error. OPENAI_MAX_RETRIES therefore only takes effect on that fallback path — see Auto Mode Providers for the fallback flow.

---

Configuration Options

Option	Type	Default	Description
max_retries (arg on OpenAIClient / get_openai_client)	Optional[int]	None	Number of automatic retries for transient errors on the native OpenAI client path.
OPENAI_MAX_RETRIES (env var)	int (string)	unset	Fallback used when max_retries is not passed. Non-integer values silently fall back to the SDK default.

Precedence: explicit arg > OPENAI_MAX_RETRIES env var > SDK default.

Non-integer OPENAI_MAX_RETRIES (e.g. "abc") is silently ignored and the SDK default takes over — no crash.

---

Which Approach to Use

Match the retry surface to how broadly you want the policy to apply.

---

Common Patterns

Turn it on globally with one env var — for production deployments where every call should retry the same way.

# export OPENAI_MAX_RETRIES=5
from praisonaiagents import Agent

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
agent.start("Draft a weekly status report.")

Scope it to one call site — pass max_retries explicitly when you build the client for a hot path.

from praisonaiagents.llm import get_openai_client

# Only this client retries; the rest of the process is unaffected.
client = get_openai_client(max_retries=5)

AutoAgents also accepts a max_retries argument, but that controls its own config-generation retries — it is separate from the SDK-level max_retries documented here. Use OPENAI_MAX_RETRIES for a process-wide native-client policy.

Local server (LM Studio / vLLM) — leave it off — local endpoints rarely emit Retry-After, so retries are wasted latency.

from praisonaiagents.llm import get_openai_client

# No max_retries: keep local calls fast and fail fast.
client = get_openai_client(base_url="http://localhost:1234/v1")

---

Best Practices

Prefer the env var for cluster-wide policy

One place, no code change, easy to bump per environment. Set OPENAI_MAX_RETRIES once and every native call inherits it.

Start with 3–5

This matches the SDK’s typical rate-limit budget without inflating tail latency.

Don't stack with agent-level retry unless you mean to

Combining OPENAI_MAX_RETRIES=5 with Agent(retry=True, max_retries=3) multiplies attempts (5 × 3 = 15). Pick one layer for the primary retry policy and use the other only as a safety net.

Not a substitute for failover

Retries help transient blips; for provider outages use LLMConfig(fallbacks=[...]) — see Model Fallback.

---

Related

Agent Retry

Retry the LiteLLM-backed agent loop with jittered exponential backoff.

Model Fallback

Fail over to alternate models during provider outages.

LLM Error Classification

Understand which errors are retryable versus fatal.