Codex (Codex SDK v0.7.2)

Public entry point for the Codex SDK.

Provides helpers to start new threads or resume existing ones.

Realtime Voice

For real-time voice interactions using WebSockets:

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

# Create and run a session
{:ok, session} = Codex.Realtime.run(agent)

# Send audio and subscribe to events
Codex.Realtime.send_audio(session, audio_bytes)
Codex.Realtime.subscribe(session, self())

receive do
  {:session_event, event} -> handle_event(event)
end

See Codex.Realtime for full documentation.

Voice Pipeline

For non-realtime voice processing (STT -> Workflow -> TTS):

workflow = Codex.Voice.simple_workflow(fn text ->
  ["You said: #{text}"]
end)

{:ok, result} = Codex.Voice.run(audio, workflow: workflow)

See Codex.Voice for full documentation.

Summary

Types

start_opts()

thread_opts()

Functions

list_sessions(opts \\ [])

Lists session files persisted by the Codex CLI.

realtime_agent(opts)

Create a realtime agent.

realtime_run(agent, opts \\ [])

Create and start a realtime session with an agent.

resume_thread(thread_id, opts \\ %{}, thread_opts \\ %{})

Resumes an existing thread with the given thread_id.

start_thread(opts \\ %{}, thread_opts \\ %{})

Starts a new Codex thread returning a %Codex.Thread{} struct.

voice_audio_input(data, opts \\ [])

Create an audio input from binary data.

voice_run(audio, opts)

Create and run a voice pipeline.

Types

start_opts()

@type start_opts() :: map() | keyword() | Codex.Options.t()

thread_opts()

@type thread_opts() :: map() | keyword() | Codex.Thread.Options.t()

Functions

list_sessions(opts \\ [])

@spec list_sessions(keyword()) ::
  {:ok, [Codex.Sessions.session_entry()]} | {:error, term()}

Lists session files persisted by the Codex CLI.

Returns entries parsed from ~/.codex/sessions by default.

realtime_agent(opts)

@spec realtime_agent(keyword()) :: Codex.Realtime.Agent.t()

Create a realtime agent.

Delegates to Codex.Realtime.agent/1.

Example

agent = Codex.realtime_agent(
  name: "VoiceBot",
  instructions: "You are a helpful voice bot.",
  tools: [my_tool]
)

realtime_run(agent, opts \\ [])

@spec realtime_run(
  Codex.Realtime.Agent.t(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Create and start a realtime session with an agent.

Delegates to Codex.Realtime.run/2.

Example

agent = Codex.realtime_agent(name: "Assistant", instructions: "Be helpful.")
{:ok, session} = Codex.realtime_run(agent)

resume_thread(thread_id, opts \\ %{}, thread_opts \\ %{})

@spec resume_thread(String.t() | :last, start_opts(), thread_opts()) ::
  {:ok, Codex.Thread.t()} | {:error, term()}

Resumes an existing thread with the given thread_id.

Pass :last to resume the most recent recorded session (equivalent to codex exec resume --last).

start_thread(opts \\ %{}, thread_opts \\ %{})

@spec start_thread(start_opts(), thread_opts()) ::
  {:ok, Codex.Thread.t()} | {:error, term()}

Starts a new Codex thread returning a %Codex.Thread{} struct.

voice_audio_input(data, opts \\ [])

@spec voice_audio_input(
  binary(),
  keyword()
) :: Codex.Voice.Input.AudioInput.t()

Create an audio input from binary data.

Delegates to Codex.Voice.audio_input/2.

Example

audio = Codex.voice_audio_input(File.read!("recording.pcm"))

voice_run(audio, opts)

@spec voice_run(
  Codex.Voice.Input.AudioInput.t() | Codex.Voice.Input.StreamedAudioInput.t(),
  keyword()
) :: {:ok, Codex.Voice.Result.t()}

Create and run a voice pipeline.

Delegates to Codex.Voice.run/2.

Example

workflow = Codex.Voice.simple_workflow(fn text -> ["Echo: #{text}"] end)
{:ok, result} = Codex.voice_run(audio, workflow: workflow)