Transfer a call without losing context

AI Agentscontext-preserving call transfer

Pass caller identity and state with the transfer so the next call leg receives the context.

governancetransfer

The claim

The caller gives their name and reason once. When the call moves to a second agent, that agent already has both, with no re-authentication and no repeated intake. Nothing is serialised into a URL in the hope that the other side parses it.

Example · Annotated transcript

intakeWho am I speaking with, and what can I help with?

callerDana Whitfield. There is a charge on my bill I do not recognise.

caller_name, intake_reason and verified are written to the shared context, then the call connects to the billing specialist.

intakeThanks Dana, connecting you to billing.

New agent, same call. The context is already present on its first turn.

billingHi Dana - I see you are asking about an unrecognised charge. Let me pull that up.

callerYou already know?

billingIt came through with your call.

One handoff. The caller is not asked anything twice.

An example written from the code beside it, not a recording. Replays at reading pace.

Why it holds

The platform holds interaction state, so the handoff carries it. On a stateless CPaaS this is application code you write and maintain yourself.

How it works

Two agents run on one AgentServer: /intake and /billing-specialist. Both agents set params.persist_global_data = true, so the platform saves global_data to a channel variable when one AI session ends and restores it for the next. They also set params.transfer_summary = true, giving the next agent a summary of the conversation so far.

The intake tool route_caller writes what it learned from the handler, not through the model:

{"set_global_data": {"caller_name": "Dana Whitfield", "intake_reason": "...", "verified": true}}
{"SWML": {"version": "1.0.0", "sections": {"main": [{"transfer": {"dest": "https://<host>/billing-specialist"}}]}}, "transfer": "true"}

The transfer URL carries none of the context. The billing agent’s prompt reads it directly, ${global_data.caller_name} and ${global_data.intake_reason}, so its first turn already knows who is calling and why.

One SDK note: in 3.0.1, FunctionResult.execute_swml(..., transfer=True) places the transfer flag inside the SWML document. The documented action shape, and what FunctionResult.connect() emits, is a sibling "transfer": "true", so this recipe builds that action explicitly.

Limitations

Context travels with the call, not with the caller. Recognising a returning caller across separate calls is a different problem and needs durable storage keyed to the contact.

What to change first

Add a field during intake and read it from the receiving agent to find the boundary of what survives.

Where this sits

Before this

Give a voice AI agent a tool Transfer a call

Hand off from AI to a human agent Whisper a summary to the agent before connecting the caller

Offer a callback instead of a hold

Seen in a build

One of 7 recipes composed by IVR navigator: an AI agent that works through phone menus to reach a human.

python/app.py

"""Transfer a call without losing context.

Intake writes what it learned to global_data; the platform persists global_data
across AI sessions on the same call (persist_global_data); the receiving agent
reads it in its prompt on the first turn. Nothing is serialised into the transfer
URL.

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

from dotenv import load_dotenv
from signalwire import AgentBase, AgentServer, FunctionResult

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

PUBLIC_URL = os.getenv("PUBLIC_URL", "http://localhost:8080")


class ContextCarryingAgent(AgentBase):
    """Both agents opt in to the same platform behaviour."""

    def __init__(self, **kw):
        super().__init__(**kw)
        # global_data is saved to a channel variable when this AI session ends
        # and restored when the next AI session starts on the same call.
        self.set_param("persist_global_data", True)
        # Also hand the next agent a summary of the conversation so far.
        self.set_param("transfer_summary", True)


class IntakeAgent(ContextCarryingAgent):
    def __init__(self):
        super().__init__(name="intake", route="/intake")
        self.prompt_add_section(
            "Role",
            "Collect the caller's name and the reason for their call, then use "
            "route_caller to hand them to billing.",
        )

    @AgentBase.tool(
        name="route_caller",
        description="Record the caller's name and reason, then route to billing",
        parameters={
            "name": {"type": "string", "description": "The caller's full name"},
            "reason": {"type": "string", "description": "Why they are calling"},
        },
    )
    def route_caller(self, args, raw_data):
        name = (args.get("name") or "").strip()
        reason = (args.get("reason") or "").strip()
        if not name or not reason:
            return FunctionResult("I still need your name and the reason for your call.")
        result = FunctionResult(f"Thanks {name}, connecting you to billing.",
                                post_process=True)
        # Written into the call's global_data from the handler - the model does
        # not relay it, and the transfer URL carries none of it.
        result.update_global_data(
            {"caller_name": name, "intake_reason": reason, "verified": True}
        )
        # Hand the call to the billing agent's SWML. The documented action shape
        # is a SWML document plus a sibling "transfer": "true" that exits this
        # agent for good - the same shape FunctionResult.connect() emits.
        # (FunctionResult.execute_swml(transfer=True) in sdk 3.0.1 puts the
        # transfer flag inside the document instead, so it is built by hand.)
        result.action.append({
            "SWML": {
                "version": "1.0.0",
                "sections": {"main": [
                    {"transfer": {"dest": f"{PUBLIC_URL}/billing-specialist"}}]},
            },
            "transfer": "true",
        })
        return result


class BillingAgent(ContextCarryingAgent):
    def __init__(self):
        super().__init__(name="billing", route="/billing-specialist")
        # The receiving agent reads context that already exists on the call.
        self.prompt_add_section(
            "Context",
            "You are speaking with ${global_data.caller_name}. They already "
            "explained: ${global_data.intake_reason}. They are already verified. "
            "Do not ask for their name or their reason again.",
        )
        self.prompt_add_section("Role", "Resolve the caller's billing question.")


def build_server(port=None):
    server = AgentServer(port=port or int(os.getenv("PORT", "8080")))
    server.register(IntakeAgent(), "/intake")
    server.register(BillingAgent(), "/billing-specialist")
    return server


if __name__ == "__main__":
    build_server().run()

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
PUBLIC_URL=https://<your-host> python app.py

Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/intake/.

Verify it

No network, no account:

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

It renders both agents’ SWML and asserts:

persist_global_data is set on each
the intake tool emits a set_global_data action and a SWML + transfer action
no collected value appears in the transfer URL
the billing prompt reads the same global_data keys

Report an issue