SignalWire AI Agents - Cloud Functions Deployment Guide

This guide covers deploying SignalWire AI Agents to Google Cloud Functions and Azure Functions.

Overview

SignalWire AI Agents now support deployment to major cloud function platforms:

Google Cloud Functions - Serverless compute platform on Google Cloud
Azure Functions - Serverless compute service on Microsoft Azure
AWS Lambda - Already supported (see existing documentation)

Google Cloud Functions

Environment Detection

The agent automatically detects Google Cloud Functions environment using these variables:

FUNCTION_TARGET - The function entry point
K_SERVICE - Knative service name (Cloud Run/Functions)
GOOGLE_CLOUD_PROJECT - Google Cloud project ID

Deployment Steps

Create your agent file (main.py):

import functions_framework
from your_agent_module import YourAgent

# Create agent instance
agent = YourAgent(
    name="my-agent",
    # Configure your agent parameters
)

@functions_framework.http
def agent_handler(request):
    """HTTP Cloud Function entry point"""
    return agent.handle_serverless_request(event=request)

Create requirements.txt:

functions-framework==3.*
signalwire-agents
# Add your other dependencies

Deploy using gcloud:

gcloud functions deploy my-agent \
    --runtime python39 \
    --trigger-http \
    --entry-point agent_handler \
    --allow-unauthenticated

Environment Variables

Set these environment variables for your function:

# SignalWire credentials
export SIGNALWIRE_PROJECT_ID="your-project-id"
export SIGNALWIRE_TOKEN="your-token"

# Agent configuration
export AGENT_USERNAME="your-username"
export AGENT_PASSWORD="your-password"

# Optional: Custom region/project settings
export FUNCTION_REGION="us-central1"
export GOOGLE_CLOUD_PROJECT="your-project-id"

URL Format

Google Cloud Functions URLs follow this pattern:

https://{region}-{project-id}.cloudfunctions.net/{function-name}

With authentication:

https://username:password@{region}-{project-id}.cloudfunctions.net/{function-name}

Azure Functions

Environment Detection

The agent automatically detects Azure Functions environment using these variables:

AZURE_FUNCTIONS_ENVIRONMENT - Azure Functions runtime environment
FUNCTIONS_WORKER_RUNTIME - Runtime language (python, node, etc.)
AzureWebJobsStorage - Azure storage connection string

Deployment Steps

Create your function app structure:

my-agent-function/
├── __init__.py
├── function.json
└── requirements.txt

Create __init__.py:

import azure.functions as func
from your_agent_module import YourAgent

# Create agent instance
agent = YourAgent(
    name="my-agent",
    # Configure your agent parameters
)

def main(req: func.HttpRequest) -> func.HttpResponse:
    """Azure Function entry point"""
    return agent.handle_serverless_request(event=req)

Create function.json:

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Create requirements.txt:

azure-functions
signalwire-agents
# Add your other dependencies

Deploy using Azure CLI:

# Create function app
az functionapp create \
    --resource-group myResourceGroup \
    --consumption-plan-location westus \
    --runtime python \
    --runtime-version 3.9 \
    --functions-version 4 \
    --name my-agent-function \
    --storage-account mystorageaccount

# Deploy code
func azure functionapp publish my-agent-function

Environment Variables

Set these in your Azure Function App settings:

# SignalWire credentials
SIGNALWIRE_PROJECT_ID="your-project-id"
SIGNALWIRE_TOKEN="your-token"

# Agent configuration
AGENT_USERNAME="your-username"
AGENT_PASSWORD="your-password"

# Azure-specific (usually auto-set)
AZURE_FUNCTIONS_ENVIRONMENT="Development"
WEBSITE_SITE_NAME="my-agent-function"

URL Format

Azure Functions URLs follow this pattern:

https://{function-app-name}.azurewebsites.net/api/{function-name}

With authentication:

https://username:password@{function-app-name}.azurewebsites.net/api/{function-name}

Authentication

Both platforms support HTTP Basic Authentication:

Automatic Authentication

The agent automatically validates credentials in cloud function environments:

agent = YourAgent(
    name="my-agent",
    username="your-username",
    password="your-password"
)

Authentication Flow

Client sends request with Authorization: Basic <credentials> header
Agent validates credentials against configured username/password
If invalid, returns 401 with WWW-Authenticate header
If valid, processes the request normally

Testing

SignalWire Agent Testing Tool

The SignalWire AI Agents SDK includes a powerful testing tool (swaig-test) that can simulate cloud function environments for comprehensive testing before deployment.

Cloud Function Environment Simulation

Google Cloud Functions:

# Test SWML generation in GCP environment
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project my-project --dump-swml

# Test function execution
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project my-project --exec my_function --param value

# With custom region and service
swaig-test examples/my_agent.py --simulate-serverless cloud_function \
  --gcp-project my-project \
  --gcp-region us-west1 \
  --gcp-service my-service \
  --dump-swml

Azure Functions:

# Test SWML generation in Azure environment
swaig-test examples/my_agent.py --simulate-serverless azure_function --dump-swml

# Test function execution
swaig-test examples/my_agent.py --simulate-serverless azure_function --exec my_function --param value

# With custom environment and URL
swaig-test examples/my_agent.py --simulate-serverless azure_function \
  --azure-env Production \
  --azure-function-url https://myapp.azurewebsites.net/api/myfunction \
  --dump-swml

Environment Variable Testing

Test with custom environment variables:

# Set individual environment variables
swaig-test examples/my_agent.py --simulate-serverless cloud_function \
  --env GOOGLE_CLOUD_PROJECT=my-project \
  --env DEBUG=1 \
  --exec my_function

# Load from environment file
swaig-test examples/my_agent.py --simulate-serverless azure_function \
  --env-file production.env \
  --dump-swml

Authentication Testing

Test authentication in cloud function environments:

# Test with authentication (uses agent's configured credentials)
swaig-test examples/my_agent.py --simulate-serverless cloud_function \
  --gcp-project my-project \
  --dump-swml --verbose

# The tool automatically tests:
# - Basic auth credential embedding in URLs
# - Authentication challenge responses
# - Platform-specific auth handling

URL Generation Testing

Verify that URLs are generated correctly for each platform:

# Check URL generation with verbose output
swaig-test examples/my_agent.py --simulate-serverless cloud_function \
  --gcp-project my-project \
  --dump-swml --verbose

# Extract webhook URLs from SWML
swaig-test examples/my_agent.py --simulate-serverless azure_function \
  --dump-swml --raw | jq '.sections.main[1].ai.SWAIG.functions[].web_hook_url'

Available Testing Options

Platform Selection:

--simulate-serverless cloud_function - Google Cloud Functions
--simulate-serverless azure_function - Azure Functions
--simulate-serverless lambda - AWS Lambda
--simulate-serverless cgi - CGI environment

Google Cloud Platform Options:

--gcp-project PROJECT_ID - Set Google Cloud project ID
--gcp-region REGION - Set Google Cloud region (default: us-central1)
--gcp-service SERVICE - Set service name
--gcp-function-url URL - Override function URL

Azure Functions Options:

--azure-env ENVIRONMENT - Set Azure environment (default: Development)
--azure-function-url URL - Override Azure Function URL

Environment Variables:

--env KEY=value - Set individual environment variables
--env-file FILE - Load environment variables from file

Output Options:

--dump-swml - Generate and display SWML document
--verbose - Show detailed information
--raw - Output raw JSON (useful for piping to jq)

Complete Testing Workflow

# 1. List available agents and tools
swaig-test examples/my_agent.py --list-agents
swaig-test examples/my_agent.py --list-tools

# 2. Test SWML generation for each platform
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project test-project --dump-swml
swaig-test examples/my_agent.py --simulate-serverless azure_function --dump-swml

# 3. Test specific function execution
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project test-project --exec search_knowledge --query "test"

# 4. Test with production-like environment
swaig-test examples/my_agent.py --simulate-serverless azure_function --env-file production.env --exec my_function --param value

# 5. Verify authentication and URL generation
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project prod-project --dump-swml --verbose

Local Testing

Google Cloud Functions:

# Install Functions Framework
pip install functions-framework

# Run locally
functions-framework --target=agent_handler --debug

Azure Functions:

# Install Azure Functions Core Tools
npm install -g azure-functions-core-tools@4

# Run locally
func start

Testing Authentication

# Test without auth (should return 401)
curl https://your-function-url/

# Test with valid auth
curl -u username:password https://your-function-url/

# Test SWAIG function call
curl -u username:password \
  -H "Content-Type: application/json" \
  -d '{"call_id": "test", "argument": {"parsed": [{"param": "value"}]}}' \
  https://your-function-url/your_function_name

Best Practices

Performance

Use connection pooling for database connections
Implement proper caching strategies
Minimize cold start times with smaller deployment packages

Security

Always use HTTPS endpoints
Implement proper authentication
Use environment variables for sensitive data
Consider using cloud-native secret management

Monitoring

Enable cloud platform logging
Monitor function execution times
Set up alerts for errors and timeouts
Use distributed tracing for complex workflows

Cost Optimization

Right-size memory allocation
Implement proper timeout settings
Use reserved capacity for predictable workloads
Monitor and optimize function execution patterns

Troubleshooting

Common Issues

Environment Detection:

# Check detected mode
from signalwire_agents.core.logging_config import get_execution_mode
print(f"Detected mode: {get_execution_mode()}")

URL Generation:

# Check generated URLs
agent = YourAgent(name="test")
print(f"Base URL: {agent.get_full_url()}")
print(f"Auth URL: {agent.get_full_url(include_auth=True)}")

Authentication Issues:

Verify username/password are set correctly
Check that Authorization header is being sent
Ensure credentials match exactly (case-sensitive)

Debugging

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Check environment variables:

import os
for key, value in os.environ.items():
    if 'FUNCTION' in key or 'AZURE' in key or 'GOOGLE' in key:
        print(f"{key}: {value}")

Migration from Other Platforms

From AWS Lambda

Update environment variable names
Modify request/response handling if needed
Update deployment scripts

From Traditional Servers

Add cloud function entry point
Configure environment variables
Update URL generation logic
Test authentication flow

Examples

See the examples/cloud_functions/ directory for complete working examples:

google_cloud_function_example/ - Complete Google Cloud Functions deployment
azure_function_example/ - Complete Azure Functions deployment
multi_platform_agent/ - Agent that works across all platforms

Support

For issues specific to cloud function deployment:

Check the troubleshooting section above
Verify environment variables are set correctly
Test authentication flow manually
Check cloud platform logs for detailed error messages
Refer to platform-specific documentation for deployment issues

Overview​

Google Cloud Functions​

Environment Detection​

Deployment Steps​

Environment Variables​

URL Format​

Azure Functions​

Environment Detection​

Deployment Steps​

Environment Variables​

URL Format​

Authentication​

Automatic Authentication​

Authentication Flow​

Testing​

SignalWire Agent Testing Tool​

Cloud Function Environment Simulation​

Environment Variable Testing​

Authentication Testing​

URL Generation Testing​

Available Testing Options​

Complete Testing Workflow​

Local Testing​

Testing Authentication​

Best Practices​

Performance​

Security​

Monitoring​

Cost Optimization​

Troubleshooting​

Common Issues​

Debugging​

Migration from Other Platforms​

From AWS Lambda​

From Traditional Servers​

Examples​

Support​

Overview

Google Cloud Functions

Environment Detection

Deployment Steps

Environment Variables

URL Format

Azure Functions

Environment Detection

Deployment Steps

Environment Variables

URL Format

Authentication

Automatic Authentication

Authentication Flow

Testing

SignalWire Agent Testing Tool

Cloud Function Environment Simulation

Environment Variable Testing

Authentication Testing

URL Generation Testing

Available Testing Options

Complete Testing Workflow

Local Testing

Testing Authentication

Best Practices

Performance

Security

Monitoring

Cost Optimization

Troubleshooting

Common Issues

Debugging

Migration from Other Platforms

From AWS Lambda

From Traditional Servers

Examples

Support