Normandy.Coordination.HierarchicalCoordinator (normandy v0.2.0)

Coordinates hierarchical multi-agent systems with manager-worker patterns.

The Hierarchical Coordinator implements a manager-worker pattern where a manager agent delegates tasks to worker agents and aggregates results.

Example

coordinator = HierarchicalCoordinator.new(
  manager: manager_agent,
  workers: [worker1, worker2, worker3],
  delegation_strategy: :round_robin
)

{:ok, result} = HierarchicalCoordinator.execute(
  coordinator,
  "Analyze this dataset",
  shared_context: context
)

Summary

Types

delegation_strategy()

t()

Functions

add_worker(coordinator, worker_id, agent)

Adds a worker to the coordinator.

execute(coordinator, input, opts \\ [])

Executes the hierarchical coordination.

execute_with_tasks(coordinator, tasks, opts \\ [])

Executes with explicit task delegation.

new(opts)

Creates a new hierarchical coordinator.

remove_worker(coordinator, worker_id)

Removes a worker from the coordinator.

Types

delegation_strategy()

@type delegation_strategy() :: :round_robin | :broadcast | :conditional

t()

@type t() :: %Normandy.Coordination.HierarchicalCoordinator{
  delegation_strategy: delegation_strategy(),
  manager: struct(),
  shared_context: Normandy.Coordination.SharedContext.t(),
  workers: [%{id: String.t(), agent: struct()}]
}

Functions

add_worker(coordinator, worker_id, agent)

@spec add_worker(t(), String.t(), struct()) :: t()

Adds a worker to the coordinator.

Example

coordinator = HierarchicalCoordinator.add_worker(
  coordinator,
  "new_worker",
  new_agent
)

execute(coordinator, input, opts \\ [])

@spec execute(t(), term(), keyword()) :: {:error, term()}

Executes the hierarchical coordination.

The manager agent analyzes the input and decides how to delegate work to worker agents.

Options

:shared_context - Override coordinator's shared context
:max_concurrency - Max concurrent workers (default: 5)
:manager_prompt - Custom prompt for manager

Example

{:ok, result} = HierarchicalCoordinator.execute(
  coordinator,
  input,
  manager_prompt: "Break down this task for worker agents"
)

execute_with_tasks(coordinator, tasks, opts \\ [])

@spec execute_with_tasks(t(), [%{worker_id: String.t(), task: term()}], keyword()) ::
  {:error, term()}

Executes with explicit task delegation.

Bypasses manager's delegation planning and directly assigns tasks to workers.

Example

tasks = [
  %{worker_id: "worker_1", task: "Research topic A"},
  %{worker_id: "worker_2", task: "Research topic B"}
]

{:ok, result} = HierarchicalCoordinator.execute_with_tasks(
  coordinator,
  tasks
)

new(opts)

@spec new(keyword()) :: t()

Creates a new hierarchical coordinator.

Options

:manager - Manager agent (required)
:workers - List of worker agents (required)
:delegation_strategy - How to delegate: :round_robin, :broadcast, :conditional
:shared_context - SharedContext to use (default: new context)

Example

coordinator = HierarchicalCoordinator.new(
  manager: manager_agent,
  workers: [
    %{id: "worker_1", agent: worker1},
    %{id: "worker_2", agent: worker2}
  ],
  delegation_strategy: :broadcast
)

remove_worker(coordinator, worker_id)

@spec remove_worker(t(), String.t()) :: t()

Removes a worker from the coordinator.

Example

coordinator = HierarchicalCoordinator.remove_worker(coordinator, "worker_1")