@signalwire/sdk 2.0.5 → 3.6.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 (659) hide show
  1. package/CHANGELOG.md +821 -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 +510 -126
  6. package/dist/AgentBase.js +1581 -455
  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 +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -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 +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  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 +18 -0
  42. package/dist/PomBuilder.js +53 -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 +22 -1
  48. package/dist/PromptManager.js +28 -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 +169 -59
  58. package/dist/SWMLService.js +456 -129
  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 +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,641 @@
1
+ /**
2
+ * Extending agents (Lesson 5)
3
+ *
4
+ * A custom skill, per-call and persistent state, multi-step workflows,
5
+ * external services, personas, prompt techniques and resilience helpers.
6
+ * Persistent state uses node:sqlite, which needs Node.js 22.13 or later
7
+ * (22.5 through 22.12 need the --experimental-sqlite flag).
8
+ *
9
+ * Run: npx tsx tutorial/multi_agents/extending_agents.ts
10
+ */
11
+
12
+ import { DatabaseSync } from 'node:sqlite';
13
+ import { fileURLToPath, pathToFileURL } from 'node:url';
14
+ import { Hono } from 'hono';
15
+ import {
16
+ AgentBase,
17
+ FunctionResult,
18
+ NativeVectorSearchSkill,
19
+ SkillBase,
20
+ getLogger,
21
+ type ParameterSchemaEntry,
22
+ type SkillPromptSection,
23
+ type SkillToolDefinition,
24
+ } from '@signalwire/sdk';
25
+ import { loadKnowledge } from './knowledge.js';
26
+
27
+ const log = getLogger('extending_agents');
28
+
29
+ export const agent = new AgentBase({ name: 'Extended Agent', route: '/' });
30
+
31
+ // region: weather-skill
32
+ /** Current weather and forecasts from WeatherAPI.com. */
33
+ export class WeatherSkill extends SkillBase {
34
+ static override SKILL_NAME = 'weather_lookup';
35
+ static override SKILL_DESCRIPTION = 'Provides weather information and forecasts';
36
+ static override SKILL_VERSION = '1.0.0';
37
+ static override REQUIRED_ENV_VARS = ['WEATHER_API_KEY'] as const;
38
+
39
+ private apiKey = '';
40
+ private baseUrl = '';
41
+
42
+ static override getParameterSchema(): Record<string, ParameterSchemaEntry> {
43
+ return {
44
+ ...super.getParameterSchema(),
45
+ base_url: {
46
+ type: 'string',
47
+ description: 'Base URL of the weather API',
48
+ default: 'https://api.weatherapi.com/v1',
49
+ required: false,
50
+ },
51
+ };
52
+ }
53
+
54
+ // Runs once when the skill is added. Returning false refuses the skill.
55
+ override async setup(): Promise<boolean> {
56
+ this.apiKey = process.env['WEATHER_API_KEY'] ?? '';
57
+ this.baseUrl = this.getConfig<string>('base_url', 'https://api.weatherapi.com/v1');
58
+ return this.apiKey !== '';
59
+ }
60
+
61
+ /** GET a path of the weather API, or null when it fails. */
62
+ private async get(path: string, params: Record<string, string>): Promise<unknown> {
63
+ const query = new URLSearchParams({ key: this.apiKey, ...params });
64
+ const res = await fetch(`${this.baseUrl}${path}?${query}`, {
65
+ signal: AbortSignal.timeout(5000),
66
+ });
67
+ return res.ok ? res.json() : null;
68
+ }
69
+
70
+ override getTools(): SkillToolDefinition[] {
71
+ return [
72
+ {
73
+ name: 'get_weather',
74
+ description: 'Get current weather for a location',
75
+ parameters: {
76
+ location: { type: 'string', description: 'City or location name' },
77
+ },
78
+ required: ['location'],
79
+ handler: async (args) => {
80
+ const location = String(args['location']);
81
+ const data = (await this.get('/current.json', { q: location })) as {
82
+ current: { temp_f: number; condition: { text: string } };
83
+ } | null;
84
+ if (!data) return new FunctionResult(`Could not get weather for ${location}`);
85
+ return new FunctionResult(
86
+ `Current weather in ${location}: ${data.current.temp_f}°F, ${data.current.condition.text}`,
87
+ );
88
+ },
89
+ },
90
+ {
91
+ name: 'get_forecast',
92
+ description: 'Get weather forecast',
93
+ parameters: {
94
+ location: { type: 'string', description: 'City or location name' },
95
+ days: { type: 'integer', description: 'Number of days to forecast (default 3)' },
96
+ },
97
+ required: ['location'],
98
+ handler: async (args) => {
99
+ const location = String(args['location']);
100
+ const days = String(args['days'] ?? 3);
101
+ const data = (await this.get('/forecast.json', { q: location, days })) as {
102
+ forecast: {
103
+ forecastday: {
104
+ date: string;
105
+ day: { maxtemp_f: number; mintemp_f: number; condition: { text: string } };
106
+ }[];
107
+ };
108
+ } | null;
109
+ if (!data) return new FunctionResult(`Could not get a forecast for ${location}`);
110
+ const lines = data.forecast.forecastday.map(
111
+ (d) => `${d.date}: ${d.day.condition.text}, ${d.day.mintemp_f}-${d.day.maxtemp_f}°F`,
112
+ );
113
+ return new FunctionResult(`Forecast for ${location}:\n${lines.join('\n')}`);
114
+ },
115
+ },
116
+ ];
117
+ }
118
+
119
+ protected override _getPromptSections(): SkillPromptSection[] {
120
+ return [
121
+ {
122
+ title: 'Weather',
123
+ body: 'You can look up current weather and forecasts.',
124
+ bullets: ['Use get_weather for current conditions, and get_forecast for the coming days'],
125
+ },
126
+ ];
127
+ }
128
+ }
129
+ // endregion: weather-skill
130
+
131
+ // region: use-skill
132
+ // The skill refuses to load without WEATHER_API_KEY, so add it only when the key is set
133
+ if (process.env['WEATHER_API_KEY']) {
134
+ await agent.addSkill(new WeatherSkill());
135
+ } else {
136
+ log.warn('WEATHER_API_KEY not set; the weather tools are not available');
137
+ }
138
+ // endregion: use-skill
139
+
140
+ // region: multiple-instances
141
+ // Two instances of one skill, told apart by tool_name
142
+ const here = (name: string) => fileURLToPath(new URL(`./${name}`, import.meta.url));
143
+
144
+ await agent.addSkill(
145
+ new NativeVectorSearchSkill({
146
+ tool_name: 'search_products',
147
+ description: 'Search product and build information',
148
+ documents: loadKnowledge(here('sales_knowledge.md')),
149
+ count: 3,
150
+ }),
151
+ );
152
+ await agent.addSkill(
153
+ new NativeVectorSearchSkill({
154
+ tool_name: 'search_troubleshooting',
155
+ description: 'Search troubleshooting guides',
156
+ documents: loadKnowledge(here('support_knowledge.md')),
157
+ count: 3,
158
+ }),
159
+ );
160
+ // endregion: multiple-instances
161
+
162
+ // region: call-state
163
+ // Preferences for each call, keyed by the call ID SignalWire sends with every
164
+ // function call. This lives in one process's memory: a restart loses it.
165
+ const preferences = new Map<string, Map<string, string>>();
166
+
167
+ agent.defineTool({
168
+ name: 'remember_preference',
169
+ description: 'Remember a preference the customer states',
170
+ parameters: {
171
+ key: { type: 'string', description: 'Preference name, such as budget or color' },
172
+ value: { type: 'string', description: 'Preference value' },
173
+ },
174
+ required: ['key', 'value'],
175
+ handler: ({ key, value }, rawData) => {
176
+ const callId = rawData.call_id ?? 'unknown';
177
+ if (!preferences.has(callId)) preferences.set(callId, new Map());
178
+ preferences.get(callId)!.set(key, value);
179
+ return new FunctionResult(`I'll remember that your ${key} is ${value}`);
180
+ },
181
+ });
182
+
183
+ agent.defineTool({
184
+ name: 'recall_preference',
185
+ description: 'Recall a preference the customer stated earlier in this call',
186
+ parameters: {
187
+ key: { type: 'string', description: 'Preference name to recall' },
188
+ },
189
+ required: ['key'],
190
+ handler: ({ key }, rawData) => {
191
+ const value = preferences.get(rawData.call_id ?? 'unknown')?.get(key);
192
+ return new FunctionResult(
193
+ value === undefined ? `I don't have your ${key} on record` : `Your ${key} is ${value}`,
194
+ );
195
+ },
196
+ });
197
+ // endregion: call-state
198
+
199
+ // region: persistent-state
200
+ // Interactions that outlive the process, in a SQLite file
201
+ const db = new DatabaseSync(process.env['INTERACTIONS_DB'] ?? 'interactions.db');
202
+ db.exec(`CREATE TABLE IF NOT EXISTS interactions (
203
+ customer_id TEXT NOT NULL,
204
+ type TEXT NOT NULL,
205
+ details TEXT NOT NULL,
206
+ timestamp TEXT NOT NULL
207
+ )`);
208
+
209
+ agent.defineTool({
210
+ name: 'save_interaction',
211
+ description: 'Save an interaction to the customer history',
212
+ parameters: {
213
+ customer_id: { type: 'string', description: 'Customer identifier' },
214
+ interaction_type: { type: 'string', description: 'Type of interaction' },
215
+ details: { type: 'string', description: 'Interaction details' },
216
+ },
217
+ required: ['customer_id', 'interaction_type', 'details'],
218
+ handler: ({ customer_id, interaction_type, details }) => {
219
+ db.prepare('INSERT INTO interactions VALUES (?, ?, ?, ?)').run(
220
+ customer_id,
221
+ interaction_type,
222
+ details,
223
+ new Date().toISOString(),
224
+ );
225
+ return new FunctionResult('Interaction saved successfully');
226
+ },
227
+ });
228
+
229
+ agent.defineTool({
230
+ name: 'get_history',
231
+ description: 'Get customer interaction history',
232
+ parameters: {
233
+ customer_id: { type: 'string', description: 'Customer identifier' },
234
+ limit: { type: 'integer', description: 'Max number of records (default 5)' },
235
+ },
236
+ required: ['customer_id'],
237
+ handler: ({ customer_id, limit = 5 }) => {
238
+ const rows = db
239
+ .prepare(
240
+ `SELECT type, details, timestamp FROM interactions
241
+ WHERE customer_id = ? ORDER BY timestamp DESC LIMIT ?`,
242
+ )
243
+ .all(customer_id, limit) as { type: string; details: string; timestamp: string }[];
244
+ if (rows.length === 0) return new FunctionResult('No previous interactions found');
245
+ const history = rows.map((r) => `- ${r.type} on ${r.timestamp}: ${r.details}`).join('\n');
246
+ return new FunctionResult(`Previous interactions:\n${history}`);
247
+ },
248
+ });
249
+ // endregion: persistent-state
250
+
251
+ // region: global-data
252
+ agent.defineTool({
253
+ name: 'set_customer_data',
254
+ description: 'Store a customer detail for the rest of the call',
255
+ parameters: {
256
+ key: { type: 'string', description: 'Detail name, such as name or email' },
257
+ value: { type: 'string', description: 'Detail value' },
258
+ },
259
+ required: ['key', 'value'],
260
+ handler: ({ key, value }) =>
261
+ new FunctionResult(`Stored ${key}`).updateGlobalData({ [`customer_${key}`]: value }),
262
+ });
263
+
264
+ // A later function call receives the global data with its request
265
+ agent.defineTool({
266
+ name: 'get_customer_data',
267
+ description: 'Read a customer detail stored earlier in the call',
268
+ parameters: {
269
+ key: { type: 'string', description: 'Detail name' },
270
+ },
271
+ required: ['key'],
272
+ handler: ({ key }, rawData) => {
273
+ const value = rawData.global_data?.[`customer_${key}`];
274
+ return new FunctionResult(value === undefined ? `No ${key} stored` : `${key}: ${value}`);
275
+ },
276
+ });
277
+ // endregion: global-data
278
+
279
+ // region: workflow
280
+ // An order built over several function calls, one per call ID
281
+ interface Order {
282
+ state: 'awaiting_items' | 'ready_to_confirm';
283
+ items: { name: string; quantity: number; price: number }[];
284
+ }
285
+ const orders = new Map<string, Order>();
286
+ const PRICES: Record<string, number> = { 'RTX 4070': 549, 'Ryzen 7 7700X': 299, '32GB DDR5': 99 };
287
+
288
+ agent.defineTool({
289
+ name: 'start_order',
290
+ description: 'Start a new order',
291
+ handler: (_args, rawData) => {
292
+ orders.set(rawData.call_id ?? 'unknown', { state: 'awaiting_items', items: [] });
293
+ return new FunctionResult('Order started. Ask the customer which items they want.');
294
+ },
295
+ });
296
+
297
+ agent.defineTool({
298
+ name: 'add_item',
299
+ description: 'Add an item to the current order',
300
+ parameters: {
301
+ item: { type: 'string', enum: Object.keys(PRICES), description: 'Item name' },
302
+ quantity: { type: 'integer', description: 'Quantity (default 1)' },
303
+ },
304
+ required: ['item'],
305
+ handler: ({ item, quantity = 1 }, rawData) => {
306
+ const order = orders.get(rawData.call_id ?? 'unknown');
307
+ if (!order) return new FunctionResult('No active order. Start a new order first.');
308
+ order.items.push({ name: item, quantity, price: PRICES[item] ?? 0 });
309
+ order.state = 'ready_to_confirm';
310
+ const list = order.items.map((i) => `${i.quantity}x ${i.name}`).join(', ');
311
+ return new FunctionResult(`Added ${quantity}x ${item}. Current order: ${list}.`);
312
+ },
313
+ });
314
+
315
+ agent.defineTool({
316
+ name: 'confirm_order',
317
+ description: 'Confirm and submit the current order',
318
+ handler: (_args, rawData) => {
319
+ const callId = rawData.call_id ?? 'unknown';
320
+ const order = orders.get(callId);
321
+ if (!order) return new FunctionResult('No active order');
322
+ if (order.state !== 'ready_to_confirm') {
323
+ return new FunctionResult('Add items before confirming');
324
+ }
325
+ const total = order.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
326
+ orders.delete(callId);
327
+ return new FunctionResult(`Order confirmed. Total: $${total.toFixed(2)}`);
328
+ },
329
+ });
330
+ // endregion: workflow
331
+
332
+ // region: conditional
333
+ agent.promptAddSection('Conditional Responses', {
334
+ body: 'Adapt your behavior based on context:',
335
+ bullets: [
336
+ 'For new customers: Be extra welcoming and explain our services',
337
+ 'For VIP customers: Acknowledge their status and offer premium options',
338
+ 'For support issues: Show empathy and urgency',
339
+ 'For sales inquiries: Be enthusiastic and helpful',
340
+ ],
341
+ });
342
+
343
+ const STATUSES: Record<string, string> = { C100: 'platinum', C200: 'standard' };
344
+
345
+ agent.defineTool({
346
+ name: 'check_customer_status',
347
+ description: 'Check customer status',
348
+ parameters: {
349
+ customer_id: { type: 'string', description: 'Customer identifier' },
350
+ },
351
+ required: ['customer_id'],
352
+ handler: ({ customer_id }) => {
353
+ const status = STATUSES[customer_id] ?? 'new';
354
+ // The response tells the model the status, and the Conditional Responses
355
+ // section says what to do with it. Global data keeps it for later tools.
356
+ return new FunctionResult(`Customer status: ${status}`).updateGlobalData({
357
+ customer_status: status,
358
+ is_vip: status === 'platinum',
359
+ });
360
+ },
361
+ });
362
+ // endregion: conditional
363
+
364
+ // region: rest-api
365
+ agent.defineTool({
366
+ name: 'check_availability',
367
+ description: 'Check product availability in the inventory service',
368
+ parameters: {
369
+ product_sku: { type: 'string', description: 'Product SKU to check' },
370
+ },
371
+ required: ['product_sku'],
372
+ handler: async ({ product_sku }) => {
373
+ const base = process.env['INVENTORY_API_URL'];
374
+ const key = process.env['INVENTORY_API_KEY'];
375
+ if (!base || !key) return new FunctionResult('The inventory service is not configured.');
376
+ try {
377
+ const res = await fetch(`${base}/inventory/${encodeURIComponent(product_sku)}`, {
378
+ headers: { Authorization: `Bearer ${key}` },
379
+ signal: AbortSignal.timeout(5000),
380
+ });
381
+ if (!res.ok) return new FunctionResult('Unable to check availability');
382
+ const data = (await res.json()) as {
383
+ in_stock: boolean;
384
+ quantity: number;
385
+ restock_date?: string;
386
+ };
387
+ return new FunctionResult(
388
+ data.in_stock
389
+ ? `Product ${product_sku} is in stock. Available quantity: ${data.quantity}`
390
+ : `Product ${product_sku} is out of stock. Expected restock: ${data.restock_date ?? 'unknown'}`,
391
+ );
392
+ } catch (err) {
393
+ log.error('inventory request failed', { error: String(err) });
394
+ return new FunctionResult('Unable to check availability');
395
+ }
396
+ },
397
+ });
398
+ // endregion: rest-api
399
+
400
+ // region: webhook
401
+ // Order updates from another service, on a route beside the agent's.
402
+ // A mounted app isn't behind the agent's basic auth: check a secret of your own.
403
+ const webhooks = new Hono();
404
+ webhooks.post('/order_update', async (c) => {
405
+ const secret = process.env['ORDER_WEBHOOK_SECRET'];
406
+ if (!secret || c.req.header('x-webhook-secret') !== secret) {
407
+ return c.json({ error: 'forbidden' }, 403);
408
+ }
409
+ const { order_id, status } = await c.req.json<{ order_id: string; status: string }>();
410
+ // Answer now, and do the work after the response is sent
411
+ setImmediate(() => processOrderUpdate(order_id, status));
412
+ return c.json({ status: 'received' });
413
+ });
414
+ agent.mount(webhooks, { prefix: '/webhook' });
415
+
416
+ export const orderUpdates: { order_id: string; status: string }[] = [];
417
+ function processOrderUpdate(orderId: string, status: string): void {
418
+ log.info('order updated', { order_id: orderId, status });
419
+ orderUpdates.push({ order_id: orderId, status });
420
+ }
421
+ // endregion: webhook
422
+
423
+ // region: work-queue
424
+ // Work that should happen outside the call: a function queues it and returns,
425
+ // and a worker drains the queue. A deployment with several processes uses a
426
+ // shared queue (Redis, SQS) the same way.
427
+ interface Task {
428
+ type: string;
429
+ data: string;
430
+ timestamp: string;
431
+ }
432
+ const taskQueue: Task[] = [];
433
+ export const completedTasks: Task[] = [];
434
+
435
+ agent.defineTool({
436
+ name: 'queue_task',
437
+ description: 'Queue a follow-up task, such as sending a quote by email',
438
+ parameters: {
439
+ task_type: { type: 'string', description: 'Type of task to queue' },
440
+ data: { type: 'string', description: 'Task details' },
441
+ },
442
+ required: ['task_type', 'data'],
443
+ handler: ({ task_type, data }) => {
444
+ taskQueue.push({ type: task_type, data, timestamp: new Date().toISOString() });
445
+ return new FunctionResult('Task queued for processing');
446
+ },
447
+ });
448
+
449
+ const worker = setInterval(() => {
450
+ const task = taskQueue.shift();
451
+ if (!task) return;
452
+ try {
453
+ completedTasks.push(task); // do the real work here
454
+ } catch (err) {
455
+ log.error('task failed', { type: task.type, error: String(err) });
456
+ }
457
+ }, 1000);
458
+ worker.unref(); // the worker alone doesn't keep the process running
459
+ // endregion: work-queue
460
+
461
+ // region: personas
462
+ // A persona per request, chosen by a query parameter: ?persona=professional
463
+ const PERSONAS = {
464
+ professional: { voice: 'rime.cove', style: 'formal and precise', pace: 'measured' },
465
+ friendly: { voice: 'rime.marsh', style: 'warm and conversational', pace: 'relaxed' },
466
+ energetic: { voice: 'rime.spore', style: 'enthusiastic and upbeat', pace: 'quick' },
467
+ };
468
+ type PersonaName = keyof typeof PERSONAS;
469
+
470
+ agent.addPerCallConfig((query, _body, _headers, copy) => {
471
+ const name: PersonaName =
472
+ query['persona'] && query['persona'] in PERSONAS
473
+ ? (query['persona'] as PersonaName)
474
+ : 'friendly';
475
+ const persona = PERSONAS[name];
476
+ copy.setLanguages([{ name: 'English', code: 'en-US', voice: persona.voice }]);
477
+ copy.promptAddSection('Voice Style', {
478
+ body: `Speak in a ${persona.style} manner at a ${persona.pace} pace`,
479
+ });
480
+ });
481
+ // endregion: personas
482
+
483
+ // region: multilingual
484
+ export const multilingual = new AgentBase({ name: 'Multilingual Agent', route: '/multilingual' });
485
+
486
+ multilingual.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.marsh' });
487
+ multilingual.addLanguage({ name: 'Spanish', code: 'es-MX', voice: 'rime.marsh' });
488
+ multilingual.addLanguage({ name: 'French', code: 'fr-FR', voice: 'rime.marsh' });
489
+
490
+ multilingual.promptAddSection('Language Instructions', {
491
+ body: 'Adapt your communication style to the selected language:',
492
+ bullets: [
493
+ 'English: Professional but friendly American business style',
494
+ 'Spanish: Warm and personable Latin American style',
495
+ 'French: Polite and formal French business etiquette',
496
+ ],
497
+ });
498
+ // endregion: multilingual
499
+
500
+ // region: reasoning
501
+ agent.promptAddSection('Reasoning Framework', {
502
+ body: 'Follow this structured approach for complex requests:',
503
+ bullets: [
504
+ 'Understand: Clarify what the customer is asking for',
505
+ 'Analyze: Break down the request into components',
506
+ 'Plan: Determine the best approach to help',
507
+ 'Execute: Take action using available tools',
508
+ 'Verify: Confirm the solution meets their needs',
509
+ ],
510
+ numberedBullets: true,
511
+ });
512
+
513
+ agent.promptAddSection('Decision Criteria', {
514
+ body: 'When making recommendations, consider:',
515
+ bullets: [
516
+ "Customer's stated requirements",
517
+ 'Budget constraints',
518
+ 'Technical compatibility',
519
+ 'Future scalability',
520
+ 'Best value proposition',
521
+ ],
522
+ });
523
+ // endregion: reasoning
524
+
525
+ // region: switch-context
526
+ agent.defineTool({
527
+ name: 'set_explanation_mode',
528
+ description: 'Change how the agent explains things for the rest of the call',
529
+ parameters: {
530
+ mode: {
531
+ type: 'string',
532
+ enum: ['technical', 'simple', 'sales'],
533
+ description: 'Explanation mode',
534
+ },
535
+ },
536
+ required: ['mode'],
537
+ handler: ({ mode }) => {
538
+ const base = 'You are a helpful assistant for our PC products.';
539
+ const modes = {
540
+ technical: 'Provide detailed technical explanations.',
541
+ simple: 'Explain everything in simple, non-technical terms.',
542
+ sales: 'Focus on benefits and value proposition.',
543
+ };
544
+ // switchContext replaces the whole system prompt, so pass all of it
545
+ return new FunctionResult(`Switching to ${mode} mode`).switchContext({
546
+ systemPrompt: `${base} ${modes[mode]}`,
547
+ });
548
+ },
549
+ });
550
+ // endregion: switch-context
551
+
552
+ // region: retry
553
+ /** Run `fn`, retrying a failure with a delay that doubles each time. */
554
+ export async function retryWithBackoff<T>(
555
+ fn: () => Promise<T>,
556
+ maxAttempts = 3,
557
+ initialDelayMs = 1000,
558
+ ): Promise<T> {
559
+ let delay = initialDelayMs;
560
+ for (let attempt = 1; ; attempt++) {
561
+ try {
562
+ return await fn();
563
+ } catch (err) {
564
+ if (attempt >= maxAttempts) throw err;
565
+ log.warn('attempt failed, retrying', { attempt, delay_ms: delay, error: String(err) });
566
+ await new Promise((resolve) => setTimeout(resolve, delay));
567
+ delay *= 2;
568
+ }
569
+ }
570
+ }
571
+ // endregion: retry
572
+
573
+ // region: circuit-breaker
574
+ /** Stops calling a failing dependency until `resetTimeoutMs` has passed. */
575
+ export class CircuitBreaker {
576
+ private failureCount = 0;
577
+ private openedAt: number | null = null;
578
+
579
+ constructor(
580
+ private readonly failureThreshold = 5,
581
+ private readonly resetTimeoutMs = 60_000,
582
+ ) {}
583
+
584
+ async call<T>(fn: () => Promise<T>): Promise<T> {
585
+ if (this.openedAt !== null) {
586
+ if (Date.now() - this.openedAt < this.resetTimeoutMs) {
587
+ throw new Error('Circuit breaker is open');
588
+ }
589
+ this.openedAt = null; // try the dependency again
590
+ this.failureCount = 0;
591
+ }
592
+ try {
593
+ const result = await fn();
594
+ this.failureCount = 0;
595
+ return result;
596
+ } catch (err) {
597
+ this.failureCount += 1;
598
+ if (this.failureCount >= this.failureThreshold) {
599
+ this.openedAt = Date.now();
600
+ log.error('circuit breaker opened after repeated failures');
601
+ }
602
+ throw err;
603
+ }
604
+ }
605
+ }
606
+ // endregion: circuit-breaker
607
+
608
+ // region: factory
609
+ /** The kinds of agent the factory can build, and what makes each one different. */
610
+ const AGENT_TYPES = {
611
+ sales: { name: 'Sales Agent', route: '/sales', role: 'You are Morgan, a PC sales specialist.' },
612
+ support: {
613
+ name: 'Support Agent',
614
+ route: '/support',
615
+ role: 'You are Sam, a PC support specialist.',
616
+ },
617
+ triage: { name: 'Triage Agent', route: '/', role: 'You are Alex, the front desk assistant.' },
618
+ };
619
+
620
+ interface AgentConfig {
621
+ skills?: SkillBase[];
622
+ languages?: { name: string; code: string; voice?: string }[];
623
+ }
624
+
625
+ /** Build and configure an agent of one of the known types. */
626
+ export async function createAgent(type: string, config: AgentConfig = {}): Promise<AgentBase> {
627
+ if (!(type in AGENT_TYPES)) throw new Error(`Unknown agent type: ${type}`);
628
+ const spec = AGENT_TYPES[type as keyof typeof AGENT_TYPES];
629
+
630
+ const created = new AgentBase({ name: spec.name, route: spec.route });
631
+ created.promptAddSection('AI Role', { body: spec.role });
632
+ for (const skill of config.skills ?? []) await created.addSkill(skill);
633
+ for (const language of config.languages ?? []) created.addLanguage(language);
634
+ return created;
635
+ }
636
+ // endregion: factory
637
+
638
+ // Start the server only when this file is run, not when it's imported
639
+ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
640
+ await agent.run();
641
+ }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Knowledge base loader for the multi-agent tutorial (Lesson 2).
3
+ *
4
+ * Splits a Markdown knowledge base into one document per section, in the
5
+ * shape the native_vector_search skill indexes in memory:
6
+ * `{ id, text, metadata: { filename, section } }`.
7
+ */
8
+
9
+ // region: loader
10
+ import { readFileSync } from 'node:fs';
11
+ import { basename } from 'node:path';
12
+
13
+ /** One searchable section of a knowledge base file. */
14
+ export interface KnowledgeDocument {
15
+ id: string;
16
+ text: string;
17
+ metadata: { filename: string; section: string };
18
+ }
19
+
20
+ /**
21
+ * Read a Markdown file and return one document per `###` section. Each
22
+ * document starts with its `##` and `###` headings, so a result read on its
23
+ * own still says what it's about. A heading with no text under it adds no document.
24
+ */
25
+ export function loadKnowledge(path: string): KnowledgeDocument[] {
26
+ const filename = basename(path);
27
+ const docs: KnowledgeDocument[] = [];
28
+ let chapter = '';
29
+ let heading = '';
30
+ let body: string[] = [];
31
+
32
+ const flush = (): void => {
33
+ const text = body.join('\n').trim();
34
+ const section = heading && chapter ? `${chapter} > ${heading}` : heading || chapter;
35
+ if (section && text) {
36
+ docs.push({
37
+ id: `${filename}#${docs.length + 1}`,
38
+ text: `${section}\n${text}`,
39
+ metadata: { filename, section },
40
+ });
41
+ }
42
+ body = [];
43
+ };
44
+
45
+ for (const line of readFileSync(path, 'utf8').split('\n')) {
46
+ const match = /^(#{1,3})\s+(.*)$/.exec(line);
47
+ if (!match) {
48
+ body.push(line);
49
+ continue;
50
+ }
51
+ flush();
52
+ const [, hashes, title] = match;
53
+ if (hashes !== '###') chapter = hashes === '##' ? title!.trim() : '';
54
+ heading = hashes === '###' ? title!.trim() : '';
55
+ }
56
+ flush();
57
+ return docs;
58
+ }
59
+ // endregion: loader