Editor Support

A single comment line at the top of agents.yaml unlocks autocomplete, inline validation, and hover docs in any LSP-aware editor.

from praisonaiagents import Agent

# The scaffolded agents.yaml now ships with editor autocomplete out of the box.
# Runtime behaviour is unchanged — the header is a YAML comment.
agent = Agent(
    name="Researcher",
    instructions="Find and summarise the latest info on {topic}",
)

agent.start("quantum error correction breakthroughs in 2026")

Quick Start

Scaffold a new project

praisonai init writes agents.yaml with the # yaml-language-server: $schema=… header already in place. Open it in VS Code with the YAML extension and you immediately get autocomplete for roles, agents, tasks, tools, llm, and workflow.

praisonai init

Add editor support to an existing agents.yaml

Paste one comment line at the top of any existing file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json
roles:
  researcher:
    role: Research Analyst
    goal: Find and summarise the latest info on {topic}
    backstory: Expert at spotting reliable primary sources.

How the header wires it up

The editor reads the leading comment, fetches the schema, and starts validating as you type.

What you get

The header enables four editor affordances against the published schema:

Key/value autocomplete — roles, agents, tasks, tools, llm, workflow at the correct nesting level.
Inline error markers — a red squiggle on unknown keys the moment you type them.
Hover docs — descriptions sourced from the Pydantic description=… fields.
Structural checks — e.g. workflow steps needing both agent and task.

Emit the schema locally

Offline or air-gapped setups can generate the schema file and point the editor at it.

praisonai validate schema --agents              # print to stdout
praisonai validate schema -o agents.schema.json # write to a file

Successful write output:

✓ Wrote agents JSON Schema to agents.schema.json

The emitted file starts like this:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json",
  "title": "PraisonAI Agents Configuration",
  "description": "Schema for agents.yaml consumed by the PraisonAI agent runtime (roles/agents, tasks, tools, llm, workflow).",
  "type": "object",
  "properties": {
    "roles": {
      "title": "Roles",
      "description": "Agent role definitions"
    }
  }
}

Then point the editor at the local file:

# yaml-language-server: $schema=./agents.schema.json

Editor setup

VS Code
Neovim / Helix
JetBrains IDEs

Install the YAML extension by Red Hat. The header is enough — no settings.json change needed.Optional: pin via yaml.schemas when you cannot embed the header (e.g. a shared config):

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json": "agents*.yaml"
  }
}

Install yaml-language-server; the header is respected by any LSP-aware editor.

npm install -g yaml-language-server

In PyCharm/WebStorm: Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings. Add either the URL or the file emitted by -o, with the file mask agents*.yaml.

Which schema for which file

PraisonAI publishes two schemas — one for the CLI config, one for agent definitions.

File	Schema	Published URL
`.praisonai/config.yaml` (CLI defaults)	`config.schema.json`	https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/cli/configuration/config.schema.json
`agents.yaml` (agent/task/workflow definitions)	`agents.schema.json`	https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json

User Interaction Flow

Run praisonai init → get .praisonai/config.yaml and agents.yaml, both with the language-server header.
Open agents.yaml in VS Code (YAML extension installed).
Type ro under the root → autocomplete offers roles / role at the correct nesting level with hover docs.
Misspell backstroy: → a red squiggle appears immediately, before saving or running any command.
On an air-gapped machine: run praisonai validate schema -o agents.schema.json once, commit the file, and swap the header to # yaml-language-server: $schema=./agents.schema.json.

The header is a YAML comment — yaml.safe_load ignores it, so praisonai start agents.yaml behaves identically with or without it.

Common Patterns

Add editor support to an existing config

# yaml-language-server: $schema=https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json

roles:
  researcher:
    role: Research Analyst
    goal: Find and summarise the latest info on {topic}
    backstory: Expert at spotting reliable primary sources.
    tasks:
      collect_sources:
        description: Collect 5 recent, authoritative sources on {topic}.
        expected_output: A bulleted list of sources with one-line summaries.

Pin a local schema for offline work

# Print to stdout (useful for piping to jq / diff)
praisonai validate schema --agents

# Write a local file the editor can point at
praisonai validate schema -o agents.schema.json

Then in agents.yaml:

# yaml-language-server: $schema=./agents.schema.json

Best Practices

Let praisonai init add the header for you

Scaffolded agents.yaml files ship with the header already in place — no manual step. Just install the YAML extension and start typing.

Pin a local schema for air-gapped machines

Run praisonai validate schema -o agents.schema.json once, commit the file, and point the header at ./agents.schema.json so editors work without network access.

Use yaml.schemas when you cannot embed the header

For shared configs where a leading comment is undesirable, map the schema in VS Code settings.json via yaml.schemas with the agents*.yaml file mask instead.

Remember the header never affects runtime

The header is a plain YAML comment. Runtime parsing and execution are unchanged, so it is always safe to keep it committed.

Validate

Emit the machine-readable schema and validate configs

Config CLI

Manage project and global configuration

Init

Scaffold a project with the editor header in place

CLI Configuration

Layered, project-aware CLI defaults

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How the header wires it up

What you get

Emit the schema locally

Editor setup

Which schema for which file

User Interaction Flow

Common Patterns

Add editor support to an existing config

Pin a local schema for offline work

Best Practices

Validate

Config CLI

Init

CLI Configuration

​Quick Start

​How the header wires it up

​What you get

​Emit the schema locally

​Editor setup

​Which schema for which file

​User Interaction Flow

​Common Patterns

​Add editor support to an existing config

​Pin a local schema for offline work

​Best Practices

​Related

Validate

Config CLI

Init

CLI Configuration

Quick Start

How the header wires it up

What you get

Emit the schema locally

Editor setup

Which schema for which file

User Interaction Flow

Common Patterns

Add editor support to an existing config

Pin a local schema for offline work

Best Practices

Related