Native Functions

View as MarkdownOpen in Claude

What Are Native Functions?

Native functions run directly on SignalWire’s platform. Enable them to give the AI access to built-in capabilities without creating handlers.

Handler FunctionNative Function
You define handlerSignalWire provides
Runs on your serverRuns on SignalWire
Custom logicPre-built behavior

Available Native Functions:

  • web_search - Search the web
  • debug - Debug mode for testing

Enabling Native Functions

Enable native functions in the constructor. The syntax varies by language:

LanguageSyntax
PythonAgentBase(name="my-agent", native_functions=["web_search"])
TypeScriptnew AgentBase({ name: 'my-agent', nativeFunctions: ['web_search'] })
1from signalwire import AgentBase
2
3class MyAgent(AgentBase):
4 def __init__(self):
5 super().__init__(
6 name="my-agent",
7 native_functions=["web_search"] # Enable web search
8 )
9 self.add_language("English", "en-US", "rime.spore")

Web Search Function

Enable web search to let the AI autonomously search the web during conversations:

1class ResearchAgent(AgentBase):
2 def __init__(self):
3 super().__init__(
4 name="research-agent",
5 native_functions=["web_search"]
6 )
7 self.add_language("English", "en-US", "rime.spore")
8
9 self.prompt_add_section(
10 "Role",
11 "You are a research assistant. Search the web to answer questions."
12 )

How Web Search Works

When enabled, the AI can decide to search the web when it needs information to answer a question. The process is:

  1. AI decides to search: Based on the conversation, the AI determines a search is needed
  2. Query formulation: The AI creates a search query from the conversation context
  3. Search execution: SignalWire executes the search on the AI’s behalf
  4. Results processing: Search results are returned to the AI as context
  5. Response generation: The AI synthesizes the results into a spoken response

The caller doesn’t interact with search directly — the AI handles everything automatically.

What Web Search Returns

The AI receives search results including:

  • Page titles and snippets
  • URLs of matching pages
  • Relevant text excerpts

The AI then summarizes and presents this information conversationally. It doesn’t read URLs or raw HTML to the caller.

Web Search Limitations

No control over search behavior:

  • Cannot specify search engine (Google, Bing, etc.)
  • Cannot filter by domain or site
  • Cannot control result count
  • Cannot exclude specific sources

Content limitations:

  • Results may be outdated (search index lag)
  • Cannot access paywalled or login-required content
  • Cannot search private/internal sites
  • May not find very recent information

No result logging:

  • Search queries aren’t logged to your server
  • Cannot audit what was searched
  • Cannot cache results for reuse

Rate and cost:

  • Subject to SignalWire’s rate limits
  • May incur additional usage costs
  • Multiple searches per call add latency

Good use cases:

  • General knowledge questions (“What year was the Eiffel Tower built?”)
  • Current events (with freshness caveats)
  • Quick fact lookups during calls
  • Agents that need broad knowledge access

When to use alternatives instead:

NeedAlternative
Specific search engineweb_search skill with Google API
Domain-restricted searchCustom handler with filtered API
Result logging/auditingCustom handler with logging
Cached resultsCustom handler with caching layer
Internal/private contentCustom handler with your search backend

Guide the AI on when and how to use web search:

1self.prompt_add_section(
2 "Search Guidelines",
3 """
4 Use web search when:
5 - Asked about current events or recent information
6 - Need to verify facts you're uncertain about
7 - Question is outside your core knowledge
8
9 Don't search for:
10 - Information already in your prompt
11 - Customer-specific data (use account functions instead)
12 - Simple calculations or conversions
13 """
14)

Debug Function

Enable debug mode for development and testing:

1class DebugAgent(AgentBase):
2 def __init__(self):
3 super().__init__(
4 name="debug-agent",
5 native_functions=["debug"]
6 )
7 self.add_language("English", "en-US", "rime.spore")

What Debug Provides

The debug function exposes diagnostic information during calls:

  • Current conversation state
  • Function call history
  • Configuration details
  • Timing information

When to Use Debug

Use during development:

  • Testing conversation flows
  • Verifying function registration
  • Checking prompt configuration
  • Troubleshooting unexpected behavior

Don’t use in production:

  • Exposes internal details to callers
  • May reveal sensitive configuration
  • Adds unnecessary function to AI’s options
  • Remove before deploying to production

Call Transfers

For call transfers, use FunctionResult.connect() in a custom handler function - there is no native transfer function:

1from signalwire import AgentBase, FunctionResult
2
3class TransferAgent(AgentBase):
4 DEPARTMENTS = {
5 "sales": "+15551111111",
6 "support": "+15552222222",
7 "billing": "+15553333333"
8 }
9
10 def __init__(self):
11 super().__init__(name="transfer-agent")
12 self.add_language("English", "en-US", "rime.spore")
13
14 self.prompt_add_section(
15 "Role",
16 "You are a receptionist. Transfer callers to the appropriate department."
17 )
18
19 self.define_tool(
20 name="transfer_call",
21 description="Transfer the call to a department",
22 parameters={
23 "type": "object",
24 "properties": {
25 "department": {
26 "type": "string",
27 "description": "Department to transfer to",
28 "enum": ["sales", "support", "billing"]
29 }
30 },
31 "required": ["department"]
32 },
33 handler=self.transfer_call
34 )
35
36 def transfer_call(self, args, raw_data):
37 department = args.get("department")
38 number = self.DEPARTMENTS.get(department)
39
40 if not number:
41 return FunctionResult("Invalid department")
42
43 return (
44 FunctionResult(f"Transferring you to {department}")
45 .connect(number, final=True)
46 )

Combining Native and Custom Functions

The examples below use Python. The pattern of passing native_functions in the constructor and adding define_tool() calls works identically in all SDK languages using the syntax shown in the table above.

Use native functions alongside your custom handlers:

1from signalwire import AgentBase, FunctionResult
2
3class HybridAgent(AgentBase):
4 def __init__(self):
5 super().__init__(
6 name="hybrid-agent",
7 native_functions=["web_search"] # Native
8 )
9 self.add_language("English", "en-US", "rime.spore")
10
11 # Custom function alongside native ones
12 self.define_tool(
13 name="check_account",
14 description="Look up customer account information",
15 parameters={
16 "type": "object",
17 "properties": {
18 "account_id": {
19 "type": "string",
20 "description": "Account ID"
21 }
22 },
23 "required": ["account_id"]
24 },
25 handler=self.check_account
26 )
27
28 self.prompt_add_section(
29 "Role",
30 "You are a customer service agent. "
31 "You can check accounts and search the web for information."
32 )
33
34 def check_account(self, args, raw_data):
35 account_id = args.get("account_id")
36 return FunctionResult(f"Account {account_id} is active")

When to Use Native vs Custom Functions

ScenarioRecommendation
Web search capabilityUse web_search native function
Development testingUse debug native function
Transfer to phone numberUse FunctionResult.connect() in custom handler
Transfer to SIP addressUse FunctionResult.connect() in custom handler
Custom business logicUse define_tool() with handler
Database lookupsUse define_tool() with handler

Native Functions Reference

FunctionDescriptionUse Case
web_searchSearch the webAnswer general questions
debugDebug informationDevelopment/testing

Next Steps

You’ve now learned all about SWAIG functions. Next, explore Skills to add pre-built capabilities to your agents.