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": "redis"}`	Config shorthand (strict validation)
4	Array	`knowledge=["docs/", "data.pdf"]`	Multiple sources (feature-specific)
5	String	`memory="redis"` or `memory="postgresql://..."`	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:

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

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

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

# 4. String URL - Direct connection string 
agent = Agent(instructions="...", memory="redis://localhost:6379")

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

# 6. Config - Full control
agent = Agent(instructions="...", memory=MemoryConfig(backend="redis", config={"port": 6380}))

# 7. Instance - Pre-configured
db = create_memory_backend("redis", port=6380)
agent = Agent(instructions="...", memory=db)

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
`postgresql://`	`postgresql://user:pass@host:5432/db`	Database URL
`redis://`	`redis://localhost:6379`	Redis URL
`sqlite:///`	`sqlite:///path/to/db.sqlite`	SQLite path
`mongodb://`	`mongodb://localhost:27017/db`	MongoDB URL
`http://`, `https://`	`https://api.example.com`	API endpoint

# URL auto-detection
agent = Agent(
    instructions="...",
    memory="postgresql://postgres:password@localhost:5432/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

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

Preset Lookup

String values are matched against preset registries:

# Memory presets
memory="file"      # File-based memory
memory="redis"     # Redis backend
memory="postgres"  # PostgreSQL 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:

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:

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

# 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(...)`

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

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

Array Parsing Rules

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.

# ❌ This fails for memory parameter
memory=["redis", {"port": 6380}]  # Multiple items not allowed

# ✅ Use these instead
memory="redis://localhost:6380"   # URL string
memory={"backend": "redis", "config": {"port": 6380}}  # Dict
memory=MemoryConfig(backend="redis", config={"port": 6380})  # Config

Preset with Overrides

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

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

# Multiple knowledge sources
agent = Agent(
    instructions="...",
    knowledge=["docs/", "data.pdf", "https://example.com/api"]
)

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

Provider with Mode

For web search, arrays can specify provider and mode:

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

Config Classes Reference

MemoryConfig

from praisonaiagents import MemoryConfig

agent = Agent(
    instructions="...",
    memory=MemoryConfig(
        backend="redis",
        config={
            "host": "localhost",
            "port": 6379,
            "db": 0,
            "ttl": 3600,
        }
    )
)

KnowledgeConfig

from praisonaiagents import KnowledgeConfig

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

OutputConfig

from praisonaiagents import OutputConfig

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

ExecutionConfig

from praisonaiagents import ExecutionConfig

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

WebConfig

from praisonaiagents import WebConfig

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

PlanningConfig

from praisonaiagents import PlanningConfig

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

ReflectionConfig

from praisonaiagents import ReflectionConfig

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

GuardrailConfig

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

Task Design: Task intentionally lacks llm and output because it delegates to an Agent which holds these settings. Use task.agent.llm for the LLM and output_config for output settings.

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

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

Resolver Utilities (Advanced)

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

​Parameter Resolution

​Precedence Rules

​Resolution Order (Highest to Lowest)

​User-Friendly Progression

​Unified Parameter Table

​String Parsing Rules

​URL Scheme Detection

​Path Detection

​Preset Lookup

​Error Handling with Typo Suggestions

​Dict Parsing Rules

​Config Shorthand

​Strict Validation

​When to Use Dict vs Config

​Array Parsing Rules

​Preset with Overrides

​Multiple Sources

​Provider with Mode

​Config Classes Reference

​MemoryConfig

​KnowledgeConfig

​OutputConfig

​ExecutionConfig

​WebConfig

​PlanningConfig

​ReflectionConfig

​GuardrailConfig

​Performance Considerations

​O(1) Happy Path

​Expensive Operations (Error Path Only)

​API Consistency Matrix

​Consolidated Parameters

​Config Classes by Feature

​Import Patterns

​One-Line Imports

​Resolver Utilities (Advanced)

​See Also