@signalwire/sdk 3.7.1 → 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 +214 -0
- package/README.md +1 -0
- package/dist/AgentBase.d.ts +120 -3
- package/dist/AgentBase.js +291 -18
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +30 -6
- package/dist/AgentServer.js +28 -2
- package/dist/AgentServer.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 +197 -14
- package/dist/ContextBuilder.js +422 -13
- 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/Logger.d.ts +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 +151 -10
- package/dist/SWMLService.js +377 -61
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.js +14 -1
- package/dist/SchemaUtils.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/SessionManager.d.ts +17 -6
- package/dist/SessionManager.js +16 -3
- package/dist/SessionManager.js.map +1 -1
- package/dist/SwaigFunction.d.ts +86 -9
- package/dist/SwaigFunction.js +215 -59
- 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 +2 -2
- package/dist/TypeInference.js +1 -1
- package/dist/TypeInference.js.map +1 -1
- package/dist/ai-chat/ChatGateway.d.ts +5 -5
- package/dist/ai-chat/HandoffRouter.d.ts +3 -3
- 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 +23 -8
- package/dist/index.js +16 -5
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +3 -0
- package/dist/livewire/index.js +3 -0
- package/dist/livewire/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/relay/Call.d.ts +1 -1
- package/dist/relay/Call.js +1 -1
- package/dist/relay/Message.d.ts +1 -1
- package/dist/relay/Message.js +1 -1
- package/dist/relay/RelayClient.d.ts +0 -2
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +3 -3
- package/dist/relay/RelayEvent.js +3 -3
- package/dist/relay/closedSets.d.ts +10 -10
- package/dist/relay/closedSets.js +2 -2
- package/dist/relay/types.d.ts +1 -1
- package/dist/rest/base/CrudResource.d.ts +1 -1
- package/dist/rest/base/CrudResource.js +1 -1
- package/dist/skills/SkillBase.d.ts +26 -3
- package/dist/skills/SkillBase.js +14 -3
- 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 +4 -4
- package/docs/api-reference.md +285 -28
- package/docs/architecture.md +8 -4
- package/docs/cli-guide.md +2 -0
- package/docs/contexts-guide.md +47 -4
- package/docs/conversation_patterns.md +257 -0
- package/docs/mcp_integration.md +1 -1
- package/docs/pgi_agent_guide.md +2 -1
- package/docs/programmatically_governed_inference.md +2 -2
- package/docs/swaig-reference.md +95 -3
- package/docs/swml_service_guide.md +31 -6
- package/package.json +3 -1
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,220 @@
|
|
|
3
3
|
All notable changes to `@signalwire/sdk` are documented here. This project
|
|
4
4
|
follows [Semantic Versioning](https://semver.org/).
|
|
5
5
|
|
|
6
|
+
## 3.9.0 (2026-11-13)
|
|
7
|
+
|
|
8
|
+
Parity with signalwire-python 3.9.0: tool-name and reset checks, a
|
|
9
|
+
`noBargeNextResponse()` action, and doc fixes after 3.8.0. It's the first
|
|
10
|
+
release with the 3.8.0 changes below.
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Rendering logs `tool_named_but_not_offered`, once each, when a step that
|
|
15
|
+
lists its functions names a registered tool it doesn't offer: in its text,
|
|
16
|
+
its criteria, its context's prompt, a gather question, or a gate's output on
|
|
17
|
+
one of its tools. The model reads the name and may call a tool it doesn't
|
|
18
|
+
have. `namedTools(text, tools)` finds the names; a one-word name counts only
|
|
19
|
+
in backticks or before "(".
|
|
20
|
+
- `FunctionResult.noBargeNextResponse()` has the next spoken reply play whole,
|
|
21
|
+
with what the caller says during it held until after it. It needs a platform
|
|
22
|
+
release that has the action.
|
|
23
|
+
- Rendering logs `step_reset_is_terminal` for a step with a reset, whose text
|
|
24
|
+
the platform never runs, and `context_reset_without_system_prompt` for a
|
|
25
|
+
context's consolidate, full reset or user prompt, which act only with a
|
|
26
|
+
system prompt. Each is logged once, across per-request copies too.
|
|
27
|
+
- `new CallSimulator(agent, { checkToolMentions: true })` rejects a call with
|
|
28
|
+
`ToolMentionError` when its result names a tool the step it leaves the call
|
|
29
|
+
in doesn't offer.
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
|
|
33
|
+
- The docs said a slow tool can run more than once on a retry; since 3.8.0 the
|
|
34
|
+
agent answers a retry with the first attempt's result. They now say the
|
|
35
|
+
record is kept per process, so with several replicas a retry that reaches
|
|
36
|
+
another one runs the tool again.
|
|
37
|
+
- `Context.setIsolated()` says what the platform does: it drops every entry
|
|
38
|
+
but the base prompt, rather than the whole conversation.
|
|
39
|
+
- The step reset methods say what the platform does: a step with a reset is
|
|
40
|
+
terminal. The `next_step` schema is rewritten when a step loads, not every
|
|
41
|
+
turn.
|
|
42
|
+
|
|
43
|
+
## 3.8.0 (2026-11-13)
|
|
44
|
+
|
|
45
|
+
Tagged but not published: its changes first ship in 3.9.0.
|
|
46
|
+
|
|
47
|
+
Parity with signalwire-python 3.8.0, the voice-agent toolkit: newer semantic
|
|
48
|
+
gate keys, tool outcomes and options, tool middleware with retry dedupe, the
|
|
49
|
+
caller's own words, speech helpers, conversation patterns and a call
|
|
50
|
+
simulator. The gate keys, `semantic_gate_dialogue`,
|
|
51
|
+
`unavailable_function_response`, `semantic_gate_mark` and `expected_answer`
|
|
52
|
+
need a platform release that has them: one with gates but without a key
|
|
53
|
+
refuses the function, as it treats an unknown gate key as an error.
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
|
|
57
|
+
- Semantic gates take the platform's newer keys. `new SemanticGate(question,
|
|
58
|
+
threshold, onFail, { dialogue, history })` sets the dialogue one gate
|
|
59
|
+
judges, `'window'` or `'proposal'` and 1 to 100 entries, in place of the
|
|
60
|
+
agent's; every gate of a function must set the same ones, as the platform
|
|
61
|
+
requires, and rendering throws when they differ. `unclear: true` asks yes,
|
|
62
|
+
no or unclear, and `onUnclear` is what the model gets for an unclear
|
|
63
|
+
answer. `since` anchors a gate's dialogue at a mark your code sets with the
|
|
64
|
+
new `FunctionResult.setSemanticGateMark(name)` action.
|
|
65
|
+
`setSemanticGates({ dialogue })` sets the agent's `semantic_gate_dialogue`.
|
|
66
|
+
- `setUnavailableFunctionResponse(text)` sets what the model is told when it
|
|
67
|
+
calls a tool it can't use now, with `${function}`, `${tools}` and
|
|
68
|
+
`${steps}`.
|
|
69
|
+
- `defineTool({ vouched: true })` adds a required boolean argument,
|
|
70
|
+
`data_supplied_by_user`, in which the model says every argument came from
|
|
71
|
+
the caller. Unless it's true, the handler doesn't run, and the model is
|
|
72
|
+
told to get the answer from the caller first.
|
|
73
|
+
- `ToolRefusal`: throw `new ToolRefusal(toolResult, toolPrompt)` from a
|
|
74
|
+
handler or middleware to decline a call with an outcome you know. It
|
|
75
|
+
bypasses the `onError` hooks.
|
|
76
|
+
- `FunctionResult.backToBackFunctions(value)` sets whether the model may call
|
|
77
|
+
another function right after a result (`true`, `false` or `'forever'`).
|
|
78
|
+
- `FunctionResult.refreshStep(name)` enters the current step again, so step
|
|
79
|
+
text that shows `${global_data.*}` values, which are expanded once on
|
|
80
|
+
entry, shows the new ones.
|
|
81
|
+
- `Step.setExpectedAnswer(digits)` (or `{ minDigits, maxDigits }`), the
|
|
82
|
+
`expectedAnswer()` helper and a gather question's `expectedAnswer` tell the
|
|
83
|
+
recognizer how many digits the caller's answer has, so it ends its wait
|
|
84
|
+
once they're said.
|
|
85
|
+
- `defineTool({ nullableOptional: true })` and
|
|
86
|
+
`setNullableOptionalParameters()` let the model send null for optional
|
|
87
|
+
arguments, as strict provider schemas require; a null reaches the handler
|
|
88
|
+
as an argument not given.
|
|
89
|
+
- `defineNativeTool(name, description, parameters?, fields?)` defines a
|
|
90
|
+
function the platform implements itself, sent with `web_hook_url:
|
|
91
|
+
"native"`, under your own description.
|
|
92
|
+
- Tool middleware: `addToolMiddleware(fn)` and `defineTool({ middleware })`
|
|
93
|
+
run `fn(name, args, rawData, callNext)` around tool calls; `callNext`
|
|
94
|
+
returns a promise of the handler's result. On `SWMLService` too, so a
|
|
95
|
+
plain service's tools have them.
|
|
96
|
+
- A transport retry of a tool request no longer runs the tool twice.
|
|
97
|
+
SignalWire sends a request again, with the same `tool_call_id`, after a
|
|
98
|
+
timeout, a failed connection or a 5xx; the agent answers the retry with
|
|
99
|
+
the first attempt's result, and one that arrives while the first is still
|
|
100
|
+
running waits for it. A call the model makes again has a new
|
|
101
|
+
`tool_call_id` and runs. On by default, and shared with per-request
|
|
102
|
+
copies; `setToolResendDedupe(false)` turns it off. The state lives in the
|
|
103
|
+
process, so replicas each keep their own.
|
|
104
|
+
- The caller's own words in a handler: `callerTurns(rawData)` reads what the
|
|
105
|
+
caller said from the request's conversation, and `defineTool({
|
|
106
|
+
needsConversation: true })` turns on `swaig_post_conversation` so requests
|
|
107
|
+
carry it. `recordSpeechFinals()` and `speechFinals(callId)` keep the
|
|
108
|
+
recognizer's finals with their word confidences, from the platform's
|
|
109
|
+
`ai.speech_detect` events, and `onAiEvent(handler)` receives every AI
|
|
110
|
+
event; the agent sets `event_webhook_url` to its new `/ai_events` endpoint
|
|
111
|
+
for them (POST, JSON, size-limited, authenticated and signature-checked as
|
|
112
|
+
the agent's other endpoints are). Register them on the agent, not in a
|
|
113
|
+
per-request callback.
|
|
114
|
+
- Speech helpers: `sayDigits`, `sayLastDigits`, `sayMoney` and `numberWords`
|
|
115
|
+
give the words a voice should say for digits and amounts, which
|
|
116
|
+
`addPronunciation` can't fix, since the platform normalizes text before its
|
|
117
|
+
pronunciation rules run. `sayMoney` takes a number, a bigint or a decimal
|
|
118
|
+
string and rounds half up from its decimal digits. `readSpelled` reads what
|
|
119
|
+
a caller spelled (letters, letter names, "S as in Sam", NATO words, "double
|
|
120
|
+
l", digits), `spokenEmail` reads an address said aloud, and
|
|
121
|
+
`spellingVariants` expands letters the recognizer confuses, with groups you
|
|
122
|
+
supply.
|
|
123
|
+
- `Proposal` is the platform's confirm pattern: `propose()` reads a change
|
|
124
|
+
back and records it in `semantic_state` in one action object, and
|
|
125
|
+
`confirmGates()` gives the confirm tool the three gates (answered, agreed,
|
|
126
|
+
read back) judged on the proposal's dialogue, with an `onFail` that quotes
|
|
127
|
+
the proposal. `askAgain()` and `complete()` round it out.
|
|
128
|
+
- `RequestList` keeps what the caller asked for while the agent was busy, in
|
|
129
|
+
the call's `global_data`, with step text that lists it, to take up when the
|
|
130
|
+
current task is done.
|
|
131
|
+
- `CallSimulator` runs an agent's tools through a simulated call, checked as
|
|
132
|
+
the platform checks them: the step's function list (with the platform's
|
|
133
|
+
reply for a tool it won't run), the semantic gates from a callback, and
|
|
134
|
+
each result's actions on the call's state. Tools run as the `/swaig` route
|
|
135
|
+
runs them. `RequestRecorder` middleware records tool requests for
|
|
136
|
+
`CallSimulator.replay()`.
|
|
137
|
+
- [Conversation Patterns](docs/conversation_patterns.md), a new guide.
|
|
138
|
+
- `ContextBuilder.stepsOffering(name)` lists the steps whose function lists
|
|
139
|
+
name a tool. Rendering logs `tool_offered_by_no_step` once for a
|
|
140
|
+
registered tool that no step offers, when every step lists its functions.
|
|
141
|
+
|
|
142
|
+
### Changed
|
|
143
|
+
|
|
144
|
+
- A tool handler that throws now tells the model the function failed before
|
|
145
|
+
it finished, so whether it took effect is unknown, with a tool prompt not
|
|
146
|
+
to tell the caller it worked or that it didn't. It used to return "Sorry, I
|
|
147
|
+
couldn't complete that action. Please try again or contact support if the
|
|
148
|
+
issue persists.", which let the model guess the outcome. The error is
|
|
149
|
+
logged; the `onError` hooks and a tool's `errorMessage` still come first.
|
|
150
|
+
`DEFAULT_SWAIG_ERROR_MESSAGE` is deprecated.
|
|
151
|
+
- A handler that returns an object with neither `response` nor `action` gives
|
|
152
|
+
the model the object as JSON, and an empty object says the outcome is
|
|
153
|
+
unknown. It used to answer "Function completed successfully", dropping the
|
|
154
|
+
object. A handler that returns nothing answers "Function executed
|
|
155
|
+
successfully"; it used to answer "undefined". Handler types allow `void`.
|
|
156
|
+
- A plain `SWMLService`'s `/swaig` route runs tools with the same rules as an
|
|
157
|
+
agent's: the vouched check, middleware, the retry dedupe and the outcome
|
|
158
|
+
rules.
|
|
159
|
+
|
|
160
|
+
## 3.7.2 (2026-11-12)
|
|
161
|
+
|
|
162
|
+
Parity with signalwire-python 3.7.7: the chat-session token fix, a plain
|
|
163
|
+
`SWMLService` on an `AgentServer`, the `isolate` history mode and the schema
|
|
164
|
+
validator warning.
|
|
165
|
+
|
|
166
|
+
### Added
|
|
167
|
+
|
|
168
|
+
- A step's or context's history mode can be `"isolate"`:
|
|
169
|
+
`step.setHistory('isolate')`. While the agent is in the step, the model
|
|
170
|
+
sees none of the earlier dialogue and none of the earlier step
|
|
171
|
+
instructions, as with `"hide"`. When the agent leaves the step, the
|
|
172
|
+
earlier dialogue comes back, and the step's own turns stay; the earlier
|
|
173
|
+
instructions stay cleared, and what an earlier `"hide"` step hid stays
|
|
174
|
+
hidden. Entering the step again isolates it again. On a context, it
|
|
175
|
+
applies to every step that doesn't set its own mode. A platform without
|
|
176
|
+
isolate treats it as `"default"`. Parity with signalwire-python 3.7.7.
|
|
177
|
+
|
|
178
|
+
### Fixed
|
|
179
|
+
|
|
180
|
+
- A chat session's post-prompt summary was refused with `403`, so its
|
|
181
|
+
transcript never saved. The chat service fetches an agent's SWML under the
|
|
182
|
+
conversation's id, so the SDK mints that SWML's tokens for the
|
|
183
|
+
conversation, but the summary can arrive under the chat service's own call
|
|
184
|
+
id, with the conversation's id as `conversation_id`. A token is now
|
|
185
|
+
accepted when it names the request's `call_id` or its `conversation_id`,
|
|
186
|
+
for post-prompt summaries and secure functions alike. A voice call, where
|
|
187
|
+
the two are the same, is unchanged, and the token still has to name this
|
|
188
|
+
call or conversation. A `call_id` that isn't a non-empty string is
|
|
189
|
+
refused, and an accepted chat request logs no token mismatch. Parity with
|
|
190
|
+
signalwire-python 3.7.4 (#166).
|
|
191
|
+
- `AgentServer` hosts a plain `SWMLService` next to its agents, as
|
|
192
|
+
signalwire-python 3.7.6 does. Registering one made every request under its
|
|
193
|
+
route answer with 500. Use `new AgentServer<SWMLService>()`:
|
|
194
|
+
`AgentServer<T extends SWMLService = AgentBase>` is now generic over what
|
|
195
|
+
it hosts, so `getAgent()` and `getAgents()` keep returning agents on a
|
|
196
|
+
plain `new AgentServer()`. The service answers at its route with or
|
|
197
|
+
without a trailing slash, under its own basic auth, and serves its
|
|
198
|
+
`/swaig` endpoint and routing callbacks; the agent endpoints
|
|
199
|
+
(`/post_prompt`, `/check_for_input`, `/debug`) aren't served for it.
|
|
200
|
+
- `SWMLService.asRouter()` returns a router whose routes are relative to
|
|
201
|
+
the service's route, as the reference's `as_router()` does, so a host can
|
|
202
|
+
mount it at any prefix. It returned the service's own app, so a service at
|
|
203
|
+
`/menu` mounted at `/menu` served `/menu/menu`. The router's own routes
|
|
204
|
+
and callbacks carry the service's security headers, CORS and basic auth,
|
|
205
|
+
and it has no middleware for every path, so it leaves a host's other
|
|
206
|
+
routes alone; a route you add to the router checks auth itself, as with
|
|
207
|
+
`AgentBase.asRouter()`. A `SWMLService` route
|
|
208
|
+
drops a trailing slash (`/menu/` is stored as `/menu`), as the reference
|
|
209
|
+
does, so it's served the same mounted or on its own.
|
|
210
|
+
- A plain `SWMLService` serves its routing callbacks under its route
|
|
211
|
+
(`/menu/sip`), as the reference does, and still at the bare path
|
|
212
|
+
(`/sip`), where earlier releases served them. A callback registered after
|
|
213
|
+
the service has served a request now answers; it used to throw.
|
|
214
|
+
- Where the SWML schema can't be compiled, as on a runtime that blocks code
|
|
215
|
+
generation from strings (Cloudflare Workers), verb validation falls back
|
|
216
|
+
to checking verb names and required fields, and now logs
|
|
217
|
+
`schema_validator_unavailable` once instead of falling back silently, as
|
|
218
|
+
signalwire-python 3.7.2 does.
|
|
219
|
+
|
|
6
220
|
## 3.7.1 (2026-10-14)
|
|
7
221
|
|
|
8
222
|
Parity with signalwire-python 3.7.1, and `onCallStart()` from its main branch (#118).
|
package/README.md
CHANGED
|
@@ -265,6 +265,7 @@ The [`docs/`](docs/) directory has these guides. They're installed with the pack
|
|
|
265
265
|
|
|
266
266
|
- [SWAIG Reference](docs/swaig-reference.md): function results, actions, post_data lifecycle
|
|
267
267
|
- [Contexts and Steps](docs/contexts-guide.md): structured workflows, navigation, gather mode
|
|
268
|
+
- [Conversation Patterns](docs/conversation_patterns.md): confirming a change, the caller's own words, numbers to say, testing a call flow
|
|
268
269
|
- [DataMap Guide](docs/datamap-guide.md): serverless API tools without webhooks
|
|
269
270
|
- [LLM Parameters](docs/llm_parameters.md): temperature, top_p, barge settings
|
|
270
271
|
- [SWML Service Guide](docs/swml_service_guide.md): low-level construction of SWML documents
|
package/dist/AgentBase.d.ts
CHANGED
|
@@ -10,10 +10,17 @@ import type { HostAppRouter } from './web.js';
|
|
|
10
10
|
import { PromptManager } from './PromptManager.js';
|
|
11
11
|
import { PromptObjectModel } from './POM/PromptObjectModel.js';
|
|
12
12
|
import { SWMLService } from './SWMLService.js';
|
|
13
|
+
import type { ToolMiddleware } from './ToolMiddleware.js';
|
|
14
|
+
import { type SpeechFinal } from './AiEvents.js';
|
|
15
|
+
/**
|
|
16
|
+
* A handler for the AI events the platform posts during calls, as
|
|
17
|
+
* {@link AgentBase.onAiEvent} registers it.
|
|
18
|
+
*/
|
|
19
|
+
export type AiEventHandler = (eventType: string, params: Record<string, unknown>, event: Record<string, unknown>) => unknown;
|
|
13
20
|
import { SwaigFunction, type SwaigErrorHandler } from './SwaigFunction.js';
|
|
14
21
|
import { type FillerPhrases, type SemanticGate } from './SemanticGate.js';
|
|
15
22
|
import { type TypedToolHandler } from './TypeInference.js';
|
|
16
|
-
import { FunctionResult } from './FunctionResult.js';
|
|
23
|
+
import { FunctionResult, type SwaigResultDict } from './FunctionResult.js';
|
|
17
24
|
import { ContextBuilder } from './ContextBuilder.js';
|
|
18
25
|
import { type Logger } from './Logger.js';
|
|
19
26
|
import { SkillManager } from './skills/SkillManager.js';
|
|
@@ -45,7 +52,7 @@ export type RoutingCallback = (body: SwmlRequestData, headers?: Record<string, s
|
|
|
45
52
|
* - `POST /post_prompt` receives the end-of-call summary and invokes {@link onSummary}
|
|
46
53
|
*
|
|
47
54
|
* Most user agents either (a) subclass `AgentBase` and override `defineTools()` / `onSummary()`
|
|
48
|
-
* or (b) use one of the
|
|
55
|
+
* or (b) use one of the prefab agents (e.g. {@link ReceptionistAgent}).
|
|
49
56
|
*
|
|
50
57
|
* @example Subclass with a custom tool
|
|
51
58
|
* ```ts
|
|
@@ -126,6 +133,10 @@ export declare class AgentBase extends SWMLService {
|
|
|
126
133
|
private perCallConfigs;
|
|
127
134
|
/** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
|
|
128
135
|
private _serving;
|
|
136
|
+
/** Handlers registered with {@link onAiEvent}. */
|
|
137
|
+
private _aiEventHandlers;
|
|
138
|
+
/** The recognizer's finals per call, once {@link recordSpeechFinals} is on. */
|
|
139
|
+
private _speechLog;
|
|
129
140
|
/** Handlers registered with {@link onCallStart}. */
|
|
130
141
|
private callStartHandlers;
|
|
131
142
|
/** Handlers registered with {@link onCallEnd}. */
|
|
@@ -136,6 +147,8 @@ export declare class AgentBase extends SWMLService {
|
|
|
136
147
|
private webHookUrlOverride;
|
|
137
148
|
private postPromptUrlOverride;
|
|
138
149
|
private contextsBuilder;
|
|
150
|
+
/** Tools the contexts reported as offered by no step; shared with per-request copies. */
|
|
151
|
+
private _unofferedToolsWarned;
|
|
139
152
|
/** Contexts given as a plain object, rendered as they are. */
|
|
140
153
|
private _rawContexts;
|
|
141
154
|
private _mcpServers;
|
|
@@ -549,6 +562,14 @@ export declare class AgentBase extends SWMLService {
|
|
|
549
562
|
* `semantic_gate_timeout_ms`.
|
|
550
563
|
* @param opts.history - How many recent dialogue entries the decision model
|
|
551
564
|
* sees, 0 to 100. Default 20. Sent as `semantic_gate_history`.
|
|
565
|
+
* @param opts.dialogue - Which dialogue the decision model judges:
|
|
566
|
+
* `'window'`, the newest `history` entries, or `'proposal'`, those since
|
|
567
|
+
* `global_data.semantic_state` last changed (see
|
|
568
|
+
* {@link FunctionResult.setSemanticState}), from the agent's first turn
|
|
569
|
+
* after it: the read-back and the caller's reply. With no
|
|
570
|
+
* `semantic_state` set, the window. A gate's own `dialogue` and `history`
|
|
571
|
+
* take the place of these for its function. Default `'window'`. Sent as
|
|
572
|
+
* `semantic_gate_dialogue`; it needs a platform release that has it.
|
|
552
573
|
* @returns This agent instance for chaining.
|
|
553
574
|
* @throws {Error} When a value has the wrong type or is out of range.
|
|
554
575
|
*/
|
|
@@ -556,7 +577,23 @@ export declare class AgentBase extends SWMLService {
|
|
|
556
577
|
enabled?: boolean;
|
|
557
578
|
timeoutMs?: number;
|
|
558
579
|
history?: number;
|
|
580
|
+
dialogue?: 'window' | 'proposal';
|
|
559
581
|
}): this;
|
|
582
|
+
/**
|
|
583
|
+
* Set what the model is told when it calls a tool it can't use now.
|
|
584
|
+
*
|
|
585
|
+
* Without it, the platform says nothing ran, which steps offer the tool, and
|
|
586
|
+
* which tools are available now. `text` takes its place, with `${function}`
|
|
587
|
+
* for the tool's name, `${tools}` for the tools the request offered,
|
|
588
|
+
* comma-separated, and `${steps}` for the current context's steps whose
|
|
589
|
+
* functions include it (empty for a name the agent doesn't have). Sent as
|
|
590
|
+
* the `unavailable_function_response` param; it needs a platform release
|
|
591
|
+
* that has it.
|
|
592
|
+
* @param text - The text.
|
|
593
|
+
* @returns This agent instance for chaining.
|
|
594
|
+
* @throws {Error} When `text` isn't a non-empty string.
|
|
595
|
+
*/
|
|
596
|
+
setUnavailableFunctionResponse(text: string): this;
|
|
560
597
|
/**
|
|
561
598
|
* **MERGES** `data` into the global_data object passed into the AI
|
|
562
599
|
* configuration. **Despite the name, this does NOT replace** the existing
|
|
@@ -826,6 +863,14 @@ export declare class AgentBase extends SWMLService {
|
|
|
826
863
|
gates?: ReadonlyArray<SemanticGate | Record<string, unknown>>;
|
|
827
864
|
/** Phrases said while the gates are checked (see `SwaigFunctionOptions.gateFillers`). */
|
|
828
865
|
gateFillers?: FillerPhrases;
|
|
866
|
+
/** Whether the model must vouch for the arguments (see `SwaigFunctionOptions.vouched`). */
|
|
867
|
+
vouched?: boolean;
|
|
868
|
+
/** Whether optional arguments take null (see `SwaigFunctionOptions.nullableOptional`). */
|
|
869
|
+
nullableOptional?: boolean;
|
|
870
|
+
/** Whether the handler reads the conversation (see `SwaigFunctionOptions.needsConversation`). */
|
|
871
|
+
needsConversation?: boolean;
|
|
872
|
+
/** Middleware around this tool's calls (see `SwaigFunctionOptions.middleware`). */
|
|
873
|
+
middleware?: readonly ToolMiddleware[];
|
|
829
874
|
}): this;
|
|
830
875
|
/**
|
|
831
876
|
* Validate a tool-call token for the given function.
|
|
@@ -1049,6 +1094,58 @@ export declare class AgentBase extends SWMLService {
|
|
|
1049
1094
|
* @returns This agent instance for chaining.
|
|
1050
1095
|
*/
|
|
1051
1096
|
addPerCallConfig(cb: DynamicConfigCallback): this;
|
|
1097
|
+
/**
|
|
1098
|
+
* Register a handler for the AI events the platform posts during calls.
|
|
1099
|
+
*
|
|
1100
|
+
* The agent sets the call's `event_webhook_url` to its own `/ai_events`
|
|
1101
|
+
* endpoint, unless you set `event_webhook_url` yourself, and calls each
|
|
1102
|
+
* handler with every event posted there. An event is `ai.speech_detect` for
|
|
1103
|
+
* each final of the caller's speech, with its `text` and the recognizer's
|
|
1104
|
+
* `words` and confidences, or one of the platform's other AI events.
|
|
1105
|
+
* Register handlers on the agent, not in a per-call configuration callback:
|
|
1106
|
+
* the endpoint runs on the agent. The handler may be async; its return value
|
|
1107
|
+
* is ignored, and an error is logged.
|
|
1108
|
+
* @param handler - Called with `(eventType, params, event)`: the event, such
|
|
1109
|
+
* as `'ai.speech_detect'`; its fields, with the `call_id`; and the whole
|
|
1110
|
+
* event as posted, with its `timestamp`.
|
|
1111
|
+
* @returns The handler.
|
|
1112
|
+
*
|
|
1113
|
+
* @example
|
|
1114
|
+
* ```ts
|
|
1115
|
+
* agent.onAiEvent((eventType, params) => {
|
|
1116
|
+
* if (eventType === 'ai.speech_detect') console.log(params['call_id'], params['text']);
|
|
1117
|
+
* });
|
|
1118
|
+
* ```
|
|
1119
|
+
*/
|
|
1120
|
+
onAiEvent(handler: AiEventHandler): AiEventHandler;
|
|
1121
|
+
/**
|
|
1122
|
+
* Keep each call's recognizer finals, with their word confidences, for tool
|
|
1123
|
+
* handlers to read with {@link speechFinals}.
|
|
1124
|
+
*
|
|
1125
|
+
* A final is what the recognizer heard for one turn of the caller's, from
|
|
1126
|
+
* the platform's `ai.speech_detect` event: `{ text, words, timestamp }`, with
|
|
1127
|
+
* `words` as `[{ word, confidence }]` as heard, before hearing hints and
|
|
1128
|
+
* number formatting change the text. A handler can ask the caller again
|
|
1129
|
+
* about a word the recognizer wasn't sure of, such as a letter of a spelled
|
|
1130
|
+
* name. Like {@link onAiEvent}, it sets the call's `event_webhook_url` to the
|
|
1131
|
+
* agent's `/ai_events`, unless you set it yourself. A call with
|
|
1132
|
+
* `redact_prompt` sends no finals unless debug is on. The finals live in the
|
|
1133
|
+
* process: replicas each keep their own.
|
|
1134
|
+
* @param maxCalls - The most calls to keep finals for; the oldest call's go first.
|
|
1135
|
+
* @param maxFinals - The most finals to keep for one call.
|
|
1136
|
+
* @returns This agent instance for chaining.
|
|
1137
|
+
*/
|
|
1138
|
+
recordSpeechFinals(maxCalls?: number, maxFinals?: number): this;
|
|
1139
|
+
/**
|
|
1140
|
+
* The recognizer's finals for a call, oldest first, once
|
|
1141
|
+
* {@link recordSpeechFinals} is on: `{ text, words, timestamp }`.
|
|
1142
|
+
* @param callId - The call, as a tool request's `rawData.call_id`.
|
|
1143
|
+
* @param since - Only the finals from this time on, in seconds since the
|
|
1144
|
+
* epoch (the event's `timestamp`).
|
|
1145
|
+
* @returns The finals, empty for a call with none or with recording off.
|
|
1146
|
+
*/
|
|
1147
|
+
speechFinals(callId: string, since?: number): SpeechFinal[];
|
|
1148
|
+
private warnIfEventWebhookTaken;
|
|
1052
1149
|
/**
|
|
1053
1150
|
* Register a handler that runs when the call starts, before the AI speaks.
|
|
1054
1151
|
*
|
|
@@ -1346,6 +1443,13 @@ export declare class AgentBase extends SWMLService {
|
|
|
1346
1443
|
* or void/undefined to proceed normally.
|
|
1347
1444
|
*/
|
|
1348
1445
|
onFunctionCall(_name: string, _args: Record<string, unknown>, _rawData: Record<string, unknown>): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
|
|
1446
|
+
/**
|
|
1447
|
+
* Run a tool on this agent as the `/swaig` route does once the request is
|
|
1448
|
+
* checked: its middleware, handler and outcome rules, with the agent's
|
|
1449
|
+
* error hook. The MCP bridge and the call simulator run tools through it too.
|
|
1450
|
+
* @internal
|
|
1451
|
+
*/
|
|
1452
|
+
_executeFunction(fn: SwaigFunction, args: Record<string, unknown>, rawData: Record<string, unknown>): Promise<SwaigResultDict>;
|
|
1349
1453
|
/**
|
|
1350
1454
|
* Extract the tool-call arguments from a SWAIG request body.
|
|
1351
1455
|
*
|
|
@@ -1371,11 +1475,24 @@ export declare class AgentBase extends SWMLService {
|
|
|
1371
1475
|
* missing `call_id`, is refused like a wrong token. A non-secure function
|
|
1372
1476
|
* runs without a token.
|
|
1373
1477
|
*
|
|
1478
|
+
* The token may name the request's `call_id` or its `conversation_id`. A
|
|
1479
|
+
* chat session fetches its SWML, and so gets its tokens, under the
|
|
1480
|
+
* conversation's id, then sends every request under the chat service's own
|
|
1481
|
+
* call id, with the conversation's id beside it.
|
|
1482
|
+
*
|
|
1374
1483
|
* @returns The SWAIG response to send instead of running the function, or
|
|
1375
1484
|
* `null` when the function may run.
|
|
1376
1485
|
*/
|
|
1377
1486
|
private swaigTokenRefusal;
|
|
1378
|
-
|
|
1487
|
+
/**
|
|
1488
|
+
* Whether `token` was minted for `functionName` and the request's call:
|
|
1489
|
+
* its `call_id`, or its `conversation_id` when it names a different one.
|
|
1490
|
+
* The request must name a call: a `call_id` that isn't a non-empty string
|
|
1491
|
+
* is refused, so the conversation can't stand in for a malformed one.
|
|
1492
|
+
*/
|
|
1493
|
+
private tokenNamesCall;
|
|
1494
|
+
/** @internal The call simulator replays recorded requests through it. */
|
|
1495
|
+
_extractSwaigArgs(body: Record<string, unknown>, reqLog?: Logger): Record<string, unknown>;
|
|
1379
1496
|
/**
|
|
1380
1497
|
* Render the complete SWML document by assembling all 5 phases: pre-answer, answer,
|
|
1381
1498
|
* post-answer, AI, and post-AI verbs.
|