Auto Mode

Automatically generate and execute agents with intelligent tool discovery

The --auto flag automatically generates an agents.yaml configuration from a natural language task description, using intelligent tool discovery to assign the most appropriate tools based on task analysis.

Quick Start

bash

praisonai --auto "Create a research team to analyze market trends"

Auto Mode vs Recipe Create

Diagram

Auto Mode

Generates and executes immediately
Creates agents.yaml in current directory
Best for one-off tasks
No optimization loop

Recipe Create

Creates a reusable recipe folder
Includes agents.yaml + tools.py
Optimization loop for quality
Best for reusable workflows

Usage

bash

praisonai --auto "<task description>" [options]

Options

Option	Description
`--auto`	Enable auto mode with task description
`--merge`	Merge with existing agents.yaml instead of overwriting. Refuses to clobber an un-parseable target — see Merge safety below.
`--framework`	Framework adapter to use. Discovered dynamically from the adapter registry — built-in (`ag2`, `autogen`, `autogen_v4`, `crewai`, `praisonai`) and any installed third-party adapter (entry-point group `praisonai.framework_adapters`).

Merge safety

--merge reads the existing agents.yaml (or workflow YAML) before writing the merged result. If that file cannot be parsed, the merge refuses to overwrite it — your data is preserved instead of being silently replaced with a freshly generated scaffold.

Diagram

When the target is un-parseable, --merge now:

Writes a collision-safe backup at `<file>.

.bak` next to the original.

Raises praisonai.auto.MergeConflictError — which propagates out of convert_and_save to the CLI, so no write happens and your original file stays intact.

text

MergeConflictError: Refusing to overwrite un-parseable agents.yaml: mapping values are not allowed here … Original preserved at agents.yaml.20260906143221.bak. Fix the file or re-run without --merge.

If the backup copy itself fails, the original is left untouched and the message says so instead (Backup failed; original left untouched at <path>.).

Resolution: fix the reported parse error in your YAML, or re-run without --merge to regenerate the file from scratch.

The same protection applies to the workflow YAML path (WorkflowAutoGenerator.merge_with_existing_workflow).

Intelligent Tool Discovery

Auto mode sources tool suggestions from the canonical ToolResolver.list_available(), so only tools you actually have installed are surfaced.

Keyword hints still prioritise suggestions by task, but the recommended set is intersected with the installed registry before it reaches the prompt.

Diagram

When the resolver is available, the generation prompt header reads “AVAILABLE TOOLS (installed)” and lists only installed tools. If the resolver cannot be constructed, auto mode falls back to keyword hints and the header reads “AVAILABLE TOOLS BY CATEGORY”.

The legacy AVAILABLE_TOOLS and TOOL_CATEGORIES remain importable from praisonai.auto for backward compatibility.

The enhanced auto mode analyzes your task description and automatically assigns appropriate tools from 9 categories:

Category	Tools	Triggered By
Web Search	`internet_search`, `tavily_search`, `exa_search`	“search”, “find”, “look up”
Web Scraping	`scrape_page`, `crawl`, `extract_text`	“scrape”, “crawl”, “extract”
File Operations	`read_file`, `write_file`, `list_files`	“read file”, “save”, “load”
Code Execution	`execute_command`, `execute_code`	“execute”, “run code”, “script”
Data Processing	`read_csv`, `write_csv`, `read_json`	“csv”, “excel”, “json”, “data”
Research	`search_arxiv`, `wiki_search`	“research”, “paper”, “wikipedia”
Finance	`get_stock_price`, `get_historical_data`	“stock”, “price”, “financial”
Math	`evaluate`, `solve_equation`	“calculate”, “math”, “equation”
Database	`query`, `find_documents`	“database”, “sql”, “mongodb”

Examples

Financial Research

bash

praisonai --auto "Research stock prices and create a financial report"

Generated tools: get_stock_price, get_stock_info, get_historical_data, write_file

Web Scraping

bash

praisonai --auto "Scrape websites for product data and save to CSV"

Generated tools: scrape_page, crawl, extract_text, write_csv, read_csv

Data Analysis

bash

praisonai --auto "Analyze CSV data and generate statistics"

Generated tools: read_csv, analyze_csv, calculate_statistics, write_file

With Framework

bash

praisonai --auto "Create a data analysis team" --framework praisonai

Merge Existing

bash

praisonai --auto "Add a quality reviewer" --merge

How It Works

Diagram

Task Complexity Analysis
Determines if task is simple (1 agent), moderate (2 agents), or complex (3-4 agents)
Keyword Matching
Identifies relevant tool categories from task description
Tool Assignment
Assigns appropriate tools from matched categories
Agent Generation
Creates specialized agents with focused roles
YAML Output
Generates agents.yaml configuration file
Execution
Runs the generated agents to complete the task

Auto Mode Providers

LiteLLM unlocks 100+ providers for auto mode, with automatic OpenAI fallback. Learn how provider selection works. Generated job-workflow YAML no longer pins gpt-4o-mini — steps inherit your configured model. LiteLLM transient errors (429/5xx/timeouts) are retried up to 2× before OpenAI fallback engages.

Generated Output

The auto mode creates an agents.yaml file with:

Intelligent agent count based on task complexity
Specialized roles with clear responsibilities
Appropriate tools from 50+ available tools
Focused tasks with expected outputs
Process configuration (sequential, parallel, etc.)

Generated YAML files are written atomically — a crash or interruption during save will not corrupt the existing file.

When to Use Each

Use Auto Mode When…

You need a quick one-off task
You want immediate execution
You don’t need to save the workflow
You’re prototyping ideas

Use Recipe Create When…

You want a reusable workflow
You need optimization for quality
You want to share the recipe
You need custom tools in tools.py
You want to version control the recipe