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

# Agent Module

> Documentation for the praisonaiagents.agent.agent module

# Agent

The core class for AI agents with tools, memory, knowledge, and handoffs.

## Param Cluster Map

| Cluster | Legacy Params | Consolidated To | Status |
| - | - | - | - |
| Output | `verbose`, `markdown`, `stream`, `metrics`, `reasoning_steps` | `output=` | ✅ |
| Execution | `max_iter`, `max_rpm`, `max_execution_time`, `max_retry_limit`, `retry_initial_delay`, `retry_backoff_factor`, `retry_jitter` | `execution=` | ✅ |
| Memory | `memory`, `auto_memory`, `claude_memory`, `user_id`, `session_id`, `db` | `memory=` | ✅ |
| Knowledge | `knowledge`, `retrieval_config`, `embedder_config` | `knowledge=` | ✅ |
| Planning | `planning`, `plan_mode`, `planning_tools`, `planning_reasoning` | `planning=` | ✅ |
| Reflection | `self_reflect`, `max_reflect`, `min_reflect`, `reflect_llm` | `reflection=` | ✅ |
| Guardrails | `guardrail`, `max_guardrail_retries`, `policy` | `guardrails=` | ✅ |
| Web | `web_search`, `web_fetch` | `web=` | ✅ |
| Templates | `system_template`, `prompt_template`, `response_template` | `templates=` | ✅ |
| Caching | `cache`, `prompt_caching` | `caching=` | ✅ |
| LLM | `llm`, `llm_config`, `function_calling_llm` | `llm=` | ✅ |

**Note:** `base_url` and `api_key` remain **separate** (connection/auth constraint).

## Precedence Ladder

`Instance > Config > Array > Dict > String > Bool > Default`

## Quick Start

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

agent = Agent(instructions="You are a helpful assistant")
response = agent.start("Hello!")
```

## Parameters Table

### Core Identity

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | `None` | Agent name for identification |
| `role` | `str` | `None` | Role/job title defining expertise |
| `goal` | `str` | `None` | Primary objective |
| `backstory` | `str` | `None` | Background context |
| `instructions` | `str` | `None` | 💡 **Canonical** - Direct instructions (overrides role/goal/backstory) |

### LLM Configuration

| Parameter | Type | Default | Description |
| - | - | - | - |
| `llm` | `str \| Any` | `None` | ✅ Model name (`"gpt-4o"`) or LLM object |
| `model` | `str \| Any` | `None` | ✅ **Alias** for `llm=` |
| `base_url` | `str` | `None` | Custom endpoint URL (kept separate) |
| `api_key` | `str` | `None` | API key (kept separate) |
| `function_calling_llm` | `Any` | `None` | ⚠️ **Deprecated** - use `llm=` |
| `llm_config` | `Dict` | `None` | ⚠️ **Deprecated** - use `llm=` |

### Tools & Capabilities

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tools` | `List[Any]` | `None` | Tools, functions, or MCP instances |
| `handoffs` | `List[Agent \| Handoff]` | `None` | Agents for task delegation |
| `allow_delegation` | `bool` | `False` | ⚠️ **Deprecated** — use `handoffs=` |
| `allow_code_execution` | `bool` | `False` | ⚠️ **Deprecated** — use `execution=ExecutionConfig(code_execution=True)` |
| `code_execution_mode` | `"safe" \| "unsafe"` | `"safe"` | ⚠️ **Deprecated** — use `execution=ExecutionConfig(code_mode=)` |

### Deprecated Standalone Params

These still work for backward compatibility but emit `DeprecationWarning`. Use the consolidated config objects instead.

| Parameter | Type | Default | Replacement |
| - | - | - | - |
| `auto_save` | `str` | `None` | `memory=MemoryConfig(auto_save="name")` |
| `rate_limiter` | `Any` | `None` | `execution=ExecutionConfig(rate_limiter=obj)` |
| `verification_hooks` | `List[VerificationHook]` | `None` | `autonomy=AutonomyConfig(verification_hooks=[...])` |

### Consolidated Feature Params

Each follows: `False`=disabled, `True`=defaults, `Config`=custom

| Parameter | Type | Default | Description |
| - | - | - | - |
| `memory` | `bool \| MemoryConfig` | `None` | Memory system |
| `knowledge` | `bool \| List[str] \| KnowledgeConfig` | `None` | Knowledge sources |
| `planning` | `bool \| PlanningConfig` | `False` | Planning mode |
| `reflection` | `bool \| ReflectionConfig` | `None` | Self-reflection |
| `guardrails` | `bool \| Callable \| GuardrailConfig` | `None` | Output validation |
| `web` | `bool \| WebConfig` | `None` | Web search/fetch |
| `context` | `bool \| ContextConfig` | `False` | Context management |
| `autonomy` | `bool \| Dict \| AutonomyConfig` | `None` | Autonomy settings |
| `output` | `str \| OutputConfig` | `None` | Output preset or config |
| `execution` | `str \| ExecutionConfig` | `None` | Execution preset or config |
| `caching` | `bool \| CachingConfig` | `None` | Caching settings |
| `hooks` | `List \| HooksConfig` | `None` | Event hooks |
| `skills` | `List[str] \| SkillsConfig` | `None` | Agent skills |
| `templates` | `TemplateConfig` | `None` | Template configuration |

## Precedence Ladder

> [!NOTE]
>
> **Resolution Order**: Instance > Config > Array > Dict > String > Bool > Default
>
> When you pass a consolidated param, the resolver checks in this order:
>
> 1. **Instance** - Already a config object? Use as-is
> 2. **Config** - Dataclass instance? Use as-is
> 3. **Array** - `["preset", {"override": value}]`? Apply overrides
> 4. **Dict** - `{"key": value}`? Convert to config
> 5. **String** - `"preset_name"` or URL? Look up preset or parse URL
> 6. **Bool** - `True`? Use defaults. `False`? Disable
> 7. **Default** - `None`? Use default value

## Usage Forms Table

| Form | Example | When to Use |
| - | - | - |
| **Bool** | `memory=True` | Enable with defaults |
| **String preset** | `output="verbose"` | Use predefined config |
| **URL** | `memory="mongodb://localhost:27017"` | Backend-specific config |
| **Dict** | `memory={"backend": "mongodb"}` | Custom config as dict |
| **Array + overrides** | `output=["verbose", {"stream": False}]` | Preset + customization |
| **Config instance** | `memory=MemoryConfig(backend="sqlite")` | Full control |

### Examples for Each Form

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Bool - enable with defaults
agent = Agent(instructions="...", memory=True)

# String preset
agent = Agent(instructions="...", output="verbose")

# URL scheme
agent = Agent(instructions="...", memory="mongodb://localhost:27017")

# Dict
agent = Agent(instructions="...", memory={"backend": "mongodb", "user_id": "u1"})

# Array with overrides
agent = Agent(instructions="...", output=["verbose", {"stream": False}])

# Config instance
from praisonaiagents import MemoryConfig
agent = Agent(instructions="...", memory=MemoryConfig(backend="sqlite"))
```

> [!NOTE]
>
> For Redis/Postgres, use `memory=MemoryConfig(db=db(url=...))` — see [Redis persistence](https://praison.ai/docs/features/persistence-redis.md). `MemoryConfig(backend="redis")` now raises a `ValueError`.

## Presets & Options

### Output Presets

| Preset | Description | Example |
| - | - | - |
| `"silent"` | Zero output (default) | — |
| `"status"` | Tool calls + response, no timestamps | `▸ get_weather → Sunny ✓` |
| `"trace"` | Full trace with timestamps | `[14:30:29] ▸ get_weather → Sunny [0.2s] ✓` |
| `"debug"` | trace + metrics (no boxes) | Timestamps + token counts, cost |
| `"verbose"` | Rich panels with Markdown | Task + Response panels |
| `"stream"` | Real-time token streaming | Tokens appear as generated |
| `"json"` | JSONL events | `{"event": "tool_call", ...}` |

**Aliases:** `"text"`, `"actions"` → `"status"` | `"plain"`, `"minimal"` → `"silent"` | `"normal"` → `"verbose"`

### Execution Presets

| Preset | max\_iter | max\_retry\_limit |
| - | - | - |
| `"fast"` | 10 | 1 |
| `"balanced"` | 20 | 2 |
| `"thorough"` | 50 | 5 |
| `"unlimited"` | 1000 | 10 |

### Memory Presets

| Preset | Backend |
| - | - |
| `"file"` | Local file storage (default) |
| `"sqlite"` | SQLite database |
| `"chroma"` | ChromaDB vector store |
| `"mem0"` | Mem0 service |
| `"mongodb"` | MongoDB |
| `"dakera"` | Dakera memory server |
| `"in_memory"` | In-process store |

### Web Presets

| Preset | search | fetch | provider |
| - | - | - | - |
| `"duckduckgo"` | ✅ | ✅ | DuckDuckGo |
| `"tavily"` | ✅ | ✅ | Tavily |
| `"google"` | ✅ | ✅ | Google |
| `"search_only"` | ✅ | ❌ | Default |
| `"fetch_only"` | ❌ | ✅ | Default |

### Reflection Presets

| Preset | min\_iterations | max\_iterations |
| - | - | - |
| `"minimal"` | 1 | 1 |
| `"standard"` | 1 | 3 |
| `"thorough"` | 2 | 5 |

### Guardrail Presets

| Preset | max\_retries | on\_fail |
| - | - | - |
| `"strict"` | 5 | raise |
| `"permissive"` | 1 | skip |
| `"safety"` | 3 | retry |

## Methods

### Execution Methods

| Method | Streams by Default | Display | Use Case |
| - | - | - | - |
| `start(prompt, **kwargs)` | ✅ Yes (in TTY) | ✅ Auto | Interactive/terminal use |
| `run(prompt, **kwargs)` | ❌ No | ❌ No | Production/scripted use |
| `iter_stream(prompt, **kwargs)` | ✅ Always | ❌ No | App integration (yields chunks) |
| `chat(prompt, ...)` | Configurable | Configurable | Low-level execution |

### Async Execution Methods

| Method | Streams by Default | Use Case |
| - | - | - |
| `astart(prompt, **kwargs)` | ✅ Yes (in TTY) | Async interactive |
| `arun(prompt, **kwargs)` | ❌ No | Async production |
| `achat(prompt, ...)` | Configurable | Async low-level |

### Other Methods

| Method | Description |
| - | - |
| `query(question, **kwargs)` | Query knowledge base (RAG) |
| `retrieve(query, **kwargs)` | Retrieve context from knowledge |
| `clear_history()` | Clear chat history |
| `execute_tool(name, args)` | Execute a tool dynamically |

### Class Methods

| Method | Description |
| - | - |
| `from_template(uri, config, offline, **kwargs)` | Create agent from template |

## Common Recipes

### Simple Agent with Instructions

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

agent = Agent(
    name="Assistant",
    instructions="You are a helpful AI assistant that provides concise, accurate answers."
)
response = agent.start("What is the capital of France?")
print(response)
```

### Agent with Tools

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

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Weather in {city}: Sunny, 22°C"

agent = Agent(
    name="Weather Assistant",
    instructions="Help users check the weather",
    tools=[get_weather]
)
response = agent.start("What's the weather in Paris?")
```

### Agent with Handoffs

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

billing_agent = Agent(name="Billing", instructions="Handle billing inquiries")
tech_agent = Agent(name="Tech Support", instructions="Solve technical issues")

main_agent = Agent(
    name="Customer Service",
    instructions="Route customers to the right department",
    handoffs=[billing_agent, tech_agent]
)
response = main_agent.start("I have a billing question")
```

### Agent with Knowledge Base

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

agent = Agent(
    name="Research Assistant",
    instructions="Answer questions using the knowledge base",
    knowledge=["research_papers/", "data.pdf"]
)
response = agent.start("Summarize the key findings")
```

### Agent with Streaming

Choose the right method based on your use case:

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

agent = Agent(
    name="Story Writer",
    instructions="Write creative stories"
)

# Method 1: start() - streams automatically in terminal (TTY)
# Best for interactive/beginner use
for chunk in agent.start("Write a short story"):
    print(chunk, end="", flush=True)

# Method 2: iter_stream() - always streams, no display
# Best for app integration
full_response = ""
for chunk in agent.iter_stream("Write a short story"):
    full_response += chunk
    # Custom processing here

# Method 3: run() - silent, returns result directly
# Best for production/scripted use
result = agent.run("Write a short story")
print(result)

# Method 2: Use any preset + stream=True in start() (per-call control)
agent = Agent(
    name="Story Writer",
    instructions="Write creative stories",
    output="verbose"  # Any preset
)

for chunk in agent.start("Write a short story", stream=True):
    print(chunk, end="", flush=True)

# Method 3: Silent streaming (no verbose output, clean stream)
agent = Agent(
    name="Writer",
    instructions="You are concise",
    output="silent"
)

for chunk in agent.start("Write a haiku", stream=True):
    print(chunk, end="", flush=True)

# Method 4: Collect full response while streaming
chunks = []
for chunk in agent.start("List 3 tips"):
    chunks.append(chunk)
    print(chunk, end="", flush=True)
full_response = "".join(chunks)
```

> [!NOTE]
>
> **Streaming Precedence**: `start(stream=True/False)` overrides `OutputConfig.stream`.
>
> * `output="stream"` sets `stream=True` by default
> * `start(stream=False)` can disable streaming even with `output="stream"`
> * `start(stream=True)` enables streaming for any preset

> [!WARNING]
>
> **When to use which method:**
>
> * **`output="stream"`**: Agent always streams, no per-call control needed
> * **`start(stream=True)`**: Control streaming per-call, useful for conditional streaming
> * **`output="silent"` + `stream=True`**: Clean streaming without agent status messages

### Agent with Custom LLM

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

# Using Ollama
agent = Agent(
    name="Local Assistant",
    instructions="You are a helpful assistant",
    llm="ollama/llama3",
    base_url="http://localhost:11434"
)

# Using Anthropic
agent = Agent(
    name="Claude Assistant",
    instructions="You are a helpful assistant",
    llm="anthropic/claude-3-sonnet-20240229"
)
```

### Agent with Consolidated Config

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

agent = Agent(
    name="Advanced Agent",
    instructions="You are an advanced assistant",
    output="verbose",           # Output preset
    execution="thorough",       # Execution preset
    memory=True,                # Enable memory with defaults
    planning=True,              # Enable planning mode
    reflection=True,            # Enable self-reflection
)
```

## Async Support

The Agent class provides full async support:

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

async def main():
    agent = Agent(
        name="AsyncAgent",
        instructions="Handle async operations efficiently"
    )
    
    # Async chat
    result = await agent.achat("Process this request")
    print(result)
    
    # Async start
    result = await agent.astart("Another request")
    print(result)

asyncio.run(main())
```

## Multi-Agent Safe

Agents are designed to be multi-agent safe. Each agent maintains its own:

* Chat history
* Memory instance
* Knowledge base
* Session state

Multiple agents can run concurrently without interference.

## See Also

* [Agents Module](https://praison.ai/docs/sdk/praisonaiagents/agents/agents.md) - Multi-agent orchestration
* [Handoff Module](https://praison.ai/docs/sdk/praisonaiagents/handoff/handoff.md) - Agent-to-agent handoffs
* [Tools Module](https://praison.ai/docs/sdk/praisonaiagents/tools/tools.md) - Tool system
* [Memory Module](https://praison.ai/docs/sdk/praisonaiagents/memory/memory.md) - Memory management
* [Knowledge Module](https://praison.ai/docs/sdk/praisonaiagents/knowledge/knowledge.md) - Knowledge bases


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.