@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/contexts_guide.md
DELETED
|
@@ -1,511 +0,0 @@
|
|
|
1
|
-
# Contexts & Steps Guide
|
|
2
|
-
|
|
3
|
-
Complete guide to building multi-step conversation workflows using the Contexts & Steps system in the SignalWire AI Agents TypeScript SDK.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Table of Contents
|
|
8
|
-
|
|
9
|
-
1. [Overview](#overview)
|
|
10
|
-
2. [Creating Contexts](#creating-contexts)
|
|
11
|
-
3. [Steps](#steps)
|
|
12
|
-
4. [Step Navigation](#step-navigation)
|
|
13
|
-
5. [Function Control](#function-control)
|
|
14
|
-
6. [End States](#end-states)
|
|
15
|
-
7. [GatherInfo](#gatherinfo)
|
|
16
|
-
8. [Context Settings](#context-settings)
|
|
17
|
-
9. [Isolation and Reset](#isolation-and-reset)
|
|
18
|
-
10. [Fillers](#fillers)
|
|
19
|
-
11. [Validation](#validation)
|
|
20
|
-
12. [Real-World Example](#real-world-example)
|
|
21
|
-
13. [Best Practices](#best-practices)
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
|
-
## Overview
|
|
26
|
-
|
|
27
|
-
The Contexts & Steps system provides a **state machine** for structuring multi-step AI conversations. Instead of a single flat prompt, you define a graph of **contexts** that each contain ordered **steps**. The AI navigates through these steps based on completion criteria, enabling complex branching workflows such as customer intake, troubleshooting trees, or multi-department routing.
|
|
28
|
-
|
|
29
|
-
**Key concepts:**
|
|
30
|
-
|
|
31
|
-
- **Context** -- A named group of ordered steps with its own prompt, system prompt, navigation rules, and isolation settings. Think of it as a "page" or "scene" in the conversation.
|
|
32
|
-
- **Step** -- A single stage within a context. Each step has prompt text (raw text or POM sections), completion criteria, function restrictions, and rules about which steps or contexts the AI can move to next.
|
|
33
|
-
- **ContextBuilder** -- The top-level builder that holds all contexts, validates cross-references, and serializes everything to SWML output.
|
|
34
|
-
|
|
35
|
-
### When to Use Contexts vs Traditional Prompts
|
|
36
|
-
|
|
37
|
-
**Use Contexts and Steps when:**
|
|
38
|
-
- Building multi-step workflows (onboarding, support tickets, applications)
|
|
39
|
-
- Need explicit navigation control between conversation states
|
|
40
|
-
- Want to restrict function access based on conversation stage
|
|
41
|
-
- Building complex customer service or troubleshooting flows
|
|
42
|
-
- Creating guided experiences with clear progression
|
|
43
|
-
|
|
44
|
-
**Use Traditional Prompts when:**
|
|
45
|
-
- Building simple, freeform conversational agents
|
|
46
|
-
- Want maximum flexibility in conversation flow
|
|
47
|
-
- Creating general-purpose assistants
|
|
48
|
-
- Prototyping or building simple proof-of-concepts
|
|
49
|
-
|
|
50
|
-
### Classes
|
|
51
|
-
|
|
52
|
-
| Class | Role |
|
|
53
|
-
|---|---|
|
|
54
|
-
| `ContextBuilder` | Top-level container; holds and validates all contexts |
|
|
55
|
-
| `Context` | A named context with steps, prompts, fillers, and navigation rules |
|
|
56
|
-
| `Step` | A single step within a context, with text, criteria, and function control |
|
|
57
|
-
| `GatherInfo` | Structured data collection attached to a step |
|
|
58
|
-
| `GatherQuestion` | A single question within a GatherInfo operation |
|
|
59
|
-
|
|
60
|
-
All classes are exported from `@signalwire/sdk`.
|
|
61
|
-
|
|
62
|
-
---
|
|
63
|
-
|
|
64
|
-
## Creating Contexts
|
|
65
|
-
|
|
66
|
-
### Using `agent.defineContexts()`
|
|
67
|
-
|
|
68
|
-
The primary entry point is the `defineContexts()` method on `AgentBase`. It returns a `ContextBuilder` that you use to add contexts.
|
|
69
|
-
|
|
70
|
-
```typescript
|
|
71
|
-
import { AgentBase } from '@signalwire/sdk';
|
|
72
|
-
|
|
73
|
-
const agent = new AgentBase({ name: 'my-agent' });
|
|
74
|
-
|
|
75
|
-
// Create and get the ContextBuilder
|
|
76
|
-
const cb = agent.defineContexts();
|
|
77
|
-
|
|
78
|
-
// Add contexts to the builder
|
|
79
|
-
const greeting = cb.addContext('greeting');
|
|
80
|
-
const support = cb.addContext('support');
|
|
81
|
-
const farewell = cb.addContext('farewell');
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
You can also pass an existing `ContextBuilder` instance:
|
|
85
|
-
|
|
86
|
-
```typescript
|
|
87
|
-
import { ContextBuilder } from '@signalwire/sdk';
|
|
88
|
-
|
|
89
|
-
const cb = new ContextBuilder();
|
|
90
|
-
cb.addContext('default');
|
|
91
|
-
// ... configure ...
|
|
92
|
-
|
|
93
|
-
agent.defineContexts(cb);
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
### Using `ContextBuilder.addContext()`
|
|
97
|
-
|
|
98
|
-
```typescript
|
|
99
|
-
const cb = new ContextBuilder();
|
|
100
|
-
|
|
101
|
-
// Returns the new Context instance for chaining
|
|
102
|
-
const ctx = cb.addContext('intake');
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
Context names must be unique within a builder. Adding a duplicate name throws an error.
|
|
106
|
-
|
|
107
|
-
### Retrieving a Context
|
|
108
|
-
|
|
109
|
-
```typescript
|
|
110
|
-
const ctx = cb.getContext('intake');
|
|
111
|
-
if (ctx) {
|
|
112
|
-
// configure further
|
|
113
|
-
}
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
### Single-Context Rule
|
|
117
|
-
|
|
118
|
-
When only one context is defined, it must be named `"default"`. The validation method enforces this:
|
|
119
|
-
|
|
120
|
-
```typescript
|
|
121
|
-
const cb = new ContextBuilder();
|
|
122
|
-
cb.addContext('default'); // OK -- single context named "default"
|
|
123
|
-
|
|
124
|
-
const cb2 = new ContextBuilder();
|
|
125
|
-
cb2.addContext('intake'); // Will fail validation (single context must be "default")
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
## Steps
|
|
131
|
-
|
|
132
|
-
Each context contains ordered steps. Steps are added via `context.addStep()`:
|
|
133
|
-
|
|
134
|
-
```typescript
|
|
135
|
-
const ctx = cb.addContext('intake');
|
|
136
|
-
|
|
137
|
-
const welcome = ctx.addStep('welcome');
|
|
138
|
-
welcome.setText('Welcome! I will help you get set up today.');
|
|
139
|
-
|
|
140
|
-
const info = ctx.addStep('collect_info');
|
|
141
|
-
info.setText('I need to collect some information from you.');
|
|
142
|
-
info.setCriteria('The user has provided their name, email, and phone number.');
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
### Step Methods
|
|
146
|
-
|
|
147
|
-
| Method | Description |
|
|
148
|
-
|--------|-------------|
|
|
149
|
-
| `setText(text)` | Set the step's prompt text (raw string). |
|
|
150
|
-
| `addSection(title, opts?)` | Add a POM section to the step. |
|
|
151
|
-
| `setCriteria(criteria)` | Set the completion criteria string. |
|
|
152
|
-
| `setFunctions(fns)` | Restrict which SWAIG functions are available. |
|
|
153
|
-
| `setValidSteps(steps)` | Define which steps the AI can navigate to next. |
|
|
154
|
-
| `setValidContexts(contexts)` | Define which contexts the AI can switch to. |
|
|
155
|
-
| `setEnd(end)` | Mark this step as an end state. |
|
|
156
|
-
| `setGatherInfo(info)` | Attach structured data collection. |
|
|
157
|
-
| `setResetOnEntry(reset)` | Reset step state when re-entered. |
|
|
158
|
-
| `setFillers(fillers)` | Set step-level filler phrases. |
|
|
159
|
-
|
|
160
|
-
### Step Prompt Text
|
|
161
|
-
|
|
162
|
-
Steps support two modes for prompt content:
|
|
163
|
-
|
|
164
|
-
```typescript
|
|
165
|
-
// Raw text mode
|
|
166
|
-
const step = ctx.addStep('greeting');
|
|
167
|
-
step.setText('Hello! Welcome to our service.');
|
|
168
|
-
|
|
169
|
-
// POM section mode
|
|
170
|
-
const step2 = ctx.addStep('troubleshoot');
|
|
171
|
-
step2.addSection('Instructions', {
|
|
172
|
-
body: 'Follow these troubleshooting steps:',
|
|
173
|
-
bullets: [
|
|
174
|
-
'Ask the user to restart the device',
|
|
175
|
-
'Check if the issue persists',
|
|
176
|
-
'If yes, escalate to a technician',
|
|
177
|
-
],
|
|
178
|
-
});
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
---
|
|
182
|
-
|
|
183
|
-
## Step Navigation
|
|
184
|
-
|
|
185
|
-
Control how the AI moves between steps within and across contexts.
|
|
186
|
-
|
|
187
|
-
### Valid Steps (Within a Context)
|
|
188
|
-
|
|
189
|
-
```typescript
|
|
190
|
-
const welcome = ctx.addStep('welcome');
|
|
191
|
-
welcome.setValidSteps(['verify_identity', 'skip_to_support']);
|
|
192
|
-
|
|
193
|
-
const verify = ctx.addStep('verify_identity');
|
|
194
|
-
verify.setCriteria('User has provided their account number.');
|
|
195
|
-
verify.setValidSteps(['account_details']);
|
|
196
|
-
|
|
197
|
-
const skip = ctx.addStep('skip_to_support');
|
|
198
|
-
skip.setValidSteps(['account_details']);
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
### Valid Contexts (Cross-Context Navigation)
|
|
202
|
-
|
|
203
|
-
```typescript
|
|
204
|
-
const welcome = ctx.addStep('welcome');
|
|
205
|
-
welcome.setValidContexts(['support', 'billing']);
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
When the AI determines the step criteria are met (or the user requests a context change), it can navigate to one of the valid contexts.
|
|
209
|
-
|
|
210
|
-
### Navigation with FunctionResult
|
|
211
|
-
|
|
212
|
-
Tool handlers can trigger navigation programmatically:
|
|
213
|
-
|
|
214
|
-
```typescript
|
|
215
|
-
import { FunctionResult } from '@signalwire/sdk';
|
|
216
|
-
|
|
217
|
-
// Navigate to a step
|
|
218
|
-
const result = new FunctionResult('Moving to verification.')
|
|
219
|
-
.swmlChangeStep('verify_identity');
|
|
220
|
-
|
|
221
|
-
// Navigate to a context
|
|
222
|
-
const result2 = new FunctionResult('Transferring to billing.')
|
|
223
|
-
.swmlChangeContext('billing', 'initial');
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
---
|
|
227
|
-
|
|
228
|
-
## Function Control
|
|
229
|
-
|
|
230
|
-
Restrict which SWAIG functions are available at each step:
|
|
231
|
-
|
|
232
|
-
```typescript
|
|
233
|
-
// Only allow these functions during the payment step
|
|
234
|
-
const paymentStep = ctx.addStep('process_payment');
|
|
235
|
-
paymentStep.setFunctions(['validate_card', 'process_payment', 'check_balance']);
|
|
236
|
-
|
|
237
|
-
// No function restrictions (all agent functions available)
|
|
238
|
-
const generalStep = ctx.addStep('general_help');
|
|
239
|
-
// Don't call setFunctions() -- all functions remain available
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
This is useful for security (preventing payment functions during greeting) and for guiding the AI's behavior (limiting distractions during focused steps).
|
|
243
|
-
|
|
244
|
-
---
|
|
245
|
-
|
|
246
|
-
## End States
|
|
247
|
-
|
|
248
|
-
Mark a step as the terminal state of a workflow:
|
|
249
|
-
|
|
250
|
-
```typescript
|
|
251
|
-
const farewell = ctx.addStep('goodbye');
|
|
252
|
-
farewell.setText('Thank you for calling. Goodbye!');
|
|
253
|
-
farewell.setEnd(true);
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
When the AI reaches an end step and its criteria are met (or it has no criteria), the conversation flow for that context is considered complete.
|
|
257
|
-
|
|
258
|
-
---
|
|
259
|
-
|
|
260
|
-
## GatherInfo
|
|
261
|
-
|
|
262
|
-
`GatherInfo` provides structured data collection at a step. It defines a set of questions the AI asks, with optional validation rules.
|
|
263
|
-
|
|
264
|
-
```typescript
|
|
265
|
-
import { GatherInfo, GatherQuestion } from '@signalwire/sdk';
|
|
266
|
-
|
|
267
|
-
const gather = new GatherInfo()
|
|
268
|
-
.addQuestion(
|
|
269
|
-
new GatherQuestion('full_name')
|
|
270
|
-
.setQuestion('What is your full name?')
|
|
271
|
-
.setDescription('Customer legal name'),
|
|
272
|
-
)
|
|
273
|
-
.addQuestion(
|
|
274
|
-
new GatherQuestion('email')
|
|
275
|
-
.setQuestion('What is your email address?')
|
|
276
|
-
.setDescription('Primary contact email')
|
|
277
|
-
.setValidation('^[^@]+@[^@]+\\.[^@]+$'),
|
|
278
|
-
)
|
|
279
|
-
.addQuestion(
|
|
280
|
-
new GatherQuestion('phone')
|
|
281
|
-
.setQuestion('What is your phone number?')
|
|
282
|
-
.setDescription('Contact phone number'),
|
|
283
|
-
);
|
|
284
|
-
|
|
285
|
-
const infoStep = ctx.addStep('collect_info');
|
|
286
|
-
infoStep.setText('I need to collect some information from you.');
|
|
287
|
-
infoStep.setGatherInfo(gather);
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
### GatherQuestion Methods
|
|
291
|
-
|
|
292
|
-
| Method | Description |
|
|
293
|
-
|--------|-------------|
|
|
294
|
-
| `setQuestion(text)` | The question to ask the user. |
|
|
295
|
-
| `setDescription(desc)` | Description of the expected answer (for the AI). |
|
|
296
|
-
| `setValidation(regex)` | Regex pattern for answer validation. |
|
|
297
|
-
|
|
298
|
-
When a step has a `GatherInfo`, the AI systematically asks each question in order, validates answers against the regex patterns (if provided), and collects all responses before marking the step as complete.
|
|
299
|
-
|
|
300
|
-
---
|
|
301
|
-
|
|
302
|
-
## Context Settings
|
|
303
|
-
|
|
304
|
-
### Context-Level Prompts
|
|
305
|
-
|
|
306
|
-
Each context can have its own prompt text and system prompt:
|
|
307
|
-
|
|
308
|
-
```typescript
|
|
309
|
-
const support = cb.addContext('support');
|
|
310
|
-
support.setPrompt('You are now helping the user with a technical issue.');
|
|
311
|
-
support.setSystemPrompt('You are a level-2 technical support specialist.');
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
### Context Entry Behavior
|
|
315
|
-
|
|
316
|
-
When the AI switches to a new context, the context-level prompt supplements the agent's base prompt. The system prompt (if set) can override aspects of the agent's personality or role for that specific context.
|
|
317
|
-
|
|
318
|
-
---
|
|
319
|
-
|
|
320
|
-
## Isolation and Reset
|
|
321
|
-
|
|
322
|
-
### Reset on Entry
|
|
323
|
-
|
|
324
|
-
Steps can be configured to reset their state when the AI returns to them:
|
|
325
|
-
|
|
326
|
-
```typescript
|
|
327
|
-
const verifyStep = ctx.addStep('verify');
|
|
328
|
-
verifyStep.setResetOnEntry(true);
|
|
329
|
-
// If the user navigates back to this step, all gathered data and progress are cleared
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
This is useful for steps that should always start fresh, such as identity verification or payment collection.
|
|
333
|
-
|
|
334
|
-
---
|
|
335
|
-
|
|
336
|
-
## Fillers
|
|
337
|
-
|
|
338
|
-
Set filler phrases that the AI speaks while processing or transitioning.
|
|
339
|
-
|
|
340
|
-
### Context-Level Fillers
|
|
341
|
-
|
|
342
|
-
```typescript
|
|
343
|
-
const support = cb.addContext('support');
|
|
344
|
-
support.setFillers({
|
|
345
|
-
'en-US': ['Let me look into that...', 'One moment please...'],
|
|
346
|
-
'es-MX': ['Un momento por favor...', 'Dejame revisar...'],
|
|
347
|
-
});
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
### Step-Level Fillers
|
|
351
|
-
|
|
352
|
-
```typescript
|
|
353
|
-
const searchStep = ctx.addStep('search');
|
|
354
|
-
searchStep.setFillers({
|
|
355
|
-
'en-US': ['Searching our database...', 'This may take a moment...'],
|
|
356
|
-
});
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
Step-level fillers override context-level fillers for that specific step.
|
|
360
|
-
|
|
361
|
-
---
|
|
362
|
-
|
|
363
|
-
## Validation
|
|
364
|
-
|
|
365
|
-
Call `validate()` on the `ContextBuilder` to check for configuration errors:
|
|
366
|
-
|
|
367
|
-
```typescript
|
|
368
|
-
try {
|
|
369
|
-
cb.validate();
|
|
370
|
-
} catch (err) {
|
|
371
|
-
console.error('Context configuration error:', err);
|
|
372
|
-
}
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
Validation rules:
|
|
376
|
-
- If only one context exists, it must be named `"default"`.
|
|
377
|
-
- Context names must be unique.
|
|
378
|
-
- Step names must be unique within a context.
|
|
379
|
-
- References in `validSteps` must point to existing steps in the same context.
|
|
380
|
-
- References in `validContexts` must point to existing contexts.
|
|
381
|
-
|
|
382
|
-
---
|
|
383
|
-
|
|
384
|
-
## Real-World Example
|
|
385
|
-
|
|
386
|
-
### Customer Support Workflow
|
|
387
|
-
|
|
388
|
-
```typescript
|
|
389
|
-
import { AgentBase, ContextBuilder, GatherInfo, GatherQuestion, FunctionResult } from '@signalwire/sdk';
|
|
390
|
-
|
|
391
|
-
const agent = new AgentBase({ name: 'support-agent' });
|
|
392
|
-
agent.setPromptText('You are a customer support agent for TechCorp.');
|
|
393
|
-
|
|
394
|
-
const cb = agent.defineContexts();
|
|
395
|
-
|
|
396
|
-
// --- Greeting Context ---
|
|
397
|
-
const greeting = cb.addContext('greeting');
|
|
398
|
-
|
|
399
|
-
const welcome = greeting.addStep('welcome');
|
|
400
|
-
welcome.setText('Welcome to TechCorp support! How can I help you today?');
|
|
401
|
-
welcome.setValidSteps(['identify']);
|
|
402
|
-
welcome.setValidContexts(['technical', 'billing']);
|
|
403
|
-
|
|
404
|
-
const identify = greeting.addStep('identify');
|
|
405
|
-
identify.setText('Let me verify your identity first.');
|
|
406
|
-
identify.setGatherInfo(
|
|
407
|
-
new GatherInfo()
|
|
408
|
-
.addQuestion(
|
|
409
|
-
new GatherQuestion('account_number')
|
|
410
|
-
.setQuestion('What is your account number?')
|
|
411
|
-
.setDescription('8-digit account number')
|
|
412
|
-
.setValidation('^\\d{8}$'),
|
|
413
|
-
)
|
|
414
|
-
.addQuestion(
|
|
415
|
-
new GatherQuestion('name')
|
|
416
|
-
.setQuestion('What is the name on the account?')
|
|
417
|
-
.setDescription('Account holder name'),
|
|
418
|
-
),
|
|
419
|
-
);
|
|
420
|
-
identify.setCriteria('User has provided a valid account number and name.');
|
|
421
|
-
identify.setFunctions(['verify_account']);
|
|
422
|
-
identify.setValidContexts(['technical', 'billing']);
|
|
423
|
-
|
|
424
|
-
// --- Technical Support Context ---
|
|
425
|
-
const technical = cb.addContext('technical');
|
|
426
|
-
technical.setPrompt('The user needs technical assistance.');
|
|
427
|
-
|
|
428
|
-
const diagnose = technical.addStep('diagnose');
|
|
429
|
-
diagnose.setText('Let me help diagnose your issue.');
|
|
430
|
-
diagnose.addSection('Troubleshooting', {
|
|
431
|
-
body: 'Follow this diagnostic flow:',
|
|
432
|
-
bullets: [
|
|
433
|
-
'Ask what device or service is affected',
|
|
434
|
-
'Ask when the issue started',
|
|
435
|
-
'Check if the user has tried restarting',
|
|
436
|
-
],
|
|
437
|
-
});
|
|
438
|
-
diagnose.setFunctions(['check_service_status', 'run_diagnostics']);
|
|
439
|
-
diagnose.setValidSteps(['resolve', 'escalate']);
|
|
440
|
-
|
|
441
|
-
const resolve = technical.addStep('resolve');
|
|
442
|
-
resolve.setText('Based on the diagnosis, apply the appropriate fix.');
|
|
443
|
-
resolve.setFunctions(['apply_fix', 'schedule_technician']);
|
|
444
|
-
resolve.setEnd(true);
|
|
445
|
-
|
|
446
|
-
const escalate = technical.addStep('escalate');
|
|
447
|
-
escalate.setText('I will escalate this to our engineering team.');
|
|
448
|
-
escalate.setFunctions(['create_ticket']);
|
|
449
|
-
escalate.setEnd(true);
|
|
450
|
-
|
|
451
|
-
// --- Billing Context ---
|
|
452
|
-
const billing = cb.addContext('billing');
|
|
453
|
-
billing.setPrompt('The user has a billing question.');
|
|
454
|
-
|
|
455
|
-
const reviewBill = billing.addStep('review');
|
|
456
|
-
reviewBill.setText('Let me pull up your billing information.');
|
|
457
|
-
reviewBill.setFunctions(['get_billing_summary', 'get_recent_charges']);
|
|
458
|
-
reviewBill.setValidSteps(['adjust']);
|
|
459
|
-
|
|
460
|
-
const adjustBill = billing.addStep('adjust');
|
|
461
|
-
adjustBill.setText('I can help with billing adjustments.');
|
|
462
|
-
adjustBill.setFunctions(['apply_credit', 'process_refund']);
|
|
463
|
-
adjustBill.setEnd(true);
|
|
464
|
-
|
|
465
|
-
// Define tools
|
|
466
|
-
agent.defineTool({
|
|
467
|
-
name: 'verify_account',
|
|
468
|
-
description: 'Verify a customer account by number and name',
|
|
469
|
-
parameters: {
|
|
470
|
-
account_number: { type: 'string', description: 'Account number' },
|
|
471
|
-
name: { type: 'string', description: 'Account holder name' },
|
|
472
|
-
},
|
|
473
|
-
handler: async (args) => {
|
|
474
|
-
const verified = await verifyAccount(
|
|
475
|
-
args.account_number as string,
|
|
476
|
-
args.name as string,
|
|
477
|
-
);
|
|
478
|
-
if (verified) {
|
|
479
|
-
return new FunctionResult('Account verified successfully.')
|
|
480
|
-
.updateGlobalData({ account_verified: true });
|
|
481
|
-
}
|
|
482
|
-
return new FunctionResult('Account verification failed. Please try again.');
|
|
483
|
-
},
|
|
484
|
-
});
|
|
485
|
-
|
|
486
|
-
agent.defineTool({
|
|
487
|
-
name: 'check_service_status',
|
|
488
|
-
description: 'Check the status of a service',
|
|
489
|
-
parameters: {
|
|
490
|
-
service: { type: 'string', description: 'Service name' },
|
|
491
|
-
},
|
|
492
|
-
handler: async (args) => {
|
|
493
|
-
return new FunctionResult(`Service ${args.service} is operational.`);
|
|
494
|
-
},
|
|
495
|
-
});
|
|
496
|
-
|
|
497
|
-
agent.serve();
|
|
498
|
-
```
|
|
499
|
-
|
|
500
|
-
---
|
|
501
|
-
|
|
502
|
-
## Best Practices
|
|
503
|
-
|
|
504
|
-
1. **Name contexts and steps descriptively** -- Use names like `"billing_review"` instead of `"step1"`.
|
|
505
|
-
2. **Always set completion criteria** -- Without criteria, the AI may not know when to advance.
|
|
506
|
-
3. **Use function restrictions** -- Limit available tools per step to prevent the AI from calling irrelevant functions.
|
|
507
|
-
4. **Validate before serving** -- Call `cb.validate()` during development to catch configuration errors early.
|
|
508
|
-
5. **Use GatherInfo for structured collection** -- When you need specific fields from the user, GatherInfo provides better structure than freeform prompting.
|
|
509
|
-
6. **Set fillers for long operations** -- Filler phrases keep the conversation natural during processing.
|
|
510
|
-
7. **Design for re-entry** -- Use `setResetOnEntry(true)` on steps that should always start fresh.
|
|
511
|
-
8. **Limit context depth** -- Keep the context graph shallow; deeply nested contexts can confuse the AI.
|