Editor Support

Autocomplete, inline validation, and hover docs for agents.yaml and CLI config in any LSP-aware editor

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

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

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

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

npm install -g yaml-language-server

Which schema for which file

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

User Interaction Flow

1. Run praisonai init → get .praisonai/config.yaml and agents.yaml, both with the language-server header.
2. Open agents.yaml in VS Code (YAML extension installed).
3. Type ro under the root → autocomplete offers roles / role at the correct nesting level with hover docs.
4. Misspell backstroy: → a red squiggle appears immediately, before saving or running any command.
5. 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.

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

Related