SignalWire AI Agents SDK - LLM Discovery Guide

This file provides a comprehensive guide for LLM coding agents to understand the SignalWire AI Agents SDK structure, key files, and concepts.

Quick Discovery Path

To understand this SDK, read these files in order:

1. Start with the Main README

2. Core Documentation Files

3. Advanced Documentation

4. Search System Documentation

5. Core Python Code

6. Skills System

7. Prefab Agents

8. Examples

9. CLI Tools

SDK Architecture Overview

SignalWire AI Agents SDK
├── Core Framework
│   ├── SWMLService (Base HTTP service + SWML generation)
│   ├── AgentBase (AI agent functionality + cloud function support)
│   └── Custom Agents (User implementations)
├── Skills System (Modular capabilities)
├── DataMap Tools (Serverless API integration)
├── Contexts & Steps (Structured workflows)
├── Prefab Agents (Ready-to-use types)
├── Search System (Local document search)
├── Cloud Function Support (Google Cloud, Azure, AWS Lambda)
└── CLI Tools (Development & testing with serverless simulation)

Key Concepts

1. AgentBase Class

2. Skills System

3. DataMap Tools

4. Contexts and Steps

5. State Management

6. Search System

7. Cloud Function Support

File Structure Guide

signalwire-agents/
├── README.md                          # Main documentation (START HERE)
├── signalwire_agents/                 # Main Python package
│   ├── __init__.py                    # Public API exports
│   ├── core/                          # Core framework
│   │   ├── agent_base.py              # Main AgentBase class (3810 lines)
│   │   ├── swml_service.py            # Base SWML service
│   │   ├── function_result.py         # SWAIG function results
│   │   ├── data_map.py                # DataMap serverless tools
│   │   ├── contexts.py                # Contexts and Steps system
│   │   ├── skill_manager.py           # Skills management
│   │   ├── logging_config.py          # Centralized logging
│   │   └── state/                     # State management
│   ├── skills/                        # Modular skills system
│   │   ├── README.md                  # How to create skills
│   │   ├── datetime/                  # Date/time skill
│   │   ├── math/                      # Math skill
│   │   ├── web_search/                # Web search skill
│   │   └── native_vector_search/      # Local search skill
│   ├── prefabs/                       # Ready-to-use agents
│   │   ├── info_gatherer.py           # Information gathering
│   │   ├── survey.py                  # Survey agent
│   │   └── receptionist.py            # Receptionist agent
│   ├── search/                        # Local search system
│   └── cli/                           # Command-line tools
│       └── test_swaig.py              # Comprehensive testing tool (2655 lines)
├── docs/                              # Comprehensive documentation
│   ├── architecture.md                # SDK architecture
│   ├── agent_guide.md                 # Complete agent guide
│   ├── contexts_guide.md              # Contexts and Steps
│   ├── skills_system.md               # Skills system
│   ├── datamap_guide.md               # DataMap tools
│   ├── search-system.md               # Search system
│   ├── cli_testing_guide.md           # Testing tools
│   ├── cloud_functions_guide.md       # Cloud function deployment
│   ├── signalwire_agents_api_reference.md # Complete API reference
│   ├── signalwire_agents_concepts_guide.md # Deep concepts
│   ├── signalwire_ai_developer_guide.md # AI development
│   ├── swml_service_guide.md          # SWML service guide
│   ├── datamap_swml_complete_guide.md # Complete DataMap guide
│   ├── swaig_actions_reference.md     # SWAIG actions
│   ├── swaig_function_result_methods.md # Function results
│   ├── post_data_complete_reference.md # POST data reference
│   ├── search_installation.md         # Search installation
│   └── troubleshooting_search.md      # Search troubleshooting
└── examples/                          # Practical examples
    ├── simple_static_agent.py         # Basic agent
    ├── skills_demo.py                 # Skills demonstration
    ├── contexts_demo.py               # Contexts example
    └── comprehensive_dynamic_agent.py # Advanced features

Installation and Dependencies

Basic Installation

pip install signalwire-agents

With Search Capabilities

# Basic search (~500MB)
pip install signalwire-agents[search]

# Full document processing (~600MB)
pip install signalwire-agents[search-full]

# Advanced NLP features (~700MB)
pip install signalwire-agents[search-nlp]

# All search features (~700MB)
pip install signalwire-agents[search-all]

Quick Start Pattern

from signalwire_agents import AgentBase

class MyAgent(AgentBase):
    def __init__(self):
        super().__init__(name="my-agent", route="/agent")

        # Add skills (one-liners)
        self.add_skill("datetime")
        self.add_skill("math")

        # Configure prompt
        self.prompt_add_section("Role", "You are a helpful assistant")

        # Custom tool
        @AgentBase.tool(name="custom_tool", description="Custom functionality")
        def my_tool(self, args, raw_data):
            return SwaigFunctionResult("Tool response")

# Run the agent (auto-detects environment)
if __name__ == "__main__":
    agent = MyAgent()
    agent.run()  # Works in server/CGI/Lambda/Cloud Functions/etc.

CLI Tools

Testing Tool (swaig-test)

# Test agent functions locally
swaig-test examples/my_agent.py --list-tools
swaig-test examples/my_agent.py --exec function_name --param value
swaig-test examples/my_agent.py --dump-swml

# Serverless simulation
swaig-test examples/my_agent.py --simulate-serverless lambda --dump-swml
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project my-project --dump-swml
swaig-test examples/my_agent.py --simulate-serverless azure_function --dump-swml
swaig-test examples/my_agent.py --simulate-serverless cgi --cgi-host example.com --dump-swml

# Environment variable testing
swaig-test examples/my_agent.py --simulate-serverless lambda --env API_KEY=secret --exec my_function
swaig-test examples/my_agent.py --simulate-serverless cloud_function --env-file production.env --dump-swml

# Authentication and URL testing
swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project prod --dump-swml --verbose

Search Index Builder

# Build search index
sw-search docs/ --output knowledge.swsearch
sw-search README.md docs/agent_guide.md --output specific.swsearch

Key Design Patterns

1. Agent Creation

2. Skills Integration

3. Custom Tools

4. Dynamic Configuration

5. Structured Workflows

6. Multi-Platform Deployment

Environment Variables

# Authentication
SWML_BASIC_AUTH_USER=username
SWML_BASIC_AUTH_PASSWORD=password

# SSL/HTTPS
SWML_SSL_ENABLED=true
SWML_SSL_CERT_PATH=/path/to/cert.pem
SWML_SSL_KEY_PATH=/path/to/key.pem
SWML_DOMAIN=yourdomain.com

# Proxy support
SWML_PROXY_URL_BASE=https://your-proxy.com

# Skills (example for web_search)
GOOGLE_SEARCH_API_KEY=your_api_key
GOOGLE_SEARCH_ENGINE_ID=your_engine_id

# Cloud Functions (auto-detected)
# Google Cloud Functions
GOOGLE_CLOUD_PROJECT=my-project
FUNCTION_TARGET=my_function
K_SERVICE=my-service
GOOGLE_CLOUD_REGION=us-central1

# Azure Functions
AZURE_FUNCTIONS_ENVIRONMENT=Development
FUNCTIONS_WORKER_RUNTIME=python
WEBSITE_SITE_NAME=my-function-app

# AWS Lambda
AWS_LAMBDA_FUNCTION_NAME=my-function
AWS_LAMBDA_FUNCTION_URL=https://abc123.lambda-url.us-east-1.on.aws
AWS_REGION=us-east-1

# Logging control
SIGNALWIRE_LOG_MODE=off|stderr|default|auto
SIGNALWIRE_LOG_LEVEL=debug|info|warning|error|critical

Deployment Modes

The SDK automatically detects and configures for:

  1. HTTP Server - Direct FastAPI server (python agent.py)
  2. CGI - Traditional web server CGI
  3. AWS Lambda - Serverless functions
  4. Google Cloud Functions - Cloud serverless (NEW)
  5. Azure Functions - Microsoft serverless (NEW)

Cloud Function Features

Testing Strategy

  1. Local Development: Use swaig-test CLI tool with comprehensive options
  2. Function Testing: Test individual SWAIG functions with CLI arguments
  3. SWML Generation: Test document generation with --dump-swml
  4. Serverless Simulation: Test all deployment environments (Lambda, GCP, Azure, CGI)
  5. Environment Testing: Test with custom environment variables and files
  6. Authentication Testing: Verify auth works across all platforms
  7. URL Generation Testing: Verify webhook URLs are correct for each platform
  8. Integration Testing: Test with real SignalWire platform

Common Use Cases

  1. Customer Service: Multi-context routing with function restrictions
  2. Information Gathering: Structured data collection workflows
  3. Knowledge Base: Search-enabled Q&A agents
  4. Survey/Forms: Step-by-step data collection
  5. Technical Support: Troubleshooting workflows with tool access
  6. Cloud Deployment: Serverless agents on Google Cloud, Azure, or AWS
  7. Hybrid Deployment: Same agent code across multiple platforms

Recent Major Additions

Cloud Function Support

Enhanced Testing

Documentation Expansion

Authentication Improvements

Next Steps for LLM Agents

  1. Read README.md for overview
  2. Study docs/architecture.md for design understanding
  3. Examine signalwire_agents/core/agent_base.py for implementation
  4. Review examples in examples/ directory
  5. Understand skills system via signalwire_agents/skills/
  6. Test with swaig-test CLI tool (including cloud function simulation)
  7. Review cloud deployment options in docs/cloud_functions_guide.md
  8. Study complete API reference in docs/signalwire_agents_api_reference.md

This guide provides the roadmap to fully understand the SignalWire AI Agents SDK architecture, capabilities, and implementation patterns, including the latest cloud function support and enhanced testing capabilities.