Builtin Skills

Built-in Skills

The SDK includes ready-to-use skills for common tasks like datetime, math, web search, and more. Each skill adds specific capabilities to your agents.

Available Skills

datetime

Get current date and time information with timezone support. This is one of the most commonly used skills—callers often ask “what time is it?” or need scheduling help.

Functions:

• get_current_time - Get current time in a timezone
• get_current_date - Get today’s date

Requirements: pytz package (usually installed automatically)

Parameters:

Output format:

• Time: “The current time in America/New_York is 2:30 PM”
• Date: “Today’s date is November 25, 2024”

Common use cases:

• “What time is it?” / “What time is it in Tokyo?”
• “What’s today’s date?”
• Scheduling and appointment contexts
• Time zone conversions

Limitations:

• Requires valid timezone names (e.g., “America/New_York”, not “EST”)
• Doesn’t do time math or calculate durations
• Doesn’t handle historical dates

1
from signalwire_agents import AgentBase
2
3
4
class TimeAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="time-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("datetime", {
10
            "default_timezone": "America/New_York"
11
        })
12
13
        self.prompt_add_section(
14
            "Role",
15
            "You help users with date and time information."
16
        )

math

Perform mathematical calculations safely. The skill uses a secure expression evaluator that supports common operations without executing arbitrary code.

Functions:

• calculate - Evaluate mathematical expressions

Requirements: None

Parameters:

Supported operations:

• Basic: +, -, *, /, ** (power), % (modulo)
• Functions: sqrt, sin, cos, tan, log, abs, round
• Constants: pi, e
• Parentheses for grouping

Output format:

• “The result of 15 * 23 is 345”
• “The square root of 144 is 12”

Common use cases:

• “What’s 15 percent of 230?”
• “Calculate 45 times 67”
• “What’s the square root of 256?”
• Price calculations, tip calculations

Limitations:

• Limited to supported functions (no arbitrary Python)
• Large numbers may lose precision
• Can’t solve equations or do symbolic math

1
from signalwire_agents import AgentBase
2
3
4
class CalculatorAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="calculator")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("math")
10
11
        self.prompt_add_section(
12
            "Role",
13
            "You are a calculator that helps with math."
14
        )

web_search

Search the web using Google Custom Search API. Results are filtered for quality and summarized for voice delivery.

Functions:

• web_search - Search the web and return summarized results

Requirements:

• Google Custom Search API key (from Google Cloud Console)
• Search Engine ID (from Programmable Search Engine)

Setup:

1. Create a project in Google Cloud Console
2. Enable the Custom Search JSON API
3. Create an API key
4. Create a Programmable Search Engine at https://programmablesearchengine.google.com/
5. Get the Search Engine ID

Parameters:

Output format: Returns a summary of top results with titles, snippets, and URLs.

Common use cases:

• Current events and news queries
• Fact-checking and verification
• Looking up specific information
• Research assistance

Limitations:

• Requires paid Google API (free tier has limits)
• Results depend on search engine configuration
• May not work for very recent events (indexing delay)
• Quality varies with search terms

Multi-instance support: Yes - add multiple instances for different search engines (news, docs, etc.)

1
from signalwire_agents import AgentBase
2
3
4
class SearchAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="search-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("web_search", {
10
            "api_key": "YOUR_GOOGLE_API_KEY",
11
            "search_engine_id": "YOUR_SEARCH_ENGINE_ID",
12
            "num_results": 3
13
        })
14
15
        self.prompt_add_section(
16
            "Role",
17
            "You search the web to answer questions."
18
        )

wikipedia_search

Search Wikipedia for information. A free, no-API-key alternative to web search for factual queries.

Functions:

• search_wikipedia - Search and retrieve Wikipedia article summaries

Requirements: None (uses public Wikipedia API)

Parameters:

Output format: Returns article title and summary excerpt.

Common use cases:

• Factual questions (“Who was Marie Curie?”)
• Definitions and explanations
• Historical information
• General knowledge queries

Limitations:

• Only searches Wikipedia (not general web)
• May not have very recent information
• Content quality varies by article
• Not suitable for opinions or current events

1
from signalwire_agents import AgentBase
2
3
4
class WikiAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="wiki-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("wikipedia_search", {
10
            "sentences": 5  # More detailed summaries
11
        })
12
13
        self.prompt_add_section(
14
            "Role",
15
            "You look up information on Wikipedia to answer factual questions."
16
        )

weather_api

Get current weather information for locations worldwide. Commonly used for small talk, travel planning, and location-aware services.

Functions:

• get_weather - Get current weather conditions for a location

Requirements: WeatherAPI.com API key (free tier available)

Setup:

1. Sign up at https://www.weatherapi.com/
2. Get your API key from the dashboard
3. Free tier allows 1 million calls/month

Parameters:

Output format: “Weather in Seattle: 58°F (14°C), partly cloudy. Humidity: 72%. Wind: 8 mph.”

Common use cases:

• “What’s the weather in Chicago?”
• “Is it raining in London?”
• Travel and event planning
• Small talk and conversation starters

Limitations:

• Current conditions only (no forecast in basic skill)
• Location must be recognizable (city names, zip codes)
• Weather data may have slight delay
• API rate limits apply

1
from signalwire_agents import AgentBase
2
3
4
class WeatherAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="weather-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("weather_api", {
10
            "api_key": "YOUR_WEATHER_API_KEY"
11
        })
12
13
        self.prompt_add_section(
14
            "Role",
15
            "You provide weather information for any location."
16
        )

joke

Tell jokes to lighten the mood or entertain callers. Uses a curated joke database for clean, family-friendly humor.

Functions:

• tell_joke - Get a random joke

Requirements: None

Parameters:

Common use cases:

• Entertainment and engagement
• Breaking tension in conversations
• Waiting periods during processing
• Adding personality to your agent

Limitations:

• Limited joke database
• May repeat jokes in long conversations
• Humor is subjective

1
from signalwire_agents import AgentBase
2
3
4
class FunAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="fun-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("joke")
10
11
        self.prompt_add_section(
12
            "Role",
13
            "You are a fun assistant that tells jokes when asked."
14
        )

play_background_file

Play audio files in the background during calls. Audio plays while conversation continues, useful for hold music, ambient sound, or audio cues.

Functions:

• play_background_file - Start playing audio file
• stop_background_file - Stop currently playing audio

Requirements: None (audio file must be accessible via URL)

Parameters:

Supported formats: MP3, WAV, OGG

Common use cases:

• Hold music while processing
• Ambient sound for atmosphere
• Audio notifications or alerts
• Branding jingles

Limitations:

• Audio file must be publicly accessible
• Large files may have loading delay
• Background audio may interfere with speech recognition

1
from signalwire_agents import AgentBase
2
3
4
class MusicAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="music-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("play_background_file", {
10
            "audio_url": "https://example.com/hold-music.mp3",
11
            "volume": 0.3,  # Lower volume for background
12
            "loop": True
13
        })

swml_transfer

Transfer calls to another SWML endpoint.

Functions:

• transfer_to_swml - Transfer to SWML URL

Requirements: None

1
from signalwire_agents import AgentBase
2
3
4
class TransferAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="transfer-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("swml_transfer", {
10
            "swml_url": "https://your-server.com/other-agent",
11
            "description": "Transfer to specialist"
12
        })

datasphere

Search SignalWire DataSphere documents.

Functions:

• search_datasphere - Search uploaded documents

Requirements: DataSphere API credentials

1
from signalwire_agents import AgentBase
2
3
4
class KnowledgeAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="knowledge-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("datasphere", {
10
            "space_name": "your-space",
11
            "project_id": "YOUR_PROJECT_ID",
12
            "api_token": "YOUR_API_TOKEN"
13
        })

native_vector_search

Local vector search using .swsearch index files.

Functions:

• search_knowledge - Search local vector index

Requirements: Search extras installed (pip install "signalwire-agents[search]")

1
from signalwire_agents import AgentBase
2
3
4
class LocalSearchAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="local-search")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("native_vector_search", {
10
            "index_path": "/path/to/knowledge.swsearch",
11
            "tool_name": "search_docs"
12
        })

mcp_gateway

Connect to MCP (Model Context Protocol) servers via the MCP Gateway service. This skill dynamically creates SWAIG functions from MCP tools, enabling your agent to use any MCP-compatible tool.

Functions: Dynamically created based on connected MCP services

Requirements:

• MCP Gateway service running (see MCP Gateway)
• Gateway URL and authentication credentials

Parameters:

How it works:

1. Skill connects to gateway and discovers available tools
2. Each MCP tool becomes a SWAIG function (e.g., mcp_todo_add_todo)
3. Sessions persist per call_id, enabling stateful tools
4. Session automatically closes when call ends

Common use cases:

• Integrating existing MCP ecosystem tools
• Stateful operations that persist across a call
• Sandboxed tool execution
• Managing multiple tool services

Limitations:

• Requires running MCP Gateway service
• Adds network latency (gateway hop)
• Tools must be MCP-compatible

1
from signalwire_agents import AgentBase
2
3
4
class MCPAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="mcp-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
9
        self.add_skill("mcp_gateway", {
10
            "gateway_url": "http://localhost:8080",
11
            "auth_user": "admin",
12
            "auth_password": "secure-password",
13
            "services": [
14
                {"name": "todo", "tools": "*"},
15
                {"name": "calculator", "tools": ["add", "multiply"]}
16
            ]
17
        })
18
19
        self.prompt_add_section(
20
            "Role",
21
            "You help users manage tasks and perform calculations."
22
        )

For detailed setup and configuration, see MCP Gateway.

Skills Summary Table

* Requires MCP Gateway service, not external API