@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.
Files changed (610) hide show
  1. package/dist/AgentBase.d.ts +1045 -0
  2. package/dist/AgentBase.js +2375 -0
  3. package/dist/AgentBase.js.map +1 -0
  4. package/dist/AgentServer.d.ts +146 -0
  5. package/dist/AgentServer.js +388 -0
  6. package/dist/AgentServer.js.map +1 -0
  7. package/dist/AuthHandler.d.ts +127 -0
  8. package/dist/AuthHandler.js +212 -0
  9. package/dist/AuthHandler.js.map +1 -0
  10. package/dist/ConfigLoader.d.ts +170 -0
  11. package/dist/ConfigLoader.js +393 -0
  12. package/dist/ConfigLoader.js.map +1 -0
  13. package/dist/ContextBuilder.d.ts +652 -0
  14. package/dist/ContextBuilder.js +1115 -0
  15. package/dist/ContextBuilder.js.map +1 -0
  16. package/dist/DataMap.d.ts +271 -0
  17. package/dist/DataMap.js +430 -0
  18. package/dist/DataMap.js.map +1 -0
  19. package/dist/FunctionResult.d.ts +481 -0
  20. package/dist/FunctionResult.js +775 -0
  21. package/dist/FunctionResult.js.map +1 -0
  22. package/dist/Logger.d.ts +113 -0
  23. package/dist/Logger.js +320 -0
  24. package/dist/Logger.js.map +1 -0
  25. package/dist/PomBuilder.d.ts +208 -0
  26. package/dist/PomBuilder.js +409 -0
  27. package/dist/PomBuilder.js.map +1 -0
  28. package/dist/PromptManager.d.ts +85 -0
  29. package/dist/PromptManager.js +108 -0
  30. package/dist/PromptManager.js.map +1 -0
  31. package/dist/SWMLHandler.d.ts +159 -0
  32. package/dist/SWMLHandler.js +229 -0
  33. package/dist/SWMLHandler.js.map +1 -0
  34. package/dist/SWMLService.d.ts +326 -0
  35. package/dist/SWMLService.js +610 -0
  36. package/dist/SWMLService.js.map +1 -0
  37. package/dist/SchemaUtils.d.ts +108 -0
  38. package/dist/SchemaUtils.js +317 -0
  39. package/dist/SchemaUtils.js.map +1 -0
  40. package/dist/SecurityUtils.d.ts +60 -0
  41. package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
  42. package/dist/SecurityUtils.js.map +1 -0
  43. package/dist/ServerlessAdapter.d.ts +119 -0
  44. package/dist/ServerlessAdapter.js +188 -0
  45. package/dist/ServerlessAdapter.js.map +1 -0
  46. package/dist/SessionManager.d.ts +142 -0
  47. package/dist/SessionManager.js +260 -0
  48. package/dist/SessionManager.js.map +1 -0
  49. package/dist/SslConfig.d.ts +77 -0
  50. package/dist/SslConfig.js +100 -0
  51. package/dist/SslConfig.js.map +1 -0
  52. package/dist/SwaigFunction.d.ts +159 -0
  53. package/dist/SwaigFunction.js +209 -0
  54. package/dist/SwaigFunction.js.map +1 -0
  55. package/dist/SwmlBuilder.d.ts +165 -0
  56. package/dist/SwmlBuilder.js +247 -0
  57. package/dist/SwmlBuilder.js.map +1 -0
  58. package/dist/SwmlVerbMethods.generated.d.ts +254 -0
  59. package/dist/SwmlVerbMethods.generated.js +9 -0
  60. package/dist/SwmlVerbMethods.generated.js.map +1 -0
  61. package/dist/TypeInference.d.ts +71 -0
  62. package/dist/TypeInference.js +164 -0
  63. package/dist/TypeInference.js.map +1 -0
  64. package/dist/WebService.d.ts +148 -0
  65. package/dist/WebService.js +532 -0
  66. package/dist/WebService.js.map +1 -0
  67. package/dist/cli/agent-loader.d.ts +22 -0
  68. package/dist/cli/agent-loader.js +144 -0
  69. package/dist/cli/agent-loader.js.map +1 -0
  70. package/dist/cli/mock-data.d.ts +37 -0
  71. package/dist/cli/mock-data.js +80 -0
  72. package/dist/cli/mock-data.js.map +1 -0
  73. package/dist/cli/swaig-test.d.ts +32 -0
  74. package/dist/cli/swaig-test.js +418 -0
  75. package/dist/cli/swaig-test.js.map +1 -0
  76. package/dist/generateVerbTypes.d.ts +11 -0
  77. package/dist/generateVerbTypes.js +265 -0
  78. package/dist/generateVerbTypes.js.map +1 -0
  79. package/{src/index.ts → dist/index.d.ts} +13 -100
  80. package/dist/index.js +152 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/livewire/index.d.ts +653 -0
  83. package/dist/livewire/index.js +992 -0
  84. package/dist/livewire/index.js.map +1 -0
  85. package/dist/prefabs/ConciergeAgent.d.ts +89 -0
  86. package/dist/prefabs/ConciergeAgent.js +245 -0
  87. package/dist/prefabs/ConciergeAgent.js.map +1 -0
  88. package/dist/prefabs/FAQBotAgent.d.ts +113 -0
  89. package/dist/prefabs/FAQBotAgent.js +329 -0
  90. package/dist/prefabs/FAQBotAgent.js.map +1 -0
  91. package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
  92. package/dist/prefabs/InfoGathererAgent.js +287 -0
  93. package/dist/prefabs/InfoGathererAgent.js.map +1 -0
  94. package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
  95. package/dist/prefabs/ReceptionistAgent.js +303 -0
  96. package/dist/prefabs/ReceptionistAgent.js.map +1 -0
  97. package/dist/prefabs/SurveyAgent.d.ts +148 -0
  98. package/dist/prefabs/SurveyAgent.js +540 -0
  99. package/dist/prefabs/SurveyAgent.js.map +1 -0
  100. package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
  101. package/dist/prefabs/index.js +14 -0
  102. package/dist/prefabs/index.js.map +1 -0
  103. package/dist/relay/Action.d.ts +258 -0
  104. package/dist/relay/Action.js +402 -0
  105. package/dist/relay/Action.js.map +1 -0
  106. package/dist/relay/Call.d.ts +697 -0
  107. package/dist/relay/Call.js +1062 -0
  108. package/dist/relay/Call.js.map +1 -0
  109. package/dist/relay/Deferred.d.ts +44 -0
  110. package/dist/relay/Deferred.js +69 -0
  111. package/dist/relay/Deferred.js.map +1 -0
  112. package/dist/relay/Message.d.ts +103 -0
  113. package/dist/relay/Message.js +169 -0
  114. package/dist/relay/Message.js.map +1 -0
  115. package/dist/relay/RelayClient.d.ts +302 -0
  116. package/dist/relay/RelayClient.js +1019 -0
  117. package/dist/relay/RelayClient.js.map +1 -0
  118. package/dist/relay/RelayError.d.ts +15 -0
  119. package/dist/relay/RelayError.js +20 -0
  120. package/dist/relay/RelayError.js.map +1 -0
  121. package/dist/relay/RelayEvent.d.ts +254 -0
  122. package/dist/relay/RelayEvent.js +509 -0
  123. package/dist/relay/RelayEvent.js.map +1 -0
  124. package/dist/relay/constants.d.ts +90 -0
  125. package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
  126. package/dist/relay/constants.js.map +1 -0
  127. package/dist/relay/index.d.ts +16 -0
  128. package/dist/relay/index.js +18 -0
  129. package/dist/relay/index.js.map +1 -0
  130. package/dist/relay/types.d.ts +142 -0
  131. package/dist/relay/types.js +5 -0
  132. package/dist/relay/types.js.map +1 -0
  133. package/dist/rest/HttpClient.d.ts +80 -0
  134. package/dist/rest/HttpClient.js +148 -0
  135. package/dist/rest/HttpClient.js.map +1 -0
  136. package/dist/rest/RestError.d.ts +30 -0
  137. package/dist/rest/RestError.js +39 -0
  138. package/dist/rest/RestError.js.map +1 -0
  139. package/dist/rest/base/BaseResource.d.ts +24 -0
  140. package/dist/rest/base/BaseResource.js +29 -0
  141. package/dist/rest/base/BaseResource.js.map +1 -0
  142. package/dist/rest/base/CrudResource.d.ts +68 -0
  143. package/dist/rest/base/CrudResource.js +82 -0
  144. package/dist/rest/base/CrudResource.js.map +1 -0
  145. package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
  146. package/dist/rest/base/CrudWithAddresses.js +25 -0
  147. package/dist/rest/base/CrudWithAddresses.js.map +1 -0
  148. package/dist/rest/index.d.ts +131 -0
  149. package/{src/rest/index.ts → dist/rest/index.js} +101 -136
  150. package/dist/rest/index.js.map +1 -0
  151. package/dist/rest/namespaces/addresses.d.ts +46 -0
  152. package/dist/rest/namespaces/addresses.js +55 -0
  153. package/dist/rest/namespaces/addresses.js.map +1 -0
  154. package/dist/rest/namespaces/calling.d.ts +382 -0
  155. package/dist/rest/namespaces/calling.js +478 -0
  156. package/dist/rest/namespaces/calling.js.map +1 -0
  157. package/dist/rest/namespaces/chat.d.ts +22 -0
  158. package/dist/rest/namespaces/chat.js +26 -0
  159. package/dist/rest/namespaces/chat.js.map +1 -0
  160. package/dist/rest/namespaces/compat.d.ts +585 -0
  161. package/dist/rest/namespaces/compat.js +735 -0
  162. package/dist/rest/namespaces/compat.js.map +1 -0
  163. package/dist/rest/namespaces/datasphere.d.ts +66 -0
  164. package/dist/rest/namespaces/datasphere.js +77 -0
  165. package/dist/rest/namespaces/datasphere.js.map +1 -0
  166. package/dist/rest/namespaces/fabric.d.ts +282 -0
  167. package/dist/rest/namespaces/fabric.js +373 -0
  168. package/dist/rest/namespaces/fabric.js.map +1 -0
  169. package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
  170. package/dist/rest/namespaces/imported-numbers.js +26 -0
  171. package/dist/rest/namespaces/imported-numbers.js.map +1 -0
  172. package/dist/rest/namespaces/logs.d.ts +105 -0
  173. package/dist/rest/namespaces/logs.js +133 -0
  174. package/dist/rest/namespaces/logs.js.map +1 -0
  175. package/dist/rest/namespaces/lookup.d.ts +29 -0
  176. package/dist/rest/namespaces/lookup.js +32 -0
  177. package/dist/rest/namespaces/lookup.js.map +1 -0
  178. package/dist/rest/namespaces/mfa.d.ts +46 -0
  179. package/dist/rest/namespaces/mfa.js +54 -0
  180. package/dist/rest/namespaces/mfa.js.map +1 -0
  181. package/dist/rest/namespaces/number-groups.d.ts +49 -0
  182. package/dist/rest/namespaces/number-groups.js +58 -0
  183. package/dist/rest/namespaces/number-groups.js.map +1 -0
  184. package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
  185. package/dist/rest/namespaces/phone-numbers.js +67 -0
  186. package/dist/rest/namespaces/phone-numbers.js.map +1 -0
  187. package/dist/rest/namespaces/project.d.ts +46 -0
  188. package/dist/rest/namespaces/project.js +56 -0
  189. package/dist/rest/namespaces/project.js.map +1 -0
  190. package/dist/rest/namespaces/pubsub.d.ts +22 -0
  191. package/dist/rest/namespaces/pubsub.js +26 -0
  192. package/dist/rest/namespaces/pubsub.js.map +1 -0
  193. package/dist/rest/namespaces/queues.d.ts +42 -0
  194. package/dist/rest/namespaces/queues.js +49 -0
  195. package/dist/rest/namespaces/queues.js.map +1 -0
  196. package/dist/rest/namespaces/recordings.d.ts +38 -0
  197. package/dist/rest/namespaces/recordings.js +45 -0
  198. package/dist/rest/namespaces/recordings.js.map +1 -0
  199. package/dist/rest/namespaces/registry.d.ts +141 -0
  200. package/dist/rest/namespaces/registry.js +178 -0
  201. package/dist/rest/namespaces/registry.js.map +1 -0
  202. package/dist/rest/namespaces/short-codes.d.ts +39 -0
  203. package/dist/rest/namespaces/short-codes.js +46 -0
  204. package/dist/rest/namespaces/short-codes.js.map +1 -0
  205. package/dist/rest/namespaces/sip-profile.d.ts +28 -0
  206. package/dist/rest/namespaces/sip-profile.js +34 -0
  207. package/dist/rest/namespaces/sip-profile.js.map +1 -0
  208. package/dist/rest/namespaces/verified-callers.d.ts +33 -0
  209. package/dist/rest/namespaces/verified-callers.js +39 -0
  210. package/dist/rest/namespaces/verified-callers.js.map +1 -0
  211. package/dist/rest/namespaces/video.d.ts +235 -0
  212. package/dist/rest/namespaces/video.js +297 -0
  213. package/dist/rest/namespaces/video.js.map +1 -0
  214. package/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
  215. package/dist/rest/pagination.js +78 -0
  216. package/dist/rest/pagination.js.map +1 -0
  217. package/dist/rest/types.d.ts +54 -0
  218. package/dist/rest/types.js +5 -0
  219. package/dist/rest/types.js.map +1 -0
  220. package/dist/skills/SkillBase.d.ts +404 -0
  221. package/dist/skills/SkillBase.js +471 -0
  222. package/dist/skills/SkillBase.js.map +1 -0
  223. package/dist/skills/SkillManager.d.ts +195 -0
  224. package/dist/skills/SkillManager.js +378 -0
  225. package/dist/skills/SkillManager.js.map +1 -0
  226. package/dist/skills/SkillRegistry.d.ts +176 -0
  227. package/dist/skills/SkillRegistry.js +310 -0
  228. package/dist/skills/SkillRegistry.js.map +1 -0
  229. package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
  230. package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
  231. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
  232. package/dist/skills/builtin/ask_claude.d.ts +37 -0
  233. package/dist/skills/builtin/ask_claude.js +162 -0
  234. package/dist/skills/builtin/ask_claude.js.map +1 -0
  235. package/dist/skills/builtin/claude_skills.d.ts +75 -0
  236. package/dist/skills/builtin/claude_skills.js +753 -0
  237. package/dist/skills/builtin/claude_skills.js.map +1 -0
  238. package/dist/skills/builtin/custom_skills.d.ts +79 -0
  239. package/dist/skills/builtin/custom_skills.js +227 -0
  240. package/dist/skills/builtin/custom_skills.js.map +1 -0
  241. package/dist/skills/builtin/datasphere.d.ts +73 -0
  242. package/dist/skills/builtin/datasphere.js +350 -0
  243. package/dist/skills/builtin/datasphere.js.map +1 -0
  244. package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
  245. package/dist/skills/builtin/datasphere_serverless.js +291 -0
  246. package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
  247. package/dist/skills/builtin/datetime.d.ts +40 -0
  248. package/dist/skills/builtin/datetime.js +118 -0
  249. package/dist/skills/builtin/datetime.js.map +1 -0
  250. package/dist/skills/builtin/google_maps.d.ts +48 -0
  251. package/dist/skills/builtin/google_maps.js +470 -0
  252. package/dist/skills/builtin/google_maps.js.map +1 -0
  253. package/dist/skills/builtin/index.d.ts +31 -0
  254. package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
  255. package/dist/skills/builtin/index.js.map +1 -0
  256. package/dist/skills/builtin/info_gatherer.d.ts +115 -0
  257. package/dist/skills/builtin/info_gatherer.js +328 -0
  258. package/dist/skills/builtin/info_gatherer.js.map +1 -0
  259. package/dist/skills/builtin/joke.d.ts +41 -0
  260. package/dist/skills/builtin/joke.js +156 -0
  261. package/dist/skills/builtin/joke.js.map +1 -0
  262. package/dist/skills/builtin/math.d.ts +39 -0
  263. package/dist/skills/builtin/math.js +119 -0
  264. package/dist/skills/builtin/math.js.map +1 -0
  265. package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
  266. package/dist/skills/builtin/mcp_gateway.js +574 -0
  267. package/dist/skills/builtin/mcp_gateway.js.map +1 -0
  268. package/dist/skills/builtin/native_vector_search.d.ts +128 -0
  269. package/dist/skills/builtin/native_vector_search.js +752 -0
  270. package/dist/skills/builtin/native_vector_search.js.map +1 -0
  271. package/dist/skills/builtin/play_background_file.d.ts +59 -0
  272. package/dist/skills/builtin/play_background_file.js +274 -0
  273. package/dist/skills/builtin/play_background_file.js.map +1 -0
  274. package/dist/skills/builtin/spider.d.ts +91 -0
  275. package/dist/skills/builtin/spider.js +758 -0
  276. package/dist/skills/builtin/spider.js.map +1 -0
  277. package/dist/skills/builtin/swml_transfer.d.ts +66 -0
  278. package/dist/skills/builtin/swml_transfer.js +475 -0
  279. package/dist/skills/builtin/swml_transfer.js.map +1 -0
  280. package/dist/skills/builtin/weather_api.d.ts +59 -0
  281. package/dist/skills/builtin/weather_api.js +196 -0
  282. package/dist/skills/builtin/weather_api.js.map +1 -0
  283. package/dist/skills/builtin/web_search.d.ts +160 -0
  284. package/dist/skills/builtin/web_search.js +894 -0
  285. package/dist/skills/builtin/web_search.js.map +1 -0
  286. package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
  287. package/dist/skills/builtin/wikipedia_search.js +241 -0
  288. package/dist/skills/builtin/wikipedia_search.js.map +1 -0
  289. package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
  290. package/dist/skills/index.js +10 -0
  291. package/dist/skills/index.js.map +1 -0
  292. package/dist/types.d.ts +118 -0
  293. package/dist/types.js +5 -0
  294. package/dist/types.js.map +1 -0
  295. package/package.json +7 -1
  296. package/.github/workflows/publish.yml +0 -27
  297. package/.github/workflows/test.yml +0 -17
  298. package/CLAUDE.md +0 -112
  299. package/docs/MIGRATION-2.0.md +0 -81
  300. package/docs/agent-guide.md +0 -869
  301. package/docs/agent_guide.md +0 -1026
  302. package/docs/api-reference.md +0 -2420
  303. package/docs/api_reference.md +0 -1301
  304. package/docs/architecture.md +0 -843
  305. package/docs/cli-guide.md +0 -579
  306. package/docs/cli_guide.md +0 -448
  307. package/docs/cloud_functions_guide.md +0 -474
  308. package/docs/configuration.md +0 -422
  309. package/docs/contexts-guide.md +0 -787
  310. package/docs/contexts_guide.md +0 -511
  311. package/docs/datamap-guide.md +0 -1141
  312. package/docs/datamap_guide.md +0 -595
  313. package/docs/llm_parameters.md +0 -239
  314. package/docs/mcp_gateway_reference.md +0 -648
  315. package/docs/mcp_integration.md +0 -108
  316. package/docs/prefabs-guide.md +0 -800
  317. package/docs/sdk_features.md +0 -477
  318. package/docs/security.md +0 -436
  319. package/docs/serverless-guide.md +0 -513
  320. package/docs/skills-guide.md +0 -857
  321. package/docs/skills-system.md +0 -301
  322. package/docs/skills_parameter_schema.md +0 -392
  323. package/docs/skills_system.md +0 -467
  324. package/docs/swaig-reference.md +0 -1627
  325. package/docs/swaig_reference.md +0 -910
  326. package/docs/swml_service_guide.md +0 -600
  327. package/docs/third_party_skills.md +0 -533
  328. package/docs/web_service.md +0 -677
  329. package/examples/README.md +0 -131
  330. package/examples/advanced-datamap.ts +0 -100
  331. package/examples/advanced-dynamic-config.ts +0 -70
  332. package/examples/auto-vivified.ts +0 -94
  333. package/examples/call-flow.ts +0 -63
  334. package/examples/comprehensive-dynamic.ts +0 -125
  335. package/examples/contexts-steps.ts +0 -65
  336. package/examples/custom-path.ts +0 -45
  337. package/examples/datamap-tools.ts +0 -55
  338. package/examples/datasphere-multi-instance.ts +0 -63
  339. package/examples/datasphere-serverless-env.ts +0 -68
  340. package/examples/datasphere-webhook-env.ts +0 -66
  341. package/examples/datasphere.ts +0 -37
  342. package/examples/declarative.ts +0 -100
  343. package/examples/dynamic-config.ts +0 -54
  344. package/examples/dynamic-info-gatherer.ts +0 -69
  345. package/examples/dynamic-swml-service.ts +0 -67
  346. package/examples/gather-info.ts +0 -71
  347. package/examples/gather-per-question-functions-demo.ts +0 -140
  348. package/examples/joke-agent.ts +0 -34
  349. package/examples/kubernetes-agent.ts +0 -45
  350. package/examples/llm-params.ts +0 -69
  351. package/examples/mcp-agent.ts +0 -84
  352. package/examples/mcp-gateway.ts +0 -35
  353. package/examples/multi-agent.ts +0 -73
  354. package/examples/multi-endpoint.ts +0 -79
  355. package/examples/pom-prompt.ts +0 -71
  356. package/examples/prefab-concierge.ts +0 -47
  357. package/examples/prefab-faq.ts +0 -54
  358. package/examples/prefab-info-gatherer.ts +0 -33
  359. package/examples/prefab-receptionist.ts +0 -36
  360. package/examples/prefab-survey.ts +0 -68
  361. package/examples/record-call.ts +0 -67
  362. package/examples/relay-demo.ts +0 -33
  363. package/examples/room-and-sip.ts +0 -94
  364. package/examples/serverless-lambda.ts +0 -35
  365. package/examples/session-state.ts +0 -83
  366. package/examples/simple-agent.ts +0 -36
  367. package/examples/simple-static.ts +0 -29
  368. package/examples/skills-demo.ts +0 -38
  369. package/examples/step-function-inheritance-demo.ts +0 -124
  370. package/examples/swaig-features.ts +0 -187
  371. package/examples/swml-service-routing.ts +0 -66
  372. package/examples/swml-service.ts +0 -38
  373. package/examples/tap.ts +0 -68
  374. package/examples/verb-methods.ts +0 -45
  375. package/examples/web-search-multi-instance.ts +0 -72
  376. package/examples/web-search.ts +0 -38
  377. package/examples/wikipedia.ts +0 -36
  378. package/livewire/README.md +0 -140
  379. package/livewire/docs/migration-guide.md +0 -228
  380. package/livewire/examples/livewire-basic-agent.ts +0 -74
  381. package/livewire/examples/livewire-handoff.ts +0 -197
  382. package/livewire/examples/livewire-multi-tool.ts +0 -117
  383. package/relay/README.md +0 -70
  384. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
  385. package/relay/docs/call-methods.md +0 -474
  386. package/relay/docs/client-reference.md +0 -142
  387. package/relay/docs/events.md +0 -134
  388. package/relay/docs/getting-started.md +0 -134
  389. package/relay/docs/guide.md +0 -306
  390. package/relay/docs/messaging.md +0 -182
  391. package/relay/examples/relay-inbound.ts +0 -66
  392. package/relay/examples/relay-messaging.ts +0 -71
  393. package/relay/examples/relay-outbound.ts +0 -76
  394. package/rest/README.md +0 -95
  395. package/rest/docs/calling.md +0 -273
  396. package/rest/docs/client-reference.md +0 -107
  397. package/rest/docs/compat.md +0 -204
  398. package/rest/docs/fabric.md +0 -183
  399. package/rest/docs/getting-started.md +0 -110
  400. package/rest/docs/guide.md +0 -351
  401. package/rest/docs/namespaces.md +0 -285
  402. package/rest/examples/rest-10dlc-registration.ts +0 -161
  403. package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
  404. package/rest/examples/rest-calling-play-and-record.ts +0 -91
  405. package/rest/examples/rest-client.ts +0 -65
  406. package/rest/examples/rest-compat-laml.ts +0 -210
  407. package/rest/examples/rest-datasphere-search.ts +0 -82
  408. package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
  409. package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
  410. package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
  411. package/rest/examples/rest-manage-resources.ts +0 -65
  412. package/rest/examples/rest-phone-number-management.ts +0 -197
  413. package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
  414. package/rest/examples/rest-video-rooms.ts +0 -186
  415. package/src/AgentBase.ts +0 -2598
  416. package/src/AgentServer.ts +0 -442
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1181
  420. package/src/DataMap.ts +0 -477
  421. package/src/FunctionResult.ts +0 -903
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -467
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -749
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -240
  429. package/src/SessionManager.ts +0 -311
  430. package/src/SslConfig.ts +0 -118
  431. package/src/SwaigFunction.ts +0 -276
  432. package/src/SwmlBuilder.ts +0 -283
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -199
  435. package/src/WebService.ts +0 -641
  436. package/src/cli/agent-loader.ts +0 -166
  437. package/src/cli/mock-data.ts +0 -111
  438. package/src/cli/swaig-test.ts +0 -452
  439. package/src/generateVerbTypes.ts +0 -322
  440. package/src/livewire/index.ts +0 -1252
  441. package/src/prefabs/ConciergeAgent.ts +0 -309
  442. package/src/prefabs/FAQBotAgent.ts +0 -415
  443. package/src/prefabs/InfoGathererAgent.ts +0 -379
  444. package/src/prefabs/ReceptionistAgent.ts +0 -395
  445. package/src/prefabs/SurveyAgent.ts +0 -671
  446. package/src/relay/Action.ts +0 -482
  447. package/src/relay/Call.ts +0 -1270
  448. package/src/relay/Deferred.ts +0 -94
  449. package/src/relay/Message.ts +0 -199
  450. package/src/relay/RelayClient.ts +0 -1185
  451. package/src/relay/RelayError.ts +0 -20
  452. package/src/relay/RelayEvent.ts +0 -944
  453. package/src/relay/index.ts +0 -123
  454. package/src/relay/types.ts +0 -149
  455. package/src/rest/HttpClient.ts +0 -164
  456. package/src/rest/RestError.ts +0 -45
  457. package/src/rest/base/BaseResource.ts +0 -32
  458. package/src/rest/base/CrudResource.ts +0 -98
  459. package/src/rest/base/CrudWithAddresses.ts +0 -37
  460. package/src/rest/namespaces/addresses.ts +0 -64
  461. package/src/rest/namespaces/calling.ts +0 -534
  462. package/src/rest/namespaces/chat.ts +0 -31
  463. package/src/rest/namespaces/compat.ts +0 -812
  464. package/src/rest/namespaces/datasphere.ts +0 -88
  465. package/src/rest/namespaces/fabric.ts +0 -417
  466. package/src/rest/namespaces/imported-numbers.ts +0 -31
  467. package/src/rest/namespaces/logs.ts +0 -151
  468. package/src/rest/namespaces/lookup.ts +0 -38
  469. package/src/rest/namespaces/mfa.ts +0 -61
  470. package/src/rest/namespaces/number-groups.ts +0 -68
  471. package/src/rest/namespaces/phone-numbers.ts +0 -76
  472. package/src/rest/namespaces/project.ts +0 -65
  473. package/src/rest/namespaces/pubsub.ts +0 -31
  474. package/src/rest/namespaces/queues.ts +0 -58
  475. package/src/rest/namespaces/recordings.ts +0 -53
  476. package/src/rest/namespaces/registry.ts +0 -200
  477. package/src/rest/namespaces/short-codes.ts +0 -54
  478. package/src/rest/namespaces/sip-profile.ts +0 -40
  479. package/src/rest/namespaces/verified-callers.ts +0 -46
  480. package/src/rest/namespaces/video.ts +0 -332
  481. package/src/rest/types.ts +0 -61
  482. package/src/skills/SkillBase.ts +0 -582
  483. package/src/skills/SkillManager.ts +0 -419
  484. package/src/skills/SkillRegistry.ts +0 -367
  485. package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
  486. package/src/skills/builtin/ask_claude.ts +0 -246
  487. package/src/skills/builtin/claude_skills.ts +0 -983
  488. package/src/skills/builtin/custom_skills.ts +0 -327
  489. package/src/skills/builtin/datasphere.ts +0 -447
  490. package/src/skills/builtin/datasphere_serverless.ts +0 -347
  491. package/src/skills/builtin/datetime.ts +0 -137
  492. package/src/skills/builtin/google_maps.ts +0 -656
  493. package/src/skills/builtin/info_gatherer.ts +0 -415
  494. package/src/skills/builtin/joke.ts +0 -196
  495. package/src/skills/builtin/math.ts +0 -149
  496. package/src/skills/builtin/mcp_gateway.ts +0 -685
  497. package/src/skills/builtin/native_vector_search.ts +0 -910
  498. package/src/skills/builtin/play_background_file.ts +0 -367
  499. package/src/skills/builtin/spider.ts +0 -874
  500. package/src/skills/builtin/swml_transfer.ts +0 -645
  501. package/src/skills/builtin/weather_api.ts +0 -255
  502. package/src/skills/builtin/web_search.ts +0 -1083
  503. package/src/skills/builtin/wikipedia_search.ts +0 -304
  504. package/src/types.ts +0 -132
  505. package/tests/AgentBase.test.ts +0 -1093
  506. package/tests/AgentServer.test.ts +0 -126
  507. package/tests/AuthHandler.test.ts +0 -133
  508. package/tests/ConfigLoader.test.ts +0 -151
  509. package/tests/ContextBuilder.test.ts +0 -108
  510. package/tests/DataMap.test.ts +0 -367
  511. package/tests/EphemeralSkillCopy.test.ts +0 -107
  512. package/tests/FunctionResult.test.ts +0 -298
  513. package/tests/GracefulShutdown.test.ts +0 -46
  514. package/tests/Logger.test.ts +0 -420
  515. package/tests/PomBuilder.test.ts +0 -228
  516. package/tests/ProxyDetection.test.ts +0 -228
  517. package/tests/SWMLService.test.ts +0 -320
  518. package/tests/SWMLVerbHandler.test.ts +0 -523
  519. package/tests/SchemaUtils.test.ts +0 -106
  520. package/tests/SchemaUtils.verb.test.ts +0 -206
  521. package/tests/SecurityUtils.test.ts +0 -192
  522. package/tests/ServerlessAdapter.test.ts +0 -222
  523. package/tests/SessionManager.test.ts +0 -257
  524. package/tests/SkillBaseFeatures.test.ts +0 -130
  525. package/tests/SkillMultiInstance.test.ts +0 -102
  526. package/tests/SkillParameterSchemas.test.ts +0 -134
  527. package/tests/SkillRegistrySchema.test.ts +0 -84
  528. package/tests/SslConfig.test.ts +0 -97
  529. package/tests/SwmlBuilder.test.ts +0 -400
  530. package/tests/TypeInference.test.ts +0 -165
  531. package/tests/VerbHandlerRegistry.test.ts +0 -128
  532. package/tests/cli/mock-data.test.ts +0 -113
  533. package/tests/cli/swaig-test.test.ts +0 -108
  534. package/tests/examples.test.ts +0 -194
  535. package/tests/fixtures/scrape-parity/README.md +0 -53
  536. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  537. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  538. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  548. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  549. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  550. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  551. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  552. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  553. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  554. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  555. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  556. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  557. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  558. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  559. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  560. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  561. package/tests/livewire/livewire.test.ts +0 -780
  562. package/tests/mcp.test.ts +0 -221
  563. package/tests/prefabs/prefabs.test.ts +0 -1093
  564. package/tests/relay/Action.test.ts +0 -392
  565. package/tests/relay/Call.test.ts +0 -535
  566. package/tests/relay/Deferred.test.ts +0 -71
  567. package/tests/relay/Message.test.ts +0 -164
  568. package/tests/relay/RelayClient.test.ts +0 -779
  569. package/tests/relay/RelayEvent.test.ts +0 -463
  570. package/tests/relay/helpers.ts +0 -79
  571. package/tests/rest/HttpClient.test.ts +0 -274
  572. package/tests/rest/RestError.test.ts +0 -53
  573. package/tests/rest/calling.test.ts +0 -156
  574. package/tests/rest/client.test.ts +0 -197
  575. package/tests/rest/compat.test.ts +0 -335
  576. package/tests/rest/datasphere.test.ts +0 -71
  577. package/tests/rest/fabric.test.ts +0 -186
  578. package/tests/rest/helpers.ts +0 -95
  579. package/tests/rest/logs.test.ts +0 -68
  580. package/tests/rest/pagination.test.ts +0 -133
  581. package/tests/rest/registry.test.ts +0 -94
  582. package/tests/rest/relay-rest.test.ts +0 -290
  583. package/tests/rest/video.test.ts +0 -173
  584. package/tests/setup.ts +0 -6
  585. package/tests/skills/SkillBase.test.ts +0 -108
  586. package/tests/skills/SkillManager.test.ts +0 -268
  587. package/tests/skills/SkillRegistry.test.ts +0 -176
  588. package/tests/skills/builtin.test.ts +0 -1472
  589. package/tests/skills/claude-skills.test.ts +0 -54
  590. package/tests/skills/custom-skills.test.ts +0 -53
  591. package/tests/skills/datasphere-serverless.test.ts +0 -70
  592. package/tests/skills/datasphere.test.ts +0 -107
  593. package/tests/skills/datetime.test.ts +0 -101
  594. package/tests/skills/google-maps.test.ts +0 -78
  595. package/tests/skills/info-gatherer.test.ts +0 -411
  596. package/tests/skills/joke.test.ts +0 -81
  597. package/tests/skills/math.test.ts +0 -68
  598. package/tests/skills/mcp-gateway.test.ts +0 -101
  599. package/tests/skills/play-background.test.ts +0 -54
  600. package/tests/skills/spider.test.ts +0 -108
  601. package/tests/skills/swml-transfer.test.ts +0 -178
  602. package/tests/skills/trivia.test.ts +0 -54
  603. package/tests/skills/vector-search.test.ts +0 -135
  604. package/tests/skills/weather-api.test.ts +0 -77
  605. package/tests/skills/web-search-parity.test.ts +0 -59
  606. package/tests/skills/web-search.test.ts +0 -103
  607. package/tests/skills/wikipedia.test.ts +0 -63
  608. package/tsconfig.json +0 -18
  609. package/vitest.config.ts +0 -9
  610. /package/{src → dist}/schema.json +0 -0
@@ -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.