@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.
- package/.github/workflows/publish.yml +27 -0
- package/.github/workflows/test.yml +17 -0
- package/CLAUDE.md +112 -0
- package/README.md +254 -0
- package/docs/MIGRATION-2.0.md +81 -0
- package/docs/agent-guide.md +869 -0
- package/docs/agent_guide.md +1026 -0
- package/docs/api-reference.md +2420 -0
- package/docs/api_reference.md +1301 -0
- package/docs/architecture.md +843 -0
- package/docs/cli-guide.md +579 -0
- package/docs/cli_guide.md +448 -0
- package/docs/cloud_functions_guide.md +474 -0
- package/docs/configuration.md +422 -0
- package/docs/contexts-guide.md +787 -0
- package/docs/contexts_guide.md +511 -0
- package/docs/datamap-guide.md +1141 -0
- package/docs/datamap_guide.md +595 -0
- package/docs/llm_parameters.md +239 -0
- package/docs/mcp_gateway_reference.md +648 -0
- package/docs/mcp_integration.md +108 -0
- package/docs/prefabs-guide.md +800 -0
- package/docs/sdk_features.md +477 -0
- package/docs/security.md +436 -0
- package/docs/serverless-guide.md +513 -0
- package/docs/skills-guide.md +857 -0
- package/docs/skills-system.md +301 -0
- package/docs/skills_parameter_schema.md +392 -0
- package/docs/skills_system.md +467 -0
- package/docs/swaig-reference.md +1627 -0
- package/docs/swaig_reference.md +910 -0
- package/docs/swml_service_guide.md +600 -0
- package/docs/third_party_skills.md +533 -0
- package/docs/web_service.md +677 -0
- package/examples/README.md +131 -0
- package/examples/advanced-datamap.ts +100 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +94 -0
- package/examples/call-flow.ts +63 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +55 -0
- package/examples/datasphere-multi-instance.ts +63 -0
- package/examples/datasphere-serverless-env.ts +68 -0
- package/examples/datasphere-webhook-env.ts +66 -0
- package/examples/datasphere.ts +37 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +71 -0
- package/examples/gather-per-question-functions-demo.ts +140 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +69 -0
- package/examples/mcp-agent.ts +84 -0
- package/examples/mcp-gateway.ts +35 -0
- package/examples/multi-agent.ts +73 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pom-prompt.ts +71 -0
- package/examples/prefab-concierge.ts +47 -0
- package/examples/prefab-faq.ts +54 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +68 -0
- package/examples/record-call.ts +67 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +94 -0
- package/examples/serverless-lambda.ts +35 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +38 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +187 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/tap.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +72 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +140 -0
- package/livewire/docs/migration-guide.md +228 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +197 -0
- package/livewire/examples/livewire-multi-tool.ts +117 -0
- package/package.json +38 -0
- package/relay/README.md +70 -0
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
- package/relay/docs/call-methods.md +474 -0
- package/relay/docs/client-reference.md +142 -0
- package/relay/docs/events.md +134 -0
- package/relay/docs/getting-started.md +134 -0
- package/relay/docs/guide.md +306 -0
- package/relay/docs/messaging.md +182 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +71 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +95 -0
- package/rest/docs/calling.md +273 -0
- package/rest/docs/client-reference.md +107 -0
- package/rest/docs/compat.md +204 -0
- package/rest/docs/fabric.md +183 -0
- package/rest/docs/getting-started.md +110 -0
- package/rest/docs/guide.md +351 -0
- package/rest/docs/namespaces.md +285 -0
- package/rest/examples/rest-10dlc-registration.ts +161 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
- package/rest/examples/rest-calling-play-and-record.ts +91 -0
- package/rest/examples/rest-client.ts +65 -0
- package/rest/examples/rest-compat-laml.ts +210 -0
- package/rest/examples/rest-datasphere-search.ts +82 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
- package/rest/examples/rest-manage-resources.ts +65 -0
- package/rest/examples/rest-phone-number-management.ts +197 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/src/AgentBase.ts +2489 -0
- package/src/AgentServer.ts +415 -0
- package/src/AuthHandler.ts +256 -0
- package/src/ConfigLoader.ts +447 -0
- package/src/ContextBuilder.ts +1150 -0
- package/src/DataMap.ts +449 -0
- package/src/FunctionResult.ts +866 -0
- package/src/Logger.ts +337 -0
- package/src/PomBuilder.ts +439 -0
- package/src/PromptManager.ts +133 -0
- package/src/SWMLHandler.ts +298 -0
- package/src/SWMLService.ts +717 -0
- package/src/SchemaUtils.ts +361 -0
- package/src/SecurityUtils.ts +153 -0
- package/src/ServerlessAdapter.ts +221 -0
- package/src/SessionManager.ts +311 -0
- package/src/SslConfig.ts +118 -0
- package/src/SwaigFunction.ts +276 -0
- package/src/SwmlBuilder.ts +258 -0
- package/src/SwmlVerbMethods.generated.ts +234 -0
- package/src/TypeInference.ts +181 -0
- package/src/WebService.ts +619 -0
- package/src/cli/agent-loader.ts +166 -0
- package/src/cli/mock-data.ts +111 -0
- package/src/cli/swaig-test.ts +452 -0
- package/src/generateVerbTypes.ts +322 -0
- package/src/index.ts +167 -0
- package/src/livewire/index.ts +950 -0
- package/src/prefabs/ConciergeAgent.ts +287 -0
- package/src/prefabs/FAQBotAgent.ts +384 -0
- package/src/prefabs/InfoGathererAgent.ts +339 -0
- package/src/prefabs/ReceptionistAgent.ts +366 -0
- package/src/prefabs/SurveyAgent.ts +646 -0
- package/src/prefabs/index.ts +27 -0
- package/src/relay/Action.ts +314 -0
- package/src/relay/Call.ts +854 -0
- package/src/relay/Deferred.ts +71 -0
- package/src/relay/Message.ts +148 -0
- package/src/relay/RelayClient.ts +1036 -0
- package/src/relay/RelayError.ts +14 -0
- package/src/relay/RelayEvent.ts +892 -0
- package/src/relay/constants.ts +132 -0
- package/src/relay/index.ts +123 -0
- package/src/relay/types.ts +149 -0
- package/src/rest/HttpClient.ts +103 -0
- package/src/rest/RestError.ts +31 -0
- package/src/rest/base/BaseResource.ts +19 -0
- package/src/rest/base/CrudResource.ts +51 -0
- package/src/rest/base/CrudWithAddresses.ts +26 -0
- package/src/rest/index.ts +200 -0
- package/src/rest/namespaces/addresses.ts +32 -0
- package/src/rest/namespaces/calling.ts +187 -0
- package/src/rest/namespaces/chat.ts +20 -0
- package/src/rest/namespaces/compat.ts +352 -0
- package/src/rest/namespaces/datasphere.ts +45 -0
- package/src/rest/namespaces/fabric.ts +222 -0
- package/src/rest/namespaces/imported-numbers.ts +20 -0
- package/src/rest/namespaces/logs.ts +84 -0
- package/src/rest/namespaces/lookup.ts +21 -0
- package/src/rest/namespaces/mfa.ts +30 -0
- package/src/rest/namespaces/number-groups.ts +38 -0
- package/src/rest/namespaces/phone-numbers.ts +44 -0
- package/src/rest/namespaces/project.ts +36 -0
- package/src/rest/namespaces/pubsub.ts +20 -0
- package/src/rest/namespaces/queues.ts +33 -0
- package/src/rest/namespaces/recordings.ts +28 -0
- package/src/rest/namespaces/registry.ts +101 -0
- package/src/rest/namespaces/short-codes.ts +28 -0
- package/src/rest/namespaces/sip-profile.ts +25 -0
- package/src/rest/namespaces/verified-callers.ts +27 -0
- package/src/rest/namespaces/video.ts +165 -0
- package/src/rest/pagination.ts +84 -0
- package/src/rest/types.ts +61 -0
- package/src/schema.json +12250 -0
- package/src/skills/SkillBase.ts +547 -0
- package/src/skills/SkillManager.ts +415 -0
- package/src/skills/SkillRegistry.ts +367 -0
- package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
- package/src/skills/builtin/ask_claude.ts +241 -0
- package/src/skills/builtin/claude_skills.ts +978 -0
- package/src/skills/builtin/custom_skills.ts +312 -0
- package/src/skills/builtin/datasphere.ts +438 -0
- package/src/skills/builtin/datasphere_serverless.ts +339 -0
- package/src/skills/builtin/datetime.ts +130 -0
- package/src/skills/builtin/google_maps.ts +651 -0
- package/src/skills/builtin/index.ts +88 -0
- package/src/skills/builtin/info_gatherer.ts +405 -0
- package/src/skills/builtin/joke.ts +191 -0
- package/src/skills/builtin/math.ts +142 -0
- package/src/skills/builtin/mcp_gateway.ts +677 -0
- package/src/skills/builtin/native_vector_search.ts +901 -0
- package/src/skills/builtin/play_background_file.ts +358 -0
- package/src/skills/builtin/spider.ts +869 -0
- package/src/skills/builtin/swml_transfer.ts +635 -0
- package/src/skills/builtin/weather_api.ts +248 -0
- package/src/skills/builtin/web_search.ts +1074 -0
- package/src/skills/builtin/wikipedia_search.ts +299 -0
- package/src/skills/index.ts +12 -0
- package/src/types.ts +132 -0
- package/tests/AgentBase.test.ts +1093 -0
- package/tests/AgentServer.test.ts +126 -0
- package/tests/AuthHandler.test.ts +133 -0
- package/tests/ConfigLoader.test.ts +151 -0
- package/tests/ContextBuilder.test.ts +108 -0
- package/tests/DataMap.test.ts +367 -0
- package/tests/EphemeralSkillCopy.test.ts +107 -0
- package/tests/FunctionResult.test.ts +298 -0
- package/tests/GracefulShutdown.test.ts +46 -0
- package/tests/Logger.test.ts +420 -0
- package/tests/PomBuilder.test.ts +228 -0
- package/tests/ProxyDetection.test.ts +228 -0
- package/tests/SWMLService.test.ts +320 -0
- package/tests/SWMLVerbHandler.test.ts +523 -0
- package/tests/SchemaUtils.test.ts +106 -0
- package/tests/SchemaUtils.verb.test.ts +206 -0
- package/tests/SecurityUtils.test.ts +192 -0
- package/tests/ServerlessAdapter.test.ts +222 -0
- package/tests/SessionManager.test.ts +257 -0
- package/tests/SkillBaseFeatures.test.ts +130 -0
- package/tests/SkillMultiInstance.test.ts +102 -0
- package/tests/SkillParameterSchemas.test.ts +134 -0
- package/tests/SkillRegistrySchema.test.ts +84 -0
- package/tests/SslConfig.test.ts +97 -0
- package/tests/SwmlBuilder.test.ts +400 -0
- package/tests/TypeInference.test.ts +165 -0
- package/tests/VerbHandlerRegistry.test.ts +128 -0
- package/tests/cli/mock-data.test.ts +113 -0
- package/tests/cli/swaig-test.test.ts +108 -0
- package/tests/examples.test.ts +194 -0
- package/tests/fixtures/scrape-parity/README.md +53 -0
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
- package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
- package/tests/fixtures/scrape-parity/python_extract.py +109 -0
- package/tests/livewire/livewire.test.ts +780 -0
- package/tests/mcp.test.ts +221 -0
- package/tests/prefabs/prefabs.test.ts +1093 -0
- package/tests/relay/Action.test.ts +392 -0
- package/tests/relay/Call.test.ts +535 -0
- package/tests/relay/Deferred.test.ts +71 -0
- package/tests/relay/Message.test.ts +164 -0
- package/tests/relay/RelayClient.test.ts +779 -0
- package/tests/relay/RelayEvent.test.ts +463 -0
- package/tests/relay/helpers.ts +79 -0
- package/tests/rest/HttpClient.test.ts +274 -0
- package/tests/rest/RestError.test.ts +53 -0
- package/tests/rest/calling.test.ts +156 -0
- package/tests/rest/client.test.ts +197 -0
- package/tests/rest/compat.test.ts +335 -0
- package/tests/rest/datasphere.test.ts +71 -0
- package/tests/rest/fabric.test.ts +186 -0
- package/tests/rest/helpers.ts +95 -0
- package/tests/rest/logs.test.ts +68 -0
- package/tests/rest/pagination.test.ts +133 -0
- package/tests/rest/registry.test.ts +94 -0
- package/tests/rest/relay-rest.test.ts +290 -0
- package/tests/rest/video.test.ts +173 -0
- package/tests/setup.ts +6 -0
- package/tests/skills/SkillBase.test.ts +108 -0
- package/tests/skills/SkillManager.test.ts +268 -0
- package/tests/skills/SkillRegistry.test.ts +176 -0
- package/tests/skills/builtin.test.ts +1472 -0
- package/tests/skills/claude-skills.test.ts +54 -0
- package/tests/skills/custom-skills.test.ts +53 -0
- package/tests/skills/datasphere-serverless.test.ts +70 -0
- package/tests/skills/datasphere.test.ts +107 -0
- package/tests/skills/datetime.test.ts +101 -0
- package/tests/skills/google-maps.test.ts +78 -0
- package/tests/skills/info-gatherer.test.ts +411 -0
- package/tests/skills/joke.test.ts +81 -0
- package/tests/skills/math.test.ts +68 -0
- package/tests/skills/mcp-gateway.test.ts +101 -0
- package/tests/skills/play-background.test.ts +54 -0
- package/tests/skills/spider.test.ts +108 -0
- package/tests/skills/swml-transfer.test.ts +178 -0
- package/tests/skills/trivia.test.ts +54 -0
- package/tests/skills/vector-search.test.ts +135 -0
- package/tests/skills/weather-api.test.ts +77 -0
- package/tests/skills/web-search-parity.test.ts +59 -0
- package/tests/skills/web-search.test.ts +103 -0
- package/tests/skills/wikipedia.test.ts +63 -0
- package/tsconfig.json +18 -0
- 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
|
+
```
|