SignalWire SDK for Java

Build AI voice agents, control live calls over WebSocket, and manage every SignalWire resource over REST -- all from one package.

Documentation · Report an Issue · Maven Central

---

What's in this SDK

Capability	What it does	Quick link
AI Agents	Build voice agents that handle calls autonomously -- the platform runs the AI pipeline, your code defines the persona, tools, and call flow	Agent Guide
RELAY Client	Control live calls and SMS/MMS in real time over WebSocket -- answer, play, record, collect DTMF, conference, transfer, and more	RELAY docs
REST Client	Manage SignalWire resources over HTTP -- phone numbers, SIP endpoints, Fabric AI agents, video rooms, messaging, and 18+ API namespaces	REST docs

Gradle:

implementation 'com.signalwire:signalwire-sdk:2.0.0'

Maven:

<dependency>
    <groupId>com.signalwire</groupId>
    <artifactId>signalwire-sdk</artifactId>
    <version>2.0.0</version>
</dependency>

Requires Java 21+.

---

AI Agents

Each agent is a self-contained microservice that generates SWML (SignalWire Markup Language) and handles SWAIG (SignalWire AI Gateway) tool calls. The SignalWire platform runs the entire AI pipeline (STT, LLM, TTS) -- your agent just defines the behavior.

import com.signalwire.sdk.agent.AgentBase;
import com.signalwire.sdk.swaig.FunctionResult;

import java.time.LocalTime;
import java.util.List;
import java.util.Map;

public class MyAgent {
    public static void main(String[] args) throws Exception {
        var agent = AgentBase.builder()
                .name("my-agent")
                .route("/")
                .port(3000)
                .build();

        agent.addLanguage("English", "en-US", "inworld.Mark");
        agent.promptAddSection("Role", "You are a helpful assistant.");
        agent.promptAddSection("Rules", "", List.of(
                "Always answer concisely",
                "Use the get_time tool when asked about the time"
        ));

        agent.defineTool(
                "get_time",
                "Get the current time",
                Map.of(),
                (toolArgs, rawData) ->
                        new FunctionResult("The time is " + LocalTime.now())
        );

        agent.run();
    }
}

Test locally without running a server:

bin/swaig-test --url http://user:pass@localhost:3000 --list-tools
bin/swaig-test --url http://user:pass@localhost:3000 --dump-swml
bin/swaig-test --url http://user:pass@localhost:3000 --exec get_time

Agent Features

• Prompt Object Model (POM) -- structured prompt composition via promptAddSection()
• SWAIG tools -- define functions with defineTool() that the AI calls mid-conversation, with native access to the call's media stack
• Skills system -- add capabilities with one-liners: agent.addSkill("datetime")
• Contexts and steps -- structured multi-step workflows with navigation control
• DataMap tools -- tools that execute on SignalWire's servers, calling REST APIs without your own webhook
• Dynamic configuration -- per-request agent customization for multi-tenant deployments
• Call flow control -- pre-answer, post-answer, and post-AI verb insertion
• Prefab agents -- ready-to-use archetypes (InfoGatherer, Survey, FAQ, Receptionist, Concierge)
• Multi-agent hosting -- serve multiple agents on a single server with AgentServer
• SIP routing -- route SIP calls to agents based on usernames
• Session state -- persistent conversation state with global data and post-prompt summaries
• Security -- auto-generated basic auth, function-specific HMAC tokens, SSL support
• Serverless -- deploy to AWS Lambda, Kubernetes, or embed in Spring Boot and Servlet containers

Agent Examples

The examples/ directory contains 30+ working examples:

Example	What it demonstrates
SimpleAgent.java	POM prompts, SWAIG tools, speech hints
ContextsDemo.java	Multi-persona workflow with context switching and step navigation
DataMapDemo.java	Server-side API tools without webhooks
CallFlow.java	Call flow verbs and actions
SessionState.java	Global data and post-prompt summaries
MultiAgentServer.java	Multiple agents on one server
LambdaAgent.java	AWS Lambda deployment
ComprehensiveDynamic.java	Per-request dynamic configuration, multi-tenant routing

See examples/README.md for the full list organized by category.

---

RELAY Client

Real-time call control and messaging over WebSocket. The RELAY client connects to SignalWire via the Blade protocol and gives you imperative control over live phone calls and SMS/MMS, powered by Java virtual threads.

import com.signalwire.sdk.relay.RelayClient;

import java.util.List;
import java.util.Map;

var client = RelayClient.builder()
        .project("your-project-id")
        .token("your-api-token")
        .space("example.signalwire.com")
        .contexts(List.of("default"))
        .build();

client.onCall(call -> {
    call.answer();
    var action = call.play(List.of(Map.of(
            "type", "tts",
            "params", Map.of("text", "Welcome to SignalWire!")
    )));
    action.waitForCompletion();
    call.hangup();
});

client.run();

• All calling methods: play, record, collect, connect, detect, fax, tap, stream, AI, conferencing, and more
• SMS/MMS messaging with delivery tracking
• Action objects with waitForCompletion(), stop(), pause(), resume()
• Virtual-thread based with auto-reconnect and exponential backoff

See the RELAY documentation for the full guide, API reference, and examples.

---

REST Client

Synchronous REST client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required.

import com.signalwire.sdk.rest.RestClient;

import java.util.Map;

var client = RestClient.builder()
        .project("your-project-id")
        .token("your-api-token")
        .space("example.signalwire.com")
        .build();

// Create an AI agent
client.fabric().aiAgents().create(Map.of(
        "name", "Support Bot",
        "prompt", Map.of("text", "You are a helpful support agent.")
));

// Control a live call
client.calling().execute("play", Map.of(
        "call_id", callId,
        "play", List.of(Map.of("type", "tts", "text", "Hello!"))
));

// Search for phone numbers
client.phoneNumbers().search(Map.of("area_code", "512"));

// Semantic search across documents
client.datasphere().documents().search(Map.of("query_string", "billing policy"));

• 21 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), Phone Numbers, SIP, Queues, Recordings, and more
• Uses java.net.http.HttpClient for connection pooling
• Map returns -- raw JSON decoded to Maps, no wrapper objects

See the REST documentation for the full guide, API reference, and examples.

---

Documentation

Full reference documentation is available at developer.signalwire.com/sdks/agents-sdk.

Guides are also available in the docs/ directory:

Getting Started

• Agent Guide -- creating agents, prompt configuration, dynamic setup
• Architecture -- SDK architecture and core concepts
• SDK Features -- feature overview, SDK vs raw SWML comparison

Core Features

• SWAIG Reference -- function results, actions, post_data lifecycle
• Contexts and Steps -- structured workflows, navigation, gather mode
• DataMap Guide -- serverless API tools without webhooks
• LLM Parameters -- temperature, top_p, barge confidence tuning
• SWML Service Guide -- low-level construction of SWML documents

Skills and Extensions

• Skills System -- built-in skills and the modular framework
• Third-Party Skills -- creating and publishing custom skills
• MCP Gateway -- Model Context Protocol integration

Deployment

• CLI Guide -- swaig-test command reference
• Cloud Functions -- Lambda and container deployment
• Configuration -- environment variables, SSL, proxy setup
• Security -- authentication and security model

Reference

• API Reference -- complete class and method reference
• Web Service -- HTTP server and endpoint details
• Skills Parameter Schema -- skill parameter definitions

Environment Variables

Variable	Used by	Description
SIGNALWIRE_PROJECT_ID	RELAY, REST	Project identifier
SIGNALWIRE_API_TOKEN	RELAY, REST	API token
SIGNALWIRE_SPACE	RELAY, REST	Space hostname (e.g. example.signalwire.com)
SWML_BASIC_AUTH_USER	Agents	Basic auth username (default: auto-generated)
SWML_BASIC_AUTH_PASSWORD	Agents	Basic auth password (default: auto-generated)
SWML_PROXY_URL_BASE	Agents	Base URL when behind a reverse proxy
SWML_SSL_ENABLED	Agents	Enable HTTPS (true, 1, yes)
SWML_SSL_CERT_PATH	Agents	Path to SSL certificate
SWML_SSL_KEY_PATH	Agents	Path to SSL private key
SIGNALWIRE_LOG_LEVEL	All	Logging level (debug, info, warn, error)
SIGNALWIRE_LOG_MODE	All	Set to off to suppress all logging

Testing

# Build the SDK
./gradlew build

# Run the test suite
./gradlew test

# Run a specific test class
./gradlew test --tests "com.signalwire.sdk.agent.AgentBaseTest"

# Coverage
./gradlew test jacocoTestReport

License

MIT -- see LICENSE for details.