Parameter Resolution

Comprehensive guide to consolidated parameters, precedence rules, and parsing behavior in PraisonAI Agents

Parameter Resolution

PraisonAI Agents uses a unified parameter resolution system that provides flexible configuration through multiple input types while maintaining predictable precedence rules.

Precedence Rules

Resolution Order (Highest to Lowest)

When multiple configuration sources are provided, the system resolves them in this order:

Priority	Type	Example	Description
1	Instance	`memory=db_instance`	Pre-configured object instance
2	Config	`memory=MemoryConfig(...)`	Explicit configuration object
3	Dict	`memory={"backend": "sqlite"}`	Config shorthand (strict validation)
4	Array	`knowledge=["docs/", "data.pdf"]`	Multiple sources (feature-specific)
5	String	`memory="sqlite"` or `memory="mongodb://..."`	Preset name or URL
6	Bool	`memory=True`	Enable with defaults
7	Default	(not specified)	Feature disabled or default config

User-Friendly Progression

When learning the API, start simple and add complexity as needed:

Bool → String → Array → Dict → Config → Instance

Example progression for memory:

python

# 1. Bool - Just enable it
agent = Agent(instructions="...", memory=True)

# 2. String - Use a preset
agent = Agent(instructions="...", memory="sqlite")

# 3. String - Use a URL
agent = Agent(instructions="...", memory="mongodb://localhost:27017/mydb")

# 4. String URL - Direct connection string
agent = Agent(instructions="...", memory="sqlite:///path/to/memory.db")

# 5. Dict - Config shorthand (strict validation)
agent = Agent(instructions="...", memory={"backend": "chroma"})

# 6. Config - Full control
agent = Agent(instructions="...", memory=MemoryConfig(backend="sqlite"))

# 7. Instance - Pre-configured (Redis/Postgres go through db(url=...))
from praisonaiagents import db
agent = Agent(instructions="...", memory=MemoryConfig(db=db(url="redis://localhost:6379/0")))

Unified Parameter Table

Param	Surfaces	Bool	String	Array	Config Class
`memory`	Agent, Agents	✅ Enable file-based	Preset/URL	`["url"]` (single item only)	`MemoryConfig`
`knowledge`	Agent, Agents	✅ Enable	Path/URL	`[path1, path2]`	`KnowledgeConfig`
`planning`	Agent, Agents	✅ Enable	LLM model	`[model, {opts}]`	`PlanningConfig`
`reflection`	Agent, Agents	✅ Enable	Preset	`[preset, {opts}]`	`ReflectionConfig`
`guardrails`	Agent, Task	✅ Enable	Preset/Prompt	`[preset, {opts}]` or `[policy:x]`	`GuardrailConfig`
`web`	Agent	✅ Enable	Provider	`[provider, mode]`	`WebConfig`
`output`	Agent, Agents	—	Preset	`[preset, {opts}]`	`OutputConfig`
`execution`	Agent, Agents	—	Preset	`[preset, {opts}]`	`ExecutionConfig`
`caching`	Agent	✅ Enable	Preset	—	`CachingConfig`
`context`	Agent	✅ Enable	Preset	`[preset, {opts}]`	`ManagerConfig`
`hooks`	Agent	—	—	`[hook1, hook2]`	`HooksConfig`
`skills`	Agent	—	Path	`[path1, path2]`	`SkillsConfig`

String Parsing Rules

URL Scheme Detection

URLs are automatically detected and parsed:

Scheme	Example	Detected As
`sqlite:///`	`sqlite:///path/to/db.sqlite`	SQLite path
`mongodb://`	`mongodb://localhost:27017/db`	MongoDB URL
`mongodb+srv://`	`mongodb+srv://host/db`	MongoDB URL
`http://`, `https://`	`https://api.example.com`	API endpoint

python

# URL auto-detection
agent = Agent(
    instructions="...",
    memory="mongodb://localhost:27017/praisonai"
)

Path Detection

File and directory paths are detected:

Pattern	Example	Detected As
Ends with `/`	`docs/`	Directory
Contains `/`	`./data/file.pdf`	File path
File extension	`knowledge.pdf`	File

python

# Path detection for knowledge
agent = Agent(
    instructions="...",
    knowledge="docs/"  # Directory of documents
)

Preset Lookup

String values are matched against preset registries:

python

# Memory presets
memory="file"      # File-based memory (default)
memory="sqlite"    # SQLite backend
memory="chroma"    # ChromaDB vector backend

# Output presets (from least to most output)
output="silent"    # Nothing (default for SDK, max performance)
output="status"    # Tool calls + response, no timestamps: ▸ tool → result ✓
output="trace"     # Full trace with timestamps: [HH:MM:SS] ▸ tool [0.2s] ✓
output="debug"     # trace + metrics (no boxes)
output="verbose"   # Rich panels with Markdown
output="stream"    # Real-time token streaming
output="json"      # JSONL events for scripting

# Backward compatible aliases
output="plain"     # → silent
output="minimal"   # → silent
output="normal"    # → verbose
output="text"      # → status
output="actions"   # → status

# Execution presets
execution="fast"   # Optimized for speed
execution="safe"   # Extra validation

# Web presets
web="tavily"       # Tavily search
web="duckduckgo"   # DuckDuckGo search

Error Handling with Typo Suggestions

Invalid values trigger helpful error messages:

python

agent = Agent(instructions="...", execution="fsat")
# Error: Invalid execution value: 'fsat'. Did you mean 'fast'?

Dict Parsing Rules

Config Shorthand

Dicts provide a convenient shorthand for configuration without importing config classes:

python

# Dict shorthand (equivalent to OutputConfig(output="verbose", stream=False))
agent = Agent(
    instructions="...",
    output={"verbose": True, "stream": False}
)

# Dict shorthand for execution
agent = Agent(
    instructions="...",
    execution={"max_iter": 20, "timeout": 300}
)

Strict Validation

Dict keys are strictly validated against the config class fields. Unknown keys raise a clear TypeError:

python

# This will raise an error with helpful message
try:
    agent = Agent(
        instructions="...",
        output={"verbose": True, "invalid_key": "value"}
    )
except TypeError as e:
    print(e)
    # Output: Unknown keys for output: ['invalid_key']. 
    #         Valid keys: verbose, stream, markdown, ...
    #         Example: output={'verbose': True, 'stream': True, ...}

When to Use Dict vs Config

Use Case	Recommended	Example
Quick prototyping	Dict	`output={"verbose": True}`
IDE autocomplete	Config	`output=OutputConfig(output="verbose")`
Dynamic config	Dict	`output=config_from_yaml`
Type safety	Config	`output=OutputConfig(...)`

Note

Important: base_url and api_key are NOT consolidated parameters. They remain separate, explicit parameters on Agent:

python

agent = Agent(
    instructions="...",
    base_url="http://localhost:11434/v1",  # Separate parameter
    api_key="your-key",                     # Separate parameter
)

Array Parsing Rules

Note

Memory Parameter: The memory parameter uses ArrayMode.SINGLE_OR_LIST, which only accepts single-item arrays. For multiple values or preset + overrides, use dict or config object instead.

python

# ❌ This fails for memory parameter
memory=["chroma", {"path": "./db"}]  # Multiple items not allowed

# ✅ Use these instead
memory="sqlite:///path/to/memory.db"          # URL string
memory={"backend": "chroma"}                   # Dict
memory=MemoryConfig(backend="sqlite")          # Config

Preset with Overrides

The most common array pattern combines a preset with custom options:

python

# Pattern: [preset_name, {overrides}]
agent = Agent(
    instructions="...",
    output=["verbose", {"stream": True, "metrics": True}],
    execution=["fast", {"max_iter": 15}],
)

Multiple Sources

For knowledge and skills, arrays can specify multiple sources:

python

# Multiple knowledge sources
agent = Agent(
    instructions="...",
    knowledge=["docs/", "data.pdf"]
)

# Multiple skill directories
agent = Agent(
    instructions="...",
    skills=["./skills/", "./custom_skills/"]
)

Provider with Mode

For web search, arrays can specify provider and mode:

python

# Web search with mode
agent = Agent(
    instructions="...",
    web=["tavily", "search_only"]  # Provider + mode
)

Config Classes Reference

MemoryConfig

python

from praisonaiagents import MemoryConfig

agent = Agent(
    instructions="...",
    memory=MemoryConfig(
        backend="sqlite",
        user_id="alice",
    )
)

Inner precedence: `backend=` vs `config=`

MemoryConfig‘s own two-argument form has its own inner precedence — an explicit provider or backend key inside config= wins; otherwise the outer backend= fills in. The config dict is never mutated.

What you wrote	Backend actually used
`MemoryConfig(backend="sqlite")`	`sqlite`
`MemoryConfig(backend="sqlite", config={"short_db": "…"})`	`sqlite`
`MemoryConfig(backend="sqlite", config={"provider": "file"})`	`file` (inner wins)
`MemoryConfig(backend="sqlite", config={"backend": "file"})`	`file` (inner wins)
`MemoryConfig(backend="file")`	`file`

See Memory → Combining backend and config.

KnowledgeConfig

python

from praisonaiagents import KnowledgeConfig

agent = Agent(
    instructions="...",
    knowledge=KnowledgeConfig(
        sources=["docs/", "data.pdf"],
        chunk_size=1000,
        chunk_overlap=200,
        embedder="openai",
    )
)

OutputConfig

python

from praisonaiagents import OutputConfig

agent = Agent(
    instructions="...",
    output=OutputConfig(
        output="verbose",
        markdown=True,
        stream=True,
        metrics=True,
        reasoning_steps=False,
    )
)

ExecutionConfig

python

from praisonaiagents import ExecutionConfig

agent = Agent(
    instructions="...",
    execution=ExecutionConfig(
        max_iter=10,
        timeout=300,
        retry_on_error=True,
        max_retries=3,
    )
)

WebConfig

python

from praisonaiagents import WebConfig

agent = Agent(
    instructions="...",
    web=WebConfig(
        provider="tavily",
        api_key_env="TAVILY_API_KEY",
        max_results=5,
    )
)

PlanningConfig

python

from praisonaiagents import PlanningConfig

agent = Agent(
    instructions="...",
    planning=PlanningConfig(
        enabled=True,
        llm="gpt-4o-mini",
        reasoning=True,
    )
)

ReflectionConfig

python

from praisonaiagents import ReflectionConfig

agent = Agent(
    instructions="...",
    reflection=ReflectionConfig(
        enabled=True,
        max_iterations=3,
        threshold=0.8,
    )
)

GuardrailConfig

python

from praisonaiagents import GuardrailConfig

agent = Agent(
    instructions="...",
    guardrails=GuardrailConfig(
        input_guardrails="Validate input is safe",
        output_guardrails="Ensure output is appropriate",
        max_retries=3,
    )
)

Performance Considerations

O(1) Happy Path

The resolver is optimized for the common case:

Bool/None: Immediate return (no parsing)
Instance: Type check only
Config: Direct use
String preset: Dictionary lookup

Expensive Operations (Error Path Only)

These only run when validation fails:

Typo suggestion (Levenshtein distance calculation)
URL scheme parsing
Path validation

API Consistency Matrix

PraisonAI uses consolidated parameters that are consistent across all major classes. This enables a unified API where features work the same way regardless of which class you use.

Consolidated Parameters

Parameter	Agent	AgentFlow	AgentTeam	Task	Notes
`autonomy`	✅	✅	✅	✅	Agent decision-making autonomy
`caching`	✅	✅	✅	✅	Response caching
`context`	✅	✅	✅	✅	Context management
`execution`	✅	✅	✅	✅	Execution settings (max_iter, timeout)
`guardrails`	✅	✅	✅	✅	Input/output validation
`hooks`	✅	✅	✅	✅	Lifecycle event hooks
`knowledge`	✅	✅	✅	✅	RAG/knowledge base
`llm`	✅	✅	✅	—	Default LLM model (Task uses `agent.llm`)
`memory`	✅	✅	✅	✅	Persistent memory
`name`	✅	✅	✅	✅	Identifier name
`output`	✅	✅	✅	—	Output configuration (Task uses `output_config`)
`planning`	✅	✅	✅	✅	Task planning/reasoning
`reflection`	✅	✅	✅	✅	Self-reflection
`web`	✅	✅	✅	✅	Web search/fetch

Config Classes by Feature

Feature	Config Class	Agent	AgentTeam	AgentFlow	Task
Memory	`MemoryConfig`	✅	✅	✅	✅
Knowledge	`KnowledgeConfig`	✅	✅	✅	✅
Planning	`PlanningConfig`	✅	✅	✅	✅
Reflection	`ReflectionConfig`	✅	✅	✅	✅
Guardrails	`GuardrailConfig`	✅	✅	✅	✅
Web	`WebConfig`	✅	✅	✅	✅
Output	`OutputConfig`	✅	✅	✅	—
Execution	`ExecutionConfig`	✅	✅	✅	✅
Caching	`CachingConfig`	✅	✅	✅	✅
Context	`ManagerConfig`	✅	✅	✅	✅
Autonomy	`AutonomyConfig`	✅	✅	✅	✅
Hooks	`HooksConfig`	✅	✅	✅	✅
Skills	`SkillsConfig`	✅	—	—	—
Templates	`TemplateConfig`	✅	—	—	—
Learning	`LearnConfig`	✅	—	—	—

Import Patterns

One-Line Imports

python

from praisonaiagents import (
    Agent,
    Agents,
    Task,
    MemoryConfig,
    KnowledgeConfig,
    OutputConfig,
    ExecutionConfig,
)

Resolver Utilities (Advanced)

python

from praisonaiagents import (
    resolve,
    ArrayMode,
    OUTPUT_PRESETS,
    EXECUTION_PRESETS,
    MEMORY_PRESETS,
)

Parameter Resolution