Installation

Install the SignalWire Agents SDK using pip and verify everything works correctly.

System Requirements

Requirement	Minimum	Recommended
Python	3.8+	3.10+
pip	20.0+	Latest
OS	Linux, macOS, Windows	Any
Memory	512MB	1GB+

Basic Installation

Install the SDK from PyPI:

$ pip install signalwire-agents

This installs the core SDK with all essential features for building voice AI agents.

Verify Installation

Confirm the installation was successful:

$ python -c "from signalwire_agents import AgentBase; print('SignalWire Agents SDK installed successfully!')"

You should see:

SignalWire Agents SDK installed successfully!

Installation Extras

The SDK provides optional extras for additional features:

Search Capabilities

$ ## Query-only (read .swsearch files) - ~400MB
$ pip install "signalwire-agents[search-queryonly]"
$ 
$ ## Build indexes + vector search - ~500MB
$ pip install "signalwire-agents[search]"
$ 
$ ## Full document processing (PDF, DOCX) - ~600MB
$ pip install "signalwire-agents[search-full]"
$ 
$ ## NLP features (spaCy) - ~600MB
$ pip install "signalwire-agents[search-nlp]"
$ 
$ ## All search features - ~700MB
$ pip install "signalwire-agents[search-all]"

Database Support

$ ## PostgreSQL vector database support
$ pip install "signalwire-agents[pgvector]"

Development Dependencies

$ ## All development tools (testing, linting)
$ pip install "signalwire-agents[dev]"

Installation from Source

For development or to get the latest changes:

$ ## Clone the repository
$ git clone https://github.com/signalwire/signalwire-agents.git
$ cd signalwire-agents
$ 
$ ## Create virtual environment
$ python -m venv venv
$ source venv/bin/activate  # On Windows: venv\Scripts\activate
$ 
$ ## Install in development mode
$ pip install -e .
$ 
$ ## Or with extras
$ pip install -e ".[search,dev]"

Virtual Environment Setup

Always use a virtual environment to avoid conflicts:

$ ## Create virtual environment
$ python -m venv venv
$ 
$ ## Activate (Linux/macOS)
$ source venv/bin/activate
$ 
$ ## Activate (Windows Command Prompt)
$ venv\Scripts\activate
$ 
$ ## Activate (Windows PowerShell)
$ venv\Scripts\Activate.ps1
$ 
$ ## Install the SDK
$ pip install signalwire-agents
$ 
$ ## Verify activation (should show venv path)
$ which python

Quick Verification Script

1 #!/usr/bin/env python3
2 ## verify_install.py - Verify SignalWire Agents SDK installation
3 """Verify SignalWire Agents SDK installation."""
4 
5 def main():
6     print("Checking SignalWire Agents SDK installation...\n")
7 
8     # Check core import
9     try:
10         from signalwire_agents import AgentBase
11         print("[OK] Core SDK: AgentBase imported successfully")
12     except ImportError as e:
13         print(f"[FAIL] Core SDK: Failed to import AgentBase - {e}")
14         return False
15 
16     # Check SWAIG function support
17     try:
18         from signalwire_agents import SwaigFunctionResult
19         print("[OK] SWAIG: SwaigFunctionResult imported successfully")
20     except ImportError as e:
21         print(f"[FAIL] SWAIG: Failed to import SwaigFunctionResult - {e}")
22         return False
23 
24     # Check prefabs
25     try:
26         from signalwire_agents.prefabs import InfoGathererAgent
27         print("[OK] Prefabs: InfoGathererAgent imported successfully")
28     except ImportError as e:
29         print(f"[FAIL] Prefabs: Failed to import - {e}")
30 
31     # Check search (optional)
32     try:
33         from signalwire_agents.search import SearchEngine
34         print("[OK] Search: SearchEngine available")
35     except ImportError:
36         print("[SKIP] Search: Not installed (optional)")
37 
38     print("\n" + "="*50)
39     print("Installation verification complete!")
40     print("="*50)
41     return True
42 
43 
44 if __name__ == "__main__":
45     main()

Run it:

$ python verify_install.py

Expected output:

Checking SignalWire Agents SDK installation...
[OK] Core SDK: AgentBase imported successfully
[OK] SWAIG: SwaigFunctionResult imported successfully
[OK] Prefabs: InfoGathererAgent imported successfully
[SKIP] Search: Not installed (optional)
==================================================
Installation verification complete!
==================================================

Troubleshooting

Common Issues

Problem	Cause	Solution
`ModuleNotFoundError: No module named 'signalwire_agents'`	Package not installed	Run `pip install signalwire-agents`
`pip: command not found`	pip not in PATH	Use `python -m pip install signalwire-agents`
Permission errors	Installing globally without sudo	Use virtual environment or `pip install --user`
Old pip version	pip can’t resolve dependencies	Run `pip install --upgrade pip`
Conflicts with other packages	Dependency version mismatch	Use a fresh virtual environment

Python Version Check

Ensure you have Python 3.8+:

$ python --version
$ ## or
$ python3 --version

If you have multiple Python versions:

$ ## Use specific version
$ python3.10 -m venv venv
$ source venv/bin/activate
$ pip install signalwire-agents

Upgrade Existing Installation

$ pip install --upgrade signalwire-agents

Clean Reinstall

$ pip uninstall signalwire-agents
$ pip cache purge
$ pip install signalwire-agents

CLI Tools

The SDK includes command-line tools:

Tool	Purpose
`swaig-test`	Test agents and functions locally
`sw-search`	Build and query search indexes
`sw-agent-init`	Create new agent projects

Verify CLI tools are available:

$ swaig-test --help
$ sw-agent-init --help

What Gets Installed

The SDK installs these core dependencies:

Package	Purpose
`fastapi`	Web framework for serving SWML
`uvicorn`	ASGI server for running the agent
`pydantic`	Data validation and settings
`structlog`	Structured logging
`httpx`	HTTP client for API calls

Next Steps

Now that the SDK is installed, let’s create your first agent.