YAML Configuration Reference

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

Both files are fully compatible! PraisonAI accepts both agents.yaml and workflow.yaml with the same features. The difference is primarily in naming conventions.

Quick Comparison

agents.yaml Style
workflow.yaml Style (Canonical)

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.

Canonical (Recommended)	Alias (Also Works)	Purpose
`agents`	`roles`	Define agent personas
`instructions`	`backstory`	Agent behavior/persona
`action`	`description`	What the step does
`steps`	`tasks` (nested in roles)	Define work items
`name`	-	Workflow identifier
`input`	`topic`	Data passed INTO the workflow

A-I-G-S Mnemonic - Easy to remember:

Agents - Who does the work
Instructions - How they behave
Goal - What they achieve
Steps - What they do

Automatic Field Validation

PraisonAI automatically checks every field name in your agents.yaml and warns you about typos when the workflow starts.

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
    backstory: Expert researcher.

Run workflow and see warning

praisonai start agents.yaml

Output:

WARNING: Unknown field 'instrutions' in agent 'researcher'. Did you mean 'instructions'?

Fix the typo

    instructions: "Focus ONLY on years 1989–2000."   # fixed

Now the warning disappears and the field is properly used.

Recognized Fields

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

Field	Type	Purpose
`role`	string	Agent’s job title
`goal`	string	Agent’s objective
`instructions`	string	Behavior instructions
`backstory`	string	Personality/background context
`tools`	array	List of tool names
`tasks`	object	Nested task definitions (legacy)
`llm`	string \| dict	Model to use
`function_calling_llm`	string \| dict	Model for tool calls
`allow_delegation`	bool	Allow task delegation
`max_iter`	int	Maximum iterations
`max_rpm`	int	Max requests per minute
`max_execution_time`	int	Timeout in seconds
`verbose`	bool	Verbose output
`cache`	bool	Enable response caching
`system_template`	string	Custom system prompt
`prompt_template`	string	Custom prompt template
`response_template`	string	Custom response template
`tool_timeout`	int	Per-call tool execution timeout in seconds. Enforced at two layers when running `framework: praisonai`: (1) the wrapper wraps every tool callable in a timeout-enforcing shim that returns a structured `{"error": "tool_timeout", ...}` dict on timeout, and (2) the SDK Agent’s executor pool also honours the same value. Sync tools run in a daemon thread on the wrapper layer; async tools use `asyncio.wait_for`. See Tool Configuration for the full shape.
`tool_retry_policy`	object	Tool retry configuration with exponential backoff. See example below.
`planning_tools`	array	Tools for planning
`planning`	bool	Enable planning
`autonomy`	string/object	Autonomy configuration
`guardrails`	array	Guardrail functions
`streaming`	bool	Enable streaming
`stream`	bool	Alias for streaming
`approval`	bool	Require human approval
`skills`	array	Skill definitions
`cli_backend`	string / dict	CLI backend (e.g. `claude-code`) or `{id: ..., overrides: {...}}`. Requires `framework: praisonai`. See CLI Backend Protocol.
`reflection`	bool/object	Reflection configuration

How Suggestions Work

PraisonAI uses Python’s built-in difflib with a 0.6 similarity cutoff. Only the single closest match is shown, and only when a close match exists.

Warnings are non-blocking. Your workflow still runs; the typo’d field is simply ignored. Always check warnings before assuming an agent is configured correctly.

Set your log level to WARNING or below (INFO, DEBUG) to see these messages. They’re emitted via the standard praisonai logger.

Sample Output

WARNING: Unknown field 'instrutions' in agent 'researcher'. Did you mean 'instructions'?
WARNING: Unknown field 'xyz_random_field' in agent 'test_agent'.

Both Sections Covered

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

Run once after editing YAML

Start the workflow once and grep logs for Unknown field to catch all typos at once.

Don't disable the warning

Instead of disabling warnings, fix the typo or add a comment explaining the custom field. The validator helps catch configuration mistakes.

Custom fields are ignored, not preserved

If you intentionally use a non-standard key, the parser will not pass it through to the agent. Only recognized fields are used.

Root-Level Options

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

Workflow Metadata

Field	Type	Default	Description
`name`	string	”Workflow”	Workflow identifier
`description`	string	""	Workflow description
`input`	string	""	Data passed INTO workflow (use `{{input}}` in steps)
`topic`	string	""	Alias for `input` (legacy)
`framework`	string	”praisonai”	Framework: `praisonai`, `crewai`, `autogen`
`process`	string	”sequential”	Process type: `sequential`, `hierarchical`, `workflow`
`manager_llm`	string	-	LLM for hierarchical process manager

Workflow Settings

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

Field	Type	Default	Description
`planning`	bool	false	Enable planning mode
`planning_llm`	string	-	LLM for planning
`reasoning`	bool	false	Enable reasoning mode
`verbose`	bool	false	Verbose output
`default_llm`	string	”gpt-4o-mini”	Default LLM for agents
`output`	string	”normal”	Output mode preset
`memory_config`	object	-	Memory configuration

Context Management

Prevent token overflow errors with automatic context compaction.

# 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

Field	Type	Default	Description
`auto_compact` / `enabled`	bool	false	Enable auto-compaction
`compact_threshold` / `threshold`	float	0.8	Trigger threshold (0-1)
`strategy`	string	”smart”	Compaction strategy
`tool_output_max` / `max_tool_output_tokens`	int	10000	Max tokens per tool

Always enable context: true for workflows with search/crawl tools to prevent “context_length_exceeded” errors.

Tool Retry Policy

Configure automatic retry for failed tool calls with exponential backoff:

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

Field	Type	Default	Description
`max_attempts`	int	3	Total attempts including the first try
`retry_on`	array	[“timeout”, “rate_limit”, “connection_error”]	Error types that trigger retry
`backoff_factor`	float	2.0	Multiplier for delay between attempts
`initial_delay_ms`	int	1000	Initial delay before first retry (ms)
`jitter`	bool	false	Add randomized jitter to delays

For detailed configuration options, see Tool Retry Policy.

Variables

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

Use variables in steps with {{variable_name}} syntax.

Pattern	Description
`{{input}}`	Workflow input
`{{topic}}`	Topic field value
`{{previous_output}}`	Previous step result
`{{variable_name}}`	Custom variable
`{{item}}`	Current loop item
`{{item.field}}`	Field in loop item

Custom Models

Define custom models for model routing.

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]

Field	Required	Description
`provider`	✅	`openai`, `anthropic`, `google`, `openrouter`
`complexity`	✅	List: `simple`, `moderate`, `complex`, `very_complex`
`cost_per_1k`	✅	Cost per 1,000 tokens in USD
`capabilities`	❌	List: `text`, `vision`, `function-calling`
`context_window`	❌	Max context window in tokens
`supports_tools`	❌	Supports tool/function calling
`strengths`	❌	List: `reasoning`, `code-generation`, etc.

Callbacks

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

Callbacks are resolved from your tools.py file.

Agent Options

All options available for agent definitions.

Core Fields

Field	Required	Default	Description
`role`	✅	-	Agent’s job title
`name`	❌	Agent ID	Display name
`goal`	❌	“Complete the task”	Agent’s objective
`instructions`	❌	Generic	Direct behavior instructions (simple agents)
`backstory`	❌	-	Personality/background context (advanced)

LLM Configuration

Field	Type	Default	Description
`llm`	string \| dict	`gpt-4o-mini`	Model to use
`function_calling_llm`	string \| dict	Same as `llm`	Model for tool calls
`reflect_llm`	string \| dict	Same as `llm`	Model for self-reflection
`system_template`	string	-	Custom system prompt
`prompt_template`	string	-	Custom prompt template
`response_template`	string	-	Custom response template

Both llm and function_calling_llm accept a model name as a string, or a dict when you also need to override base_url / api_key. Both shapes work identically across every supported framework (praisonai, crewai, autogen, autogen_v4).

String form (simplest)
Dict form (when overriding endpoint / key)

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

If llm is omitted, PraisonAI falls back to the MODEL_NAME environment variable, then to openai/gpt-4o-mini. This fallback is shared by every framework adapter.

Rate Limiting & Execution

Field	Default	Description
`max_rpm`	Unlimited	Max requests per minute
`max_execution_time`	300	Timeout in seconds
`max_iter`	3	Maximum iterations
`min_reflect`	0	Minimum reflection iterations
`max_reflect`	3	Maximum reflection iterations
`cache`	true	Enable response caching

Advanced Features

Field	Default	Description
`planning`	false	Enable agent-level planning
`reasoning`	false	Enable reasoning mode
`allow_delegation`	false	Allow task delegation
`verbose`	false	Verbose output
`tools`	[]	List of tool names
`web`	false	Enable web search capabilities
`web_fetch`	false	Enable web content fetching
`handoff`	-	Handoff configuration (see below)

Handoff Configuration

Configure agent handoff with nested options:

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

Field	Default	Description
`to`	[]	List of agent names to handoff to
`policy`	”full”	Handoff policy: `full`, `summary`, `none`, `last_n`
`timeout`	30	Timeout for handoff in seconds
`max_depth`	10	Maximum depth of handoff chain
`max_concurrent`	5	Maximum concurrent handoffs
`detect_cycles`	false	Enable handoff cycle detection

Specialized Agent Types

Use the agent: field to specify specialized agent types:

agents:
  image_creator:
    agent: ImageAgent          # Specialized type
    role: Image Generator
    llm: dall-e-3
    style: natural
  
  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

Agent Type	Purpose	Key Options
`ImageAgent`	Image generation	`style`, `llm` (dall-e-3)
`AudioAgent`	TTS/STT	`voice`, `audio` config
`VideoAgent`	Video generation	`video` config
`OCRAgent`	Text extraction	`ocr` config
`DeepResearchAgent`	Automated research	`instructions`

Step Options

All options available for step definitions.

Basic Step Fields

Field	Required	Default	Description
`agent`	✅*	-	Agent to execute (*not needed for patterns)
`action`	❌	`{{input}}`	What the step does
~~`description`~~	❌	-	Deprecated - use `action`
`name`	❌	Auto-generated	Step identifier
`expected_output`	❌	-	Description of expected output

Output Options

Field	Description
`output_file`	Save output to file path
`create_directory`	Create output directory if needed
`output_json`	JSON schema for structured output
`output_pydantic`	Pydantic model name from tools.py
`output_variable`	Store output in named variable

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

Context & Dependencies

Field	Description
`context`	List of dependent step names

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

Execution Control

Field	Default	Description
`async_execution`	false	Run asynchronously
`max_retries`	3	Maximum retry attempts
`guardrail`	-	Guardrail function name
`callback`	-	Callback function name

Workflow Patterns

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

Parallel

Execute multiple agents concurrently

Route

Classify and route to specialized agents

Loop

Iterate over a list of items

Repeat

Repeat until condition is met

Include

Include modular recipes

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

Field	Required	Default	Description
`over`	✅*	-	Variable name to iterate
`from_csv`	❌	-	CSV file path to iterate
`from_file`	❌	-	File path to iterate lines
`var_name`	❌	“item”	Variable name for current item
`parallel`	❌	false	Execute iterations in parallel
`max_workers`	❌	-	Limit parallel workers
`output_variable`	❌	-	Store all outputs in variable

Repeat Options

Field	Required	Default	Description
`until`	✅	-	Condition string to match in output
`max_iterations`	❌	5	Maximum iterations

Include Options

Field	Required	Default	Description
`recipe`	✅	-	Recipe name or path
`input`	❌	`{{previous_output}}`	Input for included recipe

Feature Compatibility Matrix

What works where:

Feature	agents.yaml	workflow.yaml	Notes
Agent Definition	✅	✅	Use `agents:` (canonical) or `roles:`
Steps/Tasks	✅	✅	Use `steps:` (canonical)
Workflow Patterns	✅	✅	`parallel`, `route`, `loop`, `repeat`
Include Recipes	✅	✅	`include:` in steps
Variables	✅	✅	`variables:` section
Context Management	✅	✅	`context:` section
Planning Mode	✅	✅	`workflow.planning: true`
Reasoning Mode	✅	✅	`workflow.reasoning: true`
Memory Config	✅	✅	`workflow.memory_config:`
Custom Models	✅	✅	`models:` section
Callbacks	✅	✅	`callbacks:` section
Specialized Agents	✅	✅	`agent: ImageAgent`, etc.
Handoff Configuration	✅	✅	`handoff:` in agent definition
Web Search	✅	✅	`web: true` in agent definition
Web Content Fetching	✅	✅	`web_fetch: true` in agent definition
Structured Output	✅	✅	`output_json`, `output_pydantic`

Full Feature Parity! Both file formats support all features. The only difference is naming conventions.

Framework LLM Configuration Parity: The llm and function_calling_llm configuration shapes (string and dict forms) work identically across all supported frameworks (praisonai, crewai, autogen, autogen_v4). You can switch between frameworks without changing your LLM configuration syntax.

What’s NOT Possible

These limitations apply to both agents.yaml and workflow.yaml:

Limitation	Workaround
Nested loops	Use multi-step loop with sequential steps
Conditional branching mid-step	Use `route:` pattern instead
Dynamic agent creation	Pre-define all agents in `agents:` section
Cross-workflow state	Use `include:` with explicit input passing
Real-time streaming in loops	Streaming works per-step, not across loop

Migration Guide

From agents.yaml to workflow.yaml

Rename container

roles: → agents:

Rename agent fields

backstory: → instructions:

Extract tasks to steps

Move nested tasks: to top-level steps:

Rename step fields

description: → action:

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

Validation

Validate your YAML configuration:

praisonai workflow validate my-workflow.yaml

Output shows:

✅ Valid fields
💡 Suggestions for canonical names
❌ Errors if invalid

Best Practices

Use Canonical Names

agents, instructions, action, steps, input

Enable Context Management

context: true for tool-heavy workflows

Define Expected Output

Always specify expected_output for clarity

Use Variables

Centralize reusable values in variables:

Run praisonai workflow validate <file.yaml> to check for issues and get suggestions for canonical field names.

​YAML Configuration Reference

​Quick Comparison

​Field Name Mapping

​Automatic Field Validation

​Recognized Fields

​How Suggestions Work

​Sample Output

​Both Sections Covered

​Root-Level Options

​Agent Options

​Step Options

​Workflow Patterns

Parallel

Route

Loop

Repeat

Include

​Loop Options

​Repeat Options

​Include Options

​Feature Compatibility Matrix

​What’s NOT Possible

​Migration Guide

​From agents.yaml to workflow.yaml

​Validation

​Best Practices

Use Canonical Names

Enable Context Management

Define Expected Output

Use Variables

YAML Configuration Reference

Quick Comparison

Field Name Mapping

Automatic Field Validation

Recognized Fields

How Suggestions Work

Sample Output

Both Sections Covered

Root-Level Options

Agent Options

Step Options

Workflow Patterns

Loop Options

Repeat Options

Include Options

Feature Compatibility Matrix

What’s NOT Possible

Migration Guide

From agents.yaml to workflow.yaml

Validation

Best Practices