@signalwire/sdk 2.0.5 → 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 +481 -126
  6. package/dist/AgentBase.js +1502 -438
  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 +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +18 -0
  42. package/dist/PomBuilder.js +53 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +22 -1
  48. package/dist/PromptManager.js +28 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +158 -58
  58. package/dist/SWMLService.js +435 -127
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/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 +92 -33
  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 -371
  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 +47 -68
  169. package/dist/index.js +44 -73
  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 +44 -17
  204. package/dist/relay/RelayClient.js +175 -65
  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 +73 -42
  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 +5 -2
  245. package/dist/rest/callHandler.js +4 -1
  246. package/dist/rest/callHandler.js.map +1 -1
  247. package/dist/rest/index.d.ts +18 -77
  248. package/dist/rest/index.js +47 -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 -327
  284. package/dist/rest/namespaces/fabric.js +14 -439
  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 +8 -196
  332. package/dist/rest/namespaces/phone-numbers.js +8 -230
  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 +22 -11
  412. package/dist/skills/SkillRegistry.js +47 -17
  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 +18 -6
  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 +21 -22
  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 +42 -4
  460. package/dist/skills/builtin/spider.js +277 -104
  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 +38 -30
  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 +294 -100
  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 +14 -13
  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 +59 -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 +85 -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,805 @@
1
+ # Lesson 4: Advanced Features and Best Practices
2
+
3
+ This lesson covers what an agent needs before it takes real calls: SWAIG functions that do real work, error handling, logging, testing, deployment, performance and security. Its examples are the tools of one agent, `tutorial/multi_agents/advanced_agent.ts`, and the deployment files for the Lesson 3 system.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Custom SWAIG functions](#custom-swaig-functions)
8
+ 2. [Error handling and results](#error-handling-and-results)
9
+ 3. [Logging and debugging](#logging-and-debugging)
10
+ 4. [Production deployment](#production-deployment)
11
+ 5. [Testing strategies](#testing-strategies)
12
+ 6. [Performance optimization](#performance-optimization)
13
+ 7. [Security best practices](#security-best-practices)
14
+ 8. [Summary](#summary)
15
+
16
+ ---
17
+
18
+ ## Custom SWAIG functions
19
+
20
+ A SWAIG function is a tool the AI can call during a call. SignalWire sends the call to the agent's `/swaig` route with the arguments the model chose, and the agent runs the tool's handler. The handler can call an API, query a database or calculate, and returns a `FunctionResult` that tells the model what happened.
21
+
22
+ ### Basic function structure
23
+
24
+ The file starts with the agent and a logger:
25
+
26
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#setup -->
27
+ ```typescript
28
+ import { pathToFileURL } from 'node:url';
29
+ import { Hono } from 'hono';
30
+ import { AgentBase, FunctionResult, getLogger } from '@signalwire/sdk';
31
+
32
+ const log = getLogger('advanced_agent');
33
+
34
+ export const agent = new AgentBase({ name: 'Advanced Features Agent', route: '/' });
35
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.marsh' });
36
+ ```
37
+
38
+ `defineTool()` registers a tool with a name, a description, its parameters and a handler. This one calculates a price with tax:
39
+
40
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#calculate-price -->
41
+ ```typescript
42
+ agent.defineTool({
43
+ name: 'calculate_price',
44
+ description: 'Calculate total price with tax',
45
+ parameters: {
46
+ amount: { type: 'number', description: 'Base price in dollars' },
47
+ tax_rate: { type: 'number', description: 'Tax rate as a decimal (default 0.08)' },
48
+ },
49
+ required: ['amount'],
50
+ handler: ({ amount, tax_rate = 0.08 }) => {
51
+ const tax = amount * tax_rate;
52
+ const total = amount + tax;
53
+ return new FunctionResult(
54
+ `The total price is $${total.toFixed(2)} ($${amount.toFixed(2)} + $${tax.toFixed(2)} tax)`,
55
+ );
56
+ },
57
+ });
58
+ ```
59
+
60
+ The model reads the description and the parameter descriptions to decide when to call the tool and what to pass, so write them for the model. The handler receives the arguments as its first parameter, and TypeScript infers their types from `parameters` and `required`. `amount` is a `number`. `tax_rate` is a `number` or `undefined`, so the default applies when the model leaves it out.
61
+
62
+ ### Required parameters
63
+
64
+ List the parameters the model must always pass in `required`. An `enum` limits a string to the values you list:
65
+
66
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#create-order -->
67
+ ```typescript
68
+ agent.defineTool({
69
+ name: 'create_order',
70
+ description: 'Create a new order',
71
+ parameters: {
72
+ customer_name: { type: 'string', description: "Customer's full name" },
73
+ items: { type: 'string', description: 'Items to order' },
74
+ priority: {
75
+ type: 'string',
76
+ enum: ['normal', 'rush'],
77
+ description: 'Order priority (default normal)',
78
+ },
79
+ },
80
+ required: ['customer_name', 'items'],
81
+ handler: ({ customer_name, items, priority = 'normal' }) =>
82
+ new FunctionResult(`Order for ${customer_name} created: ${items} (${priority} priority)`),
83
+ });
84
+ ```
85
+
86
+ ### Parameter types
87
+
88
+ A parameter's `type` is a JSON Schema type. These four cover most tools:
89
+
90
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#parameter-types -->
91
+ ```typescript
92
+ agent.defineTool({
93
+ name: 'quote_upgrade',
94
+ description: 'Quote a component upgrade',
95
+ parameters: {
96
+ component: { type: 'string', description: 'The component to upgrade' },
97
+ quantity: { type: 'integer', description: 'How many to install' },
98
+ unit_price: { type: 'number', description: 'Price of one, in dollars' },
99
+ installation: { type: 'boolean', description: 'Whether the store installs it' },
100
+ },
101
+ required: ['component', 'quantity', 'unit_price', 'installation'],
102
+ handler: ({ component, quantity, unit_price, installation }) => {
103
+ const labor = installation ? 50 : 0;
104
+ const total = quantity * unit_price + labor;
105
+ return new FunctionResult(`${quantity} x ${component}: $${total.toFixed(2)}`);
106
+ },
107
+ });
108
+ ```
109
+
110
+ `integer` and `number` arrive as JavaScript numbers, and `boolean` as `true` or `false`. The model produces the arguments, so a handler that needs a value in a range should still check it.
111
+
112
+ ### Results with actions
113
+
114
+ A `FunctionResult` carries the text the model reads, and optionally actions for SignalWire to run. `updateGlobalData()` adds a `set_global_data` action, which stores values for the rest of the call:
115
+
116
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#check-inventory -->
117
+ ```typescript
118
+ agent.defineTool({
119
+ name: 'check_inventory',
120
+ description: 'Check product availability',
121
+ parameters: {
122
+ product_id: { type: 'string', description: 'The product ID to check' },
123
+ },
124
+ required: ['product_id'],
125
+ handler: ({ product_id }) => {
126
+ const inStock = product_id.startsWith('GPU') ? 5 : 0; // stands in for a real lookup
127
+ if (inStock === 0) {
128
+ return new FunctionResult(`Product ${product_id} is out of stock`);
129
+ }
130
+ // Keep the result in global data, where later function calls can read it
131
+ return new FunctionResult(
132
+ `Product ${product_id} is in stock (${inStock} units)`,
133
+ ).updateGlobalData({ last_checked_product: product_id, stock_level: inStock });
134
+ },
135
+ });
136
+ ```
137
+
138
+ Every later SWAIG request in the call carries the stored values in its `global_data`. For the full list of actions, see the [SWAIG reference](../../docs/swaig-reference.md).
139
+
140
+ ### Async and sync handlers
141
+
142
+ A handler can be `async`, and the SDK awaits it. Use `async` for I/O, such as an HTTP request. Keep synchronous handlers for quick work, because a long synchronous calculation blocks every other call the process is serving:
143
+
144
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#async-and-sync -->
145
+ ```typescript
146
+ // An async handler, for I/O: the event loop keeps serving other requests while it waits
147
+ agent.defineTool({
148
+ name: 'fetch_product_reviews',
149
+ description: 'Fetch the review count for a product from the review service',
150
+ parameters: {
151
+ product_id: { type: 'string', description: 'The product ID' },
152
+ },
153
+ required: ['product_id'],
154
+ handler: async ({ product_id }) => {
155
+ const base = process.env['REVIEWS_API_URL'];
156
+ if (!base) return new FunctionResult('The review service is not configured.');
157
+ const res = await fetch(`${base}/reviews/${encodeURIComponent(product_id)}`, {
158
+ signal: AbortSignal.timeout(5000),
159
+ });
160
+ if (!res.ok) return new FunctionResult('The review service is unavailable right now.');
161
+ const reviews = (await res.json()) as unknown[];
162
+ return new FunctionResult(`Found ${reviews.length} reviews for ${product_id}`);
163
+ },
164
+ });
165
+
166
+ // A synchronous handler, for quick calculations
167
+ agent.defineTool({
168
+ name: 'add_numbers',
169
+ description: 'Add two numbers',
170
+ parameters: {
171
+ x: { type: 'integer', description: 'First number' },
172
+ y: { type: 'integer', description: 'Second number' },
173
+ },
174
+ required: ['x', 'y'],
175
+ handler: ({ x, y }) => new FunctionResult(`Result: ${x + y}`),
176
+ });
177
+ ```
178
+
179
+ `AbortSignal.timeout()` stops a request that hangs. The model is waiting on the caller's behalf, so give external calls a short timeout.
180
+
181
+ ## Error handling and results
182
+
183
+ A tool that fails should still tell the model what happened, so the model can tell the caller.
184
+
185
+ ### Function error handling
186
+
187
+ Catch the errors you expect, and describe them in the result. Log the ones you don't:
188
+
189
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#process-order -->
190
+ ```typescript
191
+ class OrderError extends Error {}
192
+
193
+ agent.defineTool({
194
+ name: 'process_order',
195
+ description: 'Process customer order',
196
+ parameters: {
197
+ order_id: { type: 'string', description: 'The order ID to process' },
198
+ },
199
+ required: ['order_id'],
200
+ handler: ({ order_id }) => {
201
+ try {
202
+ // Validate input
203
+ if (order_id.length < 5) {
204
+ return new FunctionResult('Invalid order ID format');
205
+ }
206
+ if (order_id.startsWith('TEST')) {
207
+ throw new OrderError('Test orders cannot be processed');
208
+ }
209
+ return new FunctionResult(`Order ${order_id} processed successfully`);
210
+ } catch (err) {
211
+ if (err instanceof OrderError) {
212
+ return new FunctionResult(`Order processing failed: ${err.message}`);
213
+ }
214
+ // Log unexpected errors, and tell the model only that something went wrong
215
+ log.error('unexpected error processing order', { error: String(err) });
216
+ return new FunctionResult('An unexpected error occurred. Please try again.');
217
+ }
218
+ },
219
+ });
220
+ ```
221
+
222
+ A handler that throws doesn't take the agent down. The SDK logs the error and answers the model with "Sorry, I couldn't complete that action. Please try again or contact support if the issue persists." A result you write says more about what went wrong.
223
+
224
+ ### Agent-level error handling
225
+
226
+ The prompt can tell the model how to talk about a failure:
227
+
228
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#error-prompt -->
229
+ ```typescript
230
+ agent.promptAddSection('Error Handling', {
231
+ body: 'How to handle errors gracefully:',
232
+ bullets: [
233
+ 'If a function returns an error, acknowledge it politely',
234
+ 'Offer alternative solutions when possible',
235
+ 'Never expose technical error details to customers',
236
+ 'Always maintain a helpful, professional tone',
237
+ ],
238
+ });
239
+ ```
240
+
241
+ ### Validation patterns
242
+
243
+ Collect every validation problem, then report them together, so the model can ask for all the corrections at once:
244
+
245
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#update-customer -->
246
+ ```typescript
247
+ agent.defineTool({
248
+ name: 'update_customer',
249
+ description: 'Update customer information',
250
+ parameters: {
251
+ customer_id: { type: 'string', description: "The customer's ID" },
252
+ email: { type: 'string', description: "Customer's email address" },
253
+ phone: { type: 'string', description: "Customer's phone number" },
254
+ },
255
+ handler: ({ customer_id, email, phone }) => {
256
+ // Collect every problem, and report them together
257
+ const errors: string[] = [];
258
+ if (!customer_id) errors.push('Customer ID is required');
259
+ if (email && !email.includes('@')) errors.push('Invalid email format');
260
+ if (phone && phone.replace(/\D/g, '').length < 10) {
261
+ errors.push('Phone number must be at least 10 digits');
262
+ }
263
+ if (errors.length > 0) {
264
+ return new FunctionResult(`Validation failed: ${errors.join(', ')}`);
265
+ }
266
+ return new FunctionResult('Customer updated successfully');
267
+ },
268
+ });
269
+ ```
270
+
271
+ Called with an invalid email and a short phone number, the tool reports all three problems:
272
+
273
+ ```bash
274
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts \
275
+ --exec update_customer --email nope --phone 555
276
+ ```
277
+
278
+ The result lists them in one sentence:
279
+
280
+ ```text
281
+ RESULT:
282
+ Response: Validation failed: Customer ID is required, Invalid email format, Phone number must be at least 10 digits
283
+ ```
284
+
285
+ ## Logging and debugging
286
+
287
+ Logs are how you find out what an agent did on a call you weren't on.
288
+
289
+ ### Using the logger
290
+
291
+ `getLogger(name)` returns the SDK's structured logger. Each call takes a message and an object of fields, and the fields are printed as `key=value`. A handler's second parameter, `rawData`, is the whole SWAIG request, with the call ID:
292
+
293
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#logging -->
294
+ ```typescript
295
+ agent.defineTool({
296
+ name: 'normalize_part_number',
297
+ description: 'Normalize a part number to upper case',
298
+ parameters: {
299
+ part_number: { type: 'string', description: 'The part number as the caller said it' },
300
+ },
301
+ required: ['part_number'],
302
+ handler: ({ part_number }, rawData) => {
303
+ log.debug('normalize_part_number called', { call_id: rawData.call_id, part_number });
304
+ const normalized = part_number.trim().toUpperCase().replace(/\s+/g, '-');
305
+ log.info('part number normalized', { normalized });
306
+ return new FunctionResult(`The part number is ${normalized}`);
307
+ },
308
+ });
309
+ ```
310
+
311
+ ### Log levels
312
+
313
+ The SDK reads `SIGNALWIRE_LOG_LEVEL`: `debug`, `info` (the default), `warn` or `error`. Set it when you start the agent:
314
+
315
+ ```bash
316
+ SIGNALWIRE_LOG_LEVEL=debug npx tsx tutorial/multi_agents/advanced_agent.ts
317
+ ```
318
+
319
+ Set `SIGNALWIRE_LOG_MODE=off` to turn logging off, as tests often do. `new AgentServer()` sets the level from its `logLevel` option, so `pc_builder.ts` passes `SIGNALWIRE_LOG_LEVEL` through to it.
320
+
321
+ ### Debugging techniques
322
+
323
+ These four techniques cover most debugging.
324
+
325
+ **1. Request logging.** A per-call configuration callback sees every request before the agent handles it:
326
+
327
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#request-logging -->
328
+ ```typescript
329
+ // Runs on every request, on that request's copy of the agent. It logs names,
330
+ // not values: the query can carry a SWAIG token, and the body caller data.
331
+ agent.addPerCallConfig((query, body, headers) => {
332
+ log.debug('request', {
333
+ query_keys: Object.keys(query),
334
+ body_keys: Object.keys(body ?? {}),
335
+ user_agent: headers['user-agent'],
336
+ });
337
+ });
338
+ ```
339
+
340
+ **2. SWML and tool inspection.** `swaig-test` prints the SWML, and runs a tool with the arguments you give it:
341
+
342
+ ```bash
343
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts --dump-swml
344
+ npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts --exec calculate_price --amount 100
345
+ ```
346
+
347
+ Put `swaig-test`'s own options, such as `--verbose`, before `--exec`. Everything after the tool name is an argument to the tool. With `SIGNALWIRE_LOG_LEVEL=debug` and `--verbose`, the part-number tool shows the request logging and the tool's own lines:
348
+
349
+ ```bash
350
+ SIGNALWIRE_LOG_LEVEL=debug npx tsx src/cli/swaig-test.ts tutorial/multi_agents/advanced_agent.ts \
351
+ --verbose --exec normalize_part_number --part_number 'cx 4090 b'
352
+ ```
353
+
354
+ This excerpt shows the lines the file logs. The SDK's own lines, and the full request, are left out:
355
+
356
+ ```text
357
+ [DEBUG] [advanced_agent] request query_keys=["__token"] body_keys=["call_id","call","vars","params",...]
358
+ [DEBUG] [advanced_agent] normalize_part_number called call_id=82c4c94d-a7dd-4a07-9a5b-9b9edb33e3a0 part_number="cx 4090 b"
359
+ [INFO] [advanced_agent] part number normalized normalized=CX-4090-B
360
+ ```
361
+
362
+ **3. Agent state.** A handler's third parameter is the agent handling the request. With a per-call configuration callback, that's the request's configured copy:
363
+
364
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#debug-state -->
365
+ ```typescript
366
+ agent.defineTool({
367
+ name: 'debug_state',
368
+ description: 'Log the agent state',
369
+ handler: (_args, _rawData, current) => {
370
+ const state = {
371
+ agent_name: current?.getName(),
372
+ functions: current?.getTools().map((fn) => fn.name),
373
+ };
374
+ log.info('agent state', state);
375
+ return new FunctionResult('State logged to console');
376
+ },
377
+ });
378
+ ```
379
+
380
+ **4. The SWML itself.** Request it with curl, as SignalWire does, and read the prompt and tools it carries. [Lesson 3](lesson3_multi_agent_systems.md#testing-individual-agents) shows how with `jq`.
381
+
382
+ ## Production deployment
383
+
384
+ Configure a deployed agent through the environment, and keep secrets out of the code.
385
+
386
+ ### Environment variables
387
+
388
+ These are the variables a production deployment sets:
389
+
390
+ ```bash
391
+ # Credentials SignalWire uses to fetch the SWML and call the tools
392
+ export SWML_BASIC_AUTH_USER=pcbuilder
393
+ export SWML_BASIC_AUTH_PASSWORD=a-long-random-password
394
+
395
+ # Verifies that requests come from SignalWire
396
+ export SIGNALWIRE_SIGNING_KEY=your-signing-key
397
+
398
+ # Signs tool tokens, so they stay valid across restarts and replicas
399
+ export SIGNALWIRE_SWAIG_SECRET=another-long-random-value
400
+
401
+ export SIGNALWIRE_LOG_LEVEL=info
402
+
403
+ # HTTPS, or SWML_PROXY_URL_BASE when a proxy terminates TLS
404
+ export SWML_SSL_ENABLED=true
405
+ export SWML_SSL_CERT_PATH=/etc/ssl/certs/agent.crt
406
+ export SWML_SSL_KEY_PATH=/etc/ssl/private/agent.key
407
+ export SWML_SSL_DOMAIN=agents.example.com
408
+ ```
409
+
410
+ Each tool call carries a token that the agent signed when it served the SWML. Without `SIGNALWIRE_SWAIG_SECRET`, each process generates its own secret, so a restart or a second replica rejects the tokens the first one issued. For more information, see the [security guide](../../docs/security.md).
411
+
412
+ ### Docker deployment
413
+
414
+ This `Dockerfile` runs the Lesson 3 system. It builds from a project whose `package.json` depends on `@signalwire/sdk` and `tsx`, with a `package-lock.json`. List `tsx` under `dependencies`, not `devDependencies`: `npm ci --omit=dev` leaves dev dependencies out, and the image runs `tsx`.
415
+
416
+ ```dockerfile
417
+ # PC Builder Pro multi-agent service (Lesson 4).
418
+ # Build context: a project whose package.json depends on @signalwire/sdk and tsx,
419
+ # with package-lock.json, pc_builder.ts, knowledge.ts and the two knowledge files.
420
+ FROM node:22-slim
421
+
422
+ WORKDIR /app
423
+ ENV NODE_ENV=production
424
+
425
+ # Install the locked dependencies first, so a code change reuses this layer
426
+ COPY package.json package-lock.json ./
427
+ RUN npm ci --omit=dev
428
+
429
+ # Copy the application
430
+ COPY pc_builder.ts knowledge.ts sales_knowledge.md support_knowledge.md ./
431
+
432
+ # Run as the image's unprivileged user
433
+ USER node
434
+
435
+ EXPOSE 3001
436
+
437
+ # Node has fetch built in, and the slim image has no curl
438
+ HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
439
+ CMD node -e "fetch('http://localhost:3001/health').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
440
+
441
+ CMD ["./node_modules/.bin/tsx", "pc_builder.ts"]
442
+ ```
443
+
444
+ The health check uses Node's built-in `fetch`, because the slim image has no `curl`, and it fails on any status but 2xx. Build and run the image with the credentials:
445
+
446
+ ```bash
447
+ docker build -t pc-builder .
448
+ docker run -d -p 3001:3001 \
449
+ -e SWML_BASIC_AUTH_USER=pcbuilder -e SWML_BASIC_AUTH_PASSWORD=a-long-random-password \
450
+ pc-builder
451
+ ```
452
+
453
+ `docker ps` shows the container as `healthy` once `/health` answers.
454
+
455
+ ### systemd service
456
+
457
+ On a Linux host without Docker, a systemd unit keeps the service running and restarts it when it fails. This unit expects the project in `/opt/pc-builder`, and the secrets in `/etc/pc-builder/env`:
458
+
459
+ ```ini
460
+ [Unit]
461
+ Description=PC Builder Pro voice agents
462
+ After=network-online.target
463
+ Wants=network-online.target
464
+
465
+ [Service]
466
+ Type=simple
467
+ User=pcbuilder
468
+ WorkingDirectory=/opt/pc-builder
469
+ # The basic auth credentials, the signing key and the SSL paths, readable only by root
470
+ EnvironmentFile=/etc/pc-builder/env
471
+ Environment=PORT=3001
472
+ Environment=SIGNALWIRE_LOG_LEVEL=info
473
+ ExecStart=/opt/pc-builder/node_modules/.bin/tsx pc_builder.ts
474
+ Restart=always
475
+ RestartSec=10
476
+
477
+ [Install]
478
+ WantedBy=multi-user.target
479
+ ```
480
+
481
+ Save it as `/etc/systemd/system/pc-builder.service`, then run `sudo systemctl enable --now pc-builder`.
482
+
483
+ ### Health monitoring
484
+
485
+ An agent and an `AgentServer` answer `/health` without credentials. For a status page with details of your own, mount a Hono app beside the agent's routes. A mounted app isn't behind the agent's basic auth, so return nothing secret from it:
486
+
487
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#status-route -->
488
+ ```typescript
489
+ // A route of your own beside the agent's, outside its basic auth
490
+ const status = new Hono();
491
+ status.get('/', (c) =>
492
+ c.json({
493
+ status: 'healthy',
494
+ timestamp: new Date().toISOString(),
495
+ tools: agent.getTools().length,
496
+ uptime_seconds: Math.round(process.uptime()),
497
+ }),
498
+ );
499
+ agent.mount(status, { prefix: '/status' });
500
+ ```
501
+
502
+ The route answers with the agent's status:
503
+
504
+ ```bash
505
+ curl http://localhost:3000/status
506
+ ```
507
+
508
+ The output has the values the route computes:
509
+
510
+ ```json
511
+ {"status":"healthy","timestamp":"2026-09-29T17:41:42.221Z","tools":15,"uptime_seconds":6}
512
+ ```
513
+
514
+ Hono is the web framework the SDK is built on. Add it to your project's dependencies to import it.
515
+
516
+ ## Testing strategies
517
+
518
+ Test the tools directly, then the agent over HTTP. These examples use vitest, and come from `tests/tutorial/multi_agents-lessons.test.ts`.
519
+
520
+ ### Unit testing functions
521
+
522
+ `agent.getTool(name)` returns a registered tool, and `execute()` runs its handler as the SWAIG endpoint does:
523
+
524
+ <!-- snippet: no-compile a region of tests/tutorial/multi_agents-lessons.test.ts; the test file itself is type-checked and run --> <!-- include: tests/tutorial/multi_agents-lessons.test.ts#unit-test -->
525
+ ```typescript
526
+ it('calculates the price with tax', async () => {
527
+ const fn = advanced.getTool('calculate_price')!;
528
+ const result = await fn.execute({ amount: 100, tax_rate: 0.08 });
529
+ expect(result['response']).toBe('The total price is $108.00 ($100.00 + $8.00 tax)');
530
+
531
+ // The tax rate is optional, and defaults to 8%
532
+ const noRate = await fn.execute({ amount: 50 });
533
+ expect(noRate['response']).toContain('$54.00');
534
+ });
535
+ ```
536
+
537
+ `execute()` returns the response the agent would send, with `response`, and `action` when the result has actions.
538
+
539
+ ### Integration testing
540
+
541
+ `agent.getApp()` returns the agent's HTTP app, and its `request()` sends a request without a server or a port. This test checks the credentials and the SWML:
542
+
543
+ <!-- snippet: no-compile a region of tests/tutorial/multi_agents-lessons.test.ts; the test file itself is type-checked and run --> <!-- include: tests/tutorial/multi_agents-lessons.test.ts#integration-test -->
544
+ ```typescript
545
+ it('serves SWML that lists calculate_price, and refuses a request without credentials', async () => {
546
+ const app = advanced.getApp();
547
+ expect((await app.request('/')).status).toBe(401);
548
+
549
+ const res = await app.request('/', { headers: AUTH });
550
+ expect(res.status).toBe(200);
551
+ const swml = (await res.json()) as Swml;
552
+ const ai = swml.sections.main.find((verb) => verb.ai)!.ai!;
553
+ const names = ai.SWAIG.functions.map((f) => f.function);
554
+ expect(names).toContain('calculate_price');
555
+ });
556
+ ```
557
+
558
+ To call a tool over HTTP as SignalWire does, read the tool's `web_hook_url` from the SWML, and POST to it with the token it carries. `tests/tutorial/multi_agents.test.ts` does that for every agent in this tutorial.
559
+
560
+ A test can also run `swaig-test` itself, as `tests/tutorial/multi_agents-lessons.test.ts` does with `execFileSync`.
561
+
562
+ ### Load testing
563
+
564
+ Apache Bench sends concurrent requests to the SWML route. Pass the credentials with `-A`:
565
+
566
+ ```bash
567
+ ab -n 1000 -c 10 -A devuser:devpassword http://localhost:3000/
568
+ ```
569
+
570
+ On a development machine, the agent served all 1000 requests. These are the lines of the report that matter:
571
+
572
+ ```text
573
+ Complete requests: 1000
574
+ Failed requests: 0
575
+ Requests per second: 480.98 [#/sec] (mean)
576
+ Time per request: 20.791 [ms] (mean)
577
+ ```
578
+
579
+ Load-test the tools that call slow services too, because those set how many calls one process can serve.
580
+
581
+ ## Performance optimization
582
+
583
+ Most of a tool's time goes to the services it calls, so start there.
584
+
585
+ ### Caching strategies
586
+
587
+ Cache a slow lookup in a `Map`, with an expiry time on each entry:
588
+
589
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#caching -->
590
+ ```typescript
591
+ // Stands in for a slow database or API call
592
+ async function lookupProduct(productId: string): Promise<string> {
593
+ await new Promise((resolve) => setTimeout(resolve, 200));
594
+ return `Product ${productId}: 16GB DDR5 memory kit`;
595
+ }
596
+
597
+ const productCache = new Map<string, { value: string; expires: number }>();
598
+ const CACHE_TTL_MS = 5 * 60 * 1000;
599
+
600
+ agent.defineTool({
601
+ name: 'get_product_info',
602
+ description: 'Get product information',
603
+ parameters: {
604
+ product_id: { type: 'string', description: 'The product ID to look up' },
605
+ },
606
+ required: ['product_id'],
607
+ handler: async ({ product_id }) => {
608
+ const cached = productCache.get(product_id);
609
+ if (cached && cached.expires > Date.now()) {
610
+ log.debug('cache hit', { product_id });
611
+ return new FunctionResult(cached.value);
612
+ }
613
+ const info = await lookupProduct(product_id);
614
+ productCache.set(product_id, { value: info, expires: Date.now() + CACHE_TTL_MS });
615
+ return new FunctionResult(info);
616
+ },
617
+ });
618
+ ```
619
+
620
+ The cache is per process. With several replicas, each has its own. Use a shared cache such as Redis when the replicas must agree.
621
+
622
+ ### Running independent work concurrently
623
+
624
+ `Promise.all()` runs independent lookups at the same time, so the tool takes as long as the slowest one, not the sum of all three:
625
+
626
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#concurrent -->
627
+ ```typescript
628
+ // Stand-ins for three independent services
629
+ const getOrders = async (id: string) => [`${id}-order-1`, `${id}-order-2`];
630
+ const getProfile = async (id: string) => ({ id, tier: 'gold' });
631
+ const getPreferences = async (id: string) => ({ id, contact: 'email' });
632
+
633
+ agent.defineTool({
634
+ name: 'get_full_info',
635
+ description: 'Get complete customer information',
636
+ parameters: {
637
+ customer_id: { type: 'string', description: 'The customer ID' },
638
+ },
639
+ required: ['customer_id'],
640
+ handler: async ({ customer_id }) => {
641
+ // The three lookups run at the same time, not one after another
642
+ const [orders, profile, preferences] = await Promise.all([
643
+ getOrders(customer_id),
644
+ getProfile(customer_id),
645
+ getPreferences(customer_id),
646
+ ]);
647
+ return new FunctionResult(
648
+ `Found ${orders.length} orders for a ${profile.tier} customer who prefers ${preferences.contact}`,
649
+ );
650
+ },
651
+ });
652
+ ```
653
+
654
+ Awaiting them one after another would add up the three wait times.
655
+
656
+ ### Memory management
657
+
658
+ A few habits keep a long-running agent's memory flat:
659
+
660
+ - Keep search results small. Lesson 2's `count: 3` returns three sections, not the whole knowledge base.
661
+ - Give per-call state an end. Lesson 5 deletes an order when it's confirmed.
662
+ - Put an expiry on caches, as the product cache does, and a size limit if the key space is large.
663
+
664
+ ## Security best practices
665
+
666
+ Tool arguments come from the model, which takes them from what the caller said. Treat them as untrusted input.
667
+
668
+ ### Input sanitization
669
+
670
+ Strip the characters a query doesn't need, and cap the length, before you use caller-supplied text:
671
+
672
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#sanitize -->
673
+ ```typescript
674
+ const catalog = ['RTX 4070', 'RTX 4090', 'Ryzen 7 7700X', 'Z790 motherboard'];
675
+
676
+ agent.defineTool({
677
+ name: 'safe_search',
678
+ description: 'Search the product catalog',
679
+ parameters: {
680
+ query: { type: 'string', description: 'Search query' },
681
+ },
682
+ required: ['query'],
683
+ handler: ({ query }) => {
684
+ // Keep letters, digits, spaces and hyphens, and at most 100 characters
685
+ const safeQuery = query
686
+ .replace(/[^\w\s-]/g, '')
687
+ .trim()
688
+ .slice(0, 100);
689
+ if (!safeQuery) return new FunctionResult('Invalid search query');
690
+ const results = catalog.filter((item) => item.toLowerCase().includes(safeQuery.toLowerCase()));
691
+ return new FunctionResult(`Found ${results.length} results: ${results.join(', ')}`);
692
+ },
693
+ });
694
+ ```
695
+
696
+ For a database, use parameterized queries, as Lesson 5's SQLite example does, instead of building SQL from strings.
697
+
698
+ ### Secrets management
699
+
700
+ Read secrets from the environment, and never log them or put them in a prompt:
701
+
702
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#secrets -->
703
+ ```typescript
704
+ // Read secrets from the environment, and never log them
705
+ const apiKey = process.env['PARTNER_API_KEY'];
706
+ if (!apiKey) log.warn('PARTNER_API_KEY not set');
707
+
708
+ agent.defineTool({
709
+ name: 'check_partner_stock',
710
+ description: 'Check stock at the partner warehouse',
711
+ parameters: {
712
+ sku: { type: 'string', description: 'The product SKU' },
713
+ },
714
+ required: ['sku'],
715
+ handler: async ({ sku }) => {
716
+ const base = process.env['PARTNER_API_URL'];
717
+ if (!apiKey || !base) return new FunctionResult('The partner API is not configured.');
718
+ log.info('calling partner API', { sku }); // the key stays out of the log
719
+ const res = await fetch(`${base}/stock/${encodeURIComponent(sku)}`, {
720
+ headers: { Authorization: `Bearer ${apiKey}` },
721
+ signal: AbortSignal.timeout(5000),
722
+ });
723
+ return new FunctionResult(
724
+ res.ok ? `Partner stock for ${sku}: ${await res.text()}` : 'Unable to check partner stock.',
725
+ );
726
+ },
727
+ });
728
+ ```
729
+
730
+ ### Rate limiting
731
+
732
+ Limit how often one caller can run an expensive tool. Key the limit by the caller's number from the request, not by an argument, because the model fills in arguments:
733
+
734
+ <!-- snippet: no-compile a region of tutorial/multi_agents/advanced_agent.ts; the file itself is type-checked --> <!-- include: tutorial/multi_agents/advanced_agent.ts#rate-limit -->
735
+ ```typescript
736
+ // Calls per caller in the last minute. The caller comes from the request
737
+ // SignalWire sends, not from an argument the model fills in.
738
+ const callTimes = new Map<string, number[]>();
739
+ const LIMIT_PER_MINUTE = 10;
740
+
741
+ agent.defineTool({
742
+ name: 'limited_function',
743
+ description: 'A function each caller may run 10 times a minute',
744
+ handler: (_args, rawData) => {
745
+ const caller = rawData.caller_id_num ?? rawData.call_id ?? 'unknown';
746
+ const now = Date.now();
747
+ const recent = (callTimes.get(caller) ?? []).filter((t) => t > now - 60_000);
748
+ if (recent.length >= LIMIT_PER_MINUTE) {
749
+ callTimes.set(caller, recent);
750
+ return new FunctionResult('Rate limit exceeded. Please try again later.');
751
+ }
752
+ recent.push(now);
753
+ callTimes.set(caller, recent);
754
+ return new FunctionResult('Function executed successfully');
755
+ },
756
+ });
757
+ ```
758
+
759
+ To limit requests per client address on all of the agent's routes as well, set `SWML_RATE_LIMIT` to the number of requests a minute to allow. SignalWire's own requests count too, so set it well above your call volume.
760
+
761
+ ### Request verification
762
+
763
+ Set `SIGNALWIRE_SIGNING_KEY` in production. With it, the agent checks the signature SignalWire puts on each request, and refuses a request that doesn't have a valid one. Without it, the agent logs a warning at startup.
764
+
765
+ ## Summary
766
+
767
+ This lesson covered what an agent needs before production. The main points:
768
+
769
+ - `defineTool()` takes parameters as JSON Schema, and infers the handler's argument types from them
770
+ - A `FunctionResult` tells the model what happened, and carries actions such as `updateGlobalData()`
771
+ - Handle expected errors in the handler, and let the SDK's generic message cover the rest
772
+ - `getLogger()` gives structured logs, and `swaig-test` runs tools without a call
773
+ - The environment carries the credentials, the signing key, the token secret and the SSL settings
774
+ - `getTool().execute()` and `getApp().request()` test an agent without a server
775
+
776
+ ### Practice exercises
777
+
778
+ Try these before you move on:
779
+
780
+ 1. **Build a calculator agent**: add, subtract, multiply and divide tools, with a clear result for division by zero.
781
+ 2. **Add caching**: cache the review service's answers in `fetch_product_reviews`.
782
+ 3. **Extend the status route**: report whether the knowledge base loaded, and how many sections it has.
783
+ 4. **Review an agent**: find every place a tool uses an argument without checking it.
784
+
785
+ ### Production checklist
786
+
787
+ Check each item before the agent takes real calls:
788
+
789
+ - [ ] Credentials, signing key and token secret set from the environment
790
+ - [ ] HTTPS served by the agent, or by a proxy with `SWML_PROXY_URL_BASE` set
791
+ - [ ] Log level set, and no secrets in the logs
792
+ - [ ] Every tool returns a useful result on failure
793
+ - [ ] Health checks point at `/health`
794
+ - [ ] Monitoring and alerts set up
795
+ - [ ] Load tested, including the slow tools
796
+ - [ ] Tool arguments validated
797
+ - [ ] Tests pass
798
+
799
+ ### Next steps
800
+
801
+ Next, write a skill of your own, and keep state across a call. Continue with [Lesson 5: Extending Your Agents](lesson5_extending_agents.md).
802
+
803
+ ---
804
+
805
+ [Previous: Lesson 3 - Building Multi-Agent Systems](lesson3_multi_agent_systems.md) | [Tutorial Overview](README.md) | [Next: Lesson 5 - Extending Your Agents](lesson5_extending_agents.md)