SW-AGENT-INIT(1)

NAME
sw-agent-init - create a new SignalWire AI agent project

SYNOPSIS
sw-agent-init [options]
sw-agent-init project_name [options]

DESCRIPTION
sw-agent-init is an interactive command-line tool for creating new SignalWire AI agent projects. It supports both local agent projects (FastAPI/uvicorn) and cloud function deployments (AWS Lambda, Google Cloud Functions, Azure Functions).

When run without arguments, the tool enters interactive mode and prompts for project configuration including platform selection. When given a project name, it runs in quick mode with sensible defaults (local platform by default).

For local projects, the generated project includes:

•   Agent module with sample SWAIG function

•   Main application entry point

•   Environment configuration (.env)

•   Test scaffolding with pytest

•   Optional web UI for browser-based testing

•   Debug webhook handlers

•   README documentation

ARGUMENTS

project_name
    Name of the project to create. If not provided, the tool enters interactive mode and prompts for a name.

OPTIONS

-h, --help
    Display help message and exit.

-p, --platform PLATFORM
    Target deployment platform. Valid values:

    •   local - Local agent with FastAPI/uvicorn server (default)

    •   aws - AWS Lambda function with API Gateway

    •   gcp - Google Cloud Function (Gen 2)

    •   azure - Azure Function

-r, --region REGION
    Cloud region for deployment (only for cloud platforms). Default regions:

    •   AWS: us-east-1

    •   GCP: us-central1

    •   Azure: eastus

--type TYPE
    Agent type to create (only for local platform). Valid values:

    •   basic - Minimal agent with example tool (default)

    •   full - Complete setup with debug webhooks, web UI, and all features

--no-venv
    Skip virtual environment creation (only for local platform). By default, a Python virtual environment is created in the project directory.

--dir DIRECTORY
    Parent directory for the project. The project will be created as a subdirectory. Default is the current directory.

INTERACTIVE MODE
When run without a project name, the tool prompts for:

  Project Configuration

•   Target platform - Local, AWS Lambda, GCP, or Azure

•   Project name - Name of the project directory

•   Project directory - Where to create the project

•   Region - Cloud region (for cloud platforms only)

•   Agent type - Basic or full setup (for local platform only)

  Feature Selection
The following features can be enabled or disabled:

•   Debug webhooks - Console output for real-time call data

•   Post-prompt summary - Call summary handling

•   Web UI - Browser-based agent testing interface

•   Example SWAIG tool - Sample get_info function

•   Test scaffolding - pytest-based tests

•   Basic authentication - Secure webhook endpoints

  Credentials
The tool checks for existing SignalWire credentials in environment variables:

•   SIGNALWIRE_SPACE_NAME

•   SIGNALWIRE_PROJECT_ID

•   SIGNALWIRE_TOKEN

If found, they are offered as defaults. Otherwise, you can enter them manually or skip and configure later.

PROJECT STRUCTURE
A generated project has the following structure:

    project_name/
    —— agents/
    |   —— __init__.py
    |   ∇a—— main_agent.py      # Agent implementation
    —— skills/
    |   ∇a—— __init__.py        # Custom skills
    —— tests/
    |   —— __init__.py
    |   ∇a—— test_agent.py      # Unit tests
    —— web/
    |   ∇a—— index.html         # Web UI (if enabled)
    —— .env                    # Environment config
    —— .env.example            # Example config
    —— .gitignore
    —— .venv/                  # Virtual environment
    —— app.py                  # Entry point
    —— README.md
    ∇a—— requirements.txt

GENERATED FILES

  agents/main_agent.py
The main agent class with:

•   Voice and language configuration

•   Prompt sections (role, guidelines)

•   Example SWAIG tool using the @tool decorator

•   Debug webhook configuration (if enabled)

•   Basic authentication support (if enabled)

  app.py
Application entry point that:

•   Loads environment variables from .env

•   Creates and configures the AgentServer

•   Registers webhook endpoints

•   Serves static files from web/ directory

•   Pretty-prints debug data to console

  .env
Environment configuration with:

•   SignalWire credentials

•   Server host and port

•   Basic auth credentials (auto-generated secure password)

•   Debug level settings

•   Public URL configuration

  tests/test_agent.py
Test suite that verifies:

•   Agent loads without errors

•   SWML structure is valid

•   SWAIG functions are defined correctly

•   Functions execute and return expected results

EXAMPLES

  Interactive Mode
Run without arguments for guided setup:

    sw-agent-init

  Quick Mode - Local
Create a basic local agent project:

    sw-agent-init myagent

Create a full-featured local project:

    sw-agent-init myagent --type full

Create without virtual environment:

    sw-agent-init myagent --no-venv

Create in a specific directory:

    sw-agent-init myagent --dir /opt/projects

  Quick Mode - Cloud Functions
Create an AWS Lambda project:

    sw-agent-init myagent -p aws

Create an AWS Lambda project in a specific region:

    sw-agent-init myagent -p aws -r us-west-2

Create a Google Cloud Function project:

    sw-agent-init myagent -p gcp

Create an Azure Function project:

    sw-agent-init myagent -p azure

  After Creation - Local
Start the agent:

    cd myagent
    source .venv/bin/activate
    python app.py

Run tests:

    cd myagent
    source .venv/bin/activate
    pytest tests/ -v

Test with swaig-test:

    swaig-test agents/main_agent.py --list-tools
    swaig-test agents/main_agent.py --exec get_info --topic "test"
    swaig-test agents/main_agent.py --dump-swml

  After Creation - Cloud Functions
Deploy to AWS Lambda:

    cd myagent

Deploy to Google Cloud:

    cd myagent

Deploy to Azure:

    cd myagent

AGENT TYPES

  Basic Agent
The basic agent type includes:

•   Minimal agent with single example tool

•   Basic prompt configuration

•   Test scaffolding

•   Simple app.py without extra features

  Full Agent
The full agent type includes everything in basic, plus:

•   Debug webhook endpoints (/debug, /post_prompt)

•   Pretty-printed console output for call events

•   Web UI for browser-based testing

•   Basic authentication for endpoints

•   Post-prompt summary configuration

•   Static file serving

ENVIRONMENT
The following environment variables affect credential defaults:

SIGNALWIRE_SPACE_NAME
    SignalWire space name. If set, used as default in interactive mode.

SIGNALWIRE_PROJECT_ID
    SignalWire project ID. If set, used as default in interactive mode.

SIGNALWIRE_TOKEN
    SignalWire API token. If set, used as default in interactive mode.

EXIT STATUS

0   Project created successfully.

1   An error occurred. Check stderr for details.

SEE ALSO
swaig-test(1), sw-search(1), pytest(1)

SignalWire AI Agents SDK documentation: https://github.com/signalwire/signalwire-agents

AUTHORS
SignalWire Team <info@signalwire.com>

COPYRIGHT
Copyright (c) 2025 SignalWire. Licensed under the MIT License.