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

# DuckDB Agent

> DuckDB database tools for AI agents.

<Note>
  **Prerequisites**

  * Python 3.10 or higher
  * PraisonAI Agents package installed
  * PraisonAI Tools package installed
  * `duckdb` package installed
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import execute_query

agent = Agent(name="Analyst", tools=[execute_query])
agent.start("How many rows are in the orders table?")
```

The user asks an analytics question; the agent runs DuckDB queries and returns results.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[Input] --> A[Agent]
    A --> T[Tool]
    T --> O[Output]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,O tool
    class T tool
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as DuckDB Agent

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

## DuckDB Tools

Use DuckDB Tools to manage and query databases with AI agents.

<Steps>
  <Step title="Install Dependencies">
    First, install the required packages:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonaiagents praisonai-tools duckdb
    ```
  </Step>

  <Step title="Import Components">
    Import the necessary components:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, Task, AgentTeam
    from praisonai_tools import execute_query, load_csv, export_csv
    ```
  </Step>

  <Step title="Create Agent">
    Create a DuckDB database agent:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    db_agent = Agent(
        name="DBProcessor",
        role="Database Management Specialist",
        goal="Manage and query databases efficiently.",
        backstory="Expert in database operations and SQL.",
        tools=[execute_query, load_csv, export_csv],
        reflection=False
    )
    ```
  </Step>

  <Step title="Define Task">
    Define the database task:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    db_task = Task(
        description="Query and analyze database data.",
        expected_output="Query results and analysis.",
        agent=db_agent,
        name="db_analysis"
    )
    ```
  </Step>

  <Step title="Run Agent">
    Initialize and run the agent:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agents = AgentTeam(
        agents=[db_agent],
        tasks=[db_task],
        process="sequential"
    )
    agents.start()
    ```
  </Step>
</Steps>

## Available Functions

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import execute_query
from praisonai_tools import load_csv
from praisonai_tools import export_csv
```

## Function Details

### execute\_query(query: str, params: Optional\[Union\[tuple, dict]] = None, return\_df: bool = True)

Executes SQL queries with advanced features:

* Supports parameterized queries
* Returns results as DataFrame records or raw tuples
* Full SQL query support (SELECT, INSERT, UPDATE, DELETE, etc.)
* Automatic connection management

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import execute_query

# Basic SELECT query
results = execute_query("SELECT * FROM employees")

# Parameterized query
results = execute_query(
    "SELECT * FROM employees WHERE department = ? AND salary > ?",
    params=('Engineering', 75000)
)

# Named parameters
results = execute_query(
    "SELECT * FROM employees WHERE department = :dept",
    params={'dept': 'Engineering'}
)
# Returns: List[Dict[str, Any]]
```

### load\_csv(table\_name: str, filepath: str, schema: Optional\[Dict\[str, str]] = None, if\_exists: str = 'replace')

Loads CSV files into DuckDB tables:

* Optional schema definition
* Flexible table existence handling
* Automatic type inference
* Support for large files

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import load_csv

# Basic usage - auto schema inference
success = load_csv("employees", "employees.csv")

# With custom schema
schema = {
    "id": "INTEGER PRIMARY KEY",
    "name": "VARCHAR",
    "salary": "DECIMAL(10,2)",
    "hire_date": "DATE"
}
success = load_csv(
    "employees",
    "employees.csv",
    schema=schema,
    if_exists='replace'
)
# Returns: bool (True if successful)
```

### export\_csv(query: str, filepath: str, params: Optional\[Union\[tuple, dict]] = None)

Exports query results to CSV files:

* Supports parameterized queries
* Automatic header generation
* Configurable output formatting
* Large result set handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import export_csv

# Export simple query results
success = export_csv(
    "SELECT * FROM employees",
    "exported_employees.csv"
)

# Export filtered data with parameters
success = export_csv(
    "SELECT * FROM employees WHERE department = ? AND year = ?",
    "eng_2023.csv",
    params=('Engineering', 2023)
)
# Returns: bool (True if successful)
```

## Understanding DuckDB Tools

<Card title="What are DuckDB Tools?" icon="question">
  DuckDB Tools provide database capabilities for AI agents:

  * SQL query execution
  * Data import/export
  * Schema management
  * Data analysis
  * Performance optimization
</Card>

## Key Components

<CardGroup cols={2}>
  <Card title="DB Agent" icon="user-robot">
    Create specialized database agents:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    Agent(tools=[execute_query, load_csv, export_csv])
    ```
  </Card>

  <Card title="DB Task" icon="list-check">
    Define database tasks:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    Task(description="db_operation")
    ```
  </Card>

  <Card title="Process Types" icon="arrows-split-up-and-left">
    Sequential or parallel processing:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    process="sequential"
    ```
  </Card>

  <Card title="DB Options" icon="sliders">
    Customize database parameters:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    read_only=True, memory=True
    ```
  </Card>
</CardGroup>

## Examples

### Basic Database Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam
from praisonai_tools import execute_query, load_csv, export_csv

# Create database agent
db_agent = Agent(
    name="DBExpert",
    role="Database Specialist",
    goal="Query and analyze data efficiently.",
    backstory="Expert in database management and SQL.",
    tools=[execute_query, load_csv, export_csv],
    reflection=False
)

# Define database task
db_task = Task(
    description="Analyze sales performance data.",
    expected_output="Sales analysis report.",
    agent=db_agent,
    name="sales_analysis"
)

# Run agent
agents = AgentTeam(
    agents=[db_agent],
    tasks=[db_task],
    process="sequential"
)
agents.start()
```

### Advanced Database Operations with Multiple Agents

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam
from praisonai_tools import execute_query, load_csv, export_csv

# Create query agent
query_agent = Agent(
    name="QueryProcessor",
    role="SQL Query Specialist",
    goal="Execute SQL queries efficiently.",
    tools=[execute_query],
    reflection=False
)

# Create data import/export agent
data_agent = Agent(
    name="DataProcessor",
    role="Data Import/Export Specialist",
    goal="Handle data import and export operations efficiently.",
    tools=[load_csv, export_csv],
    reflection=False
)

# Define tasks
query_task = Task(
    description="Query sales data",
    agent=query_agent,
    name="query_task"
)

data_task = Task(
    description="Export query results",
    agent=data_agent,
    name="data_task"
)

# Run agents
agents = AgentTeam(
    agents=[query_agent, data_agent],
    tasks=[query_task, data_task],
    process="sequential"
)
agents.start()
```

## Best Practices

<AccordionGroup>
  <Accordion title="Agent Configuration">
    Configure agents with clear database focus:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_tools import execute_query, load_csv, export_csv

    Agent(
        name="DBProcessor",
        role="Database Specialist",
        goal="Process queries accurately and efficiently",
        tools=[execute_query, load_csv, export_csv]
    )
    ```
  </Accordion>

  <Accordion title="Task Definition">
    Define specific database operations:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    Task(
        description="Query sales data and generate reports",
        expected_output="Sales performance report"
    )
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### Database Operation Pipeline

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam
from praisonai_tools import execute_query, load_csv, export_csv

# Query agent
querier = Agent(
    name="Querier",
    role="SQL Specialist",
    tools=[execute_query]
)

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

# Define tasks
query_task = Task(
    description="Execute SQL queries",
    agent=querier
)

analyze_task = Task(
    description="Analyze query results",
    agent=analyzer
)

# Run workflow
agents = AgentTeam(
    agents=[querier, analyzer],
    tasks=[query_task, analyze_task]
)
```

## Related

<CardGroup cols={2}>
  <Card title="Custom Tools" icon="wrench" href="/docs/tools/custom">
    Build your own agent tools
  </Card>

  <Card title="Tools Overview" icon="toolbox" href="/docs/tools/tools">
    Browse PraisonAI tool documentation
  </Card>
</CardGroup>