Configuration File

Set default values for all Agent parameters using a configuration file. When you pass True to a feature, it uses your configured defaults.

from praisonaiagents import Agent

agent = Agent(name="configured", instructions="Use defaults from config.toml.")
agent.start("Hello — apply my saved model and memory settings.")

The user sets defaults in .praisonai/config.toml; explicit Agent parameters still override the file.

How It Works

classDef agent fill:#8B0000,color:#fff classDef tool fill:#189AB4,color:#fff Precedence (highest to lowest):

Explicit parameters in code
Environment variables
Config file
Built-in defaults

Project Config

.praisonai/config.toml — project-specific defaults

Root Config

praisonai.toml — project root alternative

User Global

~/.praisonai/config.toml — applies across projects

Environment Override

PRAISONAI_* env vars beat config file values

Quick Start

Create Config File

Create .praisonai/config.toml in your project:

[defaults]
model = "gpt-4o-mini"

[defaults.memory]
enabled = true
backend = "sqlite"

Use in Code

from praisonaiagents import Agent

# memory=True now uses your config defaults (sqlite backend)
agent = Agent(
    name="Assistant",
    instructions="Help users",
    memory=True  # Uses [defaults.memory] settings
)

PraisonAI now validates field names automatically — see Automatic Field Validation for typo detection and suggestions.

Config File Locations

Config files are searched in this order:

Location	Scope
`.praisonai/config.toml` · `.yaml` · `.yml`	Project-specific
`praisonai.toml` · `.yaml` · `.yml`	Project root
`~/.praisonai/config.toml` · `.yaml` · `.yml`	User global

Small Model for Cheap Internal Calls

small_model routes internal LLM calls (session title generation today; summarisation/compaction going forward) to a cheaper model than your primary model.

# .praisonai/config.yaml
defaults:
  model: gpt-4o            # primary — used by your agents
  small_model: gpt-4o-mini # cheap auxiliary — internal calls

When unset, behaviour is byte-identical to today: internal calls fall back to gpt-4o-mini. Resolution precedence (highest first):

Field	Type	Default	Description
`small_model`	`str`	`None` (falls back to `gpt-4o-mini`)	Cheap auxiliary model for internal LLM calls. Falls back to `primary_model`, then `defaults.model`, then `gpt-4o-mini`.

An explicit llm_model= at the call site (e.g. generate_title(..., llm_model="gpt-4o")) always wins over small_model.

The CLI/JSON-schema namespace agent.small_model is honoured too — both defaults.small_model and agent.small_model read the same config file.

Full Configuration Reference

[plugins]
# Enable all plugins: true
# Enable specific: ["logging", "metrics"]
# Disable: false
enabled = false

# Auto-discover from default directories
auto_discover = true

# Plugin directories to scan
directories = [
    "./.praisonai/plugins/",
    "~/.praisonai/plugins/"
]

plugins:
  enabled: true
  auto_discover: true
  directories:
    - ./.praisonai/plugins/
    - ~/.praisonai/plugins/
  pii_guardrail:          # per-plugin option block
    redact: [email, phone]
  memory_watchdog:
    interval: 30
    enabled: false        # disable just this plugin

Both formats are discovered — .praisonai/config.toml and .praisonai/config.yaml (plus .yml) share the same search walk. A per-plugin <name>: { ... } block also implicitly opts that plugin in unless it sets enabled: false.

When [plugins] enabled = true (or PRAISONAI_PLUGINS=true), constructing any Agent(...) calls plugins.maybe_enable_from_config() internally — you don’t need to call plugins.enable() yourself. Per-plugin option maps are delivered automatically to each plugin’s on_config(options) hook. See Plugins → Configure from config.yaml for the full per-plugin surface.

[defaults]
# Primary LLM model — used by every agent unless overridden
model = "gpt-4o"

# Cheap/fast auxiliary model for internal LLM calls
# (session-title generation; summarisation/compaction planned).
# When unset, falls back to `model`, then a built-in default.
small_model = "gpt-4o-mini"

# Custom endpoint (for local LLMs)
# base_url = "http://localhost:11434/v1"

# Feature flags
allow_delegation = false
allow_code_execution = false
code_execution_mode = "safe"

defaults:
  model: gpt-4o
  small_model: gpt-4o-mini
  # base_url: http://localhost:11434/v1

small_model is used by PraisonAI for cheap internal LLM calls (currently session-title generation; summarisation/compaction in future). When unset, PraisonAI falls back to your primary model — so single-provider users (Anthropic, Ollama, on-prem) no longer make unexpected OpenAI calls.

[defaults.memory]
enabled = false
backend = "file"  # file, sqlite, redis, postgres, mongodb
auto_memory = false
history = false
history_limit = 10

[defaults.memory.learn]
enabled = false
persona = true
insights = true
patterns = false

[defaults.knowledge]
enabled = false
embedder = "openai"
chunking_strategy = "semantic"
chunk_size = 1000
chunk_overlap = 200
retrieval_k = 5
rerank = false

[defaults.planning]
enabled = false
reasoning = false
auto_approve = false

[defaults.reflection]
enabled = false
min_iterations = 1
max_iterations = 3

[defaults.output]
preset = "silent"  # silent, actions, verbose, json
verbose = false
stream = false
metrics = false

[defaults.execution]
max_iter = 20
max_retry_limit = 2
# retry_initial_delay = 1.0
# retry_backoff_factor = 2.0
# retry_jitter = 0.1

Cheap auxiliary model for internal calls

small_model sets a cheap/fast model for PraisonAI’s internal LLM calls (session-title generation today; summarisation/compaction in future), independent of your agent’s primary model.

Field	Type	Default	Description
`defaults.small_model`	`str` (optional)	`None` (falls back to primary `model`, then `gpt-4o-mini`)	Cheap/fast auxiliary model used for internal LLM calls. Honoured under both `[defaults]` (typed loader) and `[agent]` (CLI/JSON-schema) namespaces of the same config file.

Resolution order for get_small_model(primary_model, fallback):

defaults.small_model (or agent.small_model CLI namespace) — if set.
primary_model — the running agent’s model, if any.
defaults.model (or agent.model) — if set.
fallback — preserves today’s hardcoded gpt-4o-mini when nothing is configured.

Usage Examples

Cheap auxiliary model for internal calls

Use a cheap/fast model for internal work (session titles, summarisation) while keeping a powerful primary model for the agent itself.

# .praisonai/config.toml
[defaults]
model = "gpt-4o"            # primary — used for the agent
small_model = "gpt-4o-mini" # cheap auxiliary — used for internal calls

from praisonaiagents import Agent

# Agent runs on gpt-4o; session titles use gpt-4o-mini automatically.
agent = Agent(
    name="Assistant",
    instructions="Help users"
)

Single-provider setups work the same way:

# Anthropic-only setup — no OpenAI calls anywhere
[defaults]
model = "anthropic/claude-3-5-sonnet-latest"
small_model = "anthropic/claude-3-5-haiku-latest"

# Ollama-only setup — everything runs locally
[defaults]
model = "ollama/llama3.1:70b"
small_model = "ollama/llama3.1:8b"
base_url = "http://localhost:11434/v1"

Explicit Agent(...) kwargs still override the config file, same as model.

Memory with PostgreSQL

# .praisonai/config.toml
[defaults.memory]
enabled = true
backend = "postgres"

[defaults.memory.learn]
enabled = true
persona = true
insights = true

from praisonaiagents import Agent

# memory=True now uses PostgreSQL
agent = Agent(
    name="Assistant",
    instructions="Help users",
    memory=True
)

Knowledge with Reranking

# .praisonai/config.toml
[defaults.knowledge]
enabled = true
embedder = "openai"
retrieval_k = 10
rerank = true
rerank_model = "cohere"

from praisonaiagents import Agent

# knowledge=True uses reranking
agent = Agent(
    name="Researcher",
    instructions="Research topics",
    knowledge=True
)

Verbose Output Mode

# .praisonai/config.toml
[defaults.output]
preset = "verbose"
verbose = true
markdown = true
stream = true

from praisonaiagents import Agent

# All agents now use verbose output by default
agent = Agent(
    name="Assistant",
    instructions="Help users"
)

Local LLM (Ollama)

# .praisonai/config.toml
[defaults]
model = "llama3"
base_url = "http://localhost:11434/v1"

from praisonaiagents import Agent

# Uses local Ollama by default
agent = Agent(
    name="Local Assistant",
    instructions="Help users"
)

Programmatic Access

Access config values programmatically:

from praisonaiagents.config.loader import (
    get_config,
    get_default,
    get_small_model,          # NEW
    get_plugins_config,
    get_plugin_options,
    is_plugins_enabled,
)

# Get entire config
config = get_config()
print(config.plugins.enabled)
print(config.defaults.model)

# Get specific default with fallback
model = get_default("model", "gpt-4o-mini")
memory_backend = get_default("memory.backend", "file")

# Resolve the cheap auxiliary model with fallback chain:
#   defaults.small_model  ->  primary_model  ->  defaults.model  ->  fallback
small = get_small_model(primary_model="gpt-4o", fallback="gpt-4o-mini")
print(small)

# Check plugins status
if is_plugins_enabled():
    print("Plugins are enabled")

# Read per-plugin option maps ({plugin_name: options_dict})
options = get_plugin_options()
print(options.get("pii_guardrail", {}))

Auxiliary / Small Model Resolution

small_model routes PraisonAI’s internal LLM calls — session-title generation today, summarisation and compaction going forward — to a cheap, fast, or local model without changing your agent’s primary model.

# .praisonai/config.yaml
defaults:
  model: gpt-4o          # user-facing quality
  small_model: gpt-4o-mini  # cheap background work

Set small_model to a local model to keep background calls off third-party APIs:

defaults:
  model: gpt-4o
  small_model: ollama/llama3
  base_url: http://localhost:11434/v1

The resolver picks the first available source top to bottom: Precedence: explicit llm_model > defaults.small_model > primary_model > defaults.model > built-in gpt-4o-mini. Resolve the auxiliary model programmatically:

from praisonaiagents.config.loader import get_small_model

# Resolves according to config + primary hint + fallback
model = get_small_model(primary_model="gpt-4o", fallback="gpt-4o-mini")

The CLI/schema namespace agent.small_model reaches the same resolver, so both [defaults] and [agent] in the same config file work.

small_model is fully additive. When it is unset and no primary model is available, the resolver returns gpt-4o-mini — reproducing the previous hardcoded behaviour exactly.

Config Validation

Config files are validated automatically. Invalid keys trigger helpful error messages with suggestions.

from praisonaiagents import validate_config, ConfigValidationError

# Validate a config dict
config = {
    "plugins": {"enabled": True},
    "defaults": {"modell": "gpt-4o"}  # Typo!
}

errors = validate_config(config)
# Output: ["[defaults] Unknown key 'modell'. Did you mean 'model'?"]

# Or raise on error
try:
    validate_config(config, raise_on_error=True)
except ConfigValidationError as e:
    print(e.errors)

Override Precedence

Explicit parameters always override config defaults:

from praisonaiagents import Agent, MemoryConfig

# Config file has: backend = "sqlite"
# But explicit config wins:
agent = Agent(
    name="Assistant",
    instructions="Help users",
    memory=MemoryConfig(backend="postgres")  # Uses postgres, not sqlite
)

Sample Config File

Show Complete config.toml template

# PraisonAI Agents Configuration
# Copy to .praisonai/config.toml

[plugins]
enabled = false
auto_discover = true
directories = ["./.praisonai/plugins/", "~/.praisonai/plugins/"]

[defaults]
model = "gpt-4o"
small_model = "gpt-4o-mini"  # cheap auxiliary model; falls back to `model` when unset
allow_delegation = false
allow_code_execution = false
code_execution_mode = "safe"

[defaults.memory]
enabled = false
backend = "file"
auto_memory = false
history = false
history_limit = 10

[defaults.memory.learn]
enabled = false
persona = true
insights = true
patterns = false

[defaults.knowledge]
enabled = false
embedder = "openai"
chunking_strategy = "semantic"
chunk_size = 1000
retrieval_k = 5
rerank = false

[defaults.planning]
enabled = false
reasoning = false
auto_approve = false

[defaults.reflection]
enabled = false
min_iterations = 1
max_iterations = 3

[defaults.web]
enabled = false
search = true
fetch = true
search_provider = "duckduckgo"
max_results = 5

[defaults.output]
preset = "silent"
verbose = false
stream = false
metrics = false

[defaults.execution]
max_iter = 20
max_retry_limit = 2
# retry_initial_delay = 1.0
# retry_backoff_factor = 2.0
# retry_jitter = 0.1

[defaults.caching]
enabled = true
prompt_caching = false

[defaults.autonomy]
level = "suggest"
escalation_enabled = true
doom_loop_detection = true

Best Practices

Set org-wide defaults, override per agent

Put values every project should share (model, memory backend, output preset) in .praisonai/config.toml, and let explicit Agent(...) parameters override them where a specific agent needs something different. Explicit parameters always win over the file, so the config is a floor, not a cage.

Remember the precedence order

Configuration resolves as Explicit Agent parameter > Environment variable > Config file > Built-in default. When a setting seems ignored, check for a higher-precedence source (an env var like PRAISONAI_PLUGINS=true or an explicit kwarg) before editing the TOML.

Keep the file in version control

Commit .praisonai/config.toml so every teammate and CI run starts from the same defaults. Keep secrets (API keys) in environment variables, not the config file, so the file stays safe to share.

Enable features conservatively

Most feature defaults ship disabled (enabled = false) for a reason — turning on memory, knowledge, or reflection globally adds latency and cost to every agent. Enable them in the config only when the whole project needs them; otherwise flip them on per agent.

Run agents and YAML configs directly from your terminal.

See every field available in YAML agent and task configuration.

Plugins

Auto-enable plugins from [plugins] on Agent init.

Tool Discovery

How Agent resolves tool names at runtime.

​How It Works

Project Config

Root Config

User Global

Environment Override

​Quick Start

​Config File Locations

​Small Model for Cheap Internal Calls

​Full Configuration Reference

​Cheap auxiliary model for internal calls

​Usage Examples

​Programmatic Access

​Auxiliary / Small Model Resolution

​Config Validation

​Override Precedence

​Sample Config File

​Best Practices

​Related

Plugins

Tool Discovery

How It Works

Quick Start

Config File Locations

Small Model for Cheap Internal Calls

Full Configuration Reference

Cheap auxiliary model for internal calls

Usage Examples

Programmatic Access

Auxiliary / Small Model Resolution

Config Validation

Override Precedence

Sample Config File

Best Practices

Related