@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,856 @@
1
+ # Lesson 5: Extending Your Agents
2
+
3
+ This lesson adds capabilities to an agent: a skill of your own, state, multi-step workflows, and connections to other services. The examples are one agent, `tutorial/multi_agents/extending_agents.ts`, and its tests are in `tests/tutorial/multi_agents-lessons.test.ts`.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Creating custom skills](#creating-custom-skills)
8
+ 2. [State management](#state-management)
9
+ 3. [Complex conversation flows](#complex-conversation-flows)
10
+ 4. [External service integration](#external-service-integration)
11
+ 5. [Custom voice personas](#custom-voice-personas)
12
+ 6. [Advanced prompt engineering](#advanced-prompt-engineering)
13
+ 7. [Common patterns](#common-patterns)
14
+ 8. [Summary](#summary)
15
+
16
+ ---
17
+
18
+ ## Creating custom skills
19
+
20
+ A skill packages tools, prompt sections, speech hints and setup into one class that any agent can add. The built-in skills, such as `native_vector_search` and `swml_transfer`, are written the same way.
21
+
22
+ ### Basic skill structure
23
+
24
+ A skill extends `SkillBase`, and sets a name and a description. This one looks up the weather with the WeatherAPI.com service:
25
+
26
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#weather-skill -->
27
+ ```typescript
28
+ /** Current weather and forecasts from WeatherAPI.com. */
29
+ export class WeatherSkill extends SkillBase {
30
+ static override SKILL_NAME = 'weather_lookup';
31
+ static override SKILL_DESCRIPTION = 'Provides weather information and forecasts';
32
+ static override SKILL_VERSION = '1.0.0';
33
+ static override REQUIRED_ENV_VARS = ['WEATHER_API_KEY'] as const;
34
+
35
+ private apiKey = '';
36
+ private baseUrl = '';
37
+
38
+ static override getParameterSchema(): Record<string, ParameterSchemaEntry> {
39
+ return {
40
+ ...super.getParameterSchema(),
41
+ base_url: {
42
+ type: 'string',
43
+ description: 'Base URL of the weather API',
44
+ default: 'https://api.weatherapi.com/v1',
45
+ required: false,
46
+ },
47
+ };
48
+ }
49
+
50
+ // Runs once when the skill is added. Returning false refuses the skill.
51
+ override async setup(): Promise<boolean> {
52
+ this.apiKey = process.env['WEATHER_API_KEY'] ?? '';
53
+ this.baseUrl = this.getConfig<string>('base_url', 'https://api.weatherapi.com/v1');
54
+ return this.apiKey !== '';
55
+ }
56
+
57
+ /** GET a path of the weather API, or null when it fails. */
58
+ private async get(path: string, params: Record<string, string>): Promise<unknown> {
59
+ const query = new URLSearchParams({ key: this.apiKey, ...params });
60
+ const res = await fetch(`${this.baseUrl}${path}?${query}`, {
61
+ signal: AbortSignal.timeout(5000),
62
+ });
63
+ return res.ok ? res.json() : null;
64
+ }
65
+
66
+ override getTools(): SkillToolDefinition[] {
67
+ return [
68
+ {
69
+ name: 'get_weather',
70
+ description: 'Get current weather for a location',
71
+ parameters: {
72
+ location: { type: 'string', description: 'City or location name' },
73
+ },
74
+ required: ['location'],
75
+ handler: async (args) => {
76
+ const location = String(args['location']);
77
+ const data = (await this.get('/current.json', { q: location })) as {
78
+ current: { temp_f: number; condition: { text: string } };
79
+ } | null;
80
+ if (!data) return new FunctionResult(`Could not get weather for ${location}`);
81
+ return new FunctionResult(
82
+ `Current weather in ${location}: ${data.current.temp_f}°F, ${data.current.condition.text}`,
83
+ );
84
+ },
85
+ },
86
+ {
87
+ name: 'get_forecast',
88
+ description: 'Get weather forecast',
89
+ parameters: {
90
+ location: { type: 'string', description: 'City or location name' },
91
+ days: { type: 'integer', description: 'Number of days to forecast (default 3)' },
92
+ },
93
+ required: ['location'],
94
+ handler: async (args) => {
95
+ const location = String(args['location']);
96
+ const days = String(args['days'] ?? 3);
97
+ const data = (await this.get('/forecast.json', { q: location, days })) as {
98
+ forecast: {
99
+ forecastday: {
100
+ date: string;
101
+ day: { maxtemp_f: number; mintemp_f: number; condition: { text: string } };
102
+ }[];
103
+ };
104
+ } | null;
105
+ if (!data) return new FunctionResult(`Could not get a forecast for ${location}`);
106
+ const lines = data.forecast.forecastday.map(
107
+ (d) => `${d.date}: ${d.day.condition.text}, ${d.day.mintemp_f}-${d.day.maxtemp_f}°F`,
108
+ );
109
+ return new FunctionResult(`Forecast for ${location}:\n${lines.join('\n')}`);
110
+ },
111
+ },
112
+ ];
113
+ }
114
+
115
+ protected override _getPromptSections(): SkillPromptSection[] {
116
+ return [
117
+ {
118
+ title: 'Weather',
119
+ body: 'You can look up current weather and forecasts.',
120
+ bullets: ['Use get_weather for current conditions, and get_forecast for the coming days'],
121
+ },
122
+ ];
123
+ }
124
+ }
125
+ ```
126
+
127
+ The parts do these jobs:
128
+
129
+ - `SKILL_NAME` and `SKILL_DESCRIPTION` are required, and the constructor throws without them.
130
+ - `REQUIRED_ENV_VARS` lists variables that must be set. Adding the skill fails when one is missing.
131
+ - `getParameterSchema()` describes the options the skill accepts. `getConfig()` reads them, with a default.
132
+ - `setup()` runs once, when the skill is added. Returning `false` refuses the skill.
133
+ - `getTools()` returns the tools, in the same shape `defineTool()` takes.
134
+ - `_getPromptSections()` returns prompt sections the skill adds to the agent's prompt.
135
+
136
+ ### Using custom skills
137
+
138
+ Add a custom skill the same way as a built-in one, with an instance:
139
+
140
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#use-skill -->
141
+ ```typescript
142
+ // The skill refuses to load without WEATHER_API_KEY, so add it only when the key is set
143
+ if (process.env['WEATHER_API_KEY']) {
144
+ await agent.addSkill(new WeatherSkill());
145
+ } else {
146
+ log.warn('WEATHER_API_KEY not set; the weather tools are not available');
147
+ }
148
+ ```
149
+
150
+ `addSkill()` rejects when a required variable is missing, so the file checks first. With `WEATHER_API_KEY` set, the tool answers from the live service:
151
+
152
+ ```bash
153
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/extending_agents.ts --route / \
154
+ --exec get_weather --location Austin
155
+ ```
156
+
157
+ The result is the current weather:
158
+
159
+ ```text
160
+ RESULT:
161
+ Response: Current weather in Austin: 88.2°F, Patchy rain nearby
162
+ ```
163
+
164
+ To add a skill by name, register its class once with `SkillRegistry.getInstance().register(WeatherSkill)`, then call `agent.addSkillByName('weather_lookup')`. For more information, see [Creating Custom Skills](../../docs/skills-guide.md#creating-custom-skills) in the skills guide.
165
+
166
+ ### Skill configuration
167
+
168
+ A skill that sets `SUPPORTS_MULTIPLE_INSTANCES` can be added more than once, with different options. `native_vector_search` tells its instances apart by `tool_name`:
169
+
170
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#multiple-instances -->
171
+ ```typescript
172
+ // Two instances of one skill, told apart by tool_name
173
+ const here = (name: string) => fileURLToPath(new URL(`./${name}`, import.meta.url));
174
+
175
+ await agent.addSkill(
176
+ new NativeVectorSearchSkill({
177
+ tool_name: 'search_products',
178
+ description: 'Search product and build information',
179
+ documents: loadKnowledge(here('sales_knowledge.md')),
180
+ count: 3,
181
+ }),
182
+ );
183
+ await agent.addSkill(
184
+ new NativeVectorSearchSkill({
185
+ tool_name: 'search_troubleshooting',
186
+ description: 'Search troubleshooting guides',
187
+ documents: loadKnowledge(here('support_knowledge.md')),
188
+ count: 3,
189
+ }),
190
+ );
191
+ ```
192
+
193
+ The agent gets two tools, `search_products` and `search_troubleshooting`, each over its own documents.
194
+
195
+ ## State management
196
+
197
+ An agent serves many calls at once, so state must be keyed by call, or stored where every process can reach it.
198
+
199
+ ### Per-call state
200
+
201
+ Every SWAIG request carries the call's ID in `rawData.call_id`. Key per-call state by it, not by an argument the model fills in:
202
+
203
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#call-state -->
204
+ ```typescript
205
+ // Preferences for each call, keyed by the call ID SignalWire sends with every
206
+ // function call. This lives in one process's memory: a restart loses it.
207
+ const preferences = new Map<string, Map<string, string>>();
208
+
209
+ agent.defineTool({
210
+ name: 'remember_preference',
211
+ description: 'Remember a preference the customer states',
212
+ parameters: {
213
+ key: { type: 'string', description: 'Preference name, such as budget or color' },
214
+ value: { type: 'string', description: 'Preference value' },
215
+ },
216
+ required: ['key', 'value'],
217
+ handler: ({ key, value }, rawData) => {
218
+ const callId = rawData.call_id ?? 'unknown';
219
+ if (!preferences.has(callId)) preferences.set(callId, new Map());
220
+ preferences.get(callId)!.set(key, value);
221
+ return new FunctionResult(`I'll remember that your ${key} is ${value}`);
222
+ },
223
+ });
224
+
225
+ agent.defineTool({
226
+ name: 'recall_preference',
227
+ description: 'Recall a preference the customer stated earlier in this call',
228
+ parameters: {
229
+ key: { type: 'string', description: 'Preference name to recall' },
230
+ },
231
+ required: ['key'],
232
+ handler: ({ key }, rawData) => {
233
+ const value = preferences.get(rawData.call_id ?? 'unknown')?.get(key);
234
+ return new FunctionResult(
235
+ value === undefined ? `I don't have your ${key} on record` : `Your ${key} is ${value}`,
236
+ );
237
+ },
238
+ });
239
+ ```
240
+
241
+ The map lives in one process. It's lost on a restart, and a second replica can't see it. It also grows with every call, so a production version deletes a call's entry when the call ends. `agent.onCallEnd()` registers a handler that runs at hangup.
242
+
243
+ ### Persistent state with a database
244
+
245
+ State that must outlive the process belongs in a database. Node's built-in `node:sqlite` needs no package. It needs Node.js 22.13 or later, or the `--experimental-sqlite` flag on 22.5 through 22.12:
246
+
247
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#persistent-state -->
248
+ ```typescript
249
+ // Interactions that outlive the process, in a SQLite file
250
+ const db = new DatabaseSync(process.env['INTERACTIONS_DB'] ?? 'interactions.db');
251
+ db.exec(`CREATE TABLE IF NOT EXISTS interactions (
252
+ customer_id TEXT NOT NULL,
253
+ type TEXT NOT NULL,
254
+ details TEXT NOT NULL,
255
+ timestamp TEXT NOT NULL
256
+ )`);
257
+
258
+ agent.defineTool({
259
+ name: 'save_interaction',
260
+ description: 'Save an interaction to the customer history',
261
+ parameters: {
262
+ customer_id: { type: 'string', description: 'Customer identifier' },
263
+ interaction_type: { type: 'string', description: 'Type of interaction' },
264
+ details: { type: 'string', description: 'Interaction details' },
265
+ },
266
+ required: ['customer_id', 'interaction_type', 'details'],
267
+ handler: ({ customer_id, interaction_type, details }) => {
268
+ db.prepare('INSERT INTO interactions VALUES (?, ?, ?, ?)').run(
269
+ customer_id,
270
+ interaction_type,
271
+ details,
272
+ new Date().toISOString(),
273
+ );
274
+ return new FunctionResult('Interaction saved successfully');
275
+ },
276
+ });
277
+
278
+ agent.defineTool({
279
+ name: 'get_history',
280
+ description: 'Get customer interaction history',
281
+ parameters: {
282
+ customer_id: { type: 'string', description: 'Customer identifier' },
283
+ limit: { type: 'integer', description: 'Max number of records (default 5)' },
284
+ },
285
+ required: ['customer_id'],
286
+ handler: ({ customer_id, limit = 5 }) => {
287
+ const rows = db
288
+ .prepare(
289
+ `SELECT type, details, timestamp FROM interactions
290
+ WHERE customer_id = ? ORDER BY timestamp DESC LIMIT ?`,
291
+ )
292
+ .all(customer_id, limit) as { type: string; details: string; timestamp: string }[];
293
+ if (rows.length === 0) return new FunctionResult('No previous interactions found');
294
+ const history = rows.map((r) => `- ${r.type} on ${r.timestamp}: ${r.details}`).join('\n');
295
+ return new FunctionResult(`Previous interactions:\n${history}`);
296
+ },
297
+ });
298
+ ```
299
+
300
+ The `?` placeholders pass the arguments as parameters, so a caller's words can't change the SQL. `DatabaseSync` runs each query synchronously. That's fine for small, indexed queries. A slow query blocks every call the process is serving, so use a server database with an async client for heavy work. SQLite is a file on one machine: for several replicas, use a shared database.
301
+
302
+ The history survives between processes. Save an interaction, then read it back with a second run of `swaig-test`:
303
+
304
+ ```bash
305
+ export INTERACTIONS_DB=/tmp/interactions.db
306
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/extending_agents.ts --route / \
307
+ --exec save_interaction --customer_id C1 --interaction_type quote --details 'Quoted a $2000 gaming build'
308
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/extending_agents.ts --route / \
309
+ --exec get_history --customer_id C1
310
+ ```
311
+
312
+ The second run finds the row the first one wrote:
313
+
314
+ ```text
315
+ RESULT:
316
+ Response: Previous interactions:
317
+ - quote on 2026-09-29T17:44:27.731Z: Quoted a $2000 gaming build
318
+ ```
319
+
320
+ ### Global data between function calls
321
+
322
+ Global data belongs to the call, and SignalWire keeps it. A result sets it with `updateGlobalData()`, and every later SWAIG request in the call carries it in `rawData.global_data`:
323
+
324
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#global-data -->
325
+ ```typescript
326
+ agent.defineTool({
327
+ name: 'set_customer_data',
328
+ description: 'Store a customer detail for the rest of the call',
329
+ parameters: {
330
+ key: { type: 'string', description: 'Detail name, such as name or email' },
331
+ value: { type: 'string', description: 'Detail value' },
332
+ },
333
+ required: ['key', 'value'],
334
+ handler: ({ key, value }) =>
335
+ new FunctionResult(`Stored ${key}`).updateGlobalData({ [`customer_${key}`]: value }),
336
+ });
337
+
338
+ // A later function call receives the global data with its request
339
+ agent.defineTool({
340
+ name: 'get_customer_data',
341
+ description: 'Read a customer detail stored earlier in the call',
342
+ parameters: {
343
+ key: { type: 'string', description: 'Detail name' },
344
+ },
345
+ required: ['key'],
346
+ handler: ({ key }, rawData) => {
347
+ const value = rawData.global_data?.[`customer_${key}`];
348
+ return new FunctionResult(value === undefined ? `No ${key} stored` : `${key}: ${value}`);
349
+ },
350
+ });
351
+ ```
352
+
353
+ Global data needs no storage of your own, and every replica sees it, because it arrives with the request.
354
+
355
+ ## Complex conversation flows
356
+
357
+ Some tasks take several tool calls, in order.
358
+
359
+ ### Multi-step workflows
360
+
361
+ An order starts, collects items, and is confirmed. Each step checks the state the one before it left:
362
+
363
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#workflow -->
364
+ ```typescript
365
+ // An order built over several function calls, one per call ID
366
+ interface Order {
367
+ state: 'awaiting_items' | 'ready_to_confirm';
368
+ items: { name: string; quantity: number; price: number }[];
369
+ }
370
+ const orders = new Map<string, Order>();
371
+ const PRICES: Record<string, number> = { 'RTX 4070': 549, 'Ryzen 7 7700X': 299, '32GB DDR5': 99 };
372
+
373
+ agent.defineTool({
374
+ name: 'start_order',
375
+ description: 'Start a new order',
376
+ handler: (_args, rawData) => {
377
+ orders.set(rawData.call_id ?? 'unknown', { state: 'awaiting_items', items: [] });
378
+ return new FunctionResult('Order started. Ask the customer which items they want.');
379
+ },
380
+ });
381
+
382
+ agent.defineTool({
383
+ name: 'add_item',
384
+ description: 'Add an item to the current order',
385
+ parameters: {
386
+ item: { type: 'string', enum: Object.keys(PRICES), description: 'Item name' },
387
+ quantity: { type: 'integer', description: 'Quantity (default 1)' },
388
+ },
389
+ required: ['item'],
390
+ handler: ({ item, quantity = 1 }, rawData) => {
391
+ const order = orders.get(rawData.call_id ?? 'unknown');
392
+ if (!order) return new FunctionResult('No active order. Start a new order first.');
393
+ order.items.push({ name: item, quantity, price: PRICES[item] ?? 0 });
394
+ order.state = 'ready_to_confirm';
395
+ const list = order.items.map((i) => `${i.quantity}x ${i.name}`).join(', ');
396
+ return new FunctionResult(`Added ${quantity}x ${item}. Current order: ${list}.`);
397
+ },
398
+ });
399
+
400
+ agent.defineTool({
401
+ name: 'confirm_order',
402
+ description: 'Confirm and submit the current order',
403
+ handler: (_args, rawData) => {
404
+ const callId = rawData.call_id ?? 'unknown';
405
+ const order = orders.get(callId);
406
+ if (!order) return new FunctionResult('No active order');
407
+ if (order.state !== 'ready_to_confirm') {
408
+ return new FunctionResult('Add items before confirming');
409
+ }
410
+ const total = order.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
411
+ orders.delete(callId);
412
+ return new FunctionResult(`Order confirmed. Total: $${total.toFixed(2)}`);
413
+ },
414
+ });
415
+ ```
416
+
417
+ The `enum` on `item` limits the model to products with a price. Each tool refuses to run out of order, and says why, so the model can recover. For workflows where the model must not skip a step, the SDK's contexts and steps limit which tools each step offers. For more information, see the [contexts guide](../../docs/contexts-guide.md).
418
+
419
+ ### Conditional flows
420
+
421
+ A tool can report a fact that the prompt already says how to handle. The status goes to the model in the response, and into global data for later tools:
422
+
423
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#conditional -->
424
+ ```typescript
425
+ agent.promptAddSection('Conditional Responses', {
426
+ body: 'Adapt your behavior based on context:',
427
+ bullets: [
428
+ 'For new customers: Be extra welcoming and explain our services',
429
+ 'For VIP customers: Acknowledge their status and offer premium options',
430
+ 'For support issues: Show empathy and urgency',
431
+ 'For sales inquiries: Be enthusiastic and helpful',
432
+ ],
433
+ });
434
+
435
+ const STATUSES: Record<string, string> = { C100: 'platinum', C200: 'standard' };
436
+
437
+ agent.defineTool({
438
+ name: 'check_customer_status',
439
+ description: 'Check customer status',
440
+ parameters: {
441
+ customer_id: { type: 'string', description: 'Customer identifier' },
442
+ },
443
+ required: ['customer_id'],
444
+ handler: ({ customer_id }) => {
445
+ const status = STATUSES[customer_id] ?? 'new';
446
+ // The response tells the model the status, and the Conditional Responses
447
+ // section says what to do with it. Global data keeps it for later tools.
448
+ return new FunctionResult(`Customer status: ${status}`).updateGlobalData({
449
+ customer_status: status,
450
+ is_vip: status === 'platinum',
451
+ });
452
+ },
453
+ });
454
+ ```
455
+
456
+ ## External service integration
457
+
458
+ An agent often fronts other systems: an inventory service, an order system, a queue.
459
+
460
+ ### REST API integration
461
+
462
+ A tool can call any HTTP API. Read the address and key from the environment, give the request a timeout, and turn every failure into a result the model can use:
463
+
464
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#rest-api -->
465
+ ```typescript
466
+ agent.defineTool({
467
+ name: 'check_availability',
468
+ description: 'Check product availability in the inventory service',
469
+ parameters: {
470
+ product_sku: { type: 'string', description: 'Product SKU to check' },
471
+ },
472
+ required: ['product_sku'],
473
+ handler: async ({ product_sku }) => {
474
+ const base = process.env['INVENTORY_API_URL'];
475
+ const key = process.env['INVENTORY_API_KEY'];
476
+ if (!base || !key) return new FunctionResult('The inventory service is not configured.');
477
+ try {
478
+ const res = await fetch(`${base}/inventory/${encodeURIComponent(product_sku)}`, {
479
+ headers: { Authorization: `Bearer ${key}` },
480
+ signal: AbortSignal.timeout(5000),
481
+ });
482
+ if (!res.ok) return new FunctionResult('Unable to check availability');
483
+ const data = (await res.json()) as {
484
+ in_stock: boolean;
485
+ quantity: number;
486
+ restock_date?: string;
487
+ };
488
+ return new FunctionResult(
489
+ data.in_stock
490
+ ? `Product ${product_sku} is in stock. Available quantity: ${data.quantity}`
491
+ : `Product ${product_sku} is out of stock. Expected restock: ${data.restock_date ?? 'unknown'}`,
492
+ );
493
+ } catch (err) {
494
+ log.error('inventory request failed', { error: String(err) });
495
+ return new FunctionResult('Unable to check availability');
496
+ }
497
+ },
498
+ });
499
+ ```
500
+
501
+ ### Webhook integration
502
+
503
+ Other services can call the agent too. Mount a Hono app for their webhooks. A mounted app isn't behind the agent's basic auth, so check a shared secret of your own:
504
+
505
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#webhook -->
506
+ ```typescript
507
+ // Order updates from another service, on a route beside the agent's.
508
+ // A mounted app isn't behind the agent's basic auth: check a secret of your own.
509
+ const webhooks = new Hono();
510
+ webhooks.post('/order_update', async (c) => {
511
+ const secret = process.env['ORDER_WEBHOOK_SECRET'];
512
+ if (!secret || c.req.header('x-webhook-secret') !== secret) {
513
+ return c.json({ error: 'forbidden' }, 403);
514
+ }
515
+ const { order_id, status } = await c.req.json<{ order_id: string; status: string }>();
516
+ // Answer now, and do the work after the response is sent
517
+ setImmediate(() => processOrderUpdate(order_id, status));
518
+ return c.json({ status: 'received' });
519
+ });
520
+ agent.mount(webhooks, { prefix: '/webhook' });
521
+
522
+ export const orderUpdates: { order_id: string; status: string }[] = [];
523
+ function processOrderUpdate(orderId: string, status: string): void {
524
+ log.info('order updated', { order_id: orderId, status });
525
+ orderUpdates.push({ order_id: orderId, status });
526
+ }
527
+ ```
528
+
529
+ `setImmediate()` runs the work after the response is sent, so the sender isn't kept waiting. The route answers `403` without the secret.
530
+
531
+ ### Background work queue
532
+
533
+ Work that doesn't need to finish during the call, such as emailing a quote, can go on a queue. The tool returns as soon as the task is queued:
534
+
535
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#work-queue -->
536
+ ```typescript
537
+ // Work that should happen outside the call: a function queues it and returns,
538
+ // and a worker drains the queue. A deployment with several processes uses a
539
+ // shared queue (Redis, SQS) the same way.
540
+ interface Task {
541
+ type: string;
542
+ data: string;
543
+ timestamp: string;
544
+ }
545
+ const taskQueue: Task[] = [];
546
+ export const completedTasks: Task[] = [];
547
+
548
+ agent.defineTool({
549
+ name: 'queue_task',
550
+ description: 'Queue a follow-up task, such as sending a quote by email',
551
+ parameters: {
552
+ task_type: { type: 'string', description: 'Type of task to queue' },
553
+ data: { type: 'string', description: 'Task details' },
554
+ },
555
+ required: ['task_type', 'data'],
556
+ handler: ({ task_type, data }) => {
557
+ taskQueue.push({ type: task_type, data, timestamp: new Date().toISOString() });
558
+ return new FunctionResult('Task queued for processing');
559
+ },
560
+ });
561
+
562
+ const worker = setInterval(() => {
563
+ const task = taskQueue.shift();
564
+ if (!task) return;
565
+ try {
566
+ completedTasks.push(task); // do the real work here
567
+ } catch (err) {
568
+ log.error('task failed', { type: task.type, error: String(err) });
569
+ }
570
+ }, 1000);
571
+ worker.unref(); // the worker alone doesn't keep the process running
572
+ ```
573
+
574
+ An in-memory queue loses its tasks on a restart. When a task must not be lost, use a queue service that stores it.
575
+
576
+ ## Custom voice personas
577
+
578
+ A persona is a voice and a speaking style. The same agent can take a different persona per call.
579
+
580
+ ### Choosing a persona per request
581
+
582
+ A per-call configuration callback sets the voice and adds a style section on the request's copy of the agent. The SWML URL chooses the persona, for example `https://agents.example.com/?persona=professional`:
583
+
584
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#personas -->
585
+ ```typescript
586
+ // A persona per request, chosen by a query parameter: ?persona=professional
587
+ const PERSONAS = {
588
+ professional: { voice: 'rime.cove', style: 'formal and precise', pace: 'measured' },
589
+ friendly: { voice: 'rime.marsh', style: 'warm and conversational', pace: 'relaxed' },
590
+ energetic: { voice: 'rime.spore', style: 'enthusiastic and upbeat', pace: 'quick' },
591
+ };
592
+ type PersonaName = keyof typeof PERSONAS;
593
+
594
+ agent.addPerCallConfig((query, _body, _headers, copy) => {
595
+ const name: PersonaName =
596
+ query['persona'] && query['persona'] in PERSONAS
597
+ ? (query['persona'] as PersonaName)
598
+ : 'friendly';
599
+ const persona = PERSONAS[name];
600
+ copy.setLanguages([{ name: 'English', code: 'en-US', voice: persona.voice }]);
601
+ copy.promptAddSection('Voice Style', {
602
+ body: `Speak in a ${persona.style} manner at a ${persona.pace} pace`,
603
+ });
604
+ });
605
+ ```
606
+
607
+ `setLanguages()` replaces the language list instead of adding to it, and the copy is discarded after the request. Calling `addLanguage()` and `promptAddSection()` on the agent itself each time would add a second English entry and a second style section to every later call.
608
+
609
+ ### Multilingual support
610
+
611
+ Call `addLanguage()` once for each language the agent speaks:
612
+
613
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#multilingual -->
614
+ ```typescript
615
+ export const multilingual = new AgentBase({ name: 'Multilingual Agent', route: '/multilingual' });
616
+
617
+ multilingual.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.marsh' });
618
+ multilingual.addLanguage({ name: 'Spanish', code: 'es-MX', voice: 'rime.marsh' });
619
+ multilingual.addLanguage({ name: 'French', code: 'fr-FR', voice: 'rime.marsh' });
620
+
621
+ multilingual.promptAddSection('Language Instructions', {
622
+ body: 'Adapt your communication style to the selected language:',
623
+ bullets: [
624
+ 'English: Professional but friendly American business style',
625
+ 'Spanish: Warm and personable Latin American style',
626
+ 'French: Polite and formal French business etiquette',
627
+ ],
628
+ });
629
+ ```
630
+
631
+ This second agent is at `/multilingual`, so `swaig-test --route /multilingual` selects it.
632
+
633
+ ## Advanced prompt engineering
634
+
635
+ Prompt structure changes how reliably the model follows it.
636
+
637
+ ### Structured reasoning
638
+
639
+ A section can lay out the steps for the model to follow. `numberedBullets` numbers them in the prompt:
640
+
641
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#reasoning -->
642
+ ```typescript
643
+ agent.promptAddSection('Reasoning Framework', {
644
+ body: 'Follow this structured approach for complex requests:',
645
+ bullets: [
646
+ 'Understand: Clarify what the customer is asking for',
647
+ 'Analyze: Break down the request into components',
648
+ 'Plan: Determine the best approach to help',
649
+ 'Execute: Take action using available tools',
650
+ 'Verify: Confirm the solution meets their needs',
651
+ ],
652
+ numberedBullets: true,
653
+ });
654
+
655
+ agent.promptAddSection('Decision Criteria', {
656
+ body: 'When making recommendations, consider:',
657
+ bullets: [
658
+ "Customer's stated requirements",
659
+ 'Budget constraints',
660
+ 'Technical compatibility',
661
+ 'Future scalability',
662
+ 'Best value proposition',
663
+ ],
664
+ });
665
+ ```
666
+
667
+ ### Changing the prompt during a call
668
+
669
+ `switchContext()` replaces the system prompt from a tool result, for the rest of the call. It replaces the whole prompt, so pass all of it, not only the part that changes:
670
+
671
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#switch-context -->
672
+ ```typescript
673
+ agent.defineTool({
674
+ name: 'set_explanation_mode',
675
+ description: 'Change how the agent explains things for the rest of the call',
676
+ parameters: {
677
+ mode: {
678
+ type: 'string',
679
+ enum: ['technical', 'simple', 'sales'],
680
+ description: 'Explanation mode',
681
+ },
682
+ },
683
+ required: ['mode'],
684
+ handler: ({ mode }) => {
685
+ const base = 'You are a helpful assistant for our PC products.';
686
+ const modes = {
687
+ technical: 'Provide detailed technical explanations.',
688
+ simple: 'Explain everything in simple, non-technical terms.',
689
+ sales: 'Focus on benefits and value proposition.',
690
+ };
691
+ // switchContext replaces the whole system prompt, so pass all of it
692
+ return new FunctionResult(`Switching to ${mode} mode`).switchContext({
693
+ systemPrompt: `${base} ${modes[mode]}`,
694
+ });
695
+ },
696
+ });
697
+ ```
698
+
699
+ With only a system prompt, the action is `{ "context_switch": "<the prompt>" }`. `switchContext()` also takes `userPrompt`, `consolidate` and `fullReset`. For more information, see the [SWAIG reference](../../docs/swaig-reference.md).
700
+
701
+ ## Common patterns
702
+
703
+ These helpers make calls to other services more robust. The tests exercise both.
704
+
705
+ ### Retry pattern
706
+
707
+ Retry a failure that may be temporary, with a delay that doubles each time:
708
+
709
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#retry -->
710
+ ```typescript
711
+ /** Run `fn`, retrying a failure with a delay that doubles each time. */
712
+ export async function retryWithBackoff<T>(
713
+ fn: () => Promise<T>,
714
+ maxAttempts = 3,
715
+ initialDelayMs = 1000,
716
+ ): Promise<T> {
717
+ let delay = initialDelayMs;
718
+ for (let attempt = 1; ; attempt++) {
719
+ try {
720
+ return await fn();
721
+ } catch (err) {
722
+ if (attempt >= maxAttempts) throw err;
723
+ log.warn('attempt failed, retrying', { attempt, delay_ms: delay, error: String(err) });
724
+ await new Promise((resolve) => setTimeout(resolve, delay));
725
+ delay *= 2;
726
+ }
727
+ }
728
+ }
729
+ ```
730
+
731
+ Keep the total wait short in a tool. The caller is waiting on the line.
732
+
733
+ ### Circuit breaker pattern
734
+
735
+ When a dependency keeps failing, stop calling it for a while, so each call fails fast instead of waiting for a timeout:
736
+
737
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#circuit-breaker -->
738
+ ```typescript
739
+ /** Stops calling a failing dependency until `resetTimeoutMs` has passed. */
740
+ export class CircuitBreaker {
741
+ private failureCount = 0;
742
+ private openedAt: number | null = null;
743
+
744
+ constructor(
745
+ private readonly failureThreshold = 5,
746
+ private readonly resetTimeoutMs = 60_000,
747
+ ) {}
748
+
749
+ async call<T>(fn: () => Promise<T>): Promise<T> {
750
+ if (this.openedAt !== null) {
751
+ if (Date.now() - this.openedAt < this.resetTimeoutMs) {
752
+ throw new Error('Circuit breaker is open');
753
+ }
754
+ this.openedAt = null; // try the dependency again
755
+ this.failureCount = 0;
756
+ }
757
+ try {
758
+ const result = await fn();
759
+ this.failureCount = 0;
760
+ return result;
761
+ } catch (err) {
762
+ this.failureCount += 1;
763
+ if (this.failureCount >= this.failureThreshold) {
764
+ this.openedAt = Date.now();
765
+ log.error('circuit breaker opened after repeated failures');
766
+ }
767
+ throw err;
768
+ }
769
+ }
770
+ }
771
+ ```
772
+
773
+ Wrap a call as `await breaker.call(() => fetch(url))`, and turn the error into a result that tells the model the service is down.
774
+
775
+ ### Factory pattern for agents
776
+
777
+ A factory builds agents from a plain configuration, which can come from a file or a database:
778
+
779
+ <!-- snippet: no-compile a region of tutorial/multi_agents/extending_agents.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/extending_agents.ts#factory -->
780
+ ```typescript
781
+ /** The kinds of agent the factory can build, and what makes each one different. */
782
+ const AGENT_TYPES = {
783
+ sales: { name: 'Sales Agent', route: '/sales', role: 'You are Morgan, a PC sales specialist.' },
784
+ support: {
785
+ name: 'Support Agent',
786
+ route: '/support',
787
+ role: 'You are Sam, a PC support specialist.',
788
+ },
789
+ triage: { name: 'Triage Agent', route: '/', role: 'You are Alex, the front desk assistant.' },
790
+ };
791
+
792
+ interface AgentConfig {
793
+ skills?: SkillBase[];
794
+ languages?: { name: string; code: string; voice?: string }[];
795
+ }
796
+
797
+ /** Build and configure an agent of one of the known types. */
798
+ export async function createAgent(type: string, config: AgentConfig = {}): Promise<AgentBase> {
799
+ if (!(type in AGENT_TYPES)) throw new Error(`Unknown agent type: ${type}`);
800
+ const spec = AGENT_TYPES[type as keyof typeof AGENT_TYPES];
801
+
802
+ const created = new AgentBase({ name: spec.name, route: spec.route });
803
+ created.promptAddSection('AI Role', { body: spec.role });
804
+ for (const skill of config.skills ?? []) await created.addSkill(skill);
805
+ for (const language of config.languages ?? []) created.addLanguage(language);
806
+ return created;
807
+ }
808
+ ```
809
+
810
+ `createAgent('sales', { skills: [...], languages: [...] })` returns a configured agent, ready to register on an `AgentServer`.
811
+
812
+ ## Summary
813
+
814
+ This tutorial went from a single agent to a multi-agent system with search, custom tools, and now custom skills and state. This lesson covered these topics:
815
+
816
+ - Creating custom skills with options, setup and required variables
817
+ - Keeping per-call state by call ID, persistent state in SQLite, and call state in global data
818
+ - Building workflows that span several tool calls
819
+ - Calling external APIs, and accepting webhooks and queued work
820
+ - Choosing personas per request, and speaking several languages
821
+ - Structuring prompts, and replacing the prompt during a call
822
+ - Retries, circuit breakers and agent factories
823
+
824
+ ### Where to go next
825
+
826
+ These steps build on what you have:
827
+
828
+ 1. **Build your own agent**: start with one use case and a few tools, and grow it.
829
+ 2. **Share a skill**: package a skill for other agents. For more information, see [Third-Party Skills](../../docs/third_party_skills.md).
830
+ 3. **Measure**: time your tools, and fix the slowest first.
831
+ 4. **Deploy**: put the agents in production with Lesson 4's checklist.
832
+ 5. **Iterate**: listen to real calls, and improve the prompts and tools.
833
+
834
+ ### Resources for continued learning
835
+
836
+ These resources cover the SDK and the platform:
837
+
838
+ - [SignalWire documentation](https://signalwire.com/docs)
839
+ - The SDK's guides, starting with the [agent guide](../../docs/agent-guide.md)
840
+ - The SDK's runnable examples, in [`examples/`](../../examples/README.md)
841
+
842
+ ### Final tips
843
+
844
+ Keep these in mind as you build:
845
+
846
+ - Start small and iterate
847
+ - Test tools before you place a call
848
+ - Monitor agents in production
849
+ - Keep your dependencies up to date
850
+ - Document the skills you write
851
+
852
+ This completes the tutorial. Build on Morgan, Alex and Sam, or start a new agent from what you've learned.
853
+
854
+ ---
855
+
856
+ [Previous: Lesson 4 - Advanced Features](lesson4_advanced_features.md) | [Tutorial Overview](README.md)