Delegate to Agents

​

Overview

• Independent runs. Each delegated task is a fully independent run of the target agent with the prompt you provide. The parent cannot steer a child mid-run.
• Barrier semantics (default). By default the parent’s tool call finishes only when every delegated task reaches a terminal state (completed / failed / stopped — any outcome). The parent then resumes with each child’s status + output and decides what to do next.
• Fire-and-forget (async: true). When async is on, the parent starts the children and continues immediately in the same turn — it does not wait and never receives their results. No await group is created, so the parent stays running. Use this for work whose output the parent doesn’t need back (kick off a long background job, trigger notifications, etc.). See Async / fire-and-forget.
• Fan-out. A single task entry can carry an inputs array to spawn one child per value (a {{item}} placeholder in the prompt/title is substituted per value).
• Bounded. Recursion depth, per-call count, and wait timeout are all configurable (see Configuration). (timeout_minutes is ignored when async is on — there is nothing to wait for.)
• Pausing tool (unless async). delegate_tasks is registered as a pausing tool in the orchestrator: while its child awaits are pending, the parent stays in waiting_for_input and the agent loop does not advance. An async call creates no awaits, so the orchestrator keeps the loop running instead of pausing (see Flow).

​

Per-agent delegation settings

1. Delegate out (caller) — “Automatically choose from available agents”. Backed by config.auto_delegate (nil/absent = on). When off, the agent can never spawn subtasks: agent.filterToolsByAgentConfig strips delegate_tasks from its tool list, which also drops the agent roster from the decision prompt (since canSpawnAgents keys off that list). When on, the agent decides on its own whether to delegate.
2. Receive delegations (callee) — “Allow other agents to delegate to this one”. Backed by config.delegation_enabled (nil/absent = on) plus the delegation_profile editor revealed beneath it (see Delegation profiles).

​

Per-task override (home task runner)

​

Flow

1. The worker executes the delegate_tasks step. For each (expanded) target it resolves the agent_group_id to the runnable target agent and builds a child task (tasks row with parent_task_id, parent_step_id, spawn_depth = parent+1, source = 'spawned') plus its first user message — without emitting new_message yet.
2. It creates one task_await per child in a group (source_type = child_task, correlation_key = child task id, strategy = all_required, scheduled_resume_at = now + timeout).
3. Only after the awaits are committed does it emit new_message per child, so a fast child can’t reach a terminal state before its await row exists (which would otherwise leave the parent hung).
4. The parent task is left in waiting_for_input. The chat feed renders a Delegated tasks card listing each child with a live status pill (polled every 2s).
5. When a child reaches any terminal state, TaskTerminalNotifier enqueues a child_task signal (dedup_key = child id, so repeated terminal fires are idempotent).
6. The SignalMatcher matches the signal to the parent’s pending await, completes it, and once the whole all_required group is complete emits an await_completed event.
7. The orchestrator resumes the parent: it inserts ONE consolidated task_message summarizing every child (title / agent / status / output) and a decide_next_action step, then flips the task back to running.
8. On scheduled_resume_at the AwaitTimeoutProcessor re-checks each child’s liveness. A child that is still non-terminal (running, or parked in waiting_for_input — which a user can still answer on the child’s own task page) is not timed out: its await is rescheduled one window forward so the parent stays paused. The parent therefore resumes only once every child reaches a terminal state (via the child_task signal). This guarantees a parent never completes while a delegated subtask is still pending.

​

Async / fire-and-forget

1. The worker still builds each child task and emits new_message (steps 1 + 3 above) — the children run exactly as normal.
2. It skips the await group (step 2) entirely — no task_await rows, no timeout, no resume path.
3. The tool returns a result with status: "spawned_async" (and empty group_id / strategy). The orchestrator’s isAsyncDelegate helper reads that status and treats the completion as non-pausing: it creates the next decide_next_action step and leaves the task running, so the agent loop continues in the same turn with the children already started.

​

Tool input

{
  "tasks": [
    {
      "agent_group_id": "…", // a workspace agent (not self, not another workspace)
      "prompt": "Process {{item}}", // {{item}} substituted per input when fanning out
      "title": "optional",
      "inputs": ["c1", "c2", "c3"], // optional fan-out → one child per value
    },
  ],
  "timeout_minutes": 60, // optional; capped by config; ignored when async is true
  "async": false, // optional; true = start the tasks and continue without waiting (default false)
}

• No inputs → one child per task entry.
• inputs set → one child per value; {{item}} in prompt/title is replaced (if absent, the value is appended). The per-call limit applies to the total expanded count.
• async → false (default) waits for all children and returns their combined output; true starts them and continues immediately without their results. Exposed to the LLM, and surfaced in the configured-tool modal as a toggle (“Run in the background (don’t wait for results)”, x-display-name) that an author can pin to a static value.

​

Examples

{
  "tasks": [
    {
      "agent_group_id": "9c1b…",
      "title": "Q3 competitor pricing",
      "prompt": "Research current list pricing for Acme, Globex and Initech and return a short comparison table.",
    },
  ],
  "timeout_minutes": 30,
}

{
  "tasks": [
    {
      "agent_group_id": "9c1b…",
      "title": "Research {{item}}",
      "prompt": "Research the latest financials for ticker {{item}} and return revenue, margin and a one-line outlook.",
      "inputs": ["MSFT", "GOOG", "AMZN"],
    },
  ],
}

{
  "tasks": [
    {
      "agent_group_id": "4f7e…",
      "title": "Re-index knowledge base",
      "prompt": "Re-crawl the docs site and refresh the vector index. No reply needed.",
    },
  ],
  "async": true,
}

​

Configuration

​

Runtime bounds

spawn_tasks:
  max_depth: 3 # SPAWN_TASKS_MAX_DEPTH — caps recursion (top-level=0)
  max_children_per_call: 0 # SPAWN_TASKS_MAX_CHILDREN_PER_CALL — 0 = unlimited
  default_timeout_minutes: 60 # SPAWN_TASKS_DEFAULT_TIMEOUT_MINUTES
  max_timeout_minutes: 1440 # SPAWN_TASKS_MAX_TIMEOUT_MINUTES — ceiling for per-call override

​

Delegation allowlist (optional)

• Leave all unchecked → any workspace agent (default).
• Select some → allowlist. The tool will only delegate to those agents; a task targeting any other agent is rejected at execution.

• Description hint (routing): loadConfiguredTools resolves the allowlist agent_group_ids to agent names and appends them to the tool’s description — e.g. “This delegate tool can ONLY delegate to: “Pricing Agent” (agent_group_id …). To delegate to any other agent, use the delegate_tasks tool instead.” So the model sees, before calling, which agents each configured delegate tool can reach (agent.describeDelegateAllowlist / buildAgentNameByGroup).
• Actionable rejection (recovery): if it still targets a disallowed agent, the execution error names the allowed agents and points to the open delegate_tasks tool (spawn_agent_tasks.allowedAgentNames), so it recovers immediately instead of leaving a failed step.

​

Discoverability (how the agent knows who to delegate to)

# Agents you can delegate to
You can delegate tasks to the agents below using the delegate_tasks tool. ...
- Research Agent — agent_group_id: <uuid>
    Description: Researches a stock ticker and returns financials.
    Example input: { "ticker": "MSFT" }
- Summarizer — agent_group_id: <uuid>

​

Delegation profiles

1. Delegation is on — config.delegation_enabled is unset or true (the default). Setting it to false removes the agent from every roster.
2. It has a profile description — an agent with no config.delegation_profile.description is skipped, since the decider has nothing to match on. (Delegation is allowed by default, but undescribed agents are invisible until a profile exists.)

• Generate per agent: the agent’s Settings tab has a “Delegation profile” section (AgentDelegationProfileSection) with a master Delegatable toggle (on by default), a Generate with AI button, and editable description/example saved on blur. delegation_enabled persists via the standard agent update (config.delegation_enabled).
• Backfill all: POST /api/agents/delegation-profiles/backfill (workspace-scoped; ?force=true regenerates existing ones) fills in any agents missing a profile.
• Single endpoint: POST /api/agents/:id/delegation-profile generates + saves one.
• Generation: services.AgentProfileService.GenerateDelegationProfile prompts an LLM (gemini-2.5-flash) with the agent’s name, instructions, and tools; prompt text lives in prompts/files/agent/agent_delegation_profile_{system.txt,user.tmpl}. The call sets DisableReasoning: true so thinking tokens don’t starve the small output budget (a thinking model otherwise returns truncated/empty JSON).

​

UI

• Parent task feed: a “Delegated tasks” card lists each child with a live status pill (“3 of 4 complete”); deleted children show as deleted. Backed by useChildTasks → GET /api/tasks/query?parentTaskId=…. For an async delegation (result status = spawned_async) the header reads “Started tasks” instead, since the parent isn’t waiting on them.
• Child task feed: a floating ”↳ Delegated by <Agent>” ticker links back to the parent (feed response carries a parent ref with the parent’s agent id).
• Task list: spawned children appear in the main list with a ”↳ subtask” badge (click → filter to that parent’s children). source=spawned is included in the default view. A parent row shows an “N subtasks” toggle (TaskTitleCell). Clicking it expands the delegated-subtasks list (SubtaskList) as its own full-width row directly beneath the parent — so the parent row’s cell heights and alignment never change when it opens. Each child shows its live status, the agent name it was delegated to, and a link to its task page; the list loads lazily and live-polls only while open. Expansion state lives in TasksTable (via table meta.subtaskExpansion). The count comes from subtask_count on the task-query response (a correlated COUNT(*) of non-deleted children, workspace-pinned).

​

Stopping & deleting

• Stop (chat): if the task has delegated subtasks, a dialog offers “Stop only this” vs “Stop this & N subtasks”. Cascade stops each active descendant, cancels their steps and their pending awaits (so an in-flight child signal can’t resume a just-stopped task — delegate_tasks does not fire wake-up signals during teardown). Stopping an already-terminal parent with the cascade flag still stops orphaned children.
• Delete (single row + bulk): same prompt; cascades a soft-delete to descendants (include_subtasks). Note: delete is soft-delete only — it hides children but does not halt ones still executing.

​

Edge cases & guarantees

• Self / same-group delegation is rejected (infinite-loop guard), as is any agent_group_id outside the workspace (tenant isolation / BOLA) or outside the configured allowlist.
• Recursion is capped by max_depth; a child may delegate further only until the cap.
• Duplicate resume is prevented by dedup_key = child id on the signal + the race-safe CompleteAwait CAS.
• Spawn↔await race is closed by committing all child awaits before emitting any child’s new_message.
• Parent stopped/deleted while children run: the parent’s awaits are cancelled, so a child’s terminal signal finds no pending await (no_match, harmless).
• Async (async: true): no await group is created, so the parent never blocks and the children’s terminal signals always land as unmatched (harmless). The parent gets no results back and cannot be resumed by the children — choose this only when the output isn’t needed. timeout_minutes is ignored. The recursion-depth, allowlist, self / cross-workspace, and per-call-count guards all still apply (async changes only the wait, not who can be spawned).