---
title: "Excel Agent"
description: "Excel file processing tools for AI agents."
icon: "file-excel"
---

<Note>
  **Prerequisites**
  - Python 3.10 or higher
  - PraisonAI Agents package installed
  - `openpyxl` package installed
  - Basic understanding of Excel files
</Note>

## Excel Tools

Use Excel Tools to process and manipulate Excel files with AI agents.

<Steps>
  <Step title="Install Dependencies">
    First, install the required packages:
    ```bash
    pip install praisonaiagents openpyxl
    ```
  </Step>

  <Step title="Import Components">
    Import the necessary components:
    ```python
    from praisonaiagents import Agent, Task, PraisonAIAgents
    from praisonaiagents.tools import read_excel, write_excel, merge_excel
    ```
  </Step>

  <Step title="Create Agent">
    Create an Excel processing agent:
    ```python
    excel_agent = Agent(
        name="ExcelProcessor",
        role="Excel Processing Specialist",
        goal="Process Excel files efficiently and accurately.",
        backstory="Expert in Excel file manipulation and analysis.",
        tools=[read_excel, write_excel, merge_excel],
        self_reflect=False
    )
    ```
  </Step>

  <Step title="Define Task">
    Define the Excel processing task:
    ```python
    excel_task = Task(
        description="Process and analyze Excel spreadsheets.",
        expected_output="Processed Excel data with analysis.",
        agent=excel_agent,
        name="excel_processing"
    )
    ```
  </Step>

  <Step title="Run Agent">
    Initialize and run the agent:
    ```python
    agents = PraisonAIAgents(
        agents=[excel_agent],
        tasks=[excel_task],
        process="sequential"
    )
    agents.start()
    ```
  </Step>
</Steps>

## Understanding Excel Tools

<Card title="What are Excel Tools?" icon="question">
  Excel Tools provide Excel processing capabilities for AI agents:
  - File reading and writing
  - Data extraction
  - Sheet manipulation
  - Formula handling
  - Data analysis
</Card>

## Key Components

<CardGroup cols={2}>
  <Card title="Excel Agent" icon="user-robot">
    Create specialized Excel agents:
    ```python
    Agent(tools=[read_excel, write_excel, merge_excel])
    ```
  </Card>
  <Card title="Excel Task" icon="list-check">
    Define Excel tasks:
    ```python
    Task(description="excel_operation")
    ```
  </Card>
  <Card title="Process Types" icon="arrows-split-up-and-left">
    Sequential or parallel processing:
    ```python
    process="sequential"
    ```
  </Card>
  <Card title="Excel Options" icon="sliders">
    Customize Excel parameters:
    ```python
    sheet_name="Sheet1", header=0
    ```
  </Card>
</CardGroup>

## Available Functions

```python
from praisonaiagents.tools import read_excel
from praisonaiagents.tools import write_excel
from praisonaiagents.tools import merge_excel
```

## Function Details

### read_excel(filepath: str, sheet_name: Optional[Union[str, int, List[Union[str, int]]]] = 0, header: Optional[int] = 0, usecols: Optional[List[str]] = None, skiprows: Optional[Union[int, List[int]]] = None, na_values: Optional[List[str]] = None, dtype: Optional[Dict[str, str]] = None)

Reads Excel files with advanced options:
- Support for multiple sheets
- Flexible header handling
- Column selection
- Row skipping
- Custom NA values
- Data type specification

```python
# Basic usage - read first sheet
data = read_excel("data.xlsx")

# Read specific sheets
data = read_excel(
    "data.xlsx",
    sheet_name=['Sheet1', 'Sheet2'],
    header=0,
    usecols=['A', 'B', 'C'],
    skiprows=[0, 1],
    na_values=['NA', 'missing'],
    dtype={'age': 'int32', 'salary': 'float64'}
)
# Returns: Dict[str, List[Dict[str, Any]]] for multiple sheets
# Example: {
#   'Sheet1': [{"name": "Alice", "age": 25}, ...],
#   'Sheet2': [{"dept": "Engineering", "count": 10}, ...]
# }
```

### write_excel(filepath: str, data: Union[Dict[str, List[Dict[str, Any]]], List[Dict[str, Any]]], sheet_name: Optional[str] = None, index: bool = False, header: bool = True, mode: str = 'w')

Writes data to Excel files with formatting:
- Multiple sheet support
- Append mode for existing files
- Optional row indices
- Optional headers
- Flexible data structure handling

```python
# Write single sheet
data = [
    {"name": "Alice", "age": 25, "city": "New York"},
    {"name": "Bob", "age": 30, "city": "San Francisco"}
]
success = write_excel("output.xlsx", data, sheet_name="Employees")

# Write multiple sheets
data = {
    "Employees": [
        {"name": "Alice", "age": 25},
        {"name": "Bob", "age": 30}
    ],
    "Departments": [
        {"name": "Engineering", "count": 50},
        {"name": "Sales", "count": 30}
    ]
}
success = write_excel(
    "company.xlsx",
    data,
    index=False,
    header=True,
    mode='w'
)
# Returns: bool (True if successful)
```

### merge_excel(files: List[str], output_file: str, how: str = 'inner', on: Optional[Union[str, List[str]]] = None, suffixes: Optional[Tuple[str, str]] = None)

Merges multiple Excel files:
- Flexible join operations
- Multiple key columns support
- Custom column suffix handling
- Preserves data types

```python
# Merge two files on a common column
success = merge_excel(
    files=["employees.xlsx", "salaries.xlsx"],
    output_file="merged.xlsx",
    how='inner',
    on='employee_id'
)

# Advanced merge with multiple keys and custom suffixes
success = merge_excel(
    files=["data2022.xlsx", "data2023.xlsx"],
    output_file="combined.xlsx",
    how='outer',
    on=['id', 'department'],
    suffixes=('_2022', '_2023')
)
# Returns: bool (True if successful)
```

## Examples

### Basic Excel Processing Agent

```python
from praisonaiagents import Agent, Task, PraisonAIAgents
from praisonaiagents.tools import read_excel, write_excel, merge_excel

# Create Excel agent
excel_agent = Agent(
    name="ExcelExpert",
    role="Excel Processing Specialist",
    goal="Process Excel files efficiently and accurately.",
    backstory="Expert in spreadsheet manipulation and analysis.",
    tools=[read_excel, write_excel, merge_excel],
    self_reflect=False
)

# Define Excel task
excel_task = Task(
    description="Process and analyze sales data.",
    expected_output="Sales analysis report.",
    agent=excel_agent,
    name="sales_analysis"
)

# Run agent
agents = PraisonAIAgents(
    agents=[excel_agent],
    tasks=[excel_task],
    process="sequential"
)
agents.start()
```

### Advanced Excel Processing with Multiple Agents

```python
# Create data processing agent
processor_agent = Agent(
    name="Processor",
    role="Data Processor",
    goal="Process Excel data systematically.",
    tools=[read_excel, write_excel, merge_excel],
    self_reflect=False
)

# Create analysis agent
analysis_agent = Agent(
    name="Analyzer",
    role="Data Analyst",
    goal="Analyze processed Excel data.",
    backstory="Expert in data analysis and reporting.",
    self_reflect=False
)

# Define tasks
processing_task = Task(
    description="Process sales spreadsheets.",
    agent=processor_agent,
    name="data_processing"
)

analysis_task = Task(
    description="Analyze sales trends and patterns.",
    agent=analysis_agent,
    name="data_analysis"
)

# Run agents
agents = PraisonAIAgents(
    agents=[processor_agent, analysis_agent],
    tasks=[processing_task, analysis_task],
    process="sequential"
)
agents.start()
```

## Best Practices

<AccordionGroup>
  <Accordion title="Agent Configuration">
    Configure agents with clear Excel focus:
    ```python
    Agent(
        name="ExcelProcessor",
        role="Excel Processing Specialist",
        goal="Process Excel files accurately and efficiently",
        tools=[read_excel, write_excel, merge_excel]
    )
    ```
  </Accordion>

  <Accordion title="Task Definition">
    Define specific Excel operations:
    ```python
    Task(
        description="Process sales data and generate reports"
    )
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### Excel Processing Pipeline
```python
# Processing agent
processor = Agent(
    name="Processor",
    role="Excel Processor",
    tools=[read_excel, write_excel, merge_excel]
)

# Analysis agent
analyzer = Agent(
    name="Analyzer",
    role="Data Analyst"
)

# Define tasks
process_task = Task(
    description="Process Excel files",
    agent=processor
)

analyze_task = Task(
    description="Analyze processed data",
    agent=analyzer
)

# Run workflow
agents = PraisonAIAgents(
    agents=[processor, analyzer],
    tasks=[process_task, analyze_task]
)

```

## Dependencies

The Excel tools require the following Python packages:
- pandas: For data manipulation
- openpyxl: For Excel file operations

These will be automatically installed when needed.

## Example Agent Configuration

```python
from praisonaiagents import Agent
from praisonaiagents.tools import read_excel, write_excel, merge_excel

agent = Agent(
    name="ExcelProcessor",
    description="An agent that processes Excel files",
    tools=[read_excel, write_excel, merge_excel]
)
```

## Error Handling

All functions include comprehensive error handling:
- File not found errors
- Permission errors
- Invalid sheet names
- Data format errors
- Missing dependency errors

Errors are logged and returned in a consistent format:
- Success cases return the expected data type
- Error cases return a dict with an "error" key containing the error message

## Common Use Cases

1. Data Analysis:
```python
# Read and analyze employee data
data = read_excel(
    "employees.xlsx",
    sheet_name="Salaries",
    usecols=["department", "salary"]
)

# Write summary to new sheet
summary = [
    {"department": dept, "avg_salary": sum(d["salary"] for d in dept_data) / len(dept_data)}
    for dept, dept_data in groupby(data, key=lambda x: x["department"])
]
write_excel("summary.xlsx", summary, sheet_name="Salary Summary")
```

2. Data Consolidation:
```python
# Merge monthly reports
monthly_files = ["jan.xlsx", "feb.xlsx", "mar.xlsx"]
merge_excel(
    files=monthly_files,
    output_file="q1_report.xlsx",
    how='outer',
    on='transaction_id'
)
```

3. Multi-sheet Processing:
```python
# Read multiple sheets
data = read_excel(
    "company_data.xlsx",
    sheet_name=None  # Read all sheets
)

# Process each sheet
processed = {
    sheet: [process_record(record) for record in records]
    for sheet, records in data.items()
}

# Write back to new file
write_excel("processed_data.xlsx", processed)

```