@signalwire/sdk 2.0.1 → 2.0.2
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/dist/AgentBase.d.ts +1045 -0
- package/dist/AgentBase.js +2375 -0
- package/dist/AgentBase.js.map +1 -0
- package/dist/AgentServer.d.ts +146 -0
- package/dist/AgentServer.js +388 -0
- package/dist/AgentServer.js.map +1 -0
- package/dist/AuthHandler.d.ts +127 -0
- package/dist/AuthHandler.js +212 -0
- package/dist/AuthHandler.js.map +1 -0
- package/dist/ConfigLoader.d.ts +170 -0
- package/dist/ConfigLoader.js +393 -0
- package/dist/ConfigLoader.js.map +1 -0
- package/dist/ContextBuilder.d.ts +652 -0
- package/dist/ContextBuilder.js +1115 -0
- package/dist/ContextBuilder.js.map +1 -0
- package/dist/DataMap.d.ts +271 -0
- package/dist/DataMap.js +430 -0
- package/dist/DataMap.js.map +1 -0
- package/dist/FunctionResult.d.ts +481 -0
- package/dist/FunctionResult.js +775 -0
- package/dist/FunctionResult.js.map +1 -0
- package/dist/Logger.d.ts +113 -0
- package/dist/Logger.js +320 -0
- package/dist/Logger.js.map +1 -0
- package/dist/PomBuilder.d.ts +208 -0
- package/dist/PomBuilder.js +409 -0
- package/dist/PomBuilder.js.map +1 -0
- package/dist/PromptManager.d.ts +85 -0
- package/dist/PromptManager.js +108 -0
- package/dist/PromptManager.js.map +1 -0
- package/dist/SWMLHandler.d.ts +159 -0
- package/dist/SWMLHandler.js +229 -0
- package/dist/SWMLHandler.js.map +1 -0
- package/dist/SWMLService.d.ts +326 -0
- package/dist/SWMLService.js +610 -0
- package/dist/SWMLService.js.map +1 -0
- package/dist/SchemaUtils.d.ts +108 -0
- package/dist/SchemaUtils.js +317 -0
- package/dist/SchemaUtils.js.map +1 -0
- package/dist/SecurityUtils.d.ts +60 -0
- package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
- package/dist/SecurityUtils.js.map +1 -0
- package/dist/ServerlessAdapter.d.ts +119 -0
- package/dist/ServerlessAdapter.js +188 -0
- package/dist/ServerlessAdapter.js.map +1 -0
- package/dist/SessionManager.d.ts +142 -0
- package/dist/SessionManager.js +260 -0
- package/dist/SessionManager.js.map +1 -0
- package/dist/SslConfig.d.ts +77 -0
- package/dist/SslConfig.js +100 -0
- package/dist/SslConfig.js.map +1 -0
- package/dist/SwaigFunction.d.ts +159 -0
- package/dist/SwaigFunction.js +209 -0
- package/dist/SwaigFunction.js.map +1 -0
- package/dist/SwmlBuilder.d.ts +165 -0
- package/dist/SwmlBuilder.js +247 -0
- package/dist/SwmlBuilder.js.map +1 -0
- package/dist/SwmlVerbMethods.generated.d.ts +254 -0
- package/dist/SwmlVerbMethods.generated.js +9 -0
- package/dist/SwmlVerbMethods.generated.js.map +1 -0
- package/dist/TypeInference.d.ts +71 -0
- package/dist/TypeInference.js +164 -0
- package/dist/TypeInference.js.map +1 -0
- package/dist/WebService.d.ts +148 -0
- package/dist/WebService.js +532 -0
- package/dist/WebService.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +22 -0
- package/dist/cli/agent-loader.js +144 -0
- package/dist/cli/agent-loader.js.map +1 -0
- package/dist/cli/mock-data.d.ts +37 -0
- package/dist/cli/mock-data.js +80 -0
- package/dist/cli/mock-data.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +32 -0
- package/dist/cli/swaig-test.js +418 -0
- package/dist/cli/swaig-test.js.map +1 -0
- package/dist/generateVerbTypes.d.ts +11 -0
- package/dist/generateVerbTypes.js +265 -0
- package/dist/generateVerbTypes.js.map +1 -0
- package/{src/index.ts → dist/index.d.ts} +13 -100
- package/dist/index.js +152 -0
- package/dist/index.js.map +1 -0
- package/dist/livewire/index.d.ts +653 -0
- package/dist/livewire/index.js +992 -0
- package/dist/livewire/index.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +89 -0
- package/dist/prefabs/ConciergeAgent.js +245 -0
- package/dist/prefabs/ConciergeAgent.js.map +1 -0
- package/dist/prefabs/FAQBotAgent.d.ts +113 -0
- package/dist/prefabs/FAQBotAgent.js +329 -0
- package/dist/prefabs/FAQBotAgent.js.map +1 -0
- package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
- package/dist/prefabs/InfoGathererAgent.js +287 -0
- package/dist/prefabs/InfoGathererAgent.js.map +1 -0
- package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
- package/dist/prefabs/ReceptionistAgent.js +303 -0
- package/dist/prefabs/ReceptionistAgent.js.map +1 -0
- package/dist/prefabs/SurveyAgent.d.ts +148 -0
- package/dist/prefabs/SurveyAgent.js +540 -0
- package/dist/prefabs/SurveyAgent.js.map +1 -0
- package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
- package/dist/prefabs/index.js +14 -0
- package/dist/prefabs/index.js.map +1 -0
- package/dist/relay/Action.d.ts +258 -0
- package/dist/relay/Action.js +402 -0
- package/dist/relay/Action.js.map +1 -0
- package/dist/relay/Call.d.ts +697 -0
- package/dist/relay/Call.js +1062 -0
- package/dist/relay/Call.js.map +1 -0
- package/dist/relay/Deferred.d.ts +44 -0
- package/dist/relay/Deferred.js +69 -0
- package/dist/relay/Deferred.js.map +1 -0
- package/dist/relay/Message.d.ts +103 -0
- package/dist/relay/Message.js +169 -0
- package/dist/relay/Message.js.map +1 -0
- package/dist/relay/RelayClient.d.ts +302 -0
- package/dist/relay/RelayClient.js +1019 -0
- package/dist/relay/RelayClient.js.map +1 -0
- package/dist/relay/RelayError.d.ts +15 -0
- package/dist/relay/RelayError.js +20 -0
- package/dist/relay/RelayError.js.map +1 -0
- package/dist/relay/RelayEvent.d.ts +254 -0
- package/dist/relay/RelayEvent.js +509 -0
- package/dist/relay/RelayEvent.js.map +1 -0
- package/dist/relay/constants.d.ts +90 -0
- package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
- package/dist/relay/constants.js.map +1 -0
- package/dist/relay/index.d.ts +16 -0
- package/dist/relay/index.js +18 -0
- package/dist/relay/index.js.map +1 -0
- package/dist/relay/types.d.ts +142 -0
- package/dist/relay/types.js +5 -0
- package/dist/relay/types.js.map +1 -0
- package/dist/rest/HttpClient.d.ts +80 -0
- package/dist/rest/HttpClient.js +148 -0
- package/dist/rest/HttpClient.js.map +1 -0
- package/dist/rest/RestError.d.ts +30 -0
- package/dist/rest/RestError.js +39 -0
- package/dist/rest/RestError.js.map +1 -0
- package/dist/rest/base/BaseResource.d.ts +24 -0
- package/dist/rest/base/BaseResource.js +29 -0
- package/dist/rest/base/BaseResource.js.map +1 -0
- package/dist/rest/base/CrudResource.d.ts +68 -0
- package/dist/rest/base/CrudResource.js +82 -0
- package/dist/rest/base/CrudResource.js.map +1 -0
- package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
- package/dist/rest/base/CrudWithAddresses.js +25 -0
- package/dist/rest/base/CrudWithAddresses.js.map +1 -0
- package/dist/rest/index.d.ts +131 -0
- package/{src/rest/index.ts → dist/rest/index.js} +101 -136
- package/dist/rest/index.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +46 -0
- package/dist/rest/namespaces/addresses.js +55 -0
- package/dist/rest/namespaces/addresses.js.map +1 -0
- package/dist/rest/namespaces/calling.d.ts +382 -0
- package/dist/rest/namespaces/calling.js +478 -0
- package/dist/rest/namespaces/calling.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +22 -0
- package/dist/rest/namespaces/chat.js +26 -0
- package/dist/rest/namespaces/chat.js.map +1 -0
- package/dist/rest/namespaces/compat.d.ts +585 -0
- package/dist/rest/namespaces/compat.js +735 -0
- package/dist/rest/namespaces/compat.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +66 -0
- package/dist/rest/namespaces/datasphere.js +77 -0
- package/dist/rest/namespaces/datasphere.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +282 -0
- package/dist/rest/namespaces/fabric.js +373 -0
- package/dist/rest/namespaces/fabric.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
- package/dist/rest/namespaces/imported-numbers.js +26 -0
- package/dist/rest/namespaces/imported-numbers.js.map +1 -0
- package/dist/rest/namespaces/logs.d.ts +105 -0
- package/dist/rest/namespaces/logs.js +133 -0
- package/dist/rest/namespaces/logs.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +29 -0
- package/dist/rest/namespaces/lookup.js +32 -0
- package/dist/rest/namespaces/lookup.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +46 -0
- package/dist/rest/namespaces/mfa.js +54 -0
- package/dist/rest/namespaces/mfa.js.map +1 -0
- package/dist/rest/namespaces/number-groups.d.ts +49 -0
- package/dist/rest/namespaces/number-groups.js +58 -0
- package/dist/rest/namespaces/number-groups.js.map +1 -0
- package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
- package/dist/rest/namespaces/phone-numbers.js +67 -0
- package/dist/rest/namespaces/phone-numbers.js.map +1 -0
- package/dist/rest/namespaces/project.d.ts +46 -0
- package/dist/rest/namespaces/project.js +56 -0
- package/dist/rest/namespaces/project.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +22 -0
- package/dist/rest/namespaces/pubsub.js +26 -0
- package/dist/rest/namespaces/pubsub.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +42 -0
- package/dist/rest/namespaces/queues.js +49 -0
- package/dist/rest/namespaces/queues.js.map +1 -0
- package/dist/rest/namespaces/recordings.d.ts +38 -0
- package/dist/rest/namespaces/recordings.js +45 -0
- package/dist/rest/namespaces/recordings.js.map +1 -0
- package/dist/rest/namespaces/registry.d.ts +141 -0
- package/dist/rest/namespaces/registry.js +178 -0
- package/dist/rest/namespaces/registry.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +39 -0
- package/dist/rest/namespaces/short-codes.js +46 -0
- package/dist/rest/namespaces/short-codes.js.map +1 -0
- package/dist/rest/namespaces/sip-profile.d.ts +28 -0
- package/dist/rest/namespaces/sip-profile.js +34 -0
- package/dist/rest/namespaces/sip-profile.js.map +1 -0
- package/dist/rest/namespaces/verified-callers.d.ts +33 -0
- package/dist/rest/namespaces/verified-callers.js +39 -0
- package/dist/rest/namespaces/verified-callers.js.map +1 -0
- package/dist/rest/namespaces/video.d.ts +235 -0
- package/dist/rest/namespaces/video.js +297 -0
- package/dist/rest/namespaces/video.js.map +1 -0
- package/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
- package/dist/rest/pagination.js +78 -0
- package/dist/rest/pagination.js.map +1 -0
- package/dist/rest/types.d.ts +54 -0
- package/dist/rest/types.js +5 -0
- package/dist/rest/types.js.map +1 -0
- package/dist/skills/SkillBase.d.ts +404 -0
- package/dist/skills/SkillBase.js +471 -0
- package/dist/skills/SkillBase.js.map +1 -0
- package/dist/skills/SkillManager.d.ts +195 -0
- package/dist/skills/SkillManager.js +378 -0
- package/dist/skills/SkillManager.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +176 -0
- package/dist/skills/SkillRegistry.js +310 -0
- package/dist/skills/SkillRegistry.js.map +1 -0
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
- package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
- package/dist/skills/builtin/ask_claude.d.ts +37 -0
- package/dist/skills/builtin/ask_claude.js +162 -0
- package/dist/skills/builtin/ask_claude.js.map +1 -0
- package/dist/skills/builtin/claude_skills.d.ts +75 -0
- package/dist/skills/builtin/claude_skills.js +753 -0
- package/dist/skills/builtin/claude_skills.js.map +1 -0
- package/dist/skills/builtin/custom_skills.d.ts +79 -0
- package/dist/skills/builtin/custom_skills.js +227 -0
- package/dist/skills/builtin/custom_skills.js.map +1 -0
- package/dist/skills/builtin/datasphere.d.ts +73 -0
- package/dist/skills/builtin/datasphere.js +350 -0
- package/dist/skills/builtin/datasphere.js.map +1 -0
- package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
- package/dist/skills/builtin/datasphere_serverless.js +291 -0
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
- package/dist/skills/builtin/datetime.d.ts +40 -0
- package/dist/skills/builtin/datetime.js +118 -0
- package/dist/skills/builtin/datetime.js.map +1 -0
- package/dist/skills/builtin/google_maps.d.ts +48 -0
- package/dist/skills/builtin/google_maps.js +470 -0
- package/dist/skills/builtin/google_maps.js.map +1 -0
- package/dist/skills/builtin/index.d.ts +31 -0
- package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
- package/dist/skills/builtin/index.js.map +1 -0
- package/dist/skills/builtin/info_gatherer.d.ts +115 -0
- package/dist/skills/builtin/info_gatherer.js +328 -0
- package/dist/skills/builtin/info_gatherer.js.map +1 -0
- package/dist/skills/builtin/joke.d.ts +41 -0
- package/dist/skills/builtin/joke.js +156 -0
- package/dist/skills/builtin/joke.js.map +1 -0
- package/dist/skills/builtin/math.d.ts +39 -0
- package/dist/skills/builtin/math.js +119 -0
- package/dist/skills/builtin/math.js.map +1 -0
- package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
- package/dist/skills/builtin/mcp_gateway.js +574 -0
- package/dist/skills/builtin/mcp_gateway.js.map +1 -0
- package/dist/skills/builtin/native_vector_search.d.ts +128 -0
- package/dist/skills/builtin/native_vector_search.js +752 -0
- package/dist/skills/builtin/native_vector_search.js.map +1 -0
- package/dist/skills/builtin/play_background_file.d.ts +59 -0
- package/dist/skills/builtin/play_background_file.js +274 -0
- package/dist/skills/builtin/play_background_file.js.map +1 -0
- package/dist/skills/builtin/spider.d.ts +91 -0
- package/dist/skills/builtin/spider.js +758 -0
- package/dist/skills/builtin/spider.js.map +1 -0
- package/dist/skills/builtin/swml_transfer.d.ts +66 -0
- package/dist/skills/builtin/swml_transfer.js +475 -0
- package/dist/skills/builtin/swml_transfer.js.map +1 -0
- package/dist/skills/builtin/weather_api.d.ts +59 -0
- package/dist/skills/builtin/weather_api.js +196 -0
- package/dist/skills/builtin/weather_api.js.map +1 -0
- package/dist/skills/builtin/web_search.d.ts +160 -0
- package/dist/skills/builtin/web_search.js +894 -0
- package/dist/skills/builtin/web_search.js.map +1 -0
- package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
- package/dist/skills/builtin/wikipedia_search.js +241 -0
- package/dist/skills/builtin/wikipedia_search.js.map +1 -0
- package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
- package/dist/skills/index.js +10 -0
- package/dist/skills/index.js.map +1 -0
- package/dist/types.d.ts +118 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- package/package.json +7 -1
- package/.github/workflows/publish.yml +0 -27
- package/.github/workflows/test.yml +0 -17
- package/CLAUDE.md +0 -112
- package/docs/MIGRATION-2.0.md +0 -81
- package/docs/agent-guide.md +0 -869
- package/docs/agent_guide.md +0 -1026
- package/docs/api-reference.md +0 -2420
- package/docs/api_reference.md +0 -1301
- package/docs/architecture.md +0 -843
- package/docs/cli-guide.md +0 -579
- package/docs/cli_guide.md +0 -448
- package/docs/cloud_functions_guide.md +0 -474
- package/docs/configuration.md +0 -422
- package/docs/contexts-guide.md +0 -787
- package/docs/contexts_guide.md +0 -511
- package/docs/datamap-guide.md +0 -1141
- package/docs/datamap_guide.md +0 -595
- package/docs/llm_parameters.md +0 -239
- package/docs/mcp_gateway_reference.md +0 -648
- package/docs/mcp_integration.md +0 -108
- package/docs/prefabs-guide.md +0 -800
- package/docs/sdk_features.md +0 -477
- package/docs/security.md +0 -436
- package/docs/serverless-guide.md +0 -513
- package/docs/skills-guide.md +0 -857
- package/docs/skills-system.md +0 -301
- package/docs/skills_parameter_schema.md +0 -392
- package/docs/skills_system.md +0 -467
- package/docs/swaig-reference.md +0 -1627
- package/docs/swaig_reference.md +0 -910
- package/docs/swml_service_guide.md +0 -600
- package/docs/third_party_skills.md +0 -533
- package/docs/web_service.md +0 -677
- package/examples/README.md +0 -131
- package/examples/advanced-datamap.ts +0 -100
- package/examples/advanced-dynamic-config.ts +0 -70
- package/examples/auto-vivified.ts +0 -94
- package/examples/call-flow.ts +0 -63
- package/examples/comprehensive-dynamic.ts +0 -125
- package/examples/contexts-steps.ts +0 -65
- package/examples/custom-path.ts +0 -45
- package/examples/datamap-tools.ts +0 -55
- package/examples/datasphere-multi-instance.ts +0 -63
- package/examples/datasphere-serverless-env.ts +0 -68
- package/examples/datasphere-webhook-env.ts +0 -66
- package/examples/datasphere.ts +0 -37
- package/examples/declarative.ts +0 -100
- package/examples/dynamic-config.ts +0 -54
- package/examples/dynamic-info-gatherer.ts +0 -69
- package/examples/dynamic-swml-service.ts +0 -67
- package/examples/gather-info.ts +0 -71
- package/examples/gather-per-question-functions-demo.ts +0 -140
- package/examples/joke-agent.ts +0 -34
- package/examples/kubernetes-agent.ts +0 -45
- package/examples/llm-params.ts +0 -69
- package/examples/mcp-agent.ts +0 -84
- package/examples/mcp-gateway.ts +0 -35
- package/examples/multi-agent.ts +0 -73
- package/examples/multi-endpoint.ts +0 -79
- package/examples/pom-prompt.ts +0 -71
- package/examples/prefab-concierge.ts +0 -47
- package/examples/prefab-faq.ts +0 -54
- package/examples/prefab-info-gatherer.ts +0 -33
- package/examples/prefab-receptionist.ts +0 -36
- package/examples/prefab-survey.ts +0 -68
- package/examples/record-call.ts +0 -67
- package/examples/relay-demo.ts +0 -33
- package/examples/room-and-sip.ts +0 -94
- package/examples/serverless-lambda.ts +0 -35
- package/examples/session-state.ts +0 -83
- package/examples/simple-agent.ts +0 -36
- package/examples/simple-static.ts +0 -29
- package/examples/skills-demo.ts +0 -38
- package/examples/step-function-inheritance-demo.ts +0 -124
- package/examples/swaig-features.ts +0 -187
- package/examples/swml-service-routing.ts +0 -66
- package/examples/swml-service.ts +0 -38
- package/examples/tap.ts +0 -68
- package/examples/verb-methods.ts +0 -45
- package/examples/web-search-multi-instance.ts +0 -72
- package/examples/web-search.ts +0 -38
- package/examples/wikipedia.ts +0 -36
- package/livewire/README.md +0 -140
- package/livewire/docs/migration-guide.md +0 -228
- package/livewire/examples/livewire-basic-agent.ts +0 -74
- package/livewire/examples/livewire-handoff.ts +0 -197
- package/livewire/examples/livewire-multi-tool.ts +0 -117
- package/relay/README.md +0 -70
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
- package/relay/docs/call-methods.md +0 -474
- package/relay/docs/client-reference.md +0 -142
- package/relay/docs/events.md +0 -134
- package/relay/docs/getting-started.md +0 -134
- package/relay/docs/guide.md +0 -306
- package/relay/docs/messaging.md +0 -182
- package/relay/examples/relay-inbound.ts +0 -66
- package/relay/examples/relay-messaging.ts +0 -71
- package/relay/examples/relay-outbound.ts +0 -76
- package/rest/README.md +0 -95
- package/rest/docs/calling.md +0 -273
- package/rest/docs/client-reference.md +0 -107
- package/rest/docs/compat.md +0 -204
- package/rest/docs/fabric.md +0 -183
- package/rest/docs/getting-started.md +0 -110
- package/rest/docs/guide.md +0 -351
- package/rest/docs/namespaces.md +0 -285
- package/rest/examples/rest-10dlc-registration.ts +0 -161
- package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
- package/rest/examples/rest-calling-play-and-record.ts +0 -91
- package/rest/examples/rest-client.ts +0 -65
- package/rest/examples/rest-compat-laml.ts +0 -210
- package/rest/examples/rest-datasphere-search.ts +0 -82
- package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
- package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
- package/rest/examples/rest-manage-resources.ts +0 -65
- package/rest/examples/rest-phone-number-management.ts +0 -197
- package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
- package/rest/examples/rest-video-rooms.ts +0 -186
- package/src/AgentBase.ts +0 -2598
- package/src/AgentServer.ts +0 -442
- package/src/AuthHandler.ts +0 -256
- package/src/ConfigLoader.ts +0 -447
- package/src/ContextBuilder.ts +0 -1181
- package/src/DataMap.ts +0 -477
- package/src/FunctionResult.ts +0 -903
- package/src/Logger.ts +0 -337
- package/src/PomBuilder.ts +0 -467
- package/src/PromptManager.ts +0 -133
- package/src/SWMLHandler.ts +0 -298
- package/src/SWMLService.ts +0 -749
- package/src/SchemaUtils.ts +0 -361
- package/src/ServerlessAdapter.ts +0 -240
- package/src/SessionManager.ts +0 -311
- package/src/SslConfig.ts +0 -118
- package/src/SwaigFunction.ts +0 -276
- package/src/SwmlBuilder.ts +0 -283
- package/src/SwmlVerbMethods.generated.ts +0 -234
- package/src/TypeInference.ts +0 -199
- package/src/WebService.ts +0 -641
- package/src/cli/agent-loader.ts +0 -166
- package/src/cli/mock-data.ts +0 -111
- package/src/cli/swaig-test.ts +0 -452
- package/src/generateVerbTypes.ts +0 -322
- package/src/livewire/index.ts +0 -1252
- package/src/prefabs/ConciergeAgent.ts +0 -309
- package/src/prefabs/FAQBotAgent.ts +0 -415
- package/src/prefabs/InfoGathererAgent.ts +0 -379
- package/src/prefabs/ReceptionistAgent.ts +0 -395
- package/src/prefabs/SurveyAgent.ts +0 -671
- package/src/relay/Action.ts +0 -482
- package/src/relay/Call.ts +0 -1270
- package/src/relay/Deferred.ts +0 -94
- package/src/relay/Message.ts +0 -199
- package/src/relay/RelayClient.ts +0 -1185
- package/src/relay/RelayError.ts +0 -20
- package/src/relay/RelayEvent.ts +0 -944
- package/src/relay/index.ts +0 -123
- package/src/relay/types.ts +0 -149
- package/src/rest/HttpClient.ts +0 -164
- package/src/rest/RestError.ts +0 -45
- package/src/rest/base/BaseResource.ts +0 -32
- package/src/rest/base/CrudResource.ts +0 -98
- package/src/rest/base/CrudWithAddresses.ts +0 -37
- package/src/rest/namespaces/addresses.ts +0 -64
- package/src/rest/namespaces/calling.ts +0 -534
- package/src/rest/namespaces/chat.ts +0 -31
- package/src/rest/namespaces/compat.ts +0 -812
- package/src/rest/namespaces/datasphere.ts +0 -88
- package/src/rest/namespaces/fabric.ts +0 -417
- package/src/rest/namespaces/imported-numbers.ts +0 -31
- package/src/rest/namespaces/logs.ts +0 -151
- package/src/rest/namespaces/lookup.ts +0 -38
- package/src/rest/namespaces/mfa.ts +0 -61
- package/src/rest/namespaces/number-groups.ts +0 -68
- package/src/rest/namespaces/phone-numbers.ts +0 -76
- package/src/rest/namespaces/project.ts +0 -65
- package/src/rest/namespaces/pubsub.ts +0 -31
- package/src/rest/namespaces/queues.ts +0 -58
- package/src/rest/namespaces/recordings.ts +0 -53
- package/src/rest/namespaces/registry.ts +0 -200
- package/src/rest/namespaces/short-codes.ts +0 -54
- package/src/rest/namespaces/sip-profile.ts +0 -40
- package/src/rest/namespaces/verified-callers.ts +0 -46
- package/src/rest/namespaces/video.ts +0 -332
- package/src/rest/types.ts +0 -61
- package/src/skills/SkillBase.ts +0 -582
- package/src/skills/SkillManager.ts +0 -419
- package/src/skills/SkillRegistry.ts +0 -367
- package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
- package/src/skills/builtin/ask_claude.ts +0 -246
- package/src/skills/builtin/claude_skills.ts +0 -983
- package/src/skills/builtin/custom_skills.ts +0 -327
- package/src/skills/builtin/datasphere.ts +0 -447
- package/src/skills/builtin/datasphere_serverless.ts +0 -347
- package/src/skills/builtin/datetime.ts +0 -137
- package/src/skills/builtin/google_maps.ts +0 -656
- package/src/skills/builtin/info_gatherer.ts +0 -415
- package/src/skills/builtin/joke.ts +0 -196
- package/src/skills/builtin/math.ts +0 -149
- package/src/skills/builtin/mcp_gateway.ts +0 -685
- package/src/skills/builtin/native_vector_search.ts +0 -910
- package/src/skills/builtin/play_background_file.ts +0 -367
- package/src/skills/builtin/spider.ts +0 -874
- package/src/skills/builtin/swml_transfer.ts +0 -645
- package/src/skills/builtin/weather_api.ts +0 -255
- package/src/skills/builtin/web_search.ts +0 -1083
- package/src/skills/builtin/wikipedia_search.ts +0 -304
- package/src/types.ts +0 -132
- package/tests/AgentBase.test.ts +0 -1093
- package/tests/AgentServer.test.ts +0 -126
- package/tests/AuthHandler.test.ts +0 -133
- package/tests/ConfigLoader.test.ts +0 -151
- package/tests/ContextBuilder.test.ts +0 -108
- package/tests/DataMap.test.ts +0 -367
- package/tests/EphemeralSkillCopy.test.ts +0 -107
- package/tests/FunctionResult.test.ts +0 -298
- package/tests/GracefulShutdown.test.ts +0 -46
- package/tests/Logger.test.ts +0 -420
- package/tests/PomBuilder.test.ts +0 -228
- package/tests/ProxyDetection.test.ts +0 -228
- package/tests/SWMLService.test.ts +0 -320
- package/tests/SWMLVerbHandler.test.ts +0 -523
- package/tests/SchemaUtils.test.ts +0 -106
- package/tests/SchemaUtils.verb.test.ts +0 -206
- package/tests/SecurityUtils.test.ts +0 -192
- package/tests/ServerlessAdapter.test.ts +0 -222
- package/tests/SessionManager.test.ts +0 -257
- package/tests/SkillBaseFeatures.test.ts +0 -130
- package/tests/SkillMultiInstance.test.ts +0 -102
- package/tests/SkillParameterSchemas.test.ts +0 -134
- package/tests/SkillRegistrySchema.test.ts +0 -84
- package/tests/SslConfig.test.ts +0 -97
- package/tests/SwmlBuilder.test.ts +0 -400
- package/tests/TypeInference.test.ts +0 -165
- package/tests/VerbHandlerRegistry.test.ts +0 -128
- package/tests/cli/mock-data.test.ts +0 -113
- package/tests/cli/swaig-test.test.ts +0 -108
- package/tests/examples.test.ts +0 -194
- package/tests/fixtures/scrape-parity/README.md +0 -53
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
- package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
- package/tests/fixtures/scrape-parity/python_extract.py +0 -109
- package/tests/livewire/livewire.test.ts +0 -780
- package/tests/mcp.test.ts +0 -221
- package/tests/prefabs/prefabs.test.ts +0 -1093
- package/tests/relay/Action.test.ts +0 -392
- package/tests/relay/Call.test.ts +0 -535
- package/tests/relay/Deferred.test.ts +0 -71
- package/tests/relay/Message.test.ts +0 -164
- package/tests/relay/RelayClient.test.ts +0 -779
- package/tests/relay/RelayEvent.test.ts +0 -463
- package/tests/relay/helpers.ts +0 -79
- package/tests/rest/HttpClient.test.ts +0 -274
- package/tests/rest/RestError.test.ts +0 -53
- package/tests/rest/calling.test.ts +0 -156
- package/tests/rest/client.test.ts +0 -197
- package/tests/rest/compat.test.ts +0 -335
- package/tests/rest/datasphere.test.ts +0 -71
- package/tests/rest/fabric.test.ts +0 -186
- package/tests/rest/helpers.ts +0 -95
- package/tests/rest/logs.test.ts +0 -68
- package/tests/rest/pagination.test.ts +0 -133
- package/tests/rest/registry.test.ts +0 -94
- package/tests/rest/relay-rest.test.ts +0 -290
- package/tests/rest/video.test.ts +0 -173
- package/tests/setup.ts +0 -6
- package/tests/skills/SkillBase.test.ts +0 -108
- package/tests/skills/SkillManager.test.ts +0 -268
- package/tests/skills/SkillRegistry.test.ts +0 -176
- package/tests/skills/builtin.test.ts +0 -1472
- package/tests/skills/claude-skills.test.ts +0 -54
- package/tests/skills/custom-skills.test.ts +0 -53
- package/tests/skills/datasphere-serverless.test.ts +0 -70
- package/tests/skills/datasphere.test.ts +0 -107
- package/tests/skills/datetime.test.ts +0 -101
- package/tests/skills/google-maps.test.ts +0 -78
- package/tests/skills/info-gatherer.test.ts +0 -411
- package/tests/skills/joke.test.ts +0 -81
- package/tests/skills/math.test.ts +0 -68
- package/tests/skills/mcp-gateway.test.ts +0 -101
- package/tests/skills/play-background.test.ts +0 -54
- package/tests/skills/spider.test.ts +0 -108
- package/tests/skills/swml-transfer.test.ts +0 -178
- package/tests/skills/trivia.test.ts +0 -54
- package/tests/skills/vector-search.test.ts +0 -135
- package/tests/skills/weather-api.test.ts +0 -77
- package/tests/skills/web-search-parity.test.ts +0 -59
- package/tests/skills/web-search.test.ts +0 -103
- package/tests/skills/wikipedia.test.ts +0 -63
- package/tsconfig.json +0 -18
- package/vitest.config.ts +0 -9
- /package/{src → dist}/schema.json +0 -0
package/docs/agent_guide.md
DELETED
|
@@ -1,1026 +0,0 @@
|
|
|
1
|
-
# SignalWire AI Agents TypeScript SDK -- Agent Guide
|
|
2
|
-
|
|
3
|
-
## Table of Contents
|
|
4
|
-
|
|
5
|
-
- [Introduction](#introduction)
|
|
6
|
-
- [Creating an Agent](#creating-an-agent)
|
|
7
|
-
- [Prompts](#prompts)
|
|
8
|
-
- [Raw Text Prompts](#raw-text-prompts)
|
|
9
|
-
- [Prompt Object Model (POM)](#prompt-object-model-pom)
|
|
10
|
-
- [Declarative PROMPT_SECTIONS](#declarative-prompt_sections)
|
|
11
|
-
- [Tools (SWAIG Functions)](#tools-swaig-functions)
|
|
12
|
-
- [Defining Tools](#defining-tools)
|
|
13
|
-
- [Tool Parameters](#tool-parameters)
|
|
14
|
-
- [Secure Tools](#secure-tools)
|
|
15
|
-
- [FunctionResult](#functionresult)
|
|
16
|
-
- [DataMap (Server-Side Tools)](#datamap-server-side-tools)
|
|
17
|
-
- [Speech and Languages](#speech-and-languages)
|
|
18
|
-
- [Hints](#hints)
|
|
19
|
-
- [Languages](#languages)
|
|
20
|
-
- [Pronunciation](#pronunciation)
|
|
21
|
-
- [AI Parameters](#ai-parameters)
|
|
22
|
-
- [Global Data](#global-data)
|
|
23
|
-
- [Call Flow (5 Phases)](#call-flow-5-phases)
|
|
24
|
-
- [Dynamic Configuration](#dynamic-configuration)
|
|
25
|
-
- [Post-Prompt and Summaries](#post-prompt-and-summaries)
|
|
26
|
-
- [Skills System](#skills-system)
|
|
27
|
-
- [Multi-Agent Server](#multi-agent-server)
|
|
28
|
-
- [Subclassing AgentBase](#subclassing-agentbase)
|
|
29
|
-
- [HTTP Endpoints](#http-endpoints)
|
|
30
|
-
- [State Management](#state-management)
|
|
31
|
-
- [SIP Routing](#sip-routing)
|
|
32
|
-
- [Environment Variables](#environment-variables)
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
## Introduction
|
|
37
|
-
|
|
38
|
-
The SignalWire AI Agents TypeScript SDK lets you build AI-powered voice agents as HTTP microservices. Each agent is a lightweight HTTP server built on the [Hono](https://hono.dev/) framework that serves **SWML** (SignalWire Markup Language) documents and handles **SWAIG** (SignalWire AI Gateway) function callbacks.
|
|
39
|
-
|
|
40
|
-
When SignalWire receives an inbound call (or an outbound call is placed), it requests a SWML document from your agent's HTTP endpoint. The SWML document describes the entire call flow: answering, playing audio, launching the AI engine with a prompt, registering tools the AI can invoke, and handling post-call summaries. The agent SDK automates all of this -- you configure the prompt, define tools, and the SDK handles SWML rendering, webhook routing, authentication, and session management.
|
|
41
|
-
|
|
42
|
-
```
|
|
43
|
-
Caller --> SignalWire Platform --> GET/POST your-agent/ --> SWML document
|
|
44
|
-
POST your-agent/swaig --> tool execution
|
|
45
|
-
POST your-agent/post_prompt --> call summary
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
### Architecture Overview
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
+-------------------+
|
|
52
|
-
| Your Agent | (Extends AgentBase with your specific functionality)
|
|
53
|
-
+--------+----------+
|
|
54
|
-
|
|
|
55
|
-
+--------+----------+
|
|
56
|
-
| AgentBase | (HTTP server, SWML rendering, tool dispatch, auth)
|
|
57
|
-
+--------+----------+
|
|
58
|
-
|
|
|
59
|
-
+--------+----------+
|
|
60
|
-
| Hono HTTP Server | (Routes, middleware, CORS, rate limiting)
|
|
61
|
-
+--------------------+
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### Installation
|
|
65
|
-
|
|
66
|
-
```bash
|
|
67
|
-
npm install @signalwire/sdk
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
### Quick Start
|
|
71
|
-
|
|
72
|
-
```typescript
|
|
73
|
-
import { AgentBase, FunctionResult } from '@signalwire/sdk';
|
|
74
|
-
|
|
75
|
-
const agent = new AgentBase({ name: 'my-agent' });
|
|
76
|
-
|
|
77
|
-
agent.setPromptText('You are a helpful customer service agent for Acme Corp.');
|
|
78
|
-
|
|
79
|
-
agent.defineTool({
|
|
80
|
-
name: 'check_order_status',
|
|
81
|
-
description: 'Look up the status of a customer order by order number.',
|
|
82
|
-
parameters: {
|
|
83
|
-
order_id: { type: 'string', description: 'The order number to look up' },
|
|
84
|
-
},
|
|
85
|
-
handler: async (args) => {
|
|
86
|
-
const status = await lookupOrder(args.order_id as string);
|
|
87
|
-
return new FunctionResult(`Order ${args.order_id} is ${status}.`);
|
|
88
|
-
},
|
|
89
|
-
});
|
|
90
|
-
|
|
91
|
-
agent.serve();
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
## Creating an Agent
|
|
97
|
-
|
|
98
|
-
The `AgentBase` constructor accepts an `AgentOptions` object:
|
|
99
|
-
|
|
100
|
-
```typescript
|
|
101
|
-
import { AgentBase } from '@signalwire/sdk';
|
|
102
|
-
|
|
103
|
-
const agent = new AgentBase({
|
|
104
|
-
name: 'support-bot',
|
|
105
|
-
route: '/',
|
|
106
|
-
host: '0.0.0.0',
|
|
107
|
-
port: 3000,
|
|
108
|
-
basicAuth: ['admin', 's3cretP@ss'],
|
|
109
|
-
usePom: true,
|
|
110
|
-
tokenExpirySecs: 3600,
|
|
111
|
-
autoAnswer: true,
|
|
112
|
-
recordCall: false,
|
|
113
|
-
recordFormat: 'mp4',
|
|
114
|
-
recordStereo: true,
|
|
115
|
-
nativeFunctions: [],
|
|
116
|
-
suppressLogs: false,
|
|
117
|
-
});
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
### AgentOptions Reference
|
|
121
|
-
|
|
122
|
-
| Option | Type | Default | Description |
|
|
123
|
-
|--------|------|---------|-------------|
|
|
124
|
-
| `name` | `string` | **(required)** | Display name; also used as the default basic-auth username when credentials are auto-generated. |
|
|
125
|
-
| `route` | `string` | `"/"` | HTTP route path this agent listens on. |
|
|
126
|
-
| `host` | `string` | `"0.0.0.0"` | Hostname the server binds to. |
|
|
127
|
-
| `port` | `number` | `PORT` env or `3000` | Port number for the HTTP server. |
|
|
128
|
-
| `basicAuth` | `[string, string]` | auto-generated | Explicit `[username, password]` pair; if omitted, reads from env vars or generates random credentials. |
|
|
129
|
-
| `usePom` | `boolean` | `true` | Use Prompt Object Model for structured prompts. |
|
|
130
|
-
| `tokenExpirySecs` | `number` | `3600` | Session token validity in seconds for secure tools. |
|
|
131
|
-
| `autoAnswer` | `boolean` | `true` | Automatically insert an `answer` verb in the SWML call flow. |
|
|
132
|
-
| `recordCall` | `boolean` | `false` | Whether to record the call. |
|
|
133
|
-
| `recordFormat` | `string` | `"mp4"` | Recording format (e.g., `"mp4"`, `"wav"`). |
|
|
134
|
-
| `recordStereo` | `boolean` | `true` | Whether to record in stereo. |
|
|
135
|
-
| `defaultWebhookUrl` | `string` | `null` | Override the default SWAIG function webhook URL. |
|
|
136
|
-
| `nativeFunctions` | `string[]` | `[]` | List of built-in platform function names to include. |
|
|
137
|
-
| `agentId` | `string` | random hex | Unique identifier for this agent instance. |
|
|
138
|
-
| `suppressLogs` | `boolean` | `false` | Suppress all log output. |
|
|
139
|
-
|
|
140
|
-
### Basic Auth
|
|
141
|
-
|
|
142
|
-
Authentication credentials are resolved in this order:
|
|
143
|
-
|
|
144
|
-
1. **Provided** -- `basicAuth` option in the constructor.
|
|
145
|
-
2. **Environment** -- `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables.
|
|
146
|
-
3. **Generated** -- A random password is generated, using the agent name as the username. Credentials are logged at startup so you can retrieve them.
|
|
147
|
-
|
|
148
|
-
```typescript
|
|
149
|
-
// Explicit credentials
|
|
150
|
-
const agent = new AgentBase({
|
|
151
|
-
name: 'my-agent',
|
|
152
|
-
basicAuth: ['admin', 'hunter2'],
|
|
153
|
-
});
|
|
154
|
-
|
|
155
|
-
// Environment-based: set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD
|
|
156
|
-
const agent2 = new AgentBase({ name: 'my-agent' });
|
|
157
|
-
|
|
158
|
-
// Auto-generated: credentials are logged at startup
|
|
159
|
-
const agent3 = new AgentBase({ name: 'my-agent' });
|
|
160
|
-
// Logs: Auth: my-agent:**** (source: generated)
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
### Starting the Server
|
|
164
|
-
|
|
165
|
-
```typescript
|
|
166
|
-
// Start listening
|
|
167
|
-
await agent.serve();
|
|
168
|
-
// or equivalently:
|
|
169
|
-
await agent.run();
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
The server logs its address and auth credentials at startup:
|
|
173
|
-
|
|
174
|
-
```
|
|
175
|
-
Agent 'support-bot' running at http://0.0.0.0:3000/
|
|
176
|
-
Auth: support-bot:**** (source: generated)
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
---
|
|
180
|
-
|
|
181
|
-
## Prompts
|
|
182
|
-
|
|
183
|
-
The SDK provides two ways to define the system prompt sent to the AI: **raw text** and the **Prompt Object Model (POM)**.
|
|
184
|
-
|
|
185
|
-
### Raw Text Prompts
|
|
186
|
-
|
|
187
|
-
The simplest approach -- pass a complete prompt string:
|
|
188
|
-
|
|
189
|
-
```typescript
|
|
190
|
-
agent.setPromptText(`
|
|
191
|
-
You are a friendly receptionist for Dr. Smith's office.
|
|
192
|
-
You help patients schedule appointments and answer basic questions.
|
|
193
|
-
Always be polite and professional.
|
|
194
|
-
`);
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
When raw text is set, it is used verbatim as the AI's system prompt. This bypasses POM rendering.
|
|
198
|
-
|
|
199
|
-
### Prompt Object Model (POM)
|
|
200
|
-
|
|
201
|
-
POM allows you to build structured prompts from titled sections, body text, bullet points, and nested subsections. The SDK renders them as Markdown headings and lists. POM is enabled by default (`usePom: true`).
|
|
202
|
-
|
|
203
|
-
#### Adding Sections
|
|
204
|
-
|
|
205
|
-
```typescript
|
|
206
|
-
agent.promptAddSection('Personality', {
|
|
207
|
-
body: 'You are a cheerful and knowledgeable tech support agent.',
|
|
208
|
-
bullets: [
|
|
209
|
-
'Always greet the customer warmly',
|
|
210
|
-
'Ask clarifying questions before troubleshooting',
|
|
211
|
-
'Offer to escalate if you cannot resolve the issue',
|
|
212
|
-
],
|
|
213
|
-
});
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
#### Appending to Existing Sections
|
|
217
|
-
|
|
218
|
-
```typescript
|
|
219
|
-
agent.promptAddToSection('Personality', {
|
|
220
|
-
bullet: 'Never make promises about timelines',
|
|
221
|
-
});
|
|
222
|
-
|
|
223
|
-
agent.promptAddToSection('Personality', {
|
|
224
|
-
bullets: ['Speak in simple, non-technical language', 'Confirm understanding before proceeding'],
|
|
225
|
-
});
|
|
226
|
-
|
|
227
|
-
agent.promptAddToSection('Personality', {
|
|
228
|
-
body: 'Remember to always thank the customer at the end of the call.',
|
|
229
|
-
});
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
#### Subsections
|
|
233
|
-
|
|
234
|
-
```typescript
|
|
235
|
-
agent.promptAddSubsection('Personality', 'Tone', {
|
|
236
|
-
body: 'Maintain a warm but professional tone throughout the conversation.',
|
|
237
|
-
bullets: ['Avoid slang', 'Do not use jargon'],
|
|
238
|
-
});
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
#### Checking for Sections
|
|
242
|
-
|
|
243
|
-
```typescript
|
|
244
|
-
if (!agent.promptHasSection('Escalation')) {
|
|
245
|
-
agent.promptAddSection('Escalation', {
|
|
246
|
-
body: 'If the issue cannot be resolved, transfer to a human agent.',
|
|
247
|
-
});
|
|
248
|
-
}
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
#### Numbered Sections and Bullets
|
|
252
|
-
|
|
253
|
-
```typescript
|
|
254
|
-
agent.promptAddSection('Troubleshooting Steps', {
|
|
255
|
-
numbered: true,
|
|
256
|
-
numberedBullets: true,
|
|
257
|
-
bullets: [
|
|
258
|
-
'Ask the customer to restart the device',
|
|
259
|
-
'Check if the firmware is up to date',
|
|
260
|
-
'Try a factory reset',
|
|
261
|
-
],
|
|
262
|
-
});
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
#### Retrieving the Rendered Prompt
|
|
266
|
-
|
|
267
|
-
```typescript
|
|
268
|
-
const renderedPrompt: string = agent.getPrompt();
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
### Declarative PROMPT_SECTIONS
|
|
272
|
-
|
|
273
|
-
When subclassing `AgentBase`, you can define prompt sections declaratively as a static property. They are automatically applied in the constructor:
|
|
274
|
-
|
|
275
|
-
```typescript
|
|
276
|
-
class SupportAgent extends AgentBase {
|
|
277
|
-
static PROMPT_SECTIONS = [
|
|
278
|
-
{
|
|
279
|
-
title: 'Role',
|
|
280
|
-
body: 'You are a technical support agent for CloudCo.',
|
|
281
|
-
},
|
|
282
|
-
{
|
|
283
|
-
title: 'Guidelines',
|
|
284
|
-
bullets: [
|
|
285
|
-
'Be concise and helpful',
|
|
286
|
-
'Verify the customer identity before sharing account details',
|
|
287
|
-
],
|
|
288
|
-
},
|
|
289
|
-
];
|
|
290
|
-
|
|
291
|
-
constructor() {
|
|
292
|
-
super({ name: 'support-agent' });
|
|
293
|
-
this.defineTools();
|
|
294
|
-
}
|
|
295
|
-
}
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
---
|
|
299
|
-
|
|
300
|
-
## Tools (SWAIG Functions)
|
|
301
|
-
|
|
302
|
-
Tools (also called SWAIG functions) are actions the AI can invoke during a conversation. When the AI decides to call a tool, SignalWire sends a POST request to your agent's `/swaig` endpoint with the function name and arguments.
|
|
303
|
-
|
|
304
|
-
### SWAIG functions ARE LLM tools — descriptions matter
|
|
305
|
-
|
|
306
|
-
Before writing your first SWAIG function, internalize this: a SWAIG function is **exactly the same concept** as a "tool" in native OpenAI / Anthropic tool calling. There is no separate "SWAIG layer" between your function and the model. Each SWAIG function is rendered into the OpenAI tool schema format on every turn:
|
|
307
|
-
|
|
308
|
-
```json
|
|
309
|
-
{
|
|
310
|
-
"type": "function",
|
|
311
|
-
"function": {
|
|
312
|
-
"name": "your_function_name",
|
|
313
|
-
"description": "your description text",
|
|
314
|
-
"parameters": { /* your JSON schema */ }
|
|
315
|
-
}
|
|
316
|
-
}
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
That schema is sent to the model as part of the same API call that produces the next assistant message. The model reads:
|
|
320
|
-
|
|
321
|
-
- the **function `description`** to decide WHEN to call this tool
|
|
322
|
-
- the **per-parameter `description` strings** inside `parameters` to decide HOW to fill in each argument
|
|
323
|
-
|
|
324
|
-
This means **descriptions are prompt engineering**, not developer documentation. They are not a comment for the next human reading the code — they are instructions to the LLM that directly determine whether the model picks your tool when the user's request matches it.
|
|
325
|
-
|
|
326
|
-
Compare:
|
|
327
|
-
|
|
328
|
-
| Bad (model often misses the tool) | Good (model picks it reliably) |
|
|
329
|
-
|---|---|
|
|
330
|
-
| `description: 'Lookup function'` | `description: 'Look up a customer's account details by their account number. Use this BEFORE quoting any account-specific information (balance, plan, status, billing date). Don't use it for general product questions.'` |
|
|
331
|
-
| `description: 'the id'` (parameter) | `description: 'The customer's 8-digit account number, no dashes or spaces. Ask the user if they don't provide it.'` |
|
|
332
|
-
|
|
333
|
-
A vague description is the #1 cause of "the model has the right tool but doesn't call it" failures. When you find yourself debugging why the model isn't picking a tool that obviously matches the user's request, the first thing to check is whether the description tells the model — in plain language — when to use it and what makes it the right choice over sibling tools.
|
|
334
|
-
|
|
335
|
-
**Tool count matters too.** LLM tool selection accuracy degrades noticeably past ~7-8 simultaneously-active tools per call. If you have many tools, partition them across steps using `Step.setFunctions()` so only the relevant subset is active at any moment. See `contexts_guide.md` for the per-step whitelist mechanism.
|
|
336
|
-
|
|
337
|
-
### Defining Tools
|
|
338
|
-
|
|
339
|
-
Use `defineTool()` to register a tool:
|
|
340
|
-
|
|
341
|
-
```typescript
|
|
342
|
-
agent.defineTool({
|
|
343
|
-
name: 'get_weather',
|
|
344
|
-
description: 'Get the current weather for a city.',
|
|
345
|
-
parameters: {
|
|
346
|
-
city: { type: 'string', description: 'City name' },
|
|
347
|
-
units: { type: 'string', description: 'Temperature units', enum: ['celsius', 'fahrenheit'] },
|
|
348
|
-
},
|
|
349
|
-
required: ['city'],
|
|
350
|
-
handler: async (args, rawData) => {
|
|
351
|
-
const weather = await fetchWeather(args.city as string, args.units as string);
|
|
352
|
-
return new FunctionResult(
|
|
353
|
-
`The weather in ${args.city} is ${weather.temp} degrees and ${weather.condition}.`
|
|
354
|
-
);
|
|
355
|
-
},
|
|
356
|
-
});
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
The `handler` function receives two arguments:
|
|
360
|
-
|
|
361
|
-
| Argument | Type | Description |
|
|
362
|
-
|----------|------|-------------|
|
|
363
|
-
| `args` | `Record<string, unknown>` | Parsed arguments extracted by the AI from the user's speech. |
|
|
364
|
-
| `rawData` | `Record<string, unknown>` | The full raw SWAIG request payload from SignalWire. |
|
|
365
|
-
|
|
366
|
-
The handler can return:
|
|
367
|
-
|
|
368
|
-
- A `FunctionResult` instance (recommended)
|
|
369
|
-
- A plain object with a `response` key
|
|
370
|
-
- A plain string (wrapped automatically)
|
|
371
|
-
|
|
372
|
-
### Tool Parameters
|
|
373
|
-
|
|
374
|
-
Parameters follow JSON Schema conventions. You can provide them in shorthand (just the properties) or full schema format:
|
|
375
|
-
|
|
376
|
-
```typescript
|
|
377
|
-
// Shorthand -- properties only, SDK wraps in { type: 'object', properties: ... }
|
|
378
|
-
agent.defineTool({
|
|
379
|
-
name: 'lookup',
|
|
380
|
-
description: 'Look up a customer',
|
|
381
|
-
parameters: {
|
|
382
|
-
name: { type: 'string', description: 'Customer name' },
|
|
383
|
-
email: { type: 'string', description: 'Email address' },
|
|
384
|
-
},
|
|
385
|
-
handler: async (args) => new FunctionResult(`Found: ${args.name}`),
|
|
386
|
-
});
|
|
387
|
-
|
|
388
|
-
// Full schema
|
|
389
|
-
agent.defineTool({
|
|
390
|
-
name: 'lookup_full',
|
|
391
|
-
description: 'Look up a customer',
|
|
392
|
-
parameters: {
|
|
393
|
-
type: 'object',
|
|
394
|
-
properties: {
|
|
395
|
-
name: { type: 'string', description: 'Customer name' },
|
|
396
|
-
email: { type: 'string', description: 'Email address' },
|
|
397
|
-
},
|
|
398
|
-
required: ['name'],
|
|
399
|
-
},
|
|
400
|
-
handler: async (args) => new FunctionResult(`Found: ${args.name}`),
|
|
401
|
-
});
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
### Secure Tools
|
|
405
|
-
|
|
406
|
-
Secure tools require a valid HMAC session token for each invocation. The token is bound to the call ID and function name, preventing replay attacks:
|
|
407
|
-
|
|
408
|
-
```typescript
|
|
409
|
-
agent.defineTool({
|
|
410
|
-
name: 'transfer_funds',
|
|
411
|
-
description: 'Transfer money between accounts.',
|
|
412
|
-
secure: true,
|
|
413
|
-
parameters: {
|
|
414
|
-
amount: { type: 'number', description: 'Amount to transfer' },
|
|
415
|
-
to_account: { type: 'string', description: 'Destination account ID' },
|
|
416
|
-
},
|
|
417
|
-
handler: async (args) => {
|
|
418
|
-
await doTransfer(args.amount as number, args.to_account as string);
|
|
419
|
-
return new FunctionResult('Transfer completed successfully.');
|
|
420
|
-
},
|
|
421
|
-
});
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
When `secure: true` is set, the SWML document includes a `__token` query parameter in the tool's webhook URL. On each `/swaig` request, the SDK validates the token's HMAC signature, call ID binding, and expiry before executing the handler.
|
|
425
|
-
|
|
426
|
-
### FunctionResult
|
|
427
|
-
|
|
428
|
-
`FunctionResult` is a fluent builder for tool responses. It carries response text and an ordered list of actions:
|
|
429
|
-
|
|
430
|
-
```typescript
|
|
431
|
-
import { FunctionResult } from '@signalwire/sdk';
|
|
432
|
-
|
|
433
|
-
// Simple text response
|
|
434
|
-
const result = new FunctionResult('The order has been placed.');
|
|
435
|
-
|
|
436
|
-
// Response with actions
|
|
437
|
-
const transfer = new FunctionResult('Transferring you now.')
|
|
438
|
-
.connect('+15551234567')
|
|
439
|
-
.hangup();
|
|
440
|
-
|
|
441
|
-
// Update global data from within a tool
|
|
442
|
-
const verified = new FunctionResult('Account verified.')
|
|
443
|
-
.updateGlobalData({ verified: true, customer_id: '12345' });
|
|
444
|
-
|
|
445
|
-
// Context switch
|
|
446
|
-
const billing = new FunctionResult('Let me transfer you to billing.')
|
|
447
|
-
.switchContext({ systemPrompt: 'You are now a billing specialist.' });
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
Key `FunctionResult` methods:
|
|
451
|
-
|
|
452
|
-
| Method | Description |
|
|
453
|
-
|--------|-------------|
|
|
454
|
-
| `setResponse(text)` | Set the response text. |
|
|
455
|
-
| `connect(destination, final?, from?)` | Transfer the call to a destination. |
|
|
456
|
-
| `hangup()` | Hang up the call. |
|
|
457
|
-
| `hold(timeout?)` | Place the call on hold (0-900 seconds). |
|
|
458
|
-
| `say(text)` | Speak text via TTS. |
|
|
459
|
-
| `stop()` | Stop the AI session. |
|
|
460
|
-
| `updateGlobalData(data)` | Merge data into the shared global store. |
|
|
461
|
-
| `setMetadata(data)` | Set call metadata. |
|
|
462
|
-
| `switchContext(opts)` | Switch the AI context with optional prompt changes. |
|
|
463
|
-
| `toggleFunctions(toggles)` | Enable/disable specific SWAIG functions. |
|
|
464
|
-
| `sendSms(opts)` | Send an SMS or MMS. |
|
|
465
|
-
| `playBackgroundFile(url, wait?)` | Play background audio. |
|
|
466
|
-
| `waitForUser(opts?)` | Wait for user input before continuing. |
|
|
467
|
-
| `addDynamicHints(hints)` | Add speech recognition hints at runtime. |
|
|
468
|
-
| `executeSwml(swml, transfer?)` | Execute arbitrary SWML content. |
|
|
469
|
-
| `pay(opts)` | Initiate a payment collection flow. |
|
|
470
|
-
|
|
471
|
-
Serialization fallback: if both `response` and `action` are empty, `toDict()` returns `{ response: "Action completed." }`.
|
|
472
|
-
|
|
473
|
-
### DataMap (Server-Side Tools)
|
|
474
|
-
|
|
475
|
-
DataMap tools execute entirely on the SignalWire platform without requiring a webhook. They are useful for simple API calls and pattern-matching:
|
|
476
|
-
|
|
477
|
-
```typescript
|
|
478
|
-
import { DataMap, FunctionResult } from '@signalwire/sdk';
|
|
479
|
-
|
|
480
|
-
const weatherTool = new DataMap('get_weather')
|
|
481
|
-
.purpose('Look up weather for a city')
|
|
482
|
-
.parameter('city', 'string', 'City name', { required: true })
|
|
483
|
-
.webhook('GET', 'https://api.weather.com/v1/current?q=${args.city}', {
|
|
484
|
-
headers: { Authorization: 'Bearer ${ENV.WEATHER_API_KEY}' },
|
|
485
|
-
})
|
|
486
|
-
.output(new FunctionResult('The weather is ${temp}F and ${condition}.'))
|
|
487
|
-
.enableEnvExpansion();
|
|
488
|
-
|
|
489
|
-
weatherTool.registerWithAgent(agent);
|
|
490
|
-
```
|
|
491
|
-
|
|
492
|
-
Convenience helpers:
|
|
493
|
-
|
|
494
|
-
```typescript
|
|
495
|
-
import { createSimpleApiTool, createExpressionTool } from '@signalwire/sdk';
|
|
496
|
-
|
|
497
|
-
const tool = createSimpleApiTool({
|
|
498
|
-
name: 'joke',
|
|
499
|
-
url: 'https://api.example.com/joke',
|
|
500
|
-
responseTemplate: 'Here is a joke: ${joke}',
|
|
501
|
-
});
|
|
502
|
-
tool.registerWithAgent(agent);
|
|
503
|
-
```
|
|
504
|
-
|
|
505
|
-
---
|
|
506
|
-
|
|
507
|
-
## Speech and Languages
|
|
508
|
-
|
|
509
|
-
### Hints
|
|
510
|
-
|
|
511
|
-
Speech recognition hints improve transcription accuracy for domain-specific vocabulary:
|
|
512
|
-
|
|
513
|
-
```typescript
|
|
514
|
-
// Single hint
|
|
515
|
-
agent.addHint('SignalWire');
|
|
516
|
-
|
|
517
|
-
// Multiple hints
|
|
518
|
-
agent.addHints(['HIPAA', 'deductible', 'copay', 'pre-authorization']);
|
|
519
|
-
|
|
520
|
-
// Pattern hint (find and replace in transcription)
|
|
521
|
-
agent.addPatternHint({
|
|
522
|
-
pattern: 'signal wire',
|
|
523
|
-
replace: 'SignalWire',
|
|
524
|
-
ignoreCase: true,
|
|
525
|
-
});
|
|
526
|
-
```
|
|
527
|
-
|
|
528
|
-
### Languages
|
|
529
|
-
|
|
530
|
-
Configure supported languages with voice and filler phrases:
|
|
531
|
-
|
|
532
|
-
```typescript
|
|
533
|
-
agent.addLanguage({
|
|
534
|
-
name: 'English',
|
|
535
|
-
code: 'en-US',
|
|
536
|
-
voice: 'en-US-Neural2-F',
|
|
537
|
-
engine: 'google',
|
|
538
|
-
speechModel: 'enhanced',
|
|
539
|
-
fillers: { thinking: ['Let me check on that...', 'One moment please...'] },
|
|
540
|
-
functionFillers: { get_weather: { 'en-US': ['Checking the forecast...'] } },
|
|
541
|
-
});
|
|
542
|
-
|
|
543
|
-
agent.addLanguage({
|
|
544
|
-
name: 'Spanish',
|
|
545
|
-
code: 'es-MX',
|
|
546
|
-
voice: 'es-MX-Neural2-A',
|
|
547
|
-
});
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
Replace all languages at once:
|
|
551
|
-
|
|
552
|
-
```typescript
|
|
553
|
-
agent.setLanguages([
|
|
554
|
-
{ name: 'English', code: 'en-US', voice: 'en-US-Neural2-F' },
|
|
555
|
-
{ name: 'French', code: 'fr-FR', voice: 'fr-FR-Neural2-A' },
|
|
556
|
-
]);
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
### Pronunciation
|
|
560
|
-
|
|
561
|
-
Override how the TTS engine pronounces specific words:
|
|
562
|
-
|
|
563
|
-
```typescript
|
|
564
|
-
agent.addPronunciation({
|
|
565
|
-
replace: 'SQL',
|
|
566
|
-
with: 'sequel',
|
|
567
|
-
ignoreCase: true,
|
|
568
|
-
});
|
|
569
|
-
|
|
570
|
-
agent.addPronunciation({
|
|
571
|
-
replace: 'API',
|
|
572
|
-
with: 'A P I',
|
|
573
|
-
});
|
|
574
|
-
```
|
|
575
|
-
|
|
576
|
-
---
|
|
577
|
-
|
|
578
|
-
## AI Parameters
|
|
579
|
-
|
|
580
|
-
Control the AI model's behavior with parameters like temperature and top_p:
|
|
581
|
-
|
|
582
|
-
```typescript
|
|
583
|
-
// Set a single parameter
|
|
584
|
-
agent.setParam('temperature', 0.7);
|
|
585
|
-
agent.setParam('top_p', 0.9);
|
|
586
|
-
|
|
587
|
-
// Set multiple parameters at once
|
|
588
|
-
agent.setParams({
|
|
589
|
-
temperature: 0.3,
|
|
590
|
-
top_p: 0.85,
|
|
591
|
-
confidence: 0.5,
|
|
592
|
-
barge_confidence: 0.3,
|
|
593
|
-
presence_penalty: 0.2,
|
|
594
|
-
frequency_penalty: 0.5,
|
|
595
|
-
});
|
|
596
|
-
```
|
|
597
|
-
|
|
598
|
-
### Prompt-Specific LLM Parameters
|
|
599
|
-
|
|
600
|
-
Set LLM parameters that apply specifically to the main prompt or post-prompt:
|
|
601
|
-
|
|
602
|
-
```typescript
|
|
603
|
-
// Main prompt LLM params (e.g., model selection, temperature override)
|
|
604
|
-
agent.setPromptLlmParams({
|
|
605
|
-
model: 'gpt-4',
|
|
606
|
-
temperature: 0.2,
|
|
607
|
-
});
|
|
608
|
-
|
|
609
|
-
// Post-prompt LLM params
|
|
610
|
-
agent.setPostPromptLlmParams({
|
|
611
|
-
model: 'gpt-3.5-turbo',
|
|
612
|
-
temperature: 0.1,
|
|
613
|
-
});
|
|
614
|
-
```
|
|
615
|
-
|
|
616
|
-
---
|
|
617
|
-
|
|
618
|
-
## Global Data
|
|
619
|
-
|
|
620
|
-
Global data is a key-value store shared across all tool invocations within a call. Tools can read from it and update it:
|
|
621
|
-
|
|
622
|
-
```typescript
|
|
623
|
-
// Replace the entire global data object
|
|
624
|
-
agent.setGlobalData({
|
|
625
|
-
company: 'Acme Corp',
|
|
626
|
-
support_hours: '9am-5pm EST',
|
|
627
|
-
max_refund: 500,
|
|
628
|
-
});
|
|
629
|
-
|
|
630
|
-
// Merge additional entries into existing global data
|
|
631
|
-
agent.updateGlobalData({
|
|
632
|
-
promo_code: 'SUMMER2025',
|
|
633
|
-
});
|
|
634
|
-
```
|
|
635
|
-
|
|
636
|
-
Within a tool handler, you can update global data dynamically:
|
|
637
|
-
|
|
638
|
-
```typescript
|
|
639
|
-
handler: async (args) => {
|
|
640
|
-
return new FunctionResult('Customer verified.')
|
|
641
|
-
.updateGlobalData({ customer_verified: true, customer_name: args.name });
|
|
642
|
-
}
|
|
643
|
-
```
|
|
644
|
-
|
|
645
|
-
---
|
|
646
|
-
|
|
647
|
-
## Call Flow (5 Phases)
|
|
648
|
-
|
|
649
|
-
The SWML document is assembled from five sequential phases. Each phase adds verbs to the document's `main` section:
|
|
650
|
-
|
|
651
|
-
| Phase | Method | Description |
|
|
652
|
-
|-------|--------|-------------|
|
|
653
|
-
| **1. Pre-Answer** | `addPreAnswerVerb(verb, config)` | Verbs executed before answering the call (e.g., playing a ring tone). |
|
|
654
|
-
| **2. Answer** | `addAnswerVerb(config?)` | The `answer` verb that picks up the call. Automatic when `autoAnswer: true`. |
|
|
655
|
-
| **3. Post-Answer** | `addPostAnswerVerb(verb, config)` | Verbs after answering but before the AI starts (e.g., `record_call`, `play`). |
|
|
656
|
-
| **4. AI** | *(automatic)* | The `ai` verb containing the prompt, tools, hints, languages, and all AI configuration. |
|
|
657
|
-
| **5. Post-AI** | `addPostAiVerb(verb, config)` | Verbs executed after the AI session ends (e.g., `hangup`, `connect`). |
|
|
658
|
-
|
|
659
|
-
### Example
|
|
660
|
-
|
|
661
|
-
```typescript
|
|
662
|
-
const agent = new AgentBase({ name: 'ivr-bot', autoAnswer: true, recordCall: true });
|
|
663
|
-
|
|
664
|
-
// Phase 1: Play hold music before answering
|
|
665
|
-
agent.addPreAnswerVerb('play', {
|
|
666
|
-
url: 'https://cdn.example.com/hold-music.mp3',
|
|
667
|
-
});
|
|
668
|
-
|
|
669
|
-
// Phase 3: Play a greeting after answering, before AI starts
|
|
670
|
-
agent.addPostAnswerVerb('play', {
|
|
671
|
-
url: 'https://cdn.example.com/greeting.wav',
|
|
672
|
-
});
|
|
673
|
-
|
|
674
|
-
// Phase 5: Hang up after the AI session ends
|
|
675
|
-
agent.addPostAiVerb('hangup', {});
|
|
676
|
-
```
|
|
677
|
-
|
|
678
|
-
Note: When `recordCall: true`, a `record_call` verb is automatically inserted at the start of Phase 3.
|
|
679
|
-
|
|
680
|
-
### Clearing Verbs
|
|
681
|
-
|
|
682
|
-
```typescript
|
|
683
|
-
agent.clearPreAnswerVerbs();
|
|
684
|
-
agent.clearPostAnswerVerbs();
|
|
685
|
-
agent.clearPostAiVerbs();
|
|
686
|
-
```
|
|
687
|
-
|
|
688
|
-
---
|
|
689
|
-
|
|
690
|
-
## Dynamic Configuration
|
|
691
|
-
|
|
692
|
-
Dynamic configuration lets you modify the agent's settings per-request. On each SWML request, the SDK creates an **ephemeral copy** of the agent, passes it to your callback, and renders SWML from the modified copy. The original agent is never mutated.
|
|
693
|
-
|
|
694
|
-
```typescript
|
|
695
|
-
agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, ephemeralAgent) => {
|
|
696
|
-
const agent = ephemeralAgent as AgentBase;
|
|
697
|
-
|
|
698
|
-
// Customize based on query parameters
|
|
699
|
-
const lang = queryParams['lang'];
|
|
700
|
-
if (lang === 'es') {
|
|
701
|
-
agent.setPromptText('Eres un asistente de servicio al cliente amable.');
|
|
702
|
-
agent.addLanguage({ name: 'Spanish', code: 'es-MX', voice: 'es-MX-Neural2-A' });
|
|
703
|
-
}
|
|
704
|
-
|
|
705
|
-
// Customize based on request headers
|
|
706
|
-
const tier = headers['x-customer-tier'];
|
|
707
|
-
if (tier === 'premium') {
|
|
708
|
-
agent.updateGlobalData({ premium: true, max_refund: 1000 });
|
|
709
|
-
}
|
|
710
|
-
|
|
711
|
-
// Customize based on body data
|
|
712
|
-
const callerId = bodyParams['caller_id_number'] as string;
|
|
713
|
-
if (callerId) {
|
|
714
|
-
const customer = await lookupCustomer(callerId);
|
|
715
|
-
agent.updateGlobalData({ customer_name: customer.name });
|
|
716
|
-
}
|
|
717
|
-
});
|
|
718
|
-
```
|
|
719
|
-
|
|
720
|
-
The callback signature:
|
|
721
|
-
|
|
722
|
-
```typescript
|
|
723
|
-
type DynamicConfigCallback = (
|
|
724
|
-
queryParams: Record<string, string>, // URL query parameters
|
|
725
|
-
bodyParams: Record<string, unknown>, // Parsed request body
|
|
726
|
-
headers: Record<string, string>, // HTTP headers
|
|
727
|
-
agent: unknown, // Ephemeral AgentBase copy (cast as needed)
|
|
728
|
-
) => void | Promise<void>;
|
|
729
|
-
```
|
|
730
|
-
|
|
731
|
-
### SWAIG Query Parameters
|
|
732
|
-
|
|
733
|
-
Append custom query parameters to all SWAIG webhook URLs:
|
|
734
|
-
|
|
735
|
-
```typescript
|
|
736
|
-
agent.addSwaigQueryParams({ tenant: 'acme', region: 'us-east' });
|
|
737
|
-
```
|
|
738
|
-
|
|
739
|
-
---
|
|
740
|
-
|
|
741
|
-
## Post-Prompt and Summaries
|
|
742
|
-
|
|
743
|
-
The **post-prompt** is a separate prompt evaluated after the call ends. It is typically used to generate a structured summary of the conversation.
|
|
744
|
-
|
|
745
|
-
### Setting the Post-Prompt
|
|
746
|
-
|
|
747
|
-
```typescript
|
|
748
|
-
agent.setPostPrompt(`
|
|
749
|
-
Summarize this conversation as JSON with the following fields:
|
|
750
|
-
- "resolution": whether the issue was resolved (true/false)
|
|
751
|
-
- "category": the type of issue (billing, technical, general)
|
|
752
|
-
- "summary": a one-sentence summary of the call
|
|
753
|
-
`);
|
|
754
|
-
```
|
|
755
|
-
|
|
756
|
-
### Handling Summaries
|
|
757
|
-
|
|
758
|
-
Override the `onSummary` lifecycle hook to process the summary when it arrives:
|
|
759
|
-
|
|
760
|
-
```typescript
|
|
761
|
-
class MyAgent extends AgentBase {
|
|
762
|
-
constructor() {
|
|
763
|
-
super({ name: 'my-agent' });
|
|
764
|
-
}
|
|
765
|
-
|
|
766
|
-
async onSummary(
|
|
767
|
-
summary: Record<string, unknown> | null,
|
|
768
|
-
rawData: Record<string, unknown>,
|
|
769
|
-
): Promise<void> {
|
|
770
|
-
if (summary) {
|
|
771
|
-
console.log('Call summary:', summary);
|
|
772
|
-
await saveToDatabase(summary);
|
|
773
|
-
}
|
|
774
|
-
}
|
|
775
|
-
}
|
|
776
|
-
```
|
|
777
|
-
|
|
778
|
-
### Post-Prompt LLM Parameters
|
|
779
|
-
|
|
780
|
-
You can use a different (often cheaper/faster) model for the post-prompt evaluation:
|
|
781
|
-
|
|
782
|
-
```typescript
|
|
783
|
-
agent.setPostPromptLlmParams({
|
|
784
|
-
model: 'gpt-3.5-turbo',
|
|
785
|
-
temperature: 0.0,
|
|
786
|
-
});
|
|
787
|
-
```
|
|
788
|
-
|
|
789
|
-
---
|
|
790
|
-
|
|
791
|
-
## Skills System
|
|
792
|
-
|
|
793
|
-
Skills are modular bundles of tools, prompt sections, hints, and global data that can be added to an agent with a single call:
|
|
794
|
-
|
|
795
|
-
```typescript
|
|
796
|
-
import { AgentBase, DateTimeSkill, MathSkill, WebSearchSkill } from '@signalwire/sdk';
|
|
797
|
-
|
|
798
|
-
const agent = new AgentBase({ name: 'assistant' });
|
|
799
|
-
|
|
800
|
-
// Add skills with one-liners
|
|
801
|
-
await agent.addSkill(new DateTimeSkill());
|
|
802
|
-
await agent.addSkill(new MathSkill());
|
|
803
|
-
|
|
804
|
-
// Add skills with custom parameters
|
|
805
|
-
await agent.addSkill(new WebSearchSkill({
|
|
806
|
-
max_results: 3,
|
|
807
|
-
safe_search: 'active',
|
|
808
|
-
}));
|
|
809
|
-
```
|
|
810
|
-
|
|
811
|
-
When `addSkill()` is called, the `SkillManager` validates environment variables, calls `setup()`, registers tools, merges hints and prompt sections, and merges global data.
|
|
812
|
-
|
|
813
|
-
See [skills_system.md](skills_system.md) for the full skills architecture reference.
|
|
814
|
-
|
|
815
|
-
---
|
|
816
|
-
|
|
817
|
-
## Multi-Agent Server
|
|
818
|
-
|
|
819
|
-
`AgentServer` hosts multiple `AgentBase` instances on a single HTTP server, each mounted at its own route prefix:
|
|
820
|
-
|
|
821
|
-
```typescript
|
|
822
|
-
import { AgentBase, AgentServer } from '@signalwire/sdk';
|
|
823
|
-
|
|
824
|
-
const salesAgent = new AgentBase({ name: 'sales', route: '/sales' });
|
|
825
|
-
salesAgent.setPromptText('You are a sales representative.');
|
|
826
|
-
|
|
827
|
-
const supportAgent = new AgentBase({ name: 'support', route: '/support' });
|
|
828
|
-
supportAgent.setPromptText('You are a technical support agent.');
|
|
829
|
-
|
|
830
|
-
const server = new AgentServer({ host: '0.0.0.0', port: 4000 });
|
|
831
|
-
server.register(salesAgent);
|
|
832
|
-
server.register(supportAgent);
|
|
833
|
-
|
|
834
|
-
await server.run();
|
|
835
|
-
```
|
|
836
|
-
|
|
837
|
-
### AgentServer Features
|
|
838
|
-
|
|
839
|
-
- **Agent listing**: If no agent is mounted at `/`, a GET to `/` returns a JSON listing of all registered agents and their routes.
|
|
840
|
-
- **Health endpoints**: `/health` and `/ready` return `{ "status": "ok" }` and `{ "status": "ready" }` respectively.
|
|
841
|
-
- **Security headers**: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, and `Referrer-Policy` are set on all responses.
|
|
842
|
-
- **CORS**: Enabled globally with `origin: *`.
|
|
843
|
-
|
|
844
|
-
### API
|
|
845
|
-
|
|
846
|
-
| Method | Description |
|
|
847
|
-
|--------|-------------|
|
|
848
|
-
| `register(agent, route?)` | Mount an agent at a route prefix. Throws if the route is already in use. |
|
|
849
|
-
| `unregister(route)` | Remove an agent registration. |
|
|
850
|
-
| `getAgents()` | Returns a `Map<string, AgentBase>` of all registered agents. |
|
|
851
|
-
| `getAgent(route)` | Look up an agent by route. |
|
|
852
|
-
| `getApp()` | Returns the underlying Hono application. |
|
|
853
|
-
| `run(host?, port?)` | Start the HTTP server. |
|
|
854
|
-
|
|
855
|
-
---
|
|
856
|
-
|
|
857
|
-
## Subclassing AgentBase
|
|
858
|
-
|
|
859
|
-
For reusable, self-contained agents, extend `AgentBase`:
|
|
860
|
-
|
|
861
|
-
```typescript
|
|
862
|
-
import { AgentBase, FunctionResult } from '@signalwire/sdk';
|
|
863
|
-
|
|
864
|
-
class RestaurantBot extends AgentBase {
|
|
865
|
-
// Declarative prompt sections
|
|
866
|
-
static PROMPT_SECTIONS = [
|
|
867
|
-
{
|
|
868
|
-
title: 'Role',
|
|
869
|
-
body: 'You are a helpful restaurant reservation assistant for Bella Italia.',
|
|
870
|
-
},
|
|
871
|
-
{
|
|
872
|
-
title: 'Guidelines',
|
|
873
|
-
bullets: [
|
|
874
|
-
'Be warm and inviting',
|
|
875
|
-
'Always confirm the reservation details before finalizing',
|
|
876
|
-
'Mention daily specials when relevant',
|
|
877
|
-
],
|
|
878
|
-
},
|
|
879
|
-
];
|
|
880
|
-
|
|
881
|
-
constructor() {
|
|
882
|
-
super({ name: 'restaurant-bot', route: '/restaurant' });
|
|
883
|
-
|
|
884
|
-
this.addHints(['Bella Italia', 'risotto', 'tiramisu']);
|
|
885
|
-
this.setParams({ temperature: 0.6 });
|
|
886
|
-
|
|
887
|
-
// Must be called explicitly at the end of the constructor
|
|
888
|
-
this.defineTools();
|
|
889
|
-
}
|
|
890
|
-
|
|
891
|
-
// Override to register tools
|
|
892
|
-
protected defineTools(): void {
|
|
893
|
-
this.defineTool({
|
|
894
|
-
name: 'make_reservation',
|
|
895
|
-
description: 'Create a restaurant reservation.',
|
|
896
|
-
parameters: {
|
|
897
|
-
date: { type: 'string', description: 'Reservation date (YYYY-MM-DD)' },
|
|
898
|
-
time: { type: 'string', description: 'Reservation time (HH:MM)' },
|
|
899
|
-
party_size: { type: 'number', description: 'Number of guests' },
|
|
900
|
-
name: { type: 'string', description: 'Name for the reservation' },
|
|
901
|
-
},
|
|
902
|
-
required: ['date', 'time', 'party_size', 'name'],
|
|
903
|
-
handler: async (args) => {
|
|
904
|
-
const id = await createReservation(args);
|
|
905
|
-
return new FunctionResult(
|
|
906
|
-
`Reservation confirmed for ${args.party_size} on ${args.date} at ${args.time}. ` +
|
|
907
|
-
`Confirmation number: ${id}.`,
|
|
908
|
-
);
|
|
909
|
-
},
|
|
910
|
-
});
|
|
911
|
-
}
|
|
912
|
-
|
|
913
|
-
// Override the post-prompt summary hook
|
|
914
|
-
async onSummary(summary: Record<string, unknown> | null): Promise<void> {
|
|
915
|
-
if (summary) {
|
|
916
|
-
await logReservationSummary(summary);
|
|
917
|
-
}
|
|
918
|
-
}
|
|
919
|
-
|
|
920
|
-
// Override pre-execution hook for all tools
|
|
921
|
-
async onFunctionCall(name: string, args: Record<string, unknown>): Promise<void> {
|
|
922
|
-
console.log(`Tool invoked: ${name}`, args);
|
|
923
|
-
}
|
|
924
|
-
|
|
925
|
-
// Override basic auth validation
|
|
926
|
-
validateBasicAuth(username: string, password: string): boolean {
|
|
927
|
-
return username === 'admin' && password === process.env['ADMIN_PASSWORD']!;
|
|
928
|
-
}
|
|
929
|
-
}
|
|
930
|
-
```
|
|
931
|
-
|
|
932
|
-
### Extension Points
|
|
933
|
-
|
|
934
|
-
| Method / Property | Purpose |
|
|
935
|
-
|-------------------|---------|
|
|
936
|
-
| `static PROMPT_SECTIONS` | Declarative prompt sections applied in the constructor. |
|
|
937
|
-
| `defineTools()` | Override to register tools. Call explicitly at the end of your constructor. |
|
|
938
|
-
| `onSummary(summary, rawData)` | Called when a post-prompt summary is received. |
|
|
939
|
-
| `onFunctionCall(name, args, rawData)` | Called before each tool handler executes. |
|
|
940
|
-
| `onSwmlRequest(rawData)` | Called on every SWML request before rendering. |
|
|
941
|
-
| `onDebugEvent(event)` | Called when a debug event webhook is received. |
|
|
942
|
-
| `validateBasicAuth(username, password)` | Override to add custom auth validation logic. |
|
|
943
|
-
|
|
944
|
-
---
|
|
945
|
-
|
|
946
|
-
## HTTP Endpoints
|
|
947
|
-
|
|
948
|
-
Each agent exposes the following HTTP endpoints (all relative to the agent's `route`):
|
|
949
|
-
|
|
950
|
-
| Method | Path | Auth | Description |
|
|
951
|
-
|--------|------|------|-------------|
|
|
952
|
-
| GET / POST | `/` | Basic Auth | Returns the rendered SWML document. Triggers proxy detection and dynamic config callback. |
|
|
953
|
-
| GET / POST | `/swaig` | Basic Auth | SWAIG function dispatcher. Validates tokens for secure tools, calls `onFunctionCall`, executes the handler. |
|
|
954
|
-
| GET / POST | `/post_prompt` | Basic Auth | Receives post-prompt summary data. Extracts the summary and calls `onSummary`. |
|
|
955
|
-
| POST | `/debug_events` | Basic Auth | Receives debug event webhooks (when `enableDebugEvents()` is active). |
|
|
956
|
-
| GET | `/health` | None | Returns `{ "status": "ok" }`. |
|
|
957
|
-
| GET | `/ready` | None | Returns `{ "status": "ready" }`. |
|
|
958
|
-
|
|
959
|
-
---
|
|
960
|
-
|
|
961
|
-
## State Management
|
|
962
|
-
|
|
963
|
-
### Global Data
|
|
964
|
-
|
|
965
|
-
Global data is shared across all tool invocations within a call. Set initial data on the agent and update it dynamically from tool handlers:
|
|
966
|
-
|
|
967
|
-
```typescript
|
|
968
|
-
// Initial data
|
|
969
|
-
agent.setGlobalData({ company: 'Acme', tier: 'standard' });
|
|
970
|
-
|
|
971
|
-
// In a tool handler -- update data during the call
|
|
972
|
-
handler: async (args) => {
|
|
973
|
-
return new FunctionResult('Verified.')
|
|
974
|
-
.updateGlobalData({ verified: true });
|
|
975
|
-
}
|
|
976
|
-
```
|
|
977
|
-
|
|
978
|
-
### Session Metadata
|
|
979
|
-
|
|
980
|
-
The `SessionManager` provides per-session in-memory metadata storage:
|
|
981
|
-
|
|
982
|
-
```typescript
|
|
983
|
-
import { SessionManager } from '@signalwire/sdk';
|
|
984
|
-
|
|
985
|
-
const sm = new SessionManager();
|
|
986
|
-
sm.setSessionMetadata('session-1', { userId: 'u-42', plan: 'pro' });
|
|
987
|
-
const meta = sm.getSessionMetadata('session-1');
|
|
988
|
-
sm.deleteSessionMetadata('session-1');
|
|
989
|
-
```
|
|
990
|
-
|
|
991
|
-
---
|
|
992
|
-
|
|
993
|
-
## SIP Routing
|
|
994
|
-
|
|
995
|
-
Enable SIP-based routing to direct calls to specific agents based on the SIP username:
|
|
996
|
-
|
|
997
|
-
```typescript
|
|
998
|
-
const server = new AgentServer({ host: '0.0.0.0', port: 4000 });
|
|
999
|
-
|
|
1000
|
-
// Register agents
|
|
1001
|
-
server.register(salesAgent);
|
|
1002
|
-
server.register(supportAgent);
|
|
1003
|
-
|
|
1004
|
-
// Map SIP usernames to agent routes
|
|
1005
|
-
server.registerSipUsername('sales-line', '/sales');
|
|
1006
|
-
server.registerSipUsername('support-line', '/support');
|
|
1007
|
-
```
|
|
1008
|
-
|
|
1009
|
-
---
|
|
1010
|
-
|
|
1011
|
-
## Environment Variables
|
|
1012
|
-
|
|
1013
|
-
| Variable | Default | Description |
|
|
1014
|
-
|----------|---------|-------------|
|
|
1015
|
-
| `PORT` | `3000` | HTTP server port (used when `port` is not specified in `AgentOptions`). |
|
|
1016
|
-
| `SWML_BASIC_AUTH_USER` | *(none)* | Basic auth username. Used when `basicAuth` is not provided in options. |
|
|
1017
|
-
| `SWML_BASIC_AUTH_PASSWORD` | *(none)* | Basic auth password. Used when `basicAuth` is not provided in options. |
|
|
1018
|
-
| `SWML_PROXY_URL_BASE` | *(none)* | External-facing base URL for webhook URLs (e.g., `https://agents.example.com`). |
|
|
1019
|
-
| `SWML_PROXY_DEBUG` | `"false"` | Set to `"true"` to enable verbose logging of proxy/header detection. |
|
|
1020
|
-
| `SWML_CORS_ORIGINS` | `"*"` | Comma-separated list of allowed CORS origins. |
|
|
1021
|
-
| `SWML_ALLOWED_HOSTS` | *(none)* | Comma-separated list of allowed `Host` header values. |
|
|
1022
|
-
| `SWML_MAX_REQUEST_SIZE` | `1048576` | Maximum request body size in bytes (default 1 MB). |
|
|
1023
|
-
| `SWML_RATE_LIMIT` | *(none)* | Maximum requests per minute per IP address. |
|
|
1024
|
-
| `SWML_REQUEST_TIMEOUT` | `30000` | Request timeout in milliseconds. |
|
|
1025
|
-
| `SIGNALWIRE_LOG_LEVEL` | `"info"` | Logging level: `"debug"`, `"info"`, `"warn"`, `"error"`. |
|
|
1026
|
-
| `SIGNALWIRE_LOG_MODE` | `"pretty"` | Log output format: `"pretty"` for human-readable, `"json"` for structured JSON. |
|