Skip to main content

Quickstart

Agents SDK

Get up and running quickly with the SignalWire AI Agents SDK. This section covers installation, basic setup, and your first AI agent implementation.

Prerequisites​

  • Python 3+
  • A SignalWire account
  • Ngrok (or other tunneling service)
  • jq (Optional but recommended)
😎You don't need:
  • A credit card: New SignalWire Spaces come with a $5 starter credit
  • Extensive Python or telecom knowledge: This guide is beginner-friendly

Set up a virtual environment​

Run this command in your desired project location.

python -m venv .venv

# On macOS and some other Unix systems, use python3 for this step.
# With a venv active, "python" alone can be used.

Next, run the activation script corresponding to your shell:

source .venv/bin/activate

Install the SDK​

With a virtual environment activated, install the latest release of the Agents SDK and its dependencies.

pip install signalwire-agents

Create your first agent​

Create dev-agent.py and copy in the boilerplate below.

dev-agent.py
from signalwire_agents import AgentBase

# Create an agent and assign a route
agent = AgentBase("My Assistant", route="/assistant")

# Add some basic capabilities
agent.add_skill("datetime")     # Current date/time info
agent.add_skill("math")         # Mathematical calculations

# Start the agent
agent.serve()

Done! It's literally that simple. We've created and named an agent, given it a route on our server, and taught it the datetime and math skills.

Serve the agent​

Our boilerplate script above creates a new agent and assigns it a route on your server. To verify everything is working as it should, let's run the server locally.

python dev-agent.py

Test the server​

Great! The server should now be running on port 3000. Next, let's make an authenticated request to see the SWML generated by our boilerplate application. For now, we'll use the basic auth generated by the server. By default, the username is signalwire. Copy the generated password from the terminal on the line starting with Basic Auth.

curl signalwire:password@0.0.0.0:3000/assistant

You'll get back a payload of unstructured JSON. That's right, SWML is JSON!

To read it more easily, pipe the result into jq, or open 0.0.0.0:3000/assistant in the pretty print view available in most browsers.

This basic SWML script is how the SignalWire cloud platform interacts with your application. When you configure a SignalWire phone number to call the application, SignalWire requests and processes SWML from your server.

Expose development server via tunnel​

To let SignalWire make requests to your server running locally, we'll use Ngrok (or your tunneling service of choice) to expose port 3000.

ngrok http 3000

Verify that the tunneling is working with the same command as before. Replace 0.0.0.0 with your temporary hosted URL. You should get the same JSON response.

curl https://signalwire:{{password}}@{{generated-url}}.ngrok-free.app:3000/assistant

Assign a phone number​

We're almost done! The final step is to purchase and assign a phone number in your SignalWire Dashboard. In the Assign Resource menu, select SWML Script. Under Primary Script, set Handle Calls Using and select External URL. Here, paste the URL you just tested.

https://signalwire:{{password}}@{{generated-url}}.ngrok-free.app:3000/assistant

Lastly, click Save.

Try it out​

With your application created, server running, tunnel live, and phone number configured, you can now call and talk to your brand-new Agent at its phone number. 🎉

What's next?​

Now that you have a basic agent running, explore these advanced topics:

  • Configuration guide: Set up JSON configuration files and environment variable substitution
  • Security guide: Configure HTTPS, authentication, and production security
  • CLI tools: Test and debug your agents with the command-line interface