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

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

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

  <Step title="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
    ```
  </Step>
</Steps>

***

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

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

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

  <Accordion title="Regenerate the pinned schema after upgrading">
    After `pip install -U praisonai`, refresh your local copy: `praisonai validate schema -o agents.schema.json`.
  </Accordion>

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

***

## Related

<CardGroup cols={2}>
  <Card title="Validate CLI" icon="circle-check" href="/docs/cli/validate">
    Fail-fast YAML validation and the `schema --agents` / `-o` flags
  </Card>

  <Card title="YAML Configuration Reference" icon="book" href="/docs/features/yaml-configuration-reference">
    Complete field reference for agents.yaml and workflow\.yaml
  </Card>
</CardGroup>