Validate

Fail-fast YAML configuration validation with aggregated, actionable errors

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

1. Validate a single file (success path)

   praisonai validate agents.yaml

   Output:

   ✅ agents.yaml is valid

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

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

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

Flags

praisonai validate <file>

praisonai validate check [directory]

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:

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.resolve(name):

• Unknown tool → error: “Unknown tool ‘X’. Ensure it’s properly installed or defined in your configuration.” — the name doesn’t exist in the local tools.py, the wrapper registry, TOOL_MAPPINGS, praisonai-tools, or any registered plugin.
• Known optional tool → warning: “Tool ‘X’ requires additional dependencies. Install with: pip install ‘praisonai[tools]’ …” — the name is recognised (either in the hardcoded optional-tool list or in TOOL_MAPPINGS), but the optional dependency isn’t installed.

Recognised optional-tool families include database (PostgreSQLTool, MongoDBTool, RedisTool, ElasticsearchTool, …), messaging (SlackTool, DiscordTool, TelegramTool, EmailTool, TwitterTool, LinkedInTool, GitHubTool), cloud (AWSTool, AzureTool, GCPTool, S3Tool), AI/ML (HuggingFaceTool, OpenAITool, AnthropicTool), data (PandasTool, NumpyTool, ScipyTool), and browser/infra (BrowserTool, SeleniumTool, PlaywrightTool, KubernetesTool, DockerTool, TerraformTool). Any built-in tool declared in TOOL_MAPPINGS (e.g. duckduckgo, wiki_search, execute_code, crawl4ai) is also treated as a known tool — missing deps yield a warning, not an error.

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

Output Formats

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

praisonai validate agents.yaml -q

praisonai validate agents.yaml --json

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

{
  "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
}

┌──────────────────┬─────────┬────────┬──────────┐
│ 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.

Embedding the wrapper? Set strictness per run instead of via the env var:

from praisonai import PraisonAI

PraisonAI(agent_file="agents.yaml", strict_validation=True).run()

# or, from the AgentsGenerator directly:
from praisonai.agents_generator import AgentsGenerator

AgentsGenerator(agent_file="agents.yaml", framework="praisonai", config_list=[], cli_config={"strict_validation": True})

Strictness resolves in this order:

strict_validation:
  explicit arg  >  cli_config["strict_validation"]  >  PRAISONAI_VALIDATE_STRICT env  >  False (default)

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:

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

Backward-Compatible Aliases

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

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

Related