LLM Timeouts
Bound every LLM call with a default timeout so a stuck provider can't hang your agent
Every agent gets a bounded LLM timeout for free — no setting needed. Override it per agent when you need more or less.
Quick Start
- Do nothing — you get a 600s bound
No timeout set → each request is bounded to 600 seconds (10 minutes). A black-holed provider stops the turn after 10 minutes instead of litellm’s 100-minute ceiling.
python from praisonaiagents import Agent agent = Agent( name="Assistant", llm="gpt-4o-mini", instructions="Answer carefully", ) agent.start("Summarise the attached report.") - Set your own timeout
An explicit
timeoutalways wins over the default.python from praisonaiagents import Agent agent = Agent( name="Fast", instructions="Answer briefly", llm={"model": "gpt-4o", "timeout": 30}, # 30s wins over the 600s default ) agent.start("What is 2 + 2?")
How It Works
There are two timeout layers. Agents built with praisonaiagents use the first one.
| Layer | Default | When it applies | Drop the default |
|---|---|---|---|
Agent(llm=...) / LLM class | 600 s | Whenever timeout is not set on the agent’s llm | timeout=None or timeout=0 |
Framework registry / gateway (praisonai) | 60 s + 2 retries | Framework-wrapped calls that go through the provider registry or a gateway (OpenRouter, LiteLLM-Proxy, Custom) | Set timeout per call |
| You write | Resolved timeout | Sent to provider |
|---|---|---|
llm="gpt-4o" or llm={"model": "gpt-4o"} | 600 | timeout=600 |
llm={"model": "gpt-4o", "timeout": 30} | 30 | timeout=30 |
llm={"model": "gpt-4o", "timeout": None} | None | Not sent — litellm’s ~100 min ceiling applies |
llm={"model": "gpt-4o", "timeout": 0} | 0 | Not sent — litellm’s ~100 min ceiling applies |
Configuration Options
| Setting | Layer | Default | How to override |
|---|---|---|---|
timeout | Agent / LLM class | 600 | Agent(llm={"model": "...", "timeout": N}) |
PRAISONAI_LLM_TIMEOUT | Framework registry / gateway | 60 | Env var, float seconds. Applies only where the call didn’t set timeout |
num_retries | Framework registry / gateway | 2 | Per-call num_retries= |
Opting Out
Rarely needed. Passing timeout=None (or 0) drops the 600 s default and falls back to litellm’s own ~100 minute ceiling (the old behaviour).
from praisonaiagents import Agent
agent = Agent(
name="LongRunner",
instructions="Work through the long task",
llm={"model": "gpt-4o", "timeout": None}, # opt out of the 600s default
)Best Practices
Raise the timeout, don't remove it
A large explicit timeout still bounds a stuck provider. Prefer 1200 or 1800 for very slow local models over an unbounded wait.
Override per agent for one slow model
Keep the default and raise timeout only for the specific agent that needs it.
from praisonaiagents import Agent
agent = Agent(name="LocalLLM", llm={"model": "ollama/llama3", "timeout": 900})Know which layer you're on
PRAISONAI_LLM_TIMEOUT only affects the framework registry / gateway layer. To change the timeout for a praisonaiagents agent, set timeout in its llm dict.
Registry retries are bounded on purpose
The registry default num_retries=2 recovers from transient blips without amplifying a real outage into a retry storm. Raise it only when a provider is known-flaky.