Skip to main content

​
Agent Runtimes

The AGENT_RUNTIME environment variable controls how the agent is started when you click Test in the builder or make a request to /api/agent-session. 
# .env.local
AGENT_RUNTIME=inprocess   # default

​
The three modes

ModeValueRequires a separate process?Best for
In-processinprocessNoLocal development, zero-config testing
TypeScript workertypescriptYes (pnpm agent-typescript:dev)Production (TypeScript)
Python workerpythonYes (pnpm agent-python:dev)Production (Python), broader provider ecosystem

​
inprocess (default)

The TypeScript agent runs inside the Next.js process. No separate terminal needed. 
# .env.local
AGENT_RUNTIME=inprocess
Start the app normally: 
pnpm dev
When a session starts, /api/agent-session calls startLocalAgent() directly. The agent reads the AgentConfig from the LiveKit room metadata and publishes step/state events on the voiceblox.agent.events data channel — the same path used in worker modes. Limitations: The in-process agent shares memory and CPU with Next.js. For production workloads, use a dedicated worker.

​
typescript worker

A standalone TypeScript worker process connects to your LiveKit project and handles agent jobs. 
# .env.local
AGENT_RUNTIME=typescript
Run both in separate terminals: 
# Terminal 1
pnpm dev

# Terminal 2
pnpm agent-typescript:dev
See TypeScript Worker for full setup details.

​
python worker

A standalone Python worker process with full feature parity and a broader provider/plugin ecosystem via the LiveKit Agents Python SDK. 
# .env.local
AGENT_RUNTIME=python
Run both in separate terminals: 
# Terminal 1
pnpm dev

# Terminal 2
pnpm agent-python:dev
See Python Worker for setup instructions and supported providers.

​
How dispatch works

For typescript and python modes, /api/agent-session:
  1. Creates a LiveKit room with the AgentConfig JSON serialized into the room metadata
  2. Calls AgentDispatchClient.createDispatch() to dispatch the job to a registered worker named voiceblox
  3. Returns a JWT so the browser can join the room
The worker picks up the job, reads the config from metadata, builds the LLM/TTS/STT instances, and starts the session. For inprocess mode, steps 2–3 are replaced by a direct call to startLocalAgent() inside the same process.