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

# Editor Autocomplete for agents.yaml

> Get autocomplete, inline validation, and hover docs while authoring agents.yaml

Every new `agents.yaml` PraisonAI scaffolds comes pre-wired for editor autocomplete — no setup required.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Y["📄 agents.yaml"] --> H["# yaml-language-server:<br/>$schema=…"]
    H --> E["🖊️ Editor"]
    E --> AC["✅ Autocomplete"]
    E --> IV["⚠️ Inline errors"]
    E --> HD["📖 Hover docs"]

    classDef file fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef header fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef editor fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Y file
    class H header
    class E editor
    class AC,IV,HD result
```

## Quick Start

**1. Zero-config — scaffold a new project**

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

The generated `agents.yaml` has the schema directive on line 1:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# yaml-language-server: $schema=https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json
framework: praisonai
roles:
  researcher:
    role: Research Analyst
    goal: Research the topic
    backstory: Expert researcher.
```

Open it in VS Code (with the Red Hat YAML extension) and you get autocomplete immediately.

**2. Add it to an existing agents.yaml**

Paste this one line at the top of any `agents.yaml`:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# yaml-language-server: $schema=https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json
```

Your editor fetches the schema and starts suggesting fields as you type.

**3. Pin the schema locally**

For offline or air-gapped setups, write the schema to a file:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai validate schema -o agents.schema.json
```

Then point the header at the local copy:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# yaml-language-server: $schema=./agents.schema.json
```

***

## How It Works

The header is a leading YAML comment, so `yaml.safe_load` ignores it — runtime parsing and execution are unchanged. It's authoring-time only.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Editor
    participant LSP as YAML Language Server
    participant Schema as Schema (URL or local file)

    Editor->>LSP: Open agents.yaml
    LSP->>Schema: Fetch $schema from header
    Schema-->>LSP: JSON Schema
    LSP-->>Editor: Completions + inline errors + hover docs
```

| Step | What happens |
| - | - |
| Header read | The YAML language server reads the `$schema` directive on line 1 |
| Schema load | It fetches the URL (or reads the local file for pinned setups) |
| Assist | It returns field completions, red-underlines invalid values, and shows hover docs |

***

## Editor Support

| Editor | Setup |
| - | - |
| VS Code | Install the [YAML extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml); the header is picked up automatically |
| JetBrains IDEs (PyCharm, WebStorm, IntelliJ) | YAML support is built in; the schema directive is honoured automatically |
| Neovim / Vim | Install `yaml-language-server` via any LSP client (coc.nvim, nvim-lspconfig) |
| Zed | Built-in YAML language server support |
| Sublime Text | Install `LSP-yaml` |

***

## Two Flavours

The published (editor) schema is intentionally a touch more permissive than the strict runtime validator, so editors never red-underline valid, executable YAML.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph Authoring["Editor Schema (authoring)"]
        A1["role / goal / backstory optional<br/>(runtime auto-fills them)"]
        A2["roles / agents accept dict OR list form"]
    end

    subgraph Runtime["Runtime Validator (strict)"]
        R1["role / goal / backstory required"]
        R2["roles / agents require dict form"]
    end

    A1 -.stricter at run time.-> R1
    A2 -.stricter at run time.-> R2

    classDef authoring fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef runtime fill:#8B0000,stroke:#7C90A0,color:#fff

    class A1,A2 authoring
    class R1,R2 runtime
```

Two intentional relaxations in the editor schema:

* `role`/`goal`/`backstory` are optional — the runtime auto-fills `role`/`goal` from the agent key and maps `instructions` → `backstory`.
* `roles` and `agents` accept **either** the canonical dict form **or** a list form (`anyOf`).

The strict validator behind `praisonai validate` still requires the dict form and all three fields, so run `validate` before shipping.

***

## Best Practices

> [accordion] Pin the schema locally for air-gapped setups
>
> Run `praisonai validate schema -o agents.schema.json` and point the header at `./agents.schema.json` so authoring works with no network access.

> [accordion] Use the header and praisonai validate together
>
> The header catches typos while you type; `praisonai validate` enforces the strict runtime rules before you run. They cover different layers — use both.

> [accordion] Regenerate the pinned schema after upgrading
>
> After `pip install -U praisonai`, refresh your local copy: `praisonai validate schema -o agents.schema.json`.

> [accordion] Embed the schema in your own tooling (advanced)
>
> Power users can import `AGENTS_SCHEMA_URL`, `AGENTS_SCHEMA_HEADER`, and `generate_agents_schema()` from `praisonai.config` to generate or host the schema themselves.

***

## Related

> [card] [Validate CLI](https://praison.ai/docs/cli/validate.md)
>
> Fail-fast YAML validation and the `schema --agents` / `-o` flags

> [card] [YAML Configuration Reference](https://praison.ai/docs/features/yaml-configuration-reference.md)
>
> Complete field reference for agents.yaml and workflow\.yaml


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