This guide will walk through the basics of creating an AI Culinary Companion by integrating Spoonacular with a voice AI agent. Follow along in the Recipe AI Agent Github Repo
What is SWAIG?
SignalWire AI Gateway (SWAIG) allows voice AI agents to delegate tasks to your backend via HTTP POST. Think of it like CGI (Common Gateway Interface) - where a web server hands off execution to an external program using raw query strings or form-encoded data - but for AI agents.
Traditional AI function integration often looks like the Model Context Protocol (MCP): multiple services stitched together, lots of orchestration, and brittle webhook chains. It works, but it’s imperative and heavy.
The key difference? SWAIG allows you to incorporate external API calls into your AI agent conversation in real time - seamlessly, during natural voice conversations, without awkward pauses or "please hold" moments.
Why SWAIG + Agents SDK Changes Everything
Traditional voice AI architecture requires multiple services, webhook management, and complex orchestration. The SignalWire Agents SDK eliminates this complexity: the agent SDK allows you to set up these functions, set up a web server, and build complex AI agents (with POM), ALL IN A SINGLE PYTHON FILE!
Here's your complete voice AI system:
SWAIG 101: Understanding the Basics
Step 1: The @SWAIGFunction Decorator
The @SWAIGFunction decorator is your gateway to real-time API integration. Here's how our recipe agent example demonstrates the pattern:
Key Elements:
name: How the AI identifies the function
description: Tells the AI when to use this function
Parameters: Automatically parsed from voice input
Type hints: Enable automatic validation
Step 2: DataMaps for Declarative API Integration
The DataMap system handles API calls declaratively. Instead of imperative code with error handling, you describe what you want:
DataMap handles automatically:
HTTP request formatting
Parameter substitution (${variable} syntax)
JSON response parsing
Error handling and retries
Response transformation
Step 3: Understanding SWAIG Request Context
SWAIG requests include rich context: The function name (e.g., "search_movie"), Parsed arguments in the structured argument.parsed field, The full argument schema (argument_desc) to describe expected inputs, Session, caller, and project context so you can make smart decisions without additional lookups
This rich context enables powerful patterns like automatic authentication using caller ID.
Advanced SWAIG Patterns
Custom Logic with SwaigFunctionResult
For complex business logic beyond simple API calls, use custom SWAIG functions with the SwaigFunctionResult class:
SwaigFunctionResult enables:
Natural language responses for the AI to speak
Action data for conversation state management
Complex response orchestration
Error Handling and Graceful Degradation
Production SWAIG functions handle failures elegantly:
State Management Across Conversations
SWAIG functions can persist data across phone calls using the built-in state management:
Universal SWAIG Patterns
The beauty of SWAIG? This pattern works with ANY API. Swap out Spoonacular for:
E-commerce: Product searches and inventory checks
Travel: Flight prices and hotel availability
Finance: Stock quotes and account balances
Healthcare: Appointment scheduling and prescription refills
Real Estate: Property listings and market data
Customer Service: Account lookups and order status (using caller ID for automatic authentication)
Need authenticated APIs? SWAIG handles that too. The rich context includes caller information, so you can automatically authenticate users and access their personal data without asking them to recite account numbers over the phone.
Integrating with the Agents SDK
Setting Up Your Agent Foundation
The AgentBase class provides the foundation for creating AI-powered agents using the SignalWire AI Agent SDK. It extends the SignalWire Markup Language (SWML) Service class, inheriting all its SWML document creation and serving capabilities, while adding AI-specific functionality
Context-Aware Function Availability
Define which SWAIG functions are available in different conversation contexts:
SWAIG Best Practices
1. Function Design Principles
Single responsibility: Each SWAIG function should do one thing well
Clear descriptions: Help the AI understand when to call your function
Sensible defaults: Use optional parameters with reasonable defaults
Error handling: Always handle API failures gracefully
2. DataMap Optimization
3. State Management Strategy
Use session state for conversation-specific data
Use global state for shared/cached data
Implement state cleanup for expired data
Consider state size limits for performance
4. Voice-Optimized Responses
Production Deployment Guide
Environment Configuration
Set up your environment variables:
Automatic environment detection:
Local development: Starts web server
AWS Lambda: Configures as Lambda handler
Docker: Handles containerization
Cloud Functions: Adapts automatically
Testing Your SWAIG Functions
Test individual functions during development:
Common SWAIG Patterns and Examples
Pattern 1: Simple API Integration
Pattern 2: Multi-Step Business Logic
Pattern 3: Authenticated User Data
Troubleshooting Common Issues
DataMap Parameter Problems
Missing Error Handling
State Management Issues
Next Steps: Building Your SWAIG Application
1. Start with the Recipe Agent
Clone and explore the complete recipe agent implementation to understand all SWAIG patterns in context.
2. Study the Documentation
3. Explore More Examples
Flo's Flowers demo - AI with SMS/MMS integration
Complete guides showcase - Various SignalWire patterns
4. Build Your First Agent
Follow these steps to get your SWAIG agent running:
Step 1: Set Up Your Python Environment
Step 2: Get Your API Keys
Sign up for Spoonacular API (free tier available)
Get your SignalWire credentials from the SignalWire Dashboard
Set environment variables:
Step 3: Run Your Agent Server
Step 4: Expose Your Local Server. Install ngrok and expose your local server to the internet:
Copy the public URL (e.g., https://983f-93-41-16-193.ngro...)
Step 5: Configure Your Phone Number
Buy a phone number in SignalWire Dashboard
Create a new Resource → Script → SWML type
Set to "External URL" and input your ngrok URL
Test by calling your number!
Detailed setup instructions: Handle incoming calls from code
Welcome to SWAIG development—where enterprise voice AI becomes as simple as writing Python functions, and your biggest architectural decision is choosing meaningful function names.
Ready to dive deeper? The recipe agent demonstrates every pattern covered in this guide. Use it as your foundation for building sophisticated voice AI applications with SWAIG and the SignalWire Agents SDK.
