> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent CLI

> Define and run multiple agents with custom roles, tools, and instructions from the command line

The `praisonai agents` command allows you to define and run multiple agents directly from the command line without creating a YAML configuration file.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run a single agent with tools
praisonai agents run \
  --agent "researcher:Research Analyst:internet_search" \
  --task "Find the latest AI news"

# Run multiple agents
praisonai agents run \
  --agent "researcher:Research Analyst:internet_search" \
  --agent "writer:Content Writer:write_file" \
  --task "Research AI trends and write a summary report"
```

## Commands

### Run Agents

Execute one or more agents with a specified task.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run [options]
```

**Required Options:**

| Option          | Description                                   |
| --------------- | --------------------------------------------- |
| `--agent`, `-a` | Agent definition (can be used multiple times) |
| `--task`, `-t`  | Task for the agents to complete               |

**Optional Options:**

| Option                 | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| `--process`, `-p`      | Execution process: `sequential` (default) or `parallel` |
| `--llm`, `-m`          | LLM model to use for all agents                         |
| `--instructions`, `-i` | Additional instructions for all agents                  |
| `--verbose`, `-v`      | Enable verbose output                                   |

### List Available Tools

List all tools that can be assigned to agents.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents list
```

**Output:**

```
Available tools for agents:
------------------------------
  internet_search: Search the web
  read_file: Read file contents
  write_file: Write to a file
  list_files: List directory contents
  execute_command: Execute shell commands
  read_csv: Read CSV files
  write_csv: Write CSV files
  analyze_csv: Analyze CSV data
```

## Agent Definition Format

Agents are defined using a colon-separated format:

```
name:role:tools:goal
```

| Part    | Required | Description                     |
| ------- | -------- | ------------------------------- |
| `name`  | Yes      | Unique identifier for the agent |
| `role`  | Yes      | The agent's role/title          |
| `tools` | No       | Comma-separated list of tools   |
| `goal`  | No       | Specific goal for the agent     |

### Examples

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic agent with one tool
--agent "researcher:Research Analyst:internet_search"

# Agent with multiple tools
--agent "analyst:Data Analyst:read_csv,write_csv,analyze_csv"

# Agent without tools
--agent "helper:Assistant"

# Agent with goal
--agent "writer:Writer:write_file:Create high-quality content"
```

## Usage Examples

### Single Agent

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple question
praisonai agents run \
  --agent "assistant:Helper" \
  --task "What is the capital of France?"

# With web search
praisonai agents run \
  --agent "researcher:Researcher:internet_search" \
  --task "Find the latest news about AI"
```

### Multiple Agents (Sequential)

Agents execute one after another, passing context between them.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "researcher:Research Analyst:internet_search" \
  --agent "writer:Content Writer:write_file" \
  --task "Research renewable energy trends and write a blog post"
```

### Multiple Agents (Parallel)

Agents execute simultaneously for faster results.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "analyst1:Market Analyst:internet_search" \
  --agent "analyst2:Tech Analyst:internet_search" \
  --process parallel \
  --task "Analyze the current state of AI industry"
```

### With Custom LLM

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "coder:Developer:execute_command" \
  --llm "gpt-4o" \
  --task "Write a Python script to calculate fibonacci numbers"
```

### With Additional Instructions

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "analyst:Data Analyst:read_csv,analyze_csv" \
  --instructions "Be thorough and provide detailed analysis" \
  --task "Analyze the sales data in data.csv"
```

### Data Analysis Pipeline

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "reader:Data Reader:read_csv" \
  --agent "analyst:Data Analyst:analyze_csv" \
  --agent "reporter:Report Writer:write_file" \
  --task "Read sales.csv, analyze trends, and write a report"
```

### Code Development

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "architect:Software Architect" \
  --agent "developer:Developer:execute_command,write_file" \
  --agent "tester:QA Engineer:execute_command" \
  --task "Design and implement a REST API for user management"
```

## Available Tools

| Tool              | Description                      |
| ----------------- | -------------------------------- |
| `internet_search` | Search the web for information   |
| `read_file`       | Read contents of a file          |
| `write_file`      | Write content to a file          |
| `list_files`      | List files in a directory        |
| `execute_command` | Execute shell commands           |
| `read_csv`        | Read and parse CSV files         |
| `write_csv`       | Write data to CSV files          |
| `analyze_csv`     | Analyze CSV data with statistics |

## Execution Modes

### Sequential (Default)

Agents execute one after another. Each agent receives the context from previous agents.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "agent1:Role1:tool1" \
  --agent "agent2:Role2:tool2" \
  --process sequential \
  --task "Complete this task"
```

### Parallel

Agents execute simultaneously. Useful for independent tasks.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "agent1:Role1:tool1" \
  --agent "agent2:Role2:tool2" \
  --process parallel \
  --task "Complete this task"
```

## Output

The command displays:

1. Agent information (name, role)
2. Task description
3. Agent responses
4. Final result

**Example Output:**

```
🚀 Running 2 agents (sequential mode)...
  - researcher: Research Analyst
  - writer: Content Writer

╭─ Agent Info ─────────────────────────────────────────────────────────────────╮
│  👤 Agent: researcher                                                        │
│  Role: Research Analyst                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────── Response ──────────────────────────────────╮
│ [Agent's response here]                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

==================================================
RESULT:
==================================================
[Final result here]
```

## Comparison with agents.yaml

| Feature       | `praisonai agents run` | `agents.yaml`          |
| ------------- | ---------------------- | ---------------------- |
| Setup         | No file needed         | Requires YAML file     |
| Complexity    | Simple, quick tasks    | Complex workflows      |
| Reusability   | One-time use           | Reusable configuration |
| Customization | Basic options          | Full configuration     |
| Best for      | Quick experiments      | Production workflows   |

## Tips

1. **Start Simple**: Begin with a single agent, then add more as needed
2. **Use Descriptive Roles**: Clear roles help agents understand their purpose
3. **Match Tools to Tasks**: Only assign tools that are relevant to the task
4. **Sequential for Dependencies**: Use sequential mode when agents depend on each other
5. **Parallel for Speed**: Use parallel mode for independent tasks

## Troubleshooting

### Agent Not Using Tools

Ensure the tool name is spelled correctly and the tool is available:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents list
```

### Task Not Completing

Try adding more specific instructions:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "helper:Assistant" \
  --instructions "Be concise and direct" \
  --task "Your task here"
```

### Model Errors

Specify a different model:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents run \
  --agent "helper:Assistant" \
  --llm "gpt-4o-mini" \
  --task "Your task here"
```