Configure a voice AI agent per request for many tenants

AI Agentsmulti-tenant voice AI

Configure a temporary voice AI agent for each request from tenant data in a query string or header, without changing the deployed agent.

Also called caller ID greeting, personalise the greeting by caller, multi-tenant AI agent

multi-tenant

The claim

set_dynamic_config_callback registers a function the SDK calls on every SWML request with the query parameters, the POST body, the headers and an agent to configure. That agent is an ephemeral copy. Your callback adds a prompt section, a voice and global_data for the tenant the request names. The SDK renders the document from the copy and leaves the deployed agent as it was.

Why it holds

The mechanism is the SDK’s: set_dynamic_config_callback in web_mixin.py, and _create_ephemeral_copy in agent_base.py, which copies the prompt, languages, params and global_data before the callback runs.

How it works

def configure(query_params, body_params, headers, agent):
    key = (query_params.get("tenant") or headers.get("x-tenant") or DEFAULT_TENANT).lower()
    tenant = TENANTS.get(key) or TENANTS[DEFAULT_TENANT]
    agent.prompt_add_section("Tenant", f"You answer for {tenant['name']}. ...")
    agent.add_language("English", "en-US", tenant["voice"])
    agent.set_global_data({"tenant": key, "shop": tenant["name"]})

class FrontDeskAgent(AgentBase):
    def __init__(self):
        super().__init__(name="front-desk", route="/front-desk")
        self.prompt_add_section("Role", "You are a bicycle shop's front desk. ...")
        self.set_dynamic_config_callback(configure)

The document rendered for ?tenant=harbor contains this ai object:

{"prompt": {"pom": [{"title": "Role", "body": "..."}, {"title": "Tenant", "body": "You answer for Harbor Bike Repair. ..."}]},
 "languages": [{"name": "English", "code": "en-US", "voice": "rime.marisol"}],
 "global_data": {"tenant": "harbor", "shop": "Harbor Bike Repair"}}

What every tenant shares stays on the deployed agent. What differs is a dictionary here and a database row in production, keyed by the tenant id.

Limitations

SDK 3.0.1 registers the agent’s root only as /front-desk/. A request to /front-desk falls through to a catch-all that answers 200 null. A number pointed at the URL without the slash gets no document. The verifier asserts this so the trap is on record.

This recipe changes the prompt, the voice and global_data per request. You register tools on the deployed agent, and every tenant shares them.

What to change first

Delete the agent.add_language(...) line from the callback and add self.add_language("English", "en-US", TENANTS[DEFAULT_TENANT]["voice"]) to __init__, then run the verifier. Both tenants now render the same voice and Harbor’s assertion fails. That is the point: what sits on the deployed agent is what every tenant gets.

Where this sits

python/app.py

"""Configure an agent per request.

One deployed agent serves many tenants. `set_dynamic_config_callback`
registers a function that runs on every SWML request with the query string,
the POST body and the headers. It receives an ephemeral copy of the agent and
configures that copy: prompt sections, voice, global_data. The document the
platform gets is rendered from the copy, and the agent you deployed is left as
it was for the next request.

Point each tenant's number at the same host with a different query string:
`https://<user>:<password>@host/front-desk/?tenant=harbor`. The trailing slash
matters in 3.0.1. A header, `X-Tenant`, works too.

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

from dotenv import load_dotenv
from signalwire import AgentBase

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

# What differs per tenant. In production this is a database row keyed by the
# tenant id; here it is a dict so the recipe runs from a clone.
TENANTS = {
    "ridgeline": {
        "name": "Ridgeline Cycles",
        "voice": "rime.spore",
        "hours": "8 to 6, Monday to Saturday",
    },
    "harbor": {
        "name": "Harbor Bike Repair",
        "voice": "rime.marisol",
        "hours": "10 to 7, every day",
    },
}
DEFAULT_TENANT = os.getenv("DEFAULT_TENANT", "ridgeline")


def configure(query_params, body_params, headers, agent):
    """Runs on every request, against an ephemeral copy of the agent."""
    key = (query_params.get("tenant") or headers.get("x-tenant")
           or DEFAULT_TENANT).lower()
    tenant = TENANTS.get(key) or TENANTS[DEFAULT_TENANT]
    if key not in TENANTS:
        key = DEFAULT_TENANT
    agent.prompt_add_section(
        "Tenant",
        f"You answer for {tenant['name']}. Opening hours are {tenant['hours']}. "
        "Never mention any other shop.",
    )
    agent.add_language("English", "en-US", tenant["voice"])
    agent.set_global_data({"tenant": key, "shop": tenant["name"]})


class FrontDeskAgent(AgentBase):
    def __init__(self):
        super().__init__(name="front-desk", route="/front-desk")
        # Everything every tenant shares lives here, on the deployed agent.
        self.prompt_add_section(
            "Role",
            "You are a bicycle shop's front desk. Answer questions about hours "
            "and take a message for anything else.",
        )
        self.set_dynamic_config_callback(configure)


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 one number at https://<user>:<password>@<your-host>/front-desk/?tenant=ridgeline and another at the same URL with ?tenant=harbor. The trailing slash matters; see Limitations.

Verify it

No network, no account. The verifier drives the agent’s own HTTP app with FastAPI’s test client and fetches the SWML the way the platform does.

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

It asserts the following.

a GET without basic auth is refused
?tenant=harbor and ?tenant=ridgeline each render their own voice, one Tenant section naming their shop, and global_data with their key, with the shared Role section first
an X-Tenant: harbor header passes the same voice, section and global_data assertion as the query string
?tenant=nobody passes the default tenant’s assertion in full
after all of those requests, the deployed agent renders byte-for-byte the document it rendered before the first one
a GET on the route without its trailing slash returns 200 with a body of null

Report an issue

Configure a voice AI agent per request for many tenants

The claim

Why it holds

How it works

Limitations

What to change first

Where this sits

Before this

Related

Seen in a build

Seen in a build

Seen in a build

Seen in a build