@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,298 @@
1
+ # LLM Parameters Guide
2
+
3
+ This guide covers the LLM parameters of a SignalWire AI agent's main prompt and post-prompt, and how to set them with the TypeScript SDK.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module (top-level await)
8
+ declare global {
9
+ const agent: import('@signalwire/sdk').AgentBase;
10
+ const AgentBase: typeof import('@signalwire/sdk').AgentBase; // used with `extends`
11
+ }
12
+ ```
13
+
14
+ ## Overview
15
+
16
+ The SDK has one method for the main prompt's LLM parameters and one for the post-prompt's. The SDK writes the parameters into the SWML `prompt` and `post_prompt` objects, next to the prompt text.
17
+
18
+ **Important:** The SDK doesn't validate these parameters. It passes every key and value through to SignalWire unchanged, so a misspelled key or an out-of-range value reaches the platform as written.
19
+
20
+ ## Available Methods
21
+
22
+ ### `setPromptLlmParams(params)`
23
+
24
+ `setPromptLlmParams()` merges parameters into the main prompt:
25
+
26
+ ```typescript
27
+ agent.setPromptLlmParams({
28
+ temperature: 0.7,
29
+ top_p: 0.9,
30
+ presence_penalty: 0.0,
31
+ frequency_penalty: 0.0,
32
+ });
33
+ ```
34
+
35
+ ### `setPostPromptLlmParams(params)`
36
+
37
+ `setPostPromptLlmParams()` merges parameters into the post-prompt, which produces the call summary:
38
+
39
+ ```typescript
40
+ agent.setPostPromptLlmParams({
41
+ temperature: 0.3,
42
+ top_p: 0.95,
43
+ presence_penalty: 0.0,
44
+ frequency_penalty: 0.0,
45
+ });
46
+ ```
47
+
48
+ Both methods merge into the parameters already set, so you can call them more than once. A later value for the same key replaces the earlier one.
49
+
50
+ The prompt objects are separate from the `ai` verb's `params`, which `setParam()` and `setParams()` set. `temperature` and the other keys in this guide belong in the prompt objects.
51
+
52
+ ## Parameter Reference
53
+
54
+ The SWML schema defines these parameters for both `prompt` and `post_prompt`. The ranges and defaults come from the schema bundled with the SDK (`src/schema.json`):
55
+
56
+ | Parameter | Type | Range | Default | Description |
57
+ |---|---|---|---|---|
58
+ | `temperature` | number | 0.0 to 1.5 | 1.0 | Randomness. Values closer to 0 make the output less random. |
59
+ | `top_p` | number | 0.0 to 1.0 | 1.0 | Nucleus sampling, an alternative to `temperature`. Values closer to 0 make the output less random. |
60
+ | `presence_penalty` | number | -2.0 to 2.0 | 0 | Aversion to staying on a topic. Positive values make new topics more likely. |
61
+ | `frequency_penalty` | number | -2.0 to 2.0 | 0 | Aversion to repeating lines. Positive values make verbatim repetition less likely. |
62
+ | `confidence` | number | 0.0 to 1.0 | 0.6 | Threshold for the speech-detect event at the end of an utterance. Lower values shorten the pause after the caller speaks, and can add false positives. |
63
+ | `max_tokens` | integer | 0 to 4096 | 256 | Limit on the tokens the model may generate for a response. |
64
+
65
+ The defaults are the platform's. The SDK sends a parameter only when you set it.
66
+
67
+ ### temperature
68
+
69
+ `temperature` controls how random the responses are. These ranges are guidance, not rules:
70
+
71
+ - **Lower values (for example, 0.0 to 0.3)**: more deterministic and consistent responses
72
+ - **Middle values (for example, 0.4 to 0.7)**: a balance of variety and consistency
73
+ - **Higher values (for example, 0.8 and up)**: more varied and less predictable responses
74
+
75
+ ### top_p
76
+
77
+ `top_p` limits token selection to the most likely tokens whose probabilities add up to the value:
78
+
79
+ - **Lower values (for example, 0.1 to 0.5)**: only the most likely tokens
80
+ - **Middle values (for example, 0.6 to 0.9)**: a balanced selection
81
+ - **Higher values (for example, 0.95 to 1.0)**: a wider range of tokens
82
+
83
+ ### presence_penalty
84
+
85
+ `presence_penalty` penalizes tokens that already appear in the conversation:
86
+
87
+ - **Negative values**: encourage returning to the same topics
88
+ - **Zero**: no penalty
89
+ - **Positive values**: discourage repetition, and encourage new topics
90
+
91
+ ### frequency_penalty
92
+
93
+ `frequency_penalty` penalizes tokens by how often they appear in the conversation:
94
+
95
+ - **Negative values**: encourage repeating the same words
96
+ - **Zero**: no penalty
97
+ - **Positive values**: discourage word repetition
98
+
99
+ ### Interruption
100
+
101
+ How easily the caller can interrupt the AI isn't an LLM parameter. `barge_confidence` isn't in the SWML schema's `prompt` object, so a document that sets it there fails validation against the SWML schema, and the platform doesn't apply it. Tune interruption with these AI params, through `setParam()`:
102
+
103
+ - **`barge_min_words`** (1 to 99): how many words the caller must say before the AI stops speaking. Higher values make the AI harder to interrupt.
104
+ - **`enable_barge`**: which barge modes are on: `"complete"`, `"partial"`, `"all"`, or a boolean. `false` turns barge-in off.
105
+ - **`barge_match_string`**: a string or regular expression that interrupts the AI when the caller says it.
106
+
107
+ ```typescript
108
+ agent.setParam('barge_min_words', 3); // Let the AI finish unless the caller says 3 or more words
109
+ ```
110
+
111
+ ## Use Case Examples
112
+
113
+ ### Customer Service Agent
114
+
115
+ A low temperature and a small penalty keep the responses consistent:
116
+
117
+ ```typescript
118
+ import { AgentBase } from '@signalwire/sdk';
119
+
120
+ class CustomerServiceAgent extends AgentBase {
121
+ constructor() {
122
+ super({ name: 'customer-service', route: '/support' });
123
+
124
+ this.promptAddSection('Role', {
125
+ body: 'You are a professional customer service representative.',
126
+ });
127
+
128
+ // Consistent, helpful responses
129
+ this.setPromptLlmParams({
130
+ temperature: 0.3, // Low randomness for consistency
131
+ top_p: 0.9, // Focused token selection
132
+ presence_penalty: 0.1, // Slight penalty to avoid repetition
133
+ frequency_penalty: 0.1, // Encourage varied language
134
+ });
135
+ }
136
+ }
137
+ ```
138
+
139
+ ### Creative Writing Assistant
140
+
141
+ A higher temperature and a wider `top_p` suit an agent that should vary its answers:
142
+
143
+ ```typescript
144
+ class CreativeWritingAgent extends AgentBase {
145
+ constructor() {
146
+ super({ name: 'creative-writer', route: '/writer' });
147
+
148
+ this.promptAddSection('Role', { body: 'You are a creative writing assistant.' });
149
+
150
+ // Varied responses
151
+ this.setPromptLlmParams({
152
+ temperature: 0.8, // Higher randomness for variety
153
+ top_p: 0.95, // Wide token selection
154
+ presence_penalty: -0.1, // Allow topic revisiting
155
+ frequency_penalty: 0.3, // Encourage vocabulary diversity
156
+ });
157
+ }
158
+ }
159
+ ```
160
+
161
+ ### Technical Documentation Bot
162
+
163
+ A low temperature keeps technical answers precise, and the post-prompt uses a lower one still:
164
+
165
+ ```typescript
166
+ class TechnicalDocsAgent extends AgentBase {
167
+ constructor() {
168
+ super({ name: 'tech-docs', route: '/docs' });
169
+
170
+ this.promptAddSection('Role', { body: 'You are a technical documentation assistant.' });
171
+
172
+ // Precise responses
173
+ this.setPromptLlmParams({
174
+ temperature: 0.2, // Low randomness
175
+ top_p: 0.8, // More focused token selection
176
+ presence_penalty: 0.0, // Neutral on repetition
177
+ frequency_penalty: 0.2, // Some vocabulary variety
178
+ max_tokens: 400, // Room for longer explanations
179
+ });
180
+
181
+ // Even more focused for summaries
182
+ this.setPostPromptLlmParams({ temperature: 0.1 });
183
+ }
184
+ }
185
+ ```
186
+
187
+ ### Legal Information Bot
188
+
189
+ A legal information agent repeats legal terms on purpose, so it sets no penalties:
190
+
191
+ ```typescript
192
+ class LegalAdvisorAgent extends AgentBase {
193
+ constructor() {
194
+ super({ name: 'legal-advisor', route: '/legal' });
195
+
196
+ this.promptAddSection('Role', { body: 'You are a legal information assistant.' });
197
+ this.promptAddSection('Disclaimer', {
198
+ body: 'Always remind users to consult a real attorney.',
199
+ });
200
+
201
+ // Cautious, precise responses
202
+ this.setPromptLlmParams({
203
+ temperature: 0.2, // Consistent
204
+ top_p: 0.85, // Focused selection
205
+ presence_penalty: 0.0, // Allow legal term repetition
206
+ frequency_penalty: 0.0, // Legal language often repeats
207
+ });
208
+ }
209
+ }
210
+ ```
211
+
212
+ ## Best Practices
213
+
214
+ ### 1. Start with the Platform Defaults
215
+
216
+ Set nothing at first, and adjust based on the behavior you observe.
217
+
218
+ ### 2. Change One Thing at a Time
219
+
220
+ Make small changes and test each one, so you know which change had which effect.
221
+
222
+ ### 3. Match the Use Case
223
+
224
+ These starting points are guidance, not measured values:
225
+
226
+ - **Customer service**: low temperature (0.2 to 0.4)
227
+ - **Creative tasks**: higher temperature (0.7 to 0.9)
228
+ - **Technical or legal**: the lowest temperatures (0.1 to 0.3)
229
+ - **General assistant**: middle temperature (0.5 to 0.7)
230
+
231
+ ### 4. Lower the Post-Prompt Temperature
232
+
233
+ A post-prompt usually produces a structured summary, so a lower temperature than the main prompt's keeps it consistent.
234
+
235
+ ## Parameter Interactions
236
+
237
+ ### Temperature and top_p
238
+
239
+ Both parameters control randomness, and they combine:
240
+
241
+ - Low temperature and low `top_p`: the most focused responses
242
+ - High temperature and high `top_p`: the most variety
243
+ - Low temperature and high `top_p`: consistent, with some alternatives available
244
+ - High temperature and low `top_p`: varied, within a narrow token set
245
+
246
+ ### Penalty Parameters
247
+
248
+ The two penalties can be used together:
249
+
250
+ - Both positive: stronger push toward variety
251
+ - Both negative: stronger push toward repetition
252
+ - Mixed: finer control over which kind of repetition is allowed
253
+
254
+ ## Troubleshooting
255
+
256
+ ### The AI Repeats Itself
257
+
258
+ These changes reduce repetition:
259
+
260
+ - Increase `presence_penalty` (try 0.3 to 0.6)
261
+ - Increase `frequency_penalty` (try 0.3 to 0.6)
262
+ - Increase `temperature` slightly
263
+
264
+ ### The AI Is Too Random or Inconsistent
265
+
266
+ These changes make the output steadier:
267
+
268
+ - Decrease `temperature` (try 0.2 to 0.4)
269
+ - Decrease `top_p` (try 0.7 to 0.85)
270
+
271
+ ### Interruptions
272
+
273
+ Interruption behavior is set in the `ai` verb's `params`, not in the prompt objects:
274
+
275
+ - If background noise interrupts the AI, raise `barge_min_words`, as in `agent.setParam('barge_min_words', 3)`.
276
+ - If callers can't interrupt the AI, lower `barge_min_words`, and check that `enable_barge` isn't `false`.
277
+
278
+ See also `barge_match_string` and `interrupt_on_noise` in the SWML schema.
279
+
280
+ ## Parameter Behavior
281
+
282
+ **No defaults from the SDK:** The SDK sends no LLM parameters unless you set them with `setPromptLlmParams()` or `setPostPromptLlmParams()`. Without them, the platform uses its own defaults.
283
+
284
+ **No validation in the SDK:** The SDK accepts any key and passes it through unchanged. A parameter the platform adds later works without an SDK update, and a typo isn't caught.
285
+
286
+ **Partial configuration:** You can set only the parameters you want to change:
287
+
288
+ ```typescript
289
+ // Only set temperature; the platform handles the rest
290
+ agent.setPromptLlmParams({ temperature: 0.7 });
291
+
292
+ // Or set several specific parameters
293
+ agent.setPromptLlmParams({ temperature: 0.5, top_p: 0.9 });
294
+ ```
295
+
296
+ ## Related
297
+
298
+ For the rest of `AgentBase`'s configuration, including `setParams()` for the `ai` verb's other parameters, see the [Agent Guide](agent-guide.md).
@@ -0,0 +1,354 @@
1
+ # MCP to SWAIG Gateway
2
+
3
+ <!-- snippet-setup -->
4
+
5
+ ```ts
6
+ export {}; // treat each example as a module (top-level await)
7
+ declare global {
8
+ const agent: import('@signalwire/sdk').AgentBase;
9
+ const McpGatewaySkill: typeof import('@signalwire/sdk').McpGatewaySkill;
10
+ }
11
+ ```
12
+
13
+ ## Overview
14
+
15
+ The MCP-SWAIG gateway lets a SignalWire AI agent call tools on Model Context Protocol (MCP) servers that run as local processes, through SWAIG functions.
16
+
17
+ There are two pieces:
18
+
19
+ 1. **The gateway service**: a standalone HTTP server that starts MCP server processes, keeps a session per call, and translates between the two protocols. The TypeScript SDK doesn't include one. The Python SDK ships one as the `mcp-gateway` command (`pip install "signalwire-sdk[mcp-gateway]"`). Deploy it once and point your agents at it.
20
+ 2. **`McpGatewaySkill`**: a built-in skill in the TypeScript SDK that connects an agent to a running gateway, lists each service's tools, and registers them as SWAIG functions.
21
+
22
+ This page covers the skill's configuration and behavior, and the gateway endpoints the skill calls. To give a call the tools of an MCP server that speaks HTTP, you don't need a gateway: see [MCP Integration](mcp_integration.md).
23
+
24
+ ## Installation (SDK Side)
25
+
26
+ `McpGatewaySkill` ships with the SDK, so no extra package is required:
27
+
28
+ ```bash
29
+ npm install @signalwire/sdk
30
+ ```
31
+
32
+ Add it to an agent like any other built-in skill. `addSkill()` runs the skill's setup, which contacts the gateway, so it needs a gateway that's running:
33
+
34
+ <!-- snippet: no-run instantiating the `mcp_gateway` builtin requires live credentials/network at setup — cannot run standalone -->
35
+
36
+ ```typescript
37
+ import { AgentBase, McpGatewaySkill } from '@signalwire/sdk';
38
+
39
+ const agent = new AgentBase({ name: 'mcp-agent' });
40
+
41
+ await agent.addSkill(
42
+ new McpGatewaySkill({
43
+ gateway_url: 'https://mcp-gateway.example.com',
44
+ auth_user: 'admin',
45
+ auth_password: process.env.MCP_GATEWAY_AUTH_PASSWORD,
46
+ services: [{ name: 'todo' }],
47
+ }),
48
+ );
49
+ ```
50
+
51
+ `agent.addSkillByName('mcp_gateway', { ... })` takes the same configuration.
52
+
53
+ ## Architecture
54
+
55
+ ### Components
56
+
57
+ The gateway and the skill divide the work this way:
58
+
59
+ 1. **MCP gateway service** (standalone server)
60
+ - HTTP or HTTPS server with basic or bearer-token authentication
61
+ - Starts and manages MCP server processes
62
+ - Keeps a session per SignalWire call
63
+ - Translates between SWAIG and MCP
64
+
65
+ 2. **`McpGatewaySkill`** (`src/skills/builtin/mcp_gateway.ts`)
66
+ - Checks the gateway's health and lists each service's tools during setup
67
+ - Registers each MCP tool as a SWAIG function named `<tool_prefix><service>_<tool>` (default prefix `mcp_`)
68
+ - Registers an internal `_mcp_gateway_hangup` tool, marked `is_hangup_hook`, that closes the call's MCP session
69
+
70
+ ## Protocol Flow
71
+
72
+ A tool call passes through these steps between the agent, the gateway and the MCP server:
73
+
74
+ ```text
75
+ SignalWire Agent Gateway Service MCP Server
76
+ | | |
77
+ |---(1) Add Skill--------------->| |
78
+ |<--(2) Query Tools--------------| |
79
+ | |---(3) List Tools-------->|
80
+ | |<--(4) Tool List----------|
81
+ |---(5) Call SWAIG Function----->| |
82
+ | |---(6) Spawn Session----->|
83
+ | |---(7) Call MCP Tool----->|
84
+ | |<--(8) MCP Response-------|
85
+ |<--(9) SWAIG Response-----------| |
86
+ | | |
87
+ |---(10) Hangup Hook------------>| |
88
+ | |---(11) Close Session---->|
89
+ ```
90
+
91
+ ## Message Envelope Format
92
+
93
+ When a registered tool runs, the skill POSTs this body to the gateway's `/services/<name>/call` endpoint. The service name is part of the URL, not the body:
94
+
95
+ ```json
96
+ {
97
+ "tool": "add_todo",
98
+ "arguments": { "text": "Buy milk" },
99
+ "session_id": "call_xyz123",
100
+ "timeout": 300,
101
+ "metadata": {
102
+ "agent_id": "mcp-agent",
103
+ "timestamp": "2026-09-28T10:30:00Z",
104
+ "call_id": "call_xyz123"
105
+ }
106
+ }
107
+ ```
108
+
109
+ The fields come from these sources:
110
+
111
+ - `session_id`: `global_data.mcp_call_id` when it's a string, otherwise the SWAIG request's `call_id`, otherwise `unknown`.
112
+ - `timeout`: the `session_timeout` setting.
113
+ - `metadata.agent_id`: the agent's name. `metadata.timestamp` and `metadata.call_id` are copied from the SWAIG request, and left out when it has none.
114
+
115
+ ## Skill Configuration
116
+
117
+ `McpGatewaySkill` takes these configuration keys, in `snake_case` like every skill's configuration:
118
+
119
+ ```typescript
120
+ await agent.addSkill(
121
+ new McpGatewaySkill({
122
+ gateway_url: 'https://mcp-gateway.example.com', // required
123
+ auth_user: 'admin', // basic auth (or use auth_token)
124
+ auth_password: process.env.MCP_GATEWAY_AUTH_PASSWORD,
125
+ // auth_token: process.env.MCP_GATEWAY_AUTH_TOKEN, // bearer token instead of basic auth
126
+ services: [
127
+ { name: 'todo', tools: ['add_todo', 'list_todos'] }, // these tools only
128
+ { name: 'calculator', tools: '*' }, // all tools
129
+ ],
130
+ session_timeout: 300, // sent to the gateway as each call's timeout, in seconds
131
+ tool_prefix: 'mcp_', // prefix for SWAIG function names
132
+ retry_attempts: 3, // attempts per tool call
133
+ request_timeout: 30, // per-request timeout in seconds
134
+ verify_ssl: true, // TLS certificate verification
135
+ }),
136
+ );
137
+ ```
138
+
139
+ | Key | Type | Default | Description |
140
+ | -------------------- | ------- | --------------------------- | -------------------------------------------------------------------------------------------------------- |
141
+ | `gateway_url` | string | (required) | URL of the gateway service. A trailing slash is removed. |
142
+ | `auth_token` | string | `MCP_GATEWAY_AUTH_TOKEN` | Bearer token. When set, it's used instead of basic auth. |
143
+ | `auth_user` | string | `MCP_GATEWAY_AUTH_USER` | Basic auth username. Required when there's no token. |
144
+ | `auth_password` | string | `MCP_GATEWAY_AUTH_PASSWORD` | Basic auth password. Required when there's no token. |
145
+ | `services` | array | `[]` | Services to connect to, each `{ name, tools? }`. `tools` is `'*'` (the default) or a list of tool names. |
146
+ | `session_timeout` | integer | `300` | Session timeout in seconds, sent in each call's envelope |
147
+ | `tool_prefix` | string | `mcp_` | Prefix for registered SWAIG function names |
148
+ | `retry_attempts` | integer | `3` | Attempts per tool call, the first one included |
149
+ | `request_timeout` | integer | `30` | Timeout for each request to the gateway, in seconds |
150
+ | `verify_ssl` | boolean | `true` | Verify the gateway's TLS certificate. `false` has an effect only with `allow_insecure_tls`. |
151
+ | `allow_insecure_tls` | boolean | `false` | Second switch needed to turn verification off. Both must be set to accept any certificate. |
152
+
153
+ The Default column names the environment variable the skill reads when a credential key is missing.
154
+
155
+ When `services` is empty, the skill requests the gateway's `/services` endpoint and connects to every service it lists.
156
+
157
+ ### Safe Defaults
158
+
159
+ The skill's defaults refuse the two riskiest configurations:
160
+
161
+ - **Private addresses**: the skill refuses a `gateway_url` that resolves to a private, loopback or link-local address, including `localhost`. A configuration value can't point it at an internal service. Every request to the gateway is checked the same way, including each redirect, and connects only to an address it checked. This holds with `allow_insecure_tls` on too: it skips only the certificate check. For a gateway on the same host or a private network, set `SWML_ALLOW_PRIVATE_URLS=true` in the agent's environment. [Security](security.md#outbound-url-protection-ssrf) lists the refused ranges.
162
+ - **Certificate verification**: `verify_ssl: false` alone leaves verification on and logs a warning. To accept a self-signed certificate, also set `allow_insecure_tls: true`. The agent then accepts any certificate from the gateway, so a machine in the network path can read and change the traffic. The address checks on every request and redirect still apply.
163
+
164
+ The skill sends the credentials on every request to the gateway, including the health check. Use an `https://` gateway URL outside a private network.
165
+
166
+ ## What the Skill Registers
167
+
168
+ After setup, the skill adds these items to the agent:
169
+
170
+ - **One SWAIG function per MCP tool**, named `<tool_prefix><service>_<tool>`, with the description `[<service>] <tool description>`. Each top-level property of the tool's input schema becomes a parameter with its `type` (default `string`), `description`, `enum` and, for optional parameters, `default`. Nested schemas (`properties` of an object, `items` of an array) aren't copied.
171
+ - **The `_mcp_gateway_hangup` tool**, marked `is_hangup_hook`, which sends `DELETE /sessions/<session_id>` when the call ends.
172
+ - **Global data**: `mcp_gateway_url`, `mcp_services` and `mcp_session_id` (always `null`).
173
+ - **A prompt section** titled "MCP Gateway Integration" that lists the gateway URL and the services.
174
+ - **Speech hints**: `MCP`, `gateway` and each service name.
175
+
176
+ When setup succeeds but finds no tool, for example because `/services` failed, the skill registers a single `mcp_invoke` tool. Its response says the gateway isn't configured.
177
+
178
+ ## Gateway Service Configuration
179
+
180
+ The gateway service reads its own configuration file, whose format depends on the gateway you deploy. The Python SDK's gateway reads a `config.json` that substitutes environment variables with `${VAR_NAME|default}` syntax. This is an example of that format:
181
+
182
+ ```json
183
+ {
184
+ "server": {
185
+ "host": "${MCP_HOST|0.0.0.0}",
186
+ "port": "${MCP_PORT|8080}",
187
+ "auth_user": "${MCP_AUTH_USER|admin}",
188
+ "auth_password": "${MCP_AUTH_PASSWORD}",
189
+ "auth_token": "${MCP_AUTH_TOKEN}"
190
+ },
191
+ "services": {
192
+ "todo": {
193
+ "command": ["node", "./test/todo_mcp.js"],
194
+ "description": "Simple todo list for testing",
195
+ "enabled": true
196
+ },
197
+ "calculator": {
198
+ "command": ["node", "/path/to/calculator.js"],
199
+ "description": "Math calculations",
200
+ "enabled": true
201
+ }
202
+ },
203
+ "session": {
204
+ "default_timeout": 300,
205
+ "max_sessions_per_service": 100,
206
+ "cleanup_interval": 60
207
+ }
208
+ }
209
+ ```
210
+
211
+ ## API Endpoints (Gateway Service)
212
+
213
+ The skill calls these endpoints on the gateway, with its credentials on each request.
214
+
215
+ #### GET /health
216
+
217
+ Health check. The skill calls it during setup, and setup fails unless it returns a 2xx status:
218
+
219
+ ```bash
220
+ curl https://mcp-gateway.example.com/health
221
+ ```
222
+
223
+ #### GET /services
224
+
225
+ Lists the available services as an object keyed by service name. The skill calls it when `services` is empty:
226
+
227
+ ```bash
228
+ curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" https://mcp-gateway.example.com/services
229
+ ```
230
+
231
+ #### GET /services/{serviceName}/tools
232
+
233
+ Returns a service's tools as `{ "tools": [...] }`, each with a `name`, a `description` and an `inputSchema`:
234
+
235
+ ```bash
236
+ curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" https://mcp-gateway.example.com/services/todo/tools
237
+ ```
238
+
239
+ #### POST /services/{serviceName}/call
240
+
241
+ Calls a tool on a service. This request uses basic auth:
242
+
243
+ ```bash
244
+ curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" -X POST https://mcp-gateway.example.com/services/todo/call \
245
+ -H "Content-Type: application/json" \
246
+ -d '{
247
+ "tool": "add_todo",
248
+ "arguments": {"text": "Test item"},
249
+ "session_id": "test-123",
250
+ "timeout": 300
251
+ }'
252
+ ```
253
+
254
+ This request uses a bearer token:
255
+
256
+ ```bash
257
+ curl -X POST https://mcp-gateway.example.com/services/todo/call \
258
+ -H "Authorization: Bearer $MCP_GATEWAY_AUTH_TOKEN" \
259
+ -H "Content-Type: application/json" \
260
+ -d '{
261
+ "tool": "add_todo",
262
+ "arguments": {"text": "Test item"},
263
+ "session_id": "test-123"
264
+ }'
265
+ ```
266
+
267
+ The skill reads the `result` field of a `200` response. A string is used as the tool's response, another value is sent as its JSON, and a missing field becomes `No response`.
268
+
269
+ #### DELETE /sessions/{sessionId}
270
+
271
+ Closes a session. The skill's hangup hook calls it, and treats `200` and `404` as success:
272
+
273
+ ```bash
274
+ curl -u "admin:$MCP_GATEWAY_AUTH_PASSWORD" -X DELETE https://mcp-gateway.example.com/sessions/test-123
275
+ ```
276
+
277
+ ## Testing
278
+
279
+ ### Testing with the swaig-test CLI
280
+
281
+ `swaig-test` loads the agent file, which runs the skill's setup against the gateway. Put `--call-id` before `--exec`, since everything after the function name is an argument to the function. Using the same call ID for each call keeps the calls in one gateway session:
282
+
283
+ ```bash
284
+ # List the registered MCP tools
285
+ npx tsx src/cli/swaig-test.ts test/test-agent.ts --list-tools
286
+
287
+ # Call two tools in the same session
288
+ npx tsx src/cli/swaig-test.ts test/test-agent.ts --call-id test-session --exec mcp_todo_add_todo --text "Buy milk"
289
+ npx tsx src/cli/swaig-test.ts test/test-agent.ts --call-id test-session --exec mcp_todo_list_todos
290
+
291
+ # Print the SWML document
292
+ npx tsx src/cli/swaig-test.ts test/test-agent.ts --dump-swml
293
+ ```
294
+
295
+ ### End-to-End Test Agent
296
+
297
+ This agent connects to a gateway on the same machine, so its environment needs `SWML_ALLOW_PRIVATE_URLS=true` for setup to accept the `localhost` URL:
298
+
299
+ <!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port) — collides under the concurrent gate and cannot run standalone -->
300
+
301
+ ```typescript
302
+ // test/test-agent.ts
303
+ import { AgentBase, McpGatewaySkill } from '@signalwire/sdk';
304
+
305
+ class TestMcpAgent extends AgentBase {
306
+ static async create(): Promise<TestMcpAgent> {
307
+ const agent = new TestMcpAgent({ name: 'MCP Test Agent' });
308
+ await agent.addSkill(
309
+ new McpGatewaySkill({
310
+ gateway_url: 'http://localhost:8080',
311
+ auth_user: 'admin',
312
+ auth_password: process.env.MCP_GATEWAY_AUTH_PASSWORD,
313
+ services: [{ name: 'todo' }],
314
+ }),
315
+ );
316
+ return agent;
317
+ }
318
+ }
319
+
320
+ const agent = await TestMcpAgent.create();
321
+ await agent.run();
322
+ ```
323
+
324
+ ## Implementation Details
325
+
326
+ ### Session Management
327
+
328
+ The gateway, not the skill, keeps session state. The skill's part is to send a stable `session_id`:
329
+
330
+ 1. **Session creation**: the first tool call with a new `session_id` creates a session on the gateway.
331
+ 2. **Session persistence**: later tool calls in the same call send the same `session_id`, so they reach the same session.
332
+ 3. **Session cleanup**: the hangup hook sends `DELETE /sessions/{id}` when the call ends.
333
+ 4. **State isolation**: each session gets its own MCP server process on the gateway.
334
+
335
+ ### Error Handling
336
+
337
+ A tool call makes up to `retry_attempts` attempts, the first one included:
338
+
339
+ 1. **Server errors (5xx)**: retried.
340
+ 2. **Client errors (4xx)**: returned without a retry.
341
+ 3. **Timeouts and network errors**: retried. Other exceptions stop the attempts.
342
+ 4. **Final failure**: the tool's response is `Failed to call <service>.<tool>: <error>`. The error is the gateway's `error` field, or the status and the start of the body.
343
+
344
+ ## Troubleshooting
345
+
346
+ 1. **`Failed to setup skill 'mcp_gateway'`**: `addSkill()` throws this when setup fails. The log gives the reason: a missing `gateway_url` or credentials, a URL refused as private, a health check that didn't return 2xx, or a connection error.
347
+ 2. **`gateway_url rejected by SSRF protection`**: the URL resolves to a private or loopback address. Set `SWML_ALLOW_PRIVATE_URLS=true` if the gateway is on a private network.
348
+ 3. **Authentication failures**: check that `auth_user` and `auth_password`, or `auth_token`, match the gateway's configuration.
349
+ 4. **TLS certificate errors**: give the gateway a certificate from a trusted CA. For a self-signed certificate on a private network, set both `verify_ssl: false` and `allow_insecure_tls: true`.
350
+ 5. **Lost session state**: check that the gateway keeps the MCP process alive between tool calls, and that each call sends the same `session_id`.
351
+
352
+ ## Related Pages
353
+
354
+ For MCP servers that SignalWire can reach over HTTP, which need no gateway, see [MCP Integration](mcp_integration.md). For the address ranges the skill refuses, see [Security](security.md#outbound-url-protection-ssrf).