Multi-Agent Execution

Multi-Agent Execution config controls how many times each task can iterate and how many retries are allowed when tasks fail.

from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentExecutionConfig

agent = Agent(name="Researcher", instructions="Research topics thoroughly.")
task = Task(description="Research the history of artificial intelligence", agent=agent)

workflow = PraisonAIAgents(
    agents=[agent],
    tasks=[task],
    execution=MultiAgentExecutionConfig(max_iter=20, max_retries=3),
)
workflow.start()

PraisonAIAgents here is a silent alias for AgentTeam, the canonical multi-agent class. AgentManager and Agents are aliases too — see Back-compat class aliases.

`ExecutionConfig` vs `MultiAgentExecutionConfig`

Only MultiAgentExecutionConfig is the team-level config. Passing the single-agent ExecutionConfig to the team no longer silently drops fields — it issues a UserWarning, adapts what it can, and names what it ignored. When you pass an ExecutionConfig to AgentTeam(execution=...), the team:

carries max_iter over (both classes have it),
maps max_retry_limit → max_retries only when you changed it (otherwise the team keeps its own default of 5, since ExecutionConfig.max_retry_limit defaults to 2),
emits a UserWarning naming MultiAgentExecutionConfig and listing every field with no team-level counterpart (e.g. code_execution, max_rpm).

Passing the correct class stays silent.

Right — team-level config
Wrong — single-agent config

from praisonaiagents import Agent, Task, PraisonAIAgents, ExecutionConfig, MultiAgentExecutionConfig

# Per-agent knobs go on each Agent
agent = Agent(
    name="Researcher",
    instructions="Research topics thoroughly.",
    execution=ExecutionConfig(code_execution=True, max_rpm=60),
)
task = Task(description="Research AI history", agent=agent)

# Orchestration knobs go on MultiAgentExecutionConfig — no warning
workflow = PraisonAIAgents(
    agents=[agent],
    tasks=[task],
    execution=MultiAgentExecutionConfig(max_iter=20, max_retries=3),
)
workflow.start()

from praisonaiagents import Agent, Task, PraisonAIAgents, ExecutionConfig

agent = Agent(name="Researcher", instructions="Research topics thoroughly.")
task = Task(description="Research AI history", agent=agent)

# UserWarning: max_iter carried over; code_execution, max_rpm, ... ignored.
# Use MultiAgentExecutionConfig for team-level settings.
workflow = PraisonAIAgents(
    agents=[agent],
    tasks=[task],
    execution=ExecutionConfig(max_iter=20, code_execution=True, max_rpm=60),
)
workflow.start()

Split the knobs by scope: per-agent settings (code_execution, max_budget, max_rpm, parallel_tool_calls) belong on each Agent(execution=...); team-level orchestration (max_iter, max_retries) belongs on MultiAgentExecutionConfig.

The user sets iteration and retry limits; the workflow stops or retries tasks within those bounds.

`ExecutionConfig` vs `MultiAgentExecutionConfig`

Only MultiAgentExecutionConfig is the team-level config. If you pass the single-agent ExecutionConfig to AgentTeam(execution=...), the team adapts what it can and warns instead of silently dropping the rest:

max_iter carries over (both classes have it).
max_retry_limit maps to the team’s max_retries — but only when you explicitly changed it. Otherwise the team keeps its own default of 5 (because ExecutionConfig.max_retry_limit defaults to 2).
A UserWarning names MultiAgentExecutionConfig and lists every field that has no team-level counterpart (e.g. code_execution, max_rpm), so you can see exactly what was ignored.
Passing MultiAgentExecutionConfig stays silent.

Wrong shape (single-agent config)
Right shape (team-level + per-agent)

from praisonaiagents import Agent, Task, AgentTeam, ExecutionConfig

agent = Agent(name="Researcher", instructions="Research thoroughly.")
task = Task(description="Research AI history", agent=agent)

# UserWarning: pass MultiAgentExecutionConfig; code_execution / max_rpm ignored
team = AgentTeam(
    agents=[agent],
    tasks=[task],
    execution=ExecutionConfig(max_iter=20, max_rpm=100, code_execution=True),
)

from praisonaiagents import Agent, Task, AgentTeam, MultiAgentExecutionConfig, ExecutionConfig

# Per-agent knobs go on the Agent
agent = Agent(
    name="Researcher",
    instructions="Research thoroughly.",
    execution=ExecutionConfig(code_execution=True, max_rpm=100),
)
task = Task(description="Research AI history", agent=agent)

# Team-level orchestration knobs go on MultiAgentExecutionConfig
team = AgentTeam(
    agents=[agent],
    tasks=[task],
    execution=MultiAgentExecutionConfig(max_iter=20, max_retries=5),
)

Split the config by scope: per-agent knobs (code_execution, max_budget, max_rpm, parallel_tool_calls) belong on each Agent(execution=...); team-level orchestration knobs (max_iter, max_retries) belong on MultiAgentExecutionConfig.

Quick Start

Simple Usage

from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentExecutionConfig

agent = Agent(name="Helper", instructions="Complete tasks efficiently.")
task = Task(description="Write a marketing email for our new product", agent=agent)

workflow = PraisonAIAgents(
    agents=[agent],
    tasks=[task],
    execution=MultiAgentExecutionConfig(max_iter=10),
)
workflow.start()

With Custom Retry Settings

from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentExecutionConfig

agent1 = Agent(name="Researcher", instructions="Research topics in depth.")
agent2 = Agent(name="Writer", instructions="Write clear reports.")

task1 = Task(description="Research quantum computing applications", agent=agent1)
task2 = Task(description="Write a report based on the research", agent=agent2)

workflow = PraisonAIAgents(
    agents=[agent1, agent2],
    tasks=[task1, task2],
    execution=MultiAgentExecutionConfig(max_iter=15, max_retries=5),
)
workflow.start()

How It Works

Setting	Controls	Default
`max_iter`	Max iterations per task	`10`
`max_retries`	Max retries on failure	`5`

Configuration Options

Full list of options, types, and defaults — MultiAgentExecutionConfig

Option	Type	Default	Description
`max_iter`	`int`	`10`	Maximum iterations per task
`max_retries`	`int`	`5`	Maximum retries on task failure

Common Patterns

Pattern 1 — Long-running research workflow

from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentExecutionConfig

researcher = Agent(name="Researcher", instructions="Do thorough multi-step research.")
writer = Agent(name="Writer", instructions="Write clear, comprehensive reports.")

tasks = [
    Task(description="Research AI trends in 2025", agent=researcher),
    Task(description="Compile findings into a structured report", agent=writer),
]

response = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=tasks,
    execution=MultiAgentExecutionConfig(max_iter=25, max_retries=3),
).start()
print(response)

Pattern 2 — Conservative limits for cost control

from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentExecutionConfig

agent = Agent(name="Classifier", instructions="Classify text into categories.")
task = Task(description="Classify 50 customer support tickets", agent=agent)

workflow = PraisonAIAgents(
    agents=[agent],
    tasks=[task],
    execution=MultiAgentExecutionConfig(max_iter=5, max_retries=2),
)
workflow.start()

Best Practices

Tune max_iter per task complexity

Simple tasks (classification, extraction) need max_iter=5–10. Complex research or multi-step synthesis tasks may need max_iter=20–30. Start low and increase if tasks don’t complete.

max_retries for fault tolerance

Set max_retries=3–5 for workflows calling external services that may fail intermittently. For offline or deterministic tasks, max_retries=1–2 is usually enough.

Monitor with hooks

Pair MultiAgentExecutionConfig with MultiAgentHooksConfig to log when retries happen. This helps diagnose why tasks hit their retry limit in production.

Multi-Agent Hooks

Intercept task lifecycle events

Multi-Agent Planning

Plan tasks before executing them

Execution Systems

Single-agent execution configuration

Agent Retry

Single-agent retry behavior

Spawn & Announce

Reliable async sub-agent spawn — no hangs, safe sync/async mixing (#4887)

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Multi-Agent Execution

`ExecutionConfig` vs `MultiAgentExecutionConfig`

`ExecutionConfig` vs `MultiAgentExecutionConfig`

Quick Start

How It Works

Configuration Options

Common Patterns

Pattern 1 — Long-running research workflow

Pattern 2 — Conservative limits for cost control

Best Practices

Multi-Agent Hooks

Multi-Agent Planning

Execution Systems

Agent Retry

Spawn & Announce

​ExecutionConfig vs MultiAgentExecutionConfig

​ExecutionConfig vs MultiAgentExecutionConfig

​Quick Start

​How It Works

​Configuration Options

​Common Patterns

​Pattern 1 — Long-running research workflow

​Pattern 2 — Conservative limits for cost control

​Best Practices

​Related

Multi-Agent Hooks

Multi-Agent Planning

Execution Systems

Agent Retry

Spawn & Announce

`ExecutionConfig` vs `MultiAgentExecutionConfig`

`ExecutionConfig` vs `MultiAgentExecutionConfig`

Quick Start

How It Works

Configuration Options

Common Patterns

Pattern 1 — Long-running research workflow

Pattern 2 — Conservative limits for cost control

Best Practices

Related