Praison AI

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
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"),
)
Diagram

Legacy → Config

allow_delegation=True

handoffs=…

allow_code_execution=True

execution=ExecutionConfig

auto_save=name

memory=MemoryConfig

verification_hooks=…

autonomy=AutonomyConfig

cli_backend=…

runtime=…

Quick Start

  1. Find the old params

    Scan your code for any of the seven deprecated names:

    bash
    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 paramOld defaultReplacement (public API)
allow_delegationFalsehandoffs=[...]
allow_code_executionFalseexecution=ExecutionConfig(code_execution=True)
code_execution_mode"safe"execution=ExecutionConfig(code_mode="safe") (or "unsafe")
auto_saveNonememory=MemoryConfig(auto_save="name")
rate_limiterNoneexecution=ExecutionConfig(rate_limiter=obj)
verification_hooksNoneautonomy=AutonomyConfig(verification_hooks=[...])
cli_backendNoneruntime=... (see Runtime)
llm—model=... (canonical); llm= is a deprecated alias, passing both raises TypeError
retrieval_configNoneNo 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
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))

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.

Old

python
from praisonaiagents import Agent

agent = Agent(name="Assistant", llm="gpt-4o")

New

python
from praisonaiagents import Agent

agent = Agent(name="Assistant", model="gpt-4o")

Refused

python
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")

allow_delegation → handoffs

Old

python
from praisonaiagents import Agent

other = Agent(name="specialist")
agent = Agent(name="router", allow_delegation=True)

New

python
from praisonaiagents import Agent

other = Agent(name="specialist")
agent = Agent(name="router", handoffs=[other])

allow_code_execution + code_execution_mode → execution

Old

python
from praisonaiagents import Agent

agent = Agent(
    name="coder",
    allow_code_execution=True,
    code_execution_mode="safe",
)

New

python
from praisonaiagents import Agent, ExecutionConfig

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

auto_save → memory

Old

python
from praisonaiagents import Agent

agent = Agent(name="assistant", auto_save="session")

New

python
from praisonaiagents import Agent, MemoryConfig

agent = Agent(name="assistant", memory=MemoryConfig(auto_save="session"))

rate_limiter → execution

Old

python
from praisonaiagents import Agent

agent = Agent(name="worker", rate_limiter=my_limiter)

New

python
from praisonaiagents import Agent, ExecutionConfig

agent = Agent(name="worker", execution=ExecutionConfig(rate_limiter=my_limiter))

verification_hooks → autonomy

Old

python
from praisonaiagents import Agent

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

New

python
from praisonaiagents import Agent, AutonomyConfig

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

cli_backend → runtime

Old

python
from praisonaiagents import Agent

agent = Agent(name="cli-agent", cli_backend="claude-code")

New

python
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
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
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
TypeError: Agent.__init__() got unexpected keyword argument(s): session_id
Diagram

session_id

user_id

db

prompt_caching

🤖 Agent

💾 memory=MemoryConfig

⚙️ caching=CachingConfig

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(...)ErrorCorrect spelling
Agent(session_id="my-session")TypeError: ... session_idAgent(memory={"session_id": "my-session"}) or Agent(memory=MemoryConfig(session_id="my-session"))
Agent(user_id="alice")TypeError: ... user_idAgent(memory=MemoryConfig(user_id="alice"))
Agent(db="postgresql://…")TypeError: ... dbAgent(memory=MemoryConfig(session_id="…", db="postgresql://…")) — or MemoryConfig(db=db.PostgresDB(...)) for the optional praisonai wrapper
Agent(prompt_caching=True)TypeError: ... prompt_cachingAgent(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

Rejected

python
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)

Correct

python
from praisonaiagents import Agent, ToolConfig

agent = Agent(name="Assistant", tool_config=ToolConfig(timeout=30))

tool_retry_policy → tool_config

Rejected

python
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())

Correct

python
from praisonaiagents import Agent, ToolConfig
from praisonaiagents.tools import RetryPolicy

agent = Agent(
    name="Assistant",
    tool_config=ToolConfig(retry_policy=RetryPolicy()),
)

session_id → memory

Rejected

python
from praisonaiagents import Agent

# TypeError: Agent.__init__() got unexpected keyword argument(s): session_id
agent = Agent(name="Assistant", session_id="my-session")

Correct

python
from praisonaiagents import Agent

agent = Agent(name="Assistant", memory={"session_id": "my-session"})

user_id → memory

Rejected

python
from praisonaiagents import Agent

# TypeError: Agent.__init__() got unexpected keyword argument(s): user_id
agent = Agent(name="Assistant", user_id="alice")

Correct

python
from praisonaiagents import Agent, MemoryConfig

agent = Agent(name="Assistant", memory=MemoryConfig(user_id="alice"))

db → memory

Rejected

python
from praisonaiagents import Agent

# TypeError: Agent.__init__() got unexpected keyword argument(s): db
agent = Agent(name="Assistant", db="postgresql://user:pass@localhost/mydb")

Correct (URL)

python
from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="Assistant",
    memory=MemoryConfig(
        session_id="user-123-main",
        db="postgresql://user:pass@localhost/mydb",
    ),
)

Correct (wrapper)

python
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

Rejected

python
from praisonaiagents import Agent

# TypeError: Agent.__init__() got unexpected keyword argument(s): prompt_caching
agent = Agent(name="Assistant", prompt_caching=True)

Correct

python
from praisonaiagents import Agent, CachingConfig

agent = Agent(name="Assistant", caching=CachingConfig(prompt_caching=True))

Should I Migrate?

Use this flow to decide when to switch.

Diagram

Yes

No, I have old code

Yes, with warning

TypeError

Is the code new?

Use the Config form only

Does it still work?

Migrate at your convenience

Check the migration table

Common Patterns

The three migrations you will hit most often.

Coder agent — allow_code_execution + code_execution_mode → ExecutionConfig:

python
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
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
from praisonaiagents import Agent, AutonomyConfig

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

Best Practices

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.

Fix DeprecationWarnings as they surface

Migrate the warnings that appear in your test suite as you touch each agent, not all at once.

Always pass Config params by name

Never pass Agent(..., value) positionally past toolsets=. Keyword form prevents accidental misbinding.

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.

Related

Handoffs

Replaces allow_delegation=True.

 Execution

Replaces allow_code_execution, code_execution_mode, and rate_limiter.

 Autonomy

Replaces verification_hooks=[...].

 Memory

Replaces auto_save="name".

 Runtime

Replaces cli_backend=.

 Rate Limiter

Replaces rate_limiter= on Agent().

 Session Resume

Full session lifecycle for memory={"session_id": ...}.

 Prompt Caching

CachingConfig(prompt_caching=True) replaces prompt_caching=.