Swml Schema

View as Markdown

SWML Schema

Reference for SWML (SignalWire Markup Language) document structure and validation.

Overview

SWML (SignalWire Markup Language) is a JSON format for defining call flows and AI agent behavior.

Key Components:

  • version: Schema version (always “1.0.0”)
  • sections: Named groups of verbs
  • Verbs: Actions like ai, play, connect, transfer

Basic Structure

1{
2 "version": "1.0.0",
3 "sections": {
4 "main": [
5 { "verb_name": { "param": "value" } }
6 ]
7 }
8}

Required Fields

FieldTypeDescription
versionstringMust be “1.0.0”
sectionsobjectContains named section arrays
mainarrayDefault entry section (required)

AI Verb

The ai verb creates an AI agent:

1{
2 "version": "1.0.0",
3 "sections": {
4 "main": [
5 {
6 "ai": {
7 "prompt": {
8 "text": "You are a helpful assistant."
9 },
10 "post_prompt": {
11 "text": "Summarize the conversation."
12 },
13 "post_prompt_url": "https://example.com/summary",
14 "params": {
15 "temperature": 0.7
16 },
17 "languages": [
18 {
19 "name": "English",
20 "code": "en-US",
21 "voice": "rime.spore"
22 }
23 ],
24 "hints": ["SignalWire", "SWAIG"],
25 "SWAIG": {
26 "functions": [],
27 "native_functions": [],
28 "includes": []
29 }
30 }
31 }
32 ]
33 }
34}

AI Verb Parameters

ParameterTypeDescription
promptobjectMain prompt configuration
post_promptobjectSummary/completion prompt
post_prompt_urlstringURL for summary delivery
paramsobjectAI model parameters
languagesarraySupported languages and voices
hintsarraySpeech recognition hints
SWAIGobjectFunction definitions
pronouncearrayPronunciation rules
global_dataobjectInitial session data

SWAIG Object

1{
2 "SWAIG": {
3 "functions": [
4 {
5 "function": "search",
6 "description": "Search for information",
7 "parameters": {
8 "type": "object",
9 "properties": {
10 "query": {
11 "type": "string",
12 "description": "Search query"
13 }
14 },
15 "required": ["query"]
16 },
17 "web_hook_url": "https://example.com/swaig"
18 }
19 ],
20 "native_functions": [
21 "check_time"
22 ],
23 "includes": [
24 {
25 "url": "https://example.com/shared_functions",
26 "functions": ["shared_search", "shared_lookup"]
27 }
28 ]
29 }
30}

Function Definition

FieldTypeRequiredDescription
functionstringYesFunction name
descriptionstringYesWhat the function does
parametersobjectNoJSON Schema for parameters
web_hook_urlstring*Webhook URL (if not data_map)
data_mapobject*DataMap definition
meta_dataobjectNoCustom metadata
meta_data_tokenstringNoToken scope for metadata
fillersarrayNoProcessing phrases
wait_filestringNoHold audio URL

Common Verbs

answer

1{ "answer": {} }

play

1{
2 "play": {
3 "url": "https://example.com/audio.mp3"
4 }
5}

connect

1{
2 "connect": {
3 "to": "+15551234567",
4 "from": "+15559876543"
5 }
6}

transfer

1{
2 "transfer": {
3 "dest": "https://example.com/other_agent"
4 }
5}

hangup

1{ "hangup": {} }

record_call

1{
2 "record_call": {
3 "stereo": true,
4 "format": "mp3"
5 }
6}

record

1{
2 "record": {
3 "format": "mp3"
4 }
5}

Contexts Structure

1{
2 "version": "1.0.0",
3 "sections": {
4 "main": [{
5 "ai": {
6 "contexts": {
7 "default": "main",
8 "main": {
9 "steps": [
10 {
11 "name": "greeting",
12 "text": "Welcome the caller.",
13 "valid_steps": ["collect"]
14 },
15 {
16 "name": "collect",
17 "text": "Collect information.",
18 "functions": ["lookup_account"],
19 "valid_steps": ["confirm"]
20 }
21 ]
22 }
23 }
24 }
25 }]
26 }
27}

Step Structure

FieldTypeDescription
namestringStep identifier
textstringStep prompt text
step_criteriastringCompletion criteria
functionsstring | array”none” or list of function names
valid_stepsarrayAllowed next steps
valid_contextsarrayAllowed context switches

DataMap Structure

1{
2 "function": "get_weather",
3 "description": "Get weather information",
4 "parameters": {
5 "type": "object",
6 "properties": {
7 "city": {
8 "type": "string",
9 "description": "City name"
10 }
11 },
12 "required": ["city"]
13 },
14 "data_map": {
15 "webhooks": [
16 {
17 "url": "https://api.weather.com/current?q=${enc:args.city}",
18 "method": "GET",
19 "output": {
20 "response": "Weather: ${response.condition}"
21 }
22 }
23 ]
24 }
25}

Prompt Object (POM)

1{
2 "prompt": {
3 "pom": [
4 {
5 "section": "Role",
6 "body": "You are a helpful assistant."
7 },
8 {
9 "section": "Guidelines",
10 "bullets": [
11 "Be concise",
12 "Be helpful",
13 "Be accurate"
14 ]
15 }
16 ]
17 }
18}

Language Configuration

1{
2 "languages": [
3 {
4 "name": "English",
5 "code": "en-US",
6 "voice": "rime.spore",
7 "speech_fillers": ["um", "uh"],
8 "function_fillers": ["Let me check..."]
9 },
10 {
11 "name": "Spanish",
12 "code": "es-ES",
13 "voice": "rime.spore"
14 }
15 ]
16}

Model Parameters

1{
2 "params": {
3 "temperature": 0.7,
4 "top_p": 0.9,
5 "max_tokens": 150,
6 "frequency_penalty": 0.0,
7 "presence_penalty": 0.0,
8 "confidence": 0.6,
9 "barge_confidence": 0.1
10 }
11}

Schema Validation

The SDK includes a schema.json file for validation:

1from signalwire_agents.utils.schema_utils import SchemaUtils
2
3schema = SchemaUtils()
4schema.validate(swml_document)

Full Example

1{
2 "version": "1.0.0",
3 "sections": {
4 "main": [
5 { "answer": {} },
6 {
7 "ai": {
8 "prompt": {
9 "pom": [
10 {
11 "section": "Role",
12 "body": "You are a customer service agent."
13 },
14 {
15 "section": "Guidelines",
16 "bullets": [
17 "Be helpful and professional",
18 "Verify customer identity",
19 "Resolve issues efficiently"
20 ]
21 }
22 ]
23 },
24 "post_prompt": {
25 "text": "Summarize the customer interaction."
26 },
27 "post_prompt_url": "https://example.com/swaig/summary",
28 "params": {
29 "temperature": 0.7
30 },
31 "languages": [
32 {
33 "name": "English",
34 "code": "en-US",
35 "voice": "rime.spore"
36 }
37 ],
38 "hints": ["account", "billing", "support"],
39 "SWAIG": {
40 "functions": [
41 {
42 "function": "lookup_account",
43 "description": "Look up customer account",
44 "parameters": {
45 "type": "object",
46 "properties": {
47 "account_id": {
48 "type": "string",
49 "description": "Account number"
50 }
51 },
52 "required": ["account_id"]
53 },
54 "web_hook_url": "https://example.com/swaig"
55 }
56 ]
57 }
58 }
59 }
60 ]
61 }
62}