Normandy.Coordination.AgentSupervisor (normandy v2.2.0)

Dynamic supervisor for managing agent processes.

AgentSupervisor provides fault-tolerant supervision of agent processes, enabling automatic restarts on failures and dynamic agent pool management.

Features

Dynamic agent spawning
Automatic restart on failure
Configurable restart intensity (:max_restarts, :max_seconds)
Agent process discovery

Example

# Start supervisor
{:ok, sup_pid} = AgentSupervisor.start_link(
  name: :agent_supervisor,
  strategy: :one_for_one
)

# Start an agent under supervision
{:ok, agent_pid} = AgentSupervisor.start_agent(
  sup_pid,
  agent: my_agent,
  agent_id: "research_agent"
)

# List all supervised agents
agents = AgentSupervisor.list_agents(sup_pid)

Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

count_agents(supervisor)

Returns count of supervised agents.

fetch_agent(supervisor, agent_id)

Looks up a running agent by its agent_id: {:ok, pid} or :error.

list_agents(supervisor)

Lists all supervised agent processes.

start_agent(supervisor, opts)

Starts an agent process under supervision.

start_link(opts \\ [])

Starts the agent supervisor.

terminate_agent(supervisor, agent_pid)

Terminates an agent process.

terminate_all(supervisor)

Terminates all supervised agents.

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

count_agents(supervisor)

@spec count_agents(Supervisor.supervisor()) :: non_neg_integer()

Returns count of supervised agents.

Example

count = AgentSupervisor.count_agents(supervisor)
#=> 5

fetch_agent(supervisor, agent_id)

@spec fetch_agent(Supervisor.supervisor(), String.t()) :: {:ok, pid()} | :error

Looks up a running agent by its agent_id: {:ok, pid} or :error.

Example

{:ok, pid} = AgentSupervisor.fetch_agent(supervisor, "agent_1")

list_agents(supervisor)

@spec list_agents(Supervisor.supervisor()) :: [{pid(), String.t()}]

Lists all supervised agent processes.

Returns list of {pid, agent_id} tuples.

Example

agents = AgentSupervisor.list_agents(supervisor)
#=> [{#PID<0.123.0>, "agent_1"}, {#PID<0.124.0>, "agent_2"}]

start_agent(supervisor, opts)

@spec start_agent(
  Supervisor.supervisor(),
  keyword()
) :: DynamicSupervisor.on_start_child()

Starts an agent process under supervision.

Options

AgentProcess.start_link/1's options, plus :restart:

:agent (a %Normandy.Agents.BaseAgentConfig{}) - Required. The agent config the process runs.
:name (term/0) - A GenServer.name/0 for the process.
:agent_id (String.t/0) - The agent's id (default: a new UUID). In :server mode it is also the session id.
:context_pid - A Normandy.Coordination.StatefulContext process, kept in the agent's state.
:turn_engine - :inline runs BaseAgent.run/3 in a worker process, one turn at a time; :server routes turns through Turn.Session/Turn.Server (approval parking, passivation, persistence). The default value is :inline.
:store ({module, handle}) - :server mode: the SessionStore as {module, handle}. Without it the process starts and owns an in-memory store.
:registry ({module, handle}) - :server mode: the SessionRegistry as {module, handle}. Without it the process uses a scope of its own in a registry Normandy starts.
:supervisor (a pid or a supervisor name) - :server mode: the session supervisor. Without it the process starts and owns a Turn.Supervisor.
:supervisor_mod - :server mode: the module whose start_server/2 starts sessions (default Normandy.Agents.Turn.Supervisor).
:template_provider ({module, handle}) - :server mode: the AgentTemplate as {module, handle}.
:resume_policy - :server mode: the session's resume policy (default :lazy).
:template_id (String.t/0) - :server mode: the template id (default: the config's name).
:subscriber (function of arity 2) - :server mode: passed to Turn.Server.start_link/1.
:handlers (a Normandy.Agents.Turn.Driver.Handlers or nil) - :server mode: passed to Turn.Server.start_link/1.
:approval_timeout_ms (timeout/0) - :server mode: passed to Turn.Server.start_link/1.
:on_approval_timeout - :server mode: passed to Turn.Server.start_link/1.
:idle_timeout_ms (timeout/0) - :server mode: passed to Turn.Server.start_link/1.
:max_pending_runs (a positive integer or :infinity) - Runs and casts admitted and not finished (queued or in flight). One more is refused with a :queue_full Normandy.TurnError. The default value is 100.
:restart - The child's restart value. Not passed to the agent process. The default value is :transient.

Example

{:ok, pid} = AgentSupervisor.start_agent(
  supervisor,
  agent: my_agent,
  agent_id: "agent_1",
  name: :research_agent
)

start_link(opts \\ [])

@spec start_link(keyword()) :: Supervisor.on_start()

Starts the agent supervisor.

Options

:name (term/0) - A GenServer.name/0 for the supervisor.
:strategy - DynamicSupervisor supports only :one_for_one. The default value is :one_for_one.
:max_restarts (non_neg_integer/0) - Restarts allowed within :max_seconds. The default value is 3.
:max_seconds (pos_integer/0) - The window for :max_restarts, in seconds. The default value is 5.

Example

{:ok, pid} = AgentSupervisor.start_link(name: :my_supervisor)

terminate_agent(supervisor, agent_pid)

@spec terminate_agent(Supervisor.supervisor(), pid()) :: :ok | {:error, :not_found}

Terminates an agent process.

Example

:ok = AgentSupervisor.terminate_agent(supervisor, agent_pid)

terminate_all(supervisor)

@spec terminate_all(Supervisor.supervisor()) :: :ok

Terminates all supervised agents.

Example

:ok = AgentSupervisor.terminate_all(supervisor)