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.

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)

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`

Prints all main config sections with field names, types, and required markers — no extra flags.

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.

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.

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

​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

​Exit Codes

​Backward-Compatible Aliases

​Fail-Fast Runtime Validation

​Best Practices

​Related

YAML Configuration Reference

CLI Reference

Doctor

Workflow CLI

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

Exit Codes

Backward-Compatible Aliases

Fail-Fast Runtime Validation

Best Practices

Related