Migration

View as Markdown

Migration Guide

Guide for migrating to the SignalWire Agents SDK and common migration patterns.

Current Version

SDK VersionPythonSignalWire APIStatus
1.0.x3.8+v1Current stable release

Before Upgrading

  1. Review changelog for breaking changes
  2. Backup your code before upgrading
  3. Test in development before production
  4. Check dependency compatibility
$## Check current version
$pip show signalwire-agents
$
$## View available versions
$pip index versions signalwire-agents

Upgrading

$## Upgrade to latest
$pip install --upgrade signalwire-agents
$
$## Upgrade to specific version
$pip install signalwire-agents==1.0.15
$
$## Upgrade with all extras
$pip install --upgrade "signalwire-agents[search-all]"

Migration from Raw SWML

If migrating from hand-written SWML to the SDK:

Before (Raw SWML)

1{
2 "version": "1.0.0",
3 "sections": {
4 "main": [{
5 "ai": {
6 "prompt": {
7 "text": "You are a helpful assistant."
8 },
9 "languages": [{
10 "name": "English",
11 "code": "en-US",
12 "voice": "rime.spore"
13 }],
14 "SWAIG": {
15 "functions": [{
16 "function": "lookup",
17 "description": "Look up information",
18 "parameters": {
19 "type": "object",
20 "properties": {
21 "id": {
22 "type": "string",
23 "description": "Item ID"
24 }
25 },
26 "required": ["id"]
27 },
28 "web_hook_url": "https://example.com/webhook"
29 }]
30 }
31 }
32 }]
33 }
34}

After (SDK)

1from signalwire_agents import AgentBase
2from signalwire_agents.core.function_result import SwaigFunctionResult
3
4agent = AgentBase(name="assistant", route="/")
5agent.prompt_add_section("Role", "You are a helpful assistant.")
6agent.add_language("English", "en-US", "rime.spore")
7
8@agent.tool(description="Look up information")
9def lookup(id: str) -> SwaigFunctionResult:
10 # Your logic here
11 return SwaigFunctionResult(f"Found item {id}")
12
13if __name__ == "__main__":
14 agent.run()

Common Migration Tasks

Old StyleNew Style
JSON parameter schemaPython type hints
Manual webhook handler@agent.tool decorator
Return JSON dictReturn SwaigFunctionResult
Manual response parsingAutomatic parameter injection

Class-Based Migration

If migrating from functional to class-based agents:

Before (Functional)

1from signalwire_agents import AgentBase
2from signalwire_agents.core.function_result import SwaigFunctionResult
3
4agent = AgentBase(name="service", route="/service")
5agent.prompt_add_section("Role", "Customer service agent.")
6agent.add_language("English", "en-US", "rime.spore")
7
8@agent.tool(description="Get account balance")
9def get_balance(account_id: str) -> SwaigFunctionResult:
10 balance = lookup_balance(account_id)
11 return SwaigFunctionResult(f"Balance: ${balance}")
12
13if __name__ == "__main__":
14 agent.run()

After (Class-Based)

1from signalwire_agents import AgentBase
2from signalwire_agents.core.function_result import SwaigFunctionResult
3
4
5class ServiceAgent(AgentBase):
6 def __init__(self):
7 super().__init__(name="service", route="/service")
8 self.prompt_add_section("Role", "Customer service agent.")
9 self.add_language("English", "en-US", "rime.spore")
10
11 @AgentBase.tool(description="Get account balance")
12 def get_balance(self, account_id: str) -> SwaigFunctionResult:
13 balance = self.lookup_balance(account_id)
14 return SwaigFunctionResult(f"Balance: ${balance}")
15
16 def lookup_balance(self, account_id: str) -> float:
17 # Your lookup logic
18 return 100.00
19
20
21if __name__ == "__main__":
22 agent = ServiceAgent()
23 agent.run()

Multi-Agent Migration

If migrating multiple agents to use AgentServer:

Before (Separate Processes)

$## Running separate agent processes
$python sales_agent.py &
$python support_agent.py &
$python billing_agent.py &

After (AgentServer)

1from signalwire_agents import AgentServer
2from sales_agent import SalesAgent
3from support_agent import SupportAgent
4from billing_agent import BillingAgent
5
6server = AgentServer(host="0.0.0.0", port=8080)
7server.register(SalesAgent())
8server.register(SupportAgent())
9server.register(BillingAgent())
10
11if __name__ == "__main__":
12 server.run()

Testing After Migration

$## Verify SWML generation
$swaig-test agent.py --dump-swml
$
$## Compare with expected output
$swaig-test agent.py --dump-swml > new_swml.json
$diff old_swml.json new_swml.json
$
$## Test all functions
$swaig-test agent.py --list-tools
$swaig-test agent.py --exec function_name --param value
$
$## Run integration tests
$pytest tests/

Getting Help

For migration assistance:

  1. Check the changelog for breaking changes
  2. Review updated examples in /examples
  3. Use swaig-test to validate changes
  4. Test thoroughly in development