@signalwire/sdk 2.0.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 (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Simple Static Agent Example
3
+ *
4
+ * The most minimal possible agent: no tools, no dynamic config,
5
+ * just a prompt and a voice. Useful as a starting template.
6
+ * Run: npx tsx examples/simple-static.ts
7
+ * Test: curl http://user:pass@localhost:3000/
8
+ */
9
+
10
+ import { AgentBase } from '../src/index.js';
11
+
12
+ export const agent = new AgentBase({
13
+ name: 'greeter',
14
+ route: '/',
15
+ basicAuth: [
16
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
17
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
18
+ ],
19
+ });
20
+
21
+ agent.setPromptText(
22
+ 'You are a friendly greeter. Welcome each caller warmly, ' +
23
+ 'ask how their day is going, and make pleasant small talk. ' +
24
+ 'Keep responses brief and conversational.',
25
+ );
26
+
27
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
28
+
29
+ agent.run();
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Skills Demo Example
3
+ *
4
+ * Shows how to add built-in skills (datetime, math) to an agent.
5
+ * Skills inject tools, prompt sections, and hints automatically.
6
+ * Run: npx tsx examples/skills-demo.ts
7
+ */
8
+
9
+ import { AgentBase, DateTimeSkill, MathSkill } from '../src/index.js';
10
+
11
+ export const agent = new AgentBase({
12
+ name: 'skilled-agent',
13
+ route: '/',
14
+ basicAuth: [
15
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
16
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
17
+ ],
18
+ });
19
+
20
+ agent.setPromptText(
21
+ 'You are a helpful assistant with access to time and math tools. ' +
22
+ 'Use the available tools to answer questions about dates, times, and calculations.',
23
+ );
24
+
25
+ // Add skills — each injects its own tools, prompt sections, and hints
26
+ await agent.addSkill(new DateTimeSkill());
27
+ await agent.addSkill(new MathSkill());
28
+
29
+ // List what skills are loaded
30
+ console.log('Loaded skills:', agent.listSkills().map(s => s.name));
31
+
32
+ // Query parameter schemas programmatically
33
+ console.log('DateTimeSkill parameters:', DateTimeSkill.getParameterSchema());
34
+ console.log('MathSkill parameters:', MathSkill.getParameterSchema());
35
+
36
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
37
+
38
+ agent.run();
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Step Function Inheritance Demo
3
+ *
4
+ * This example exists to teach one specific gotcha: the per-step `functions`
5
+ * whitelist INHERITS from the previous step when omitted.
6
+ *
7
+ * Why this matters
8
+ * ----------------
9
+ * A common mistake when building multi-step agents is to assume each step
10
+ * starts with a fresh tool set. It does not. The runtime only resets the
11
+ * active set when a step explicitly declares its `functions` field. If you
12
+ * forget setFunctions() on a later step, the previous step's tools quietly
13
+ * remain available.
14
+ *
15
+ * This file shows four step-shaped patterns side by side:
16
+ *
17
+ * 1. step_lookup — explicitly whitelists `lookup_account`
18
+ * 2. step_inherit — has NO setFunctions() call. Inherits step_lookup's
19
+ * whitelist, so `lookup_account` is still callable here.
20
+ * This is rarely what you want.
21
+ * 3. step_explicit — explicitly whitelists `process_payment`. The previously
22
+ * inherited `lookup_account` is now disabled, and only
23
+ * `process_payment` is active.
24
+ * 4. step_disabled — explicitly disables ALL user functions with []
25
+ * (or 'none'). Internal tools like next_step still work.
26
+ *
27
+ * Best practice
28
+ * -------------
29
+ * Call setFunctions() on EVERY step that should differ from the previous one.
30
+ * Treat omission as an explicit decision to inherit, not a default.
31
+ *
32
+ * Run this file just to see the rendered SWML — there are no real webhook
33
+ * endpoints behind the tools, this is purely a documentation example.
34
+ */
35
+
36
+ import { AgentBase } from '../src/AgentBase.js';
37
+ import { FunctionResult } from '../src/FunctionResult.js';
38
+
39
+ class StepFunctionInheritanceAgent extends AgentBase {
40
+ constructor() {
41
+ super({ name: 'step_function_inheritance_demo', route: '/' });
42
+
43
+ // Register three SWAIG tools so we have something to whitelist.
44
+ // In a real agent these would call out to webhooks; here they're stubs.
45
+ this.defineTool({
46
+ name: 'lookup_account',
47
+ description: 'Look up customer account details by account number',
48
+ parameters: { account_number: { type: 'string' } },
49
+ handler: async () => new FunctionResult('looked up'),
50
+ });
51
+ this.defineTool({
52
+ name: 'process_payment',
53
+ description: 'Process a payment for the current customer',
54
+ parameters: { amount: { type: 'number' } },
55
+ handler: async () => new FunctionResult('payment processed'),
56
+ });
57
+ this.defineTool({
58
+ name: 'send_receipt',
59
+ description: 'Email a receipt to the customer',
60
+ parameters: { email: { type: 'string' } },
61
+ handler: async () => new FunctionResult('sent'),
62
+ });
63
+
64
+ // Build the contexts.
65
+ const contexts = this.defineContexts();
66
+ const ctx = contexts.addContext('default');
67
+
68
+ // ── Step 1: explicit whitelist ─────────────────────────────────
69
+ // `lookup_account` is the only tool active in this step.
70
+ ctx
71
+ .addStep('step_lookup')
72
+ .setText(
73
+ 'Greet the customer and ask for their account number. ' +
74
+ 'Use lookup_account to fetch their details.',
75
+ )
76
+ .setFunctions(['lookup_account'])
77
+ .setValidSteps(['step_inherit']);
78
+
79
+ // ── Step 2: NO setFunctions() call → inheritance ──────────────
80
+ // Because we didn't call setFunctions(), this step inherits the
81
+ // active set from step_lookup. `lookup_account` is STILL callable
82
+ // here, even though we never asked for it. Most of the time this
83
+ // is a bug. To break the inheritance, call setFunctions() with an
84
+ // explicit list (even if it's empty).
85
+ ctx
86
+ .addStep('step_inherit')
87
+ .setText(
88
+ "Confirm the customer's identity. (No setFunctions() here, " +
89
+ 'so lookup_account is still active — this is the inheritance ' +
90
+ 'trap.)',
91
+ )
92
+ .setValidSteps(['step_explicit']);
93
+
94
+ // ── Step 3: explicit replacement ───────────────────────────────
95
+ // Whitelist replaces the inherited set. lookup_account is now
96
+ // inactive; only process_payment is active.
97
+ ctx
98
+ .addStep('step_explicit')
99
+ .setText(
100
+ "Take the customer's payment. Use process_payment. " +
101
+ 'lookup_account is no longer available.',
102
+ )
103
+ .setFunctions(['process_payment'])
104
+ .setValidSteps(['step_disabled']);
105
+
106
+ // ── Step 4: explicit disable-all ───────────────────────────────
107
+ // Pass [] (or 'none') to lock out every user-defined tool.
108
+ // Internal navigation tools (next_step) are unaffected.
109
+ ctx
110
+ .addStep('step_disabled')
111
+ .setText(
112
+ 'Thank the customer and wrap up. No tools are needed here, ' +
113
+ 'so we lock everything down with setFunctions([]).',
114
+ )
115
+ .setFunctions([])
116
+ .setEnd(true);
117
+ }
118
+ }
119
+
120
+ const agent = new StepFunctionInheritanceAgent();
121
+ // Render and pretty-print the resulting SWML so you can see exactly
122
+ // which steps have a `functions` key in the output and which don't.
123
+ const swml = agent.renderSwml();
124
+ console.log(JSON.stringify(JSON.parse(swml), null, 2));
@@ -0,0 +1,187 @@
1
+ /**
2
+ * SWAIG Features Showcase
3
+ *
4
+ * Demonstrates the full range of FunctionResult actions:
5
+ * hangup, hold, say, context switching, dynamic hints, global data,
6
+ * metadata, toggleFunctions, background audio, and more.
7
+ * Run: npx tsx examples/swaig-features.ts
8
+ */
9
+
10
+ import { AgentBase, FunctionResult } from '../src/index.js';
11
+
12
+ export const agent = new AgentBase({
13
+ name: 'features-agent',
14
+ route: '/',
15
+ basicAuth: [
16
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
17
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
18
+ ],
19
+ });
20
+
21
+ agent.setPromptText(
22
+ 'You are a demo assistant showing off all SWAIG function result actions. ' +
23
+ 'The user can ask you to perform various call control actions.',
24
+ );
25
+
26
+ // Hang up the call
27
+ agent.defineTool({
28
+ name: 'end_call',
29
+ description: 'End the call when the user wants to hang up',
30
+ parameters: {},
31
+ handler: () => {
32
+ const result = new FunctionResult('Goodbye! Ending the call now.');
33
+ result.hangup();
34
+ return result;
35
+ },
36
+ });
37
+
38
+ // Place on hold
39
+ agent.defineTool({
40
+ name: 'hold_call',
41
+ description: 'Place the caller on hold',
42
+ parameters: {
43
+ seconds: { type: 'number', description: 'Hold duration in seconds (max 900)' },
44
+ },
45
+ handler: (args) => {
46
+ const secs = (args.seconds as number) ?? 60;
47
+ const result = new FunctionResult(
48
+ `Placing you on hold for ${secs} seconds.`,
49
+ );
50
+ result.hold(secs);
51
+ return result;
52
+ },
53
+ });
54
+
55
+ // Say something via TTS
56
+ agent.defineTool({
57
+ name: 'announce',
58
+ description: 'Make an announcement to the caller',
59
+ parameters: {
60
+ message: { type: 'string', description: 'The announcement message' },
61
+ },
62
+ handler: (args) => {
63
+ const result = new FunctionResult('Making announcement.');
64
+ result.say(args.message as string);
65
+ return result;
66
+ },
67
+ });
68
+
69
+ // Play background music
70
+ agent.defineTool({
71
+ name: 'play_music',
72
+ description: 'Play background music during the call',
73
+ parameters: {
74
+ url: { type: 'string', description: 'URL of the audio file' },
75
+ },
76
+ handler: (args) => {
77
+ const result = new FunctionResult('Playing background music.');
78
+ result.playBackgroundFile(args.url as string);
79
+ return result;
80
+ },
81
+ });
82
+
83
+ // Stop background music
84
+ agent.defineTool({
85
+ name: 'stop_music',
86
+ description: 'Stop any playing background music',
87
+ parameters: {},
88
+ handler: () => {
89
+ const result = new FunctionResult('Stopping background music.');
90
+ result.stopBackgroundFile();
91
+ return result;
92
+ },
93
+ });
94
+
95
+ // Update global data
96
+ agent.defineTool({
97
+ name: 'save_preference',
98
+ description: 'Save a user preference to the call session',
99
+ parameters: {
100
+ key: { type: 'string', description: 'Preference key' },
101
+ value: { type: 'string', description: 'Preference value' },
102
+ },
103
+ handler: (args) => {
104
+ const result = new FunctionResult(
105
+ `Saved preference: ${args.key} = ${args.value}`,
106
+ );
107
+ result.updateGlobalData({ [args.key as string]: args.value });
108
+ return result;
109
+ },
110
+ });
111
+
112
+ // Set call metadata
113
+ agent.defineTool({
114
+ name: 'tag_call',
115
+ description: 'Add a tag to the current call for tracking',
116
+ parameters: {
117
+ tag: { type: 'string', description: 'Tag to add to the call' },
118
+ },
119
+ handler: (args) => {
120
+ const result = new FunctionResult(`Call tagged as "${args.tag}".`);
121
+ result.setMetadata({ tag: args.tag });
122
+ return result;
123
+ },
124
+ });
125
+
126
+ // Context switch
127
+ agent.defineTool({
128
+ name: 'switch_mode',
129
+ description: 'Switch the AI to a different mode or personality',
130
+ parameters: {
131
+ mode: { type: 'string', description: 'New mode: "formal" or "casual"' },
132
+ },
133
+ handler: (args) => {
134
+ const prompt =
135
+ args.mode === 'formal'
136
+ ? 'You are now a formal, professional assistant. Use proper language.'
137
+ : 'You are now a casual, friendly assistant. Be relaxed and conversational.';
138
+ const result = new FunctionResult(`Switched to ${args.mode} mode.`);
139
+ result.switchContext({ systemPrompt: prompt });
140
+ return result;
141
+ },
142
+ });
143
+
144
+ // Send SMS
145
+ agent.defineTool({
146
+ name: 'send_sms',
147
+ description: 'Send an SMS message to a phone number',
148
+ parameters: {
149
+ to: { type: 'string', description: 'Recipient phone number' },
150
+ message: { type: 'string', description: 'SMS message text' },
151
+ },
152
+ handler: (args) => {
153
+ const result = new FunctionResult(
154
+ `SMS sent to ${args.to}: "${args.message}"`,
155
+ );
156
+ result.sendSms({
157
+ toNumber: args.to as string,
158
+ fromNumber: '+15551234567',
159
+ body: args.message as string,
160
+ });
161
+ return result;
162
+ },
163
+ });
164
+
165
+ // Toggle functions dynamically
166
+ agent.defineTool({
167
+ name: 'lock_down',
168
+ description: 'Disable all tools except end_call for security',
169
+ parameters: {},
170
+ handler: () => {
171
+ const result = new FunctionResult(
172
+ 'Entering secure mode. Only the end call function is available.',
173
+ );
174
+ result.toggleFunctions([
175
+ { function: 'hold_call', active: false },
176
+ { function: 'announce', active: false },
177
+ { function: 'play_music', active: false },
178
+ { function: 'stop_music', active: false },
179
+ { function: 'send_sms', active: false },
180
+ ]);
181
+ return result;
182
+ },
183
+ });
184
+
185
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
186
+
187
+ agent.run();
@@ -0,0 +1,66 @@
1
+ /**
2
+ * SWML Service Routing Example
3
+ *
4
+ * Demonstrates dynamic SWML routing using SWMLService's onRequestCallback.
5
+ * Different SWML documents are generated based on query parameters,
6
+ * enabling a single endpoint to serve multiple call flows.
7
+ * Run: npx tsx examples/swml-service-routing.ts
8
+ * Test:
9
+ * curl http://user:pass@localhost:3000/?dept=sales
10
+ * curl http://user:pass@localhost:3000/?dept=support
11
+ * curl http://user:pass@localhost:3000/ (default IVR)
12
+ */
13
+
14
+ import { SWMLService, SwmlBuilder } from '../src/index.js';
15
+
16
+ export const agent = new SWMLService({
17
+ name: 'ivr-router',
18
+ route: '/',
19
+ basicAuth: [
20
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
21
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
22
+ ],
23
+ });
24
+
25
+ // Dynamic routing: build different SWML based on request parameters
26
+ agent.setOnRequestCallback(async (queryParams, _bodyParams, _headers) => {
27
+ const builder = new SwmlBuilder();
28
+ const dept = queryParams['dept'];
29
+
30
+ builder.addVerb('answer', { max_duration: 300 });
31
+
32
+ if (dept === 'sales') {
33
+ builder.addVerb('play', {
34
+ url: 'say:Thank you for calling the sales department. Please hold while we connect you.',
35
+ });
36
+ builder.addVerb('connect', {
37
+ from: '+15551234567',
38
+ to: '+15559876543',
39
+ });
40
+ } else if (dept === 'support') {
41
+ builder.addVerb('play', {
42
+ url: 'say:Thank you for calling technical support. Your call is important to us.',
43
+ });
44
+ builder.addVerb('record', {
45
+ stereo: true,
46
+ format: 'mp3',
47
+ beep: true,
48
+ terminators: '#',
49
+ });
50
+ } else {
51
+ // Default IVR menu
52
+ builder.addVerb('play', {
53
+ url: 'say:Welcome to Acme Corp. Press 1 for sales, 2 for support, or stay on the line for the operator.',
54
+ });
55
+ builder.addVerb('sleep', 3);
56
+ builder.addVerb('play', {
57
+ url: 'say:Connecting you to an operator. Please hold.',
58
+ });
59
+ }
60
+
61
+ builder.addVerb('hangup', {});
62
+
63
+ return builder;
64
+ });
65
+
66
+ agent.run();
@@ -0,0 +1,38 @@
1
+ /**
2
+ * SWML Service Example
3
+ *
4
+ * A non-AI SWML service that builds IVR call flows without an AI block.
5
+ * Uses SWMLService instead of AgentBase for pure call-flow control.
6
+ * Run: npx tsx examples/swml-service.ts
7
+ */
8
+
9
+ import { SWMLService, SwmlBuilder } from '../src/index.js';
10
+
11
+ export const agent = new SWMLService({
12
+ name: 'ivr-menu',
13
+ route: '/',
14
+ basicAuth: [
15
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
16
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
17
+ ],
18
+ });
19
+
20
+ // Build a simple IVR: answer → play greeting → record voicemail → hangup
21
+ agent.addVerb('answer', { max_duration: 300 });
22
+ agent.addVerb('play', {
23
+ url: 'say:Thank you for calling Acme Corp. All agents are currently busy. Please leave a message after the beep.',
24
+ });
25
+ agent.addVerb('record', {
26
+ stereo: true,
27
+ format: 'mp3',
28
+ direction: 'both',
29
+ terminators: '#',
30
+ beep: true,
31
+ });
32
+ agent.addVerb('play', { url: 'say:Thank you. Goodbye!' });
33
+ agent.addVerb('hangup', {});
34
+
35
+ // Print the generated SWML
36
+ console.log('SWML Document:', JSON.stringify(agent.renderSwml(), null, 2));
37
+
38
+ agent.run();
@@ -0,0 +1,68 @@
1
+ /**
2
+ * TAP (Media Tap) Example
3
+ *
4
+ * Demonstrates using the TAP action to stream call audio to an
5
+ * external RTP endpoint for real-time processing (e.g., analytics,
6
+ * transcription, or recording to an external system).
7
+ * Run: npx tsx examples/tap.ts
8
+ */
9
+
10
+ import { AgentBase, FunctionResult } from '../src/index.js';
11
+
12
+ export const agent = new AgentBase({
13
+ name: 'tap-agent',
14
+ route: '/',
15
+ basicAuth: [
16
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
17
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
18
+ ],
19
+ });
20
+
21
+ agent.setPromptText(
22
+ 'You are a helpful assistant. The call audio can be streamed to ' +
23
+ 'an external system for real-time processing. You can start and stop ' +
24
+ 'the audio tap when the caller requests it.',
25
+ );
26
+
27
+ // Start audio streaming via TAP
28
+ agent.defineTool({
29
+ name: 'start_tap',
30
+ description: 'Start streaming call audio to an external RTP endpoint',
31
+ parameters: {
32
+ uri: {
33
+ type: 'string',
34
+ description: 'RTP URI to stream audio to (e.g., rtp://192.168.1.100:5000)',
35
+ },
36
+ },
37
+ handler: (args) => {
38
+ const result = new FunctionResult(
39
+ 'Audio streaming started. Call audio is now being sent to the external system.',
40
+ );
41
+ result.tap({
42
+ uri: args.uri as string,
43
+ controlId: 'main-tap',
44
+ direction: 'both',
45
+ codec: 'PCMU',
46
+ });
47
+ return result;
48
+ },
49
+ });
50
+
51
+ // Stop audio streaming
52
+ agent.defineTool({
53
+ name: 'stop_tap',
54
+ description: 'Stop streaming call audio to the external endpoint',
55
+ parameters: {},
56
+ handler: () => {
57
+ const result = new FunctionResult(
58
+ 'Audio streaming stopped.',
59
+ );
60
+ result.stopTap('main-tap');
61
+ return result;
62
+ },
63
+ });
64
+
65
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
66
+ agent.addHints(['tap', 'stream', 'RTP', 'audio']);
67
+
68
+ agent.run();
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Verb Methods Example
3
+ *
4
+ * Demonstrates SwmlBuilder's auto-vivified verb methods for
5
+ * building SWML call flows with fluent chaining.
6
+ * Run: npx tsx examples/verb-methods.ts
7
+ */
8
+
9
+ import { AgentBase, SwmlBuilder } from '../src/index.js';
10
+
11
+ export const agent = new AgentBase({
12
+ name: 'verb-demo',
13
+ route: '/',
14
+ basicAuth: [
15
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
16
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
17
+ ],
18
+ });
19
+
20
+ agent.setPromptText('You are a helpful assistant.');
21
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
22
+
23
+ // Use SwmlBuilder verb methods to control the call flow
24
+ // Phase 1: Pre-answer — play ringing
25
+ agent.addPreAnswerVerb('play', { urls: ['ring:us'], auto_answer: false });
26
+
27
+ // Phase 3: Post-answer — play a welcome message, then a short pause
28
+ agent.addPostAnswerVerb('play', {
29
+ url: 'say:Welcome! Please hold while I connect you.',
30
+ });
31
+ agent.addPostAnswerVerb('sleep', 1);
32
+
33
+ // Phase 5: Post-AI — hangup after the AI conversation
34
+ agent.addPostAiVerb('hangup', {});
35
+
36
+ // You can also build standalone SWML documents with SwmlBuilder directly:
37
+ const ivr = new SwmlBuilder();
38
+ ivr.addVerb('answer', { max_duration: 300 });
39
+ ivr.addVerb('play', { url: 'say:Hello from the SWML builder!' });
40
+ ivr.addVerb('sleep', 2);
41
+ ivr.addVerb('hangup', {});
42
+
43
+ console.log('Standalone SWML:', JSON.stringify(ivr.getDocument(), null, 2));
44
+
45
+ agent.run();
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Web Search Multiple Instance Demo
3
+ *
4
+ * Loads the web search skill multiple times with different configurations and
5
+ * custom tool names (general search, news search, quick search).
6
+ *
7
+ * Requires GOOGLE_SEARCH_API_KEY and GOOGLE_SEARCH_CX environment variables.
8
+ * Run: npx tsx examples/web-search-multi-instance.ts
9
+ */
10
+
11
+ import {
12
+ AgentBase,
13
+ WebSearchSkill,
14
+ WikipediaSkill,
15
+ DateTimeSkill,
16
+ MathSkill,
17
+ } from '../src/index.js';
18
+
19
+ export const agent = new AgentBase({
20
+ name: 'multi-search',
21
+ route: '/',
22
+ basicAuth: [
23
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
24
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
25
+ ],
26
+ });
27
+
28
+ agent.setPromptText(
29
+ 'You are a research assistant with access to multiple search tools. ' +
30
+ 'Use the most appropriate search tool for each query: ' +
31
+ 'general web search, news search, quick search, or Wikipedia.',
32
+ );
33
+
34
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
35
+ agent.addHints(['search', 'look up', 'find', 'news', 'Wikipedia']);
36
+
37
+ // Utility skills
38
+ await agent.addSkill(new DateTimeSkill());
39
+ await agent.addSkill(new MathSkill());
40
+
41
+ // Wikipedia search
42
+ await agent.addSkill(new WikipediaSkill({ max_results: 2 }));
43
+
44
+ // Instance 1: General web search (default tool name)
45
+ await agent.addSkill(
46
+ new WebSearchSkill({
47
+ max_results: 3,
48
+ safe_search: 'medium',
49
+ }),
50
+ );
51
+
52
+ // Instance 2: News-focused search
53
+ await agent.addSkill(
54
+ new WebSearchSkill({
55
+ tool_name: 'search_news',
56
+ max_results: 5,
57
+ safe_search: 'medium',
58
+ }),
59
+ );
60
+
61
+ // Instance 3: Quick single-result search
62
+ await agent.addSkill(
63
+ new WebSearchSkill({
64
+ tool_name: 'quick_search',
65
+ max_results: 1,
66
+ }),
67
+ );
68
+
69
+ console.log('Loaded skills:', agent.listSkills().map(s => s.name));
70
+ console.log('Search tools: web_search (general), search_news, quick_search, search_wiki');
71
+
72
+ agent.run();