Change a voice AI agent's instructions mid-call

AI Agentsvoice AI prompt switching mid-call

A tool result replaces the system prompt on the call in progress, summarising or dropping the earlier turns, with no transfer.

contexts

The claim

A tool result can carry a context_switch action. The platform replaces the system prompt of the conversation that is already running, on the same call, with no transfer and no second agent. You choose whether the turns so far are summarised into the new context or dropped. The context switch guide documents the action and its fields.

Why it holds

The SDK method is switch_context; the wire key is context_switch. The verifier asserts the key and the complete payload.

How it works

One agent takes the call, finds out what it is about, then hands over to itself.

@AgentBase.tool(name="become_billing", description="...", parameters={...})
def become_billing(self, args, raw_data):
    return FunctionResult("Switching you to billing.").switch_context(
        system_prompt=BILLING_PROMPT, consolidate=True
    )

The function result the platform receives:

{"response": "Switching you to billing.",
 "action": [{"context_switch": {
   "system_prompt": "You are now the billing specialist ...",
   "consolidate": true}}]}

consolidate asks the platform to summarise the conversation so far into the new context. full_reset drops the history instead. start_over uses it and hands back the prompt the call opened with. Both are fields of the documented action object.

With system_prompt alone the SDK emits the prompt as a bare string. The bundled schema documents context_switch as an object, so every switch in this recipe passes consolidate or full_reset and gets the object form. The verifier shows both shapes.

Limitations

The switch replaces the prompt, not the toolset. Every tool on the agent stays registered after the switch. To scope tools, use contexts and steps. Each step’s functions field names the tools it offers, per the steps reference.

consolidate is a summary the platform writes, not a record. This recipe does not carry state across the switch. For a fact that must survive verbatim, see enforce-state-transitions-in-a-tool-handler under Where this sits, where a handler writes global_data.

What to change first

Change consolidate=True to full_reset=True in become_billing and run the verifier. The payload assertion fails, and on a call the billing specialist starts with no memory of what the caller said at the front desk.

Where this sits

Before this

Give a voice AI agent a tool

Control which tools an AI agent can call at each step Transfer a call without losing context Enforce an AI agent's next step in code

python/app.py

"""Change the agent's instructions mid-call.

A tool result can replace the system prompt on the call that is already in
progress. No transfer, no second agent, no new leg: the same conversation
continues under new instructions.

The action key the platform reads is `context_switch`, not the SDK method
name `switch_context`. It takes an object with `system_prompt` and, when you
want the earlier turns summarised into the new context instead of carried
verbatim, `consolidate`. `full_reset` drops them entirely.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

# the SDK does not read .env for you
load_dotenv()

FRONT_DESK_PROMPT = (
    "You answer the phone for a bicycle shop. Find out whether the caller "
    "needs billing or the workshop, then hand over using the matching tool. "
    "Do not answer their question yourself."
)

BILLING_PROMPT = (
    "You are now the billing specialist for Ridgeline Cycles. The caller has "
    "already been identified. Answer questions about invoices, refunds and "
    "payment dates. Do not discuss repairs or parts."
)

REPAIRS_PROMPT = (
    "You are now the workshop coordinator for Ridgeline Cycles. Book, move "
    "or check repair appointments. Do not discuss billing."
)


class FrontDeskAgent(AgentBase):
    """One agent that becomes a specialist once it knows what the call is."""

    def __init__(self):
        super().__init__(name="front-desk", route="/front-desk")
        self.prompt_add_section("Role", FRONT_DESK_PROMPT)

    @AgentBase.tool(
        name="become_billing",
        description=(
            "Use this once the caller says they are calling about an invoice, "
            "a refund or a payment. It changes your instructions so you can "
            "help them directly."
        ),
        parameters={"type": "object", "properties": {}},
    )
    def become_billing(self, args, raw_data):
        # consolidate=True: the platform summarises the turns so far into
        # the new context, so the specialist knows what was said without the
        # front-desk prompt still steering it.
        return FunctionResult("Switching you to billing.").switch_context(
            system_prompt=BILLING_PROMPT, consolidate=True
        )

    @AgentBase.tool(
        name="become_workshop",
        description=(
            "Use this once the caller says they are calling about a repair or "
            "an appointment. It changes your instructions so you can help "
            "them directly."
        ),
        parameters={"type": "object", "properties": {}},
    )
    def become_workshop(self, args, raw_data):
        return FunctionResult("Switching you to the workshop.").switch_context(
            system_prompt=REPAIRS_PROMPT, consolidate=True
        )

    @AgentBase.tool(
        name="start_over",
        description=(
            "Use this only if the caller asks to start again from the "
            "beginning. It clears the conversation so far."
        ),
        parameters={"type": "object", "properties": {}},
    )
    def start_over(self, args, raw_data):
        # full_reset=True: the history is dropped, not summarised, and the
        # front desk's own instructions come back.
        return FunctionResult("Starting over.").switch_context(
            system_prompt=FRONT_DESK_PROMPT, full_reset=True
        )


agent = FrontDeskAgent()

if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py

The webhook needs a public HTTPS URL. For a local run, expose port 3000 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/front-desk/, say you are calling about a refund, then ask about a repair. The billing prompt tells the model not to discuss repairs.

Verify it

No network, no account. The verifier proves the payload, not the live conversation.

python verify.py          # from the recipe folder, not python/

It renders and validates the SWML, runs all three handlers, and asserts the following.

each result equals its expected payload exactly: the response text and one context_switch object
become_billing and become_workshop carry the new system_prompt with consolidate: true
start_over carries full_reset: true with the same prompt the rendered document opens with
no key at any depth of any result is SWML, transfer or connect
switch_context(system_prompt=...) on its own emits the bare-string form

Report an issue