@signalwire/sdk 2.0.0 → 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 (612) 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/dist/index.d.ts +146 -0
  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/{src/rest/index.ts → dist/rest/index.d.ts} +53 -122
  149. package/dist/rest/index.js +195 -0
  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/dist/rest/pagination.d.ts +39 -0
  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 -2489
  416. package/src/AgentServer.ts +0 -415
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1150
  420. package/src/DataMap.ts +0 -449
  421. package/src/FunctionResult.ts +0 -866
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -439
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -717
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -221
  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 -258
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -181
  435. package/src/WebService.ts +0 -619
  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/index.ts +0 -167
  441. package/src/livewire/index.ts +0 -950
  442. package/src/prefabs/ConciergeAgent.ts +0 -287
  443. package/src/prefabs/FAQBotAgent.ts +0 -384
  444. package/src/prefabs/InfoGathererAgent.ts +0 -339
  445. package/src/prefabs/ReceptionistAgent.ts +0 -366
  446. package/src/prefabs/SurveyAgent.ts +0 -646
  447. package/src/relay/Action.ts +0 -314
  448. package/src/relay/Call.ts +0 -854
  449. package/src/relay/Deferred.ts +0 -71
  450. package/src/relay/Message.ts +0 -148
  451. package/src/relay/RelayClient.ts +0 -1036
  452. package/src/relay/RelayError.ts +0 -14
  453. package/src/relay/RelayEvent.ts +0 -892
  454. package/src/relay/index.ts +0 -123
  455. package/src/relay/types.ts +0 -149
  456. package/src/rest/HttpClient.ts +0 -103
  457. package/src/rest/RestError.ts +0 -31
  458. package/src/rest/base/BaseResource.ts +0 -19
  459. package/src/rest/base/CrudResource.ts +0 -51
  460. package/src/rest/base/CrudWithAddresses.ts +0 -26
  461. package/src/rest/namespaces/addresses.ts +0 -32
  462. package/src/rest/namespaces/calling.ts +0 -187
  463. package/src/rest/namespaces/chat.ts +0 -20
  464. package/src/rest/namespaces/compat.ts +0 -352
  465. package/src/rest/namespaces/datasphere.ts +0 -45
  466. package/src/rest/namespaces/fabric.ts +0 -222
  467. package/src/rest/namespaces/imported-numbers.ts +0 -20
  468. package/src/rest/namespaces/logs.ts +0 -84
  469. package/src/rest/namespaces/lookup.ts +0 -21
  470. package/src/rest/namespaces/mfa.ts +0 -30
  471. package/src/rest/namespaces/number-groups.ts +0 -38
  472. package/src/rest/namespaces/phone-numbers.ts +0 -44
  473. package/src/rest/namespaces/project.ts +0 -36
  474. package/src/rest/namespaces/pubsub.ts +0 -20
  475. package/src/rest/namespaces/queues.ts +0 -33
  476. package/src/rest/namespaces/recordings.ts +0 -28
  477. package/src/rest/namespaces/registry.ts +0 -101
  478. package/src/rest/namespaces/short-codes.ts +0 -28
  479. package/src/rest/namespaces/sip-profile.ts +0 -25
  480. package/src/rest/namespaces/verified-callers.ts +0 -27
  481. package/src/rest/namespaces/video.ts +0 -165
  482. package/src/rest/pagination.ts +0 -84
  483. package/src/rest/types.ts +0 -61
  484. package/src/skills/SkillBase.ts +0 -547
  485. package/src/skills/SkillManager.ts +0 -415
  486. package/src/skills/SkillRegistry.ts +0 -367
  487. package/src/skills/builtin/api_ninjas_trivia.ts +0 -280
  488. package/src/skills/builtin/ask_claude.ts +0 -241
  489. package/src/skills/builtin/claude_skills.ts +0 -978
  490. package/src/skills/builtin/custom_skills.ts +0 -312
  491. package/src/skills/builtin/datasphere.ts +0 -438
  492. package/src/skills/builtin/datasphere_serverless.ts +0 -339
  493. package/src/skills/builtin/datetime.ts +0 -130
  494. package/src/skills/builtin/google_maps.ts +0 -651
  495. package/src/skills/builtin/info_gatherer.ts +0 -405
  496. package/src/skills/builtin/joke.ts +0 -191
  497. package/src/skills/builtin/math.ts +0 -142
  498. package/src/skills/builtin/mcp_gateway.ts +0 -677
  499. package/src/skills/builtin/native_vector_search.ts +0 -901
  500. package/src/skills/builtin/play_background_file.ts +0 -358
  501. package/src/skills/builtin/spider.ts +0 -869
  502. package/src/skills/builtin/swml_transfer.ts +0 -635
  503. package/src/skills/builtin/weather_api.ts +0 -248
  504. package/src/skills/builtin/web_search.ts +0 -1074
  505. package/src/skills/builtin/wikipedia_search.ts +0 -299
  506. package/src/types.ts +0 -132
  507. package/tests/AgentBase.test.ts +0 -1093
  508. package/tests/AgentServer.test.ts +0 -126
  509. package/tests/AuthHandler.test.ts +0 -133
  510. package/tests/ConfigLoader.test.ts +0 -151
  511. package/tests/ContextBuilder.test.ts +0 -108
  512. package/tests/DataMap.test.ts +0 -367
  513. package/tests/EphemeralSkillCopy.test.ts +0 -107
  514. package/tests/FunctionResult.test.ts +0 -298
  515. package/tests/GracefulShutdown.test.ts +0 -46
  516. package/tests/Logger.test.ts +0 -420
  517. package/tests/PomBuilder.test.ts +0 -228
  518. package/tests/ProxyDetection.test.ts +0 -228
  519. package/tests/SWMLService.test.ts +0 -320
  520. package/tests/SWMLVerbHandler.test.ts +0 -523
  521. package/tests/SchemaUtils.test.ts +0 -106
  522. package/tests/SchemaUtils.verb.test.ts +0 -206
  523. package/tests/SecurityUtils.test.ts +0 -192
  524. package/tests/ServerlessAdapter.test.ts +0 -222
  525. package/tests/SessionManager.test.ts +0 -257
  526. package/tests/SkillBaseFeatures.test.ts +0 -130
  527. package/tests/SkillMultiInstance.test.ts +0 -102
  528. package/tests/SkillParameterSchemas.test.ts +0 -134
  529. package/tests/SkillRegistrySchema.test.ts +0 -84
  530. package/tests/SslConfig.test.ts +0 -97
  531. package/tests/SwmlBuilder.test.ts +0 -400
  532. package/tests/TypeInference.test.ts +0 -165
  533. package/tests/VerbHandlerRegistry.test.ts +0 -128
  534. package/tests/cli/mock-data.test.ts +0 -113
  535. package/tests/cli/swaig-test.test.ts +0 -108
  536. package/tests/examples.test.ts +0 -194
  537. package/tests/fixtures/scrape-parity/README.md +0 -53
  538. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  548. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  549. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  550. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  551. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  552. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  553. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  554. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  555. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  556. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  557. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  558. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  559. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  560. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  561. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  562. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  563. package/tests/livewire/livewire.test.ts +0 -780
  564. package/tests/mcp.test.ts +0 -221
  565. package/tests/prefabs/prefabs.test.ts +0 -1093
  566. package/tests/relay/Action.test.ts +0 -392
  567. package/tests/relay/Call.test.ts +0 -535
  568. package/tests/relay/Deferred.test.ts +0 -71
  569. package/tests/relay/Message.test.ts +0 -164
  570. package/tests/relay/RelayClient.test.ts +0 -779
  571. package/tests/relay/RelayEvent.test.ts +0 -463
  572. package/tests/relay/helpers.ts +0 -79
  573. package/tests/rest/HttpClient.test.ts +0 -274
  574. package/tests/rest/RestError.test.ts +0 -53
  575. package/tests/rest/calling.test.ts +0 -156
  576. package/tests/rest/client.test.ts +0 -197
  577. package/tests/rest/compat.test.ts +0 -335
  578. package/tests/rest/datasphere.test.ts +0 -71
  579. package/tests/rest/fabric.test.ts +0 -186
  580. package/tests/rest/helpers.ts +0 -95
  581. package/tests/rest/logs.test.ts +0 -68
  582. package/tests/rest/pagination.test.ts +0 -133
  583. package/tests/rest/registry.test.ts +0 -94
  584. package/tests/rest/relay-rest.test.ts +0 -290
  585. package/tests/rest/video.test.ts +0 -173
  586. package/tests/setup.ts +0 -6
  587. package/tests/skills/SkillBase.test.ts +0 -108
  588. package/tests/skills/SkillManager.test.ts +0 -268
  589. package/tests/skills/SkillRegistry.test.ts +0 -176
  590. package/tests/skills/builtin.test.ts +0 -1472
  591. package/tests/skills/claude-skills.test.ts +0 -54
  592. package/tests/skills/custom-skills.test.ts +0 -53
  593. package/tests/skills/datasphere-serverless.test.ts +0 -70
  594. package/tests/skills/datasphere.test.ts +0 -107
  595. package/tests/skills/datetime.test.ts +0 -101
  596. package/tests/skills/google-maps.test.ts +0 -78
  597. package/tests/skills/info-gatherer.test.ts +0 -411
  598. package/tests/skills/joke.test.ts +0 -81
  599. package/tests/skills/math.test.ts +0 -68
  600. package/tests/skills/mcp-gateway.test.ts +0 -101
  601. package/tests/skills/play-background.test.ts +0 -54
  602. package/tests/skills/spider.test.ts +0 -108
  603. package/tests/skills/swml-transfer.test.ts +0 -178
  604. package/tests/skills/trivia.test.ts +0 -54
  605. package/tests/skills/vector-search.test.ts +0 -135
  606. package/tests/skills/weather-api.test.ts +0 -77
  607. package/tests/skills/web-search-parity.test.ts +0 -59
  608. package/tests/skills/web-search.test.ts +0 -103
  609. package/tests/skills/wikipedia.test.ts +0 -63
  610. package/tsconfig.json +0 -18
  611. package/vitest.config.ts +0 -9
  612. /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.