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 runs | Use | Entrypoint |
|---|---|---|
| Your production backend, which can accept an authenticated WebSocket | An inbound route (the default) | run_session |
| Your laptop, during development | Cortex: no tunnel, no public route | serve |
| A serverless function, or a network that allows only outbound connections | Cortex | serve |
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.
Setting the brain_url
Section titled “Setting the brain_url”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.
| Rule | Detail |
|---|---|
| Scheme | wss://. Plain ws:// is accepted only for localhost and 127.0.0.1. |
| Path | Give the full URL of your route. Voqalize dials it as given and appends only ?session_id=. |
| Mode | Setting brain_url puts the agent in inbound mode. |
| Cortex | You 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.
A route Voqalize dials
Section titled “A route Voqalize dials”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.
pip install "voqalize-agent-sdk==0.15.0" fastapi "uvicorn[standard]"import contextlibimport os
from fastapi import FastAPI, WebSocketfrom starlette.websockets import WebSocketDisconnectfrom 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 failedRun 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_sessionaccepts any object withasync send(bytes)andasync 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.
Surviving a redeploy
Section titled “Surviving a redeploy”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 storeIt 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 inon_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_endruns 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 onsession.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 brain | Voqalize |
|---|---|
Hangs up with End (the SDK always does), or closes 1000 | Ends the call. |
Closes 1012 or 1001: the drain on a deploy | Redials at once. |
Exits, crashes or is killed with no close frame, closes 1011, or the network drops | Redials. |
Closes with 4000–4999, or a protocol or policy code | Ends the call: an application decision is final. |
- Drain with
1012, never1000. A1000is a hang-up. uvicorn closes every socket1012onSIGTERMby itself. - A
finally: await ws.close()turns every crash into a hang-up. Close1011on 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.
A brain that dials out
Section titled “A brain that dials out”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…")| Field | Where it goes |
|---|---|
agent_secret | An sk_ key for this agent, passed as api_key=. Shown once; it cannot be read back, only revoked and re-minted. |
cortex_url | Passed 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 asyncioimport 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"], ))versionandcortex_urlare required.serveforwards them to its relay client, so leaving one out raises aTypeErrorfrom insideserve.versionis your own string; it travels as theX-Agent-Versionheader and tells you which build answered a session.- Pass exactly one credential:
api_key=(ansk_key), orauthorization_provider=, a callable that returns"Bearer <jwt>"for each connect. Both or neither raises at once. serveblocks for the life of the relay connection and returns when the relay closes it permanently. Run it fromasyncio.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.
The brain-connection token
Section titled “The brain-connection token”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.
Check the token names your agent
Section titled “Check the token names your agent”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.
How calls are kept apart
Section titled “How calls are kept apart”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.
Local development
Section titled “Local development”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:
export VOQALIZE_AGENT_SECRET=sk_live_… # agent_secretexport VOQALIZE_CORTEX_URL=wss://cortex.prod.voqalize.com/agent # cortex_url, as returnedpython run_cortex.pyBoth 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.
Read next
Section titled “Read next”- Keys and authentication: which key goes where, and how to rotate one.
- Connect your app: start a session from your page.
- Test the brain: drive the brain over the real wire, with no microphone.