Skip to content

dispatch_agents

Batch-register sub-agents from the current filtered frontier.

Read-only: No

Description

Computes the live frontier (same path as next_task), filters out items that already have a running agent or an active frontier lease held by a different task, and registers up to count running agent tasks with auto-computed subgraph scopes. Returns the list of dispatched task IDs and the items skipped (with reasons).

This is the generic batch-dispatch tool. For campaign-aware dispatch (strategy-specific scope, campaign progression), use dispatch_campaign_agents. For subnet-specific dispatch with CIDR scoping, use dispatch_subnet_agents.

Parameters

Parameter Type Required Default Description
count number No 4 Number of agents to dispatch (1–20)
strategy "top_priority" \| "by_type" No "top_priority" How to select frontier items
hops number No 2 Subgraph scope depth around each frontier seed (1–5)
skill string No — Optional skill override applied to all dispatched agents
agent_id_prefix string No "sub" Prefix for synthesized agent_ids

Strategies:

  • top_priority — picks the top-N items by frontier score
  • by_type — picks one item per frontier item type (incomplete_node, untested_edge, inferred_edge, …) to keep the dispatch diverse

Returns

{
  "dispatched": [
    {
      "task_id": "task-abc-123",
      "agent_id": "sub-1",
      "frontier_item_id": "fi-host-10-10-10-5",
      "scope_node_count": 5
    }
  ],
  "skipped": [
    {
      "frontier_item_id": "fi-host-10-10-10-6",
      "reason": "already has running agent"
    },
    {
      "frontier_item_id": "fi-host-10-10-10-7",
      "reason": "frontier_lease_conflict",
      "existing_task_id": "task-other-456"
    }
  ]
}
Field Type Description
dispatched[] array Successfully registered agent tasks
skipped[] array Items intentionally skipped, with reason

Lease Conflict Behavior (P1.4)

Each registration takes a TTL lease on the frontier item (default 600s). When two dispatch_agents calls compete for the same item, the second one gets lease_conflict and the item lands in skipped. The lease is released when the agent's status transitions to completed / failed / interrupted, or when its TTL elapses without a heartbeat (the watchdog handles this).

For long-running agents, ensure they call agent_heartbeat periodically to prevent the lease from expiring.

Usage Notes

  • dispatch_agents is idempotent in spirit: running it twice in succession will skip items already claimed by the first run.
  • For finer control over which frontier items are dispatched, fetch with next_task and call register_agent per item.
  • The dispatched agents' subgraph is captured at registration time — if the frontier moves between dispatch and the agent's get_agent_context call, the agent still sees its original scope.

See Also