@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,533 @@
1
+ # Third-Party Skills Integration Guide
2
+
3
+ This guide explains how to create and integrate third-party skills with the SignalWire AI Agents SDK. The SDK supports multiple methods for loading external skills, making it easy to extend agent capabilities without modifying the core SDK.
4
+
5
+ ## Overview
6
+
7
+ Third-party skills can be integrated using four different methods:
8
+
9
+ 1. **Direct Registration** - Register skill classes programmatically
10
+ 2. **Directory Registration** - Add directories containing skill collections
11
+ 3. **Python Entry Points** - Install skills as Python packages
12
+ 4. **Environment Variables** - Configure skill paths via environment
13
+
14
+ All third-party skills are discovered and indexed the same way as built-in skills, appearing in `list_skills_with_params()` output with their parameter schemas.
15
+
16
+ ## Creating a Third-Party Skill
17
+
18
+ Third-party skills follow the same structure as built-in skills. Here's a minimal example:
19
+
20
+ ```python
21
+ # my_weather_skill/skill.py
22
+ from signalwire_agents.core.skill_base import SkillBase
23
+ from signalwire_agents.core.function_result import FunctionResult
24
+ from typing import Dict, Any, List
25
+
26
+ class WeatherSkill(SkillBase):
27
+ """Custom weather information skill"""
28
+
29
+ SKILL_NAME = "weather"
30
+ SKILL_DESCRIPTION = "Get weather information for any location"
31
+ SKILL_VERSION = "1.0.0"
32
+ REQUIRED_PACKAGES = ["requests"]
33
+ REQUIRED_ENV_VARS = []
34
+
35
+ @classmethod
36
+ def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
37
+ """Define configuration parameters"""
38
+ schema = super().get_parameter_schema()
39
+
40
+ schema.update({
41
+ "api_key": {
42
+ "type": "string",
43
+ "description": "Weather API key",
44
+ "required": True,
45
+ "hidden": True,
46
+ "env_var": "WEATHER_API_KEY"
47
+ },
48
+ "units": {
49
+ "type": "string",
50
+ "description": "Temperature units",
51
+ "default": "celsius",
52
+ "required": False,
53
+ "enum": ["celsius", "fahrenheit", "kelvin"]
54
+ },
55
+ "cache_timeout": {
56
+ "type": "integer",
57
+ "description": "Cache timeout in seconds",
58
+ "default": 300,
59
+ "required": False,
60
+ "min": 0,
61
+ "max": 3600
62
+ }
63
+ })
64
+
65
+ return schema
66
+
67
+ def setup(self) -> bool:
68
+ """Initialize the skill"""
69
+ if not self.validate_packages():
70
+ return False
71
+
72
+ self.api_key = self.params.get('api_key')
73
+ if not self.api_key:
74
+ self.logger.error("Weather API key is required")
75
+ return False
76
+
77
+ self.units = self.params.get('units', 'celsius')
78
+ self.cache_timeout = self.params.get('cache_timeout', 300)
79
+
80
+ return True
81
+
82
+ def register_tools(self) -> None:
83
+ """Register weather tools with the agent"""
84
+ self.define_tool(
85
+ name="get_weather",
86
+ description="Get current weather for a location",
87
+ parameters={
88
+ "location": {
89
+ "type": "string",
90
+ "description": "City name or coordinates"
91
+ }
92
+ },
93
+ handler=self._get_weather_handler
94
+ )
95
+
96
+ def _get_weather_handler(self, args, raw_data):
97
+ """Handle weather requests"""
98
+ location = args.get('location', '').strip()
99
+
100
+ if not location:
101
+ return FunctionResult("Please provide a location")
102
+
103
+ # Implementation would call weather API here
104
+ # This is just an example
105
+ return FunctionResult(
106
+ f"The weather in {location} is sunny and 22°{self.units[0].upper()}"
107
+ )
108
+ ```
109
+
110
+ ## Integration Methods
111
+
112
+ ### Method 1: Direct Registration
113
+
114
+ Register individual skill classes programmatically:
115
+
116
+ ```python
117
+ from signalwire_agents import AgentBase, register_skill
118
+ from my_weather_skill import WeatherSkill
119
+
120
+ # Register the skill globally
121
+ register_skill(WeatherSkill)
122
+
123
+ # Now use it in any agent
124
+ class MyAgent(AgentBase):
125
+ def __init__(self):
126
+ super().__init__(name="my-agent")
127
+
128
+ # Add the registered skill
129
+ self.add_skill("weather", {
130
+ "api_key": "your-api-key",
131
+ "units": "fahrenheit"
132
+ })
133
+ ```
134
+
135
+ ### Method 2: Directory Registration
136
+
137
+ Register directories containing multiple skills:
138
+
139
+ ```python
140
+ from signalwire_agents import add_skill_directory
141
+
142
+ # Add a directory of custom skills
143
+ add_skill_directory('/opt/custom_skills')
144
+
145
+ # Directory structure should be:
146
+ # /opt/custom_skills/
147
+ # weather/
148
+ # skill.py # Contains WeatherSkill class
149
+ # stock_market/
150
+ # skill.py # Contains StockMarketSkill class
151
+ # translation/
152
+ # skill.py # Contains TranslationSkill class
153
+
154
+ # Now use any skill from the directory
155
+ agent.add_skill("weather", {"api_key": "..."})
156
+ agent.add_skill("stock_market", {"api_key": "..."})
157
+ ```
158
+
159
+ ### Method 3: Python Entry Points
160
+
161
+ Create installable skill packages using setuptools entry points:
162
+
163
+ ```python
164
+ # setup.py for your skill package
165
+ from setuptools import setup, find_packages
166
+
167
+ setup(
168
+ name="my-signalwire-skills",
169
+ version="1.0.0",
170
+ packages=find_packages(),
171
+ install_requires=[
172
+ "@signalwire/sdk",
173
+ "requests",
174
+ ],
175
+ entry_points={
176
+ 'signalwire_agents.skills': [
177
+ 'weather = my_skills.weather:WeatherSkill',
178
+ 'stock = my_skills.stock:StockMarketSkill',
179
+ 'translate = my_skills.translate:TranslationSkill',
180
+ ]
181
+ }
182
+ )
183
+ ```
184
+
185
+ After installation, skills are automatically available:
186
+
187
+ ```bash
188
+ pip install my-signalwire-skills
189
+ ```
190
+
191
+ ```python
192
+ # Skills are automatically discovered
193
+ agent.add_skill("weather", {"api_key": "..."})
194
+ ```
195
+
196
+ ### Method 4: Environment Variable
197
+
198
+ Set the `SIGNALWIRE_SKILL_PATHS` environment variable:
199
+
200
+ ```bash
201
+ # Single directory
202
+ export SIGNALWIRE_SKILL_PATHS=/opt/my_skills
203
+
204
+ # Multiple directories (colon-separated)
205
+ export SIGNALWIRE_SKILL_PATHS=/opt/my_skills:/home/user/custom_skills
206
+ ```
207
+
208
+ Skills in these directories are automatically discovered:
209
+
210
+ ```python
211
+ # No registration needed - skills are found automatically
212
+ agent.add_skill("weather", {"api_key": "..."})
213
+ ```
214
+
215
+ ## Directory Structure
216
+
217
+ Skills loaded from directories must follow this structure:
218
+
219
+ ```
220
+ my_skills_directory/
221
+ ├── weather/ # Skill directory (matches SKILL_NAME)
222
+ │ ├── skill.py # Required: Contains skill class
223
+ │ ├── __init__.py # Optional: Makes it a package
224
+ │ └── README.md # Optional: Documentation
225
+ ├── translation/
226
+ │ ├── skill.py
227
+ │ └── resources/ # Optional: Additional files
228
+ │ └── languages.json
229
+ └── stock_market/
230
+ └── skill.py
231
+ ```
232
+
233
+ ## Skill Discovery and Schema
234
+
235
+ Third-party skills are fully integrated with the SDK's discovery system:
236
+
237
+ ```python
238
+ from signalwire_agents import list_skills_with_params
239
+
240
+ # Get all skills including third-party ones
241
+ all_skills = list_skills_with_params()
242
+
243
+ # Third-party skills include source information
244
+ print(all_skills['weather'])
245
+ # Output:
246
+ {
247
+ "name": "weather",
248
+ "description": "Get weather information for any location",
249
+ "version": "1.0.0",
250
+ "supports_multiple_instances": False,
251
+ "required_packages": ["requests"],
252
+ "required_env_vars": [],
253
+ "parameters": {
254
+ "api_key": {
255
+ "type": "string",
256
+ "description": "Weather API key",
257
+ "required": True,
258
+ "hidden": True,
259
+ "env_var": "WEATHER_API_KEY"
260
+ },
261
+ "units": {
262
+ "type": "string",
263
+ "description": "Temperature units",
264
+ "default": "celsius",
265
+ "required": False,
266
+ "enum": ["celsius", "fahrenheit", "kelvin"]
267
+ }
268
+ },
269
+ "source": "external" # Shows it's a third-party skill
270
+ }
271
+ ```
272
+
273
+ ## Best Practices
274
+
275
+ ### 1. Skill Naming
276
+
277
+ - Use lowercase, underscore-separated names
278
+ - Choose unique names to avoid conflicts with built-in skills
279
+ - Match directory name to `SKILL_NAME` for directory-based loading
280
+
281
+ ### 2. Parameter Design
282
+
283
+ - Always implement `get_parameter_schema()` for GUI compatibility
284
+ - Mark sensitive parameters as `hidden`
285
+ - Provide sensible defaults
286
+ - Use `env_var` for parameters that can come from environment
287
+
288
+ ### 3. Error Handling
289
+
290
+ ```python
291
+ def setup(self) -> bool:
292
+ """Proper setup with error handling"""
293
+ # Validate packages
294
+ if not self.validate_packages():
295
+ return False
296
+
297
+ # Validate required parameters
298
+ if not self.params.get('api_key'):
299
+ self.logger.error("API key is required")
300
+ return False
301
+
302
+ # Test connectivity
303
+ try:
304
+ self._test_api_connection()
305
+ except Exception as e:
306
+ self.logger.error(f"Failed to connect to API: {e}")
307
+ return False
308
+
309
+ return True
310
+ ```
311
+
312
+ ### 4. Documentation
313
+
314
+ Include a README.md in your skill directory:
315
+
316
+ ```markdown
317
+ # Weather Skill
318
+
319
+ Provides weather information for any location.
320
+
321
+ ## Configuration
322
+
323
+ - `api_key` (required): Your weather API key
324
+ - `units` (optional): Temperature units (celsius, fahrenheit, kelvin)
325
+ - `cache_timeout` (optional): Cache timeout in seconds
326
+
327
+ ## Usage
328
+
329
+ ```python
330
+ agent.add_skill("weather", {
331
+ "api_key": "your-api-key",
332
+ "units": "fahrenheit"
333
+ })
334
+ ```
335
+ ```
336
+
337
+ ## Advanced Features
338
+
339
+ ### Multiple Instances
340
+
341
+ Support multiple instances of your skill:
342
+
343
+ ```python
344
+ class WeatherSkill(SkillBase):
345
+ SKILL_NAME = "weather"
346
+ SUPPORTS_MULTIPLE_INSTANCES = True # Enable multiple instances
347
+
348
+ def get_instance_key(self) -> str:
349
+ """Create unique key for this instance"""
350
+ service = self.params.get('service', 'default')
351
+ return f"{self.SKILL_NAME}_{service}"
352
+ ```
353
+
354
+ Usage:
355
+
356
+ ```python
357
+ # Add multiple weather services
358
+ agent.add_skill("weather", {
359
+ "tool_name": "openweather",
360
+ "service": "openweathermap",
361
+ "api_key": "key1"
362
+ })
363
+
364
+ agent.add_skill("weather", {
365
+ "tool_name": "weatherapi",
366
+ "service": "weatherapi",
367
+ "api_key": "key2"
368
+ })
369
+ ```
370
+
371
+ ### Dynamic Tool Names
372
+
373
+ Customize tool names for better agent prompts:
374
+
375
+ ```python
376
+ def register_tools(self) -> None:
377
+ tool_name = self.params.get('tool_name', 'get_weather')
378
+
379
+ self.define_tool(
380
+ name=tool_name,
381
+ description=f"Get weather using {self.params.get('service', 'default')}",
382
+ parameters={...},
383
+ handler=self._weather_handler
384
+ )
385
+ ```
386
+
387
+ ### Skill Dependencies
388
+
389
+ Load skills that depend on other skills:
390
+
391
+ ```python
392
+ def setup(self) -> bool:
393
+ # Check if required skill is available
394
+ if not self.agent.skill_manager.has_skill("translation"):
395
+ self.logger.error("This skill requires the translation skill")
396
+ return False
397
+
398
+ return True
399
+ ```
400
+
401
+ ## Testing Third-Party Skills
402
+
403
+ Test your skills before distribution:
404
+
405
+ ```python
406
+ # test_my_skill.py
407
+ import unittest
408
+ from signalwire_agents import AgentBase
409
+ from my_weather_skill import WeatherSkill
410
+
411
+ class TestWeatherSkill(unittest.TestCase):
412
+ def setUp(self):
413
+ self.agent = AgentBase(name="test-agent")
414
+
415
+ def test_skill_registration(self):
416
+ # Test direct registration
417
+ from signalwire_agents import register_skill
418
+ register_skill(WeatherSkill)
419
+
420
+ # Test adding skill
421
+ success, error = self.agent.add_skill("weather", {
422
+ "api_key": "test-key"
423
+ })
424
+ self.assertTrue(success)
425
+
426
+ def test_parameter_schema(self):
427
+ schema = WeatherSkill.get_parameter_schema()
428
+ self.assertIn("api_key", schema)
429
+ self.assertTrue(schema["api_key"]["required"])
430
+ self.assertTrue(schema["api_key"]["hidden"])
431
+ ```
432
+
433
+ ## Troubleshooting
434
+
435
+ ### Skill Not Found
436
+
437
+ If your skill isn't being discovered:
438
+
439
+ 1. Check the skill directory structure
440
+ 2. Verify `SKILL_NAME` matches the directory name
441
+ 3. Ensure `skill.py` exists and contains a valid skill class
442
+ 4. Check logs for loading errors
443
+
444
+ ### Import Errors
445
+
446
+ For skills with relative imports:
447
+
448
+ ```python
449
+ # Use absolute imports in skill.py
450
+ from my_skills.weather.utils import parse_temperature
451
+
452
+ # Or handle import errors gracefully
453
+ try:
454
+ from .utils import parse_temperature
455
+ except ImportError:
456
+ from utils import parse_temperature
457
+ ```
458
+
459
+ ### Environment Variables
460
+
461
+ Debug environment variable loading:
462
+
463
+ ```python
464
+ import os
465
+ print(f"Skill paths: {os.environ.get('SIGNALWIRE_SKILL_PATHS', 'Not set')}")
466
+
467
+ from signalwire_agents.skills.registry import skill_registry
468
+ sources = skill_registry.list_all_skill_sources()
469
+ print(f"External skills: {sources['external_paths']}")
470
+ ```
471
+
472
+ ## Example: Complete Third-Party Skill Package
473
+
474
+ Here's a complete example of a distributable skill package:
475
+
476
+ ```
477
+ my-signalwire-skills/
478
+ ├── setup.py
479
+ ├── README.md
480
+ ├── requirements.txt
481
+ ├── my_signalwire_skills/
482
+ │ ├── __init__.py
483
+ │ ├── weather/
484
+ │ │ ├── __init__.py
485
+ │ │ ├── skill.py
486
+ │ │ └── utils.py
487
+ │ └── translation/
488
+ │ ├── __init__.py
489
+ │ └── skill.py
490
+ └── tests/
491
+ ├── __init__.py
492
+ ├── test_weather.py
493
+ └── test_translation.py
494
+ ```
495
+
496
+ ```python
497
+ # setup.py
498
+ from setuptools import setup, find_packages
499
+
500
+ setup(
501
+ name="my-signalwire-skills",
502
+ version="1.0.0",
503
+ author="Your Name",
504
+ description="Custom skills for SignalWire AI Agents",
505
+ packages=find_packages(),
506
+ install_requires=[
507
+ "@signalwire/sdk>=1.0.12",
508
+ "requests>=2.25.0",
509
+ ],
510
+ entry_points={
511
+ 'signalwire_agents.skills': [
512
+ 'weather = my_signalwire_skills.weather.skill:WeatherSkill',
513
+ 'translate = my_signalwire_skills.translation.skill:TranslationSkill',
514
+ ]
515
+ },
516
+ python_requires='>=3.7',
517
+ )
518
+ ```
519
+
520
+ Install and use:
521
+
522
+ ```bash
523
+ pip install git+https://github.com/yourname/my-signalwire-skills.git
524
+ ```
525
+
526
+ ```python
527
+ from signalwire_agents import AgentBase
528
+
529
+ agent = AgentBase(name="my-agent")
530
+ agent.add_skill("weather", {"api_key": "..."})
531
+ agent.add_skill("translate", {"api_key": "..."})
532
+ agent.run()
533
+ ```