@signalwire/sdk 3.5.0 → 3.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +71 -0
- package/dist/AgentBase.d.ts +101 -0
- package/dist/AgentBase.js +209 -22
- package/dist/AgentBase.js.map +1 -1
- package/dist/DataMap.d.ts +28 -0
- package/dist/DataMap.js +43 -0
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +32 -0
- package/dist/FunctionResult.js +39 -0
- package/dist/FunctionResult.js.map +1 -1
- package/dist/SWMLService.d.ts +11 -1
- package/dist/SWMLService.js +21 -2
- package/dist/SWMLService.js.map +1 -1
- package/dist/SemanticGate.d.ts +197 -0
- package/dist/SemanticGate.js +554 -0
- package/dist/SemanticGate.js.map +1 -0
- package/dist/SwaigFunction.d.ts +29 -3
- package/dist/SwaigFunction.js +19 -3
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/cli/tsdocs/api-index.json +1 -1
- package/dist/cli/tsdocs/topics.js +21 -0
- package/dist/cli/tsdocs/topics.js.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/skills/SkillBase.d.ts +14 -1
- package/dist/skills/SkillBase.js.map +1 -1
- package/docs/agent-guide.md +122 -2
- package/docs/api-reference.md +142 -4
- package/docs/architecture.md +2 -1
- package/docs/datamap-guide.md +51 -4
- package/docs/swaig-reference.md +48 -0
- package/package.json +1 -1
package/docs/architecture.md
CHANGED
|
@@ -135,7 +135,7 @@ SignalWire requests the SWML with a `POST` whose body describes the call. The ag
|
|
|
135
135
|
- **Tool dispatch**: running the handler for a SWAIG request, after checking its per-call token.
|
|
136
136
|
- **Proxy detection**: finding the external URL for the webhook URLs in the SWML.
|
|
137
137
|
- **Per-request configuration**: making a per-request copy of the agent for a dynamic config callback.
|
|
138
|
-
- **Lifecycle hooks**: `onSummary`, `onFunctionCall`, `onSwmlRequest`, `onDebugEvent`, `onCallEnd` and `onError`.
|
|
138
|
+
- **Lifecycle hooks**: `onSummary`, `onFunctionCall`, `onSwmlRequest`, `onDebugEvent`, `onCallStart`, `onCallEnd` and `onError`.
|
|
139
139
|
|
|
140
140
|
`SWMLService` supplies the `SwmlBuilder`, the tool registry, basic-auth resolution, routing callbacks and `handleRequest()`, the framework-free request handler that the agent's SWML routes call.
|
|
141
141
|
|
|
@@ -777,6 +777,7 @@ A subclass can override these methods:
|
|
|
777
777
|
These methods register handlers instead of being overridden:
|
|
778
778
|
|
|
779
779
|
- `onError(handler)`: called when a tool handler throws, after the tool's own `onError`. A `FunctionResult` it returns is sent as the response.
|
|
780
|
+
- `onCallStart(handler)`: registers the reserved `startup_hook` tool, so the handler runs before the AI's first turn; the actions and response text of the `FunctionResult` it returns reach the call.
|
|
780
781
|
- `onCallEnd(handler)`: registers the reserved `hangup_hook` tool and turns on `swaig_post_conversation`, so the handler gets the call log when the call ends.
|
|
781
782
|
|
|
782
783
|
### Dynamic Configuration Callback
|
package/docs/datamap-guide.md
CHANGED
|
@@ -5,13 +5,14 @@ This page is the reference for the `DataMap` class in the SignalWire AI Agents T
|
|
|
5
5
|
<!-- snippet-setup -->
|
|
6
6
|
```ts
|
|
7
7
|
export {}; // treat each runnable example as a module
|
|
8
|
-
// Shared context the examples assume: `DataMap`/`FunctionResult` (imported
|
|
9
|
-
// reused), `agent` (an AgentBase), and `tool` (the DataMap built in the current
|
|
10
|
-
// Declared as ambient globals so each fragment resolves without repeating the
|
|
11
|
-
// A block that constructs or imports its own `const tool`/`DataMap` shadows these.
|
|
8
|
+
// Shared context the examples assume: `DataMap`/`FunctionResult`/`SemanticGate` (imported
|
|
9
|
+
// once and reused), `agent` (an AgentBase), and `tool` (the DataMap built in the current
|
|
10
|
+
// example). Declared as ambient globals so each fragment resolves without repeating the
|
|
11
|
+
// boilerplate. A block that constructs or imports its own `const tool`/`DataMap` shadows these.
|
|
12
12
|
declare global {
|
|
13
13
|
const DataMap: typeof import('@signalwire/sdk').DataMap;
|
|
14
14
|
const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
|
|
15
|
+
const SemanticGate: typeof import('@signalwire/sdk').SemanticGate;
|
|
15
16
|
const agent: import('@signalwire/sdk').AgentBase;
|
|
16
17
|
const tool: import('@signalwire/sdk').DataMap;
|
|
17
18
|
}
|
|
@@ -43,6 +44,9 @@ The page has these sections:
|
|
|
43
44
|
- [fallbackOutput](#fallbackoutput)
|
|
44
45
|
- [errorKeys](#errorkeys)
|
|
45
46
|
- [globalErrorKeys](#globalerrorkeys)
|
|
47
|
+
- [Semantic Gates](#semantic-gates)
|
|
48
|
+
- [gate](#gate)
|
|
49
|
+
- [gateFillers](#gatefillers)
|
|
46
50
|
- [Iteration](#iteration)
|
|
47
51
|
- [foreach](#foreach)
|
|
48
52
|
- [Environment Variables](#environment-variables)
|
|
@@ -629,6 +633,49 @@ With a ZIP code, the platform requests the first webhook. With only a city, it s
|
|
|
629
633
|
|
|
630
634
|
---
|
|
631
635
|
|
|
636
|
+
## Semantic Gates
|
|
637
|
+
|
|
638
|
+
A semantic gate is a yes/no question a decision model answers about the call right before the platform runs the function. When a gate fails, the data_map doesn't run at all: no expression or webhook is tried, and the model gets the gate's `on_fail` output. The [API reference](api-reference.md#semantic-gates) describes gates and their limits. They need a platform release that supports them; one that doesn't runs the function ungated.
|
|
639
|
+
|
|
640
|
+
### gate
|
|
641
|
+
|
|
642
|
+
This method adds a gate. Call it once per gate, up to 8.
|
|
643
|
+
|
|
644
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
645
|
+
```typescript
|
|
646
|
+
gate(gate: SemanticGate | Record<string, unknown>): this
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
`toSwaigFunction()` checks the gates by the platform's rules, after environment variables are expanded, and throws for one the platform would refuse. This tool places an order only once the caller has confirmed it:
|
|
650
|
+
|
|
651
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` and `SemanticGate` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
652
|
+
```typescript
|
|
653
|
+
const placeOrder = new DataMap('place_order')
|
|
654
|
+
.purpose('Place the order the caller confirmed')
|
|
655
|
+
.webhook('POST', 'https://orders.example.com/orders')
|
|
656
|
+
.params({ item: '${args.item}' })
|
|
657
|
+
.output(new FunctionResult('The order is placed.'))
|
|
658
|
+
.gate(
|
|
659
|
+
new SemanticGate(
|
|
660
|
+
'Has the caller confirmed the order in `conversation`?',
|
|
661
|
+
0.9,
|
|
662
|
+
'place_order was not run.',
|
|
663
|
+
),
|
|
664
|
+
)
|
|
665
|
+
.gateFillers({ default: ['Let me check that.'] });
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
### gateFillers
|
|
669
|
+
|
|
670
|
+
This method sets what the AI says while the gates are checked, shaped like a function's fillers: phrases keyed by language code, `auto` or `default`. It's only for a function with gates.
|
|
671
|
+
|
|
672
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
673
|
+
```typescript
|
|
674
|
+
gateFillers(fillers: FillerPhrases): this
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
---
|
|
678
|
+
|
|
632
679
|
## Iteration
|
|
633
680
|
|
|
634
681
|
### foreach
|
package/docs/swaig-reference.md
CHANGED
|
@@ -43,6 +43,7 @@ The reference groups the methods by what they do:
|
|
|
43
43
|
- [say](#say)
|
|
44
44
|
- [playBackgroundFile](#playbackgroundfile)
|
|
45
45
|
- [stopBackgroundFile](#stopbackgroundfile)
|
|
46
|
+
- [changeVoice](#changevoice)
|
|
46
47
|
- [Speech](#speech)
|
|
47
48
|
- [addDynamicHints](#adddynamichints)
|
|
48
49
|
- [clearDynamicHints](#cleardynamichints)
|
|
@@ -51,6 +52,7 @@ The reference groups the methods by what they do:
|
|
|
51
52
|
- [Data Management](#data-management)
|
|
52
53
|
- [updateGlobalData](#updateglobaldata)
|
|
53
54
|
- [removeGlobalData](#removeglobaldata)
|
|
55
|
+
- [setSemanticState](#setsemanticstate)
|
|
54
56
|
- [setMetadata](#setmetadata)
|
|
55
57
|
- [removeMetadata](#removemetadata)
|
|
56
58
|
- [SWML Actions](#swml-actions)
|
|
@@ -702,6 +704,29 @@ const result = new FunctionResult('The music is stopped.')
|
|
|
702
704
|
.stopBackgroundFile();
|
|
703
705
|
```
|
|
704
706
|
|
|
707
|
+
### changeVoice
|
|
708
|
+
|
|
709
|
+
Change the AI's voice for the rest of the call (`change_voice`). The voice takes the `engine.voice:model` form a language's voice takes, and may be on another engine. It replaces the current language's voice from the next batch of speech on, never mid-utterance, and stays for that language for the rest of the call. A voice that won't open falls back to the fallback voice.
|
|
710
|
+
|
|
711
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
712
|
+
```typescript
|
|
713
|
+
changeVoice(voice: string): this
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
| Parameter | Type | Description |
|
|
717
|
+
|-----------|----------|--------------------------------------------------------|
|
|
718
|
+
| `voice` | `string` | The voice as `engine.voice:model`, such as `elevenlabs.rachel`. |
|
|
719
|
+
|
|
720
|
+
**Returns:** `this` for chaining.
|
|
721
|
+
|
|
722
|
+
**Throws:** `Error` when `voice` is empty or only whitespace. The platform would ignore it.
|
|
723
|
+
|
|
724
|
+
**Example:**
|
|
725
|
+
|
|
726
|
+
```typescript
|
|
727
|
+
const result = new FunctionResult('The voice is changed.').changeVoice('elevenlabs.rachel');
|
|
728
|
+
```
|
|
729
|
+
|
|
705
730
|
## Speech
|
|
706
731
|
|
|
707
732
|
### addDynamicHints
|
|
@@ -822,6 +847,29 @@ const result = new FunctionResult('The customer record is loaded.')
|
|
|
822
847
|
.updateGlobalData({ customer_id: 'C-123', tier: 'premium' });
|
|
823
848
|
```
|
|
824
849
|
|
|
850
|
+
### setSemanticState
|
|
851
|
+
|
|
852
|
+
Set the state the call's semantic gates judge, besides the dialogue: `global_data.semantic_state` (sent as `set_global_data`). It replaces the state as a whole: to change one field, send the whole state with that field changed, and send `{}` to reset it. Keep it to what the application has established, such as an order the caller confirmed, rather than what the caller claims. It's the only global data copied into the decision model's state; a gate question can still bring in other global data with a `${global_data.x}` template. See [Semantic gates](api-reference.md#semantic-gates).
|
|
853
|
+
|
|
854
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
855
|
+
```typescript
|
|
856
|
+
setSemanticState(state: Record<string, unknown>): this
|
|
857
|
+
```
|
|
858
|
+
|
|
859
|
+
| Parameter | Type | Description |
|
|
860
|
+
|-----------|---------------------------|---------------------|
|
|
861
|
+
| `state` | `Record<string, unknown>` | The semantic state. |
|
|
862
|
+
|
|
863
|
+
**Returns:** `this` for chaining.
|
|
864
|
+
|
|
865
|
+
**Example:**
|
|
866
|
+
|
|
867
|
+
```typescript
|
|
868
|
+
const result = new FunctionResult('The order is confirmed.').setSemanticState({
|
|
869
|
+
order: { item: 'large pepperoni', confirmed: true },
|
|
870
|
+
});
|
|
871
|
+
```
|
|
872
|
+
|
|
825
873
|
### removeGlobalData
|
|
826
874
|
|
|
827
875
|
Remove one or more keys from the global data (`unset_global_data`).
|