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

# Runtime Selection

> Choose which runtime executes each model — per model, per provider, or per agent

Runtime selection lets you pick which execution backend (Claude Code, Codex CLI, the built-in PraisonAI runtime) runs each model — declared on the model map, not the agent.

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

agent = Agent(
    name="Coder",
    instructions="Write Python code",
    runtime="claude-code",
)
agent.start("Build a CLI tool that lists open PRs")
```

The user chooses a runtime backend for the agent; PraisonAI resolves CLI versus native execution for each model.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Runtime Resolution Order"
        A[Per-model runtime] --> B[Per-provider default]
        B --> C[Auto-selection]
        C --> D[Built-in praisonai]
    end

    classDef model fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef provider fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef auto fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef default fill:#10B981,stroke:#7C90A0,color:#fff

    class A model
    class B provider
    class C auto
    class D default
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Coder",
        instructions="Write Python code",
        runtime="claude-code"
    )

    agent.start("Build a CLI tool that lists open PRs")
    ```
  </Step>

  <Step title="With Configuration">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonaiagents.runtime import AgentRuntimeConfig

    agent = Agent(
        name="Coder",
        instructions="Write Python code",
        runtime=AgentRuntimeConfig(
            runtime="claude-code",
            config_overrides={"timeout": 120}
        )
    )
    ```
  </Step>
</Steps>

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Resolver as RuntimeResolver
    participant Registry as RuntimeRegistry
    participant Runtime

    User->>Agent: agent.start("...")
    Agent->>Resolver: resolve(model, provider)
    Resolver->>Resolver: check per-model runtime
    Resolver->>Resolver: fall back to per-provider default
    Resolver->>Resolver: fall back to built-in praisonai
    Resolver->>Registry: resolve(runtime_id)
    Registry-->>Resolver: Runtime instance
    Resolver-->>Agent: RuntimeResolutionResult
    Agent->>Runtime: execute turn
    Runtime-->>User: response
```

**Resolution order** (from `RuntimeResolver`):

1. **Per-model runtime** — `model_runtime_configs[model_name]`
2. **Per-provider default** — `provider_runtime_configs[provider_name]`
3. **Auto-selection** — `resolve_runtime()` picks the highest-priority runtime whose `supports(model_ref)` returns true; see [Agent Runtime Protocol](/docs/features/agent-runtime-protocol)
4. **Built-in default** — `"praisonai"`
5. **Legacy `cli_backend`** — emits `DeprecationWarning`

Provider is inferred from the model name: split on `/` first, otherwise `claude*` → `anthropic`, `gpt*`/`openai*` → `openai`, `gemini*`/`google*` → `google`, `llama*` → `meta`.

## Configuration

### Agent parameter forms

| Form                 | Example                                                         | When to use                                 |
| -------------------- | --------------------------------------------------------------- | ------------------------------------------- |
| `str` (runtime ID)   | `runtime="claude-code"`                                         | Most cases                                  |
| `dict`               | `runtime={"runtime": "claude-code", "config_overrides": {...}}` | Inline overrides                            |
| `AgentRuntimeConfig` | `runtime=AgentRuntimeConfig(runtime="claude-code", ...)`        | Full programmatic control                   |
| `None` (default)     | omit                                                            | Use model-map / provider-default / built-in |

Invalid types raise:

```
Invalid runtime type: <type>. Expected bool, str, dict, RuntimeConfig, or AgentRuntimeConfig instance.
```

### YAML — choose your level

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    Start[Need runtime control?] -->|One backend for all models| Prov[Set providers.*.runtime_default]
    Start -->|Different backend per model| Model[Set models.*.runtime]
    Start -->|One agent is special| Agent[Set agent runtime override]
    Prov --> Run[framework: praisonai required]
    Model --> Run
    Agent --> Run

    classDef decide fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef config fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef gate fill:#8B0000,stroke:#7C90A0,color:#fff

    class Start decide
    class Prov,Model,Agent config
    class Run gate
```

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai   # required — runtime features only work here

providers:
  anthropic:
    runtime_default: claude-code
  openai:
    runtime_default: codex-cli

models:
  claude-3-sonnet:
    runtime: claude-code
  gpt-4o:
    runtime: praisonai

agents:
  coder:
    role: Developer
    llm: claude-3-sonnet
    # resolves to claude-code from models.claude-3-sonnet.runtime
  reviewer:
    role: Reviewer
    llm: gpt-4o
    runtime: claude-code   # agent-level override beats model/provider
```

### `AgentRuntimeConfig` options

| Option                  | Type             | Default | Description                                                     |
| ----------------------- | ---------------- | ------- | --------------------------------------------------------------- |
| `runtime`               | `Optional[str]`  | `None`  | Runtime ID (e.g. `"claude-code"`, `"codex-cli"`, `"praisonai"`) |
| `config_overrides`      | `Dict[str, Any]` | `{}`    | Runtime-specific config passed to the runtime factory           |
| `provider_default`      | `Optional[str]`  | `None`  | Provider default (YAML `providers.<name>.runtime_default`)      |
| `enable_auto_selection` | `bool`           | `True`  | Allow auto-selection step in resolution order                   |
| `metadata`              | `Dict[str, Any]` | `{}`    | Free-form metadata                                              |

Helper methods: `from_runtime_id(id, **kwargs)`, `from_dict(d)`, `to_dict()`, `merge_overrides(overrides)`, `with_runtime(id)`, `is_explicit()`.

### Built-in runtime IDs

Reference IDs: `"claude-code"`, `"codex-cli"`, `"praisonai"`. Built-in default is `"praisonai"`.

### Framework gate

Runtime features require an adapter whose `SUPPORTS_RUNTIME_FEATURES = True` (the built-in `praisonai` adapter has it). Frameworks without that flag raise:

```
ValueError: Runtime features (runtime, models.*.runtime, providers.*.runtime_default) are not supported for framework='<x>'. Use a framework whose adapter sets SUPPORTS_RUNTIME_FEATURES = True (e.g. framework='praisonai').
```

Third-party adapters opt in by setting `SUPPORTS_RUNTIME_FEATURES = True` on their subclass — see [Capability Flags](/docs/features/framework-adapter-plugins#capability-flags).

### Fail-closed behaviour

Unknown runtime IDs raise — they do **not** silently fall back:

```
Unknown runtime ID: <id>. Available runtimes: [...]. Original error: ...
```

Top-level `RuntimeError` from Agent:

```
Runtime resolution failed for agent='<name>', model='<model>': <err>. Fix the runtime ID/configuration or remove the runtime override.
```

<Warning>
  If you typo a runtime ID, the agent fails at start. This is intentional — silent fallbacks should not ship to production.
</Warning>

## Common Patterns

1. **One provider, one runtime everywhere** — set `providers.anthropic.runtime_default: claude-code`.
2. **Mix runtimes per model** — `models.claude-3-sonnet.runtime: claude-code` plus `models.gpt-4o.runtime: praisonai`.
3. **Per-agent override** — agent-level `runtime` beats model/provider config when one role needs different behaviour.

## Migration from `cli_backend`

`cli_backend` still works but emits `DeprecationWarning` (slated for removal in 2.0.0).

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Before (deprecated)
agent = Agent(name="X", cli_backend="claude-code")

# After
agent = Agent(name="X", runtime="claude-code")
```

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Before
agents:
  coder:
    cli_backend: claude-code

# After (preferred — declare at the model)
models:
  claude-3-sonnet:
    runtime: claude-code
agents:
  coder:
    llm: claude-3-sonnet
```

For automatic YAML migration, run `praisonai doctor fix --execute` (or `praisonai doctor runtime --fix --execute`) — see [Runtime Config Migration](/docs/features/doctor-runtime-migration).

Agent-level YAML warning:

```
Agent-level 'cli_backend' in YAML is deprecated. Use 'runtime' parameter or model-scoped runtime configuration instead.
```

## Best Practices

<AccordionGroup>
  <Accordion title="Prefer model-map config over agent-level">
    Keep runtime choice with the model, not the role. Use `models.<name>.runtime` unless one agent truly needs an override.
  </Accordion>

  <Accordion title="Always set a provider_default">
    `providers.<name>.runtime_default` makes adding new models painless — new models inherit the provider backend automatically.
  </Accordion>

  <Accordion title="Don't catch the fail-closed error">
    Typo'd runtime IDs should fail at startup, not silently fall back to the built-in runtime.
  </Accordion>

  <Accordion title="Migrate cli_backend to runtime">
    Use the migration table above or `praisonai doctor fix` (the shorter equivalent of `praisonai doctor runtime --fix`) before 2.0.0 removes `cli_backend`.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Runtime Protocol" icon="plug" href="/docs/features/agent-runtime-protocol">
    Plugin harness registry, register\_runtime, and praisonai.runtimes entry points
  </Card>

  <Card title="Runtime Preflight" icon="shield-check" href="/docs/features/runtime-preflight">
    Validate team YAML before AgentTeam.start()
  </Card>
</CardGroup>