docs: document published agents.yaml JSON Schema + editor autocomplete/validation (PR #3437)

[MervinPraison]

Summary

PraisonAI PR #3437 (merged 2026-07-29) publishes a JSON Schema for agents.yaml and wires it into the authoring loop:

• A stable, published schema file at src/praisonai/praisonai/config/agents.schema.json (raw URL below).
• A new CLI surface: praisonai validate schema --agents and praisonai validate schema -o <file>.
• A # yaml-language-server: $schema=…agents.schema.json header prepended to every scaffolded agents.yaml so VS Code (YAML extension) and any LSP-aware editor light up autocomplete, inline validation, and hover docs out of the box.

Today the PraisonAI docs cover the same feature for the CLI config file (config.schema.json) but say nothing about the analogous authoring-time support for agents.yaml — the very surface most users spend the most time editing. This issue captures every doc change needed to bring agents.yaml editor tooling to the same visibility as the CLI-config schema.

Source of truth (all inspected while drafting this issue):

• Upstream PR: fix: publish agents.yaml JSON Schema + wire editor autocomplete/validation PraisonAI#3437
• Upstream issue with full context: Publish a JSON Schema for agents.yaml and wire live editor autocomplete/validation PraisonAI#3427
• SDK schema module: src/praisonai/praisonai/config/schema.py (AGENTS_SCHEMA_URL, AGENTS_SCHEMA_HEADER, generate_agents_schema())
• CLI command: src/praisonai/praisonai/cli/commands/validate.py (schema subcommand, --agents, --output/-o)
• Scaffold writer: src/praisonai/praisonai/auto.py::convert_and_save (writes the header)
• Published artefact: src/praisonai/praisonai/config/agents.schema.json
• Raw schema URL used by editors: https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/src/praisonai/praisonai/config/agents.schema.json

---

What changed in the SDK (grounded in code)

1. New public schema constants (src/praisonai/praisonai/config/schema.py)

AGENTS_SCHEMA_URL = (
    "https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/"
    "src/praisonai/praisonai/config/agents.schema.json"
)
AGENTS_SCHEMA_HEADER = f"# yaml-language-server: $schema={AGENTS_SCHEMA_URL}\n"

def generate_agents_schema() -> dict[str, Any]:
    """JSON Schema derived from YAMLConfig.model_json_schema()."""

The published (authoring) schema is deliberately a touch more permissive than the strict runtime validator so editors accept every YAML shape the runtime accepts — list-form roles/agents, plus configs that rely on runtime normalisation (instructions → backstory, auto-filled role/goal).

2. New CLI flags on praisonai validate schema

src/praisonai/praisonai/cli/commands/validate.py::schema:

Flag	Type	Default	Behaviour
--agents	bool	False	Emit the machine-readable JSON Schema for agents.yaml (derived from YAMLConfig) to stdout, instead of the human-readable summary.
--output / -o	str (path)	None	Write the JSON Schema to a file instead of stdout. Implies --agents. Useful for offline / pinned editor setups.

Existing behaviour (no flags → human-readable summary) is unchanged.

3. Scaffold writer prepends the header

src/praisonai/praisonai/auto.py::convert_and_save now prepends AGENTS_SCHEMA_HEADER when writing a scaffolded agents.yaml. A leading YAML comment is ignored by yaml.safe_load, so runtime parsing/execution is unaffected.

4. Fully backwards-compatible

• No change to how agents.yaml is parsed or executed at runtime.
• Existing agents.yaml files without the header continue to work; users can add the header manually to get editor support.
• No change to the strict ConfigValidator used by praisonai validate (the published schema loosens only the editor view).

---

Documentation changes required

Follow the AGENTS.md rules: all new content goes under docs/features/; edits to docs/cli/*.mdx are updates to existing pages. Nothing in docs/concepts/ may change.

A. NEW PAGE — docs/features/editor-support.mdx

A dedicated feature page for the whole editor-tooling story (CLI config + agents.yaml + init header + local schema emission). This is the primary deliverable.

Frontmatter:

---
title: "Editor Support"
sidebarTitle: "Editor Support"
description: "Autocomplete, inline validation, and hover docs for agents.yaml and CLI config in any LSP-aware editor"
icon: "file-code"
---

Required sections (in this order):

1. Hero one-liner + Mermaid — see diagram spec below.

2. Quick Start (<Steps>) with two steps:

   • Step 1: Scaffold a new project — praisonai init writes agents.yaml with the # yaml-language-server: $schema=… header already in place; opening it in VS Code with the YAML extension immediately yields autocomplete for roles/agents/tasks/tools/llm/workflow.
   • Step 2: Add editor support to an existing agents.yaml — paste one comment line at the top:

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

3. What you get — bullet list of the four editor affordances: key/value autocomplete, inline error markers on unknown keys, hover docs sourced from the Pydantic description=… fields, structural checks (e.g. workflow steps needing agent+task).

4. Emit the schema locally (offline / pinned editor setups) — cover the new CLI:

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

   Show a screenshot-shaped code block of the first ~20 lines of the emitted JSON so users can recognise the artefact. Then show pointing an editor at the local file:

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

5. Editor setup — three <Tab> panels inside a <Tabs> block:

   • VS Code: install the YAML extension by Red Hat; the header is enough — no settings.json change needed. Optional: pin via yaml.schemas if you cannot embed the header (e.g. shared config).
   • Neovim / Helix / any LSP editor: install yaml-language-server; the header is respected.
   • JetBrains IDEs (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.

6. Two schemas, two files — a small table so users don't confuse the CLI-config schema with the agents-YAML schema:

   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

7. Runtime is unaffected — a single <Note> reminding readers that the header is a YAML comment; yaml.safe_load ignores it, so praisonai start agents.yaml behaves identically with or without the header.

8. Related — <CardGroup cols={2}> linking to /docs/cli/validate, /docs/cli/config, /docs/cli/init, /docs/features/cli-configuration.

B. UPDATE — docs/cli/validate.mdx

The current page (as of SHA 8b9549e) documents praisonai validate schema as taking no extra flags. That is now out of date.

Two concrete edits:

1. Extend the praisonai validate schema flag table (currently reads "no extra flags"):

   Flag	Type	Default	Description
   --agents	bool	False	Emit the machine-readable JSON Schema for agents.yaml (derived from YAMLConfig) instead of the human-readable summary.
   --output / -o	str	None	Write the JSON Schema to a file. Implies --agents. Prints ✓ Wrote agents JSON Schema to <path> on success.

2. Add a new "Emit machine-readable schema" <Step> to the Quick Start <Steps> block, right after the current "CI usage" step:

   praisonai validate schema --agents > agents.schema.json
   # or
   praisonai validate schema -o agents.schema.json

3. Cross-link to the new Editor Support page from the Related <CardGroup> at the bottom.

C. UPDATE — docs/cli/init.mdx

The page today (SHA a6f6b0a) already shows the CLI-config schema header injected into .praisonai/config.yaml. It does not mention that praisonai init (and any scaffold path that emits an agents.yaml) now prepends an analogous header to agents.yaml.

Add a short new subsection agents.yaml editor header with:

• A one-sentence explainer that scaffolded agents.yaml files now include the # yaml-language-server: $schema=…agents.schema.json header so editors validate them immediately.
• The exact header text that will appear at the top of a freshly scaffolded agents.yaml.
• A pointer to /docs/features/editor-support for full setup.

D. UPDATE — docs/features/cli-configuration.mdx

The existing <Note> block near the bottom mentions only config.schema.json. Extend it (or add a peer <Note>) so the reader learns that both files get schema-driven editor support:

Editor autocomplete works for both the CLI config file (.praisonai/config.yaml, validated against config.schema.json) and the agent definition file (agents.yaml, validated against agents.schema.json). Full setup: Editor Support.

E. UPDATE — docs.json

Add the new page to the Features sidebar group (per AGENTS.md §1.8, never under Concepts):

• Path to add: docs/features/editor-support
• Suggested placement: adjacent to docs/features/cli-configuration in the same group.
• Do not modify any auto-generated docs/js/… or docs/rust/… entries.

---

Required Mermaid diagrams

Follow AGENTS.md §3 — same colour scheme, white text, classDef declarations, and the mandatory hero diagram at the top of every new page.

D1. Hero diagram for docs/features/editor-support.mdx

graph LR
    subgraph "Editor Support"
        Y["📄 agents.yaml"] --> H["📝 $schema header"]
        H --> LSP["🧠 YAML LSP"]
        LSP --> A["✨ Autocomplete"]
        LSP --> V["❌ Inline validation"]
        LSP --> D["💡 Hover docs"]
    end

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

    class Y input
    class H,LSP process
    class A,V,D output

Loading

D2. "How the header wires it up" flow (also on the new page)

sequenceDiagram
    participant User
    participant Init as praisonai init
    participant File as agents.yaml
    participant Editor as VS Code + YAML LSP
    participant Schema as agents.schema.json

    User->>Init: praisonai init
    Init->>File: write yaml-language-server header + config
    User->>Editor: open agents.yaml
    Editor->>File: read leading comment
    Editor->>Schema: fetch schema URL (or local -o file)
    Schema-->>Editor: JSON Schema
    Editor-->>User: autocomplete + inline errors + hover docs

Loading

D3. "Which schema for which file" chooser (on the new page and echoed in cli-configuration.mdx)

graph TB
    Q{Which YAML<br/>am I editing?}
    Q -->|CLI defaults| C["📄 .praisonai/config.yaml"]
    Q -->|Agents / tasks / workflow| A["📄 agents.yaml"]
    C --> CS["🔗 config.schema.json"]
    A --> AS["🔗 agents.schema.json"]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef file fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef schema fill:#10B981,stroke:#7C90A0,color:#fff

    class Q decision
    class C,A file
    class CS,AS schema

Loading

---

Runnable code examples (all should copy-paste without edits)

Add editor support to an existing agents.yaml

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

Emit the schema locally (offline / pinned setup)

# 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

Successful write output:

✓ Wrote agents JSON Schema to agents.schema.json

Then in agents.yaml:

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

Agent-centric example (per AGENTS.md §1.1 — start with an Agent Centric code example)

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")

---

User interaction flow (per AGENTS.md §1.1 rule 10)

1. User runs praisonai init → gets .praisonai/config.yaml and agents.yaml, both with the language-server header.
2. User opens agents.yaml in VS Code (YAML extension installed).
3. Typing ro under the root shows autocomplete for roles / role at the correct nesting level with hover docs sourced from the Pydantic description=….
4. User misspells backstroy: — a red squiggle appears immediately (before hitting save, before running any command).
5. User has no network / is on an air-gapped machine: runs praisonai validate schema -o agents.schema.json once, commits the file, and swaps the header to # yaml-language-server: $schema=./agents.schema.json.

---

Acceptance criteria

• docs/features/editor-support.mdx created, following the AGENTS.md §2 page template exactly (frontmatter, hero Mermaid with standard palette, <Steps> Quick Start, <Tabs> for editor-specific setup, <AccordionGroup> best practices, <CardGroup> related).
• docs/cli/validate.mdx updated so the praisonai validate schema flag table includes --agents and --output/-o, and the Quick Start <Steps> gains a "machine-readable schema" step.
• docs/cli/init.mdx updated with a subsection describing the agents.yaml editor header.
• docs/features/cli-configuration.mdx updated so the existing <Note> mentions both schemas (or a peer <Note> is added).
• docs.json gains one entry — docs/features/editor-support — under the Features group only. No changes to Concepts, docs/js/, or docs/rust/.
• All code blocks are copy-paste runnable — no your-key-here-style placeholders (per AGENTS.md §9.3).
• Every Mermaid block uses the standard palette (#8B0000 / #189AB4 / #10B981 / #F59E0B / #6366F1) with white text and classDef declarations.
• Field types, defaults, and behaviour on any new/updated table match src/praisonai/praisonai/cli/commands/validate.py::schema and src/praisonai/praisonai/config/schema.py exactly — no invented flags, no invented defaults.
• docs.json remains valid JSON after edits (AGENTS.md §1.9 rule 8).

---

Out of scope for this issue

The following user-facing changes also landed on 2026-07-29 and each deserves its own issue rather than being bundled here:

• PR #3442 — gateway safe-by-default reliability (admission ceiling + drain based on bind posture, reliability="off" opt-out).
• PR #3472 — gateway /stop command, abort capability, and gateway.per_turn_timeout config.
• PR #3497 — auxiliary LLM calls (context compaction, guardrail validation) now route through small_model.
• PR #3507 — per-identity scoping of scheduler automations and suggestions.
• PR #3508 — core dialect converter now consumes markdown_dialect capability.

If any of those need doc coverage, please open separate issues so each stays focused.

[praisonai-triage-agent]

🤖 Auto-triaging with Claude. Analysing issue and implementing a fix...

Claude will:

1. Read AGENTS.md and the SDK source
2. Create or update documentation on a claude/issue-* branch
3. Push and open a PR automatically (Fixes #<issue>)

If the PR is missing after Claude finishes, CI will open it within ~30 minutes.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-2487-20260729-1048 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-2487-20260729-1048?quick_pull=1&title=Issue%20%232487%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%232487%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Task: agents.yaml JSON Schema + Editor Support — Done

• Read AGENTS.md rules
• Read SDK source (schema.py, validate.py, auto.py) — verified all flags/constants against upstream PR #3437
• Read existing docs (validate.mdx, init.mdx, cli-configuration.mdx, docs.json)
• Create docs/features/editor-support.mdx
• Update docs/cli/validate.mdx
• Update docs/cli/init.mdx
• Update docs/features/cli-configuration.mdx
• Update docs.json (valid JSON verified)
• Commit, push, open PR

PR: #2501

What was done

• NEW docs/features/editor-support.mdx — hero + sequence + decision Mermaid diagrams (standard palette, white text, classDef), agent-centric Quick Start <Steps>, <Tabs> for VS Code / Neovim / JetBrains, <AccordionGroup> best practices, <CardGroup> related, the "two schemas / two files" table, local schema emission (--agents / -o), and a user-interaction flow.
• UPDATE docs/cli/validate.mdx — added --agents and --output/-o to the validate schema flag table + subcommand row, a new "Emit machine-readable schema" Quick Start step, and a related card.
• UPDATE docs/cli/init.mdx — new agents.yaml editor header subsection with the exact header string + related card.
• UPDATE docs/features/cli-configuration.mdx — <Note> now mentions both config.schema.json and agents.schema.json + related card.
• UPDATE docs.json — added docs/features/editor-support under the Features group (no Concepts / js / rust changes).

All flag names, types, defaults, the ✓ Wrote agents JSON Schema to <path> message, and the emitted schema shape were verified against config/schema.py, cli/commands/validate.py, and auto.py in the cloned PraisonAI SDK — nothing invented.

Branch: claude/issue-2487-20260729-1048 ·