Multi-Agent Execution

Control iteration limits and retry behavior for multi-agent workflows

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

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.

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.

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

Quick Start

1. 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()

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

Configuration Options

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

Related