@signalwire/sdk 2.0.5 → 3.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +821 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +510 -126
- package/dist/AgentBase.js +1581 -455
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +21 -0
- package/dist/AgentServer.js +154 -47
- package/dist/AgentServer.js.map +1 -1
- package/dist/AuthHandler.d.ts +14 -2
- package/dist/AuthHandler.js +7 -2
- package/dist/AuthHandler.js.map +1 -1
- package/dist/ConfigLoader.d.ts +5 -13
- package/dist/ConfigLoader.js +15 -29
- package/dist/ConfigLoader.js.map +1 -1
- package/dist/ContextBuilder.d.ts +202 -9
- package/dist/ContextBuilder.js +219 -36
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/DataMap.d.ts +186 -45
- package/dist/DataMap.js +210 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +309 -83
- package/dist/FunctionResult.js +483 -116
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +30 -5
- package/dist/Logger.js +77 -19
- package/dist/Logger.js.map +1 -1
- package/dist/POM/PromptObjectModel.d.ts +12 -1
- package/dist/POM/PromptObjectModel.js +25 -9
- package/dist/POM/PromptObjectModel.js.map +1 -1
- package/dist/ParameterSchema.d.ts +306 -0
- package/dist/ParameterSchema.js +251 -0
- package/dist/ParameterSchema.js.map +1 -0
- package/dist/PlatformContracts.d.ts +21 -0
- package/dist/PlatformContracts.generated.d.ts +109 -0
- package/dist/PlatformContracts.generated.js +8 -0
- package/dist/PlatformContracts.generated.js.map +1 -0
- package/dist/PlatformContracts.js +2 -0
- package/dist/PlatformContracts.js.map +1 -0
- package/dist/PomBuilder.d.ts +18 -0
- package/dist/PomBuilder.js +53 -3
- package/dist/PomBuilder.js.map +1 -1
- package/dist/PostPrompt.d.ts +110 -0
- package/dist/PostPrompt.js +204 -0
- package/dist/PostPrompt.js.map +1 -0
- package/dist/PromptManager.d.ts +22 -1
- package/dist/PromptManager.js +28 -1
- package/dist/PromptManager.js.map +1 -1
- package/dist/PublicFetch.d.ts +132 -0
- package/dist/PublicFetch.js +311 -0
- package/dist/PublicFetch.js.map +1 -0
- package/dist/RobotsTxt.d.ts +41 -0
- package/dist/RobotsTxt.js +152 -0
- package/dist/RobotsTxt.js.map +1 -0
- package/dist/SWMLHandler.js.map +1 -1
- package/dist/SWMLService.d.ts +169 -59
- package/dist/SWMLService.js +456 -129
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.d.ts +115 -2
- package/dist/SchemaUtils.js +444 -12
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SecurityUtils.d.ts +49 -9
- package/dist/SecurityUtils.js +153 -51
- package/dist/SecurityUtils.js.map +1 -1
- package/dist/SemanticGate.d.ts +183 -0
- package/dist/SemanticGate.js +533 -0
- package/dist/SemanticGate.js.map +1 -0
- package/dist/ServerlessAdapter.d.ts +156 -7
- package/dist/ServerlessAdapter.js +399 -42
- package/dist/ServerlessAdapter.js.map +1 -1
- package/dist/SessionManager.d.ts +11 -2
- package/dist/SessionManager.js +50 -18
- package/dist/SessionManager.js.map +1 -1
- package/dist/SslConfig.d.ts +2 -1
- package/dist/SslConfig.js +4 -1
- package/dist/SslConfig.js.map +1 -1
- package/dist/SwaigActions.generated.d.ts +23 -0
- package/dist/SwaigActions.generated.js +8 -0
- package/dist/SwaigActions.generated.js.map +1 -0
- package/dist/SwaigContracts.d.ts +15 -0
- package/dist/SwaigContracts.generated.d.ts +264 -0
- package/dist/SwaigContracts.generated.js +12 -0
- package/dist/SwaigContracts.generated.js.map +1 -0
- package/dist/SwaigContracts.js +2 -0
- package/dist/SwaigContracts.js.map +1 -0
- package/dist/SwaigFunction.d.ts +139 -7
- package/dist/SwaigFunction.js +170 -22
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/SwmlBuilder.d.ts +68 -19
- package/dist/SwmlBuilder.js +74 -38
- package/dist/SwmlBuilder.js.map +1 -1
- package/dist/SwmlVerbMethods.generated.d.ts +41 -4
- package/dist/SwmlVerbMethods.generated.js +1 -1
- package/dist/TypeInference.d.ts +39 -3
- package/dist/TypeInference.js +256 -16
- package/dist/TypeInference.js.map +1 -1
- package/dist/WebService.d.ts +79 -11
- package/dist/WebService.js +320 -109
- package/dist/WebService.js.map +1 -1
- package/dist/WebhookMiddleware.d.ts +119 -0
- package/dist/WebhookMiddleware.js +271 -0
- package/dist/WebhookMiddleware.js.map +1 -0
- package/dist/WebhookValidator.d.ts +92 -0
- package/dist/WebhookValidator.js +409 -0
- package/dist/WebhookValidator.js.map +1 -0
- package/dist/agents/BedrockAgent.d.ts +162 -0
- package/dist/agents/BedrockAgent.js +323 -0
- package/dist/agents/BedrockAgent.js.map +1 -0
- package/dist/ai-chat/AIChatClient.d.ts +316 -0
- package/dist/ai-chat/AIChatClient.js +535 -0
- package/dist/ai-chat/AIChatClient.js.map +1 -0
- package/dist/ai-chat/ChatGateway.d.ts +408 -0
- package/dist/ai-chat/ChatGateway.js +747 -0
- package/dist/ai-chat/ChatGateway.js.map +1 -0
- package/dist/ai-chat/HandoffRouter.d.ts +282 -0
- package/dist/ai-chat/HandoffRouter.js +518 -0
- package/dist/ai-chat/HandoffRouter.js.map +1 -0
- package/dist/ai-chat/index.d.ts +12 -0
- package/dist/ai-chat/index.js +10 -0
- package/dist/ai-chat/index.js.map +1 -0
- package/dist/capabilities.d.ts +64 -0
- package/dist/capabilities.js +95 -0
- package/dist/capabilities.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +32 -6
- package/dist/cli/agent-loader.js +92 -33
- package/dist/cli/agent-loader.js.map +1 -1
- package/dist/cli/datamap-exec.d.ts +175 -0
- package/dist/cli/datamap-exec.js +1284 -0
- package/dist/cli/datamap-exec.js.map +1 -0
- package/dist/cli/function-args.d.ts +40 -0
- package/dist/cli/function-args.js +146 -0
- package/dist/cli/function-args.js.map +1 -0
- package/dist/cli/simulation.d.ts +99 -0
- package/dist/cli/simulation.js +490 -0
- package/dist/cli/simulation.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +12 -25
- package/dist/cli/swaig-test.js +935 -371
- package/dist/cli/swaig-test.js.map +1 -1
- package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
- package/dist/cli/tsdocs/agentsNote.js +92 -0
- package/dist/cli/tsdocs/agentsNote.js.map +1 -0
- package/dist/cli/tsdocs/api-index.json +1 -0
- package/dist/cli/tsdocs/api.d.ts +91 -0
- package/dist/cli/tsdocs/api.js +372 -0
- package/dist/cli/tsdocs/api.js.map +1 -0
- package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
- package/dist/cli/tsdocs/apiTypes.js +7 -0
- package/dist/cli/tsdocs/apiTypes.js.map +1 -0
- package/dist/cli/tsdocs/bin.d.ts +6 -0
- package/dist/cli/tsdocs/bin.js +23 -0
- package/dist/cli/tsdocs/bin.js.map +1 -0
- package/dist/cli/tsdocs/files.d.ts +108 -0
- package/dist/cli/tsdocs/files.js +287 -0
- package/dist/cli/tsdocs/files.js.map +1 -0
- package/dist/cli/tsdocs/index.d.ts +28 -0
- package/dist/cli/tsdocs/index.js +307 -0
- package/dist/cli/tsdocs/index.js.map +1 -0
- package/dist/cli/tsdocs/live.d.ts +41 -0
- package/dist/cli/tsdocs/live.js +202 -0
- package/dist/cli/tsdocs/live.js.map +1 -0
- package/dist/cli/tsdocs/locate.d.ts +51 -0
- package/dist/cli/tsdocs/locate.js +75 -0
- package/dist/cli/tsdocs/locate.js.map +1 -0
- package/dist/cli/tsdocs/render.d.ts +75 -0
- package/dist/cli/tsdocs/render.js +323 -0
- package/dist/cli/tsdocs/render.js.map +1 -0
- package/dist/cli/tsdocs/topics.d.ts +43 -0
- package/dist/cli/tsdocs/topics.js +920 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +49 -68
- package/dist/index.js +45 -73
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +229 -155
- package/dist/livewire/index.js +298 -195
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +65 -0
- package/dist/prefabs/CallSessionStore.d.ts +52 -0
- package/dist/prefabs/CallSessionStore.js +72 -0
- package/dist/prefabs/CallSessionStore.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +13 -1
- package/dist/prefabs/ConciergeAgent.js +36 -31
- package/dist/prefabs/ConciergeAgent.js.map +1 -1
- package/dist/prefabs/FAQBotAgent.d.ts +9 -1
- package/dist/prefabs/FAQBotAgent.js +113 -47
- package/dist/prefabs/FAQBotAgent.js.map +1 -1
- package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
- package/dist/prefabs/InfoGathererAgent.js +67 -58
- package/dist/prefabs/InfoGathererAgent.js.map +1 -1
- package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
- package/dist/prefabs/ReceptionistAgent.js +39 -31
- package/dist/prefabs/ReceptionistAgent.js.map +1 -1
- package/dist/prefabs/SurveyAgent.d.ts +22 -4
- package/dist/prefabs/SurveyAgent.js +84 -68
- package/dist/prefabs/SurveyAgent.js.map +1 -1
- package/dist/relay/Action.d.ts +44 -21
- package/dist/relay/Action.js +75 -17
- package/dist/relay/Action.js.map +1 -1
- package/dist/relay/Call.d.ts +312 -47
- package/dist/relay/Call.js +369 -18
- package/dist/relay/Call.js.map +1 -1
- package/dist/relay/Deferred.js.map +1 -1
- package/dist/relay/Message.d.ts +26 -5
- package/dist/relay/Message.js +36 -6
- package/dist/relay/Message.js.map +1 -1
- package/dist/relay/RelayClient.d.ts +44 -17
- package/dist/relay/RelayClient.js +175 -65
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayError.d.ts +14 -0
- package/dist/relay/RelayError.js +15 -0
- package/dist/relay/RelayError.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +96 -65
- package/dist/relay/RelayEvent.js +85 -56
- package/dist/relay/RelayEvent.js.map +1 -1
- package/dist/relay/closedSets.d.ts +111 -0
- package/dist/relay/closedSets.js +83 -0
- package/dist/relay/closedSets.js.map +1 -0
- package/dist/relay/index.d.ts +3 -1
- package/dist/relay/index.js +1 -0
- package/dist/relay/index.js.map +1 -1
- package/dist/relay/normalize.js.map +1 -1
- package/dist/relay/protocol.types.generated.d.ts +1195 -0
- package/dist/relay/protocol.types.generated.js +8 -0
- package/dist/relay/protocol.types.generated.js.map +1 -0
- package/dist/relay/types.d.ts +73 -42
- package/dist/rest/HttpClient.d.ts +36 -8
- package/dist/rest/HttpClient.js +233 -40
- package/dist/rest/HttpClient.js.map +1 -1
- package/dist/rest/RequestOptions.d.ts +110 -0
- package/dist/rest/RequestOptions.js +113 -0
- package/dist/rest/RequestOptions.js.map +1 -0
- package/dist/rest/RestError.d.ts +52 -6
- package/dist/rest/RestError.js +89 -5
- package/dist/rest/RestError.js.map +1 -1
- package/dist/rest/base/CrudResource.d.ts +16 -26
- package/dist/rest/base/CrudResource.js +19 -33
- package/dist/rest/base/CrudResource.js.map +1 -1
- package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
- package/dist/rest/base/CrudWithAddresses.js +2 -2
- package/dist/rest/base/CrudWithAddresses.js.map +1 -1
- package/dist/rest/base/FabricResource.d.ts +15 -0
- package/dist/rest/base/FabricResource.js +16 -0
- package/dist/rest/base/FabricResource.js.map +1 -0
- package/dist/rest/base/ReadResource.d.ts +62 -0
- package/dist/rest/base/ReadResource.js +69 -0
- package/dist/rest/base/ReadResource.js.map +1 -0
- package/dist/rest/callHandler.d.ts +5 -2
- package/dist/rest/callHandler.js +4 -1
- package/dist/rest/callHandler.js.map +1 -1
- package/dist/rest/index.d.ts +18 -77
- package/dist/rest/index.js +47 -120
- package/dist/rest/index.js.map +1 -1
- package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
- package/dist/rest/namespaces/_client_tree_generated.js +171 -0
- package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +3 -42
- package/dist/rest/namespaces/addresses.js +3 -50
- package/dist/rest/namespaces/addresses.js.map +1 -1
- package/dist/rest/namespaces/calling.d.ts +6 -378
- package/dist/rest/namespaces/calling.js +6 -473
- package/dist/rest/namespaces/calling.js.map +1 -1
- package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
- package/dist/rest/namespaces/calling.resources.generated.js +477 -0
- package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
- package/dist/rest/namespaces/calling.types.generated.js +8 -0
- package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +4 -18
- package/dist/rest/namespaces/chat.js +4 -21
- package/dist/rest/namespaces/chat.js.map +1 -1
- package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/chat.resources.generated.js +29 -0
- package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
- package/dist/rest/namespaces/chat.types.generated.js +8 -0
- package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +6 -62
- package/dist/rest/namespaces/datasphere.js +6 -72
- package/dist/rest/namespaces/datasphere.js.map +1 -1
- package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
- package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
- package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +11 -327
- package/dist/rest/namespaces/fabric.js +14 -439
- package/dist/rest/namespaces/fabric.js.map +1 -1
- package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
- package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
- package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
- package/dist/rest/namespaces/fabric.types.generated.js +8 -0
- package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/fax.resources.generated.js +14 -0
- package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/fax.types.generated.js +8 -0
- package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
- package/dist/rest/namespaces/imported-numbers.js +3 -21
- package/dist/rest/namespaces/imported-numbers.js.map +1 -1
- package/dist/rest/namespaces/logs.d.ts +10 -101
- package/dist/rest/namespaces/logs.js +10 -128
- package/dist/rest/namespaces/logs.js.map +1 -1
- package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/logs.resources.generated.js +17 -0
- package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/logs.types.generated.js +8 -0
- package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +3 -25
- package/dist/rest/namespaces/lookup.js +3 -27
- package/dist/rest/namespaces/lookup.js.map +1 -1
- package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/message.resources.generated.js +14 -0
- package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
- package/dist/rest/namespaces/message.types.generated.js +8 -0
- package/dist/rest/namespaces/message.types.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
- package/dist/rest/namespaces/messages.resources.generated.js +44 -0
- package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
- package/dist/rest/namespaces/messages.types.generated.js +8 -0
- package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +3 -42
- package/dist/rest/namespaces/mfa.js +3 -49
- package/dist/rest/namespaces/mfa.js.map +1 -1
- package/dist/rest/namespaces/number-groups.d.ts +3 -45
- package/dist/rest/namespaces/number-groups.js +3 -53
- package/dist/rest/namespaces/number-groups.js.map +1 -1
- package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
- package/dist/rest/namespaces/phone-numbers.js +8 -230
- package/dist/rest/namespaces/phone-numbers.js.map +1 -1
- package/dist/rest/namespaces/project.d.ts +6 -42
- package/dist/rest/namespaces/project.js +6 -51
- package/dist/rest/namespaces/project.js.map +1 -1
- package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
- package/dist/rest/namespaces/project.resources.generated.js +44 -0
- package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
- package/dist/rest/namespaces/project.types.generated.js +8 -0
- package/dist/rest/namespaces/project.types.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/projects.resources.generated.js +25 -0
- package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
- package/dist/rest/namespaces/projects.types.generated.js +8 -0
- package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +4 -18
- package/dist/rest/namespaces/pubsub.js +4 -21
- package/dist/rest/namespaces/pubsub.js.map +1 -1
- package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
- package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
- package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +3 -38
- package/dist/rest/namespaces/queues.js +3 -44
- package/dist/rest/namespaces/queues.js.map +1 -1
- package/dist/rest/namespaces/recordings.d.ts +3 -34
- package/dist/rest/namespaces/recordings.js +3 -40
- package/dist/rest/namespaces/recordings.js.map +1 -1
- package/dist/rest/namespaces/registry.d.ts +6 -137
- package/dist/rest/namespaces/registry.js +6 -173
- package/dist/rest/namespaces/registry.js.map +1 -1
- package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +3 -35
- package/dist/rest/namespaces/short-codes.js +3 -41
- package/dist/rest/namespaces/short-codes.js.map +1 -1
- package/dist/rest/namespaces/sip-profile.d.ts +3 -24
- package/dist/rest/namespaces/sip-profile.js +3 -29
- package/dist/rest/namespaces/sip-profile.js.map +1 -1
- package/dist/rest/namespaces/verified-callers.d.ts +3 -29
- package/dist/rest/namespaces/verified-callers.js +3 -34
- package/dist/rest/namespaces/verified-callers.js.map +1 -1
- package/dist/rest/namespaces/video.d.ts +10 -227
- package/dist/rest/namespaces/video.js +10 -288
- package/dist/rest/namespaces/video.js.map +1 -1
- package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
- package/dist/rest/namespaces/video.resources.generated.js +171 -0
- package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
- package/dist/rest/namespaces/video.types.generated.js +8 -0
- package/dist/rest/namespaces/video.types.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/voice.resources.generated.js +17 -0
- package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
- package/dist/rest/namespaces/voice.types.generated.js +8 -0
- package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
- package/dist/rest/pagination.d.ts +5 -1
- package/dist/rest/pagination.js +40 -20
- package/dist/rest/pagination.js.map +1 -1
- package/dist/rest/types.d.ts +21 -3
- package/dist/schema.json +299 -98
- package/dist/skills/SkillBase.d.ts +111 -21
- package/dist/skills/SkillBase.js +100 -17
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/skills/SkillManager.d.ts +66 -13
- package/dist/skills/SkillManager.js +101 -20
- package/dist/skills/SkillManager.js.map +1 -1
- package/dist/skills/SkillName.d.ts +44 -0
- package/dist/skills/SkillName.js +2 -0
- package/dist/skills/SkillName.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +22 -11
- package/dist/skills/SkillRegistry.js +47 -17
- package/dist/skills/SkillRegistry.js.map +1 -1
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
- package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
- package/dist/skills/builtin/ask_claude.d.ts +14 -4
- package/dist/skills/builtin/ask_claude.js +36 -14
- package/dist/skills/builtin/ask_claude.js.map +1 -1
- package/dist/skills/builtin/claude_skills.d.ts +3 -1
- package/dist/skills/builtin/claude_skills.js +19 -15
- package/dist/skills/builtin/claude_skills.js.map +1 -1
- package/dist/skills/builtin/custom_skills.d.ts +10 -3
- package/dist/skills/builtin/custom_skills.js +26 -9
- package/dist/skills/builtin/custom_skills.js.map +1 -1
- package/dist/skills/builtin/datasphere.d.ts +5 -3
- package/dist/skills/builtin/datasphere.js +21 -22
- package/dist/skills/builtin/datasphere.js.map +1 -1
- package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
- package/dist/skills/builtin/datasphere_serverless.js +17 -6
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
- package/dist/skills/builtin/datetime.d.ts +3 -1
- package/dist/skills/builtin/datetime.js +11 -7
- package/dist/skills/builtin/datetime.js.map +1 -1
- package/dist/skills/builtin/google_maps.d.ts +29 -14
- package/dist/skills/builtin/google_maps.js +89 -269
- package/dist/skills/builtin/google_maps.js.map +1 -1
- package/dist/skills/builtin/index.d.ts +8 -6
- package/dist/skills/builtin/index.js +8 -6
- package/dist/skills/builtin/index.js.map +1 -1
- package/dist/skills/builtin/info_gatherer.d.ts +4 -2
- package/dist/skills/builtin/info_gatherer.js +20 -12
- package/dist/skills/builtin/info_gatherer.js.map +1 -1
- package/dist/skills/builtin/joke.d.ts +16 -6
- package/dist/skills/builtin/joke.js +54 -37
- package/dist/skills/builtin/joke.js.map +1 -1
- package/dist/skills/builtin/math.d.ts +3 -1
- package/dist/skills/builtin/math.js +14 -9
- package/dist/skills/builtin/math.js.map +1 -1
- package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
- package/dist/skills/builtin/mcp_gateway.js +77 -46
- package/dist/skills/builtin/mcp_gateway.js.map +1 -1
- package/dist/skills/builtin/native_vector_search.d.ts +19 -5
- package/dist/skills/builtin/native_vector_search.js +179 -61
- package/dist/skills/builtin/native_vector_search.js.map +1 -1
- package/dist/skills/builtin/play_background_file.d.ts +21 -15
- package/dist/skills/builtin/play_background_file.js +43 -122
- package/dist/skills/builtin/play_background_file.js.map +1 -1
- package/dist/skills/builtin/spider.d.ts +42 -4
- package/dist/skills/builtin/spider.js +277 -104
- package/dist/skills/builtin/spider.js.map +1 -1
- package/dist/skills/builtin/swml_transfer.d.ts +14 -3
- package/dist/skills/builtin/swml_transfer.js +45 -24
- package/dist/skills/builtin/swml_transfer.js.map +1 -1
- package/dist/skills/builtin/weather_api.d.ts +24 -13
- package/dist/skills/builtin/weather_api.js +38 -30
- package/dist/skills/builtin/weather_api.js.map +1 -1
- package/dist/skills/builtin/web_search.d.ts +48 -10
- package/dist/skills/builtin/web_search.js +294 -100
- package/dist/skills/builtin/web_search.js.map +1 -1
- package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
- package/dist/skills/builtin/wikipedia_search.js +14 -13
- package/dist/skills/builtin/wikipedia_search.js.map +1 -1
- package/dist/skills/index.d.ts +3 -2
- package/dist/skills/index.js +1 -1
- package/dist/skills/index.js.map +1 -1
- package/dist/swml_verbs_generated.d.ts +2824 -0
- package/dist/swml_verbs_generated.js +12 -0
- package/dist/swml_verbs_generated.js.map +1 -0
- package/dist/types.d.ts +59 -6
- package/dist/web.d.ts +27 -0
- package/dist/web.js +20 -0
- package/dist/web.js.map +1 -0
- package/docs/agent-guide.md +1034 -0
- package/docs/ai_chat.md +560 -0
- package/docs/api-reference.md +3641 -0
- package/docs/architecture.md +846 -0
- package/docs/bedrock_agent.md +411 -0
- package/docs/cli-guide.md +403 -0
- package/docs/cloud_functions_guide.md +399 -0
- package/docs/configuration.md +548 -0
- package/docs/contexts-guide.md +884 -0
- package/docs/datamap-guide.md +1207 -0
- package/docs/developer_pain_points.md +548 -0
- package/docs/llm_parameters.md +298 -0
- package/docs/mcp_gateway_reference.md +354 -0
- package/docs/mcp_integration.md +162 -0
- package/docs/pgi_agent_guide.md +1820 -0
- package/docs/prefabs-guide.md +815 -0
- package/docs/programmatically_governed_inference.md +301 -0
- package/docs/sdk_features.md +501 -0
- package/docs/security.md +559 -0
- package/docs/serverless-guide.md +520 -0
- package/docs/skills-guide.md +1223 -0
- package/docs/skills-system.md +405 -0
- package/docs/skills_parameter_schema.md +417 -0
- package/docs/swaig-reference.md +1986 -0
- package/docs/swml_service_guide.md +573 -0
- package/docs/third_party_skills.md +410 -0
- package/docs/web_service.md +666 -0
- package/examples/README.md +202 -0
- package/examples/advanced-datamap.ts +108 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +95 -0
- package/examples/call-flow.ts +65 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +51 -0
- package/examples/datasphere-multi-instance.ts +66 -0
- package/examples/datasphere-serverless-env.ts +87 -0
- package/examples/datasphere-webhook-env.ts +65 -0
- package/examples/datasphere.ts +56 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +95 -0
- package/examples/gather-per-question-functions-demo.ts +139 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +75 -0
- package/examples/mcp-agent.ts +89 -0
- package/examples/mcp-gateway.ts +81 -0
- package/examples/multi-agent.ts +80 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pgi/case-domain.ts +114 -0
- package/examples/pgi/serve.ts +16 -0
- package/examples/pgi/support-agent.ts +265 -0
- package/examples/pom-prompt.ts +70 -0
- package/examples/prefab-concierge.ts +42 -0
- package/examples/prefab-faq.ts +58 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +69 -0
- package/examples/quickstart-agent.ts +29 -0
- package/examples/quickstart-relay.ts +25 -0
- package/examples/quickstart-rest.ts +25 -0
- package/examples/record-call.ts +65 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +93 -0
- package/examples/serverless-lambda.ts +43 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +41 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +193 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/swmlservice_ai_sidecar.ts +104 -0
- package/examples/swmlservice_swaig_standalone.ts +79 -0
- package/examples/tap.ts +67 -0
- package/examples/typed-tools.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +75 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +164 -0
- package/livewire/docs/migration-guide.md +251 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +196 -0
- package/livewire/examples/livewire-multi-tool.ts +121 -0
- package/package.json +85 -13
- package/relay/README.md +101 -0
- package/relay/docs/call-methods.md +622 -0
- package/relay/docs/client-reference.md +281 -0
- package/relay/docs/events.md +193 -0
- package/relay/docs/getting-started.md +221 -0
- package/relay/docs/guide.md +386 -0
- package/relay/docs/messaging.md +246 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +74 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +141 -0
- package/rest/docs/calling.md +313 -0
- package/rest/docs/client-reference.md +149 -0
- package/rest/docs/fabric.md +192 -0
- package/rest/docs/getting-started.md +138 -0
- package/rest/docs/guide.md +421 -0
- package/rest/docs/namespaces.md +367 -0
- package/rest/docs/phone-binding.md +116 -0
- package/rest/examples/rest-10dlc-registration.ts +177 -0
- package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
- package/rest/examples/rest-calling-play-and-record.ts +98 -0
- package/rest/examples/rest-client.ts +59 -0
- package/rest/examples/rest-datasphere-search.ts +81 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
- package/rest/examples/rest-manage-resources.ts +64 -0
- package/rest/examples/rest-phone-number-management.ts +200 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/tutorial/fred/fred.ts +218 -0
- package/tutorial/fred/tutorial/01-introduction.md +141 -0
- package/tutorial/fred/tutorial/02-setup.md +304 -0
- package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
- package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
- package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
- package/tutorial/fred/tutorial/06-running-testing.md +642 -0
- package/tutorial/fred/tutorial/README.md +56 -0
- package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
- package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
- package/tutorial/full-guardrails-agent/handlers.ts +436 -0
- package/tutorial/full-guardrails-agent/penny.ts +305 -0
- package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
- package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
- package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
- package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
- package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
- package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
- package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
- package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
- package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
- package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
- package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
- package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
- package/tutorial/full-guardrails-agent/workflow.ts +219 -0
- package/tutorial/multi_agents/README.md +175 -0
- package/tutorial/multi_agents/advanced_agent.ts +395 -0
- package/tutorial/multi_agents/extending_agents.ts +641 -0
- package/tutorial/multi_agents/knowledge.ts +59 -0
- package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
- package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
- package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
- package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
- package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
- package/tutorial/multi_agents/pc_builder.ts +529 -0
- package/tutorial/multi_agents/sales_agent.ts +88 -0
- package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
- package/tutorial/multi_agents/sales_knowledge.md +139 -0
- package/tutorial/multi_agents/support_knowledge.md +256 -0
- package/dist/cli/mock-data.d.ts +0 -37
- package/dist/cli/mock-data.js +0 -80
- package/dist/cli/mock-data.js.map +0 -1
- package/dist/generateVerbTypes.d.ts +0 -11
- package/dist/generateVerbTypes.js +0 -265
- package/dist/generateVerbTypes.js.map +0 -1
- package/dist/rest/namespaces/compat.d.ts +0 -585
- package/dist/rest/namespaces/compat.js +0 -735
- package/dist/rest/namespaces/compat.js.map +0 -1
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
# LLM Parameters Guide
|
|
2
|
+
|
|
3
|
+
This guide covers the LLM parameters of a SignalWire AI agent's main prompt and post-prompt, and how to set them with the TypeScript SDK.
|
|
4
|
+
|
|
5
|
+
<!-- snippet-setup -->
|
|
6
|
+
```ts
|
|
7
|
+
export {}; // treat each example as a module (top-level await)
|
|
8
|
+
declare global {
|
|
9
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
10
|
+
const AgentBase: typeof import('@signalwire/sdk').AgentBase; // used with `extends`
|
|
11
|
+
}
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Overview
|
|
15
|
+
|
|
16
|
+
The SDK has one method for the main prompt's LLM parameters and one for the post-prompt's. The SDK writes the parameters into the SWML `prompt` and `post_prompt` objects, next to the prompt text.
|
|
17
|
+
|
|
18
|
+
**Important:** The SDK doesn't validate these parameters. It passes every key and value through to SignalWire unchanged, so a misspelled key or an out-of-range value reaches the platform as written.
|
|
19
|
+
|
|
20
|
+
## Available Methods
|
|
21
|
+
|
|
22
|
+
### `setPromptLlmParams(params)`
|
|
23
|
+
|
|
24
|
+
`setPromptLlmParams()` merges parameters into the main prompt:
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
agent.setPromptLlmParams({
|
|
28
|
+
temperature: 0.7,
|
|
29
|
+
top_p: 0.9,
|
|
30
|
+
presence_penalty: 0.0,
|
|
31
|
+
frequency_penalty: 0.0,
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### `setPostPromptLlmParams(params)`
|
|
36
|
+
|
|
37
|
+
`setPostPromptLlmParams()` merges parameters into the post-prompt, which produces the call summary:
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
agent.setPostPromptLlmParams({
|
|
41
|
+
temperature: 0.3,
|
|
42
|
+
top_p: 0.95,
|
|
43
|
+
presence_penalty: 0.0,
|
|
44
|
+
frequency_penalty: 0.0,
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Both methods merge into the parameters already set, so you can call them more than once. A later value for the same key replaces the earlier one.
|
|
49
|
+
|
|
50
|
+
The prompt objects are separate from the `ai` verb's `params`, which `setParam()` and `setParams()` set. `temperature` and the other keys in this guide belong in the prompt objects.
|
|
51
|
+
|
|
52
|
+
## Parameter Reference
|
|
53
|
+
|
|
54
|
+
The SWML schema defines these parameters for both `prompt` and `post_prompt`. The ranges and defaults come from the schema bundled with the SDK (`src/schema.json`):
|
|
55
|
+
|
|
56
|
+
| Parameter | Type | Range | Default | Description |
|
|
57
|
+
|---|---|---|---|---|
|
|
58
|
+
| `temperature` | number | 0.0 to 1.5 | 1.0 | Randomness. Values closer to 0 make the output less random. |
|
|
59
|
+
| `top_p` | number | 0.0 to 1.0 | 1.0 | Nucleus sampling, an alternative to `temperature`. Values closer to 0 make the output less random. |
|
|
60
|
+
| `presence_penalty` | number | -2.0 to 2.0 | 0 | Aversion to staying on a topic. Positive values make new topics more likely. |
|
|
61
|
+
| `frequency_penalty` | number | -2.0 to 2.0 | 0 | Aversion to repeating lines. Positive values make verbatim repetition less likely. |
|
|
62
|
+
| `confidence` | number | 0.0 to 1.0 | 0.6 | Threshold for the speech-detect event at the end of an utterance. Lower values shorten the pause after the caller speaks, and can add false positives. |
|
|
63
|
+
| `max_tokens` | integer | 0 to 4096 | 256 | Limit on the tokens the model may generate for a response. |
|
|
64
|
+
|
|
65
|
+
The defaults are the platform's. The SDK sends a parameter only when you set it.
|
|
66
|
+
|
|
67
|
+
### temperature
|
|
68
|
+
|
|
69
|
+
`temperature` controls how random the responses are. These ranges are guidance, not rules:
|
|
70
|
+
|
|
71
|
+
- **Lower values (for example, 0.0 to 0.3)**: more deterministic and consistent responses
|
|
72
|
+
- **Middle values (for example, 0.4 to 0.7)**: a balance of variety and consistency
|
|
73
|
+
- **Higher values (for example, 0.8 and up)**: more varied and less predictable responses
|
|
74
|
+
|
|
75
|
+
### top_p
|
|
76
|
+
|
|
77
|
+
`top_p` limits token selection to the most likely tokens whose probabilities add up to the value:
|
|
78
|
+
|
|
79
|
+
- **Lower values (for example, 0.1 to 0.5)**: only the most likely tokens
|
|
80
|
+
- **Middle values (for example, 0.6 to 0.9)**: a balanced selection
|
|
81
|
+
- **Higher values (for example, 0.95 to 1.0)**: a wider range of tokens
|
|
82
|
+
|
|
83
|
+
### presence_penalty
|
|
84
|
+
|
|
85
|
+
`presence_penalty` penalizes tokens that already appear in the conversation:
|
|
86
|
+
|
|
87
|
+
- **Negative values**: encourage returning to the same topics
|
|
88
|
+
- **Zero**: no penalty
|
|
89
|
+
- **Positive values**: discourage repetition, and encourage new topics
|
|
90
|
+
|
|
91
|
+
### frequency_penalty
|
|
92
|
+
|
|
93
|
+
`frequency_penalty` penalizes tokens by how often they appear in the conversation:
|
|
94
|
+
|
|
95
|
+
- **Negative values**: encourage repeating the same words
|
|
96
|
+
- **Zero**: no penalty
|
|
97
|
+
- **Positive values**: discourage word repetition
|
|
98
|
+
|
|
99
|
+
### Interruption
|
|
100
|
+
|
|
101
|
+
How easily the caller can interrupt the AI isn't an LLM parameter. `barge_confidence` isn't in the SWML schema's `prompt` object, so a document that sets it there fails validation against the SWML schema, and the platform doesn't apply it. Tune interruption with these AI params, through `setParam()`:
|
|
102
|
+
|
|
103
|
+
- **`barge_min_words`** (1 to 99): how many words the caller must say before the AI stops speaking. Higher values make the AI harder to interrupt.
|
|
104
|
+
- **`enable_barge`**: which barge modes are on: `"complete"`, `"partial"`, `"all"`, or a boolean. `false` turns barge-in off.
|
|
105
|
+
- **`barge_match_string`**: a string or regular expression that interrupts the AI when the caller says it.
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
agent.setParam('barge_min_words', 3); // Let the AI finish unless the caller says 3 or more words
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Use Case Examples
|
|
112
|
+
|
|
113
|
+
### Customer Service Agent
|
|
114
|
+
|
|
115
|
+
A low temperature and a small penalty keep the responses consistent:
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
import { AgentBase } from '@signalwire/sdk';
|
|
119
|
+
|
|
120
|
+
class CustomerServiceAgent extends AgentBase {
|
|
121
|
+
constructor() {
|
|
122
|
+
super({ name: 'customer-service', route: '/support' });
|
|
123
|
+
|
|
124
|
+
this.promptAddSection('Role', {
|
|
125
|
+
body: 'You are a professional customer service representative.',
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
// Consistent, helpful responses
|
|
129
|
+
this.setPromptLlmParams({
|
|
130
|
+
temperature: 0.3, // Low randomness for consistency
|
|
131
|
+
top_p: 0.9, // Focused token selection
|
|
132
|
+
presence_penalty: 0.1, // Slight penalty to avoid repetition
|
|
133
|
+
frequency_penalty: 0.1, // Encourage varied language
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Creative Writing Assistant
|
|
140
|
+
|
|
141
|
+
A higher temperature and a wider `top_p` suit an agent that should vary its answers:
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
class CreativeWritingAgent extends AgentBase {
|
|
145
|
+
constructor() {
|
|
146
|
+
super({ name: 'creative-writer', route: '/writer' });
|
|
147
|
+
|
|
148
|
+
this.promptAddSection('Role', { body: 'You are a creative writing assistant.' });
|
|
149
|
+
|
|
150
|
+
// Varied responses
|
|
151
|
+
this.setPromptLlmParams({
|
|
152
|
+
temperature: 0.8, // Higher randomness for variety
|
|
153
|
+
top_p: 0.95, // Wide token selection
|
|
154
|
+
presence_penalty: -0.1, // Allow topic revisiting
|
|
155
|
+
frequency_penalty: 0.3, // Encourage vocabulary diversity
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Technical Documentation Bot
|
|
162
|
+
|
|
163
|
+
A low temperature keeps technical answers precise, and the post-prompt uses a lower one still:
|
|
164
|
+
|
|
165
|
+
```typescript
|
|
166
|
+
class TechnicalDocsAgent extends AgentBase {
|
|
167
|
+
constructor() {
|
|
168
|
+
super({ name: 'tech-docs', route: '/docs' });
|
|
169
|
+
|
|
170
|
+
this.promptAddSection('Role', { body: 'You are a technical documentation assistant.' });
|
|
171
|
+
|
|
172
|
+
// Precise responses
|
|
173
|
+
this.setPromptLlmParams({
|
|
174
|
+
temperature: 0.2, // Low randomness
|
|
175
|
+
top_p: 0.8, // More focused token selection
|
|
176
|
+
presence_penalty: 0.0, // Neutral on repetition
|
|
177
|
+
frequency_penalty: 0.2, // Some vocabulary variety
|
|
178
|
+
max_tokens: 400, // Room for longer explanations
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
// Even more focused for summaries
|
|
182
|
+
this.setPostPromptLlmParams({ temperature: 0.1 });
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Legal Information Bot
|
|
188
|
+
|
|
189
|
+
A legal information agent repeats legal terms on purpose, so it sets no penalties:
|
|
190
|
+
|
|
191
|
+
```typescript
|
|
192
|
+
class LegalAdvisorAgent extends AgentBase {
|
|
193
|
+
constructor() {
|
|
194
|
+
super({ name: 'legal-advisor', route: '/legal' });
|
|
195
|
+
|
|
196
|
+
this.promptAddSection('Role', { body: 'You are a legal information assistant.' });
|
|
197
|
+
this.promptAddSection('Disclaimer', {
|
|
198
|
+
body: 'Always remind users to consult a real attorney.',
|
|
199
|
+
});
|
|
200
|
+
|
|
201
|
+
// Cautious, precise responses
|
|
202
|
+
this.setPromptLlmParams({
|
|
203
|
+
temperature: 0.2, // Consistent
|
|
204
|
+
top_p: 0.85, // Focused selection
|
|
205
|
+
presence_penalty: 0.0, // Allow legal term repetition
|
|
206
|
+
frequency_penalty: 0.0, // Legal language often repeats
|
|
207
|
+
});
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Best Practices
|
|
213
|
+
|
|
214
|
+
### 1. Start with the Platform Defaults
|
|
215
|
+
|
|
216
|
+
Set nothing at first, and adjust based on the behavior you observe.
|
|
217
|
+
|
|
218
|
+
### 2. Change One Thing at a Time
|
|
219
|
+
|
|
220
|
+
Make small changes and test each one, so you know which change had which effect.
|
|
221
|
+
|
|
222
|
+
### 3. Match the Use Case
|
|
223
|
+
|
|
224
|
+
These starting points are guidance, not measured values:
|
|
225
|
+
|
|
226
|
+
- **Customer service**: low temperature (0.2 to 0.4)
|
|
227
|
+
- **Creative tasks**: higher temperature (0.7 to 0.9)
|
|
228
|
+
- **Technical or legal**: the lowest temperatures (0.1 to 0.3)
|
|
229
|
+
- **General assistant**: middle temperature (0.5 to 0.7)
|
|
230
|
+
|
|
231
|
+
### 4. Lower the Post-Prompt Temperature
|
|
232
|
+
|
|
233
|
+
A post-prompt usually produces a structured summary, so a lower temperature than the main prompt's keeps it consistent.
|
|
234
|
+
|
|
235
|
+
## Parameter Interactions
|
|
236
|
+
|
|
237
|
+
### Temperature and top_p
|
|
238
|
+
|
|
239
|
+
Both parameters control randomness, and they combine:
|
|
240
|
+
|
|
241
|
+
- Low temperature and low `top_p`: the most focused responses
|
|
242
|
+
- High temperature and high `top_p`: the most variety
|
|
243
|
+
- Low temperature and high `top_p`: consistent, with some alternatives available
|
|
244
|
+
- High temperature and low `top_p`: varied, within a narrow token set
|
|
245
|
+
|
|
246
|
+
### Penalty Parameters
|
|
247
|
+
|
|
248
|
+
The two penalties can be used together:
|
|
249
|
+
|
|
250
|
+
- Both positive: stronger push toward variety
|
|
251
|
+
- Both negative: stronger push toward repetition
|
|
252
|
+
- Mixed: finer control over which kind of repetition is allowed
|
|
253
|
+
|
|
254
|
+
## Troubleshooting
|
|
255
|
+
|
|
256
|
+
### The AI Repeats Itself
|
|
257
|
+
|
|
258
|
+
These changes reduce repetition:
|
|
259
|
+
|
|
260
|
+
- Increase `presence_penalty` (try 0.3 to 0.6)
|
|
261
|
+
- Increase `frequency_penalty` (try 0.3 to 0.6)
|
|
262
|
+
- Increase `temperature` slightly
|
|
263
|
+
|
|
264
|
+
### The AI Is Too Random or Inconsistent
|
|
265
|
+
|
|
266
|
+
These changes make the output steadier:
|
|
267
|
+
|
|
268
|
+
- Decrease `temperature` (try 0.2 to 0.4)
|
|
269
|
+
- Decrease `top_p` (try 0.7 to 0.85)
|
|
270
|
+
|
|
271
|
+
### Interruptions
|
|
272
|
+
|
|
273
|
+
Interruption behavior is set in the `ai` verb's `params`, not in the prompt objects:
|
|
274
|
+
|
|
275
|
+
- If background noise interrupts the AI, raise `barge_min_words`, as in `agent.setParam('barge_min_words', 3)`.
|
|
276
|
+
- If callers can't interrupt the AI, lower `barge_min_words`, and check that `enable_barge` isn't `false`.
|
|
277
|
+
|
|
278
|
+
See also `barge_match_string` and `interrupt_on_noise` in the SWML schema.
|
|
279
|
+
|
|
280
|
+
## Parameter Behavior
|
|
281
|
+
|
|
282
|
+
**No defaults from the SDK:** The SDK sends no LLM parameters unless you set them with `setPromptLlmParams()` or `setPostPromptLlmParams()`. Without them, the platform uses its own defaults.
|
|
283
|
+
|
|
284
|
+
**No validation in the SDK:** The SDK accepts any key and passes it through unchanged. A parameter the platform adds later works without an SDK update, and a typo isn't caught.
|
|
285
|
+
|
|
286
|
+
**Partial configuration:** You can set only the parameters you want to change:
|
|
287
|
+
|
|
288
|
+
```typescript
|
|
289
|
+
// Only set temperature; the platform handles the rest
|
|
290
|
+
agent.setPromptLlmParams({ temperature: 0.7 });
|
|
291
|
+
|
|
292
|
+
// Or set several specific parameters
|
|
293
|
+
agent.setPromptLlmParams({ temperature: 0.5, top_p: 0.9 });
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
## Related
|
|
297
|
+
|
|
298
|
+
For the rest of `AgentBase`'s configuration, including `setParams()` for the `ai` verb's other parameters, see the [Agent Guide](agent-guide.md).
|
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
# MCP to SWAIG Gateway
|
|
2
|
+
|
|
3
|
+
<!-- snippet-setup -->
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
export {}; // treat each example as a module (top-level await)
|
|
7
|
+
declare global {
|
|
8
|
+
const agent: import('@signalwire/sdk').AgentBase;
|
|
9
|
+
const McpGatewaySkill: typeof import('@signalwire/sdk').McpGatewaySkill;
|
|
10
|
+
}
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
The MCP-SWAIG gateway lets a SignalWire AI agent call tools on Model Context Protocol (MCP) servers that run as local processes, through SWAIG functions.
|
|
16
|
+
|
|
17
|
+
There are two pieces:
|
|
18
|
+
|
|
19
|
+
1. **The gateway service**: a standalone HTTP server that starts MCP server processes, keeps a session per call, and translates between the two protocols. The TypeScript SDK doesn't include one. The Python SDK ships one as the `mcp-gateway` command (`pip install "signalwire-sdk[mcp-gateway]"`). Deploy it once and point your agents at it.
|
|
20
|
+
2. **`McpGatewaySkill`**: a built-in skill in the TypeScript SDK that connects an agent to a running gateway, lists each service's tools, and registers them as SWAIG functions.
|
|
21
|
+
|
|
22
|
+
This page covers the skill's configuration and behavior, and the gateway endpoints the skill calls. To give a call the tools of an MCP server that speaks HTTP, you don't need a gateway: see [MCP Integration](mcp_integration.md).
|
|
23
|
+
|
|
24
|
+
## Installation (SDK Side)
|
|
25
|
+
|
|
26
|
+
`McpGatewaySkill` ships with the SDK, so no extra package is required:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install @signalwire/sdk
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Add it to an agent like any other built-in skill. `addSkill()` runs the skill's setup, which contacts the gateway, so it needs a gateway that's running:
|
|
33
|
+
|
|
34
|
+
<!-- snippet: no-run instantiating the `mcp_gateway` builtin requires live credentials/network at setup — cannot run standalone -->
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
import { AgentBase, McpGatewaySkill } from '@signalwire/sdk';
|
|
38
|
+
|
|
39
|
+
const agent = new AgentBase({ name: 'mcp-agent' });
|
|
40
|
+
|
|
41
|
+
await agent.addSkill(
|
|
42
|
+
new McpGatewaySkill({
|
|
43
|
+
gateway_url: 'https://mcp-gateway.example.com',
|
|
44
|
+
auth_user: 'admin',
|
|
45
|
+
auth_password: process.env.MCP_GATEWAY_AUTH_PASSWORD,
|
|
46
|
+
services: [{ name: 'todo' }],
|
|
47
|
+
}),
|
|
48
|
+
);
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`agent.addSkillByName('mcp_gateway', { ... })` takes the same configuration.
|
|
52
|
+
|
|
53
|
+
## Architecture
|
|
54
|
+
|
|
55
|
+
### Components
|
|
56
|
+
|
|
57
|
+
The gateway and the skill divide the work this way:
|
|
58
|
+
|
|
59
|
+
1. **MCP gateway service** (standalone server)
|
|
60
|
+
- HTTP or HTTPS server with basic or bearer-token authentication
|
|
61
|
+
- Starts and manages MCP server processes
|
|
62
|
+
- Keeps a session per SignalWire call
|
|
63
|
+
- Translates between SWAIG and MCP
|
|
64
|
+
|
|
65
|
+
2. **`McpGatewaySkill`** (`src/skills/builtin/mcp_gateway.ts`)
|
|
66
|
+
- Checks the gateway's health and lists each service's tools during setup
|
|
67
|
+
- Registers each MCP tool as a SWAIG function named `<tool_prefix><service>_<tool>` (default prefix `mcp_`)
|
|
68
|
+
- Registers an internal `_mcp_gateway_hangup` tool, marked `is_hangup_hook`, that closes the call's MCP session
|
|
69
|
+
|
|
70
|
+
## Protocol Flow
|
|
71
|
+
|
|
72
|
+
A tool call passes through these steps between the agent, the gateway and the MCP server:
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
SignalWire Agent Gateway Service MCP Server
|
|
76
|
+
| | |
|
|
77
|
+
|---(1) Add Skill--------------->| |
|
|
78
|
+
|<--(2) Query Tools--------------| |
|
|
79
|
+
| |---(3) List Tools-------->|
|
|
80
|
+
| |<--(4) Tool List----------|
|
|
81
|
+
|---(5) Call SWAIG Function----->| |
|
|
82
|
+
| |---(6) Spawn Session----->|
|
|
83
|
+
| |---(7) Call MCP Tool----->|
|
|
84
|
+
| |<--(8) MCP Response-------|
|
|
85
|
+
|<--(9) SWAIG Response-----------| |
|
|
86
|
+
| | |
|
|
87
|
+
|---(10) Hangup Hook------------>| |
|
|
88
|
+
| |---(11) Close Session---->|
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Message Envelope Format
|
|
92
|
+
|
|
93
|
+
When a registered tool runs, the skill POSTs this body to the gateway's `/services/<name>/call` endpoint. The service name is part of the URL, not the body:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"tool": "add_todo",
|
|
98
|
+
"arguments": { "text": "Buy milk" },
|
|
99
|
+
"session_id": "call_xyz123",
|
|
100
|
+
"timeout": 300,
|
|
101
|
+
"metadata": {
|
|
102
|
+
"agent_id": "mcp-agent",
|
|
103
|
+
"timestamp": "2026-09-28T10:30:00Z",
|
|
104
|
+
"call_id": "call_xyz123"
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The fields come from these sources:
|
|
110
|
+
|
|
111
|
+
- `session_id`: `global_data.mcp_call_id` when it's a string, otherwise the SWAIG request's `call_id`, otherwise `unknown`.
|
|
112
|
+
- `timeout`: the `session_timeout` setting.
|
|
113
|
+
- `metadata.agent_id`: the agent's name. `metadata.timestamp` and `metadata.call_id` are copied from the SWAIG request, and left out when it has none.
|
|
114
|
+
|
|
115
|
+
## Skill Configuration
|
|
116
|
+
|
|
117
|
+
`McpGatewaySkill` takes these configuration keys, in `snake_case` like every skill's configuration:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
await agent.addSkill(
|
|
121
|
+
new McpGatewaySkill({
|
|
122
|
+
gateway_url: 'https://mcp-gateway.example.com', // required
|
|
123
|
+
auth_user: 'admin', // basic auth (or use auth_token)
|
|
124
|
+
auth_password: process.env.MCP_GATEWAY_AUTH_PASSWORD,
|
|
125
|
+
// auth_token: process.env.MCP_GATEWAY_AUTH_TOKEN, // bearer token instead of basic auth
|
|
126
|
+
services: [
|
|
127
|
+
{ name: 'todo', tools: ['add_todo', 'list_todos'] }, // these tools only
|
|
128
|
+
{ name: 'calculator', tools: '*' }, // all tools
|
|
129
|
+
],
|
|
130
|
+
session_timeout: 300, // sent to the gateway as each call's timeout, in seconds
|
|
131
|
+
tool_prefix: 'mcp_', // prefix for SWAIG function names
|
|
132
|
+
retry_attempts: 3, // attempts per tool call
|
|
133
|
+
request_timeout: 30, // per-request timeout in seconds
|
|
134
|
+
verify_ssl: true, // TLS certificate verification
|
|
135
|
+
}),
|
|
136
|
+
);
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
| Key | Type | Default | Description |
|
|
140
|
+
| -------------------- | ------- | --------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
141
|
+
| `gateway_url` | string | (required) | URL of the gateway service. A trailing slash is removed. |
|
|
142
|
+
| `auth_token` | string | `MCP_GATEWAY_AUTH_TOKEN` | Bearer token. When set, it's used instead of basic auth. |
|
|
143
|
+
| `auth_user` | string | `MCP_GATEWAY_AUTH_USER` | Basic auth username. Required when there's no token. |
|
|
144
|
+
| `auth_password` | string | `MCP_GATEWAY_AUTH_PASSWORD` | Basic auth password. Required when there's no token. |
|
|
145
|
+
| `services` | array | `[]` | Services to connect to, each `{ name, tools? }`. `tools` is `'*'` (the default) or a list of tool names. |
|
|
146
|
+
| `session_timeout` | integer | `300` | Session timeout in seconds, sent in each call's envelope |
|
|
147
|
+
| `tool_prefix` | string | `mcp_` | Prefix for registered SWAIG function names |
|
|
148
|
+
| `retry_attempts` | integer | `3` | Attempts per tool call, the first one included |
|
|
149
|
+
| `request_timeout` | integer | `30` | Timeout for each request to the gateway, in seconds |
|
|
150
|
+
| `verify_ssl` | boolean | `true` | Verify the gateway's TLS certificate. `false` has an effect only with `allow_insecure_tls`. |
|
|
151
|
+
| `allow_insecure_tls` | boolean | `false` | Second switch needed to turn verification off. Both must be set to accept any certificate. |
|
|
152
|
+
|
|
153
|
+
The Default column names the environment variable the skill reads when a credential key is missing.
|
|
154
|
+
|
|
155
|
+
When `services` is empty, the skill requests the gateway's `/services` endpoint and connects to every service it lists.
|
|
156
|
+
|
|
157
|
+
### Safe Defaults
|
|
158
|
+
|
|
159
|
+
The skill's defaults refuse the two riskiest configurations:
|
|
160
|
+
|
|
161
|
+
- **Private addresses**: the skill refuses a `gateway_url` that resolves to a private, loopback or link-local address, including `localhost`. A configuration value can't point it at an internal service. Every request to the gateway is checked the same way, including each redirect, and connects only to an address it checked. This holds with `allow_insecure_tls` on too: it skips only the certificate check. For a gateway on the same host or a private network, set `SWML_ALLOW_PRIVATE_URLS=true` in the agent's environment. [Security](security.md#outbound-url-protection-ssrf) lists the refused ranges.
|
|
162
|
+
- **Certificate verification**: `verify_ssl: false` alone leaves verification on and logs a warning. To accept a self-signed certificate, also set `allow_insecure_tls: true`. The agent then accepts any certificate from the gateway, so a machine in the network path can read and change the traffic. The address checks on every request and redirect still apply.
|
|
163
|
+
|
|
164
|
+
The skill sends the credentials on every request to the gateway, including the health check. Use an `https://` gateway URL outside a private network.
|
|
165
|
+
|
|
166
|
+
## What the Skill Registers
|
|
167
|
+
|
|
168
|
+
After setup, the skill adds these items to the agent:
|
|
169
|
+
|
|
170
|
+
- **One SWAIG function per MCP tool**, named `<tool_prefix><service>_<tool>`, with the description `[<service>] <tool description>`. Each top-level property of the tool's input schema becomes a parameter with its `type` (default `string`), `description`, `enum` and, for optional parameters, `default`. Nested schemas (`properties` of an object, `items` of an array) aren't copied.
|
|
171
|
+
- **The `_mcp_gateway_hangup` tool**, marked `is_hangup_hook`, which sends `DELETE /sessions/<session_id>` when the call ends.
|
|
172
|
+
- **Global data**: `mcp_gateway_url`, `mcp_services` and `mcp_session_id` (always `null`).
|
|
173
|
+
- **A prompt section** titled "MCP Gateway Integration" that lists the gateway URL and the services.
|
|
174
|
+
- **Speech hints**: `MCP`, `gateway` and each service name.
|
|
175
|
+
|
|
176
|
+
When setup succeeds but finds no tool, for example because `/services` failed, the skill registers a single `mcp_invoke` tool. Its response says the gateway isn't configured.
|
|
177
|
+
|
|
178
|
+
## Gateway Service Configuration
|
|
179
|
+
|
|
180
|
+
The gateway service reads its own configuration file, whose format depends on the gateway you deploy. The Python SDK's gateway reads a `config.json` that substitutes environment variables with `${VAR_NAME|default}` syntax. This is an example of that format:
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"server": {
|
|
185
|
+
"host": "${MCP_HOST|0.0.0.0}",
|
|
186
|
+
"port": "${MCP_PORT|8080}",
|
|
187
|
+
"auth_user": "${MCP_AUTH_USER|admin}",
|
|
188
|
+
"auth_password": "${MCP_AUTH_PASSWORD}",
|
|
189
|
+
"auth_token": "${MCP_AUTH_TOKEN}"
|
|
190
|
+
},
|
|
191
|
+
"services": {
|
|
192
|
+
"todo": {
|
|
193
|
+
"command": ["node", "./test/todo_mcp.js"],
|
|
194
|
+
"description": "Simple todo list for testing",
|
|
195
|
+
"enabled": true
|
|
196
|
+
},
|
|
197
|
+
"calculator": {
|
|
198
|
+
"command": ["node", "/path/to/calculator.js"],
|
|
199
|
+
"description": "Math calculations",
|
|
200
|
+
"enabled": true
|
|
201
|
+
}
|
|
202
|
+
},
|
|
203
|
+
"session": {
|
|
204
|
+
"default_timeout": 300,
|
|
205
|
+
"max_sessions_per_service": 100,
|
|
206
|
+
"cleanup_interval": 60
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## API Endpoints (Gateway Service)
|
|
212
|
+
|
|
213
|
+
The skill calls these endpoints on the gateway, with its credentials on each request.
|
|
214
|
+
|
|
215
|
+
#### GET /health
|
|
216
|
+
|
|
217
|
+
Health check. The skill calls it during setup, and setup fails unless it returns a 2xx status:
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
curl https://mcp-gateway.example.com/health
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
#### GET /services
|
|
224
|
+
|
|
225
|
+
Lists the available services as an object keyed by service name. The skill calls it when `services` is empty:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" https://mcp-gateway.example.com/services
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
#### GET /services/{serviceName}/tools
|
|
232
|
+
|
|
233
|
+
Returns a service's tools as `{ "tools": [...] }`, each with a `name`, a `description` and an `inputSchema`:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" https://mcp-gateway.example.com/services/todo/tools
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
#### POST /services/{serviceName}/call
|
|
240
|
+
|
|
241
|
+
Calls a tool on a service. This request uses basic auth:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" -X POST https://mcp-gateway.example.com/services/todo/call \
|
|
245
|
+
-H "Content-Type: application/json" \
|
|
246
|
+
-d '{
|
|
247
|
+
"tool": "add_todo",
|
|
248
|
+
"arguments": {"text": "Test item"},
|
|
249
|
+
"session_id": "test-123",
|
|
250
|
+
"timeout": 300
|
|
251
|
+
}'
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
This request uses a bearer token:
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
curl -X POST https://mcp-gateway.example.com/services/todo/call \
|
|
258
|
+
-H "Authorization: Bearer $MCP_GATEWAY_AUTH_TOKEN" \
|
|
259
|
+
-H "Content-Type: application/json" \
|
|
260
|
+
-d '{
|
|
261
|
+
"tool": "add_todo",
|
|
262
|
+
"arguments": {"text": "Test item"},
|
|
263
|
+
"session_id": "test-123"
|
|
264
|
+
}'
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
The skill reads the `result` field of a `200` response. A string is used as the tool's response, another value is sent as its JSON, and a missing field becomes `No response`.
|
|
268
|
+
|
|
269
|
+
#### DELETE /sessions/{sessionId}
|
|
270
|
+
|
|
271
|
+
Closes a session. The skill's hangup hook calls it, and treats `200` and `404` as success:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" -X DELETE https://mcp-gateway.example.com/sessions/test-123
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## Testing
|
|
278
|
+
|
|
279
|
+
### Testing with the swaig-test CLI
|
|
280
|
+
|
|
281
|
+
`swaig-test` loads the agent file, which runs the skill's setup against the gateway. Put `--call-id` before `--exec`, since everything after the function name is an argument to the function. Using the same call ID for each call keeps the calls in one gateway session:
|
|
282
|
+
|
|
283
|
+
```bash
|
|
284
|
+
# List the registered MCP tools
|
|
285
|
+
npx tsx src/cli/swaig-test.ts test/test-agent.ts --list-tools
|
|
286
|
+
|
|
287
|
+
# Call two tools in the same session
|
|
288
|
+
npx tsx src/cli/swaig-test.ts test/test-agent.ts --call-id test-session --exec mcp_todo_add_todo --text "Buy milk"
|
|
289
|
+
npx tsx src/cli/swaig-test.ts test/test-agent.ts --call-id test-session --exec mcp_todo_list_todos
|
|
290
|
+
|
|
291
|
+
# Print the SWML document
|
|
292
|
+
npx tsx src/cli/swaig-test.ts test/test-agent.ts --dump-swml
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
### End-to-End Test Agent
|
|
296
|
+
|
|
297
|
+
This agent connects to a gateway on the same machine, so its environment needs `SWML_ALLOW_PRIVATE_URLS=true` for setup to accept the `localhost` URL:
|
|
298
|
+
|
|
299
|
+
<!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port) — collides under the concurrent gate and cannot run standalone -->
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
// test/test-agent.ts
|
|
303
|
+
import { AgentBase, McpGatewaySkill } from '@signalwire/sdk';
|
|
304
|
+
|
|
305
|
+
class TestMcpAgent extends AgentBase {
|
|
306
|
+
static async create(): Promise<TestMcpAgent> {
|
|
307
|
+
const agent = new TestMcpAgent({ name: 'MCP Test Agent' });
|
|
308
|
+
await agent.addSkill(
|
|
309
|
+
new McpGatewaySkill({
|
|
310
|
+
gateway_url: 'http://localhost:8080',
|
|
311
|
+
auth_user: 'admin',
|
|
312
|
+
auth_password: process.env.MCP_GATEWAY_AUTH_PASSWORD,
|
|
313
|
+
services: [{ name: 'todo' }],
|
|
314
|
+
}),
|
|
315
|
+
);
|
|
316
|
+
return agent;
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
const agent = await TestMcpAgent.create();
|
|
321
|
+
await agent.run();
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
## Implementation Details
|
|
325
|
+
|
|
326
|
+
### Session Management
|
|
327
|
+
|
|
328
|
+
The gateway, not the skill, keeps session state. The skill's part is to send a stable `session_id`:
|
|
329
|
+
|
|
330
|
+
1. **Session creation**: the first tool call with a new `session_id` creates a session on the gateway.
|
|
331
|
+
2. **Session persistence**: later tool calls in the same call send the same `session_id`, so they reach the same session.
|
|
332
|
+
3. **Session cleanup**: the hangup hook sends `DELETE /sessions/{id}` when the call ends.
|
|
333
|
+
4. **State isolation**: each session gets its own MCP server process on the gateway.
|
|
334
|
+
|
|
335
|
+
### Error Handling
|
|
336
|
+
|
|
337
|
+
A tool call makes up to `retry_attempts` attempts, the first one included:
|
|
338
|
+
|
|
339
|
+
1. **Server errors (5xx)**: retried.
|
|
340
|
+
2. **Client errors (4xx)**: returned without a retry.
|
|
341
|
+
3. **Timeouts and network errors**: retried. Other exceptions stop the attempts.
|
|
342
|
+
4. **Final failure**: the tool's response is `Failed to call <service>.<tool>: <error>`. The error is the gateway's `error` field, or the status and the start of the body.
|
|
343
|
+
|
|
344
|
+
## Troubleshooting
|
|
345
|
+
|
|
346
|
+
1. **`Failed to setup skill 'mcp_gateway'`**: `addSkill()` throws this when setup fails. The log gives the reason: a missing `gateway_url` or credentials, a URL refused as private, a health check that didn't return 2xx, or a connection error.
|
|
347
|
+
2. **`gateway_url rejected by SSRF protection`**: the URL resolves to a private or loopback address. Set `SWML_ALLOW_PRIVATE_URLS=true` if the gateway is on a private network.
|
|
348
|
+
3. **Authentication failures**: check that `auth_user` and `auth_password`, or `auth_token`, match the gateway's configuration.
|
|
349
|
+
4. **TLS certificate errors**: give the gateway a certificate from a trusted CA. For a self-signed certificate on a private network, set both `verify_ssl: false` and `allow_insecure_tls: true`.
|
|
350
|
+
5. **Lost session state**: check that the gateway keeps the MCP process alive between tool calls, and that each call sends the same `session_id`.
|
|
351
|
+
|
|
352
|
+
## Related Pages
|
|
353
|
+
|
|
354
|
+
For MCP servers that SignalWire can reach over HTTP, which need no gateway, see [MCP Integration](mcp_integration.md). For the address ranges the skill refuses, see [Security](security.md#outbound-url-protection-ssrf).
|