Validate - PraisonAI

Catch configuration mistakes before they cause runtime failures — praisonai validate checks your YAML files against the full schema and reports every error at once.

Quick Start

Validate a single file (success path)

praisonai validate agents.yaml

Output:

✅ agents.yaml is valid

Validate a file with errors (failure path)

praisonai validate agents.yaml

Output when the config has problems:

❌ agents.yaml is invalid

Configuration validation failed with 2 error(s):
  1. Agent 'researcher': missing required field 'goal'
  2. Task 'write_report': references unknown agent 'writer' (not defined in agents/roles)

Additionally, there are 1 warning(s):
  1. Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored.

Exit code: 1

CI usage — strict mode + JSON output

praisonai validate agents.yaml --strict --json

Output:

{
  "file": "agents.yaml",
  "valid": false,
  "errors": [
    "Agent 'researcher': missing required field 'goal'"
  ],
  "warnings": [
    "Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored."
  ],
  "strict_mode": true
}

With --strict, warnings are also treated as errors, so exit code is 1 even when only warnings are present.

Emit machine-readable schema

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

Point your editor’s YAML language server at the file for autocomplete and inline validation — see Editor Support.

Subcommands

Command	Purpose
`praisonai validate <file>`	Validate a single YAML file
`praisonai validate check [directory]`	Validate every YAML file in a directory
`praisonai validate schema`	Print the YAML config schema (fields, types, required markers), or emit the machine-readable JSON Schema with `--agents` / `--output` / `-o`

Flags

`praisonai validate <file>`

Flag	Type	Default	Description
`file` (positional)	`str`	—	Path to YAML config to validate
`--strict`	`bool`	`False`	Treat warnings as errors
`--quiet` / `-q`	`bool`	`False`	Only show errors, suppress success messages
`--json`	`bool`	`False`	Emit results as JSON (for CI)

`praisonai validate check [directory]`

Flag	Type	Default	Description
`directory` (positional)	`str`	`"."`	Directory to search for YAML files
`--pattern` / `-p`	`str`	`"*.yaml"`	Glob pattern (also auto-includes `*.yml` when using the default)
`--strict`	`bool`	`False`	Treat warnings as errors
`--stop-on-error`	`bool`	`False`	Stop on the first invalid file

`praisonai validate schema`

With no flags, prints all main config sections with field names, types, and required markers. Two flags emit the machine-readable JSON Schema instead:

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 instead of stdout (implies `--agents`; prints `✓ Wrote agents JSON Schema to <path>` on success)

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

Point your editor’s YAML language server at that schema for autocomplete and inline validation — see Editor Autocomplete.

What Gets Validated

1. Schema Validation

Enforces the Pydantic schema. Every agent must have role, goal, and backstory — these are required. Every task must have description and agent (matching ^[a-zA-Z0-9_-]+$). When process: workflow, the config must also include steps or workflow.

2. Cross-Reference Validation

Every tasks[i].agent must name an agent defined under roles / agents
Workflow step agent fields are validated recursively (through nested steps and routes)
Every handoff.to target must resolve to a known role

3. Tool Validation

Tool names are resolved through ToolResolver:

Unknown tool → error: “Unknown tool ‘X’. Ensure it’s properly installed or defined in your configuration.”
Known optional tool (e.g. PostgreSQLTool, SlackTool, AWSTool, BrowserTool, PandasTool, KubernetesTool) → warning: “Tool ‘X’ requires additional dependencies. Install with: pip install ‘praisonai[tools]’ …“

4. Unknown Fields

Top-level unknown keys and unknown agent/role fields produce warnings, not errors: “Unknown agent field ‘X’. This field will be ignored.”

Unknown-field warnings are non-blocking — your workflow still runs. Only errors (missing required fields, bad cross-references, unknown tools) cause a hard failure.

Output Formats

Plain (Rich)
Quiet (-q)
JSON (--json)
Directory Scan

Default output uses Rich formatting for easy reading in the terminal:

✅ agents.yaml is valid
  Warnings:
    • Unknown agent field 'stream' in agent 'writer'. This field will be ignored.

❌ agents.yaml is invalid

Configuration validation failed with 2 error(s):
  1. Agent 'researcher': missing required field 'goal'
  2. Task 'write_report': references unknown agent 'writer' (not defined in agents/roles)

Additionally, there are 1 warning(s):
  1. Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored.

Only errors are printed; success messages and warnings are suppressed:

praisonai validate agents.yaml -q

Produces no output when valid. On error, only the error block is shown.

Structured output for CI pipelines:

praisonai validate agents.yaml --json

{
  "file": "agents.yaml",
  "valid": true,
  "errors": [],
  "warnings": [],
  "strict_mode": false
}

When invalid:

{
  "file": "agents.yaml",
  "valid": false,
  "errors": [
    "Agent 'researcher': missing required field 'goal'"
  ],
  "warnings": [
    "Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored."
  ],
  "strict_mode": false
}

praisonai validate check renders a Rich table:

┌──────────────────┬─────────┬────────┬──────────┐
│ File             │ Status  │ Errors │ Warnings │
├──────────────────┼─────────┼────────┼──────────┤
│ agents.yaml      │ ✅ PASS │ 0      │ 1        │
│ workflow.yaml    │ ❌ FAIL │ 2      │ 0        │
└──────────────────┴─────────┴────────┴──────────┘

Summary: 1/2 files valid

CI Integration

Add validation to your GitHub Actions workflow to block merges on broken configs:

name: Validate PraisonAI Config
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install PraisonAI
        run: pip install praisonai

      - name: Validate all YAML configs
        run: praisonai validate check . --strict --json

Exit code 1 on any validation failure causes the step to fail.

Strict Mode

Strict mode promotes warnings to errors — useful in CI to keep configs clean. Enable per-command:

praisonai validate agents.yaml --strict
praisonai validate check . --strict

Enable globally via environment variable:

export PRAISONAI_VALIDATE_STRICT=true
praisonai validate agents.yaml

With PRAISONAI_VALIDATE_STRICT=true, all validation runs (including the automatic pre-run check in agents_generator.py) use strict mode.

Runtime YAML normalisation (`_normalize_yaml_config`)

Even without running praisonai validate explicitly, every praisonai start agents.yaml normalises the YAML — and now catches three silent bugs that used to cause agents to disappear. Three rules run during normalisation, all gated by PRAISONAI_VALIDATE_STRICT:

Situation	Non-strict (default)	Strict (`PRAISONAI_VALIDATE_STRICT=true`)
Two agents (or roles) with the same `name`	`WARNING: Duplicate agent name(s) in YAML: ['researcher']`; both preserved as `researcher` and `researcher__dup_1`	`raise ValueError` — run aborts
A `task.agent` referencing an undefined agent	`WARNING: Task 'x' references unknown agent 'y'; skipping.`; task is dropped	`raise ValueError` — run aborts
Two tasks with the same `name` on the same agent	`WARNING: Duplicate task name 'x' for agent 'y' in YAML — kept both by suffixing keys; rename to silence.`; both preserved as `x` and `x__dup_i`	`raise ValueError` — run aborts

Toggle strict mode to abort instead of warn:

export PRAISONAI_VALIDATE_STRICT=true
praisonai start agents.yaml

The __dup_i suffix marks a preserved duplicate. Given a list-form config with two researcher agents:

agents:
  - name: researcher
    role: Research Analyst
    goal: Research topics
    backstory: Expert researcher.
  - name: researcher
    role: Second Researcher
    goal: Research topics
    backstory: Another researcher.

Non-strict output keeps both agents so nothing silently vanishes:

WARNING: Duplicate agent name(s) in YAML: ['researcher'] — kept both by suffixing keys; rename to silence.

The second agent is stored under researcher__dup_1. If you see researcher__dup_1 in traces or logs, it means a duplicate name was collapsed — rename one entry to silence the warning.

Exit Codes

Code	Meaning
`0`	File is valid (or all files in directory are valid)
`1`	One or more errors found, or the file does not exist

Backward-Compatible Aliases

The validator automatically normalises these field aliases — you can use either form:

Alias	Canonical
`agents:`	`roles:`
`topic:`	`input:`
`stream:`	`streaming:`

Fail-Fast Runtime Validation

When you run praisonai start agents.yaml, validation now runs automatically before execution. If any errors are found, the run aborts with an aggregated ValueError:

Configuration validation failed with 2 error(s):
  1. Agent 'researcher': missing required field 'goal'
  2. Task 'write_report': references unknown agent 'writer'

Additionally, there are 1 warning(s):
  1. Unknown agent field 'instrutions'. This field will be ignored.

This replaces the old behaviour where invalid configs emitted non-blocking warnings and continued running.

Best Practices

Run validate before every commit

Add praisonai validate agents.yaml to your pre-commit checks or CI pipeline to catch errors early.

Use --json in automated pipelines

JSON output is easy to parse in scripts or CI steps that need to inspect specific error messages programmatically.

Set PRAISONAI_VALIDATE_STRICT=true in production

Strict mode treats warnings as errors, preventing unknown or misspelled fields from silently being ignored in production environments.

Use validate schema to discover required fields

Run praisonai validate schema to see all fields, their types, and which are required — before writing a new config from scratch.

Wire your editor to the schema for autocomplete

Emit the JSON Schema with praisonai validate schema --agents (or pin it with -o agents.schema.json) and point your editor’s YAML language server at it for autocomplete and inline validation. See Editor Autocomplete.

YAML Configuration Reference

Complete field reference for agents.yaml and workflow.yaml

CLI Reference

All available CLI commands

Doctor

Diagnose environment and dependency issues

Workflow CLI

Run and manage YAML workflows from the terminal

Editor Autocomplete

Wire agents.yaml to your editor for autocomplete and inline validation

​Quick Start

​Subcommands

​Flags

​praisonai validate <file>

​praisonai validate check [directory]

​praisonai validate schema

​What Gets Validated

​1. Schema Validation

​2. Cross-Reference Validation

​3. Tool Validation

​4. Unknown Fields

​Output Formats

​CI Integration

​Strict Mode

​Runtime YAML normalisation (_normalize_yaml_config)

​Exit Codes

​Backward-Compatible Aliases

​Fail-Fast Runtime Validation

​Best Practices

​Related

YAML Configuration Reference

CLI Reference

Doctor

Workflow CLI

Editor Autocomplete

Quick Start

Subcommands

Flags

`praisonai validate <file>`

`praisonai validate check [directory]`

`praisonai validate schema`

What Gets Validated

1. Schema Validation

2. Cross-Reference Validation

3. Tool Validation

4. Unknown Fields

Output Formats

CI Integration

Strict Mode

Runtime YAML normalisation (`_normalize_yaml_config`)

Exit Codes

Backward-Compatible Aliases

Fail-Fast Runtime Validation

Best Practices

Related