---
title: "Orchestrate Team of Agents"
source: https://docs.autohand.ai/guides/teams-and-swarms/
---

# Orchestrate Team of Agents

Split complex work across focused Autohand sub-agents, coordinate long-running teams with explicit dependencies, gather cited evidence with /deep-research, and improve measurable systems with /autoresearch.

**Start with the smallest useful pattern.** Delegate one bounded question before creating a team. Use parallel delegation only for independent work. Use a persistent team when tasks need dependencies, progress, or follow-up messages and any idle teammate is capable of claiming the next available task.

## Choose an execution pattern

The number of agents is not the important decision. Choose based on coupling: whether the outputs can be produced independently, whether later work depends on earlier results, and whether the work needs a measurable loop.

| Need | Use | Runtime behavior | Best first instruction |
|---|---|---|---|
| One specialist result | delegate_task | One synchronous sub-agent returns one result to the lead | “Delegate the repository map to the researcher; do not edit files.” |
| Two to five independent results | delegate_parallel | Up to five sub-agents run concurrently and return labeled outputs | “Review security, accessibility, tests, and performance in parallel; consolidate findings by severity.” |
| Shared tasks and dependencies | Agent Team | The first idle teammate claims the next unblocked task from a lead-managed graph | “Create a team of compatible implementers with disjoint files and dependency-gated tasks.” |
| Current external evidence | /deep-research | Scopes subquestions, reads sources, cross-checks claims, and saves a cited report | /deep-research Compare durable workflow engines for our TypeScript service... |
| Repeated measurable improvement | /autoresearch | Changes one variable, benchmarks it, keeps or reverts, logs the run, and repeats | /autoresearch reduce unit test runtime --metric total_ms ... |

## How the pieces fit together

The interactive Autohand session remains the lead. It owns the user goal, sees the registered agent definitions, chooses a delegation mechanism, and verifies the combined result. A sub-agent receives a narrower system prompt and only the tools allowed by its definition.

1.  **Discover.** Run `/agents definitions`, create a definition with `/agents new`, or ask Autohand to find an exact specialist in the catalog.
2.  **Partition.** Give every worker a distinct question, file boundary, output format, and completion test.
3.  **Execute.** Delegate once, launch an independent swarm, or build a task graph for a persistent team.
4.  **Integrate.** The lead resolves contradictory findings, checks cross-file assumptions, and runs repository-level validation.
5.  **Close.** Record the result, shut down persistent teammates, and leave reviewable artifacts rather than only chat summaries.

`/deep-research` and `/autoresearch` reuse the same runtime. Deep research can discover agent and parallel-research tools for broad investigations. Autoresearch can delegate idea generation, measurement analysis, and finalization while the lead experiment loop retains ownership of the benchmark and keep/revert decision.

## Run a first parallel delegation

Start Autohand in the repository you want to inspect, list the definitions available to the session, and give the lead an explicit integration contract.

``` bash
cd /path/to/project
autohand

/agents definitions

Review the current branch with independent reviewer, security-auditor,
accessibility-tester, and performance-engineer sub-agents. Use parallel
delegation, keep every worker read-only, and return one deduplicated report.
For each finding include severity, file and line, evidence, impact, and the
smallest safe fix. Do not edit files.
```

If a named catalog role is not installed, ask the lead to search the default catalog, show the exact match and requested tool access, and wait for installation approval before delegating.

## Define the operating contract

Parallelism only helps when the lead can merge the outputs. Put these details in the initial instruction instead of relying on workers to infer them:

-   **Scope:** exact directories, services, commits, or external questions each worker owns.
-   **Mutation policy:** read-only, patch allowed, command execution allowed, or isolated worktree required.
-   **Dependencies:** which result must exist before another task can start.
-   **Output schema:** findings, patch, report path, benchmark metric, or task status expected from each worker.
-   **Evidence:** file and line references for code claims; URLs and dates for external claims; command output for verification.
-   **Stop condition:** tests passing, no high-severity findings, confidence threshold reached, or experiment budget exhausted.

**Avoid shared write ownership.** Team children share the current workspace; the task queue does not create isolated worktrees. Do not send two write-capable agents into the same files concurrently. Separate them by directory or phase, or create isolated worktrees outside the team runtime before integration.

## Use this guide family

[Sub-agents and delegation](/docs/guides/teams-and-swarms/sub-agents.html) - Definitions, discovery paths, built-ins, permissions, and delegation limits

[Sub-agent Catalog](/docs/guides/sub-agent-catalog.html) - Find, inspect, approve, and install existing specialist roles

[Agent teams and tasks](/docs/guides/teams-and-swarms/agent-teams.html) - Persistent teammates, task dependencies, status, messages, and shutdown

[/deep-research](/docs/guides/teams-and-swarms/deep-research.html) - Scope current questions, cross-check sources, and save cited reports

[/autoresearch](/docs/guides/teams-and-swarms/autoresearch.html) - Configure metrics, safeguards, hooks, sub-agent phases, and experiment artifacts

[Agent orchestration playbooks](/docs/guides/teams-and-swarms/use-cases.html) - Copyable playbooks for engineering, operations, research, and optimization

## Selection rules that scale

-   Use a built-in agent when its tool boundary already fits the task. Built-ins cover codebase research, review, tests, documentation, dead-code cleanup, and TODO resolution.
-   Use a catalog agent for domain expertise such as PostgreSQL, Kubernetes, accessibility, compliance, or language-specific implementation.
-   Use a definition from a configured external directory when the role depends on repository conventions, internal commands, or a narrow ownership boundary that should travel with the project.
-   Use direct `delegate_task` or `delegate_parallel` calls when an exact named specialist must receive exact work. Use a team queue only when each idle teammate can safely handle each task that may become available.
-   Prefer one lead and three to five distinct workers over a large group of overlapping generalists.
-   Make the lead independently validate the integrated state. A worker saying “done” is an input to verification, not the completion criterion.