@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,467 @@
1
+ # Skills System Reference
2
+
3
+ Architectural reference for the Skills system in the SignalWire AI Agents TypeScript SDK.
4
+
5
+ ---
6
+
7
+ ## Table of Contents
8
+
9
+ 1. [Architecture](#architecture)
10
+ 2. [SkillBase](#skillbase)
11
+ 3. [SkillManager](#skillmanager)
12
+ 4. [SkillRegistry](#skillregistry)
13
+ 5. [Tool Registration Flow](#tool-registration-flow)
14
+ 6. [Built-in Skills](#built-in-skills)
15
+ 7. [Creating a Custom Skill](#creating-a-custom-skill)
16
+ 8. [Multi-Instance Skills](#multi-instance-skills)
17
+ 9. [Environment Validation](#environment-validation)
18
+ 10. [Parameter Schema Discovery](#parameter-schema-discovery)
19
+ 11. [Lifecycle Hooks](#lifecycle-hooks)
20
+
21
+ ---
22
+
23
+ ## Architecture
24
+
25
+ The skills system consists of three cooperating components:
26
+
27
+ ```
28
+ SkillRegistry (singleton)
29
+ |
30
+ +-- registers skill factories by name
31
+ |
32
+ +-- SkillBase subclasses
33
+ |
34
+ +-- provide tools, prompts, hints, global data
35
+ |
36
+ +-- managed by SkillManager (per-agent)
37
+ ```
38
+
39
+ | Component | Responsibility |
40
+ |---|---|
41
+ | **SkillBase** | Abstract base class every skill extends. Declares tools, prompts, hints, and config schema. |
42
+ | **SkillManager** | Attached to each `AgentBase`. Loads, validates, and wires skills into the agent. |
43
+ | **SkillRegistry** | Global singleton. Maps skill names to factory functions for `agent.addSkill()` lookups. |
44
+
45
+ ---
46
+
47
+ ## SkillBase
48
+
49
+ All skills extend `SkillBase`. The base class defines the contract:
50
+
51
+ ```typescript
52
+ import { SkillBase, FunctionResult } from '@signalwire/sdk';
53
+ import type { SkillManifest, SkillToolRegistration } from '@signalwire/sdk';
54
+
55
+ class MySkill extends SkillBase {
56
+ static manifest: SkillManifest = {
57
+ name: 'my_skill',
58
+ version: '1.0.0',
59
+ description: 'Does something useful',
60
+ requiredEnvVars: ['MY_API_KEY'],
61
+ supportsMultipleInstances: false,
62
+ };
63
+
64
+ registerTools(): SkillToolRegistration[] {
65
+ return [
66
+ {
67
+ name: 'my_tool',
68
+ description: 'Performs the action',
69
+ parameters: { query: { type: 'string', description: 'Input' } },
70
+ handler: (args: Record<string, unknown>) => {
71
+ return new FunctionResult(`Result for ${args.query}`);
72
+ },
73
+ },
74
+ ];
75
+ }
76
+
77
+ getHints(): string[] {
78
+ return ['my skill', 'useful action'];
79
+ }
80
+
81
+ getPromptSections(): Array<{ title: string; body: string; bullets?: string[] }> {
82
+ return [
83
+ {
84
+ title: 'My Skill',
85
+ body: 'You have access to my_tool for performing useful actions.',
86
+ },
87
+ ];
88
+ }
89
+
90
+ getGlobalData(): Record<string, unknown> {
91
+ return { my_skill_enabled: true };
92
+ }
93
+ }
94
+ ```
95
+
96
+ ### Key Methods
97
+
98
+ | Method | Returns | Purpose |
99
+ |---|---|---|
100
+ | `registerTools()` | `SkillToolRegistration[]` | Define the SWAIG tools this skill provides. |
101
+ | `getHints()` | `string[]` | Speech recognition hints for ASR accuracy. |
102
+ | `getPromptSections()` | Section array | Prompt text injected into the agent's system prompt. |
103
+ | `getGlobalData()` | `Record<string, unknown>` | Key-value pairs merged into agent global data. |
104
+ | `setup()` | `Promise<void>` | Async initialization (API connections, file loading). |
105
+ | `teardown()` | `Promise<void>` | Cleanup on agent shutdown. |
106
+
107
+ ### SkillManifest Interface
108
+
109
+ ```typescript
110
+ interface SkillManifest {
111
+ name: string; // Unique skill identifier
112
+ version: string; // Semantic version
113
+ description: string; // Human-readable description
114
+ requiredEnvVars?: string[]; // Environment variables that must be set
115
+ supportsMultipleInstances?: boolean; // Whether multiple instances can coexist
116
+ }
117
+ ```
118
+
119
+ ---
120
+
121
+ ## SkillManager
122
+
123
+ Each `AgentBase` has an internal `SkillManager`. When you call `agent.addSkill()`, the manager:
124
+
125
+ 1. Validates required environment variables from the skill manifest.
126
+ 2. Calls `skill.setup()` for async initialization.
127
+ 3. Registers all tools from `skill.registerTools()` with the agent.
128
+ 4. Merges hints from `skill.getHints()` into the agent's hint list.
129
+ 5. Adds prompt sections from `skill.getPromptSections()` to the POM.
130
+ 6. Merges global data from `skill.getGlobalData()`.
131
+
132
+ ### Usage
133
+
134
+ ```typescript
135
+ import { AgentBase, DateTimeSkill, MathSkill } from '@signalwire/sdk';
136
+
137
+ const agent = new AgentBase({ name: 'assistant' });
138
+
139
+ // Add skills
140
+ await agent.addSkill(new DateTimeSkill());
141
+ await agent.addSkill(new MathSkill());
142
+
143
+ // Query loaded skills
144
+ const skills = agent.listSkills();
145
+ // => [{ name: 'datetime', version: '1.0.0', description: '...' }, ...]
146
+
147
+ // Check if a skill is loaded
148
+ if (agent.hasSkill('datetime')) {
149
+ console.log('DateTime skill is active');
150
+ }
151
+
152
+ // Remove a skill
153
+ agent.removeSkill('datetime');
154
+ ```
155
+
156
+ ---
157
+
158
+ ## SkillRegistry
159
+
160
+ The global registry allows skills to be discovered by name:
161
+
162
+ ```typescript
163
+ import { SkillRegistry } from '@signalwire/sdk';
164
+
165
+ // List all registered skills
166
+ const available = SkillRegistry.listSkills();
167
+ // => [{ name: 'datetime', description: '...', version: '1.0.0' }, ...]
168
+
169
+ // Get a skill's parameter schema
170
+ const schema = SkillRegistry.getParameterSchema('web_search');
171
+ // => { max_results: { type: 'number', default: 5 }, ... }
172
+ ```
173
+
174
+ Built-in skills register themselves automatically when imported. Custom skills must call `SkillRegistry.register()`:
175
+
176
+ ```typescript
177
+ SkillRegistry.register('my_skill', (config) => new MySkill(config));
178
+ ```
179
+
180
+ ---
181
+
182
+ ## Tool Registration Flow
183
+
184
+ ```
185
+ agent.addSkill(new WebSearchSkill({ max_results: 5 }))
186
+ |
187
+ v
188
+ SkillManager.loadSkill(skill)
189
+ |
190
+ +-- validate env vars (GOOGLE_SEARCH_API_KEY, etc.)
191
+ +-- skill.setup() // async init
192
+ +-- skill.registerTools() // get tool definitions
193
+ | |
194
+ | v
195
+ +-- agent.defineTool(...) // register each tool on the agent
196
+ +-- agent.addHints(...) // merge hints
197
+ +-- agent.promptAddSection(...) // add prompt text
198
+ +-- agent.updateGlobalData(...) // merge global data
199
+ ```
200
+
201
+ ---
202
+
203
+ ## Built-in Skills
204
+
205
+ The SDK includes 18 built-in skills:
206
+
207
+ | Skill | Class | Tools | Required Env Vars |
208
+ |-------|-------|-------|-------------------|
209
+ | datetime | `DateTimeSkill` | `get_current_time`, `get_current_date` | -- |
210
+ | math | `MathSkill` | `calculate` | -- |
211
+ | joke | `JokeSkill` | `tell_joke` | -- |
212
+ | weather_api | `WeatherApiSkill` | `get_weather` | `WEATHER_API_KEY` |
213
+ | web_search | `WebSearchSkill` | `web_search` | `GOOGLE_SEARCH_API_KEY`, `GOOGLE_SEARCH_ENGINE_ID` |
214
+ | wikipedia_search | `WikipediaSearchSkill` | `search_wiki` | -- |
215
+ | google_maps | `GoogleMapsSkill` | `lookup_address`, `compute_route` | `GOOGLE_MAPS_API_KEY` |
216
+ | spider | `SpiderSkill` | `scrape_url` | -- |
217
+ | datasphere | `DataSphereSkill` | `search_datasphere` | `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_TOKEN` |
218
+ | datasphere_serverless | `DataSphereServerlessSkill` | `search_datasphere` | `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_TOKEN` |
219
+ | swml_transfer | `SwmlTransferSkill` | `transfer_call` | -- |
220
+ | play_background_file | `PlayBackgroundFileSkill` | `play_background_file`, `stop_background_file` | -- |
221
+ | api_ninjas_trivia | `ApiNinjasTriviaSkill` | `get_trivia` | `API_NINJAS_KEY` |
222
+ | native_vector_search | `NativeVectorSearchSkill` | `search_knowledge` | -- |
223
+ | info_gatherer | `InfoGathererSkill` | `start_questions`, `submit_answer` | -- |
224
+ | claude_skills | `ClaudeSkillsSkill` | *(from SKILL.md files)* | -- |
225
+ | mcp_gateway | `McpGatewaySkill` | *(MCP server bridge)* | -- |
226
+ | custom_skills | `CustomSkillsSkill` | *(user-defined from config)* | -- |
227
+
228
+ ### Example Usage
229
+
230
+ ```typescript
231
+ import {
232
+ AgentBase, DateTimeSkill, MathSkill, WebSearchSkill,
233
+ WeatherApiSkill, WikipediaSearchSkill, JokeSkill,
234
+ } from '@signalwire/sdk';
235
+
236
+ const agent = new AgentBase({ name: 'assistant' });
237
+
238
+ // Skills without env vars work immediately
239
+ await agent.addSkill(new DateTimeSkill());
240
+ await agent.addSkill(new MathSkill());
241
+ await agent.addSkill(new JokeSkill());
242
+ await agent.addSkill(new WikipediaSearchSkill());
243
+
244
+ // Skills with env vars require them to be set
245
+ // WEATHER_API_KEY must be set in the environment
246
+ await agent.addSkill(new WeatherApiSkill());
247
+
248
+ // Skills with custom configuration
249
+ await agent.addSkill(new WebSearchSkill({
250
+ max_results: 3,
251
+ safe_search: 'active',
252
+ }));
253
+ ```
254
+
255
+ ---
256
+
257
+ ## Creating a Custom Skill
258
+
259
+ ### Step 1: Extend SkillBase
260
+
261
+ ```typescript
262
+ import { SkillBase, FunctionResult } from '@signalwire/sdk';
263
+ import type { SkillManifest, SkillToolRegistration } from '@signalwire/sdk';
264
+
265
+ export class StockPriceSkill extends SkillBase {
266
+ static manifest: SkillManifest = {
267
+ name: 'stock_price',
268
+ version: '1.0.0',
269
+ description: 'Look up current stock prices',
270
+ requiredEnvVars: ['STOCK_API_KEY'],
271
+ supportsMultipleInstances: false,
272
+ };
273
+
274
+ private apiKey: string;
275
+
276
+ constructor(config: Record<string, unknown> = {}) {
277
+ super(config);
278
+ this.apiKey = process.env['STOCK_API_KEY'] ?? '';
279
+ }
280
+
281
+ registerTools(): SkillToolRegistration[] {
282
+ return [
283
+ {
284
+ name: 'get_stock_price',
285
+ description: 'Get the current price of a stock by ticker symbol',
286
+ parameters: {
287
+ ticker: { type: 'string', description: 'Stock ticker symbol (e.g. AAPL)' },
288
+ },
289
+ handler: async (args: Record<string, unknown>) => {
290
+ const ticker = String(args.ticker).toUpperCase();
291
+ const price = await this.fetchPrice(ticker);
292
+ return new FunctionResult(`${ticker} is currently trading at $${price}`);
293
+ },
294
+ },
295
+ ];
296
+ }
297
+
298
+ getHints(): string[] {
299
+ return ['stock', 'ticker', 'price', 'market', 'shares', 'NYSE', 'NASDAQ'];
300
+ }
301
+
302
+ getPromptSections() {
303
+ return [
304
+ {
305
+ title: 'Stock Price Lookup',
306
+ body: 'You can look up current stock prices using the get_stock_price tool. ' +
307
+ 'Ask the user for a ticker symbol if they want a price quote.',
308
+ },
309
+ ];
310
+ }
311
+
312
+ getGlobalData() {
313
+ return { stock_skill_enabled: true };
314
+ }
315
+
316
+ async setup(): Promise<void> {
317
+ // Validate API key format, warm up connections, etc.
318
+ if (!this.apiKey) {
319
+ throw new Error('STOCK_API_KEY is required');
320
+ }
321
+ }
322
+
323
+ private async fetchPrice(ticker: string): Promise<string> {
324
+ const resp = await fetch(
325
+ `https://api.stocks.example.com/price/${ticker}`,
326
+ { headers: { Authorization: `Bearer ${this.apiKey}` } },
327
+ );
328
+ const data = await resp.json() as { price: number };
329
+ return data.price.toFixed(2);
330
+ }
331
+ }
332
+ ```
333
+
334
+ ### Step 2: Register (Optional)
335
+
336
+ ```typescript
337
+ import { SkillRegistry } from '@signalwire/sdk';
338
+ SkillRegistry.register('stock_price', (config) => new StockPriceSkill(config));
339
+ ```
340
+
341
+ ### Step 3: Use
342
+
343
+ ```typescript
344
+ await agent.addSkill(new StockPriceSkill());
345
+ ```
346
+
347
+ ---
348
+
349
+ ## Multi-Instance Skills
350
+
351
+ Some skills support multiple instances with different configurations. Set `supportsMultipleInstances: true` in the manifest and accept a `tool_name` config parameter:
352
+
353
+ ```typescript
354
+ import { DataSphereSkill } from '@signalwire/sdk';
355
+
356
+ // Two DataSphere instances with different knowledge bases
357
+ await agent.addSkill(new DataSphereSkill({
358
+ document_id: 'drinks-doc',
359
+ tool_name: 'search_drinks',
360
+ }));
361
+
362
+ await agent.addSkill(new DataSphereSkill({
363
+ document_id: 'food-doc',
364
+ tool_name: 'search_food',
365
+ }));
366
+ ```
367
+
368
+ Each instance registers its tools under the configured `tool_name`, avoiding collisions.
369
+
370
+ ---
371
+
372
+ ## Environment Validation
373
+
374
+ Skills declare required environment variables in their manifest. The `SkillManager` checks these before calling `setup()`:
375
+
376
+ ```typescript
377
+ static manifest: SkillManifest = {
378
+ name: 'weather_api',
379
+ version: '1.0.0',
380
+ description: 'Weather lookups',
381
+ requiredEnvVars: ['WEATHER_API_KEY'],
382
+ };
383
+ ```
384
+
385
+ If any required variable is missing, `addSkill()` throws with a descriptive error message listing the missing variables.
386
+
387
+ ```typescript
388
+ try {
389
+ await agent.addSkill(new WeatherApiSkill());
390
+ } catch (err) {
391
+ // Error: Missing required environment variables for weather_api: WEATHER_API_KEY
392
+ }
393
+ ```
394
+
395
+ ---
396
+
397
+ ## Parameter Schema Discovery
398
+
399
+ Skills can expose their configuration schema for tooling and documentation:
400
+
401
+ ```typescript
402
+ // Get the parameter schema for a skill class
403
+ const schema = WebSearchSkill.getParameterSchema();
404
+ // => { max_results: { type: 'number', default: 5 }, safe_search: { type: 'string', ... } }
405
+
406
+ // Via the registry
407
+ const schema2 = SkillRegistry.getParameterSchema('web_search');
408
+ ```
409
+
410
+ This allows external tools to generate configuration UIs or validate config objects before passing them to the skill constructor.
411
+
412
+ ---
413
+
414
+ ## Lifecycle Hooks
415
+
416
+ | Hook | When | Use Case |
417
+ |---|---|---|
418
+ | `constructor(config)` | Instantiation | Store config, set defaults. |
419
+ | `setup()` | During `addSkill()` | Async init: connect to APIs, load data. |
420
+ | `registerTools()` | During `addSkill()` | Return tool definitions. |
421
+ | `teardown()` | Agent shutdown | Close connections, flush buffers. |
422
+
423
+ All hooks are called by the `SkillManager` in the order shown above.
424
+
425
+ ### Example with Lifecycle Hooks
426
+
427
+ ```typescript
428
+ class DatabaseSkill extends SkillBase {
429
+ static manifest: SkillManifest = {
430
+ name: 'database',
431
+ version: '1.0.0',
432
+ description: 'Query a database',
433
+ requiredEnvVars: ['DATABASE_URL'],
434
+ };
435
+
436
+ private connection: DatabaseConnection | null = null;
437
+
438
+ async setup(): Promise<void> {
439
+ // Connect to the database during skill loading
440
+ this.connection = await connect(process.env['DATABASE_URL']!);
441
+ }
442
+
443
+ registerTools() {
444
+ return [
445
+ {
446
+ name: 'query_db',
447
+ description: 'Run a read-only database query',
448
+ parameters: {
449
+ query: { type: 'string', description: 'SQL query' },
450
+ },
451
+ handler: async (args: Record<string, unknown>) => {
452
+ const rows = await this.connection!.query(args.query as string);
453
+ return new FunctionResult(`Found ${rows.length} results.`);
454
+ },
455
+ },
456
+ ];
457
+ }
458
+
459
+ async teardown(): Promise<void> {
460
+ // Close the database connection on shutdown
461
+ if (this.connection) {
462
+ await this.connection.close();
463
+ this.connection = null;
464
+ }
465
+ }
466
+ }
467
+ ```