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

# Agent Behaviour Flags in YAML

> Turn planning, reflection, guardrails, web, skills, and autonomy on or off from agents.yaml

These YAML keys under each `roles:` entry map directly onto the corresponding `Agent(...)` kwargs when you run with `framework: praisonai`.

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

agent = Agent(
    name="Coder",
    instructions="Refactor code with a plan and self-review.",
    planning=True,
    reflection=True,
    autonomy="auto_edit",
)
agent.start("Refactor the authentication module.")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Agent Flags in YAML"
        YAML[📄 agents.yaml] --> Adapter[⚙️ PraisonAI Adapter]
        Adapter --> Core[🤖 Agent]
        Core --> Result[✅ Response]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class YAML input
    class Adapter process
    class Core agent
    class Result output
```

## Quick Start

**1. Simple — one flag on**

Enable a single behaviour flag in `agents.yaml`, then run it.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
roles:
  writer:
    role: "Writer"
    goal: "Draft clear content"
    backstory: "Senior technical writer"
    planning: true
    tasks:
      draft:
        description: "Draft an intro for {{topic}}"
        expected_output: "A short intro paragraph"
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai start agents.yaml
```

**2. All flags**

Combine every behaviour flag on one agent.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
roles:
  coder:
    role: "Autonomous Coder"
    goal: "Complete coding tasks with minimal supervision"
    backstory: "Senior engineer"
    autonomy: 6            # -> "auto_edit" preset in core
    planning: true         # forwarded as-is
    reflection: true       # forwarded as-is
    web: true              # forwarded as-is
    skills: ["python", "testing"]
    guardrails: ["no_prod_writes"]
    tasks:
      write_tests:
        description: "Write pytest tests for {{topic}}"
        expected_output: "A file with pytest test cases"
```

**3. From code**

The same flags as `Agent(...)` kwargs — identical behaviour, no YAML.

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

agent = Agent(
    name="Coder",
    instructions="Complete coding tasks with minimal supervision.",
    planning=True,
    reflection=True,
    web=True,
    skills=["python", "testing"],
    guardrails=["no_prod_writes"],
    autonomy="auto_edit",
)
agent.start("Write pytest tests for the auth module.")
```

***

## Flag reference

Each key maps onto one `Agent(...)` kwarg — follow the deep-dive link for the full option set.

| YAML key | Type | Core kwarg | Notes | Deep dive |
| - | - | - | - | - |
| `planning` | `bool` | `planning=` | Enables planning mode. | [Planning](https://praison.ai/docs/features/planning-mode.md) |
| `reflection` | `bool` | `reflection=` | Enables self-reflection. | [Reflection](https://praison.ai/docs/features/reflection.md) |
| `guardrails` | `list[str]` | `guardrails=` | Names of guardrails to apply. | [Guardrails](https://praison.ai/docs/features/guardrails.md) |
| `web` | `bool` | `web=` | Enables built-in web tools. | [Web](https://praison.ai/docs/features/web.md) |
| `skills` | `list[str]` | `skills=` | Skills the agent has. | [Skills](https://praison.ai/docs/features/skills.md) |
| `autonomy` | `int 0-10` | `autonomy=` (preset str) | Wrapper maps 1-3→`suggest`, 4-7→`auto_edit`, 8-10→`full_auto`. Also accepts bool/str/dict passthrough. | [Autonomy](https://praison.ai/docs/features/autonomy.md) |

***

## How It Works

The CLI hands your `agents.yaml` to the adapter, which forwards each flag into the core `Agent` constructor.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as CLI (praisonai start)
    participant Adapter as PraisonAIAdapter
    participant Agent

    User->>CLI: agents.yaml
    CLI->>Adapter: _build_agents_and_tasks(config)
    Adapter->>Agent: Agent(planning=..., reflection=..., autonomy="auto_edit", ...)
    Agent-->>User: response
```

***

## Autonomy Levels in YAML

The `autonomy` integer maps onto a core preset before it reaches `Agent(autonomy=…)`.

| YAML `autonomy:` value | Core preset |
| - | - |
| `0` (or omitted) | off |
| `1` – `3` | `suggest` |
| `4` – `7` | `auto_edit` |
| `8` – `10` | `full_auto` |

`bool` / `str` preset / `dict` / `AutonomyConfig` values pass through unchanged, mirroring the Python API.

***

## Best Practices

> [accordion] Start with autonomy: 3 and graduate up
>
> Begin at `autonomy: 3` (the `suggest` preset) so the agent proposes changes for your approval. Raise the level to `auto_edit` (4-7) or `full_auto` (8-10) once you trust its behaviour.

> [accordion] Combine planning with reflection
>
> Set `planning: true` and `reflection: true` together for research-heavy tasks — the agent plans its steps, then self-reviews each result.

> [accordion] Use guardrail names, not callables
>
> `guardrails:` takes a list of registered guardrail names. YAML can't express Python functions, so define callables in code and reference them by name here.

> [accordion] Use the dict form for advanced autonomy
>
> For fine-grained tuning (iteration caps, doom-loop thresholds), use `autonomy: {...}` dict form instead of the 0-10 int — the dict is passed through to `AutonomyConfig` unchanged.

***

## Related

> [card]
>
> YAML Configuration Reference — the full field table
>
> [Open](https://praison.ai/docs/features/yaml-configuration-reference.md)

> [card]
>
> Autonomy — deep dive into levels, doom-loop protection, and budgets
>
> [Open](https://praison.ai/docs/features/autonomy.md)


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