@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,501 @@
1
+ # SignalWire AI Agents SDK: Why the SDK, Not Raw SWML
2
+
3
+ <!-- snippet-setup -->
4
+ ```ts
5
+ export {}; // treat each example as a module (top-level await)
6
+ declare global {
7
+ const agent: import('@signalwire/sdk').AgentBase;
8
+ const AgentBase: typeof import('@signalwire/sdk').AgentBase;
9
+ const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
10
+ const MyAgent: any; // illustrative user-defined AgentBase subclass
11
+ const SalesAgent: any;
12
+ const SupportAgent: any;
13
+ const TriageAgent: any;
14
+ const loadTenantConfig: (tenant: string) => any;
15
+ }
16
+ ```
17
+
18
+ ## The Problem with Raw SWML
19
+
20
+ SWML (SignalWire Markup Language) is a JSON document format that defines what happens during a call. The bundled SWML schema defines 39 verbs, and the `ai` verb alone has dozens of parameters. An AI agent's document also carries SWAIG (SignalWire AI Gateway) function definitions with JSON Schema, post-prompt URLs, webhook credentials and language arrays. It can also hold pronunciation rules, hints, global data, contexts, steps and gather configurations.
21
+
22
+ Writing it by hand means building nested JSON, assembling authenticated webhook URLs, writing parameter schemas, and running a separate webhook server for your tools. With the SDK, you write TypeScript. The SDK generates the SWML, serves it over HTTP, and handles its own webhook callbacks, all in one process.
23
+
24
+ ---
25
+
26
+ ## The Self-Referencing Pipeline
27
+
28
+ The agent is both the **SWML generator** and the **SWAIG webhook handler**, in a single microservice. A call moves through the pipeline in five steps:
29
+
30
+ 1. SignalWire requests the SWML, and the agent generates the document.
31
+ 2. The document's webhook URLs point back to the agent.
32
+ 3. When the AI calls a function, SignalWire posts to the agent's `/swaig` endpoint.
33
+ 4. The agent runs the function and returns the result to the AI.
34
+ 5. When the call ends, SignalWire posts the post-prompt result to the agent's `/post_prompt` endpoint.
35
+
36
+ The agent builds its own public URL for the webhooks. Behind a proxy or tunnel, set `SWML_PROXY_URL_BASE`. Or set `SWML_TRUST_PROXY_HEADERS=true`, and the agent reads `X-Forwarded-Host`, `Forwarded` or `X-Original-Host`. It puts the basic-auth credentials in the webhook URLs, and a per-call token in the URL of each secure function. This agent needs none of that code:
37
+
38
+ <!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
39
+ ```typescript
40
+ import { AgentBase, FunctionResult } from '@signalwire/sdk';
41
+
42
+ class WeatherAgent extends AgentBase {
43
+ constructor() {
44
+ super({ name: 'weather', route: '/weather' });
45
+ this.promptAddSection('Role', { body: 'You help with weather.' });
46
+ }
47
+
48
+ protected override defineTools(): void {
49
+ this.defineTool({
50
+ name: 'get_weather',
51
+ description: 'Get weather',
52
+ parameters: {
53
+ city: { type: 'string', description: 'City name' },
54
+ },
55
+ required: ['city'],
56
+ handler: async (args) => {
57
+ const city = args.city as string;
58
+ // ... fetch weather ...
59
+ return new FunctionResult(`72°F and sunny in ${city}`);
60
+ },
61
+ });
62
+ }
63
+ }
64
+
65
+ const agent = new WeatherAgent();
66
+ await agent.run();
67
+ ```
68
+
69
+ The class is a complete agent: an HTTP server, SWML generation, authenticated webhook routing and function execution. The generated SWML holds the AI configuration, the function schemas, and webhook URLs that point back to the running process.
70
+
71
+ ---
72
+
73
+ ## Prompt Object Model (POM)
74
+
75
+ Raw SWML prompts are strings. The SDK builds structured prompts from sections:
76
+
77
+ ```typescript
78
+ agent.promptAddSection('Role', { body: 'You are a travel booking assistant.' });
79
+ agent.promptAddSection('Rules', {
80
+ bullets: [
81
+ 'Never make up flight information',
82
+ 'Always confirm before booking',
83
+ 'Use the search tool for real data',
84
+ ],
85
+ });
86
+ agent.promptAddSection('Personality', { body: 'Friendly but professional.' });
87
+ ```
88
+
89
+ You can add subsections (`promptAddSubsection`), append to a section (`promptAddToSection`), and check whether a section exists (`promptHasSection`). Skills add their own sections the same way.
90
+
91
+ ---
92
+
93
+ ## Tools: Three Ways
94
+
95
+ ### 1. `defineTool` (Local Execution)
96
+
97
+ `defineTool()` registers a handler that runs in the agent's process:
98
+
99
+ <!-- snippet: no-compile fragment from inside a subclass defineTools(); uses `this` and an illustrative `db` -->
100
+ ```typescript
101
+ this.defineTool({
102
+ name: 'lookup_order',
103
+ description: 'Look up an order',
104
+ parameters: {
105
+ order_id: { type: 'string', description: 'Order identifier' },
106
+ },
107
+ required: ['order_id'],
108
+ handler: async (args) => {
109
+ const order = await db.get(args.order_id as string);
110
+ const result = new FunctionResult(`Order ${order.id}: ${order.status}`);
111
+ result.updateGlobalData({ current_order: order });
112
+ return result;
113
+ },
114
+ });
115
+ ```
116
+
117
+ The SDK turns this into a SWAIG function definition with JSON Schema parameters. Tools are secure by default, so each one's webhook URL carries a per-call token. The SDK routes the POST requests to the handler, parses the arguments, and formats the response. A `FunctionResult` can also carry actions for the platform, such as a transfer, a hold, a context switch or a change to the active functions.
118
+
119
+ When `parameters` is a flat inline map, as in the example, TypeScript infers the handler's `args`. `args.order_id` is typed `string`, required keys are present, and an `enum` property narrows to its literal union. `defineTypedTool()` registers a handler that takes named parameters. Without explicit `parameters`, it infers the schema from the handler's source: its parameter names and default values.
120
+
121
+ ### 2. DataMap (Server-Side Execution)
122
+
123
+ A DataMap tool declares an API call, and SignalWire's servers make it:
124
+
125
+ ```typescript
126
+ import { DataMap, FunctionResult } from '@signalwire/sdk';
127
+
128
+ const dataMap = new DataMap('check_stock')
129
+ .purpose('Check product stock levels')
130
+ .parameter('sku', 'string', 'Product SKU', { required: true })
131
+ .webhook('GET', 'https://api.warehouse.com/stock/${args.sku}')
132
+ .output(new FunctionResult('Stock for ${input.args.sku}: ${quantity} units'));
133
+
134
+ agent.registerSwaigFunction(dataMap.toSwaigFunction());
135
+ ```
136
+
137
+ The agent never receives a callback for a DataMap tool. The SDK writes the `data_map` structure into the SWML, and the platform expands its templates. `${args.*}` reads the arguments in the URL and params, and `${input.args.*}` in the webhook's output, where the response's fields are read from the root, such as `${quantity}`. The SDK also supports foreach iteration, expression matching and error keys. For the full builder API, see the [DataMap Guide](datamap-guide.md).
138
+
139
+ ### 3. Skills (Packaged Integrations)
140
+
141
+ A skill packages tools, prompt sections and hints behind one `addSkill()` call:
142
+
143
+ ```typescript
144
+ import { WebSearchSkill, DateTimeSkill, MathSkill } from '@signalwire/sdk';
145
+
146
+ await agent.addSkill(new WebSearchSkill({ num_results: 5 }));
147
+ await agent.addSkill(new DateTimeSkill());
148
+ await agent.addSkill(new MathSkill());
149
+ ```
150
+
151
+ The skill registers its tools, adds its prompt sections and speech hints, and checks its dependencies. `addSkill()` takes a skill **instance** and is **async**. `WebSearchSkill` reads its Google credentials from `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_ENGINE_ID` when you don't pass `api_key` and `search_engine_id`.
152
+
153
+ ---
154
+
155
+ ## The Skills System
156
+
157
+ Skills are modules that package tools, prompt sections, hints and configuration. A skill has these parts:
158
+
159
+ - It extends `SkillBase`, and returns its tools from `getTools()` or registers them with `defineTool()`. An optional async `setup()` runs when the skill loads.
160
+ - It declares `REQUIRED_PACKAGES` and `REQUIRED_ENV_VARS`, which the skill manager checks at load time.
161
+ - It can add prompt sections by overriding `_getPromptSections()`.
162
+ - It can provide speech hints with `getHints()`, and global data with `getGlobalData()`.
163
+ - With `SUPPORTS_MULTIPLE_INSTANCES`, it can load more than once with different configurations, such as two search skills.
164
+
165
+ The SDK registers 19 built-in skills. Seventeen match the Python reference set: `DateTimeSkill`, `MathSkill`, `JokeSkill`, `WeatherApiSkill`, `PlayBackgroundFileSkill`, `SwmlTransferSkill`, `ApiNinjasTriviaSkill`, `InfoGathererSkill`, `WebSearchSkill`, `WikipediaSearchSkill`, `GoogleMapsSkill`, `DataSphereSkill`, `DataSphereServerlessSkill`, `NativeVectorSearchSkill`, `SpiderSkill`, `ClaudeSkillsSkill` and `McpGatewaySkill`. The other two, `CustomSkillsSkill` and `AskClaudeSkill`, are TypeScript additions (see `PORT_ADDITIONS.md`).
166
+
167
+ Skills don't know about each other, and they register into the same agent. One agent can combine web search, datetime, a custom booking tool and a DataMap stock checker. For the full reference, see the [Skills System Guide](skills-guide.md).
168
+
169
+ ---
170
+
171
+ ## Contexts and Steps: Priming the State Machine
172
+
173
+ Contexts and steps define a conversation's workflow declaratively. Each step lists the tools the model can use and the steps it can move to:
174
+
175
+ ```typescript
176
+ const ctx = agent.defineContexts();
177
+
178
+ const greeting = ctx.addContext('default');
179
+
180
+ greeting
181
+ .addStep('welcome')
182
+ .setText('Greet the user and ask how you can help.')
183
+ .setValidSteps(['collect_info'])
184
+ .setFunctions(['check_hours']); // Only this tool available here
185
+
186
+ greeting
187
+ .addStep('collect_info')
188
+ .setText("Collect the user's name and email.")
189
+ .setStepCriteria('User has provided both name and email')
190
+ .setFunctions('none') // Without this, the step keeps check_hours
191
+ .setValidSteps(['confirm']);
192
+
193
+ greeting
194
+ .addStep('confirm')
195
+ .setText('Confirm the information and say goodbye.')
196
+ .setFunctions([]); // No tools in this step
197
+ ```
198
+
199
+ The SDK renders this as the SWML contexts structure. The platform offers the model only the tools and transitions each step lists. The model can't call a tool the step doesn't list, or move where the step doesn't allow. Those tools and transitions aren't offered to it. This is PGI (Programmatically Governed Inference) in practice. For the full API, see the [Contexts Guide](contexts-guide.md).
200
+
201
+ **Multi-context** agents can define separate conversation modes, such as `sales` and `support`, each with its own tools, and control switching with `setValidContexts()`.
202
+
203
+ ---
204
+
205
+ ## Programmatically Governed Inference (PGI)
206
+
207
+ Contexts and steps are the SDK's implementation of a broader discipline: **Programmatically Governed Inference**. PGI starts from one design rule: *don't tell the AI anything it doesn't need to know.*
208
+
209
+ Current AI models handle language well. They understand loosely phrased input, map intent onto structured actions, and turn system decisions back into natural speech. They're also inconsistent, non-deterministic and prone to confident error. These are properties of probabilistic inference, not bugs a later model generation will fix. A common response is to write longer prompts and hope the model follows them ("prompt and pray"). That treats the model as the brain of the system. PGI treats the model as one participant inside a deterministic system that stays in charge.
210
+
211
+ ### The Four Layers
212
+
213
+ PGI works through four layers of constraint, each independent of the others. Only the first depends on the model's cooperation. The other three are mechanical.
214
+
215
+ **Layer 1: Semantic Constraints**. The model receives a prompt that describes its role and how to behave. This is the weakest layer, because it depends on the model complying. PGI treats it as guidance, not enforcement.
216
+
217
+ **Layer 2: Schema Constraints**. At each step, the model sees only the tools listed for that step. Tools that belong to other steps aren't in its function schema, so it can't call them.
218
+
219
+ **Layer 3: Transition Constraints**. Each step defines which steps the model may move to, and the platform offers the model only those. The model can't skip phases or jump to unreachable states. Trusted code can still move the conversation: a tool handler's `swmlChangeStep()` isn't limited by the list, so the application decides when a phase ends.
220
+
221
+ **Layer 4: Execution Authority**. A tool call from the model is a request. The tool handler reads authoritative state, applies business logic, and returns a response for the model and a set of actions for the platform to run. The model doesn't update state; the handler and the platform do.
222
+
223
+ ### PGI in Practice: Blackjack
224
+
225
+ A blackjack dealer agent gives each phase of the game its own step and its own tools:
226
+
227
+ <!-- snippet: no-run illustrative fragment: references the assumed `agent` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
228
+ ```typescript
229
+ const game = agent.defineContexts().addContext('default');
230
+
231
+ const betting = game.addStep('betting').setText("Take the player's bet.");
232
+ betting.setFunctions(['place_bet']).setValidSteps(['playing']);
233
+
234
+ const playing = game.addStep('playing').setText('Play the hand.');
235
+ playing.setFunctions(['hit', 'stand', 'double_down']).setValidSteps(['betting']);
236
+
237
+ const lost = game.addStep('you_lost').setText('Tell the player the game is over.');
238
+ lost.setFunctions('none');
239
+ ```
240
+
241
+ During the betting step, the model can call only `place_bet`. It can't deal, draw or resolve hands, because those functions aren't in its schema. When the conversation moves to the playing step, `place_bet` goes away and `hit`, `stand` and `double_down` appear.
242
+
243
+ The `you_lost` step has no functions, and nothing in the flow leads out of it. A tool handler moves the conversation there, and the model has no part in that decision:
244
+
245
+ <!-- snippet: no-compile fragment from inside a subclass defineTools(); uses `this`, `GameState`, `calculateHand` -->
246
+ ```typescript
247
+ this.defineTool({
248
+ name: 'hit',
249
+ description: 'Draw a card.',
250
+ parameters: {},
251
+ handler: (args, rawData) => {
252
+ const globalData = rawData.global_data as Record<string, unknown>;
253
+ const game = globalData.game_state as GameState;
254
+ const card = game.deck.pop()!;
255
+ game.player_hand.push(card);
256
+ const score = calculateHand(game.player_hand);
257
+
258
+ const result = new FunctionResult(`The player drew ${formatCard(card)}. The total is ${score}.`);
259
+ result.updateGlobalData({ game_state: game });
260
+
261
+ if (score > 21) {
262
+ result.swmlChangeStep('you_lost');
263
+ }
264
+ return result;
265
+ },
266
+ });
267
+ ```
268
+
269
+ The model gets the result as context and decides what to say. The platform changes the step.
270
+
271
+ ### Why PGI, Not Guardrails
272
+
273
+ Under PGI, the model has no view of the governance. It isn't told that other tools exist elsewhere in the system. It sees its current prompt, its current functions and the conversation history, and works within them. There is no hidden rule for it to reason around. The model makes the interaction natural, and the software makes it correct.
274
+
275
+ ---
276
+
277
+ ## Deployment: One `run()` Call
278
+
279
+ `run()` picks the mode from the environment:
280
+
281
+ <!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
282
+ ```typescript
283
+ const agent = new MyAgent();
284
+ await agent.run();
285
+ ```
286
+
287
+ These are the environments it detects:
288
+
289
+ | Environment | Detection | What Happens |
290
+ |-------------|-----------|--------------|
291
+ | **Standalone** | Default | Starts the Hono HTTP server via `@hono/node-server` |
292
+ | **AWS Lambda** | `AWS_LAMBDA_FUNCTION_NAME` / `_HANDLER` | Returns a Lambda-formatted response |
293
+ | **Google Cloud Functions** | `K_SERVICE` / `FUNCTION_TARGET` | Returns a GCF-compatible response |
294
+ | **Azure Functions** | `FUNCTIONS_WORKER_RUNTIME` | Returns an Azure HTTP response |
295
+ | **CGI** | `GATEWAY_INTERFACE` | Reads stdin, writes stdout |
296
+
297
+ When it detects a serverless environment, or you pass an `event`, `run()` calls `runServerless(event, context, platform)`. Otherwise it starts the HTTP server with `serve()`. For a fixed mode, call `serve()` or `runServerless()` directly.
298
+
299
+ In standalone mode, the agent provides these:
300
+
301
+ - Health (`/health`) and readiness (`/ready`) endpoints, without auth
302
+ - CORS configuration through `SWML_CORS_ORIGINS`
303
+ - Debug events at `/debug_events`, after `enableDebugEvents()`
304
+
305
+ `AgentBase.serve()` serves HTTPS when `SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH` are set, and plain HTTP otherwise. A TLS-terminating proxy in front of the agent works too.
306
+
307
+ ---
308
+
309
+ ## Multi-Agent Hosting
310
+
311
+ `AgentServer` hosts several agents in one process:
312
+
313
+ <!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
314
+ ```typescript
315
+ import { AgentServer } from '@signalwire/sdk';
316
+
317
+ const server = new AgentServer({ host: '0.0.0.0', port: 3000 });
318
+ server.register(new SalesAgent(), '/sales');
319
+ server.register(new SupportAgent(), '/support');
320
+ server.register(new TriageAgent(), '/triage');
321
+ await server.run();
322
+ ```
323
+
324
+ Each agent gets its own SWML endpoint and SWAIG routes under its route. SIP routing can map usernames to specific agents.
325
+
326
+ ---
327
+
328
+ ## Dynamic Configuration and Multi-Tenancy
329
+
330
+ A dynamic config callback configures the agent for each request, for example per tenant:
331
+
332
+ ```typescript
333
+ agent.setDynamicConfigCallback((queryParams, bodyParams, headers, copy) => {
334
+ const tenant = headers['x-tenant-id'] ?? 'default';
335
+ const config = loadTenantConfig(tenant);
336
+ copy.promptAddSection('Company', { body: config.companyInfo });
337
+ copy.setGlobalData({ tenant_id: tenant, tier: config.tier });
338
+ });
339
+ ```
340
+
341
+ For each request, the SDK makes a per-request copy of the agent and passes it to the callback. The callback can give the copy its own prompt, global data, languages and tools. The SWML is rendered from the copy, and the `/swaig` and `/post_prompt` requests of the call run on it. The original agent isn't modified. One deployment can serve many tenants this way. `addPerCallConfig()` registers more callbacks that run on the same copy.
342
+
343
+ ---
344
+
345
+ ## Document Search Skills
346
+
347
+ `NativeVectorSearchSkill` indexes documents in the agent's process:
348
+
349
+ ```typescript
350
+ import { NativeVectorSearchSkill } from '@signalwire/sdk';
351
+
352
+ await agent.addSkill(
353
+ new NativeVectorSearchSkill({
354
+ documents: [
355
+ { id: 'faq-1', text: 'To reset your password, go to Settings > Security.' },
356
+ { id: 'faq-2', text: 'Business hours are Monday-Friday, 9am-5pm EST.' },
357
+ ],
358
+ }),
359
+ );
360
+ ```
361
+
362
+ It scores the documents supplied in its configuration with in-memory TF-IDF, and needs no external service or API key. For search hosted by SignalWire, `DataSphereSkill` and `DataSphereServerlessSkill` query SignalWire DataSphere. `WikipediaSearchSkill` and `WebSearchSkill` search the web. For more, see the [Skills System Guide](skills-guide.md).
363
+
364
+ ---
365
+
366
+ ## Prefab Agents
367
+
368
+ Prefab agents package common patterns:
369
+
370
+ ```typescript
371
+ import { InfoGathererAgent, ReceptionistAgent } from '@signalwire/sdk';
372
+
373
+ // Collect structured data
374
+ const gatherer = new InfoGathererAgent({
375
+ questions: [
376
+ { key_name: 'name', question_text: 'What is your name?' },
377
+ { key_name: 'issue', question_text: 'Describe your issue', confirm: true },
378
+ ],
379
+ });
380
+
381
+ // Route calls to departments
382
+ const receptionist = new ReceptionistAgent({
383
+ departments: [
384
+ { name: 'Sales', number: '+15551234567', description: 'Product inquiries' },
385
+ { name: 'Support', number: '+15559876543', description: 'Technical help' },
386
+ ],
387
+ });
388
+ ```
389
+
390
+ The SDK has five prefabs: `InfoGathererAgent`, `SurveyAgent`, `ReceptionistAgent`, `FAQBotAgent` and `ConciergeAgent`. Each generates SWML with its own prompts, tools and workflow. For more, see the [Prefabs Guide](prefabs-guide.md).
391
+
392
+ ---
393
+
394
+ ## AI Configuration
395
+
396
+ The SDK has methods for the `ai` verb's settings:
397
+
398
+ ```typescript
399
+ // LLM sampling for the main prompt
400
+ agent.setPromptLlmParams({ temperature: 0.3, top_p: 0.9 });
401
+
402
+ // Multi-language
403
+ agent.addLanguage({
404
+ name: 'Spanish',
405
+ code: 'es',
406
+ voice: 'google.es-ES-Neural2-A',
407
+ });
408
+
409
+ // Speech recognition
410
+ agent.addHints(['SignalWire', 'SWML', 'SWAIG']);
411
+ agent.addPronunciation({ replace: 'SignalWire', with: 'Signal Wire' });
412
+
413
+ // Vision, thinking
414
+ agent.setParams({ enable_vision: true });
415
+ agent.setParams({ enable_thinking: true });
416
+
417
+ // Interruption control
418
+ agent.setParams({
419
+ barge_match_string: '^(stop|cancel|nevermind)$',
420
+ barge_min_words: 2,
421
+ });
422
+
423
+ // Native functions with custom fillers
424
+ agent.setNativeFunctions(['check_time', 'wait_for_user']);
425
+ agent.addInternalFiller('check_time', 'en-US', ['Let me check the time...']);
426
+
427
+ // Call flow verbs
428
+ agent.addPreAnswerVerb('play', { url: 'https://cdn.example.com/ringback.wav', auto_answer: false });
429
+ agent.addPostAiVerb('hangup', {});
430
+ ```
431
+
432
+ The constructor options `recordCall`, `recordFormat` and `recordStereo` add a `record_call` verb after the answer:
433
+
434
+ ```typescript
435
+ const agent = new AgentBase({ name: 'recorded', recordCall: true, recordFormat: 'wav', recordStereo: true });
436
+ ```
437
+
438
+ Without the SDK, each of these means writing the matching SWML JSON by hand.
439
+
440
+ ---
441
+
442
+ ## swaig-test CLI
443
+
444
+ `swaig-test` inspects and runs an agent without deploying it. In the repository, run it with `npx tsx src/cli/swaig-test.ts`:
445
+
446
+ ```bash
447
+ # List available tools
448
+ npx tsx src/cli/swaig-test.ts examples/mcp-agent.ts --list-tools
449
+
450
+ # Execute a specific tool (options go before --exec; the function's arguments after it)
451
+ npx tsx src/cli/swaig-test.ts examples/mcp-agent.ts --exec get_weather --location "San Francisco"
452
+
453
+ # Dump generated SWML for inspection
454
+ npx tsx src/cli/swaig-test.ts examples/mcp-agent.ts --dump-swml
455
+ ```
456
+
457
+ The `--exec` command prints the tool's result:
458
+
459
+ ```text
460
+ RESULT:
461
+ Response: Currently 72F and sunny in San Francisco.
462
+ ```
463
+
464
+ For the full set of options, see the [CLI Guide](cli-guide.md).
465
+
466
+ ---
467
+
468
+ ## Authentication
469
+
470
+ The SDK sets up authentication and request checks for you:
471
+
472
+ - **Basic auth**: from the `basicAuth` constructor option, a config file, or `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD`. With none of those, the SDK generates a password that exists only in the process, and logs a warning.
473
+ - **Credentials in URLs**: the webhook URLs include `user:password@host`, so SignalWire can call back.
474
+ - **Per-function tokens**: each secure function's URL gets a `__token` query parameter, an HMAC over the call, the function and an expiry. Set `SIGNALWIRE_SWAIG_SECRET` so tokens survive restarts and work across replicas.
475
+ - **Webhook signatures**: with a Signing Key (`signingKey` or `SIGNALWIRE_SIGNING_KEY`), the agent rejects POST requests without a valid SignalWire signature.
476
+
477
+ ---
478
+
479
+ ## What You'd Have to Build Without the SDK
480
+
481
+ This table compares the work with and without the SDK:
482
+
483
+ | Capability | Without SDK | With SDK |
484
+ |-----------|-------------|----------|
485
+ | SWML document | Hand-craft JSON | Generated from TypeScript |
486
+ | Webhook server | Build and deploy separately | Built into the agent process |
487
+ | URL routing | Manual Hono/Express setup | Automatic route registration |
488
+ | Auth tokens | Manual token system | Generated per call and function |
489
+ | Proxy URL | Build webhook URLs yourself | `SWML_PROXY_URL_BASE`, or trusted proxy headers |
490
+ | Tool schemas | Write JSON Schema by hand | `defineTool()` / `defineTypedTool()` |
491
+ | Serverless deploy | Platform-specific handler code | `agent.run()` detects the platform |
492
+ | Multi-language | Build language arrays by hand | `addLanguage()` |
493
+ | State machine | Build contexts JSON by hand | Fluent `defineContexts()` API |
494
+ | Search | Build the pipeline | `addSkill(new NativeVectorSearchSkill(...))` |
495
+ | Multi-agent | Separate deployments and a router | `AgentServer` with route registration |
496
+ | Dynamic config | Custom middleware | `setDynamicConfigCallback()` and `addPerCallConfig()` |
497
+ | Post-call analytics | Parse the raw webhook payload | `onSummary()` hook |
498
+ | Health checks | Manual endpoints | Built-in `/health` and `/ready` |
499
+ | Call recording | Insert the SWML verb by hand | `recordCall: true` constructor option |
500
+
501
+ With the SDK, an agent is one TypeScript class. You write what the agent does, and the SDK generates the SWML, routes the webhooks, and handles authentication and deployment.