@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,197 @@
1
+ /**
2
+ * Example: Multi-agent with AgentHandoff.
3
+ *
4
+ * Demonstrates how to use AgentHandoff to switch between different
5
+ * agents within a single session. The triage agent determines the
6
+ * caller's intent and hands off to a specialized agent.
7
+ *
8
+ * Run:
9
+ * npx tsx livewire/examples/livewire-handoff.ts
10
+ *
11
+ * Then point a SignalWire phone number at http://your-host:3000/
12
+ */
13
+
14
+ import {
15
+ Agent,
16
+ AgentSession,
17
+ AgentHandoff,
18
+ tool,
19
+ handoff,
20
+ defineAgent,
21
+ runApp,
22
+ type JobContext,
23
+ } from '../../src/livewire/index.js';
24
+
25
+ // ---------------------------------------------------------------------------
26
+ // Sales Agent
27
+ // ---------------------------------------------------------------------------
28
+
29
+ function createSalesAgent(): Agent {
30
+ const getPricing = tool({
31
+ description: 'Get pricing for a product',
32
+ parameters: {
33
+ type: 'object',
34
+ properties: {
35
+ product: { type: 'string', description: 'Product name' },
36
+ },
37
+ required: ['product'],
38
+ },
39
+ execute: (params: { product: string }) => {
40
+ console.log(`[sales] get_pricing called for: ${params.product}`);
41
+ return (
42
+ `The ${params.product} is available at $29.99/month or $299/year (save 17%). ` +
43
+ 'We also offer a 30-day free trial.'
44
+ );
45
+ },
46
+ });
47
+
48
+ const createOrder = tool({
49
+ description: 'Create an order for a product',
50
+ parameters: {
51
+ type: 'object',
52
+ properties: {
53
+ product: { type: 'string', description: 'Product name' },
54
+ plan: { type: 'string', description: 'Pricing plan (monthly or annual)' },
55
+ },
56
+ required: ['product', 'plan'],
57
+ },
58
+ execute: (params: { product: string; plan: string }) => {
59
+ console.log(`[sales] create_order: product=${params.product} plan=${params.plan}`);
60
+ return (
61
+ `Order created! You're now subscribed to ${params.product} on the ${params.plan} plan. ` +
62
+ 'A confirmation email will arrive shortly.'
63
+ );
64
+ },
65
+ });
66
+
67
+ return new Agent({
68
+ instructions:
69
+ 'You are a sales specialist at Acme Corp. You help customers ' +
70
+ 'find the right products and process orders. Be enthusiastic ' +
71
+ 'but not pushy. Always mention our satisfaction guarantee.',
72
+ tools: {
73
+ get_pricing: { ...getPricing, name: 'get_pricing' },
74
+ create_order: { ...createOrder, name: 'create_order' },
75
+ },
76
+ });
77
+ }
78
+
79
+ // ---------------------------------------------------------------------------
80
+ // Support Agent
81
+ // ---------------------------------------------------------------------------
82
+
83
+ function createSupportAgent(): Agent {
84
+ const checkSystemStatus = tool({
85
+ description: 'Check current system status',
86
+ execute: () => {
87
+ console.log('[support] check_system_status called');
88
+ return 'All systems operational. API uptime: 99.99%. No known issues.';
89
+ },
90
+ });
91
+
92
+ const resetPassword = tool({
93
+ description: 'Send a password reset email',
94
+ parameters: {
95
+ type: 'object',
96
+ properties: {
97
+ email: { type: 'string', description: 'User email address' },
98
+ },
99
+ required: ['email'],
100
+ },
101
+ execute: (params: { email: string }) => {
102
+ console.log(`[support] reset_password called for: ${params.email}`);
103
+ return `Password reset email sent to ${params.email}. The link expires in 30 minutes.`;
104
+ },
105
+ });
106
+
107
+ const createTicket = tool({
108
+ description: 'Create a support ticket',
109
+ parameters: {
110
+ type: 'object',
111
+ properties: {
112
+ issue: { type: 'string', description: 'Description of the issue' },
113
+ priority: { type: 'string', description: 'Priority level: low, medium, high' },
114
+ },
115
+ required: ['issue', 'priority'],
116
+ },
117
+ execute: (params: { issue: string; priority: string }) => {
118
+ console.log(`[support] create_ticket: issue=${params.issue} priority=${params.priority}`);
119
+ return (
120
+ `Support ticket #TKT-10042 created with ${params.priority} priority. ` +
121
+ 'Our team will respond within 4 hours.'
122
+ );
123
+ },
124
+ });
125
+
126
+ return new Agent({
127
+ instructions:
128
+ 'You are a technical support specialist at Acme Corp. You help ' +
129
+ 'customers troubleshoot issues, reset passwords, and resolve ' +
130
+ 'technical problems. Be patient and thorough.',
131
+ tools: {
132
+ check_system_status: { ...checkSystemStatus, name: 'check_system_status' },
133
+ reset_password: { ...resetPassword, name: 'reset_password' },
134
+ create_ticket: { ...createTicket, name: 'create_ticket' },
135
+ },
136
+ });
137
+ }
138
+
139
+ // ---------------------------------------------------------------------------
140
+ // Triage Agent (entry point)
141
+ // ---------------------------------------------------------------------------
142
+
143
+ const agentDef = defineAgent({
144
+ entry: async (ctx: JobContext) => {
145
+ await ctx.connect();
146
+
147
+ // Pre-build the specialized agents
148
+ const salesAgent = createSalesAgent();
149
+ const supportAgent = createSupportAgent();
150
+
151
+ const session = new AgentSession({
152
+ llm: 'openai/gpt-4',
153
+ });
154
+
155
+ // Create handoff tools for the triage agent
156
+ const handoffToSales = tool({
157
+ description: 'Transfer the caller to the sales department',
158
+ execute: () => {
159
+ console.log('[triage] Handing off to sales agent');
160
+ session.say('Let me connect you to our sales team.');
161
+ // In a full implementation, handoff() would trigger a session swap
162
+ const _h = handoff({ agent: salesAgent });
163
+ return 'Connecting you to our sales team now.';
164
+ },
165
+ });
166
+
167
+ const handoffToSupport = tool({
168
+ description: 'Transfer the caller to technical support',
169
+ execute: () => {
170
+ console.log('[triage] Handing off to support agent');
171
+ session.say('Let me connect you to our technical support team.');
172
+ const _h = handoff({ agent: supportAgent });
173
+ return 'Connecting you to our technical support team now.';
174
+ },
175
+ });
176
+
177
+ const triageAgent = new Agent({
178
+ instructions:
179
+ 'You are the front-desk receptionist at Acme Corp. Your job is to ' +
180
+ 'understand what the caller needs and route them to the right department. ' +
181
+ 'Ask clarifying questions if needed, then use the appropriate handoff tool.',
182
+ tools: {
183
+ handoff_to_sales: { ...handoffToSales, name: 'handoff_to_sales' },
184
+ handoff_to_support: { ...handoffToSupport, name: 'handoff_to_support' },
185
+ },
186
+ });
187
+
188
+ await session.start({ agent: triageAgent });
189
+ session.generateReply({
190
+ instructions:
191
+ 'Welcome the caller to Acme Corp. Ask whether they need help ' +
192
+ 'with sales, purchasing, or technical support.',
193
+ });
194
+ },
195
+ });
196
+
197
+ runApp(agentDef);
@@ -0,0 +1,117 @@
1
+ /**
2
+ * Example: LiveWire agent with multiple function tools and RunContext.
3
+ *
4
+ * Demonstrates registering several tools on an agent and using RunContext
5
+ * to access session state. Mirrors a typical @livekit/agents-js pattern.
6
+ *
7
+ * Run:
8
+ * npx tsx livewire/examples/livewire-multi-tool.ts
9
+ *
10
+ * Then point a SignalWire phone number at http://your-host:3000/
11
+ */
12
+
13
+ import {
14
+ Agent,
15
+ AgentSession,
16
+ tool,
17
+ defineAgent,
18
+ runApp,
19
+ type RunContext,
20
+ type JobContext,
21
+ } from '../../src/livewire/index.js';
22
+
23
+ // Tool 1: Check order status
24
+ const checkOrder = tool({
25
+ description: 'Check the status of a customer order',
26
+ parameters: {
27
+ type: 'object',
28
+ properties: {
29
+ order_id: { type: 'string', description: 'The order ID to check, e.g. ORD-12345' },
30
+ },
31
+ required: ['order_id'],
32
+ },
33
+ execute: (params: { order_id: string }, context: { ctx: RunContext }) => {
34
+ console.log(`[tool] check_order called with: ${params.order_id}`);
35
+ const delivery = new Date(Date.now() + 48 * 60 * 60 * 1000).toLocaleDateString();
36
+ return `Order ${params.order_id} is currently in transit. Expected delivery: ${delivery}`;
37
+ },
38
+ });
39
+
40
+ // Tool 2: Product lookup
41
+ const lookupProduct = tool({
42
+ description: 'Search for product information',
43
+ parameters: {
44
+ type: 'object',
45
+ properties: {
46
+ query: { type: 'string', description: 'Product name or keyword to search for' },
47
+ },
48
+ required: ['query'],
49
+ },
50
+ execute: (params: { query: string }) => {
51
+ console.log(`[tool] lookup_product called with: ${params.query}`);
52
+ return (
53
+ `Found 3 products matching '${params.query}': ` +
54
+ '1) Acme Widget Pro ($29.99) ' +
55
+ '2) Acme Widget Lite ($14.99) ' +
56
+ '3) Acme Widget Bundle ($39.99)'
57
+ );
58
+ },
59
+ });
60
+
61
+ // Tool 3: Schedule callback
62
+ const scheduleCallback = tool({
63
+ description: 'Schedule a callback from a human agent',
64
+ execute: () => {
65
+ const callbackTime = new Date(Date.now() + 2 * 60 * 60 * 1000).toLocaleTimeString();
66
+ return `Callback scheduled for ${callbackTime}. An agent will call you back.`;
67
+ },
68
+ });
69
+
70
+ // Tool 4: Escalate to human
71
+ const escalate = tool({
72
+ description: 'Escalate the call to a human agent',
73
+ parameters: {
74
+ type: 'object',
75
+ properties: {
76
+ reason: { type: 'string', description: 'Reason for escalation' },
77
+ },
78
+ required: ['reason'],
79
+ },
80
+ execute: (params: { reason: string }) => {
81
+ const reason = params.reason.toLowerCase();
82
+ let department = 'general support';
83
+ if (reason.includes('billing')) department = 'billing';
84
+ else if (reason.includes('technical')) department = 'technical support';
85
+ return `Transferring you to ${department}. Please hold.`;
86
+ },
87
+ });
88
+
89
+ const agentDef = defineAgent({
90
+ entry: async (ctx: JobContext) => {
91
+ await ctx.connect();
92
+
93
+ const session = new AgentSession({
94
+ llm: 'openai/gpt-4',
95
+ });
96
+
97
+ const agent = new Agent({
98
+ instructions:
99
+ 'You are a helpful customer support agent for Acme Corp. ' +
100
+ 'You can check order status, look up product information, ' +
101
+ 'and schedule callbacks. Be concise and helpful.',
102
+ tools: {
103
+ check_order: { ...checkOrder, name: 'check_order' },
104
+ lookup_product: { ...lookupProduct, name: 'lookup_product' },
105
+ schedule_callback: { ...scheduleCallback, name: 'schedule_callback' },
106
+ escalate: { ...escalate, name: 'escalate' },
107
+ },
108
+ });
109
+
110
+ await session.start({ agent });
111
+ session.generateReply({
112
+ instructions: 'Welcome the caller to Acme Corp support. Ask how you can help them today.',
113
+ });
114
+ },
115
+ });
116
+
117
+ runApp(agentDef);
package/package.json ADDED
@@ -0,0 +1,38 @@
1
+ {
2
+ "name": "@signalwire/sdk",
3
+ "version": "2.0.0",
4
+ "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "swaig-test": "./dist/cli/swaig-test.js"
10
+ },
11
+ "scripts": {
12
+ "generate:verbs": "npx tsx src/generateVerbTypes.ts",
13
+ "prebuild": "npm run generate:verbs",
14
+ "build": "tsc",
15
+ "test": "vitest run",
16
+ "test:watch": "vitest",
17
+ "dev": "tsc --watch"
18
+ },
19
+ "engines": {
20
+ "node": ">=18.0.0"
21
+ },
22
+ "license": "MIT",
23
+ "dependencies": {
24
+ "@hono/node-server": "^1.11.0",
25
+ "ajv": "^8.18.0",
26
+ "cheerio": "^1.2.0",
27
+ "hono": "^4.4.0",
28
+ "js-yaml": "^4.1.1",
29
+ "ws": "^8.17.0"
30
+ },
31
+ "devDependencies": {
32
+ "@types/js-yaml": "^4.0.9",
33
+ "@types/node": "^20.14.0",
34
+ "@types/ws": "^8.5.10",
35
+ "typescript": "^5.5.0",
36
+ "vitest": "^4.1.5"
37
+ }
38
+ }
@@ -0,0 +1,70 @@
1
+ # SignalWire RELAY Client
2
+
3
+ Real-time call control and messaging over WebSocket using TypeScript. The RELAY client connects to SignalWire via the Blade protocol (JSON-RPC 2.0 over WebSocket) and gives you imperative control over live phone calls and SMS/MMS messaging.
4
+
5
+ ## Quick Start
6
+
7
+ ```typescript
8
+ import { RelayClient, Call } from '@signalwire/sdk';
9
+
10
+ const client = new RelayClient({
11
+ contexts: ['default'],
12
+ });
13
+
14
+ client.onCall(async (call: Call) => {
15
+ await call.answer();
16
+ const action = await call.play([
17
+ { type: 'tts', text: 'Welcome to SignalWire!' },
18
+ ]);
19
+ await action.wait();
20
+ await call.hangup();
21
+ });
22
+
23
+ client.run();
24
+ ```
25
+
26
+ ## Features
27
+
28
+ - Auto-reconnect with exponential backoff
29
+ - All 40+ calling methods: play, record, collect, connect, detect, tap, stream, AI, and more
30
+ - SMS/MMS messaging: send outbound messages, receive inbound messages, track delivery state
31
+ - Action objects with `wait()`, `stop()`, `pause()`, `resume()` for controllable operations
32
+ - Typed event classes for all call events
33
+ - JWT and legacy authentication
34
+ - Dynamic context subscription/unsubscription
35
+
36
+ ## Documentation
37
+
38
+ - [Getting Started](docs/guide.md) — installation, configuration, first call
39
+
40
+ ## Examples
41
+
42
+ - [relay-inbound.ts](examples/relay-inbound.ts) — answer an inbound call, play TTS, collect digits
43
+ - [relay-outbound.ts](examples/relay-outbound.ts) — dial outbound, detect answering machine, play message
44
+ - [relay-messaging.ts](examples/relay-messaging.ts) — send SMS, track delivery, receive inbound messages
45
+
46
+ ## Environment Variables
47
+
48
+ | Variable | Description |
49
+ |----------|-------------|
50
+ | `SIGNALWIRE_PROJECT_ID` | Project ID for authentication |
51
+ | `SIGNALWIRE_TOKEN` | API token for authentication |
52
+ | `SIGNALWIRE_JWT_TOKEN` | JWT token (alternative to project/token) |
53
+ | `SIGNALWIRE_SPACE` | Space hostname (default: `relay.signalwire.com`) |
54
+ | `SIGNALWIRE_LOG_LEVEL` | Log level (`debug` for WebSocket traffic) |
55
+
56
+ ## Module Structure
57
+
58
+ ```
59
+ src/relay/
60
+ index.ts # Public exports
61
+ RelayClient.ts # WebSocket connection, auth, event dispatch, reconnect
62
+ Call.ts # Call object — 40+ calling methods and Action tracking
63
+ Action.ts # Base Action + 11 subclasses (Play, Record, Detect, etc.)
64
+ Message.ts # SMS/MMS message tracking with Deferred-based wait()
65
+ RelayEvent.ts # Base + 22 typed event subclasses, parseEvent() dispatcher
66
+ Deferred.ts # Promise wrapper for async correlation
67
+ RelayError.ts # Typed error class with code field
68
+ constants.ts # Protocol constants, call states, event types
69
+ types.ts # TypeScript interfaces
70
+ ```