YAML Configuration Reference

Complete reference for agents.yaml and workflow.yaml configuration options

Complete reference for all configuration options in agents.yaml and workflow.yaml files.

Quick Start

1. Load an agent from YAML

   from praisonaiagents import Agent
   
   agent = Agent(name="yaml-runner", instructions="Behaviour defined in agents.yaml")
   agent.start("Run the workflow defined in YAML")

2. Run the YAML workflow

   praisonai start agents.yaml

   The user maintains YAML config; the agent loads it and executes the requested workflow.

How It Works

Quick Comparison

framework: praisonai
topic: "Research AI trends"

roles:
  researcher:
    role: Research Analyst
    backstory: "Expert researcher"
    goal: Research topics
    tools:
      - tavily_search

  researcher:
    tasks:
      research_task:
        description: "Research {{topic}}"
        expected_output: "Research report"

name: Research Workflow
input: "Research AI trends"

agents:
  researcher:
    role: Research Analyst
    instructions: "Expert researcher"
    goal: Research topics
    tools:
      - tavily_search

steps:
  - agent: researcher
    action: "Research {{input}}"
    expected_output: "Research report"

Field Name Mapping

PraisonAI accepts both old and new field names. Use canonical names for new projects.

List vs. Dict Shape

PraisonAI auto-normalises list-form agents, roles, and tasks into dict form on load — you don’t need to convert legacy configs by hand.

agents:
  - name: researcher
    role: Research Analyst
    instructions: "Expert researcher"

tasks:
  - name: research_task
    agent: researcher
    description: "Research {{topic}}"

agents:
  researcher:
    role: Research Analyst
    instructions: "Expert researcher"
    tasks:
      research_task:
        description: "Research {{topic}}"

Empty roles: {} Is Treated as Missing

A YAML that carries an empty roles: {} alongside a populated agents: block (dict or list) and a list-form tasks: promotes the agents into roles and grafts the tasks — it does not run with zero agents.

This YAML now yields one role per agent with its tasks attached:

framework: praisonai
topic: research renewable energy
roles: {}
agents:
  researcher:
    role: Renewable Energy Researcher
    goal: Find the latest solar breakthroughs
    backstory: A materials-science PhD.
tasks:
  - name: summarise
    agent: researcher
    description: Summarise the top 3 breakthroughs of 2026.
    expected_output: A 3-bullet summary.

Shorthand: agents: gets promoted to roles:

agents.yaml accepts two spellings of the same idea. The shorthand agents: bucket is merged into roles: before the workflow runs, so both forms produce the same result.

framework: praisonai
roles:
  writer:
    role: "Writer"
    goal: "Draft clear content"
    tasks:
      draft:
        description: "Draft an intro for {{topic}}"

framework: praisonai
agents:
  writer:
    role: "Writer"
    goal: "Draft clear content"
    tasks:
      draft:
        description: "Draft an intro for {{topic}}"

As of PraisonAI PR #5307 the merge is authoritative — _prepare_for_run promotes the shorthand and then drops it so validators and the executor read a single source of truth:

• agents: is deleted after promotion, so downstream validators and the executor read the same map.
• When both spellings define the same key, the canonical roles: entry wins.
• instructions: inside an agent block is renamed to backstory: during promotion (existing behaviour, unchanged).

Precedence on conflict — the canonical roles: entry wins and the agents: duplicate is ignored:

framework: praisonai
roles:
  writer:
    role: "Senior Writer"          # ← wins
agents:
  writer:
    role: "Junior Writer"          # ← ignored (canonical roles: wins)

Task Ordering in Roles-File YAML

Tasks in a roles-file YAML run in the order they are declared under each role and, across roles, in the order the roles appear.

The loader walks roles: top-to-bottom, and each role’s tasks: top-to-bottom, appending every task to a single run list in that order.

framework: praisonai
topic: "Latest AI research"

roles:
  researcher:
    role: Research Analyst
    goal: Gather findings on the topic
    backstory: Expert researcher.
    tasks:
      research_task:
        description: "Research {{topic}}"
        expected_output: "A list of key findings"

  writer:
    role: Technical Writer
    goal: Summarise the findings
    backstory: Clear, concise writer.
    tasks:
      summary_task:
        description: "Summarise the research findings"
        expected_output: "A short summary"

# documentary only — the roles-file loader does NOT read this block
dependencies:
  summary_task:
    - research_task

research_task runs first because researcher is declared before writer; summary_task runs second. The dependencies: block reflects that intent for readers but does not drive it.

Copy-paste starter: examples/yaml/teams/research-writer/.

Running a Roles-File YAML

A roles-file YAML runs as a positional argument to praisonai; from Python the equivalent is praisonai.run(<path>).

export OPENAI_API_KEY=sk-...
praisonai agents.yaml

import praisonai

praisonai.run("agents.yaml")

See CLI Reference for the full flag surface of the positional form, and praisonai run for the per-prompt entry point.

Automatic Field Validation

PraisonAI validates every field name in your agents.yaml before execution begins — unknown fields produce warnings and invalid configs abort immediately.

1. Create YAML with typo

   # agents.yaml
   framework: praisonai
   topic: "Summarize Python history"
   agents:
     researcher:
       role: Research Analyst
       goal: Provide a historical summary
       instrutions: "Focus ONLY on years 1989–2000."   # typo — warning
       backstory: Expert researcher.

2. Run workflow and see warning

   praisonai start agents.yaml

   Output (unknown field → warning, workflow still runs):

   WARNING: Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored.

3. Validate before running

   praisonai validate agents.yaml

   Catch all errors upfront without running the workflow.

Fail-Fast Errors

These conditions abort the run immediately with an aggregated error message.

Missing required field:

agents:
  researcher:
    role: Research Analyst
    # goal is required but missing
    backstory: Expert researcher.

Result:

Configuration validation failed with 1 error(s):
  1. Agent 'researcher': missing required field 'goal'

Bad cross-reference (task references undefined agent):

agents:
  researcher:
    role: Research Analyst
    goal: Research topics
    backstory: Expert researcher.

tasks:
  write_report:
    description: Write a report
    agent: writer      # 'writer' is not defined!

Result:

Configuration validation failed with 1 error(s):
  1. Task 'write_report': references unknown agent 'writer' (not defined in agents/roles)

Unknown tool:

agents:
  researcher:
    role: Research Analyst
    goal: Research topics
    backstory: Expert researcher.
    tools:
      - nonexistent_tool

Result:

Configuration validation failed with 1 error(s):
  1. Unknown tool 'nonexistent_tool'. Ensure it's properly installed or defined in your configuration.

Optional tools with extra dependencies produce a warning instead:

WARNING: Tool 'BrowserTool' requires additional dependencies. Install with: pip install 'praisonai[tools]'

Required Agent Fields

The editor schema (used for autocomplete) does not require these three fields — the runtime auto-fills role/goal from the agent key and maps instructions → backstory. The strict validator behind praisonai validate still requires them, so run validate before shipping even if your editor shows no errors.

Recognized Fields

All recognized field names for agents in both agents: and roles: sections:

Agent Behaviour Flags

Six per-agent keys map directly onto the matching Agent(...) kwargs. See Agent Behaviour Flags in YAML for the full mapping and Autonomy for the level presets.

roles:
  writer:
    role: "Writer"
    goal: "Draft and refine content"
    backstory: "Senior technical writer"
    planning: true          # enable planning
    reflection: true        # enable self-reflection
    guardrails: ["safe_output"]
    web: true               # enable web tools
    skills: ["research", "editing"]
    autonomy: 3             # -> suggest preset

The autonomy integer maps onto a core preset before it reaches Agent(autonomy=…):

framework: praisonai
roles:
  coder:
    role: "Autonomous Coder"
    goal: "Complete coding tasks with minimal supervision"
    backstory: "Senior engineer"
    autonomy: 6            # -> "auto_edit" preset in core
    planning: true         # forwarded as-is
    reflection: true       # forwarded as-is
    web: true              # forwarded as-is
    skills: ["python", "testing"]
    guardrails: ["no_prod_writes"]
    tasks:
      write_tests:
        description: "Write pytest tests for {{topic}}"
        expected_output: "A file with pytest test cases"

Deep dives: Planning, Reflection, Guardrails, Web, Skills, Autonomy.

execution: block

An agent’s execution: mapping passes straight through to ExecutionConfig, so budget caps and durable runs can be set from YAML.

process: workflow
roles:
  researcher:
    role: Researcher
    goal: Produce a clean summary
    backstory: You research topics thoroughly
    execution:
      max_budget: 1.50           # USD cap for the whole run
      on_budget_exceeded: stop   # stop (default) or warn
      durable: true              # journal this turn's tool calls
      journal_path: .praisonai/journal.sqlite
      resume_run_id: run-123     # replay finished tool calls from this run
    tasks:
      t1:
        description: Summarise the topic
        expected_output: One paragraph

Unknown-Field Warnings

Unknown keys at the top level or in agent/role definitions produce warnings:

WARNING: Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored.
WARNING: Unknown agent field 'xyz_random_field' in agent 'test_agent'. This field will be ignored.

Warnings are non-blocking — the unrecognised field is ignored and the workflow continues. Only use --strict, PRAISONAI_VALIDATE_STRICT=true, or the per-run strict_validation=True override on AgentsGenerator (or cli_config={"strict_validation": True}) to promote them to errors.

Both Sections Covered

The validator inspects both agents: and roles: sections. The warning text changes from agent 'X' to role 'X' accordingly.

Strict Mode

Promote all warnings to errors globally:

export PRAISONAI_VALIDATE_STRICT=true
praisonai start agents.yaml

Strict mode also raises on duplicate agent/task name keys and unknown task→agent references. Without strict mode both are surfaced as loud warnings, and the second entry is preserved with a __dup_i suffix instead of being silently collapsed (as of PR #3176).

Or per-command:

praisonai validate agents.yaml --strict

Root-Level Options

All options available at the root level of your YAML file.

workflow:
  planning: true                    # Enable planning mode
  planning_llm: gpt-4o              # LLM for planning
  reasoning: true                   # Enable reasoning mode
  verbose: true                     # Verbose output
  default_llm: gpt-4o-mini          # Default LLM for all agents
  output: verbose                   # Output mode: silent, minimal, normal, verbose, debug
  memory_config:
    provider: chroma
    persist: true

# Simple enable
context: true

# Detailed configuration
context:
  auto_compact: true           # Enable auto-compaction
  compact_threshold: 0.8       # Trigger at 80% of context window
  strategy: smart              # smart | truncate | sliding_window | summarize | prune_tools
  tool_output_max: 10000       # Max tokens per tool output

agents:
  api_researcher:
    role: API Researcher
    instructions: "Research using external APIs"
    tools: [web_search, api_tool]
    tool_retry_policy:
      max_attempts: 4
      retry_on: [timeout, rate_limit, connection_error]
      backoff_factor: 2.0
      initial_delay_ms: 1000
      jitter: true

variables:
  topic: AI trends
  max_results: 5
  categories:
    - Machine Learning
    - NLP
    - Computer Vision

providers:
  anthropic:
    runtime_default: claude-code
  openai:
    runtime_default: codex-cli

models:
  claude-3-sonnet:
    runtime: claude-code
  gpt-4o:
    runtime: praisonai

models:
  cheap-fast:
    provider: openai
    complexity: [simple]
    cost_per_1k: 0.0001
    capabilities: [text]
    context_window: 16000

  premium:
    provider: anthropic
    complexity: [complex, very_complex]
    cost_per_1k: 0.015
    capabilities: [text, vision, function-calling]
    context_window: 200000
    supports_tools: true
    strengths: [reasoning, analysis]

callbacks:
  on_workflow_start: log_start
  on_step_start: log_step_start
  on_step_complete: log_step_complete
  on_step_error: handle_error
  on_workflow_complete: log_complete

from praisonaiagents.workflows import YAMLWorkflowParser

def log_start(*args, **kwargs):
    print("workflow started")

parser = YAMLWorkflowParser()
parser.register_callback("log_start", log_start)
workflow = parser.parse_file("workflow.yaml")

Agent Options

All options available for agent definitions.

agents:
  writer:
    role: Writer
    llm: gpt-4o-mini
    function_calling_llm: gpt-4o-mini

agents:
  writer:
    role: Writer
    llm:
      model: gpt-4o-mini
      base_url: https://my-proxy.example.com/v1
      api_key: sk-...
    function_calling_llm:
      model: gpt-4o-mini

agents:
  coordinator:
    role: Coordinator
    handoff:
      to: [writer, reviewer]      # List of target agents
      policy: summary             # Handoff policy: full, summary, none, last_n
      timeout: 60                 # Handoff timeout in seconds
      max_depth: 5                # Maximum handoff chain depth
      max_concurrent: 3           # Maximum concurrent handoffs
      detect_cycles: true         # Enable cycle detection

agents:
  image_creator:
    agent: ImageAgent          # Specialized type
    role: Image Generator
    llm: dall-e-3
    style: natural             # optional — omit to let the provider pick

  narrator:
    agent: AudioAgent
    role: Audio Narrator
    llm: tts-1
    voice: alloy

  video_maker:
    agent: VideoAgent
    role: Video Creator
    llm: openai/sora-2

  document_reader:
    agent: OCRAgent
    role: Document Reader
    llm: mistral/mistral-ocr-latest

  researcher:
    agent: DeepResearchAgent
    role: Deep Researcher
    llm: o3-deep-research

Step Options

All options available for step definitions.

steps:
  - agent: researcher
    action: "Find topics"
    output_json:
      type: array
      items:
        type: object
        properties:
          title: { type: string }
          url: { type: string }
    output_variable: topics

steps:
  - name: research_step
    agent: researcher
    action: "Research {{input}}"

  - name: writing_step
    agent: writer
    action: "Write based on: {{previous_output}}"
    context:
      - research_step    # Explicit dependency

Workflow Patterns

Advanced workflow patterns available in both agents.yaml and workflow.yaml.

steps:
  - name: parallel_research
    parallel:
      - agent: market_analyst
        action: "Research market trends"
      - agent: tech_analyst
        action: "Research technology"

  - agent: aggregator
    action: "Combine findings: {{previous_output}}"

steps:
  - agent: classifier
    action: "Classify: {{input}}"

  - name: routing
    route:
      technical: [tech_expert]
      creative: [creative_expert]
      default: [general_agent]

variables:
  topics:
    - Machine Learning
    - NLP
    - Computer Vision

steps:
  - agent: researcher
    action: "Research {{item}}"
    loop:
      over: topics
      parallel: true      # Optional: run in parallel
      max_workers: 4      # Optional: limit workers

steps:
  - loop:
      over: topics
      parallel: true
    steps:
      - agent: researcher
        action: "Research {{item}}"
      - agent: writer
        action: "Write about: {{previous_output}}"
      - agent: publisher
        action: "Publish: {{previous_output}}"

steps:
  - agent: writer
    action: "Write article about {{topic}}"
    repeat:
      until: "approved"
      max_iterations: 3

steps:
  - include: ai-topic-gatherer

  - include:
      recipe: wordpress-publisher
      input: "{{previous_output}}"

  - agent: writer
    action: "Summarize: {{previous_output}}"

Loop Options

Repeat Options

Include Options

Feature Compatibility Matrix

What works where:

What’s NOT Possible

Migration Guide

From agents.yaml to workflow.yaml

1. Rename container

   roles: → agents:

2. Rename agent fields

   backstory: → instructions:

3. Extract tasks to steps

   Move nested tasks: to top-level steps:

4. Rename step fields

   description: → action:

5. Update input reference

   topic: → input: (optional but recommended)

framework: praisonai
topic: "Research AI"

roles:
  researcher:
    role: Analyst
    backstory: "Expert researcher"
    goal: Research
    tasks:
      research_task:
        description: "Research {{topic}}"

name: Research Workflow
input: "Research AI"

agents:
  researcher:
    role: Analyst
    instructions: "Expert researcher"
    goal: Research

steps:
  - agent: researcher
    action: "Research {{input}}"

Validation

Validate your YAML configuration before running:

praisonai validate agents.yaml

Output shows:

• ✅ Valid configuration
• ⚠️ Non-blocking warnings (unknown fields, optional tool deps)
• ❌ Errors that would abort execution

Scan an entire directory:

praisonai validate check . --strict --json

See the Validate CLI page for all flags, JSON output format, and CI integration examples.

praisonai workflow validate is the workflow-specific variant and remains available for backwards compatibility.

Best Practices

Related