> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Call[📞 LLM call] --> Path{Which path?}
    Path -->|Agent / LLM class| Direct{timeout set?}
    Path -->|Framework registry / gateway| Reg{timeout set?}
    Path -->|Native OpenAIClient| Nat{OPENAI_TIMEOUT set?}
    Direct -->|No| D600[600s default]
    Direct -->|Yes| Keep[Use caller value]
    Reg -->|No| D60[PRAISONAI_LLM_TIMEOUT or 60s + 2 retries]
    Reg -->|Yes| Keep
    Nat -->|No| SDK600[SDK default 600s]
    Nat -->|Yes| Keep
    D600 --> Provider[🤖 Provider]
    D60 --> Provider
    SDK600 --> Provider
    Keep --> Provider

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef gate fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Call input
    class Path,Direct,Reg,Nat gate
    class D600,D60,SDK600,Keep process
    class Provider output
```

## Quick Start

**1. 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    llm="gpt-4o-mini",
    instructions="Answer carefully",
)
agent.start("Summarise the attached report.")
```

**2. Set your own timeout**

An explicit `timeout` always wins over the default.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 three 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 |
| Native `OpenAIClient` / `get_openai_client` | **600 s** (SDK default) | `AutoAgents`, the `praisonai --auto` OpenAI fallback leg, and direct `OpenAIClient` callers | Set `OPENAI_TIMEOUT` (float seconds) |

> [!NOTE]
>
> The native OpenAI client layer is controlled only by the `OPENAI_TIMEOUT` env var — see [OpenAI Client Timeout](https://praison.ai/docs/features/openai-client-timeout.md).

| 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 |

> [!NOTE]
>
> **Why 600 s?** It matches the OpenAI SDK default already used for bare model names, so every route has the same bound. It is long enough for non-streaming reasoning-model calls that legitimately exceed 2 minutes, while cutting a stuck call from 100 minutes to 10.

> [!NOTE]
>
> **Streaming:** for streaming calls the 600 s is a *read-gap* bound (max gap between chunks), not the total duration — a slow stream that keeps sending data is not cut off.

***

## 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=` |

> [!NOTE]
>
> An invalid `PRAISONAI_LLM_TIMEOUT` (e.g. `abc`) safely falls back to `60` seconds and logs a warning — a bad value never breaks a run.

***

## 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).

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
)
```

> [!WARNING]
>
> Without the 600 s bound, a stuck provider can hang the agent for up to \~100 minutes per attempt. Prefer a large explicit value like `1800` instead.

***

## Best Practices

> [accordion] 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.

> [accordion] Override per agent for one slow model
>
> Keep the default and raise `timeout` only for the specific agent that needs it.
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="LocalLLM", llm={"model": "ollama/llama3", "timeout": 900})
> ```

> [accordion] 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.

> [accordion] 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.

***

## Related

> [card] [LLM Configuration](https://praison.ai/docs/configuration/llm-config.md)
>
> Full reference for timeouts, retries, and headers

> [card] [Model Fallback](https://praison.ai/docs/features/model-fallback.md)
>
> Switch models when a provider fails

> [card] [Tool Timeout](https://praison.ai/docs/features/tool-timeout.md)
>
> Bound tool execution the same way

> [card] [Models](https://praison.ai/docs/models.md)
>
> Configure providers and model names


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.