@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,805 @@
|
|
|
1
|
+
# Lesson 4: Advanced Features and Best Practices
|
|
2
|
+
|
|
3
|
+
This lesson covers what an agent needs before it takes real calls: SWAIG functions that do real work, error handling, logging, testing, deployment, performance and security. Its examples are the tools of one agent, `tutorial/multi_agents/advanced_agent.ts`, and the deployment files for the Lesson 3 system.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
1. [Custom SWAIG functions](#custom-swaig-functions)
|
|
8
|
+
2. [Error handling and results](#error-handling-and-results)
|
|
9
|
+
3. [Logging and debugging](#logging-and-debugging)
|
|
10
|
+
4. [Production deployment](#production-deployment)
|
|
11
|
+
5. [Testing strategies](#testing-strategies)
|
|
12
|
+
6. [Performance optimization](#performance-optimization)
|
|
13
|
+
7. [Security best practices](#security-best-practices)
|
|
14
|
+
8. [Summary](#summary)
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Custom SWAIG functions
|
|
19
|
+
|
|
20
|
+
A SWAIG function is a tool the AI can call during a call. SignalWire sends the call to the agent's `/swaig` route with the arguments the model chose, and the agent runs the tool's handler. The handler can call an API, query a database or calculate, and returns a `FunctionResult` that tells the model what happened.
|
|
21
|
+
|
|
22
|
+
### Basic function structure
|
|
23
|
+
|
|
24
|
+
The file starts with the agent and a logger:
|
|
25
|
+
|
|
26
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#setup -->
|
|
27
|
+
```typescript
|
|
28
|
+
import { pathToFileURL } from 'node:url';
|
|
29
|
+
import { Hono } from 'hono';
|
|
30
|
+
import { AgentBase, FunctionResult, getLogger } from '@signalwire/sdk';
|
|
31
|
+
|
|
32
|
+
const log = getLogger('advanced_agent');
|
|
33
|
+
|
|
34
|
+
export const agent = new AgentBase({ name: 'Advanced Features Agent', route: '/' });
|
|
35
|
+
agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.marsh' });
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`defineTool()` registers a tool with a name, a description, its parameters and a handler. This one calculates a price with tax:
|
|
39
|
+
|
|
40
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#calculate-price -->
|
|
41
|
+
```typescript
|
|
42
|
+
agent.defineTool({
|
|
43
|
+
name: 'calculate_price',
|
|
44
|
+
description: 'Calculate total price with tax',
|
|
45
|
+
parameters: {
|
|
46
|
+
amount: { type: 'number', description: 'Base price in dollars' },
|
|
47
|
+
tax_rate: { type: 'number', description: 'Tax rate as a decimal (default 0.08)' },
|
|
48
|
+
},
|
|
49
|
+
required: ['amount'],
|
|
50
|
+
handler: ({ amount, tax_rate = 0.08 }) => {
|
|
51
|
+
const tax = amount * tax_rate;
|
|
52
|
+
const total = amount + tax;
|
|
53
|
+
return new FunctionResult(
|
|
54
|
+
`The total price is $${total.toFixed(2)} ($${amount.toFixed(2)} + $${tax.toFixed(2)} tax)`,
|
|
55
|
+
);
|
|
56
|
+
},
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The model reads the description and the parameter descriptions to decide when to call the tool and what to pass, so write them for the model. The handler receives the arguments as its first parameter, and TypeScript infers their types from `parameters` and `required`. `amount` is a `number`. `tax_rate` is a `number` or `undefined`, so the default applies when the model leaves it out.
|
|
61
|
+
|
|
62
|
+
### Required parameters
|
|
63
|
+
|
|
64
|
+
List the parameters the model must always pass in `required`. An `enum` limits a string to the values you list:
|
|
65
|
+
|
|
66
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#create-order -->
|
|
67
|
+
```typescript
|
|
68
|
+
agent.defineTool({
|
|
69
|
+
name: 'create_order',
|
|
70
|
+
description: 'Create a new order',
|
|
71
|
+
parameters: {
|
|
72
|
+
customer_name: { type: 'string', description: "Customer's full name" },
|
|
73
|
+
items: { type: 'string', description: 'Items to order' },
|
|
74
|
+
priority: {
|
|
75
|
+
type: 'string',
|
|
76
|
+
enum: ['normal', 'rush'],
|
|
77
|
+
description: 'Order priority (default normal)',
|
|
78
|
+
},
|
|
79
|
+
},
|
|
80
|
+
required: ['customer_name', 'items'],
|
|
81
|
+
handler: ({ customer_name, items, priority = 'normal' }) =>
|
|
82
|
+
new FunctionResult(`Order for ${customer_name} created: ${items} (${priority} priority)`),
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Parameter types
|
|
87
|
+
|
|
88
|
+
A parameter's `type` is a JSON Schema type. These four cover most tools:
|
|
89
|
+
|
|
90
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#parameter-types -->
|
|
91
|
+
```typescript
|
|
92
|
+
agent.defineTool({
|
|
93
|
+
name: 'quote_upgrade',
|
|
94
|
+
description: 'Quote a component upgrade',
|
|
95
|
+
parameters: {
|
|
96
|
+
component: { type: 'string', description: 'The component to upgrade' },
|
|
97
|
+
quantity: { type: 'integer', description: 'How many to install' },
|
|
98
|
+
unit_price: { type: 'number', description: 'Price of one, in dollars' },
|
|
99
|
+
installation: { type: 'boolean', description: 'Whether the store installs it' },
|
|
100
|
+
},
|
|
101
|
+
required: ['component', 'quantity', 'unit_price', 'installation'],
|
|
102
|
+
handler: ({ component, quantity, unit_price, installation }) => {
|
|
103
|
+
const labor = installation ? 50 : 0;
|
|
104
|
+
const total = quantity * unit_price + labor;
|
|
105
|
+
return new FunctionResult(`${quantity} x ${component}: $${total.toFixed(2)}`);
|
|
106
|
+
},
|
|
107
|
+
});
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`integer` and `number` arrive as JavaScript numbers, and `boolean` as `true` or `false`. The model produces the arguments, so a handler that needs a value in a range should still check it.
|
|
111
|
+
|
|
112
|
+
### Results with actions
|
|
113
|
+
|
|
114
|
+
A `FunctionResult` carries the text the model reads, and optionally actions for SignalWire to run. `updateGlobalData()` adds a `set_global_data` action, which stores values for the rest of the call:
|
|
115
|
+
|
|
116
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#check-inventory -->
|
|
117
|
+
```typescript
|
|
118
|
+
agent.defineTool({
|
|
119
|
+
name: 'check_inventory',
|
|
120
|
+
description: 'Check product availability',
|
|
121
|
+
parameters: {
|
|
122
|
+
product_id: { type: 'string', description: 'The product ID to check' },
|
|
123
|
+
},
|
|
124
|
+
required: ['product_id'],
|
|
125
|
+
handler: ({ product_id }) => {
|
|
126
|
+
const inStock = product_id.startsWith('GPU') ? 5 : 0; // stands in for a real lookup
|
|
127
|
+
if (inStock === 0) {
|
|
128
|
+
return new FunctionResult(`Product ${product_id} is out of stock`);
|
|
129
|
+
}
|
|
130
|
+
// Keep the result in global data, where later function calls can read it
|
|
131
|
+
return new FunctionResult(
|
|
132
|
+
`Product ${product_id} is in stock (${inStock} units)`,
|
|
133
|
+
).updateGlobalData({ last_checked_product: product_id, stock_level: inStock });
|
|
134
|
+
},
|
|
135
|
+
});
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Every later SWAIG request in the call carries the stored values in its `global_data`. For the full list of actions, see the [SWAIG reference](../../docs/swaig-reference.md).
|
|
139
|
+
|
|
140
|
+
### Async and sync handlers
|
|
141
|
+
|
|
142
|
+
A handler can be `async`, and the SDK awaits it. Use `async` for I/O, such as an HTTP request. Keep synchronous handlers for quick work, because a long synchronous calculation blocks every other call the process is serving:
|
|
143
|
+
|
|
144
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#async-and-sync -->
|
|
145
|
+
```typescript
|
|
146
|
+
// An async handler, for I/O: the event loop keeps serving other requests while it waits
|
|
147
|
+
agent.defineTool({
|
|
148
|
+
name: 'fetch_product_reviews',
|
|
149
|
+
description: 'Fetch the review count for a product from the review service',
|
|
150
|
+
parameters: {
|
|
151
|
+
product_id: { type: 'string', description: 'The product ID' },
|
|
152
|
+
},
|
|
153
|
+
required: ['product_id'],
|
|
154
|
+
handler: async ({ product_id }) => {
|
|
155
|
+
const base = process.env['REVIEWS_API_URL'];
|
|
156
|
+
if (!base) return new FunctionResult('The review service is not configured.');
|
|
157
|
+
const res = await fetch(`${base}/reviews/${encodeURIComponent(product_id)}`, {
|
|
158
|
+
signal: AbortSignal.timeout(5000),
|
|
159
|
+
});
|
|
160
|
+
if (!res.ok) return new FunctionResult('The review service is unavailable right now.');
|
|
161
|
+
const reviews = (await res.json()) as unknown[];
|
|
162
|
+
return new FunctionResult(`Found ${reviews.length} reviews for ${product_id}`);
|
|
163
|
+
},
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
// A synchronous handler, for quick calculations
|
|
167
|
+
agent.defineTool({
|
|
168
|
+
name: 'add_numbers',
|
|
169
|
+
description: 'Add two numbers',
|
|
170
|
+
parameters: {
|
|
171
|
+
x: { type: 'integer', description: 'First number' },
|
|
172
|
+
y: { type: 'integer', description: 'Second number' },
|
|
173
|
+
},
|
|
174
|
+
required: ['x', 'y'],
|
|
175
|
+
handler: ({ x, y }) => new FunctionResult(`Result: ${x + y}`),
|
|
176
|
+
});
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
`AbortSignal.timeout()` stops a request that hangs. The model is waiting on the caller's behalf, so give external calls a short timeout.
|
|
180
|
+
|
|
181
|
+
## Error handling and results
|
|
182
|
+
|
|
183
|
+
A tool that fails should still tell the model what happened, so the model can tell the caller.
|
|
184
|
+
|
|
185
|
+
### Function error handling
|
|
186
|
+
|
|
187
|
+
Catch the errors you expect, and describe them in the result. Log the ones you don't:
|
|
188
|
+
|
|
189
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#process-order -->
|
|
190
|
+
```typescript
|
|
191
|
+
class OrderError extends Error {}
|
|
192
|
+
|
|
193
|
+
agent.defineTool({
|
|
194
|
+
name: 'process_order',
|
|
195
|
+
description: 'Process customer order',
|
|
196
|
+
parameters: {
|
|
197
|
+
order_id: { type: 'string', description: 'The order ID to process' },
|
|
198
|
+
},
|
|
199
|
+
required: ['order_id'],
|
|
200
|
+
handler: ({ order_id }) => {
|
|
201
|
+
try {
|
|
202
|
+
// Validate input
|
|
203
|
+
if (order_id.length < 5) {
|
|
204
|
+
return new FunctionResult('Invalid order ID format');
|
|
205
|
+
}
|
|
206
|
+
if (order_id.startsWith('TEST')) {
|
|
207
|
+
throw new OrderError('Test orders cannot be processed');
|
|
208
|
+
}
|
|
209
|
+
return new FunctionResult(`Order ${order_id} processed successfully`);
|
|
210
|
+
} catch (err) {
|
|
211
|
+
if (err instanceof OrderError) {
|
|
212
|
+
return new FunctionResult(`Order processing failed: ${err.message}`);
|
|
213
|
+
}
|
|
214
|
+
// Log unexpected errors, and tell the model only that something went wrong
|
|
215
|
+
log.error('unexpected error processing order', { error: String(err) });
|
|
216
|
+
return new FunctionResult('An unexpected error occurred. Please try again.');
|
|
217
|
+
}
|
|
218
|
+
},
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
A handler that throws doesn't take the agent down. The SDK logs the error and answers the model with "Sorry, I couldn't complete that action. Please try again or contact support if the issue persists." A result you write says more about what went wrong.
|
|
223
|
+
|
|
224
|
+
### Agent-level error handling
|
|
225
|
+
|
|
226
|
+
The prompt can tell the model how to talk about a failure:
|
|
227
|
+
|
|
228
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#error-prompt -->
|
|
229
|
+
```typescript
|
|
230
|
+
agent.promptAddSection('Error Handling', {
|
|
231
|
+
body: 'How to handle errors gracefully:',
|
|
232
|
+
bullets: [
|
|
233
|
+
'If a function returns an error, acknowledge it politely',
|
|
234
|
+
'Offer alternative solutions when possible',
|
|
235
|
+
'Never expose technical error details to customers',
|
|
236
|
+
'Always maintain a helpful, professional tone',
|
|
237
|
+
],
|
|
238
|
+
});
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Validation patterns
|
|
242
|
+
|
|
243
|
+
Collect every validation problem, then report them together, so the model can ask for all the corrections at once:
|
|
244
|
+
|
|
245
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#update-customer -->
|
|
246
|
+
```typescript
|
|
247
|
+
agent.defineTool({
|
|
248
|
+
name: 'update_customer',
|
|
249
|
+
description: 'Update customer information',
|
|
250
|
+
parameters: {
|
|
251
|
+
customer_id: { type: 'string', description: "The customer's ID" },
|
|
252
|
+
email: { type: 'string', description: "Customer's email address" },
|
|
253
|
+
phone: { type: 'string', description: "Customer's phone number" },
|
|
254
|
+
},
|
|
255
|
+
handler: ({ customer_id, email, phone }) => {
|
|
256
|
+
// Collect every problem, and report them together
|
|
257
|
+
const errors: string[] = [];
|
|
258
|
+
if (!customer_id) errors.push('Customer ID is required');
|
|
259
|
+
if (email && !email.includes('@')) errors.push('Invalid email format');
|
|
260
|
+
if (phone && phone.replace(/\D/g, '').length < 10) {
|
|
261
|
+
errors.push('Phone number must be at least 10 digits');
|
|
262
|
+
}
|
|
263
|
+
if (errors.length > 0) {
|
|
264
|
+
return new FunctionResult(`Validation failed: ${errors.join(', ')}`);
|
|
265
|
+
}
|
|
266
|
+
return new FunctionResult('Customer updated successfully');
|
|
267
|
+
},
|
|
268
|
+
});
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Called with an invalid email and a short phone number, the tool reports all three problems:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts \
|
|
275
|
+
--exec update_customer --email nope --phone 555
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
The result lists them in one sentence:
|
|
279
|
+
|
|
280
|
+
```text
|
|
281
|
+
RESULT:
|
|
282
|
+
Response: Validation failed: Customer ID is required, Invalid email format, Phone number must be at least 10 digits
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
## Logging and debugging
|
|
286
|
+
|
|
287
|
+
Logs are how you find out what an agent did on a call you weren't on.
|
|
288
|
+
|
|
289
|
+
### Using the logger
|
|
290
|
+
|
|
291
|
+
`getLogger(name)` returns the SDK's structured logger. Each call takes a message and an object of fields, and the fields are printed as `key=value`. A handler's second parameter, `rawData`, is the whole SWAIG request, with the call ID:
|
|
292
|
+
|
|
293
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#logging -->
|
|
294
|
+
```typescript
|
|
295
|
+
agent.defineTool({
|
|
296
|
+
name: 'normalize_part_number',
|
|
297
|
+
description: 'Normalize a part number to upper case',
|
|
298
|
+
parameters: {
|
|
299
|
+
part_number: { type: 'string', description: 'The part number as the caller said it' },
|
|
300
|
+
},
|
|
301
|
+
required: ['part_number'],
|
|
302
|
+
handler: ({ part_number }, rawData) => {
|
|
303
|
+
log.debug('normalize_part_number called', { call_id: rawData.call_id, part_number });
|
|
304
|
+
const normalized = part_number.trim().toUpperCase().replace(/\s+/g, '-');
|
|
305
|
+
log.info('part number normalized', { normalized });
|
|
306
|
+
return new FunctionResult(`The part number is ${normalized}`);
|
|
307
|
+
},
|
|
308
|
+
});
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Log levels
|
|
312
|
+
|
|
313
|
+
The SDK reads `SIGNALWIRE_LOG_LEVEL`: `debug`, `info` (the default), `warn` or `error`. Set it when you start the agent:
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
SIGNALWIRE_LOG_LEVEL=debug npx tsx tutorial/multi_agents/advanced_agent.ts
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
Set `SIGNALWIRE_LOG_MODE=off` to turn logging off, as tests often do. `new AgentServer()` sets the level from its `logLevel` option, so `pc_builder.ts` passes `SIGNALWIRE_LOG_LEVEL` through to it.
|
|
320
|
+
|
|
321
|
+
### Debugging techniques
|
|
322
|
+
|
|
323
|
+
These four techniques cover most debugging.
|
|
324
|
+
|
|
325
|
+
**1. Request logging.** A per-call configuration callback sees every request before the agent handles it:
|
|
326
|
+
|
|
327
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#request-logging -->
|
|
328
|
+
```typescript
|
|
329
|
+
// Runs on every request, on that request's copy of the agent. It logs names,
|
|
330
|
+
// not values: the query can carry a SWAIG token, and the body caller data.
|
|
331
|
+
agent.addPerCallConfig((query, body, headers) => {
|
|
332
|
+
log.debug('request', {
|
|
333
|
+
query_keys: Object.keys(query),
|
|
334
|
+
body_keys: Object.keys(body ?? {}),
|
|
335
|
+
user_agent: headers['user-agent'],
|
|
336
|
+
});
|
|
337
|
+
});
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
**2. SWML and tool inspection.** `swaig-test` prints the SWML, and runs a tool with the arguments you give it:
|
|
341
|
+
|
|
342
|
+
```bash
|
|
343
|
+
npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts --dump-swml
|
|
344
|
+
npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts --exec calculate_price --amount 100
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
Put `swaig-test`'s own options, such as `--verbose`, before `--exec`. Everything after the tool name is an argument to the tool. With `SIGNALWIRE_LOG_LEVEL=debug` and `--verbose`, the part-number tool shows the request logging and the tool's own lines:
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
SIGNALWIRE_LOG_LEVEL=debug npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts \
|
|
351
|
+
--verbose --exec normalize_part_number --part_number 'cx 4090 b'
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
This excerpt shows the lines the file logs. The SDK's own lines, and the full request, are left out:
|
|
355
|
+
|
|
356
|
+
```text
|
|
357
|
+
[DEBUG] [advanced_agent] request query_keys=["__token"] body_keys=["call_id","call","vars","params",...]
|
|
358
|
+
[DEBUG] [advanced_agent] normalize_part_number called call_id=82c4c94d-a7dd-4a07-9a5b-9b9edb33e3a0 part_number="cx 4090 b"
|
|
359
|
+
[INFO] [advanced_agent] part number normalized normalized=CX-4090-B
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
**3. Agent state.** A handler's third parameter is the agent handling the request. With a per-call configuration callback, that's the request's configured copy:
|
|
363
|
+
|
|
364
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#debug-state -->
|
|
365
|
+
```typescript
|
|
366
|
+
agent.defineTool({
|
|
367
|
+
name: 'debug_state',
|
|
368
|
+
description: 'Log the agent state',
|
|
369
|
+
handler: (_args, _rawData, current) => {
|
|
370
|
+
const state = {
|
|
371
|
+
agent_name: current?.getName(),
|
|
372
|
+
functions: current?.getTools().map((fn) => fn.name),
|
|
373
|
+
};
|
|
374
|
+
log.info('agent state', state);
|
|
375
|
+
return new FunctionResult('State logged to console');
|
|
376
|
+
},
|
|
377
|
+
});
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
**4. The SWML itself.** Request it with curl, as SignalWire does, and read the prompt and tools it carries. [Lesson 3](lesson3_multi_agent_systems.md#testing-individual-agents) shows how with `jq`.
|
|
381
|
+
|
|
382
|
+
## Production deployment
|
|
383
|
+
|
|
384
|
+
Configure a deployed agent through the environment, and keep secrets out of the code.
|
|
385
|
+
|
|
386
|
+
### Environment variables
|
|
387
|
+
|
|
388
|
+
These are the variables a production deployment sets:
|
|
389
|
+
|
|
390
|
+
```bash
|
|
391
|
+
# Credentials SignalWire uses to fetch the SWML and call the tools
|
|
392
|
+
export SWML_BASIC_AUTH_USER=pcbuilder
|
|
393
|
+
export SWML_BASIC_AUTH_PASSWORD=a-long-random-password
|
|
394
|
+
|
|
395
|
+
# Verifies that requests come from SignalWire
|
|
396
|
+
export SIGNALWIRE_SIGNING_KEY=your-signing-key
|
|
397
|
+
|
|
398
|
+
# Signs tool tokens, so they stay valid across restarts and replicas
|
|
399
|
+
export SIGNALWIRE_SWAIG_SECRET=another-long-random-value
|
|
400
|
+
|
|
401
|
+
export SIGNALWIRE_LOG_LEVEL=info
|
|
402
|
+
|
|
403
|
+
# HTTPS, or SWML_PROXY_URL_BASE when a proxy terminates TLS
|
|
404
|
+
export SWML_SSL_ENABLED=true
|
|
405
|
+
export SWML_SSL_CERT_PATH=/etc/ssl/certs/agent.crt
|
|
406
|
+
export SWML_SSL_KEY_PATH=/etc/ssl/private/agent.key
|
|
407
|
+
export SWML_SSL_DOMAIN=agents.example.com
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
Each tool call carries a token that the agent signed when it served the SWML. Without `SIGNALWIRE_SWAIG_SECRET`, each process generates its own secret, so a restart or a second replica rejects the tokens the first one issued. For more information, see the [security guide](../../docs/security.md).
|
|
411
|
+
|
|
412
|
+
### Docker deployment
|
|
413
|
+
|
|
414
|
+
This `Dockerfile` runs the Lesson 3 system. It builds from a project whose `package.json` depends on `@signalwire/sdk` and `tsx`, with a `package-lock.json`. List `tsx` under `dependencies`, not `devDependencies`: `npm ci --omit=dev` leaves dev dependencies out, and the image runs `tsx`.
|
|
415
|
+
|
|
416
|
+
```dockerfile
|
|
417
|
+
# PC Builder Pro multi-agent service (Lesson 4).
|
|
418
|
+
# Build context: a project whose package.json depends on @signalwire/sdk and tsx,
|
|
419
|
+
# with package-lock.json, pc_builder.ts, knowledge.ts and the two knowledge files.
|
|
420
|
+
FROM node:22-slim
|
|
421
|
+
|
|
422
|
+
WORKDIR /app
|
|
423
|
+
ENV NODE_ENV=production
|
|
424
|
+
|
|
425
|
+
# Install the locked dependencies first, so a code change reuses this layer
|
|
426
|
+
COPY package.json package-lock.json ./
|
|
427
|
+
RUN npm ci --omit=dev
|
|
428
|
+
|
|
429
|
+
# Copy the application
|
|
430
|
+
COPY pc_builder.ts knowledge.ts sales_knowledge.md support_knowledge.md ./
|
|
431
|
+
|
|
432
|
+
# Run as the image's unprivileged user
|
|
433
|
+
USER node
|
|
434
|
+
|
|
435
|
+
EXPOSE 3001
|
|
436
|
+
|
|
437
|
+
# Node has fetch built in, and the slim image has no curl
|
|
438
|
+
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
|
|
439
|
+
CMD node -e "fetch('http://localhost:3001/health').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
|
|
440
|
+
|
|
441
|
+
CMD ["./node_modules/.bin/tsx", "pc_builder.ts"]
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
The health check uses Node's built-in `fetch`, because the slim image has no `curl`, and it fails on any status but 2xx. Build and run the image with the credentials:
|
|
445
|
+
|
|
446
|
+
```bash
|
|
447
|
+
docker build -t pc-builder .
|
|
448
|
+
docker run -d -p 3001:3001 \
|
|
449
|
+
-e SWML_BASIC_AUTH_USER=pcbuilder -e SWML_BASIC_AUTH_PASSWORD=a-long-random-password \
|
|
450
|
+
pc-builder
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
`docker ps` shows the container as `healthy` once `/health` answers.
|
|
454
|
+
|
|
455
|
+
### systemd service
|
|
456
|
+
|
|
457
|
+
On a Linux host without Docker, a systemd unit keeps the service running and restarts it when it fails. This unit expects the project in `/opt/pc-builder`, and the secrets in `/etc/pc-builder/env`:
|
|
458
|
+
|
|
459
|
+
```ini
|
|
460
|
+
[Unit]
|
|
461
|
+
Description=PC Builder Pro voice agents
|
|
462
|
+
After=network-online.target
|
|
463
|
+
Wants=network-online.target
|
|
464
|
+
|
|
465
|
+
[Service]
|
|
466
|
+
Type=simple
|
|
467
|
+
User=pcbuilder
|
|
468
|
+
WorkingDirectory=/opt/pc-builder
|
|
469
|
+
# The basic auth credentials, the signing key and the SSL paths, readable only by root
|
|
470
|
+
EnvironmentFile=/etc/pc-builder/env
|
|
471
|
+
Environment=PORT=3001
|
|
472
|
+
Environment=SIGNALWIRE_LOG_LEVEL=info
|
|
473
|
+
ExecStart=/opt/pc-builder/node_modules/.bin/tsx pc_builder.ts
|
|
474
|
+
Restart=always
|
|
475
|
+
RestartSec=10
|
|
476
|
+
|
|
477
|
+
[Install]
|
|
478
|
+
WantedBy=multi-user.target
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Save it as `/etc/systemd/system/pc-builder.service`, then run `sudo systemctl enable --now pc-builder`.
|
|
482
|
+
|
|
483
|
+
### Health monitoring
|
|
484
|
+
|
|
485
|
+
An agent and an `AgentServer` answer `/health` without credentials. For a status page with details of your own, mount a Hono app beside the agent's routes. A mounted app isn't behind the agent's basic auth, so return nothing secret from it:
|
|
486
|
+
|
|
487
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#status-route -->
|
|
488
|
+
```typescript
|
|
489
|
+
// A route of your own beside the agent's, outside its basic auth
|
|
490
|
+
const status = new Hono();
|
|
491
|
+
status.get('/', (c) =>
|
|
492
|
+
c.json({
|
|
493
|
+
status: 'healthy',
|
|
494
|
+
timestamp: new Date().toISOString(),
|
|
495
|
+
tools: agent.getTools().length,
|
|
496
|
+
uptime_seconds: Math.round(process.uptime()),
|
|
497
|
+
}),
|
|
498
|
+
);
|
|
499
|
+
agent.mount(status, { prefix: '/status' });
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
The route answers with the agent's status:
|
|
503
|
+
|
|
504
|
+
```bash
|
|
505
|
+
curl http://localhost:3000/status
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
The output has the values the route computes:
|
|
509
|
+
|
|
510
|
+
```json
|
|
511
|
+
{"status":"healthy","timestamp":"2026-09-29T17:41:42.221Z","tools":15,"uptime_seconds":6}
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
Hono is the web framework the SDK is built on. Add it to your project's dependencies to import it.
|
|
515
|
+
|
|
516
|
+
## Testing strategies
|
|
517
|
+
|
|
518
|
+
Test the tools directly, then the agent over HTTP. These examples use vitest, and come from `tests/tutorial/multi_agents-lessons.test.ts`.
|
|
519
|
+
|
|
520
|
+
### Unit testing functions
|
|
521
|
+
|
|
522
|
+
`agent.getTool(name)` returns a registered tool, and `execute()` runs its handler as the SWAIG endpoint does:
|
|
523
|
+
|
|
524
|
+
<!-- snippet: no-compile a region of tests/tutorial/multi_agents-lessons.test.ts; the test file itself is type-checked and run --> <!-- include: tests/tutorial/multi_agents-lessons.test.ts#unit-test -->
|
|
525
|
+
```typescript
|
|
526
|
+
it('calculates the price with tax', async () => {
|
|
527
|
+
const fn = advanced.getTool('calculate_price')!;
|
|
528
|
+
const result = await fn.execute({ amount: 100, tax_rate: 0.08 });
|
|
529
|
+
expect(result['response']).toBe('The total price is $108.00 ($100.00 + $8.00 tax)');
|
|
530
|
+
|
|
531
|
+
// The tax rate is optional, and defaults to 8%
|
|
532
|
+
const noRate = await fn.execute({ amount: 50 });
|
|
533
|
+
expect(noRate['response']).toContain('$54.00');
|
|
534
|
+
});
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
`execute()` returns the response the agent would send, with `response`, and `action` when the result has actions.
|
|
538
|
+
|
|
539
|
+
### Integration testing
|
|
540
|
+
|
|
541
|
+
`agent.getApp()` returns the agent's HTTP app, and its `request()` sends a request without a server or a port. This test checks the credentials and the SWML:
|
|
542
|
+
|
|
543
|
+
<!-- snippet: no-compile a region of tests/tutorial/multi_agents-lessons.test.ts; the test file itself is type-checked and run --> <!-- include: tests/tutorial/multi_agents-lessons.test.ts#integration-test -->
|
|
544
|
+
```typescript
|
|
545
|
+
it('serves SWML that lists calculate_price, and refuses a request without credentials', async () => {
|
|
546
|
+
const app = advanced.getApp();
|
|
547
|
+
expect((await app.request('/')).status).toBe(401);
|
|
548
|
+
|
|
549
|
+
const res = await app.request('/', { headers: AUTH });
|
|
550
|
+
expect(res.status).toBe(200);
|
|
551
|
+
const swml = (await res.json()) as Swml;
|
|
552
|
+
const ai = swml.sections.main.find((verb) => verb.ai)!.ai!;
|
|
553
|
+
const names = ai.SWAIG.functions.map((f) => f.function);
|
|
554
|
+
expect(names).toContain('calculate_price');
|
|
555
|
+
});
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
To call a tool over HTTP as SignalWire does, read the tool's `web_hook_url` from the SWML, and POST to it with the token it carries. `tests/tutorial/multi_agents.test.ts` does that for every agent in this tutorial.
|
|
559
|
+
|
|
560
|
+
A test can also run `swaig-test` itself, as `tests/tutorial/multi_agents-lessons.test.ts` does with `execFileSync`.
|
|
561
|
+
|
|
562
|
+
### Load testing
|
|
563
|
+
|
|
564
|
+
Apache Bench sends concurrent requests to the SWML route. Pass the credentials with `-A`:
|
|
565
|
+
|
|
566
|
+
```bash
|
|
567
|
+
ab -n 1000 -c 10 -A devuser:devpassword http://localhost:3000/
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
On a development machine, the agent served all 1000 requests. These are the lines of the report that matter:
|
|
571
|
+
|
|
572
|
+
```text
|
|
573
|
+
Complete requests: 1000
|
|
574
|
+
Failed requests: 0
|
|
575
|
+
Requests per second: 480.98 [#/sec] (mean)
|
|
576
|
+
Time per request: 20.791 [ms] (mean)
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
Load-test the tools that call slow services too, because those set how many calls one process can serve.
|
|
580
|
+
|
|
581
|
+
## Performance optimization
|
|
582
|
+
|
|
583
|
+
Most of a tool's time goes to the services it calls, so start there.
|
|
584
|
+
|
|
585
|
+
### Caching strategies
|
|
586
|
+
|
|
587
|
+
Cache a slow lookup in a `Map`, with an expiry time on each entry:
|
|
588
|
+
|
|
589
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#caching -->
|
|
590
|
+
```typescript
|
|
591
|
+
// Stands in for a slow database or API call
|
|
592
|
+
async function lookupProduct(productId: string): Promise<string> {
|
|
593
|
+
await new Promise((resolve) => setTimeout(resolve, 200));
|
|
594
|
+
return `Product ${productId}: 16GB DDR5 memory kit`;
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
const productCache = new Map<string, { value: string; expires: number }>();
|
|
598
|
+
const CACHE_TTL_MS = 5 * 60 * 1000;
|
|
599
|
+
|
|
600
|
+
agent.defineTool({
|
|
601
|
+
name: 'get_product_info',
|
|
602
|
+
description: 'Get product information',
|
|
603
|
+
parameters: {
|
|
604
|
+
product_id: { type: 'string', description: 'The product ID to look up' },
|
|
605
|
+
},
|
|
606
|
+
required: ['product_id'],
|
|
607
|
+
handler: async ({ product_id }) => {
|
|
608
|
+
const cached = productCache.get(product_id);
|
|
609
|
+
if (cached && cached.expires > Date.now()) {
|
|
610
|
+
log.debug('cache hit', { product_id });
|
|
611
|
+
return new FunctionResult(cached.value);
|
|
612
|
+
}
|
|
613
|
+
const info = await lookupProduct(product_id);
|
|
614
|
+
productCache.set(product_id, { value: info, expires: Date.now() + CACHE_TTL_MS });
|
|
615
|
+
return new FunctionResult(info);
|
|
616
|
+
},
|
|
617
|
+
});
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
The cache is per process. With several replicas, each has its own. Use a shared cache such as Redis when the replicas must agree.
|
|
621
|
+
|
|
622
|
+
### Running independent work concurrently
|
|
623
|
+
|
|
624
|
+
`Promise.all()` runs independent lookups at the same time, so the tool takes as long as the slowest one, not the sum of all three:
|
|
625
|
+
|
|
626
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#concurrent -->
|
|
627
|
+
```typescript
|
|
628
|
+
// Stand-ins for three independent services
|
|
629
|
+
const getOrders = async (id: string) => [`${id}-order-1`, `${id}-order-2`];
|
|
630
|
+
const getProfile = async (id: string) => ({ id, tier: 'gold' });
|
|
631
|
+
const getPreferences = async (id: string) => ({ id, contact: 'email' });
|
|
632
|
+
|
|
633
|
+
agent.defineTool({
|
|
634
|
+
name: 'get_full_info',
|
|
635
|
+
description: 'Get complete customer information',
|
|
636
|
+
parameters: {
|
|
637
|
+
customer_id: { type: 'string', description: 'The customer ID' },
|
|
638
|
+
},
|
|
639
|
+
required: ['customer_id'],
|
|
640
|
+
handler: async ({ customer_id }) => {
|
|
641
|
+
// The three lookups run at the same time, not one after another
|
|
642
|
+
const [orders, profile, preferences] = await Promise.all([
|
|
643
|
+
getOrders(customer_id),
|
|
644
|
+
getProfile(customer_id),
|
|
645
|
+
getPreferences(customer_id),
|
|
646
|
+
]);
|
|
647
|
+
return new FunctionResult(
|
|
648
|
+
`Found ${orders.length} orders for a ${profile.tier} customer who prefers ${preferences.contact}`,
|
|
649
|
+
);
|
|
650
|
+
},
|
|
651
|
+
});
|
|
652
|
+
```
|
|
653
|
+
|
|
654
|
+
Awaiting them one after another would add up the three wait times.
|
|
655
|
+
|
|
656
|
+
### Memory management
|
|
657
|
+
|
|
658
|
+
A few habits keep a long-running agent's memory flat:
|
|
659
|
+
|
|
660
|
+
- Keep search results small. Lesson 2's `count: 3` returns three sections, not the whole knowledge base.
|
|
661
|
+
- Give per-call state an end. Lesson 5 deletes an order when it's confirmed.
|
|
662
|
+
- Put an expiry on caches, as the product cache does, and a size limit if the key space is large.
|
|
663
|
+
|
|
664
|
+
## Security best practices
|
|
665
|
+
|
|
666
|
+
Tool arguments come from the model, which takes them from what the caller said. Treat them as untrusted input.
|
|
667
|
+
|
|
668
|
+
### Input sanitization
|
|
669
|
+
|
|
670
|
+
Strip the characters a query doesn't need, and cap the length, before you use caller-supplied text:
|
|
671
|
+
|
|
672
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#sanitize -->
|
|
673
|
+
```typescript
|
|
674
|
+
const catalog = ['RTX 4070', 'RTX 4090', 'Ryzen 7 7700X', 'Z790 motherboard'];
|
|
675
|
+
|
|
676
|
+
agent.defineTool({
|
|
677
|
+
name: 'safe_search',
|
|
678
|
+
description: 'Search the product catalog',
|
|
679
|
+
parameters: {
|
|
680
|
+
query: { type: 'string', description: 'Search query' },
|
|
681
|
+
},
|
|
682
|
+
required: ['query'],
|
|
683
|
+
handler: ({ query }) => {
|
|
684
|
+
// Keep letters, digits, spaces and hyphens, and at most 100 characters
|
|
685
|
+
const safeQuery = query
|
|
686
|
+
.replace(/[^\w\s-]/g, '')
|
|
687
|
+
.trim()
|
|
688
|
+
.slice(0, 100);
|
|
689
|
+
if (!safeQuery) return new FunctionResult('Invalid search query');
|
|
690
|
+
const results = catalog.filter((item) => item.toLowerCase().includes(safeQuery.toLowerCase()));
|
|
691
|
+
return new FunctionResult(`Found ${results.length} results: ${results.join(', ')}`);
|
|
692
|
+
},
|
|
693
|
+
});
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
For a database, use parameterized queries, as Lesson 5's SQLite example does, instead of building SQL from strings.
|
|
697
|
+
|
|
698
|
+
### Secrets management
|
|
699
|
+
|
|
700
|
+
Read secrets from the environment, and never log them or put them in a prompt:
|
|
701
|
+
|
|
702
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#secrets -->
|
|
703
|
+
```typescript
|
|
704
|
+
// Read secrets from the environment, and never log them
|
|
705
|
+
const apiKey = process.env['PARTNER_API_KEY'];
|
|
706
|
+
if (!apiKey) log.warn('PARTNER_API_KEY not set');
|
|
707
|
+
|
|
708
|
+
agent.defineTool({
|
|
709
|
+
name: 'check_partner_stock',
|
|
710
|
+
description: 'Check stock at the partner warehouse',
|
|
711
|
+
parameters: {
|
|
712
|
+
sku: { type: 'string', description: 'The product SKU' },
|
|
713
|
+
},
|
|
714
|
+
required: ['sku'],
|
|
715
|
+
handler: async ({ sku }) => {
|
|
716
|
+
const base = process.env['PARTNER_API_URL'];
|
|
717
|
+
if (!apiKey || !base) return new FunctionResult('The partner API is not configured.');
|
|
718
|
+
log.info('calling partner API', { sku }); // the key stays out of the log
|
|
719
|
+
const res = await fetch(`${base}/stock/${encodeURIComponent(sku)}`, {
|
|
720
|
+
headers: { Authorization: `Bearer ${apiKey}` },
|
|
721
|
+
signal: AbortSignal.timeout(5000),
|
|
722
|
+
});
|
|
723
|
+
return new FunctionResult(
|
|
724
|
+
res.ok ? `Partner stock for ${sku}: ${await res.text()}` : 'Unable to check partner stock.',
|
|
725
|
+
);
|
|
726
|
+
},
|
|
727
|
+
});
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
### Rate limiting
|
|
731
|
+
|
|
732
|
+
Limit how often one caller can run an expensive tool. Key the limit by the caller's number from the request, not by an argument, because the model fills in arguments:
|
|
733
|
+
|
|
734
|
+
<!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#rate-limit -->
|
|
735
|
+
```typescript
|
|
736
|
+
// Calls per caller in the last minute. The caller comes from the request
|
|
737
|
+
// SignalWire sends, not from an argument the model fills in.
|
|
738
|
+
const callTimes = new Map<string, number[]>();
|
|
739
|
+
const LIMIT_PER_MINUTE = 10;
|
|
740
|
+
|
|
741
|
+
agent.defineTool({
|
|
742
|
+
name: 'limited_function',
|
|
743
|
+
description: 'A function each caller may run 10 times a minute',
|
|
744
|
+
handler: (_args, rawData) => {
|
|
745
|
+
const caller = rawData.caller_id_num ?? rawData.call_id ?? 'unknown';
|
|
746
|
+
const now = Date.now();
|
|
747
|
+
const recent = (callTimes.get(caller) ?? []).filter((t) => t > now - 60_000);
|
|
748
|
+
if (recent.length >= LIMIT_PER_MINUTE) {
|
|
749
|
+
callTimes.set(caller, recent);
|
|
750
|
+
return new FunctionResult('Rate limit exceeded. Please try again later.');
|
|
751
|
+
}
|
|
752
|
+
recent.push(now);
|
|
753
|
+
callTimes.set(caller, recent);
|
|
754
|
+
return new FunctionResult('Function executed successfully');
|
|
755
|
+
},
|
|
756
|
+
});
|
|
757
|
+
```
|
|
758
|
+
|
|
759
|
+
To limit requests per client address on all of the agent's routes as well, set `SWML_RATE_LIMIT` to the number of requests a minute to allow. SignalWire's own requests count too, so set it well above your call volume.
|
|
760
|
+
|
|
761
|
+
### Request verification
|
|
762
|
+
|
|
763
|
+
Set `SIGNALWIRE_SIGNING_KEY` in production. With it, the agent checks the signature SignalWire puts on each request, and refuses a request that doesn't have a valid one. Without it, the agent logs a warning at startup.
|
|
764
|
+
|
|
765
|
+
## Summary
|
|
766
|
+
|
|
767
|
+
This lesson covered what an agent needs before production. The main points:
|
|
768
|
+
|
|
769
|
+
- `defineTool()` takes parameters as JSON Schema, and infers the handler's argument types from them
|
|
770
|
+
- A `FunctionResult` tells the model what happened, and carries actions such as `updateGlobalData()`
|
|
771
|
+
- Handle expected errors in the handler, and let the SDK's generic message cover the rest
|
|
772
|
+
- `getLogger()` gives structured logs, and `swaig-test` runs tools without a call
|
|
773
|
+
- The environment carries the credentials, the signing key, the token secret and the SSL settings
|
|
774
|
+
- `getTool().execute()` and `getApp().request()` test an agent without a server
|
|
775
|
+
|
|
776
|
+
### Practice exercises
|
|
777
|
+
|
|
778
|
+
Try these before you move on:
|
|
779
|
+
|
|
780
|
+
1. **Build a calculator agent**: add, subtract, multiply and divide tools, with a clear result for division by zero.
|
|
781
|
+
2. **Add caching**: cache the review service's answers in `fetch_product_reviews`.
|
|
782
|
+
3. **Extend the status route**: report whether the knowledge base loaded, and how many sections it has.
|
|
783
|
+
4. **Review an agent**: find every place a tool uses an argument without checking it.
|
|
784
|
+
|
|
785
|
+
### Production checklist
|
|
786
|
+
|
|
787
|
+
Check each item before the agent takes real calls:
|
|
788
|
+
|
|
789
|
+
- [ ] Credentials, signing key and token secret set from the environment
|
|
790
|
+
- [ ] HTTPS served by the agent, or by a proxy with `SWML_PROXY_URL_BASE` set
|
|
791
|
+
- [ ] Log level set, and no secrets in the logs
|
|
792
|
+
- [ ] Every tool returns a useful result on failure
|
|
793
|
+
- [ ] Health checks point at `/health`
|
|
794
|
+
- [ ] Monitoring and alerts set up
|
|
795
|
+
- [ ] Load tested, including the slow tools
|
|
796
|
+
- [ ] Tool arguments validated
|
|
797
|
+
- [ ] Tests pass
|
|
798
|
+
|
|
799
|
+
### Next steps
|
|
800
|
+
|
|
801
|
+
Next, write a skill of your own, and keep state across a call. Continue with [Lesson 5: Extending Your Agents](lesson5_extending_agents.md).
|
|
802
|
+
|
|
803
|
+
---
|
|
804
|
+
|
|
805
|
+
[Previous: Lesson 3 - Building Multi-Agent Systems](lesson3_multi_agent_systems.md) | [Tutorial Overview](README.md) | [Next: Lesson 5 - Extending Your Agents](lesson5_extending_agents.md)
|