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

# 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": "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`:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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        |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Path detection for knowledge
agent = Agent(
    instructions="...",
    knowledge="docs/"  # Directory of documents
)
```

### Preset Lookup

String values are matched against preset registries:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  agent = Agent(
      instructions="...",
      base_url="http://localhost:11434/v1",  # Separate parameter
      api_key="your-key",                     # Separate parameter
  )
  ```
</Note>

## 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # ❌ 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
  ```
</Note>

### Preset with Overrides

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Web search with mode
agent = Agent(
    instructions="...",
    web=["tavily", "search_only"]  # Provider + mode
)
```

## Config Classes Reference

### MemoryConfig

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

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

### KnowledgeConfig

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

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

### OutputConfig

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

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

### ExecutionConfig

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

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

### WebConfig

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

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

### PlanningConfig

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

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

### ReflectionConfig

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

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

### GuardrailConfig

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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                                 |

<Note>
  **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.
</Note>

### 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import (
    Agent,
    Agents,
    Task,
    MemoryConfig,
    KnowledgeConfig,
    OutputConfig,
    ExecutionConfig,
)
```

### Resolver Utilities (Advanced)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import (
    resolve,
    ArrayMode,
    OUTPUT_PRESETS,
    EXECUTION_PRESETS,
    MEMORY_PRESETS,
)
```

## See Also

* [Agent Reference](/docs/sdk/praisonaiagents/agent/agent) - Core Agent class
* [Agents Reference](/docs/sdk/praisonaiagents/agents/agents) - Multi-agent orchestration
* [Memory](/docs/concepts/memory) - Memory configuration details
* [Knowledge](/docs/rag/quickstart) - RAG and knowledge base setup