Codex.Realtime.Runner (Codex SDK v0.7.2)

Orchestrates realtime agent sessions.

A Runner is the equivalent of Codex.AgentRunner for realtime agents. It automatically handles multiple turns by maintaining a persistent connection with the underlying model layer.

The session manages the local history copy, executes tools, runs guardrails and facilitates handoffs between agents.

Since this code runs on your server, it uses WebSockets by default. You can optionally create your own custom model layer by implementing the Codex.Realtime.Model behaviour.

Example

# Create an agent
agent = Codex.Realtime.Agent.new(
  name: "VoiceAssistant",
  instructions: "You are a helpful voice assistant."
)

# Create a runner
runner = Codex.Realtime.Runner.new(agent,
  config: %Codex.Realtime.Config.RunConfig{
    tracing_disabled: false
  }
)

# Start a session
{:ok, session} = Codex.Realtime.Runner.run(runner)

# Use the session
Codex.Realtime.Session.send_message(session, "Hello!")

# Subscribe to events
Codex.Realtime.Session.subscribe(session, self())
receive do
  {:session_event, event} -> handle_event(event)
end

Options

When creating a runner with new/2:

:config - A %Codex.Realtime.Config.RunConfig{} for runtime settings
:model - Optional custom model module implementing the Model behaviour

When starting a session with run/2:

:context - Context map passed to the session
:model_config - A %Codex.Realtime.Config.ModelConfig{} for API settings
:websocket_pid - For testing with a mock WebSocket
:websocket_module - Override the WebSocket module (default: WebSockex)

Summary

Types

t()

Functions

new(starting_agent, opts \\ [])

Create a new realtime runner.

run(runner, opts \\ [])

Start a realtime session.

Types

t()

@type t() :: %Codex.Realtime.Runner{
  config: Codex.Realtime.Config.RunConfig.t() | nil,
  model: module() | nil,
  starting_agent: Codex.Realtime.Agent.t() | nil
}

Functions

new(starting_agent, opts \\ [])

@spec new(
  Codex.Realtime.Agent.t(),
  keyword()
) :: t()

Create a new realtime runner.

Arguments

starting_agent - The agent to start the session with.

Options

:config - Override parameters to use for the entire run.
:model - The model to use. If not provided, will use the default OpenAI realtime model.

Example

agent = Codex.Realtime.Agent.new(name: "Assistant")
runner = Codex.Realtime.Runner.new(agent,
  config: %Codex.Realtime.Config.RunConfig{tracing_disabled: true}
)

run(runner, opts \\ [])

@spec run(
  t(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Start a realtime session.

Returns a session that can be used for bidirectional communication.

Options

:context - Context to pass to the session (default: %{})
:model_config - Model connection configuration (%ModelConfig{})
:websocket_pid - For testing with a mock WebSocket
:websocket_module - Override the WebSocket module

Returns

{:ok, pid} - Session started successfully
{:error, reason} - Failed to start session

Example

runner = Runner.new(agent)
{:ok, session} = Runner.run(runner)

# Send messages
Session.send_message(session, "Hello!")

# Stream events
Session.subscribe(session, self())
receive do
  {:session_event, event} -> handle_event(event)
end

# Close when done
Session.close(session)