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

# Agents Module

> Documentation for the praisonaiagents.agents.agents module

# Agents

Multi-agent orchestration with sequential, hierarchical, and workflow patterns (parallel fan-out via `async_execution=True` tasks).

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, AgentTeam

researcher = Agent(name="Researcher", instructions="Research topics")
writer = Agent(name="Writer", instructions="Write content")

agents = AgentTeam(agents=[researcher, writer], memory=True)
result = agents.start()
```

## Parameters Table

### Core Parameters

| Parameter     | Type          | Default        | Description                               |
| ------------- | ------------- | -------------- | ----------------------------------------- |
| `agents`      | `List[Agent]` | required       | List of agents to orchestrate             |
| `tasks`       | `List[Task]`  | `None`         | Tasks to execute (auto-generated if None) |
| `process`     | `str`         | `"sequential"` | Execution pattern (see below)             |
| `name`        | `str`         | `None`         | Name for this agent collection            |
| `variables`   | `Dict`        | `None`         | Global variables for substitution         |
| `manager_llm` | `str`         | `None`         | LLM for manager agent (hierarchical)      |

### Process Types

Valid `process` values are `"sequential"`, `"workflow"`, and `"hierarchical"`. Any other value (including `"parallel"`) raises `ValueError`. For parallel fan-out, set `async_execution=True` on individual `Task` objects within a `"workflow"` or `"sequential"` process.

| Process          | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `"sequential"`   | Execute tasks in order                                                           |
| `"workflow"`     | Follow task dependencies (use `async_execution=True` tasks for parallel fan-out) |
| `"hierarchical"` | Manager agent delegates to workers                                               |

### Consolidated Feature Params

| Parameter    | Type                                   | Default | Description        |
| ------------ | -------------------------------------- | ------- | ------------------ |
| `memory`     | `bool \| MultiAgentMemoryConfig`       | `False` | Shared memory      |
| `planning`   | `bool \| MultiAgentPlanningConfig`     | `False` | Planning mode      |
| `context`    | `bool \| ContextConfig`                | `False` | Context management |
| `output`     | `str \| MultiAgentOutputConfig`        | `None`  | Output config      |
| `execution`  | `str \| MultiAgentExecutionConfig`     | `None`  | Execution config   |
| `hooks`      | `MultiAgentHooksConfig`                | `None`  | Event hooks        |
| `autonomy`   | `bool \| AutonomyConfig`               | `None`  | Autonomy settings  |
| `knowledge`  | `bool \| List[str] \| KnowledgeConfig` | `None`  | Knowledge/RAG      |
| `guardrails` | `bool \| Callable \| GuardrailConfig`  | `None`  | Validation         |
| `web`        | `bool \| WebConfig`                    | `None`  | Web search/fetch   |
| `reflection` | `bool \| ReflectionConfig`             | `None`  | Self-reflection    |

## Precedence Ladder

<Info>
  **Resolution Order**: Instance > Config > Array > Dict > String > Bool > Default

  Same precedence as Agent. Consolidated params propagate to underlying agents.
</Info>

## Usage Forms Table

| Form                  | Example                                 | When to Use            |
| --------------------- | --------------------------------------- | ---------------------- |
| **Bool**              | `memory=True`                           | Enable with defaults   |
| **String preset**     | `output="verbose"`                      | Use predefined config  |
| **Dict**              | `memory={"backend": "sqlite"}`          | Custom config          |
| **Array + overrides** | `output=["verbose", {"stream": False}]` | Preset + customization |
| **Config instance**   | `memory=MultiAgentMemoryConfig(...)`    | Full control           |

## Presets & Options

### Output Presets (Multi-Agent)

| Preset      | verbose | stream | Description                                         |
| ----------- | ------- | ------ | --------------------------------------------------- |
| `"silent"`  | 0       | False  | No output                                           |
| `"minimal"` | 1       | True   | Short status lines                                  |
| `"verbose"` | 2       | True   | Rich panels (streaming on — opt out via array form) |

<Card title="Multi-Agent Output" icon="users-rectangle" href="/docs/features/multi-agent-output">
  Comprehensive guide to multi-agent output configuration and streaming
</Card>

### Execution Presets (Multi-Agent)

| Preset        | max\_iter | max\_retries |
| ------------- | --------- | ------------ |
| `"fast"`      | 5         | 2            |
| `"balanced"`  | 10        | 5            |
| `"thorough"`  | 20        | 5            |
| `"unlimited"` | 100       | 10           |

## Methods

| Method                     | Description                 |
| -------------------------- | --------------------------- |
| `start()`                  | Start synchronous execution |
| `astart()`                 | Async execution             |
| `run_all_tasks()`          | Execute all tasks           |
| `add_task(task)`           | Add task dynamically        |
| `get_task_status(task_id)` | Get task status             |
| `set_state(key, value)`    | Set shared state            |
| `get_state(key, default)`  | Get shared state            |

## Common Recipes

### Sequential (Default)

Tasks execute one after another in order:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents = AgentTeam(
    agents=[agent1, agent2],
    tasks=[task1, task2, task3],
    process="sequential"
)
```

### Parallel

Independent tasks execute concurrently. Set `async_execution=True` on each task inside a `workflow` (or `sequential`) process — `process="parallel"` is not a valid value and raises `ValueError`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Task, AgentTeam

agents = AgentTeam(
    agents=[agent1, agent2, agent3],
    tasks=[
        Task(description="First", agent=agent1, async_execution=True),
        Task(description="Second", agent=agent2, async_execution=True),
        Task(description="Third", agent=agent3, async_execution=True),
    ],
    process="workflow"
)
```

<Note>
  `process` accepts only `"sequential"`, `"workflow"`, or `"hierarchical"`. Passing `process="parallel"` raises a `ValueError`; parallel fan-out is achieved via `async_execution=True` on individual `Task` objects.
</Note>

### Hierarchical

Manager agent delegates to worker agents:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents = AgentTeam(
    agents=[worker1, worker2, worker3],
    tasks=[complex_task],
    process="hierarchical",
    manager_llm="gpt-4o-mini"
)
```

### Workflow

Tasks follow explicit dependencies via `context`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
task1 = Task(description="Step 1", agent=agent1)
task2 = Task(description="Step 2", agent=agent2, context=[task1])
task3 = Task(description="Step 3", agent=agent3, context=[task1, task2])

agents = AgentTeam(
    agents=[agent1, agent2, agent3],
    tasks=[task1, task2, task3],
    process="workflow"
)
```

## Async Support

Full async/await support for non-blocking execution:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonaiagents import Agent, Task, AgentTeam

async def main():
    agents = AgentTeam(
        agents=[agent1, agent2],
        tasks=[task1, task2],
        process="workflow"
    )
    
    result = await agents.astart()
    print(result["task_results"])

asyncio.run(main())
```

## Shared State

Agents can share state during execution:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents = AgentTeam(agents=[agent1, agent2], tasks=[task1, task2])

# Set shared state
agents.set_state("api_key", "xxx")
agents.set_state("config", {"mode": "production"})

# Access in tasks via context
result = agents.start()

# Read state after execution
final_data = agents.get_state("collected_data")
```

## Advanced Examples

### With Memory

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents = AgentTeam(
    agents=[agent1, agent2],
    tasks=[task1, task2],
    memory=True,  # Enable shared memory
    user_id="user123"
)
```

### With Custom Completion Checker

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def my_checker(task, output):
    """Custom validation for task completion."""
    if "error" in output.lower():
        return False, "Output contains errors"
    return True, output

agents = AgentTeam(
    agents=[agent1],
    tasks=[task1],
    completion_checker=my_checker
)
```

### With Verbose Logging

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents = AgentTeam(
    agents=[agent1, agent2],
    tasks=[task1, task2],
    verbose=2  # Debug level
)
```

## See Also

* [Agent Module](/docs/sdk/praisonaiagents/agent/agent) - Individual agents
* [Task Module](/docs/sdk/praisonaiagents/task/task) - Task definition
* [Process Module](/docs/sdk/praisonaiagents/process/process) - Execution flows
* [AutoAgents](/docs/sdk/praisonaiagents/agents/autoagents) - Auto-generated agents