@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,175 @@
1
+ # SignalWire Agents SDK Tutorial: Multi-Agent PC Builder
2
+
3
+ This tutorial builds AI voice agents with the SignalWire Agents SDK for TypeScript. It starts with a single sales agent and ends with a multi-agent system that searches a knowledge base and hands off calls between specialists.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [What you build](#what-you-build)
8
+ 2. [Prerequisites](#prerequisites)
9
+ 3. [Tutorial structure](#tutorial-structure)
10
+ 4. [Getting started](#getting-started)
11
+ 5. [Additional resources](#additional-resources)
12
+
13
+ ---
14
+
15
+ ## What you build
16
+
17
+ The tutorial builds PC Builder Pro, a store with three voice agents:
18
+
19
+ - Morgan, a sales specialist who recommends builds from a product knowledge base
20
+ - Sam, a support specialist who troubleshoots from a support knowledge base
21
+ - Alex, a front desk agent who greets callers and transfers them to Morgan or Sam
22
+
23
+ Along the way it covers these topics:
24
+
25
+ - Creating an agent with `AgentBase` and a structured prompt (the Prompt Object Model, or POM)
26
+ - Configuring voices and languages, and serving over HTTPS
27
+ - Adding a knowledge-base search tool with the `native_vector_search` skill
28
+ - Hosting several agents on one `AgentServer`, and transferring calls between them
29
+ - Writing SWAIG functions (the tools the AI calls), handling errors, and deploying
30
+ - Writing custom skills, keeping state, and calling external services
31
+
32
+ ## Prerequisites
33
+
34
+ You need these to follow the tutorial:
35
+
36
+ - Node.js 22.13 or later. Lesson 5's SQLite example uses `node:sqlite`, which Node.js 22.5 through 22.12 offer only behind the `--experimental-sqlite` flag.
37
+ - npm, and a basic knowledge of TypeScript, including `async` and `await`
38
+ - A text editor
39
+
40
+ A SignalWire account lets you call the agents from a phone, but every lesson also works without one.
41
+
42
+ ## Tutorial structure
43
+
44
+ Each lesson builds on the one before it:
45
+
46
+ 1. [Lesson 1: Creating Your First Agent](lesson1_first_agent.md) builds Morgan, a sales agent with a structured prompt and a voice. It covers running the agent locally and over HTTPS.
47
+ 2. [Lesson 2: Adding Intelligence with Knowledge Bases](lesson2_knowledge_bases.md) gives Morgan a search tool over a Markdown knowledge base.
48
+ 3. [Lesson 3: Building Multi-Agent Systems](lesson3_multi_agent_systems.md) hosts Alex, Morgan and Sam on one server, with transfers that carry the caller's name and a summary.
49
+ 4. [Lesson 4: Advanced Features and Best Practices](lesson4_advanced_features.md) covers SWAIG functions, error handling, logging, testing and deployment.
50
+ 5. [Lesson 5: Extending Your Agents](lesson5_extending_agents.md) covers custom skills, state, workflows and external services.
51
+
52
+ ## Getting started
53
+
54
+ The commands in this tutorial run from the root of the SDK repository, where `@signalwire/sdk` resolves to the source tree. Install the dependencies once:
55
+
56
+ ```bash
57
+ npm install
58
+ ```
59
+
60
+ In a project of your own, install the SDK and `tsx`, which runs TypeScript files directly:
61
+
62
+ ```bash
63
+ npm install @signalwire/sdk
64
+ npm install --save-dev tsx
65
+ ```
66
+
67
+ ### Running your first agent
68
+
69
+ Every request to an agent needs basic auth. Set the credentials, then start the Lesson 1 agent:
70
+
71
+ ```bash
72
+ export SWML_BASIC_AUTH_USER=devuser
73
+ export SWML_BASIC_AUTH_PASSWORD=devpassword
74
+ npx tsx tutorial/multi_agents/sales_agent.ts
75
+ ```
76
+
77
+ The agent listens on port 3000, or on the port in the `PORT` environment variable.
78
+
79
+ ### Testing with SWML
80
+
81
+ From a second terminal, request the agent's SWML document with the same credentials:
82
+
83
+ ```bash
84
+ curl -u devuser:devpassword http://localhost:3000/
85
+ ```
86
+
87
+ ## Additional resources
88
+
89
+ ### Quick reference
90
+
91
+ These commands come up throughout the tutorial:
92
+
93
+ ```bash
94
+ # List an agent's tools, and call one without starting a server
95
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/sales_agent_with_search.ts --list-tools
96
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/sales_agent_with_search.ts --exec search_sales_knowledge --query "RTX 4070"
97
+
98
+ # Print the SWML one agent of a multi-agent file serves
99
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/pc_builder.ts --route /sales --dump-swml
100
+
101
+ # Serve HTTPS
102
+ SWML_SSL_ENABLED=true \
103
+ SWML_SSL_CERT_PATH=/path/to/cert.pem \
104
+ SWML_SSL_KEY_PATH=/path/to/key.pem \
105
+ npx tsx tutorial/multi_agents/sales_agent.ts
106
+ ```
107
+
108
+ In a project that installs the SDK, run the CLI as `npx swaig-test`.
109
+
110
+ The agents read these environment variables:
111
+
112
+ | Variable | Description | Default |
113
+ |----------|-------------|---------|
114
+ | `PORT` | Port to listen on | `3000` (`3001` for `pc_builder.ts`) |
115
+ | `SWML_BASIC_AUTH_USER` | Basic auth username | The agent's name |
116
+ | `SWML_BASIC_AUTH_PASSWORD` | Basic auth password | Generated at startup, and never logged |
117
+ | `SWML_SSL_ENABLED` | Serve HTTPS: `true`, `1` or `yes` | Off |
118
+ | `SWML_SSL_CERT_PATH` | Path to the PEM certificate | None |
119
+ | `SWML_SSL_KEY_PATH` | Path to the PEM private key | None |
120
+ | `SWML_SSL_DOMAIN` | Domain the agent's webhook URLs use when it serves HTTPS | None |
121
+ | `SWML_PROXY_URL_BASE` | Public URL of the agent, when a proxy or tunnel is in front of it | None |
122
+ | `SIGNALWIRE_SIGNING_KEY` | Key that verifies requests come from SignalWire | None |
123
+ | `SIGNALWIRE_LOG_LEVEL` | `debug`, `info`, `warn` or `error` | `info` |
124
+
125
+ ### Code examples
126
+
127
+ This directory holds every file the lessons build:
128
+
129
+ - `sales_agent.ts`: the basic sales agent (Lesson 1)
130
+ - `knowledge.ts` and `sales_agent_with_search.ts`: the knowledge-base loader and the agent that searches it (Lesson 2)
131
+ - `pc_builder.ts`: the multi-agent system (Lesson 3)
132
+ - `advanced_agent.ts` and `Dockerfile`: the tools and deployment from Lesson 4
133
+ - `extending_agents.ts`: the skills and patterns from Lesson 5
134
+ - `sales_knowledge.md` and `support_knowledge.md`: the two knowledge bases
135
+
136
+ The tests in `tests/tutorial/multi_agents.test.ts` and `tests/tutorial/multi_agents-lessons.test.ts` check what the lessons say about each file. Run them with `npx vitest run tests/tutorial/multi_agents`.
137
+
138
+ ### Troubleshooting
139
+
140
+ These problems come up most often:
141
+
142
+ 1. **Port already in use:** another process holds the port. Start the agent on a different one:
143
+
144
+ ```bash
145
+ PORT=3002 npx tsx tutorial/multi_agents/sales_agent.ts
146
+ ```
147
+
148
+ 2. **401 Unauthorized from curl:** the credentials don't match the agent's. Set `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` before starting the agent. Without them the agent generates a password it doesn't log.
149
+ 3. **`Cannot find module '@signalwire/sdk'`:** install the dependencies with `npm install`, and run the commands from the project root.
150
+
151
+ ### Getting help
152
+
153
+ For more information, see the [SignalWire documentation](https://signalwire.com/docs) and the SDK guides in [`docs/`](../../docs/agent-guide.md).
154
+
155
+ These habits help when you debug an agent:
156
+
157
+ - Test tools with `swaig-test` before you place a call.
158
+ - Request the SWML with `curl` to see exactly what SignalWire receives.
159
+ - Set `SIGNALWIRE_LOG_LEVEL=debug` for more detail in the logs.
160
+
161
+ ### Best practices checklist
162
+
163
+ Check these before you put an agent in front of callers:
164
+
165
+ - Structure prompts with sections, and describe every tool and parameter precisely
166
+ - Return a `FunctionResult` that tells the model what happened, including failures
167
+ - Test locally with `swaig-test` and your own tests
168
+ - Serve HTTPS, or put the agent behind a proxy that does
169
+ - Set the basic auth credentials and `SIGNALWIRE_SIGNING_KEY` from the environment
170
+ - Keep secrets out of prompts and logs, and validate every argument a tool receives
171
+ - Keep your dependencies up to date
172
+
173
+ ---
174
+
175
+ Start with [Lesson 1: Creating Your First Agent](lesson1_first_agent.md).
@@ -0,0 +1,395 @@
1
+ /**
2
+ * Advanced features (Lesson 4)
3
+ *
4
+ * One agent with the tools Lesson 4 walks through: parameters and required
5
+ * arguments, results with actions, async handlers, error handling and
6
+ * validation, logging, caching, input sanitization, secrets and rate limiting.
7
+ *
8
+ * Run: npx tsx tutorial/multi_agents/advanced_agent.ts
9
+ */
10
+
11
+ // region: setup
12
+ import { pathToFileURL } from 'node:url';
13
+ import { Hono } from 'hono';
14
+ import { AgentBase, FunctionResult, getLogger } from '@signalwire/sdk';
15
+
16
+ const log = getLogger('advanced_agent');
17
+
18
+ export const agent = new AgentBase({ name: 'Advanced Features Agent', route: '/' });
19
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.marsh' });
20
+ // endregion: setup
21
+
22
+ // region: calculate-price
23
+ agent.defineTool({
24
+ name: 'calculate_price',
25
+ description: 'Calculate total price with tax',
26
+ parameters: {
27
+ amount: { type: 'number', description: 'Base price in dollars' },
28
+ tax_rate: { type: 'number', description: 'Tax rate as a decimal (default 0.08)' },
29
+ },
30
+ required: ['amount'],
31
+ handler: ({ amount, tax_rate = 0.08 }) => {
32
+ const tax = amount * tax_rate;
33
+ const total = amount + tax;
34
+ return new FunctionResult(
35
+ `The total price is $${total.toFixed(2)} ($${amount.toFixed(2)} + $${tax.toFixed(2)} tax)`,
36
+ );
37
+ },
38
+ });
39
+ // endregion: calculate-price
40
+
41
+ // region: create-order
42
+ agent.defineTool({
43
+ name: 'create_order',
44
+ description: 'Create a new order',
45
+ parameters: {
46
+ customer_name: { type: 'string', description: "Customer's full name" },
47
+ items: { type: 'string', description: 'Items to order' },
48
+ priority: {
49
+ type: 'string',
50
+ enum: ['normal', 'rush'],
51
+ description: 'Order priority (default normal)',
52
+ },
53
+ },
54
+ required: ['customer_name', 'items'],
55
+ handler: ({ customer_name, items, priority = 'normal' }) =>
56
+ new FunctionResult(`Order for ${customer_name} created: ${items} (${priority} priority)`),
57
+ });
58
+ // endregion: create-order
59
+
60
+ // region: parameter-types
61
+ agent.defineTool({
62
+ name: 'quote_upgrade',
63
+ description: 'Quote a component upgrade',
64
+ parameters: {
65
+ component: { type: 'string', description: 'The component to upgrade' },
66
+ quantity: { type: 'integer', description: 'How many to install' },
67
+ unit_price: { type: 'number', description: 'Price of one, in dollars' },
68
+ installation: { type: 'boolean', description: 'Whether the store installs it' },
69
+ },
70
+ required: ['component', 'quantity', 'unit_price', 'installation'],
71
+ handler: ({ component, quantity, unit_price, installation }) => {
72
+ const labor = installation ? 50 : 0;
73
+ const total = quantity * unit_price + labor;
74
+ return new FunctionResult(`${quantity} x ${component}: $${total.toFixed(2)}`);
75
+ },
76
+ });
77
+ // endregion: parameter-types
78
+
79
+ // region: check-inventory
80
+ agent.defineTool({
81
+ name: 'check_inventory',
82
+ description: 'Check product availability',
83
+ parameters: {
84
+ product_id: { type: 'string', description: 'The product ID to check' },
85
+ },
86
+ required: ['product_id'],
87
+ handler: ({ product_id }) => {
88
+ const inStock = product_id.startsWith('GPU') ? 5 : 0; // stands in for a real lookup
89
+ if (inStock === 0) {
90
+ return new FunctionResult(`Product ${product_id} is out of stock`);
91
+ }
92
+ // Keep the result in global data, where later function calls can read it
93
+ return new FunctionResult(
94
+ `Product ${product_id} is in stock (${inStock} units)`,
95
+ ).updateGlobalData({ last_checked_product: product_id, stock_level: inStock });
96
+ },
97
+ });
98
+ // endregion: check-inventory
99
+
100
+ // region: async-and-sync
101
+ // An async handler, for I/O: the event loop keeps serving other requests while it waits
102
+ agent.defineTool({
103
+ name: 'fetch_product_reviews',
104
+ description: 'Fetch the review count for a product from the review service',
105
+ parameters: {
106
+ product_id: { type: 'string', description: 'The product ID' },
107
+ },
108
+ required: ['product_id'],
109
+ handler: async ({ product_id }) => {
110
+ const base = process.env['REVIEWS_API_URL'];
111
+ if (!base) return new FunctionResult('The review service is not configured.');
112
+ const res = await fetch(`${base}/reviews/${encodeURIComponent(product_id)}`, {
113
+ signal: AbortSignal.timeout(5000),
114
+ });
115
+ if (!res.ok) return new FunctionResult('The review service is unavailable right now.');
116
+ const reviews = (await res.json()) as unknown[];
117
+ return new FunctionResult(`Found ${reviews.length} reviews for ${product_id}`);
118
+ },
119
+ });
120
+
121
+ // A synchronous handler, for quick calculations
122
+ agent.defineTool({
123
+ name: 'add_numbers',
124
+ description: 'Add two numbers',
125
+ parameters: {
126
+ x: { type: 'integer', description: 'First number' },
127
+ y: { type: 'integer', description: 'Second number' },
128
+ },
129
+ required: ['x', 'y'],
130
+ handler: ({ x, y }) => new FunctionResult(`Result: ${x + y}`),
131
+ });
132
+ // endregion: async-and-sync
133
+
134
+ // region: process-order
135
+ class OrderError extends Error {}
136
+
137
+ agent.defineTool({
138
+ name: 'process_order',
139
+ description: 'Process customer order',
140
+ parameters: {
141
+ order_id: { type: 'string', description: 'The order ID to process' },
142
+ },
143
+ required: ['order_id'],
144
+ handler: ({ order_id }) => {
145
+ try {
146
+ // Validate input
147
+ if (order_id.length < 5) {
148
+ return new FunctionResult('Invalid order ID format');
149
+ }
150
+ if (order_id.startsWith('TEST')) {
151
+ throw new OrderError('Test orders cannot be processed');
152
+ }
153
+ return new FunctionResult(`Order ${order_id} processed successfully`);
154
+ } catch (err) {
155
+ if (err instanceof OrderError) {
156
+ return new FunctionResult(`Order processing failed: ${err.message}`);
157
+ }
158
+ // Log unexpected errors, and tell the model only that something went wrong
159
+ log.error('unexpected error processing order', { error: String(err) });
160
+ return new FunctionResult('An unexpected error occurred. Please try again.');
161
+ }
162
+ },
163
+ });
164
+ // endregion: process-order
165
+
166
+ // region: error-prompt
167
+ agent.promptAddSection('Error Handling', {
168
+ body: 'How to handle errors gracefully:',
169
+ bullets: [
170
+ 'If a function returns an error, acknowledge it politely',
171
+ 'Offer alternative solutions when possible',
172
+ 'Never expose technical error details to customers',
173
+ 'Always maintain a helpful, professional tone',
174
+ ],
175
+ });
176
+ // endregion: error-prompt
177
+
178
+ // region: update-customer
179
+ agent.defineTool({
180
+ name: 'update_customer',
181
+ description: 'Update customer information',
182
+ parameters: {
183
+ customer_id: { type: 'string', description: "The customer's ID" },
184
+ email: { type: 'string', description: "Customer's email address" },
185
+ phone: { type: 'string', description: "Customer's phone number" },
186
+ },
187
+ handler: ({ customer_id, email, phone }) => {
188
+ // Collect every problem, and report them together
189
+ const errors: string[] = [];
190
+ if (!customer_id) errors.push('Customer ID is required');
191
+ if (email && !email.includes('@')) errors.push('Invalid email format');
192
+ if (phone && phone.replace(/\D/g, '').length < 10) {
193
+ errors.push('Phone number must be at least 10 digits');
194
+ }
195
+ if (errors.length > 0) {
196
+ return new FunctionResult(`Validation failed: ${errors.join(', ')}`);
197
+ }
198
+ return new FunctionResult('Customer updated successfully');
199
+ },
200
+ });
201
+ // endregion: update-customer
202
+
203
+ // region: logging
204
+ agent.defineTool({
205
+ name: 'normalize_part_number',
206
+ description: 'Normalize a part number to upper case',
207
+ parameters: {
208
+ part_number: { type: 'string', description: 'The part number as the caller said it' },
209
+ },
210
+ required: ['part_number'],
211
+ handler: ({ part_number }, rawData) => {
212
+ log.debug('normalize_part_number called', { call_id: rawData.call_id, part_number });
213
+ const normalized = part_number.trim().toUpperCase().replace(/\s+/g, '-');
214
+ log.info('part number normalized', { normalized });
215
+ return new FunctionResult(`The part number is ${normalized}`);
216
+ },
217
+ });
218
+ // endregion: logging
219
+
220
+ // region: request-logging
221
+ // Runs on every request, on that request's copy of the agent. It logs names,
222
+ // not values: the query can carry a SWAIG token, and the body caller data.
223
+ agent.addPerCallConfig((query, body, headers) => {
224
+ log.debug('request', {
225
+ query_keys: Object.keys(query),
226
+ body_keys: Object.keys(body ?? {}),
227
+ user_agent: headers['user-agent'],
228
+ });
229
+ });
230
+ // endregion: request-logging
231
+
232
+ // region: debug-state
233
+ agent.defineTool({
234
+ name: 'debug_state',
235
+ description: 'Log the agent state',
236
+ handler: (_args, _rawData, current) => {
237
+ const state = {
238
+ agent_name: current?.getName(),
239
+ functions: current?.getTools().map((fn) => fn.name),
240
+ };
241
+ log.info('agent state', state);
242
+ return new FunctionResult('State logged to console');
243
+ },
244
+ });
245
+ // endregion: debug-state
246
+
247
+ // region: status-route
248
+ // A route of your own beside the agent's, outside its basic auth
249
+ const status = new Hono();
250
+ status.get('/', (c) =>
251
+ c.json({
252
+ status: 'healthy',
253
+ timestamp: new Date().toISOString(),
254
+ tools: agent.getTools().length,
255
+ uptime_seconds: Math.round(process.uptime()),
256
+ }),
257
+ );
258
+ agent.mount(status, { prefix: '/status' });
259
+ // endregion: status-route
260
+
261
+ // region: caching
262
+ // Stands in for a slow database or API call
263
+ async function lookupProduct(productId: string): Promise<string> {
264
+ await new Promise((resolve) => setTimeout(resolve, 200));
265
+ return `Product ${productId}: 16GB DDR5 memory kit`;
266
+ }
267
+
268
+ const productCache = new Map<string, { value: string; expires: number }>();
269
+ const CACHE_TTL_MS = 5 * 60 * 1000;
270
+
271
+ agent.defineTool({
272
+ name: 'get_product_info',
273
+ description: 'Get product information',
274
+ parameters: {
275
+ product_id: { type: 'string', description: 'The product ID to look up' },
276
+ },
277
+ required: ['product_id'],
278
+ handler: async ({ product_id }) => {
279
+ const cached = productCache.get(product_id);
280
+ if (cached && cached.expires > Date.now()) {
281
+ log.debug('cache hit', { product_id });
282
+ return new FunctionResult(cached.value);
283
+ }
284
+ const info = await lookupProduct(product_id);
285
+ productCache.set(product_id, { value: info, expires: Date.now() + CACHE_TTL_MS });
286
+ return new FunctionResult(info);
287
+ },
288
+ });
289
+ // endregion: caching
290
+
291
+ // region: concurrent
292
+ // Stand-ins for three independent services
293
+ const getOrders = async (id: string) => [`${id}-order-1`, `${id}-order-2`];
294
+ const getProfile = async (id: string) => ({ id, tier: 'gold' });
295
+ const getPreferences = async (id: string) => ({ id, contact: 'email' });
296
+
297
+ agent.defineTool({
298
+ name: 'get_full_info',
299
+ description: 'Get complete customer information',
300
+ parameters: {
301
+ customer_id: { type: 'string', description: 'The customer ID' },
302
+ },
303
+ required: ['customer_id'],
304
+ handler: async ({ customer_id }) => {
305
+ // The three lookups run at the same time, not one after another
306
+ const [orders, profile, preferences] = await Promise.all([
307
+ getOrders(customer_id),
308
+ getProfile(customer_id),
309
+ getPreferences(customer_id),
310
+ ]);
311
+ return new FunctionResult(
312
+ `Found ${orders.length} orders for a ${profile.tier} customer who prefers ${preferences.contact}`,
313
+ );
314
+ },
315
+ });
316
+ // endregion: concurrent
317
+
318
+ // region: sanitize
319
+ const catalog = ['RTX 4070', 'RTX 4090', 'Ryzen 7 7700X', 'Z790 motherboard'];
320
+
321
+ agent.defineTool({
322
+ name: 'safe_search',
323
+ description: 'Search the product catalog',
324
+ parameters: {
325
+ query: { type: 'string', description: 'Search query' },
326
+ },
327
+ required: ['query'],
328
+ handler: ({ query }) => {
329
+ // Keep letters, digits, spaces and hyphens, and at most 100 characters
330
+ const safeQuery = query
331
+ .replace(/[^\w\s-]/g, '')
332
+ .trim()
333
+ .slice(0, 100);
334
+ if (!safeQuery) return new FunctionResult('Invalid search query');
335
+ const results = catalog.filter((item) => item.toLowerCase().includes(safeQuery.toLowerCase()));
336
+ return new FunctionResult(`Found ${results.length} results: ${results.join(', ')}`);
337
+ },
338
+ });
339
+ // endregion: sanitize
340
+
341
+ // region: secrets
342
+ // Read secrets from the environment, and never log them
343
+ const apiKey = process.env['PARTNER_API_KEY'];
344
+ if (!apiKey) log.warn('PARTNER_API_KEY not set');
345
+
346
+ agent.defineTool({
347
+ name: 'check_partner_stock',
348
+ description: 'Check stock at the partner warehouse',
349
+ parameters: {
350
+ sku: { type: 'string', description: 'The product SKU' },
351
+ },
352
+ required: ['sku'],
353
+ handler: async ({ sku }) => {
354
+ const base = process.env['PARTNER_API_URL'];
355
+ if (!apiKey || !base) return new FunctionResult('The partner API is not configured.');
356
+ log.info('calling partner API', { sku }); // the key stays out of the log
357
+ const res = await fetch(`${base}/stock/${encodeURIComponent(sku)}`, {
358
+ headers: { Authorization: `Bearer ${apiKey}` },
359
+ signal: AbortSignal.timeout(5000),
360
+ });
361
+ return new FunctionResult(
362
+ res.ok ? `Partner stock for ${sku}: ${await res.text()}` : 'Unable to check partner stock.',
363
+ );
364
+ },
365
+ });
366
+ // endregion: secrets
367
+
368
+ // region: rate-limit
369
+ // Calls per caller in the last minute. The caller comes from the request
370
+ // SignalWire sends, not from an argument the model fills in.
371
+ const callTimes = new Map<string, number[]>();
372
+ const LIMIT_PER_MINUTE = 10;
373
+
374
+ agent.defineTool({
375
+ name: 'limited_function',
376
+ description: 'A function each caller may run 10 times a minute',
377
+ handler: (_args, rawData) => {
378
+ const caller = rawData.caller_id_num ?? rawData.call_id ?? 'unknown';
379
+ const now = Date.now();
380
+ const recent = (callTimes.get(caller) ?? []).filter((t) => t > now - 60_000);
381
+ if (recent.length >= LIMIT_PER_MINUTE) {
382
+ callTimes.set(caller, recent);
383
+ return new FunctionResult('Rate limit exceeded. Please try again later.');
384
+ }
385
+ recent.push(now);
386
+ callTimes.set(caller, recent);
387
+ return new FunctionResult('Function executed successfully');
388
+ },
389
+ });
390
+ // endregion: rate-limit
391
+
392
+ // Start the server only when this file is run, not when it's imported
393
+ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
394
+ await agent.run();
395
+ }