<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/2.7-autoagents -->

# AutoAgents

- .github/ISSUE_TEMPLATE/bug_report.md
- .github/actions/claude-code-action/action.yml
- .github/actions/claude-issue-triage-action/action.yml
- .github/actions/gemini/action.yml
- .github/workflows/auto-issue-comment.yml
- .github/workflows/auto-pr-comment.yml
- .github/workflows/claude-issue-triage.yml
- .github/workflows/claude.yml
- .github/workflows/docker-publish.yml
- .github/workflows/gemini-issue-automated-triage.yml
- .github/workflows/gemini-issue-review.yml
- .github/workflows/gemini-pr-review.yml
- .gitignore
- src/praisonai-agents/autoagents-tavily.py
- src/praisonai-agents/praisonaiagents/agents/autoagents.py
- src/praisonai-agents/praisonaiagents/llm/model_capabilities.py

This document describes the AutoAgents system, which provides automatic AI-powered generation of multi-agent teams. AutoAgents uses an LLM to analyze a natural language instruction and automatically generate appropriate agent configurations, task definitions, and execution workflows.

For information about manually defining agent teams, see [Multi-Agent Orchestration](/MervinPraison/PraisonAI/2.5-multi-agent-orchestration). For information about specialized single-purpose agent types, see [Specialized Agent Types](/MervinPraison/PraisonAI/2.2-specialized-agent-types).

## Purpose and Scope

AutoAgents is a high-level abstraction that enables users to create complete multi-agent systems using only a natural language instruction. Instead of manually defining each agent's role, goal, backstory, and tasks, AutoAgents delegates this configuration generation to an LLM, which analyzes the user's requirements and produces a structured configuration automatically.

**Key capabilities:**

- AI-powered agent team generation from natural language instructions
- Automatic task decomposition and assignment
- Intelligent tool distribution among agents
- Support for multiple LLM providers with fallback mechanisms
- Configurable agent count constraints (1-10 agents)
- Validation and retry logic for configuration generation

**Scope:** This document covers the AutoAgents class implementation, configuration generation workflow, validation mechanisms, and integration with the broader agent orchestration system.

## System Architecture

AutoAgents operates as a specialized wrapper around the `AgentManager` class, adding an AI-powered configuration generation layer before agent instantiation.

### AutoAgents Position in the Agent Hierarchy

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py1-527](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L1-L527)

### Class Hierarchy

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py8-9](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L8-L9) [src/praisonai-agents/praisonaiagents/agents/autoagents.py41](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L41-L41)

## Configuration Data Models

AutoAgents uses three Pydantic models to represent the generated configuration structure:

### Model Definitions

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py19-40](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L19-L40)

## Configuration Generation Workflow

The configuration generation process uses an LLM to convert natural language instructions into structured agent configurations. The system supports multiple LLM providers and includes retry logic for robust generation.

### Generation Pipeline

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py272-449](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L272-L449)

### LLM Provider Detection

The system detects which LLM provider is in use and selects the appropriate configuration generation strategy:

```

```

**Code Flow:**

1. Check if model supports structured outputs: src/praisonai-agents/praisonaiagents/agents/autoagents.py 357-363
2. OpenAI path: src/praisonai-agents/praisonaiagents/agents/autoagents.py 366-377
3. Generic LLM path: src/praisonai-agents/praisonaiagents/agents/autoagents.py 379-416

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py357-416](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L357-L416) [src/praisonai-agents/praisonaiagents/llm/model_capabilities.py50-75](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/llm/model_capabilities.py#L50-L75)

### Prompt Construction

The prompt sent to the LLM includes:

**Required Elements:**

- Main instruction describing the overall goal
- List of available tools from self.tools
- Maximum agent count constraint
- JSON schema structure
- Task object requirements (critical: tasks must be objects, not strings)

**Retry Enhancement:**

- On retry attempts, includes previous LLM response
- Includes validation error from previous attempt
- Emphasizes specific requirements that were violated

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py273-353](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L273-L353)

## Validation System

AutoAgents implements multi-level validation to ensure generated configurations are correct before agent instantiation.

### Validation Pipeline

```

```

### Validation Implementation

The `_validate_config()` method performs comprehensive validation:

**Validation Checks:**

1. Agent has tasks list: src/praisonai-agents/praisonaiagents/agents/autoagents.py 252-253
2. Task is proper TaskConfig instance: src/praisonai-agents/praisonaiagents/agents/autoagents.py 257-258
3. Task has required fields ( name , description , expected_output , tools ): src/praisonai-agents/praisonaiagents/agents/autoagents.py 261-268
4. Agent count constraints: src/praisonai-agents/praisonaiagents/agents/autoagents.py 428-432

**Return Format:** `(is_valid: bool, error_message: str)`

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py244-271](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L244-L271)

## Agent and Task Creation

After successful configuration generation and validation, AutoAgents instantiates concrete `Agent` and `Task` objects.

### Creation Workflow

```

```

### Tool Assignment Strategy

Tools are assigned to agents using a multi-stage strategy:

```

```

**Tool Matching Logic:**

1. Collect tool names from agent_config.tools and all task_config.tools : src/praisonai-agents/praisonaiagents/agents/autoagents.py 224-230
2. Match by __name__ attribute or string representation: src/praisonai-agents/praisonaiagents/agents/autoagents.py 232-236
3. Fallback: If no matches, assign all available tools: src/praisonai-agents/praisonaiagents/agents/autoagents.py 238-242

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py214-242](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L214-L242) [src/praisonai-agents/praisonaiagents/agents/autoagents.py451-510](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L451-L510)

### Agent Instance Creation

Each agent is created with consolidated parameters:

**Parameter Flow:**

- Legacy parameters (verbose, markdown, self_reflect, etc.) are stored in __init__
- Consolidated parameters ( output , reflection , caching , knowledge , etc.) take precedence
- All parameters flow to Agent.__init__() : src/praisonai-agents/praisonaiagents/agents/autoagents.py 465-488

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py465-510](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L465-L510)

## Initialization Parameters

AutoAgents accepts a comprehensive set of parameters for configuring the generated agent team.

### Parameter Categories

### Critical Parameters

**instructions: str** (required)

- Natural language description of the overall task
- Used as input to LLM configuration generator
- Example: "Search for information about AI Agents and create a summary"

**max_agents: int** (default: 3, range: 1-10)

- Maximum number of agents to generate
- Enforced at initialization: src/praisonai-agents/praisonaiagents/agents/autoagents.py 89-92
- LLM is instructed to generate exactly this many agents

**tools: Optional[List[Any]]** (default: `[]`)

- List of tool functions/objects available to agents
- Tools are intelligently distributed among agents based on requirements
- Available tools are listed in the LLM prompt

**process: str** (default: `"sequential"`)

- Orchestration pattern: "sequential" , "parallel" , "hierarchical" , "workflow"
- Passed to parent AgentManager

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py42-87](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L42-L87)

### Consolidated Parameters

AutoAgents supports the new consolidated parameter system that takes precedence over legacy parameters:

**Parameter Precedence:**

```

```

**Implementation:**

- Consolidated params stored with _ prefix: src/praisonai-agents/praisonaiagents/agents/autoagents.py 124-132
- Passed to parent AgentManager : src/praisonai-agents/praisonaiagents/agents/autoagents.py 152-167
- Passed to generated agents: src/praisonai-agents/praisonaiagents/agents/autoagents.py 479-487

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py77-87](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L77-L87) [src/praisonai-agents/praisonaiagents/agents/autoagents.py124-167](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L124-L167)

## Display System

AutoAgents provides verbose output showing the generation process and resulting agent configurations.

### Display Components

```

```

### Display Output Format

When `verbose=True`, AutoAgents displays:

**1. Initial Configuration:**

```
 Main Task: {instructions}
 Maximum Agents: {max_agents}
Tools Available Tools: {tool1, tool2, tool3}
```

**2. Generated Agents:**

```
Generated Generated Agents and Tasks:

Agent Agent: {name}
   Role: {role}
   Goal: {goal}
   Tools: {tool1, tool2}
   
    Task 1: {task.name}
      Description: {task.description}
      Expected Output: {task.expected_output}
      Tools: {tool1, tool2}
```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py135-149](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L135-L149) [src/praisonai-agents/praisonaiagents/agents/autoagents.py169-199](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L169-L199)

## Usage Patterns

### Basic Usage

```

```

### With Custom Tools

```

```

### With Multiple Tools and Configurations

```

```

**Sources:** [src/praisonai-agents/autoagents-tavily.py1-62](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/autoagents-tavily.py#L1-L62)

### Async Usage

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py512-518](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L512-L518)

## Integration with AgentManager

AutoAgents inherits from `AgentManager` and leverages its orchestration capabilities.

### Parent Class Integration

```

```

**Key Integration Points:**

1. Initialization: AutoAgents generates agents/tasks, then passes them to AgentManager.__init__() : src/praisonai-agents/praisonaiagents/agents/autoagents.py 152-167
2. Execution: Delegates to parent start() and astart() methods: src/praisonai-agents/praisonaiagents/agents/autoagents.py 520-525
3. Parameters: All execution-related parameters (process, manager_llm, memory, etc.) flow through to parent

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py152-167](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L152-L167) [src/praisonai-agents/praisonaiagents/agents/autoagents.py512-525](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L512-L525)

## Error Handling and Retry Logic

AutoAgents implements robust error handling with automatic retry mechanisms.

### Retry Mechanism

```

```

### Error Types

**Error Messages Include:**

- Specific validation failure reason
- Previous LLM response (on retry)
- Attempt number

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py89-92](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L89-L92) [src/praisonai-agents/praisonaiagents/agents/autoagents.py325-353](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L325-L353) [src/praisonai-agents/praisonaiagents/agents/autoagents.py418-449](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L418-L449)

## JSON Response Parsing

AutoAgents handles various JSON response formats from different LLM providers.

### Response Format Handling

```

```

**Cleaning Logic:**

1. Strip outer whitespace
2. Remove \ ``json` prefix if present: src/praisonai-agents/praisonaiagents/agents/autoagents.py 407-408
3. Remove \ ``` prefix if present: src/praisonai-agents/praisonaiagents/agents/autoagents.py 409-410
4. Remove \ ``` suffix if present: src/praisonai-agents/praisonaiagents/agents/autoagents.py 411-412
5. Strip again and parse: src/praisonai-agents/praisonaiagents/agents/autoagents.py 413-416

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py399-416](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L399-L416)

## Configuration Constraints

AutoAgents enforces several constraints on generated configurations.

### Agent Count Constraints

**Enforcement Implementation:**

```

```

**Post-generation adjustment:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py89-92](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L89-L92) [src/praisonai-agents/praisonaiagents/agents/autoagents.py428-432](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L428-L432)

### Task Constraints

**Requirements:**

- Each agent must have at least one task
- Each task must be a proper TaskConfig object (not a string)
- Each task must have: name , description , expected_output , tools field

**Common Failure:** LLM returns tasks as strings instead of objects:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py244-271](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L244-L271) [src/praisonai-agents/praisonaiagents/agents/autoagents.py318](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L318-L318)

## LLM Provider Support

AutoAgents supports multiple LLM providers with automatic detection and fallback strategies.

### Provider Detection Flow

```

```

### Supported Providers

**Tier 1: Structured Output Support**

- OpenAI models (gpt-4, gpt-4o, etc.)
- Uses native structured output API
- Most reliable configuration generation

**Tier 2: Generic LLM Support**

- Gemini (gemini-2.5-flash, gemini-pro, etc.)
- Anthropic Claude (claude-3-5-sonnet, etc.)
- Groq, Ollama, DeepSeek, and 100+ others via LiteLLM
- Uses output_pydantic parameter with manual JSON parsing

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py357-416](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L357-L416) [src/praisonai-agents/praisonaiagents/llm/model_capabilities.py50-75](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/llm/model_capabilities.py#L50-L75)

## Relationship to Manual Agent Definition

AutoAgents provides an alternative to manually defining agent teams while producing identical runtime structures.

### Comparison: AutoAgents vs Manual Definition

### Workflow Equivalence

**AutoAgents approach:**

```

```

**Manual approach (equivalent result):**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py41-167](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L41-L167) [src/praisonai-agents/autoagents-tavily.py1-62](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/autoagents-tavily.py#L1-L62)

## Common Issues and Troubleshooting

### Issue: Tasks Generated as Strings

**Problem:** LLM returns tasks as simple strings instead of objects with required fields.

**Detection:** `_validate_config()` fails with: `"Task at index X for agent 'Y' is not a proper TaskConfig object"`

**Solution:**

- Retry mechanism includes enhanced prompt emphasizing task structure
- Manual workaround: Adjust prompt or increase max_retries

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py257-258](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L257-L258) [src/praisonai-agents/praisonaiagents/agents/autoagents.py342-351](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L342-L351)

### Issue: Wrong Number of Agents Generated

**Problem:** LLM generates fewer or more agents than `max_agents`.

**Behavior:**

- Too many: Automatically trimmed to max_agents
- Too few: Warning logged, execution continues

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py428-432](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L428-L432)

### Issue: Tool Assignment Failures

**Problem:** Agent requires specific tools that aren't matched by name.

**Fallback:** If no tools match, all available tools are assigned to agent

**Prevention:** Ensure tool functions have clear `__name__` attributes matching LLM suggestions

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py238-242](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L238-L242)

## Performance Considerations

### LLM Call Overhead

**Cost:** One LLM call per `AutoAgents.__init__()` for configuration generation

**Optimization Strategies:**

1. Cache generated configurations for reuse
2. Use faster/cheaper models for configuration generation (e.g., gpt-4o-mini, gemini-2.5-flash-lite)
3. Use structured output-compatible models for faster parsing

### Initialization Time

**Breakdown:**

1. LLM configuration generation: ~2-10 seconds (varies by provider)
2. Response parsing and validation: <100ms
3. Agent/task instantiation: ~100-500ms
4. Total: ~2-11 seconds

**Comparison to Manual:** Manual definition is instantaneous (~100-500ms total)

**Trade-off:** Slower initialization for simplified API and automatic optimization

## Summary

AutoAgents provides a high-level abstraction for creating multi-agent systems using natural language instructions. Key characteristics:

**Strengths:**

- Simplifies agent team creation to a single natural language instruction
- Automatic task decomposition and agent role assignment
- Intelligent tool distribution
- Support for multiple LLM providers
- Robust validation and retry mechanisms

**Limitations:**

- Requires LLM call at initialization (cost + latency)
- Less control than manual definition
- Subject to LLM generation quality
- Configuration generation may require retries

**Typical Use Cases:**

- Rapid prototyping of multi-agent systems
- Exploratory workflows where exact agent configuration is flexible
- Applications where developer time is more valuable than LLM API costs
- Demonstrations and educational examples

**When to Use Manual Definition Instead:**

- Production systems requiring deterministic behavior
- Complex agent configurations with subtle requirements
- Performance-critical applications where initialization latency matters
- When full control over agent configuration is needed

**Sources:** [src/praisonai-agents/praisonaiagents/agents/autoagents.py1-527](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/autoagents.py#L1-L527)
