@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,846 @@
|
|
|
1
|
+
# SignalWire AI Agents TypeScript SDK Architecture
|
|
2
|
+
|
|
3
|
+
This page explains how the TypeScript SDK is put together. It covers the classes an agent is built from, how it renders SWML, and what happens to each request SignalWire sends it.
|
|
4
|
+
|
|
5
|
+
<!-- snippet-setup -->
|
|
6
|
+
```ts
|
|
7
|
+
export {}; // treat each example as a module (top-level await)
|
|
8
|
+
declare global {
|
|
9
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
10
|
+
const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
|
|
11
|
+
}
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Table of Contents
|
|
15
|
+
|
|
16
|
+
- [Overview](#overview)
|
|
17
|
+
- [Core Components](#core-components)
|
|
18
|
+
- [AgentBase](#agentbase)
|
|
19
|
+
- [PromptManager and PomBuilder](#promptmanager-and-pombuilder)
|
|
20
|
+
- [SwmlBuilder](#swmlbuilder)
|
|
21
|
+
- [SwaigFunction](#swaigfunction)
|
|
22
|
+
- [FunctionResult](#functionresult)
|
|
23
|
+
- [SessionManager](#sessionmanager)
|
|
24
|
+
- [ContextBuilder](#contextbuilder)
|
|
25
|
+
- [DataMap](#datamap)
|
|
26
|
+
- [Composition Architecture](#composition-architecture)
|
|
27
|
+
- [SWML Rendering Pipeline](#swml-rendering-pipeline)
|
|
28
|
+
- [Request Flow](#request-flow)
|
|
29
|
+
- [SWML Request (GET/POST /)](#swml-request-getpost-)
|
|
30
|
+
- [SWAIG Function Dispatch (POST /swaig)](#swaig-function-dispatch-post-swaig)
|
|
31
|
+
- [Post-Prompt Handler (POST /post_prompt)](#post-prompt-handler-post-post_prompt)
|
|
32
|
+
- [Tool System](#tool-system)
|
|
33
|
+
- [SwaigFunction Wrapper](#swaigfunction-wrapper)
|
|
34
|
+
- [Handler Signature](#handler-signature)
|
|
35
|
+
- [Result Serialization](#result-serialization)
|
|
36
|
+
- [DataMap Tools](#datamap-tools)
|
|
37
|
+
- [Session Management](#session-management)
|
|
38
|
+
- [Token Format](#token-format)
|
|
39
|
+
- [Token Generation](#token-generation)
|
|
40
|
+
- [Token Validation](#token-validation)
|
|
41
|
+
- [Proxy Detection](#proxy-detection)
|
|
42
|
+
- [Security Layers](#security-layers)
|
|
43
|
+
- [Basic Authentication](#basic-authentication)
|
|
44
|
+
- [CORS](#cors)
|
|
45
|
+
- [Security Headers](#security-headers)
|
|
46
|
+
- [Rate Limiting](#rate-limiting)
|
|
47
|
+
- [Allowed Hosts](#allowed-hosts)
|
|
48
|
+
- [Request Size Limits](#request-size-limits)
|
|
49
|
+
- [Webhook Signatures and TLS](#webhook-signatures-and-tls)
|
|
50
|
+
- [Extension Points](#extension-points)
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Overview
|
|
55
|
+
|
|
56
|
+
Each agent is an HTTP service. It serves a SWML document, the JSON call-flow instructions SignalWire runs. It also answers the SWAIG requests SignalWire sends when the model on the call uses a tool. The SDK builds on the [Hono](https://hono.dev/) web framework and uses Node.js `crypto` for its per-call tokens.
|
|
57
|
+
|
|
58
|
+
The diagram shows the parts of an agent and the requests of one call:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
+--------------------------------------------------+
|
|
62
|
+
| AgentBase (extends SWMLService) |
|
|
63
|
+
| |
|
|
64
|
+
| +----------------+ +---------------------+ |
|
|
65
|
+
| | PromptManager | | SessionManager | |
|
|
66
|
+
| | +----------+ | | (per-call HMAC | |
|
|
67
|
+
| | |PomBuilder| | | tokens) | |
|
|
68
|
+
| | +----------+ | +---------------------+ |
|
|
69
|
+
| +----------------+ |
|
|
70
|
+
| |
|
|
71
|
+
| +----------------+ +---------------------+ |
|
|
72
|
+
| | SwmlBuilder | | Tool registry | |
|
|
73
|
+
| | (the SWML | | Map<name, | |
|
|
74
|
+
| | document) | | SwaigFunction or | |
|
|
75
|
+
| +----------------+ | DataMap object> | |
|
|
76
|
+
| +---------------------+ |
|
|
77
|
+
| +----------------+ +---------------------+ |
|
|
78
|
+
| | ContextBuilder | | SkillManager | |
|
|
79
|
+
| | (optional) | | | |
|
|
80
|
+
| +----------------+ +---------------------+ |
|
|
81
|
+
| |
|
|
82
|
+
| +--------------------------------------------+ |
|
|
83
|
+
| | Hono app | |
|
|
84
|
+
| | GET/POST {route} -> SWML | |
|
|
85
|
+
| | POST {route}/swaig -> tool handler | |
|
|
86
|
+
| | POST {route}/post_prompt -> onSummary() | |
|
|
87
|
+
| | GET {route}/health, /ready (no auth) | |
|
|
88
|
+
| +--------------------------------------------+ |
|
|
89
|
+
+--------------------------------------------------+
|
|
90
|
+
|
|
91
|
+
Inbound call
|
|
92
|
+
|
|
|
93
|
+
v
|
|
94
|
+
SignalWire --POST--> {route} (returns the SWML)
|
|
95
|
+
|
|
|
96
|
+
v
|
|
97
|
+
The platform runs the SWML; its ai verb starts the model
|
|
98
|
+
|
|
|
99
|
+
v
|
|
100
|
+
Model uses a tool --POST--> {route}/swaig (runs the handler)
|
|
101
|
+
|
|
|
102
|
+
v
|
|
103
|
+
Call ends --POST--> {route}/post_prompt (delivers the summary)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
SignalWire requests the SWML with a `POST` whose body describes the call. The agent route also answers `GET`, which is useful for testing with a browser or `curl`. `GET {route}/swaig` and `GET {route}/post_prompt` return the SWML too; only a `POST` runs a tool or delivers a summary.
|
|
107
|
+
|
|
108
|
+
### AgentServer (Multi-Agent)
|
|
109
|
+
|
|
110
|
+
`AgentServer` hosts several agents on one port. `register(agent)` mounts the agent's route-relative router (`agent.asRouter()`) at the agent's route, so each agent's paths are its route plus the agent's own paths:
|
|
111
|
+
|
|
112
|
+
```text
|
|
113
|
+
AgentServer (Hono)
|
|
114
|
+
|-- /sales, /sales/swaig, /sales/post_prompt -> sales agent
|
|
115
|
+
|-- /support, /support/swaig, /support/post_prompt -> support agent
|
|
116
|
+
|-- /health -> server health check
|
|
117
|
+
|-- /ready -> server readiness check
|
|
118
|
+
|-- / -> agent listing (if no agent is registered at /)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`register()` copies the agent's routes when it's called. `setupSipRouting()` and `registerGlobalRoutingCallback()` can be called before or after it, even after the server has served requests: a change to the routes rebuilds the server's app, so the callback is served at the agent's route, such as `/sales/sip`.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Core Components
|
|
126
|
+
|
|
127
|
+
### AgentBase
|
|
128
|
+
|
|
129
|
+
**File**: `src/AgentBase.ts`
|
|
130
|
+
|
|
131
|
+
`AgentBase` extends `SWMLService` and holds the other components as fields. It's responsible for:
|
|
132
|
+
|
|
133
|
+
- **HTTP**: building the Hono app, its middleware and routes, and starting the server.
|
|
134
|
+
- **SWML rendering**: assembling the document from the call-flow verbs, the prompt, the tools and the AI settings.
|
|
135
|
+
- **Tool dispatch**: running the handler for a SWAIG request, after checking its per-call token.
|
|
136
|
+
- **Proxy detection**: finding the external URL for the webhook URLs in the SWML.
|
|
137
|
+
- **Per-request configuration**: making a per-request copy of the agent for a dynamic config callback.
|
|
138
|
+
- **Lifecycle hooks**: `onSummary`, `onFunctionCall`, `onSwmlRequest`, `onDebugEvent`, `onCallEnd` and `onError`.
|
|
139
|
+
|
|
140
|
+
`SWMLService` supplies the `SwmlBuilder`, the tool registry, basic-auth resolution, routing callbacks and `handleRequest()`, the framework-free request handler that the agent's SWML routes call.
|
|
141
|
+
|
|
142
|
+
### PromptManager and PomBuilder
|
|
143
|
+
|
|
144
|
+
**Files**: `src/PromptManager.ts`, `src/PomBuilder.ts`
|
|
145
|
+
|
|
146
|
+
`PromptManager` holds the agent's prompt and post-prompt. The prompt has two forms:
|
|
147
|
+
|
|
148
|
+
1. **Raw text**: a string set with `setPromptText()`. When set, it takes precedence over sections.
|
|
149
|
+
2. **Sections (POM)**: a `PomBuilder` of sections added with `promptAddSection()`, used when the `usePom` option is `true` (the default).
|
|
150
|
+
|
|
151
|
+
Each section has a `title`, a `body`, `bullets` (optionally `numbered`) and `subsections`. The rendered SWML carries sections as a structured `prompt.pom` array. Raw text goes in `prompt.text`.
|
|
152
|
+
|
|
153
|
+
`PromptManager.getPrompt()` returns:
|
|
154
|
+
1. The raw text, if set.
|
|
155
|
+
2. The sections rendered as Markdown, if sections exist.
|
|
156
|
+
3. An empty string otherwise.
|
|
157
|
+
|
|
158
|
+
### SwmlBuilder
|
|
159
|
+
|
|
160
|
+
**File**: `src/SwmlBuilder.ts`
|
|
161
|
+
|
|
162
|
+
`SwmlBuilder` holds a SWML document:
|
|
163
|
+
|
|
164
|
+
```json
|
|
165
|
+
{
|
|
166
|
+
"version": "1.0.0",
|
|
167
|
+
"sections": {
|
|
168
|
+
"main": [
|
|
169
|
+
{ "answer": {} },
|
|
170
|
+
{ "ai": { "prompt": { "text": "You are a support agent." } } },
|
|
171
|
+
{ "hangup": {} }
|
|
172
|
+
]
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
It has these methods:
|
|
178
|
+
|
|
179
|
+
| Method | Description |
|
|
180
|
+
|--------|-------------|
|
|
181
|
+
| `reset()` | Replaces the document with an empty `{ version, sections: { main: [] } }`. |
|
|
182
|
+
| `addVerb(verbName, config)` | Validates the verb against the bundled schema, then appends `{ [verbName]: config }` to `main`. |
|
|
183
|
+
| `addVerbToSection(section, verb, config)` | Validates, then appends to a named section, creating it if needed. |
|
|
184
|
+
| `addSection(section)` | Adds an empty section. |
|
|
185
|
+
| `build()` | Returns the document object. |
|
|
186
|
+
| `render()` | Returns `JSON.stringify(document)`. |
|
|
187
|
+
|
|
188
|
+
The constructor also adds a method for each verb in the bundled schema, such as `answer()`, `play()` and `connect()`, which call `addVerb()` and return the builder. `SWML_SKIP_SCHEMA_VALIDATION=true` turns validation off.
|
|
189
|
+
|
|
190
|
+
`AgentBase.renderSwml()` calls `reset()`, adds every phase's verbs, and returns `render()`, so the builder holds only the latest render.
|
|
191
|
+
|
|
192
|
+
### SwaigFunction
|
|
193
|
+
|
|
194
|
+
**File**: `src/SwaigFunction.ts`
|
|
195
|
+
|
|
196
|
+
`SwaigFunction` wraps a tool handler with the metadata SWAIG needs. Its main fields are:
|
|
197
|
+
|
|
198
|
+
<!-- snippet: no-compile field-shape reference for SwaigFunction; abbreviated types, not runnable -->
|
|
199
|
+
```typescript
|
|
200
|
+
class SwaigFunction {
|
|
201
|
+
name: string; // Tool name, read by the model
|
|
202
|
+
handler: SwaigHandler; // The callback function
|
|
203
|
+
description: string; // Tells the model when to use the tool
|
|
204
|
+
parameters: Record; // JSON Schema for the arguments
|
|
205
|
+
secure: boolean; // Requires a per-call token (default true)
|
|
206
|
+
fillers?: Record; // Per-language filler phrases
|
|
207
|
+
waitFile?: string; // Audio to play while the tool runs
|
|
208
|
+
waitFileLoops?: number; // Loop count for the wait file
|
|
209
|
+
webhookUrl?: string; // External webhook, rendered in place of the agent's /swaig
|
|
210
|
+
required: string[]; // Required parameter names
|
|
211
|
+
extraFields: Record; // Additional SWAIG fields, merged into the definition
|
|
212
|
+
onError?: SwaigErrorHandler; // Per-tool error hook
|
|
213
|
+
errorMessage?: string; // Response when the handler throws
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
`execute(args, rawData)` runs the handler and returns the result as a SWAIG response object. [Result Serialization](#result-serialization) lists how each return type is converted.
|
|
218
|
+
|
|
219
|
+
### FunctionResult
|
|
220
|
+
|
|
221
|
+
**File**: `src/FunctionResult.ts`
|
|
222
|
+
|
|
223
|
+
`FunctionResult` is a builder for a tool's response. It carries:
|
|
224
|
+
|
|
225
|
+
- `response`: text returned to the model. It's context for the model, not speech: the model decides what to say.
|
|
226
|
+
- `action`: an ordered list of actions for the platform to run.
|
|
227
|
+
- `postProcess`: when `true`, the model gets one more turn to respond before the actions run.
|
|
228
|
+
|
|
229
|
+
A `FunctionResult` can also carry a structured response, `{ tool_result, tool_prompt }`, set with the constructor option or `setToolResponse()`. It separates the facts from the instructions for the model. `toDict()` serializes it:
|
|
230
|
+
|
|
231
|
+
<!-- snippet: no-compile method-body excerpt shown outside its class, not a standalone module -->
|
|
232
|
+
```typescript
|
|
233
|
+
toDict(): SwaigResultDict {
|
|
234
|
+
const result: SwaigResultDict = {};
|
|
235
|
+
if (this._toolResponse && Object.keys(this._toolResponse).length > 0) {
|
|
236
|
+
result.response = { ...this._toolResponse };
|
|
237
|
+
} else if (this.response) {
|
|
238
|
+
result.response = this.response;
|
|
239
|
+
}
|
|
240
|
+
if (this.action.length > 0) result.action = this.action;
|
|
241
|
+
if (this.postProcess && this.action.length > 0) result.post_process = true;
|
|
242
|
+
if (Object.keys(result).length === 0) result.response = 'Action completed.';
|
|
243
|
+
return result;
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
The fallback `"Action completed."` keeps the response from being empty.
|
|
248
|
+
|
|
249
|
+
The action methods fall into these groups:
|
|
250
|
+
|
|
251
|
+
| Category | Methods |
|
|
252
|
+
|----------|---------|
|
|
253
|
+
| Call control | `connect()`, `hangup()`, `hold()`, `stop()`, `waitForUser()` |
|
|
254
|
+
| Audio | `say()`, `playBackgroundFile()`, `stopBackgroundFile()` |
|
|
255
|
+
| Speech | `addDynamicHints()`, `clearDynamicHints()`, `setEndOfSpeechTimeout()` |
|
|
256
|
+
| Data | `updateGlobalData()`, `removeGlobalData()`, `setMetadata()`, `removeMetadata()` |
|
|
257
|
+
| SWML | `executeSwml()`, `swmlChangeStep()`, `swmlChangeContext()`, `swmlUserEvent()` |
|
|
258
|
+
| Context | `switchContext()` |
|
|
259
|
+
| Functions | `toggleFunctions()`, `enableFunctionsOnTimeout()`, `updateSettings()` |
|
|
260
|
+
| Comms | `sendSms()`, `recordCall()`, `stopRecordCall()`, `tap()`, `stopTap()`, `sipRefer()` |
|
|
261
|
+
| Rooms | `joinRoom()`, `joinConference()` |
|
|
262
|
+
| RPC | `executeRpc()`, `rpcDial()`, `rpcAiMessage()`, `rpcAiUnhold()` |
|
|
263
|
+
| Payments | `pay()` |
|
|
264
|
+
|
|
265
|
+
### SessionManager
|
|
266
|
+
|
|
267
|
+
**File**: `src/SessionManager.ts`
|
|
268
|
+
|
|
269
|
+
`SessionManager` creates and checks the HMAC-SHA256 tokens that protect secure tools and the post-prompt URL. It stores nothing for a token: everything it needs is in the token. See [Session Management](#session-management).
|
|
270
|
+
|
|
271
|
+
### ContextBuilder
|
|
272
|
+
|
|
273
|
+
**File**: `src/ContextBuilder.ts`
|
|
274
|
+
|
|
275
|
+
`ContextBuilder` defines multi-step conversations. It holds named contexts, each an ordered list of steps. A step has prompt content, completion criteria, the functions it allows, and the steps and contexts it can move to:
|
|
276
|
+
|
|
277
|
+
```text
|
|
278
|
+
ContextBuilder
|
|
279
|
+
|-- Context "greeting"
|
|
280
|
+
| |-- Step "welcome" (text, criteria, functions)
|
|
281
|
+
| |-- Step "identify" (gather_info questions)
|
|
282
|
+
|
|
|
283
|
+
|-- Context "support"
|
|
284
|
+
|-- Step "diagnose" (POM sections, valid_steps)
|
|
285
|
+
|-- Step "resolve" (end: true)
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`defineContexts()` returns the agent's builder, creating it on first use. `renderSwml()` puts the contexts inside the `ai` verb's prompt object, as `prompt.contexts`.
|
|
289
|
+
|
|
290
|
+
### DataMap
|
|
291
|
+
|
|
292
|
+
**File**: `src/DataMap.ts`
|
|
293
|
+
|
|
294
|
+
`DataMap` builds a tool that the SignalWire platform runs itself, without a request to the agent. A DataMap tool can have:
|
|
295
|
+
|
|
296
|
+
- **Webhooks**: HTTP requests to external APIs, with templates for the request and the output.
|
|
297
|
+
- **Expressions**: patterns matched against template values, each with its output.
|
|
298
|
+
- **Outputs**: `FunctionResult` objects, serialized as the tool's response.
|
|
299
|
+
|
|
300
|
+
DataMap tools are stored in the tool registry as plain objects, not `SwaigFunction` instances. For the template syntax, see the DataMap guide.
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Composition Architecture
|
|
305
|
+
|
|
306
|
+
The Python SDK builds `AgentBase` from several mixin classes. The TypeScript SDK has one level of inheritance, `AgentBase extends SWMLService`, and holds the rest as fields:
|
|
307
|
+
|
|
308
|
+
```text
|
|
309
|
+
Python SDK TypeScript SDK
|
|
310
|
+
-------------------------- ---------------------------------------
|
|
311
|
+
class AgentBase( class SWMLService {
|
|
312
|
+
AuthMixin, WebMixin, swmlBuilder: SwmlBuilder
|
|
313
|
+
SWMLService, PromptMixin, toolRegistry: Map<...>
|
|
314
|
+
SkillMixin, AIConfigMixin, _app: Hono
|
|
315
|
+
ServerlessMixin, StateMixin, _routingCallbacks: Map<...>
|
|
316
|
+
MCPServerMixin) }
|
|
317
|
+
class AgentBase extends SWMLService {
|
|
318
|
+
_promptManager: PromptManager
|
|
319
|
+
sessionManager: SessionManager
|
|
320
|
+
_skillManager: SkillManager
|
|
321
|
+
contextsBuilder: ContextBuilder | null
|
|
322
|
+
perCallConfigs: DynamicConfigCallback[]
|
|
323
|
+
}
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
The public methods on `AgentBase` delegate to these fields. For example, `setPromptText()` sets the prompt on the `PromptManager`. You configure an agent through its methods, and don't need to reach the fields.
|
|
327
|
+
|
|
328
|
+
The tool registry holds two kinds of entries: `SwaigFunction` instances for tools with a handler, and plain objects for DataMap tools.
|
|
329
|
+
|
|
330
|
+
A dynamic config callback, or one added with `addPerCallConfig()`, receives a per-request copy of the agent. The copy has its own prompt, tools, hints, languages, pronunciations, params, global data, call-flow verbs, contexts and routing callbacks. The callback's changes stay on that request. Skills the agent loaded are shared with the copy without running their setup again. The SWML is rendered from the copy, `/swaig` and `/post_prompt` requests run on it, and the original agent isn't modified.
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## SWML Rendering Pipeline
|
|
335
|
+
|
|
336
|
+
`renderSwml(callId?, modifications?)` builds the SWML document for one call in five phases:
|
|
337
|
+
|
|
338
|
+
```text
|
|
339
|
+
renderSwml(callId?, modifications?)
|
|
340
|
+
|
|
|
341
|
+
|-- defineTools() (once per agent), swmlBuilder.reset()
|
|
342
|
+
|-- callId: the argument, or a new random ID
|
|
343
|
+
|
|
|
344
|
+
|-- Build webhook URLs
|
|
345
|
+
| - base: external URL + route, with the basic-auth credentials in it
|
|
346
|
+
| - {base}/swaig with the SWAIG query params (defaults.web_hook_url)
|
|
347
|
+
| - a secure tool's URL adds __token, a token for that tool and call
|
|
348
|
+
| - {base}/post_prompt with a post_prompt token, if a post-prompt is set
|
|
349
|
+
|
|
|
350
|
+
|-- Build the SWAIG object
|
|
351
|
+
| - native_functions, includes, internal_fillers
|
|
352
|
+
| - functions[] from the tool registry:
|
|
353
|
+
| SwaigFunction: function, description, parameters,
|
|
354
|
+
| fillers, wait_file, wait_file_loops, web_hook_url, extra fields
|
|
355
|
+
| DataMap object: copied as it is
|
|
356
|
+
| - defaults.web_hook_url (when there are functions)
|
|
357
|
+
| - mcp_servers
|
|
358
|
+
|
|
|
359
|
+
|-- PHASE 1: pre-answer verbs (addPreAnswerVerb)
|
|
360
|
+
|-- PHASE 2: answer, if autoAnswer
|
|
361
|
+
|-- PHASE 3: record_call, if recordCall; post-answer verbs (addPostAnswerVerb)
|
|
362
|
+
|-- PHASE 4: the ai verb
|
|
363
|
+
| prompt: { pom: [...] } or { text: ... }, plus prompt LLM params,
|
|
364
|
+
| and contexts, if contexts are defined
|
|
365
|
+
| post_prompt, post_prompt_url
|
|
366
|
+
| SWAIG, hints, languages, multilingual, pronounce, params, global_data
|
|
367
|
+
| debug_webhook_url, debug_webhook_level, if debug events are on
|
|
368
|
+
| modifications from onSwmlRequest: global_data merged, other keys replaced
|
|
369
|
+
|-- PHASE 5: post-AI verbs (addPostAiVerb)
|
|
370
|
+
|
|
|
371
|
+
|-- Return swmlBuilder.render() (a JSON string)
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Verbs you add are validated against the bundled schema. The `answer`, `record_call` and `ai` verbs the agent builds itself aren't.
|
|
375
|
+
|
|
376
|
+
A document with every phase looks like this:
|
|
377
|
+
|
|
378
|
+
```json
|
|
379
|
+
{
|
|
380
|
+
"version": "1.0.0",
|
|
381
|
+
"sections": {
|
|
382
|
+
"main": [
|
|
383
|
+
{ "play": { "url": "https://example.com/ring.wav" } },
|
|
384
|
+
{ "answer": {} },
|
|
385
|
+
{ "record_call": { "format": "mp4", "stereo": true } },
|
|
386
|
+
{
|
|
387
|
+
"ai": {
|
|
388
|
+
"prompt": { "text": "..." },
|
|
389
|
+
"post_prompt": { "text": "..." },
|
|
390
|
+
"post_prompt_url": "https://user:pass@agents.example.com/support/post_prompt?__token=...",
|
|
391
|
+
"SWAIG": {
|
|
392
|
+
"functions": [ ... ],
|
|
393
|
+
"defaults": { "web_hook_url": "https://user:pass@agents.example.com/support/swaig" }
|
|
394
|
+
},
|
|
395
|
+
"hints": [ "SignalWire", "HIPAA" ],
|
|
396
|
+
"params": { "temperature": 0.7 },
|
|
397
|
+
"global_data": { "company": "Acme" }
|
|
398
|
+
}
|
|
399
|
+
},
|
|
400
|
+
{ "hangup": {} }
|
|
401
|
+
]
|
|
402
|
+
}
|
|
403
|
+
}
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
---
|
|
407
|
+
|
|
408
|
+
## Request Flow
|
|
409
|
+
|
|
410
|
+
### SWML Request (GET/POST /)
|
|
411
|
+
|
|
412
|
+
A request for the SWML goes through these steps:
|
|
413
|
+
|
|
414
|
+
```text
|
|
415
|
+
Request from SignalWire (POST) or a browser (GET)
|
|
416
|
+
|
|
|
417
|
+
v
|
|
418
|
+
Hono middleware:
|
|
419
|
+
1. Security headers (added to the response)
|
|
420
|
+
2. Request size limit (SWML_MAX_REQUEST_SIZE)
|
|
421
|
+
3. Allowed hosts (SWML_ALLOWED_HOSTS, if set)
|
|
422
|
+
4. Rate limit (SWML_RATE_LIMIT, if set)
|
|
423
|
+
5. CORS (SWML_CORS_ORIGINS)
|
|
424
|
+
6. CSRF origin check (SWML_CSRF_PROTECTION, if set)
|
|
425
|
+
7. Basic auth
|
|
426
|
+
8. Webhook signature, for a POST (if a signing key is set)
|
|
427
|
+
|
|
|
428
|
+
v
|
|
429
|
+
Route handler:
|
|
430
|
+
1. Proxy detection from the request headers (see Proxy Detection)
|
|
431
|
+
2. Parse the JSON body (none for a GET)
|
|
432
|
+
|
|
|
433
|
+
v
|
|
434
|
+
handleRequest(method, url, headers, body):
|
|
435
|
+
1. call_id: body.call_id or body.call.call_id for a POST; ?call_id= for a GET
|
|
436
|
+
2. For a POST to a routing-callback path: run the callback;
|
|
437
|
+
a returned route is sent as a 307 redirect
|
|
438
|
+
3. modifications = await onSwmlRequest(body, callbackPath, context)
|
|
439
|
+
4. The agent to render from: a per-request copy configured by the
|
|
440
|
+
dynamic config callbacks, or this agent when there are none
|
|
441
|
+
5. renderSwml(callId, modifications)
|
|
442
|
+
6. Return 200 with the SWML
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
### SWAIG Function Dispatch (POST /swaig)
|
|
446
|
+
|
|
447
|
+
A tool request from SignalWire goes through these steps:
|
|
448
|
+
|
|
449
|
+
```text
|
|
450
|
+
Request from SignalWire
|
|
451
|
+
|
|
|
452
|
+
v
|
|
453
|
+
Middleware (as for the SWML request; signature check when a signing key is set)
|
|
454
|
+
|
|
|
455
|
+
v
|
|
456
|
+
handleSwaig():
|
|
457
|
+
1. Parse the JSON body
|
|
458
|
+
2. Function name from body.function
|
|
459
|
+
- missing -> 400; longer than 128 characters or not an identifier -> 400
|
|
460
|
+
3. The agent to run on: the per-request copy, when there are dynamic config callbacks
|
|
461
|
+
4. Look the name up in that agent's tool registry
|
|
462
|
+
- not found, or not a SwaigFunction (a DataMap tool) -> 404 { error: "Unknown function: ..." }
|
|
463
|
+
5. If the tool is secure: check __token (or token) from the URL against the
|
|
464
|
+
function name and body.call_id. A missing or invalid token gets a 200 response
|
|
465
|
+
whose text says the token is invalid or expired; the handler doesn't run.
|
|
466
|
+
6. Arguments from body.argument.parsed[0], body.argument.raw, or body.arguments
|
|
467
|
+
7. onFunctionCall(name, args, body): a returned value is sent instead of running the handler
|
|
468
|
+
8. Run the handler with (args, body, agent), and send its result
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
### Post-Prompt Handler (POST /post_prompt)
|
|
472
|
+
|
|
473
|
+
The end-of-call summary goes through these steps:
|
|
474
|
+
|
|
475
|
+
```text
|
|
476
|
+
Request from SignalWire at the end of the call
|
|
477
|
+
|
|
|
478
|
+
v
|
|
479
|
+
Middleware (as for the SWML request)
|
|
480
|
+
|
|
|
481
|
+
v
|
|
482
|
+
handlePostPrompt():
|
|
483
|
+
1. Parse the JSON body
|
|
484
|
+
2. call_id from the body, or the URL's ?call_id=; if both are present and differ -> 400
|
|
485
|
+
3. Check __token for the post_prompt function and that call; missing or invalid -> 403
|
|
486
|
+
4. The agent to run on: the per-request copy, when there are dynamic config callbacks
|
|
487
|
+
5. findSummary(body): body.summary, else post_prompt_data.parsed[0],
|
|
488
|
+
else post_prompt_data.raw parsed as JSON, else the raw text, else null
|
|
489
|
+
6. await onSummary(summary, body); an error it throws is logged
|
|
490
|
+
7. Return { "success": true }, or onSummary's return value for a
|
|
491
|
+
fetch_conversation request
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
---
|
|
495
|
+
|
|
496
|
+
## Tool System
|
|
497
|
+
|
|
498
|
+
### SwaigFunction Wrapper
|
|
499
|
+
|
|
500
|
+
Each tool registered with `defineTool()` is a `SwaigFunction` in the tool registry, a `Map` keyed by name. `registerSwaigFunction()` stores a `SwaigFunction`, or a plain object for a DataMap tool:
|
|
501
|
+
|
|
502
|
+
<!-- snippet: no-compile registry illustration with `...` elision, not runnable -->
|
|
503
|
+
```typescript
|
|
504
|
+
// Handler-based tool
|
|
505
|
+
toolRegistry.set('get_weather', new SwaigFunction({ name, handler, description, ... }));
|
|
506
|
+
|
|
507
|
+
// DataMap tool (plain object)
|
|
508
|
+
toolRegistry.set('lookup_zip', { function: 'lookup_zip', description: '...', data_map: {...} });
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
Rendering walks the registry. A `SwaigFunction` becomes a definition with its schema and webhook URL. A plain object is copied as it is.
|
|
512
|
+
|
|
513
|
+
### Handler Signature
|
|
514
|
+
|
|
515
|
+
A handler receives the arguments, the whole request body, and the agent the request runs on:
|
|
516
|
+
|
|
517
|
+
<!-- snippet: no-compile handler type-alias reference, not runnable code -->
|
|
518
|
+
```typescript
|
|
519
|
+
type SwaigHandler = (
|
|
520
|
+
args: Record<string, unknown>, // Arguments the model supplied
|
|
521
|
+
rawData: SwaigRequest, // The full SWAIG request body
|
|
522
|
+
agent?: AgentBase, // The per-request copy, or the agent itself
|
|
523
|
+
) => FunctionResult | Record<string, unknown> | string
|
|
524
|
+
| Promise<FunctionResult | Record<string, unknown> | string>;
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
The third argument is the agent the request was configured on: the per-request copy when a dynamic config callback or `addPerCallConfig()` is in use. A handler that closes over the original agent sees the original, not the copy. The route awaits the handler. A synchronous or CPU-bound handler blocks Node's event loop, and every other request, until it returns.
|
|
528
|
+
|
|
529
|
+
### Result Serialization
|
|
530
|
+
|
|
531
|
+
`SwaigFunction` converts the handler's result like this:
|
|
532
|
+
|
|
533
|
+
```text
|
|
534
|
+
Handler returns:
|
|
535
|
+
|
|
|
536
|
+
|-- FunctionResult --> result.toDict()
|
|
537
|
+
|-- { response: ... } --> sent as it is
|
|
538
|
+
|-- object without response --> FunctionResult("Function completed successfully").toDict()
|
|
539
|
+
|-- anything else (a string) --> FunctionResult(String(value)).toDict()
|
|
540
|
+
|-- throws --> the tool's onError hook, then the agent's onError hook;
|
|
541
|
+
a FunctionResult either returns is sent. Otherwise
|
|
542
|
+
FunctionResult(errorMessage or the default message).toDict()
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
`FunctionResult.toDict()` produces an object like this one:
|
|
546
|
+
|
|
547
|
+
```json
|
|
548
|
+
{
|
|
549
|
+
"response": "The weather in Austin is 72F and sunny.",
|
|
550
|
+
"action": [
|
|
551
|
+
{ "set_global_data": { "last_city": "Austin" } }
|
|
552
|
+
]
|
|
553
|
+
}
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
`post_process` appears only when it's `true` and there are actions. If both `response` and `action` are empty, the response is `"Action completed."`.
|
|
557
|
+
|
|
558
|
+
### DataMap Tools
|
|
559
|
+
|
|
560
|
+
The SignalWire platform runs a DataMap tool itself, so it has a `data_map` key and no `web_hook_url`:
|
|
561
|
+
|
|
562
|
+
```json
|
|
563
|
+
{
|
|
564
|
+
"function": "check_status",
|
|
565
|
+
"description": "Check order status",
|
|
566
|
+
"parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } },
|
|
567
|
+
"data_map": {
|
|
568
|
+
"webhooks": [
|
|
569
|
+
{
|
|
570
|
+
"url": "https://api.example.com/orders/${args.order_id}",
|
|
571
|
+
"method": "GET",
|
|
572
|
+
"output": { "response": "Order status: ${status}" }
|
|
573
|
+
}
|
|
574
|
+
]
|
|
575
|
+
}
|
|
576
|
+
}
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
A webhook's JSON response is read from the root of the template data (`${status}`). The URL and params read the arguments as `${args.name}`, and the webhook's output as `${input.args.name}`. A request for a DataMap tool at the agent's `/swaig` gets `404`, because the agent has no handler for it.
|
|
580
|
+
|
|
581
|
+
---
|
|
582
|
+
|
|
583
|
+
## Session Management
|
|
584
|
+
|
|
585
|
+
`SessionManager` creates and checks the per-call tokens for secure tools and for the post-prompt URL. It stores no state for them: a token carries everything the check needs.
|
|
586
|
+
|
|
587
|
+
### Token Format
|
|
588
|
+
|
|
589
|
+
A token is the base64url encoding of five dot-separated fields:
|
|
590
|
+
|
|
591
|
+
```text
|
|
592
|
+
base64url( callId . functionName . expiry . nonce . hmacSignature )
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
| Field | Description |
|
|
596
|
+
|-------|-------------|
|
|
597
|
+
| `callId` | The call the token is for. |
|
|
598
|
+
| `functionName` | The function the token allows (`post_prompt` for the post-prompt URL). |
|
|
599
|
+
| `expiry` | Unix time, in seconds, when the token expires. |
|
|
600
|
+
| `nonce` | 16 random hex characters. |
|
|
601
|
+
| `hmacSignature` | The HMAC-SHA256 hex digest of `callId:functionName:expiry:nonce`. |
|
|
602
|
+
|
|
603
|
+
### Token Generation
|
|
604
|
+
|
|
605
|
+
`generateToken()` builds the token:
|
|
606
|
+
|
|
607
|
+
<!-- snippet: no-compile method-body excerpt shown outside its class, not a standalone module -->
|
|
608
|
+
```typescript
|
|
609
|
+
generateToken(functionName: string, callId: string): string {
|
|
610
|
+
const expiry = Math.floor(Date.now() / 1000) + this.tokenExpirySecs;
|
|
611
|
+
const nonce = randomBytes(8).toString('hex');
|
|
612
|
+
const message = `${callId}:${functionName}:${expiry}:${nonce}`;
|
|
613
|
+
const signature = createHmac('sha256', this.secretKey).update(message).digest('hex');
|
|
614
|
+
const token = `${callId}.${functionName}.${expiry}.${nonce}.${signature}`;
|
|
615
|
+
return Buffer.from(token).toString('base64url');
|
|
616
|
+
}
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
The secret key is the `swaigSecret` option, else `SIGNALWIRE_SWAIG_SECRET`, else 32 random bytes generated when the agent is created. With a random key, tokens stop validating after a restart and on other replicas, so set the same secret on every replica. Tokens last `tokenExpirySecs` seconds, 3600 by default for an agent. `renderSwml()` creates them and puts them in the `__token` query parameter of each secure tool's webhook URL and of the post-prompt URL.
|
|
620
|
+
|
|
621
|
+
### Token Validation
|
|
622
|
+
|
|
623
|
+
For each `/swaig` request for a secure tool, and each `/post_prompt` request, the agent checks the token:
|
|
624
|
+
|
|
625
|
+
1. Decode the base64url token and split it into fields. The last four are the function, expiry, nonce and signature; the rest is the call ID, which can contain dots.
|
|
626
|
+
2. Reject it if the request has no call ID.
|
|
627
|
+
3. Check that the function name matches the request.
|
|
628
|
+
4. Check that the expiry hasn't passed.
|
|
629
|
+
5. Recompute the HMAC-SHA256 signature and compare it in constant time.
|
|
630
|
+
6. Check that the call ID matches the request's.
|
|
631
|
+
|
|
632
|
+
A secure tool with a missing or failed token doesn't run. The response is `200` with a response text saying the token is invalid or expired. A `/post_prompt` request with a missing or failed token gets `403`.
|
|
633
|
+
|
|
634
|
+
### Session Metadata
|
|
635
|
+
|
|
636
|
+
`SessionManager` also has an in-memory store keyed by session ID, in this process only:
|
|
637
|
+
|
|
638
|
+
<!-- snippet: no-compile bare method signatures shown for reference, not runnable -->
|
|
639
|
+
```typescript
|
|
640
|
+
setSessionMetadata(sessionId: string, metadata: Record<string, unknown>): void;
|
|
641
|
+
getSessionMetadata(sessionId: string): Record<string, unknown>;
|
|
642
|
+
deleteSessionMetadata(sessionId: string): boolean;
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
The token checks don't use it. It isn't shared between replicas, and it's lost on a restart.
|
|
646
|
+
|
|
647
|
+
---
|
|
648
|
+
|
|
649
|
+
## Proxy Detection
|
|
650
|
+
|
|
651
|
+
Behind a reverse proxy (nginx, a load balancer, a tunnel), the agent needs its external URL to build the webhook URLs in its SWML. It chooses the base URL like this:
|
|
652
|
+
|
|
653
|
+
1. **`SWML_PROXY_URL_BASE`**, read when the agent is created. While it's set, request headers never change the base URL.
|
|
654
|
+
2. **`manualSetProxyUrl(url)`**, which replaces the base URL from then on.
|
|
655
|
+
3. **Request headers**, only with `SWML_TRUST_PROXY_HEADERS=true` and without `SWML_PROXY_URL_BASE`. On each SWML request, the agent reads, in order:
|
|
656
|
+
- `X-Forwarded-Host`, with `X-Forwarded-Proto` (default `https`)
|
|
657
|
+
- `Forwarded` (RFC 7239), its `host=` and `proto=` values
|
|
658
|
+
- `X-Original-Host`, with `X-Forwarded-Proto`
|
|
659
|
+
- `X-Forwarded-For` alone has no host; with `SWML_PROXY_DEBUG=true`, the agent logs that it can't determine the host.
|
|
660
|
+
4. **Serverless**: on a detected serverless platform, the platform's URL for the function.
|
|
661
|
+
5. **Fallback**: `http://{host}:{port}`, with `localhost` for the host `0.0.0.0`, and `https` when `SWML_ENFORCE_HTTPS=true`.
|
|
662
|
+
|
|
663
|
+
A base URL found from headers stays in effect for later requests until other headers replace it.
|
|
664
|
+
|
|
665
|
+
### Webhook URL Building
|
|
666
|
+
|
|
667
|
+
`buildWebhookUrl(endpoint, extraParams?)` builds each webhook URL:
|
|
668
|
+
|
|
669
|
+
<!-- snippet: no-compile bare method signature shown for reference, not runnable -->
|
|
670
|
+
```typescript
|
|
671
|
+
buildWebhookUrl(endpoint: string, extraParams?: Record<string, string>): string
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
It follows these steps:
|
|
675
|
+
|
|
676
|
+
1. Call `getFullUrl(true)` for the base URL and route, with the basic-auth credentials in it.
|
|
677
|
+
2. Append the endpoint (`swaig`, `post_prompt` or `debug_events`).
|
|
678
|
+
3. Append the query parameters: the SWAIG query params and, for a secure tool, `__token`.
|
|
679
|
+
|
|
680
|
+
A generated URL looks like this:
|
|
681
|
+
|
|
682
|
+
```text
|
|
683
|
+
https://admin:a-long-random-password@agents.example.com/support/swaig?tenant=acme&__token=...
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
---
|
|
687
|
+
|
|
688
|
+
## Security Layers
|
|
689
|
+
|
|
690
|
+
The agent's security settings are Hono middleware on its app. [Configuration](configuration.md) lists every variable.
|
|
691
|
+
|
|
692
|
+
### Basic Authentication
|
|
693
|
+
|
|
694
|
+
Every route except `/health` and `/ready` requires HTTP Basic Authentication. The agent resolves the credentials in this order:
|
|
695
|
+
|
|
696
|
+
1. The `basicAuth` constructor option.
|
|
697
|
+
2. The config file's `security.auth.basic` (or `security.basicAuth`) password.
|
|
698
|
+
3. `SWML_BASIC_AUTH_PASSWORD`, with `SWML_BASIC_AUTH_USER` or `signalwire` as the username.
|
|
699
|
+
4. Generated: `SWML_BASIC_AUTH_USER` or the agent's name, and 32 random hex characters.
|
|
700
|
+
|
|
701
|
+
The credentials are in the webhook URLs of the SWML, so SignalWire authenticates when it calls the agent back. The routes check credentials through `validateBasicAuth()`, which compares them with the configured pair in constant time and which a subclass can override.
|
|
702
|
+
|
|
703
|
+
### CORS
|
|
704
|
+
|
|
705
|
+
`SWML_CORS_ORIGINS` sets the allowed origins:
|
|
706
|
+
|
|
707
|
+
<!-- snippet: no-compile illustrative Hono middleware calls, not a standalone program -->
|
|
708
|
+
```typescript
|
|
709
|
+
// Default: any origin, without credentials
|
|
710
|
+
cors({ origin: '*', credentials: false })
|
|
711
|
+
|
|
712
|
+
// SWML_CORS_ORIGINS=https://app.example.com,https://admin.example.com
|
|
713
|
+
cors({ origin: ['https://app.example.com', 'https://admin.example.com'], credentials: true })
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
With `SWML_CSRF_PROTECTION=true` and a `SWML_CORS_ORIGINS` list, a `POST` whose `Origin` header isn't in the list gets `403`.
|
|
717
|
+
|
|
718
|
+
### Security Headers
|
|
719
|
+
|
|
720
|
+
Every response from the agent's routes carries these headers:
|
|
721
|
+
|
|
722
|
+
| Header | Value |
|
|
723
|
+
|--------|-------|
|
|
724
|
+
| `X-Content-Type-Options` | `nosniff` |
|
|
725
|
+
| `X-Frame-Options` | `DENY` |
|
|
726
|
+
| `X-XSS-Protection` | `1; mode=block` |
|
|
727
|
+
| `Referrer-Policy` | `strict-origin-when-cross-origin` |
|
|
728
|
+
| `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` |
|
|
729
|
+
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |
|
|
730
|
+
|
|
731
|
+
An app added with `mount()` sets its own headers and CORS, and isn't behind the agent's basic auth.
|
|
732
|
+
|
|
733
|
+
### Rate Limiting
|
|
734
|
+
|
|
735
|
+
When `SWML_RATE_LIMIT` is set, it's the number of requests allowed per minute per client IP:
|
|
736
|
+
|
|
737
|
+
- With `SWML_TRUST_PROXY_HEADERS=true`, the IP is the first `X-Forwarded-For` entry, else `X-Real-IP`, else the connection's address. Without it, the IP is the connection's address.
|
|
738
|
+
- An in-memory `Map` counts requests per IP, in 60-second windows.
|
|
739
|
+
- A request over the limit gets `429` `{"error":"Rate limit exceeded"}`.
|
|
740
|
+
|
|
741
|
+
### Allowed Hosts
|
|
742
|
+
|
|
743
|
+
When `SWML_ALLOWED_HOSTS` is set to a comma-separated list of host names:
|
|
744
|
+
|
|
745
|
+
- The agent reads the `Host` header, drops the port and lowercases it.
|
|
746
|
+
- A host not in the list gets `403`.
|
|
747
|
+
|
|
748
|
+
### Request Size Limits
|
|
749
|
+
|
|
750
|
+
The agent checks each request's `Content-Length` against `SWML_MAX_REQUEST_SIZE`, 1048576 bytes (1 MB) by default:
|
|
751
|
+
|
|
752
|
+
- A larger or non-numeric value gets `413` `{"error":"Request too large"}`.
|
|
753
|
+
- A request without `Content-Length` isn't checked.
|
|
754
|
+
|
|
755
|
+
### Webhook Signatures and TLS
|
|
756
|
+
|
|
757
|
+
A signing key comes from the `signingKey` option or `SIGNALWIRE_SIGNING_KEY`. With one, a `POST` to the agent route, `/swaig`, `/post_prompt` or a routing-callback path needs a valid SignalWire signature, or gets `403`. `GET` requests aren't checked.
|
|
758
|
+
|
|
759
|
+
`AgentBase.serve()` serves HTTPS when `SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH` are set, and plain HTTP otherwise. Behind a TLS-terminating proxy, set `SWML_PROXY_URL_BASE` to its `https` URL.
|
|
760
|
+
|
|
761
|
+
---
|
|
762
|
+
|
|
763
|
+
## Extension Points
|
|
764
|
+
|
|
765
|
+
### Lifecycle Hooks (Override in Subclass)
|
|
766
|
+
|
|
767
|
+
A subclass can override these methods:
|
|
768
|
+
|
|
769
|
+
| Hook | Signature | When Called |
|
|
770
|
+
|------|-----------|------------|
|
|
771
|
+
| `defineTools()` | `protected defineTools(): void` | Once, the first time tools are needed: `renderSwml()`, `getTools()`, `getApp()`/`serve()` or a SWAIG request. Register tools here with `this.defineTool()`. |
|
|
772
|
+
| `onSummary(summary, rawData)` | returns `void`, or a value for `fetch_conversation` | For each valid `/post_prompt` request, on the per-request copy. |
|
|
773
|
+
| `onFunctionCall(name, args, rawData)` | returns `void`, or a result to send instead | Before each tool handler runs at `/swaig`. |
|
|
774
|
+
| `onSwmlRequest(rawData, callbackPath?, context?)` | returns `void`, or modifications for the `ai` verb | On each SWML request, on the agent itself, before the per-request copy is made. `context` is the Hono context. |
|
|
775
|
+
| `onDebugEvent(event)` | `void \| Promise<void>` | For each `POST /debug_events`. |
|
|
776
|
+
|
|
777
|
+
These methods register handlers instead of being overridden:
|
|
778
|
+
|
|
779
|
+
- `onError(handler)`: called when a tool handler throws, after the tool's own `onError`. A `FunctionResult` it returns is sent as the response.
|
|
780
|
+
- `onCallEnd(handler)`: registers the reserved `hangup_hook` tool and turns on `swaig_post_conversation`, so the handler gets the call log when the call ends.
|
|
781
|
+
|
|
782
|
+
### Dynamic Configuration Callback
|
|
783
|
+
|
|
784
|
+
`setDynamicConfigCallback()` registers a callback that configures a per-request copy of the agent:
|
|
785
|
+
|
|
786
|
+
```typescript
|
|
787
|
+
agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, callAgent) => {
|
|
788
|
+
// Configure callAgent; the original agent is unchanged
|
|
789
|
+
if (queryParams['tier'] === 'gold') {
|
|
790
|
+
callAgent.promptAddSection('Priority', { body: 'This caller has priority support.' });
|
|
791
|
+
}
|
|
792
|
+
});
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
The callback receives the request's query parameters, body and headers (with credential-bearing headers removed), and the copy. `addPerCallConfig()` adds another callback to the chain, and `setDynamicConfigCallback()` replaces the chain. [Composition Architecture](#composition-architecture) describes what the copy has of its own.
|
|
796
|
+
|
|
797
|
+
A field a subclass adds is shared between the copy and the agent. Assigning a new value to it on the copy is safe; changing a shared object in place affects every request.
|
|
798
|
+
|
|
799
|
+
### Declarative PROMPT_SECTIONS
|
|
800
|
+
|
|
801
|
+
A subclass can declare its prompt sections as a static field:
|
|
802
|
+
|
|
803
|
+
<!-- snippet: no-compile bare static-field type signature shown for reference, not runnable -->
|
|
804
|
+
```typescript
|
|
805
|
+
static PROMPT_SECTIONS?: {
|
|
806
|
+
title: string;
|
|
807
|
+
body?: string;
|
|
808
|
+
bullets?: string[];
|
|
809
|
+
numbered?: boolean;
|
|
810
|
+
}[];
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
The `AgentBase` constructor adds each entry with `promptAddSection()`.
|
|
814
|
+
|
|
815
|
+
### Skills System
|
|
816
|
+
|
|
817
|
+
Skills are packages of tools, prompt sections, hints and global data:
|
|
818
|
+
|
|
819
|
+
```typescript
|
|
820
|
+
import { DateTimeSkill } from '@signalwire/sdk';
|
|
821
|
+
|
|
822
|
+
await agent.addSkill(new DateTimeSkill());
|
|
823
|
+
```
|
|
824
|
+
|
|
825
|
+
`addSkill()` runs the skill's setup, which registers its tools, prompt sections, hints and global data on the agent. `addSkillByName(name, params)` creates a skill from the registry first.
|
|
826
|
+
|
|
827
|
+
### Webhook URL Overrides
|
|
828
|
+
|
|
829
|
+
Two methods replace the webhook URLs the agent generates:
|
|
830
|
+
|
|
831
|
+
```typescript
|
|
832
|
+
agent.setWebHookUrl('https://custom-swaig-endpoint.example.com/swaig');
|
|
833
|
+
agent.setPostPromptUrl('https://custom-endpoint.example.com/post_prompt');
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
`setWebHookUrl()` replaces `defaults.web_hook_url`; a secure tool still gets its own URL with a token. `setPostPromptUrl()` replaces `post_prompt_url`.
|
|
837
|
+
|
|
838
|
+
### Debug Events
|
|
839
|
+
|
|
840
|
+
`enableDebugEvents(level)` turns on debug webhooks, with level 1 by default:
|
|
841
|
+
|
|
842
|
+
```typescript
|
|
843
|
+
agent.enableDebugEvents(2);
|
|
844
|
+
```
|
|
845
|
+
|
|
846
|
+
The SWML then has `debug_webhook_url` (the agent's `/debug_events`) and `debug_webhook_level` in the `ai` verb. Each `POST /debug_events` calls `onDebugEvent()`.
|