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

# Configurable Model

> Switch models per-call or permanently at runtime without recreating the agent

One agent, many models — override the LLM for a single call with `config=`, or permanently swap it with `switch_model()`, all while keeping your conversation history intact.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Configurable Model"
        Request[📋 User Request] --> Process[⚙️ Configurable Model]
        Process --> Result[✅ Result]
    end

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

    class Request input
    class Process process
    class Result output
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="flex", instructions="Answer with the best model for each task.", llm="gpt-4o-mini")
agent.start("Draft a short poem, then switch to a stronger model for critique.")
```

The user keeps one agent; per-call `config=` or `switch_model()` changes the LLM without losing history.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Configurable Model"
        In[📝 Request] --> Select[⚙️ Select Model]
        Select --> Agent[🤖 Agent]
        Agent --> Out[✅ Response]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class In input
    class Select process
    class Agent agent
    class Out output
```

### Override vs Switch

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    A[Agent] --> B{Which model?}
    B -->|Per-call override| C[chat config=model]
    B -->|Permanent switch| D[switch_model]
    C --> E[gpt-4o for this call]
    D --> F[gpt-4o for all future calls]
    C --> G[Back to default next call]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef method fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
    class A agent
    class B decision
    class C,D method
    class E,F result
    class G config
```

## Quick Start

<Steps>
  <Step title="Override model for a single call">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="FlexBot",
        instructions="Answer questions helpfully.",
        llm="gpt-4o-mini"
    )

    cheap = agent.chat("Summarize this paragraph.")

    expensive = agent.chat(
        "Write a detailed technical analysis.",
        config={"model": "gpt-4o"}
    )
    ```

    The agent uses `gpt-4o-mini` by default. Passing `config={"model": "gpt-4o"}` upgrades just that one call. The next call reverts to `gpt-4o-mini`.
  </Step>

  <Step title="Permanently switch the agent's model">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="AdaptiveBot",
        instructions="Help with various tasks.",
        llm="gpt-4o-mini"
    )

    agent.chat("Quick question: what's 2 + 2?")

    agent.switch_model("gpt-4o")

    agent.chat("Now write a 500-word essay on climate change.")
    ```

    `switch_model()` updates the agent in place. All future calls use the new model, and the conversation history is fully preserved.
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant LLM

    User->>Agent: chat("question", config={"model": "gpt-4o"})
    Agent->>Agent: Apply config override for this call
    Agent->>LLM: Request with gpt-4o
    LLM-->>Agent: Response
    Agent-->>User: Answer

    User->>Agent: chat("next question")
    Agent->>LLM: Request with default model
    LLM-->>Agent: Response
    Agent-->>User: Answer
```

Per-call config overrides are isolated to that single invocation and never mutate the agent's defaults. This makes them safe for concurrent use — multiple threads can call the same agent with different models simultaneously.

`switch_model()` updates `agent.llm` and recreates the internal LLM instance. Conversation history stored in `agent._chat_history` is untouched.

***

## Configuration Options

**`chat()` config keys:**

| Key           | Type    | Description                                                                |
| ------------- | ------- | -------------------------------------------------------------------------- |
| `model`       | `str`   | Override model name for this call (e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`) |
| `temperature` | `float` | Override temperature for this call                                         |
| `provider`    | `str`   | Override provider (e.g. `"openai"`, `"anthropic"`)                         |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
response = agent.chat(
    "Write a creative story.",
    config={
        "model": "gpt-4o",
        "temperature": 0.9,
    }
)
```

**`switch_model()` signature:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent.switch_model("gpt-4o")
```

Accepts any model string supported by LiteLLM (same format as the `llm=` constructor argument).

<Card title="Agent Config TypeScript Reference" icon="code" href="/docs/sdk/reference/typescript/classes/AgentConfig">
  TypeScript agent configuration
</Card>

<Card title="Agent Rust Reference" icon="code" href="/docs/sdk/reference/rust/classes/AgentConfig">
  Rust agent configuration
</Card>

***

## Common Patterns

**Route by task complexity:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="Router", instructions="Answer questions.", llm="gpt-4o-mini")

def ask(prompt: str, complex: bool = False) -> str:
    if complex:
        return agent.chat(prompt, config={"model": "gpt-4o"})
    return agent.chat(prompt)

simple = ask("What is 10 * 5?")
detailed = ask("Explain quantum entanglement.", complex=True)
```

**Override temperature for creative tasks:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(name="Writer", instructions="Write content.", llm="gpt-4o-mini")

factual = agent.chat("What year was Python created?")

creative = agent.chat(
    "Write a haiku about debugging.",
    config={"temperature": 1.2}
)
```

**Escalate on failure:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def safe_chat(agent, prompt):
    try:
        return agent.chat(prompt)
    except Exception:
        return agent.chat(prompt, config={"model": "gpt-4o"})
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use per-call config for cost optimization">
    Default to a fast, cheap model and escalate to a powerful model only for complex requests. This gives you the best cost-to-quality ratio without managing multiple agents.
  </Accordion>

  <Accordion title="Use switch_model for long-running sessions">
    When a user explicitly asks to use a different model, call `switch_model()` so all subsequent turns in that session use the new model automatically. Per-call config is better for one-off overrides.
  </Accordion>

  <Accordion title="Per-call config is thread-safe">
    Config overrides are applied within the scope of a single `chat()` call and never persist to agent state. Multiple concurrent callers can override different models on the same agent instance safely.
  </Accordion>

  <Accordion title="Conversation history survives model switches">
    `switch_model()` only changes the model — it does not clear `agent._chat_history`. The new model receives the full conversation context from previous turns.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Model Failover" icon="arrow-rotate-right" href="/docs/features/failover">
    Automatic fallback when a model call fails
  </Card>

  <Card title="Model Router" icon="route" href="/docs/features/model-router">
    Dynamic model selection based on task type
  </Card>
</CardGroup>