> ## 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.

# Calculator Agent

> Mathematical calculation tools for AI agents.

<Note>
  **Prerequisites**

  * Python 3.10 or higher
  * PraisonAI Agents package installed
  * PraisonAI Tools package installed
  * `sympy` and `pint` packages installed
</Note>

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

agent = Agent(name="MathAssistant", tools=[evaluate])
agent.start("What is the area of a circle with radius 5?")
```

The user asks a maths question; the agent evaluates expressions and returns a precise answer.

```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 Calculator Agent

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

## Calculator Tools

Use Calculator Tools to perform mathematical calculations 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 sympy pint
    ```
  </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 (
        evaluate, solve_equation, convert_units,
        calculate_statistics, calculate_financial
    )
    ```
  </Step>

  <Step title="Create Agent">
    Create a calculator agent:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    calculator_agent = Agent(
        name="MathAssistant",
        role="Mathematical Computation Specialist",
        goal="Perform accurate mathematical calculations and solve equations.",
        backstory="Expert in mathematical computations and problem-solving.",
        tools=[
            evaluate, solve_equation, convert_units,
            calculate_statistics, calculate_financial
        ],
        reflection=False
    )
    ```
  </Step>

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

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    calc_task = Task(
        description="Calculate the area of a circle with radius 5",
        expected_output="The area of the circle in square units",
        agent=calculator_agent,
        name="circle_area"
    )
    ```
  </Step>

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

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

## Understanding Calculator Tools

<Card title="What are Calculator Tools?" icon="question">
  Calculator Tools provide mathematical computation capabilities for AI agents:

  * Expression evaluation
  * Equation solving
  * Unit conversions
  * Support for mathematical functions
  * Variable substitution
</Card>

## Key Components

<CardGroup cols={2}>
  <Card title="Expression Evaluation" icon="function">
    Evaluate mathematical expressions:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = evaluate("2 + 2 * 3")
    ```
  </Card>

  <Card title="Equation Solving" icon="equals">
    Solve mathematical equations:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = solve_equation("2*x + 3 = 7")
    ```
  </Card>

  <Card title="Unit Conversions" icon="exchange">
    Convert between units:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = convert_units(100, "meters", "kilometers")
    ```
  </Card>

  <Card title="Statistical Calculations" icon="chart-line">
    Calculate statistical metrics:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = calculate_statistics([1, 2, 3, 4, 5])
    ```
  </Card>

  <Card title="Financial Calculations" icon="chart-pie">
    Calculate financial metrics:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = calculate_financial(1000, 5, 2)
    ```
  </Card>
</CardGroup>

## Available Functions

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import evaluate
from praisonai_tools import solve_equation
from praisonai_tools import convert_units
from praisonai_tools import calculate_statistics
from praisonai_tools import calculate_financial
```

## Advanced Usage

<AccordionGroup>
  <Accordion title="Expression Evaluation">
    Evaluate complex mathematical expressions with variables:

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

    # Basic arithmetic
    result = evaluate("2 + 2 * 3")

    # With mathematical functions
    result = evaluate("sin(pi/2) + sqrt(16)")

    # With variables
    result = evaluate(
        "x^2 + y",
        variables={"x": 3, "y": 4}
    )
    ```
  </Accordion>

  <Accordion title="Equation Solving">
    Solve different types of equations:

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

    # Linear equation
    result = solve_equation("2*x + 3 = 7")

    # With custom variable
    result = solve_equation("y^2 = 4", variable="y")
    ```
  </Accordion>

  <Accordion title="Unit Conversions">
    Convert between different units:

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

    # Length conversion
    result = convert_units(100, "meters", "kilometers")

    # Temperature conversion
    result = convert_units(32, "fahrenheit", "celsius")

    # Time conversion
    result = convert_units(2.5, "hours", "minutes")
    ```
  </Accordion>

  <Accordion title="Statistical Calculations">
    Calculate statistical metrics:

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

    result = calculate_statistics([1, 2, 3, 4, 5])
    ```
  </Accordion>

  <Accordion title="Financial Calculations">
    Calculate financial metrics:

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

    result = calculate_financial(1000, 5, 2)
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

<Card title="Error Management" icon="shield-check">
  The tools include comprehensive error handling:

  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # Returns success result
  {"result": 8.0}

  # Returns error message
  {"error": "Invalid expression"}
  ```
</Card>

## Best Practices

<AccordionGroup>
  <Accordion title="Precision Control">
    Control calculation precision:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    evaluate(
        "pi",
        precision=5
    )
    ```
  </Accordion>

  <Accordion title="Safe Execution">
    Uses safe evaluation environment with:

    * Restricted builtins
    * Mathematical functions only
    * Variable validation
  </Accordion>
</AccordionGroup>

## Examples

### Basic Calculator Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam
from praisonai_tools import evaluate, solve_equation, convert_units

# Create calculator agent
calc_agent = Agent(
    name="MathExpert",
    role="Mathematical Specialist",
    goal="Solve mathematical problems accurately.",
    backstory="Expert in mathematics and calculations.",
    tools=[evaluate, solve_equation, convert_units],
    reflection=False
)

# Define task
calc_task = Task(
    description="Solve the equation 2x + 5 = 15",
    expected_output="Value of x",
    agent=calc_agent,
    name="equation_solver"
)

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

## 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>