Kye Gomez
6 days ago
parent
26d5047f76
commit
1f0ee6950c
@ -0,0 +1,600 @@
|
|||||||
|
# Swarms Tools Documentation
|
||||||
|
|
||||||
|
Swarms provides a comprehensive toolkit for integrating various types of tools into your AI agents. This guide covers all available tool options including callable functions, MCP servers, schemas, and more.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install swarms
|
||||||
|
```
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Swarms provides a comprehensive suite of tool integration methods to enhance your AI agents' capabilities:
|
||||||
|
|
||||||
|
| Tool Type | Description |
|
||||||
|
|-----------|-------------|
|
||||||
|
| **Callable Functions** | Direct integration of Python functions with proper type hints and comprehensive docstrings for immediate tool functionality |
|
||||||
|
| **MCP Servers** | Model Context Protocol servers enabling distributed tool functionality across multiple services and environments |
|
||||||
|
| **Tool Schemas** | Structured tool definitions that provide standardized interfaces and validation for tool integration |
|
||||||
|
| **Tool Collections** | Pre-built tool packages offering ready-to-use functionality for common use cases |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Method 1: Callable Functions
|
||||||
|
|
||||||
|
Callable functions are the simplest way to add tools to your Swarms agents. They are regular Python functions with type hints and comprehensive docstrings.
|
||||||
|
|
||||||
|
### Step 1: Define Your Tool Functions
|
||||||
|
|
||||||
|
Create functions with the following requirements:
|
||||||
|
|
||||||
|
- **Type hints** for all parameters and return values
|
||||||
|
|
||||||
|
- **Comprehensive docstrings** with Args, Returns, Raises, and Examples sections
|
||||||
|
|
||||||
|
- **Error handling** for robust operation
|
||||||
|
|
||||||
|
#### Example: Cryptocurrency Price Tools
|
||||||
|
|
||||||
|
```python
|
||||||
|
import json
|
||||||
|
import requests
|
||||||
|
from swarms import Agent
|
||||||
|
|
||||||
|
|
||||||
|
def get_coin_price(coin_id: str, vs_currency: str = "usd") -> str:
|
||||||
|
"""
|
||||||
|
Get the current price of a specific cryptocurrency.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
coin_id (str): The CoinGecko ID of the cryptocurrency
|
||||||
|
Examples: 'bitcoin', 'ethereum', 'cardano'
|
||||||
|
vs_currency (str, optional): The target currency for price conversion.
|
||||||
|
Supported: 'usd', 'eur', 'gbp', 'jpy', etc.
|
||||||
|
Defaults to "usd".
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: JSON formatted string containing the coin's current price and market data
|
||||||
|
including market cap, 24h volume, and price changes
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
requests.RequestException: If the API request fails due to network issues
|
||||||
|
ValueError: If coin_id is empty or invalid
|
||||||
|
TimeoutError: If the request takes longer than 10 seconds
|
||||||
|
|
||||||
|
Example:
|
||||||
|
>>> result = get_coin_price("bitcoin", "usd")
|
||||||
|
>>> print(result)
|
||||||
|
{"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}}
|
||||||
|
|
||||||
|
>>> result = get_coin_price("ethereum", "eur")
|
||||||
|
>>> print(result)
|
||||||
|
{"ethereum": {"eur": 3200, "eur_market_cap": 384000000000, ...}}
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
# Validate input parameters
|
||||||
|
if not coin_id or not coin_id.strip():
|
||||||
|
raise ValueError("coin_id cannot be empty")
|
||||||
|
|
||||||
|
url = "https://api.coingecko.com/api/v3/simple/price"
|
||||||
|
params = {
|
||||||
|
"ids": coin_id.lower().strip(),
|
||||||
|
"vs_currencies": vs_currency.lower(),
|
||||||
|
"include_market_cap": True,
|
||||||
|
"include_24hr_vol": True,
|
||||||
|
"include_24hr_change": True,
|
||||||
|
"include_last_updated_at": True,
|
||||||
|
}
|
||||||
|
|
||||||
|
response = requests.get(url, params=params, timeout=10)
|
||||||
|
response.raise_for_status()
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
# Check if the coin was found
|
||||||
|
if not data:
|
||||||
|
return json.dumps({
|
||||||
|
"error": f"Cryptocurrency '{coin_id}' not found. Please check the coin ID."
|
||||||
|
})
|
||||||
|
|
||||||
|
return json.dumps(data, indent=2)
|
||||||
|
|
||||||
|
except requests.RequestException as e:
|
||||||
|
return json.dumps({
|
||||||
|
"error": f"Failed to fetch price for {coin_id}: {str(e)}",
|
||||||
|
"suggestion": "Check your internet connection and try again"
|
||||||
|
})
|
||||||
|
except ValueError as e:
|
||||||
|
return json.dumps({"error": str(e)})
|
||||||
|
except Exception as e:
|
||||||
|
return json.dumps({"error": f"Unexpected error: {str(e)}"})
|
||||||
|
|
||||||
|
|
||||||
|
def get_top_cryptocurrencies(limit: int = 10, vs_currency: str = "usd") -> str:
|
||||||
|
"""
|
||||||
|
Fetch the top cryptocurrencies by market capitalization.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
limit (int, optional): Number of coins to retrieve.
|
||||||
|
Range: 1-250 coins
|
||||||
|
Defaults to 10.
|
||||||
|
vs_currency (str, optional): The target currency for price conversion.
|
||||||
|
Supported: 'usd', 'eur', 'gbp', 'jpy', etc.
|
||||||
|
Defaults to "usd".
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: JSON formatted string containing top cryptocurrencies with detailed market data
|
||||||
|
including: id, symbol, name, current_price, market_cap, market_cap_rank,
|
||||||
|
total_volume, price_change_24h, price_change_7d, last_updated
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
requests.RequestException: If the API request fails
|
||||||
|
ValueError: If limit is not between 1 and 250
|
||||||
|
|
||||||
|
Example:
|
||||||
|
>>> result = get_top_cryptocurrencies(5, "usd")
|
||||||
|
>>> print(result)
|
||||||
|
[{"id": "bitcoin", "name": "Bitcoin", "current_price": 45000, ...}]
|
||||||
|
|
||||||
|
>>> result = get_top_cryptocurrencies(limit=3, vs_currency="eur")
|
||||||
|
>>> print(result)
|
||||||
|
[{"id": "bitcoin", "name": "Bitcoin", "current_price": 38000, ...}]
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
# Validate parameters
|
||||||
|
if not isinstance(limit, int) or not 1 <= limit <= 250:
|
||||||
|
raise ValueError("Limit must be an integer between 1 and 250")
|
||||||
|
|
||||||
|
url = "https://api.coingecko.com/api/v3/coins/markets"
|
||||||
|
params = {
|
||||||
|
"vs_currency": vs_currency.lower(),
|
||||||
|
"order": "market_cap_desc",
|
||||||
|
"per_page": limit,
|
||||||
|
"page": 1,
|
||||||
|
"sparkline": False,
|
||||||
|
"price_change_percentage": "24h,7d",
|
||||||
|
}
|
||||||
|
|
||||||
|
response = requests.get(url, params=params, timeout=10)
|
||||||
|
response.raise_for_status()
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
# Simplify and structure the data for better readability
|
||||||
|
simplified_data = []
|
||||||
|
for coin in data:
|
||||||
|
simplified_data.append({
|
||||||
|
"id": coin.get("id"),
|
||||||
|
"symbol": coin.get("symbol", "").upper(),
|
||||||
|
"name": coin.get("name"),
|
||||||
|
"current_price": coin.get("current_price"),
|
||||||
|
"market_cap": coin.get("market_cap"),
|
||||||
|
"market_cap_rank": coin.get("market_cap_rank"),
|
||||||
|
"total_volume": coin.get("total_volume"),
|
||||||
|
"price_change_24h": round(coin.get("price_change_percentage_24h", 0), 2),
|
||||||
|
"price_change_7d": round(coin.get("price_change_percentage_7d_in_currency", 0), 2),
|
||||||
|
"last_updated": coin.get("last_updated"),
|
||||||
|
})
|
||||||
|
|
||||||
|
return json.dumps(simplified_data, indent=2)
|
||||||
|
|
||||||
|
except (requests.RequestException, ValueError) as e:
|
||||||
|
return json.dumps({
|
||||||
|
"error": f"Failed to fetch top cryptocurrencies: {str(e)}"
|
||||||
|
})
|
||||||
|
except Exception as e:
|
||||||
|
return json.dumps({"error": f"Unexpected error: {str(e)}"})
|
||||||
|
|
||||||
|
|
||||||
|
def search_cryptocurrencies(query: str) -> str:
|
||||||
|
"""
|
||||||
|
Search for cryptocurrencies by name or symbol.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
query (str): The search term (coin name or symbol)
|
||||||
|
Examples: 'bitcoin', 'btc', 'ethereum', 'eth'
|
||||||
|
Case-insensitive search
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: JSON formatted string containing search results with coin details
|
||||||
|
including: id, name, symbol, market_cap_rank, thumb (icon URL)
|
||||||
|
Limited to top 10 results for performance
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
requests.RequestException: If the API request fails
|
||||||
|
ValueError: If query is empty
|
||||||
|
|
||||||
|
Example:
|
||||||
|
>>> result = search_cryptocurrencies("ethereum")
|
||||||
|
>>> print(result)
|
||||||
|
{"coins": [{"id": "ethereum", "name": "Ethereum", "symbol": "eth", ...}]}
|
||||||
|
|
||||||
|
>>> result = search_cryptocurrencies("btc")
|
||||||
|
>>> print(result)
|
||||||
|
{"coins": [{"id": "bitcoin", "name": "Bitcoin", "symbol": "btc", ...}]}
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
# Validate input
|
||||||
|
if not query or not query.strip():
|
||||||
|
raise ValueError("Search query cannot be empty")
|
||||||
|
|
||||||
|
url = "https://api.coingecko.com/api/v3/search"
|
||||||
|
params = {"query": query.strip()}
|
||||||
|
|
||||||
|
response = requests.get(url, params=params, timeout=10)
|
||||||
|
response.raise_for_status()
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
# Extract and format the results
|
||||||
|
coins = data.get("coins", [])[:10] # Limit to top 10 results
|
||||||
|
|
||||||
|
result = {
|
||||||
|
"coins": coins,
|
||||||
|
"query": query,
|
||||||
|
"total_results": len(data.get("coins", [])),
|
||||||
|
"showing": min(len(coins), 10)
|
||||||
|
}
|
||||||
|
|
||||||
|
return json.dumps(result, indent=2)
|
||||||
|
|
||||||
|
except requests.RequestException as e:
|
||||||
|
return json.dumps({
|
||||||
|
"error": f'Failed to search for "{query}": {str(e)}'
|
||||||
|
})
|
||||||
|
except ValueError as e:
|
||||||
|
return json.dumps({"error": str(e)})
|
||||||
|
except Exception as e:
|
||||||
|
return json.dumps({"error": f"Unexpected error: {str(e)}"})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Configure Your Agent
|
||||||
|
|
||||||
|
Create an agent with the following key parameters:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Initialize the agent with cryptocurrency tools
|
||||||
|
agent = Agent(
|
||||||
|
agent_name="Financial-Analysis-Agent", # Unique identifier for your agent
|
||||||
|
agent_description="Personal finance advisor agent with cryptocurrency market analysis capabilities",
|
||||||
|
system_prompt="""You are a personal finance advisor agent with access to real-time
|
||||||
|
cryptocurrency data from CoinGecko. You can help users analyze market trends, check
|
||||||
|
coin prices, find trending cryptocurrencies, and search for specific coins. Always
|
||||||
|
provide accurate, up-to-date information and explain market data in an easy-to-understand way.""",
|
||||||
|
max_loops=1, # Number of reasoning loops
|
||||||
|
max_tokens=4096, # Maximum response length
|
||||||
|
model_name="anthropic/claude-3-opus-20240229", # LLM model to use
|
||||||
|
dynamic_temperature_enabled=True, # Enable adaptive creativity
|
||||||
|
output_type="all", # Return complete response
|
||||||
|
tools=[ # List of callable functions
|
||||||
|
get_coin_price,
|
||||||
|
get_top_cryptocurrencies,
|
||||||
|
search_cryptocurrencies,
|
||||||
|
],
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Use Your Agent
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Example usage with different queries
|
||||||
|
response = agent.run("What are the top 5 cryptocurrencies by market cap?")
|
||||||
|
print(response)
|
||||||
|
|
||||||
|
# Query with specific parameters
|
||||||
|
response = agent.run("Get the current price of Bitcoin and Ethereum in EUR")
|
||||||
|
print(response)
|
||||||
|
|
||||||
|
# Search functionality
|
||||||
|
response = agent.run("Search for cryptocurrencies related to 'cardano'")
|
||||||
|
print(response)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Method 2: MCP (Model Context Protocol) Servers
|
||||||
|
|
||||||
|
MCP servers provide a standardized way to create distributed tool functionality. They're ideal for:
|
||||||
|
- **Reusable tools** across multiple agents
|
||||||
|
- **Complex tool logic** that needs isolation
|
||||||
|
- **Third-party tool integration**
|
||||||
|
- **Scalable architectures**
|
||||||
|
|
||||||
|
### Step 1: Create Your MCP Server
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mcp.server.fastmcp import FastMCP
|
||||||
|
import requests
|
||||||
|
|
||||||
|
# Initialize the MCP server with configuration
|
||||||
|
mcp = FastMCP("OKXCryptoPrice") # Server name for identification
|
||||||
|
mcp.settings.port = 8001 # Port for server communication
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Define MCP Tools
|
||||||
|
|
||||||
|
Each MCP tool requires the `@mcp.tool` decorator with specific parameters:
|
||||||
|
|
||||||
|
```python
|
||||||
|
@mcp.tool(
|
||||||
|
name="get_okx_crypto_price", # Tool identifier (must be unique)
|
||||||
|
description="Get the current price and basic information for a given cryptocurrency from OKX exchange.",
|
||||||
|
)
|
||||||
|
def get_okx_crypto_price(symbol: str) -> str:
|
||||||
|
"""
|
||||||
|
Get the current price and basic information for a given cryptocurrency using OKX API.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
symbol (str): The cryptocurrency trading pair
|
||||||
|
Format: 'BASE-QUOTE' (e.g., 'BTC-USDT', 'ETH-USDT')
|
||||||
|
If only base currency provided, '-USDT' will be appended
|
||||||
|
Case-insensitive input
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: A formatted string containing:
|
||||||
|
- Current price in USDT
|
||||||
|
- 24-hour price change percentage
|
||||||
|
- Formatted for human readability
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
requests.RequestException: If the OKX API request fails
|
||||||
|
ValueError: If symbol format is invalid
|
||||||
|
ConnectionError: If unable to connect to OKX servers
|
||||||
|
|
||||||
|
Example:
|
||||||
|
>>> get_okx_crypto_price('BTC-USDT')
|
||||||
|
'Current price of BTC/USDT: $45,000.00\n24h Change: +2.34%'
|
||||||
|
|
||||||
|
>>> get_okx_crypto_price('eth') # Automatically converts to ETH-USDT
|
||||||
|
'Current price of ETH/USDT: $3,200.50\n24h Change: -1.23%'
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
# Input validation and formatting
|
||||||
|
if not symbol or not symbol.strip():
|
||||||
|
return "Error: Please provide a valid trading pair (e.g., 'BTC-USDT')"
|
||||||
|
|
||||||
|
# Normalize symbol format
|
||||||
|
symbol = symbol.upper().strip()
|
||||||
|
if not symbol.endswith("-USDT"):
|
||||||
|
symbol = f"{symbol}-USDT"
|
||||||
|
|
||||||
|
# OKX API endpoint for ticker information
|
||||||
|
url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}"
|
||||||
|
|
||||||
|
# Make the API request with timeout
|
||||||
|
response = requests.get(url, timeout=10)
|
||||||
|
response.raise_for_status()
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
# Check API response status
|
||||||
|
if data.get("code") != "0":
|
||||||
|
return f"Error: {data.get('msg', 'Unknown error from OKX API')}"
|
||||||
|
|
||||||
|
# Extract ticker data
|
||||||
|
ticker_data = data.get("data", [{}])[0]
|
||||||
|
if not ticker_data:
|
||||||
|
return f"Error: Could not find data for {symbol}. Please verify the trading pair exists."
|
||||||
|
|
||||||
|
# Parse numerical data
|
||||||
|
price = float(ticker_data.get("last", 0))
|
||||||
|
change_percent = float(ticker_data.get("change24h", 0)) * 100 # Convert to percentage
|
||||||
|
|
||||||
|
# Format response
|
||||||
|
base_currency = symbol.split("-")[0]
|
||||||
|
change_symbol = "+" if change_percent >= 0 else ""
|
||||||
|
|
||||||
|
return (f"Current price of {base_currency}/USDT: ${price:,.2f}\n"
|
||||||
|
f"24h Change: {change_symbol}{change_percent:.2f}%")
|
||||||
|
|
||||||
|
except requests.exceptions.Timeout:
|
||||||
|
return "Error: Request timed out. OKX servers may be slow."
|
||||||
|
except requests.exceptions.RequestException as e:
|
||||||
|
return f"Error fetching OKX data: {str(e)}"
|
||||||
|
except (ValueError, KeyError) as e:
|
||||||
|
return f"Error parsing OKX response: {str(e)}"
|
||||||
|
except Exception as e:
|
||||||
|
return f"Unexpected error: {str(e)}"
|
||||||
|
|
||||||
|
|
||||||
|
@mcp.tool(
|
||||||
|
name="get_okx_crypto_volume", # Second tool with different functionality
|
||||||
|
description="Get the 24-hour trading volume for a given cryptocurrency from OKX exchange.",
|
||||||
|
)
|
||||||
|
def get_okx_crypto_volume(symbol: str) -> str:
|
||||||
|
"""
|
||||||
|
Get the 24-hour trading volume for a given cryptocurrency using OKX API.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
symbol (str): The cryptocurrency trading pair
|
||||||
|
Format: 'BASE-QUOTE' (e.g., 'BTC-USDT', 'ETH-USDT')
|
||||||
|
If only base currency provided, '-USDT' will be appended
|
||||||
|
Case-insensitive input
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: A formatted string containing:
|
||||||
|
- 24-hour trading volume in the base currency
|
||||||
|
- Volume formatted with thousand separators
|
||||||
|
- Currency symbol for clarity
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
requests.RequestException: If the OKX API request fails
|
||||||
|
ValueError: If symbol format is invalid
|
||||||
|
|
||||||
|
Example:
|
||||||
|
>>> get_okx_crypto_volume('BTC-USDT')
|
||||||
|
'24h Trading Volume for BTC/USDT: 12,345.67 BTC'
|
||||||
|
|
||||||
|
>>> get_okx_crypto_volume('ethereum') # Converts to ETH-USDT
|
||||||
|
'24h Trading Volume for ETH/USDT: 98,765.43 ETH'
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
# Input validation and formatting
|
||||||
|
if not symbol or not symbol.strip():
|
||||||
|
return "Error: Please provide a valid trading pair (e.g., 'BTC-USDT')"
|
||||||
|
|
||||||
|
# Normalize symbol format
|
||||||
|
symbol = symbol.upper().strip()
|
||||||
|
if not symbol.endswith("-USDT"):
|
||||||
|
symbol = f"{symbol}-USDT"
|
||||||
|
|
||||||
|
# OKX API endpoint
|
||||||
|
url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}"
|
||||||
|
|
||||||
|
# Make API request
|
||||||
|
response = requests.get(url, timeout=10)
|
||||||
|
response.raise_for_status()
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
# Validate API response
|
||||||
|
if data.get("code") != "0":
|
||||||
|
return f"Error: {data.get('msg', 'Unknown error from OKX API')}"
|
||||||
|
|
||||||
|
ticker_data = data.get("data", [{}])[0]
|
||||||
|
if not ticker_data:
|
||||||
|
return f"Error: Could not find data for {symbol}. Please verify the trading pair."
|
||||||
|
|
||||||
|
# Extract volume data
|
||||||
|
volume_24h = float(ticker_data.get("vol24h", 0))
|
||||||
|
base_currency = symbol.split("-")[0]
|
||||||
|
|
||||||
|
return f"24h Trading Volume for {base_currency}/USDT: {volume_24h:,.2f} {base_currency}"
|
||||||
|
|
||||||
|
except requests.exceptions.RequestException as e:
|
||||||
|
return f"Error fetching OKX data: {str(e)}"
|
||||||
|
except Exception as e:
|
||||||
|
return f"Error: {str(e)}"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Start Your MCP Server
|
||||||
|
|
||||||
|
```python
|
||||||
|
if __name__ == "__main__":
|
||||||
|
# Run the MCP server with SSE (Server-Sent Events) transport
|
||||||
|
# Server will be available at http://localhost:8001/sse
|
||||||
|
mcp.run(transport="sse")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Connect Agent to MCP Server
|
||||||
|
|
||||||
|
```python
|
||||||
|
from swarms import Agent
|
||||||
|
|
||||||
|
# Method 2: Using direct URL (simpler for development)
|
||||||
|
mcp_url = "http://0.0.0.0:8001/sse"
|
||||||
|
|
||||||
|
# Initialize agent with MCP tools
|
||||||
|
agent = Agent(
|
||||||
|
agent_name="Financial-Analysis-Agent", # Agent identifier
|
||||||
|
agent_description="Personal finance advisor with OKX exchange data access",
|
||||||
|
system_prompt="""You are a financial analysis agent with access to real-time
|
||||||
|
cryptocurrency data from OKX exchange. You can check prices, analyze trading volumes,
|
||||||
|
and provide market insights. Always format numerical data clearly and explain
|
||||||
|
market movements in context.""",
|
||||||
|
max_loops=1, # Processing loops
|
||||||
|
mcp_url=mcp_url, # MCP server connection
|
||||||
|
output_type="all", # Complete response format
|
||||||
|
# Note: tools are automatically loaded from MCP server
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Use Your MCP-Enabled Agent
|
||||||
|
|
||||||
|
```python
|
||||||
|
# The agent automatically discovers and uses tools from the MCP server
|
||||||
|
response = agent.run(
|
||||||
|
"Fetch the price for Bitcoin using the OKX exchange and also get its trading volume"
|
||||||
|
)
|
||||||
|
print(response)
|
||||||
|
|
||||||
|
# Multiple tool usage
|
||||||
|
response = agent.run(
|
||||||
|
"Compare the prices of BTC, ETH, and ADA on OKX, and show their trading volumes"
|
||||||
|
)
|
||||||
|
print(response)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Function Design
|
||||||
|
|
||||||
|
| Practice | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Type Hints | Always use type hints for all parameters and return values |
|
||||||
|
| Docstrings | Write comprehensive docstrings with Args, Returns, Raises, and Examples |
|
||||||
|
| Error Handling | Implement proper error handling with specific exception types |
|
||||||
|
| Input Validation | Validate input parameters before processing |
|
||||||
|
| Data Structure | Return structured data (preferably JSON) for consistency |
|
||||||
|
|
||||||
|
### MCP Server Development
|
||||||
|
|
||||||
|
| Practice | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Tool Naming | Use descriptive tool names that clearly indicate functionality |
|
||||||
|
| Timeouts | Set appropriate timeouts for external API calls |
|
||||||
|
| Error Handling | Implement graceful error handling for network issues |
|
||||||
|
| Configuration | Use environment variables for sensitive configuration |
|
||||||
|
| Testing | Test tools independently before integration |
|
||||||
|
|
||||||
|
### Agent Configuration
|
||||||
|
|
||||||
|
| Practice | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Loop Control | Choose appropriate max_loops based on task complexity |
|
||||||
|
| Token Management | Set reasonable token limits to control response length |
|
||||||
|
| System Prompts | Write clear system prompts that explain tool capabilities |
|
||||||
|
| Agent Naming | Use meaningful agent names for debugging and logging |
|
||||||
|
| Tool Integration | Consider tool combinations for comprehensive functionality |
|
||||||
|
|
||||||
|
### Performance Optimization
|
||||||
|
|
||||||
|
| Practice | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Data Caching | Cache frequently requested data when possible |
|
||||||
|
| Connection Management | Use connection pooling for multiple API calls |
|
||||||
|
| Rate Control | Implement rate limiting to respect API constraints |
|
||||||
|
| Performance Monitoring | Monitor tool execution times and optimize slow operations |
|
||||||
|
| Async Operations | Use async operations for concurrent tool execution when supported |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
|
||||||
|
#### Tool Not Found
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Ensure function is in tools list
|
||||||
|
agent = Agent(
|
||||||
|
# ... other config ...
|
||||||
|
tools=[your_function_name], # Function object, not string
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### MCP Connection Failed
|
||||||
|
```python
|
||||||
|
# Check server status and URL
|
||||||
|
import requests
|
||||||
|
response = requests.get("http://localhost:8001/health") # Health check endpoint
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Type Hint Errors
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Always specify return types
|
||||||
|
def my_tool(param: str) -> str: # Not just -> None
|
||||||
|
return "result"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### JSON Parsing Issues
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Always return valid JSON strings
|
||||||
|
import json
|
||||||
|
return json.dumps({"result": data}, indent=2)
|
||||||
|
```
|
||||||
@ -1,204 +0,0 @@
|
|||||||
# CreateNow API Documentation
|
|
||||||
|
|
||||||
Welcome to the CreateNow API documentation! This API enables developers to generate AI-powered content, including images, music, videos, and speech, using natural language prompts. Use the endpoints below to start generating content.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **1. Claim Your API Key**
|
|
||||||
To use the API, you must first claim your API key. Visit the following link to create an account and get your API key:
|
|
||||||
|
|
||||||
### **Claim Your Key**
|
|
||||||
```
|
|
||||||
https://createnow.xyz/account
|
|
||||||
```
|
|
||||||
|
|
||||||
After signing up, your API key will be available in your account dashboard. Keep it secure and include it in your API requests as a Bearer token.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **2. Generation Endpoint**
|
|
||||||
The generation endpoint allows you to create AI-generated content using natural language prompts.
|
|
||||||
|
|
||||||
### **Endpoint**
|
|
||||||
```
|
|
||||||
POST https://createnow.xyz/api/v1/generate
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Authentication**
|
|
||||||
Include a Bearer token in the `Authorization` header for all requests:
|
|
||||||
```
|
|
||||||
Authorization: Bearer YOUR_API_KEY
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Basic Usage**
|
|
||||||
The simplest way to use the API is to send a prompt. The system will automatically detect the appropriate media type.
|
|
||||||
|
|
||||||
#### **Example Request (Basic)**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"prompt": "a beautiful sunset over the ocean"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Advanced Options**
|
|
||||||
You can specify additional parameters for finer control over the output.
|
|
||||||
|
|
||||||
#### **Parameters**
|
|
||||||
| Parameter | Type | Description | Default |
|
|
||||||
|----------------|-----------|---------------------------------------------------------------------------------------------------|--------------|
|
|
||||||
| `prompt` | `string` | The natural language description of the content to generate. | Required |
|
|
||||||
| `type` | `string` | The type of content to generate (`image`, `music`, `video`, `speech`). | Auto-detect |
|
|
||||||
| `count` | `integer` | The number of outputs to generate (1-4). | 1 |
|
|
||||||
| `duration` | `integer` | Duration of audio or video content in seconds (applicable to `music` and `speech`). | N/A |
|
|
||||||
|
|
||||||
#### **Example Request (Advanced)**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"prompt": "create an upbeat jazz melody",
|
|
||||||
"type": "music",
|
|
||||||
"count": 2,
|
|
||||||
"duration": 30
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Response Format**
|
|
||||||
|
|
||||||
#### **Success Response**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"outputs": [
|
|
||||||
{
|
|
||||||
"url": "https://createnow.xyz/storage/image1.png",
|
|
||||||
"creation_id": "12345",
|
|
||||||
"share_url": "https://createnow.xyz/share/12345"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"mediaType": "image",
|
|
||||||
"confidence": 0.95,
|
|
||||||
"detected": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **Error Response**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"error": "Invalid API Key",
|
|
||||||
"status": 401
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **3. Examples in Multiple Languages**
|
|
||||||
|
|
||||||
### **Python**
|
|
||||||
```python
|
|
||||||
import requests
|
|
||||||
|
|
||||||
url = "https://createnow.xyz/api/v1/generate"
|
|
||||||
headers = {
|
|
||||||
"Authorization": "Bearer YOUR_API_KEY",
|
|
||||||
"Content-Type": "application/json"
|
|
||||||
}
|
|
||||||
|
|
||||||
payload = {
|
|
||||||
"prompt": "a futuristic cityscape at night",
|
|
||||||
"type": "image",
|
|
||||||
"count": 2
|
|
||||||
}
|
|
||||||
|
|
||||||
response = requests.post(url, json=payload, headers=headers)
|
|
||||||
print(response.json())
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Node.js**
|
|
||||||
```javascript
|
|
||||||
const axios = require('axios');
|
|
||||||
|
|
||||||
const url = "https://createnow.xyz/api/v1/generate";
|
|
||||||
const headers = {
|
|
||||||
Authorization: "Bearer YOUR_API_KEY",
|
|
||||||
"Content-Type": "application/json"
|
|
||||||
};
|
|
||||||
|
|
||||||
const payload = {
|
|
||||||
prompt: "a futuristic cityscape at night",
|
|
||||||
type: "image",
|
|
||||||
count: 2
|
|
||||||
};
|
|
||||||
|
|
||||||
axios.post(url, payload, { headers })
|
|
||||||
.then(response => {
|
|
||||||
console.log(response.data);
|
|
||||||
})
|
|
||||||
.catch(error => {
|
|
||||||
console.error(error.response.data);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### **cURL**
|
|
||||||
```bash
|
|
||||||
curl -X POST https://createnow.xyz/api/v1/generate \
|
|
||||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"prompt": "a futuristic cityscape at night",
|
|
||||||
"type": "image",
|
|
||||||
"count": 2
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Java**
|
|
||||||
```java
|
|
||||||
import java.net.HttpURLConnection;
|
|
||||||
import java.net.URL;
|
|
||||||
import java.io.OutputStream;
|
|
||||||
|
|
||||||
public class CreateNowAPI {
|
|
||||||
public static void main(String[] args) throws Exception {
|
|
||||||
URL url = new URL("https://createnow.xyz/api/v1/generate");
|
|
||||||
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
|
|
||||||
conn.setRequestMethod("POST");
|
|
||||||
conn.setRequestProperty("Authorization", "Bearer YOUR_API_KEY");
|
|
||||||
conn.setRequestProperty("Content-Type", "application/json");
|
|
||||||
conn.setDoOutput(true);
|
|
||||||
|
|
||||||
String jsonPayload = "{" +
|
|
||||||
"\"prompt\": \"a futuristic cityscape at night\", " +
|
|
||||||
"\"type\": \"image\", " +
|
|
||||||
"\"count\": 2}";
|
|
||||||
|
|
||||||
OutputStream os = conn.getOutputStream();
|
|
||||||
os.write(jsonPayload.getBytes());
|
|
||||||
os.flush();
|
|
||||||
|
|
||||||
int responseCode = conn.getResponseCode();
|
|
||||||
System.out.println("Response Code: " + responseCode);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **4. Error Codes**
|
|
||||||
| Status Code | Meaning | Possible Causes |
|
|
||||||
|-------------|----------------------------------|----------------------------------------|
|
|
||||||
| 400 | Bad Request | Invalid parameters or payload. |
|
|
||||||
| 401 | Unauthorized | Invalid or missing API key. |
|
|
||||||
| 402 | Payment Required | Insufficient credits for the request. |
|
|
||||||
| 500 | Internal Server Error | Issue on the server side. |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **5. Notes and Limitations**
|
|
||||||
- **Maximum Prompt Length:** 1000 characters.
|
|
||||||
- **Maximum Outputs per Request:** 4.
|
|
||||||
- **Supported Media Types:** `image`, `music`, `video`, `speech`.
|
|
||||||
- **Content Shareability:** Every output includes a unique creation ID and shareable URL.
|
|
||||||
- **Auto-Detection:** Uses advanced natural language processing to determine the most appropriate media type.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
For further support or questions, please contact our support team at [support@createnow.xyz](mailto:support@createnow.xyz).
|
|
||||||
|
|
||||||
@ -1,20 +1,106 @@
|
|||||||
import subprocess
|
from litellm import encode, model_list
|
||||||
|
from loguru import logger
|
||||||
|
from typing import Optional
|
||||||
|
from functools import lru_cache
|
||||||
|
|
||||||
|
# Use consistent default model
|
||||||
|
DEFAULT_MODEL = "gpt-4o-mini"
|
||||||
|
|
||||||
def count_tokens(text: str, model: str = "gpt-4o") -> int:
|
|
||||||
"""Count the number of tokens in the given text."""
|
def count_tokens(
|
||||||
|
text: str,
|
||||||
|
model: str = DEFAULT_MODEL,
|
||||||
|
default_encoder: Optional[str] = DEFAULT_MODEL,
|
||||||
|
) -> int:
|
||||||
|
"""
|
||||||
|
Count the number of tokens in the given text using the specified model.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
text: The text to tokenize
|
||||||
|
model: The model to use for tokenization (defaults to gpt-4o-mini)
|
||||||
|
default_encoder: Fallback encoder if the primary model fails (defaults to DEFAULT_MODEL)
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
int: Number of tokens in the text
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
ValueError: If text is empty or if both primary and fallback models fail
|
||||||
|
"""
|
||||||
|
if not text or not text.strip():
|
||||||
|
logger.warning("Empty or whitespace-only text provided")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
# Set fallback encoder
|
||||||
|
fallback_model = default_encoder or DEFAULT_MODEL
|
||||||
|
|
||||||
|
# First attempt with the requested model
|
||||||
try:
|
try:
|
||||||
from litellm import encode
|
tokens = encode(model=model, text=text)
|
||||||
except ImportError:
|
return len(tokens)
|
||||||
import sys
|
|
||||||
|
|
||||||
subprocess.run(
|
except Exception as e:
|
||||||
[sys.executable, "-m", "pip", "install", "litellm"]
|
logger.warning(
|
||||||
|
f"Failed to tokenize with model '{model}': {e} using fallback model '{fallback_model}'"
|
||||||
)
|
)
|
||||||
from litellm import encode
|
|
||||||
|
|
||||||
return len(encode(model=model, text=text))
|
logger.info(f"Using fallback model '{fallback_model}'")
|
||||||
|
|
||||||
|
# Only try fallback if it's different from the original model
|
||||||
|
if fallback_model != model:
|
||||||
|
try:
|
||||||
|
logger.info(
|
||||||
|
f"Falling back to default encoder: {fallback_model}"
|
||||||
|
)
|
||||||
|
tokens = encode(model=fallback_model, text=text)
|
||||||
|
return len(tokens)
|
||||||
|
|
||||||
|
except Exception as fallback_error:
|
||||||
|
logger.error(
|
||||||
|
f"Fallback encoder '{fallback_model}' also failed: {fallback_error}"
|
||||||
|
)
|
||||||
|
raise ValueError(
|
||||||
|
f"Both primary model '{model}' and fallback '{fallback_model}' failed to tokenize text"
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
logger.error(
|
||||||
|
f"Primary model '{model}' failed and no different fallback available"
|
||||||
|
)
|
||||||
|
raise ValueError(
|
||||||
|
f"Model '{model}' failed to tokenize text: {e}"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@lru_cache(maxsize=100)
|
||||||
|
def get_supported_models() -> list:
|
||||||
|
"""Get list of supported models from litellm."""
|
||||||
|
try:
|
||||||
|
return model_list
|
||||||
|
except Exception as e:
|
||||||
|
logger.warning(f"Could not retrieve model list: {e}")
|
||||||
|
return []
|
||||||
|
|
||||||
|
|
||||||
# if __name__ == "__main__":
|
# if __name__ == "__main__":
|
||||||
# print(count_tokens("Hello, how are you?"))
|
# # Test with different scenarios
|
||||||
|
# test_text = "Hello, how are you?"
|
||||||
|
|
||||||
|
# # # Test with Claude model
|
||||||
|
# # try:
|
||||||
|
# # tokens = count_tokens(test_text, model="claude-3-5-sonnet-20240620")
|
||||||
|
# # print(f"Claude tokens: {tokens}")
|
||||||
|
# # except Exception as e:
|
||||||
|
# # print(f"Claude test failed: {e}")
|
||||||
|
|
||||||
|
# # # Test with default model
|
||||||
|
# # try:
|
||||||
|
# # tokens = count_tokens(test_text)
|
||||||
|
# # print(f"Default model tokens: {tokens}")
|
||||||
|
# # except Exception as e:
|
||||||
|
# # print(f"Default test failed: {e}")
|
||||||
|
|
||||||
|
# # Test with explicit fallback
|
||||||
|
# try:
|
||||||
|
# tokens = count_tokens(test_text, model="some-invalid-model", default_encoder="gpt-4o-mini")
|
||||||
|
# print(f"Fallback test tokens: {tokens}")
|
||||||
|
# except Exception as e:
|
||||||
|
# print(f"Fallback test failed: {e}")
|
||||||
|
|||||||
Loading…
Reference in new issue