{"slug":"swml-context-switch","title":"SWML Context Switch — Multi-Persona AI in One Call","tags":["signalwire","swml","context-switch","multi-persona","ai-routing"],"agent_summary":"The `context_switch` verb (and FunctionResult.switch_context) lets a live AI agent change persona mid-call. Use cases: triage agent → specialist agent, language change, escalation. Covers consolidate semantics and prompt overrides.","trigger_phrases":["context switch SWML","switch AI persona mid-call","consolidate context","triage to specialist agent","FunctionResult.switch_context","swml_change_context"],"runnable":true,"markdown":"\n# SWML `context_switch` — Mid-Call Persona Change\n\n`context_switch` swaps the active AI persona without dropping the call. Common pattern: a generic triage agent answers, identifies what the caller needs, and hands off to a specialist persona (sales, support, billing) that has its own prompt and SWAIG tools — all in the same call session.\n\n## The two ways to switch contexts\n\n### 1. From SWML (declarative)\n\nUse when contexts are predefined and selection happens via SWAIG or `cond`.\n\n```yaml\nversion: 1.0.0\nsections:\n main:\n - answer: {}\n - ai:\n prompt: { text: \"You are a triage agent. Identify if the caller needs sales, support, or billing.\" }\n SWAIG:\n defaults: { web_hook_url: \"https://your.api/swaig\" }\n functions:\n - function: route_to_sales\n description: Caller needs sales.\n - function: route_to_support\n description: Caller needs technical support.\n - function: route_to_billing\n description: Caller has a billing question.\n```\n\nThe SWAIG handler returns a `FunctionResult` that switches the context.\n\n### 2. From a SWAIG handler (programmatic)\n\nIn the handler:\n\n```python\nfrom signalwire import FunctionResult\n\ndef route_to_sales(args, raw_data=None):\n return FunctionResult(\"Connecting you to a sales specialist.\").switch_context(\n \"sales\",\n system_prompt=\"\"\"You are a senior sales rep for Acme Corp.\n Focus on pricing, demos, and closing.\n Use the lookup_pricing and book_demo tools as needed.\"\"\",\n consolidate=True,\n )\n\ndef route_to_support(args, raw_data=None):\n return FunctionResult(\"Connecting you to support.\").switch_context(\n \"support\",\n system_prompt=\"You are a tier-2 support engineer. Triage and create a ticket.\",\n consolidate=True,\n )\n```\n\n## `switch_context` parameters\n\n| Parameter | Notes |\n|---|---|\n| `context_name` | Required. Name of the context to enter. |\n| `system_prompt` | Override the new context's prompt at runtime. Optional. |\n| `consolidate` | If `true`, replaces the entire conversation history with a one-paragraph summary before the new context starts. If `false`, the new persona inherits the full prior conversation. Defaults to `false`. |\n| `user_prompt` | Optional opening turn the AI will respond to inside the new context. |\n\n`consolidate=True` is the default in any handoff scenario — you don't want the specialist agent re-reading every word the caller said to the triage agent.\n\n## ContextBuilder (Python SDK) — defining the contexts up front\n\nUse [Context Builder](/topic/agents-context-builder) to define multiple contexts inside one agent.\n\n```python\ncontexts = self.define_contexts()\n\nmain = contexts.add_context(\"default\")\nmain.add_step(\"menu\") \\\n .set_text(\"Ask whether the caller needs sales, support, or billing.\") \\\n .set_functions(\"none\") \\\n .set_valid_contexts([\"sales\", \"support\", \"billing\"])\n\nsales = contexts.add_context(\"sales\")\nsales.set_system_prompt(\"You are a friendly sales representative for Acme Corp.\")\nsales.add_step(\"qualify\") \\\n .set_text(\"Understand what product the caller is interested in.\") \\\n .set_functions([\"check_inventory\", \"get_pricing\"]) \\\n .set_valid_steps([\"close\"])\nsales.add_step(\"close\") \\\n .set_text(\"Close the sale or schedule a follow-up.\") \\\n .set_valid_contexts([\"default\"])\n\nsupport = contexts.add_context(\"support\")\nsupport.set_system_prompt(\"You are a tier-2 support engineer.\")\nsupport.add_step(\"triage\").set_text(\"Get problem details, system info, urgency.\")\n```\n\nWhen the triage agent calls `switch_context(\"sales\")`, the SDK loads the sales context's system prompt, allowed functions, and entry step.\n\n## Mid-call language switch\n\n`switch_context` is the canonical way to change language mid-call. Define a Spanish context with its own voice, then switch:\n\n```python\nspanish = contexts.add_context(\"spanish\")\nspanish.set_system_prompt(\"Eres un agente bilingüe. Responde solo en español.\")\n# Languages are set at the agent level, but the prompt forces Spanish output.\n```\n\n```python\ndef switch_to_spanish(args, raw_data=None):\n return FunctionResult(\"Cambiando al español.\").switch_context(\n \"spanish\",\n consolidate=True,\n )\n```\n\nFor TTS voice changes per language, use the agent's [`languages` config](/topic/swml-ai-verb#languages-and-hints) — the AI picks the voice based on detected output language.\n\n## `consolidate` — when to set it false\n\n`consolidate=False` keeps the prior conversation in context. Use cases:\n\n- \"Hold while I check\" → backend lookup → resume same persona with new data.\n- Side-quest into a specialist that returns to the original persona.\n\n`consolidate=True` (recommended for handoffs):\n\n- Triage → specialist agent that should not see the triage chatter.\n- Compliance reset before billing questions.\n- Persona reset after extracting structured data.\n\n## `goto` vs `execute` vs `switch_context` — which one to use\n\n| Verb | Effect |\n|---|---|\n| `goto` | Jump to a different SWML section (no AI context implied). |\n| `execute` | Fetch and run a sub-SWML, return when done. The active AI session pauses during execution. |\n| `switch_context` (SWAIG return) | Keep the AI session alive, change its persona/tools/prompt. |\n\nIf the call has an active `ai` verb, prefer `switch_context` — it keeps the speech recognition, hints, and language settings warm.\n\n## Anti-patterns\n\n- Switching contexts without `consolidate=True` when the new persona shouldn't know the prior chat — leaks context, confuses the specialist agent.\n- Defining 10+ contexts on one agent — split into multiple agents on an [AgentServer](/topic/signalwire-python-agents-sdk#agentserver-multiple-agents-one-port) instead.\n- Switching contexts inside a `confirm` SWML — confirm scripts run on the callee leg, not the AI session.\n- Forgetting to `set_valid_contexts` on the source context — the SDK will refuse to transition.\n\n## See also\n\n- [Context Builder for multi-step flows](/topic/agents-context-builder)\n- [SWML AI verb](/topic/swml-ai-verb)\n- [SWAIG functions](/topic/swaig-functions)\n- [Python Agents SDK](/topic/signalwire-python-agents-sdk)\n","html":"

SWML context_switch — Mid-Call Persona Change

\n

context_switch swaps the active AI persona without dropping the call. Common pattern: a generic triage agent answers, identifies what the caller needs, and hands off to a specialist persona (sales, support, billing) that has its own prompt and SWAIG tools — all in the same call session.

\n

The two ways to switch contexts

\n

1. From SWML (declarative)

\n

Use when contexts are predefined and selection happens via SWAIG or cond.

\n
version: 1.0.0\nsections:\n  main:\n    - answer: {}\n    - ai:\n        prompt: { text: \"You are a triage agent. Identify if the caller needs sales, support, or billing.\" }\n        SWAIG:\n          defaults: { web_hook_url: \"https://your.api/swaig\" }\n          functions:\n            - function: route_to_sales\n              description: Caller needs sales.\n            - function: route_to_support\n              description: Caller needs technical support.\n            - function: route_to_billing\n              description: Caller has a billing question.\n
\n

The SWAIG handler returns a FunctionResult that switches the context.

\n

2. From a SWAIG handler (programmatic)

\n

In the handler:

\n
from signalwire import FunctionResult\n\ndef route_to_sales(args, raw_data=None):\n    return FunctionResult(\"Connecting you to a sales specialist.\").switch_context(\n        \"sales\",\n        system_prompt=\"\"\"You are a senior sales rep for Acme Corp.\n        Focus on pricing, demos, and closing.\n        Use the lookup_pricing and book_demo tools as needed.\"\"\",\n        consolidate=True,\n    )\n\ndef route_to_support(args, raw_data=None):\n    return FunctionResult(\"Connecting you to support.\").switch_context(\n        \"support\",\n        system_prompt=\"You are a tier-2 support engineer. Triage and create a ticket.\",\n        consolidate=True,\n    )\n
\n

switch_context parameters

\n

| Parameter | Notes |\n|---|---|\n| context_name | Required. Name of the context to enter. |\n| system_prompt | Override the new context's prompt at runtime. Optional. |\n| consolidate | If true, replaces the entire conversation history with a one-paragraph summary before the new context starts. If false, the new persona inherits the full prior conversation. Defaults to false. |\n| user_prompt | Optional opening turn the AI will respond to inside the new context. |

\n

consolidate=True is the default in any handoff scenario — you don't want the specialist agent re-reading every word the caller said to the triage agent.

\n

ContextBuilder (Python SDK) — defining the contexts up front

\n

Use Context Builder to define multiple contexts inside one agent.

\n
contexts = self.define_contexts()\n\nmain = contexts.add_context(\"default\")\nmain.add_step(\"menu\") \\\n    .set_text(\"Ask whether the caller needs sales, support, or billing.\") \\\n    .set_functions(\"none\") \\\n    .set_valid_contexts([\"sales\", \"support\", \"billing\"])\n\nsales = contexts.add_context(\"sales\")\nsales.set_system_prompt(\"You are a friendly sales representative for Acme Corp.\")\nsales.add_step(\"qualify\") \\\n    .set_text(\"Understand what product the caller is interested in.\") \\\n    .set_functions([\"check_inventory\", \"get_pricing\"]) \\\n    .set_valid_steps([\"close\"])\nsales.add_step(\"close\") \\\n    .set_text(\"Close the sale or schedule a follow-up.\") \\\n    .set_valid_contexts([\"default\"])\n\nsupport = contexts.add_context(\"support\")\nsupport.set_system_prompt(\"You are a tier-2 support engineer.\")\nsupport.add_step(\"triage\").set_text(\"Get problem details, system info, urgency.\")\n
\n

When the triage agent calls switch_context(\"sales\"), the SDK loads the sales context's system prompt, allowed functions, and entry step.

\n

Mid-call language switch

\n

switch_context is the canonical way to change language mid-call. Define a Spanish context with its own voice, then switch:

\n
spanish = contexts.add_context(\"spanish\")\nspanish.set_system_prompt(\"Eres un agente bilingüe. Responde solo en español.\")\n# Languages are set at the agent level, but the prompt forces Spanish output.\n
\n
def switch_to_spanish(args, raw_data=None):\n    return FunctionResult(\"Cambiando al español.\").switch_context(\n        \"spanish\",\n        consolidate=True,\n    )\n
\n

For TTS voice changes per language, use the agent's languages config — the AI picks the voice based on detected output language.

\n

consolidate — when to set it false

\n

consolidate=False keeps the prior conversation in context. Use cases:

\n\n

consolidate=True (recommended for handoffs):

\n\n

goto vs execute vs switch_context — which one to use

\n

| Verb | Effect |\n|---|---|\n| goto | Jump to a different SWML section (no AI context implied). |\n| execute | Fetch and run a sub-SWML, return when done. The active AI session pauses during execution. |\n| switch_context (SWAIG return) | Keep the AI session alive, change its persona/tools/prompt. |

\n

If the call has an active ai verb, prefer switch_context — it keeps the speech recognition, hints, and language settings warm.

\n

Anti-patterns

\n\n

See also

\n\n"}