Jido.AgentServer.Status (Jido v2.0.0-rc.4)

View Source

Runtime status for an agent process.

Combines Strategy.Snapshot with process-level metadata to provide a clean, stable API for querying agent status without depending on internal __strategy__ implementation details.

Fields

  • agent_module - The agent's module (e.g., MyAgent)
  • agent_id - The agent's unique ID
  • pid - The GenServer process PID
  • snapshot - The Strategy.Snapshot containing core status info
  • raw_state - Escape hatch containing full agent state (use sparingly)

Usage

{:ok, agent_status} = AgentServer.status(pid)

# Check if completed
if agent_status.snapshot.done? do
  IO.puts("Result: " <> inspect(agent_status.snapshot.result))
end

# Access snapshot fields via helpers
case Status.status(agent_status) do
  :success -> handle_success(agent_status)
  :failure -> handle_failure(agent_status)
  :running -> poll_again()
end

Delegate Helpers

The module provides convenience delegates to common snapshot fields:

  • status/1 - Returns the snapshot's status
  • done?/1 - Returns the snapshot's done? flag
  • result/1 - Returns the snapshot's result
  • details/1 - Returns the snapshot's details map

Summary

Types

t()

Functions

active_requests(status)

Returns active request tuples [{id, status}].

details(status)

Returns strategy-specific details from the snapshot.

done?(status)

Returns whether the agent has reached a terminal state.

iteration(status)

Returns the current iteration count from snapshot details.

new(attrs)

Creates a new Status from a map of attributes.

queue_length(status)

Returns the directive queue length.

result(status)

Returns the result from the snapshot (if any).

status(status)

Returns the status from the snapshot (:idle, :running, :waiting, :success, :failure).

termination_reason(status)

Returns the termination reason (e.g., :final_answer, :max_iterations, :error).

Types

t()

@type t() :: %Jido.AgentServer.Status{
  agent_id: binary(),
  agent_module: atom(),
  pid: any(),
  raw_state: map(),
  snapshot: any()
}

Functions

active_requests(status)

@spec active_requests(t()) :: [{String.t(), atom()}]

Returns active request tuples [{id, status}].

details(status)

@spec details(t()) :: map()

Returns strategy-specific details from the snapshot.

done?(status)

@spec done?(t()) :: boolean()

Returns whether the agent has reached a terminal state.

iteration(status)

@spec iteration(t()) :: non_neg_integer() | nil

Returns the current iteration count from snapshot details.

new(attrs)

@spec new(map()) :: {:ok, t()} | {:error, term()}

Creates a new Status from a map of attributes.

Returns {:ok, status} or {:error, reason}.

queue_length(status)

@spec queue_length(t()) :: non_neg_integer()

Returns the directive queue length.

result(status)

@spec result(t()) :: term() | nil

Returns the result from the snapshot (if any).

status(status)

@spec status(t()) :: Jido.Agent.Strategy.status()

Returns the status from the snapshot (:idle, :running, :waiting, :success, :failure).

termination_reason(status)

@spec termination_reason(t()) :: atom() | nil

Returns the termination reason (e.g., :final_answer, :max_iterations, :error).