@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,301 @@
1
+ # Skills System Reference
2
+
3
+ Architectural reference for the Skills system in the SignalWire AI Agents TypeScript SDK.
4
+
5
+ > **See also:** [skills-guide.md](skills-guide.md) for usage patterns and built-in skill details.
6
+
7
+ ---
8
+
9
+ ## Table of Contents
10
+
11
+ 1. [Architecture](#architecture)
12
+ 2. [SkillBase](#skillbase)
13
+ 3. [SkillManager](#skillmanager)
14
+ 4. [SkillRegistry](#skillregistry)
15
+ 5. [Tool Registration Flow](#tool-registration-flow)
16
+ 6. [Creating a Custom Skill](#creating-a-custom-skill)
17
+ 7. [Multi-Instance Skills](#multi-instance-skills)
18
+ 8. [Environment Validation](#environment-validation)
19
+ 9. [Parameter Schema Discovery](#parameter-schema-discovery)
20
+ 10. [Lifecycle Hooks](#lifecycle-hooks)
21
+
22
+ ---
23
+
24
+ ## Architecture
25
+
26
+ The skills system consists of three cooperating components:
27
+
28
+ ```
29
+ SkillRegistry (singleton)
30
+ |
31
+ +-- registers skill factories by name
32
+ |
33
+ +-- SkillBase subclasses
34
+ |
35
+ +-- provide tools, prompts, hints, global data
36
+ |
37
+ +-- managed by SkillManager (per-agent)
38
+ ```
39
+
40
+ | Component | Responsibility |
41
+ |---|---|
42
+ | **SkillBase** | Abstract base class every skill extends. Declares tools, prompts, hints, and config schema. |
43
+ | **SkillManager** | Attached to each `AgentBase`. Loads, validates, and wires skills into the agent. |
44
+ | **SkillRegistry** | Global singleton. Maps skill names to factory functions for `agent.addSkill()` lookups. |
45
+
46
+ ---
47
+
48
+ ## SkillBase
49
+
50
+ All skills extend `SkillBase`. The base class defines the contract:
51
+
52
+ ```typescript
53
+ import { SkillBase, 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) => {
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
+ ---
108
+
109
+ ## SkillManager
110
+
111
+ Each `AgentBase` has an internal `SkillManager`. When you call `agent.addSkill()`, the manager:
112
+
113
+ 1. Validates required environment variables from the skill manifest.
114
+ 2. Calls `skill.setup()` for async initialization.
115
+ 3. Registers all tools from `skill.registerTools()` with the agent.
116
+ 4. Merges hints from `skill.getHints()` into the agent's hint list.
117
+ 5. Adds prompt sections from `skill.getPromptSections()` to the POM.
118
+ 6. Merges global data from `skill.getGlobalData()`.
119
+
120
+ ```typescript
121
+ // SkillManager is used internally by AgentBase
122
+ const skills = agent.listSkills(); // Returns loaded skill metadata
123
+ ```
124
+
125
+ ---
126
+
127
+ ## SkillRegistry
128
+
129
+ The global registry allows skills to be discovered by name:
130
+
131
+ ```typescript
132
+ import { SkillRegistry } from '@signalwire/sdk';
133
+
134
+ // List all registered skills
135
+ const available = SkillRegistry.listSkills();
136
+ // => [{ name: 'datetime', description: '...', version: '1.0.0' }, ...]
137
+
138
+ // Get a skill's parameter schema
139
+ const schema = SkillRegistry.getParameterSchema('web_search');
140
+ ```
141
+
142
+ Built-in skills register themselves automatically when imported. Custom skills must call `SkillRegistry.register()`:
143
+
144
+ ```typescript
145
+ SkillRegistry.register('my_skill', (config) => new MySkill(config));
146
+ ```
147
+
148
+ ---
149
+
150
+ ## Tool Registration Flow
151
+
152
+ ```
153
+ agent.addSkill(new WebSearchSkill({ max_results: 5 }))
154
+ |
155
+ v
156
+ SkillManager.loadSkill(skill)
157
+ |
158
+ +-- validate env vars (GOOGLE_SEARCH_API_KEY, etc.)
159
+ +-- skill.setup() // async init
160
+ +-- skill.registerTools() // get tool definitions
161
+ | |
162
+ | v
163
+ +-- agent.defineTool(...) // register each tool on the agent
164
+ +-- agent.addHints(...) // merge hints
165
+ +-- agent.promptAddSection(...) // add prompt text
166
+ +-- agent.updateGlobalData(...) // merge global data
167
+ ```
168
+
169
+ ---
170
+
171
+ ## Creating a Custom Skill
172
+
173
+ 1. **Extend `SkillBase`** and declare a static `manifest`:
174
+
175
+ ```typescript
176
+ import { SkillBase, FunctionResult } from '@signalwire/sdk';
177
+
178
+ export class StockPriceSkill extends SkillBase {
179
+ static manifest = {
180
+ name: 'stock_price',
181
+ version: '1.0.0',
182
+ description: 'Look up current stock prices',
183
+ requiredEnvVars: ['STOCK_API_KEY'],
184
+ supportsMultipleInstances: false,
185
+ };
186
+
187
+ private apiKey: string;
188
+
189
+ constructor(config: Record<string, unknown> = {}) {
190
+ super(config);
191
+ this.apiKey = process.env['STOCK_API_KEY'] ?? '';
192
+ }
193
+
194
+ registerTools() {
195
+ return [
196
+ {
197
+ name: 'get_stock_price',
198
+ description: 'Get the current price of a stock by ticker symbol',
199
+ parameters: {
200
+ ticker: { type: 'string', description: 'Stock ticker symbol (e.g. AAPL)' },
201
+ },
202
+ handler: async (args: Record<string, unknown>) => {
203
+ const ticker = String(args.ticker).toUpperCase();
204
+ // In production, call a real stock API here
205
+ return new FunctionResult(`${ticker} is currently trading at $150.25`);
206
+ },
207
+ },
208
+ ];
209
+ }
210
+
211
+ getHints() {
212
+ return ['stock', 'ticker', 'price', 'market', 'shares'];
213
+ }
214
+
215
+ getPromptSections() {
216
+ return [
217
+ {
218
+ title: 'Stock Price Lookup',
219
+ body: 'You can look up current stock prices using the get_stock_price tool. ' +
220
+ 'Ask the user for a ticker symbol if they want a price quote.',
221
+ },
222
+ ];
223
+ }
224
+ }
225
+ ```
226
+
227
+ 2. **Register** the skill (optional, for name-based discovery):
228
+
229
+ ```typescript
230
+ import { SkillRegistry } from '@signalwire/sdk';
231
+ SkillRegistry.register('stock_price', (config) => new StockPriceSkill(config));
232
+ ```
233
+
234
+ 3. **Use** the skill:
235
+
236
+ ```typescript
237
+ await agent.addSkill(new StockPriceSkill());
238
+ ```
239
+
240
+ ---
241
+
242
+ ## Multi-Instance Skills
243
+
244
+ Some skills support multiple instances with different configurations. Set `supportsMultipleInstances: true` in the manifest and accept a `tool_name` config parameter:
245
+
246
+ ```typescript
247
+ // Two DataSphere instances with different knowledge bases
248
+ await agent.addSkill(new DataSphereSkill({
249
+ document_id: 'drinks-doc',
250
+ tool_name: 'search_drinks',
251
+ }));
252
+
253
+ await agent.addSkill(new DataSphereSkill({
254
+ document_id: 'food-doc',
255
+ tool_name: 'search_food',
256
+ }));
257
+ ```
258
+
259
+ Each instance registers its tools under the configured `tool_name`, avoiding collisions.
260
+
261
+ ---
262
+
263
+ ## Environment Validation
264
+
265
+ Skills declare required environment variables in their manifest. The `SkillManager` checks these before calling `setup()`:
266
+
267
+ ```typescript
268
+ static manifest = {
269
+ // ...
270
+ requiredEnvVars: ['GOOGLE_SEARCH_API_KEY', 'GOOGLE_SEARCH_CX'],
271
+ };
272
+ ```
273
+
274
+ If any required variable is missing, `addSkill()` throws with a descriptive error message listing the missing variables.
275
+
276
+ ---
277
+
278
+ ## Parameter Schema Discovery
279
+
280
+ Skills can expose their configuration schema for tooling and documentation:
281
+
282
+ ```typescript
283
+ // Get the parameter schema for a skill class
284
+ const schema = WebSearchSkill.getParameterSchema();
285
+ // => { max_results: { type: 'number', default: 5 }, safe_search: { type: 'string', ... } }
286
+ ```
287
+
288
+ This allows external tools to generate configuration UIs or validate config objects before passing them to the skill constructor.
289
+
290
+ ---
291
+
292
+ ## Lifecycle Hooks
293
+
294
+ | Hook | When | Use Case |
295
+ |---|---|---|
296
+ | `constructor(config)` | Instantiation | Store config, set defaults |
297
+ | `setup()` | During `addSkill()` | Async init: connect to APIs, load data |
298
+ | `registerTools()` | During `addSkill()` | Return tool definitions |
299
+ | `teardown()` | Agent shutdown | Close connections, flush buffers |
300
+
301
+ All hooks are called by the `SkillManager` in the order shown above.
@@ -0,0 +1,392 @@
1
+ # Skills Parameter Schema System
2
+
3
+ This guide explains the parameter schema system for SignalWire AI Agents SDK skills, which enables GUI configuration tools and programmatic skill discovery.
4
+
5
+ ## Overview
6
+
7
+ The parameter schema system allows skills to declare their configurable parameters with metadata including types, descriptions, default values, and security hints. This enables:
8
+
9
+ - **GUI Configuration Tools** - Automatically generate configuration forms
10
+ - **API Documentation** - Document all available parameters
11
+ - **Validation** - Type checking and constraint validation
12
+ - **Security** - Mark sensitive parameters as hidden
13
+ - **Environment Variables** - Indicate which parameters can be sourced from environment
14
+
15
+ ## Using the Schema System
16
+
17
+ ### Getting All Skills Schema
18
+
19
+ Use the `list_skills_with_params()` function to get a complete schema of all available skills:
20
+
21
+ ```python
22
+ from signalwire_agents import list_skills_with_params
23
+
24
+ # Get complete schema for all skills
25
+ schema = list_skills_with_params()
26
+
27
+ # Example output structure:
28
+ {
29
+ "web_search": {
30
+ "name": "web_search",
31
+ "description": "Search the web for information using Google Custom Search API",
32
+ "version": "1.0.0",
33
+ "supports_multiple_instances": True,
34
+ "required_packages": ["bs4", "requests"],
35
+ "required_env_vars": [],
36
+ "parameters": {
37
+ "api_key": {
38
+ "type": "string",
39
+ "description": "Google Custom Search API key",
40
+ "required": True,
41
+ "hidden": True,
42
+ "env_var": "GOOGLE_SEARCH_API_KEY"
43
+ },
44
+ "search_engine_id": {
45
+ "type": "string",
46
+ "description": "Google Custom Search Engine ID",
47
+ "required": True,
48
+ "hidden": True,
49
+ "env_var": "GOOGLE_SEARCH_ENGINE_ID"
50
+ },
51
+ "num_results": {
52
+ "type": "integer",
53
+ "description": "Default number of search results to return",
54
+ "default": 1,
55
+ "required": False,
56
+ "min": 1,
57
+ "max": 10
58
+ },
59
+ ...
60
+ }
61
+ },
62
+ "datetime": {
63
+ "name": "datetime",
64
+ "description": "Get current date, time, and timezone information",
65
+ "version": "1.0.0",
66
+ "supports_multiple_instances": False,
67
+ "required_packages": ["pytz"],
68
+ "required_env_vars": [],
69
+ "parameters": {
70
+ "swaig_fields": {
71
+ "type": "object",
72
+ "description": "Additional SWAIG function metadata to merge into tool definitions",
73
+ "default": {},
74
+ "required": False
75
+ }
76
+ }
77
+ },
78
+ ...
79
+ }
80
+ ```
81
+
82
+ ### Using Schema for GUI Configuration
83
+
84
+ Here's an example of how to use the schema to generate a configuration form:
85
+
86
+ ```python
87
+ import json
88
+ from signalwire_agents import list_skills_with_params, AgentBase
89
+
90
+ # Get skills schema
91
+ schema = list_skills_with_params()
92
+
93
+ # Example: Generate HTML form for web_search skill
94
+ web_search_schema = schema['web_search']
95
+
96
+ def generate_form_field(param_name, param_info):
97
+ """Generate HTML form field based on parameter schema"""
98
+ field_html = f'<div class="form-group">\n'
99
+ field_html += f' <label for="{param_name}">{param_info["description"]}</label>\n'
100
+
101
+ # Mark required fields
102
+ required = "required" if param_info.get("required", False) else ""
103
+
104
+ # Hide sensitive fields
105
+ input_type = "password" if param_info.get("hidden", False) else "text"
106
+
107
+ # Handle different types
108
+ if param_info["type"] == "string":
109
+ default = param_info.get("default", "")
110
+ field_html += f' <input type="{input_type}" id="{param_name}" name="{param_name}" '
111
+ field_html += f'value="{default}" {required}>\n'
112
+
113
+ elif param_info["type"] == "integer":
114
+ default = param_info.get("default", 0)
115
+ min_val = f'min="{param_info["min"]}"' if "min" in param_info else ""
116
+ max_val = f'max="{param_info["max"]}"' if "max" in param_info else ""
117
+ field_html += f' <input type="number" id="{param_name}" name="{param_name}" '
118
+ field_html += f'value="{default}" {min_val} {max_val} {required}>\n'
119
+
120
+ elif param_info["type"] == "boolean":
121
+ default = param_info.get("default", False)
122
+ checked = "checked" if default else ""
123
+ field_html += f' <input type="checkbox" id="{param_name}" name="{param_name}" {checked}>\n'
124
+
125
+ # Show environment variable hint
126
+ if "env_var" in param_info:
127
+ field_html += f' <small>Can also be set via {param_info["env_var"]} environment variable</small>\n'
128
+
129
+ field_html += '</div>\n'
130
+ return field_html
131
+
132
+ # Generate form fields for web_search skill
133
+ print("<form>")
134
+ for param_name, param_info in web_search_schema["parameters"].items():
135
+ print(generate_form_field(param_name, param_info))
136
+ print("</form>")
137
+ ```
138
+
139
+ ### Programmatic Skill Configuration
140
+
141
+ Use the schema to validate and configure skills programmatically:
142
+
143
+ ```python
144
+ from signalwire_agents import AgentBase, list_skills_with_params
145
+
146
+ class MyAgent(AgentBase):
147
+ def __init__(self):
148
+ super().__init__(name="my-agent")
149
+
150
+ # Get schema to validate configuration
151
+ schema = list_skills_with_params()
152
+
153
+ # Configure web_search skill with validation
154
+ web_search_params = {
155
+ "api_key": "your-api-key",
156
+ "search_engine_id": "your-engine-id",
157
+ "num_results": 3,
158
+ "max_content_length": 3000
159
+ }
160
+
161
+ # Validate required parameters
162
+ web_search_schema = schema["web_search"]["parameters"]
163
+ for param, info in web_search_schema.items():
164
+ if info.get("required", False) and param not in web_search_params:
165
+ raise ValueError(f"Missing required parameter: {param}")
166
+
167
+ # Add skill with validated parameters
168
+ self.add_skill("web_search", web_search_params)
169
+ ```
170
+
171
+ ## Parameter Schema Reference
172
+
173
+ Each parameter in the schema can have the following properties:
174
+
175
+ | Property | Type | Description |
176
+ |----------|------|-------------|
177
+ | `type` | string | Parameter type: "string", "integer", "number", "boolean", "object", "array" |
178
+ | `description` | string | Human-readable description of the parameter |
179
+ | `default` | any | Default value if not provided |
180
+ | `required` | boolean | Whether the parameter is required (default: false) |
181
+ | `hidden` | boolean | Whether to hide this field in UIs (for secrets/API keys) |
182
+ | `env_var` | string | Environment variable that can provide this value |
183
+ | `enum` | array | List of allowed values (for string types) |
184
+ | `min` | number | Minimum value (for numeric types) |
185
+ | `max` | number | Maximum value (for numeric types) |
186
+
187
+ ## Implementing Parameter Schema in Skills
188
+
189
+ To add parameter schema support to a skill, override the `get_parameter_schema()` class method:
190
+
191
+ ```python
192
+ from signalwire_agents.core.skill_base import SkillBase
193
+ from typing import Dict, Any
194
+
195
+ class MyCustomSkill(SkillBase):
196
+ SKILL_NAME = "my_custom_skill"
197
+ SKILL_DESCRIPTION = "My custom skill"
198
+ SKILL_VERSION = "1.0.0"
199
+ REQUIRED_PACKAGES = []
200
+ REQUIRED_ENV_VARS = []
201
+
202
+ @classmethod
203
+ def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
204
+ """Get parameter schema for this skill"""
205
+ # Get base schema from parent (includes common parameters)
206
+ schema = super().get_parameter_schema()
207
+
208
+ # Add skill-specific parameters
209
+ schema.update({
210
+ "api_endpoint": {
211
+ "type": "string",
212
+ "description": "API endpoint URL",
213
+ "required": True,
214
+ "default": "https://api.example.com"
215
+ },
216
+ "api_key": {
217
+ "type": "string",
218
+ "description": "API authentication key",
219
+ "required": True,
220
+ "hidden": True, # Mark as sensitive
221
+ "env_var": "MY_API_KEY" # Can be set via environment
222
+ },
223
+ "timeout": {
224
+ "type": "integer",
225
+ "description": "Request timeout in seconds",
226
+ "default": 30,
227
+ "required": False,
228
+ "min": 1,
229
+ "max": 300
230
+ },
231
+ "retry_count": {
232
+ "type": "integer",
233
+ "description": "Number of retries on failure",
234
+ "default": 3,
235
+ "required": False,
236
+ "min": 0,
237
+ "max": 10
238
+ },
239
+ "output_format": {
240
+ "type": "string",
241
+ "description": "Output format for results",
242
+ "default": "json",
243
+ "required": False,
244
+ "enum": ["json", "xml", "text"] # Allowed values
245
+ },
246
+ "enable_cache": {
247
+ "type": "boolean",
248
+ "description": "Enable response caching",
249
+ "default": True,
250
+ "required": False
251
+ }
252
+ })
253
+
254
+ return schema
255
+
256
+ def setup(self) -> bool:
257
+ """Setup the skill using parameters"""
258
+ # Access parameters via self.params
259
+ self.api_endpoint = self.params.get('api_endpoint')
260
+ self.api_key = self.params.get('api_key')
261
+ self.timeout = self.params.get('timeout', 30)
262
+ # ... etc
263
+ return True
264
+ ```
265
+
266
+ ## Common Parameter Patterns
267
+
268
+ ### API Keys and Secrets
269
+
270
+ Always mark sensitive parameters as `hidden` and provide an `env_var` option:
271
+
272
+ ```python
273
+ "api_key": {
274
+ "type": "string",
275
+ "description": "API key for authentication",
276
+ "required": True,
277
+ "hidden": True,
278
+ "env_var": "SERVICE_API_KEY"
279
+ }
280
+ ```
281
+
282
+ ### Numeric Parameters with Constraints
283
+
284
+ Use `min` and `max` to enforce valid ranges:
285
+
286
+ ```python
287
+ "port": {
288
+ "type": "integer",
289
+ "description": "Server port number",
290
+ "default": 8080,
291
+ "required": False,
292
+ "min": 1,
293
+ "max": 65535
294
+ }
295
+ ```
296
+
297
+ ### Enumerated Values
298
+
299
+ Use `enum` to restrict to specific values:
300
+
301
+ ```python
302
+ "log_level": {
303
+ "type": "string",
304
+ "description": "Logging level",
305
+ "default": "info",
306
+ "required": False,
307
+ "enum": ["debug", "info", "warning", "error"]
308
+ }
309
+ ```
310
+
311
+ ### Optional Features
312
+
313
+ Use boolean parameters for optional features:
314
+
315
+ ```python
316
+ "enable_analytics": {
317
+ "type": "boolean",
318
+ "description": "Enable analytics tracking",
319
+ "default": False,
320
+ "required": False
321
+ }
322
+ ```
323
+
324
+ ## Base Parameters
325
+
326
+ All skills automatically inherit these base parameters from `SkillBase`:
327
+
328
+ - **`swaig_fields`** (object) - Additional SWAIG function metadata to merge into tool definitions
329
+ - **`tool_name`** (string) - Custom name for skill instances (only for skills with `SUPPORTS_MULTIPLE_INSTANCES = True`)
330
+
331
+ ## Examples
332
+
333
+ ### Simple Skill (No Parameters)
334
+
335
+ Skills like `datetime` and `math` that don't need configuration:
336
+
337
+ ```python
338
+ @classmethod
339
+ def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
340
+ # Just return base schema
341
+ return super().get_parameter_schema()
342
+ ```
343
+
344
+ ### Complex Skill (Many Parameters)
345
+
346
+ Skills like `web_search` with multiple configuration options:
347
+
348
+ ```python
349
+ @classmethod
350
+ def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
351
+ schema = super().get_parameter_schema()
352
+
353
+ schema.update({
354
+ # API credentials (hidden)
355
+ "api_key": {...},
356
+ "api_secret": {...},
357
+
358
+ # Configuration options
359
+ "timeout": {...},
360
+ "retry_count": {...},
361
+
362
+ # Feature flags
363
+ "enable_cache": {...},
364
+ "debug_mode": {...},
365
+
366
+ # Customization
367
+ "response_template": {...},
368
+ "error_messages": {...}
369
+ })
370
+
371
+ return schema
372
+ ```
373
+
374
+ ## Best Practices
375
+
376
+ 1. **Always provide descriptions** - Make parameters self-documenting
377
+ 2. **Set sensible defaults** - Allow skills to work with minimal configuration
378
+ 3. **Mark secrets as hidden** - Protect sensitive information in UIs
379
+ 4. **Use appropriate types** - Enable proper validation and UI controls
380
+ 5. **Document environment variables** - Show alternative configuration methods
381
+ 6. **Validate in setup()** - Ensure all required parameters are present
382
+ 7. **Support backward compatibility** - Handle deprecated parameters gracefully
383
+
384
+ ## Future Enhancements
385
+
386
+ The parameter schema system is designed to be extensible. Future enhancements may include:
387
+
388
+ - **Conditional parameters** - Show/hide based on other parameter values
389
+ - **Complex validation** - Cross-parameter validation rules
390
+ - **Nested schemas** - Support for complex object parameters
391
+ - **Internationalization** - Localized descriptions and error messages
392
+ - **Runtime parameter updates** - Modify configuration without restart