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

# Init Team

> Scaffold a runnable multi-agent AgentTeam project in one command

`praisonai init team <name>` scaffolds a runnable, YAML-first multi-agent AgentTeam project — edit two YAML files, then `python -m <slug>.main`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "praisonai init team my-research-crew"
        I[⚡ init team my-research-crew] --> P[📁 my-research-crew/]
        P --> A[🤖 agents.yaml]
        P --> T[📋 tasks.yaml]
        P --> TM[🛠 team.py]
        P --> M[▶️ main.py]
        M --> R[✅ python -m my_research_crew.main]
    end

    classDef cmd fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef dir fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef run fill:#10B981,stroke:#7C90A0,color:#fff

    class I cmd
    class P dir
    class A,T agent
    class TM,M dir
    class R run
```

> [!TIP]
>
> For a single-agent `.praisonai/` project (config + one agent + a command + a tool), use [`praisonai init`](https://praison.ai/docs/cli/init) instead. This page scaffolds a **multi-agent team** with its own Python package and entry point.

## Quick Start

**1. Scaffold**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai init team my-research-crew
```

Creates a `my-research-crew/` project with a `my_research_crew` Python package.

**2. Set your API key**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
cd my-research-crew
cp .env.example .env   # then edit and add your key
```

**3. Run**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
python -m my_research_crew.main
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as praisonai init team
    participant FS as File system
    participant Pkg as <slug> package
    participant Team as AgentTeam runtime

    User->>CLI: praisonai init team my-research-crew
    CLI->>FS: Resolve slug (my_research_crew)
    CLI->>FS: Write agents.yaml / tasks.yaml / team.py / main.py
    FS-->>CLI: Created / Skipped per file
    CLI-->>User: Next-step commands
    User->>Pkg: python -m my_research_crew.main
    Pkg->>Team: build_team().start()
    Team-->>User: Result
```

| Step | What happens |
| - | - |
| Resolve slug | Turns the name into a valid Python package (`my-research-crew` → `my_research_crew`) |
| Write files | Creates `agents.yaml`, `tasks.yaml`, `team.py`, `main.py`, README, `.env.example`, `.gitignore`, optional `pyproject.toml` |
| Report | Prints `Created <path>` or `Skipped (already exists, use --force): <path>` per file |
| Next steps | Prints the exact `cd`, `cp .env.example .env`, and `python -m <slug>.main` commands to copy |

## Generated project structure

```
my-research-crew/
  .env.example
  .gitignore
  README.md
  pyproject.toml            # optional (skip with --no-pyproject)
  my_research_crew/
    __init__.py
    main.py                 # run() entry point
    team.py                 # build_team() factory
    config/
      agents.yaml           # roles / goals / backstories + process
      tasks.yaml            # description / expected_output / agent / context
```

> [!NOTE]
>
> The package uses a **flat layout** (no `src/`) and `config/` lives inside the package. That means `python -m my_research_crew.main` runs from the project root with no install step.

## Flags

| Flag | Type | Default | Description |
| - | - | - | - |
| `name` (positional) | `str` | *(required)* | Project name; slugified into a Python package |
| `--process` | `str` | `sequential` | Default process type: `sequential` or `hierarchical` |
| `--agents` | `int` | `2` | Number of starter agents to scaffold (min 1) |
| `--force` / `-f` | `bool` | `False` | Overwrite existing files |
| `--no-pyproject` | `bool` | `False` | Skip `pyproject.toml` generation |

## Slug rules

The project name becomes a valid Python package identifier.

| Input | Package |
| - | - |
| `my-research-crew` | `my_research_crew` |
| `My Cool Crew!` | `my_cool_crew` |
| `123crew` | `_123crew` |
| `class` | `class_team` |

* Non-alphanumeric runs collapse to a single underscore, then the name is lower-cased.
* A leading digit is prefixed with `_`.
* Python keywords and soft keywords are suffixed with `_team` (so imports like `from <slug>.team import ...` stay valid).
* A name that slugifies to nothing (e.g. `---`) raises an error.

## What the generated files do

**`agents.yaml`** — one entry per agent with `name`, `role`, `goal`, and `backstory`, plus a top-level `process:` key (default `sequential`, or `hierarchical`).

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
process: sequential

agents:
  researcher:
    name: Research Analyst
    role: Senior Research Analyst
    goal: Find accurate, up-to-date information on the assigned topic
    backstory: >
      You excel at synthesising sources into concise research briefs.
```

**`tasks.yaml`** — each task has a `description`, `expected_output`, `agent`, and optional `context:` list. Descriptions use double-brace `{{topic}}` placeholders, filled at runtime by `AgentTeam(variables=…)`.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
tasks:
  - description: >
      Research the latest developments in {{topic}}.
      Focus on practical applications and key players.
    expected_output: >
      A bullet-point research brief with at least 5 findings and 3 sources.
    agent: researcher
```

**`team.py`** — a `build_team(variables=None)` factory that loads both YAML files, builds `Agent` instances, wires `Task`s to their agents, and returns an `AgentTeam`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from pathlib import Path

import yaml
from praisonaiagents import Agent, AgentTeam, Task

CONFIG_DIR = Path(__file__).parent / "config"


def load_yaml(name: str) -> dict:
    with open(CONFIG_DIR / name, encoding="utf-8") as f:
        return yaml.safe_load(f)


def build_team(variables: dict | None = None) -> AgentTeam:
    agents_cfg = load_yaml("agents.yaml")
    tasks_cfg = load_yaml("tasks.yaml")

    agents = {key: Agent(**spec) for key, spec in agents_cfg["agents"].items()}

    tasks = []
    for spec in tasks_cfg["tasks"]:
        spec = dict(spec)
        agent_key = spec.pop("agent", None)
        tasks.append(Task(agent=agents.get(agent_key), **spec))

    return AgentTeam(
        agents=list(agents.values()),
        tasks=tasks,
        process=agents_cfg.get("process", "sequential"),
        variables=variables or {},
    )
```

**`main.py`** — the `run()` entry point that builds the team, passes `variables`, and prints the result.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from my_research_crew.team import build_team


def run():
    team = build_team(variables={"topic": "AI agents"})
    result = team.start()
    print(result)


if __name__ == "__main__":
    run()
```

**`.env.example`** — commented provider credentials (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`). Copy it to `.env` and set at least one.

**`pyproject.toml`** — optional (skip with `--no-pyproject`). Uses a flat-layout `[tool.setuptools.packages.find] include = ["<slug>*"]` so the package installs cleanly.

**`.gitignore`** — ignores `.env`, `__pycache__/`, `*.pyc`, and `.venv/`.

## Customise the team

Change roles, add a task, or switch the process — all without touching Python.

**1. Edit the agents**

Open `my_research_crew/config/agents.yaml` and change any `role`, `goal`, or `backstory`. Add a new agent by adding another key under `agents:`.

**2. Edit the tasks**

Open `my_research_crew/config/tasks.yaml` and change a `description` or `expected_output`. Point a task at an agent with `agent: <key>` and reference upstream output with a `context:` list.

**3. Run again**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
python -m my_research_crew.main
```

## User interaction flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant YAML as agents.yaml / tasks.yaml
    participant Main as python -m <slug>.main
    participant Team as AgentTeam

    User->>YAML: Edit roles, goals, tasks
    User->>Main: python -m <slug>.main
    Main->>Team: build_team().start()
    Team-->>User: Prints result
```

## Common Patterns

### Change the topic without editing YAML

The `{{topic}}` placeholder is filled from `variables` in `main.py`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
team = build_team(variables={"topic": "quantum computing"})
```

### Add a third agent

Scaffold with more agents, or add one to the YAML later:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai init team my-research-crew --agents 3
```

### Switch to hierarchical process

A manager delegates instead of running tasks in order:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai init team my-research-crew --process hierarchical
```

Or set `process: hierarchical` in `agents.yaml` after scaffolding.

## Best Practices

> [accordion] Commit .env.example, not .env
>
> Check in `.env.example` so teammates know which credentials to set, and keep the real `.env` out of git (it is already in the generated `.gitignore`).

> [accordion] Keep task context in sync
>
> When you change a task `description`, update any `context:` entries that reference it so downstream tasks receive the right upstream output.

> [accordion] Use --force intentionally
>
> `--force` overwrites existing files without prompting. Commit or back up your edits first.

> [accordion] Prefer editing YAML over team.py
>
> `team.py` is a generic factory. Editing `agents.yaml` and `tasks.yaml` keeps it reusable — reach for `team.py` only when you need tools, memory, or guardrails.

## Related

> [card] [Init](https://praison.ai/docs/cli/init.md)
>
> Single-agent `.praisonai/` scaffold

> [card] [AgentTeam](https://praison.ai/docs/concepts/agentteam.md)
>
> The AgentTeam runtime this scaffold targets

> [card] [Tasks](https://praison.ai/docs/concepts/tasks.md)
>
> Task schema referenced by `tasks.yaml`

> [card] [Process](https://praison.ai/docs/concepts/process.md)
>
> Sequential vs hierarchical execution

> [card] [Run](https://praison.ai/docs/cli/run.md)
>
> Running scaffolded agents and commands

> [card] [Custom Agents & Commands](https://praison.ai/docs/features/custom-agents-commands.md)
>
> The `.praisonai/` convention


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.