---
title: "Agent Teams and Task Graphs"
source: https://docs.autohand.ai/guides/teams-and-swarms/agent-teams
---

# Agent Teams and Task Graphs

Use a persistent lead-and-teammate runtime when work needs distinct owners, dependency ordering, progress updates, reassignment, or direct follow-up—not only a batch of parallel answers.

## When a team is the right abstraction

A team adds coordination state. The lead manages registered teammates and a shared task list; each teammate runs as a separate headless process with its own agent definition, model context, and tool boundary.

| Situation | Use | Reason |
|---|---|---|
| Four independent reviews that return once | delegate_parallel | No persistent status or dependencies are needed |
| Several compatible workers processing a dependency graph | Agent Team | Later tasks remain blocked until prerequisites complete |
| Exact specialist must receive exact work | delegate_task or delegate_parallel | Team tasks do not select an agent; the first idle teammate claims the next available task |
| One specialist question | delegate_task | A persistent teammate would add coordination overhead |

## Lead-managed architecture

-   **Lead process:** owns the user goal, creates the team, launches teammates, creates tasks, routes messages, and verifies the integrated result.
-   **Teammate process:** starts in teammate mode using a registered agent definition and receives assignments over JSON-RPC on standard I/O.
-   **Task manager:** stores pending, in-progress, and completed tasks with optional `blocked_by` task IDs.
-   **Auto-assignment:** the first idle teammate receives the first pending task whose dependencies are complete. `create_task` has no owner or agent selector.
-   **Message routing:** teammates do not form an uncontrolled peer network; the lead routes task messages and direct follow-ups.
-   **Recovery:** if a teammate exits, its in-progress work can return to pending so another worker can take it.

## Know the current runtime boundary

-   **One active team:** creating a differently named team shuts down the old team before creating the replacement.
-   **In-memory coordination:** team membership and tasks live in the lead process. Shut down the team before ending the session and do not treat it as a durable queue.
-   **Headless children:** every teammate is a separate Autohand process connected to the lead over JSON-RPC on standard input and output.
-   **Shared workspace:** teammate processes run against the same workspace path. The runtime does not create one worktree per teammate.
-   **Persistent definitions:** teammate children reload user, configured external, and bundled definitions. Prefer file-based definitions for team members; inline `--agents` definitions belong only to the lead session.
-   **Tool approval:** teammate mode auto-confirms its local tool prompts. The agent definition's narrow tool allowlist is the main safety boundary.

**Start from a clean branch or dedicated worktree.** Use read-only definitions whenever possible. For write-capable teammates, grant only the required tools and ensure every available task is safe for every idle teammate that could claim it.

## Create a team from an outcome

`/team create <name>` creates an empty team. A natural-language instruction can ask the lead to create or reuse a team, profile the project, list available definitions, launch teammates, and create dependency-aware tasks. It does not create a project-derived plan automatically.

``` text
First use direct, read-only delegation to map the authorization gaps and decide
the exact regression cases. Then create a team named auth-regression-tests with
two teammates that both use the registered tester definition.

Outcome: add the agreed authorization regression tests without changing
production code or public request and response contracts.

Create independent tasks for these disjoint files:
- tests/auth/projects.test.ts
- tests/auth/organizations.test.ts

Create a final verification task blocked by both file tasks. Either teammate may
claim either file task, so put the complete case list, mutation boundary, command,
and expected evidence in each description. The lead reviews the combined diff and
runs the focused auth suite before reporting completion.
```

If a catalog role is missing, ask the lead to show the exact catalog result and wait for installation approval before adding that teammate.

## Understand the coordination tools

The lead calls these model-facing tools. They are documented so you can specify the workflow precisely; you normally do not type them directly.

| Tool | Contract | Operational note |
|---|---|---|
| create_team | Create or reuse a named team, profile the project, and list available definitions | It does not add teammates or tasks; call those tools next |
| add_teammate | Launch a named teammate from a registered agent_name; optional model override | The agent definition controls tools and behavior |
| create_task | Create a subject and detailed description with optional blocked_by IDs | There is no agent selector; the first idle teammate claims the first available task |
| task_get / task_list | Inspect one task or filter the queue by status or owner | Use this before declaring the team stuck |
| task_update | Change task details, dependencies, or status | Update the graph when evidence changes the plan |
| task_stop | Stop active or queued work and return it to pending | Use before reassigning overlapping or misguided work |
| task_output | Store the latest progress note or result against a task | Preserve evidence, commands, and artifact paths |
| team_status | Return teammates, states, and task progress | Status is coordination data, not validation proof |
| send_team_message | Send a correction or question from the lead to one teammate | Do not silently change another worker's ownership |

## Design a task graph

Dependencies should encode information flow, not only chronology. A task is available when it is pending and every ID in `blocked_by` is complete.

``` text
task-1  Add project authorization regression cases       [any tester teammate]
task-2  Add organization authorization regression cases  [any tester teammate]
task-3  Run focused suite and summarize failures          [any tester teammate]
         blocked_by: task-1, task-2
task-4  Review combined diff and repository checks        [lead]
         blocked_by: task-3
```

Keep tasks large enough to produce a coherent artifact and small enough to have one owner. “Fix authentication” is too broad; “add regression tests for cross-tenant project reads in `tests/auth/projects.test.ts`” is assignable and verifiable. If only one named specialist can do a task, use direct delegation or stage a separate homogeneous team for that phase.

## Prevent write collisions

-   Give every write-capable teammate an exclusive directory or explicit file list.
-   Make design, research, and review agents read-only where possible.
-   Use dependency edges when two roles must touch the same surface at different phases.
-   Create isolated worktrees outside the team runtime when parallel branches are intentional, then run a separate Autohand session in each worktree.
-   Stop and re-plan a task as soon as its scope crosses another owner's boundary.

**Shared working directory means shared risk.** A team task queue prevents duplicate assignment, but it does not isolate files, route tasks by specialist, or make concurrent edits merge cleanly. File ownership and tool access are part of every task contract.

## Monitor and control the team

``` bash
# Summarize team, teammates, and task progress
/team status

# Show task IDs, owners, dependencies, and state
/tasks

# Correct or extend one teammate's assignment
/message tester-a Do not touch production code; add the failing command and output to the task result.

# Gracefully stop all teammate processes after integration
/team shutdown
```

A teammate that reports completion should include changed files, commands run, results, open risks, and any assumptions the lead must verify. If a task fails or the teammate exits, inspect its latest output before returning the task to pending or assigning it elsewhere.

## Use phase gates for risky work

For migrations, security changes, or cross-service work, use several small teams or shut down and re-form the team between phases:

1.  **Discovery gate:** repository map, current contracts, risks, and proposed ownership are reviewed by the lead.
2.  **Test gate:** failures reproduce the problem and baseline validation is recorded.
3.  **Implementation gate:** one owner per surface, focused checks green, and no unauthorized contract drift.
4.  **Integration gate:** the lead reviews the combined diff and runs repository-level build, lint, type, and test commands.
5.  **Release gate:** documentation, migration notes, rollout, rollback, and monitoring are complete.

## Define team completion

A team is complete only when the integrated workspace satisfies the user-facing acceptance criteria. Require:

-   all required tasks completed and no dependency left unresolved;
-   every worker's output inspected, with contradictory assumptions resolved;
-   the combined diff reviewed for cross-task regressions;
-   focused and repository-level validation commands recorded with results;
-   temporary teammates shut down and their artifacts either retained intentionally or cleaned up safely.

See the broader [Agent Teams reference](/docs/working-with-autohand-code/agent-teams.html) for hooks and additional operational examples.