@signalwire/sdk 2.0.5 → 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 +481 -126
- package/dist/AgentBase.js +1502 -438
- 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 +12 -1
- package/dist/POM/PromptObjectModel.js +25 -9
- package/dist/POM/PromptObjectModel.js.map +1 -1
- 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 +18 -0
- package/dist/PomBuilder.js +53 -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 +22 -1
- package/dist/PromptManager.js +28 -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 +158 -58
- package/dist/SWMLService.js +435 -127
- 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 +49 -9
- package/dist/SecurityUtils.js +153 -51
- 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 +92 -33
- 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 -371
- 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 +47 -68
- package/dist/index.js +44 -73
- 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 +44 -17
- package/dist/relay/RelayClient.js +175 -65
- 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 +73 -42
- 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 +5 -2
- package/dist/rest/callHandler.js +4 -1
- package/dist/rest/callHandler.js.map +1 -1
- package/dist/rest/index.d.ts +18 -77
- package/dist/rest/index.js +47 -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 -327
- package/dist/rest/namespaces/fabric.js +14 -439
- 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 +8 -196
- package/dist/rest/namespaces/phone-numbers.js +8 -230
- 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 +22 -11
- package/dist/skills/SkillRegistry.js +47 -17
- 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 +18 -6
- 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 +21 -22
- 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 +42 -4
- package/dist/skills/builtin/spider.js +277 -104
- 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 +38 -30
- 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 +294 -100
- 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 +14 -13
- 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 +59 -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 +85 -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,1034 @@
|
|
|
1
|
+
# SignalWire AI Agents TypeScript SDK: Agent Guide
|
|
2
|
+
|
|
3
|
+
## Table of Contents
|
|
4
|
+
|
|
5
|
+
- [Introduction](#introduction)
|
|
6
|
+
- [Creating an Agent](#creating-an-agent)
|
|
7
|
+
- [Prompts](#prompts)
|
|
8
|
+
- [Raw Text Prompts](#raw-text-prompts)
|
|
9
|
+
- [Prompt Object Model (POM)](#prompt-object-model-pom)
|
|
10
|
+
- [Declarative PROMPT_SECTIONS](#declarative-prompt_sections)
|
|
11
|
+
- [Tools (SWAIG Functions)](#tools-swaig-functions)
|
|
12
|
+
- [Defining Tools](#defining-tools)
|
|
13
|
+
- [Tool Parameters](#tool-parameters)
|
|
14
|
+
- [Secure Tools](#secure-tools)
|
|
15
|
+
- [FunctionResult](#functionresult)
|
|
16
|
+
- [DataMap (Server-Side Tools)](#datamap-server-side-tools)
|
|
17
|
+
- [Speech and Languages](#speech-and-languages)
|
|
18
|
+
- [Hints](#hints)
|
|
19
|
+
- [Languages](#languages)
|
|
20
|
+
- [Pronunciation](#pronunciation)
|
|
21
|
+
- [AI Parameters](#ai-parameters)
|
|
22
|
+
- [Global Data](#global-data)
|
|
23
|
+
- [Call Flow (5 Phases)](#call-flow-5-phases)
|
|
24
|
+
- [Dynamic Configuration](#dynamic-configuration)
|
|
25
|
+
- [Post-Prompt and Summaries](#post-prompt-and-summaries)
|
|
26
|
+
- [Call End Hook](#call-end-hook)
|
|
27
|
+
- [Mounting Extra Routes](#mounting-extra-routes)
|
|
28
|
+
- [Multi-Agent Server](#multi-agent-server)
|
|
29
|
+
- [Subclassing AgentBase](#subclassing-agentbase)
|
|
30
|
+
- [HTTP Endpoints](#http-endpoints)
|
|
31
|
+
- [Environment Variables](#environment-variables)
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Introduction
|
|
36
|
+
|
|
37
|
+
The SignalWire AI Agents TypeScript SDK builds voice AI agents as HTTP microservices. Each agent is an HTTP server built on the [Hono](https://hono.dev/) framework. It serves **SWML** (SignalWire Markup Language) documents and handles **SWAIG** (SignalWire AI Gateway) function callbacks.
|
|
38
|
+
|
|
39
|
+
When a call reaches an agent's number, SignalWire requests a SWML document from the agent's HTTP endpoint. SignalWire requests it with a POST; the route also answers GET, for browsers and testing. The document describes the call flow: answering, playing audio, starting the AI with a prompt, and the tools the AI can call. You configure the prompt and define tools. The SDK renders the SWML, routes the webhooks, and checks authentication and tool tokens.
|
|
40
|
+
|
|
41
|
+
The agent answers three kinds of requests from SignalWire:
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
SignalWire --POST /--> agent returns the SWML document
|
|
45
|
+
SignalWire --POST /swaig--> agent runs a tool handler
|
|
46
|
+
SignalWire --POST /post_prompt--> agent delivers the call summary
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
<!-- snippet-setup -->
|
|
50
|
+
```ts
|
|
51
|
+
export {}; // treat each example as a module so top-level `await` is allowed
|
|
52
|
+
declare global {
|
|
53
|
+
// Shared context the fragments on this page assume (constructed in the prose examples).
|
|
54
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
55
|
+
const AgentBase: typeof import('@signalwire/sdk').AgentBase;
|
|
56
|
+
const AgentServer: typeof import('@signalwire/sdk').AgentServer;
|
|
57
|
+
const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
|
|
58
|
+
const DataMap: typeof import('@signalwire/sdk').DataMap;
|
|
59
|
+
const createSimpleApiTool: typeof import('@signalwire/sdk').createSimpleApiTool;
|
|
60
|
+
const createExpressionTool: typeof import('@signalwire/sdk').createExpressionTool;
|
|
61
|
+
// Illustrative user-supplied helpers referenced by tool handlers on this page.
|
|
62
|
+
const lookupOrder: (id: string) => Promise<string>;
|
|
63
|
+
const fetchWeather: (city: string, units: string) => Promise<{ temp: number; condition: string }>;
|
|
64
|
+
const doTransfer: (amount: number, account: string) => Promise<void>;
|
|
65
|
+
const createReservation: (args: Record<string, unknown>) => Promise<string>;
|
|
66
|
+
const logReservationSummary: (summary: Record<string, unknown>) => Promise<void>;
|
|
67
|
+
const saveToDatabase: (summary: Record<string, unknown>) => Promise<void>;
|
|
68
|
+
const lookupCustomer: (callerId: string) => Promise<{ name: string }>;
|
|
69
|
+
const archiveTranscript: (callId: string, callLog: Record<string, unknown>[]) => Promise<void>;
|
|
70
|
+
// Node globals (tsconfig sets types:[], so declare them here).
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Installation
|
|
75
|
+
|
|
76
|
+
Install the package from npm:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npm install @signalwire/sdk
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Quick Start
|
|
83
|
+
|
|
84
|
+
This agent has a prompt and one tool, and starts an HTTP server:
|
|
85
|
+
|
|
86
|
+
<!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
|
|
87
|
+
```typescript
|
|
88
|
+
import { AgentBase, FunctionResult } from '@signalwire/sdk';
|
|
89
|
+
|
|
90
|
+
const agent = new AgentBase({ name: 'my-agent' });
|
|
91
|
+
|
|
92
|
+
agent.setPromptText('You are a helpful customer service agent for Acme Corp.');
|
|
93
|
+
|
|
94
|
+
agent.defineTool({
|
|
95
|
+
name: 'check_order_status',
|
|
96
|
+
description: 'Look up the status of a customer order by order number.',
|
|
97
|
+
parameters: {
|
|
98
|
+
order_id: { type: 'string', description: 'The order number to look up' },
|
|
99
|
+
},
|
|
100
|
+
handler: async (args) => {
|
|
101
|
+
const status = await lookupOrder(args.order_id as string);
|
|
102
|
+
return new FunctionResult(`Order ${args.order_id} is ${status}.`);
|
|
103
|
+
},
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
agent.serve();
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Creating an Agent
|
|
112
|
+
|
|
113
|
+
The `AgentBase` constructor takes an `AgentOptions` object. This example sets the common options. It passes no secrets, so the SDK reads the basic-auth credentials, the Signing Key and the token secret from the environment:
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
const agent = new AgentBase({
|
|
117
|
+
name: 'support-bot',
|
|
118
|
+
route: '/',
|
|
119
|
+
host: '0.0.0.0',
|
|
120
|
+
port: 3000,
|
|
121
|
+
usePom: true,
|
|
122
|
+
tokenExpirySecs: 3600,
|
|
123
|
+
autoAnswer: true,
|
|
124
|
+
recordCall: false,
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### AgentOptions Reference
|
|
129
|
+
|
|
130
|
+
Every option except `name` is optional:
|
|
131
|
+
|
|
132
|
+
| Option | Type | Default | Description |
|
|
133
|
+
|--------|------|---------|-------------|
|
|
134
|
+
| `name` | `string` | (required) | Display name. It's also the basic-auth username when the SDK generates credentials. |
|
|
135
|
+
| `route` | `string` | `"/"` | HTTP route the agent serves. A trailing slash is removed. |
|
|
136
|
+
| `host` | `string` | `"0.0.0.0"` | Address the server binds to. |
|
|
137
|
+
| `port` | `number` | `PORT` env, else `3000` | Port for the HTTP server. The constructor throws for a value outside 1 to 65535. |
|
|
138
|
+
| `basicAuth` | `[string, string]` | from config or env, else generated | Explicit `[username, password]`. See [Basic Auth](#basic-auth). |
|
|
139
|
+
| `usePom` | `boolean` | `true` | Render the prompt from POM sections. |
|
|
140
|
+
| `tokenExpirySecs` | `number` | `3600` | Lifetime, in seconds, of the per-call tokens for secure tools and the post-prompt URL. |
|
|
141
|
+
| `swaigSecret` | `string` | `SIGNALWIRE_SWAIG_SECRET` env, else random per process | Secret that signs the per-call tool tokens. See [Secure Tools](#secure-tools). |
|
|
142
|
+
| `signingKey` | `string` | `SIGNALWIRE_SIGNING_KEY` env, else none | SignalWire Signing Key. When set, the agent checks the webhook signature on POST requests. See [Webhook signatures](#webhook-signatures). |
|
|
143
|
+
| `webhookTrustProxy` | `boolean` | `false` | Let the signature check use `X-Forwarded-Proto` and `X-Forwarded-Host` to rebuild the URL SignalWire posted to. |
|
|
144
|
+
| `autoAnswer` | `boolean` | `true` | Add an `answer` verb to the call flow. |
|
|
145
|
+
| `recordCall` | `boolean` | `false` | Add a `record_call` verb after the answer. |
|
|
146
|
+
| `recordFormat` | `string` | `"mp4"` | Format for `record_call`, such as `"mp4"` or `"wav"`. |
|
|
147
|
+
| `recordStereo` | `boolean` | `true` | Record in stereo. |
|
|
148
|
+
| `defaultWebhookUrl` | `string` | none | Accepted, but not used when the SWML is rendered. Use `setWebHookUrl()` to change the tool webhook URL. |
|
|
149
|
+
| `nativeFunctions` | `string[]` | `[]` | Platform native functions to enable, emitted as `SWAIG.native_functions`. |
|
|
150
|
+
| `agentId` | `string` | 16 random hex characters | Identifier for this agent instance. |
|
|
151
|
+
| `suppressLogs` | `boolean` | `false` | Turn off all SDK logging in the process, not only this agent's. |
|
|
152
|
+
| `configFile` | `string` | none | Path to a JSON config file. Its `service` section supplies `route`, `host` and `port` when the constructor doesn't. |
|
|
153
|
+
| `schemaPath` | `string` | bundled schema | Path to a SWML JSON Schema file that verbs are validated against, in place of the bundled schema. |
|
|
154
|
+
| `schemaValidation` | `boolean` | `true` | `false` turns off the validation of verbs, as `SWML_SKIP_SCHEMA_VALIDATION=true` does. |
|
|
155
|
+
| `enablePostPromptOverride` | `boolean` | `false` | Add a basic-auth `POST /post_prompt_override` route. Its `post_prompt` field replaces the agent's post-prompt for every later call. |
|
|
156
|
+
| `checkForInputOverride` | `boolean` | `false` | Add a basic-auth `/check_for_input` route (GET and POST) that returns `{ ok: true, received: <body> }`. |
|
|
157
|
+
|
|
158
|
+
### Basic Auth
|
|
159
|
+
|
|
160
|
+
Every route except `/health` and `/ready` requires HTTP basic auth. The SDK resolves the credentials in this order:
|
|
161
|
+
|
|
162
|
+
1. **Provided**: the `basicAuth` constructor option.
|
|
163
|
+
2. **Config file**: `security.auth.basic.user` and `security.auth.basic.password` in the file named by `configFile`.
|
|
164
|
+
3. **Environment**: `SWML_BASIC_AUTH_PASSWORD`, with `SWML_BASIC_AUTH_USER` as the username (`signalwire` when it's unset).
|
|
165
|
+
4. **Generated**: a random password. The username is `SWML_BASIC_AUTH_USER` if it's set, otherwise the agent's `name`.
|
|
166
|
+
|
|
167
|
+
A generated password exists only in the process, and the startup log masks it. The SDK logs a warning when it generates one, because callers outside the process get `401`. Set the environment variables, or pass `basicAuth`, for any agent that SignalWire calls.
|
|
168
|
+
|
|
169
|
+
The SDK puts the credentials into the webhook URLs it renders (`https://user:password@host/swaig`), so SignalWire can call back. Anyone who can read the SWML can read the password.
|
|
170
|
+
|
|
171
|
+
### Webhook signatures
|
|
172
|
+
|
|
173
|
+
When `signingKey` or `SIGNALWIRE_SIGNING_KEY` is set, the agent checks the signature on `POST /`, `POST /swaig`, `POST /post_prompt` and any routing-callback path. It accepts `X-SignalWire-Sha256-Signature` (HMAC-SHA256), and falls back to `X-SignalWire-Signature` (HMAC-SHA1). A request with a missing or wrong signature gets `403`. GET requests aren't checked.
|
|
174
|
+
|
|
175
|
+
When neither is set, the agent logs a warning at construction and doesn't check where requests come from. Basic auth still applies. If the agent is behind a proxy that changes the URL, set `SWML_PROXY_URL_BASE`, or set `webhookTrustProxy: true` when you control the proxy. The signature covers the URL SignalWire posted to.
|
|
176
|
+
|
|
177
|
+
### Starting the Server
|
|
178
|
+
|
|
179
|
+
`serve()` starts the HTTP server. `run()` does the same outside a serverless environment, and handles one serverless request inside one:
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
// Start listening
|
|
183
|
+
await agent.serve();
|
|
184
|
+
// or, detecting the environment:
|
|
185
|
+
await agent.run();
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The server logs its address and credential source at startup. This is the output of an agent named `support-bot` with no credentials configured:
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
[WARN] [AgentBase] [signalwire] webhook signature validation is disabled — set signingKey or SIGNALWIRE_SIGNING_KEY to enable
|
|
192
|
+
[WARN] [AgentBase] basic_auth_password_autogenerated: username="support-bot". No SWML_BASIC_AUTH_PASSWORD found in environment and no basicAuth passed to the agent constructor. ...
|
|
193
|
+
[INFO] [AgentBase] Agent 'support-bot' running at http://0.0.0.0:3000/
|
|
194
|
+
[INFO] [AgentBase] Auth: support-bot:**** (source: generated)
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Each line also starts with a timestamp.
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Prompts
|
|
202
|
+
|
|
203
|
+
The SDK builds the system prompt in one of two ways: **raw text** or the **Prompt Object Model (POM)**.
|
|
204
|
+
|
|
205
|
+
### Raw Text Prompts
|
|
206
|
+
|
|
207
|
+
Pass the whole prompt as a string:
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
agent.setPromptText(`
|
|
211
|
+
You are a friendly receptionist for Dr. Smith's office.
|
|
212
|
+
You help patients schedule appointments and answer basic questions.
|
|
213
|
+
Always be polite and professional.
|
|
214
|
+
`);
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
When raw text is set, the SDK sends it as the prompt text, and doesn't render POM sections.
|
|
218
|
+
|
|
219
|
+
### Prompt Object Model (POM)
|
|
220
|
+
|
|
221
|
+
POM builds a prompt from titled sections, body text, bullets and nested subsections. The SDK renders them as Markdown headings and lists. POM is on by default (`usePom: true`).
|
|
222
|
+
|
|
223
|
+
#### Adding Sections
|
|
224
|
+
|
|
225
|
+
`promptAddSection()` adds a section with a body, bullets, or both:
|
|
226
|
+
|
|
227
|
+
```typescript
|
|
228
|
+
agent.promptAddSection('Personality', {
|
|
229
|
+
body: 'You are a cheerful and knowledgeable tech support agent.',
|
|
230
|
+
bullets: [
|
|
231
|
+
'Always greet the customer warmly',
|
|
232
|
+
'Ask clarifying questions before troubleshooting',
|
|
233
|
+
'Offer to escalate if you cannot resolve the issue',
|
|
234
|
+
],
|
|
235
|
+
});
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
#### Appending to Existing Sections
|
|
239
|
+
|
|
240
|
+
`promptAddToSection()` adds a bullet, several bullets, or more body text to a section:
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
agent.promptAddToSection('Personality', {
|
|
244
|
+
bullet: 'Never make promises about timelines',
|
|
245
|
+
});
|
|
246
|
+
|
|
247
|
+
agent.promptAddToSection('Personality', {
|
|
248
|
+
bullets: ['Speak in plain, non-technical language', 'Confirm understanding before proceeding'],
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
agent.promptAddToSection('Personality', {
|
|
252
|
+
body: 'Remember to always thank the customer at the end of the call.',
|
|
253
|
+
});
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
#### Subsections
|
|
257
|
+
|
|
258
|
+
`promptAddSubsection()` nests a section under a parent section:
|
|
259
|
+
|
|
260
|
+
```typescript
|
|
261
|
+
agent.promptAddSubsection('Personality', 'Tone', {
|
|
262
|
+
body: 'Maintain a warm but professional tone throughout the conversation.',
|
|
263
|
+
bullets: ['Avoid slang', 'Do not use jargon'],
|
|
264
|
+
});
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
#### Checking for Sections
|
|
268
|
+
|
|
269
|
+
`promptHasSection()` reports whether a section exists:
|
|
270
|
+
|
|
271
|
+
```typescript
|
|
272
|
+
if (!agent.promptHasSection('Escalation')) {
|
|
273
|
+
agent.promptAddSection('Escalation', {
|
|
274
|
+
body: 'If the issue cannot be resolved, transfer to a human agent.',
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
#### Numbered Sections and Bullets
|
|
280
|
+
|
|
281
|
+
`numbered` numbers the section, and `numberedBullets` numbers its bullets:
|
|
282
|
+
|
|
283
|
+
```typescript
|
|
284
|
+
agent.promptAddSection('Troubleshooting Steps', {
|
|
285
|
+
numbered: true,
|
|
286
|
+
numberedBullets: true,
|
|
287
|
+
bullets: [
|
|
288
|
+
'Ask the customer to restart the device',
|
|
289
|
+
'Check if the firmware is up to date',
|
|
290
|
+
'Try a factory reset',
|
|
291
|
+
],
|
|
292
|
+
});
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
#### Retrieving the Rendered Prompt
|
|
296
|
+
|
|
297
|
+
`getPrompt()` returns the prompt rendered as text. In POM mode, the SWML carries the sections as a `pom` array instead:
|
|
298
|
+
|
|
299
|
+
```typescript
|
|
300
|
+
const renderedPrompt = agent.getPrompt();
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
### Declarative PROMPT_SECTIONS
|
|
304
|
+
|
|
305
|
+
A subclass can declare its prompt sections as a static property. The constructor adds them with `promptAddSection()`. Each entry takes `title`, and optionally `body`, `bullets` and `numbered`:
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
class SupportAgent extends AgentBase {
|
|
309
|
+
static override PROMPT_SECTIONS = [
|
|
310
|
+
{
|
|
311
|
+
title: 'Role',
|
|
312
|
+
body: 'You are a technical support agent for CloudCo.',
|
|
313
|
+
},
|
|
314
|
+
{
|
|
315
|
+
title: 'Guidelines',
|
|
316
|
+
bullets: [
|
|
317
|
+
'Be concise and helpful',
|
|
318
|
+
'Verify the customer identity before sharing account details',
|
|
319
|
+
],
|
|
320
|
+
},
|
|
321
|
+
];
|
|
322
|
+
|
|
323
|
+
constructor() {
|
|
324
|
+
super({ name: 'support-agent' });
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## Tools (SWAIG Functions)
|
|
332
|
+
|
|
333
|
+
Tools, also called SWAIG functions, are actions the AI can call during a conversation. When the AI calls a tool, SignalWire sends a POST request to the agent's `/swaig` endpoint with the function name and arguments.
|
|
334
|
+
|
|
335
|
+
### Defining Tools
|
|
336
|
+
|
|
337
|
+
`defineTool()` registers a tool:
|
|
338
|
+
|
|
339
|
+
```typescript
|
|
340
|
+
agent.defineTool({
|
|
341
|
+
name: 'get_weather',
|
|
342
|
+
description: 'Get the current weather for a city.',
|
|
343
|
+
parameters: {
|
|
344
|
+
city: { type: 'string', description: 'City name' },
|
|
345
|
+
units: { type: 'string', description: 'Temperature units', enum: ['celsius', 'fahrenheit'] },
|
|
346
|
+
},
|
|
347
|
+
required: ['city'],
|
|
348
|
+
handler: async (args, rawData) => {
|
|
349
|
+
const weather = await fetchWeather(args.city as string, args.units as string);
|
|
350
|
+
return new FunctionResult(`The weather in ${args.city} is ${weather.temp} degrees and ${weather.condition}.`);
|
|
351
|
+
},
|
|
352
|
+
});
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
The `handler` function receives three arguments:
|
|
356
|
+
|
|
357
|
+
| Argument | Type | Description |
|
|
358
|
+
|----------|------|-------------|
|
|
359
|
+
| `args` | `Record<string, unknown>` | The arguments the AI passed, taken from the request's `argument.parsed[0]`. |
|
|
360
|
+
| `rawData` | `SwaigRequest` | The whole SWAIG request body from SignalWire, including `call_id` and `global_data`. |
|
|
361
|
+
| `agent` | `AgentBase` | The agent the request was configured on: the per-request copy when a dynamic config callback or `addPerCallConfig()` is in use, otherwise the agent itself. |
|
|
362
|
+
|
|
363
|
+
A handler that reads the agent's configuration should read it from the third argument. An arrow function that captured `agent` sees the original agent, not the per-request copy.
|
|
364
|
+
|
|
365
|
+
The handler can return any of these:
|
|
366
|
+
|
|
367
|
+
- A `FunctionResult` instance
|
|
368
|
+
- A plain object with a `response` key
|
|
369
|
+
- A string, which the SDK wraps in a `FunctionResult`
|
|
370
|
+
|
|
371
|
+
A handler runs on Node's event loop. Synchronous or CPU-heavy work in a handler blocks every other request the process is serving, so await asynchronous calls instead.
|
|
372
|
+
|
|
373
|
+
### Tool Parameters
|
|
374
|
+
|
|
375
|
+
Parameters follow JSON Schema. You can pass the properties alone, or a full object schema:
|
|
376
|
+
|
|
377
|
+
<!-- snippet: no-compile bare object-literal property fragment, not a standalone statement -->
|
|
378
|
+
```typescript
|
|
379
|
+
// Properties only: the SDK wraps them in { type: 'object', properties: ... }
|
|
380
|
+
parameters: {
|
|
381
|
+
name: { type: 'string', description: 'Customer name' },
|
|
382
|
+
email: { type: 'string', description: 'Email address' },
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
// Full schema
|
|
386
|
+
parameters: {
|
|
387
|
+
type: 'object',
|
|
388
|
+
properties: {
|
|
389
|
+
name: { type: 'string', description: 'Customer name' },
|
|
390
|
+
email: { type: 'string', description: 'Email address' },
|
|
391
|
+
},
|
|
392
|
+
required: ['name'],
|
|
393
|
+
}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
### Secure Tools
|
|
397
|
+
|
|
398
|
+
Tools are secure unless you pass `secure: false`. A secure tool runs only with a valid token minted for that function and that call:
|
|
399
|
+
|
|
400
|
+
```typescript
|
|
401
|
+
agent.defineTool({
|
|
402
|
+
name: 'transfer_funds',
|
|
403
|
+
description: 'Transfer money between accounts.',
|
|
404
|
+
secure: true,
|
|
405
|
+
parameters: {
|
|
406
|
+
amount: { type: 'number', description: 'Amount to transfer' },
|
|
407
|
+
to_account: { type: 'string', description: 'Destination account ID' },
|
|
408
|
+
},
|
|
409
|
+
handler: async (args) => {
|
|
410
|
+
// Runs only when the request carries a valid token for this call
|
|
411
|
+
await doTransfer(args.amount as number, args.to_account as string);
|
|
412
|
+
return new FunctionResult('Transfer completed.');
|
|
413
|
+
},
|
|
414
|
+
});
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
When the SDK renders the SWML, it adds a `__token` query parameter to each secure tool's `web_hook_url`. The token is an HMAC over the call ID, the function name and an expiry. On each `/swaig` request, the SDK checks the signature, the call ID and the expiry before it runs the handler. A request with no token, or with no `call_id` in its body, is refused like a wrong token. The refusal is a normal SWAIG response whose text says the token is invalid or expired.
|
|
418
|
+
|
|
419
|
+
The token proves that the request came from SWML this agent rendered for that call. It doesn't replace basic auth or the webhook signature check.
|
|
420
|
+
|
|
421
|
+
By default, each process generates its own signing secret at startup. A restart then invalidates the tokens of calls in progress, and two replicas can't check each other's tokens. Set the same `swaigSecret`, or `SIGNALWIRE_SWAIG_SECRET`, on every replica and keep it across restarts.
|
|
422
|
+
|
|
423
|
+
SignalWire's requests already carry the token. To call a secure tool yourself, for example with `curl`, first fetch the SWML for the call with `GET /?call_id=<id>`. Then take the token from that tool's `web_hook_url`. `swaig-test --exec` runs the handler directly and doesn't need a token.
|
|
424
|
+
|
|
425
|
+
### FunctionResult
|
|
426
|
+
|
|
427
|
+
`FunctionResult` builds a tool's response. It carries response text and an ordered list of actions. The response text is context for the model, not speech: the model reads it and decides what to say. These examples show four ways to build one:
|
|
428
|
+
|
|
429
|
+
<!-- snippet: no-compile four alternative constructions reuse the `result` name for illustration -->
|
|
430
|
+
```typescript
|
|
431
|
+
import { FunctionResult } from '@signalwire/sdk';
|
|
432
|
+
|
|
433
|
+
// Text for the model
|
|
434
|
+
const result = new FunctionResult('The order has been placed.');
|
|
435
|
+
|
|
436
|
+
// Text and actions
|
|
437
|
+
const result = new FunctionResult('Transferring the caller now.')
|
|
438
|
+
.connect('+15551234567'); // Transfer the call
|
|
439
|
+
|
|
440
|
+
// Update global data from within a tool
|
|
441
|
+
const result = new FunctionResult('Account verified.')
|
|
442
|
+
.updateGlobalData({ verified: true, customer_id: '12345' });
|
|
443
|
+
|
|
444
|
+
// Separate the facts from the instruction
|
|
445
|
+
const result = new FunctionResult().setToolResponse(
|
|
446
|
+
'status: 3 seats left',
|
|
447
|
+
'Tell the caller how many seats are left and ask how many they want.',
|
|
448
|
+
);
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
`setToolResponse(toolResult, toolPrompt)`, or a `{ tool_result, tool_prompt }` object passed to the constructor, sends a structured response in place of the text. `tool_result` states what the tool did. `tool_prompt` tells the model what to do next.
|
|
452
|
+
|
|
453
|
+
These are the `FunctionResult` methods used most often:
|
|
454
|
+
|
|
455
|
+
| Method | Description |
|
|
456
|
+
|--------|-------------|
|
|
457
|
+
| `setResponse(text)` | Set the response text. |
|
|
458
|
+
| `setToolResponse(toolResult?, toolPrompt?)` | Set the structured `{ tool_result, tool_prompt }` response. |
|
|
459
|
+
| `connect(destination, final = true, fromAddr?)` | Transfer the call to a phone number or SIP address. |
|
|
460
|
+
| `hangup()` | Hang up the call. |
|
|
461
|
+
| `hold(prompt?, timeout = 300, step?, timeoutStep?)` | Put the call on hold. The SDK clamps `timeout` to 0 to 900 seconds. A number as the first argument is taken as the timeout. |
|
|
462
|
+
| `say(text)` | Add a `say` action, which speaks the text on the call. |
|
|
463
|
+
| `stop()` | Stop the AI session. |
|
|
464
|
+
| `updateGlobalData(data)` | Merge data into the call's global data. |
|
|
465
|
+
| `setMetadata(data)` | Set metadata (`set_meta_data`) for the function's `meta_data_token`. Functions that share a token share the metadata. |
|
|
466
|
+
| `switchContext(opts)` | Replace the system prompt, with `systemPrompt`, `userPrompt`, `consolidate` and `fullReset`. |
|
|
467
|
+
| `swmlChangeStep(stepName)` | Move to another step of the current context. |
|
|
468
|
+
| `toggleFunctions(toggles)` | Turn functions on or off, as `{ function, active }` pairs. |
|
|
469
|
+
| `sendSms(opts)` | Send an SMS or MMS. |
|
|
470
|
+
| `playBackgroundFile(filename, wait = false)` | Play an audio file in the background. |
|
|
471
|
+
| `waitForUser(opts?)` | Wait for the caller, with `enabled`, `timeout` or `answerFirst`. |
|
|
472
|
+
| `addDynamicHints(hints)` | Add speech recognition hints during the call. |
|
|
473
|
+
| `executeSwml(swml, transfer = false)` | Run a SWML document. |
|
|
474
|
+
| `pay(opts)` | Start a payment collection flow. |
|
|
475
|
+
|
|
476
|
+
If a result has no response text and no actions, `toDict()` returns `{ response: "Action completed." }`.
|
|
477
|
+
|
|
478
|
+
### DataMap (Server-Side Tools)
|
|
479
|
+
|
|
480
|
+
A DataMap tool runs on the SignalWire platform, so the agent receives no webhook for it. It fits a single API call, or pattern matching on the arguments. In this example, the platform reads the webhook's JSON response from the root of the template data, so `${temp}` is the response's `temp` field:
|
|
481
|
+
|
|
482
|
+
```typescript
|
|
483
|
+
import { DataMap, FunctionResult } from '@signalwire/sdk';
|
|
484
|
+
|
|
485
|
+
const weatherTool = new DataMap('get_weather')
|
|
486
|
+
.purpose('Look up weather for a city')
|
|
487
|
+
.parameter('city', 'string', 'City name', { required: true })
|
|
488
|
+
.webhook('GET', 'https://api.weather.example.com/v1/current?q=${lc:enc:args.city}', {
|
|
489
|
+
headers: { Authorization: 'Bearer ${ENV.WEATHER_API_KEY}' },
|
|
490
|
+
})
|
|
491
|
+
.output(new FunctionResult('The weather is ${temp}F and ${condition}.'))
|
|
492
|
+
.enableEnvExpansion()
|
|
493
|
+
.setAllowedEnvPrefixes(['WEATHER_']);
|
|
494
|
+
|
|
495
|
+
weatherTool.registerWithAgent(agent);
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
`${args.city}` is the tool's `city` argument, and `lc:enc:` lowercases and URL-encodes it. The SDK expands `${ENV.NAME}` itself, when `toSwaigFunction()` runs (here, inside `registerWithAgent()`). It expands only names with an allowed prefix, by default `SIGNALWIRE_`, `SWML_` or `SW_`. Any other name becomes an empty string. `setAllowedEnvPrefixes()` changes the list for one DataMap, and `setAllowedEnvPrefixes()` from the package changes the default. The expanded value is part of the SWML the agent serves.
|
|
499
|
+
|
|
500
|
+
`createSimpleApiTool()` builds a one-webhook DataMap from a URL and a response template:
|
|
501
|
+
|
|
502
|
+
```typescript
|
|
503
|
+
import { createSimpleApiTool, createExpressionTool } from '@signalwire/sdk';
|
|
504
|
+
|
|
505
|
+
const tool = createSimpleApiTool({
|
|
506
|
+
name: 'joke',
|
|
507
|
+
url: 'https://api.example.com/joke',
|
|
508
|
+
responseTemplate: 'Here is a joke: ${joke}',
|
|
509
|
+
});
|
|
510
|
+
tool.registerWithAgent(agent);
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
For the template syntax and the builder API, see the [DataMap Guide](datamap-guide.md).
|
|
514
|
+
|
|
515
|
+
---
|
|
516
|
+
|
|
517
|
+
## Speech and Languages
|
|
518
|
+
|
|
519
|
+
### Hints
|
|
520
|
+
|
|
521
|
+
Speech recognition hints help transcription with domain-specific words:
|
|
522
|
+
|
|
523
|
+
```typescript
|
|
524
|
+
// Single hint
|
|
525
|
+
agent.addHint('SignalWire');
|
|
526
|
+
|
|
527
|
+
// Multiple hints
|
|
528
|
+
agent.addHints(['HIPAA', 'deductible', 'copay', 'pre-authorization']);
|
|
529
|
+
|
|
530
|
+
// Pattern hint: a hint with a pattern and its replacement
|
|
531
|
+
agent.addPatternHint({
|
|
532
|
+
hint: 'SignalWire',
|
|
533
|
+
pattern: 'signal wire',
|
|
534
|
+
replace: 'SignalWire',
|
|
535
|
+
ignoreCase: true,
|
|
536
|
+
});
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
### Languages
|
|
540
|
+
|
|
541
|
+
`addLanguage()` adds a language, with its voice and TTS engine:
|
|
542
|
+
|
|
543
|
+
```typescript
|
|
544
|
+
agent.addLanguage({
|
|
545
|
+
name: 'English',
|
|
546
|
+
code: 'en-US',
|
|
547
|
+
voice: 'en-US-Neural2-F',
|
|
548
|
+
engine: 'google',
|
|
549
|
+
});
|
|
550
|
+
|
|
551
|
+
agent.addLanguage({
|
|
552
|
+
name: 'Spanish',
|
|
553
|
+
code: 'es-MX',
|
|
554
|
+
voice: 'es-MX-Neural2-A',
|
|
555
|
+
});
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
`LanguageConfig` also takes filler phrases. `speechFillers` fill a pause in speech, and `functionFillers` play while a tool runs; both are string arrays. Given both, the SDK emits `speech_fillers` and `function_fillers`; given one, it emits the schema's older `fillers` list, as the Python SDK does. The object forms `fillers` keyed by category and `functionFillers` keyed by function are flattened into lists, with a warning. `speechModel` adds a `speech_model` key, which the bundled schema doesn't define.
|
|
559
|
+
|
|
560
|
+
`setLanguages()` replaces all the languages at once:
|
|
561
|
+
|
|
562
|
+
```typescript
|
|
563
|
+
agent.setLanguages([
|
|
564
|
+
{ name: 'English', code: 'en-US', voice: 'en-US-Neural2-F' },
|
|
565
|
+
{ name: 'French', code: 'fr-FR', voice: 'fr-FR-Neural2-A' },
|
|
566
|
+
]);
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
### Pronunciation
|
|
570
|
+
|
|
571
|
+
`addPronunciation()` changes how the TTS engine says a word:
|
|
572
|
+
|
|
573
|
+
```typescript
|
|
574
|
+
agent.addPronunciation({
|
|
575
|
+
replace: 'SQL',
|
|
576
|
+
with: 'sequel',
|
|
577
|
+
ignoreCase: true,
|
|
578
|
+
});
|
|
579
|
+
|
|
580
|
+
agent.addPronunciation({
|
|
581
|
+
replace: 'API',
|
|
582
|
+
with: 'A P I',
|
|
583
|
+
});
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
---
|
|
587
|
+
|
|
588
|
+
## AI Parameters
|
|
589
|
+
|
|
590
|
+
`setParam()` and `setParams()` set keys of the `ai` verb's `params` object, such as timeouts and barge behavior. The SWML schema lists the keys and their ranges:
|
|
591
|
+
|
|
592
|
+
```typescript
|
|
593
|
+
// Set a single parameter
|
|
594
|
+
agent.setParam('end_of_speech_timeout', 700);
|
|
595
|
+
|
|
596
|
+
// Set several at once
|
|
597
|
+
agent.setParams({
|
|
598
|
+
attention_timeout: 15000,
|
|
599
|
+
inactivity_timeout: 600000,
|
|
600
|
+
barge_min_words: 2,
|
|
601
|
+
});
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
Sampling settings, such as `temperature`, `top_p` and the penalties, belong to the prompt, not to `params`.
|
|
605
|
+
|
|
606
|
+
### Prompt-Specific LLM Parameters
|
|
607
|
+
|
|
608
|
+
`setPromptLlmParams()` and `setPostPromptLlmParams()` merge keys into the `prompt` and `post_prompt` objects:
|
|
609
|
+
|
|
610
|
+
```typescript
|
|
611
|
+
// Main prompt
|
|
612
|
+
agent.setPromptLlmParams({
|
|
613
|
+
temperature: 0.3,
|
|
614
|
+
top_p: 0.9,
|
|
615
|
+
});
|
|
616
|
+
|
|
617
|
+
// Post-prompt
|
|
618
|
+
agent.setPostPromptLlmParams({
|
|
619
|
+
temperature: 0.1,
|
|
620
|
+
});
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
The SDK passes these keys through without checking them. For the keys the schema defines, with their ranges and defaults, see the [LLM Parameters Guide](llm_parameters.md).
|
|
624
|
+
|
|
625
|
+
---
|
|
626
|
+
|
|
627
|
+
## Global Data
|
|
628
|
+
|
|
629
|
+
Global data is a set of key-value pairs the SDK sends as the `ai` verb's `global_data`. SignalWire includes it in each SWAIG request, as `rawData.global_data`:
|
|
630
|
+
|
|
631
|
+
```typescript
|
|
632
|
+
// Replace the global data
|
|
633
|
+
agent.setGlobalData({
|
|
634
|
+
company: 'Acme Corp',
|
|
635
|
+
support_hours: '9am-5pm EST',
|
|
636
|
+
max_refund: 500,
|
|
637
|
+
});
|
|
638
|
+
|
|
639
|
+
// Merge more entries into it
|
|
640
|
+
agent.updateGlobalData({
|
|
641
|
+
promo_code: 'SUMMER2025',
|
|
642
|
+
});
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
A tool handler changes the call's global data by returning an action:
|
|
646
|
+
|
|
647
|
+
<!-- snippet: no-compile bare handler property fragment, not a standalone statement -->
|
|
648
|
+
```typescript
|
|
649
|
+
handler: async (args: Record<string, unknown>) => {
|
|
650
|
+
return new FunctionResult('Customer verified.')
|
|
651
|
+
.updateGlobalData({ customer_verified: true, customer_name: args.name });
|
|
652
|
+
}
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
---
|
|
656
|
+
|
|
657
|
+
## Call Flow (5 Phases)
|
|
658
|
+
|
|
659
|
+
The SDK builds the SWML document's `main` section in five phases:
|
|
660
|
+
|
|
661
|
+
| Phase | Method | Description |
|
|
662
|
+
|-------|--------|-------------|
|
|
663
|
+
| 1. Pre-answer | `addPreAnswerVerb(verb, config)` | Verbs that run before the call is answered. |
|
|
664
|
+
| 2. Answer | `addAnswerVerb(config?)` | Configures the `answer` verb, which the SDK adds when `autoAnswer` is `true`. |
|
|
665
|
+
| 3. Post-answer | `addPostAnswerVerb(verb, config)` | Verbs after the answer and before the AI, such as `play`. |
|
|
666
|
+
| 4. AI | (automatic) | The `ai` verb, with the prompt, tools, hints, languages and parameters. |
|
|
667
|
+
| 5. Post-AI | `addPostAiVerb(verb, config)` | Verbs that run after the AI session ends, such as `hangup`. |
|
|
668
|
+
|
|
669
|
+
### Example
|
|
670
|
+
|
|
671
|
+
This agent plays audio before and after the answer, and hangs up after the AI session:
|
|
672
|
+
|
|
673
|
+
```typescript
|
|
674
|
+
const agent = new AgentBase({ name: 'ivr-bot', autoAnswer: true, recordCall: true });
|
|
675
|
+
|
|
676
|
+
// Phase 1: play audio as early media, without answering
|
|
677
|
+
agent.addPreAnswerVerb('play', {
|
|
678
|
+
url: 'https://cdn.example.com/ringback.mp3',
|
|
679
|
+
auto_answer: false,
|
|
680
|
+
});
|
|
681
|
+
|
|
682
|
+
// Phase 3: play a greeting after answering, before the AI starts
|
|
683
|
+
agent.addPostAnswerVerb('play', {
|
|
684
|
+
url: 'https://cdn.example.com/greeting.wav',
|
|
685
|
+
});
|
|
686
|
+
|
|
687
|
+
// Phase 5: hang up after the AI session ends
|
|
688
|
+
agent.addPostAiVerb('hangup', {});
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
The SWML schema says a `play` verb answers the call unless `auto_answer` is `false`. When `recordCall` is `true`, the SDK adds a `record_call` verb at the start of phase 3.
|
|
692
|
+
|
|
693
|
+
### Clearing Verbs
|
|
694
|
+
|
|
695
|
+
These methods remove the verbs added to a phase:
|
|
696
|
+
|
|
697
|
+
```typescript
|
|
698
|
+
agent.clearPreAnswerVerbs();
|
|
699
|
+
agent.clearPostAnswerVerbs();
|
|
700
|
+
agent.clearPostAiVerbs();
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
---
|
|
704
|
+
|
|
705
|
+
## Dynamic Configuration
|
|
706
|
+
|
|
707
|
+
Dynamic configuration changes the agent for one request. `setDynamicConfigCallback()` registers a callback that runs on each request that renders SWML, runs a SWAIG function or delivers a summary. The SDK makes a per-request copy of the agent, calls the callback with the copy, and handles the request with it:
|
|
708
|
+
|
|
709
|
+
```typescript
|
|
710
|
+
agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, copy) => {
|
|
711
|
+
// Customize from query parameters
|
|
712
|
+
if (queryParams['lang'] === 'es') {
|
|
713
|
+
copy.setPromptText('Eres un asistente de servicio al cliente amable.');
|
|
714
|
+
copy.addLanguage({ name: 'Spanish', code: 'es-MX', voice: 'es-MX-Neural2-A' });
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
// Customize from request headers (names are lowercase)
|
|
718
|
+
if (headers['x-customer-tier'] === 'premium') {
|
|
719
|
+
copy.updateGlobalData({ premium: true, max_refund: 1000 });
|
|
720
|
+
}
|
|
721
|
+
|
|
722
|
+
// Customize from the request body
|
|
723
|
+
const callerId = bodyParams.call?.from;
|
|
724
|
+
if (callerId) {
|
|
725
|
+
const customer = await lookupCustomer(callerId);
|
|
726
|
+
copy.updateGlobalData({ customer_name: customer.name });
|
|
727
|
+
}
|
|
728
|
+
});
|
|
729
|
+
```
|
|
730
|
+
|
|
731
|
+
The SWML is rendered from the copy. `/swaig` and `/post_prompt` requests run on the copy too, so a tool the callback adds or secures is the one that runs. Tool handlers get the copy as their third argument, and `onSummary` runs on it. The original agent isn't modified.
|
|
732
|
+
|
|
733
|
+
The copy has its own prompt, tools, hints, languages, pronunciations, params and global data. It also has its own function includes, LLM params, fillers, call-flow verbs, SWAIG query params, native functions, MCP servers, SIP usernames, routing callbacks and contexts. Skills loaded on the agent are shared with the copy, without running their setup again. A field your subclass adds is shared with every request in flight. Assign a new value to such a field on the copy, rather than changing the shared object in place. A subclass's JavaScript `#private` fields aren't on the copy, so use TypeScript `private` fields.
|
|
734
|
+
|
|
735
|
+
The callback receives these arguments:
|
|
736
|
+
|
|
737
|
+
<!-- snippet: no-compile type signature excerpt; SwmlRequestData and AgentBase are not imported -->
|
|
738
|
+
```typescript
|
|
739
|
+
type DynamicConfigCallback = (
|
|
740
|
+
queryParams: Record<string, string>, // URL query parameters
|
|
741
|
+
bodyParams: SwmlRequestData, // Parsed request body
|
|
742
|
+
headers: Record<string, string>, // Headers, without credential-bearing ones
|
|
743
|
+
agent: AgentBase, // The per-request copy to configure
|
|
744
|
+
) => void | Promise<void>;
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
If the callback throws, the SDK logs the error and handles the request with the copy as far as the callback configured it.
|
|
748
|
+
|
|
749
|
+
### Composing callbacks with addPerCallConfig()
|
|
750
|
+
|
|
751
|
+
`addPerCallConfig()` takes a callback with the same signature, and adds it to the ones already registered. The callbacks run in registration order on the same copy, so a later one sees what an earlier one set. A base class and a subclass can each register what they own:
|
|
752
|
+
|
|
753
|
+
```typescript
|
|
754
|
+
agent.addPerCallConfig((query, _body, _headers, copy) => {
|
|
755
|
+
copy.updateGlobalData({ tenant: query['tenant'] ?? 'default' });
|
|
756
|
+
});
|
|
757
|
+
|
|
758
|
+
agent.addPerCallConfig((_query, _body, headers, copy) => {
|
|
759
|
+
if (headers['x-debug'] === '1') copy.setParam('verbose_logs', true);
|
|
760
|
+
});
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
`setDynamicConfigCallback()` replaces every callback registered so far, including those from `addPerCallConfig()`.
|
|
764
|
+
|
|
765
|
+
### SWAIG Query Parameters
|
|
766
|
+
|
|
767
|
+
`addSwaigQueryParams()` appends query parameters to the SWAIG webhook URLs:
|
|
768
|
+
|
|
769
|
+
```typescript
|
|
770
|
+
agent.addSwaigQueryParams({ tenant: 'acme', region: 'us-east' });
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
---
|
|
774
|
+
|
|
775
|
+
## Post-Prompt and Summaries
|
|
776
|
+
|
|
777
|
+
The **post-prompt** is a second prompt that the platform runs when the call ends, usually to summarize the conversation. SignalWire posts the result to the agent's `/post_prompt` route.
|
|
778
|
+
|
|
779
|
+
### Setting the Post-Prompt
|
|
780
|
+
|
|
781
|
+
`setPostPrompt()` sets the post-prompt text:
|
|
782
|
+
|
|
783
|
+
```typescript
|
|
784
|
+
agent.setPostPrompt(`
|
|
785
|
+
Summarize this conversation as JSON with the following fields:
|
|
786
|
+
- "resolution": whether the issue was resolved (true/false)
|
|
787
|
+
- "category": the type of issue (billing, technical, general)
|
|
788
|
+
- "summary": a one-sentence summary of the call
|
|
789
|
+
`);
|
|
790
|
+
```
|
|
791
|
+
|
|
792
|
+
### Handling Summaries
|
|
793
|
+
|
|
794
|
+
Override the `onSummary` hook to process the summary:
|
|
795
|
+
|
|
796
|
+
```typescript
|
|
797
|
+
class MyAgent extends AgentBase {
|
|
798
|
+
constructor() {
|
|
799
|
+
super({ name: 'my-agent' });
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
override async onSummary(summary: Record<string, unknown> | null): Promise<void> {
|
|
803
|
+
if (summary) {
|
|
804
|
+
await saveToDatabase(summary);
|
|
805
|
+
}
|
|
806
|
+
}
|
|
807
|
+
}
|
|
808
|
+
```
|
|
809
|
+
|
|
810
|
+
The SDK takes the summary from `body.summary`, then `body.post_prompt_data.parsed[0]`, then `body.post_prompt_data.raw` parsed as JSON. The second argument is the whole request body. With a dynamic config callback set, `onSummary` runs on the per-request copy.
|
|
811
|
+
|
|
812
|
+
A `POST /post_prompt` needs the `__token` that the SDK put in the SWML's `post_prompt_url` for that call. A missing or wrong token gets `403`.
|
|
813
|
+
|
|
814
|
+
### Post-Prompt LLM Parameters
|
|
815
|
+
|
|
816
|
+
`setPostPromptLlmParams()` sets sampling parameters for the post-prompt alone:
|
|
817
|
+
|
|
818
|
+
```typescript
|
|
819
|
+
agent.setPostPromptLlmParams({
|
|
820
|
+
temperature: 0.0,
|
|
821
|
+
});
|
|
822
|
+
```
|
|
823
|
+
|
|
824
|
+
---
|
|
825
|
+
|
|
826
|
+
## Call End Hook
|
|
827
|
+
|
|
828
|
+
`onCallEnd()` registers a handler that runs when the call ends, with the transcript. Handlers run in registration order with `(callLog, rawData)`:
|
|
829
|
+
|
|
830
|
+
```typescript
|
|
831
|
+
agent.onCallEnd(async (callLog, rawData) => {
|
|
832
|
+
await archiveTranscript(rawData.call_id as string, callLog);
|
|
833
|
+
});
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
The first registration adds the platform's reserved `hangup_hook` function, which fires on hangup and isn't offered to the model. It also sets the `swaig_post_conversation` parameter to `true`, because without it the hook carries no transcript. If you set that parameter to `false` yourself, the SDK leaves it and logs a warning, and handlers get an empty list.
|
|
837
|
+
|
|
838
|
+
The SDK ignores a handler's return value. It logs an error a handler throws, and runs the remaining handlers.
|
|
839
|
+
|
|
840
|
+
---
|
|
841
|
+
|
|
842
|
+
## Mounting Extra Routes
|
|
843
|
+
|
|
844
|
+
`mount()` serves another Hono app, or a fetch handler, alongside the agent's routes:
|
|
845
|
+
|
|
846
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `agent` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
847
|
+
```typescript
|
|
848
|
+
import { Hono } from 'hono';
|
|
849
|
+
|
|
850
|
+
const status = new Hono();
|
|
851
|
+
status.get('/', (c) => c.json({ build: '2026-09-28' }));
|
|
852
|
+
|
|
853
|
+
agent.mount(status, { prefix: '/status' });
|
|
854
|
+
```
|
|
855
|
+
|
|
856
|
+
Mount before you call `serve()`. The agent replays its mounts each time it rebuilds its app, so a mount survives a routing change. A mounted app isn't behind the agent's basic auth, and it sets its own security headers and answers its own CORS preflights. The `name` option is accepted for code written for the Python SDK, and has no effect.
|
|
857
|
+
|
|
858
|
+
---
|
|
859
|
+
|
|
860
|
+
## Multi-Agent Server
|
|
861
|
+
|
|
862
|
+
`AgentServer` hosts several agents on one HTTP server, each under its own route:
|
|
863
|
+
|
|
864
|
+
<!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
|
|
865
|
+
```typescript
|
|
866
|
+
import { AgentBase, AgentServer } from '@signalwire/sdk';
|
|
867
|
+
|
|
868
|
+
const salesAgent = new AgentBase({ name: 'sales', route: '/sales' });
|
|
869
|
+
salesAgent.setPromptText('You are a sales representative.');
|
|
870
|
+
|
|
871
|
+
const supportAgent = new AgentBase({ name: 'support', route: '/support' });
|
|
872
|
+
supportAgent.setPromptText('You are a technical support agent.');
|
|
873
|
+
|
|
874
|
+
const server = new AgentServer({ host: '0.0.0.0', port: 4000 });
|
|
875
|
+
server.register(salesAgent);
|
|
876
|
+
server.register(supportAgent);
|
|
877
|
+
|
|
878
|
+
await server.run();
|
|
879
|
+
```
|
|
880
|
+
|
|
881
|
+
### AgentServer Features
|
|
882
|
+
|
|
883
|
+
The server adds these to the agents' own routes:
|
|
884
|
+
|
|
885
|
+
- **Agent listing**: when no agent is registered at `/`, `GET /` returns `{ "service": "SignalWire AI Agents", "agents": [{ "name", "route" }] }`.
|
|
886
|
+
- **Health endpoints**: `/health` and `/ready` return `{ "status": "ok" }` and `{ "status": "ready" }`, without auth.
|
|
887
|
+
- **Security headers**: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, `Referrer-Policy`, `Content-Security-Policy` and `Permissions-Policy`, on every response except a mounted app's.
|
|
888
|
+
- **CORS**: the origins in `SWML_CORS_ORIGINS`, or any origin when it's unset.
|
|
889
|
+
|
|
890
|
+
### API
|
|
891
|
+
|
|
892
|
+
These methods manage the server:
|
|
893
|
+
|
|
894
|
+
| Method | Description |
|
|
895
|
+
|--------|-------------|
|
|
896
|
+
| `register(agent, route?)` | Mount an agent at `route`, or at the agent's own route. Throws if the route is in use. |
|
|
897
|
+
| `unregister(route)` | Remove an agent, its routes and its entry in the listing and `getAgents()`. |
|
|
898
|
+
| `getAgents()` | Return a `Map<string, AgentBase>` of the registered agents. |
|
|
899
|
+
| `getAgent(route)` | Look up an agent by route. |
|
|
900
|
+
| `serveStaticFiles(directory, route = '/')` | Serve files from a directory. |
|
|
901
|
+
| `getApp()` | Return the Hono application. |
|
|
902
|
+
| `run(host?, port?)` | Start the HTTP server. |
|
|
903
|
+
|
|
904
|
+
---
|
|
905
|
+
|
|
906
|
+
## Subclassing AgentBase
|
|
907
|
+
|
|
908
|
+
A subclass keeps an agent's prompt, tools and hooks in one class:
|
|
909
|
+
|
|
910
|
+
```typescript
|
|
911
|
+
import { AgentBase, FunctionResult } from '@signalwire/sdk';
|
|
912
|
+
|
|
913
|
+
class RestaurantBot extends AgentBase {
|
|
914
|
+
// Declarative prompt sections
|
|
915
|
+
static override PROMPT_SECTIONS = [
|
|
916
|
+
{
|
|
917
|
+
title: 'Role',
|
|
918
|
+
body: 'You are a restaurant reservation assistant for Bella Italia.',
|
|
919
|
+
},
|
|
920
|
+
{
|
|
921
|
+
title: 'Guidelines',
|
|
922
|
+
bullets: [
|
|
923
|
+
'Be warm and inviting',
|
|
924
|
+
'Always confirm the reservation details before finalizing',
|
|
925
|
+
'Mention daily specials when relevant',
|
|
926
|
+
],
|
|
927
|
+
},
|
|
928
|
+
];
|
|
929
|
+
|
|
930
|
+
constructor() {
|
|
931
|
+
super({ name: 'restaurant-bot', route: '/restaurant' });
|
|
932
|
+
|
|
933
|
+
this.addHints(['Bella Italia', 'risotto', 'tiramisu']);
|
|
934
|
+
this.setPromptLlmParams({ temperature: 0.6 });
|
|
935
|
+
}
|
|
936
|
+
|
|
937
|
+
// The SDK calls this once, the first time the tools are needed
|
|
938
|
+
protected override defineTools(): void {
|
|
939
|
+
this.defineTool({
|
|
940
|
+
name: 'make_reservation',
|
|
941
|
+
description: 'Create a restaurant reservation.',
|
|
942
|
+
parameters: {
|
|
943
|
+
date: { type: 'string', description: 'Reservation date (YYYY-MM-DD)' },
|
|
944
|
+
time: { type: 'string', description: 'Reservation time (HH:MM)' },
|
|
945
|
+
party_size: { type: 'number', description: 'Number of guests' },
|
|
946
|
+
name: { type: 'string', description: 'Name for the reservation' },
|
|
947
|
+
},
|
|
948
|
+
required: ['date', 'time', 'party_size', 'name'],
|
|
949
|
+
handler: async (args) => {
|
|
950
|
+
const id = await createReservation(args);
|
|
951
|
+
return new FunctionResult(
|
|
952
|
+
`Reservation confirmed for ${args.party_size} on ${args.date} at ${args.time}. ` +
|
|
953
|
+
`Confirmation number: ${id}.`
|
|
954
|
+
);
|
|
955
|
+
},
|
|
956
|
+
});
|
|
957
|
+
}
|
|
958
|
+
|
|
959
|
+
// Post-prompt summary hook
|
|
960
|
+
override async onSummary(summary: Record<string, unknown> | null): Promise<void> {
|
|
961
|
+
if (summary) {
|
|
962
|
+
await logReservationSummary(summary);
|
|
963
|
+
}
|
|
964
|
+
}
|
|
965
|
+
|
|
966
|
+
// Runs before each tool handler
|
|
967
|
+
override async onFunctionCall(name: string, args: Record<string, unknown>): Promise<void> {
|
|
968
|
+
console.log(`Tool invoked: ${name}`, args);
|
|
969
|
+
}
|
|
970
|
+
}
|
|
971
|
+
```
|
|
972
|
+
|
|
973
|
+
`defineTools()` runs lazily, the first time the tools are needed: on `renderSwml()`, `getTools()`, `getApp()`, `serve()` or a SWAIG request. It runs after the subclass's fields are initialized. Calling `this.defineTools()` from the constructor also works, and the SDK still registers the tools once.
|
|
974
|
+
|
|
975
|
+
### Extension Points
|
|
976
|
+
|
|
977
|
+
A subclass can override these members:
|
|
978
|
+
|
|
979
|
+
| Method / Property | Purpose |
|
|
980
|
+
|-------------------|---------|
|
|
981
|
+
| `static PROMPT_SECTIONS` | Prompt sections the constructor adds. |
|
|
982
|
+
| `defineTools()` | Register tools. The SDK calls it once. |
|
|
983
|
+
| `onSummary(summary, rawData)` | Runs when a post-prompt summary arrives. For a `fetch_conversation` request, a returned object is sent back as the response. |
|
|
984
|
+
| `onFunctionCall(name, args, rawData)` | Runs before each tool handler. A returned value other than `undefined` or `null` is sent as the result, and the handler doesn't run. |
|
|
985
|
+
| `onSwmlRequest(rawData, callbackPath?, context?)` | Runs on each SWML request before rendering. A returned object is merged into the `ai` verb's configuration. |
|
|
986
|
+
| `onDebugEvent(event)` | Runs when a debug event arrives at `/debug_events`. |
|
|
987
|
+
|
|
988
|
+
Every route that requires basic auth calls `validateBasicAuth(username, password)`, which compares the credentials in constant time. Override it to add a check; call `super.validateBasicAuth()` to keep the comparison.
|
|
989
|
+
|
|
990
|
+
---
|
|
991
|
+
|
|
992
|
+
## HTTP Endpoints
|
|
993
|
+
|
|
994
|
+
Each agent serves these routes, relative to its `route`:
|
|
995
|
+
|
|
996
|
+
| Method | Path | Auth | Description |
|
|
997
|
+
|--------|------|------|-------------|
|
|
998
|
+
| GET, POST | `/` | Basic auth, and the signature on POST when a signing key is set | Returns the SWML document. Runs `onSwmlRequest` and the dynamic config callbacks. |
|
|
999
|
+
| GET, POST | `/swaig` | Basic auth, and the signature on POST | POST runs a tool: it reads `function` and `argument` from the body, checks the token of a secure tool, calls `onFunctionCall`, then the handler. GET returns the SWML document. |
|
|
1000
|
+
| GET, POST | `/post_prompt` | Basic auth, the signature on POST, and the post-prompt token on POST | POST delivers the call's summary and calls `onSummary`. GET returns the SWML document. |
|
|
1001
|
+
| POST | `/debug_events` | Basic auth | Receives debug events and calls `onDebugEvent`. `enableDebugEvents()` adds the URL to the SWML. |
|
|
1002
|
+
| POST | `/mcp` | Basic auth | JSON-RPC endpoint for MCP clients, after `enableMcpServer()`. It doesn't list or run DataMap tools or tools with an external webhook URL. |
|
|
1003
|
+
| POST | `/post_prompt_override` | Basic auth | Only with `enablePostPromptOverride: true`. |
|
|
1004
|
+
| GET, POST | `/check_for_input` | Basic auth | Only with `checkForInputOverride: true`. |
|
|
1005
|
+
| GET | `/health` | None | Returns `{ "status": "ok" }`. |
|
|
1006
|
+
| GET | `/ready` | None | Returns `{ "status": "ready" }`. |
|
|
1007
|
+
|
|
1008
|
+
---
|
|
1009
|
+
|
|
1010
|
+
## Environment Variables
|
|
1011
|
+
|
|
1012
|
+
The agent reads these variables. For the security settings, see the [Security Guide](security.md):
|
|
1013
|
+
|
|
1014
|
+
| Variable | Default | Description |
|
|
1015
|
+
|----------|---------|-------------|
|
|
1016
|
+
| `PORT` | `3000` | HTTP port, when the constructor and config file don't set one. |
|
|
1017
|
+
| `SWML_BASIC_AUTH_USER` | (none) | Basic-auth username, when `basicAuth` isn't passed. |
|
|
1018
|
+
| `SWML_BASIC_AUTH_PASSWORD` | (none) | Basic-auth password, when `basicAuth` isn't passed. Without it, the SDK generates one. |
|
|
1019
|
+
| `SIGNALWIRE_SIGNING_KEY` | (none) | Signing Key for the webhook signature check, when `signingKey` isn't passed. |
|
|
1020
|
+
| `SIGNALWIRE_SWAIG_SECRET` | (random per process) | Secret for the per-call tool tokens, when `swaigSecret` isn't passed. |
|
|
1021
|
+
| `SWML_PROXY_URL_BASE` | (none) | Public base URL for the webhook URLs, such as `https://agents.example.com`. It takes priority over detection from headers. |
|
|
1022
|
+
| `SWML_TRUST_PROXY_HEADERS` | `false` | Set to `true` to build the public URL from `X-Forwarded-Host`, `Forwarded` or `X-Original-Host`, and to rate-limit by `X-Forwarded-For`. |
|
|
1023
|
+
| `SWML_PROXY_DEBUG` | `false` | Set to `true` to log proxy detection. |
|
|
1024
|
+
| `SWML_ENFORCE_HTTPS` | `false` | Set to `true` to build webhook URLs with `https` when no proxy base URL is known. |
|
|
1025
|
+
| `SWML_CORS_ORIGINS` | any origin | Comma-separated list of allowed CORS origins. When set, CORS responses allow credentials. |
|
|
1026
|
+
| `SWML_CSRF_PROTECTION` | `false` | Set to `true` to refuse a POST whose `Origin` isn't in `SWML_CORS_ORIGINS`, with `403`. |
|
|
1027
|
+
| `SWML_ALLOWED_HOSTS` | (none) | Comma-separated list of allowed `Host` values. Other hosts get `403`. |
|
|
1028
|
+
| `SWML_MAX_REQUEST_SIZE` | `1048576` | Largest `Content-Length`, in bytes. A larger request gets `413`. |
|
|
1029
|
+
| `SWML_RATE_LIMIT` | (none) | Requests per minute. A client over the limit gets `429`. The limit is per client address: the connection's, or the forwarded one with `SWML_TRUST_PROXY_HEADERS=true`. |
|
|
1030
|
+
| `SWML_SKIP_SCHEMA_VALIDATION` | `false` | Set to `true` to skip SWML schema validation. |
|
|
1031
|
+
| `SIGNALWIRE_LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error`. |
|
|
1032
|
+
| `SIGNALWIRE_LOG_MODE` | `auto` | `off` turns logging off, `stderr` writes to stderr, and `auto` decides from the environment. |
|
|
1033
|
+
| `SIGNALWIRE_LOG_FORMAT` | `text` | `text` or `json`. |
|
|
1034
|
+
| `SIGNALWIRE_LOG_COLOR` | on a TTY | `true` or `false`. |
|