YAML Validation

Catch duplicate agent/task names and unknown task→agent references before an agent starts

Duplicate agent names or a typo in task.agent used to collapse your YAML silently — a 3-agent config could run as 1. Now you get a warning by default, and an exception under PRAISONAI_VALIDATE_STRICT=true.

Why this exists

Before this validation existed, a YAML with a duplicate name: researcher on two agents ran as one agent — the second silently overwrote the first via a dict-merge collapse. A task typo like agent: reseacher (missing an r) skipped the task with no message. Both problems look like a broken run with no clear cause.

PRAISONAI_VALIDATE_STRICT=true turns those silent collapses into loud failures. In CI, prefer strict. In development, the default warning gives you the same hint without stopping the session.

Strictness resolves in this order:

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

Quick Start

1. Default (warn)

   A duplicate name: no longer overwrites the first agent — both are kept under suffixed keys and you get a warning.

   agents:
     - name: researcher
       instructions: "Research the topic"
     - name: researcher
       instructions: "Different researcher, same name"

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

   Both entries survive; the colliding one is preserved under researcher__dup_1 (0-based list index).

2. Strict (CI)

   Turn the warning into a hard failure so CI catches the config before an agent starts.

   export PRAISONAI_VALIDATE_STRICT=true

   ValueError: Duplicate agent name(s) in YAML: ['researcher']

3. Unknown task agent

   A task whose agent: doesn’t match any defined agent warns by default, raises under strict.

   agents:
     - name: researcher
       instructions: "Research the topic"
   
   tasks:
     - name: draft_report
       agent: reseacher   # typo: missing an 'r'
       description: "Draft the report"

   WARNING  Task 'draft_report' references unknown agent 'reseacher'; skipping.

   Under PRAISONAI_VALIDATE_STRICT=true:

   ValueError: Task 'draft_report' references unknown agent 'reseacher'; skipping.

How It Works

When both roles: and agents: are present, roles: wins for task→agent resolution.

Unknown-field warnings

Any YAML key the schema doesn’t declare is flagged, then ignored — so a typo like instrucions: doesn’t silently drop your instructions.

foo: bar                 # unknown top-level key

agents:
  myagent:
    role: Researcher
    goal: Find facts
    instructions: "Research the topic"
    bar: baz             # unknown agent key

Unknown top-level field 'foo'. This field will be ignored.
agents.myagent: Unknown field 'bar'. This field will be ignored.

The field lists are derived from the Pydantic schema, not hand-maintained:

• Top-level keys are checked against YAMLConfig.model_fields.
• Agent-block keys are checked against AgentConfig.model_fields | {"name"}.

Adding a field to YAMLConfig or AgentConfig automatically teaches the validator — there is no second list to edit. This is why type, deploy, and dependencies (added to YAMLConfig in PraisonAI PR #4651) stopped warning the moment they were declared on the schema.

Choosing a mode

Configuration

PRAISONAI_VALIDATE_STRICT controls whether validation issues warn or raise.

# Strict — raise on any validation issue
export PRAISONAI_VALIDATE_STRICT=true

# Non-strict (default) — warn only. These all count as non-strict:
export PRAISONAI_VALIDATE_STRICT=1     # ⚠️ still non-strict
export PRAISONAI_VALIDATE_STRICT=yes   # ⚠️ still non-strict
unset PRAISONAI_VALIDATE_STRICT        # non-strict

Duplicate-preserved key naming

Under the default (warn) mode, colliding entries are kept — not dropped. The duplicate is stored under a suffixed key so both survive:

{name}__dup_{i}

i is the 0-based list index of the colliding entry. A second agent named researcher at list index 1 becomes researcher__dup_1.

Grep-friendly messages

Copy these into your CI log filters:

Duplicate agent name(s) in YAML: ['researcher'] — kept both by suffixing keys; rename to silence.
Task 'draft_report' references unknown agent 'reseacher'; skipping.

Under PRAISONAI_VALIDATE_STRICT=true the same conditions raise:

ValueError: Duplicate agent name(s) in YAML: ['researcher']
ValueError: Task 'draft_report' references unknown agent 'reseacher'; skipping.

Best Practices

Related