@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,71 @@
1
+ /**
2
+ * Gather Info with Steps Example
3
+ *
4
+ * Uses the ContextBuilder with GatherInfo to collect structured
5
+ * information from the caller through a guided conversation flow.
6
+ * Run: npx tsx examples/gather-info.ts
7
+ */
8
+
9
+ import { AgentBase, FunctionResult, GatherInfo, GatherQuestion } from '../src/index.js';
10
+
11
+ export const agent = new AgentBase({
12
+ name: 'intake-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 medical office intake assistant. Collect patient information ' +
22
+ 'step by step. Be polite and professional.',
23
+ );
24
+
25
+ // Define a tool for final submission
26
+ agent.defineTool({
27
+ name: 'submit_intake',
28
+ description: 'Submit the completed intake form',
29
+ parameters: {
30
+ patient_name: { type: 'string', description: 'Full name of the patient' },
31
+ reason: { type: 'string', description: 'Reason for visit' },
32
+ },
33
+ handler: (args) => {
34
+ return new FunctionResult(
35
+ `Intake form submitted for ${args.patient_name}. Reason: ${args.reason}. ` +
36
+ 'A nurse will be with you shortly.',
37
+ );
38
+ },
39
+ });
40
+
41
+ // Define structured conversation flow with steps
42
+ const ctx = agent.defineContexts();
43
+ const intake = ctx.addContext('default');
44
+
45
+ // Step 1: Welcome and collect name
46
+ intake
47
+ .addStep('welcome', { task: 'Welcome the patient and ask for their full name.' })
48
+ .setStepCriteria('Patient has provided their full name')
49
+ .setFunctions('none')
50
+ .setValidSteps(['reason']);
51
+
52
+ // Step 2: Collect reason for visit
53
+ intake
54
+ .addStep('reason', {
55
+ task: 'Ask the patient about their reason for visiting today.',
56
+ })
57
+ .setStepCriteria('Patient has described their reason for the visit')
58
+ .setFunctions('none')
59
+ .setValidSteps(['confirm']);
60
+
61
+ // Step 3: Confirm and submit
62
+ intake
63
+ .addStep('confirm', {
64
+ task: 'Confirm the collected information with the patient and submit the intake form.',
65
+ })
66
+ .setFunctions(['submit_intake'])
67
+ .setEnd(true);
68
+
69
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
70
+
71
+ agent.run();
@@ -0,0 +1,140 @@
1
+ /**
2
+ * Per-Question Function Whitelist Demo (gather_info)
3
+ *
4
+ * This example exists to teach one specific gotcha: while a step's gather_info
5
+ * is asking questions, ALL of the step's other functions are forcibly
6
+ * deactivated. The only callable tools during a gather question are:
7
+ *
8
+ * - `gather_submit` (the native answer-submission tool, always active)
9
+ * - Whatever names you list in that question's `functions` option
10
+ *
11
+ * `next_step` and `change_context` are also filtered out — the model literally
12
+ * cannot navigate away until the gather completes. This is by design: it
13
+ * forces a tight ask → submit → next-question loop.
14
+ *
15
+ * If a question needs to call out to a tool — for example, to validate an
16
+ * email format, geocode a ZIP, or look up something from an external service
17
+ * — you must list that tool name in the question's `functions` option. The
18
+ * function is active ONLY for that question.
19
+ *
20
+ * Below: a customer-onboarding gather flow where each question unlocks a
21
+ * different validation tool, and where the step's own non-gather tools
22
+ * (escalate_to_human, lookup_existing_account) are LOCKED OUT during gather
23
+ * because they aren't whitelisted on any question.
24
+ *
25
+ * Run this file to see the resulting SWML.
26
+ */
27
+
28
+ import { AgentBase } from '../src/AgentBase.js';
29
+ import { FunctionResult } from '../src/FunctionResult.js';
30
+
31
+ class GatherPerQuestionFunctionsAgent extends AgentBase {
32
+ constructor() {
33
+ super({ name: 'gather_per_question_functions_demo', route: '/' });
34
+
35
+ // Tools that the step would normally have available — but during
36
+ // gather questioning, they're all locked out unless they appear in
37
+ // a question's `functions` whitelist.
38
+ this.defineTool({
39
+ name: 'validate_email',
40
+ description: 'Validate that an email address is well-formed and deliverable',
41
+ parameters: { email: { type: 'string' } },
42
+ handler: async () => new FunctionResult('valid'),
43
+ });
44
+ this.defineTool({
45
+ name: 'geocode_zip',
46
+ description: 'Look up the city/state for a US ZIP code',
47
+ parameters: { zip: { type: 'string' } },
48
+ handler: async () => new FunctionResult('{"city":"...","state":"..."}'),
49
+ });
50
+ this.defineTool({
51
+ name: 'check_age_eligibility',
52
+ description: 'Verify the customer is old enough for the product',
53
+ parameters: { age: { type: 'integer' } },
54
+ handler: async () => new FunctionResult('eligible'),
55
+ });
56
+ // These tools are NOT whitelisted on any gather question. They are
57
+ // registered on the agent and active outside the gather, but during
58
+ // the gather they cannot be called — gather mode locks them out.
59
+ this.defineTool({
60
+ name: 'escalate_to_human',
61
+ description: 'Transfer the conversation to a live agent',
62
+ parameters: {},
63
+ handler: async () => new FunctionResult('transferred'),
64
+ });
65
+ this.defineTool({
66
+ name: 'lookup_existing_account',
67
+ description: 'Search for an existing account by email',
68
+ parameters: { email: { type: 'string' } },
69
+ handler: async () => new FunctionResult('not found'),
70
+ });
71
+
72
+ // Build a single-context agent with one onboarding step.
73
+ const contexts = this.defineContexts();
74
+ const ctx = contexts.addContext('default');
75
+
76
+ ctx
77
+ .addStep('onboard')
78
+ .setText(
79
+ 'Onboard a new customer by collecting their details. Use ' +
80
+ 'gather_info to ask one question at a time. Each question ' +
81
+ 'may unlock a specific validation tool — only that tool ' +
82
+ 'and gather_submit are callable while answering it.',
83
+ )
84
+ .setFunctions([
85
+ // Outside of the gather (which is the entire step here),
86
+ // these would be available. During the gather they are
87
+ // forcibly hidden in favor of the per-question whitelists.
88
+ 'escalate_to_human',
89
+ 'lookup_existing_account',
90
+ ])
91
+ .setGatherInfo({
92
+ outputKey: 'customer',
93
+ completionAction: 'next_step',
94
+ prompt:
95
+ "I'll need to collect a few details to set up your " +
96
+ "account. I'll ask one question at a time.",
97
+ })
98
+ .addGatherQuestion({
99
+ key: 'email',
100
+ question: "What's your email address?",
101
+ confirm: true,
102
+ // Only validate_email + gather_submit are callable here.
103
+ functions: ['validate_email'],
104
+ })
105
+ .addGatherQuestion({
106
+ key: 'zip',
107
+ question: "What's your ZIP code?",
108
+ // Only geocode_zip + gather_submit are callable here.
109
+ functions: ['geocode_zip'],
110
+ })
111
+ .addGatherQuestion({
112
+ key: 'age',
113
+ question: 'How old are you?',
114
+ type: 'integer',
115
+ // Only check_age_eligibility + gather_submit are callable here.
116
+ functions: ['check_age_eligibility'],
117
+ })
118
+ .addGatherQuestion({
119
+ key: 'referral_source',
120
+ question: 'How did you hear about us?',
121
+ // No functions option → only gather_submit is callable.
122
+ // The model cannot validate, lookup, escalate — nothing.
123
+ // This is the right pattern when a question needs no tools.
124
+ });
125
+
126
+ // A simple confirmation step the gather auto-advances into.
127
+ ctx
128
+ .addStep('confirm')
129
+ .setText(
130
+ 'Read the collected info back to the customer and ' +
131
+ 'confirm everything is correct.',
132
+ )
133
+ .setFunctions([])
134
+ .setEnd(true);
135
+ }
136
+ }
137
+
138
+ const agent = new GatherPerQuestionFunctionsAgent();
139
+ const swml = agent.renderSwml();
140
+ console.log(JSON.stringify(JSON.parse(swml), null, 2));
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Joke Agent Example
3
+ *
4
+ * A fun agent that uses the built-in Joke skill to tell jokes.
5
+ * Run: npx tsx examples/joke-agent.ts
6
+ */
7
+
8
+ import { AgentBase, JokeSkill, DateTimeSkill } from '../src/index.js';
9
+
10
+ export const agent = new AgentBase({
11
+ name: 'joke-agent',
12
+ route: '/',
13
+ basicAuth: [
14
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
15
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
16
+ ],
17
+ });
18
+
19
+ agent.setPromptText(
20
+ 'You are a friendly comedian named Chuckles. Your job is to make people laugh! ' +
21
+ 'Tell jokes when asked, and try to keep the mood light and fun. ' +
22
+ 'You can also tell the time if someone asks.',
23
+ );
24
+
25
+ // Add the joke skill — injects the tell_joke tool, prompt sections, and hints
26
+ await agent.addSkill(new JokeSkill());
27
+
28
+ // Also add datetime so we can answer "what time is it?" questions
29
+ await agent.addSkill(new DateTimeSkill());
30
+
31
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
32
+ agent.addHints(['joke', 'funny', 'comedy', 'laugh', 'punchline']);
33
+
34
+ agent.run();
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Kubernetes-Ready Agent Example
3
+ *
4
+ * Agent with graceful shutdown for clean K8s/Docker stops,
5
+ * health check endpoints, and structured logging.
6
+ * Run: npx tsx examples/kubernetes-agent.ts
7
+ */
8
+
9
+ import { AgentBase, FunctionResult } from '../src/index.js';
10
+
11
+ // Set up graceful shutdown before anything else
12
+ AgentBase.setupGracefulShutdown({ timeout: 10000 });
13
+
14
+ export const agent = new AgentBase({
15
+ name: 'k8s-agent',
16
+ route: '/',
17
+ basicAuth: [
18
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
19
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
20
+ ],
21
+ });
22
+
23
+ agent.setPromptText(
24
+ 'You are a production-grade assistant running in Kubernetes. ' +
25
+ 'Respond helpfully and professionally.',
26
+ );
27
+
28
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
29
+
30
+ agent.defineTool({
31
+ name: 'get_status',
32
+ description: 'Get the current service status',
33
+ parameters: {},
34
+ handler: () => {
35
+ return new FunctionResult(
36
+ `Service is healthy. Uptime: ${Math.floor(process.uptime())}s. Memory: ${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)}MB.`,
37
+ );
38
+ },
39
+ });
40
+
41
+ // Health check is built into AgentBase at /health and /ready
42
+ // K8s liveness probe: GET /health -> {"status":"ok"}
43
+ // K8s readiness probe: GET /ready -> {"status":"ready"}
44
+
45
+ agent.run();
@@ -0,0 +1,69 @@
1
+ /**
2
+ * LLM Parameters Example
3
+ *
4
+ * Fine-tune AI behavior: temperature, top_p, barge confidence,
5
+ * speech recognition hints, fillers, and post-prompt instructions.
6
+ * Run: npx tsx examples/llm-params.ts
7
+ */
8
+
9
+ import { AgentBase, FunctionResult } from '../src/index.js';
10
+
11
+ export const agent = new AgentBase({
12
+ name: 'tuned-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 precise, factual assistant for a medical office. ' +
22
+ 'Always confirm information before proceeding. Never guess or speculate.',
23
+ );
24
+
25
+ // LLM parameters — low temperature for precision
26
+ agent.setParams({
27
+ temperature: 0.2,
28
+ top_p: 0.9,
29
+ confidence: 0.6,
30
+ barge_confidence: 0.3,
31
+ barge_match_string: 'stop,cancel,hold on',
32
+ attention_timeout: 15000,
33
+ inactivity_timeout: 20000,
34
+ background_file_loops: -1,
35
+ background_file_volume: 10,
36
+ });
37
+
38
+ // Language with function-level fillers
39
+ agent.addLanguage({
40
+ name: 'English',
41
+ code: 'en-US',
42
+ voice: 'rachel',
43
+ fillers: ['one moment please', 'let me check that for you', 'just a second'],
44
+ functionFillers: ['looking that up now', 'searching our records'],
45
+ });
46
+
47
+ // Post-prompt for structured call summary
48
+ agent.setPostPrompt(
49
+ 'Summarize this call as JSON with fields: patient_name, appointment_type, date_requested, special_instructions.',
50
+ );
51
+
52
+ // Speech recognition hints for medical terms
53
+ agent.addHints(['appointment', 'prescription', 'referral', 'lab results', 'follow-up']);
54
+ agent.addPronunciation({ replace: 'Dr.', with: 'Doctor' });
55
+
56
+ agent.defineTool({
57
+ name: 'check_availability',
58
+ description: 'Check appointment availability for a given date',
59
+ parameters: {
60
+ date: { type: 'string', description: 'The requested date (YYYY-MM-DD)' },
61
+ },
62
+ handler: (args) => {
63
+ return new FunctionResult(
64
+ `Availability for ${args.date}: 9:00 AM, 11:30 AM, 2:00 PM slots open.`,
65
+ );
66
+ },
67
+ });
68
+
69
+ agent.run();
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Example: MCP Integration -- Client and Server
3
+ *
4
+ * This agent demonstrates both MCP features:
5
+ *
6
+ * 1. MCP Server: Exposes tools at /mcp so external MCP clients
7
+ * (Claude Desktop, other agents) can discover and invoke them.
8
+ *
9
+ * 2. MCP Client: Connects to an external MCP server to pull in additional
10
+ * tools for voice calls.
11
+ *
12
+ * Run:
13
+ * npx tsx examples/mcp-agent.ts
14
+ *
15
+ * Then:
16
+ * - Point a SignalWire phone number at http://your-server:3000/agent
17
+ * - Connect Claude Desktop to http://your-server:3000/agent/mcp
18
+ */
19
+
20
+ import { AgentBase, FunctionResult } from '../src/index.js';
21
+
22
+ const agent = new AgentBase({
23
+ name: 'mcp-agent',
24
+ route: '/agent',
25
+ basicAuth: [
26
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
27
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
28
+ ],
29
+ });
30
+
31
+ // -- MCP Server --
32
+ // Adds a /mcp endpoint that speaks JSON-RPC 2.0 (MCP protocol).
33
+ agent.enableMcpServer();
34
+
35
+ // -- MCP Client --
36
+ // Connect to an external MCP server. Tools are discovered automatically.
37
+ agent.addMcpServer('https://mcp.example.com/tools', {
38
+ headers: { Authorization: 'Bearer sk-your-mcp-api-key' },
39
+ });
40
+
41
+ // -- MCP Client with Resources --
42
+ agent.addMcpServer('https://mcp.example.com/crm', {
43
+ headers: { Authorization: 'Bearer sk-your-crm-key' },
44
+ resources: true,
45
+ resourceVars: { caller_id: '${caller_id_number}', tenant: 'acme-corp' },
46
+ });
47
+
48
+ // -- Agent Configuration --
49
+ agent.promptAddSection('Role', {
50
+ body: 'You are a helpful customer support agent. '
51
+ + 'You have access to the customer\'s profile via global_data.',
52
+ });
53
+ agent.promptAddSection('Customer Context', {
54
+ body: 'Customer name: ${global_data.customer_name}\n'
55
+ + 'Account status: ${global_data.account_status}',
56
+ });
57
+
58
+ agent.setParams({ attention_timeout: 15000 });
59
+
60
+ // -- Local Tools --
61
+ agent.defineTool({
62
+ name: 'get_weather',
63
+ description: 'Get the current weather for a location',
64
+ parameters: { location: { type: 'string', description: 'City name or zip code' } },
65
+ handler: (args: Record<string, unknown>) => {
66
+ const location = (args['location'] as string) || 'unknown';
67
+ return new FunctionResult(`Currently 72F and sunny in ${location}.`);
68
+ },
69
+ });
70
+
71
+ agent.defineTool({
72
+ name: 'create_ticket',
73
+ description: 'Create a support ticket for the customer',
74
+ parameters: {
75
+ subject: { type: 'string', description: 'Ticket subject' },
76
+ description: { type: 'string', description: 'Detailed description' },
77
+ },
78
+ handler: (args: Record<string, unknown>) => {
79
+ const subject = (args['subject'] as string) || 'No subject';
80
+ return new FunctionResult(`Ticket created: '${subject}'. Reference: TK-12345.`);
81
+ },
82
+ });
83
+
84
+ agent.run();
@@ -0,0 +1,35 @@
1
+ /**
2
+ * MCP Gateway Skill Example
3
+ *
4
+ * Demonstrates the MCP (Model Context Protocol) gateway skill,
5
+ * which is a placeholder for future MCP server integration.
6
+ * Run: npx tsx examples/mcp-gateway.ts
7
+ */
8
+
9
+ import { AgentBase, McpGatewaySkill } from '../src/index.js';
10
+
11
+ export const agent = new AgentBase({
12
+ name: 'mcp-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 an assistant with access to external tools via MCP (Model Context Protocol). ' +
22
+ 'Use the available tools to help the caller with their requests.',
23
+ );
24
+
25
+ // Add MCP Gateway skill — currently a stub for future implementation
26
+ await agent.addSkill(
27
+ new McpGatewaySkill({
28
+ gateway_url: 'http://localhost:8080/mcp',
29
+ tool_prefix: 'ext',
30
+ }),
31
+ );
32
+
33
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
34
+
35
+ agent.run();
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Multi-Agent Server Example
3
+ *
4
+ * Host multiple agents under a single HTTP server, each at its own route.
5
+ * Run: npx tsx examples/multi-agent.ts
6
+ * Test:
7
+ * curl http://user:pass@localhost:3000/support
8
+ * curl http://user:pass@localhost:3000/sales
9
+ * curl http://localhost:3000/ (agent listing)
10
+ * curl http://localhost:3000/health
11
+ */
12
+
13
+ import { AgentBase, AgentServer, FunctionResult } from '../src/index.js';
14
+
15
+ // --- Support Agent ---
16
+ export const support = new AgentBase({
17
+ name: 'support',
18
+ route: '/support',
19
+ basicAuth: [
20
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
21
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
22
+ ],
23
+ });
24
+
25
+ support.setPromptText('You are a customer support agent. Help resolve issues quickly and politely.');
26
+ support.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
27
+
28
+ support.defineTool({
29
+ name: 'lookup_ticket',
30
+ description: 'Look up a support ticket by ID',
31
+ parameters: {
32
+ ticket_id: { type: 'string', description: 'The ticket ID' },
33
+ },
34
+ handler: (args) => {
35
+ return new FunctionResult(`Ticket ${args.ticket_id}: Status is "In Progress", assigned to Team B.`);
36
+ },
37
+ });
38
+
39
+ // --- Sales Agent ---
40
+ export const sales = new AgentBase({
41
+ name: 'sales',
42
+ route: '/sales',
43
+ basicAuth: [
44
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
45
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
46
+ ],
47
+ });
48
+
49
+ sales.setPromptText('You are a sales agent. Help potential customers understand our products and pricing.');
50
+ sales.addLanguage({ name: 'English', code: 'en-US', voice: 'dave' });
51
+
52
+ sales.defineTool({
53
+ name: 'get_pricing',
54
+ description: 'Get pricing information for a product',
55
+ parameters: {
56
+ product: { type: 'string', description: 'Product name' },
57
+ },
58
+ handler: (args) => {
59
+ const prices: Record<string, string> = {
60
+ basic: '$29/mo',
61
+ pro: '$99/mo',
62
+ enterprise: 'Custom pricing - schedule a call',
63
+ };
64
+ const price = prices[args.product?.toLowerCase()] ?? 'Product not found';
65
+ return new FunctionResult(`Pricing for ${args.product}: ${price}`);
66
+ },
67
+ });
68
+
69
+ // --- Server ---
70
+ const server = new AgentServer({ port: 3000 });
71
+ server.register(support);
72
+ server.register(sales);
73
+ server.run();
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Multi-Endpoint Example
3
+ *
4
+ * An AgentServer hosting multiple agents at different SWML routes,
5
+ * with a shared static file directory and custom health endpoint.
6
+ * Run: npx tsx examples/multi-endpoint.ts
7
+ * Test:
8
+ * curl http://user:pass@localhost:3000/billing
9
+ * curl http://user:pass@localhost:3000/tech-support
10
+ * curl http://localhost:3000/ (agent listing)
11
+ * curl http://localhost:3000/health
12
+ */
13
+
14
+ import { AgentBase, AgentServer, FunctionResult } from '../src/index.js';
15
+
16
+ // --- Billing Agent ---
17
+ const billing = new AgentBase({
18
+ name: 'billing',
19
+ route: '/billing',
20
+ basicAuth: [
21
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
22
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
23
+ ],
24
+ });
25
+
26
+ billing.setPromptText(
27
+ 'You are a billing specialist. Help callers with invoices, payments, and account balances.',
28
+ );
29
+
30
+ billing.defineTool({
31
+ name: 'get_balance',
32
+ description: 'Get the account balance for a customer',
33
+ parameters: {
34
+ account_id: { type: 'string', description: 'Customer account ID' },
35
+ },
36
+ handler: (args) => {
37
+ return new FunctionResult(
38
+ `Account ${args.account_id}: Balance is $142.50. Last payment: $50.00 on Jan 15.`,
39
+ );
40
+ },
41
+ });
42
+
43
+ billing.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
44
+
45
+ // --- Tech Support Agent ---
46
+ const techSupport = new AgentBase({
47
+ name: 'tech-support',
48
+ route: '/tech-support',
49
+ basicAuth: [
50
+ process.env['SWML_BASIC_AUTH_USER'] ?? 'user',
51
+ process.env['SWML_BASIC_AUTH_PASSWORD'] ?? 'pass',
52
+ ],
53
+ });
54
+
55
+ techSupport.setPromptText(
56
+ 'You are a technical support specialist. Help diagnose and resolve product issues.',
57
+ );
58
+
59
+ techSupport.defineTool({
60
+ name: 'run_diagnostic',
61
+ description: 'Run a remote diagnostic on the customer device',
62
+ parameters: {
63
+ device_id: { type: 'string', description: 'Device serial number' },
64
+ },
65
+ handler: (args) => {
66
+ return new FunctionResult(
67
+ `Diagnostic for device ${args.device_id}: All systems normal. Firmware: v2.3.1 (up to date).`,
68
+ );
69
+ },
70
+ });
71
+
72
+ techSupport.addLanguage({ name: 'English', code: 'en-US', voice: 'dave' });
73
+ techSupport.setParam('temperature', 0.2);
74
+
75
+ // --- Server ---
76
+ const server = new AgentServer({ port: 3000 });
77
+ server.register(billing);
78
+ server.register(techSupport);
79
+ server.run();