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

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
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```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()
    ```
  </Step>

  <Step title="With Custom Retry Settings">
    ```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()
    ```
  </Step>
</Steps>

***

## 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

<Card icon="code" href="/docs/sdk/reference/python/MultiAgentExecutionConfig">
  Full list of options, types, and defaults — `MultiAgentExecutionConfig`
</Card>

| 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Monitor with hooks">
    Pair `MultiAgentExecutionConfig` with `MultiAgentHooksConfig` to log when retries happen. This helps diagnose why tasks hit their retry limit in production.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Multi-Agent Hooks" icon="webhook" href="/docs/features/multi-agent-hooks">
    Intercept task lifecycle events
  </Card>

  <Card title="Multi-Agent Planning" icon="list-check" href="/docs/features/multi-agent-planning">
    Plan tasks before executing them
  </Card>

  <Card title="Execution Systems" icon="cpu" href="/docs/features/execution-systems">
    Single-agent execution configuration
  </Card>

  <Card title="Agent Retry" icon="rotate-cw" href="/docs/features/agent-retry">
    Single-agent retry behavior
  </Card>
</CardGroup>