@signalwire/sdk 3.7.2 → 3.9.0
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 +154 -0
- package/README.md +1 -0
- package/dist/AgentBase.d.ts +107 -2
- package/dist/AgentBase.js +259 -13
- package/dist/AgentBase.js.map +1 -1
- package/dist/AiEvents.d.ts +70 -0
- package/dist/AiEvents.js +94 -0
- package/dist/AiEvents.js.map +1 -0
- package/dist/ContextBuilder.d.ts +181 -9
- package/dist/ContextBuilder.js +407 -9
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/FunctionResult.d.ts +129 -0
- package/dist/FunctionResult.js +170 -0
- package/dist/FunctionResult.js.map +1 -1
- package/dist/PostPrompt.d.ts +19 -0
- package/dist/PostPrompt.js +43 -0
- package/dist/PostPrompt.js.map +1 -1
- package/dist/SWMLService.d.ts +97 -1
- package/dist/SWMLService.js +129 -2
- package/dist/SWMLService.js.map +1 -1
- package/dist/SemanticGate.d.ts +61 -1
- package/dist/SemanticGate.js +108 -15
- package/dist/SemanticGate.js.map +1 -1
- package/dist/SwaigFunction.d.ts +85 -9
- package/dist/SwaigFunction.js +214 -58
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/ToolMiddleware.d.ts +82 -0
- package/dist/ToolMiddleware.js +131 -0
- package/dist/ToolMiddleware.js.map +1 -0
- package/dist/TypeInference.d.ts +1 -1
- package/dist/TypeInference.js.map +1 -1
- package/dist/cli/tsdocs/api-index.json +1 -1
- package/dist/cli/tsdocs/topics.js +24 -4
- package/dist/cli/tsdocs/topics.js.map +1 -1
- package/dist/index.d.ts +22 -8
- package/dist/index.js +15 -5
- package/dist/index.js.map +1 -1
- package/dist/llms.txt +1 -0
- package/dist/patterns/Proposal.d.ts +146 -0
- package/dist/patterns/Proposal.js +212 -0
- package/dist/patterns/Proposal.js.map +1 -0
- package/dist/patterns/RequestList.d.ts +136 -0
- package/dist/patterns/RequestList.js +169 -0
- package/dist/patterns/RequestList.js.map +1 -0
- package/dist/skills/SkillBase.d.ts +24 -1
- package/dist/skills/SkillBase.js +12 -1
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/speech/numbers.d.ts +66 -0
- package/dist/speech/numbers.js +281 -0
- package/dist/speech/numbers.js.map +1 -0
- package/dist/speech/spelling.d.ts +71 -0
- package/dist/speech/spelling.js +294 -0
- package/dist/speech/spelling.js.map +1 -0
- package/dist/testing/CallSimulator.d.ts +281 -0
- package/dist/testing/CallSimulator.js +666 -0
- package/dist/testing/CallSimulator.js.map +1 -0
- package/docs/agent-guide.md +2 -2
- package/docs/api-reference.md +277 -20
- package/docs/architecture.md +8 -4
- package/docs/cli-guide.md +2 -0
- package/docs/contexts-guide.md +45 -3
- package/docs/conversation_patterns.md +257 -0
- package/docs/mcp_integration.md +1 -1
- package/docs/programmatically_governed_inference.md +1 -1
- package/docs/swaig-reference.md +95 -3
- package/package.json +1 -1
package/docs/contexts-guide.md
CHANGED
|
@@ -222,6 +222,29 @@ Help the customer with their billing inquiry.
|
|
|
222
222
|
- Offer to escalate if needed
|
|
223
223
|
```
|
|
224
224
|
|
|
225
|
+
### Variables in Step Text
|
|
226
|
+
|
|
227
|
+
The platform expands a step's variables, such as `${global_data.order_total}`, once, when the step is entered. A later `updateGlobalData()` doesn't change text the model already has. To show the new value, return `FunctionResult.refreshStep()` with the current step's name after the update. Entering the step starts it over, and its `history` mode applies again.
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
import { FunctionResult } from '@signalwire/sdk';
|
|
231
|
+
|
|
232
|
+
const result = new FunctionResult('Added the drink.')
|
|
233
|
+
.updateGlobalData({ order_total: '$14.50' })
|
|
234
|
+
.refreshStep('take_order');
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### Expected Answers
|
|
238
|
+
|
|
239
|
+
When a step asks for a number with a known length, such as a ZIP code or a PIN, tell the recognizer how many digits to expect. It ends its wait for the number once the caller has said that many. Pass the exact count, or `minDigits` and `maxDigits` for a range, each from 1 to 64. The step emits it as `expected_answer`, which needs a platform release that has it.
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
ctx.addStep('get_zip').setText("Ask for the caller's ZIP code.").setExpectedAnswer(5);
|
|
243
|
+
ctx.addStep('get_pin').setText('Ask for the PIN.').setExpectedAnswer(undefined, { minDigits: 4, maxDigits: 6 });
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
A gather question takes its own, which replaces the step's while that question is asked: see [Expected Digits](#expected-digits). The exported `expectedAnswer()` function builds one, `{ digits: 5 }` or `{ min_digits: 4, max_digits: 6 }`, and checks it; an invalid count or shape throws.
|
|
247
|
+
|
|
225
248
|
### Managing Steps
|
|
226
249
|
|
|
227
250
|
These methods find, remove, reorder and clear steps:
|
|
@@ -334,6 +357,15 @@ A later step that leaves out `setFunctions()` therefore keeps the tools of the s
|
|
|
334
357
|
|
|
335
358
|
The SDK checks every name in a `functions` list, and in each gather question's `functions`, against the agent's registered tools. `validate()` throws for a name that isn't a registered tool or one of the reserved native tools.
|
|
336
359
|
|
|
360
|
+
`ContextBuilder.stepsOffering(name)` returns the `[context, step]` pairs whose function list, or a gather question's, names a tool. The functions a step without `setFunctions()` inherits from the step before it aren't counted, since they depend on how the caller got there; its gather questions' own function lists are. When every step lists its functions and none lists a registered tool, rendering the SWML logs a `tool_offered_by_no_step` warning for it, once: the model never gets that tool unless a function result turns it on with `toggleFunctions()`.
|
|
361
|
+
|
|
362
|
+
Name only a step's own tools in what the model reads in that step. When a step lists its functions, rendering also logs a `tool_named_but_not_offered` warning, once each, for a registered tool named in the step's text, its criteria, its context's prompt (which goes before every step's text), a gather question, or a gate's output on one of its tools, when the step doesn't offer it. A name with an underscore counts anywhere; a one-word name counts only in backticks or before "(". `namedTools(text, tools)` finds the names. Tool results are built at run time, so check those in tests with `new CallSimulator(agent, { checkToolMentions: true })`.
|
|
363
|
+
|
|
364
|
+
```typescript
|
|
365
|
+
const builder = agent.defineContexts();
|
|
366
|
+
console.log(builder.stepsOffering('place_order')); // e.g. [['default', 'confirm']]
|
|
367
|
+
```
|
|
368
|
+
|
|
337
369
|
---
|
|
338
370
|
|
|
339
371
|
## End States
|
|
@@ -444,7 +476,7 @@ While a question is asked, the platform deactivates the step's other functions.
|
|
|
444
476
|
|---|---|---|---|
|
|
445
477
|
| `outputKey` | `string` | none | Key in global data that holds the answers. Without it, each answer is stored at the top level. |
|
|
446
478
|
| `completionAction` | `string` | none | Where to go when every question is answered: `'next_step'` for the following step, or the name of a step in the same context. Without it, the step returns to its normal text. |
|
|
447
|
-
| `prompt` | `string` | none |
|
|
479
|
+
| `prompt` | `string` | none | Preamble sent with every question, as a system message ahead of the question's own; each copy replaces the one before. Under the `keep` history mode it's sent with the first question only, and that copy stays. |
|
|
448
480
|
| `isolated` | `boolean` | `false` | Default for every question. When `true`, a question is asked with the other questions and answers hidden from the model, so it must ask rather than work out the answer from an earlier one. The hidden turns stay in the call log. |
|
|
449
481
|
|
|
450
482
|
`validate()` throws when `completionAction` is `'next_step'` on the last step of a context, or names a step that isn't in the context.
|
|
@@ -462,6 +494,16 @@ While a question is asked, the platform deactivates the step's other functions.
|
|
|
462
494
|
| `prompt` | `string` | none | Extra instruction for this question. |
|
|
463
495
|
| `functions` | `string[]` | none | Functions available during this question only. |
|
|
464
496
|
| `isolated` | `boolean` | inherits the gather's setting | `true` hides the other questions and answers while this one is asked. `false` keeps them visible, even in an isolated gather. |
|
|
497
|
+
| `expectedAnswer` | `ExpectedAnswer` | none | The digits the recognizer expects while this question is asked, `{ digits }` or `{ min_digits, max_digits }`. See [Expected Digits](#expected-digits). |
|
|
498
|
+
|
|
499
|
+
#### Expected Digits
|
|
500
|
+
|
|
501
|
+
A question whose answer is a number of known length can tell the recognizer how many digits to expect, with `expectedAnswer`. It applies while that question is asked, in place of the step's `setExpectedAnswer()`.
|
|
502
|
+
|
|
503
|
+
```typescript
|
|
504
|
+
step.setGatherInfo({ outputKey: 'address' });
|
|
505
|
+
step.addGatherQuestion({ key: 'zip', question: 'What is your ZIP code?', expectedAnswer: { digits: 5 } });
|
|
506
|
+
```
|
|
465
507
|
|
|
466
508
|
### GatherInfo Serialization
|
|
467
509
|
|
|
@@ -554,7 +596,7 @@ These settings control what happens to the conversation history when the convers
|
|
|
554
596
|
|
|
555
597
|
### `setIsolated()`
|
|
556
598
|
|
|
557
|
-
`setIsolated(true)` clears the conversation history when the conversation enters the context through `change_context
|
|
599
|
+
`setIsolated(true)` clears the conversation history when the conversation enters the context through `change_context`: the platform drops every entry but the first, the base system prompt. The model starts with the base prompt and the context's step instructions only:
|
|
558
600
|
|
|
559
601
|
<!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
560
602
|
```typescript
|
|
@@ -582,7 +624,7 @@ ctx.setFullReset(true);
|
|
|
582
624
|
|
|
583
625
|
### Step-Level Reset Options
|
|
584
626
|
|
|
585
|
-
A step can reset the conversation when the conversation enters it:
|
|
627
|
+
A step can reset the conversation when the conversation enters it. A step with any reset setting is terminal: the platform runs the reset in place of the step's text, and step mode ends there, so use it for a step that hands the call over to a new prompt. Rendering logs `step_reset_is_terminal` for it, and `context_reset_without_system_prompt` for a context's `setConsolidate()`, `setFullReset()` or `setUserPrompt()` without a system prompt, since a context's reset runs only with one:
|
|
586
628
|
|
|
587
629
|
```typescript
|
|
588
630
|
const step = ctx.addStep('fresh_start');
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# Conversation Patterns
|
|
2
|
+
|
|
3
|
+
Each pattern here keeps a decision in your code that the model would otherwise make from the conversation. The helpers are exported from the package root, `@signalwire/sdk`.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Confirming a Change](#confirming-a-change)
|
|
8
|
+
- [Read-Backs Callers Can Interrupt](#read-backs-callers-can-interrupt)
|
|
9
|
+
- [Recording What Was Done](#recording-what-was-done)
|
|
10
|
+
- [Questions That Carry Content](#questions-that-carry-content)
|
|
11
|
+
- [The Caller's Own Words](#the-callers-own-words)
|
|
12
|
+
- [Numbers the Way a Voice Should Say Them](#numbers-the-way-a-voice-should-say-them)
|
|
13
|
+
- [Tool Outcomes the Model Can Trust](#tool-outcomes-the-model-can-trust)
|
|
14
|
+
- [Requests to Come Back To](#requests-to-come-back-to)
|
|
15
|
+
- [What a Caller Spelled](#what-a-caller-spelled)
|
|
16
|
+
- [Testing a Call Flow](#testing-a-call-flow)
|
|
17
|
+
|
|
18
|
+
Several of these patterns use semantic gate keys, params and actions (`dialogue`, `history`, `since`, `unclear`, `on_unclear`, `semantic_gate_dialogue`, `unavailable_function_response`, `semantic_gate_mark` and `expected_answer`) that need a platform release that has them. A release with semantic gates but without one of the gate keys refuses the whole function. See [Semantic gates](api-reference.md#semantic-gates).
|
|
19
|
+
|
|
20
|
+
## Confirming a Change
|
|
21
|
+
|
|
22
|
+
A change the caller must agree to, such as placing an order or cancelling an account, needs a yes to that change, not a yes somewhere in the call. The platform's confirm pattern does this with semantic gates:
|
|
23
|
+
|
|
24
|
+
1. A function proposes the change. It reads the change back and records it in `semantic_state`, in one action object, so the proposal's dialogue starts with the read-back.
|
|
25
|
+
2. The tool that carries out the change has three gates, each judged on the proposal's dialogue: the caller's latest turn is an answer, the answer is a yes, and what they answered was a read-back of this change.
|
|
26
|
+
|
|
27
|
+
`Proposal` builds both halves. The gates' questions are the platform's own, which were replayed against logged confirmation checks.
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { AgentBase, Proposal, current } from '@signalwire/sdk';
|
|
31
|
+
|
|
32
|
+
const agent = new AgentBase({ name: 'orders', route: '/orders' });
|
|
33
|
+
const order = new Proposal('place_order', { declineTool: 'change_order' });
|
|
34
|
+
|
|
35
|
+
agent.defineTool({
|
|
36
|
+
name: 'review_order',
|
|
37
|
+
description: 'Read the order back to the caller',
|
|
38
|
+
parameters: { item: { type: 'string', description: 'The item, with its size' } },
|
|
39
|
+
required: ['item'],
|
|
40
|
+
handler: (args, rawData) =>
|
|
41
|
+
order.propose(`That's ${args.item} for pickup. Is that right?`, {
|
|
42
|
+
rawData,
|
|
43
|
+
details: { item: args.item },
|
|
44
|
+
}),
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
agent.defineTool({
|
|
48
|
+
name: 'place_order',
|
|
49
|
+
description: 'Place the order the caller said yes to',
|
|
50
|
+
handler: (_args, rawData) => {
|
|
51
|
+
const item = String(current(rawData)?.['item']);
|
|
52
|
+
return order.complete(`The order for ${item} is placed.`);
|
|
53
|
+
},
|
|
54
|
+
gates: order.confirmGates(),
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`propose()` says the read-back word for word, records `{ proposal: readBack, revision: n }` with your details, and has the model wait for the caller's answer. `current(rawData)` reads the proposal back from a request's `global_data.semantic_state`. When a gate blocks the confirm tool, the model is told why, with the proposal quoted from `semantic_state`, and chaining is turned off for the call (`backToBackFunctions(false)`), so it answers in words before it calls a tool again. To read the same change back again, use `askAgain(rawData)`: the platform marks a new proposal only when `semantic_state` changes, so it records the next revision.
|
|
59
|
+
|
|
60
|
+
`new Proposal(confirmTool, { unclear: true, threshold: 0.6 })` lets the gates answer unclear as well, where the gate provider can, which asks the caller again. Give the confirm step only the confirm tool, the decline tool and a tool that notes other requests, so a "yes, and also..." becomes two calls.
|
|
61
|
+
|
|
62
|
+
## Read-Backs Callers Can Interrupt
|
|
63
|
+
|
|
64
|
+
A caller often answers before a read-back ends. Order it so the part they must hear comes first:
|
|
65
|
+
|
|
66
|
+
1. The change itself: "That's a large tea, not a small one."
|
|
67
|
+
2. The details of the change: "for pickup at five, on the card ending in one two three four."
|
|
68
|
+
3. What was already settled, last: "at the Main Street store."
|
|
69
|
+
|
|
70
|
+
A caller who cuts it off has heard the change. The confirm gates count a yes once the caller has heard what the change is, so a read-back that leads with it confirms sooner.
|
|
71
|
+
|
|
72
|
+
## Recording What Was Done
|
|
73
|
+
|
|
74
|
+
After the change is carried out, write a `semantic_state` that records it, rather than clearing it with `{}`. `Proposal.complete(summary)` does this. A state that changes starts the next proposal's dialogue there, so a later confirmation isn't judged on what was said before this one, and the model and the gates see what's settled.
|
|
75
|
+
|
|
76
|
+
## Questions That Carry Content
|
|
77
|
+
|
|
78
|
+
A one-word answer is hard to judge: "yes" may answer something else the agent said. Ask questions whose answers carry content. "Which size would you like, small or large?" gets "large", which a gate, the recognizer and your code can check. "Do you want a large?" gets "yes".
|
|
79
|
+
|
|
80
|
+
## The Caller's Own Words
|
|
81
|
+
|
|
82
|
+
A tool can check that an argument is something the caller said, rather than something the model inferred.
|
|
83
|
+
|
|
84
|
+
`defineTool({ ..., vouched: true })` asks the model. The tool gets a required boolean, `data_supplied_by_user`, and runs only when the model sets it to `true`. Otherwise the model is told to get the answer from the caller first.
|
|
85
|
+
|
|
86
|
+
`callerTurns(rawData)` reads what the caller said from the request's conversation. A request carries the conversation only with `swaig_post_conversation` on, and `needsConversation: true` on the tool turns it on.
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { AgentBase, FunctionResult, callerTurns } from '@signalwire/sdk';
|
|
90
|
+
|
|
91
|
+
const agent = new AgentBase({ name: 'stores', route: '/stores' });
|
|
92
|
+
|
|
93
|
+
agent.defineTool({
|
|
94
|
+
name: 'find_store',
|
|
95
|
+
description: 'Find the store nearest a ZIP code',
|
|
96
|
+
parameters: { zip: { type: 'string', description: "The caller's ZIP code" } },
|
|
97
|
+
required: ['zip'],
|
|
98
|
+
needsConversation: true,
|
|
99
|
+
handler: (args, rawData) => {
|
|
100
|
+
const said = callerTurns(rawData, undefined, { last: 3 }).join(' ');
|
|
101
|
+
if (!said.replaceAll(' ', '').includes(args.zip)) {
|
|
102
|
+
return new FunctionResult().setToolResponse(
|
|
103
|
+
'find_store was not run.',
|
|
104
|
+
'Ask the caller for their ZIP code.',
|
|
105
|
+
);
|
|
106
|
+
}
|
|
107
|
+
return new FunctionResult().setToolResponse(
|
|
108
|
+
`The nearest store to ${args.zip} is on Main Street.`,
|
|
109
|
+
);
|
|
110
|
+
},
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The conversation has the recognizer's final text, after hearing hints and number formatting. For the words as the recognizer heard them, with a confidence for each, call `agent.recordSpeechFinals()` and read `agent.speechFinals(rawData.call_id)`. The finals come from the platform's `ai.speech_detect` events, which the agent receives at its own `/ai_events` endpoint. A handler can ask the caller again about a word the recognizer wasn't sure of, such as a letter of a spelled name. `agent.onAiEvent(handler)` receives every AI event the platform posts. Set both on the agent itself, not in a dynamic config callback: the `/ai_events` endpoint runs on the agent, not on a per-request copy. See [AI Event Methods](api-reference.md#ai-event-methods).
|
|
115
|
+
|
|
116
|
+
## Numbers the Way a Voice Should Say Them
|
|
117
|
+
|
|
118
|
+
The platform normalizes text before its pronunciation rules run, so a bare number is already words by then. A ZIP code given as "10001" can be read "ten thousand one", and `addPronunciation()` can't change that. Give the words to say instead:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { sayDigits, sayLastDigits, sayMoney } from '@signalwire/sdk';
|
|
122
|
+
|
|
123
|
+
sayDigits('415-555-0192'); // "four one five, five five five, zero one nine two"
|
|
124
|
+
sayDigits('10001', undefined, { zero: 'oh' }); // "one oh oh oh one"
|
|
125
|
+
sayLastDigits('4111111111111234'); // "one two three four"
|
|
126
|
+
sayMoney(14.5); // "fourteen dollars and fifty cents"
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Use them in a `say` action, or in the tool result the model reads back. They're English. `sayDigits(text, group?)` takes a group size, or a list of sizes such as `[3, 3, 4]`, in place of the text's own groups. `sayMoney(amount, currency?)` takes a number, a `bigint` or a decimal string such as `'14.50'`, and rounds half up from the amount's decimal text, so `sayMoney(2.675)` is "two dollars and sixty-eight cents". It knows USD, CAD, AUD, NZD, EUR, GBP, MXN, INR and JPY. `numberWords(n)` takes a safe integer or a `bigint` below a quadrillion: `numberWords(1405)` is "one thousand four hundred five".
|
|
130
|
+
|
|
131
|
+
When a step asks for a number with a known length, `step.setExpectedAnswer(5)` tells the recognizer to end its wait once the caller has said that many digits. See the [Contexts and Steps Guide](contexts-guide.md#expected-answers).
|
|
132
|
+
|
|
133
|
+
## Tool Outcomes the Model Can Trust
|
|
134
|
+
|
|
135
|
+
The model reads a tool's result as what happened, so the result must not claim more than the handler knows.
|
|
136
|
+
|
|
137
|
+
- Throw `new ToolRefusal(toolResult, toolPrompt)` to decline a call with an outcome you know, such as an item out of stock.
|
|
138
|
+
- Any other error tells the model the function failed before it finished, so whether it took effect is unknown, and not to tell the caller it worked or that it didn't. The error is logged, not sent. A tool's `onError` hook or `errorMessage` still takes its place when you give one.
|
|
139
|
+
- An object without a `response` or an `action` is the handler's data, and the model gets it as JSON.
|
|
140
|
+
|
|
141
|
+
SignalWire sends a tool request again after a timeout, a failed connection or a 5xx, so a slow tool could run twice. The agent answers such a retry with the first attempt's result, and one that arrives while the first is still running waits for it. `agent.setToolResendDedupe(false)` turns this off. The record is kept in the agent's process: with several processes or replicas, a retry that reaches another one runs the tool again, so make tools that change things safe to run twice. The dedupe is the first [tool middleware](api-reference.md#addtoolmiddlewaremiddleware) around every call.
|
|
142
|
+
|
|
143
|
+
## Requests to Come Back To
|
|
144
|
+
|
|
145
|
+
A caller in the middle of one task often asks for another: "and can you also check my balance?" Taking it up at once loses the first task, and ignoring it loses the second. `RequestList` keeps such requests in the call's `global_data`. A tool notes each one, and the model tells the caller it's noted for right after this. The step text shows the list, so the agent takes the requests up when the current task is done.
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
import { AgentBase, RequestList } from '@signalwire/sdk';
|
|
149
|
+
|
|
150
|
+
const agent = new AgentBase({ name: 'support', route: '/support' });
|
|
151
|
+
const later = new RequestList('later', {
|
|
152
|
+
openers: { balance: 'You also asked about your balance.' },
|
|
153
|
+
});
|
|
154
|
+
agent.setGlobalData(later.defaults());
|
|
155
|
+
|
|
156
|
+
agent.defineTool({
|
|
157
|
+
name: 'note_request',
|
|
158
|
+
description: 'Note something the caller asked to do later',
|
|
159
|
+
parameters: {
|
|
160
|
+
kind: { type: 'string', enum: ['balance', 'question'] },
|
|
161
|
+
about: { type: 'string', description: 'What the caller asked, in a few words' },
|
|
162
|
+
},
|
|
163
|
+
required: ['kind', 'about'],
|
|
164
|
+
handler: (args, rawData) => later.note(rawData, args.kind, args.about),
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
const ctx = agent.defineContexts().addContext('default');
|
|
168
|
+
ctx.addStep('take_order').setText('Take the order.\n\n${global_data.later_text}');
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`later.next(rawData)` gives the oldest request with its opener, and `later.done(rawData)` removes it once it's taken up. The kinds and their openers are yours; an opener's `{about}` is replaced by what the request is about. A step's text is expanded when the step is entered, so return `refreshStep()` with a note to show the new list at once.
|
|
172
|
+
|
|
173
|
+
## What a Caller Spelled
|
|
174
|
+
|
|
175
|
+
A caller spells a name, a code or an email address in many ways: letter by letter, with letter names, with "S as in Sam", with the NATO alphabet, or with "double l". `readSpelled`, `spokenEmail` and `spellingVariants` read them all from the recognizer's text.
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
import { readSpelled, spellingVariants, spokenEmail } from '@signalwire/sdk';
|
|
179
|
+
|
|
180
|
+
readSpelled('S as in Sam, m i t h'); // ['S', 'M', 'I', 'T', 'H']
|
|
181
|
+
readSpelled('sierra mike india tango hotel'); // ['S', 'M', 'I', 'T', 'H']
|
|
182
|
+
readSpelled('one two oh four', { ohIsZero: true }); // ['1', '2', '0', '4']
|
|
183
|
+
spokenEmail('john dot smith at example dot com'); // 'john.smith@example.com'
|
|
184
|
+
spellingVariants(['S', 'M', 'I', 'T', 'H'], { S: 'F', M: 'N' });
|
|
185
|
+
// ['SMITH', 'FMITH', 'SNITH', 'FNITH']
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The recognizer confuses some letters, and which ones depends on the recognizer and the voice, so `spellingVariants` takes confusion groups you measure on your own calls; none are built in. A group is a string of units or a list of them, and the groups may be a plain object or a `Map`. Its `positions` option limits the changes to the letters the recognizer was least sure of, which `agent.speechFinals()` gives a confidence for, and `limit` (default 50) caps the spellings. Look each variant up in your records, in order: the first that matches is the likeliest.
|
|
189
|
+
|
|
190
|
+
## Testing a Call Flow
|
|
191
|
+
|
|
192
|
+
`swaig-test` runs one tool call. To test a flow, such as a confirmation across steps, `CallSimulator` runs the agent's tools through a simulated call. It reads the agent's rendered SWML as the platform would, and checks each call as the platform does: a tool the current step doesn't offer doesn't run, and a gated tool runs only when your gate callback lets it. Each result's actions change the call: global data and `semantic_state`, the step and context, the functions turned on, `say`, and the end of the call. A tool runs as the agent's `/swaig` route runs it: through the `onFunctionCall` hook, then the tool with its middleware and the outcome rules above.
|
|
193
|
+
|
|
194
|
+
`call()` and `replay()` are async, so await them. This runs as a script; in a test, the same calls go inside the test function.
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
import assert from 'node:assert/strict';
|
|
198
|
+
import { AgentBase, CallSimulator, Proposal } from '@signalwire/sdk';
|
|
199
|
+
|
|
200
|
+
const agent = new AgentBase({ name: 'orders', route: '/orders' });
|
|
201
|
+
const order = new Proposal('place_order');
|
|
202
|
+
|
|
203
|
+
agent.defineTool({
|
|
204
|
+
name: 'review_order',
|
|
205
|
+
description: 'Read the order back to the caller',
|
|
206
|
+
parameters: { item: { type: 'string', description: 'The item' } },
|
|
207
|
+
required: ['item'],
|
|
208
|
+
handler: (args, rawData) =>
|
|
209
|
+
order
|
|
210
|
+
.propose(`That's ${args.item}. Is that right?`, { rawData, details: { item: args.item } })
|
|
211
|
+
.swmlChangeStep('confirm'),
|
|
212
|
+
});
|
|
213
|
+
agent.defineTool({
|
|
214
|
+
name: 'place_order',
|
|
215
|
+
description: 'Place the order the caller said yes to',
|
|
216
|
+
handler: () => order.complete('The order is placed.'),
|
|
217
|
+
gates: order.confirmGates(),
|
|
218
|
+
});
|
|
219
|
+
const ctx = agent.defineContexts().addContext('default');
|
|
220
|
+
ctx.addStep('take_order').setText('Take the order.').setFunctions(['review_order']);
|
|
221
|
+
ctx.addStep('confirm').setText('Confirm it.').setFunctions(['place_order']);
|
|
222
|
+
|
|
223
|
+
const sim = new CallSimulator(agent, { gates: () => true });
|
|
224
|
+
sim.caller('A large tea, please.');
|
|
225
|
+
assert.equal((await sim.call('place_order')).ran, false); // not offered until the read-back
|
|
226
|
+
await sim.call('review_order', { item: 'a large tea' });
|
|
227
|
+
sim.caller('Yes.');
|
|
228
|
+
assert.equal((await sim.call('place_order')).ran, true);
|
|
229
|
+
assert.deepEqual(sim.semanticState, { done: 'The order is placed.' });
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
The gate callback gets each gate, the simulator and the call's arguments, and returns `true`, `false`, a probability compared with the gate's threshold, or `'unclear'`, or a promise of one. A blocked call's `blockedBy` is `'step'` or the id of the gate that blocked it. With `checkToolMentions: true`, a call whose result names a tool that the step it leaves the call in doesn't offer rejects with a `ToolMentionError`: the model would read the name and might call a tool it doesn't have. Give `stubs` for DataMap tools, which run on the platform. `sim.marks` is a `Map` from each gate mark's name to its place in `sim.callLog`.
|
|
233
|
+
|
|
234
|
+
The simulator renders and runs tools on the agent itself: it doesn't make the per-request copy a dynamic config callback configures. It doesn't run a model, gather questions, or the gates' decision model.
|
|
235
|
+
|
|
236
|
+
To check changed code against real calls, record tool requests with `RequestRecorder`, which is tool middleware, and run them again with `replay()`:
|
|
237
|
+
|
|
238
|
+
<!-- snippet: no-run writes a recording file next to the snippet; illustrative -->
|
|
239
|
+
```ts
|
|
240
|
+
import { AgentBase, CallSimulator, RequestRecorder } from '@signalwire/sdk';
|
|
241
|
+
|
|
242
|
+
const agent = new AgentBase({ name: 'orders', route: '/orders' });
|
|
243
|
+
const recorder = new RequestRecorder('tool_requests.jsonl');
|
|
244
|
+
agent.addToolMiddleware(recorder.middleware);
|
|
245
|
+
|
|
246
|
+
// Later, against changed code:
|
|
247
|
+
const outcomes = await new CallSimulator(agent).replay(RequestRecorder.load('tool_requests.jsonl'));
|
|
248
|
+
console.log(outcomes.map((o) => o.response));
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
The recorder appends each request to the file, one JSON object a line, in the order they came, and keeps the newest `limit` (default 1000) in `recorder.requests`. The requests carry what callers said, so keep a recording where you'd keep call recordings.
|
|
252
|
+
|
|
253
|
+
## Related Documentation
|
|
254
|
+
|
|
255
|
+
- [API Reference](api-reference.md#semantic-gates): semantic gates and every tool option
|
|
256
|
+
- [SWAIG Reference](swaig-reference.md): every `FunctionResult` action
|
|
257
|
+
- [Contexts and Steps Guide](contexts-guide.md): steps, their function lists and expected answers
|
package/docs/mcp_integration.md
CHANGED
|
@@ -96,7 +96,7 @@ The endpoint takes JSON-RPC 2.0 requests as POSTs. It answers `404` to a GET, si
|
|
|
96
96
|
|
|
97
97
|
The endpoint lists and calls only the tools the agent runs itself. DataMap tools run on SignalWire, and external webhook tools (a `webhookUrl` on the tool) run on another server. `/mcp` doesn't list them, and `tools/call` answers `Unknown tool` for them.
|
|
98
98
|
|
|
99
|
-
A `tools/call` result carries the tool's `response` text as MCP text content. A structured `{ tool_result, tool_prompt }` response is sent as its JSON. Actions in the result, such as a transfer, have no meaning outside a call and aren't sent. A handler that throws gets the same result a SWAIG call gets: its `onError` hook's result, its `errorMessage`, or
|
|
99
|
+
A `tools/call` result carries the tool's `response` text as MCP text content. A structured `{ tool_result, tool_prompt }` response is sent as its JSON. Actions in the result, such as a transfer, have no meaning outside a call and aren't sent. A handler that throws gets the same result a SWAIG call gets: its `onError` hook's result, its `errorMessage`, or the result that tells the model the outcome is unknown, with `isError: false`. The exception's message doesn't reach the client.
|
|
100
100
|
|
|
101
101
|
Requests to `/mcp` run on the agent itself, not on a per-request copy. A dynamic config callback or `addPerCallConfig()` doesn't run for them, so tools those callbacks register aren't available. The handler's `rawData` holds only `function` and `argument`, with no `call_id` or `global_data`.
|
|
102
102
|
|
|
@@ -103,7 +103,7 @@ This is the difference between telling someone not to open a door and removing t
|
|
|
103
103
|
|
|
104
104
|
### Layer 3: Transition scope
|
|
105
105
|
|
|
106
|
-
Each step in a conversation declares which steps the model may move to next. The enforcement is mechanical and lives in the schema, not in the model's judgment.
|
|
106
|
+
Each step in a conversation declares which steps the model may move to next. The enforcement is mechanical and lives in the schema, not in the model's judgment. Each time a step loads, the platform rewrites the argument schema of the model's transition tool, `next_step`, so that only whitelisted step names exist as options. The model cannot request a transition to a step that is not on the list. The reason is the same as for a tool that is not in its schema: the option is not part of its world. An empty whitelist leaves the model no step it can request.
|
|
107
107
|
|
|
108
108
|
The whitelist constrains the model, not the software. Tool handlers, which are the developer's deterministic code, retain full transition authority. They can move the conversation to any step in the current context, or to another context, as the business logic requires. This is the authority inversion applied to control flow. The model can only request movements the system pre-approved, while the software that owns the state machine moves the conversation wherever the rules say. In the blackjack example, `playing` whitelists only `hand_complete`, so the model can't talk its way anywhere else. The `hit` handler, on detecting a bust, moves the conversation straight to `you_lost` with `swmlChangeStep()`. The software is the authority, and the whitelist was never a constraint on it.
|
|
109
109
|
|
package/docs/swaig-reference.md
CHANGED
|
@@ -53,17 +53,21 @@ The reference groups the methods by what they do:
|
|
|
53
53
|
- [updateGlobalData](#updateglobaldata)
|
|
54
54
|
- [removeGlobalData](#removeglobaldata)
|
|
55
55
|
- [setSemanticState](#setsemanticstate)
|
|
56
|
+
- [setSemanticGateMark](#setsemanticgatemark)
|
|
56
57
|
- [setMetadata](#setmetadata)
|
|
57
58
|
- [removeMetadata](#removemetadata)
|
|
58
59
|
- [SWML Actions](#swml-actions)
|
|
59
60
|
- [executeSwml](#executeswml)
|
|
60
61
|
- [switchContext](#switchcontext)
|
|
61
62
|
- [swmlChangeStep](#swmlchangestep)
|
|
63
|
+
- [refreshStep](#refreshstep)
|
|
62
64
|
- [swmlChangeContext](#swmlchangecontext)
|
|
63
65
|
- [swmlUserEvent](#swmluserevent)
|
|
64
66
|
- [Function Control](#function-control)
|
|
65
67
|
- [toggleFunctions](#togglefunctions)
|
|
66
68
|
- [enableFunctionsOnTimeout](#enablefunctionsontimeout)
|
|
69
|
+
- [noBargeNextResponse](#nobargenextresponse)
|
|
70
|
+
- [backToBackFunctions](#backtobackfunctions)
|
|
67
71
|
- [updateSettings](#updatesettings)
|
|
68
72
|
- [User Input and History](#user-input-and-history)
|
|
69
73
|
- [simulateUserInput](#simulateuserinput)
|
|
@@ -153,11 +157,12 @@ A tool handler receives `(args, rawData, agent)`. `args` holds the parsed argume
|
|
|
153
157
|
The SDK handles these return values:
|
|
154
158
|
|
|
155
159
|
- A `FunctionResult`, or a promise that resolves to one: serialized with `toDict()`.
|
|
156
|
-
- A plain object with a `response` key: sent as it is.
|
|
157
|
-
-
|
|
160
|
+
- A plain object with a `response` or an `action` key: sent as it is.
|
|
161
|
+
- Any other plain object: the handler's data, sent as its JSON in `response`. An empty object tells the model the outcome is unknown.
|
|
162
|
+
- `undefined` or `null`, as from a handler that returns nothing: `{ response: "Function executed successfully" }`.
|
|
158
163
|
- Any other value, such as a string: converted to a string and sent as the response, with a logged warning.
|
|
159
164
|
|
|
160
|
-
|
|
165
|
+
A handler that throws `new ToolRefusal(toolResult, toolPrompt?)` declines the call with an outcome it knows, such as an item out of stock: the model gets that `tool_result` and `tool_prompt`. Any other error is logged, not sent. The SDK then returns the result of the tool's `onError` hook, or of the agent's `onError()` handler, when either returns a `FunctionResult`. Otherwise it returns the tool's `errorMessage`, or the unknown-outcome result: the function failed before it finished, so whether it took effect is unknown, with a tool prompt not to tell the caller it worked or that it didn't. A crash can come after the work was done, so the model mustn't read it as a failure. See [defineTool()](api-reference.md#definetoolopts).
|
|
161
166
|
|
|
162
167
|
Tools registered with `defineTool()` are secure by default. The SWML the agent renders gives each secure tool a per-call token (`__token`). The agent runs the handler only when a `/swaig` request carries a valid token for that function and call. Otherwise it returns a refusal response. Set `swaigSecret` or `SIGNALWIRE_SWAIG_SECRET` so tokens survive a restart and work across replicas. For details, see [Secure Tools (HMAC Tokens)](security.md#secure-tools-hmac-tokens).
|
|
163
168
|
|
|
@@ -870,6 +875,29 @@ const result = new FunctionResult('The order is confirmed.').setSemanticState({
|
|
|
870
875
|
});
|
|
871
876
|
```
|
|
872
877
|
|
|
878
|
+
### setSemanticGateMark
|
|
879
|
+
|
|
880
|
+
Set a mark that semantic gates with `since: name` judge the dialogue from: the agent's first turn at or after it, at most the gate's `history` entries (`semantic_gate_mark`). The mark is set as of the start of the action object that sets it, so a `say` in the same object is the first turn after it, and setting it again moves it. Marks last for the call; the platform keeps a call's 16 newest. It needs a platform release that has it. See [Semantic gates](api-reference.md#semantic-gates).
|
|
881
|
+
|
|
882
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
883
|
+
```typescript
|
|
884
|
+
setSemanticGateMark(name: string): this
|
|
885
|
+
```
|
|
886
|
+
|
|
887
|
+
| Parameter | Type | Description |
|
|
888
|
+
|-----------|----------|-----------------------------------------------------|
|
|
889
|
+
| `name` | `string` | The mark's name, 1 to 64 letters, digits or underscores. |
|
|
890
|
+
|
|
891
|
+
**Returns:** `this` for chaining.
|
|
892
|
+
|
|
893
|
+
**Throws:** `Error` for any other name, which the platform would refuse.
|
|
894
|
+
|
|
895
|
+
**Example:**
|
|
896
|
+
|
|
897
|
+
```typescript
|
|
898
|
+
const result = new FunctionResult('Read the order back.').setSemanticGateMark('read_back');
|
|
899
|
+
```
|
|
900
|
+
|
|
873
901
|
### removeGlobalData
|
|
874
902
|
|
|
875
903
|
Remove one or more keys from the global data (`unset_global_data`).
|
|
@@ -1077,6 +1105,29 @@ const result = new FunctionResult('The premium plan is confirmed. Collect paymen
|
|
|
1077
1105
|
.swmlChangeStep('collect_payment');
|
|
1078
1106
|
```
|
|
1079
1107
|
|
|
1108
|
+
### refreshStep
|
|
1109
|
+
|
|
1110
|
+
Enter the current step again, so its text shows new global data. A step's text is expanded once, when the step is entered, so its `${global_data.*}` values are the ones from then. After `updateGlobalData()` changes one, add `refreshStep()` with the current step's name, after the update, and the model gets the step's text again with the new values. It's the same action as `swmlChangeStep(stepName)`: entering a step starts it over, and its `history` mode applies again.
|
|
1111
|
+
|
|
1112
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1113
|
+
```typescript
|
|
1114
|
+
refreshStep(stepName: string): this
|
|
1115
|
+
```
|
|
1116
|
+
|
|
1117
|
+
| Parameter | Type | Description |
|
|
1118
|
+
|------------|----------|------------------------------|
|
|
1119
|
+
| `stepName` | `string` | The name of the current step. |
|
|
1120
|
+
|
|
1121
|
+
**Returns:** `this` for chaining.
|
|
1122
|
+
|
|
1123
|
+
**Example:**
|
|
1124
|
+
|
|
1125
|
+
```typescript
|
|
1126
|
+
const result = new FunctionResult('Added the drink.')
|
|
1127
|
+
.updateGlobalData({ order_total: '$14.50' })
|
|
1128
|
+
.refreshStep('take_order');
|
|
1129
|
+
```
|
|
1130
|
+
|
|
1080
1131
|
### swmlChangeContext
|
|
1081
1132
|
|
|
1082
1133
|
Move the conversation to another context (`change_context`). The context must exist in the agent's contexts, which you define with `defineContexts()`. A change from a tool isn't limited by `setValidContexts()`.
|
|
@@ -1182,6 +1233,47 @@ const r2 = new FunctionResult('Wait for the caller to answer.')
|
|
|
1182
1233
|
.enableFunctionsOnTimeout(false);
|
|
1183
1234
|
```
|
|
1184
1235
|
|
|
1236
|
+
### noBargeNextResponse
|
|
1237
|
+
|
|
1238
|
+
Have the next spoken reply play whole, such as a read-back the caller should hear in full before answering (`no_barge_next_response`). Until a reply that speaks has played, the caller's words neither cut it nor cancel its request: they're held and delivered after it. For semantic gates, an answer begun during the reply reads as cutting it at that point, as a barge would. Needs a platform release that has the action.
|
|
1239
|
+
|
|
1240
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1241
|
+
```typescript
|
|
1242
|
+
noBargeNextResponse(): this
|
|
1243
|
+
```
|
|
1244
|
+
|
|
1245
|
+
**Returns:** `this` for chaining.
|
|
1246
|
+
|
|
1247
|
+
**Example:**
|
|
1248
|
+
|
|
1249
|
+
```typescript
|
|
1250
|
+
const result = new FunctionResult('Read the order back to the caller.').noBargeNextResponse();
|
|
1251
|
+
```
|
|
1252
|
+
|
|
1253
|
+
### backToBackFunctions
|
|
1254
|
+
|
|
1255
|
+
Set whether the model may call another function right after a function result, without answering in words first (`back_to_back_functions`). `'forever'`, the call's default, chains freely. `false` makes the model answer in words after a function result. `true`, while chaining is off, allows one more chain, and then it's off again; it never lowers `'forever'`. The setting lasts for the call. Realtime models don't read it.
|
|
1256
|
+
|
|
1257
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1258
|
+
```typescript
|
|
1259
|
+
backToBackFunctions(value?: boolean | 'forever'): this
|
|
1260
|
+
```
|
|
1261
|
+
|
|
1262
|
+
| Parameter | Type | Default | Description |
|
|
1263
|
+
|-----------|-------------------------|---------|-----------------------------------|
|
|
1264
|
+
| `value` | `boolean \| 'forever'` | `true` | The chaining setting for the call. |
|
|
1265
|
+
|
|
1266
|
+
**Returns:** `this` for chaining.
|
|
1267
|
+
|
|
1268
|
+
**Throws:** `Error` for any other value, which the platform ignores.
|
|
1269
|
+
|
|
1270
|
+
**Example:**
|
|
1271
|
+
|
|
1272
|
+
```typescript
|
|
1273
|
+
// A read-back the caller must answer before anything else runs
|
|
1274
|
+
const result = new FunctionResult('Read the order back to the caller.').backToBackFunctions(false);
|
|
1275
|
+
```
|
|
1276
|
+
|
|
1185
1277
|
### updateSettings
|
|
1186
1278
|
|
|
1187
1279
|
Update AI settings during the call (`settings`). The platform validates the keys. The Python SDK's reference lists `temperature`, `top-p`, `max-tokens`, `frequency-penalty`, `presence-penalty`, `confidence` and `barge-confidence`.
|