@signalwire/sdk 2.0.4 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (656) hide show
  1. package/CHANGELOG.md +785 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +550 -163
  6. package/dist/AgentBase.js +1640 -514
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +163 -0
  30. package/dist/POM/PromptObjectModel.js +481 -0
  31. package/dist/POM/PromptObjectModel.js.map +1 -0
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +28 -0
  42. package/dist/PomBuilder.js +81 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +29 -1
  48. package/dist/PromptManager.js +37 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +265 -66
  58. package/dist/SWMLService.js +652 -112
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +55 -8
  64. package/dist/SecurityUtils.js +162 -49
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +95 -34
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -367
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +102 -39
  169. package/dist/index.js +107 -30
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +79 -14
  204. package/dist/relay/RelayClient.js +268 -61
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +81 -39
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +63 -0
  245. package/dist/rest/callHandler.js +62 -0
  246. package/dist/rest/callHandler.js.map +1 -0
  247. package/dist/rest/index.d.ts +19 -76
  248. package/dist/rest/index.js +49 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -273
  284. package/dist/rest/namespaces/fabric.js +14 -363
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
  332. package/dist/rest/namespaces/phone-numbers.js +9 -63
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +47 -7
  412. package/dist/skills/SkillRegistry.js +85 -13
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +34 -25
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +46 -1
  460. package/dist/skills/builtin/spider.js +317 -101
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +57 -31
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +301 -84
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +32 -14
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +65 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +88 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,884 @@
1
+ # Contexts & Steps Guide
2
+
3
+ This guide covers the Contexts & Steps system in the SignalWire AI Agents TypeScript SDK, which builds multi-step conversation workflows.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module so top-level `await` is allowed
8
+ declare global {
9
+ // Shared context the fragments on this page assume (constructed in the prose examples).
10
+ const agent: import('@signalwire/sdk').AgentBase;
11
+ const AgentBase: typeof import('@signalwire/sdk').AgentBase;
12
+ const ContextBuilder: typeof import('@signalwire/sdk').ContextBuilder;
13
+ const createSimpleContext: typeof import('@signalwire/sdk').createSimpleContext;
14
+ const cb: import('@signalwire/sdk').ContextBuilder;
15
+ const ctx: import('@signalwire/sdk').Context;
16
+ const step: import('@signalwire/sdk').Step;
17
+ }
18
+ ```
19
+
20
+ ---
21
+
22
+ ## Table of Contents
23
+
24
+ 1. [Overview](#overview)
25
+ 2. [Creating Contexts](#creating-contexts)
26
+ 3. [Steps](#steps)
27
+ 4. [Step Navigation](#step-navigation)
28
+ 5. [Function Control](#function-control)
29
+ 6. [End States](#end-states)
30
+ 7. [GatherInfo](#gatherinfo)
31
+ 8. [Context Settings](#context-settings)
32
+ 9. [Isolation and Reset](#isolation-and-reset)
33
+ 10. [Fillers](#fillers)
34
+ 11. [Validation](#validation)
35
+ 12. [Real-World Example](#real-world-example)
36
+
37
+ ---
38
+
39
+ ## Overview
40
+
41
+ Contexts and steps structure a conversation as a state machine. Instead of one flat prompt, you define **contexts**, and each context holds ordered **steps**. The platform moves through the steps by the rules you set. Those rules are completion criteria, the steps and contexts each step may move to, and the tools each step allows. Customer intake, troubleshooting trees and routing between departments fit this model.
42
+
43
+ The system has three parts:
44
+
45
+ - **Context**: a named group of ordered steps. It can have its own prompt, system prompt, navigation rules and history settings.
46
+ - **Step**: one stage within a context. It has instruction text (raw text or POM sections), completion criteria, a tool list, and the steps or contexts it may move to.
47
+ - **ContextBuilder**: the container for all contexts. It validates cross-references and serializes everything to SWML.
48
+
49
+ These classes are involved:
50
+
51
+ | Class | Role |
52
+ |---|---|
53
+ | `ContextBuilder` | Holds and validates all contexts |
54
+ | `Context` | A named context with steps, prompts, fillers and navigation rules |
55
+ | `Step` | A single step within a context, with text, criteria and function control |
56
+ | `GatherInfo` | Structured data collection attached to a step |
57
+ | `GatherQuestion` | A single question within a GatherInfo operation |
58
+
59
+ The package exports all of them from `@signalwire/sdk`.
60
+
61
+ The contexts don't replace the agent's prompt. The SDK sends the agent's prompt, or `You are <name>, a helpful AI assistant.` when there's none, together with the contexts. The contexts go in the `ai` verb's prompt object, as `ai.prompt.contexts`.
62
+
63
+ ---
64
+
65
+ ## Creating Contexts
66
+
67
+ ### Using `agent.defineContexts()`
68
+
69
+ `defineContexts()` on `AgentBase` returns a `ContextBuilder` that you add contexts to:
70
+
71
+ ```typescript
72
+ import { AgentBase } from '@signalwire/sdk';
73
+
74
+ const agent = new AgentBase({ name: 'my-agent' });
75
+
76
+ // Create and get the ContextBuilder
77
+ const cb = agent.defineContexts();
78
+
79
+ // Add contexts to the builder
80
+ const greeting = cb.addContext('default');
81
+ const support = cb.addContext('support');
82
+ const farewell = cb.addContext('farewell');
83
+ ```
84
+
85
+ You can also build a `ContextBuilder` first and pass it in:
86
+
87
+ ```typescript
88
+ import { ContextBuilder } from '@signalwire/sdk';
89
+
90
+ const cb = new ContextBuilder();
91
+ cb.addContext('default');
92
+ // ... configure ...
93
+
94
+ agent.defineContexts(cb);
95
+ ```
96
+
97
+ `agent.resetContexts()` removes every context, for example in a dynamic config callback that rebuilds them for one request. `agent.getContexts()` returns the serialized contexts.
98
+
99
+ ### Using `ContextBuilder.addContext()`
100
+
101
+ `addContext()` returns the new `Context`:
102
+
103
+ ```typescript
104
+ const cb = new ContextBuilder();
105
+
106
+ // Returns the new Context instance for chaining
107
+ const ctx = cb.addContext('intake');
108
+ ```
109
+
110
+ Context names must be unique within a builder, and a builder holds at most 50 contexts. `addContext()` throws for a duplicate name or a 51st context.
111
+
112
+ ### Retrieving a Context
113
+
114
+ `getContext()` returns a context by name, or `undefined`:
115
+
116
+ <!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
117
+ ```typescript
118
+ const ctx = cb.getContext('intake');
119
+ if (ctx) {
120
+ // configure further
121
+ }
122
+ ```
123
+
124
+ ### The `default` Context
125
+
126
+ The SWML schema requires a context named `default`, and describes it as the context the conversation starts in. The SDK enforces the name only when there's one context:
127
+
128
+ ```typescript
129
+ // Valid: single context named "default"
130
+ const cb = new ContextBuilder();
131
+ cb.addContext('default');
132
+
133
+ // Invalid: single context with any other name
134
+ const bad = new ContextBuilder();
135
+ bad.addContext('main'); // validate() will throw
136
+ ```
137
+
138
+ With several contexts, the SDK accepts a set without `default`, but the schema doesn't. Name the context the call starts in `default`.
139
+
140
+ ### Helper: `createSimpleContext()`
141
+
142
+ `createSimpleContext()` creates a standalone `Context`, named `default` unless you pass a name:
143
+
144
+ ```typescript
145
+ import { createSimpleContext } from '@signalwire/sdk';
146
+
147
+ const ctx = createSimpleContext(); // name defaults to 'default'
148
+ const step = ctx.addStep('welcome');
149
+ step.setText('Welcome the caller to the service.');
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Steps
155
+
156
+ Steps are the stages of a context, kept in the order you add them. A context holds at most 100 steps.
157
+
158
+ ### Adding a Step
159
+
160
+ `addStep()` returns the new `Step`, and takes optional shorthand settings:
161
+
162
+ <!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
163
+ ```typescript
164
+ const ctx = cb.addContext('intake');
165
+
166
+ // Basic: returns the Step for further configuration
167
+ const step1 = ctx.addStep('greet');
168
+ step1.setText('Greet the customer warmly.');
169
+
170
+ // Shorthand: pass options inline
171
+ const step2 = ctx.addStep('collect_info', {
172
+ task: 'Collect the customer name and account number.',
173
+ bullets: ['Ask for full name first', 'Then ask for account number'],
174
+ criteria: 'Customer has provided both name and account number.',
175
+ functions: ['lookup_account'],
176
+ validSteps: ['verify'],
177
+ });
178
+ ```
179
+
180
+ Each shorthand option calls a `Step` method:
181
+
182
+ | Option | Effect |
183
+ |---|---|
184
+ | `task` | Calls `step.addSection('Task', task)` |
185
+ | `bullets` | Calls `step.addBullets('Process', bullets)` |
186
+ | `criteria` | Calls `step.setStepCriteria(criteria)` |
187
+ | `functions` | Calls `step.setFunctions(functions)` |
188
+ | `validSteps` | Calls `step.setValidSteps(validSteps)` |
189
+
190
+ Step names must be unique within a context. Adding a duplicate throws an error.
191
+
192
+ ### Step Content: `setText()` vs POM Sections
193
+
194
+ A step's content is either raw text or POM sections, not both. This is the raw-text form:
195
+
196
+ ```typescript
197
+ step.setText('You are greeting the customer. Be friendly and professional.');
198
+ ```
199
+
200
+ This is the POM form, with a body section and a bullet section:
201
+
202
+ ```typescript
203
+ step.addSection('Task', 'Help the customer with their billing inquiry.');
204
+ step.addBullets('Guidelines', [
205
+ 'Be empathetic and patient',
206
+ 'Verify identity before sharing account details',
207
+ 'Offer to escalate if needed',
208
+ ]);
209
+ ```
210
+
211
+ Calling `setText()` on a step with sections, or adding a section to a step with text, throws an error.
212
+
213
+ The SDK renders POM sections as Markdown text in the step's `text` field:
214
+
215
+ ```markdown
216
+ ## Task
217
+ Help the customer with their billing inquiry.
218
+
219
+ ## Guidelines
220
+ - Be empathetic and patient
221
+ - Verify identity before sharing account details
222
+ - Offer to escalate if needed
223
+ ```
224
+
225
+ ### Managing Steps
226
+
227
+ These methods find, remove, reorder and clear steps:
228
+
229
+ ```typescript
230
+ // Retrieve a step by name
231
+ const step = ctx.getStep('greet');
232
+
233
+ // Remove a step
234
+ ctx.removeStep('greet');
235
+
236
+ // Move a step to a new position (zero-indexed)
237
+ ctx.moveStep('verify', 0); // Move "verify" to the beginning
238
+
239
+ // Clear all content from a step (sections and text)
240
+ step!.clearSections();
241
+ ```
242
+
243
+ ---
244
+
245
+ ## Step Navigation
246
+
247
+ Navigation rules control which steps and contexts the conversation can move to from a step.
248
+
249
+ ### `setValidSteps()`
250
+
251
+ `setValidSteps()` lists the steps of the current context the conversation may move to. The name `next` stands for the following step:
252
+
253
+ ```typescript
254
+ step.setValidSteps(['collect_info', 'verify', 'escalate']);
255
+ ```
256
+
257
+ The schema says that without `valid_steps`, or with an empty list, the conversation proceeds to the next step in the context.
258
+
259
+ ### `setValidContexts()`
260
+
261
+ `setValidContexts()` lists the contexts the conversation may switch to from this step:
262
+
263
+ ```typescript
264
+ step.setValidContexts(['billing', 'technical_support', 'farewell']);
265
+ ```
266
+
267
+ When a step or its context sets `valid_steps` or `valid_contexts`, the platform gives the model the `next_step` and `change_context` tools to move. You don't define those tools, and you can't register tools with those names while contexts are in use.
268
+
269
+ ### `setStepCriteria()`
270
+
271
+ `setStepCriteria()` describes, in plain language, what must happen before the step is complete:
272
+
273
+ ```typescript
274
+ step.setStepCriteria(
275
+ 'The customer has confirmed their name, account number, and the nature of their issue.'
276
+ );
277
+ ```
278
+
279
+ The criteria is an instruction to the model, which uses it to decide when to move on.
280
+
281
+ ### Context-Level Navigation
282
+
283
+ A context can set navigation rules for all its steps:
284
+
285
+ <!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
286
+ ```typescript
287
+ const billing = cb.addContext('billing');
288
+ billing.setValidContexts(['technical_support', 'farewell']);
289
+ billing.setValidSteps(['step_a', 'step_b']);
290
+ ```
291
+
292
+ ### `setInitialStep()`
293
+
294
+ A context starts on its first step. `setInitialStep()` starts it on another step, for example to skip a greeting when the conversation comes back to the context:
295
+
296
+ <!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
297
+ ```typescript
298
+ const support = cb.addContext('support');
299
+ support.addStep('greeting').setText('Introduce the support team.');
300
+ support.addStep('help').setText('Help with the issue.');
301
+ support.setInitialStep('help');
302
+ ```
303
+
304
+ The step must exist in the context, or `validate()` throws.
305
+
306
+ ---
307
+
308
+ ## Function Control
309
+
310
+ Each step can limit which SWAIG functions (tools) the model can call during that step.
311
+
312
+ ### `setFunctions()`
313
+
314
+ `setFunctions()` takes a list of function names, or `'none'`:
315
+
316
+ ```typescript
317
+ // Only these functions are available
318
+ step.setFunctions(['lookup_account', 'get_balance']);
319
+
320
+ // No functions available
321
+ step.setFunctions('none');
322
+
323
+ // Same as 'none'
324
+ step.setFunctions([]);
325
+ ```
326
+
327
+ Functions not in the list are inactive during the step. Internal functions, such as `hangup_hook` and `gather_submit`, stay active, and so do `next_step` and `change_context`. Don't list those in `functions`.
328
+
329
+ ### Inheritance Between Steps
330
+
331
+ A step without `setFunctions()` emits no `functions` key. The platform then keeps the function set of the previous step, or of the previous context's last step. It changes the active set only when a step declares `functions`. On the first step of the conversation, with no earlier set to keep, every registered function is active.
332
+
333
+ A later step that leaves out `setFunctions()` therefore keeps the tools of the step before it. Call `setFunctions()` on every step whose tools differ from the previous step's.
334
+
335
+ The SDK checks every name in a `functions` list, and in each gather question's `functions`, against the agent's registered tools. `validate()` throws for a name that isn't a registered tool or one of the reserved native tools.
336
+
337
+ ---
338
+
339
+ ## End States
340
+
341
+ ### `setEnd()`
342
+
343
+ `setEnd(true)` marks the last step of the step flow:
344
+
345
+ ```typescript
346
+ const wrapUp = ctx.addStep('wrap_up');
347
+ wrapUp.setText('Thank the customer and ask if there is anything else.');
348
+ wrapUp.setEnd(true);
349
+ ```
350
+
351
+ It doesn't end the call. After the step runs, the platform leaves step mode: it clears the steps, `valid_steps` and `valid_contexts`, and stops offering `next_step`. The model then works from the base prompt and the context prompt. To end the call, have a tool return `FunctionResult.hangup()`.
352
+
353
+ ### `setSkipUserTurn()`
354
+
355
+ `setSkipUserTurn(true)` doesn't wait for the caller to speak when the step starts:
356
+
357
+ ```typescript
358
+ const transition = ctx.addStep('auto_transfer');
359
+ transition.setText('Transfer the call to the billing department.');
360
+ transition.setSkipUserTurn(true);
361
+ ```
362
+
363
+ ### `setSkipToNextStep()`
364
+
365
+ `setSkipToNextStep(true)` moves to the next step in order when this one completes:
366
+
367
+ ```typescript
368
+ const intro = ctx.addStep('intro');
369
+ intro.setText('Provide a brief introduction.');
370
+ intro.setSkipToNextStep(true);
371
+
372
+ const main = ctx.addStep('main');
373
+ main.setText('Now handle the main request.');
374
+ ```
375
+
376
+ ### `setHistory()`
377
+
378
+ `setHistory()` controls what the model still sees of earlier steps when this step starts. Nothing is removed from the call log:
379
+
380
+ ```typescript
381
+ step.setHistory('hide');
382
+ ```
383
+
384
+ The three modes are these:
385
+
386
+ - `keep`: hide nothing. Earlier steps' instructions and dialogue stay visible.
387
+ - `default`: hide earlier step instructions, and keep the dialogue. This is the behavior when `history` isn't set.
388
+ - `hide`: hide earlier instructions and the earlier dialogue. A `${step_history.*}` reference in this step's text brings back what you choose.
389
+
390
+ `Context.setHistory()` sets the default for every step in the context, and a step's own `setHistory()` overrides it. Any other value throws.
391
+
392
+ ---
393
+
394
+ ## GatherInfo
395
+
396
+ `GatherInfo` collects structured answers within a step, one question at a time. Each question has a key, an answer type, and optional confirmation and tools.
397
+
398
+ ### Setting Up GatherInfo
399
+
400
+ Call `setGatherInfo()` on a step, then add questions:
401
+
402
+ ```typescript
403
+ const step = ctx.addStep('collect_details');
404
+ step.setText('Collect the customer contact details.');
405
+
406
+ step.setGatherInfo({
407
+ outputKey: 'customer_info',
408
+ completionAction: 'next_step',
409
+ prompt: 'Explain that you need a few contact details.',
410
+ });
411
+
412
+ step.addGatherQuestion({
413
+ key: 'full_name',
414
+ question: 'What is your full name?',
415
+ confirm: true,
416
+ });
417
+
418
+ step.addGatherQuestion({
419
+ key: 'email',
420
+ question: 'What is your email address?',
421
+ confirm: true,
422
+ prompt: 'Ask the caller to spell the address.',
423
+ });
424
+
425
+ step.addGatherQuestion({
426
+ key: 'phone',
427
+ question: 'What is your phone number?',
428
+ functions: ['validate_phone'],
429
+ });
430
+
431
+ ctx.addStep('verify').setText('Read back ${customer_info} and confirm it.');
432
+ ```
433
+
434
+ `addGatherQuestion()` throws if `setGatherInfo()` wasn't called first.
435
+
436
+ While a question is asked, the platform deactivates the step's other functions. The model can call only `gather_submit`, which records the answer, and the tools listed in that question's `functions`. It can't move to another step or context until the gather completes. The answers go into the call's global data, under `outputKey` when it's set.
437
+
438
+ ### GatherInfo Options
439
+
440
+ `setGatherInfo()` takes these options:
441
+
442
+ | Option | Type | Default | Description |
443
+ |---|---|---|---|
444
+ | `outputKey` | `string` | none | Key in global data that holds the answers. Without it, each answer is stored at the top level. |
445
+ | `completionAction` | `string` | none | Where to go when every question is answered: `'next_step'` for the following step, or the name of a step in the same context. Without it, the step returns to its normal text. |
446
+ | `prompt` | `string` | none | Text the platform adds once, when the first question starts. |
447
+ | `isolated` | `boolean` | `false` | Default for every question. When `true`, a question is asked with the other questions and answers hidden from the model, so it must ask rather than work out the answer from an earlier one. The hidden turns stay in the call log. |
448
+
449
+ `validate()` throws when `completionAction` is `'next_step'` on the last step of a context, or names a step that isn't in the context.
450
+
451
+ ### GatherQuestion Options
452
+
453
+ `addGatherQuestion()` takes these options:
454
+
455
+ | Option | Type | Default | Description |
456
+ |---|---|---|---|
457
+ | `key` | `string` | (required) | Key the answer is stored under. Keys must be unique within a step. |
458
+ | `question` | `string` | (required) | The question for the model to ask. |
459
+ | `type` | `string` | `'string'` | JSON Schema type of the answer, such as `'string'`, `'integer'`, `'number'` or `'boolean'`. |
460
+ | `confirm` | `boolean` | `false` | The model must read the answer back and get the caller's confirmation before it submits. |
461
+ | `prompt` | `string` | none | Extra instruction for this question. |
462
+ | `functions` | `string[]` | none | Functions available during this question only. |
463
+ | `isolated` | `boolean` | inherits the gather's setting | `true` hides the other questions and answers while this one is asked. `false` keeps them visible, even in an isolated gather. |
464
+
465
+ ### GatherInfo Serialization
466
+
467
+ `GatherInfo.toDict()` produces the SWML `gather_info` object. For a gather with `isolated: true` whose `email` question sets `isolated: false`, the output is:
468
+
469
+ ```json
470
+ {
471
+ "questions": [
472
+ { "key": "full_name", "question": "What is your full name?", "confirm": true },
473
+ { "key": "email", "question": "What is your email address?", "confirm": true, "prompt": "Ask the caller to spell the address.", "isolated": false },
474
+ { "key": "phone", "question": "What is your phone number?", "functions": ["validate_phone"] }
475
+ ],
476
+ "prompt": "Explain that you need a few contact details.",
477
+ "output_key": "customer_info",
478
+ "completion_action": "next_step",
479
+ "isolated": true
480
+ }
481
+ ```
482
+
483
+ The SDK leaves `type` out when it's `'string'`, and `confirm` when it's `false`. A question's `isolated` appears whenever you set it, `false` included, so it can override the gather. `toDict()` throws for a gather with no questions.
484
+
485
+ ---
486
+
487
+ ## Context Settings
488
+
489
+ ### Prompt Configuration
490
+
491
+ A context can have its own prompt, which applies to all its steps. Like a step, it uses either raw text or POM sections. This is the raw-text form:
492
+
493
+ <!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
494
+ ```typescript
495
+ const ctx = cb.addContext('billing');
496
+ ctx.setPrompt('You are handling a billing inquiry. Be precise with numbers.');
497
+ ```
498
+
499
+ This is the POM form:
500
+
501
+ ```typescript
502
+ ctx.addSection('Role', 'You are a billing specialist for Acme Corp.');
503
+ ctx.addBullets('Guidelines', [
504
+ 'Always verify the account before discussing charges',
505
+ 'State every fee and credit on the account',
506
+ 'Offer payment plan options when appropriate',
507
+ ]);
508
+ ```
509
+
510
+ Raw text and POM sections can't be mixed in a context's prompt; the second kind throws.
511
+
512
+ ### System Prompt
513
+
514
+ `setSystemPrompt()` gives the context a new system prompt, used when the conversation enters it. This is the raw-text form:
515
+
516
+ ```typescript
517
+ ctx.setSystemPrompt('You are a helpful billing assistant. Be concise.');
518
+ ```
519
+
520
+ `addSystemSection()` and `addSystemBullets()` build it from POM sections:
521
+
522
+ ```typescript
523
+ ctx.addSystemSection('Identity', 'You are Acme Corp billing support.');
524
+ ctx.addSystemBullets('Rules', [
525
+ 'Never disclose internal pricing formulas',
526
+ 'Always confirm before processing refunds',
527
+ ]);
528
+ ```
529
+
530
+ Raw text and POM sections can't be mixed in a system prompt either.
531
+
532
+ ### Post-Prompt
533
+
534
+ `setPostPrompt()` replaces the agent's post-prompt while this context is active:
535
+
536
+ ```typescript
537
+ ctx.setPostPrompt('Summarize the billing changes made during the call.');
538
+ ```
539
+
540
+ ### User Prompt
541
+
542
+ `setUserPrompt()` sets a user message that the platform adds when the conversation enters this context:
543
+
544
+ ```typescript
545
+ ctx.setUserPrompt('I need help with my billing.');
546
+ ```
547
+
548
+ ---
549
+
550
+ ## Isolation and Reset
551
+
552
+ These settings control what happens to the conversation history when the conversation enters a context or step.
553
+
554
+ ### `setIsolated()`
555
+
556
+ `setIsolated(true)` clears the conversation history when the conversation enters the context through `change_context`. The model starts with the context's system prompt and step instructions only:
557
+
558
+ <!-- snippet: no-run illustrative fragment: references the assumed `cb` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
559
+ ```typescript
560
+ const secureCtx = cb.addContext('payment');
561
+ secureCtx.setIsolated(true);
562
+ ```
563
+
564
+ If the context also sets `consolidate` or `full_reset`, those apply instead of the wipe.
565
+
566
+ ### `setConsolidate()` (Context-Level)
567
+
568
+ `setConsolidate(true)` summarizes the earlier conversation into the new prompt when the conversation enters this context:
569
+
570
+ ```typescript
571
+ ctx.setConsolidate(true);
572
+ ```
573
+
574
+ ### `setFullReset()` (Context-Level)
575
+
576
+ `setFullReset(true)` replaces the system prompt completely when the conversation enters this context, instead of adding to it:
577
+
578
+ ```typescript
579
+ ctx.setFullReset(true);
580
+ ```
581
+
582
+ ### Step-Level Reset Options
583
+
584
+ A step can reset the conversation when the conversation enters it:
585
+
586
+ ```typescript
587
+ const step = ctx.addStep('fresh_start');
588
+
589
+ // Replace the system prompt when entering this step
590
+ step.setResetSystemPrompt('You are now handling a refund request.');
591
+
592
+ // Set the user prompt when entering this step
593
+ step.setResetUserPrompt('The customer wants a refund.');
594
+
595
+ // Consolidate conversation history at this step
596
+ step.setResetConsolidate(true);
597
+
598
+ // Perform a full conversation reset at this step
599
+ step.setResetFullReset(true);
600
+ ```
601
+
602
+ The SDK serializes the step-level reset options under a `reset` key:
603
+
604
+ ```json
605
+ {
606
+ "name": "fresh_start",
607
+ "text": "...",
608
+ "reset": {
609
+ "system_prompt": "You are now handling a refund request.",
610
+ "user_prompt": "The customer wants a refund.",
611
+ "consolidate": true,
612
+ "full_reset": true
613
+ }
614
+ }
615
+ ```
616
+
617
+ ---
618
+
619
+ ## Fillers
620
+
621
+ Fillers are phrases the platform plays when the conversation enters or leaves a context. Each set is keyed by language code.
622
+
623
+ ### Enter Fillers
624
+
625
+ Enter fillers play when the conversation enters the context:
626
+
627
+ ```typescript
628
+ // Set all enter fillers at once (keyed by language code)
629
+ ctx.setEnterFillers({
630
+ 'en-US': ['One moment.', 'Let me connect you.'],
631
+ 'es-ES': ['Un momento, por favor.'],
632
+ });
633
+
634
+ // Set the fillers for one language
635
+ ctx.addEnterFiller('en-US', [
636
+ 'One moment while I pull that up.',
637
+ 'Let me check on that for you.',
638
+ ]);
639
+ ```
640
+
641
+ `addEnterFiller()` replaces the list for that language.
642
+
643
+ ### Exit Fillers
644
+
645
+ Exit fillers play when the conversation leaves the context:
646
+
647
+ ```typescript
648
+ ctx.setExitFillers({
649
+ 'en-US': ['Alright, moving on.', 'Let me transfer you now.'],
650
+ });
651
+
652
+ ctx.addExitFiller('fr-FR', ['Un instant, s\'il vous plait.']);
653
+ ```
654
+
655
+ The SDK serializes them as `enter_fillers` and `exit_fillers`.
656
+
657
+ ---
658
+
659
+ ## Validation
660
+
661
+ `ContextBuilder.validate()` checks the structure before serialization. It throws when any of these fails:
662
+
663
+ 1. At least one context exists.
664
+ 2. A single context is named `'default'`.
665
+ 3. Every context has at least one step.
666
+ 4. Every `initial_step` names a step in its context.
667
+ 5. Every context in a context's or step's `valid_contexts` exists.
668
+ 6. Every step in a step's `valid_steps` exists in the context, or is `next`.
669
+ 7. Gather question keys are unique within a step.
670
+ 8. Every gather `completion_action` is `next_step` on a step that has a following step, or names a step in the context.
671
+ 9. No registered tool is named `next_step`, `change_context` or `gather_submit`.
672
+ 10. Every name in a step's or question's `functions` is a registered tool or a reserved native tool.
673
+
674
+ The last two checks run when the builder is attached to an agent, which `agent.defineContexts()` does. `toDict()` calls `validate()`, and the agent calls `toDict()` when it renders the SWML:
675
+
676
+ ```typescript
677
+ const cb = new ContextBuilder();
678
+ const ctx = cb.addContext('default');
679
+ ctx.addStep('welcome').setText('Greet the caller.');
680
+
681
+ // Explicit validation
682
+ cb.validate(); // throws if invalid
683
+
684
+ // Implicit validation on serialization
685
+ const swml = cb.toDict(); // calls validate() internally
686
+ ```
687
+
688
+ ### Common Validation Errors
689
+
690
+ These are the errors you're most likely to see:
691
+
692
+ | Error | Cause |
693
+ |---|---|
694
+ | `At least one context must be defined` | No contexts were added |
695
+ | `When using a single context, it must be named 'default'` | One context exists but isn't named `'default'` |
696
+ | `Context 'X' must have at least one step` | A context has no steps |
697
+ | `Context 'X' references unknown context 'Y'` | A context's `setValidContexts()` names a context that doesn't exist |
698
+ | `Step 'X' in context 'C' references unknown step 'Y'` | `setValidSteps()` names a step that isn't in the context |
699
+ | `Step 'X' in context 'C' references unknown context 'Y'` | A step's `setValidContexts()` names a context that doesn't exist |
700
+ | `Context/step 'functions' whitelist references unknown SWAIG function(s): ...` | A `functions` list names a tool that isn't registered |
701
+ | `Step 'X' has no text or POM sections defined` | A step has neither `setText()` nor `addSection()`/`addBullets()`; thrown by `toDict()` |
702
+
703
+ ---
704
+
705
+ ## Real-World Example
706
+
707
+ This customer service agent has three contexts. It starts in `default`, which greets and routes the caller, then moves to `troubleshooting` or `resolution`:
708
+
709
+ <!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
710
+ ```typescript
711
+ import { AgentBase } from '@signalwire/sdk';
712
+
713
+ const agent = new AgentBase({ name: 'customer-service' });
714
+ agent.setPromptText('You are a customer service agent for TechCo.');
715
+
716
+ // Define the tools
717
+ agent.defineTool({
718
+ name: 'lookup_account',
719
+ description: 'Look up a customer account by account number.',
720
+ parameters: {
721
+ account_number: { type: 'string', description: 'The customer account number.' },
722
+ },
723
+ handler: async (args) => {
724
+ // ... account lookup logic
725
+ return { response: `Account found: ${args.account_number}` };
726
+ },
727
+ });
728
+
729
+ agent.defineTool({
730
+ name: 'create_ticket',
731
+ description: 'Create a support ticket for the customer.',
732
+ parameters: {
733
+ issue: { type: 'string', description: 'Description of the issue.' },
734
+ priority: { type: 'string', description: 'Ticket priority: low, medium, high.' },
735
+ },
736
+ handler: async (args) => {
737
+ return { response: `Ticket created: ${args.issue} (${args.priority})` };
738
+ },
739
+ });
740
+
741
+ agent.defineTool({
742
+ name: 'process_refund',
743
+ description: 'Process a refund for a customer.',
744
+ parameters: {
745
+ amount: { type: 'number', description: 'Refund amount in dollars.' },
746
+ reason: { type: 'string', description: 'Reason for the refund.' },
747
+ },
748
+ handler: async (args) => {
749
+ return { response: `Refund of $${args.amount} processed.` };
750
+ },
751
+ });
752
+
753
+ // Build the conversation flow
754
+ const cb = agent.defineContexts();
755
+
756
+ // Context 1: greeting and routing (the starting context)
757
+ const greeting = cb.addContext('default');
758
+ greeting.addEnterFiller('en-US', ['Welcome. Let me help you today.']);
759
+ greeting.setValidContexts(['troubleshooting', 'resolution']);
760
+
761
+ greeting.addStep('welcome', {
762
+ task: 'Greet the customer warmly and ask how you can help today.',
763
+ criteria: 'The customer has stated the nature of their issue.',
764
+ functions: 'none',
765
+ validSteps: ['identify'],
766
+ });
767
+
768
+ greeting.addStep('identify', {
769
+ task: 'Verify the customer identity by asking for their account number.',
770
+ criteria: 'Account has been looked up and verified.',
771
+ functions: ['lookup_account'],
772
+ validSteps: ['route'],
773
+ });
774
+
775
+ const route = greeting.addStep('route');
776
+ route.addSection('Task', 'Determine the appropriate department for the customer issue.');
777
+ route.addBullets('Routing Rules', [
778
+ 'Technical issues (connectivity, hardware, software): troubleshooting context',
779
+ 'Billing, refunds, or account changes: resolution context',
780
+ 'If unclear, ask a clarifying question before routing',
781
+ ]);
782
+ route.setStepCriteria('The issue category has been determined.');
783
+ route.setValidContexts(['troubleshooting', 'resolution']);
784
+ route.setFunctions('none');
785
+
786
+ // Context 2: troubleshooting
787
+ const troubleshooting = cb.addContext('troubleshooting');
788
+ troubleshooting.setConsolidate(true);
789
+ troubleshooting.addEnterFiller('en-US', [
790
+ 'Let me look into that technical issue for you.',
791
+ 'One moment while I pull up our troubleshooting guide.',
792
+ ]);
793
+ troubleshooting.setExitFillers({
794
+ 'en-US': ['Let me get you to the right place.'],
795
+ });
796
+ troubleshooting.setValidContexts(['resolution']);
797
+
798
+ troubleshooting.addSystemSection('Role', 'You are a technical support specialist.');
799
+ troubleshooting.addSystemBullets('Approach', [
800
+ 'Start with the least disruptive fix first',
801
+ 'Ask the customer to confirm each step',
802
+ 'Escalate to a ticket if three attempts fail',
803
+ ]);
804
+
805
+ const diagnose = troubleshooting.addStep('diagnose');
806
+ diagnose.setText('Ask the customer to describe their technical issue in detail.');
807
+ diagnose.setStepCriteria('The specific technical problem is understood.');
808
+ diagnose.setFunctions('none');
809
+ diagnose.setValidSteps(['guided_fix', 'escalate']);
810
+
811
+ const guidedFix = troubleshooting.addStep('guided_fix');
812
+ guidedFix.addSection('Task', 'Walk the customer through step-by-step troubleshooting.');
813
+ guidedFix.addBullets('Steps', [
814
+ 'Have the customer restart their device',
815
+ 'Check network connectivity',
816
+ 'Verify software is up to date',
817
+ 'Try clearing the cache',
818
+ ]);
819
+ guidedFix.setStepCriteria('The issue is resolved OR three troubleshooting steps have been attempted.');
820
+ guidedFix.setFunctions('none');
821
+ guidedFix.setValidSteps(['escalate']);
822
+ guidedFix.setValidContexts(['resolution']);
823
+
824
+ const escalate = troubleshooting.addStep('escalate');
825
+ escalate.addSection('Task', 'Create a support ticket for the unresolved issue.');
826
+ escalate.setStepCriteria('A support ticket has been created.');
827
+ escalate.setFunctions(['create_ticket']);
828
+ escalate.setValidContexts(['resolution']);
829
+
830
+ // Context 3: resolution
831
+ const resolution = cb.addContext('resolution');
832
+ resolution.setIsolated(true);
833
+ resolution.addEnterFiller('en-US', ['Let me wrap things up for you.']);
834
+
835
+ const summarize = resolution.addStep('summarize');
836
+ summarize.setText('Summarize what was accomplished during this call.');
837
+ summarize.setStepCriteria('A summary has been provided to the customer.');
838
+ summarize.setFunctions('none');
839
+ summarize.setValidSteps(['refund_check', 'goodbye']);
840
+
841
+ const refundCheck = resolution.addStep('refund_check');
842
+ refundCheck.addSection('Task', 'Determine if a refund or credit is appropriate.');
843
+ refundCheck.addBullets('Policy', [
844
+ 'Refunds up to $50 can be issued immediately',
845
+ 'Refunds over $50 require manager approval, so create a ticket instead',
846
+ 'Always confirm the refund amount with the customer before processing',
847
+ ]);
848
+ refundCheck.setStepCriteria('Refund has been processed or determined not applicable.');
849
+ refundCheck.setFunctions(['process_refund', 'create_ticket']);
850
+ refundCheck.setValidSteps(['goodbye']);
851
+
852
+ // Gather customer satisfaction info before leaving step mode
853
+ const goodbye = resolution.addStep('goodbye');
854
+ goodbye.setText('Thank the customer and collect feedback.');
855
+ goodbye.setFunctions('none');
856
+ goodbye.setGatherInfo({
857
+ outputKey: 'satisfaction',
858
+ prompt: 'Ask the caller for brief feedback before the call ends.',
859
+ });
860
+ goodbye.addGatherQuestion({
861
+ key: 'rating',
862
+ question: 'On a scale of 1-5, how would you rate your experience today?',
863
+ type: 'integer',
864
+ confirm: true,
865
+ });
866
+ goodbye.addGatherQuestion({
867
+ key: 'comments',
868
+ question: 'Do you have any additional comments or suggestions?',
869
+ });
870
+ goodbye.setEnd(true);
871
+
872
+ // Start the server
873
+ agent.serve();
874
+ ```
875
+
876
+ ### How This Flow Works
877
+
878
+ The flow runs in three stages:
879
+
880
+ 1. The conversation begins in the `default` context. The model greets the customer, looks up the account, and routes the call.
881
+ 2. Technical issues go to the `troubleshooting` context, which consolidates the earlier conversation. The model walks through diagnostic steps, and can escalate by creating a ticket.
882
+ 3. Every path ends in the `resolution` context, which is isolated, so its history starts fresh. It summarizes the call, can process a refund, and collects feedback before leaving step mode.
883
+
884
+ `setValidContexts()` and `setValidSteps()` limit where each step can go. Each step calls `setFunctions()`, so no step inherits the tools of the step before it. `process_refund`, for example, is available only in the `refund_check` step. `setEnd(true)` on `goodbye` doesn't hang up; add a tool that returns `FunctionResult.hangup()` for that.