Tools¶

Tools (also known as function calling) allow agents to perform actions beyond text generation by invoking specific functions. This page explains how to integrate and use tools with Agentle agents.

Basic Tool Integration¶

Here’s a simple example of integrating a tool with an agent:

def get_weather(location: str) -> str:
    """
    Get the current weather for a location.

    Args:
        location: The city or location to get weather for

    Returns:
        A string describing the weather
    """
    weather_data = {
        "New York": "Sunny, 75°F",
        "London": "Rainy, 60°F",
        "Tokyo": "Cloudy, 65°F",
        "Sydney": "Clear, 80°F",
    }
    return weather_data.get(location, f"Weather data not available for {location}")

# Create an agent with a tool
from agentle.agents.agent import Agent
from agentle.generations.providers.google.google_genai_generation_provider import GoogleGenaiGenerationProvider

weather_agent = Agent(
    name="Weather Assistant",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="You are a helpful assistant that can answer questions about the weather.",
    tools=[get_weather]  # Pass the function as a tool
)

# The agent will automatically use the tool when appropriate
response = weather_agent.run("What's the weather like in Tokyo?")
print(response.text)

Function Docstrings and Type Hints¶

Agentle uses function docstrings and type hints to determine:

When to call the function
What parameters to pass
How to interpret the results

For best results, provide clear docstrings and type hints:

def calculate_mortgage(
    principal: float,
    interest_rate: float,
    years: int
) -> dict:
    """
    Calculate monthly mortgage payments.

    Args:
        principal: The loan amount in dollars
        interest_rate: Annual interest rate (as a percentage, e.g., 5.5 for 5.5%)
        years: Loan term in years

    Returns:
        A dictionary containing monthly payment, total interest, and total cost
    """
    monthly_rate = interest_rate / 100 / 12
    num_payments = years * 12

    # Calculate monthly payment
    monthly_payment = principal * (monthly_rate * (1 + monthly_rate) ** num_payments) / ((1 + monthly_rate) ** num_payments - 1)

    # Calculate total interest and total cost
    total_cost = monthly_payment * num_payments
    total_interest = total_cost - principal

    return {
        "monthly_payment": round(monthly_payment, 2),
        "total_interest": round(total_interest, 2),
        "total_cost": round(total_cost, 2)
    }

Adding Multiple Tools¶

You can add multiple tools to an agent:

def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    # Implementation...
    return weather_data.get(location, f"Weather data not available for {location}")

def convert_currency(amount: float, from_currency: str, to_currency: str) -> float:
    """
    Convert an amount from one currency to another.

    Args:
        amount: The amount to convert
        from_currency: The source currency code (e.g., USD, EUR)
        to_currency: The target currency code (e.g., USD, EUR)

    Returns:
        The converted amount
    """
    # Sample conversion rates (in practice, use a real API)
    rates = {
        "USD": 1.0,
        "EUR": 0.85,
        "GBP": 0.75,
        "JPY": 110.0,
        "CAD": 1.25
    }

    # Convert to USD first, then to target currency
    usd_amount = amount / rates.get(from_currency, 1.0)
    converted_amount = usd_amount * rates.get(to_currency, 1.0)

    return round(converted_amount, 2)

# Create an agent with multiple tools
travel_assistant = Agent(
    name="Travel Assistant",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="You are a helpful travel assistant.",
    tools=[get_weather, convert_currency]  # Multiple tools
)

Advanced Tool Usage¶

Combining Tools with Structured Outputs¶

For even more powerful agents, combine tool calling with structured outputs:

from pydantic import BaseModel
from typing import List, Optional

class TravelRecommendation(BaseModel):
    city: str
    country: str
    population: int
    local_time: str
    attractions: List[str]
    best_time_to_visit: str
    estimated_daily_budget: float
    safety_rating: Optional[int] = None

# Create an agent with both tools and a structured output schema
travel_agent = Agent(
    name="Travel Advisor",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="""You are a travel advisor that provides structured recommendations for city visits.""",
    tools=[get_city_data],
    response_schema=TravelRecommendation,
)

Classes as Tools¶

You can also use methods from classes as tools:

class Calculator:
    def add(self, a: float, b: float) -> float:
        """Add two numbers together."""
        return a + b

    def subtract(self, a: float, b: float) -> float:
        """Subtract b from a."""
        return a - b

calculator = Calculator()

# Use instance methods as tools
math_agent = Agent(
    name="Math Helper",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="You are a math assistant.",
    tools=[calculator.add, calculator.subtract]
)

Best Practices for Tools¶

Clear Docstrings: Provide clear, detailed docstrings that explain what the function does
Type Hints: Always use type hints for parameters and return values
Error Handling: Ensure your tools handle errors gracefully
Idempotence: When possible, make your tools idempotent (same input always produces same output)
Security: Be mindful of security implications, especially for tools that access sensitive resources