@signalwire/sdk 2.0.1 → 2.0.3

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 (610) hide show
  1. package/dist/AgentBase.d.ts +1045 -0
  2. package/dist/AgentBase.js +2375 -0
  3. package/dist/AgentBase.js.map +1 -0
  4. package/dist/AgentServer.d.ts +146 -0
  5. package/dist/AgentServer.js +388 -0
  6. package/dist/AgentServer.js.map +1 -0
  7. package/dist/AuthHandler.d.ts +127 -0
  8. package/dist/AuthHandler.js +212 -0
  9. package/dist/AuthHandler.js.map +1 -0
  10. package/dist/ConfigLoader.d.ts +170 -0
  11. package/dist/ConfigLoader.js +393 -0
  12. package/dist/ConfigLoader.js.map +1 -0
  13. package/dist/ContextBuilder.d.ts +652 -0
  14. package/dist/ContextBuilder.js +1115 -0
  15. package/dist/ContextBuilder.js.map +1 -0
  16. package/dist/DataMap.d.ts +271 -0
  17. package/dist/DataMap.js +430 -0
  18. package/dist/DataMap.js.map +1 -0
  19. package/dist/FunctionResult.d.ts +481 -0
  20. package/dist/FunctionResult.js +775 -0
  21. package/dist/FunctionResult.js.map +1 -0
  22. package/dist/Logger.d.ts +113 -0
  23. package/dist/Logger.js +320 -0
  24. package/dist/Logger.js.map +1 -0
  25. package/dist/PomBuilder.d.ts +208 -0
  26. package/dist/PomBuilder.js +409 -0
  27. package/dist/PomBuilder.js.map +1 -0
  28. package/dist/PromptManager.d.ts +85 -0
  29. package/dist/PromptManager.js +108 -0
  30. package/dist/PromptManager.js.map +1 -0
  31. package/dist/SWMLHandler.d.ts +159 -0
  32. package/dist/SWMLHandler.js +229 -0
  33. package/dist/SWMLHandler.js.map +1 -0
  34. package/dist/SWMLService.d.ts +326 -0
  35. package/dist/SWMLService.js +610 -0
  36. package/dist/SWMLService.js.map +1 -0
  37. package/dist/SchemaUtils.d.ts +108 -0
  38. package/dist/SchemaUtils.js +317 -0
  39. package/dist/SchemaUtils.js.map +1 -0
  40. package/dist/SecurityUtils.d.ts +60 -0
  41. package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
  42. package/dist/SecurityUtils.js.map +1 -0
  43. package/dist/ServerlessAdapter.d.ts +119 -0
  44. package/dist/ServerlessAdapter.js +188 -0
  45. package/dist/ServerlessAdapter.js.map +1 -0
  46. package/dist/SessionManager.d.ts +142 -0
  47. package/dist/SessionManager.js +260 -0
  48. package/dist/SessionManager.js.map +1 -0
  49. package/dist/SslConfig.d.ts +77 -0
  50. package/dist/SslConfig.js +100 -0
  51. package/dist/SslConfig.js.map +1 -0
  52. package/dist/SwaigFunction.d.ts +159 -0
  53. package/dist/SwaigFunction.js +209 -0
  54. package/dist/SwaigFunction.js.map +1 -0
  55. package/dist/SwmlBuilder.d.ts +165 -0
  56. package/dist/SwmlBuilder.js +247 -0
  57. package/dist/SwmlBuilder.js.map +1 -0
  58. package/dist/SwmlVerbMethods.generated.d.ts +254 -0
  59. package/dist/SwmlVerbMethods.generated.js +9 -0
  60. package/dist/SwmlVerbMethods.generated.js.map +1 -0
  61. package/dist/TypeInference.d.ts +71 -0
  62. package/dist/TypeInference.js +164 -0
  63. package/dist/TypeInference.js.map +1 -0
  64. package/dist/WebService.d.ts +148 -0
  65. package/dist/WebService.js +532 -0
  66. package/dist/WebService.js.map +1 -0
  67. package/dist/cli/agent-loader.d.ts +22 -0
  68. package/dist/cli/agent-loader.js +144 -0
  69. package/dist/cli/agent-loader.js.map +1 -0
  70. package/dist/cli/mock-data.d.ts +37 -0
  71. package/dist/cli/mock-data.js +80 -0
  72. package/dist/cli/mock-data.js.map +1 -0
  73. package/dist/cli/swaig-test.d.ts +32 -0
  74. package/dist/cli/swaig-test.js +418 -0
  75. package/dist/cli/swaig-test.js.map +1 -0
  76. package/dist/generateVerbTypes.d.ts +11 -0
  77. package/dist/generateVerbTypes.js +265 -0
  78. package/dist/generateVerbTypes.js.map +1 -0
  79. package/{src/index.ts → dist/index.d.ts} +13 -100
  80. package/dist/index.js +152 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/livewire/index.d.ts +653 -0
  83. package/dist/livewire/index.js +992 -0
  84. package/dist/livewire/index.js.map +1 -0
  85. package/dist/prefabs/ConciergeAgent.d.ts +89 -0
  86. package/dist/prefabs/ConciergeAgent.js +245 -0
  87. package/dist/prefabs/ConciergeAgent.js.map +1 -0
  88. package/dist/prefabs/FAQBotAgent.d.ts +113 -0
  89. package/dist/prefabs/FAQBotAgent.js +329 -0
  90. package/dist/prefabs/FAQBotAgent.js.map +1 -0
  91. package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
  92. package/dist/prefabs/InfoGathererAgent.js +287 -0
  93. package/dist/prefabs/InfoGathererAgent.js.map +1 -0
  94. package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
  95. package/dist/prefabs/ReceptionistAgent.js +303 -0
  96. package/dist/prefabs/ReceptionistAgent.js.map +1 -0
  97. package/dist/prefabs/SurveyAgent.d.ts +148 -0
  98. package/dist/prefabs/SurveyAgent.js +540 -0
  99. package/dist/prefabs/SurveyAgent.js.map +1 -0
  100. package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
  101. package/dist/prefabs/index.js +14 -0
  102. package/dist/prefabs/index.js.map +1 -0
  103. package/dist/relay/Action.d.ts +258 -0
  104. package/dist/relay/Action.js +402 -0
  105. package/dist/relay/Action.js.map +1 -0
  106. package/dist/relay/Call.d.ts +697 -0
  107. package/dist/relay/Call.js +1062 -0
  108. package/dist/relay/Call.js.map +1 -0
  109. package/dist/relay/Deferred.d.ts +44 -0
  110. package/dist/relay/Deferred.js +69 -0
  111. package/dist/relay/Deferred.js.map +1 -0
  112. package/dist/relay/Message.d.ts +103 -0
  113. package/dist/relay/Message.js +169 -0
  114. package/dist/relay/Message.js.map +1 -0
  115. package/dist/relay/RelayClient.d.ts +302 -0
  116. package/dist/relay/RelayClient.js +1026 -0
  117. package/dist/relay/RelayClient.js.map +1 -0
  118. package/dist/relay/RelayError.d.ts +15 -0
  119. package/dist/relay/RelayError.js +20 -0
  120. package/dist/relay/RelayError.js.map +1 -0
  121. package/dist/relay/RelayEvent.d.ts +254 -0
  122. package/dist/relay/RelayEvent.js +509 -0
  123. package/dist/relay/RelayEvent.js.map +1 -0
  124. package/dist/relay/constants.d.ts +90 -0
  125. package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
  126. package/dist/relay/constants.js.map +1 -0
  127. package/dist/relay/index.d.ts +16 -0
  128. package/dist/relay/index.js +18 -0
  129. package/dist/relay/index.js.map +1 -0
  130. package/dist/relay/types.d.ts +142 -0
  131. package/dist/relay/types.js +5 -0
  132. package/dist/relay/types.js.map +1 -0
  133. package/dist/rest/HttpClient.d.ts +80 -0
  134. package/dist/rest/HttpClient.js +148 -0
  135. package/dist/rest/HttpClient.js.map +1 -0
  136. package/dist/rest/RestError.d.ts +30 -0
  137. package/dist/rest/RestError.js +39 -0
  138. package/dist/rest/RestError.js.map +1 -0
  139. package/dist/rest/base/BaseResource.d.ts +24 -0
  140. package/dist/rest/base/BaseResource.js +29 -0
  141. package/dist/rest/base/BaseResource.js.map +1 -0
  142. package/dist/rest/base/CrudResource.d.ts +68 -0
  143. package/dist/rest/base/CrudResource.js +82 -0
  144. package/dist/rest/base/CrudResource.js.map +1 -0
  145. package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
  146. package/dist/rest/base/CrudWithAddresses.js +25 -0
  147. package/dist/rest/base/CrudWithAddresses.js.map +1 -0
  148. package/dist/rest/index.d.ts +131 -0
  149. package/{src/rest/index.ts → dist/rest/index.js} +101 -136
  150. package/dist/rest/index.js.map +1 -0
  151. package/dist/rest/namespaces/addresses.d.ts +46 -0
  152. package/dist/rest/namespaces/addresses.js +55 -0
  153. package/dist/rest/namespaces/addresses.js.map +1 -0
  154. package/dist/rest/namespaces/calling.d.ts +382 -0
  155. package/dist/rest/namespaces/calling.js +478 -0
  156. package/dist/rest/namespaces/calling.js.map +1 -0
  157. package/dist/rest/namespaces/chat.d.ts +22 -0
  158. package/dist/rest/namespaces/chat.js +26 -0
  159. package/dist/rest/namespaces/chat.js.map +1 -0
  160. package/dist/rest/namespaces/compat.d.ts +585 -0
  161. package/dist/rest/namespaces/compat.js +735 -0
  162. package/dist/rest/namespaces/compat.js.map +1 -0
  163. package/dist/rest/namespaces/datasphere.d.ts +66 -0
  164. package/dist/rest/namespaces/datasphere.js +77 -0
  165. package/dist/rest/namespaces/datasphere.js.map +1 -0
  166. package/dist/rest/namespaces/fabric.d.ts +282 -0
  167. package/dist/rest/namespaces/fabric.js +373 -0
  168. package/dist/rest/namespaces/fabric.js.map +1 -0
  169. package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
  170. package/dist/rest/namespaces/imported-numbers.js +26 -0
  171. package/dist/rest/namespaces/imported-numbers.js.map +1 -0
  172. package/dist/rest/namespaces/logs.d.ts +105 -0
  173. package/dist/rest/namespaces/logs.js +133 -0
  174. package/dist/rest/namespaces/logs.js.map +1 -0
  175. package/dist/rest/namespaces/lookup.d.ts +29 -0
  176. package/dist/rest/namespaces/lookup.js +32 -0
  177. package/dist/rest/namespaces/lookup.js.map +1 -0
  178. package/dist/rest/namespaces/mfa.d.ts +46 -0
  179. package/dist/rest/namespaces/mfa.js +54 -0
  180. package/dist/rest/namespaces/mfa.js.map +1 -0
  181. package/dist/rest/namespaces/number-groups.d.ts +49 -0
  182. package/dist/rest/namespaces/number-groups.js +58 -0
  183. package/dist/rest/namespaces/number-groups.js.map +1 -0
  184. package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
  185. package/dist/rest/namespaces/phone-numbers.js +67 -0
  186. package/dist/rest/namespaces/phone-numbers.js.map +1 -0
  187. package/dist/rest/namespaces/project.d.ts +46 -0
  188. package/dist/rest/namespaces/project.js +56 -0
  189. package/dist/rest/namespaces/project.js.map +1 -0
  190. package/dist/rest/namespaces/pubsub.d.ts +22 -0
  191. package/dist/rest/namespaces/pubsub.js +26 -0
  192. package/dist/rest/namespaces/pubsub.js.map +1 -0
  193. package/dist/rest/namespaces/queues.d.ts +42 -0
  194. package/dist/rest/namespaces/queues.js +49 -0
  195. package/dist/rest/namespaces/queues.js.map +1 -0
  196. package/dist/rest/namespaces/recordings.d.ts +38 -0
  197. package/dist/rest/namespaces/recordings.js +45 -0
  198. package/dist/rest/namespaces/recordings.js.map +1 -0
  199. package/dist/rest/namespaces/registry.d.ts +141 -0
  200. package/dist/rest/namespaces/registry.js +178 -0
  201. package/dist/rest/namespaces/registry.js.map +1 -0
  202. package/dist/rest/namespaces/short-codes.d.ts +39 -0
  203. package/dist/rest/namespaces/short-codes.js +46 -0
  204. package/dist/rest/namespaces/short-codes.js.map +1 -0
  205. package/dist/rest/namespaces/sip-profile.d.ts +28 -0
  206. package/dist/rest/namespaces/sip-profile.js +34 -0
  207. package/dist/rest/namespaces/sip-profile.js.map +1 -0
  208. package/dist/rest/namespaces/verified-callers.d.ts +33 -0
  209. package/dist/rest/namespaces/verified-callers.js +39 -0
  210. package/dist/rest/namespaces/verified-callers.js.map +1 -0
  211. package/dist/rest/namespaces/video.d.ts +235 -0
  212. package/dist/rest/namespaces/video.js +297 -0
  213. package/dist/rest/namespaces/video.js.map +1 -0
  214. package/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
  215. package/dist/rest/pagination.js +78 -0
  216. package/dist/rest/pagination.js.map +1 -0
  217. package/dist/rest/types.d.ts +54 -0
  218. package/dist/rest/types.js +5 -0
  219. package/dist/rest/types.js.map +1 -0
  220. package/dist/skills/SkillBase.d.ts +404 -0
  221. package/dist/skills/SkillBase.js +471 -0
  222. package/dist/skills/SkillBase.js.map +1 -0
  223. package/dist/skills/SkillManager.d.ts +195 -0
  224. package/dist/skills/SkillManager.js +378 -0
  225. package/dist/skills/SkillManager.js.map +1 -0
  226. package/dist/skills/SkillRegistry.d.ts +176 -0
  227. package/dist/skills/SkillRegistry.js +310 -0
  228. package/dist/skills/SkillRegistry.js.map +1 -0
  229. package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
  230. package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
  231. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
  232. package/dist/skills/builtin/ask_claude.d.ts +37 -0
  233. package/dist/skills/builtin/ask_claude.js +162 -0
  234. package/dist/skills/builtin/ask_claude.js.map +1 -0
  235. package/dist/skills/builtin/claude_skills.d.ts +75 -0
  236. package/dist/skills/builtin/claude_skills.js +753 -0
  237. package/dist/skills/builtin/claude_skills.js.map +1 -0
  238. package/dist/skills/builtin/custom_skills.d.ts +79 -0
  239. package/dist/skills/builtin/custom_skills.js +227 -0
  240. package/dist/skills/builtin/custom_skills.js.map +1 -0
  241. package/dist/skills/builtin/datasphere.d.ts +73 -0
  242. package/dist/skills/builtin/datasphere.js +350 -0
  243. package/dist/skills/builtin/datasphere.js.map +1 -0
  244. package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
  245. package/dist/skills/builtin/datasphere_serverless.js +291 -0
  246. package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
  247. package/dist/skills/builtin/datetime.d.ts +40 -0
  248. package/dist/skills/builtin/datetime.js +118 -0
  249. package/dist/skills/builtin/datetime.js.map +1 -0
  250. package/dist/skills/builtin/google_maps.d.ts +48 -0
  251. package/dist/skills/builtin/google_maps.js +470 -0
  252. package/dist/skills/builtin/google_maps.js.map +1 -0
  253. package/dist/skills/builtin/index.d.ts +31 -0
  254. package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
  255. package/dist/skills/builtin/index.js.map +1 -0
  256. package/dist/skills/builtin/info_gatherer.d.ts +115 -0
  257. package/dist/skills/builtin/info_gatherer.js +328 -0
  258. package/dist/skills/builtin/info_gatherer.js.map +1 -0
  259. package/dist/skills/builtin/joke.d.ts +41 -0
  260. package/dist/skills/builtin/joke.js +156 -0
  261. package/dist/skills/builtin/joke.js.map +1 -0
  262. package/dist/skills/builtin/math.d.ts +39 -0
  263. package/dist/skills/builtin/math.js +119 -0
  264. package/dist/skills/builtin/math.js.map +1 -0
  265. package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
  266. package/dist/skills/builtin/mcp_gateway.js +574 -0
  267. package/dist/skills/builtin/mcp_gateway.js.map +1 -0
  268. package/dist/skills/builtin/native_vector_search.d.ts +128 -0
  269. package/dist/skills/builtin/native_vector_search.js +752 -0
  270. package/dist/skills/builtin/native_vector_search.js.map +1 -0
  271. package/dist/skills/builtin/play_background_file.d.ts +59 -0
  272. package/dist/skills/builtin/play_background_file.js +274 -0
  273. package/dist/skills/builtin/play_background_file.js.map +1 -0
  274. package/dist/skills/builtin/spider.d.ts +91 -0
  275. package/dist/skills/builtin/spider.js +758 -0
  276. package/dist/skills/builtin/spider.js.map +1 -0
  277. package/dist/skills/builtin/swml_transfer.d.ts +66 -0
  278. package/dist/skills/builtin/swml_transfer.js +475 -0
  279. package/dist/skills/builtin/swml_transfer.js.map +1 -0
  280. package/dist/skills/builtin/weather_api.d.ts +59 -0
  281. package/dist/skills/builtin/weather_api.js +196 -0
  282. package/dist/skills/builtin/weather_api.js.map +1 -0
  283. package/dist/skills/builtin/web_search.d.ts +160 -0
  284. package/dist/skills/builtin/web_search.js +894 -0
  285. package/dist/skills/builtin/web_search.js.map +1 -0
  286. package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
  287. package/dist/skills/builtin/wikipedia_search.js +241 -0
  288. package/dist/skills/builtin/wikipedia_search.js.map +1 -0
  289. package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
  290. package/dist/skills/index.js +10 -0
  291. package/dist/skills/index.js.map +1 -0
  292. package/dist/types.d.ts +118 -0
  293. package/dist/types.js +5 -0
  294. package/dist/types.js.map +1 -0
  295. package/package.json +7 -1
  296. package/.github/workflows/publish.yml +0 -27
  297. package/.github/workflows/test.yml +0 -17
  298. package/CLAUDE.md +0 -112
  299. package/docs/MIGRATION-2.0.md +0 -81
  300. package/docs/agent-guide.md +0 -869
  301. package/docs/agent_guide.md +0 -1026
  302. package/docs/api-reference.md +0 -2420
  303. package/docs/api_reference.md +0 -1301
  304. package/docs/architecture.md +0 -843
  305. package/docs/cli-guide.md +0 -579
  306. package/docs/cli_guide.md +0 -448
  307. package/docs/cloud_functions_guide.md +0 -474
  308. package/docs/configuration.md +0 -422
  309. package/docs/contexts-guide.md +0 -787
  310. package/docs/contexts_guide.md +0 -511
  311. package/docs/datamap-guide.md +0 -1141
  312. package/docs/datamap_guide.md +0 -595
  313. package/docs/llm_parameters.md +0 -239
  314. package/docs/mcp_gateway_reference.md +0 -648
  315. package/docs/mcp_integration.md +0 -108
  316. package/docs/prefabs-guide.md +0 -800
  317. package/docs/sdk_features.md +0 -477
  318. package/docs/security.md +0 -436
  319. package/docs/serverless-guide.md +0 -513
  320. package/docs/skills-guide.md +0 -857
  321. package/docs/skills-system.md +0 -301
  322. package/docs/skills_parameter_schema.md +0 -392
  323. package/docs/skills_system.md +0 -467
  324. package/docs/swaig-reference.md +0 -1627
  325. package/docs/swaig_reference.md +0 -910
  326. package/docs/swml_service_guide.md +0 -600
  327. package/docs/third_party_skills.md +0 -533
  328. package/docs/web_service.md +0 -677
  329. package/examples/README.md +0 -131
  330. package/examples/advanced-datamap.ts +0 -100
  331. package/examples/advanced-dynamic-config.ts +0 -70
  332. package/examples/auto-vivified.ts +0 -94
  333. package/examples/call-flow.ts +0 -63
  334. package/examples/comprehensive-dynamic.ts +0 -125
  335. package/examples/contexts-steps.ts +0 -65
  336. package/examples/custom-path.ts +0 -45
  337. package/examples/datamap-tools.ts +0 -55
  338. package/examples/datasphere-multi-instance.ts +0 -63
  339. package/examples/datasphere-serverless-env.ts +0 -68
  340. package/examples/datasphere-webhook-env.ts +0 -66
  341. package/examples/datasphere.ts +0 -37
  342. package/examples/declarative.ts +0 -100
  343. package/examples/dynamic-config.ts +0 -54
  344. package/examples/dynamic-info-gatherer.ts +0 -69
  345. package/examples/dynamic-swml-service.ts +0 -67
  346. package/examples/gather-info.ts +0 -71
  347. package/examples/gather-per-question-functions-demo.ts +0 -140
  348. package/examples/joke-agent.ts +0 -34
  349. package/examples/kubernetes-agent.ts +0 -45
  350. package/examples/llm-params.ts +0 -69
  351. package/examples/mcp-agent.ts +0 -84
  352. package/examples/mcp-gateway.ts +0 -35
  353. package/examples/multi-agent.ts +0 -73
  354. package/examples/multi-endpoint.ts +0 -79
  355. package/examples/pom-prompt.ts +0 -71
  356. package/examples/prefab-concierge.ts +0 -47
  357. package/examples/prefab-faq.ts +0 -54
  358. package/examples/prefab-info-gatherer.ts +0 -33
  359. package/examples/prefab-receptionist.ts +0 -36
  360. package/examples/prefab-survey.ts +0 -68
  361. package/examples/record-call.ts +0 -67
  362. package/examples/relay-demo.ts +0 -33
  363. package/examples/room-and-sip.ts +0 -94
  364. package/examples/serverless-lambda.ts +0 -35
  365. package/examples/session-state.ts +0 -83
  366. package/examples/simple-agent.ts +0 -36
  367. package/examples/simple-static.ts +0 -29
  368. package/examples/skills-demo.ts +0 -38
  369. package/examples/step-function-inheritance-demo.ts +0 -124
  370. package/examples/swaig-features.ts +0 -187
  371. package/examples/swml-service-routing.ts +0 -66
  372. package/examples/swml-service.ts +0 -38
  373. package/examples/tap.ts +0 -68
  374. package/examples/verb-methods.ts +0 -45
  375. package/examples/web-search-multi-instance.ts +0 -72
  376. package/examples/web-search.ts +0 -38
  377. package/examples/wikipedia.ts +0 -36
  378. package/livewire/README.md +0 -140
  379. package/livewire/docs/migration-guide.md +0 -228
  380. package/livewire/examples/livewire-basic-agent.ts +0 -74
  381. package/livewire/examples/livewire-handoff.ts +0 -197
  382. package/livewire/examples/livewire-multi-tool.ts +0 -117
  383. package/relay/README.md +0 -70
  384. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
  385. package/relay/docs/call-methods.md +0 -474
  386. package/relay/docs/client-reference.md +0 -142
  387. package/relay/docs/events.md +0 -134
  388. package/relay/docs/getting-started.md +0 -134
  389. package/relay/docs/guide.md +0 -306
  390. package/relay/docs/messaging.md +0 -182
  391. package/relay/examples/relay-inbound.ts +0 -66
  392. package/relay/examples/relay-messaging.ts +0 -71
  393. package/relay/examples/relay-outbound.ts +0 -76
  394. package/rest/README.md +0 -95
  395. package/rest/docs/calling.md +0 -273
  396. package/rest/docs/client-reference.md +0 -107
  397. package/rest/docs/compat.md +0 -204
  398. package/rest/docs/fabric.md +0 -183
  399. package/rest/docs/getting-started.md +0 -110
  400. package/rest/docs/guide.md +0 -351
  401. package/rest/docs/namespaces.md +0 -285
  402. package/rest/examples/rest-10dlc-registration.ts +0 -161
  403. package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
  404. package/rest/examples/rest-calling-play-and-record.ts +0 -91
  405. package/rest/examples/rest-client.ts +0 -65
  406. package/rest/examples/rest-compat-laml.ts +0 -210
  407. package/rest/examples/rest-datasphere-search.ts +0 -82
  408. package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
  409. package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
  410. package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
  411. package/rest/examples/rest-manage-resources.ts +0 -65
  412. package/rest/examples/rest-phone-number-management.ts +0 -197
  413. package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
  414. package/rest/examples/rest-video-rooms.ts +0 -186
  415. package/src/AgentBase.ts +0 -2598
  416. package/src/AgentServer.ts +0 -442
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1181
  420. package/src/DataMap.ts +0 -477
  421. package/src/FunctionResult.ts +0 -903
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -467
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -749
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -240
  429. package/src/SessionManager.ts +0 -311
  430. package/src/SslConfig.ts +0 -118
  431. package/src/SwaigFunction.ts +0 -276
  432. package/src/SwmlBuilder.ts +0 -283
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -199
  435. package/src/WebService.ts +0 -641
  436. package/src/cli/agent-loader.ts +0 -166
  437. package/src/cli/mock-data.ts +0 -111
  438. package/src/cli/swaig-test.ts +0 -452
  439. package/src/generateVerbTypes.ts +0 -322
  440. package/src/livewire/index.ts +0 -1252
  441. package/src/prefabs/ConciergeAgent.ts +0 -309
  442. package/src/prefabs/FAQBotAgent.ts +0 -415
  443. package/src/prefabs/InfoGathererAgent.ts +0 -379
  444. package/src/prefabs/ReceptionistAgent.ts +0 -395
  445. package/src/prefabs/SurveyAgent.ts +0 -671
  446. package/src/relay/Action.ts +0 -482
  447. package/src/relay/Call.ts +0 -1270
  448. package/src/relay/Deferred.ts +0 -94
  449. package/src/relay/Message.ts +0 -199
  450. package/src/relay/RelayClient.ts +0 -1185
  451. package/src/relay/RelayError.ts +0 -20
  452. package/src/relay/RelayEvent.ts +0 -944
  453. package/src/relay/index.ts +0 -123
  454. package/src/relay/types.ts +0 -149
  455. package/src/rest/HttpClient.ts +0 -164
  456. package/src/rest/RestError.ts +0 -45
  457. package/src/rest/base/BaseResource.ts +0 -32
  458. package/src/rest/base/CrudResource.ts +0 -98
  459. package/src/rest/base/CrudWithAddresses.ts +0 -37
  460. package/src/rest/namespaces/addresses.ts +0 -64
  461. package/src/rest/namespaces/calling.ts +0 -534
  462. package/src/rest/namespaces/chat.ts +0 -31
  463. package/src/rest/namespaces/compat.ts +0 -812
  464. package/src/rest/namespaces/datasphere.ts +0 -88
  465. package/src/rest/namespaces/fabric.ts +0 -417
  466. package/src/rest/namespaces/imported-numbers.ts +0 -31
  467. package/src/rest/namespaces/logs.ts +0 -151
  468. package/src/rest/namespaces/lookup.ts +0 -38
  469. package/src/rest/namespaces/mfa.ts +0 -61
  470. package/src/rest/namespaces/number-groups.ts +0 -68
  471. package/src/rest/namespaces/phone-numbers.ts +0 -76
  472. package/src/rest/namespaces/project.ts +0 -65
  473. package/src/rest/namespaces/pubsub.ts +0 -31
  474. package/src/rest/namespaces/queues.ts +0 -58
  475. package/src/rest/namespaces/recordings.ts +0 -53
  476. package/src/rest/namespaces/registry.ts +0 -200
  477. package/src/rest/namespaces/short-codes.ts +0 -54
  478. package/src/rest/namespaces/sip-profile.ts +0 -40
  479. package/src/rest/namespaces/verified-callers.ts +0 -46
  480. package/src/rest/namespaces/video.ts +0 -332
  481. package/src/rest/types.ts +0 -61
  482. package/src/skills/SkillBase.ts +0 -582
  483. package/src/skills/SkillManager.ts +0 -419
  484. package/src/skills/SkillRegistry.ts +0 -367
  485. package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
  486. package/src/skills/builtin/ask_claude.ts +0 -246
  487. package/src/skills/builtin/claude_skills.ts +0 -983
  488. package/src/skills/builtin/custom_skills.ts +0 -327
  489. package/src/skills/builtin/datasphere.ts +0 -447
  490. package/src/skills/builtin/datasphere_serverless.ts +0 -347
  491. package/src/skills/builtin/datetime.ts +0 -137
  492. package/src/skills/builtin/google_maps.ts +0 -656
  493. package/src/skills/builtin/info_gatherer.ts +0 -415
  494. package/src/skills/builtin/joke.ts +0 -196
  495. package/src/skills/builtin/math.ts +0 -149
  496. package/src/skills/builtin/mcp_gateway.ts +0 -685
  497. package/src/skills/builtin/native_vector_search.ts +0 -910
  498. package/src/skills/builtin/play_background_file.ts +0 -367
  499. package/src/skills/builtin/spider.ts +0 -874
  500. package/src/skills/builtin/swml_transfer.ts +0 -645
  501. package/src/skills/builtin/weather_api.ts +0 -255
  502. package/src/skills/builtin/web_search.ts +0 -1083
  503. package/src/skills/builtin/wikipedia_search.ts +0 -304
  504. package/src/types.ts +0 -132
  505. package/tests/AgentBase.test.ts +0 -1093
  506. package/tests/AgentServer.test.ts +0 -126
  507. package/tests/AuthHandler.test.ts +0 -133
  508. package/tests/ConfigLoader.test.ts +0 -151
  509. package/tests/ContextBuilder.test.ts +0 -108
  510. package/tests/DataMap.test.ts +0 -367
  511. package/tests/EphemeralSkillCopy.test.ts +0 -107
  512. package/tests/FunctionResult.test.ts +0 -298
  513. package/tests/GracefulShutdown.test.ts +0 -46
  514. package/tests/Logger.test.ts +0 -420
  515. package/tests/PomBuilder.test.ts +0 -228
  516. package/tests/ProxyDetection.test.ts +0 -228
  517. package/tests/SWMLService.test.ts +0 -320
  518. package/tests/SWMLVerbHandler.test.ts +0 -523
  519. package/tests/SchemaUtils.test.ts +0 -106
  520. package/tests/SchemaUtils.verb.test.ts +0 -206
  521. package/tests/SecurityUtils.test.ts +0 -192
  522. package/tests/ServerlessAdapter.test.ts +0 -222
  523. package/tests/SessionManager.test.ts +0 -257
  524. package/tests/SkillBaseFeatures.test.ts +0 -130
  525. package/tests/SkillMultiInstance.test.ts +0 -102
  526. package/tests/SkillParameterSchemas.test.ts +0 -134
  527. package/tests/SkillRegistrySchema.test.ts +0 -84
  528. package/tests/SslConfig.test.ts +0 -97
  529. package/tests/SwmlBuilder.test.ts +0 -400
  530. package/tests/TypeInference.test.ts +0 -165
  531. package/tests/VerbHandlerRegistry.test.ts +0 -128
  532. package/tests/cli/mock-data.test.ts +0 -113
  533. package/tests/cli/swaig-test.test.ts +0 -108
  534. package/tests/examples.test.ts +0 -194
  535. package/tests/fixtures/scrape-parity/README.md +0 -53
  536. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  537. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  538. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  548. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  549. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  550. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  551. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  552. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  553. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  554. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  555. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  556. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  557. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  558. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  559. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  560. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  561. package/tests/livewire/livewire.test.ts +0 -780
  562. package/tests/mcp.test.ts +0 -221
  563. package/tests/prefabs/prefabs.test.ts +0 -1093
  564. package/tests/relay/Action.test.ts +0 -392
  565. package/tests/relay/Call.test.ts +0 -535
  566. package/tests/relay/Deferred.test.ts +0 -71
  567. package/tests/relay/Message.test.ts +0 -164
  568. package/tests/relay/RelayClient.test.ts +0 -779
  569. package/tests/relay/RelayEvent.test.ts +0 -463
  570. package/tests/relay/helpers.ts +0 -79
  571. package/tests/rest/HttpClient.test.ts +0 -274
  572. package/tests/rest/RestError.test.ts +0 -53
  573. package/tests/rest/calling.test.ts +0 -156
  574. package/tests/rest/client.test.ts +0 -197
  575. package/tests/rest/compat.test.ts +0 -335
  576. package/tests/rest/datasphere.test.ts +0 -71
  577. package/tests/rest/fabric.test.ts +0 -186
  578. package/tests/rest/helpers.ts +0 -95
  579. package/tests/rest/logs.test.ts +0 -68
  580. package/tests/rest/pagination.test.ts +0 -133
  581. package/tests/rest/registry.test.ts +0 -94
  582. package/tests/rest/relay-rest.test.ts +0 -290
  583. package/tests/rest/video.test.ts +0 -173
  584. package/tests/setup.ts +0 -6
  585. package/tests/skills/SkillBase.test.ts +0 -108
  586. package/tests/skills/SkillManager.test.ts +0 -268
  587. package/tests/skills/SkillRegistry.test.ts +0 -176
  588. package/tests/skills/builtin.test.ts +0 -1472
  589. package/tests/skills/claude-skills.test.ts +0 -54
  590. package/tests/skills/custom-skills.test.ts +0 -53
  591. package/tests/skills/datasphere-serverless.test.ts +0 -70
  592. package/tests/skills/datasphere.test.ts +0 -107
  593. package/tests/skills/datetime.test.ts +0 -101
  594. package/tests/skills/google-maps.test.ts +0 -78
  595. package/tests/skills/info-gatherer.test.ts +0 -411
  596. package/tests/skills/joke.test.ts +0 -81
  597. package/tests/skills/math.test.ts +0 -68
  598. package/tests/skills/mcp-gateway.test.ts +0 -101
  599. package/tests/skills/play-background.test.ts +0 -54
  600. package/tests/skills/spider.test.ts +0 -108
  601. package/tests/skills/swml-transfer.test.ts +0 -178
  602. package/tests/skills/trivia.test.ts +0 -54
  603. package/tests/skills/vector-search.test.ts +0 -135
  604. package/tests/skills/weather-api.test.ts +0 -77
  605. package/tests/skills/web-search-parity.test.ts +0 -59
  606. package/tests/skills/web-search.test.ts +0 -103
  607. package/tests/skills/wikipedia.test.ts +0 -63
  608. package/tsconfig.json +0 -18
  609. package/vitest.config.ts +0 -9
  610. /package/{src → dist}/schema.json +0 -0
@@ -1,1026 +0,0 @@
1
- # SignalWire AI Agents TypeScript SDK -- Agent Guide
2
-
3
- ## Table of Contents
4
-
5
- - [Introduction](#introduction)
6
- - [Creating an Agent](#creating-an-agent)
7
- - [Prompts](#prompts)
8
- - [Raw Text Prompts](#raw-text-prompts)
9
- - [Prompt Object Model (POM)](#prompt-object-model-pom)
10
- - [Declarative PROMPT_SECTIONS](#declarative-prompt_sections)
11
- - [Tools (SWAIG Functions)](#tools-swaig-functions)
12
- - [Defining Tools](#defining-tools)
13
- - [Tool Parameters](#tool-parameters)
14
- - [Secure Tools](#secure-tools)
15
- - [FunctionResult](#functionresult)
16
- - [DataMap (Server-Side Tools)](#datamap-server-side-tools)
17
- - [Speech and Languages](#speech-and-languages)
18
- - [Hints](#hints)
19
- - [Languages](#languages)
20
- - [Pronunciation](#pronunciation)
21
- - [AI Parameters](#ai-parameters)
22
- - [Global Data](#global-data)
23
- - [Call Flow (5 Phases)](#call-flow-5-phases)
24
- - [Dynamic Configuration](#dynamic-configuration)
25
- - [Post-Prompt and Summaries](#post-prompt-and-summaries)
26
- - [Skills System](#skills-system)
27
- - [Multi-Agent Server](#multi-agent-server)
28
- - [Subclassing AgentBase](#subclassing-agentbase)
29
- - [HTTP Endpoints](#http-endpoints)
30
- - [State Management](#state-management)
31
- - [SIP Routing](#sip-routing)
32
- - [Environment Variables](#environment-variables)
33
-
34
- ---
35
-
36
- ## Introduction
37
-
38
- The SignalWire AI Agents TypeScript SDK lets you build AI-powered voice agents as HTTP microservices. Each agent is a lightweight HTTP server built on the [Hono](https://hono.dev/) framework that serves **SWML** (SignalWire Markup Language) documents and handles **SWAIG** (SignalWire AI Gateway) function callbacks.
39
-
40
- When SignalWire receives an inbound call (or an outbound call is placed), it requests a SWML document from your agent's HTTP endpoint. The SWML document describes the entire call flow: answering, playing audio, launching the AI engine with a prompt, registering tools the AI can invoke, and handling post-call summaries. The agent SDK automates all of this -- you configure the prompt, define tools, and the SDK handles SWML rendering, webhook routing, authentication, and session management.
41
-
42
- ```
43
- Caller --> SignalWire Platform --> GET/POST your-agent/ --> SWML document
44
- POST your-agent/swaig --> tool execution
45
- POST your-agent/post_prompt --> call summary
46
- ```
47
-
48
- ### Architecture Overview
49
-
50
- ```
51
- +-------------------+
52
- | Your Agent | (Extends AgentBase with your specific functionality)
53
- +--------+----------+
54
- |
55
- +--------+----------+
56
- | AgentBase | (HTTP server, SWML rendering, tool dispatch, auth)
57
- +--------+----------+
58
- |
59
- +--------+----------+
60
- | Hono HTTP Server | (Routes, middleware, CORS, rate limiting)
61
- +--------------------+
62
- ```
63
-
64
- ### Installation
65
-
66
- ```bash
67
- npm install @signalwire/sdk
68
- ```
69
-
70
- ### Quick Start
71
-
72
- ```typescript
73
- import { AgentBase, FunctionResult } from '@signalwire/sdk';
74
-
75
- const agent = new AgentBase({ name: 'my-agent' });
76
-
77
- agent.setPromptText('You are a helpful customer service agent for Acme Corp.');
78
-
79
- agent.defineTool({
80
- name: 'check_order_status',
81
- description: 'Look up the status of a customer order by order number.',
82
- parameters: {
83
- order_id: { type: 'string', description: 'The order number to look up' },
84
- },
85
- handler: async (args) => {
86
- const status = await lookupOrder(args.order_id as string);
87
- return new FunctionResult(`Order ${args.order_id} is ${status}.`);
88
- },
89
- });
90
-
91
- agent.serve();
92
- ```
93
-
94
- ---
95
-
96
- ## Creating an Agent
97
-
98
- The `AgentBase` constructor accepts an `AgentOptions` object:
99
-
100
- ```typescript
101
- import { AgentBase } from '@signalwire/sdk';
102
-
103
- const agent = new AgentBase({
104
- name: 'support-bot',
105
- route: '/',
106
- host: '0.0.0.0',
107
- port: 3000,
108
- basicAuth: ['admin', 's3cretP@ss'],
109
- usePom: true,
110
- tokenExpirySecs: 3600,
111
- autoAnswer: true,
112
- recordCall: false,
113
- recordFormat: 'mp4',
114
- recordStereo: true,
115
- nativeFunctions: [],
116
- suppressLogs: false,
117
- });
118
- ```
119
-
120
- ### AgentOptions Reference
121
-
122
- | Option | Type | Default | Description |
123
- |--------|------|---------|-------------|
124
- | `name` | `string` | **(required)** | Display name; also used as the default basic-auth username when credentials are auto-generated. |
125
- | `route` | `string` | `"/"` | HTTP route path this agent listens on. |
126
- | `host` | `string` | `"0.0.0.0"` | Hostname the server binds to. |
127
- | `port` | `number` | `PORT` env or `3000` | Port number for the HTTP server. |
128
- | `basicAuth` | `[string, string]` | auto-generated | Explicit `[username, password]` pair; if omitted, reads from env vars or generates random credentials. |
129
- | `usePom` | `boolean` | `true` | Use Prompt Object Model for structured prompts. |
130
- | `tokenExpirySecs` | `number` | `3600` | Session token validity in seconds for secure tools. |
131
- | `autoAnswer` | `boolean` | `true` | Automatically insert an `answer` verb in the SWML call flow. |
132
- | `recordCall` | `boolean` | `false` | Whether to record the call. |
133
- | `recordFormat` | `string` | `"mp4"` | Recording format (e.g., `"mp4"`, `"wav"`). |
134
- | `recordStereo` | `boolean` | `true` | Whether to record in stereo. |
135
- | `defaultWebhookUrl` | `string` | `null` | Override the default SWAIG function webhook URL. |
136
- | `nativeFunctions` | `string[]` | `[]` | List of built-in platform function names to include. |
137
- | `agentId` | `string` | random hex | Unique identifier for this agent instance. |
138
- | `suppressLogs` | `boolean` | `false` | Suppress all log output. |
139
-
140
- ### Basic Auth
141
-
142
- Authentication credentials are resolved in this order:
143
-
144
- 1. **Provided** -- `basicAuth` option in the constructor.
145
- 2. **Environment** -- `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables.
146
- 3. **Generated** -- A random password is generated, using the agent name as the username. Credentials are logged at startup so you can retrieve them.
147
-
148
- ```typescript
149
- // Explicit credentials
150
- const agent = new AgentBase({
151
- name: 'my-agent',
152
- basicAuth: ['admin', 'hunter2'],
153
- });
154
-
155
- // Environment-based: set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD
156
- const agent2 = new AgentBase({ name: 'my-agent' });
157
-
158
- // Auto-generated: credentials are logged at startup
159
- const agent3 = new AgentBase({ name: 'my-agent' });
160
- // Logs: Auth: my-agent:**** (source: generated)
161
- ```
162
-
163
- ### Starting the Server
164
-
165
- ```typescript
166
- // Start listening
167
- await agent.serve();
168
- // or equivalently:
169
- await agent.run();
170
- ```
171
-
172
- The server logs its address and auth credentials at startup:
173
-
174
- ```
175
- Agent 'support-bot' running at http://0.0.0.0:3000/
176
- Auth: support-bot:**** (source: generated)
177
- ```
178
-
179
- ---
180
-
181
- ## Prompts
182
-
183
- The SDK provides two ways to define the system prompt sent to the AI: **raw text** and the **Prompt Object Model (POM)**.
184
-
185
- ### Raw Text Prompts
186
-
187
- The simplest approach -- pass a complete prompt string:
188
-
189
- ```typescript
190
- agent.setPromptText(`
191
- You are a friendly receptionist for Dr. Smith's office.
192
- You help patients schedule appointments and answer basic questions.
193
- Always be polite and professional.
194
- `);
195
- ```
196
-
197
- When raw text is set, it is used verbatim as the AI's system prompt. This bypasses POM rendering.
198
-
199
- ### Prompt Object Model (POM)
200
-
201
- POM allows you to build structured prompts from titled sections, body text, bullet points, and nested subsections. The SDK renders them as Markdown headings and lists. POM is enabled by default (`usePom: true`).
202
-
203
- #### Adding Sections
204
-
205
- ```typescript
206
- agent.promptAddSection('Personality', {
207
- body: 'You are a cheerful and knowledgeable tech support agent.',
208
- bullets: [
209
- 'Always greet the customer warmly',
210
- 'Ask clarifying questions before troubleshooting',
211
- 'Offer to escalate if you cannot resolve the issue',
212
- ],
213
- });
214
- ```
215
-
216
- #### Appending to Existing Sections
217
-
218
- ```typescript
219
- agent.promptAddToSection('Personality', {
220
- bullet: 'Never make promises about timelines',
221
- });
222
-
223
- agent.promptAddToSection('Personality', {
224
- bullets: ['Speak in simple, non-technical language', 'Confirm understanding before proceeding'],
225
- });
226
-
227
- agent.promptAddToSection('Personality', {
228
- body: 'Remember to always thank the customer at the end of the call.',
229
- });
230
- ```
231
-
232
- #### Subsections
233
-
234
- ```typescript
235
- agent.promptAddSubsection('Personality', 'Tone', {
236
- body: 'Maintain a warm but professional tone throughout the conversation.',
237
- bullets: ['Avoid slang', 'Do not use jargon'],
238
- });
239
- ```
240
-
241
- #### Checking for Sections
242
-
243
- ```typescript
244
- if (!agent.promptHasSection('Escalation')) {
245
- agent.promptAddSection('Escalation', {
246
- body: 'If the issue cannot be resolved, transfer to a human agent.',
247
- });
248
- }
249
- ```
250
-
251
- #### Numbered Sections and Bullets
252
-
253
- ```typescript
254
- agent.promptAddSection('Troubleshooting Steps', {
255
- numbered: true,
256
- numberedBullets: true,
257
- bullets: [
258
- 'Ask the customer to restart the device',
259
- 'Check if the firmware is up to date',
260
- 'Try a factory reset',
261
- ],
262
- });
263
- ```
264
-
265
- #### Retrieving the Rendered Prompt
266
-
267
- ```typescript
268
- const renderedPrompt: string = agent.getPrompt();
269
- ```
270
-
271
- ### Declarative PROMPT_SECTIONS
272
-
273
- When subclassing `AgentBase`, you can define prompt sections declaratively as a static property. They are automatically applied in the constructor:
274
-
275
- ```typescript
276
- class SupportAgent extends AgentBase {
277
- static PROMPT_SECTIONS = [
278
- {
279
- title: 'Role',
280
- body: 'You are a technical support agent for CloudCo.',
281
- },
282
- {
283
- title: 'Guidelines',
284
- bullets: [
285
- 'Be concise and helpful',
286
- 'Verify the customer identity before sharing account details',
287
- ],
288
- },
289
- ];
290
-
291
- constructor() {
292
- super({ name: 'support-agent' });
293
- this.defineTools();
294
- }
295
- }
296
- ```
297
-
298
- ---
299
-
300
- ## Tools (SWAIG Functions)
301
-
302
- Tools (also called SWAIG functions) are actions the AI can invoke during a conversation. When the AI decides to call a tool, SignalWire sends a POST request to your agent's `/swaig` endpoint with the function name and arguments.
303
-
304
- ### SWAIG functions ARE LLM tools — descriptions matter
305
-
306
- Before writing your first SWAIG function, internalize this: a SWAIG function is **exactly the same concept** as a "tool" in native OpenAI / Anthropic tool calling. There is no separate "SWAIG layer" between your function and the model. Each SWAIG function is rendered into the OpenAI tool schema format on every turn:
307
-
308
- ```json
309
- {
310
- "type": "function",
311
- "function": {
312
- "name": "your_function_name",
313
- "description": "your description text",
314
- "parameters": { /* your JSON schema */ }
315
- }
316
- }
317
- ```
318
-
319
- That schema is sent to the model as part of the same API call that produces the next assistant message. The model reads:
320
-
321
- - the **function `description`** to decide WHEN to call this tool
322
- - the **per-parameter `description` strings** inside `parameters` to decide HOW to fill in each argument
323
-
324
- This means **descriptions are prompt engineering**, not developer documentation. They are not a comment for the next human reading the code — they are instructions to the LLM that directly determine whether the model picks your tool when the user's request matches it.
325
-
326
- Compare:
327
-
328
- | Bad (model often misses the tool) | Good (model picks it reliably) |
329
- |---|---|
330
- | `description: 'Lookup function'` | `description: 'Look up a customer's account details by their account number. Use this BEFORE quoting any account-specific information (balance, plan, status, billing date). Don't use it for general product questions.'` |
331
- | `description: 'the id'` (parameter) | `description: 'The customer's 8-digit account number, no dashes or spaces. Ask the user if they don't provide it.'` |
332
-
333
- A vague description is the #1 cause of "the model has the right tool but doesn't call it" failures. When you find yourself debugging why the model isn't picking a tool that obviously matches the user's request, the first thing to check is whether the description tells the model — in plain language — when to use it and what makes it the right choice over sibling tools.
334
-
335
- **Tool count matters too.** LLM tool selection accuracy degrades noticeably past ~7-8 simultaneously-active tools per call. If you have many tools, partition them across steps using `Step.setFunctions()` so only the relevant subset is active at any moment. See `contexts_guide.md` for the per-step whitelist mechanism.
336
-
337
- ### Defining Tools
338
-
339
- Use `defineTool()` to register a tool:
340
-
341
- ```typescript
342
- agent.defineTool({
343
- name: 'get_weather',
344
- description: 'Get the current weather for a city.',
345
- parameters: {
346
- city: { type: 'string', description: 'City name' },
347
- units: { type: 'string', description: 'Temperature units', enum: ['celsius', 'fahrenheit'] },
348
- },
349
- required: ['city'],
350
- handler: async (args, rawData) => {
351
- const weather = await fetchWeather(args.city as string, args.units as string);
352
- return new FunctionResult(
353
- `The weather in ${args.city} is ${weather.temp} degrees and ${weather.condition}.`
354
- );
355
- },
356
- });
357
- ```
358
-
359
- The `handler` function receives two arguments:
360
-
361
- | Argument | Type | Description |
362
- |----------|------|-------------|
363
- | `args` | `Record<string, unknown>` | Parsed arguments extracted by the AI from the user's speech. |
364
- | `rawData` | `Record<string, unknown>` | The full raw SWAIG request payload from SignalWire. |
365
-
366
- The handler can return:
367
-
368
- - A `FunctionResult` instance (recommended)
369
- - A plain object with a `response` key
370
- - A plain string (wrapped automatically)
371
-
372
- ### Tool Parameters
373
-
374
- Parameters follow JSON Schema conventions. You can provide them in shorthand (just the properties) or full schema format:
375
-
376
- ```typescript
377
- // Shorthand -- properties only, SDK wraps in { type: 'object', properties: ... }
378
- agent.defineTool({
379
- name: 'lookup',
380
- description: 'Look up a customer',
381
- parameters: {
382
- name: { type: 'string', description: 'Customer name' },
383
- email: { type: 'string', description: 'Email address' },
384
- },
385
- handler: async (args) => new FunctionResult(`Found: ${args.name}`),
386
- });
387
-
388
- // Full schema
389
- agent.defineTool({
390
- name: 'lookup_full',
391
- description: 'Look up a customer',
392
- parameters: {
393
- type: 'object',
394
- properties: {
395
- name: { type: 'string', description: 'Customer name' },
396
- email: { type: 'string', description: 'Email address' },
397
- },
398
- required: ['name'],
399
- },
400
- handler: async (args) => new FunctionResult(`Found: ${args.name}`),
401
- });
402
- ```
403
-
404
- ### Secure Tools
405
-
406
- Secure tools require a valid HMAC session token for each invocation. The token is bound to the call ID and function name, preventing replay attacks:
407
-
408
- ```typescript
409
- agent.defineTool({
410
- name: 'transfer_funds',
411
- description: 'Transfer money between accounts.',
412
- secure: true,
413
- parameters: {
414
- amount: { type: 'number', description: 'Amount to transfer' },
415
- to_account: { type: 'string', description: 'Destination account ID' },
416
- },
417
- handler: async (args) => {
418
- await doTransfer(args.amount as number, args.to_account as string);
419
- return new FunctionResult('Transfer completed successfully.');
420
- },
421
- });
422
- ```
423
-
424
- When `secure: true` is set, the SWML document includes a `__token` query parameter in the tool's webhook URL. On each `/swaig` request, the SDK validates the token's HMAC signature, call ID binding, and expiry before executing the handler.
425
-
426
- ### FunctionResult
427
-
428
- `FunctionResult` is a fluent builder for tool responses. It carries response text and an ordered list of actions:
429
-
430
- ```typescript
431
- import { FunctionResult } from '@signalwire/sdk';
432
-
433
- // Simple text response
434
- const result = new FunctionResult('The order has been placed.');
435
-
436
- // Response with actions
437
- const transfer = new FunctionResult('Transferring you now.')
438
- .connect('+15551234567')
439
- .hangup();
440
-
441
- // Update global data from within a tool
442
- const verified = new FunctionResult('Account verified.')
443
- .updateGlobalData({ verified: true, customer_id: '12345' });
444
-
445
- // Context switch
446
- const billing = new FunctionResult('Let me transfer you to billing.')
447
- .switchContext({ systemPrompt: 'You are now a billing specialist.' });
448
- ```
449
-
450
- Key `FunctionResult` methods:
451
-
452
- | Method | Description |
453
- |--------|-------------|
454
- | `setResponse(text)` | Set the response text. |
455
- | `connect(destination, final?, from?)` | Transfer the call to a destination. |
456
- | `hangup()` | Hang up the call. |
457
- | `hold(timeout?)` | Place the call on hold (0-900 seconds). |
458
- | `say(text)` | Speak text via TTS. |
459
- | `stop()` | Stop the AI session. |
460
- | `updateGlobalData(data)` | Merge data into the shared global store. |
461
- | `setMetadata(data)` | Set call metadata. |
462
- | `switchContext(opts)` | Switch the AI context with optional prompt changes. |
463
- | `toggleFunctions(toggles)` | Enable/disable specific SWAIG functions. |
464
- | `sendSms(opts)` | Send an SMS or MMS. |
465
- | `playBackgroundFile(url, wait?)` | Play background audio. |
466
- | `waitForUser(opts?)` | Wait for user input before continuing. |
467
- | `addDynamicHints(hints)` | Add speech recognition hints at runtime. |
468
- | `executeSwml(swml, transfer?)` | Execute arbitrary SWML content. |
469
- | `pay(opts)` | Initiate a payment collection flow. |
470
-
471
- Serialization fallback: if both `response` and `action` are empty, `toDict()` returns `{ response: "Action completed." }`.
472
-
473
- ### DataMap (Server-Side Tools)
474
-
475
- DataMap tools execute entirely on the SignalWire platform without requiring a webhook. They are useful for simple API calls and pattern-matching:
476
-
477
- ```typescript
478
- import { DataMap, FunctionResult } from '@signalwire/sdk';
479
-
480
- const weatherTool = new DataMap('get_weather')
481
- .purpose('Look up weather for a city')
482
- .parameter('city', 'string', 'City name', { required: true })
483
- .webhook('GET', 'https://api.weather.com/v1/current?q=${args.city}', {
484
- headers: { Authorization: 'Bearer ${ENV.WEATHER_API_KEY}' },
485
- })
486
- .output(new FunctionResult('The weather is ${temp}F and ${condition}.'))
487
- .enableEnvExpansion();
488
-
489
- weatherTool.registerWithAgent(agent);
490
- ```
491
-
492
- Convenience helpers:
493
-
494
- ```typescript
495
- import { createSimpleApiTool, createExpressionTool } from '@signalwire/sdk';
496
-
497
- const tool = createSimpleApiTool({
498
- name: 'joke',
499
- url: 'https://api.example.com/joke',
500
- responseTemplate: 'Here is a joke: ${joke}',
501
- });
502
- tool.registerWithAgent(agent);
503
- ```
504
-
505
- ---
506
-
507
- ## Speech and Languages
508
-
509
- ### Hints
510
-
511
- Speech recognition hints improve transcription accuracy for domain-specific vocabulary:
512
-
513
- ```typescript
514
- // Single hint
515
- agent.addHint('SignalWire');
516
-
517
- // Multiple hints
518
- agent.addHints(['HIPAA', 'deductible', 'copay', 'pre-authorization']);
519
-
520
- // Pattern hint (find and replace in transcription)
521
- agent.addPatternHint({
522
- pattern: 'signal wire',
523
- replace: 'SignalWire',
524
- ignoreCase: true,
525
- });
526
- ```
527
-
528
- ### Languages
529
-
530
- Configure supported languages with voice and filler phrases:
531
-
532
- ```typescript
533
- agent.addLanguage({
534
- name: 'English',
535
- code: 'en-US',
536
- voice: 'en-US-Neural2-F',
537
- engine: 'google',
538
- speechModel: 'enhanced',
539
- fillers: { thinking: ['Let me check on that...', 'One moment please...'] },
540
- functionFillers: { get_weather: { 'en-US': ['Checking the forecast...'] } },
541
- });
542
-
543
- agent.addLanguage({
544
- name: 'Spanish',
545
- code: 'es-MX',
546
- voice: 'es-MX-Neural2-A',
547
- });
548
- ```
549
-
550
- Replace all languages at once:
551
-
552
- ```typescript
553
- agent.setLanguages([
554
- { name: 'English', code: 'en-US', voice: 'en-US-Neural2-F' },
555
- { name: 'French', code: 'fr-FR', voice: 'fr-FR-Neural2-A' },
556
- ]);
557
- ```
558
-
559
- ### Pronunciation
560
-
561
- Override how the TTS engine pronounces specific words:
562
-
563
- ```typescript
564
- agent.addPronunciation({
565
- replace: 'SQL',
566
- with: 'sequel',
567
- ignoreCase: true,
568
- });
569
-
570
- agent.addPronunciation({
571
- replace: 'API',
572
- with: 'A P I',
573
- });
574
- ```
575
-
576
- ---
577
-
578
- ## AI Parameters
579
-
580
- Control the AI model's behavior with parameters like temperature and top_p:
581
-
582
- ```typescript
583
- // Set a single parameter
584
- agent.setParam('temperature', 0.7);
585
- agent.setParam('top_p', 0.9);
586
-
587
- // Set multiple parameters at once
588
- agent.setParams({
589
- temperature: 0.3,
590
- top_p: 0.85,
591
- confidence: 0.5,
592
- barge_confidence: 0.3,
593
- presence_penalty: 0.2,
594
- frequency_penalty: 0.5,
595
- });
596
- ```
597
-
598
- ### Prompt-Specific LLM Parameters
599
-
600
- Set LLM parameters that apply specifically to the main prompt or post-prompt:
601
-
602
- ```typescript
603
- // Main prompt LLM params (e.g., model selection, temperature override)
604
- agent.setPromptLlmParams({
605
- model: 'gpt-4',
606
- temperature: 0.2,
607
- });
608
-
609
- // Post-prompt LLM params
610
- agent.setPostPromptLlmParams({
611
- model: 'gpt-3.5-turbo',
612
- temperature: 0.1,
613
- });
614
- ```
615
-
616
- ---
617
-
618
- ## Global Data
619
-
620
- Global data is a key-value store shared across all tool invocations within a call. Tools can read from it and update it:
621
-
622
- ```typescript
623
- // Replace the entire global data object
624
- agent.setGlobalData({
625
- company: 'Acme Corp',
626
- support_hours: '9am-5pm EST',
627
- max_refund: 500,
628
- });
629
-
630
- // Merge additional entries into existing global data
631
- agent.updateGlobalData({
632
- promo_code: 'SUMMER2025',
633
- });
634
- ```
635
-
636
- Within a tool handler, you can update global data dynamically:
637
-
638
- ```typescript
639
- handler: async (args) => {
640
- return new FunctionResult('Customer verified.')
641
- .updateGlobalData({ customer_verified: true, customer_name: args.name });
642
- }
643
- ```
644
-
645
- ---
646
-
647
- ## Call Flow (5 Phases)
648
-
649
- The SWML document is assembled from five sequential phases. Each phase adds verbs to the document's `main` section:
650
-
651
- | Phase | Method | Description |
652
- |-------|--------|-------------|
653
- | **1. Pre-Answer** | `addPreAnswerVerb(verb, config)` | Verbs executed before answering the call (e.g., playing a ring tone). |
654
- | **2. Answer** | `addAnswerVerb(config?)` | The `answer` verb that picks up the call. Automatic when `autoAnswer: true`. |
655
- | **3. Post-Answer** | `addPostAnswerVerb(verb, config)` | Verbs after answering but before the AI starts (e.g., `record_call`, `play`). |
656
- | **4. AI** | *(automatic)* | The `ai` verb containing the prompt, tools, hints, languages, and all AI configuration. |
657
- | **5. Post-AI** | `addPostAiVerb(verb, config)` | Verbs executed after the AI session ends (e.g., `hangup`, `connect`). |
658
-
659
- ### Example
660
-
661
- ```typescript
662
- const agent = new AgentBase({ name: 'ivr-bot', autoAnswer: true, recordCall: true });
663
-
664
- // Phase 1: Play hold music before answering
665
- agent.addPreAnswerVerb('play', {
666
- url: 'https://cdn.example.com/hold-music.mp3',
667
- });
668
-
669
- // Phase 3: Play a greeting after answering, before AI starts
670
- agent.addPostAnswerVerb('play', {
671
- url: 'https://cdn.example.com/greeting.wav',
672
- });
673
-
674
- // Phase 5: Hang up after the AI session ends
675
- agent.addPostAiVerb('hangup', {});
676
- ```
677
-
678
- Note: When `recordCall: true`, a `record_call` verb is automatically inserted at the start of Phase 3.
679
-
680
- ### Clearing Verbs
681
-
682
- ```typescript
683
- agent.clearPreAnswerVerbs();
684
- agent.clearPostAnswerVerbs();
685
- agent.clearPostAiVerbs();
686
- ```
687
-
688
- ---
689
-
690
- ## Dynamic Configuration
691
-
692
- Dynamic configuration lets you modify the agent's settings per-request. On each SWML request, the SDK creates an **ephemeral copy** of the agent, passes it to your callback, and renders SWML from the modified copy. The original agent is never mutated.
693
-
694
- ```typescript
695
- agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, ephemeralAgent) => {
696
- const agent = ephemeralAgent as AgentBase;
697
-
698
- // Customize based on query parameters
699
- const lang = queryParams['lang'];
700
- if (lang === 'es') {
701
- agent.setPromptText('Eres un asistente de servicio al cliente amable.');
702
- agent.addLanguage({ name: 'Spanish', code: 'es-MX', voice: 'es-MX-Neural2-A' });
703
- }
704
-
705
- // Customize based on request headers
706
- const tier = headers['x-customer-tier'];
707
- if (tier === 'premium') {
708
- agent.updateGlobalData({ premium: true, max_refund: 1000 });
709
- }
710
-
711
- // Customize based on body data
712
- const callerId = bodyParams['caller_id_number'] as string;
713
- if (callerId) {
714
- const customer = await lookupCustomer(callerId);
715
- agent.updateGlobalData({ customer_name: customer.name });
716
- }
717
- });
718
- ```
719
-
720
- The callback signature:
721
-
722
- ```typescript
723
- type DynamicConfigCallback = (
724
- queryParams: Record<string, string>, // URL query parameters
725
- bodyParams: Record<string, unknown>, // Parsed request body
726
- headers: Record<string, string>, // HTTP headers
727
- agent: unknown, // Ephemeral AgentBase copy (cast as needed)
728
- ) => void | Promise<void>;
729
- ```
730
-
731
- ### SWAIG Query Parameters
732
-
733
- Append custom query parameters to all SWAIG webhook URLs:
734
-
735
- ```typescript
736
- agent.addSwaigQueryParams({ tenant: 'acme', region: 'us-east' });
737
- ```
738
-
739
- ---
740
-
741
- ## Post-Prompt and Summaries
742
-
743
- The **post-prompt** is a separate prompt evaluated after the call ends. It is typically used to generate a structured summary of the conversation.
744
-
745
- ### Setting the Post-Prompt
746
-
747
- ```typescript
748
- agent.setPostPrompt(`
749
- Summarize this conversation as JSON with the following fields:
750
- - "resolution": whether the issue was resolved (true/false)
751
- - "category": the type of issue (billing, technical, general)
752
- - "summary": a one-sentence summary of the call
753
- `);
754
- ```
755
-
756
- ### Handling Summaries
757
-
758
- Override the `onSummary` lifecycle hook to process the summary when it arrives:
759
-
760
- ```typescript
761
- class MyAgent extends AgentBase {
762
- constructor() {
763
- super({ name: 'my-agent' });
764
- }
765
-
766
- async onSummary(
767
- summary: Record<string, unknown> | null,
768
- rawData: Record<string, unknown>,
769
- ): Promise<void> {
770
- if (summary) {
771
- console.log('Call summary:', summary);
772
- await saveToDatabase(summary);
773
- }
774
- }
775
- }
776
- ```
777
-
778
- ### Post-Prompt LLM Parameters
779
-
780
- You can use a different (often cheaper/faster) model for the post-prompt evaluation:
781
-
782
- ```typescript
783
- agent.setPostPromptLlmParams({
784
- model: 'gpt-3.5-turbo',
785
- temperature: 0.0,
786
- });
787
- ```
788
-
789
- ---
790
-
791
- ## Skills System
792
-
793
- Skills are modular bundles of tools, prompt sections, hints, and global data that can be added to an agent with a single call:
794
-
795
- ```typescript
796
- import { AgentBase, DateTimeSkill, MathSkill, WebSearchSkill } from '@signalwire/sdk';
797
-
798
- const agent = new AgentBase({ name: 'assistant' });
799
-
800
- // Add skills with one-liners
801
- await agent.addSkill(new DateTimeSkill());
802
- await agent.addSkill(new MathSkill());
803
-
804
- // Add skills with custom parameters
805
- await agent.addSkill(new WebSearchSkill({
806
- max_results: 3,
807
- safe_search: 'active',
808
- }));
809
- ```
810
-
811
- When `addSkill()` is called, the `SkillManager` validates environment variables, calls `setup()`, registers tools, merges hints and prompt sections, and merges global data.
812
-
813
- See [skills_system.md](skills_system.md) for the full skills architecture reference.
814
-
815
- ---
816
-
817
- ## Multi-Agent Server
818
-
819
- `AgentServer` hosts multiple `AgentBase` instances on a single HTTP server, each mounted at its own route prefix:
820
-
821
- ```typescript
822
- import { AgentBase, AgentServer } from '@signalwire/sdk';
823
-
824
- const salesAgent = new AgentBase({ name: 'sales', route: '/sales' });
825
- salesAgent.setPromptText('You are a sales representative.');
826
-
827
- const supportAgent = new AgentBase({ name: 'support', route: '/support' });
828
- supportAgent.setPromptText('You are a technical support agent.');
829
-
830
- const server = new AgentServer({ host: '0.0.0.0', port: 4000 });
831
- server.register(salesAgent);
832
- server.register(supportAgent);
833
-
834
- await server.run();
835
- ```
836
-
837
- ### AgentServer Features
838
-
839
- - **Agent listing**: If no agent is mounted at `/`, a GET to `/` returns a JSON listing of all registered agents and their routes.
840
- - **Health endpoints**: `/health` and `/ready` return `{ "status": "ok" }` and `{ "status": "ready" }` respectively.
841
- - **Security headers**: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, and `Referrer-Policy` are set on all responses.
842
- - **CORS**: Enabled globally with `origin: *`.
843
-
844
- ### API
845
-
846
- | Method | Description |
847
- |--------|-------------|
848
- | `register(agent, route?)` | Mount an agent at a route prefix. Throws if the route is already in use. |
849
- | `unregister(route)` | Remove an agent registration. |
850
- | `getAgents()` | Returns a `Map<string, AgentBase>` of all registered agents. |
851
- | `getAgent(route)` | Look up an agent by route. |
852
- | `getApp()` | Returns the underlying Hono application. |
853
- | `run(host?, port?)` | Start the HTTP server. |
854
-
855
- ---
856
-
857
- ## Subclassing AgentBase
858
-
859
- For reusable, self-contained agents, extend `AgentBase`:
860
-
861
- ```typescript
862
- import { AgentBase, FunctionResult } from '@signalwire/sdk';
863
-
864
- class RestaurantBot extends AgentBase {
865
- // Declarative prompt sections
866
- static PROMPT_SECTIONS = [
867
- {
868
- title: 'Role',
869
- body: 'You are a helpful restaurant reservation assistant for Bella Italia.',
870
- },
871
- {
872
- title: 'Guidelines',
873
- bullets: [
874
- 'Be warm and inviting',
875
- 'Always confirm the reservation details before finalizing',
876
- 'Mention daily specials when relevant',
877
- ],
878
- },
879
- ];
880
-
881
- constructor() {
882
- super({ name: 'restaurant-bot', route: '/restaurant' });
883
-
884
- this.addHints(['Bella Italia', 'risotto', 'tiramisu']);
885
- this.setParams({ temperature: 0.6 });
886
-
887
- // Must be called explicitly at the end of the constructor
888
- this.defineTools();
889
- }
890
-
891
- // Override to register tools
892
- protected defineTools(): void {
893
- this.defineTool({
894
- name: 'make_reservation',
895
- description: 'Create a restaurant reservation.',
896
- parameters: {
897
- date: { type: 'string', description: 'Reservation date (YYYY-MM-DD)' },
898
- time: { type: 'string', description: 'Reservation time (HH:MM)' },
899
- party_size: { type: 'number', description: 'Number of guests' },
900
- name: { type: 'string', description: 'Name for the reservation' },
901
- },
902
- required: ['date', 'time', 'party_size', 'name'],
903
- handler: async (args) => {
904
- const id = await createReservation(args);
905
- return new FunctionResult(
906
- `Reservation confirmed for ${args.party_size} on ${args.date} at ${args.time}. ` +
907
- `Confirmation number: ${id}.`,
908
- );
909
- },
910
- });
911
- }
912
-
913
- // Override the post-prompt summary hook
914
- async onSummary(summary: Record<string, unknown> | null): Promise<void> {
915
- if (summary) {
916
- await logReservationSummary(summary);
917
- }
918
- }
919
-
920
- // Override pre-execution hook for all tools
921
- async onFunctionCall(name: string, args: Record<string, unknown>): Promise<void> {
922
- console.log(`Tool invoked: ${name}`, args);
923
- }
924
-
925
- // Override basic auth validation
926
- validateBasicAuth(username: string, password: string): boolean {
927
- return username === 'admin' && password === process.env['ADMIN_PASSWORD']!;
928
- }
929
- }
930
- ```
931
-
932
- ### Extension Points
933
-
934
- | Method / Property | Purpose |
935
- |-------------------|---------|
936
- | `static PROMPT_SECTIONS` | Declarative prompt sections applied in the constructor. |
937
- | `defineTools()` | Override to register tools. Call explicitly at the end of your constructor. |
938
- | `onSummary(summary, rawData)` | Called when a post-prompt summary is received. |
939
- | `onFunctionCall(name, args, rawData)` | Called before each tool handler executes. |
940
- | `onSwmlRequest(rawData)` | Called on every SWML request before rendering. |
941
- | `onDebugEvent(event)` | Called when a debug event webhook is received. |
942
- | `validateBasicAuth(username, password)` | Override to add custom auth validation logic. |
943
-
944
- ---
945
-
946
- ## HTTP Endpoints
947
-
948
- Each agent exposes the following HTTP endpoints (all relative to the agent's `route`):
949
-
950
- | Method | Path | Auth | Description |
951
- |--------|------|------|-------------|
952
- | GET / POST | `/` | Basic Auth | Returns the rendered SWML document. Triggers proxy detection and dynamic config callback. |
953
- | GET / POST | `/swaig` | Basic Auth | SWAIG function dispatcher. Validates tokens for secure tools, calls `onFunctionCall`, executes the handler. |
954
- | GET / POST | `/post_prompt` | Basic Auth | Receives post-prompt summary data. Extracts the summary and calls `onSummary`. |
955
- | POST | `/debug_events` | Basic Auth | Receives debug event webhooks (when `enableDebugEvents()` is active). |
956
- | GET | `/health` | None | Returns `{ "status": "ok" }`. |
957
- | GET | `/ready` | None | Returns `{ "status": "ready" }`. |
958
-
959
- ---
960
-
961
- ## State Management
962
-
963
- ### Global Data
964
-
965
- Global data is shared across all tool invocations within a call. Set initial data on the agent and update it dynamically from tool handlers:
966
-
967
- ```typescript
968
- // Initial data
969
- agent.setGlobalData({ company: 'Acme', tier: 'standard' });
970
-
971
- // In a tool handler -- update data during the call
972
- handler: async (args) => {
973
- return new FunctionResult('Verified.')
974
- .updateGlobalData({ verified: true });
975
- }
976
- ```
977
-
978
- ### Session Metadata
979
-
980
- The `SessionManager` provides per-session in-memory metadata storage:
981
-
982
- ```typescript
983
- import { SessionManager } from '@signalwire/sdk';
984
-
985
- const sm = new SessionManager();
986
- sm.setSessionMetadata('session-1', { userId: 'u-42', plan: 'pro' });
987
- const meta = sm.getSessionMetadata('session-1');
988
- sm.deleteSessionMetadata('session-1');
989
- ```
990
-
991
- ---
992
-
993
- ## SIP Routing
994
-
995
- Enable SIP-based routing to direct calls to specific agents based on the SIP username:
996
-
997
- ```typescript
998
- const server = new AgentServer({ host: '0.0.0.0', port: 4000 });
999
-
1000
- // Register agents
1001
- server.register(salesAgent);
1002
- server.register(supportAgent);
1003
-
1004
- // Map SIP usernames to agent routes
1005
- server.registerSipUsername('sales-line', '/sales');
1006
- server.registerSipUsername('support-line', '/support');
1007
- ```
1008
-
1009
- ---
1010
-
1011
- ## Environment Variables
1012
-
1013
- | Variable | Default | Description |
1014
- |----------|---------|-------------|
1015
- | `PORT` | `3000` | HTTP server port (used when `port` is not specified in `AgentOptions`). |
1016
- | `SWML_BASIC_AUTH_USER` | *(none)* | Basic auth username. Used when `basicAuth` is not provided in options. |
1017
- | `SWML_BASIC_AUTH_PASSWORD` | *(none)* | Basic auth password. Used when `basicAuth` is not provided in options. |
1018
- | `SWML_PROXY_URL_BASE` | *(none)* | External-facing base URL for webhook URLs (e.g., `https://agents.example.com`). |
1019
- | `SWML_PROXY_DEBUG` | `"false"` | Set to `"true"` to enable verbose logging of proxy/header detection. |
1020
- | `SWML_CORS_ORIGINS` | `"*"` | Comma-separated list of allowed CORS origins. |
1021
- | `SWML_ALLOWED_HOSTS` | *(none)* | Comma-separated list of allowed `Host` header values. |
1022
- | `SWML_MAX_REQUEST_SIZE` | `1048576` | Maximum request body size in bytes (default 1 MB). |
1023
- | `SWML_RATE_LIMIT` | *(none)* | Maximum requests per minute per IP address. |
1024
- | `SWML_REQUEST_TIMEOUT` | `30000` | Request timeout in milliseconds. |
1025
- | `SIGNALWIRE_LOG_LEVEL` | `"info"` | Logging level: `"debug"`, `"info"`, `"warn"`, `"error"`. |
1026
- | `SIGNALWIRE_LOG_MODE` | `"pretty"` | Log output format: `"pretty"` for human-readable, `"json"` for structured JSON. |