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

# Legacy Agent Parameters

> Move from the 7 deprecated Agent() params to the config-object API

The `Agent()` constructor still accepts seven older parameters; each has a `Config` replacement that groups related settings.

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

# Old (still works, emits DeprecationWarning)
agent = Agent(name="coder", allow_code_execution=True, code_execution_mode="safe")

# New (preferred)
agent = Agent(
    name="coder",
    execution=ExecutionConfig(code_execution=True, code_mode="safe"),
)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Legacy → Config"
        A[allow_delegation=True] --> B[handoffs=...]
        C[allow_code_execution=True] --> D[execution=ExecutionConfig]
        E[auto_save=name] --> F[memory=MemoryConfig]
        G[verification_hooks=...] --> H[autonomy=AutonomyConfig]
        I[cli_backend=...] --> J[runtime=...]
    end

    classDef old fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef new fill:#10B981,stroke:#7C90A0,color:#fff

    class A,C,E,G,I old
    class B,D,F,H,J new
```

## Quick Start

**1. Find the old params**

Scan your code for any of the seven deprecated names:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
grep -E 'allow_delegation|allow_code_execution|code_execution_mode|auto_save|rate_limiter|verification_hooks|cli_backend|tool_timeout|tool_retry_policy'
```

**2. Look up the replacement**

Match each name to its config object in the migration table below.

**3. Swap the kwarg for the config object**

The behaviour is identical — the config form just groups related settings.

***

## Migration Table

Each deprecated param maps to one config-object replacement.

| Deprecated param | Old default | Replacement (public API) |
| - | - | - |
| `allow_delegation` | `False` | `handoffs=[...]` |
| `allow_code_execution` | `False` | `execution=ExecutionConfig(code_execution=True)` |
| `code_execution_mode` | `"safe"` | `execution=ExecutionConfig(code_mode="safe")` (or `"unsafe"`) |
| `auto_save` | `None` | `memory=MemoryConfig(auto_save="name")` |
| `rate_limiter` | `None` | `execution=ExecutionConfig(rate_limiter=obj)` |
| `verification_hooks` | `None` | `autonomy=AutonomyConfig(verification_hooks=[...])` |
| `cli_backend` | `None` | `runtime=...` (see [Runtime](https://praison.ai/docs/features/runtime.md)) |
| `llm` | — | `model=...` (canonical); `llm=` is a deprecated alias, passing both raises `TypeError` |
| `retrieval_config` | `None` | **No 1:1 replacement** — stays on `Agent(retrieval_config=...)` and resolves through `knowledge=` (see below) |

### retrieval\_config stays on Agent

`retrieval_config` is accepted directly on `Agent(...)` — it is **not** being migrated to a sub-config. It takes a dict or a `RetrievalConfig` instance and tunes retrieval on top of whatever `knowledge=` derived.

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

# dict — merges over the knowledge= config
agent = Agent(name="A", instructions="…", knowledge=["doc.pdf"], retrieval_config={"top_k": 5})

# instance — replaces the derived config wholesale
agent = Agent(name="A", instructions="…", retrieval_config=RetrievalConfig(top_k=5))
```

> [!NOTE]
>
> See [RAG → Pass retrieval tuning directly to `Agent`](https://praison.ai/docs/features/rag#pass-retrieval-tuning-directly-to-agent) for the merge-vs-replace rules and the full field table.

### llm → model

`model=` is the canonical name on every agent class (`Agent`, `AgentTeam`, `AgentFlow`, `VisionAgent`, `AudioAgent`, `OCRAgent`, `VideoAgent`, `EmbeddingAgent`, `ImageAgent`, `ContextAgent`, `CodeAgent`, `RealtimeAgent`). `llm=` is a deprecated alias for it. Passing both raises `TypeError`.

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="Assistant", llm="gpt-4o")
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="Assistant", model="gpt-4o")
> ```

> [tab] Refused
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # TypeError: Agent() received both llm= and model=. They are the same
> #   parameter, so passing both is ambiguous. Pass only one; model= is
> #   the canonical name (llm= is a deprecated alias).
> agent = Agent(name="Assistant", llm="gpt-4o", model="gpt-3.5-turbo")
> ```

> [!NOTE]
>
> See [Model Parameter](https://praison.ai/docs/features/model-parameter.md) for the full rule and the list of classes it applies to.

### allow\_delegation → handoffs

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> other = Agent(name="specialist")
> agent = Agent(name="router", allow_delegation=True)
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> other = Agent(name="specialist")
> agent = Agent(name="router", handoffs=[other])
> ```

### allow\_code\_execution + code\_execution\_mode → execution

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(
>     name="coder",
>     allow_code_execution=True,
>     code_execution_mode="safe",
> )
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, ExecutionConfig
>
> agent = Agent(
>     name="coder",
>     execution=ExecutionConfig(code_execution=True, code_mode="safe"),
> )
> ```

### auto\_save → memory

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="assistant", auto_save="session")
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, MemoryConfig
>
> agent = Agent(name="assistant", memory=MemoryConfig(auto_save="session"))
> ```

### rate\_limiter → execution

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="worker", rate_limiter=my_limiter)
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, ExecutionConfig
>
> agent = Agent(name="worker", execution=ExecutionConfig(rate_limiter=my_limiter))
> ```

### verification\_hooks → autonomy

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="auditor", verification_hooks=[check_output])
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, AutonomyConfig
>
> agent = Agent(name="auditor", autonomy=AutonomyConfig(verification_hooks=[check_output]))
> ```

### cli\_backend → runtime

> [tab] Old
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="cli-agent", cli_backend="claude-code")
> ```

> [tab] New
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="cli-agent", runtime="claude-code")
> ```

***

## What Else Changed

Two related rules make constructor mistakes fail fast instead of silently.

**Keyword-only after `toolsets=`.** `handoffs=` and every `Config` param must be passed by name. A stray positional past `toolsets` no longer binds to `handoffs=` by accident.

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

# TypeError — stray positional past toolsets cannot misbind to handoffs=
Agent("n", "r", "g", "b", "i", None, None, None, None, None, None, None, True)
```

**Unknown kwargs now raise `TypeError`.** Typos fail loudly.

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

# TypeError: Agent.__init__() got unexpected keyword argument(s): totally_unknown
Agent(name="x", totally_unknown=1)
```

The visible signature shrank from 48 to 41 params. No public param was removed — only their documentation surface.

***

## Rejected `Agent(...)` kwargs → what to use instead

`Agent(...)` rejects these kwargs — pass them on the sub-config instead.

Land here after seeing this error:

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
TypeError: Agent.__init__() got unexpected keyword argument(s): session_id
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[🤖 Agent] -->|session_id| M[💾 memory=MemoryConfig]
    Agent -->|user_id| M
    Agent -->|db| M
    Agent -->|prompt_caching| C[⚙️ caching=CachingConfig]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef mem fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef cache fill:#6366F1,stroke:#7C90A0,color:#fff

    class Agent agent
    class M mem
    class C cache
```

The dict shorthand `memory={"session_id": "…"}` is accepted as shorthand for `MemoryConfig` — use it in the Quick Start of any new example.

| Rejected on `Agent(...)` | Error | Correct spelling |
| - | - | - |
| `Agent(session_id="my-session")` | `TypeError: ... session_id` | `Agent(memory={"session_id": "my-session"})` or `Agent(memory=MemoryConfig(session_id="my-session"))` |
| `Agent(user_id="alice")` | `TypeError: ... user_id` | `Agent(memory=MemoryConfig(user_id="alice"))` |
| `Agent(db="postgresql://…")` | `TypeError: ... db` | `Agent(memory=MemoryConfig(session_id="…", db="postgresql://…"))` — or `MemoryConfig(db=db.PostgresDB(...))` for the optional `praisonai` wrapper |
| `Agent(prompt_caching=True)` | `TypeError: ... prompt_caching` | `Agent(caching=CachingConfig(prompt_caching=True))` |
| `Agent(tool_timeout=30)` | `TypeError: ... tool_timeout` (with migration hint) | `Agent(tool_config=ToolConfig(timeout=30))` |
| `Agent(tool_retry_policy=RetryPolicy(...))` | `TypeError: ... tool_retry_policy` (with migration hint) | `Agent(tool_config=ToolConfig(retry_policy=RetryPolicy(...)))` |

### tool\_timeout → tool\_config

> [tab] Rejected
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # TypeError: Agent.__init__() got an unexpected keyword argument 'tool_timeout'
> #   tool_timeout: tool timeout moved into tool_config=; use
> #     tool_config=ToolConfig(timeout=...).
> agent = Agent(name="Assistant", tool_timeout=30)
> ```

> [tab] Correct
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, ToolConfig
>
> agent = Agent(name="Assistant", tool_config=ToolConfig(timeout=30))
> ```

### tool\_retry\_policy → tool\_config

> [tab] Rejected
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
> from praisonaiagents.tools import RetryPolicy
>
> # TypeError: Agent.__init__() got an unexpected keyword argument 'tool_retry_policy'
> #   tool_retry_policy: tool retry moved into tool_config=; use
> #     tool_config=ToolConfig(retry_policy=RetryPolicy(...)).
> agent = Agent(name="Assistant", tool_retry_policy=RetryPolicy())
> ```

> [tab] Correct
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, ToolConfig
> from praisonaiagents.tools import RetryPolicy
>
> agent = Agent(
>     name="Assistant",
>     tool_config=ToolConfig(retry_policy=RetryPolicy()),
> )
> ```

### session\_id → memory

> [tab] Rejected
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # TypeError: Agent.__init__() got unexpected keyword argument(s): session_id
> agent = Agent(name="Assistant", session_id="my-session")
> ```

> [tab] Correct
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> agent = Agent(name="Assistant", memory={"session_id": "my-session"})
> ```

### user\_id → memory

> [tab] Rejected
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # TypeError: Agent.__init__() got unexpected keyword argument(s): user_id
> agent = Agent(name="Assistant", user_id="alice")
> ```

> [tab] Correct
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, MemoryConfig
>
> agent = Agent(name="Assistant", memory=MemoryConfig(user_id="alice"))
> ```

### db → memory

> [tab] Rejected
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # TypeError: Agent.__init__() got unexpected keyword argument(s): db
> agent = Agent(name="Assistant", db="postgresql://user:pass@localhost/mydb")
> ```

> [tab] Correct (URL)
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, MemoryConfig
>
> agent = Agent(
>     name="Assistant",
>     memory=MemoryConfig(
>         session_id="user-123-main",
>         db="postgresql://user:pass@localhost/mydb",
>     ),
> )
> ```

> [tab] Correct (wrapper)
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, MemoryConfig, db
>
> agent = Agent(
>     name="Assistant",
>     memory=MemoryConfig(
>         session_id="user-123-main",
>         db=db.PostgresDB(host="localhost", user="user", password="pass", database="mydb"),
>     ),
> )
> ```

### prompt\_caching → caching

> [tab] Rejected
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # TypeError: Agent.__init__() got unexpected keyword argument(s): prompt_caching
> agent = Agent(name="Assistant", prompt_caching=True)
> ```

> [tab] Correct
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent, CachingConfig
>
> agent = Agent(name="Assistant", caching=CachingConfig(prompt_caching=True))
> ```

> [!NOTE]
>
> See [Session Resume](https://praison.ai/docs/docs/memory/session-resume) for the full session lifecycle and [Prompt Caching](https://praison.ai/docs/features/prompt-caching.md) for `CachingConfig`.

***

## Should I Migrate?

Use this flow to decide when to switch.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Is the code new?} -->|Yes| N[Use the Config form only]
    Q -->|No, I have old code| M{Does it still work?}
    M -->|Yes, with warning| P[Migrate at your convenience]
    M -->|TypeError| K[Check the migration table]

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef action fill:#10B981,stroke:#7C90A0,color:#fff

    class Q,M question
    class N,P,K action
```

***

## Common Patterns

The three migrations you will hit most often.

**Coder agent** — `allow_code_execution` + `code_execution_mode` → `ExecutionConfig`:

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

agent = Agent(
    name="coder",
    execution=ExecutionConfig(code_execution=True, code_mode="safe"),
)
```

**Long-running agent** — `auto_save` + `rate_limiter` → `MemoryConfig` + `ExecutionConfig`:

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

agent = Agent(
    name="worker",
    memory=MemoryConfig(auto_save="session"),
    execution=ExecutionConfig(rate_limiter=my_limiter),
)
```

**Autonomous agent** — `verification_hooks` → `AutonomyConfig`:

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

agent = Agent(
    name="auditor",
    autonomy=AutonomyConfig(verification_hooks=[check_output]),
)
```

***

## Best Practices

> [accordion] Prefer the Config form in new code
>
> The deprecated names will be removed in a future release. Write new agents with the config objects from the start.

> [accordion] Fix DeprecationWarnings as they surface
>
> Migrate the warnings that appear in your test suite as you touch each agent, not all at once.

> [accordion] Always pass Config params by name
>
> Never pass `Agent(..., value)` positionally past `toolsets=`. Keyword form prevents accidental misbinding.

> [accordion] Do not use fallback\_models= on Agent()
>
> `fallback_models=` is not a constructor keyword — it is an internal forwarding path for `clone_for_channel()`. Use `llm=LLMConfig(fallback_models=[...])` for strings, dicts, and `base_url` setups, or assign `agent.fallback_models = [...]` after construction when `llm=` is a model object. See [Model Fallback → Custom LLMs & provider/model strings](https://praison.ai/docs/features/model-fallback.md#custom-llms--providermodel-strings).

***

## Related

> [card] [Handoffs](https://praison.ai/docs/features/handoffs.md)
>
> Replaces `allow_delegation=True`.

> [card] [Execution](https://praison.ai/docs/features/execution.md)
>
> Replaces `allow_code_execution`, `code_execution_mode`, and `rate_limiter`.

> [card] [Autonomy](https://praison.ai/docs/features/autonomy.md)
>
> Replaces `verification_hooks=[...]`.

> [card] [Memory](https://praison.ai/docs/features/memory.md)
>
> Replaces `auto_save="name"`.

> [card] [Runtime](https://praison.ai/docs/features/runtime.md)
>
> Replaces `cli_backend=`.

> [card] [Rate Limiter](https://praison.ai/docs/features/rate-limiter.md)
>
> Replaces `rate_limiter=` on `Agent()`.

> [card] [Session Resume](https://praison.ai/docs/docs/memory/session-resume)
>
> Full session lifecycle for `memory={"session_id": ...}`.

> [card] [Prompt Caching](https://praison.ai/docs/features/prompt-caching.md)
>
> `CachingConfig(prompt_caching=True)` replaces `prompt_caching=`.


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