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

A realtime agent optimized for voice interactions.

Realtime agents are specialized agents meant to be used within a Codex.Realtime.Session to build voice agents. Due to the nature of this agent, some configuration options differ from regular Codex.Agent instances:

model choice is constrained to realtime-capable models
Output types and structured outputs are not supported
Voice can be configured at the agent level

Features

Voice-to-voice communication
Tool execution during conversations
Handoffs to other agents
Dynamic instructions (string or function)
Output guardrails

Examples

# Simple agent
agent = %Codex.Realtime.Agent{
  name: "Assistant",
  instructions: "You are a helpful voice assistant."
}

# Agent with dynamic instructions
agent = %Codex.Realtime.Agent{
  name: "Greeter",
  instructions: fn ctx -> "Welcome #{ctx.user_name}!" end
}

# Agent with handoffs
support_agent = %Codex.Realtime.Agent{name: "Support"}
main_agent = %Codex.Realtime.Agent{
  name: "Main",
  handoffs: [support_agent]
}

Summary

Types

instruction_fn()

t()

Functions

clone(agent, changes)

Create a copy of the agent with the given fields changed.

find_handoff_target(agent, tool_name)

Find handoff target by tool name.

get_tools(agent)

Get all tools including handoff tools.

new(opts \\ [])

Create a new realtime agent from keyword options.

resolve_instructions(agent, context)

Resolve instructions, calling function if needed.

Types

instruction_fn()

@type instruction_fn() :: (map() -> String.t()) | (map(), t() -> String.t())

t()

@type t() :: %Codex.Realtime.Agent{
  handoff_description: String.t() | nil,
  handoffs: [t() | Codex.Handoff.t()],
  hooks: term(),
  instructions: String.t() | instruction_fn() | nil,
  model: String.t(),
  name: String.t(),
  output_guardrails: [term()],
  tools: [module()]
}

Functions

clone(agent, changes)

@spec clone(
  t(),
  keyword()
) :: t()

Create a copy of the agent with the given fields changed.

Examples

new_agent = Codex.Realtime.Agent.clone(agent, name: "NewName")

find_handoff_target(agent, tool_name)

@spec find_handoff_target(t(), String.t()) ::
  {:ok, t() | Codex.Agent.t()} | {:error, :not_found}

Find handoff target by tool name.

Given a tool name like "transfer_to_support", finds the corresponding agent or handoff target in the handoffs list.

Examples

support = %Agent{name: "Support"}
agent = %Agent{handoffs: [support]}
{:ok, target} = Agent.find_handoff_target(agent, "transfer_to_support")
target.name #=> "Support"

get_tools(agent)

@spec get_tools(t()) :: [module() | Codex.Handoff.t()]

Get all tools including handoff tools.

Returns the agent's tools combined with auto-generated handoff tools for each configured handoff.

Examples

support = %Agent{name: "Support"}
agent = %Agent{tools: [MyTool], handoffs: [support]}
Agent.get_tools(agent)
#=> [MyTool, %Handoff{tool_name: "transfer_to_support", ...}]

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new realtime agent from keyword options.

Examples

agent = Codex.Realtime.Agent.new(
  name: "VoiceBot",
  instructions: "Be helpful and concise."
)

resolve_instructions(agent, context)

@spec resolve_instructions(t(), map()) :: String.t() | nil

Resolve instructions, calling function if needed.

Supports both arity-1 functions (receiving context) and arity-2 functions (receiving context and agent).

Examples

# String instructions
agent = %Agent{instructions: "Be helpful"}
Agent.resolve_instructions(agent, %{}) #=> "Be helpful"

# Function instructions (arity 1)
agent = %Agent{instructions: fn ctx -> "Hello #{ctx.user}" end}
Agent.resolve_instructions(agent, %{user: "Alice"}) #=> "Hello Alice"

# Function instructions (arity 2)
agent = %Agent{
  name: "Bot",
  instructions: fn ctx, agent -> "Hello #{ctx.user}, I'm #{agent.name}" end
}
Agent.resolve_instructions(agent, %{user: "Bob"}) #=> "Hello Bob, I'm Bot"