Skip to content

Deploy the brain

An agent reaches its brain through one setting, deployment.brain_url, a single WebSocket URL. When a session starts, Voqalize dials {brain_url}?session_id={session_id}: one connection per session, opened when the session starts and closed when it ends.

What you choose is who dials whom. Your Brain class is the same either way; only the entrypoint changes.

Where the brain runsUseEntrypoint
Your production backend, which can accept an authenticated WebSocketAn inbound route (the default)run_session
Your laptop, during developmentCortex: no tunnel, no public routeserve
A serverless function, or a network that allows only outbound connectionsCortexserve

Cortex is Voqalize’s WebSocket relay: your brain dials out to it, and Voqalize reaches your brain through it. It adds a hop, so in production prefer an inbound route wherever your backend can take one.

Point an agent at your inbound route with the MCP server:

update_agent(tenant="acme", agent_id="06a2…", brain_url="wss://brain.example.com/voice")

create_agent takes the same brain_url argument up front.

RuleDetail
Schemewss://. Plain ws:// is accepted only for localhost and 127.0.0.1.
PathGive the full URL of your route. Voqalize dials it as given and appends only ?session_id=.
ModeSetting brain_url puts the agent in inbound mode.
CortexYou set no URL. create_agent_credentials puts the agent in cortex mode and stores the relay address for you.

An agent with neither a brain_url nor Cortex credentials cannot take a session: sessions.connect refuses it with 409 agent_not_configured, and get_agent reports its stage as unconfigured.

The agent record carries no voice or language. Those are set per session; see Voice and language.

Mount one WebSocket route in the web app you already run, read session_id from the query string, and hand the socket to the SDK’s run_session. It verifies the connection, runs the session, and returns when the session ends.

Terminal window
pip install "voqalize-agent-sdk==0.15.0" fastapi "uvicorn[standard]"
import contextlib
import os
from fastapi import FastAPI, WebSocket
from starlette.websockets import WebSocketDisconnect
from voqalize.sdk import SessionRejected, run_session
from mybrain import MyBrain # your Brain subclass
app = FastAPI()
class _WsChannel:
"""Adapts a FastAPI WebSocket to the SDK's send/recv channel."""
def __init__(self, ws: WebSocket) -> None:
self._ws = ws
async def send(self, data: bytes) -> None:
await self._ws.send_bytes(data)
async def recv(self) -> bytes:
return await self._ws.receive_bytes()
@app.websocket("/voice")
async def voice(ws: WebSocket, session_id: str) -> None: # session_id from ?session_id=
await ws.accept()
try:
await run_session(
_WsChannel(ws),
brain=MyBrain, # or brain=lambda: MyBrain(llm=...)
session_id=session_id,
token=ws.headers.get("authorization"),
expect_agent=os.environ["VOQALIZE_AGENT_ID"], # the agent this route serves
)
except SessionRejected:
await ws.close(code=4000) # the token did not verify, or names another agent
except WebSocketDisconnect:
pass # Voqalize closed the socket: the session is over
except Exception:
with contextlib.suppress(Exception):
await ws.close(code=1011) # your brain failed

Run it with uvicorn app:app --host 0.0.0.0 --port 8080 behind your own TLS and load balancer, and set the agent’s brain_url to the route’s public wss:// URL.

  • run_session accepts any object with async send(bytes) and async recv() -> bytes, so the same route mounts on Starlette, aiohttp or Django Channels.
  • brain= is a class, or a zero-argument callable that returns a brain. It is constructed fresh for each session, so no state leaks between sessions.
  • To drive the route without a real session, see Test the brain.

The socket is the session, unless the brain turns on redial. Voqalize retries opening the socket for up to 10 seconds, so a brain that is still starting up is reached. Once your route accepts it, any close ends the session, whatever the code: a second connection would reach a fresh brain with none of the first one’s history. A brain that keeps its sessions somewhere a new connection can find them can opt in to being dialled again instead; see Surviving a redeploy.

Each session is one socket, so there is nothing to pool: dropping a socket drops that session.

Without redial, every deploy of your brain ends every call it is serving. With it, a call outlives its socket: when the socket drops and your brain did not hang up, Voqalize dials your brain_url again for the same session and carries on.

Turn it on from the brain, in on_session_start, and only if the brain can rejoin a call it did not start (below):

from voqalize.sdk.wire import Config, RedialConfig
class MyBrain(Brain):
async def on_session_start(self, session):
if session.can_redial:
await session.configure(Config(redial=RedialConfig(enabled=True)))
self.state = await load_or_create(session.id) # your own store

It is off by default, applies at once, and lasts the call: a redialled brain need not set it again. On a Voqalize that does not list the redial capability, can_redial is false and configure raises Unsupported rather than send a setting that would be ignored.

What a redial is. The new socket opens exactly as the first did: the same brain_url and ?session_id=, a fresh token for the same session, and the same SessionStart, with the same init. Nothing on the wire says it is a redial, and the SDK runs it as a new session: a fresh brain instance, on_session_start, then greet. So:

  • Key what a call needs by session.id, in a store every instance behind your URL can read, and load it in on_session_start. A brain that finds nothing stored has a new call; one that finds something has a rejoin.
  • The greeting is not spoken again. Return it as usual; on a redial the user does not hear it.
  • Turns are not lost. Every user turn your brain had not answered when the socket dropped, and every turn the user took while it was down, is sent again in order. The user hears silence while the brain is away.
  • on_session_end runs at least once, not exactly once. It runs on the old socket and again on the new one, so what it does must be idempotent: key a write on session.id. It also cannot run at all when the process is killed outright, so it is no place for the only copy of anything.
  • Expire what you store. A call ends without telling a brain that is not connected, so give stored sessions a time limit.

What redials and what ends. Your brain decides by how it closes:

Your brainVoqalize
Hangs up with End (the SDK always does), or closes 1000Ends the call.
Closes 1012 or 1001: the drain on a deployRedials at once.
Exits, crashes or is killed with no close frame, closes 1011, or the network dropsRedials.
Closes with 4000–4999, or a protocol or policy codeEnds the call: an application decision is final.
  • Drain with 1012, never 1000. A 1000 is a hang-up. uvicorn closes every socket 1012 on SIGTERM by itself.
  • A finally: await ws.close() turns every crash into a hang-up. Close 1011 on an exception, as the route above does.

Limits. Voqalize redials one drop for up to 30 seconds and a call for 60 seconds in all. A socket that dies within 10 seconds of opening, three times in a row, ends the call: a brain that crashes on every rejoin is not redialled for ever. A redial answered with a refusal, such as 401, 403 or 410, ends the call at once, since asking again gets the same answer.

With Cortex, your brain opens one outbound WebSocket to the relay and keeps it open. Voqalize connects to the same relay for each session, and Cortex pairs the two by the agent their credentials name, never by anything in a URL. Many sessions share your one outbound socket.

Get the credentials over the MCP server:

create_agent_credentials(tenant="acme", agent_id="06a2…")
FieldWhere it goes
agent_secretAn sk_ key for this agent, passed as api_key=. Shown once; it cannot be read back, only revoked and re-minted.
cortex_urlPassed as cortex_url=, as returned. It already ends in /agent, for example wss://cortex.prod.voqalize.com/agent.

Calling it switches the agent to cortex mode. There is no URL to copy back into the agent.

import asyncio
import os
from voqalize.sdk import serve
from mybrain import MyBrain # your Brain subclass
asyncio.run(
serve(
MyBrain, # or a () -> Brain callable
version="1.0.0",
cortex_url=os.environ["VOQALIZE_CORTEX_URL"],
api_key=os.environ["VOQALIZE_AGENT_SECRET"],
)
)
  • version and cortex_url are required. serve forwards them to its relay client, so leaving one out raises a TypeError from inside serve. version is your own string; it travels as the X-Agent-Version header and tells you which build answered a session.
  • Pass exactly one credential: api_key= (an sk_ key), or authorization_provider=, a callable that returns "Bearer <jwt>" for each connect. Both or neither raises at once.
  • serve blocks for the life of the relay connection and returns when the relay closes it permanently. Run it from asyncio.run, a task in your app’s lifespan, or a worker entrypoint.

Cortex keeps no session state. If it restarts, your brain’s connection reconnects, and the sessions that were in flight end, unless they turned on redial.

To rotate the key, see Keys and authentication.

On both paths, Voqalize presents the same credential: the brain-connection token, a short-lived RS256 JWT whose sub is the session_id, in the Authorization header. run_session verifies it against Voqalize’s public keys, which ship inside the SDK, so you pass the header value through and check nothing yourself.

A token that fails verification raises SessionRejected; close the socket with code 4000, as the route above does.

The token also names the workspace and the agent the session was started for. Voqalize signs a genuine token for every agent it calls, so a route at a public URL that checks only the signature also answers any other agent pointed at that URL, from any workspace. Pass your agent’s id as expect_agent=, and run_session refuses a token signed for any other agent with SessionRejected, exactly as it refuses a forged one:

await run_session(
channel,
brain=MyBrain,
session_id=session_id,
token=token,
expect_agent=os.environ["VOQALIZE_AGENT_ID"], # or a list, for a route several agents share
)

Your agent’s id is the agent_id that create_agent returned, and get_agent reports it. expect_agent is optional in this release, and leaving it out logs a warning once per process. A future release will require it.

Inside the brain, session.tenant_id and session.agent_id hold the workspace and agent the verified token names. Branch on agent_id when one brain serves several agents. Both are None behind Cortex, which already admits only your agent’s sessions, and under allow_unverified=True.

The claims are listed in the wire reference, and the harness in Test the brain mints the same token for tests.

Voqalize serves many customers from the same voice nodes and the same speech tier. Everything it builds for a call is keyed by the verified session_id in the token above, which only Voqalize can sign.

The session token your page uses is a bearer credential for its call: whoever holds it can rejoin that call, which is how a page reload resumes it. Keep it in the page that started the session, and never log it.

What each session has to itself:

  • The audio and the WebRTC connection. Encrypted per connection (DTLS-SRTP), and the keys are never shared.
  • Its connection to your brain. One WebSocket per session, as above. Nothing is pooled.
  • Its connections to speech recognition and to the voice. One of each per session, neither pooled nor shared.
  • Its turn-taking, idle and acknowledgement state.
  • Its call record, recording and logs, each written under its own session_id, in your workspace’s storage path.

What is shared, and why it is safe:

  • The voice node’s process and network ports. Calls arrive on the same ports and are told apart by their encrypted connection, not by the port.
  • The relay that carries calls through restrictive networks. It relays only for a call that node holds, with credentials minted for that session.
  • The speech tier. Its models are read-only. It caches rendered sentences by voice, language and text, so the same sentence spoken by two customers may be rendered once.
  • The control plane and its database. Every record carries its workspace, and every read checks your membership of it. No browser or SDK reaches the database directly: only our services do.
  • Cortex, for brains that dial out. Both legs authenticate, and the pair is matched by the verified agent credential, never by the URL.

Your brain and its language model are yours, and none of this applies to them.

For customers who need it, the voice runtime and the speech tier can run on your own infrastructure, carrying your calls only. Ask us: Status and support.

Develop with Cortex. It needs no public route and no tunnel. Create the agent, call create_agent_credentials, export what it returned, and run the serve script above:

Terminal window
export VOQALIZE_AGENT_SECRET=sk_live_… # agent_secret
export VOQALIZE_CORTEX_URL=wss://cortex.prod.voqalize.com/agent # cortex_url, as returned
python run_cortex.py

Both variable names are your own: your code reads them and passes them to serve. Then open the agent’s test_url from get_agent and talk to it.

To exercise the inbound route itself before you deploy, run it locally, put a tunnel in front of it, and set brain_url to the tunnel’s wss:// URL with the route’s path. The token verifies exactly as in production. run_session also takes allow_unverified=True, which skips verification; never set it on a route Voqalize can reach.