@signalwire/sdk 2.0.5 → 3.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +785 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +481 -126
- package/dist/AgentBase.js +1502 -438
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +21 -0
- package/dist/AgentServer.js +154 -47
- package/dist/AgentServer.js.map +1 -1
- package/dist/AuthHandler.d.ts +14 -2
- package/dist/AuthHandler.js +7 -2
- package/dist/AuthHandler.js.map +1 -1
- package/dist/ConfigLoader.d.ts +5 -13
- package/dist/ConfigLoader.js +15 -29
- package/dist/ConfigLoader.js.map +1 -1
- package/dist/ContextBuilder.d.ts +202 -9
- package/dist/ContextBuilder.js +219 -36
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/DataMap.d.ts +158 -45
- package/dist/DataMap.js +167 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +277 -83
- package/dist/FunctionResult.js +444 -116
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +30 -5
- package/dist/Logger.js +77 -19
- package/dist/Logger.js.map +1 -1
- package/dist/POM/PromptObjectModel.d.ts +12 -1
- package/dist/POM/PromptObjectModel.js +25 -9
- package/dist/POM/PromptObjectModel.js.map +1 -1
- package/dist/ParameterSchema.d.ts +306 -0
- package/dist/ParameterSchema.js +251 -0
- package/dist/ParameterSchema.js.map +1 -0
- package/dist/PlatformContracts.d.ts +21 -0
- package/dist/PlatformContracts.generated.d.ts +109 -0
- package/dist/PlatformContracts.generated.js +8 -0
- package/dist/PlatformContracts.generated.js.map +1 -0
- package/dist/PlatformContracts.js +2 -0
- package/dist/PlatformContracts.js.map +1 -0
- package/dist/PomBuilder.d.ts +18 -0
- package/dist/PomBuilder.js +53 -3
- package/dist/PomBuilder.js.map +1 -1
- package/dist/PostPrompt.d.ts +110 -0
- package/dist/PostPrompt.js +204 -0
- package/dist/PostPrompt.js.map +1 -0
- package/dist/PromptManager.d.ts +22 -1
- package/dist/PromptManager.js +28 -1
- package/dist/PromptManager.js.map +1 -1
- package/dist/PublicFetch.d.ts +132 -0
- package/dist/PublicFetch.js +311 -0
- package/dist/PublicFetch.js.map +1 -0
- package/dist/RobotsTxt.d.ts +41 -0
- package/dist/RobotsTxt.js +152 -0
- package/dist/RobotsTxt.js.map +1 -0
- package/dist/SWMLHandler.js.map +1 -1
- package/dist/SWMLService.d.ts +158 -58
- package/dist/SWMLService.js +435 -127
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.d.ts +115 -2
- package/dist/SchemaUtils.js +444 -12
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SecurityUtils.d.ts +49 -9
- package/dist/SecurityUtils.js +153 -51
- package/dist/SecurityUtils.js.map +1 -1
- package/dist/ServerlessAdapter.d.ts +156 -7
- package/dist/ServerlessAdapter.js +399 -42
- package/dist/ServerlessAdapter.js.map +1 -1
- package/dist/SessionManager.d.ts +11 -2
- package/dist/SessionManager.js +50 -18
- package/dist/SessionManager.js.map +1 -1
- package/dist/SslConfig.d.ts +2 -1
- package/dist/SslConfig.js +4 -1
- package/dist/SslConfig.js.map +1 -1
- package/dist/SwaigActions.generated.d.ts +23 -0
- package/dist/SwaigActions.generated.js +8 -0
- package/dist/SwaigActions.generated.js.map +1 -0
- package/dist/SwaigContracts.d.ts +15 -0
- package/dist/SwaigContracts.generated.d.ts +264 -0
- package/dist/SwaigContracts.generated.js +12 -0
- package/dist/SwaigContracts.generated.js.map +1 -0
- package/dist/SwaigContracts.js +2 -0
- package/dist/SwaigContracts.js.map +1 -0
- package/dist/SwaigFunction.d.ts +110 -4
- package/dist/SwaigFunction.js +151 -19
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/SwmlBuilder.d.ts +68 -19
- package/dist/SwmlBuilder.js +74 -38
- package/dist/SwmlBuilder.js.map +1 -1
- package/dist/SwmlVerbMethods.generated.d.ts +41 -4
- package/dist/SwmlVerbMethods.generated.js +1 -1
- package/dist/TypeInference.d.ts +39 -3
- package/dist/TypeInference.js +256 -16
- package/dist/TypeInference.js.map +1 -1
- package/dist/WebService.d.ts +79 -11
- package/dist/WebService.js +320 -109
- package/dist/WebService.js.map +1 -1
- package/dist/WebhookMiddleware.d.ts +119 -0
- package/dist/WebhookMiddleware.js +271 -0
- package/dist/WebhookMiddleware.js.map +1 -0
- package/dist/WebhookValidator.d.ts +92 -0
- package/dist/WebhookValidator.js +409 -0
- package/dist/WebhookValidator.js.map +1 -0
- package/dist/agents/BedrockAgent.d.ts +162 -0
- package/dist/agents/BedrockAgent.js +323 -0
- package/dist/agents/BedrockAgent.js.map +1 -0
- package/dist/ai-chat/AIChatClient.d.ts +316 -0
- package/dist/ai-chat/AIChatClient.js +535 -0
- package/dist/ai-chat/AIChatClient.js.map +1 -0
- package/dist/ai-chat/ChatGateway.d.ts +408 -0
- package/dist/ai-chat/ChatGateway.js +747 -0
- package/dist/ai-chat/ChatGateway.js.map +1 -0
- package/dist/ai-chat/HandoffRouter.d.ts +282 -0
- package/dist/ai-chat/HandoffRouter.js +518 -0
- package/dist/ai-chat/HandoffRouter.js.map +1 -0
- package/dist/ai-chat/index.d.ts +12 -0
- package/dist/ai-chat/index.js +10 -0
- package/dist/ai-chat/index.js.map +1 -0
- package/dist/capabilities.d.ts +64 -0
- package/dist/capabilities.js +95 -0
- package/dist/capabilities.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +32 -6
- package/dist/cli/agent-loader.js +92 -33
- package/dist/cli/agent-loader.js.map +1 -1
- package/dist/cli/datamap-exec.d.ts +175 -0
- package/dist/cli/datamap-exec.js +1284 -0
- package/dist/cli/datamap-exec.js.map +1 -0
- package/dist/cli/function-args.d.ts +40 -0
- package/dist/cli/function-args.js +146 -0
- package/dist/cli/function-args.js.map +1 -0
- package/dist/cli/simulation.d.ts +99 -0
- package/dist/cli/simulation.js +490 -0
- package/dist/cli/simulation.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +12 -25
- package/dist/cli/swaig-test.js +935 -371
- package/dist/cli/swaig-test.js.map +1 -1
- package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
- package/dist/cli/tsdocs/agentsNote.js +92 -0
- package/dist/cli/tsdocs/agentsNote.js.map +1 -0
- package/dist/cli/tsdocs/api-index.json +1 -0
- package/dist/cli/tsdocs/api.d.ts +91 -0
- package/dist/cli/tsdocs/api.js +372 -0
- package/dist/cli/tsdocs/api.js.map +1 -0
- package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
- package/dist/cli/tsdocs/apiTypes.js +7 -0
- package/dist/cli/tsdocs/apiTypes.js.map +1 -0
- package/dist/cli/tsdocs/bin.d.ts +6 -0
- package/dist/cli/tsdocs/bin.js +23 -0
- package/dist/cli/tsdocs/bin.js.map +1 -0
- package/dist/cli/tsdocs/files.d.ts +108 -0
- package/dist/cli/tsdocs/files.js +287 -0
- package/dist/cli/tsdocs/files.js.map +1 -0
- package/dist/cli/tsdocs/index.d.ts +28 -0
- package/dist/cli/tsdocs/index.js +307 -0
- package/dist/cli/tsdocs/index.js.map +1 -0
- package/dist/cli/tsdocs/live.d.ts +41 -0
- package/dist/cli/tsdocs/live.js +202 -0
- package/dist/cli/tsdocs/live.js.map +1 -0
- package/dist/cli/tsdocs/locate.d.ts +51 -0
- package/dist/cli/tsdocs/locate.js +75 -0
- package/dist/cli/tsdocs/locate.js.map +1 -0
- package/dist/cli/tsdocs/render.d.ts +75 -0
- package/dist/cli/tsdocs/render.js +323 -0
- package/dist/cli/tsdocs/render.js.map +1 -0
- package/dist/cli/tsdocs/topics.d.ts +43 -0
- package/dist/cli/tsdocs/topics.js +916 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +47 -68
- package/dist/index.js +44 -73
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +229 -155
- package/dist/livewire/index.js +298 -195
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +65 -0
- package/dist/prefabs/CallSessionStore.d.ts +52 -0
- package/dist/prefabs/CallSessionStore.js +72 -0
- package/dist/prefabs/CallSessionStore.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +13 -1
- package/dist/prefabs/ConciergeAgent.js +36 -31
- package/dist/prefabs/ConciergeAgent.js.map +1 -1
- package/dist/prefabs/FAQBotAgent.d.ts +9 -1
- package/dist/prefabs/FAQBotAgent.js +113 -47
- package/dist/prefabs/FAQBotAgent.js.map +1 -1
- package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
- package/dist/prefabs/InfoGathererAgent.js +67 -58
- package/dist/prefabs/InfoGathererAgent.js.map +1 -1
- package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
- package/dist/prefabs/ReceptionistAgent.js +39 -31
- package/dist/prefabs/ReceptionistAgent.js.map +1 -1
- package/dist/prefabs/SurveyAgent.d.ts +22 -4
- package/dist/prefabs/SurveyAgent.js +84 -68
- package/dist/prefabs/SurveyAgent.js.map +1 -1
- package/dist/relay/Action.d.ts +44 -21
- package/dist/relay/Action.js +75 -17
- package/dist/relay/Action.js.map +1 -1
- package/dist/relay/Call.d.ts +312 -47
- package/dist/relay/Call.js +369 -18
- package/dist/relay/Call.js.map +1 -1
- package/dist/relay/Deferred.js.map +1 -1
- package/dist/relay/Message.d.ts +26 -5
- package/dist/relay/Message.js +36 -6
- package/dist/relay/Message.js.map +1 -1
- package/dist/relay/RelayClient.d.ts +44 -17
- package/dist/relay/RelayClient.js +175 -65
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayError.d.ts +14 -0
- package/dist/relay/RelayError.js +15 -0
- package/dist/relay/RelayError.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +96 -65
- package/dist/relay/RelayEvent.js +85 -56
- package/dist/relay/RelayEvent.js.map +1 -1
- package/dist/relay/closedSets.d.ts +111 -0
- package/dist/relay/closedSets.js +83 -0
- package/dist/relay/closedSets.js.map +1 -0
- package/dist/relay/index.d.ts +3 -1
- package/dist/relay/index.js +1 -0
- package/dist/relay/index.js.map +1 -1
- package/dist/relay/normalize.js.map +1 -1
- package/dist/relay/protocol.types.generated.d.ts +1195 -0
- package/dist/relay/protocol.types.generated.js +8 -0
- package/dist/relay/protocol.types.generated.js.map +1 -0
- package/dist/relay/types.d.ts +73 -42
- package/dist/rest/HttpClient.d.ts +36 -8
- package/dist/rest/HttpClient.js +233 -40
- package/dist/rest/HttpClient.js.map +1 -1
- package/dist/rest/RequestOptions.d.ts +110 -0
- package/dist/rest/RequestOptions.js +113 -0
- package/dist/rest/RequestOptions.js.map +1 -0
- package/dist/rest/RestError.d.ts +52 -6
- package/dist/rest/RestError.js +89 -5
- package/dist/rest/RestError.js.map +1 -1
- package/dist/rest/base/CrudResource.d.ts +16 -26
- package/dist/rest/base/CrudResource.js +19 -33
- package/dist/rest/base/CrudResource.js.map +1 -1
- package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
- package/dist/rest/base/CrudWithAddresses.js +2 -2
- package/dist/rest/base/CrudWithAddresses.js.map +1 -1
- package/dist/rest/base/FabricResource.d.ts +15 -0
- package/dist/rest/base/FabricResource.js +16 -0
- package/dist/rest/base/FabricResource.js.map +1 -0
- package/dist/rest/base/ReadResource.d.ts +62 -0
- package/dist/rest/base/ReadResource.js +69 -0
- package/dist/rest/base/ReadResource.js.map +1 -0
- package/dist/rest/callHandler.d.ts +5 -2
- package/dist/rest/callHandler.js +4 -1
- package/dist/rest/callHandler.js.map +1 -1
- package/dist/rest/index.d.ts +18 -77
- package/dist/rest/index.js +47 -120
- package/dist/rest/index.js.map +1 -1
- package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
- package/dist/rest/namespaces/_client_tree_generated.js +171 -0
- package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +3 -42
- package/dist/rest/namespaces/addresses.js +3 -50
- package/dist/rest/namespaces/addresses.js.map +1 -1
- package/dist/rest/namespaces/calling.d.ts +6 -378
- package/dist/rest/namespaces/calling.js +6 -473
- package/dist/rest/namespaces/calling.js.map +1 -1
- package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
- package/dist/rest/namespaces/calling.resources.generated.js +477 -0
- package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
- package/dist/rest/namespaces/calling.types.generated.js +8 -0
- package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +4 -18
- package/dist/rest/namespaces/chat.js +4 -21
- package/dist/rest/namespaces/chat.js.map +1 -1
- package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/chat.resources.generated.js +29 -0
- package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
- package/dist/rest/namespaces/chat.types.generated.js +8 -0
- package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +6 -62
- package/dist/rest/namespaces/datasphere.js +6 -72
- package/dist/rest/namespaces/datasphere.js.map +1 -1
- package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
- package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
- package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +11 -327
- package/dist/rest/namespaces/fabric.js +14 -439
- package/dist/rest/namespaces/fabric.js.map +1 -1
- package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
- package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
- package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
- package/dist/rest/namespaces/fabric.types.generated.js +8 -0
- package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/fax.resources.generated.js +14 -0
- package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/fax.types.generated.js +8 -0
- package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
- package/dist/rest/namespaces/imported-numbers.js +3 -21
- package/dist/rest/namespaces/imported-numbers.js.map +1 -1
- package/dist/rest/namespaces/logs.d.ts +10 -101
- package/dist/rest/namespaces/logs.js +10 -128
- package/dist/rest/namespaces/logs.js.map +1 -1
- package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/logs.resources.generated.js +17 -0
- package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/logs.types.generated.js +8 -0
- package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +3 -25
- package/dist/rest/namespaces/lookup.js +3 -27
- package/dist/rest/namespaces/lookup.js.map +1 -1
- package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/message.resources.generated.js +14 -0
- package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
- package/dist/rest/namespaces/message.types.generated.js +8 -0
- package/dist/rest/namespaces/message.types.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
- package/dist/rest/namespaces/messages.resources.generated.js +44 -0
- package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
- package/dist/rest/namespaces/messages.types.generated.js +8 -0
- package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +3 -42
- package/dist/rest/namespaces/mfa.js +3 -49
- package/dist/rest/namespaces/mfa.js.map +1 -1
- package/dist/rest/namespaces/number-groups.d.ts +3 -45
- package/dist/rest/namespaces/number-groups.js +3 -53
- package/dist/rest/namespaces/number-groups.js.map +1 -1
- package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
- package/dist/rest/namespaces/phone-numbers.js +8 -230
- package/dist/rest/namespaces/phone-numbers.js.map +1 -1
- package/dist/rest/namespaces/project.d.ts +6 -42
- package/dist/rest/namespaces/project.js +6 -51
- package/dist/rest/namespaces/project.js.map +1 -1
- package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
- package/dist/rest/namespaces/project.resources.generated.js +44 -0
- package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
- package/dist/rest/namespaces/project.types.generated.js +8 -0
- package/dist/rest/namespaces/project.types.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/projects.resources.generated.js +25 -0
- package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
- package/dist/rest/namespaces/projects.types.generated.js +8 -0
- package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +4 -18
- package/dist/rest/namespaces/pubsub.js +4 -21
- package/dist/rest/namespaces/pubsub.js.map +1 -1
- package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
- package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
- package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +3 -38
- package/dist/rest/namespaces/queues.js +3 -44
- package/dist/rest/namespaces/queues.js.map +1 -1
- package/dist/rest/namespaces/recordings.d.ts +3 -34
- package/dist/rest/namespaces/recordings.js +3 -40
- package/dist/rest/namespaces/recordings.js.map +1 -1
- package/dist/rest/namespaces/registry.d.ts +6 -137
- package/dist/rest/namespaces/registry.js +6 -173
- package/dist/rest/namespaces/registry.js.map +1 -1
- package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +3 -35
- package/dist/rest/namespaces/short-codes.js +3 -41
- package/dist/rest/namespaces/short-codes.js.map +1 -1
- package/dist/rest/namespaces/sip-profile.d.ts +3 -24
- package/dist/rest/namespaces/sip-profile.js +3 -29
- package/dist/rest/namespaces/sip-profile.js.map +1 -1
- package/dist/rest/namespaces/verified-callers.d.ts +3 -29
- package/dist/rest/namespaces/verified-callers.js +3 -34
- package/dist/rest/namespaces/verified-callers.js.map +1 -1
- package/dist/rest/namespaces/video.d.ts +10 -227
- package/dist/rest/namespaces/video.js +10 -288
- package/dist/rest/namespaces/video.js.map +1 -1
- package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
- package/dist/rest/namespaces/video.resources.generated.js +171 -0
- package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
- package/dist/rest/namespaces/video.types.generated.js +8 -0
- package/dist/rest/namespaces/video.types.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/voice.resources.generated.js +17 -0
- package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
- package/dist/rest/namespaces/voice.types.generated.js +8 -0
- package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
- package/dist/rest/pagination.d.ts +5 -1
- package/dist/rest/pagination.js +40 -20
- package/dist/rest/pagination.js.map +1 -1
- package/dist/rest/types.d.ts +21 -3
- package/dist/schema.json +299 -98
- package/dist/skills/SkillBase.d.ts +97 -20
- package/dist/skills/SkillBase.js +100 -17
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/skills/SkillManager.d.ts +66 -13
- package/dist/skills/SkillManager.js +101 -20
- package/dist/skills/SkillManager.js.map +1 -1
- package/dist/skills/SkillName.d.ts +44 -0
- package/dist/skills/SkillName.js +2 -0
- package/dist/skills/SkillName.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +22 -11
- package/dist/skills/SkillRegistry.js +47 -17
- package/dist/skills/SkillRegistry.js.map +1 -1
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
- package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
- package/dist/skills/builtin/ask_claude.d.ts +14 -4
- package/dist/skills/builtin/ask_claude.js +36 -14
- package/dist/skills/builtin/ask_claude.js.map +1 -1
- package/dist/skills/builtin/claude_skills.d.ts +3 -1
- package/dist/skills/builtin/claude_skills.js +19 -15
- package/dist/skills/builtin/claude_skills.js.map +1 -1
- package/dist/skills/builtin/custom_skills.d.ts +10 -3
- package/dist/skills/builtin/custom_skills.js +26 -9
- package/dist/skills/builtin/custom_skills.js.map +1 -1
- package/dist/skills/builtin/datasphere.d.ts +5 -3
- package/dist/skills/builtin/datasphere.js +21 -22
- package/dist/skills/builtin/datasphere.js.map +1 -1
- package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
- package/dist/skills/builtin/datasphere_serverless.js +17 -6
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
- package/dist/skills/builtin/datetime.d.ts +3 -1
- package/dist/skills/builtin/datetime.js +11 -7
- package/dist/skills/builtin/datetime.js.map +1 -1
- package/dist/skills/builtin/google_maps.d.ts +29 -14
- package/dist/skills/builtin/google_maps.js +89 -269
- package/dist/skills/builtin/google_maps.js.map +1 -1
- package/dist/skills/builtin/index.d.ts +8 -6
- package/dist/skills/builtin/index.js +8 -6
- package/dist/skills/builtin/index.js.map +1 -1
- package/dist/skills/builtin/info_gatherer.d.ts +4 -2
- package/dist/skills/builtin/info_gatherer.js +20 -12
- package/dist/skills/builtin/info_gatherer.js.map +1 -1
- package/dist/skills/builtin/joke.d.ts +16 -6
- package/dist/skills/builtin/joke.js +54 -37
- package/dist/skills/builtin/joke.js.map +1 -1
- package/dist/skills/builtin/math.d.ts +3 -1
- package/dist/skills/builtin/math.js +14 -9
- package/dist/skills/builtin/math.js.map +1 -1
- package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
- package/dist/skills/builtin/mcp_gateway.js +77 -46
- package/dist/skills/builtin/mcp_gateway.js.map +1 -1
- package/dist/skills/builtin/native_vector_search.d.ts +19 -5
- package/dist/skills/builtin/native_vector_search.js +179 -61
- package/dist/skills/builtin/native_vector_search.js.map +1 -1
- package/dist/skills/builtin/play_background_file.d.ts +21 -15
- package/dist/skills/builtin/play_background_file.js +43 -122
- package/dist/skills/builtin/play_background_file.js.map +1 -1
- package/dist/skills/builtin/spider.d.ts +42 -4
- package/dist/skills/builtin/spider.js +277 -104
- package/dist/skills/builtin/spider.js.map +1 -1
- package/dist/skills/builtin/swml_transfer.d.ts +14 -3
- package/dist/skills/builtin/swml_transfer.js +45 -24
- package/dist/skills/builtin/swml_transfer.js.map +1 -1
- package/dist/skills/builtin/weather_api.d.ts +24 -13
- package/dist/skills/builtin/weather_api.js +38 -30
- package/dist/skills/builtin/weather_api.js.map +1 -1
- package/dist/skills/builtin/web_search.d.ts +48 -10
- package/dist/skills/builtin/web_search.js +294 -100
- package/dist/skills/builtin/web_search.js.map +1 -1
- package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
- package/dist/skills/builtin/wikipedia_search.js +14 -13
- package/dist/skills/builtin/wikipedia_search.js.map +1 -1
- package/dist/skills/index.d.ts +3 -2
- package/dist/skills/index.js +1 -1
- package/dist/skills/index.js.map +1 -1
- package/dist/swml_verbs_generated.d.ts +2824 -0
- package/dist/swml_verbs_generated.js +12 -0
- package/dist/swml_verbs_generated.js.map +1 -0
- package/dist/types.d.ts +59 -6
- package/dist/web.d.ts +27 -0
- package/dist/web.js +20 -0
- package/dist/web.js.map +1 -0
- package/docs/agent-guide.md +1034 -0
- package/docs/ai_chat.md +560 -0
- package/docs/api-reference.md +3534 -0
- package/docs/architecture.md +846 -0
- package/docs/bedrock_agent.md +411 -0
- package/docs/cli-guide.md +403 -0
- package/docs/cloud_functions_guide.md +399 -0
- package/docs/configuration.md +548 -0
- package/docs/contexts-guide.md +884 -0
- package/docs/datamap-guide.md +1160 -0
- package/docs/developer_pain_points.md +548 -0
- package/docs/llm_parameters.md +298 -0
- package/docs/mcp_gateway_reference.md +354 -0
- package/docs/mcp_integration.md +162 -0
- package/docs/pgi_agent_guide.md +1820 -0
- package/docs/prefabs-guide.md +815 -0
- package/docs/programmatically_governed_inference.md +301 -0
- package/docs/sdk_features.md +501 -0
- package/docs/security.md +559 -0
- package/docs/serverless-guide.md +520 -0
- package/docs/skills-guide.md +1223 -0
- package/docs/skills-system.md +405 -0
- package/docs/skills_parameter_schema.md +417 -0
- package/docs/swaig-reference.md +1938 -0
- package/docs/swml_service_guide.md +573 -0
- package/docs/third_party_skills.md +410 -0
- package/docs/web_service.md +666 -0
- package/examples/README.md +202 -0
- package/examples/advanced-datamap.ts +108 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +95 -0
- package/examples/call-flow.ts +65 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +51 -0
- package/examples/datasphere-multi-instance.ts +66 -0
- package/examples/datasphere-serverless-env.ts +87 -0
- package/examples/datasphere-webhook-env.ts +65 -0
- package/examples/datasphere.ts +56 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +95 -0
- package/examples/gather-per-question-functions-demo.ts +139 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +75 -0
- package/examples/mcp-agent.ts +89 -0
- package/examples/mcp-gateway.ts +81 -0
- package/examples/multi-agent.ts +80 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pgi/case-domain.ts +114 -0
- package/examples/pgi/serve.ts +16 -0
- package/examples/pgi/support-agent.ts +265 -0
- package/examples/pom-prompt.ts +70 -0
- package/examples/prefab-concierge.ts +42 -0
- package/examples/prefab-faq.ts +58 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +69 -0
- package/examples/quickstart-agent.ts +29 -0
- package/examples/quickstart-relay.ts +25 -0
- package/examples/quickstart-rest.ts +25 -0
- package/examples/record-call.ts +65 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +93 -0
- package/examples/serverless-lambda.ts +43 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +41 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +193 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/swmlservice_ai_sidecar.ts +104 -0
- package/examples/swmlservice_swaig_standalone.ts +79 -0
- package/examples/tap.ts +67 -0
- package/examples/typed-tools.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +75 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +164 -0
- package/livewire/docs/migration-guide.md +251 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +196 -0
- package/livewire/examples/livewire-multi-tool.ts +121 -0
- package/package.json +85 -13
- package/relay/README.md +101 -0
- package/relay/docs/call-methods.md +622 -0
- package/relay/docs/client-reference.md +281 -0
- package/relay/docs/events.md +193 -0
- package/relay/docs/getting-started.md +221 -0
- package/relay/docs/guide.md +386 -0
- package/relay/docs/messaging.md +246 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +74 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +141 -0
- package/rest/docs/calling.md +313 -0
- package/rest/docs/client-reference.md +149 -0
- package/rest/docs/fabric.md +192 -0
- package/rest/docs/getting-started.md +138 -0
- package/rest/docs/guide.md +421 -0
- package/rest/docs/namespaces.md +367 -0
- package/rest/docs/phone-binding.md +116 -0
- package/rest/examples/rest-10dlc-registration.ts +177 -0
- package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
- package/rest/examples/rest-calling-play-and-record.ts +98 -0
- package/rest/examples/rest-client.ts +59 -0
- package/rest/examples/rest-datasphere-search.ts +81 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
- package/rest/examples/rest-manage-resources.ts +64 -0
- package/rest/examples/rest-phone-number-management.ts +200 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/tutorial/fred/fred.ts +218 -0
- package/tutorial/fred/tutorial/01-introduction.md +141 -0
- package/tutorial/fred/tutorial/02-setup.md +304 -0
- package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
- package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
- package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
- package/tutorial/fred/tutorial/06-running-testing.md +642 -0
- package/tutorial/fred/tutorial/README.md +56 -0
- package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
- package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
- package/tutorial/full-guardrails-agent/handlers.ts +436 -0
- package/tutorial/full-guardrails-agent/penny.ts +305 -0
- package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
- package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
- package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
- package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
- package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
- package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
- package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
- package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
- package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
- package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
- package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
- package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
- package/tutorial/full-guardrails-agent/workflow.ts +219 -0
- package/tutorial/multi_agents/README.md +175 -0
- package/tutorial/multi_agents/advanced_agent.ts +395 -0
- package/tutorial/multi_agents/extending_agents.ts +641 -0
- package/tutorial/multi_agents/knowledge.ts +59 -0
- package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
- package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
- package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
- package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
- package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
- package/tutorial/multi_agents/pc_builder.ts +529 -0
- package/tutorial/multi_agents/sales_agent.ts +88 -0
- package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
- package/tutorial/multi_agents/sales_knowledge.md +139 -0
- package/tutorial/multi_agents/support_knowledge.md +256 -0
- package/dist/cli/mock-data.d.ts +0 -37
- package/dist/cli/mock-data.js +0 -80
- package/dist/cli/mock-data.js.map +0 -1
- package/dist/generateVerbTypes.d.ts +0 -11
- package/dist/generateVerbTypes.js +0 -265
- package/dist/generateVerbTypes.js.map +0 -1
- package/dist/rest/namespaces/compat.d.ts +0 -585
- package/dist/rest/namespaces/compat.js +0 -735
- package/dist/rest/namespaces/compat.js.map +0 -1
|
@@ -0,0 +1,1223 @@
|
|
|
1
|
+
# Skills System Guide
|
|
2
|
+
|
|
3
|
+
Skills add a capability to an agent in one call: SWAIG tools, prompt sections, speech recognition hints and global data, packaged together. This guide covers adding skills to an agent, the built-in skills and their parameters, and writing your own skill.
|
|
4
|
+
|
|
5
|
+
The examples on this page assume this shared context:
|
|
6
|
+
|
|
7
|
+
<!-- snippet-setup -->
|
|
8
|
+
```ts
|
|
9
|
+
export {}; // treat each example as a module so top-level `await` is allowed
|
|
10
|
+
declare global {
|
|
11
|
+
// Shared context the fragments on this page assume.
|
|
12
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
13
|
+
const SkillBase: typeof import('@signalwire/sdk').SkillBase;
|
|
14
|
+
const SkillRegistry: typeof import('@signalwire/sdk').SkillRegistry;
|
|
15
|
+
const registerBuiltinSkills: typeof import('@signalwire/sdk').registerBuiltinSkills;
|
|
16
|
+
const registry: import('@signalwire/sdk').SkillRegistry;
|
|
17
|
+
// Illustrative custom skill class referenced by the registry examples.
|
|
18
|
+
const MyCustomSkill: typeof import('@signalwire/sdk').SkillBase;
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Table of Contents
|
|
25
|
+
|
|
26
|
+
1. [Overview](#overview)
|
|
27
|
+
2. [Using Skills](#using-skills)
|
|
28
|
+
3. [Built-in Skills](#built-in-skills)
|
|
29
|
+
4. [Skill Configuration](#skill-configuration)
|
|
30
|
+
5. [Skill Registry](#skill-registry)
|
|
31
|
+
6. [Creating Custom Skills](#creating-custom-skills)
|
|
32
|
+
7. [Skill Lifecycle](#skill-lifecycle)
|
|
33
|
+
8. [Environment Validation](#environment-validation)
|
|
34
|
+
9. [Environment Variables Reference](#environment-variables-reference)
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Overview
|
|
39
|
+
|
|
40
|
+
A skill is a class that extends `SkillBase`. When you add one to an agent, the agent registers everything the skill contributes. Three classes make up the system:
|
|
41
|
+
|
|
42
|
+
| Class | Role | Location |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `SkillBase` | Abstract base class that every skill extends | `src/skills/SkillBase.ts` |
|
|
45
|
+
| `SkillManager` | Loads, validates and removes the skills attached to one agent | `src/skills/SkillManager.ts` |
|
|
46
|
+
| `SkillRegistry` | Process-wide singleton that maps skill names to skill classes | `src/skills/SkillRegistry.ts` |
|
|
47
|
+
|
|
48
|
+
A skill can contribute five kinds of things:
|
|
49
|
+
|
|
50
|
+
- **Tools**: SWAIG function definitions (name, description, parameters, handler) registered on the agent.
|
|
51
|
+
- **Prompt sections**: text added to the agent's prompt that tells the model when to use the tools.
|
|
52
|
+
- **Hints**: speech recognition hints for words the skill's callers are likely to say.
|
|
53
|
+
- **Global data**: keys merged into the agent's global data.
|
|
54
|
+
- **Metadata**: the skill's name, version, required environment variables and packages, and parameter schema.
|
|
55
|
+
|
|
56
|
+
For how the classes fit together, see the [Skills System Reference](skills-system.md).
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Using Skills
|
|
61
|
+
|
|
62
|
+
### `agent.addSkill()`
|
|
63
|
+
|
|
64
|
+
`addSkill()` takes a skill instance and returns a promise, because a skill's `setup()` can do asynchronous work. This example adds two built-in skills:
|
|
65
|
+
|
|
66
|
+
<!-- snippet: no-run the `web_search` skill needs Google credentials at setup, so the add fails without them -->
|
|
67
|
+
```typescript
|
|
68
|
+
import { AgentBase, DateTimeSkill, WebSearchSkill } from '@signalwire/sdk';
|
|
69
|
+
|
|
70
|
+
const agent = new AgentBase({ name: 'my-agent' });
|
|
71
|
+
|
|
72
|
+
await agent.addSkill(new DateTimeSkill());
|
|
73
|
+
await agent.addSkill(new WebSearchSkill({ num_results: 3 }));
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
When you call `addSkill()`, the agent's `SkillManager` checks the skill, then the agent registers what it contributes:
|
|
77
|
+
|
|
78
|
+
1. A skill that doesn't support multiple instances and is already loaded is refused with an error.
|
|
79
|
+
2. Every variable in the skill's `REQUIRED_ENV_VARS` must be set. A missing one rejects the call with an error, and the skill isn't added.
|
|
80
|
+
3. The skill's parameter schema must be a non-empty object, and every package in `REQUIRED_PACKAGES` must import.
|
|
81
|
+
4. `setup()` runs. If it returns `false`, the call rejects with `Failed to setup skill '<name>'`, and the skill isn't added.
|
|
82
|
+
5. The agent registers the tools from `getTools()` and `getDataMapTools()`, the prompt sections from `getPromptSections()`, the hints from `getHints()` and the global data from `getGlobalData()`.
|
|
83
|
+
|
|
84
|
+
Because a failed check rejects the promise, wrap `addSkill()` in `try`/`catch` when the skill's configuration comes from outside your code.
|
|
85
|
+
|
|
86
|
+
### `agent.addSkillByName()`
|
|
87
|
+
|
|
88
|
+
`addSkillByName()` looks the name up in the global `SkillRegistry`, constructs the skill with the parameters you pass, and adds it. The registry starts empty, so call `registerBuiltinSkills()` once before you add a built-in skill by name:
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
import { AgentBase, registerBuiltinSkills } from '@signalwire/sdk';
|
|
92
|
+
|
|
93
|
+
registerBuiltinSkills();
|
|
94
|
+
|
|
95
|
+
const agent = new AgentBase({ name: 'my-agent' });
|
|
96
|
+
await agent.addSkillByName('datetime');
|
|
97
|
+
await agent.addSkillByName('math');
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Without `registerBuiltinSkills()`, the call rejects with `Failed to load skill 'datetime': skill not found in registry`. The name parameter accepts any string, and an editor suggests the built-in names. A misspelled name still compiles, and fails when the call runs.
|
|
101
|
+
|
|
102
|
+
### `agent.removeSkill()` and `agent.removeSkillByName()`
|
|
103
|
+
|
|
104
|
+
`removeSkill()` takes a skill's instance key or its `instanceId`, calls the skill's `cleanup()`, and removes it. It resolves to `true` when it found the skill:
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
const removed = await agent.removeSkill('datetime');
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
A single-instance skill's instance key is its skill name, as in the example. `removeSkillByName('datetime')` removes the first loaded skill with that name.
|
|
111
|
+
|
|
112
|
+
### `agent.listSkills()`
|
|
113
|
+
|
|
114
|
+
`listSkills()` returns the name, `instanceId` and initialization state of every loaded skill:
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
for (const skill of agent.listSkills()) {
|
|
118
|
+
console.log(`${skill.name} (${skill.instanceId}) initialized: ${skill.initialized}`);
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
An `instanceId` combines the skill name, a timestamp and random bytes, for example `datetime-muluil2c-65ea4f3c`.
|
|
123
|
+
|
|
124
|
+
### `agent.hasSkill()`
|
|
125
|
+
|
|
126
|
+
`hasSkill()` reports whether any loaded skill has the given name:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
if (agent.hasSkill('web_search')) {
|
|
130
|
+
console.log('Web search is available');
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Built-in Skills
|
|
137
|
+
|
|
138
|
+
The SDK ships the skills in the following table, in `src/skills/builtin/`. `custom_skills` and `ask_claude` exist only in the TypeScript SDK. The "Needs" column lists what must be in place before the skill loads.
|
|
139
|
+
|
|
140
|
+
| Skill name | Class | Tools (default names) | Needs |
|
|
141
|
+
|---|---|---|---|
|
|
142
|
+
| `datetime` | `DateTimeSkill` | `get_current_time`, `get_current_date` | Nothing |
|
|
143
|
+
| `math` | `MathSkill` | `calculate` | Nothing |
|
|
144
|
+
| `joke` | `JokeSkill` | `get_joke` | Nothing |
|
|
145
|
+
| `weather_api` | `WeatherApiSkill` | `get_weather` | An OpenWeatherMap key in `api_key` or `WEATHER_API_KEY` |
|
|
146
|
+
| `play_background_file` | `PlayBackgroundFileSkill` | `play_background_file` | A non-empty `files` list |
|
|
147
|
+
| `swml_transfer` | `SwmlTransferSkill` | `transfer_call`, plus `list_transfer_destinations` with `patterns` | `transfers` or `patterns` |
|
|
148
|
+
| `api_ninjas_trivia` | `ApiNinjasTriviaSkill` | `get_trivia` | An API Ninjas key, checked when the tool runs |
|
|
149
|
+
| `info_gatherer` | `InfoGathererSkill` | `start_questions`, `submit_answer` | A non-empty `questions` list |
|
|
150
|
+
| `custom_skills` | `CustomSkillsSkill` | One per entry in `tools` | `SWML_ALLOW_CUSTOM_HANDLER_CODE=true` for the handlers to run |
|
|
151
|
+
| `web_search` | `WebSearchSkill` | `web_search` | Google Custom Search credentials, and the `cheerio` package |
|
|
152
|
+
| `wikipedia_search` | `WikipediaSearchSkill` | `search_wiki` | Nothing |
|
|
153
|
+
| `google_maps` | `GoogleMapsSkill` | `lookup_address`, `compute_route` | A Google Maps key in `api_key` or `GOOGLE_MAPS_API_KEY` |
|
|
154
|
+
| `datasphere` | `DataSphereSkill` | `search_knowledge` | SignalWire credentials and a `document_id` |
|
|
155
|
+
| `datasphere_serverless` | `DataSphereServerlessSkill` | `search_knowledge` (DataMap) | `space_name`, `project_id`, `token` and `document_id` |
|
|
156
|
+
| `native_vector_search` | `NativeVectorSearchSkill` | `search_knowledge` | `documents` or a reachable `remote_url` |
|
|
157
|
+
| `spider` | `SpiderSkill` | `scrape_url`, `crawl_site`, `extract_structured_data` | The `cheerio` package |
|
|
158
|
+
| `claude_skills` | `ClaudeSkillsSkill` | One per SKILL.md file, prefixed `claude_` | A `skills_path` directory |
|
|
159
|
+
| `ask_claude` | `AskClaudeSkill` | `ask_claude` | An Anthropic key in `api_key` or `ANTHROPIC_API_KEY` |
|
|
160
|
+
| `mcp_gateway` | `McpGatewaySkill` | One per gateway tool, prefixed `mcp_`, plus `_mcp_gateway_hangup` | A reachable `gateway_url` and credentials |
|
|
161
|
+
|
|
162
|
+
Every skill also accepts the two base parameters `swaig_fields` and `skip_prompt`, described in [Skill Configuration](#skill-configuration). The parameter tables in the following sections leave those two out. They list each parameter as the skill's `getParameterSchema()` declares it; where the code behaves differently, the text says so.
|
|
163
|
+
|
|
164
|
+
A tool's result is text the model reads, not speech. The model decides what to say to the caller.
|
|
165
|
+
|
|
166
|
+
### datetime
|
|
167
|
+
|
|
168
|
+
`DateTimeSkill` returns the current time or date in an IANA time zone, using `Intl.DateTimeFormat`. Both tools take an optional `timezone` argument and use UTC when it's absent. An unknown time zone returns a message that asks for a valid IANA identifier. The skill has no parameters of its own. This example adds it:
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
import { DateTimeSkill } from '@signalwire/sdk';
|
|
172
|
+
await agent.addSkill(new DateTimeSkill());
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`get_current_time` returns text such as `The current time is 10:55:42 PM UTC`, and `get_current_date` returns text such as `Today's date is Monday, September 28, 2026`.
|
|
176
|
+
|
|
177
|
+
### math
|
|
178
|
+
|
|
179
|
+
`MathSkill` evaluates an arithmetic expression with the `calculate` tool. It first checks that the expression contains only digits, the operators `+ - * / ^ %`, parentheses, decimal points and spaces. It then evaluates it as a JavaScript expression, with `^` as exponentiation. A result that isn't a finite number returns an error message. The skill has no parameters of its own. This example adds it:
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
import { MathSkill } from '@signalwire/sdk';
|
|
183
|
+
await agent.addSkill(new MathSkill());
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### joke
|
|
187
|
+
|
|
188
|
+
`JokeSkill` serves jokes from a small collection built into the SDK, so it needs no API key. The tool's required `type` argument is `jokes` or `dadjokes`. The result is an instruction to the model, for example `Tell this joke to the user: What did the ocean say to the beach? ... Nothing, it just waved.`
|
|
189
|
+
|
|
190
|
+
| Parameter | Type | Default | Required | Description |
|
|
191
|
+
|---|---|---|---|---|
|
|
192
|
+
| `tool_name` | string | `"get_joke"` | No | Name of the joke tool |
|
|
193
|
+
|
|
194
|
+
This example adds the skill with its default tool name:
|
|
195
|
+
|
|
196
|
+
```typescript
|
|
197
|
+
import { JokeSkill } from '@signalwire/sdk';
|
|
198
|
+
await agent.addSkill(new JokeSkill());
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### weather_api
|
|
202
|
+
|
|
203
|
+
`WeatherApiSkill` gets current conditions from the OpenWeatherMap current-weather API (`api.openweathermap.org`). A WeatherAPI.com key doesn't work with it. The tool takes a `location` (a city, optionally with a country code, such as `Paris,FR`) and returns the conditions, temperature, humidity, wind and pressure. It's a webhook tool that runs in your agent, not a DataMap tool.
|
|
204
|
+
|
|
205
|
+
The key comes from `api_key`, or from `WEATHER_API_KEY` when `api_key` isn't set. Setup fails when neither is set.
|
|
206
|
+
|
|
207
|
+
| Parameter | Type | Default | Required | Description |
|
|
208
|
+
|---|---|---|---|---|
|
|
209
|
+
| `api_key` | string | none | Yes | OpenWeatherMap API key. Falls back to `WEATHER_API_KEY`. |
|
|
210
|
+
| `tool_name` | string | `"get_weather"` | No | Name of the weather tool |
|
|
211
|
+
| `units` | string | `"fahrenheit"` | No | `metric`, `imperial` or `standard` (Kelvin). `celsius` means `metric`, and `fahrenheit` means `imperial`. |
|
|
212
|
+
|
|
213
|
+
When you leave `units` out, the skill reports Fahrenheit. This example reports Celsius:
|
|
214
|
+
|
|
215
|
+
<!-- snippet: no-run needs an OpenWeatherMap key in WEATHER_API_KEY to load -->
|
|
216
|
+
```typescript
|
|
217
|
+
import { WeatherApiSkill } from '@signalwire/sdk';
|
|
218
|
+
await agent.addSkill(new WeatherApiSkill({ units: 'metric' }));
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### play_background_file
|
|
222
|
+
|
|
223
|
+
`PlayBackgroundFileSkill` plays and stops pre-configured audio or video files in the background of a call. It registers one tool whose required `action` argument is `start_<key>` for each file, or `stop`. The tool's result carries a `play_background_file` or `stop_background_file` action, and tells the model what to say about it. Setup fails when `files` has no valid entry.
|
|
224
|
+
|
|
225
|
+
| Parameter | Type | Default | Required | Description |
|
|
226
|
+
|---|---|---|---|---|
|
|
227
|
+
| `tool_name` | string | `"play_background_file"` | No | Name of the tool. A different name lets you add a second instance. |
|
|
228
|
+
| `files` | array | none | Yes | Entries with `key`, `description` and `url` (all required), and `wait` (boolean, default `false`) |
|
|
229
|
+
|
|
230
|
+
This example configures one hold-music file:
|
|
231
|
+
|
|
232
|
+
```typescript
|
|
233
|
+
import { PlayBackgroundFileSkill } from '@signalwire/sdk';
|
|
234
|
+
await agent.addSkill(
|
|
235
|
+
new PlayBackgroundFileSkill({
|
|
236
|
+
files: [{ key: 'hold', description: 'Hold music', url: 'https://example.com/hold-music.mp3' }],
|
|
237
|
+
}),
|
|
238
|
+
);
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### swml_transfer
|
|
242
|
+
|
|
243
|
+
`SwmlTransferSkill` transfers the call to a destination the model picks. It accepts two configuration shapes, and setup fails when neither is present:
|
|
244
|
+
|
|
245
|
+
- `transfers` maps a pattern to a destination. A key such as `/sales/i` is a regular expression, case-insensitive with the `i` flag. Each value has a `url` (a SWML transfer) or an `address` (a connect), but not both.
|
|
246
|
+
- `patterns` is a list of named destinations: `{ name, destination, description?, message?, returnMessage?, postProcess?, final?, fromAddr? }`. A destination that starts with `http://` or `https://` becomes a SWML transfer, and anything else becomes a connect.
|
|
247
|
+
|
|
248
|
+
The tool takes the destination in the argument named by `parameter_name`. It tries the `transfers` patterns first, then the `patterns` names, which must match exactly, ignoring case. With `patterns`, the skill also registers `list_transfer_destinations`.
|
|
249
|
+
|
|
250
|
+
| Parameter | Type | Default | Required | Description |
|
|
251
|
+
|---|---|---|---|---|
|
|
252
|
+
| `tool_name` | string | `"transfer_call"` | No | Name of the transfer tool |
|
|
253
|
+
| `transfers` | object | none | Yes | Pattern-to-destination map. Each value takes `url` or `address`, and optional `message`, `return_message`, `post_process`, `final` and `from_addr`. |
|
|
254
|
+
| `patterns` | array | none | No | Named destinations, as described earlier |
|
|
255
|
+
| `allow_arbitrary` | boolean | none | No | Lets the model transfer to a destination that matches nothing |
|
|
256
|
+
| `description` | string | `"Transfer call based on pattern matching"` | No | Description of the transfer tool |
|
|
257
|
+
| `parameter_name` | string | `"transfer_type"` | No | Name of the tool's destination argument |
|
|
258
|
+
| `parameter_description` | string | `"The type of transfer to perform"` | No | Description of that argument |
|
|
259
|
+
| `default_message` | string | `"Please specify a valid transfer type."` | No | Result when the destination matches nothing |
|
|
260
|
+
| `default_post_process` | boolean | `false` | No | Whether the no-match result is post-processed |
|
|
261
|
+
| `required_fields` | object | `{}` | No | Extra arguments the model must collect (name to description). They're saved under `call_data` in global data. |
|
|
262
|
+
|
|
263
|
+
The schema marks `transfers` required, but `patterns` alone also works. When you leave `allow_arbitrary` unset, it's on only if both `transfers` and `patterns` are empty. With it on, the model can transfer the caller to any number or SIP address it chooses, so leave it off unless you want that.
|
|
264
|
+
|
|
265
|
+
This example routes two departments by name:
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
import { SwmlTransferSkill } from '@signalwire/sdk';
|
|
269
|
+
await agent.addSkill(
|
|
270
|
+
new SwmlTransferSkill({
|
|
271
|
+
patterns: [
|
|
272
|
+
{ name: 'billing', destination: '+15551234567', description: 'Billing department' },
|
|
273
|
+
{ name: 'support', destination: 'sip:support@example.com', description: 'Technical support' },
|
|
274
|
+
],
|
|
275
|
+
}),
|
|
276
|
+
);
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### api_ninjas_trivia
|
|
280
|
+
|
|
281
|
+
`ApiNinjasTriviaSkill` fetches a trivia question from the API Ninjas trivia API. The key comes from `api_key` or `API_NINJAS_KEY`, and it's checked when the tool runs, not when the skill loads. By default the result gives the model the answer with an instruction not to reveal it until the caller tries.
|
|
282
|
+
|
|
283
|
+
| Parameter | Type | Default | Required | Description |
|
|
284
|
+
|---|---|---|---|---|
|
|
285
|
+
| `tool_name` | string | `"get_trivia"` | No | Name of the trivia tool |
|
|
286
|
+
| `api_key` | string | none | Yes | API Ninjas key. Falls back to `API_NINJAS_KEY`. |
|
|
287
|
+
| `categories` | array | All 14 categories | No | Categories the tool offers, from `artliterature`, `language`, `sciencenature`, `general`, `fooddrink`, `peopleplaces`, `geography`, `historyholidays`, `entertainment`, `toysgames`, `music`, `mathematics`, `religionmythology` and `sportsleisure` |
|
|
288
|
+
| `default_category` | string | none | No | Category used when the model sends none |
|
|
289
|
+
| `reveal_answer` | boolean | `false` | No | Include the answer in the result as plain text |
|
|
290
|
+
|
|
291
|
+
This example limits the tool to two categories:
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
import { ApiNinjasTriviaSkill } from '@signalwire/sdk';
|
|
295
|
+
await agent.addSkill(
|
|
296
|
+
new ApiNinjasTriviaSkill({ categories: ['sciencenature', 'geography'] }),
|
|
297
|
+
);
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
### info_gatherer
|
|
301
|
+
|
|
302
|
+
`InfoGathererSkill` asks a list of questions in order and stores the answers. `start_questions` returns the first question, and each `submit_answer` call stores an answer and returns the next question. The state lives in global data under `skill:<prefix>`, or `skill:info_gatherer` without a prefix, as `{ questions, question_index, answers }`. After the last answer, the result returns `completion_message` and turns both tools off.
|
|
303
|
+
|
|
304
|
+
A question with `confirm: true` refuses an answer until the model calls `submit_answer` again with `confirmed_by_user: true`. The result instructs the model to read the answer back first. Setup fails when `questions` is missing, empty, or has an entry without `key_name` or `question_text`.
|
|
305
|
+
|
|
306
|
+
| Parameter | Type | Default | Required | Description |
|
|
307
|
+
|---|---|---|---|---|
|
|
308
|
+
| `questions` | array | none | Yes | Entries with `key_name`, `question_text`, and optional `confirm` (boolean) and `prompt_add` (extra instruction text) |
|
|
309
|
+
| `prefix` | string | none | No | Names the tools `<prefix>_start_questions` and `<prefix>_submit_answer`, and the state key `skill:<prefix>`. Use it to add a second instance. |
|
|
310
|
+
| `completion_message` | string | `"Thank you! All questions have been answered. ..."` | No | Result returned after the last answer |
|
|
311
|
+
|
|
312
|
+
This example asks three questions and confirms the email address:
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
import { InfoGathererSkill } from '@signalwire/sdk';
|
|
316
|
+
await agent.addSkill(
|
|
317
|
+
new InfoGathererSkill({
|
|
318
|
+
questions: [
|
|
319
|
+
{ key_name: 'full_name', question_text: 'What is your full name?' },
|
|
320
|
+
{ key_name: 'email', question_text: 'What is your email address?', confirm: true },
|
|
321
|
+
{ key_name: 'reason', question_text: 'How can I help you today?' },
|
|
322
|
+
],
|
|
323
|
+
}),
|
|
324
|
+
);
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
### custom_skills
|
|
328
|
+
|
|
329
|
+
`CustomSkillsSkill` registers tools from configuration, with each handler written as a JavaScript function body in `handler_code`. The body receives `args`, `rawData` and `FunctionResult`, and returns a `FunctionResult`, a string or a plain object.
|
|
330
|
+
|
|
331
|
+
The skill compiles each body with the `Function` constructor, only when `SWML_ALLOW_CUSTOM_HANDLER_CODE` is `true`. The compiled code runs in your Node.js process with its full permissions: it isn't sandboxed. Without the variable, the tools are still registered, and each one returns an error message. Enable the variable only when the handler code comes from you, never from a caller, a model or an untrusted file.
|
|
332
|
+
|
|
333
|
+
| Parameter | Type | Default | Required | Description |
|
|
334
|
+
|---|---|---|---|---|
|
|
335
|
+
| `tools` | array | none | No | Entries with `name`, `description` and `handler_code`, and optional `parameters`, `required`, `prompt_description`, `secure` and `fillers` |
|
|
336
|
+
| `prompt_title` | string | `"Custom Tools"` | No | Title of the prompt section that lists the tools |
|
|
337
|
+
| `prompt_body` | string | none | No | Body of that prompt section |
|
|
338
|
+
|
|
339
|
+
Each `parameters` entry is `{ name, type, description }`, with an optional `required: true`. An argument is required when its entry sets `required: true` or the tool's `required` array lists its name. This example defines one tool:
|
|
340
|
+
|
|
341
|
+
```typescript
|
|
342
|
+
import { CustomSkillsSkill } from '@signalwire/sdk';
|
|
343
|
+
await agent.addSkill(
|
|
344
|
+
new CustomSkillsSkill({
|
|
345
|
+
prompt_title: 'Greeting Tools',
|
|
346
|
+
tools: [
|
|
347
|
+
{
|
|
348
|
+
name: 'get_greeting',
|
|
349
|
+
description: 'Get a personalized greeting for a customer.',
|
|
350
|
+
parameters: [{ name: 'name', type: 'string', description: 'Customer name' }],
|
|
351
|
+
required: ['name'],
|
|
352
|
+
handler_code: 'return new FunctionResult(`Hello, ${args.name}! Welcome back.`);',
|
|
353
|
+
},
|
|
354
|
+
],
|
|
355
|
+
}),
|
|
356
|
+
);
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
### web_search
|
|
360
|
+
|
|
361
|
+
`WebSearchSkill` searches with the Google Custom Search JSON API, then fetches the result pages and returns the text of the best ones. It requests `num_results` times `oversample_factor` results (at most 10), scores each page for length, relevance and boilerplate, and keeps one page per domain. When no page scores `min_quality_score` or more, or `overall_deadline` passes, it returns the search snippets instead.
|
|
362
|
+
|
|
363
|
+
The credentials come from `api_key` and `search_engine_id`, or from `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_ENGINE_ID` (`GOOGLE_SEARCH_CX` also works for the engine ID). Setup fails when either is missing, and the skill needs the optional `cheerio` package.
|
|
364
|
+
|
|
365
|
+
The skill fetches pages that search results point to, so it refuses private and internal addresses. It checks each URL and every redirect, and connects only to an address it checked. `SWML_ALLOW_PRIVATE_URLS` turns these checks off. For the proxy option, see [Configuration](configuration.md).
|
|
366
|
+
|
|
367
|
+
| Parameter | Type | Default | Required | Description |
|
|
368
|
+
|---|---|---|---|---|
|
|
369
|
+
| `tool_name` | string | none | No | Name of the search tool. The code uses `web_search` when it's unset. |
|
|
370
|
+
| `api_key` | string | none | Yes | Google Custom Search API key. Falls back to `GOOGLE_SEARCH_API_KEY`. |
|
|
371
|
+
| `search_engine_id` | string | none | Yes | Search engine ID. Falls back to `GOOGLE_SEARCH_ENGINE_ID`. |
|
|
372
|
+
| `num_results` | integer | `3` | No | Results to return, from 1 to 10 |
|
|
373
|
+
| `delay` | number | `0.5` | No | Seconds between page fetches when `parallel_scrape` is `false` |
|
|
374
|
+
| `max_content_length` | integer | `32768` | No | Maximum characters in the result, at least 1000 |
|
|
375
|
+
| `oversample_factor` | number | `2.5` | No | Multiplier for how many results to fetch, from 1 to 3.5 |
|
|
376
|
+
| `min_quality_score` | number | `0.3` | No | Lowest page score kept, from 0 to 1 |
|
|
377
|
+
| `no_results_message` | string | `"I couldn't find quality results for '{query}'. ..."` | No | Result when nothing is found. `{query}` is replaced with the query. |
|
|
378
|
+
| `per_page_timeout` | number | `2` | No | Seconds to wait for one page |
|
|
379
|
+
| `overall_deadline` | number | `10` | No | Seconds for the whole tool call |
|
|
380
|
+
| `parallel_scrape` | boolean | `true` | No | Fetch the pages at the same time instead of one after another |
|
|
381
|
+
| `snippets_only` | boolean | `false` | No | Return the search snippets without fetching pages |
|
|
382
|
+
| `response_prefix` | string | `""` | No | Text added before every non-empty result |
|
|
383
|
+
| `response_postfix` | string | `""` | No | Text added after every non-empty result |
|
|
384
|
+
| `safe_search` | string | `"medium"` | No | `off`, `medium` or `high`. Any value except `off` is sent as the `safe` parameter. |
|
|
385
|
+
|
|
386
|
+
This example returns five results and reads the credentials from the environment:
|
|
387
|
+
|
|
388
|
+
<!-- snippet: no-run needs Google Custom Search credentials, and fetches pages -->
|
|
389
|
+
```typescript
|
|
390
|
+
import { WebSearchSkill } from '@signalwire/sdk';
|
|
391
|
+
await agent.addSkill(new WebSearchSkill({ num_results: 5, safe_search: 'high' }));
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
### wikipedia_search
|
|
395
|
+
|
|
396
|
+
`WikipediaSearchSkill` searches English Wikipedia (`en.wikipedia.org`) with the MediaWiki Action API and returns the introduction of each matching article. It needs no key.
|
|
397
|
+
|
|
398
|
+
| Parameter | Type | Default | Required | Description |
|
|
399
|
+
|---|---|---|---|---|
|
|
400
|
+
| `num_results` | integer | `1` | No | Articles to return, from 1 to 5 |
|
|
401
|
+
| `no_results_message` | string | `"I couldn't find any Wikipedia articles for '{query}'. ..."` | No | Result when nothing is found. `{query}` is replaced with the query. |
|
|
402
|
+
|
|
403
|
+
This example returns up to three articles:
|
|
404
|
+
|
|
405
|
+
```typescript
|
|
406
|
+
import { WikipediaSearchSkill } from '@signalwire/sdk';
|
|
407
|
+
await agent.addSkill(new WikipediaSearchSkill({ num_results: 3 }));
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
### google_maps
|
|
411
|
+
|
|
412
|
+
`GoogleMapsSkill` registers two tools. `lookup_address` geocodes an address or business name with the Geocoding API, optionally biased toward a latitude and longitude. `compute_route` gets the driving distance and time between two coordinates from the Routes API.
|
|
413
|
+
|
|
414
|
+
The key comes from `api_key`, or from `GOOGLE_MAPS_API_KEY` when `api_key` isn't set. Setup fails when neither is set.
|
|
415
|
+
|
|
416
|
+
| Parameter | Type | Default | Required | Description |
|
|
417
|
+
|---|---|---|---|---|
|
|
418
|
+
| `api_key` | string | none | Yes | Google Maps API key. Falls back to `GOOGLE_MAPS_API_KEY`. |
|
|
419
|
+
| `lookup_tool_name` | string | `"lookup_address"` | No | Name of the geocoding tool |
|
|
420
|
+
| `route_tool_name` | string | `"compute_route"` | No | Name of the route tool |
|
|
421
|
+
|
|
422
|
+
This example adds the skill with its default tool names:
|
|
423
|
+
|
|
424
|
+
<!-- snippet: no-run needs a Google Maps key in GOOGLE_MAPS_API_KEY to load -->
|
|
425
|
+
```typescript
|
|
426
|
+
import { GoogleMapsSkill } from '@signalwire/sdk';
|
|
427
|
+
await agent.addSkill(new GoogleMapsSkill());
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
### datasphere
|
|
431
|
+
|
|
432
|
+
`DataSphereSkill` searches a SignalWire DataSphere document from your agent: its handler sends the query to your space's DataSphere search API. The space, project ID and token come from `space_name`, `project_id` and `token`, or from `SIGNALWIRE_SPACE`, `SIGNALWIRE_PROJECT_ID` and `SIGNALWIRE_API_TOKEN`. `document_id` has no fallback. Setup fails when any of the four is missing.
|
|
433
|
+
|
|
434
|
+
| Parameter | Type | Default | Required | Description |
|
|
435
|
+
|---|---|---|---|---|
|
|
436
|
+
| `tool_name` | string | `"search_knowledge"` | No | Name of the search tool. A different name lets you add a second instance. |
|
|
437
|
+
| `space_name` | string | none | Yes | Space name, such as `mycompany` for `mycompany.signalwire.com` |
|
|
438
|
+
| `project_id` | string | none | Yes | Project ID |
|
|
439
|
+
| `token` | string | none | Yes | API token |
|
|
440
|
+
| `document_id` | string | none | Yes | Document to search |
|
|
441
|
+
| `count` | integer | `1` | No | Results to return, from 1 to 10 |
|
|
442
|
+
| `distance` | number | `3` | No | Maximum distance for a result, from 0 to 10. Lower is more similar. |
|
|
443
|
+
| `tags` | array | none | No | Tags to filter results by |
|
|
444
|
+
| `language` | string | none | No | Language code for query expansion, such as `en` |
|
|
445
|
+
| `pos_to_expand` | array | none | No | Parts of speech to expand with synonyms: `NOUN`, `VERB`, `ADJ`, `ADV` |
|
|
446
|
+
| `max_synonyms` | integer | none | No | Most synonyms to use, from 1 to 10 |
|
|
447
|
+
| `no_results_message` | string | `"I couldn't find any relevant information for '{query}' ..."` | No | Result when nothing is found |
|
|
448
|
+
|
|
449
|
+
This example searches one document for up to three results:
|
|
450
|
+
|
|
451
|
+
<!-- snippet: no-run needs SignalWire credentials to load -->
|
|
452
|
+
```typescript
|
|
453
|
+
import { DataSphereSkill } from '@signalwire/sdk';
|
|
454
|
+
await agent.addSkill(new DataSphereSkill({ document_id: 'my-doc-id', count: 3 }));
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
### datasphere_serverless
|
|
458
|
+
|
|
459
|
+
`DataSphereServerlessSkill` runs the same search as a DataMap tool. The SWML carries the request and SignalWire makes it, so the search doesn't call back to your agent. It takes the same parameters as `datasphere`, but reads `space_name`, `project_id`, `token` and `document_id` only from its configuration. Setup fails when any of them is missing.
|
|
460
|
+
|
|
461
|
+
The skill writes the DataSphere URL and a Basic authorization header built from `project_id` and `token` into the SWML. Anyone who can read the agent's SWML can decode that header, so keep the agent's basic auth credentials private. The generated webhook reads the response from the root of the template data. For the template rules, see the [DataMap Guide](datamap-guide.md).
|
|
462
|
+
|
|
463
|
+
This is the `data_map` block the skill renders for `count: 2`, from a real run, with the placeholder credentials `p` and `t`:
|
|
464
|
+
|
|
465
|
+
```json
|
|
466
|
+
{
|
|
467
|
+
"webhooks": [
|
|
468
|
+
{
|
|
469
|
+
"url": "https://demo.signalwire.com/api/datasphere/documents/search",
|
|
470
|
+
"method": "POST",
|
|
471
|
+
"headers": { "Content-Type": "application/json", "Authorization": "Basic cDp0" },
|
|
472
|
+
"params": { "document_id": "doc1", "query_string": "${args.query}", "count": 2, "distance": 3 },
|
|
473
|
+
"foreach": {
|
|
474
|
+
"input_key": "chunks",
|
|
475
|
+
"output_key": "formatted_results",
|
|
476
|
+
"max": 2,
|
|
477
|
+
"append": "=== RESULT ===\n${this.text}\n==================================================\n\n"
|
|
478
|
+
},
|
|
479
|
+
"output": { "response": "I found results for \"${input.args.query}\":\n\n${formatted_results}" },
|
|
480
|
+
"error_keys": ["error"]
|
|
481
|
+
}
|
|
482
|
+
],
|
|
483
|
+
"output": {
|
|
484
|
+
"response": "I couldn't find any relevant information for '${args.query}' in the knowledge base. Try rephrasing your question or asking about a different topic."
|
|
485
|
+
}
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
`foreach` walks the `chunks` array of the response, appends each chunk's `text` (`${this.text}`) to `formatted_results`, and the output uses the result. The top-level `output` is the result when the webhook fails or returns an `error` key. This example adds the skill:
|
|
490
|
+
|
|
491
|
+
```typescript
|
|
492
|
+
import { DataSphereServerlessSkill } from '@signalwire/sdk';
|
|
493
|
+
await agent.addSkill(
|
|
494
|
+
new DataSphereServerlessSkill({
|
|
495
|
+
space_name: 'mycompany',
|
|
496
|
+
project_id: process.env['SIGNALWIRE_PROJECT_ID'],
|
|
497
|
+
token: process.env['SIGNALWIRE_API_TOKEN'],
|
|
498
|
+
document_id: 'my-doc-id',
|
|
499
|
+
}),
|
|
500
|
+
);
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
### native_vector_search
|
|
504
|
+
|
|
505
|
+
`NativeVectorSearchSkill` searches documents in one of two modes. With `documents`, it indexes them in memory when it loads and ranks them by TF-IDF blended with keyword overlap. With `remote_url`, it sends each query to a search server that speaks the Python SDK's `sw-search` protocol, and the server ranks the results.
|
|
506
|
+
|
|
507
|
+
The tool takes a required `query` and an optional `count`. A `remote_url` must not resolve to a private or internal address unless `SWML_ALLOW_PRIVATE_URLS` is set, and its `/health` must answer 200 at setup. Every request to it is checked the same way, including each redirect, and connects only to an address it checked. Credentials in the URL (`http://user:pass@host`) are sent as basic auth. In memory mode, setup succeeds with no documents, and the tool then returns a message saying nothing is loaded.
|
|
508
|
+
|
|
509
|
+
The schema also lists the Python skill's local-index parameters. This SDK accepts and ignores these: `index_file` (used only to tell instances apart), `build_index`, `source_dir`, `file_types`, `exclude_patterns`, `backend`, `connection_string`, `collection_name`, `overwrite`, `nlp_backend`, `query_nlp_backend`, `index_nlp_backend` and `model_name`. The parameters that take effect are these:
|
|
510
|
+
|
|
511
|
+
| Parameter | Type | Default | Required | Description |
|
|
512
|
+
|---|---|---|---|---|
|
|
513
|
+
| `tool_name` | string | `"search_knowledge"` | No | Name of the search tool. A different name lets you add a second instance. |
|
|
514
|
+
| `documents` | array | none | No | Documents to index in memory: `{ id, text, metadata?, tags? }` |
|
|
515
|
+
| `remote_url` | string | none | No | Base URL of a remote search server |
|
|
516
|
+
| `index_name` | string | `"default"` | No | Index to query on the remote server |
|
|
517
|
+
| `count` | integer | `5` | No | Default number of results, from 1 to 20 |
|
|
518
|
+
| `similarity_threshold` | number | `0` | No | Lowest score returned, from 0 to 1 |
|
|
519
|
+
| `tags` | array | `[]` | No | Return only documents with one of these tags |
|
|
520
|
+
| `global_tags` | array | `[]` | No | Tags added to every in-memory document |
|
|
521
|
+
| `keyword_weight` | number | none | No | In memory mode, the share of the score that keyword overlap contributes, from 0 to 1. Unset means 0.3. With `remote_url` it has no effect, and setting it logs a warning. |
|
|
522
|
+
| `no_results_message` | string | `"No information found for '{query}'"` | No | Result when nothing is found |
|
|
523
|
+
| `response_prefix` | string | `""` | No | Text added before the results |
|
|
524
|
+
| `response_postfix` | string | `""` | No | Text added after the results |
|
|
525
|
+
| `max_content_length` | integer | `32768` | No | Maximum characters in the result, shared by the results |
|
|
526
|
+
| `response_format_callback` | object | none | No | A function that receives the formatted response and the results, and returns the text to use |
|
|
527
|
+
| `description` | string | `"Search the knowledge base for information"` | No | Description of the search tool |
|
|
528
|
+
| `hints` | array | `[]` | No | Extra speech recognition hints |
|
|
529
|
+
| `verbose` | boolean | `false` | No | Log index details at setup |
|
|
530
|
+
|
|
531
|
+
This example indexes two documents in memory:
|
|
532
|
+
|
|
533
|
+
```typescript
|
|
534
|
+
import { NativeVectorSearchSkill } from '@signalwire/sdk';
|
|
535
|
+
await agent.addSkill(
|
|
536
|
+
new NativeVectorSearchSkill({
|
|
537
|
+
documents: [
|
|
538
|
+
{ id: 'faq-1', text: 'Reset your password in Settings.' },
|
|
539
|
+
{ id: 'faq-2', text: 'Business hours are 9 to 5.' },
|
|
540
|
+
],
|
|
541
|
+
}),
|
|
542
|
+
);
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
With that configuration and `keyword_weight: 0.5`, a `search_knowledge` call with the query `password reset` returned this result:
|
|
546
|
+
|
|
547
|
+
```text
|
|
548
|
+
Found 1 relevant results for 'password reset':
|
|
549
|
+
|
|
550
|
+
**Result 1** (from faq-1, relevance: 0.83)
|
|
551
|
+
Reset your password in Settings.
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
### spider
|
|
555
|
+
|
|
556
|
+
`SpiderSkill` fetches web pages itself and extracts their content. It registers three tools, each taking only a URL: `scrape_url`, `crawl_site` (argument `start_url`) and `extract_structured_data`. With `tool_name` set, the tool names get that prefix, such as `docs_scrape_url`. It needs the optional `cheerio` package.
|
|
557
|
+
|
|
558
|
+
`crawl_site` follows links breadth first from the start page, up to `max_pages` pages and `max_depth` links deep. It stays on the start page's host, and follows only links that match a `follow_patterns` expression when you set any. `extract_structured_data` returns the text that each configured selector matches. A selector is CSS; one that starts with `/` is read as XPath, and only its first `//tag` step is used.
|
|
559
|
+
|
|
560
|
+
The skill refuses private and internal addresses. It checks each URL and each link it discovers, and checks every redirect. It connects only to an address it checked. `SWML_ALLOW_PRIVATE_URLS` turns these checks off. For the proxy option, see [Configuration](configuration.md).
|
|
561
|
+
|
|
562
|
+
With `follow_robots_txt: true`, it skips a page, or a redirect to a page, that the site's robots.txt disallows for `user_agent`. It keeps a site's rules for 24 hours. A robots.txt answered with 401 or 403 disallows the whole site, and any other 4xx allows it. When robots.txt can't be fetched, or answers with a server error, the page is skipped and the next request tries again.
|
|
563
|
+
|
|
564
|
+
| Parameter | Type | Default | Required | Description |
|
|
565
|
+
|---|---|---|---|---|
|
|
566
|
+
| `tool_name` | string | none | No | Prefix for the tool names. The tools keep their plain names when it's unset. |
|
|
567
|
+
| `delay` | number | `0.1` | No | Seconds between pages while crawling |
|
|
568
|
+
| `concurrent_requests` | integer | `5` | No | Deprecated, and has no effect: the spider fetches one page at a time. Setting it logs a warning. |
|
|
569
|
+
| `timeout` | integer | `5` | No | Seconds to wait for a request, from 1 to 60 |
|
|
570
|
+
| `max_pages` | integer | `1` | No | Most pages a crawl fetches, from 1 to 100 |
|
|
571
|
+
| `max_depth` | integer | `0` | No | How many links deep a crawl goes, from 0 to 5 |
|
|
572
|
+
| `extract_type` | string | `"fast_text"` | No | How `scrape_url` extracts content: `fast_text`, `markdown` or `structured` |
|
|
573
|
+
| `max_text_length` | integer | `3000` | No | Maximum characters per page, from 100 to 100000 |
|
|
574
|
+
| `clean_text` | boolean | `true` | No | Collapse extra whitespace |
|
|
575
|
+
| `selectors` | object | `{}` | No | Field name to selector, for `extract_structured_data` and for `scrape_url` with `structured` |
|
|
576
|
+
| `follow_patterns` | array | `[]` | No | Regular expressions a crawled link must match |
|
|
577
|
+
| `user_agent` | string | `"Spider/1.0 (SignalWire AI Agent)"` | No | User agent sent with every request, and matched against robots.txt |
|
|
578
|
+
| `headers` | object | `{}` | No | Extra headers sent with every request, to any URL the model asks for. A redirect to another origin drops `Authorization`, `Cookie` and `Proxy-Authorization`. |
|
|
579
|
+
| `follow_robots_txt` | boolean | `false` | No | Honor robots.txt, as described earlier |
|
|
580
|
+
| `cache_enabled` | boolean | `true` | No | Keep up to 100 fetched pages in memory |
|
|
581
|
+
|
|
582
|
+
An `extract_type` of `clean_text`, `full_text`, `html` or `custom` was never implemented. These values still load, work as `fast_text` and log a warning. Any other value outside the three listed makes setup fail.
|
|
583
|
+
|
|
584
|
+
This example returns pages as markdown and honors robots.txt:
|
|
585
|
+
|
|
586
|
+
```typescript
|
|
587
|
+
import { SpiderSkill } from '@signalwire/sdk';
|
|
588
|
+
await agent.addSkill(
|
|
589
|
+
new SpiderSkill({ extract_type: 'markdown', max_text_length: 5000, follow_robots_txt: true }),
|
|
590
|
+
);
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
### claude_skills
|
|
594
|
+
|
|
595
|
+
`ClaudeSkillsSkill` reads Claude-style skill folders, each with a `SKILL.md` that has YAML front matter (`name`, `description`) and instructions. It registers one tool per skill, named `tool_prefix` plus the skill name. The tool returns the skill's instructions, or one of its other markdown files through the `section` argument, with the model's `arguments` substituted in.
|
|
596
|
+
|
|
597
|
+
A skill with `disable-model-invocation: true` gets no tool and no prompt entry. A skill with `user-invocable: false` gets a prompt entry and no tool. `ignore_invocation_control` registers both kinds anyway.
|
|
598
|
+
|
|
599
|
+
With `allow_shell_injection: true`, each `` !`command` `` in a skill's text runs as a shell command in the skill's folder. It runs every time the tool is called, and its output replaces the pattern. The commands come from the SKILL.md files and run with your process's permissions. The model's arguments are substituted after the commands run, so they don't reach the shell. Enable it only for skill folders you control.
|
|
600
|
+
|
|
601
|
+
| Parameter | Type | Default | Required | Description |
|
|
602
|
+
|---|---|---|---|---|
|
|
603
|
+
| `skills_path` | string | none | Yes | Directory that holds the skill folders |
|
|
604
|
+
| `include` | array | `["*"]` | No | Glob patterns of skill names to load |
|
|
605
|
+
| `exclude` | array | `[]` | No | Glob patterns of skill names to skip |
|
|
606
|
+
| `prompt_title` | string | `"Claude Skills"` | No | Title of the prompt section |
|
|
607
|
+
| `prompt_intro` | string | `"You have access to specialized skills. ..."` | No | Opening text of the prompt section |
|
|
608
|
+
| `skill_descriptions` | object | `{}` | No | Skill name to a description that replaces the one in SKILL.md |
|
|
609
|
+
| `tool_prefix` | string | `"claude_"` | No | Prefix of the tool names. Use `""` for none. |
|
|
610
|
+
| `response_prefix` | string | `""` | No | Text added before each result |
|
|
611
|
+
| `response_postfix` | string | `""` | No | Text added after each result |
|
|
612
|
+
| `allow_shell_injection` | boolean | `false` | No | Run `` !`command` `` patterns, as described earlier |
|
|
613
|
+
| `allow_script_execution` | boolean | `false` | No | List the files in each skill's `scripts/` and `assets/` folders in the prompt. It runs nothing. |
|
|
614
|
+
| `ignore_invocation_control` | boolean | `false` | No | Ignore `disable-model-invocation` and `user-invocable` |
|
|
615
|
+
| `shell_timeout` | integer | `30` | No | Seconds a shell command may run |
|
|
616
|
+
|
|
617
|
+
This example loads every skill folder under one directory:
|
|
618
|
+
|
|
619
|
+
<!-- snippet: no-run needs a real directory of SKILL.md folders -->
|
|
620
|
+
```typescript
|
|
621
|
+
import { ClaudeSkillsSkill } from '@signalwire/sdk';
|
|
622
|
+
await agent.addSkill(new ClaudeSkillsSkill({ skills_path: '/path/to/skills' }));
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
### ask_claude
|
|
626
|
+
|
|
627
|
+
`AskClaudeSkill` sends a prompt to the Anthropic Messages API and returns the reply. The tool takes a required `prompt` and an optional `system_prompt`. The key comes from `api_key`, or from `ANTHROPIC_API_KEY` when `api_key` isn't set. Setup fails when neither is set.
|
|
628
|
+
|
|
629
|
+
| Parameter | Type | Default | Required | Description |
|
|
630
|
+
|---|---|---|---|---|
|
|
631
|
+
| `api_key` | string | none | Yes | Anthropic API key. Falls back to `ANTHROPIC_API_KEY`. |
|
|
632
|
+
| `model` | string | `"claude-sonnet-4-5-20250929"` | No | Model to call |
|
|
633
|
+
| `max_tokens` | number | `1024` | No | Maximum tokens in the reply |
|
|
634
|
+
|
|
635
|
+
This example sets the reply length:
|
|
636
|
+
|
|
637
|
+
<!-- snippet: no-run needs an Anthropic key in ANTHROPIC_API_KEY to load -->
|
|
638
|
+
```typescript
|
|
639
|
+
import { AskClaudeSkill } from '@signalwire/sdk';
|
|
640
|
+
await agent.addSkill(new AskClaudeSkill({ max_tokens: 512 }));
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
### mcp_gateway
|
|
644
|
+
|
|
645
|
+
`McpGatewaySkill` connects to an MCP gateway service and registers a SWAIG tool for each tool the gateway's services expose, named `<tool_prefix><service>_<tool>`. At setup it checks `gateway_url` against private and internal addresses, calls the gateway's `/health`, and lists the tools. Setup fails if any step fails. It also registers `_mcp_gateway_hangup`, marked `is_hangup_hook`, whose handler closes the call's MCP session.
|
|
646
|
+
|
|
647
|
+
Authentication is a bearer token (`auth_token` or `MCP_GATEWAY_AUTH_TOKEN`), or basic auth (`auth_user` and `auth_password`, or `MCP_GATEWAY_AUTH_USER` and `MCP_GATEWAY_AUTH_PASSWORD`). TLS verification stays on unless you set both `verify_ssl: false` and `allow_insecure_tls: true`. With both set, the skill accepts any certificate. For the gateway itself, see the [MCP Gateway Reference](mcp_gateway_reference.md).
|
|
648
|
+
|
|
649
|
+
| Parameter | Type | Default | Required | Description |
|
|
650
|
+
|---|---|---|---|---|
|
|
651
|
+
| `gateway_url` | string | none | Yes | Base URL of the gateway |
|
|
652
|
+
| `auth_token` | string | none | No | Bearer token. Falls back to `MCP_GATEWAY_AUTH_TOKEN`. |
|
|
653
|
+
| `auth_user` | string | none | No | Basic auth user, when there's no token. Falls back to `MCP_GATEWAY_AUTH_USER`. |
|
|
654
|
+
| `auth_password` | string | none | No | Basic auth password. Falls back to `MCP_GATEWAY_AUTH_PASSWORD`. |
|
|
655
|
+
| `services` | array | `[]` | No | `{ name, tools }` entries, where `tools` is `"*"` or a list of names. Empty means every service. |
|
|
656
|
+
| `session_timeout` | integer | `300` | No | Session timeout in seconds, sent to the gateway |
|
|
657
|
+
| `tool_prefix` | string | `"mcp_"` | No | Prefix of the registered tool names |
|
|
658
|
+
| `retry_attempts` | integer | `3` | No | Retries for a failed request |
|
|
659
|
+
| `request_timeout` | integer | `30` | No | Request timeout in seconds |
|
|
660
|
+
| `verify_ssl` | boolean | `true` | No | Set `false` together with `allow_insecure_tls` to skip certificate checks |
|
|
661
|
+
| `allow_insecure_tls` | boolean | `false` | No | Required as well as `verify_ssl: false` to skip certificate checks |
|
|
662
|
+
|
|
663
|
+
This example exposes every tool of one service:
|
|
664
|
+
|
|
665
|
+
<!-- snippet: no-run needs a reachable MCP gateway at setup -->
|
|
666
|
+
```typescript
|
|
667
|
+
import { McpGatewaySkill } from '@signalwire/sdk';
|
|
668
|
+
await agent.addSkill(
|
|
669
|
+
new McpGatewaySkill({
|
|
670
|
+
gateway_url: 'https://mcp-gateway.example.com',
|
|
671
|
+
auth_token: process.env['MCP_GATEWAY_AUTH_TOKEN'],
|
|
672
|
+
services: [{ name: 'todo', tools: '*' }],
|
|
673
|
+
}),
|
|
674
|
+
);
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
---
|
|
678
|
+
|
|
679
|
+
## Skill Configuration
|
|
680
|
+
|
|
681
|
+
A skill takes its configuration as a plain object, typed `SkillConfig`:
|
|
682
|
+
|
|
683
|
+
```typescript
|
|
684
|
+
interface SkillConfig {
|
|
685
|
+
[key: string]: unknown;
|
|
686
|
+
}
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
Two parameters apply to every skill:
|
|
690
|
+
|
|
691
|
+
- `swaig_fields` (object, default `{}`): fields copied into every tool definition the skill registers, such as `{ fillers: { 'en-US': ['One moment'] } }`. They override the same fields the tool sets.
|
|
692
|
+
- `skip_prompt` (boolean, default `false`): when `true`, the skill adds no prompt sections.
|
|
693
|
+
|
|
694
|
+
A `secure` key in `swaig_fields` sets whether the skill's tools need a per-call token, unless a tool sets `secure` itself.
|
|
695
|
+
|
|
696
|
+
A skill whose class sets `SUPPORTS_MULTIPLE_INSTANCES = true` also gets `tool_name` in its schema. This example adds a second DataSphere search under its own tool name:
|
|
697
|
+
|
|
698
|
+
<!-- snippet: no-run needs SignalWire credentials to load -->
|
|
699
|
+
```typescript
|
|
700
|
+
import { DataSphereSkill } from '@signalwire/sdk';
|
|
701
|
+
await agent.addSkill(new DataSphereSkill({ document_id: 'drinks-doc', tool_name: 'search_drinks' }));
|
|
702
|
+
await agent.addSkill(new DataSphereSkill({ document_id: 'food-doc', tool_name: 'search_food' }));
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
The schema describes the parameters for tools and user interfaces. The SDK doesn't check a configuration against it. A wrong type, an out-of-range value or a missing `required` parameter is caught only if the skill's `setup()` checks it. For the schema format, see [Skills Parameter Schema](skills_parameter_schema.md).
|
|
706
|
+
|
|
707
|
+
### Accessing Config in Skills
|
|
708
|
+
|
|
709
|
+
Inside a skill, `this.getConfig<T>(key, defaultValue)` reads a configuration value and returns `defaultValue` when the key is absent:
|
|
710
|
+
|
|
711
|
+
<!-- snippet: no-compile illustrative method-body fragment; `this` refers to a SkillBase subclass -->
|
|
712
|
+
```typescript
|
|
713
|
+
// Inside a skill class
|
|
714
|
+
const maxResults = this.getConfig<number>('max_results', 5);
|
|
715
|
+
const safeSearch = this.getConfig<string>('safe_search', 'medium');
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
`this.params` returns the whole configuration, read-only, without `swaig_fields`.
|
|
719
|
+
|
|
720
|
+
### Declaring Skill Metadata and Config Schema
|
|
721
|
+
|
|
722
|
+
A skill declares its metadata as static fields, and its parameters in the static `getParameterSchema()`. Spread the base schema so `swaig_fields` and `skip_prompt` stay in it:
|
|
723
|
+
|
|
724
|
+
```typescript
|
|
725
|
+
import { SkillBase, type ParameterSchemaEntry, type SkillToolDefinition } from '@signalwire/sdk';
|
|
726
|
+
|
|
727
|
+
export class MySkill extends SkillBase {
|
|
728
|
+
static override SKILL_NAME = 'my_skill';
|
|
729
|
+
static override SKILL_DESCRIPTION = 'Looks up order status.';
|
|
730
|
+
static override SKILL_VERSION = '1.0.0';
|
|
731
|
+
static override REQUIRED_ENV_VARS = ['MY_API_KEY'] as const;
|
|
732
|
+
|
|
733
|
+
static override getParameterSchema(): Record<string, ParameterSchemaEntry> {
|
|
734
|
+
return {
|
|
735
|
+
...super.getParameterSchema(),
|
|
736
|
+
max_results: {
|
|
737
|
+
type: 'integer',
|
|
738
|
+
description: 'Maximum number of results to return.',
|
|
739
|
+
default: 5,
|
|
740
|
+
required: false,
|
|
741
|
+
min: 1,
|
|
742
|
+
max: 10,
|
|
743
|
+
},
|
|
744
|
+
};
|
|
745
|
+
}
|
|
746
|
+
|
|
747
|
+
override getTools(): SkillToolDefinition[] {
|
|
748
|
+
return [];
|
|
749
|
+
}
|
|
750
|
+
}
|
|
751
|
+
```
|
|
752
|
+
|
|
753
|
+
---
|
|
754
|
+
|
|
755
|
+
## Skill Registry
|
|
756
|
+
|
|
757
|
+
The `SkillRegistry` is a process-wide singleton that maps skill names to skill classes. `addSkillByName()` and `SkillManager.loadSkillByName()` look names up in it.
|
|
758
|
+
|
|
759
|
+
### Getting the Registry
|
|
760
|
+
|
|
761
|
+
`getInstance()` returns the singleton:
|
|
762
|
+
|
|
763
|
+
```typescript
|
|
764
|
+
import { SkillRegistry } from '@signalwire/sdk';
|
|
765
|
+
|
|
766
|
+
const registry = SkillRegistry.getInstance();
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
### Registering Built-in Skills
|
|
770
|
+
|
|
771
|
+
`registerBuiltinSkills()` registers every built-in skill, then locks every name the registry holds at that moment:
|
|
772
|
+
|
|
773
|
+
```typescript
|
|
774
|
+
import { registerBuiltinSkills } from '@signalwire/sdk';
|
|
775
|
+
|
|
776
|
+
registerBuiltinSkills();
|
|
777
|
+
```
|
|
778
|
+
|
|
779
|
+
It skips a name that's already registered, so a second call changes nothing. After it runs, `register()` refuses to replace a locked name: it logs `Cannot overwrite locked skill` and keeps the original class. The lock stops a third-party or discovered skill from taking over a built-in name. It doesn't stop `unregister()` or `clear()`.
|
|
780
|
+
|
|
781
|
+
### Manual Registration
|
|
782
|
+
|
|
783
|
+
`register()` takes the skill class itself and files it under the class's static `SKILL_NAME`. It throws when `SKILL_NAME` is empty or `getParameterSchema()` doesn't return a non-empty object:
|
|
784
|
+
|
|
785
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `registry` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
786
|
+
```typescript
|
|
787
|
+
registry.register(MyCustomSkill);
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
To lock names yourself, call `registry.lock(['my_skill'])`, or `registry.lock()` to lock every registered name.
|
|
791
|
+
|
|
792
|
+
### Creating Instances by Name
|
|
793
|
+
|
|
794
|
+
`create()` constructs a registered skill with an optional configuration, and returns `null` for an unknown name:
|
|
795
|
+
|
|
796
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `registry` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
797
|
+
```typescript
|
|
798
|
+
const skill = registry.create('datetime');
|
|
799
|
+
if (skill) {
|
|
800
|
+
await agent.addSkill(skill);
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
const weatherSkill = registry.create('weather_api', { units: 'imperial' });
|
|
804
|
+
```
|
|
805
|
+
|
|
806
|
+
### Querying the Registry
|
|
807
|
+
|
|
808
|
+
These methods report what's registered:
|
|
809
|
+
|
|
810
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `registry` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
811
|
+
```typescript
|
|
812
|
+
registry.has('datetime'); // true once registered
|
|
813
|
+
|
|
814
|
+
const names = registry.listRegistered(); // ['datetime', 'math', ...]
|
|
815
|
+
|
|
816
|
+
// Name, description, version, supportsMultipleInstances, requiredEnvVars,
|
|
817
|
+
// requiredPackages and parameters for every registered skill
|
|
818
|
+
const withSchemas = registry.listSkills();
|
|
819
|
+
|
|
820
|
+
const schema = registry.getSkillSchema('web_search'); // one skill, or undefined
|
|
821
|
+
const all = registry.getAllSkillsSchema(); // keyed by skill name
|
|
822
|
+
|
|
823
|
+
const count = registry.size;
|
|
824
|
+
```
|
|
825
|
+
|
|
826
|
+
### Skill Discovery from Directories
|
|
827
|
+
|
|
828
|
+
The registry can import skill modules from directories and register the skill classes they export. Discovery runs the code in every module it imports, with your process's permissions. For that reason it's off unless `SWML_SKILL_DISCOVERY_ENABLED` is `true`. Without it, the discovery methods log a warning and return an empty list.
|
|
829
|
+
|
|
830
|
+
These calls add a search path and discover skills:
|
|
831
|
+
|
|
832
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `registry` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
833
|
+
```typescript
|
|
834
|
+
registry.addSearchPath('/path/to/my/skills');
|
|
835
|
+
|
|
836
|
+
// Import the modules in one directory and register their skill classes
|
|
837
|
+
const discovered = await registry.discoverFromDirectory('/path/to/my/skills');
|
|
838
|
+
|
|
839
|
+
// The same, for every search path
|
|
840
|
+
const allDiscovered = await registry.discoverAll();
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
In a directory, discovery imports every `.ts` and `.js` file except `.d.ts` files, and `skill.ts` in each subdirectory, or `skill.js` when there's no `skill.ts`. It registers every exported class that extends `SkillBase` and sets `SKILL_NAME`. A module that exports only a `createSkill` factory registers nothing. Nothing runs discovery for you: call `discoverFromDirectory()` or `discoverAll()`.
|
|
844
|
+
|
|
845
|
+
`SIGNALWIRE_SKILL_PATHS` adds colon-separated search paths when the registry is first created:
|
|
846
|
+
|
|
847
|
+
```bash
|
|
848
|
+
export SIGNALWIRE_SKILL_PATHS="/app/skills:/shared/skills"
|
|
849
|
+
```
|
|
850
|
+
|
|
851
|
+
Only point discovery at directories that you control, because anyone who can write a file there can run code in your agent.
|
|
852
|
+
|
|
853
|
+
### Cleanup
|
|
854
|
+
|
|
855
|
+
These calls remove registrations, mostly for tests:
|
|
856
|
+
|
|
857
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `registry` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
858
|
+
```typescript
|
|
859
|
+
registry.unregister('my_skill'); // one name, locked or not
|
|
860
|
+
registry.clear(); // every registration
|
|
861
|
+
SkillRegistry.resetInstance(); // drop the singleton
|
|
862
|
+
```
|
|
863
|
+
|
|
864
|
+
---
|
|
865
|
+
|
|
866
|
+
## Creating Custom Skills
|
|
867
|
+
|
|
868
|
+
To create a skill, extend `SkillBase`, set `SKILL_NAME` and `SKILL_DESCRIPTION`, and return tools from `getTools()`. The constructor throws when either static field is empty.
|
|
869
|
+
|
|
870
|
+
### Minimal Custom Skill
|
|
871
|
+
|
|
872
|
+
This skill registers one tool, and its style comes from the configuration:
|
|
873
|
+
|
|
874
|
+
```typescript
|
|
875
|
+
import { SkillBase, FunctionResult, type SkillToolDefinition } from '@signalwire/sdk';
|
|
876
|
+
|
|
877
|
+
export class GreetingSkill extends SkillBase {
|
|
878
|
+
static override SKILL_NAME = 'greeting';
|
|
879
|
+
static override SKILL_DESCRIPTION = 'Provides personalized greetings.';
|
|
880
|
+
|
|
881
|
+
override getTools(): SkillToolDefinition[] {
|
|
882
|
+
const style = this.getConfig<string>('style', 'formal');
|
|
883
|
+
|
|
884
|
+
return [
|
|
885
|
+
{
|
|
886
|
+
name: 'greet_customer',
|
|
887
|
+
description: 'Generate a personalized greeting for a customer.',
|
|
888
|
+
parameters: {
|
|
889
|
+
name: { type: 'string', description: 'The customer name.' },
|
|
890
|
+
},
|
|
891
|
+
required: ['name'],
|
|
892
|
+
handler: (args: Record<string, unknown>) => {
|
|
893
|
+
const name = String(args.name ?? '');
|
|
894
|
+
if (style === 'casual') {
|
|
895
|
+
return new FunctionResult(`Greet the customer casually by name: ${name}.`);
|
|
896
|
+
}
|
|
897
|
+
return new FunctionResult(`Greet the customer formally by name: ${name}.`);
|
|
898
|
+
},
|
|
899
|
+
},
|
|
900
|
+
];
|
|
901
|
+
}
|
|
902
|
+
}
|
|
903
|
+
```
|
|
904
|
+
|
|
905
|
+
The handler's result is an instruction for the model, which decides what to say to the caller. To register the class for directory discovery, export it from the module. For discovery and packaging, see [Third-Party Skills](third_party_skills.md).
|
|
906
|
+
|
|
907
|
+
### Full-Featured Custom Skill
|
|
908
|
+
|
|
909
|
+
This skill uses every hook: a parameter schema, `setup()`, `cleanup()`, a secure tool with fillers, a prompt section, hints and global data:
|
|
910
|
+
|
|
911
|
+
```typescript
|
|
912
|
+
import {
|
|
913
|
+
SkillBase,
|
|
914
|
+
FunctionResult,
|
|
915
|
+
type SkillToolDefinition,
|
|
916
|
+
type SkillPromptSection,
|
|
917
|
+
type ParameterSchemaEntry,
|
|
918
|
+
} from '@signalwire/sdk';
|
|
919
|
+
|
|
920
|
+
export class InventorySkill extends SkillBase {
|
|
921
|
+
static override SKILL_NAME = 'inventory';
|
|
922
|
+
static override SKILL_DESCRIPTION = 'Checks product inventory levels.';
|
|
923
|
+
static override SKILL_VERSION = '1.0.0';
|
|
924
|
+
static override REQUIRED_ENV_VARS = ['INVENTORY_DB_URL'] as const;
|
|
925
|
+
|
|
926
|
+
private db: Map<string, number> = new Map();
|
|
927
|
+
|
|
928
|
+
static override getParameterSchema(): Record<string, ParameterSchemaEntry> {
|
|
929
|
+
return {
|
|
930
|
+
...super.getParameterSchema(),
|
|
931
|
+
low_stock_threshold: {
|
|
932
|
+
type: 'integer',
|
|
933
|
+
description: 'Quantity at or below which a product is low stock.',
|
|
934
|
+
default: 10,
|
|
935
|
+
required: false,
|
|
936
|
+
},
|
|
937
|
+
};
|
|
938
|
+
}
|
|
939
|
+
|
|
940
|
+
// Runs once when the skill is added. Return false to refuse the skill.
|
|
941
|
+
override async setup(): Promise<boolean> {
|
|
942
|
+
// Connect to the database named by INVENTORY_DB_URL and load data here.
|
|
943
|
+
this.db.set('widget-a', 150);
|
|
944
|
+
this.db.set('widget-b', 3);
|
|
945
|
+
return true;
|
|
946
|
+
}
|
|
947
|
+
|
|
948
|
+
// Runs when the skill is removed.
|
|
949
|
+
override async cleanup(): Promise<void> {
|
|
950
|
+
this.db.clear();
|
|
951
|
+
}
|
|
952
|
+
|
|
953
|
+
override getTools(): SkillToolDefinition[] {
|
|
954
|
+
const threshold = this.getConfig<number>('low_stock_threshold', 10);
|
|
955
|
+
|
|
956
|
+
return [
|
|
957
|
+
{
|
|
958
|
+
name: 'check_inventory',
|
|
959
|
+
description: 'Check the current inventory level for a product.',
|
|
960
|
+
parameters: {
|
|
961
|
+
product_id: { type: 'string', description: 'The product ID to check.' },
|
|
962
|
+
},
|
|
963
|
+
required: ['product_id'],
|
|
964
|
+
secure: true,
|
|
965
|
+
fillers: { 'en-US': ['Let me check our stock levels.', 'One moment.'] },
|
|
966
|
+
handler: (args: Record<string, unknown>) => {
|
|
967
|
+
const productId = String(args.product_id ?? '');
|
|
968
|
+
const quantity = this.db.get(productId);
|
|
969
|
+
if (quantity === undefined) {
|
|
970
|
+
return new FunctionResult(`Product "${productId}" was not found in inventory.`);
|
|
971
|
+
}
|
|
972
|
+
const status = quantity <= threshold ? 'low stock' : 'in stock';
|
|
973
|
+
return new FunctionResult(`Product ${productId}: ${quantity} units, ${status}.`);
|
|
974
|
+
},
|
|
975
|
+
},
|
|
976
|
+
];
|
|
977
|
+
}
|
|
978
|
+
|
|
979
|
+
protected override _getPromptSections(): SkillPromptSection[] {
|
|
980
|
+
return [
|
|
981
|
+
{
|
|
982
|
+
title: 'Inventory Lookup',
|
|
983
|
+
body: 'You can check product inventory levels for customers.',
|
|
984
|
+
bullets: [
|
|
985
|
+
'Use the check_inventory tool when a customer asks whether a product is available.',
|
|
986
|
+
'If a product is low stock, tell the customer.',
|
|
987
|
+
],
|
|
988
|
+
},
|
|
989
|
+
];
|
|
990
|
+
}
|
|
991
|
+
|
|
992
|
+
override getHints(): string[] {
|
|
993
|
+
return ['inventory', 'stock', 'availability', 'in stock', 'out of stock'];
|
|
994
|
+
}
|
|
995
|
+
|
|
996
|
+
override getGlobalData(): Record<string, unknown> {
|
|
997
|
+
return { low_stock_threshold: this.getConfig<number>('low_stock_threshold', 10) };
|
|
998
|
+
}
|
|
999
|
+
}
|
|
1000
|
+
```
|
|
1001
|
+
|
|
1002
|
+
Override `_getPromptSections()`, not `getPromptSections()`. The public method returns nothing when `skip_prompt` is `true`, and calls `_getPromptSections()` otherwise.
|
|
1003
|
+
|
|
1004
|
+
### SkillBase Members Reference
|
|
1005
|
+
|
|
1006
|
+
These are the members a skill sets or overrides:
|
|
1007
|
+
|
|
1008
|
+
| Member | Required | Description |
|
|
1009
|
+
|---|---|---|
|
|
1010
|
+
| `static SKILL_NAME` | Yes | Unique skill name, such as `'greeting'`. The constructor throws when it's empty. |
|
|
1011
|
+
| `static SKILL_DESCRIPTION` | Yes | Description shown in registry listings. The constructor throws when it's empty. |
|
|
1012
|
+
| `static SKILL_VERSION` | No | Version string. Defaults to `'1.0.0'`. |
|
|
1013
|
+
| `static REQUIRED_ENV_VARS` | No | Environment variables that must be set, or the skill doesn't load |
|
|
1014
|
+
| `static REQUIRED_PACKAGES` | No | npm packages that must import, or the skill doesn't load |
|
|
1015
|
+
| `static SUPPORTS_MULTIPLE_INSTANCES` | No | Allows more than one instance on an agent. Defaults to `false`. |
|
|
1016
|
+
| `static getParameterSchema()` | No | The skill's parameter schema. Must return a non-empty object; the base returns `swaig_fields` and `skip_prompt`. |
|
|
1017
|
+
| `getTools()` | No | Tool definitions. The default returns the tools added with the protected `defineTool()`. |
|
|
1018
|
+
| `getDataMapTools()` | No | Complete SWAIG function objects, such as `DataMap.toSwaigFunction()` output |
|
|
1019
|
+
| `setup()` | No | Async initialization. Return `false` to refuse the skill. |
|
|
1020
|
+
| `cleanup()` | No | Async teardown when the skill is removed |
|
|
1021
|
+
| `_getPromptSections()` | No | Prompt sections, returned through `getPromptSections()` unless `skip_prompt` is set |
|
|
1022
|
+
| `getHints()` | No | Speech recognition hints |
|
|
1023
|
+
| `getGlobalData()` | No | Keys merged into the agent's global data |
|
|
1024
|
+
| `getInstanceKey()` | No | Key that tells instances apart. The default is the skill name, or `<name>_<tool_name>` for a multi-instance skill. |
|
|
1025
|
+
|
|
1026
|
+
A skill can also call these helpers:
|
|
1027
|
+
|
|
1028
|
+
| Member | Description |
|
|
1029
|
+
|---|---|
|
|
1030
|
+
| `getConfig(key, default)` | Reads a configuration value, with a default |
|
|
1031
|
+
| `params` | The whole configuration, read-only, without `swaig_fields` |
|
|
1032
|
+
| `agent` | The agent the skill was added to, set before `setup()` runs |
|
|
1033
|
+
| `logger` | A logger named `signalwire.skills.<SKILL_NAME>` (protected) |
|
|
1034
|
+
| `validateEnvVars()` | Returns the missing `REQUIRED_ENV_VARS` names |
|
|
1035
|
+
| `validatePackages()` | Resolves to the `REQUIRED_PACKAGES` names that don't import |
|
|
1036
|
+
| `getSkillData(rawData)` | Reads this skill's state from a request's global data |
|
|
1037
|
+
| `updateSkillData(result, data)` | Stores this skill's state on a `FunctionResult` through `updateGlobalData()` |
|
|
1038
|
+
| `isInitialized()` | Whether `setup()` has completed |
|
|
1039
|
+
|
|
1040
|
+
### SkillToolDefinition Fields
|
|
1041
|
+
|
|
1042
|
+
A tool definition has these fields:
|
|
1043
|
+
|
|
1044
|
+
| Field | Type | Required | Description |
|
|
1045
|
+
|---|---|---|---|
|
|
1046
|
+
| `name` | `string` | Yes | Tool name |
|
|
1047
|
+
| `description` | `string` | Yes | Description the model reads |
|
|
1048
|
+
| `parameters` | `Record<string, unknown>` | No | JSON Schema properties, keyed by argument name |
|
|
1049
|
+
| `required` | `string[]` | No | Names of required arguments |
|
|
1050
|
+
| `handler` | `SwaigHandler` | Yes | Called with `(args, rawData, agent)` when the tool runs |
|
|
1051
|
+
| `secure` | `boolean` | No | Requires a valid per-call token. Tools are secure unless this is `false`. |
|
|
1052
|
+
| `fillers` | `Record<string, string[]>` | No | Filler phrases by language code, spoken while the tool runs |
|
|
1053
|
+
| `wait_for_fillers` | `boolean` | No | Wait for fillers in progress to finish before the tool runs |
|
|
1054
|
+
| `skip_fillers` | `boolean` | No | Don't play fillers for this tool |
|
|
1055
|
+
| `isHangupHook` | `boolean` | No | Adds `is_hangup_hook: true` to the tool's SWAIG function definition |
|
|
1056
|
+
|
|
1057
|
+
To get typed `args` in a handler, wrap the definition in `defineSkillTool()`. It infers the argument types from `parameters` and `required`, and returns an ordinary `SkillToolDefinition`.
|
|
1058
|
+
|
|
1059
|
+
### SkillPromptSection Fields
|
|
1060
|
+
|
|
1061
|
+
A prompt section has these fields:
|
|
1062
|
+
|
|
1063
|
+
| Field | Type | Required | Description |
|
|
1064
|
+
|---|---|---|---|
|
|
1065
|
+
| `title` | `string` | Yes | Section heading |
|
|
1066
|
+
| `body` | `string` | No | Body text |
|
|
1067
|
+
| `bullets` | `string[]` | No | Bullet points after the body |
|
|
1068
|
+
| `numbered` | `boolean` | No | Render the bullets as a numbered list |
|
|
1069
|
+
|
|
1070
|
+
---
|
|
1071
|
+
|
|
1072
|
+
## Skill Lifecycle
|
|
1073
|
+
|
|
1074
|
+
A skill goes through these phases:
|
|
1075
|
+
|
|
1076
|
+
```text
|
|
1077
|
+
constructor -> addSkill() checks -> setup() -> registration -> tool calls -> cleanup()
|
|
1078
|
+
```
|
|
1079
|
+
|
|
1080
|
+
### 1. Construction
|
|
1081
|
+
|
|
1082
|
+
The constructor stores the configuration and moves `swaig_fields` out of it. It also sets the `instanceId` from the skill name, a timestamp and random bytes:
|
|
1083
|
+
|
|
1084
|
+
```typescript
|
|
1085
|
+
import { DateTimeSkill } from '@signalwire/sdk';
|
|
1086
|
+
|
|
1087
|
+
const skill = new DateTimeSkill();
|
|
1088
|
+
console.log(skill.skillName); // 'datetime'
|
|
1089
|
+
console.log(skill.isInitialized()); // false
|
|
1090
|
+
```
|
|
1091
|
+
|
|
1092
|
+
### 2. Setup
|
|
1093
|
+
|
|
1094
|
+
`agent.addSkill(skill)` sets the skill's `agent`, and the `SkillManager` runs the checks listed in [Using Skills](#agentaddskill). Then it awaits `setup()`, and marks the skill initialized when `setup()` returns `true`. This `setup()` refuses to load without a key:
|
|
1095
|
+
|
|
1096
|
+
<!-- snippet: no-compile illustrative bare method fragment (class body context) -->
|
|
1097
|
+
```typescript
|
|
1098
|
+
override async setup(): Promise<boolean> {
|
|
1099
|
+
const apiKey = this.getConfig<string>('api_key') ?? process.env['MY_API_KEY'];
|
|
1100
|
+
if (!apiKey) {
|
|
1101
|
+
this.logger.error('api_key or MY_API_KEY is required');
|
|
1102
|
+
return false;
|
|
1103
|
+
}
|
|
1104
|
+
this.client = await connectToService(apiKey);
|
|
1105
|
+
return true;
|
|
1106
|
+
}
|
|
1107
|
+
```
|
|
1108
|
+
|
|
1109
|
+
### 3. Registration
|
|
1110
|
+
|
|
1111
|
+
After setup, `AgentBase.addSkill()` registers what the skill contributes:
|
|
1112
|
+
|
|
1113
|
+
- Each tool from `getTools()` through `defineTool()`, with `swaig_fields` merged in
|
|
1114
|
+
- Each object from `getDataMapTools()` through `registerSwaigFunction()`
|
|
1115
|
+
- Each section from `getPromptSections()` through `promptAddSection()`
|
|
1116
|
+
- The hints from `getHints()` through `addHints()`
|
|
1117
|
+
- The data from `getGlobalData()` through `updateGlobalData()`
|
|
1118
|
+
|
|
1119
|
+
### 4. Active Use
|
|
1120
|
+
|
|
1121
|
+
The model calls the skill's tools during calls, and the skill instance stays in memory while it's loaded. A per-request copy of the agent, made for a dynamic config callback or `addPerCallConfig()`, shares the loaded skill instances without running `setup()` again.
|
|
1122
|
+
|
|
1123
|
+
### 5. Cleanup
|
|
1124
|
+
|
|
1125
|
+
`agent.removeSkill()` calls the skill's `cleanup()`, then removes it. `SkillManager.clear()` does the same for every loaded skill. This `cleanup()` closes a connection:
|
|
1126
|
+
|
|
1127
|
+
<!-- snippet: no-compile illustrative bare method fragment (class body context) -->
|
|
1128
|
+
```typescript
|
|
1129
|
+
override async cleanup(): Promise<void> {
|
|
1130
|
+
await this.client.disconnect();
|
|
1131
|
+
}
|
|
1132
|
+
```
|
|
1133
|
+
|
|
1134
|
+
Removing a skill doesn't unregister the tools, prompt sections, hints or global data it already added to the agent.
|
|
1135
|
+
|
|
1136
|
+
---
|
|
1137
|
+
|
|
1138
|
+
## Environment Validation
|
|
1139
|
+
|
|
1140
|
+
A skill lists the environment variables it needs in the static `REQUIRED_ENV_VARS`. The check runs when the skill is added, and a missing variable stops it from loading.
|
|
1141
|
+
|
|
1142
|
+
### Declaring Required Env Vars
|
|
1143
|
+
|
|
1144
|
+
This skill needs two variables:
|
|
1145
|
+
|
|
1146
|
+
```typescript
|
|
1147
|
+
import { SkillBase, type SkillToolDefinition } from '@signalwire/sdk';
|
|
1148
|
+
|
|
1149
|
+
export class MyApiSkill extends SkillBase {
|
|
1150
|
+
static override SKILL_NAME = 'my_api_skill';
|
|
1151
|
+
static override SKILL_DESCRIPTION = 'Integrates with My API.';
|
|
1152
|
+
static override REQUIRED_ENV_VARS = ['MY_API_KEY', 'MY_API_SECRET'] as const;
|
|
1153
|
+
|
|
1154
|
+
override getTools(): SkillToolDefinition[] {
|
|
1155
|
+
return [];
|
|
1156
|
+
}
|
|
1157
|
+
}
|
|
1158
|
+
```
|
|
1159
|
+
|
|
1160
|
+
### Automatic Validation
|
|
1161
|
+
|
|
1162
|
+
When a variable is missing, `addSkill()` rejects with `Cannot load skill '<name>': missing environment variables: <names>`, and the skill isn't added. `SkillManager.loadSkill()` and `loadSkillByName()` catch the error and resolve to `[false, message]` instead.
|
|
1163
|
+
|
|
1164
|
+
A variable in `REQUIRED_ENV_VARS` is required even when the skill also accepts the value as a parameter. For a key that can come from either, leave it out of `REQUIRED_ENV_VARS` and check both in `setup()`, as `web_search` does.
|
|
1165
|
+
|
|
1166
|
+
### Manual Validation
|
|
1167
|
+
|
|
1168
|
+
`validateEnvVars()` returns the names of the missing variables, and logs an error when there are any:
|
|
1169
|
+
|
|
1170
|
+
```typescript
|
|
1171
|
+
import { SkillBase } from '@signalwire/sdk';
|
|
1172
|
+
|
|
1173
|
+
class MyApiSkill extends SkillBase {
|
|
1174
|
+
static override SKILL_NAME = 'my_api_skill';
|
|
1175
|
+
static override SKILL_DESCRIPTION = 'Integrates with My API.';
|
|
1176
|
+
static override REQUIRED_ENV_VARS = ['MY_API_KEY', 'MY_API_SECRET'] as const;
|
|
1177
|
+
}
|
|
1178
|
+
|
|
1179
|
+
const skill = new MyApiSkill();
|
|
1180
|
+
const missing = skill.validateEnvVars();
|
|
1181
|
+
if (missing.length > 0) {
|
|
1182
|
+
console.warn(`Missing env vars: ${missing.join(', ')}`);
|
|
1183
|
+
}
|
|
1184
|
+
```
|
|
1185
|
+
|
|
1186
|
+
`hasAllEnvVars()` returns the same check as a boolean.
|
|
1187
|
+
|
|
1188
|
+
### Runtime Handling
|
|
1189
|
+
|
|
1190
|
+
Some built-in skills also check their credentials when a tool runs, and return a message the model can relay instead of throwing:
|
|
1191
|
+
|
|
1192
|
+
<!-- snippet: no-compile illustrative handler-body fragment (bare `return` outside a function) -->
|
|
1193
|
+
```typescript
|
|
1194
|
+
// Inside a tool handler
|
|
1195
|
+
const apiKey = this.getConfig<string | undefined>('api_key') ?? process.env['GOOGLE_MAPS_API_KEY'];
|
|
1196
|
+
if (!apiKey) {
|
|
1197
|
+
return new FunctionResult('Service is not configured. Please contact your administrator.');
|
|
1198
|
+
}
|
|
1199
|
+
```
|
|
1200
|
+
|
|
1201
|
+
---
|
|
1202
|
+
|
|
1203
|
+
## Environment Variables Reference
|
|
1204
|
+
|
|
1205
|
+
The built-in skills and the registry read these variables:
|
|
1206
|
+
|
|
1207
|
+
| Variable | Used by |
|
|
1208
|
+
|---|---|
|
|
1209
|
+
| `WEATHER_API_KEY` | `weather_api` (when `api_key` isn't set) |
|
|
1210
|
+
| `API_NINJAS_KEY` | `api_ninjas_trivia` (when `api_key` isn't set) |
|
|
1211
|
+
| `GOOGLE_SEARCH_API_KEY` | `web_search` (when `api_key` isn't set) |
|
|
1212
|
+
| `GOOGLE_SEARCH_ENGINE_ID`, `GOOGLE_SEARCH_CX` | `web_search` (when `search_engine_id` isn't set) |
|
|
1213
|
+
| `GOOGLE_MAPS_API_KEY` | `google_maps` (when `api_key` isn't set) |
|
|
1214
|
+
| `SIGNALWIRE_SPACE`, `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_API_TOKEN` | `datasphere` (when the matching parameter isn't set) |
|
|
1215
|
+
| `ANTHROPIC_API_KEY` | `ask_claude` (when `api_key` isn't set) |
|
|
1216
|
+
| `MCP_GATEWAY_AUTH_TOKEN`, `MCP_GATEWAY_AUTH_USER`, `MCP_GATEWAY_AUTH_PASSWORD` | `mcp_gateway` (when the matching parameter isn't set) |
|
|
1217
|
+
| `SWML_ALLOW_CUSTOM_HANDLER_CODE` | `custom_skills`: `true` lets `handler_code` run |
|
|
1218
|
+
| `SWML_ALLOW_PRIVATE_URLS` | `spider`, `web_search`, `native_vector_search` and `mcp_gateway`: `1`, `true` or `yes` allows private and internal addresses |
|
|
1219
|
+
| `SWML_URL_FETCH_USE_PROXY` | `spider` and `web_search`: lets page fetches use the environment's proxy |
|
|
1220
|
+
| `SWML_SKILL_DISCOVERY_ENABLED` | `SkillRegistry`: `true` allows directory discovery |
|
|
1221
|
+
| `SIGNALWIRE_SKILL_PATHS` | `SkillRegistry`: colon-separated discovery paths |
|
|
1222
|
+
|
|
1223
|
+
The SDK's own tests set `WEATHER_API_BASE_URL`, `API_NINJAS_BASE_URL`, `WEB_SEARCH_BASE_URL`, `WIKIPEDIA_BASE_URL`, `DATASPHERE_BASE_URL` and `SPIDER_BASE_URL` to send requests to a local server. Leave them unset in production. `SPIDER_BASE_URL` sends every spider request to that server without the private-address check.
|