Models & API Keys

Pick a model, set sampling, and store keys in the platform keychain

Swap models from the title bar, tune sampling, and keep your API key in the platform keychain — never in a file.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    llm="gpt-4o-mini",
)
# The model you pick in the app is passed to the agent as llm=...
agent.start("Say hello")

The same string the desktop combobox passes into llm= can also be a provider-prefixed id, routed through litellm:

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    llm="anthropic/claude-sonnet-4-20250514",  # routed through litellm
)
agent.start("Say hello")

Quick Start

1. Open the model combobox

   Click the model pill in the title bar. It suggests common models and accepts any string.

2. Set your API key

   In Settings → Models → API key, paste your key. It is stored in the platform keychain.

3. Tune sampling (optional)

   Adjust temperature, max_tokens, or top_p in the Models section.

Suggested Models

The combobox suggests eleven ids. Four use the OpenAI API and your api_key; the rest are provider-prefixed and route through litellm to a different provider, which needs that provider’s credentials — in the environment, in the app’s api_key field, or reached by a Base URL. It stays free-text, so you can type any id.

Using another provider (Anthropic, Google, Ollama, …)

Three paths reach these providers. The shipped desktop venv now carries litellm — it is a core dependency of the praisonai wrapper package pinned by ENGINE_PACKAGES (see PraisonAI#4721) — so slashed ids run fine out of the box, and PraisonAI#4778 restores them in the picker.

The Base URL field is now sent to the variable the selected provider reads — OLLAMA_API_BASE for ollama/…, LM_STUDIO_API_BASE for lm_studio/…, HOSTED_VLLM_API_BASE for hosted_vllm/…, and `

_API_BASE for anything else litellm knows. The API key field follows the same rule (

_API_KEY`), with the OpenAI pair kept in step so switching back to a bare id still works. Pointing the desktop at a remote Ollama, LM Studio, or vLLM host is a two-field task: pick the slashed id, set Base URL. No shell exports needed.

Path 1 — Provider-prefixed id (recommended for Anthropic, Gemini, Ollama): Pick a slashed id from the combobox and set that provider’s key in the environment (or run Ollama locally). No Base URL needed.

Path 2 — Bare id + Base URL (for any OpenAI-compatible endpoint): Set a Base URL to that endpoint and type its bare model id.

Path 3 — Slashed id + provider Base URL (recommended for Ollama / LM Studio / vLLM on your own host): Pick the slashed id and set Base URL to your host. The app routes it to the variable that provider reads.

Both base_url and api_key are marked Requires restart — relaunch the app after changing either. See the Setup table below for the exact fields.

Behaviour introduced in PraisonAI #4921 — Base URL and API key are now routed to the environment variable the selected provider actually reads.

Sampling & Endpoint

These values are forwarded into agent.start(..., max_tokens=..., top_p=...). Since MervinPraison/PraisonAI#4725 they also take effect on streaming chats — previously the streaming path ignored them. See Streaming → Sampling knobs.

Reasoning effort

reasoning_effort grades how hard the model thinks before answering. Off leaves the provider default in place; minimal / low / medium / high map to each backend’s native control (OpenAI/xAI reasoning_effort, Anthropic/Gemini extended-thinking budget). The chosen level is forwarded on every turn — streaming and non-streaming alike (since MervinPraison/PraisonAI#4780 the streaming path honours it too). See Reasoning Effort for what each level means and which model families it affects.

Where Keys Live

The api_key is stored in the platform secret store (service ai.praison.desktop, overridable with PRAISONAI_KEYCHAIN_SERVICE) and stripped before settings.json is written — it is the only key in SECRET_KEYS, so it never reaches the file.

The store is durable: an unreadable secret raises rather than returning empty, so a transient failure never overwrites a good key, and deleting a key clears both the keychain and the plaintext fallback. See Data & Privacy for the full guarantees.

The store is durable: an unreadable store raises rather than silently returning empty (so a transient error can’t overwrite a good key), clearing a key wipes both the keychain and the fallback file, and the fallback file is written 0o600. Override the service name with PRAISONAI_KEYCHAIN_SERVICE (default ai.praison.desktop) to isolate keys. See Data & Privacy for the full guarantees.

Choosing a Setup

Best Practices

Related