@spec alive?(server()) :: boolean()

Check if the agent server process is alive.

@spec attach(server(), pid()) :: :ok | {:error, term()}

Attaches a process to this agent, tracking it as an active consumer.

When attached, the agent will not idle-timeout. The agent monitors the attached process and automatically detaches it on exit.

Used by Jido.Agent.InstanceManager to track LiveView sockets, WebSocket handlers, or any process that needs the agent to stay alive.

Examples

{:ok, pid} = Jido.Agent.InstanceManager.get(:sessions, key)
:ok = Jido.AgentServer.attach(pid)

# With explicit owner
:ok = Jido.AgentServer.attach(pid, socket_pid)

@spec await_completion(
  server(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Wait for an agent to reach a terminal status (:completed or :failed).

This is an event-driven wait - the caller blocks until the agent's state transitions to a terminal status, then receives the result immediately. No polling is involved.

Options

• :status_path - Path to status field in agent.state (default: [:status])
• :result_path - Path to result field (default: [:last_answer])
• :error_path - Path to error field (default: [:error])

Returns

• {:ok, %{status: :completed | :failed, result: any()}} - Agent reached terminal status

• {:error, :not_found} - Server not found
• Exits with {:timeout, ...} if GenServer.call times out

Examples

{:ok, result} = AgentServer.await_completion(pid, timeout: 10_000)

@spec call(server(), Jido.Signal.t(), timeout()) :: {:ok, struct()} | {:error, term()}

Synchronously sends a signal and waits for processing.

Returns the updated agent struct after signal processing. Directives are still executed asynchronously via the drain loop.

Returns

• {:ok, agent} - Signal processed successfully
• {:error, :not_found} - Server not found via registry
• {:error, :invalid_server} - Unsupported server reference
• Exits with {:noproc, ...} if process dies during call

Examples

{:ok, agent} = Jido.AgentServer.call(pid, signal)
{:ok, agent} = Jido.AgentServer.call("agent-id", signal, 10_000)

@spec cast(server(), Jido.Signal.t()) :: :ok | {:error, term()}

Asynchronously sends a signal for processing.

Returns immediately. The signal is processed in the background.

Returns

• :ok - Signal queued successfully
• {:error, :not_found} - Server not found via registry
• {:error, :invalid_server} - Unsupported server reference

Examples

:ok = Jido.AgentServer.cast(pid, signal)
:ok = Jido.AgentServer.cast("agent-id", signal)

@spec child_spec(keyword() | map()) :: Supervisor.child_spec()

Returns a child_spec for supervision.

@spec detach(server(), pid()) :: :ok | {:error, term()}

Detaches a process from this agent.

If this was the last attachment and idle_timeout is configured, the idle timer starts.

Note: You don't need to call this explicitly if the attached process exits normally — the monitor will handle cleanup automatically.

Examples

:ok = Jido.AgentServer.detach(pid)

@spec start(keyword() | map()) :: DynamicSupervisor.on_start_child()

Starts an AgentServer under Jido.AgentSupervisor.

Examples

{:ok, pid} = Jido.AgentServer.start(agent: MyAgent)
{:ok, pid} = Jido.AgentServer.start(agent: MyAgent, id: "my-agent")

@spec start_link(keyword() | map()) :: GenServer.on_start()

Starts an AgentServer linked to the calling process.

Options

See module documentation for full list of options.

Examples

{:ok, pid} = Jido.AgentServer.start_link(agent: MyAgent)
{:ok, pid} = Jido.AgentServer.start_link(agent: MyAgent, id: "custom-123")

@spec state(server()) :: {:ok, Jido.AgentServer.State.t()} | {:error, term()}

Gets the full State struct for an agent.

Returns

• {:ok, state} - Full State struct retrieved
• {:error, :not_found} - Server not found via registry
• {:error, :invalid_server} - Unsupported server reference

Examples

{:ok, state} = Jido.AgentServer.state(pid)
{:ok, state} = Jido.AgentServer.state("agent-id")

@spec status(server()) :: {:ok, Jido.AgentServer.Status.t()} | {:error, term()}

Gets runtime status for an agent process.

Returns a Status struct combining the strategy snapshot with process metadata. This provides a stable API for querying agent status without depending on internal __strategy__ state structure.

Returns

• {:ok, status} - Status struct with snapshot and metadata
• {:error, :not_found} - Server not found via registry
• {:error, :invalid_server} - Unsupported server reference

Examples

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

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

# Use delegate helpers
case Status.status(agent_status) do
  :success -> {:done, Status.result(agent_status)}
  :failure -> {:error, Status.details(agent_status)}
  _ -> :continue
end

@spec stream_status(
  server(),
  keyword()
) :: Enumerable.t()

Streams status updates by polling at regular intervals.

Returns a Stream that yields status snapshots. Useful for monitoring agent execution without manual polling loops.

Options

• :interval_ms - Polling interval in milliseconds (default: 100)

Examples

# Poll until completion
AgentServer.stream_status(pid, interval_ms: 50)
|> Enum.reduce_while(nil, fn status, _acc ->
  case Status.status(status) do
    :success -> {:halt, {:ok, Status.result(status)}}
    :failure -> {:halt, {:error, Status.details(status)}}
    _ -> {:cont, nil}
  end
end)

# Take first 10 snapshots
AgentServer.stream_status(pid)
|> Enum.take(10)

@spec touch(server()) :: :ok | {:error, term()}

Touches the agent to reset the idle timer.

Use this for request-based activity tracking (e.g., HTTP requests) where you don't want to maintain a persistent attachment.

Examples

# In a controller
{:ok, pid} = Jido.Agent.InstanceManager.get(:sessions, key)
:ok = Jido.AgentServer.touch(pid)

@spec via_tuple(String.t(), module()) :: {:via, Registry, {module(), String.t()}}

Returns a via tuple for Registry-based naming.

Examples

name = Jido.AgentServer.via_tuple("agent-id", MyApp.Jido.Registry)
GenServer.call(name, :get_state)

@spec whereis(module(), String.t()) :: pid() | nil

Looks up an agent by ID in a specific registry.

Returns the pid if found, nil otherwise.

Examples

pid = Jido.AgentServer.whereis(MyApp.Jido.Registry, "agent-123")
# => #PID<0.123.0>