> ## 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. # 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. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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](/docs/features/migrate#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. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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() ``` ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR subgraph "Execution Limits" TASK["📋 Task"] --> EXEC["🤖 Execute"] EXEC -- Success --> DONE["✅ Done"] EXEC -- Fail --> RETRY{"🔄 Retry\n< max_retries?"} RETRY -- Yes --> EXEC RETRY -- No --> FAIL["❌ Failed"] EXEC -- Loop --> ITER{"🔁 Iter\n< max_iter?"} ITER -- Yes --> EXEC ITER -- No --> DONE end classDef task fill:#6366F1,stroke:#7C90A0,color:#fff classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff classDef success fill:#10B981,stroke:#7C90A0,color:#fff classDef fail fill:#189AB4,stroke:#7C90A0,color:#fff class TASK task class EXEC agent class RETRY,ITER check class DONE success class FAIL fail ``` ## `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. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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), ) ``` ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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() ``` ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant User participant Workflow participant Execution participant Agent User->>Workflow: Start loop Each task Workflow->>Execution: Apply limits loop Iterations (up to max_iter) Execution->>Agent: Execute step alt Success Agent-->>Execution: Result else Error Execution->>Execution: Retry (up to max_retries) end end Execution-->>Workflow: Task result end Workflow-->>User: Final output ``` | 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 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. 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. Pair `MultiAgentExecutionConfig` with `MultiAgentHooksConfig` to log when retries happen. This helps diagnose why tasks hit their retry limit in production. *** ## Related Intercept task lifecycle events Plan tasks before executing them Single-agent execution configuration Single-agent retry behavior Reliable async sub-agent spawn — no hangs, safe sync/async mixing ([#4887](https://github.com/MervinPraison/PraisonAI/pull/4887)) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.