Code Migration - PraisonAI

Migrate your existing agent projects to PraisonAI using an AI-driven workflow that analyzes, converts, and validates your codebase automatically.

from praisonaiagents import Agent

agent = Agent(name="migration-helper", instructions="Help migrate from older PraisonAI versions.")
agent.start("Migrate my agents.yaml from v1 format to v2 format.")

How It Works

The user points the CLI at a project; AgentFlow runs four agents in sequence — Analyzer reads the codebase, Converter transforms it, Evaluator scores the result (1–10), and Error Agent diagnoses failures and retries up to 3 times.

Agent	Role
Analyzer	Reads all files, maps agent definitions, task dependencies, and import structures
Converter	Transforms code using a feature spec that maps source patterns to PraisonAI equivalents
Evaluator	LLM-as-Judge scoring — a score of 8+ means successful migration
Error Agent	Diagnoses evaluation failures and feeds corrections back to the Converter

Quick Start

Point to Your Project

praisonai migrate ./my-agent-project

AI Analyzes All Files

The Analyzer Agent reads your entire codebase to understand relationships between files.

Intelligent Conversion

The Converter Agent transforms your code using learned patterns.

Automatic Validation

The Evaluator Agent tests the converted code. If issues are found, the Error Agent analyzes and retries (up to 3 times).

The Migration Agents

Analyzer Agent

Scans all files in your project to understand:

Agent definitions and their relationships
Task dependencies
Workflow patterns
Import structures

Converter Agent

Transforms your code using a feature spec:

Maps parameters to PraisonAI equivalents
Preserves logic and behavior
Handles multi-file dependencies

Evaluator Agent

Uses LLM-as-Judge to verify:

Syntax correctness
Functional equivalence
Import completeness

Error Agent

When evaluation fails:

Analyzes the error
Identifies root cause
Triggers retry with fixes

CLI Reference

praisonai migrate <path> [options]

string

required

Path to file or directory to migrate

string

Output directory for converted files

flag

Apply changes (default is dry-run preview)

integer

default:"3"

Maximum retry attempts on evaluation failure

Feature Mapping

The migration uses a feature specification to map patterns:

Agent Parameters

Source Pattern	PraisonAI Equivalent
`agent = CrewAgent(role=...)`	`agent = Agent(name=..., role=...)`
`@tool` decorator	`tools=[function_name]`
`Task(description=...)`	`Task(description=..., agent=agent)`
`Crew(agents=..., tasks=...)`	`AgentTeam(agents=..., tasks=...)` — `PraisonAIAgents` also works as a silent alias, see Back-compat class aliases

Evaluation Loop

The Evaluator uses LLM-as-Judge scoring (1-10). A score of 8+ indicates successful migration.

Programmatic API

from praisonai.cli.features.migrate import MigrationFlow

# Create migration flow
flow = MigrationFlow(
    source_path="./my-project",
    output_path="./converted",
    max_retries=3
)

# Run the agent-driven migration
result = flow.run()

if result.success:
    print(f"Migration complete: {result.files_converted} files")
else:
    print(f"Issues found: {result.errors}")

Migration Tips

Multi-file projects: The migration analyzes ALL files before converting, ensuring cross-file dependencies are handled correctly.

Always use version control: Commit your code before running migration with --apply.

Review the output: Even with AI validation, review the converted code to ensure it meets your requirements.

Troubleshooting

Migration keeps retrying

The Evaluator may be finding issues. Check the error analysis output for specific problems. You may need to manually adjust complex patterns.

Some files not converted

Files without recognizable agent patterns are skipped. The Analyzer Agent only processes files with detectable patterns.

Import errors after migration

Ensure you have praisonaiagents installed. Some source-specific tools may need manual replacement.

API Migration: verbose= to output=

The verbose= parameter has been consolidated into the output= parameter across all PraisonAI components.

Quick Migration

Agent
AgentTeam
Process

# ❌ Old (raises TypeError)
agent = Agent(instructions="...", verbose=True)

# ✅ New
agent = Agent(instructions="...", output="verbose")

# ❌ Old (raises TypeError)
team = AgentTeam(agents=[...], tasks=[...], verbose=True)

# ✅ New
team = AgentTeam(agents=[...], tasks=[...], output="verbose")

# ⚠️ Old (still works, backward compat)
process = Process(tasks={...}, agents=[...], verbose=True)

# ✅ New (preferred)
process = Process(tasks={...}, agents=[...], output="verbose")

Output Presets

Preset	Description
`"silent"`	No output (default)
`"verbose"`	Rich panels with markdown
`"status"`	Tool calls + response
`"trace"`	Full trace with timestamps
`"stream"`	Real-time token streaming
`"json"`	JSONL events

Component Status

Component	`verbose=`	`output=`	Notes
Agent	❌ Rejected	✅ Required	Use `output="verbose"`
AgentTeam	❌ Rejected	✅ Required	Raises `TypeError` — use `output="verbose"`
Process	⚠️ Backward compat	✅ Preferred	Both work, prefer `output=`
Workflow	⚠️ Internal only	✅ Preferred	Use `output=` in constructor
Eval	✅ Intentional	N/A	Keep `verbose=` for eval logging

Breaking Change: Agent(verbose=True) raises TypeError. Update to Agent(output="verbose").

API Migration: max_iter= / session=

AgentTeam also removed the max_iter= and session= kwargs. Both now raise TypeError — use execution= for iteration limits and variables= for session state.

max_iter= → execution=

Replace max_iter= with an execution= preset ("fast" sets max_iter=10, "balanced" sets max_iter=20) or pass an explicit value.

Preset
Explicit max_iter

from praisonaiagents import Agent, Task, AgentTeam

# ❌ Old (raises TypeError)
# team = AgentTeam(agents=[...], tasks=[...], max_iter=20)

# ✅ New — preset ("fast"=10 | "balanced"=20)
team = AgentTeam(
    agents=[Agent(name="Analyst", instructions="Analyse the input")],
    tasks=[Task(description="Analyse Q3 metrics", expected_output="Insights")],
    execution="balanced",
)
team.start()

from praisonaiagents import Agent, Task, AgentTeam

# ❌ Old (raises TypeError)
# team = AgentTeam(agents=[...], tasks=[...], max_iter=30)

# ✅ New — explicit value via dict
team = AgentTeam(
    agents=[Agent(name="Analyst", instructions="Analyse the input")],
    tasks=[Task(description="Analyse Q3 metrics", expected_output="Insights")],
    execution={"max_iter": 30},
)
team.start()

session= → variables=

The session= kwarg is gone. Pass session state through variables= and call session.save() explicitly.

from praisonaiagents import Agent, Task, AgentTeam

# ❌ Old (raises TypeError)
# team = AgentTeam(agents=[...], tasks=[...], session=my_session)

# ✅ New — session state via variables=
team = AgentTeam(
    agents=[Agent(name="Writer", instructions="Personalise the response")],
    tasks=[Task(description="Greet {{user}} about {{topic}}", expected_output="Message")],
    variables={"user": "Alice", "topic": "PraisonAI"},
)
team.start()

# Persist session state explicitly when you need it
# my_session.save()

Removed kwargs at a glance

Removed kwarg	Runtime behaviour	Replacement
`verbose=`	Raises `TypeError`	`output="silent" \| "minimal" \| "verbose"`
`max_iter=`	Raises `TypeError`	`execution="fast" \| "balanced"` or `execution={"max_iter": N}`
`session=`	Raises `TypeError`	`variables={...}` + `session.save()`

Breaking Change: AgentTeam(max_iter=…) and AgentTeam(session=…) raise TypeError. Use execution= and variables=.

Back-compat class aliases

AgentTeam is the canonical multi-agent class in v1.0+. The SDK also exposes three silent aliases that resolve to the same class, so old snippets, older docs, and downstream integrations keep working unchanged.

All four names resolve to the same class object — the aliases are not deprecated and there is no plan to remove them. Prefer AgentTeam for new code; keep any of the aliases you already have in existing code.

All four are importable from the package root and point to the same object:

from praisonaiagents import AgentTeam, AgentManager, Agents, PraisonAIAgents

assert AgentTeam is AgentManager is Agents is PraisonAIAgents   # True

Name	Status	Use in
`AgentTeam`	✅ Canonical (v1.0+)	New code
`AgentManager`	🟰 Silent alias	Legacy integrations
`Agents`	🟰 Silent alias	Pre-v1.0 tutorials
`PraisonAIAgents`	🟰 Silent alias	Pre-1.0 code, downstream integrations that guard `from praisonaiagents import PraisonAIAgents`

PraisonAIAgents was missing from the root __all__ in a recent release; upgrade to praisonaiagents ≥ 1.6.162 (PraisonAI PR #3675) if from praisonaiagents import PraisonAIAgents raises ImportError.

Best Practices

Migrate a copy, not your working tree

The migration pipeline rewrites source files as it converts patterns. Point it at a clean checkout or branch so you can diff the result and roll back if the Evaluator score is low. Version control makes reviewing the Converter’s changes straightforward.

Trust the 8+ score gate

The Evaluator uses LLM-as-Judge scoring from 1–10 and treats 8+ as a successful migration. Don’t ship a converted project that scores below that threshold — let the Error Agent’s retries (up to 3) run, then review any file the Evaluator still flags.

Update verbose= to output= first

Agent(verbose=True) now raises TypeError. Replace it with Agent(output="verbose") before migrating, and prefer output= over the deprecated verbose= on AgentTeam, Process, and Workflow too. This clears the most common breaking change up front.

Review imports after conversion

The Analyzer maps import structures, but confirm the converted project uses friendly top-level imports (from praisonaiagents import Agent, Task, AgentTeam) and that any custom tools resolve. A quick smoke run catches missed dependencies the Evaluator can’t see.

Run and validate migrated agents from the command line.

Set project-wide defaults for your migrated agents.

​How It Works

​Quick Start

​The Migration Agents

Analyzer Agent

Converter Agent

Evaluator Agent

Error Agent

​CLI Reference

​Feature Mapping

​Evaluation Loop

​Programmatic API

​Migration Tips

​Troubleshooting

​API Migration: verbose= to output=

​Quick Migration

​Output Presets

​Component Status

​API Migration: max_iter= / session=

​max_iter= → execution=

​session= → variables=

​Removed kwargs at a glance

​Back-compat class aliases

​Best Practices

​Related

How It Works

Quick Start

The Migration Agents

CLI Reference

Feature Mapping

Evaluation Loop

Programmatic API

Migration Tips

Troubleshooting

API Migration: verbose= to output=

Quick Migration

Output Presets

Component Status

API Migration: max_iter= / session=

max_iter= → execution=

session= → variables=

Removed kwargs at a glance

Back-compat class aliases

Best Practices

Related