@signalwire/sdk 2.0.4 → 3.5.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 +785 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +550 -163
- package/dist/AgentBase.js +1640 -514
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +21 -0
- package/dist/AgentServer.js +154 -47
- package/dist/AgentServer.js.map +1 -1
- package/dist/AuthHandler.d.ts +14 -2
- package/dist/AuthHandler.js +7 -2
- package/dist/AuthHandler.js.map +1 -1
- package/dist/ConfigLoader.d.ts +5 -13
- package/dist/ConfigLoader.js +15 -29
- package/dist/ConfigLoader.js.map +1 -1
- package/dist/ContextBuilder.d.ts +202 -9
- package/dist/ContextBuilder.js +219 -36
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/DataMap.d.ts +158 -45
- package/dist/DataMap.js +167 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +277 -83
- package/dist/FunctionResult.js +444 -116
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +30 -5
- package/dist/Logger.js +77 -19
- package/dist/Logger.js.map +1 -1
- package/dist/POM/PromptObjectModel.d.ts +163 -0
- package/dist/POM/PromptObjectModel.js +481 -0
- package/dist/POM/PromptObjectModel.js.map +1 -0
- package/dist/ParameterSchema.d.ts +306 -0
- package/dist/ParameterSchema.js +251 -0
- package/dist/ParameterSchema.js.map +1 -0
- package/dist/PlatformContracts.d.ts +21 -0
- package/dist/PlatformContracts.generated.d.ts +109 -0
- package/dist/PlatformContracts.generated.js +8 -0
- package/dist/PlatformContracts.generated.js.map +1 -0
- package/dist/PlatformContracts.js +2 -0
- package/dist/PlatformContracts.js.map +1 -0
- package/dist/PomBuilder.d.ts +28 -0
- package/dist/PomBuilder.js +81 -3
- package/dist/PomBuilder.js.map +1 -1
- package/dist/PostPrompt.d.ts +110 -0
- package/dist/PostPrompt.js +204 -0
- package/dist/PostPrompt.js.map +1 -0
- package/dist/PromptManager.d.ts +29 -1
- package/dist/PromptManager.js +37 -1
- package/dist/PromptManager.js.map +1 -1
- package/dist/PublicFetch.d.ts +132 -0
- package/dist/PublicFetch.js +311 -0
- package/dist/PublicFetch.js.map +1 -0
- package/dist/RobotsTxt.d.ts +41 -0
- package/dist/RobotsTxt.js +152 -0
- package/dist/RobotsTxt.js.map +1 -0
- package/dist/SWMLHandler.js.map +1 -1
- package/dist/SWMLService.d.ts +265 -66
- package/dist/SWMLService.js +652 -112
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.d.ts +115 -2
- package/dist/SchemaUtils.js +444 -12
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SecurityUtils.d.ts +55 -8
- package/dist/SecurityUtils.js +162 -49
- package/dist/SecurityUtils.js.map +1 -1
- package/dist/ServerlessAdapter.d.ts +156 -7
- package/dist/ServerlessAdapter.js +399 -42
- package/dist/ServerlessAdapter.js.map +1 -1
- package/dist/SessionManager.d.ts +11 -2
- package/dist/SessionManager.js +50 -18
- package/dist/SessionManager.js.map +1 -1
- package/dist/SslConfig.d.ts +2 -1
- package/dist/SslConfig.js +4 -1
- package/dist/SslConfig.js.map +1 -1
- package/dist/SwaigActions.generated.d.ts +23 -0
- package/dist/SwaigActions.generated.js +8 -0
- package/dist/SwaigActions.generated.js.map +1 -0
- package/dist/SwaigContracts.d.ts +15 -0
- package/dist/SwaigContracts.generated.d.ts +264 -0
- package/dist/SwaigContracts.generated.js +12 -0
- package/dist/SwaigContracts.generated.js.map +1 -0
- package/dist/SwaigContracts.js +2 -0
- package/dist/SwaigContracts.js.map +1 -0
- package/dist/SwaigFunction.d.ts +110 -4
- package/dist/SwaigFunction.js +151 -19
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/SwmlBuilder.d.ts +68 -19
- package/dist/SwmlBuilder.js +74 -38
- package/dist/SwmlBuilder.js.map +1 -1
- package/dist/SwmlVerbMethods.generated.d.ts +41 -4
- package/dist/SwmlVerbMethods.generated.js +1 -1
- package/dist/TypeInference.d.ts +39 -3
- package/dist/TypeInference.js +256 -16
- package/dist/TypeInference.js.map +1 -1
- package/dist/WebService.d.ts +79 -11
- package/dist/WebService.js +320 -109
- package/dist/WebService.js.map +1 -1
- package/dist/WebhookMiddleware.d.ts +119 -0
- package/dist/WebhookMiddleware.js +271 -0
- package/dist/WebhookMiddleware.js.map +1 -0
- package/dist/WebhookValidator.d.ts +92 -0
- package/dist/WebhookValidator.js +409 -0
- package/dist/WebhookValidator.js.map +1 -0
- package/dist/agents/BedrockAgent.d.ts +162 -0
- package/dist/agents/BedrockAgent.js +323 -0
- package/dist/agents/BedrockAgent.js.map +1 -0
- package/dist/ai-chat/AIChatClient.d.ts +316 -0
- package/dist/ai-chat/AIChatClient.js +535 -0
- package/dist/ai-chat/AIChatClient.js.map +1 -0
- package/dist/ai-chat/ChatGateway.d.ts +408 -0
- package/dist/ai-chat/ChatGateway.js +747 -0
- package/dist/ai-chat/ChatGateway.js.map +1 -0
- package/dist/ai-chat/HandoffRouter.d.ts +282 -0
- package/dist/ai-chat/HandoffRouter.js +518 -0
- package/dist/ai-chat/HandoffRouter.js.map +1 -0
- package/dist/ai-chat/index.d.ts +12 -0
- package/dist/ai-chat/index.js +10 -0
- package/dist/ai-chat/index.js.map +1 -0
- package/dist/capabilities.d.ts +64 -0
- package/dist/capabilities.js +95 -0
- package/dist/capabilities.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +32 -6
- package/dist/cli/agent-loader.js +95 -34
- package/dist/cli/agent-loader.js.map +1 -1
- package/dist/cli/datamap-exec.d.ts +175 -0
- package/dist/cli/datamap-exec.js +1284 -0
- package/dist/cli/datamap-exec.js.map +1 -0
- package/dist/cli/function-args.d.ts +40 -0
- package/dist/cli/function-args.js +146 -0
- package/dist/cli/function-args.js.map +1 -0
- package/dist/cli/simulation.d.ts +99 -0
- package/dist/cli/simulation.js +490 -0
- package/dist/cli/simulation.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +12 -25
- package/dist/cli/swaig-test.js +935 -367
- package/dist/cli/swaig-test.js.map +1 -1
- package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
- package/dist/cli/tsdocs/agentsNote.js +92 -0
- package/dist/cli/tsdocs/agentsNote.js.map +1 -0
- package/dist/cli/tsdocs/api-index.json +1 -0
- package/dist/cli/tsdocs/api.d.ts +91 -0
- package/dist/cli/tsdocs/api.js +372 -0
- package/dist/cli/tsdocs/api.js.map +1 -0
- package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
- package/dist/cli/tsdocs/apiTypes.js +7 -0
- package/dist/cli/tsdocs/apiTypes.js.map +1 -0
- package/dist/cli/tsdocs/bin.d.ts +6 -0
- package/dist/cli/tsdocs/bin.js +23 -0
- package/dist/cli/tsdocs/bin.js.map +1 -0
- package/dist/cli/tsdocs/files.d.ts +108 -0
- package/dist/cli/tsdocs/files.js +287 -0
- package/dist/cli/tsdocs/files.js.map +1 -0
- package/dist/cli/tsdocs/index.d.ts +28 -0
- package/dist/cli/tsdocs/index.js +307 -0
- package/dist/cli/tsdocs/index.js.map +1 -0
- package/dist/cli/tsdocs/live.d.ts +41 -0
- package/dist/cli/tsdocs/live.js +202 -0
- package/dist/cli/tsdocs/live.js.map +1 -0
- package/dist/cli/tsdocs/locate.d.ts +51 -0
- package/dist/cli/tsdocs/locate.js +75 -0
- package/dist/cli/tsdocs/locate.js.map +1 -0
- package/dist/cli/tsdocs/render.d.ts +75 -0
- package/dist/cli/tsdocs/render.js +323 -0
- package/dist/cli/tsdocs/render.js.map +1 -0
- package/dist/cli/tsdocs/topics.d.ts +43 -0
- package/dist/cli/tsdocs/topics.js +916 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +102 -39
- package/dist/index.js +107 -30
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +229 -155
- package/dist/livewire/index.js +298 -195
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +65 -0
- package/dist/prefabs/CallSessionStore.d.ts +52 -0
- package/dist/prefabs/CallSessionStore.js +72 -0
- package/dist/prefabs/CallSessionStore.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +13 -1
- package/dist/prefabs/ConciergeAgent.js +36 -31
- package/dist/prefabs/ConciergeAgent.js.map +1 -1
- package/dist/prefabs/FAQBotAgent.d.ts +9 -1
- package/dist/prefabs/FAQBotAgent.js +113 -47
- package/dist/prefabs/FAQBotAgent.js.map +1 -1
- package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
- package/dist/prefabs/InfoGathererAgent.js +67 -58
- package/dist/prefabs/InfoGathererAgent.js.map +1 -1
- package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
- package/dist/prefabs/ReceptionistAgent.js +39 -31
- package/dist/prefabs/ReceptionistAgent.js.map +1 -1
- package/dist/prefabs/SurveyAgent.d.ts +22 -4
- package/dist/prefabs/SurveyAgent.js +84 -68
- package/dist/prefabs/SurveyAgent.js.map +1 -1
- package/dist/relay/Action.d.ts +44 -21
- package/dist/relay/Action.js +75 -17
- package/dist/relay/Action.js.map +1 -1
- package/dist/relay/Call.d.ts +312 -47
- package/dist/relay/Call.js +369 -18
- package/dist/relay/Call.js.map +1 -1
- package/dist/relay/Deferred.js.map +1 -1
- package/dist/relay/Message.d.ts +26 -5
- package/dist/relay/Message.js +36 -6
- package/dist/relay/Message.js.map +1 -1
- package/dist/relay/RelayClient.d.ts +79 -14
- package/dist/relay/RelayClient.js +268 -61
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayError.d.ts +14 -0
- package/dist/relay/RelayError.js +15 -0
- package/dist/relay/RelayError.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +96 -65
- package/dist/relay/RelayEvent.js +85 -56
- package/dist/relay/RelayEvent.js.map +1 -1
- package/dist/relay/closedSets.d.ts +111 -0
- package/dist/relay/closedSets.js +83 -0
- package/dist/relay/closedSets.js.map +1 -0
- package/dist/relay/index.d.ts +3 -1
- package/dist/relay/index.js +1 -0
- package/dist/relay/index.js.map +1 -1
- package/dist/relay/normalize.js.map +1 -1
- package/dist/relay/protocol.types.generated.d.ts +1195 -0
- package/dist/relay/protocol.types.generated.js +8 -0
- package/dist/relay/protocol.types.generated.js.map +1 -0
- package/dist/relay/types.d.ts +81 -39
- package/dist/rest/HttpClient.d.ts +36 -8
- package/dist/rest/HttpClient.js +233 -40
- package/dist/rest/HttpClient.js.map +1 -1
- package/dist/rest/RequestOptions.d.ts +110 -0
- package/dist/rest/RequestOptions.js +113 -0
- package/dist/rest/RequestOptions.js.map +1 -0
- package/dist/rest/RestError.d.ts +52 -6
- package/dist/rest/RestError.js +89 -5
- package/dist/rest/RestError.js.map +1 -1
- package/dist/rest/base/CrudResource.d.ts +16 -26
- package/dist/rest/base/CrudResource.js +19 -33
- package/dist/rest/base/CrudResource.js.map +1 -1
- package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
- package/dist/rest/base/CrudWithAddresses.js +2 -2
- package/dist/rest/base/CrudWithAddresses.js.map +1 -1
- package/dist/rest/base/FabricResource.d.ts +15 -0
- package/dist/rest/base/FabricResource.js +16 -0
- package/dist/rest/base/FabricResource.js.map +1 -0
- package/dist/rest/base/ReadResource.d.ts +62 -0
- package/dist/rest/base/ReadResource.js +69 -0
- package/dist/rest/base/ReadResource.js.map +1 -0
- package/dist/rest/callHandler.d.ts +63 -0
- package/dist/rest/callHandler.js +62 -0
- package/dist/rest/callHandler.js.map +1 -0
- package/dist/rest/index.d.ts +19 -76
- package/dist/rest/index.js +49 -120
- package/dist/rest/index.js.map +1 -1
- package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
- package/dist/rest/namespaces/_client_tree_generated.js +171 -0
- package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +3 -42
- package/dist/rest/namespaces/addresses.js +3 -50
- package/dist/rest/namespaces/addresses.js.map +1 -1
- package/dist/rest/namespaces/calling.d.ts +6 -378
- package/dist/rest/namespaces/calling.js +6 -473
- package/dist/rest/namespaces/calling.js.map +1 -1
- package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
- package/dist/rest/namespaces/calling.resources.generated.js +477 -0
- package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
- package/dist/rest/namespaces/calling.types.generated.js +8 -0
- package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +4 -18
- package/dist/rest/namespaces/chat.js +4 -21
- package/dist/rest/namespaces/chat.js.map +1 -1
- package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/chat.resources.generated.js +29 -0
- package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
- package/dist/rest/namespaces/chat.types.generated.js +8 -0
- package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +6 -62
- package/dist/rest/namespaces/datasphere.js +6 -72
- package/dist/rest/namespaces/datasphere.js.map +1 -1
- package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
- package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
- package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +11 -273
- package/dist/rest/namespaces/fabric.js +14 -363
- package/dist/rest/namespaces/fabric.js.map +1 -1
- package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
- package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
- package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
- package/dist/rest/namespaces/fabric.types.generated.js +8 -0
- package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/fax.resources.generated.js +14 -0
- package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/fax.types.generated.js +8 -0
- package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
- package/dist/rest/namespaces/imported-numbers.js +3 -21
- package/dist/rest/namespaces/imported-numbers.js.map +1 -1
- package/dist/rest/namespaces/logs.d.ts +10 -101
- package/dist/rest/namespaces/logs.js +10 -128
- package/dist/rest/namespaces/logs.js.map +1 -1
- package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/logs.resources.generated.js +17 -0
- package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/logs.types.generated.js +8 -0
- package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +3 -25
- package/dist/rest/namespaces/lookup.js +3 -27
- package/dist/rest/namespaces/lookup.js.map +1 -1
- package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/message.resources.generated.js +14 -0
- package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
- package/dist/rest/namespaces/message.types.generated.js +8 -0
- package/dist/rest/namespaces/message.types.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
- package/dist/rest/namespaces/messages.resources.generated.js +44 -0
- package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
- package/dist/rest/namespaces/messages.types.generated.js +8 -0
- package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +3 -42
- package/dist/rest/namespaces/mfa.js +3 -49
- package/dist/rest/namespaces/mfa.js.map +1 -1
- package/dist/rest/namespaces/number-groups.d.ts +3 -45
- package/dist/rest/namespaces/number-groups.js +3 -53
- package/dist/rest/namespaces/number-groups.js.map +1 -1
- package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
- package/dist/rest/namespaces/phone-numbers.js +9 -63
- package/dist/rest/namespaces/phone-numbers.js.map +1 -1
- package/dist/rest/namespaces/project.d.ts +6 -42
- package/dist/rest/namespaces/project.js +6 -51
- package/dist/rest/namespaces/project.js.map +1 -1
- package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
- package/dist/rest/namespaces/project.resources.generated.js +44 -0
- package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
- package/dist/rest/namespaces/project.types.generated.js +8 -0
- package/dist/rest/namespaces/project.types.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/projects.resources.generated.js +25 -0
- package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
- package/dist/rest/namespaces/projects.types.generated.js +8 -0
- package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +4 -18
- package/dist/rest/namespaces/pubsub.js +4 -21
- package/dist/rest/namespaces/pubsub.js.map +1 -1
- package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
- package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
- package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +3 -38
- package/dist/rest/namespaces/queues.js +3 -44
- package/dist/rest/namespaces/queues.js.map +1 -1
- package/dist/rest/namespaces/recordings.d.ts +3 -34
- package/dist/rest/namespaces/recordings.js +3 -40
- package/dist/rest/namespaces/recordings.js.map +1 -1
- package/dist/rest/namespaces/registry.d.ts +6 -137
- package/dist/rest/namespaces/registry.js +6 -173
- package/dist/rest/namespaces/registry.js.map +1 -1
- package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +3 -35
- package/dist/rest/namespaces/short-codes.js +3 -41
- package/dist/rest/namespaces/short-codes.js.map +1 -1
- package/dist/rest/namespaces/sip-profile.d.ts +3 -24
- package/dist/rest/namespaces/sip-profile.js +3 -29
- package/dist/rest/namespaces/sip-profile.js.map +1 -1
- package/dist/rest/namespaces/verified-callers.d.ts +3 -29
- package/dist/rest/namespaces/verified-callers.js +3 -34
- package/dist/rest/namespaces/verified-callers.js.map +1 -1
- package/dist/rest/namespaces/video.d.ts +10 -227
- package/dist/rest/namespaces/video.js +10 -288
- package/dist/rest/namespaces/video.js.map +1 -1
- package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
- package/dist/rest/namespaces/video.resources.generated.js +171 -0
- package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
- package/dist/rest/namespaces/video.types.generated.js +8 -0
- package/dist/rest/namespaces/video.types.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/voice.resources.generated.js +17 -0
- package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
- package/dist/rest/namespaces/voice.types.generated.js +8 -0
- package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
- package/dist/rest/pagination.d.ts +5 -1
- package/dist/rest/pagination.js +40 -20
- package/dist/rest/pagination.js.map +1 -1
- package/dist/rest/types.d.ts +21 -3
- package/dist/schema.json +299 -98
- package/dist/skills/SkillBase.d.ts +97 -20
- package/dist/skills/SkillBase.js +100 -17
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/skills/SkillManager.d.ts +66 -13
- package/dist/skills/SkillManager.js +101 -20
- package/dist/skills/SkillManager.js.map +1 -1
- package/dist/skills/SkillName.d.ts +44 -0
- package/dist/skills/SkillName.js +2 -0
- package/dist/skills/SkillName.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +47 -7
- package/dist/skills/SkillRegistry.js +85 -13
- package/dist/skills/SkillRegistry.js.map +1 -1
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
- package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
- package/dist/skills/builtin/ask_claude.d.ts +14 -4
- package/dist/skills/builtin/ask_claude.js +36 -14
- package/dist/skills/builtin/ask_claude.js.map +1 -1
- package/dist/skills/builtin/claude_skills.d.ts +3 -1
- package/dist/skills/builtin/claude_skills.js +19 -15
- package/dist/skills/builtin/claude_skills.js.map +1 -1
- package/dist/skills/builtin/custom_skills.d.ts +10 -3
- package/dist/skills/builtin/custom_skills.js +26 -9
- package/dist/skills/builtin/custom_skills.js.map +1 -1
- package/dist/skills/builtin/datasphere.d.ts +5 -3
- package/dist/skills/builtin/datasphere.js +34 -25
- package/dist/skills/builtin/datasphere.js.map +1 -1
- package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
- package/dist/skills/builtin/datasphere_serverless.js +17 -6
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
- package/dist/skills/builtin/datetime.d.ts +3 -1
- package/dist/skills/builtin/datetime.js +11 -7
- package/dist/skills/builtin/datetime.js.map +1 -1
- package/dist/skills/builtin/google_maps.d.ts +29 -14
- package/dist/skills/builtin/google_maps.js +89 -269
- package/dist/skills/builtin/google_maps.js.map +1 -1
- package/dist/skills/builtin/index.d.ts +8 -6
- package/dist/skills/builtin/index.js +8 -6
- package/dist/skills/builtin/index.js.map +1 -1
- package/dist/skills/builtin/info_gatherer.d.ts +4 -2
- package/dist/skills/builtin/info_gatherer.js +20 -12
- package/dist/skills/builtin/info_gatherer.js.map +1 -1
- package/dist/skills/builtin/joke.d.ts +16 -6
- package/dist/skills/builtin/joke.js +54 -37
- package/dist/skills/builtin/joke.js.map +1 -1
- package/dist/skills/builtin/math.d.ts +3 -1
- package/dist/skills/builtin/math.js +14 -9
- package/dist/skills/builtin/math.js.map +1 -1
- package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
- package/dist/skills/builtin/mcp_gateway.js +77 -46
- package/dist/skills/builtin/mcp_gateway.js.map +1 -1
- package/dist/skills/builtin/native_vector_search.d.ts +19 -5
- package/dist/skills/builtin/native_vector_search.js +179 -61
- package/dist/skills/builtin/native_vector_search.js.map +1 -1
- package/dist/skills/builtin/play_background_file.d.ts +21 -15
- package/dist/skills/builtin/play_background_file.js +43 -122
- package/dist/skills/builtin/play_background_file.js.map +1 -1
- package/dist/skills/builtin/spider.d.ts +46 -1
- package/dist/skills/builtin/spider.js +317 -101
- package/dist/skills/builtin/spider.js.map +1 -1
- package/dist/skills/builtin/swml_transfer.d.ts +14 -3
- package/dist/skills/builtin/swml_transfer.js +45 -24
- package/dist/skills/builtin/swml_transfer.js.map +1 -1
- package/dist/skills/builtin/weather_api.d.ts +24 -13
- package/dist/skills/builtin/weather_api.js +57 -31
- package/dist/skills/builtin/weather_api.js.map +1 -1
- package/dist/skills/builtin/web_search.d.ts +48 -10
- package/dist/skills/builtin/web_search.js +301 -84
- package/dist/skills/builtin/web_search.js.map +1 -1
- package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
- package/dist/skills/builtin/wikipedia_search.js +32 -14
- package/dist/skills/builtin/wikipedia_search.js.map +1 -1
- package/dist/skills/index.d.ts +3 -2
- package/dist/skills/index.js +1 -1
- package/dist/skills/index.js.map +1 -1
- package/dist/swml_verbs_generated.d.ts +2824 -0
- package/dist/swml_verbs_generated.js +12 -0
- package/dist/swml_verbs_generated.js.map +1 -0
- package/dist/types.d.ts +65 -6
- package/dist/web.d.ts +27 -0
- package/dist/web.js +20 -0
- package/dist/web.js.map +1 -0
- package/docs/agent-guide.md +1034 -0
- package/docs/ai_chat.md +560 -0
- package/docs/api-reference.md +3534 -0
- package/docs/architecture.md +846 -0
- package/docs/bedrock_agent.md +411 -0
- package/docs/cli-guide.md +403 -0
- package/docs/cloud_functions_guide.md +399 -0
- package/docs/configuration.md +548 -0
- package/docs/contexts-guide.md +884 -0
- package/docs/datamap-guide.md +1160 -0
- package/docs/developer_pain_points.md +548 -0
- package/docs/llm_parameters.md +298 -0
- package/docs/mcp_gateway_reference.md +354 -0
- package/docs/mcp_integration.md +162 -0
- package/docs/pgi_agent_guide.md +1820 -0
- package/docs/prefabs-guide.md +815 -0
- package/docs/programmatically_governed_inference.md +301 -0
- package/docs/sdk_features.md +501 -0
- package/docs/security.md +559 -0
- package/docs/serverless-guide.md +520 -0
- package/docs/skills-guide.md +1223 -0
- package/docs/skills-system.md +405 -0
- package/docs/skills_parameter_schema.md +417 -0
- package/docs/swaig-reference.md +1938 -0
- package/docs/swml_service_guide.md +573 -0
- package/docs/third_party_skills.md +410 -0
- package/docs/web_service.md +666 -0
- package/examples/README.md +202 -0
- package/examples/advanced-datamap.ts +108 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +95 -0
- package/examples/call-flow.ts +65 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +51 -0
- package/examples/datasphere-multi-instance.ts +66 -0
- package/examples/datasphere-serverless-env.ts +87 -0
- package/examples/datasphere-webhook-env.ts +65 -0
- package/examples/datasphere.ts +56 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +95 -0
- package/examples/gather-per-question-functions-demo.ts +139 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +75 -0
- package/examples/mcp-agent.ts +89 -0
- package/examples/mcp-gateway.ts +81 -0
- package/examples/multi-agent.ts +80 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pgi/case-domain.ts +114 -0
- package/examples/pgi/serve.ts +16 -0
- package/examples/pgi/support-agent.ts +265 -0
- package/examples/pom-prompt.ts +70 -0
- package/examples/prefab-concierge.ts +42 -0
- package/examples/prefab-faq.ts +58 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +69 -0
- package/examples/quickstart-agent.ts +29 -0
- package/examples/quickstart-relay.ts +25 -0
- package/examples/quickstart-rest.ts +25 -0
- package/examples/record-call.ts +65 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +93 -0
- package/examples/serverless-lambda.ts +43 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +41 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +193 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/swmlservice_ai_sidecar.ts +104 -0
- package/examples/swmlservice_swaig_standalone.ts +79 -0
- package/examples/tap.ts +67 -0
- package/examples/typed-tools.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +75 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +164 -0
- package/livewire/docs/migration-guide.md +251 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +196 -0
- package/livewire/examples/livewire-multi-tool.ts +121 -0
- package/package.json +88 -13
- package/relay/README.md +101 -0
- package/relay/docs/call-methods.md +622 -0
- package/relay/docs/client-reference.md +281 -0
- package/relay/docs/events.md +193 -0
- package/relay/docs/getting-started.md +221 -0
- package/relay/docs/guide.md +386 -0
- package/relay/docs/messaging.md +246 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +74 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +141 -0
- package/rest/docs/calling.md +313 -0
- package/rest/docs/client-reference.md +149 -0
- package/rest/docs/fabric.md +192 -0
- package/rest/docs/getting-started.md +138 -0
- package/rest/docs/guide.md +421 -0
- package/rest/docs/namespaces.md +367 -0
- package/rest/docs/phone-binding.md +116 -0
- package/rest/examples/rest-10dlc-registration.ts +177 -0
- package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
- package/rest/examples/rest-calling-play-and-record.ts +98 -0
- package/rest/examples/rest-client.ts +59 -0
- package/rest/examples/rest-datasphere-search.ts +81 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
- package/rest/examples/rest-manage-resources.ts +64 -0
- package/rest/examples/rest-phone-number-management.ts +200 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/tutorial/fred/fred.ts +218 -0
- package/tutorial/fred/tutorial/01-introduction.md +141 -0
- package/tutorial/fred/tutorial/02-setup.md +304 -0
- package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
- package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
- package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
- package/tutorial/fred/tutorial/06-running-testing.md +642 -0
- package/tutorial/fred/tutorial/README.md +56 -0
- package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
- package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
- package/tutorial/full-guardrails-agent/handlers.ts +436 -0
- package/tutorial/full-guardrails-agent/penny.ts +305 -0
- package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
- package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
- package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
- package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
- package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
- package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
- package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
- package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
- package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
- package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
- package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
- package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
- package/tutorial/full-guardrails-agent/workflow.ts +219 -0
- package/tutorial/multi_agents/README.md +175 -0
- package/tutorial/multi_agents/advanced_agent.ts +395 -0
- package/tutorial/multi_agents/extending_agents.ts +641 -0
- package/tutorial/multi_agents/knowledge.ts +59 -0
- package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
- package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
- package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
- package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
- package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
- package/tutorial/multi_agents/pc_builder.ts +529 -0
- package/tutorial/multi_agents/sales_agent.ts +88 -0
- package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
- package/tutorial/multi_agents/sales_knowledge.md +139 -0
- package/tutorial/multi_agents/support_knowledge.md +256 -0
- package/dist/cli/mock-data.d.ts +0 -37
- package/dist/cli/mock-data.js +0 -80
- package/dist/cli/mock-data.js.map +0 -1
- package/dist/generateVerbTypes.d.ts +0 -11
- package/dist/generateVerbTypes.js +0 -265
- package/dist/generateVerbTypes.js.map +0 -1
- package/dist/rest/namespaces/compat.d.ts +0 -585
- package/dist/rest/namespaces/compat.js +0 -735
- package/dist/rest/namespaces/compat.js.map +0 -1
|
@@ -0,0 +1,884 @@
|
|
|
1
|
+
# Contexts & Steps Guide
|
|
2
|
+
|
|
3
|
+
This guide covers the Contexts & Steps system in the SignalWire AI Agents TypeScript SDK, which builds multi-step conversation workflows.
|
|
4
|
+
|
|
5
|
+
<!-- snippet-setup -->
|
|
6
|
+
```ts
|
|
7
|
+
export {}; // treat each example as a module so top-level `await` is allowed
|
|
8
|
+
declare global {
|
|
9
|
+
// Shared context the fragments on this page assume (constructed in the prose examples).
|
|
10
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
11
|
+
const AgentBase: typeof import('@signalwire/sdk').AgentBase;
|
|
12
|
+
const ContextBuilder: typeof import('@signalwire/sdk').ContextBuilder;
|
|
13
|
+
const createSimpleContext: typeof import('@signalwire/sdk').createSimpleContext;
|
|
14
|
+
const cb: import('@signalwire/sdk').ContextBuilder;
|
|
15
|
+
const ctx: import('@signalwire/sdk').Context;
|
|
16
|
+
const step: import('@signalwire/sdk').Step;
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Table of Contents
|
|
23
|
+
|
|
24
|
+
1. [Overview](#overview)
|
|
25
|
+
2. [Creating Contexts](#creating-contexts)
|
|
26
|
+
3. [Steps](#steps)
|
|
27
|
+
4. [Step Navigation](#step-navigation)
|
|
28
|
+
5. [Function Control](#function-control)
|
|
29
|
+
6. [End States](#end-states)
|
|
30
|
+
7. [GatherInfo](#gatherinfo)
|
|
31
|
+
8. [Context Settings](#context-settings)
|
|
32
|
+
9. [Isolation and Reset](#isolation-and-reset)
|
|
33
|
+
10. [Fillers](#fillers)
|
|
34
|
+
11. [Validation](#validation)
|
|
35
|
+
12. [Real-World Example](#real-world-example)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Overview
|
|
40
|
+
|
|
41
|
+
Contexts and steps structure a conversation as a state machine. Instead of one flat prompt, you define **contexts**, and each context holds ordered **steps**. The platform moves through the steps by the rules you set. Those rules are completion criteria, the steps and contexts each step may move to, and the tools each step allows. Customer intake, troubleshooting trees and routing between departments fit this model.
|
|
42
|
+
|
|
43
|
+
The system has three parts:
|
|
44
|
+
|
|
45
|
+
- **Context**: a named group of ordered steps. It can have its own prompt, system prompt, navigation rules and history settings.
|
|
46
|
+
- **Step**: one stage within a context. It has instruction text (raw text or POM sections), completion criteria, a tool list, and the steps or contexts it may move to.
|
|
47
|
+
- **ContextBuilder**: the container for all contexts. It validates cross-references and serializes everything to SWML.
|
|
48
|
+
|
|
49
|
+
These classes are involved:
|
|
50
|
+
|
|
51
|
+
| Class | Role |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `ContextBuilder` | Holds and validates all contexts |
|
|
54
|
+
| `Context` | A named context with steps, prompts, fillers and navigation rules |
|
|
55
|
+
| `Step` | A single step within a context, with text, criteria and function control |
|
|
56
|
+
| `GatherInfo` | Structured data collection attached to a step |
|
|
57
|
+
| `GatherQuestion` | A single question within a GatherInfo operation |
|
|
58
|
+
|
|
59
|
+
The package exports all of them from `@signalwire/sdk`.
|
|
60
|
+
|
|
61
|
+
The contexts don't replace the agent's prompt. The SDK sends the agent's prompt, or `You are <name>, a helpful AI assistant.` when there's none, together with the contexts. The contexts go in the `ai` verb's prompt object, as `ai.prompt.contexts`.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Creating Contexts
|
|
66
|
+
|
|
67
|
+
### Using `agent.defineContexts()`
|
|
68
|
+
|
|
69
|
+
`defineContexts()` on `AgentBase` returns a `ContextBuilder` that you add contexts to:
|
|
70
|
+
|
|
71
|
+
```typescript
|
|
72
|
+
import { AgentBase } from '@signalwire/sdk';
|
|
73
|
+
|
|
74
|
+
const agent = new AgentBase({ name: 'my-agent' });
|
|
75
|
+
|
|
76
|
+
// Create and get the ContextBuilder
|
|
77
|
+
const cb = agent.defineContexts();
|
|
78
|
+
|
|
79
|
+
// Add contexts to the builder
|
|
80
|
+
const greeting = cb.addContext('default');
|
|
81
|
+
const support = cb.addContext('support');
|
|
82
|
+
const farewell = cb.addContext('farewell');
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
You can also build a `ContextBuilder` first and pass it in:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
import { ContextBuilder } from '@signalwire/sdk';
|
|
89
|
+
|
|
90
|
+
const cb = new ContextBuilder();
|
|
91
|
+
cb.addContext('default');
|
|
92
|
+
// ... configure ...
|
|
93
|
+
|
|
94
|
+
agent.defineContexts(cb);
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`agent.resetContexts()` removes every context, for example in a dynamic config callback that rebuilds them for one request. `agent.getContexts()` returns the serialized contexts.
|
|
98
|
+
|
|
99
|
+
### Using `ContextBuilder.addContext()`
|
|
100
|
+
|
|
101
|
+
`addContext()` returns the new `Context`:
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
const cb = new ContextBuilder();
|
|
105
|
+
|
|
106
|
+
// Returns the new Context instance for chaining
|
|
107
|
+
const ctx = cb.addContext('intake');
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Context names must be unique within a builder, and a builder holds at most 50 contexts. `addContext()` throws for a duplicate name or a 51st context.
|
|
111
|
+
|
|
112
|
+
### Retrieving a Context
|
|
113
|
+
|
|
114
|
+
`getContext()` returns a context by name, or `undefined`:
|
|
115
|
+
|
|
116
|
+
<!-- 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 -->
|
|
117
|
+
```typescript
|
|
118
|
+
const ctx = cb.getContext('intake');
|
|
119
|
+
if (ctx) {
|
|
120
|
+
// configure further
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### The `default` Context
|
|
125
|
+
|
|
126
|
+
The SWML schema requires a context named `default`, and describes it as the context the conversation starts in. The SDK enforces the name only when there's one context:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
// Valid: single context named "default"
|
|
130
|
+
const cb = new ContextBuilder();
|
|
131
|
+
cb.addContext('default');
|
|
132
|
+
|
|
133
|
+
// Invalid: single context with any other name
|
|
134
|
+
const bad = new ContextBuilder();
|
|
135
|
+
bad.addContext('main'); // validate() will throw
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
With several contexts, the SDK accepts a set without `default`, but the schema doesn't. Name the context the call starts in `default`.
|
|
139
|
+
|
|
140
|
+
### Helper: `createSimpleContext()`
|
|
141
|
+
|
|
142
|
+
`createSimpleContext()` creates a standalone `Context`, named `default` unless you pass a name:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
import { createSimpleContext } from '@signalwire/sdk';
|
|
146
|
+
|
|
147
|
+
const ctx = createSimpleContext(); // name defaults to 'default'
|
|
148
|
+
const step = ctx.addStep('welcome');
|
|
149
|
+
step.setText('Welcome the caller to the service.');
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Steps
|
|
155
|
+
|
|
156
|
+
Steps are the stages of a context, kept in the order you add them. A context holds at most 100 steps.
|
|
157
|
+
|
|
158
|
+
### Adding a Step
|
|
159
|
+
|
|
160
|
+
`addStep()` returns the new `Step`, and takes optional shorthand settings:
|
|
161
|
+
|
|
162
|
+
<!-- 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 -->
|
|
163
|
+
```typescript
|
|
164
|
+
const ctx = cb.addContext('intake');
|
|
165
|
+
|
|
166
|
+
// Basic: returns the Step for further configuration
|
|
167
|
+
const step1 = ctx.addStep('greet');
|
|
168
|
+
step1.setText('Greet the customer warmly.');
|
|
169
|
+
|
|
170
|
+
// Shorthand: pass options inline
|
|
171
|
+
const step2 = ctx.addStep('collect_info', {
|
|
172
|
+
task: 'Collect the customer name and account number.',
|
|
173
|
+
bullets: ['Ask for full name first', 'Then ask for account number'],
|
|
174
|
+
criteria: 'Customer has provided both name and account number.',
|
|
175
|
+
functions: ['lookup_account'],
|
|
176
|
+
validSteps: ['verify'],
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Each shorthand option calls a `Step` method:
|
|
181
|
+
|
|
182
|
+
| Option | Effect |
|
|
183
|
+
|---|---|
|
|
184
|
+
| `task` | Calls `step.addSection('Task', task)` |
|
|
185
|
+
| `bullets` | Calls `step.addBullets('Process', bullets)` |
|
|
186
|
+
| `criteria` | Calls `step.setStepCriteria(criteria)` |
|
|
187
|
+
| `functions` | Calls `step.setFunctions(functions)` |
|
|
188
|
+
| `validSteps` | Calls `step.setValidSteps(validSteps)` |
|
|
189
|
+
|
|
190
|
+
Step names must be unique within a context. Adding a duplicate throws an error.
|
|
191
|
+
|
|
192
|
+
### Step Content: `setText()` vs POM Sections
|
|
193
|
+
|
|
194
|
+
A step's content is either raw text or POM sections, not both. This is the raw-text form:
|
|
195
|
+
|
|
196
|
+
```typescript
|
|
197
|
+
step.setText('You are greeting the customer. Be friendly and professional.');
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
This is the POM form, with a body section and a bullet section:
|
|
201
|
+
|
|
202
|
+
```typescript
|
|
203
|
+
step.addSection('Task', 'Help the customer with their billing inquiry.');
|
|
204
|
+
step.addBullets('Guidelines', [
|
|
205
|
+
'Be empathetic and patient',
|
|
206
|
+
'Verify identity before sharing account details',
|
|
207
|
+
'Offer to escalate if needed',
|
|
208
|
+
]);
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Calling `setText()` on a step with sections, or adding a section to a step with text, throws an error.
|
|
212
|
+
|
|
213
|
+
The SDK renders POM sections as Markdown text in the step's `text` field:
|
|
214
|
+
|
|
215
|
+
```markdown
|
|
216
|
+
## Task
|
|
217
|
+
Help the customer with their billing inquiry.
|
|
218
|
+
|
|
219
|
+
## Guidelines
|
|
220
|
+
- Be empathetic and patient
|
|
221
|
+
- Verify identity before sharing account details
|
|
222
|
+
- Offer to escalate if needed
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Managing Steps
|
|
226
|
+
|
|
227
|
+
These methods find, remove, reorder and clear steps:
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
// Retrieve a step by name
|
|
231
|
+
const step = ctx.getStep('greet');
|
|
232
|
+
|
|
233
|
+
// Remove a step
|
|
234
|
+
ctx.removeStep('greet');
|
|
235
|
+
|
|
236
|
+
// Move a step to a new position (zero-indexed)
|
|
237
|
+
ctx.moveStep('verify', 0); // Move "verify" to the beginning
|
|
238
|
+
|
|
239
|
+
// Clear all content from a step (sections and text)
|
|
240
|
+
step!.clearSections();
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Step Navigation
|
|
246
|
+
|
|
247
|
+
Navigation rules control which steps and contexts the conversation can move to from a step.
|
|
248
|
+
|
|
249
|
+
### `setValidSteps()`
|
|
250
|
+
|
|
251
|
+
`setValidSteps()` lists the steps of the current context the conversation may move to. The name `next` stands for the following step:
|
|
252
|
+
|
|
253
|
+
```typescript
|
|
254
|
+
step.setValidSteps(['collect_info', 'verify', 'escalate']);
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
The schema says that without `valid_steps`, or with an empty list, the conversation proceeds to the next step in the context.
|
|
258
|
+
|
|
259
|
+
### `setValidContexts()`
|
|
260
|
+
|
|
261
|
+
`setValidContexts()` lists the contexts the conversation may switch to from this step:
|
|
262
|
+
|
|
263
|
+
```typescript
|
|
264
|
+
step.setValidContexts(['billing', 'technical_support', 'farewell']);
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
When a step or its context sets `valid_steps` or `valid_contexts`, the platform gives the model the `next_step` and `change_context` tools to move. You don't define those tools, and you can't register tools with those names while contexts are in use.
|
|
268
|
+
|
|
269
|
+
### `setStepCriteria()`
|
|
270
|
+
|
|
271
|
+
`setStepCriteria()` describes, in plain language, what must happen before the step is complete:
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
step.setStepCriteria(
|
|
275
|
+
'The customer has confirmed their name, account number, and the nature of their issue.'
|
|
276
|
+
);
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
The criteria is an instruction to the model, which uses it to decide when to move on.
|
|
280
|
+
|
|
281
|
+
### Context-Level Navigation
|
|
282
|
+
|
|
283
|
+
A context can set navigation rules for all its steps:
|
|
284
|
+
|
|
285
|
+
<!-- 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 -->
|
|
286
|
+
```typescript
|
|
287
|
+
const billing = cb.addContext('billing');
|
|
288
|
+
billing.setValidContexts(['technical_support', 'farewell']);
|
|
289
|
+
billing.setValidSteps(['step_a', 'step_b']);
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### `setInitialStep()`
|
|
293
|
+
|
|
294
|
+
A context starts on its first step. `setInitialStep()` starts it on another step, for example to skip a greeting when the conversation comes back to the context:
|
|
295
|
+
|
|
296
|
+
<!-- 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 -->
|
|
297
|
+
```typescript
|
|
298
|
+
const support = cb.addContext('support');
|
|
299
|
+
support.addStep('greeting').setText('Introduce the support team.');
|
|
300
|
+
support.addStep('help').setText('Help with the issue.');
|
|
301
|
+
support.setInitialStep('help');
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
The step must exist in the context, or `validate()` throws.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## Function Control
|
|
309
|
+
|
|
310
|
+
Each step can limit which SWAIG functions (tools) the model can call during that step.
|
|
311
|
+
|
|
312
|
+
### `setFunctions()`
|
|
313
|
+
|
|
314
|
+
`setFunctions()` takes a list of function names, or `'none'`:
|
|
315
|
+
|
|
316
|
+
```typescript
|
|
317
|
+
// Only these functions are available
|
|
318
|
+
step.setFunctions(['lookup_account', 'get_balance']);
|
|
319
|
+
|
|
320
|
+
// No functions available
|
|
321
|
+
step.setFunctions('none');
|
|
322
|
+
|
|
323
|
+
// Same as 'none'
|
|
324
|
+
step.setFunctions([]);
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Functions not in the list are inactive during the step. Internal functions, such as `hangup_hook` and `gather_submit`, stay active, and so do `next_step` and `change_context`. Don't list those in `functions`.
|
|
328
|
+
|
|
329
|
+
### Inheritance Between Steps
|
|
330
|
+
|
|
331
|
+
A step without `setFunctions()` emits no `functions` key. The platform then keeps the function set of the previous step, or of the previous context's last step. It changes the active set only when a step declares `functions`. On the first step of the conversation, with no earlier set to keep, every registered function is active.
|
|
332
|
+
|
|
333
|
+
A later step that leaves out `setFunctions()` therefore keeps the tools of the step before it. Call `setFunctions()` on every step whose tools differ from the previous step's.
|
|
334
|
+
|
|
335
|
+
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
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## End States
|
|
340
|
+
|
|
341
|
+
### `setEnd()`
|
|
342
|
+
|
|
343
|
+
`setEnd(true)` marks the last step of the step flow:
|
|
344
|
+
|
|
345
|
+
```typescript
|
|
346
|
+
const wrapUp = ctx.addStep('wrap_up');
|
|
347
|
+
wrapUp.setText('Thank the customer and ask if there is anything else.');
|
|
348
|
+
wrapUp.setEnd(true);
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
It doesn't end the call. After the step runs, the platform leaves step mode: it clears the steps, `valid_steps` and `valid_contexts`, and stops offering `next_step`. The model then works from the base prompt and the context prompt. To end the call, have a tool return `FunctionResult.hangup()`.
|
|
352
|
+
|
|
353
|
+
### `setSkipUserTurn()`
|
|
354
|
+
|
|
355
|
+
`setSkipUserTurn(true)` doesn't wait for the caller to speak when the step starts:
|
|
356
|
+
|
|
357
|
+
```typescript
|
|
358
|
+
const transition = ctx.addStep('auto_transfer');
|
|
359
|
+
transition.setText('Transfer the call to the billing department.');
|
|
360
|
+
transition.setSkipUserTurn(true);
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
### `setSkipToNextStep()`
|
|
364
|
+
|
|
365
|
+
`setSkipToNextStep(true)` moves to the next step in order when this one completes:
|
|
366
|
+
|
|
367
|
+
```typescript
|
|
368
|
+
const intro = ctx.addStep('intro');
|
|
369
|
+
intro.setText('Provide a brief introduction.');
|
|
370
|
+
intro.setSkipToNextStep(true);
|
|
371
|
+
|
|
372
|
+
const main = ctx.addStep('main');
|
|
373
|
+
main.setText('Now handle the main request.');
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
### `setHistory()`
|
|
377
|
+
|
|
378
|
+
`setHistory()` controls what the model still sees of earlier steps when this step starts. Nothing is removed from the call log:
|
|
379
|
+
|
|
380
|
+
```typescript
|
|
381
|
+
step.setHistory('hide');
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
The three modes are these:
|
|
385
|
+
|
|
386
|
+
- `keep`: hide nothing. Earlier steps' instructions and dialogue stay visible.
|
|
387
|
+
- `default`: hide earlier step instructions, and keep the dialogue. This is the behavior when `history` isn't set.
|
|
388
|
+
- `hide`: hide earlier instructions and the earlier dialogue. A `${step_history.*}` reference in this step's text brings back what you choose.
|
|
389
|
+
|
|
390
|
+
`Context.setHistory()` sets the default for every step in the context, and a step's own `setHistory()` overrides it. Any other value throws.
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## GatherInfo
|
|
395
|
+
|
|
396
|
+
`GatherInfo` collects structured answers within a step, one question at a time. Each question has a key, an answer type, and optional confirmation and tools.
|
|
397
|
+
|
|
398
|
+
### Setting Up GatherInfo
|
|
399
|
+
|
|
400
|
+
Call `setGatherInfo()` on a step, then add questions:
|
|
401
|
+
|
|
402
|
+
```typescript
|
|
403
|
+
const step = ctx.addStep('collect_details');
|
|
404
|
+
step.setText('Collect the customer contact details.');
|
|
405
|
+
|
|
406
|
+
step.setGatherInfo({
|
|
407
|
+
outputKey: 'customer_info',
|
|
408
|
+
completionAction: 'next_step',
|
|
409
|
+
prompt: 'Explain that you need a few contact details.',
|
|
410
|
+
});
|
|
411
|
+
|
|
412
|
+
step.addGatherQuestion({
|
|
413
|
+
key: 'full_name',
|
|
414
|
+
question: 'What is your full name?',
|
|
415
|
+
confirm: true,
|
|
416
|
+
});
|
|
417
|
+
|
|
418
|
+
step.addGatherQuestion({
|
|
419
|
+
key: 'email',
|
|
420
|
+
question: 'What is your email address?',
|
|
421
|
+
confirm: true,
|
|
422
|
+
prompt: 'Ask the caller to spell the address.',
|
|
423
|
+
});
|
|
424
|
+
|
|
425
|
+
step.addGatherQuestion({
|
|
426
|
+
key: 'phone',
|
|
427
|
+
question: 'What is your phone number?',
|
|
428
|
+
functions: ['validate_phone'],
|
|
429
|
+
});
|
|
430
|
+
|
|
431
|
+
ctx.addStep('verify').setText('Read back ${customer_info} and confirm it.');
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
`addGatherQuestion()` throws if `setGatherInfo()` wasn't called first.
|
|
435
|
+
|
|
436
|
+
While a question is asked, the platform deactivates the step's other functions. The model can call only `gather_submit`, which records the answer, and the tools listed in that question's `functions`. It can't move to another step or context until the gather completes. The answers go into the call's global data, under `outputKey` when it's set.
|
|
437
|
+
|
|
438
|
+
### GatherInfo Options
|
|
439
|
+
|
|
440
|
+
`setGatherInfo()` takes these options:
|
|
441
|
+
|
|
442
|
+
| Option | Type | Default | Description |
|
|
443
|
+
|---|---|---|---|
|
|
444
|
+
| `outputKey` | `string` | none | Key in global data that holds the answers. Without it, each answer is stored at the top level. |
|
|
445
|
+
| `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. |
|
|
446
|
+
| `prompt` | `string` | none | Text the platform adds once, when the first question starts. |
|
|
447
|
+
| `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. |
|
|
448
|
+
|
|
449
|
+
`validate()` throws when `completionAction` is `'next_step'` on the last step of a context, or names a step that isn't in the context.
|
|
450
|
+
|
|
451
|
+
### GatherQuestion Options
|
|
452
|
+
|
|
453
|
+
`addGatherQuestion()` takes these options:
|
|
454
|
+
|
|
455
|
+
| Option | Type | Default | Description |
|
|
456
|
+
|---|---|---|---|
|
|
457
|
+
| `key` | `string` | (required) | Key the answer is stored under. Keys must be unique within a step. |
|
|
458
|
+
| `question` | `string` | (required) | The question for the model to ask. |
|
|
459
|
+
| `type` | `string` | `'string'` | JSON Schema type of the answer, such as `'string'`, `'integer'`, `'number'` or `'boolean'`. |
|
|
460
|
+
| `confirm` | `boolean` | `false` | The model must read the answer back and get the caller's confirmation before it submits. |
|
|
461
|
+
| `prompt` | `string` | none | Extra instruction for this question. |
|
|
462
|
+
| `functions` | `string[]` | none | Functions available during this question only. |
|
|
463
|
+
| `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. |
|
|
464
|
+
|
|
465
|
+
### GatherInfo Serialization
|
|
466
|
+
|
|
467
|
+
`GatherInfo.toDict()` produces the SWML `gather_info` object. For a gather with `isolated: true` whose `email` question sets `isolated: false`, the output is:
|
|
468
|
+
|
|
469
|
+
```json
|
|
470
|
+
{
|
|
471
|
+
"questions": [
|
|
472
|
+
{ "key": "full_name", "question": "What is your full name?", "confirm": true },
|
|
473
|
+
{ "key": "email", "question": "What is your email address?", "confirm": true, "prompt": "Ask the caller to spell the address.", "isolated": false },
|
|
474
|
+
{ "key": "phone", "question": "What is your phone number?", "functions": ["validate_phone"] }
|
|
475
|
+
],
|
|
476
|
+
"prompt": "Explain that you need a few contact details.",
|
|
477
|
+
"output_key": "customer_info",
|
|
478
|
+
"completion_action": "next_step",
|
|
479
|
+
"isolated": true
|
|
480
|
+
}
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
The SDK leaves `type` out when it's `'string'`, and `confirm` when it's `false`. A question's `isolated` appears whenever you set it, `false` included, so it can override the gather. `toDict()` throws for a gather with no questions.
|
|
484
|
+
|
|
485
|
+
---
|
|
486
|
+
|
|
487
|
+
## Context Settings
|
|
488
|
+
|
|
489
|
+
### Prompt Configuration
|
|
490
|
+
|
|
491
|
+
A context can have its own prompt, which applies to all its steps. Like a step, it uses either raw text or POM sections. This is the raw-text form:
|
|
492
|
+
|
|
493
|
+
<!-- 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 -->
|
|
494
|
+
```typescript
|
|
495
|
+
const ctx = cb.addContext('billing');
|
|
496
|
+
ctx.setPrompt('You are handling a billing inquiry. Be precise with numbers.');
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
This is the POM form:
|
|
500
|
+
|
|
501
|
+
```typescript
|
|
502
|
+
ctx.addSection('Role', 'You are a billing specialist for Acme Corp.');
|
|
503
|
+
ctx.addBullets('Guidelines', [
|
|
504
|
+
'Always verify the account before discussing charges',
|
|
505
|
+
'State every fee and credit on the account',
|
|
506
|
+
'Offer payment plan options when appropriate',
|
|
507
|
+
]);
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
Raw text and POM sections can't be mixed in a context's prompt; the second kind throws.
|
|
511
|
+
|
|
512
|
+
### System Prompt
|
|
513
|
+
|
|
514
|
+
`setSystemPrompt()` gives the context a new system prompt, used when the conversation enters it. This is the raw-text form:
|
|
515
|
+
|
|
516
|
+
```typescript
|
|
517
|
+
ctx.setSystemPrompt('You are a helpful billing assistant. Be concise.');
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
`addSystemSection()` and `addSystemBullets()` build it from POM sections:
|
|
521
|
+
|
|
522
|
+
```typescript
|
|
523
|
+
ctx.addSystemSection('Identity', 'You are Acme Corp billing support.');
|
|
524
|
+
ctx.addSystemBullets('Rules', [
|
|
525
|
+
'Never disclose internal pricing formulas',
|
|
526
|
+
'Always confirm before processing refunds',
|
|
527
|
+
]);
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
Raw text and POM sections can't be mixed in a system prompt either.
|
|
531
|
+
|
|
532
|
+
### Post-Prompt
|
|
533
|
+
|
|
534
|
+
`setPostPrompt()` replaces the agent's post-prompt while this context is active:
|
|
535
|
+
|
|
536
|
+
```typescript
|
|
537
|
+
ctx.setPostPrompt('Summarize the billing changes made during the call.');
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
### User Prompt
|
|
541
|
+
|
|
542
|
+
`setUserPrompt()` sets a user message that the platform adds when the conversation enters this context:
|
|
543
|
+
|
|
544
|
+
```typescript
|
|
545
|
+
ctx.setUserPrompt('I need help with my billing.');
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
---
|
|
549
|
+
|
|
550
|
+
## Isolation and Reset
|
|
551
|
+
|
|
552
|
+
These settings control what happens to the conversation history when the conversation enters a context or step.
|
|
553
|
+
|
|
554
|
+
### `setIsolated()`
|
|
555
|
+
|
|
556
|
+
`setIsolated(true)` clears the conversation history when the conversation enters the context through `change_context`. The model starts with the context's system prompt and step instructions only:
|
|
557
|
+
|
|
558
|
+
<!-- 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 -->
|
|
559
|
+
```typescript
|
|
560
|
+
const secureCtx = cb.addContext('payment');
|
|
561
|
+
secureCtx.setIsolated(true);
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
If the context also sets `consolidate` or `full_reset`, those apply instead of the wipe.
|
|
565
|
+
|
|
566
|
+
### `setConsolidate()` (Context-Level)
|
|
567
|
+
|
|
568
|
+
`setConsolidate(true)` summarizes the earlier conversation into the new prompt when the conversation enters this context:
|
|
569
|
+
|
|
570
|
+
```typescript
|
|
571
|
+
ctx.setConsolidate(true);
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
### `setFullReset()` (Context-Level)
|
|
575
|
+
|
|
576
|
+
`setFullReset(true)` replaces the system prompt completely when the conversation enters this context, instead of adding to it:
|
|
577
|
+
|
|
578
|
+
```typescript
|
|
579
|
+
ctx.setFullReset(true);
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
### Step-Level Reset Options
|
|
583
|
+
|
|
584
|
+
A step can reset the conversation when the conversation enters it:
|
|
585
|
+
|
|
586
|
+
```typescript
|
|
587
|
+
const step = ctx.addStep('fresh_start');
|
|
588
|
+
|
|
589
|
+
// Replace the system prompt when entering this step
|
|
590
|
+
step.setResetSystemPrompt('You are now handling a refund request.');
|
|
591
|
+
|
|
592
|
+
// Set the user prompt when entering this step
|
|
593
|
+
step.setResetUserPrompt('The customer wants a refund.');
|
|
594
|
+
|
|
595
|
+
// Consolidate conversation history at this step
|
|
596
|
+
step.setResetConsolidate(true);
|
|
597
|
+
|
|
598
|
+
// Perform a full conversation reset at this step
|
|
599
|
+
step.setResetFullReset(true);
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
The SDK serializes the step-level reset options under a `reset` key:
|
|
603
|
+
|
|
604
|
+
```json
|
|
605
|
+
{
|
|
606
|
+
"name": "fresh_start",
|
|
607
|
+
"text": "...",
|
|
608
|
+
"reset": {
|
|
609
|
+
"system_prompt": "You are now handling a refund request.",
|
|
610
|
+
"user_prompt": "The customer wants a refund.",
|
|
611
|
+
"consolidate": true,
|
|
612
|
+
"full_reset": true
|
|
613
|
+
}
|
|
614
|
+
}
|
|
615
|
+
```
|
|
616
|
+
|
|
617
|
+
---
|
|
618
|
+
|
|
619
|
+
## Fillers
|
|
620
|
+
|
|
621
|
+
Fillers are phrases the platform plays when the conversation enters or leaves a context. Each set is keyed by language code.
|
|
622
|
+
|
|
623
|
+
### Enter Fillers
|
|
624
|
+
|
|
625
|
+
Enter fillers play when the conversation enters the context:
|
|
626
|
+
|
|
627
|
+
```typescript
|
|
628
|
+
// Set all enter fillers at once (keyed by language code)
|
|
629
|
+
ctx.setEnterFillers({
|
|
630
|
+
'en-US': ['One moment.', 'Let me connect you.'],
|
|
631
|
+
'es-ES': ['Un momento, por favor.'],
|
|
632
|
+
});
|
|
633
|
+
|
|
634
|
+
// Set the fillers for one language
|
|
635
|
+
ctx.addEnterFiller('en-US', [
|
|
636
|
+
'One moment while I pull that up.',
|
|
637
|
+
'Let me check on that for you.',
|
|
638
|
+
]);
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
`addEnterFiller()` replaces the list for that language.
|
|
642
|
+
|
|
643
|
+
### Exit Fillers
|
|
644
|
+
|
|
645
|
+
Exit fillers play when the conversation leaves the context:
|
|
646
|
+
|
|
647
|
+
```typescript
|
|
648
|
+
ctx.setExitFillers({
|
|
649
|
+
'en-US': ['Alright, moving on.', 'Let me transfer you now.'],
|
|
650
|
+
});
|
|
651
|
+
|
|
652
|
+
ctx.addExitFiller('fr-FR', ['Un instant, s\'il vous plait.']);
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
The SDK serializes them as `enter_fillers` and `exit_fillers`.
|
|
656
|
+
|
|
657
|
+
---
|
|
658
|
+
|
|
659
|
+
## Validation
|
|
660
|
+
|
|
661
|
+
`ContextBuilder.validate()` checks the structure before serialization. It throws when any of these fails:
|
|
662
|
+
|
|
663
|
+
1. At least one context exists.
|
|
664
|
+
2. A single context is named `'default'`.
|
|
665
|
+
3. Every context has at least one step.
|
|
666
|
+
4. Every `initial_step` names a step in its context.
|
|
667
|
+
5. Every context in a context's or step's `valid_contexts` exists.
|
|
668
|
+
6. Every step in a step's `valid_steps` exists in the context, or is `next`.
|
|
669
|
+
7. Gather question keys are unique within a step.
|
|
670
|
+
8. Every gather `completion_action` is `next_step` on a step that has a following step, or names a step in the context.
|
|
671
|
+
9. No registered tool is named `next_step`, `change_context` or `gather_submit`.
|
|
672
|
+
10. Every name in a step's or question's `functions` is a registered tool or a reserved native tool.
|
|
673
|
+
|
|
674
|
+
The last two checks run when the builder is attached to an agent, which `agent.defineContexts()` does. `toDict()` calls `validate()`, and the agent calls `toDict()` when it renders the SWML:
|
|
675
|
+
|
|
676
|
+
```typescript
|
|
677
|
+
const cb = new ContextBuilder();
|
|
678
|
+
const ctx = cb.addContext('default');
|
|
679
|
+
ctx.addStep('welcome').setText('Greet the caller.');
|
|
680
|
+
|
|
681
|
+
// Explicit validation
|
|
682
|
+
cb.validate(); // throws if invalid
|
|
683
|
+
|
|
684
|
+
// Implicit validation on serialization
|
|
685
|
+
const swml = cb.toDict(); // calls validate() internally
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
### Common Validation Errors
|
|
689
|
+
|
|
690
|
+
These are the errors you're most likely to see:
|
|
691
|
+
|
|
692
|
+
| Error | Cause |
|
|
693
|
+
|---|---|
|
|
694
|
+
| `At least one context must be defined` | No contexts were added |
|
|
695
|
+
| `When using a single context, it must be named 'default'` | One context exists but isn't named `'default'` |
|
|
696
|
+
| `Context 'X' must have at least one step` | A context has no steps |
|
|
697
|
+
| `Context 'X' references unknown context 'Y'` | A context's `setValidContexts()` names a context that doesn't exist |
|
|
698
|
+
| `Step 'X' in context 'C' references unknown step 'Y'` | `setValidSteps()` names a step that isn't in the context |
|
|
699
|
+
| `Step 'X' in context 'C' references unknown context 'Y'` | A step's `setValidContexts()` names a context that doesn't exist |
|
|
700
|
+
| `Context/step 'functions' whitelist references unknown SWAIG function(s): ...` | A `functions` list names a tool that isn't registered |
|
|
701
|
+
| `Step 'X' has no text or POM sections defined` | A step has neither `setText()` nor `addSection()`/`addBullets()`; thrown by `toDict()` |
|
|
702
|
+
|
|
703
|
+
---
|
|
704
|
+
|
|
705
|
+
## Real-World Example
|
|
706
|
+
|
|
707
|
+
This customer service agent has three contexts. It starts in `default`, which greets and routes the caller, then moves to `troubleshooting` or `resolution`:
|
|
708
|
+
|
|
709
|
+
<!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
|
|
710
|
+
```typescript
|
|
711
|
+
import { AgentBase } from '@signalwire/sdk';
|
|
712
|
+
|
|
713
|
+
const agent = new AgentBase({ name: 'customer-service' });
|
|
714
|
+
agent.setPromptText('You are a customer service agent for TechCo.');
|
|
715
|
+
|
|
716
|
+
// Define the tools
|
|
717
|
+
agent.defineTool({
|
|
718
|
+
name: 'lookup_account',
|
|
719
|
+
description: 'Look up a customer account by account number.',
|
|
720
|
+
parameters: {
|
|
721
|
+
account_number: { type: 'string', description: 'The customer account number.' },
|
|
722
|
+
},
|
|
723
|
+
handler: async (args) => {
|
|
724
|
+
// ... account lookup logic
|
|
725
|
+
return { response: `Account found: ${args.account_number}` };
|
|
726
|
+
},
|
|
727
|
+
});
|
|
728
|
+
|
|
729
|
+
agent.defineTool({
|
|
730
|
+
name: 'create_ticket',
|
|
731
|
+
description: 'Create a support ticket for the customer.',
|
|
732
|
+
parameters: {
|
|
733
|
+
issue: { type: 'string', description: 'Description of the issue.' },
|
|
734
|
+
priority: { type: 'string', description: 'Ticket priority: low, medium, high.' },
|
|
735
|
+
},
|
|
736
|
+
handler: async (args) => {
|
|
737
|
+
return { response: `Ticket created: ${args.issue} (${args.priority})` };
|
|
738
|
+
},
|
|
739
|
+
});
|
|
740
|
+
|
|
741
|
+
agent.defineTool({
|
|
742
|
+
name: 'process_refund',
|
|
743
|
+
description: 'Process a refund for a customer.',
|
|
744
|
+
parameters: {
|
|
745
|
+
amount: { type: 'number', description: 'Refund amount in dollars.' },
|
|
746
|
+
reason: { type: 'string', description: 'Reason for the refund.' },
|
|
747
|
+
},
|
|
748
|
+
handler: async (args) => {
|
|
749
|
+
return { response: `Refund of $${args.amount} processed.` };
|
|
750
|
+
},
|
|
751
|
+
});
|
|
752
|
+
|
|
753
|
+
// Build the conversation flow
|
|
754
|
+
const cb = agent.defineContexts();
|
|
755
|
+
|
|
756
|
+
// Context 1: greeting and routing (the starting context)
|
|
757
|
+
const greeting = cb.addContext('default');
|
|
758
|
+
greeting.addEnterFiller('en-US', ['Welcome. Let me help you today.']);
|
|
759
|
+
greeting.setValidContexts(['troubleshooting', 'resolution']);
|
|
760
|
+
|
|
761
|
+
greeting.addStep('welcome', {
|
|
762
|
+
task: 'Greet the customer warmly and ask how you can help today.',
|
|
763
|
+
criteria: 'The customer has stated the nature of their issue.',
|
|
764
|
+
functions: 'none',
|
|
765
|
+
validSteps: ['identify'],
|
|
766
|
+
});
|
|
767
|
+
|
|
768
|
+
greeting.addStep('identify', {
|
|
769
|
+
task: 'Verify the customer identity by asking for their account number.',
|
|
770
|
+
criteria: 'Account has been looked up and verified.',
|
|
771
|
+
functions: ['lookup_account'],
|
|
772
|
+
validSteps: ['route'],
|
|
773
|
+
});
|
|
774
|
+
|
|
775
|
+
const route = greeting.addStep('route');
|
|
776
|
+
route.addSection('Task', 'Determine the appropriate department for the customer issue.');
|
|
777
|
+
route.addBullets('Routing Rules', [
|
|
778
|
+
'Technical issues (connectivity, hardware, software): troubleshooting context',
|
|
779
|
+
'Billing, refunds, or account changes: resolution context',
|
|
780
|
+
'If unclear, ask a clarifying question before routing',
|
|
781
|
+
]);
|
|
782
|
+
route.setStepCriteria('The issue category has been determined.');
|
|
783
|
+
route.setValidContexts(['troubleshooting', 'resolution']);
|
|
784
|
+
route.setFunctions('none');
|
|
785
|
+
|
|
786
|
+
// Context 2: troubleshooting
|
|
787
|
+
const troubleshooting = cb.addContext('troubleshooting');
|
|
788
|
+
troubleshooting.setConsolidate(true);
|
|
789
|
+
troubleshooting.addEnterFiller('en-US', [
|
|
790
|
+
'Let me look into that technical issue for you.',
|
|
791
|
+
'One moment while I pull up our troubleshooting guide.',
|
|
792
|
+
]);
|
|
793
|
+
troubleshooting.setExitFillers({
|
|
794
|
+
'en-US': ['Let me get you to the right place.'],
|
|
795
|
+
});
|
|
796
|
+
troubleshooting.setValidContexts(['resolution']);
|
|
797
|
+
|
|
798
|
+
troubleshooting.addSystemSection('Role', 'You are a technical support specialist.');
|
|
799
|
+
troubleshooting.addSystemBullets('Approach', [
|
|
800
|
+
'Start with the least disruptive fix first',
|
|
801
|
+
'Ask the customer to confirm each step',
|
|
802
|
+
'Escalate to a ticket if three attempts fail',
|
|
803
|
+
]);
|
|
804
|
+
|
|
805
|
+
const diagnose = troubleshooting.addStep('diagnose');
|
|
806
|
+
diagnose.setText('Ask the customer to describe their technical issue in detail.');
|
|
807
|
+
diagnose.setStepCriteria('The specific technical problem is understood.');
|
|
808
|
+
diagnose.setFunctions('none');
|
|
809
|
+
diagnose.setValidSteps(['guided_fix', 'escalate']);
|
|
810
|
+
|
|
811
|
+
const guidedFix = troubleshooting.addStep('guided_fix');
|
|
812
|
+
guidedFix.addSection('Task', 'Walk the customer through step-by-step troubleshooting.');
|
|
813
|
+
guidedFix.addBullets('Steps', [
|
|
814
|
+
'Have the customer restart their device',
|
|
815
|
+
'Check network connectivity',
|
|
816
|
+
'Verify software is up to date',
|
|
817
|
+
'Try clearing the cache',
|
|
818
|
+
]);
|
|
819
|
+
guidedFix.setStepCriteria('The issue is resolved OR three troubleshooting steps have been attempted.');
|
|
820
|
+
guidedFix.setFunctions('none');
|
|
821
|
+
guidedFix.setValidSteps(['escalate']);
|
|
822
|
+
guidedFix.setValidContexts(['resolution']);
|
|
823
|
+
|
|
824
|
+
const escalate = troubleshooting.addStep('escalate');
|
|
825
|
+
escalate.addSection('Task', 'Create a support ticket for the unresolved issue.');
|
|
826
|
+
escalate.setStepCriteria('A support ticket has been created.');
|
|
827
|
+
escalate.setFunctions(['create_ticket']);
|
|
828
|
+
escalate.setValidContexts(['resolution']);
|
|
829
|
+
|
|
830
|
+
// Context 3: resolution
|
|
831
|
+
const resolution = cb.addContext('resolution');
|
|
832
|
+
resolution.setIsolated(true);
|
|
833
|
+
resolution.addEnterFiller('en-US', ['Let me wrap things up for you.']);
|
|
834
|
+
|
|
835
|
+
const summarize = resolution.addStep('summarize');
|
|
836
|
+
summarize.setText('Summarize what was accomplished during this call.');
|
|
837
|
+
summarize.setStepCriteria('A summary has been provided to the customer.');
|
|
838
|
+
summarize.setFunctions('none');
|
|
839
|
+
summarize.setValidSteps(['refund_check', 'goodbye']);
|
|
840
|
+
|
|
841
|
+
const refundCheck = resolution.addStep('refund_check');
|
|
842
|
+
refundCheck.addSection('Task', 'Determine if a refund or credit is appropriate.');
|
|
843
|
+
refundCheck.addBullets('Policy', [
|
|
844
|
+
'Refunds up to $50 can be issued immediately',
|
|
845
|
+
'Refunds over $50 require manager approval, so create a ticket instead',
|
|
846
|
+
'Always confirm the refund amount with the customer before processing',
|
|
847
|
+
]);
|
|
848
|
+
refundCheck.setStepCriteria('Refund has been processed or determined not applicable.');
|
|
849
|
+
refundCheck.setFunctions(['process_refund', 'create_ticket']);
|
|
850
|
+
refundCheck.setValidSteps(['goodbye']);
|
|
851
|
+
|
|
852
|
+
// Gather customer satisfaction info before leaving step mode
|
|
853
|
+
const goodbye = resolution.addStep('goodbye');
|
|
854
|
+
goodbye.setText('Thank the customer and collect feedback.');
|
|
855
|
+
goodbye.setFunctions('none');
|
|
856
|
+
goodbye.setGatherInfo({
|
|
857
|
+
outputKey: 'satisfaction',
|
|
858
|
+
prompt: 'Ask the caller for brief feedback before the call ends.',
|
|
859
|
+
});
|
|
860
|
+
goodbye.addGatherQuestion({
|
|
861
|
+
key: 'rating',
|
|
862
|
+
question: 'On a scale of 1-5, how would you rate your experience today?',
|
|
863
|
+
type: 'integer',
|
|
864
|
+
confirm: true,
|
|
865
|
+
});
|
|
866
|
+
goodbye.addGatherQuestion({
|
|
867
|
+
key: 'comments',
|
|
868
|
+
question: 'Do you have any additional comments or suggestions?',
|
|
869
|
+
});
|
|
870
|
+
goodbye.setEnd(true);
|
|
871
|
+
|
|
872
|
+
// Start the server
|
|
873
|
+
agent.serve();
|
|
874
|
+
```
|
|
875
|
+
|
|
876
|
+
### How This Flow Works
|
|
877
|
+
|
|
878
|
+
The flow runs in three stages:
|
|
879
|
+
|
|
880
|
+
1. The conversation begins in the `default` context. The model greets the customer, looks up the account, and routes the call.
|
|
881
|
+
2. Technical issues go to the `troubleshooting` context, which consolidates the earlier conversation. The model walks through diagnostic steps, and can escalate by creating a ticket.
|
|
882
|
+
3. Every path ends in the `resolution` context, which is isolated, so its history starts fresh. It summarizes the call, can process a refund, and collects feedback before leaving step mode.
|
|
883
|
+
|
|
884
|
+
`setValidContexts()` and `setValidSteps()` limit where each step can go. Each step calls `setFunctions()`, so no step inherits the tools of the step before it. `process_refund`, for example, is available only in the `refund_check` step. `setEnd(true)` on `goodbye` doesn't hang up; add a tool that returns `FunctionResult.hangup()` for that.
|