Sagents.AgentsDynamicSupervisor (Sagents v0.8.0-rc.2)

Copy Markdown

Dynamic supervisor for managing AgentSupervisor instances.

Each AgentSupervisor manages a single agent (conversation) and its supporting infrastructure. This supervisor allows agents to be started and stopped dynamically as conversations are created and terminated.

Scope

Unlike FileSystemSupervisor which scopes by user/project, this supervisor manages individual agent instances identified by agent_id (typically "conversation-{id}").

Usage

# Start the supervisor (typically in your Application)
{:ok, pid} = AgentsDynamicSupervisor.start_link(name: MyApp.AgentsDynamicSupervisor)

# Start an agent supervisor
{:ok, agent_sup_pid} = AgentsDynamicSupervisor.start_agent(
  agent_id: "conversation-123",
  agent: agent,
  initial_state: state,
  pubsub: {Phoenix.PubSub, :my_app_pubsub}
)

# Stop an agent supervisor
:ok = AgentsDynamicSupervisor.stop_agent("conversation-123")

# List all running agents
agent_ids = AgentsDynamicSupervisor.list_agents()

Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

count_agents(supervisor \\ __MODULE__)

Count running agents.

list_agents(supervisor \\ __MODULE__)

List all running agent IDs.

start_agent(opts)

Start a new agent supervisor as a child of this dynamic supervisor.

start_agent_sync(opts)

Start a new agent supervisor and wait for it to be ready.

start_link(opts \\ [])

Start the AgentsDynamicSupervisor.

stop_agent(agent_id, opts \\ [])

Stop an agent supervisor.

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

count_agents(supervisor \\ __MODULE__)

@spec count_agents(atom() | pid()) :: non_neg_integer()

Count running agents.

Parameters

  • supervisor - Supervisor reference (optional, defaults to __MODULE__)

Examples

count = AgentsDynamicSupervisor.count_agents()
# => 5

list_agents(supervisor \\ __MODULE__)

@spec list_agents(atom() | pid()) :: [String.t()]

List all running agent IDs.

Parameters

  • supervisor - Supervisor reference (optional, defaults to __MODULE__)

Returns

List of agent_id strings

Examples

agent_ids = AgentsDynamicSupervisor.list_agents()
# => ["conversation-1", "conversation-2"]

start_agent(opts)

@spec start_agent(keyword()) :: DynamicSupervisor.on_start_child()

Start a new agent supervisor as a child of this dynamic supervisor.

Parameters

  • opts - Keyword list of options passed to AgentSupervisor.start_link/1
    • :agent_id - Agent identifier (required, will be extracted to set supervisor name)
    • :agent - The Agent struct (required)
    • :initial_state - Initial State for AgentServer (optional)
    • :pubsub - PubSub configuration as {module(), atom()} tuple (optional, used only for Phoenix.Presence wiring)
    • :inactivity_timeout - Timeout in milliseconds (optional)
    • :shutdown_delay - Shutdown delay in milliseconds (optional)
    • :presence_tracking - Presence tracking configuration (optional)
    • :conversation_id - Conversation identifier (optional)
    • :agent_persistence - Module implementing Sagents.AgentPersistence (optional)
    • :display_message_persistence - Module implementing Sagents.DisplayMessagePersistence (optional)
    • :supervisor - Supervisor reference (optional, defaults to __MODULE__)

Returns

  • {:ok, pid} - Agent supervisor started successfully
  • {:ok, pid, info} - Agent supervisor already running (idempotent)
  • {:error, reason} - Failed to start

Examples

{:ok, agent_sup_pid} = AgentsDynamicSupervisor.start_agent(
  agent_id: "conversation-123",
  agent: agent,
  initial_state: state,
  pubsub: {Phoenix.PubSub, :my_app_pubsub}
)

start_agent_sync(opts)

@spec start_agent_sync(keyword()) ::
  {:ok, pid()} | {:ok, pid(), :already_started} | {:error, term()}

Start a new agent supervisor and wait for it to be ready.

This is a synchronous version that waits for the AgentServer child to be fully registered before returning. See AgentSupervisor.start_link_sync/1 for details on why this is needed.

Parameters

Same as start_agent/1, plus:

  • :startup_timeout - Maximum time to wait for AgentServer to be ready (default: 5000ms)

Examples

{:ok, agent_sup_pid} = AgentsDynamicSupervisor.start_agent_sync(
  agent_id: "conversation-123",
  agent: agent,
  initial_state: state,
  pubsub: {Phoenix.PubSub, :my_app_pubsub},
  startup_timeout: 10_000
)

start_link(opts \\ [])

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

Start the AgentsDynamicSupervisor.

Options

  • :name - Registered name for the supervisor (optional, defaults to __MODULE__)

Examples

{:ok, pid} = start_link(name: MyApp.AgentsDynamicSupervisor)

stop_agent(agent_id, opts \\ [])

@spec stop_agent(
  String.t(),
  keyword()
) :: :ok | {:error, :not_found}

Stop an agent supervisor.

Parameters

  • agent_id - Agent identifier
  • opts - Options (optional)
    • :supervisor - Supervisor reference (defaults to __MODULE__)
    • :reason - Shutdown reason (defaults to :normal)
    • :timeout - Shutdown timeout in milliseconds (defaults to :infinity)

Examples

:ok = AgentsDynamicSupervisor.stop_agent("conversation-123")
:ok = AgentsDynamicSupervisor.stop_agent("conversation-123", reason: :shutdown, timeout: 5000)