Normandy.Coordination.AgentSupervisor (normandy v0.2.0)

View Source

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 strategies
  • 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.

find_agent(supervisor, agent_id)

Finds an agent by its agent_id.

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

find_agent(supervisor, agent_id)

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

Finds an agent by its agent_id.

Returns {:ok, pid} if found, {:error, :not_found} otherwise.

Example

{:ok, pid} = AgentSupervisor.find_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

  • :agent - BaseAgent struct (required)
  • :agent_id - Unique identifier (default: UUID)
  • :name - Register agent process with name (optional)
  • :context_pid - StatefulContext to use (optional)
  • :restart - Restart strategy: :permanent, :temporary, :transient (default: :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 - Register supervisor with a name (optional)
  • :strategy - Supervision strategy (default: :one_for_one)
  • :max_restarts - Max restarts allowed (default: 3)
  • :max_seconds - Time window for max_restarts (default: 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)