Tools

Tools in AgentOpera are specialized components that enable agents to perform specific actions or access external resources. They bridge AI agents with various capabilities like data processing, API interactions, and more.

Core Tool Concepts

In AgentOpera, tools are implemented using the Tool protocol and typically based on the BaseTool abstract class. A tool provides:

1. A JSON schema that defines its parameters and functionality

2. Input validation and processing logic

3. Execution methods that perform the actual work

4. State management capabilities (optional)

Using BaseTool

The BaseTool abstract class serves as the foundation for most tools in AgentOpera. It provides a standardized way to define, validate, and execute tool functionality.

from agentopera.engine.types.agent import CancellationToken
from agentopera.engine.function_call import BaseTool, FunctionTool
from pydantic import BaseModel

class CalculatorInput(BaseModel):
    expression: str

class CalculatorOutput(BaseModel):
    result: float

# Create a custom tool by extending BaseTool
class CalculatorTool(BaseTool[CalculatorInput, CalculatorOutput]):
    def __init__(self):
        super().__init__(
            args_type=CalculatorInput,
            return_type=CalculatorOutput,
            name="calculator",
            description="Evaluates a mathematical expression and returns the result"
        )
    
    async def run(self, args: CalculatorInput, cancellation_token: CancellationToken) -> CalculatorOutput:
        # Implement the tool's functionality
        result = eval(args.expression)
        return CalculatorOutput(result=result)

FunctionTool: Turning Functions into Tools

The most common way to create tools is by using FunctionTool, which converts regular Python functions into AgentOpera tools. This approach is straightforward and leverages Python's type annotations for automatic schema generation.

import random
from agentopera.engine.types.agent import CancellationToken
from agentopera.engine.function_call import FunctionTool
from typing_extensions import Annotated

# Define a simple function with type annotations
async def get_weather(city: str, date: Annotated[str, "Date in YYYY-MM-DD format"]) -> str:
    """Get the weather forecast for a city on a specific date."""
    # In a real implementation, this would call a weather API
    weather_conditions = ["Sunny", "Cloudy", "Rainy", "Snowy"]
    temp = random.randint(0, 35)
    condition = random.choice(weather_conditions)
    return f"The weather in {city} on {date} is forecasted to be {condition} with a temperature of {temp}°C."

# Create a FunctionTool from the function
weather_tool = FunctionTool(
    get_weather, 
    description="Get weather forecast for a specific city and date"
)

# Example of using the tool
async def example_usage():
    cancellation_token = CancellationToken()
    result = await weather_tool.run_json(
        {"city": "London", "date": "2024-08-15"}, 
        cancellation_token
    )
    print(weather_tool.return_value_as_string(result))

Built-in Tools

AgentOpera provides several built-in tools for common tasks:

• HTTP Tools: For making web requests and API calls

• Code Execution Tools: For running code in various environments

• File Operation Tools: For reading, writing, and managing files

Best Practices for Creating Tools

1. Use Clear Descriptions: Provide detailed descriptions for your tools and parameters

2. Leverage Type Annotations: Use Python's type hints and Annotated for better schema generation

3. Keep Tools Focused: Design tools to do one thing well rather than combining multiple functionalities