Skip to main content

​
Overview

The Runner class provides multiple ways to run your agents:
  • Console mode (.run()): Run a single agent in the terminal
  • HTTP server mode (.serve()): Start a web server that spawns agents for calls
  • CLI mode (.cli()): Provide a command-line interface with both modes
from vision_agents.core import AgentLauncher, Runner, ServeOptions

launcher = AgentLauncher(
    create_agent=create_agent,
    join_call=join_call,
)

runner = Runner(
    launcher=launcher,
    serve_options=ServeOptions(),
)

if __name__ == "__main__":
    runner.cli()
With the CLI, you can: 
# Run a single agent in console
python agent.py run --call-id my-call

# Start HTTP server
python agent.py serve --port 8000

​
Constructor

Runner(
    launcher: AgentLauncher,
    serve_options: Optional[ServeOptions] = None,
)

​
Parameters

​
launcher
AgentLauncher
required
Instance of AgentLauncher that manages agent lifecycle.
​
serve_options
Optional[ServeOptions]
default:"None"
Instance of ServeOptions to configure behavior in serve mode. If None, default options are used.

​
Properties

​
fast_api

fast_api: FastAPI
​
fast_api
FastAPI
The FastAPI application instance used for serving agents. Can be customized via serve_options.fast_api.

​
Methods

​
run

def run(
    self,
    call_type: str = "default",
    call_id: Optional[str] = None,
    debug: bool = False,
    log_level: str = "INFO",
    no_demo: bool = False,
    video_track_override: Optional[str] = None,
) -> None
Run the agent as a console app with the specified configuration.
​
call_type
str
default:"default"
Call type for the video call.
​
call_id
Optional[str]
default:"None"
Call ID for the video call (auto-generated if not provided).
​
debug
bool
default:"False"
Enable debug mode.
​
log_level
str
default:"INFO"
Set the logging level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.
​
no_demo
bool
default:"False"
Disable opening the demo UI.
​
video_track_override
Optional[str]
default:"None"
Optional local video track override for debugging. This track will play instead of any incoming video track.
Example: 
runner.run(
    call_type="customer-support",
    call_id="support-123",
    log_level="DEBUG",
)

​
serve

def serve(
    self,
    host: str = "127.0.0.1",
    port: int = 8000,
    agents_log_level: str = "INFO",
    http_log_level: str = "INFO",
    debug: bool = False,
) -> None
Start the HTTP server that spawns agents to the calls.
​
host
str
default:"127.0.0.1"
Host address to bind the server to.
​
port
int
default:"8000"
Port number for the server.
​
agents_log_level
str
default:"INFO"
Logging level for agent-related logs.
​
http_log_level
str
default:"INFO"
Logging level for FastAPI and uvicorn logs.
​
debug
bool
default:"False"
Enable asyncio debug mode.
Example: 
runner.serve(
    host="0.0.0.0",
    port=8080,
    agents_log_level="DEBUG",
)

​
cli

def cli(self) -> None
Run the command-line interface with run and serve subcommands. Example: 
# agent.py
if __name__ == "__main__":
    runner.cli()
Then use from command line: 
# Run command with options
python agent.py run --call-type default --call-id test-123 --debug

# Serve command with options
python agent.py serve --host 0.0.0.0 --port 8080 --agents-log-level DEBUG

​
HTTP Server Endpoints

When using .serve(), the following REST endpoints are available:

​
POST /sessions

Start a new agent session. Request Body: 
{
  "call_id": "my-call-123",
  "call_type": "default"
}
Response: 
{
  "session_id": "agent-abc-123",
  "call_id": "my-call-123",
  "started_at": "2026-03-02T10:30:00Z"
}

​
GET /sessions//

Get information about a session. Response: 
{
  "session_id": "agent-abc-123",
  "call_id": "my-call-123",
  "started_at": "2026-03-02T10:30:00Z",
  "status": "active"
}

​
DELETE /sessions//

Close a session. Response: 
{
  "success": true
}

​
GET /health

Health check endpoint. Response: 
{
  "status": "healthy",
  "warmed_up": true,
  "running": true
}

​
GET /metrics

Get launcher metrics. Response: 
{
  "active_sessions": 3,
  "total_sessions_started": 10,
  "warmed_up": true,
  "running": true
}

​
Complete Example

from vision_agents.core import Agent, AgentLauncher, Runner, ServeOptions, User
from vision_agents.edge import Edge
from vision_agents.llm.gemini import Realtime

def create_agent():
    return Agent(
        edge=Edge(),
        agent_user=User(id="agent", name="AI Assistant"),
        llm=Realtime(),
        instructions="You are a helpful assistant.",
    )

async def join_call(agent, call_type, call_id):
    call = await agent.create_call(call_type, call_id)
    async with agent.join(call):
        await agent.finish()

launcher = AgentLauncher(
    create_agent=create_agent,
    join_call=join_call,
    agent_idle_timeout=60.0,
    max_concurrent_sessions=10,
)

runner = Runner(
    launcher=launcher,
    serve_options=ServeOptions(
        cors_allow_origins={"*"},
    ),
)

if __name__ == "__main__":
    # Provides both 'run' and 'serve' commands
    runner.cli()
Usage: 
# Console mode
python agent.py run --call-id my-test-call

# Server mode
python agent.py serve --host 0.0.0.0 --port 8000

# Then from another terminal:
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{"call_id": "test-123", "call_type": "default"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us