@signalwire/sdk 2.0.5 → 3.6.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 +821 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +510 -126
- package/dist/AgentBase.js +1581 -455
- 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 +186 -45
- package/dist/DataMap.js +210 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +309 -83
- package/dist/FunctionResult.js +483 -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 +169 -59
- package/dist/SWMLService.js +456 -129
- 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/SemanticGate.d.ts +183 -0
- package/dist/SemanticGate.js +533 -0
- package/dist/SemanticGate.js.map +1 -0
- 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 +139 -7
- package/dist/SwaigFunction.js +170 -22
- 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 +920 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +49 -68
- package/dist/index.js +45 -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 +111 -21
- 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 +3641 -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 +1207 -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 +1986 -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,1207 @@
|
|
|
1
|
+
# DataMap Guide
|
|
2
|
+
|
|
3
|
+
This page is the reference for the `DataMap` class in the SignalWire AI Agents TypeScript SDK, and for the `data_map` definition it builds.
|
|
4
|
+
|
|
5
|
+
<!-- snippet-setup -->
|
|
6
|
+
```ts
|
|
7
|
+
export {}; // treat each runnable example as a module
|
|
8
|
+
// Shared context the examples assume: `DataMap`/`FunctionResult`/`SemanticGate` (imported
|
|
9
|
+
// once and reused), `agent` (an AgentBase), and `tool` (the DataMap built in the current
|
|
10
|
+
// example). Declared as ambient globals so each fragment resolves without repeating the
|
|
11
|
+
// boilerplate. A block that constructs or imports its own `const tool`/`DataMap` shadows these.
|
|
12
|
+
declare global {
|
|
13
|
+
const DataMap: typeof import('@signalwire/sdk').DataMap;
|
|
14
|
+
const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
|
|
15
|
+
const SemanticGate: typeof import('@signalwire/sdk').SemanticGate;
|
|
16
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
17
|
+
const tool: import('@signalwire/sdk').DataMap;
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Table of Contents
|
|
24
|
+
|
|
25
|
+
The page has these sections:
|
|
26
|
+
|
|
27
|
+
- [Overview](#overview)
|
|
28
|
+
- [What the SDK does and what the platform does](#what-the-sdk-does-and-what-the-platform-does)
|
|
29
|
+
- [Creating a DataMap](#creating-a-datamap)
|
|
30
|
+
- [Configuration](#configuration)
|
|
31
|
+
- [purpose / description](#purpose--description)
|
|
32
|
+
- [parameter](#parameter)
|
|
33
|
+
- [Webhooks](#webhooks)
|
|
34
|
+
- [webhook](#webhook)
|
|
35
|
+
- [params](#params)
|
|
36
|
+
- [body](#body)
|
|
37
|
+
- [Webhook Headers](#webhook-headers)
|
|
38
|
+
- [Expressions](#expressions)
|
|
39
|
+
- [expression](#expression)
|
|
40
|
+
- [Response Processing](#response-processing)
|
|
41
|
+
- [output](#output)
|
|
42
|
+
- [webhookExpressions](#webhookexpressions)
|
|
43
|
+
- [Error Handling](#error-handling)
|
|
44
|
+
- [fallbackOutput](#fallbackoutput)
|
|
45
|
+
- [errorKeys](#errorkeys)
|
|
46
|
+
- [globalErrorKeys](#globalerrorkeys)
|
|
47
|
+
- [Semantic Gates](#semantic-gates)
|
|
48
|
+
- [gate](#gate)
|
|
49
|
+
- [gateFillers](#gatefillers)
|
|
50
|
+
- [Iteration](#iteration)
|
|
51
|
+
- [foreach](#foreach)
|
|
52
|
+
- [Environment Variables](#environment-variables)
|
|
53
|
+
- [enableEnvExpansion](#enableenvexpansion)
|
|
54
|
+
- [Allowed prefixes](#allowed-prefixes)
|
|
55
|
+
- [Registration](#registration)
|
|
56
|
+
- [registerWithAgent](#registerwithagent)
|
|
57
|
+
- [toSwaigFunction](#toswaigfunction)
|
|
58
|
+
- [Helper Functions](#helper-functions)
|
|
59
|
+
- [createSimpleApiTool](#createsimpleapitool)
|
|
60
|
+
- [createExpressionTool](#createexpressiontool)
|
|
61
|
+
- [Template Reference](#template-reference)
|
|
62
|
+
- [Template data](#template-data)
|
|
63
|
+
- [Template syntax](#template-syntax)
|
|
64
|
+
- [Template functions](#template-functions)
|
|
65
|
+
- [Testing a DataMap](#testing-a-datamap)
|
|
66
|
+
- [Complete Example](#complete-example)
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Overview
|
|
71
|
+
|
|
72
|
+
`DataMap` builds a SWAIG function that runs on the SignalWire platform instead of in your agent. You describe the HTTP request to make, or the pattern to match, and how to turn the result into the function's response. The definition goes into the SWML document as the function's `data_map`, and the platform runs it when the AI calls the function.
|
|
73
|
+
|
|
74
|
+
The two kinds of tool differ in where they run:
|
|
75
|
+
|
|
76
|
+
| Feature | `defineTool()` | `DataMap` |
|
|
77
|
+
|--------------------|--------------------------------------------|------------------------------------------------|
|
|
78
|
+
| Execution location | Your server | SignalWire platform |
|
|
79
|
+
| Custom logic | Full TypeScript/JavaScript | Template variables and pattern matching |
|
|
80
|
+
| External API calls | You make them in your handler | SignalWire makes them for you |
|
|
81
|
+
| Webhook required | Yes (your agent server must be reachable) | No (the `data_map` definition is in the SWML) |
|
|
82
|
+
| Best for | Complex logic, database access, auth flows | API lookups, pattern matching, formatting |
|
|
83
|
+
|
|
84
|
+
### How it works
|
|
85
|
+
|
|
86
|
+
A DataMap tool goes from definition to call in three steps:
|
|
87
|
+
|
|
88
|
+
1. You define a `DataMap` with a name, parameters, and webhooks or expressions.
|
|
89
|
+
2. You register it with an agent through `registerWithAgent()` or `toSwaigFunction()`.
|
|
90
|
+
3. When the AI calls the function, SignalWire runs the `data_map` definition:
|
|
91
|
+
- For **webhooks**, SignalWire makes the HTTP request and expands the output template with the response. The result goes back to the AI.
|
|
92
|
+
- For **expressions**, SignalWire expands the test value, matches it against the pattern, and returns the matching output.
|
|
93
|
+
|
|
94
|
+
The request path looks like this:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
Caller <-> SignalWire AI <-> DataMap (runs on SignalWire)
|
|
98
|
+
|
|
|
99
|
+
+--> External API (optional webhook call)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
A DataMap function call sends no request to your server. Your server only serves the SWML document that contains the `data_map` definition.
|
|
103
|
+
|
|
104
|
+
### What the SDK does and what the platform does
|
|
105
|
+
|
|
106
|
+
The SDK builds the definition. `toSwaigFunction()` serializes the builder's settings into a SWAIG function object with a `data_map` key. The one template the SDK expands itself is `${ENV.NAME}`, when you turn on [environment expansion](#environment-variables). Every other `${...}` is written into the SWML as text.
|
|
107
|
+
|
|
108
|
+
The platform does the rest during a call. It fetches each webhook, expands the templates, evaluates the expressions and builds the output. [Template Reference](#template-reference) describes the platform's side. SignalWire's own reference is the [data_map page](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions/data-map) and the [template functions page](https://signalwire.com/docs/swml/reference/template-functions).
|
|
109
|
+
|
|
110
|
+
`swaig-test --exec` runs a DataMap function locally in a simulator of the platform's processing. See [Testing a DataMap](#testing-a-datamap).
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Creating a DataMap
|
|
115
|
+
|
|
116
|
+
The `DataMap` constructor takes a single argument: the function name.
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
import { DataMap, FunctionResult } from '@signalwire/sdk';
|
|
120
|
+
|
|
121
|
+
const tool = new DataMap('get_weather');
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
| Parameter | Type | Description |
|
|
125
|
+
|----------------|----------|------------------------------------------|
|
|
126
|
+
| `functionName` | `string` | Unique name for this data map tool. |
|
|
127
|
+
|
|
128
|
+
You configure the rest through method chaining. This tool calls the wttr.in weather API and reads the temperature from its JSON response:
|
|
129
|
+
|
|
130
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
131
|
+
```typescript
|
|
132
|
+
const tool = new DataMap('get_weather')
|
|
133
|
+
.purpose('Get current weather for a city')
|
|
134
|
+
.parameter('city', 'string', 'The city name', { required: true })
|
|
135
|
+
.webhook('GET', 'https://wttr.in/${lc:enc:args.city}?format=j1')
|
|
136
|
+
.output(new FunctionResult('Temperature: ${current_condition[0].temp_F}F'))
|
|
137
|
+
.fallbackOutput(new FunctionResult('Weather data unavailable.'));
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The output reads `current_condition[0].temp_F` from the root of the response, with no `response.` prefix. [Template data](#template-data) explains why.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Configuration
|
|
145
|
+
|
|
146
|
+
### purpose / description
|
|
147
|
+
|
|
148
|
+
These methods set the tool description that the AI reads to decide when to call the tool. `description()` is an alias for `purpose()`.
|
|
149
|
+
|
|
150
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
151
|
+
```typescript
|
|
152
|
+
purpose(description: string): this
|
|
153
|
+
description(description: string): this
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
| Parameter | Type | Description |
|
|
157
|
+
|---------------|----------|----------------------------------------------------|
|
|
158
|
+
| `description` | `string` | Human-readable description of what the tool does. |
|
|
159
|
+
|
|
160
|
+
If you don't set one, the description is `"Execute <functionName>"`. Both calls in this example set the same description:
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
const tool = new DataMap('lookup_order')
|
|
164
|
+
.purpose('Look up an order by its ID and return the status');
|
|
165
|
+
|
|
166
|
+
// Equivalent:
|
|
167
|
+
const tool2 = new DataMap('lookup_order')
|
|
168
|
+
.description('Look up an order by its ID and return the status');
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
### parameter
|
|
174
|
+
|
|
175
|
+
This method defines a parameter that the AI extracts from the conversation and passes to the tool.
|
|
176
|
+
|
|
177
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
178
|
+
```typescript
|
|
179
|
+
parameter(
|
|
180
|
+
name: string,
|
|
181
|
+
paramType: string,
|
|
182
|
+
description: string,
|
|
183
|
+
opts?: { required?: boolean; enum?: string[] }
|
|
184
|
+
): this
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
| Parameter | Type | Description |
|
|
188
|
+
|-------------------|------------|----------------------------------------------------------|
|
|
189
|
+
| `name` | `string` | Parameter name. A URL, `params`, the top-level expressions and the fallback output read it as `${args.name}`; a webhook's `output`, `expressions` and `foreach` read it as `${input.args.name}`. See [Template data](#template-data). |
|
|
190
|
+
| `paramType` | `string` | JSON Schema type: `"string"`, `"number"`, `"boolean"`, `"integer"`, `"array"`, `"object"`. |
|
|
191
|
+
| `description` | `string` | Description the AI reads to decide how to fill in the value. |
|
|
192
|
+
| `opts.required` | `boolean` | If `true`, the parameter is listed in the schema's `required` array. |
|
|
193
|
+
| `opts.enum` | `string[]` | Restrict the parameter to a fixed set of allowed values. |
|
|
194
|
+
|
|
195
|
+
The options are an object: write `{ required: true }`, not `true`. Each call to `parameter()` adds one parameter:
|
|
196
|
+
|
|
197
|
+
```typescript
|
|
198
|
+
const tool = new DataMap('search_products')
|
|
199
|
+
.purpose('Search for products in the catalog')
|
|
200
|
+
.parameter('query', 'string', 'Search query text', { required: true })
|
|
201
|
+
.parameter('category', 'string', 'Product category filter', {
|
|
202
|
+
enum: ['electronics', 'clothing', 'home', 'sports'],
|
|
203
|
+
})
|
|
204
|
+
.parameter('max_results', 'integer', 'Maximum number of results to return');
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
`toSwaigFunction()` turns those calls into this parameter schema:
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"type": "object",
|
|
212
|
+
"properties": {
|
|
213
|
+
"query": { "type": "string", "description": "Search query text" },
|
|
214
|
+
"category": {
|
|
215
|
+
"type": "string",
|
|
216
|
+
"description": "Product category filter",
|
|
217
|
+
"enum": ["electronics", "clothing", "home", "sports"]
|
|
218
|
+
},
|
|
219
|
+
"max_results": { "type": "integer", "description": "Maximum number of results to return" }
|
|
220
|
+
},
|
|
221
|
+
"required": ["query"]
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Webhooks
|
|
228
|
+
|
|
229
|
+
### webhook
|
|
230
|
+
|
|
231
|
+
This method adds an HTTP request for SignalWire to make when the tool is called. You can add more than one. The platform tries them in order and skips a webhook when none of its `require_args` is among the arguments. The first webhook it requests decides the result: if that webhook fails, the [fallback output](#fallbackoutput) answers, and later webhooks aren't tried.
|
|
232
|
+
|
|
233
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
234
|
+
```typescript
|
|
235
|
+
webhook(
|
|
236
|
+
method: string,
|
|
237
|
+
url: string,
|
|
238
|
+
opts?: {
|
|
239
|
+
headers?: Record<string, string>;
|
|
240
|
+
formParam?: string;
|
|
241
|
+
inputArgsAsParams?: boolean;
|
|
242
|
+
requireArgs?: string[];
|
|
243
|
+
}
|
|
244
|
+
): this
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
| Parameter | Type | Written as | Description |
|
|
248
|
+
|--------------------------|--------------------------|------------------------|-------------|
|
|
249
|
+
| `method` | `string` | `method` | HTTP method, uppercased. The SWML schema allows `GET`, `POST`, `PUT` and `DELETE`. The platform sends a `POST` when the method is `POST` or the webhook has `params`, and a `GET` for any other method. |
|
|
250
|
+
| `url` | `string` | `url` | The request URL. The platform expands templates in it, such as `${enc:args.city}`. |
|
|
251
|
+
| `opts.headers` | `Record<string, string>` | `headers` | HTTP headers for the request, sent as written. The platform expands no templates in them. |
|
|
252
|
+
| `opts.formParam` | `string` | `form_param` | The SWML schema's webhook object doesn't define this key. |
|
|
253
|
+
| `opts.inputArgsAsParams` | `boolean` | `input_args_as_params` | If `true`, the platform merges the function's arguments into `params`. With no `params`, the arguments are the whole request body. |
|
|
254
|
+
| `opts.requireArgs` | `string[]` | `require_args` | Arguments that decide whether the platform makes this request. It skips the webhook, and tries the next one, unless at least one of them is present. The SWML schema and the platform name the key `require_args`, and SignalWire's reference page lists it as `required_args`. |
|
|
255
|
+
|
|
256
|
+
**Returns:** `this` for chaining.
|
|
257
|
+
|
|
258
|
+
A webhook's other settings (`params()`, `foreach()`, `output()`, `errorKeys()`, `webhookExpressions()`) apply to the most recently added webhook. This example builds two tools, one with a URL template and one with an authentication header:
|
|
259
|
+
|
|
260
|
+
```typescript
|
|
261
|
+
// GET request with the argument URL-encoded into the path
|
|
262
|
+
const tool = new DataMap('get_stock_price')
|
|
263
|
+
.purpose('Get the current stock price')
|
|
264
|
+
.parameter('symbol', 'string', 'Stock ticker symbol', { required: true })
|
|
265
|
+
.webhook('GET', 'https://api.stocks.example.com/v1/price/${enc:args.symbol}');
|
|
266
|
+
|
|
267
|
+
// POST with an authentication header read from the environment
|
|
268
|
+
const tool2 = new DataMap('create_ticket')
|
|
269
|
+
.purpose('Create a support ticket')
|
|
270
|
+
.parameter('subject', 'string', 'Ticket subject', { required: true })
|
|
271
|
+
.parameter('description', 'string', 'Ticket description', { required: true })
|
|
272
|
+
.enableEnvExpansion()
|
|
273
|
+
.webhook('POST', 'https://api.helpdesk.example.com/tickets', {
|
|
274
|
+
headers: {
|
|
275
|
+
'Authorization': 'Bearer ${ENV.SW_HELPDESK_API_KEY}',
|
|
276
|
+
'Content-Type': 'application/json',
|
|
277
|
+
},
|
|
278
|
+
})
|
|
279
|
+
.params({ subject: '${args.subject}', description: '${args.description}' });
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
`${ENV.SW_HELPDESK_API_KEY}` is expanded by the SDK, and only because the name starts with an allowed prefix. See [Environment Variables](#environment-variables).
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
### params
|
|
287
|
+
|
|
288
|
+
This method sets the `params` object of the most recently added webhook. The platform sends `params` as the request's JSON body, and expands templates in its values first. A webhook with `params` is a `POST`, whatever its method. A webhook with no `params` sends no body, even as a `POST`.
|
|
289
|
+
|
|
290
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
291
|
+
```typescript
|
|
292
|
+
params(data: Record<string, unknown>): this
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
| Parameter | Type | Description |
|
|
296
|
+
|-----------|----------------------------|--------------------------|
|
|
297
|
+
| `data` | `Record<string, unknown>` | The request body object. Values can contain templates. |
|
|
298
|
+
|
|
299
|
+
**Throws:** `Error` if no webhook has been added yet.
|
|
300
|
+
|
|
301
|
+
**Returns:** `this` for chaining.
|
|
302
|
+
|
|
303
|
+
This tool posts a search to a knowledge base API, with the caller's query in the body:
|
|
304
|
+
|
|
305
|
+
```typescript
|
|
306
|
+
const tool = new DataMap('search_kb')
|
|
307
|
+
.purpose('Search the knowledge base')
|
|
308
|
+
.parameter('query', 'string', 'Search query', { required: true })
|
|
309
|
+
.webhook('POST', 'https://api.kb.example.com/search')
|
|
310
|
+
.params({
|
|
311
|
+
q: '${args.query}',
|
|
312
|
+
limit: 5,
|
|
313
|
+
format: 'json',
|
|
314
|
+
});
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The request body is `{"q": "<the query>", "limit": 5, "format": "json"}`. Because `params` becomes a body, put query-string values for a `GET` request in the URL instead: `https://api.kb.example.com/search?q=${enc:args.query}`. The built-in `datasphere_serverless` skill sends its search request with `params()`.
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
### body
|
|
322
|
+
|
|
323
|
+
This method sets the request body of the most recently added webhook. It does the same as [params](#params): the platform reads a webhook's body from its `params` field, so `body()` writes `params`, and a later `params()` or `body()` call replaces it.
|
|
324
|
+
|
|
325
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
326
|
+
```typescript
|
|
327
|
+
body(data: Record<string, unknown>): this
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
| Parameter | Type | Description |
|
|
331
|
+
|-----------|----------------------------|----------------------------|
|
|
332
|
+
| `data` | `Record<string, unknown>` | The request body object, written as the webhook's `params`. Values can contain templates. |
|
|
333
|
+
|
|
334
|
+
**Throws:** `Error` if no webhook has been added yet.
|
|
335
|
+
|
|
336
|
+
**Returns:** `this` for chaining.
|
|
337
|
+
|
|
338
|
+
`createSimpleApiTool()` uses `body()` for its `body` option.
|
|
339
|
+
|
|
340
|
+
> **Upgrading:** before this release, `body()` wrote a `body` key, which the platform doesn't read, so the webhook was sent without a request body (and as a `GET` unless its method was `POST`). It now writes `params`, so the body is sent and the request is a `POST`. If a tool called both `body()` and `params()`, only the later call's object is sent now; merge them into one object. A hand-written `body` key in a `data_map` is still not sent.
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
### Webhook Headers
|
|
345
|
+
|
|
346
|
+
You set headers through the `opts.headers` parameter of `webhook()`. The platform sends each header value as written: it expands templates in `url` and `params`, not in headers, so `${args.id}` in a header is sent as that text. The SDK expands `${ENV.*}` in header values when environment expansion is on, before the SWML is sent. This tool sends a token from the environment:
|
|
347
|
+
|
|
348
|
+
```typescript
|
|
349
|
+
const tool = new DataMap('authenticated_lookup')
|
|
350
|
+
.purpose('Look up data from an authenticated API')
|
|
351
|
+
.parameter('id', 'string', 'Record ID', { required: true })
|
|
352
|
+
.enableEnvExpansion()
|
|
353
|
+
.webhook('GET', 'https://api.example.com/records/${enc:args.id}', {
|
|
354
|
+
headers: {
|
|
355
|
+
'Authorization': 'Bearer ${ENV.SW_RECORDS_API_TOKEN}',
|
|
356
|
+
'X-Request-Source': 'signalwire-agent',
|
|
357
|
+
},
|
|
358
|
+
});
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
A header value is written into the SWML document, so a token in it is readable by anyone who can fetch the agent's SWML. [Environment Variables](#environment-variables) covers what that means for secrets.
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## Expressions
|
|
366
|
+
|
|
367
|
+
### expression
|
|
368
|
+
|
|
369
|
+
This method adds a pattern-matching expression. The platform expands the test value, matches it against a regular expression, and returns the output of the first expression that matches. Expressions make no HTTP request.
|
|
370
|
+
|
|
371
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
372
|
+
```typescript
|
|
373
|
+
expression(
|
|
374
|
+
testValue: string,
|
|
375
|
+
pattern: string | RegExp,
|
|
376
|
+
output: FunctionResult,
|
|
377
|
+
nomatchOutput?: FunctionResult
|
|
378
|
+
): this
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
| Parameter | Type | Description |
|
|
382
|
+
|-----------------|-----------------------|----------------------------------------------------------|
|
|
383
|
+
| `testValue` | `string` | The text to test, usually a template such as `"${args.input}"`. Written as `string`. |
|
|
384
|
+
| `pattern` | `string \| RegExp` | The regular expression, written as `pattern`. It matches case-insensitively unless written as `/pattern/`. For a `RegExp`, only `.source` is kept: its flags are dropped. |
|
|
385
|
+
| `output` | `FunctionResult` | The result when the pattern matches. Written as `output`. |
|
|
386
|
+
| `nomatchOutput` | `FunctionResult` | The result when the pattern doesn't match. Written as `nomatch-output`, which the platform reads. The SWML schema's expression object doesn't define this key. |
|
|
387
|
+
|
|
388
|
+
**Returns:** `this` for chaining.
|
|
389
|
+
|
|
390
|
+
The platform wraps a pattern that doesn't start with `/` as `/pattern/i`, so matching is case-insensitive by default: `'star\\s*wars'` matches "Star Wars". To match case-sensitively, write the pattern as `'/pattern/'`, such as `'/^[A-Z]{3}$/'`. A pattern written as `/pattern/flags` takes only its own `i` and `s` flags.
|
|
391
|
+
|
|
392
|
+
Expressions are tried in order, and the first match's output ends the function. An expression with a `nomatchOutput` also ends it when its pattern doesn't match, so later expressions aren't tried. For an answer when nothing matches, add a last expression with a catch-all pattern, or a [fallbackOutput](#fallbackoutput). This tool classifies input with a final catch-all:
|
|
393
|
+
|
|
394
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
395
|
+
```typescript
|
|
396
|
+
const tool = new DataMap('classify_input')
|
|
397
|
+
.purpose('Classify user input as a question or command')
|
|
398
|
+
.parameter('input', 'string', 'The user input to classify', { required: true })
|
|
399
|
+
.expression(
|
|
400
|
+
'${lc:args.input}',
|
|
401
|
+
'^(what|how|why|when|where|who|is|are|can|do|does)',
|
|
402
|
+
new FunctionResult('The input is a question.'),
|
|
403
|
+
)
|
|
404
|
+
.expression(
|
|
405
|
+
'${lc:args.input}',
|
|
406
|
+
'^(set|change|update|delete|create|send)',
|
|
407
|
+
new FunctionResult('The input is a command.'),
|
|
408
|
+
)
|
|
409
|
+
.expression(
|
|
410
|
+
'${args.input}',
|
|
411
|
+
'.*',
|
|
412
|
+
new FunctionResult('The input type could not be determined.'),
|
|
413
|
+
);
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
The platform matches case-insensitively, so "What time is it" counts as a question. The `lc` helper lowercases the input as well, so the match doesn't depend on that.
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## Response Processing
|
|
421
|
+
|
|
422
|
+
### output
|
|
423
|
+
|
|
424
|
+
This method sets the output of the most recently added webhook. The output's templates read the webhook's JSON response from the root of the template data, such as `${temp}`, and the arguments as `${input.args.name}`. An array response is under `array`. `${args.name}` expands to nothing here. See [Template data](#template-data).
|
|
425
|
+
|
|
426
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
427
|
+
```typescript
|
|
428
|
+
output(result: FunctionResult): this
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
| Parameter | Type | Description |
|
|
432
|
+
|-----------|------------------|------------------------------------------------------|
|
|
433
|
+
| `result` | `FunctionResult` | The result template. Templates can appear in the response text and in action values. |
|
|
434
|
+
|
|
435
|
+
**Throws:** `Error` if no webhook has been added yet.
|
|
436
|
+
|
|
437
|
+
**Returns:** `this` for chaining.
|
|
438
|
+
|
|
439
|
+
The output's response text goes back to the AI as context for its reply. The AI decides what to say. This tool formats three fields of the wttr.in response:
|
|
440
|
+
|
|
441
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
442
|
+
```typescript
|
|
443
|
+
const tool = new DataMap('get_weather')
|
|
444
|
+
.purpose('Get current weather')
|
|
445
|
+
.parameter('city', 'string', 'City name', { required: true })
|
|
446
|
+
.webhook('GET', 'https://wttr.in/${lc:enc:args.city}?format=j1')
|
|
447
|
+
.output(
|
|
448
|
+
new FunctionResult(
|
|
449
|
+
'Weather in ${input.args.city}: ' +
|
|
450
|
+
'Temperature: ${current_condition[0].temp_F}F, ' +
|
|
451
|
+
'Conditions: ${current_condition[0].weatherDesc[0].value}, ' +
|
|
452
|
+
'Humidity: ${current_condition[0].humidity}%'
|
|
453
|
+
),
|
|
454
|
+
);
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
`output()` stores `result.toDict()`, so the output can carry actions as well as text. This tool records the alert's ID in the function's metadata:
|
|
458
|
+
|
|
459
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
460
|
+
```typescript
|
|
461
|
+
const tool = new DataMap('urgent_alert')
|
|
462
|
+
.purpose('Send an urgent alert')
|
|
463
|
+
.parameter('message', 'string', 'Alert message', { required: true })
|
|
464
|
+
.webhook('POST', 'https://api.alerts.example.com/send')
|
|
465
|
+
.params({ message: '${args.message}' })
|
|
466
|
+
.output(
|
|
467
|
+
new FunctionResult('Alert sent: ${alert_id}')
|
|
468
|
+
.setMetadata({ alert_id: '${alert_id}' }),
|
|
469
|
+
);
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
### webhookExpressions
|
|
475
|
+
|
|
476
|
+
This method sets the `expressions` array of the most recently added webhook. The platform evaluates a webhook's `foreach`, then its `expressions`, then its `output`, so the expressions can test fields of the response.
|
|
477
|
+
|
|
478
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
479
|
+
```typescript
|
|
480
|
+
webhookExpressions(expressions: Record<string, unknown>[]): this
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
| Parameter | Type | Description |
|
|
484
|
+
|---------------|-----------------------------|----------------------------------------------------------------|
|
|
485
|
+
| `expressions` | `Record<string, unknown>[]` | Expression objects with `string`, `pattern` and `output` fields, written as given. |
|
|
486
|
+
|
|
487
|
+
**Throws:** `Error` if no webhook has been added yet.
|
|
488
|
+
|
|
489
|
+
**Returns:** `this` for chaining.
|
|
490
|
+
|
|
491
|
+
The SDK writes the objects without converting them, so call `toDict()` on each output yourself. Like the output, the expressions read the response from the root and the arguments as `${input.args.name}`. The platform expands a matched expression's output a second time, against the same data. This tool answers differently for each order status, and falls back to the webhook's output:
|
|
492
|
+
|
|
493
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
494
|
+
```typescript
|
|
495
|
+
const tool = new DataMap('check_order_status')
|
|
496
|
+
.purpose('Check the status of an order')
|
|
497
|
+
.parameter('order_id', 'string', 'Order ID', { required: true })
|
|
498
|
+
.webhook('GET', 'https://api.store.example.com/orders/${enc:args.order_id}')
|
|
499
|
+
.webhookExpressions([
|
|
500
|
+
{
|
|
501
|
+
string: '${status}',
|
|
502
|
+
pattern: 'shipped',
|
|
503
|
+
output: new FunctionResult(
|
|
504
|
+
'Order ${input.args.order_id} has shipped. Tracking: ${tracking_number}'
|
|
505
|
+
).toDict(),
|
|
506
|
+
},
|
|
507
|
+
{
|
|
508
|
+
string: '${status}',
|
|
509
|
+
pattern: 'processing',
|
|
510
|
+
output: new FunctionResult(
|
|
511
|
+
'Order ${input.args.order_id} is being processed. Estimated ship date: ${est_ship_date}'
|
|
512
|
+
).toDict(),
|
|
513
|
+
},
|
|
514
|
+
{
|
|
515
|
+
string: '${status}',
|
|
516
|
+
pattern: 'delivered',
|
|
517
|
+
output: new FunctionResult(
|
|
518
|
+
'Order ${input.args.order_id} was delivered on ${delivery_date}.'
|
|
519
|
+
).toDict(),
|
|
520
|
+
},
|
|
521
|
+
])
|
|
522
|
+
.output(
|
|
523
|
+
new FunctionResult('Order ${input.args.order_id} status: ${status}'),
|
|
524
|
+
);
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
---
|
|
528
|
+
|
|
529
|
+
## Error Handling
|
|
530
|
+
|
|
531
|
+
### fallbackOutput
|
|
532
|
+
|
|
533
|
+
This method sets the `data_map`'s own `output`. The platform uses it when no expression matched and no webhook produced a result: the webhook it requested failed, it requested none, or the webhook's expressions didn't match and it has no output. Without one, the AI gets the generic "There was an error processing this request."
|
|
534
|
+
|
|
535
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
536
|
+
```typescript
|
|
537
|
+
fallbackOutput(result: FunctionResult): this
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
| Parameter | Type | Description |
|
|
541
|
+
|-----------|------------------|-----------------------------------------------|
|
|
542
|
+
| `result` | `FunctionResult` | The fallback result. |
|
|
543
|
+
|
|
544
|
+
**Returns:** `this` for chaining.
|
|
545
|
+
|
|
546
|
+
The fallback's templates read the arguments as `${args.name}`, and no response exists when it runs. This tool reports the price, or says the lookup failed:
|
|
547
|
+
|
|
548
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
549
|
+
```typescript
|
|
550
|
+
const tool = new DataMap('get_price')
|
|
551
|
+
.purpose('Get the price of a product')
|
|
552
|
+
.parameter('product', 'string', 'Product name', { required: true })
|
|
553
|
+
.webhook('GET', 'https://api.store.example.com/price/${enc:args.product}')
|
|
554
|
+
.output(new FunctionResult('${input.args.product} costs $${price}'))
|
|
555
|
+
.fallbackOutput(
|
|
556
|
+
new FunctionResult('The price lookup for ${args.product} failed. Offer to try again later.'),
|
|
557
|
+
);
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
In `$${price}`, the first `$` is a literal dollar sign and `${price}` is the template.
|
|
561
|
+
|
|
562
|
+
---
|
|
563
|
+
|
|
564
|
+
### errorKeys
|
|
565
|
+
|
|
566
|
+
This method sets `error_keys` on the most recently added webhook. If the JSON response has any of these keys, the webhook counts as failed, whatever the key's value: `"errors": []` fails it. The platform then uses the fallback output, and doesn't try the next webhook. A response that isn't JSON, or a request that doesn't complete, fails the webhook the same way. An HTTP status outside 200-299 doesn't fail it by itself: the platform adds an `http_code` key to such a response, which the output can read as `${http_code}`, so `'http_code'` in the list fails the webhook on any such status.
|
|
567
|
+
|
|
568
|
+
If no webhook has been added yet, the keys are set on the `data_map` itself, as `globalErrorKeys()` does, and the platform ignores them there.
|
|
569
|
+
|
|
570
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
571
|
+
```typescript
|
|
572
|
+
errorKeys(keys: string[]): this
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
| Parameter | Type | Description |
|
|
576
|
+
|-----------|------------|----------------------------------------------------|
|
|
577
|
+
| `keys` | `string[]` | Response keys whose presence marks the response as a failure. |
|
|
578
|
+
|
|
579
|
+
**Returns:** `this` for chaining.
|
|
580
|
+
|
|
581
|
+
This tool treats a response with an `error`, `error_message` or `fault` key as a failure:
|
|
582
|
+
|
|
583
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
584
|
+
```typescript
|
|
585
|
+
const tool = new DataMap('api_lookup')
|
|
586
|
+
.purpose('Look up data from an API')
|
|
587
|
+
.parameter('id', 'string', 'Record ID', { required: true })
|
|
588
|
+
.webhook('GET', 'https://api.example.com/data/${enc:args.id}')
|
|
589
|
+
.errorKeys(['error', 'error_message', 'fault'])
|
|
590
|
+
.output(new FunctionResult('Found: ${name}'))
|
|
591
|
+
.fallbackOutput(new FunctionResult('The lookup failed.'));
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
---
|
|
595
|
+
|
|
596
|
+
### globalErrorKeys
|
|
597
|
+
|
|
598
|
+
This method sets `error_keys` on the `data_map` object itself, whether or not a webhook has been added.
|
|
599
|
+
|
|
600
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
601
|
+
```typescript
|
|
602
|
+
globalErrorKeys(keys: string[]): this
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
| Parameter | Type | Description |
|
|
606
|
+
|-----------|------------|----------------------------------------------------|
|
|
607
|
+
| `keys` | `string[]` | Response keys whose presence marks a response as a failure. |
|
|
608
|
+
|
|
609
|
+
**Returns:** `this` for chaining.
|
|
610
|
+
|
|
611
|
+
The SWML schema defines `error_keys` only on a webhook. Its `data_map` object has `expressions`, `webhooks` and `output`, and the platform reads `error_keys` only on a webhook, so a top-level `error_keys` has no effect. Set the keys on each webhook with [errorKeys](#errorkeys) instead. This example sets them on each webhook of a two-webhook chain, where `requireArgs` picks the webhook for the arguments the caller gave:
|
|
612
|
+
|
|
613
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
614
|
+
```typescript
|
|
615
|
+
const tool = new DataMap('find_store')
|
|
616
|
+
.purpose('Find the nearest store by ZIP code or by city')
|
|
617
|
+
.parameter('zip', 'string', 'ZIP code')
|
|
618
|
+
.parameter('city', 'string', 'City name')
|
|
619
|
+
.webhook('GET', 'https://api.stores.example.com/near?zip=${enc:args.zip}', {
|
|
620
|
+
requireArgs: ['zip'],
|
|
621
|
+
})
|
|
622
|
+
.errorKeys(['error', 'err'])
|
|
623
|
+
.output(new FunctionResult('The nearest store is ${name}.'))
|
|
624
|
+
.webhook('GET', 'https://api.stores.example.com/near?city=${enc:args.city}', {
|
|
625
|
+
requireArgs: ['city'],
|
|
626
|
+
})
|
|
627
|
+
.errorKeys(['error', 'err'])
|
|
628
|
+
.output(new FunctionResult('The nearest store is ${name}.'))
|
|
629
|
+
.fallbackOutput(new FunctionResult('The store lookup failed.'));
|
|
630
|
+
```
|
|
631
|
+
|
|
632
|
+
With a ZIP code, the platform requests the first webhook. With only a city, it skips the first webhook and requests the second. If the webhook it requests fails, the fallback output answers.
|
|
633
|
+
|
|
634
|
+
---
|
|
635
|
+
|
|
636
|
+
## Semantic Gates
|
|
637
|
+
|
|
638
|
+
A semantic gate is a yes/no question a decision model answers about the call right before the platform runs the function. When a gate fails, the data_map doesn't run at all: no expression or webhook is tried, and the model gets the gate's `on_fail` output. The [API reference](api-reference.md#semantic-gates) describes gates and their limits. They need a platform release that supports them; one that doesn't runs the function ungated.
|
|
639
|
+
|
|
640
|
+
### gate
|
|
641
|
+
|
|
642
|
+
This method adds a gate. Call it once per gate, up to 8.
|
|
643
|
+
|
|
644
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
645
|
+
```typescript
|
|
646
|
+
gate(gate: SemanticGate | Record<string, unknown>): this
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
`toSwaigFunction()` checks the gates by the platform's rules, after environment variables are expanded, and throws for one the platform would refuse. This tool places an order only once the caller has confirmed it:
|
|
650
|
+
|
|
651
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` and `SemanticGate` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
652
|
+
```typescript
|
|
653
|
+
const placeOrder = new DataMap('place_order')
|
|
654
|
+
.purpose('Place the order the caller confirmed')
|
|
655
|
+
.webhook('POST', 'https://orders.example.com/orders')
|
|
656
|
+
.params({ item: '${args.item}' })
|
|
657
|
+
.output(new FunctionResult('The order is placed.'))
|
|
658
|
+
.gate(
|
|
659
|
+
new SemanticGate(
|
|
660
|
+
'Has the caller confirmed the order in `conversation`?',
|
|
661
|
+
0.9,
|
|
662
|
+
'place_order was not run.',
|
|
663
|
+
),
|
|
664
|
+
)
|
|
665
|
+
.gateFillers({ default: ['Let me check that.'] });
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
### gateFillers
|
|
669
|
+
|
|
670
|
+
This method sets what the AI says while the gates are checked, shaped like a function's fillers: phrases keyed by language code, `auto` or `default`. It's only for a function with gates.
|
|
671
|
+
|
|
672
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
673
|
+
```typescript
|
|
674
|
+
gateFillers(fillers: FillerPhrases): this
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
---
|
|
678
|
+
|
|
679
|
+
## Iteration
|
|
680
|
+
|
|
681
|
+
### foreach
|
|
682
|
+
|
|
683
|
+
This method sets the `foreach` of the most recently added webhook. The platform walks an array in the response, expands a template once per element, and joins the results into one string for the output. It skips a `foreach` that lacks `input_key`, `output_key` or `append`.
|
|
684
|
+
|
|
685
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
686
|
+
```typescript
|
|
687
|
+
foreach(config: {
|
|
688
|
+
input_key: string;
|
|
689
|
+
output_key: string;
|
|
690
|
+
append: string;
|
|
691
|
+
max?: number;
|
|
692
|
+
}): this
|
|
693
|
+
```
|
|
694
|
+
|
|
695
|
+
| Parameter | Type | Description |
|
|
696
|
+
|---------------------|----------|--------------------------------------------------------------|
|
|
697
|
+
| `config.input_key` | `string` | The path to the array in the webhook's template data, such as `"orders"` or `"data.items"`. It's a path, not a template. |
|
|
698
|
+
| `config.output_key` | `string` | Where the built text is stored. The output reads it as `${output_key}`. |
|
|
699
|
+
| `config.append` | `string` | The template added once per element. `${this.field}` reads a field of an object element, and `${this}` is a string or number element itself. It can also read the response and `${input.args.name}`. |
|
|
700
|
+
| `config.max` | `number` | Optional. The most elements to use, from the start of the array. With no `max`, or 0, every element is used. |
|
|
701
|
+
|
|
702
|
+
**Throws:** `Error` if no webhook has been added yet.
|
|
703
|
+
|
|
704
|
+
**Returns:** `this` for chaining.
|
|
705
|
+
|
|
706
|
+
Inside `append`, the current element is `this`. After the loop, the text is stored under the `output_key` name, and the webhook's output reads it there. This tool lists a customer's recent orders:
|
|
707
|
+
|
|
708
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
709
|
+
```typescript
|
|
710
|
+
const tool = new DataMap('list_orders')
|
|
711
|
+
.purpose('List recent orders for a customer')
|
|
712
|
+
.parameter('customer_id', 'string', 'Customer ID', { required: true })
|
|
713
|
+
.webhook('GET', 'https://api.store.example.com/customers/${enc:args.customer_id}/orders')
|
|
714
|
+
.foreach({
|
|
715
|
+
input_key: 'orders',
|
|
716
|
+
output_key: 'order_list',
|
|
717
|
+
append: 'Order #${this.id}: ${this.status} - $${this.total}\n',
|
|
718
|
+
max: 5,
|
|
719
|
+
})
|
|
720
|
+
.output(
|
|
721
|
+
new FunctionResult('Recent orders for customer ${input.args.customer_id}:\n${order_list}'),
|
|
722
|
+
)
|
|
723
|
+
.fallbackOutput(
|
|
724
|
+
new FunctionResult('Could not retrieve orders for customer ${args.customer_id}.'),
|
|
725
|
+
);
|
|
726
|
+
```
|
|
727
|
+
|
|
728
|
+
Suppose the API returns this response:
|
|
729
|
+
|
|
730
|
+
```json
|
|
731
|
+
{
|
|
732
|
+
"orders": [
|
|
733
|
+
{ "id": "1001", "status": "shipped", "total": "29.99" },
|
|
734
|
+
{ "id": "1002", "status": "processing", "total": "49.50" },
|
|
735
|
+
{ "id": "1003", "status": "delivered", "total": "15.00" }
|
|
736
|
+
]
|
|
737
|
+
}
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
`${order_list}` then holds one line per order:
|
|
741
|
+
|
|
742
|
+
```text
|
|
743
|
+
Order #1001: shipped - $29.99
|
|
744
|
+
Order #1002: processing - $49.50
|
|
745
|
+
Order #1003: delivered - $15.00
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
---
|
|
749
|
+
|
|
750
|
+
## Environment Variables
|
|
751
|
+
|
|
752
|
+
### enableEnvExpansion
|
|
753
|
+
|
|
754
|
+
This method turns on `${ENV.NAME}` expansion for this DataMap. Expansion is a TypeScript SDK feature, not a platform one: the SDK replaces the template with a value from `process.env` before the definition reaches the SWML. It's off by default.
|
|
755
|
+
|
|
756
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
757
|
+
```typescript
|
|
758
|
+
enableEnvExpansion(enabled?: boolean): this
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
| Parameter | Type | Default | Description |
|
|
762
|
+
|-----------|-----------|---------|-----------------------------------------|
|
|
763
|
+
| `enabled` | `boolean` | `true` | Whether to turn expansion on. Calling the method with no argument turns it on. |
|
|
764
|
+
|
|
765
|
+
**Returns:** `this` for chaining.
|
|
766
|
+
|
|
767
|
+
With expansion on, `toSwaigFunction()` replaces every `${ENV.NAME}` in every string of the function definition. That includes the URL, headers, `params`, outputs, expressions and the description. Each replacement follows these rules:
|
|
768
|
+
|
|
769
|
+
- A name that starts with an [allowed prefix](#allowed-prefixes) becomes the variable's value, or an empty string if the variable isn't set.
|
|
770
|
+
- A name without an allowed prefix becomes an empty string. The SDK logs no warning.
|
|
771
|
+
- With expansion off, the SDK leaves `${ENV.NAME}` as text. The platform's template data has no `ENV` object.
|
|
772
|
+
|
|
773
|
+
Expansion runs when `toSwaigFunction()` is called. `registerWithAgent()` calls it at once, so the values are fixed at registration, not read again for each call. This tool reads its base URL and key from variables with the `SW_` prefix:
|
|
774
|
+
|
|
775
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
776
|
+
```typescript
|
|
777
|
+
// Set in the environment, for example through deployment config:
|
|
778
|
+
// SW_LOOKUP_BASE_URL=https://api.example.com
|
|
779
|
+
// SW_LOOKUP_API_KEY=a-long-random-key
|
|
780
|
+
|
|
781
|
+
const tool = new DataMap('secure_lookup')
|
|
782
|
+
.purpose('Look up data from a secure API')
|
|
783
|
+
.parameter('query', 'string', 'Search query', { required: true })
|
|
784
|
+
.enableEnvExpansion()
|
|
785
|
+
.webhook('GET', '${ENV.SW_LOOKUP_BASE_URL}/search?q=${enc:args.query}', {
|
|
786
|
+
headers: {
|
|
787
|
+
'Authorization': 'Bearer ${ENV.SW_LOOKUP_API_KEY}',
|
|
788
|
+
},
|
|
789
|
+
})
|
|
790
|
+
.output(new FunctionResult('Result: ${data}'));
|
|
791
|
+
```
|
|
792
|
+
|
|
793
|
+
The expanded values are written into the SWML document. Anyone who can fetch the agent's SWML, which the agent's basic auth credentials allow, can read them, and SignalWire receives them with every call. Expansion keeps a secret out of your source code, not out of the SWML.
|
|
794
|
+
|
|
795
|
+
### Allowed prefixes
|
|
796
|
+
|
|
797
|
+
Only variables whose names start with an allowed prefix are expanded. The default prefixes are `SIGNALWIRE_`, `SWML_` and `SW_`.
|
|
798
|
+
|
|
799
|
+
The allowlist limits which variables a template can put into the SWML. Without it, a template such as `${ENV.DATABASE_PASSWORD}`, from a typo or from a definition someone else wrote, would publish any variable in the process. It doesn't protect variables that match a prefix: `${ENV.SIGNALWIRE_API_TOKEN}` is expanded like any other `SIGNALWIRE_` name.
|
|
800
|
+
|
|
801
|
+
Two functions set the list:
|
|
802
|
+
|
|
803
|
+
| Function | Scope |
|
|
804
|
+
|---|---|
|
|
805
|
+
| `setAllowedEnvPrefixes(prefixes)`, exported from the package | The default for every DataMap that has no list of its own. It's read when each DataMap's `toSwaigFunction()` runs. |
|
|
806
|
+
| `tool.setAllowedEnvPrefixes(prefixes)`, a `DataMap` method | This DataMap only, replacing the default. |
|
|
807
|
+
|
|
808
|
+
`getAllowedEnvPrefixes()` returns a copy of the default list. An empty array allows every variable, which removes the protection. Prefer adding a prefix to allowing everything. This example lets one DataMap read variables that start with `WEATHER_`:
|
|
809
|
+
|
|
810
|
+
```typescript
|
|
811
|
+
import { DataMap, FunctionResult } from '@signalwire/sdk';
|
|
812
|
+
|
|
813
|
+
const weather = new DataMap('get_weather')
|
|
814
|
+
.purpose('Get current weather for a city')
|
|
815
|
+
.parameter('city', 'string', 'The city name', { required: true })
|
|
816
|
+
.enableEnvExpansion()
|
|
817
|
+
.setAllowedEnvPrefixes(['WEATHER_'])
|
|
818
|
+
.webhook('GET', 'https://api.weatherapi.com/v1/current.json?key=${ENV.WEATHER_API_KEY}&q=${lc:enc:args.city}')
|
|
819
|
+
.output(new FunctionResult('${current.condition.text}, ${current.temp_f} degrees'));
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
The per-DataMap list replaces the default, so this DataMap no longer expands `SIGNALWIRE_`, `SWML_` or `SW_` names.
|
|
823
|
+
|
|
824
|
+
---
|
|
825
|
+
|
|
826
|
+
## Registration
|
|
827
|
+
|
|
828
|
+
### registerWithAgent
|
|
829
|
+
|
|
830
|
+
This method registers the DataMap tool with an agent. It calls `toSwaigFunction()` and passes the result to the agent's `registerSwaigFunction()` method.
|
|
831
|
+
|
|
832
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
833
|
+
```typescript
|
|
834
|
+
registerWithAgent(agent: {
|
|
835
|
+
registerSwaigFunction(fn: Record<string, unknown>): unknown
|
|
836
|
+
}): this
|
|
837
|
+
```
|
|
838
|
+
|
|
839
|
+
| Parameter | Type | Description |
|
|
840
|
+
|-----------|----------|----------------------------------------------------|
|
|
841
|
+
| `agent` | `object` | An object with a `registerSwaigFunction` method, such as an `AgentBase`. |
|
|
842
|
+
|
|
843
|
+
**Returns:** `this` for chaining.
|
|
844
|
+
|
|
845
|
+
This agent registers a time lookup and starts serving:
|
|
846
|
+
|
|
847
|
+
<!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port): collides under the concurrent gate and cannot run standalone -->
|
|
848
|
+
```typescript
|
|
849
|
+
import { AgentBase, DataMap, FunctionResult } from '@signalwire/sdk';
|
|
850
|
+
|
|
851
|
+
const agent = new AgentBase({ name: 'my-agent', basicAuth: ['user', 'pass'] });
|
|
852
|
+
|
|
853
|
+
new DataMap('get_time')
|
|
854
|
+
.purpose('Get the current time in a timezone')
|
|
855
|
+
.parameter('timezone', 'string', 'IANA timezone, such as America/Chicago', { required: true })
|
|
856
|
+
.webhook('GET', 'https://worldtimeapi.org/api/timezone/${args.timezone}')
|
|
857
|
+
.output(new FunctionResult('Current time: ${datetime}'))
|
|
858
|
+
.fallbackOutput(new FunctionResult('Could not get time for that timezone.'))
|
|
859
|
+
.registerWithAgent(agent);
|
|
860
|
+
|
|
861
|
+
agent.run();
|
|
862
|
+
```
|
|
863
|
+
|
|
864
|
+
The timezone isn't URL-encoded, because its `/` is part of the URL path.
|
|
865
|
+
|
|
866
|
+
---
|
|
867
|
+
|
|
868
|
+
### toSwaigFunction
|
|
869
|
+
|
|
870
|
+
This method serializes the DataMap to the SWAIG function object that goes into the SWML document.
|
|
871
|
+
|
|
872
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
873
|
+
```typescript
|
|
874
|
+
toSwaigFunction(): Record<string, unknown>
|
|
875
|
+
```
|
|
876
|
+
|
|
877
|
+
**Returns:** A plain object with `function`, `description`, `parameters`, and `data_map` fields.
|
|
878
|
+
|
|
879
|
+
This example builds an expression tool and prints its definition:
|
|
880
|
+
|
|
881
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `DataMap` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
882
|
+
```typescript
|
|
883
|
+
const tool = new DataMap('echo')
|
|
884
|
+
.purpose('Echo back the input')
|
|
885
|
+
.parameter('text', 'string', 'Text to echo', { required: true })
|
|
886
|
+
.expression(
|
|
887
|
+
'${args.text}',
|
|
888
|
+
'.*',
|
|
889
|
+
new FunctionResult('You said: ${args.text}'),
|
|
890
|
+
);
|
|
891
|
+
|
|
892
|
+
const swaigDef = tool.toSwaigFunction();
|
|
893
|
+
console.log(JSON.stringify(swaigDef, null, 2));
|
|
894
|
+
```
|
|
895
|
+
|
|
896
|
+
The script prints this definition:
|
|
897
|
+
|
|
898
|
+
```json
|
|
899
|
+
{
|
|
900
|
+
"function": "echo",
|
|
901
|
+
"description": "Echo back the input",
|
|
902
|
+
"parameters": {
|
|
903
|
+
"type": "object",
|
|
904
|
+
"properties": {
|
|
905
|
+
"text": {
|
|
906
|
+
"type": "string",
|
|
907
|
+
"description": "Text to echo"
|
|
908
|
+
}
|
|
909
|
+
},
|
|
910
|
+
"required": [
|
|
911
|
+
"text"
|
|
912
|
+
]
|
|
913
|
+
},
|
|
914
|
+
"data_map": {
|
|
915
|
+
"expressions": [
|
|
916
|
+
{
|
|
917
|
+
"string": "${args.text}",
|
|
918
|
+
"pattern": ".*",
|
|
919
|
+
"output": {
|
|
920
|
+
"response": "You said: ${args.text}"
|
|
921
|
+
}
|
|
922
|
+
}
|
|
923
|
+
]
|
|
924
|
+
}
|
|
925
|
+
}
|
|
926
|
+
```
|
|
927
|
+
|
|
928
|
+
You can then register the definition yourself:
|
|
929
|
+
|
|
930
|
+
```typescript
|
|
931
|
+
agent.registerSwaigFunction(tool.toSwaigFunction());
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
`toSwaigFunction()` always writes `expressions` and `webhooks` as lists. A `data_map` you write by hand can give either one as a single object instead. The platform runs a single expression object as a one-element list. A single webhook object runs differently from a list: the platform doesn't check its `require_args` or its `error_keys`, and a response that isn't JSON or a request that doesn't complete doesn't fail it. Its `foreach`, `expressions` and `output` then read the error response: `${parse_error}` is `true`, `${raw_response}` is the body, and `${http_code}` is the last status received, a redirect's included, or `0` when no response came back. Like a webhook in a list, it needs an `output` or `expressions`. `swaig-test --exec` runs both forms as the platform does.
|
|
935
|
+
|
|
936
|
+
---
|
|
937
|
+
|
|
938
|
+
## Helper Functions
|
|
939
|
+
|
|
940
|
+
### createSimpleApiTool
|
|
941
|
+
|
|
942
|
+
This function creates a DataMap tool with one webhook and one output template.
|
|
943
|
+
|
|
944
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
945
|
+
```typescript
|
|
946
|
+
import { createSimpleApiTool } from '@signalwire/sdk';
|
|
947
|
+
|
|
948
|
+
createSimpleApiTool(opts: {
|
|
949
|
+
name: string;
|
|
950
|
+
url: string;
|
|
951
|
+
responseTemplate: string;
|
|
952
|
+
parameters?: Record<string, {
|
|
953
|
+
type?: string;
|
|
954
|
+
description?: string;
|
|
955
|
+
required?: boolean;
|
|
956
|
+
}>;
|
|
957
|
+
method?: string;
|
|
958
|
+
headers?: Record<string, string>;
|
|
959
|
+
body?: Record<string, unknown>;
|
|
960
|
+
errorKeys?: string[];
|
|
961
|
+
}): DataMap
|
|
962
|
+
```
|
|
963
|
+
|
|
964
|
+
| Parameter | Type | Default | Description |
|
|
965
|
+
|-------------------------|----------------------------|-----------|---------------------------------------------------|
|
|
966
|
+
| `opts.name` | `string` | None | Tool name. |
|
|
967
|
+
| `opts.url` | `string` | None | Webhook URL, with templates. |
|
|
968
|
+
| `opts.responseTemplate` | `string` | None | The output's response text. Response fields are read from the root, as `${field}`, and arguments as `${input.args.name}`. |
|
|
969
|
+
| `opts.parameters` | `Record<string, {...}>` | None | Parameter definitions. A missing `type` is `string`. |
|
|
970
|
+
| `opts.method` | `string` | `'GET'` | HTTP method. The platform sends a `GET` unless it's `POST` or the tool has a `body`. |
|
|
971
|
+
| `opts.headers` | `Record<string, string>` | None | Request headers. |
|
|
972
|
+
| `opts.body` | `Record<string, unknown>` | None | The request body, written as the webhook's `params` with `body()`. A tool with a body is sent as a `POST`; an empty object is left out. See [params](#params). |
|
|
973
|
+
| `opts.errorKeys` | `string[]` | None | Response keys that mark a failure. |
|
|
974
|
+
|
|
975
|
+
**Returns:** A configured `DataMap` instance, ready for registration.
|
|
976
|
+
|
|
977
|
+
These two tools call a joke API and a document search API:
|
|
978
|
+
|
|
979
|
+
```typescript
|
|
980
|
+
import { createSimpleApiTool } from '@signalwire/sdk';
|
|
981
|
+
|
|
982
|
+
// A single GET endpoint that returns a JSON object
|
|
983
|
+
const jokeTool = createSimpleApiTool({
|
|
984
|
+
name: 'get_joke',
|
|
985
|
+
url: 'https://official-joke-api.appspot.com/random_joke',
|
|
986
|
+
responseTemplate: 'Here is a joke: ${setup} ... ${punchline}',
|
|
987
|
+
});
|
|
988
|
+
|
|
989
|
+
agent.registerSwaigFunction(jokeTool.toSwaigFunction());
|
|
990
|
+
|
|
991
|
+
// With parameters, a header and error keys
|
|
992
|
+
const searchTool = createSimpleApiTool({
|
|
993
|
+
name: 'search_docs',
|
|
994
|
+
url: 'https://api.docs.example.com/search?q=${enc:args.query}&limit=${args.limit}',
|
|
995
|
+
responseTemplate: 'Found ${total} results. Top result: ${results[0].title}',
|
|
996
|
+
parameters: {
|
|
997
|
+
query: { type: 'string', description: 'Search query', required: true },
|
|
998
|
+
limit: { type: 'integer', description: 'Max results' },
|
|
999
|
+
},
|
|
1000
|
+
headers: {
|
|
1001
|
+
'Authorization': 'Bearer a-long-random-token',
|
|
1002
|
+
},
|
|
1003
|
+
errorKeys: ['error'],
|
|
1004
|
+
});
|
|
1005
|
+
|
|
1006
|
+
agent.registerSwaigFunction(searchTool.toSwaigFunction());
|
|
1007
|
+
```
|
|
1008
|
+
|
|
1009
|
+
---
|
|
1010
|
+
|
|
1011
|
+
### createExpressionTool
|
|
1012
|
+
|
|
1013
|
+
This function creates a DataMap tool from expressions alone, with no HTTP request.
|
|
1014
|
+
|
|
1015
|
+
<!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
|
|
1016
|
+
```typescript
|
|
1017
|
+
import { createExpressionTool } from '@signalwire/sdk';
|
|
1018
|
+
|
|
1019
|
+
createExpressionTool(opts: {
|
|
1020
|
+
name: string;
|
|
1021
|
+
patterns: Record<string, [string, FunctionResult]>;
|
|
1022
|
+
parameters?: Record<string, {
|
|
1023
|
+
type?: string;
|
|
1024
|
+
description?: string;
|
|
1025
|
+
required?: boolean;
|
|
1026
|
+
}>;
|
|
1027
|
+
}): DataMap
|
|
1028
|
+
```
|
|
1029
|
+
|
|
1030
|
+
| Parameter | Type | Description |
|
|
1031
|
+
|-------------------|--------------------------------------------|--------------------------------------------------------|
|
|
1032
|
+
| `opts.name` | `string` | Tool name. |
|
|
1033
|
+
| `opts.patterns` | `Record<string, [string, FunctionResult]>` | Map of test values to `[pattern, output]` tuples. |
|
|
1034
|
+
| `opts.parameters` | `Record<string, {...}>` | Parameter definitions. |
|
|
1035
|
+
|
|
1036
|
+
Each key of `patterns` is a test value, usually a template, and each value is a `[regexPattern, result]` tuple. Because an object's keys are unique, each test value can have only one pattern. This tool checks a phone number's format:
|
|
1037
|
+
|
|
1038
|
+
```typescript
|
|
1039
|
+
import { createExpressionTool, FunctionResult } from '@signalwire/sdk';
|
|
1040
|
+
|
|
1041
|
+
const validator = createExpressionTool({
|
|
1042
|
+
name: 'validate_phone',
|
|
1043
|
+
patterns: {
|
|
1044
|
+
'${args.phone}': [
|
|
1045
|
+
'^\\+?1?\\d{10,15}$',
|
|
1046
|
+
new FunctionResult('The phone number ${args.phone} is valid.'),
|
|
1047
|
+
],
|
|
1048
|
+
},
|
|
1049
|
+
parameters: {
|
|
1050
|
+
phone: { type: 'string', description: 'Phone number to validate', required: true },
|
|
1051
|
+
},
|
|
1052
|
+
});
|
|
1053
|
+
|
|
1054
|
+
agent.registerSwaigFunction(validator.toSwaigFunction());
|
|
1055
|
+
```
|
|
1056
|
+
|
|
1057
|
+
---
|
|
1058
|
+
|
|
1059
|
+
## Template Reference
|
|
1060
|
+
|
|
1061
|
+
SignalWire's platform expands these templates when it runs a `data_map` function. The SDK writes them into the SWML as text. The source is SignalWire's [data_map reference](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions/data-map) and [template functions reference](https://signalwire.com/docs/swml/reference/template-functions).
|
|
1062
|
+
|
|
1063
|
+
### Template data
|
|
1064
|
+
|
|
1065
|
+
Every template reads from a JSON object, the template data, which the platform builds for each call of the function. A template names a path from its root: `${args.city}` reads `city` inside `args`. Which object that is depends on the stage the template is in.
|
|
1066
|
+
|
|
1067
|
+
The first object is the call data. Its root holds these values:
|
|
1068
|
+
|
|
1069
|
+
- `args`: the arguments the AI extracted for this call, by parameter name. Example: `${args.city}`.
|
|
1070
|
+
- `global_data`: the application's global data. Example: `${global_data.account_tier}`.
|
|
1071
|
+
- `meta_data`: the function's metadata, merged key by key over the global data the call starts with when the platform loads the function, so a `global_data` key the function's `meta_data` doesn't set is there too. Example: `${meta_data.table.sales}`.
|
|
1072
|
+
- The prompt variables, at the root.
|
|
1073
|
+
- Details of the call: `call_id`, `ai_session_id`, `conversation_id`, `function`, `caller_id_name`, `caller_id_num`, `project_id`, `space_id` and `app_name`.
|
|
1074
|
+
|
|
1075
|
+
When a webhook responds, its `foreach`, `expressions` and `output` read a second object, built from the response. An object response's fields are at its root: a response of `{"total": 25, "results": [...]}` gives `${total}` and `${results[0].title}`. There is no `response.` prefix, and `${response.total}` expands to nothing. An array response is under `array`, as in `${array[0].joke}`. The call data is under `input`, so the arguments are `${input.args.city}`, and `${args.city}` expands to nothing. The object also has `global_data` and `prompt_vars`. A status outside 200-299 is under `http_code`.
|
|
1076
|
+
|
|
1077
|
+
Each stage reads these values:
|
|
1078
|
+
|
|
1079
|
+
| Where the template is | What it reads | The arguments |
|
|
1080
|
+
|---|---|---|
|
|
1081
|
+
| A webhook's `url` and `params` | The call data. The response doesn't exist yet. | `${args.name}` |
|
|
1082
|
+
| A webhook's `headers` | Nothing: the platform sends header values as written | None |
|
|
1083
|
+
| The top-level `expressions` | The call data | `${args.name}` |
|
|
1084
|
+
| A webhook's `foreach`, `expressions` and `output` | The response's fields (or `array`), `input` (the call data), `global_data`, `prompt_vars`, and `http_code` for a status outside 200-299 | `${input.args.name}` |
|
|
1085
|
+
| A `foreach` `append` template | The same as the webhook's output, plus `this`, the current element | `${input.args.name}` |
|
|
1086
|
+
| The `data_map`'s own `output` (the fallback) | The call data, plus `global_data` and `prompt_vars` | `${args.name}` |
|
|
1087
|
+
|
|
1088
|
+
During a `foreach`, `this` is the current element: `${this.title}` for a field of an object, and `${this}` for a string or number. The text it builds is stored under its `output_key`, as in `${order_list}`, which the webhook's `expressions` and `output` read.
|
|
1089
|
+
|
|
1090
|
+
### Template syntax
|
|
1091
|
+
|
|
1092
|
+
`${path}` is replaced by the value at `path` in the template data, and `%{path}` means the same. A path uses dots for object fields and zero-based `[n]` for array elements, as in `${args.filters.category}` and `${results[0].title}`. A negative index counts from the end: `${results[-1].title}` is the last element. A path whose value isn't set becomes an empty string.
|
|
1093
|
+
|
|
1094
|
+
Inside `${...}`, a helper name and a colon before the path transform the value. The platform has three helpers, and matches their names in any case:
|
|
1095
|
+
|
|
1096
|
+
| Helper | What it does | Example |
|
|
1097
|
+
|---|---|---|
|
|
1098
|
+
| `lc` | Lowercases the value | `${lc:args.department}` |
|
|
1099
|
+
| `enc` | URL-encodes the value: spaces, control and non-ASCII characters, and ``"#%&+:;<=>?@[\]^`{\|}`` become `%XX`. Other characters, such as `/`, `,` and `$`, stay as they are, and a `%` that already starts an uppercase `%XX` isn't encoded again. | `${enc:args.query}` |
|
|
1100
|
+
| `fmt_ph` | Formats a phone number in national format, as it is dialed within its country. A number without a country code is read as a US number, the letters of a number with three or more of them are read as keypad digits (`1-800-FLOWERS`), and a value that isn't a valid number becomes `INVALID NUMBER`. | `${fmt_ph:args.phone}` |
|
|
1101
|
+
|
|
1102
|
+
Helpers combine, as in `${lc:enc:args.city}`. The platform applies them in a fixed order, whatever order you write them in: `fmt_ph`, then `lc`, then `enc`. So `${lc:enc:args.city}` and `${enc:lc:args.city}` both lowercase the city, then URL-encode it.
|
|
1103
|
+
|
|
1104
|
+
There is no uppercase helper, and `enc` takes no encoding name. Any other name before a colon is part of the path: in `${enc:url:args.query}`, the platform reads the path `url:args.query`, which doesn't resolve, so it writes nothing.
|
|
1105
|
+
|
|
1106
|
+
Templates nest, and expand from the inside out. In `${meta_data.contacts.${lc:args.department}}`, the inner template turns "Sales" into `sales`, and the outer one then reads `meta_data.contacts.sales`.
|
|
1107
|
+
|
|
1108
|
+
### Template functions
|
|
1109
|
+
|
|
1110
|
+
`@{...}` functions take arguments after a space. SignalWire's template functions reference documents these:
|
|
1111
|
+
|
|
1112
|
+
| Function | Syntax | What it does |
|
|
1113
|
+
|---|---|---|
|
|
1114
|
+
| `strftime_tz` | `@{strftime_tz <timezone> <format>}` | The current date and time in a time zone, with strftime codes: `@{strftime_tz America/Chicago %Y-%m-%d %H:%M:%S}` |
|
|
1115
|
+
| `fmt_ph` | `@{fmt_ph <format> <number>}` or `@{fmt_ph <format>:sep:<separator> <number>}` | Formats a phone number as `national` (the default), `international`, `RFC3966` or `e164`, optionally with a separator between digit groups: `@{fmt_ph national:sep:- ${caller_id_num}}` |
|
|
1116
|
+
| `expr` | `@{expr <expression>}` | Arithmetic on literal numbers, with `+ - * /` and parentheses. It can't read variables: `@{expr (100 - 25) / 5}` |
|
|
1117
|
+
| `echo` | `@{echo <text>}` | Returns its argument, for debugging expansion: `@{echo ${args.input}}` |
|
|
1118
|
+
| `separate` | `@{separate <text>}` | Puts a space between characters, so text-to-speech reads a code one character at a time: `@{separate ${args.code}}` |
|
|
1119
|
+
| `sleep` | `@{sleep <seconds>}` | Pauses for that many seconds. A delay can make the function time out. |
|
|
1120
|
+
|
|
1121
|
+
Template functions work in SWAIG contexts: `data_map` expressions, webhooks and outputs, responses from SWAIG function webhooks, and AI prompt variable expansion.
|
|
1122
|
+
|
|
1123
|
+
---
|
|
1124
|
+
|
|
1125
|
+
## Testing a DataMap
|
|
1126
|
+
|
|
1127
|
+
`swaig-test --exec` runs a DataMap function locally. It makes the webhook requests and expands the templates the way [Template Reference](#template-reference) describes, so you can check a template before a real call. For the command and its options, see [DataMap Functions](cli-guide.md#datamap-functions) in the CLI guide.
|
|
1128
|
+
|
|
1129
|
+
This command runs the weather tool from `examples/datamap-tools.ts` against the real wttr.in API:
|
|
1130
|
+
|
|
1131
|
+
```bash
|
|
1132
|
+
npx tsx src/cli/swaig-test.ts examples/datamap-tools.ts --exec get_weather --city London
|
|
1133
|
+
```
|
|
1134
|
+
|
|
1135
|
+
The command prints the expanded response. The temperature and conditions depend on the day:
|
|
1136
|
+
|
|
1137
|
+
```text
|
|
1138
|
+
RESULT:
|
|
1139
|
+
Response: Weather in London: 61°F, Overcast
|
|
1140
|
+
```
|
|
1141
|
+
|
|
1142
|
+
The simulator follows the platform's stage template data, template rules and webhook rules, described in [Template data](#template-data), [Template Reference](#template-reference) and [errorKeys](#errorkeys). `--custom-data` gives it the call data the platform adds, such as `global_data`, `caller_id_num` and `prompt_vars`, as in `--custom-data '{"global_data": {"account_tier": "gold"}}'`. Without `global_data` in `--custom-data`, it uses the agent's global data, as a call starts with it. A path that doesn't resolve expands to an empty string, as on the platform, and the simulator says so on stderr. It adds a hint when the path starts with `response.`, or when `${args.name}` is used in a webhook's output, expressions or `foreach`. When nothing produces a result, it returns the platform's `{"response": "There was an error processing this request."}`, says so on stderr, and `swaig-test` exits with status 0, since that is a valid result on the platform, not a failure of the tool. It differs from the platform in these ways:
|
|
1143
|
+
|
|
1144
|
+
- Without the optional `libphonenumber-js` package, `fmt_ph` formats only a North American number, as `(202) 555-0143`, and leaves any other value as it is, saying so on stderr. The platform formats any valid number in its national format, and writes `INVALID NUMBER` for one that isn't valid. With `libphonenumber-js` installed (`npm install -D libphonenumber-js`), so does the simulator, though the package's number data can differ from the platform's for a rare number. Either way, the simulator reads a vanity number as the platform does: when a number has three or more letters, they are keypad digits, so `1-800-FLOWERS` is `(800) 356-9377`.
|
|
1145
|
+
- The call data has only the function's name, `meta_data` and arguments, the agent's global data, and what you give with `--custom-data`. Call details such as `call_id` are there only if you give them.
|
|
1146
|
+
- `${meta_data.x}` reads this function's `meta_data` merged over the global data, and nothing more. On the platform, it reads a metadata store keyed by the function's token. The SDK sends no `meta_data_token`, and a DataMap function has no URL of its own, so it takes the agent's default webhook URL, and all of an agent's DataMap functions share one store. A call can then see keys from the other DataMap functions' `meta_data`, the last function loaded wins on a clash, and `set_meta_data` actions change the store during the call.
|
|
1147
|
+
- It leaves `@{...}` functions as they are, and doesn't evaluate an expression's `expr`.
|
|
1148
|
+
- It matches patterns with JavaScript regular expressions, where the platform uses PCRE. Like the platform, it matches case-insensitively unless the pattern is written `/pattern/flags`, and it accepts a leading `(?i)`. Other PCRE-only syntax is reported as an invalid pattern.
|
|
1149
|
+
- It refuses private and internal addresses, unless `SWML_ALLOW_PRIVATE_URLS` is `true`.
|
|
1150
|
+
|
|
1151
|
+
---
|
|
1152
|
+
|
|
1153
|
+
## Complete Example
|
|
1154
|
+
|
|
1155
|
+
This agent registers the DataMap tools described in the earlier sections: a webhook tool with a `foreach` and error handling, and an expression tool. Each builder call is described in its own section: [webhook](#webhook), [foreach](#foreach), [errorKeys](#errorkeys), [fallbackOutput](#fallbackoutput) and [expression](#expression).
|
|
1156
|
+
|
|
1157
|
+
<!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port): collides under the concurrent gate and cannot run standalone -->
|
|
1158
|
+
```typescript
|
|
1159
|
+
import { AgentBase, DataMap, FunctionResult } from '@signalwire/sdk';
|
|
1160
|
+
|
|
1161
|
+
const agent = new AgentBase({
|
|
1162
|
+
name: 'store-agent',
|
|
1163
|
+
route: '/',
|
|
1164
|
+
basicAuth: [
|
|
1165
|
+
process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
|
|
1166
|
+
process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'a-long-random-password',
|
|
1167
|
+
],
|
|
1168
|
+
});
|
|
1169
|
+
|
|
1170
|
+
agent.setPromptText('You help customers check their orders and validate their details.');
|
|
1171
|
+
|
|
1172
|
+
// A webhook tool: fetch the caller's orders and format them as a list.
|
|
1173
|
+
new DataMap('list_orders')
|
|
1174
|
+
.purpose('List recent orders for the caller. Use when the caller asks about their orders.')
|
|
1175
|
+
.parameter('email', 'string', 'Customer email address', { required: true })
|
|
1176
|
+
.webhook('GET', 'https://api.store.example.com/orders?email=${enc:args.email}')
|
|
1177
|
+
.errorKeys(['error'])
|
|
1178
|
+
.foreach({
|
|
1179
|
+
input_key: 'orders',
|
|
1180
|
+
output_key: 'order_summary',
|
|
1181
|
+
append: '- Order #${this.id}: ${this.status}, Total: $${this.total}\n',
|
|
1182
|
+
max: 10,
|
|
1183
|
+
})
|
|
1184
|
+
.output(new FunctionResult('Recent orders:\n${order_summary}'))
|
|
1185
|
+
.fallbackOutput(new FunctionResult('No orders were found for ${args.email}.'))
|
|
1186
|
+
.registerWithAgent(agent);
|
|
1187
|
+
|
|
1188
|
+
// An expression tool: check a ZIP code's format without an HTTP request.
|
|
1189
|
+
new DataMap('validate_zip')
|
|
1190
|
+
.purpose('Check whether a US ZIP code is well formed')
|
|
1191
|
+
.parameter('zip', 'string', 'ZIP code to validate', { required: true })
|
|
1192
|
+
.expression(
|
|
1193
|
+
'${args.zip}',
|
|
1194
|
+
'^\\d{5}(-\\d{4})?$',
|
|
1195
|
+
new FunctionResult('${args.zip} is a valid US ZIP code.'),
|
|
1196
|
+
)
|
|
1197
|
+
.expression(
|
|
1198
|
+
'${args.zip}',
|
|
1199
|
+
'.*',
|
|
1200
|
+
new FunctionResult('${args.zip} is not a valid US ZIP code. Ask the caller to repeat it.'),
|
|
1201
|
+
)
|
|
1202
|
+
.registerWithAgent(agent);
|
|
1203
|
+
|
|
1204
|
+
agent.run();
|
|
1205
|
+
```
|
|
1206
|
+
|
|
1207
|
+
For a runnable file, see `examples/datamap-tools.ts` and `examples/advanced-datamap.ts`.
|