Omni.Agent.State (Omni Agent v0.5.0)

The public state passed to all Omni.Agent callbacks.

Internal server machinery (task tracking, tool decision state, process refs) is managed separately and not exposed to callbacks.

Fields fall into two groups:

Configuration — set at startup, changeable via set_state/2,3:

:model — the %Model{} this agent is using
:system — system prompt string, or nil
:messages — committed message history. Only changes at turn boundaries or via set_state(:messages, ...); in-progress turn messages are held internally until the turn completes
:tools — list of %Tool{} available to the model
:opts — agent-level default inference options (keyword list), passed to stream_text each step

Runtime — change during operation:

:private — runtime state (PIDs, ETS refs, closures). Not persisted. Set initial values via the :private start option or in init/1, update in any callback via %{state | private: ...}. Not settable via set_state/2,3. The :omni key is reserved — when running under Omni.Session, the session writes private[:omni] = %{session_id: ..., session_pid: ...} before init/1 runs and overwrites any user-supplied value. Use any other key freely
:status — :idle, :busy, or :paused
:step — current step counter within the active turn. Resets to 0 when a new turn begins. Useful for step-based policies in callbacks (e.g. rejecting tools after a threshold)

Summary

Types

t()

The public agent state passed to all callbacks.

Functions

validate_messages(messages)

Validates that a message list is safe to sit idle in state.messages.

Types

t()

@type t() :: %Omni.Agent.State{
  messages: [Omni.Message.t()],
  model: Omni.Model.t(),
  opts: keyword(),
  private: map(),
  status: :idle | :busy | :paused,
  step: non_neg_integer(),
  system: String.t() | nil,
  tools: [Omni.Tool.t()]
}

The public agent state passed to all callbacks.

Functions

validate_messages(messages)

@spec validate_messages([Omni.Message.t()]) :: :ok | {:error, :invalid_messages}

Validates that a message list is safe to sit idle in state.messages.

Returns :ok if the list is empty, or if its last message has role: :assistant and contains no %Omni.Content.ToolUse{} blocks. Otherwise returns {:error, :invalid_messages}.

This is the invariant enforced at set_state(:messages, ...) and on the state returned from init/1. It does not perform deep validation of interior messages.