Overview
Tools extend agent capabilities beyond language generation, allowing them to:- Search the web for real-time information
- Execute code and scripts
- Query databases
- Make API calls
- Process files and data
- Perform calculations
Basic Tool Integration
Here’s a simple example of creating a tool and using it with an agent:from swarms import Agent
def calculate_roi(investment: float, return_amount: float) -> str:
"""
Calculate Return on Investment (ROI)
Args:
investment (float): Initial investment amount
return_amount (float): Return amount received
Returns:
str: ROI percentage and analysis
"""
roi = ((return_amount - investment) / investment) * 100
return f"ROI: {roi:.2f}%. Investment: ${investment:,.2f}, Return: ${return_amount:,.2f}"
# Create agent with the tool
agent = Agent(
agent_name="Financial-Analyst",
system_prompt="You are a financial analyst. Use the calculate_roi tool to analyze investments.",
model_name="gpt-5.4",
max_loops=1,
tools=[calculate_roi], # Add tools here
)
# Agent will automatically use the tool when needed
response = agent.run(
"What's the ROI if I invest $10,000 and get back $15,000?"
)
print(response)
Real-World Example: Web Search Agent
Here’s a production-ready example using the Exa search API:from swarms import Agent
import os
import httpx
from loguru import logger
from swarms.utils.any_to_str import any_to_str
def exa_search(query: str) -> str:
"""
Exa Web Search Tool
Advanced web search using the Exa.ai API for research agents.
Retrieves up-to-date information from documentation, articles, and more.
Args:
query (str): Natural language search query
Returns:
str: JSON-formatted search results with summaries
Example:
exa_search("Latest PyTorch 2.2.0 quantization APIs")
"""
api_key = os.getenv("EXA_API_KEY")
if not api_key:
raise ValueError("EXA_API_KEY environment variable is not set")
headers = {
"x-api-key": api_key,
"content-type": "application/json",
}
payload = {
"query": query,
"type": "auto",
"numResults": 5,
"contents": {
"text": True,
"summary": {
"schema": {
"type": "object",
"required": ["answer"],
"properties": {
"answer": {
"type": "string",
"description": "Key insights from the search result",
}
},
}
},
},
}
try:
logger.info(f"[SEARCH] Executing Exa search for: {query[:50]}...")
response = httpx.post(
"https://api.exa.ai/search",
json=payload,
headers=headers,
timeout=30,
)
response.raise_for_status()
json_data = response.json()
return any_to_str(json_data)
except Exception as e:
logger.error(f"Exa search failed: {e}")
return f"Search failed: {str(e)}. Please try again."
# Initialize agent with search tool
agent = Agent(
agent_name="Quantitative-Trading-Agent",
agent_description="Advanced quantitative trading and algorithmic analysis agent",
model_name="gpt-4.1",
dynamic_temperature_enabled=True,
max_loops=1,
tools=[exa_search],
)
out = agent.run(
"Create a report on the most undervalued and high potential energy stocks"
)
print(out)
Multiple Tools Example
Agents can use multiple tools in a single workflow:from swarms import Agent
import httpx
import json
def search_stocks(query: str) -> str:
"""
Search for stock information
Args:
query (str): Stock symbol or company name
Returns:
str: Stock information
"""
# Implementation here
return f"Stock information for {query}"
def analyze_financials(stock_symbol: str) -> str:
"""
Analyze financial statements for a stock
Args:
stock_symbol (str): Stock ticker symbol
Returns:
str: Financial analysis
"""
# Implementation here
return f"Financial analysis for {stock_symbol}"
def calculate_metrics(revenue: float, expenses: float) -> str:
"""
Calculate financial metrics
Args:
revenue (float): Total revenue
expenses (float): Total expenses
Returns:
str: Calculated metrics including profit margin
"""
profit = revenue - expenses
margin = (profit / revenue) * 100 if revenue > 0 else 0
return f"Profit: ${profit:,.2f}, Margin: {margin:.2f}%"
# Agent with multiple tools
multi_tool_agent = Agent(
agent_name="Investment-Analyst",
system_prompt="You are an investment analyst. Use the available tools to research and analyze stocks.",
model_name="gpt-5.4",
max_loops=3,
tools=[search_stocks, analyze_financials, calculate_metrics],
)
result = multi_tool_agent.run(
"Analyze Apple (AAPL) stock and provide investment recommendation"
)
print(result)
Tool Types
1. Python Functions
Simple Python functions with type hints and docstrings:def get_weather(city: str, units: str = "celsius") -> str:
"""
Get current weather for a city
Args:
city (str): City name
units (str): Temperature units (celsius or fahrenheit)
Returns:
str: Weather information
"""
# API call here
return f"Weather in {city}: 22°C, Sunny"
agent = Agent(
model_name="gpt-5.4",
tools=[get_weather],
)
2. BaseTool Class
For more complex tools, use theBaseTool class:
from swarms.tools.base_tool import BaseTool
from pydantic import Field
class WebSearchTool(BaseTool):
"""
Web search tool for finding information online
"""
name: str = "web_search"
description: str = "Search the web for information"
api_key: str = Field(..., description="API key for search service")
def run(self, query: str) -> str:
"""
Execute web search
Args:
query (str): Search query
Returns:
str: Search results
"""
# Implementation
return f"Search results for: {query}"
# Use the tool
search_tool = WebSearchTool(api_key=os.getenv("SEARCH_API_KEY"))
agent = Agent(
model_name="gpt-5.4",
tools=[search_tool],
)
3. External Tool Libraries
Integrate tools from external libraries:# Pip install swarms-tools
from swarms_tools import exa_search, browser_use
from swarms import Agent
# Agent with pre-built tools
agent = Agent(
agent_name="Research-Agent",
model_name="gpt-5.4",
tools=[exa_search, browser_use],
)
result = agent.run("Find the latest AI research papers from 2024")
Advanced Tool Patterns
Tool with Error Handling
def safe_api_call(endpoint: str, params: dict) -> str:
"""
Make API call with error handling
Args:
endpoint (str): API endpoint URL
params (dict): Request parameters
Returns:
str: API response or error message
"""
try:
response = httpx.get(endpoint, params=params, timeout=10)
response.raise_for_status()
return json.dumps(response.json())
except httpx.HTTPError as e:
return f"API call failed: {str(e)}"
except Exception as e:
return f"Unexpected error: {str(e)}"
Stateful Tool
class DatabaseTool:
"""
Tool that maintains connection state
"""
def __init__(self, connection_string: str):
self.connection_string = connection_string
self.connection = None
def query(self, sql: str) -> str:
"""
Execute SQL query
Args:
sql (str): SQL query to execute
Returns:
str: Query results
"""
if not self.connection:
self.connection = self._connect()
# Execute query
return "Query results"
def _connect(self):
# Establish connection
return None
# Use stateful tool
db_tool = DatabaseTool("postgresql://localhost/mydb")
agent = Agent(
model_name="gpt-5.4",
tools=[db_tool.query],
)
Best Practices
1. Clear Tool Documentation
Always provide detailed docstrings:def analyze_sentiment(text: str) -> str:
"""
Analyze sentiment of text
This tool uses natural language processing to determine whether
the sentiment of the input text is positive, negative, or neutral.
Args:
text (str): The text to analyze. Should be at least 10 characters.
Returns:
str: Sentiment analysis result with score and classification
Example:
>>> analyze_sentiment("I love this product!")
"Sentiment: Positive (Score: 0.92)"
"""
# Implementation
pass
2. Type Hints
Use proper type hints for better tool discovery:from typing import Dict, List, Optional
def search_database(
query: str,
filters: Optional[Dict[str, str]] = None,
limit: int = 10
) -> List[Dict[str, Any]]:
"""
Search database with filters
"""
pass
3. Error Handling
Handle errors gracefully:def robust_tool(input_data: str) -> str:
"""
Tool with robust error handling
"""
try:
# Tool logic
result = process(input_data)
return result
except ValueError as e:
return f"Invalid input: {e}"
except Exception as e:
logger.error(f"Tool error: {e}")
return "Tool execution failed. Please try again."
4. Logging
Add logging for debugging:from loguru import logger
def logged_tool(param: str) -> str:
"""
Tool with logging
"""
logger.info(f"Tool called with param: {param}")
try:
result = execute(param)
logger.success(f"Tool completed successfully")
return result
except Exception as e:
logger.error(f"Tool failed: {e}")
raise
Tool Configuration
Dynamic Tool Loading
from swarms import Agent
# Load tools dynamically
tools = []
if os.getenv("ENABLE_SEARCH"):
tools.append(exa_search)
if os.getenv("ENABLE_DATABASE"):
tools.append(db_query)
agent = Agent(
model_name="gpt-5.4",
tools=tools,
)
Tool Registry
from swarms.tools.tool_registry import ToolRegistry
# Create tool registry
registry = ToolRegistry()
# Register tools
registry.register("search", exa_search)
registry.register("calculate", calculate_metrics)
# Use registered tools
agent = Agent(
model_name="gpt-5.4",
tools=registry.get_all_tools(),
)
Output Examples
When an agent uses tools, you’ll see output like:🤖 Agent: Financial-Analyst
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 Using tool: calculate_roi
Arguments: {"investment": 10000, "return_amount": 15000}
📊 Tool Result:
ROI: 50.00%. Investment: $10,000.00, Return: $15,000.00
💡 Analysis:
Based on the ROI calculation, this investment returned 50%, which is
an excellent return. The investment of $10,000 generated a profit of
$5,000, indicating strong performance.
Next Steps
- Vision Agent - Add image processing capabilities
- Streaming - Stream tool results in real-time
- Multi-Agent Workflows - Coordinate agents with different tools
- Tool Development Guide - Build custom tools