Run isolated personas behind one number

AI Agentsmulti-persona AI on one number

Route one phone number among isolated sales, support, and billing AI personas, each with access only to its own tools.

contextsgovernance

The claim

Contexts do two jobs here. isolated: true on a persona context means, per the bundled schema, that entering it “resets conversation history to only the system prompt”. The support desk does not inherit what the caller told sales. functions on each persona’s step names only that desk’s tool. All three tools stay registered under SWAIG.functions. The step decides which one the platform offers the model on a given turn, and a step is not a security boundary. The default context’s step names no tools and lists the three personas in valid_contexts. The schema requires a context by that name.

Why it holds

The contexts reference documents contexts and steps; isolated is the context field the schema adds for the wipe.

How it works

triage = contexts.add_context("default")
triage.add_step("ask") \
    .set_functions([]) \
    .set_valid_contexts(["sales", "support", "billing"])

for name, (prompt, tools) in PERSONAS.items():
    ctx = contexts.add_context(name)
    ctx.set_isolated(True)
    ctx.add_section("Role", prompt)
    ctx.add_step("help").set_functions(tools).set_valid_contexts(["default"]).set_end(True)

What the platform receives for the support persona, trimmed:

{"support": {"isolated": true,
             "pom": [{"title": "Role", "body": "You are the workshop support desk ..."}],
             "steps": [{"name": "help", "functions": ["book_repair"],
                        "valid_contexts": ["default"], "end": true, ...}]}}

The platform offers the model a change_context tool, and valid_contexts limits it to the names listed. Entering support wipes the history, and the step offers book_repair alone. That step’s functions omits quote_price and look_up_invoice, so the platform does not offer them there.

Limitations

A step is not a security boundary. functions shapes which tools the platform offers the model; a handler that must not run for the wrong desk checks state itself.

Isolation wipes what the caller already said, per the schema’s description of isolated. You carry what the next desk needs to know some other way.

The three tools are stubs with fixed replies, which the verifier asserts.

What to change first

Add "quote_price" to the support step’s functions and run the verifier. The cross-persona assertion fails first, because the support step now names another persona’s tool. What a desk offers is exactly the list on its step, and nothing else decides it.

Where this sits

Before this

Control which tools an AI agent can call at each step

Change a voice AI agent's instructions mid-call Require verification before unlocking AI agent tools

python/app.py

"""Split one number into isolated personas.

One agent, three personas. The `default` context finds out why the caller
rang and can move to `sales`, `support` or `billing`. Each persona is its own
context with `isolated` set, so entering it wipes the conversation history
down to that context's prompt. Each persona's step names only its own tool in
`functions`, so the platform offers the model the sales tool only while sales
is on the line. The structure, not the prompt, keeps them apart. The tools are stubs
with fixed replies.

Written against signalwire-sdk 3.0.1 (contexts and steps).
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

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

PERSONAS = {
    "sales": ("You are the sales desk for Ridgeline Cycles. Quote prices for bikes "
              "and accessories.", ["quote_price"]),
    "support": ("You are the workshop support desk for Ridgeline Cycles. Book "
                "repair appointments.", ["book_repair"]),
    "billing": ("You are the billing desk for Ridgeline Cycles. Look up invoices.",
                ["look_up_invoice"]),
}


class FrontDoorAgent(AgentBase):
    def __init__(self):
        super().__init__(name="front-door", route="/front-door")
        self.prompt_add_section(
            "Role", "You answer one number for a bicycle shop and route the caller.")

        contexts = self.define_contexts()
        triage = contexts.add_context("default")
        triage.add_step("ask") \
            .add_section("Current Task",
                         "Find out whether the caller needs sales, support or "
                         "billing, then move to that context.") \
            .set_step_criteria("The caller has said which desk they need.") \
            .set_functions([]) \
            .set_valid_contexts(list(PERSONAS))

        for name, (prompt, tools) in PERSONAS.items():
            ctx = contexts.add_context(name)
            # entering this context wipes the history to this prompt alone
            ctx.set_isolated(True)
            ctx.add_section("Role", prompt)
            ctx.add_step("help") \
                .add_section("Current Task", "Help the caller with this desk's work.") \
                .set_step_criteria("The caller's request is handled.") \
                .set_functions(tools) \
                .set_valid_contexts(["default"]) \
                .set_end(True)

    @AgentBase.tool(name="quote_price", description="Quote the price of an item.",
                    parameters={"type": "object", "properties": {
                        "item": {"type": "string"}}, "required": ["item"]})
    def quote_price(self, args, raw_data):
        return FunctionResult(f"{args.get('item')} is 89.00.")

    @AgentBase.tool(name="book_repair", description="Book a workshop appointment.",
                    parameters={"type": "object", "properties": {
                        "day": {"type": "string"}}, "required": ["day"]})
    def book_repair(self, args, raw_data):
        return FunctionResult(f"Booked for {args.get('day')}.")

    @AgentBase.tool(name="look_up_invoice", description="Look up an invoice by number.",
                    parameters={"type": "object", "properties": {
                        "number": {"type": "string"}}, "required": ["number"]})
    def look_up_invoice(self, args, raw_data):
        return FunctionResult(f"Invoice {args.get('number')}: 45.00, paid.")


agent = FrontDoorAgent()

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-door/, ask for support, then ask for a price.

Verify it

No network, no account.

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

It renders and validates the SWML, reads ai.prompt.contexts, and asserts the following.

the contexts are exactly default, sales, support and billing
the default context’s step names no functions and lists exactly the three personas in valid_contexts, and it omits isolated
each persona context carries isolated: true and a Role section naming its desk
each persona has one step whose functions is exactly its own tool, with valid_contexts back to default and end: true
no persona step names another persona’s tool, checked before the exact list
all three tools exist on the agent, so the steps are what scopes them, and each answers with its fixed reply and no action
the bundled schema documents isolated on a context as a boolean that “resets conversation history to only the system prompt”

Report an issue