Get started

Quickstart

View as MarkdownOpen in Claude

Build one AI agent and reach it through two channels: a phone call and a text conversation. Choose the Server SDK or write SignalWire Markup Language (SWML) directly. Both paths produce one public agent configuration that you can connect to either channel.

Before you start, you need:

1

Build and publish the agent

Choose one authoring path. Both paths create the same agent definition and give it a public configuration URL. You will connect that URL to a channel in the next step.

This quickstart uses Python throughout. The voice path is also available for TypeScript, but the AI Chat client used in the next step is currently available only for Python. See the Server SDK documentation for both SDKs.

Install the Server SDK

$python3 -m pip install signalwire-sdk

Write the agent

Create agent.py:

agent.py
1from signalwire import AgentBase
2
3
4agent = AgentBase(name="quickstart-agent")
5agent.set_prompt_text(
6    "You are a concise and helpful SignalWire assistant. "
7    "Begin by greeting the person and asking how you can help."
8)
9
10
11if __name__ == "__main__":
12    agent.run()

This is the complete agent application. agent.run() starts an HTTP server on port 3000 and serves the SWML document that defines the agent.

Give the agent a public URL

In a second terminal, start ngrok:

$ngrok http 3000

Copy the HTTPS forwarding URL, such as https://abc123.ngrok-free.app. Keep ngrok running.

Start the agent with stable credentials

In the first terminal, set a URL-safe development password and the ngrok URL before starting the agent. Reuse these values for the rest of the quickstart.

$export SWML_BASIC_AUTH_USER="signalwire"
$export SWML_BASIC_AUTH_PASSWORD="replace-with-a-long-random-password"
$export SWML_PROXY_URL_BASE="https://abc123.ngrok-free.app"
$export SIGNALWIRE_AGENT_CONFIG_URL="https://signalwire:replace-with-a-long-random-password@abc123.ngrok-free.app/"
$python3 agent.py

The fixed credentials keep the agent URL valid if you restart the process. SWML_PROXY_URL_BASE lets the SDK generate public callback URLs when you add tools later.

Verify the generated SWML

From another terminal, request the agent configuration through the tunnel:

$curl --fail \
>  --user "signalwire:replace-with-a-long-random-password" \
>  "https://abc123.ngrok-free.app/" \
>  | python3 -m json.tool

A working agent returns a JSON document with "version": "1.0.0" and a sections.main array that contains answer and ai methods. If the request returns 401, use the same credentials that you exported before starting agent.py. If it cannot connect, confirm that both the agent and ngrok are still running.

2

Connect a channel

Voice and Chat use the same agent definition. Choose how you want to interact with the agent; you can return later and connect the other channel to the same configuration URL.

Route a phone number to the public configuration URL, then place a call.

Create an External URL resource

Open the SignalWire Dashboard, select Script, and then select External URL. Use the matching Primary Script URL:

SetupPrimary Script URL
Server SDKhttps://signalwire:replace-with-a-long-random-password@abc123.ngrok-free.app/
SWMLhttps://abc123.ngrok-free.app/swml.json

Select Create.

Assign a phone number

Open Phone Numbers, select a number, and then select Edit Settings. Under Inbound Call Settings, choose Assign Resource, select the External URL resource, and save the change.

Place a call

Call the SignalWire number. The agent greets you and asks how it can help. If the call does not reach the agent, request the configuration URL with curl again, then confirm that the phone number is assigned to the same External URL resource.

Next steps

Tool calling

Connect the agent to your systems so both voice and text conversations can use current data and take action.

Best practices

Prepare the agent for production with guidance for prompts, latency, recognition, testing, and compliance.