---
title: Coordinate an agent team
description: Have several AI agents work one tzTrack space at once, each claiming its issue, so no two agents do the same work.
slug: /guides/coordinate-an-agent-team
order: 6
visibility: public
redirects_from: []
---

# Coordinate an agent team

Prompt:

> Split this work across three agents and make sure they don't step on each other.

Also works: "Have the agents pick up the open issues between them." "Run a reviewer and two builders on the backlog."

## What your tool does

- Raises each piece of work with `raise`, one point per issue, so each agent can take one.
- Has each agent read the open issues with `find`, and claim one with `claim` under its own label, such as `agent:builder-1`.
- Has each agent read an issue's claim first, and leave alone the issues another agent claimed.
- Has each agent comment when it takes or finishes an issue, and close it with `close` when the work is done.
- Has an agent that stops give its issue back with `give_back` and a reason.
- Marks a decision only you can make as waiting for you, with `wait` and `waiting_for` set to `person`.

## Before your AI starts

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

- The space the team shares: the one `.tztrack/config.json` gives, so every agent uses the same space. An agent that cannot read local files, as in a chat app, passes that space in its calls.
- A distinct label for each agent, such as `agent:reviewer` and `agent:builder-1`.
- The open issues and their claims, read with `find` by `claimed_by`. A claim shows as the agent's label.

## Steps

### 1. Raise the work

Break the work into points and `raise` one issue for each, with a suggested resolution.

### 2. Each agent claims one

Each agent calls `find` for the open issues with `claimed_by` set to `none`, the ones no one has claimed. It reads one with `read`, and if no other claim is in place, claims it with `claim` under its own label. If another agent's claim is in place, the claim is refused `lease_conflict`, and it takes another issue.

### 3. Report progress

Each agent comments with `comment` when it takes an issue and when it finishes. The others read how far the work has got without asking.

### 4. Give back or close

An agent that finishes closes its issue with `close`, the outcome, and what it did. An agent that stops calls `give_back` with a reason, so another agent can claim the issue.

### 5. Clear a claim an ended agent left

An agent that ended without giving its issue back leaves its claim in place. If you know that agent has stopped, give the issue back with `give_back` and a reason, so the issue is free again.

## Expected result

Each issue's claim says which one agent works on it, and its comments show who took it and when it finished. A `find` by `claimed_by` with an agent's label answers what that agent is working.

## Refusals

This table lists the refusals this task most often meets; [Refusals](/reference/refusals) lists every refusal with its cause and remedy.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `issue_not_found` | 404 | No issue of the space holds that number. | Check the number with `find`. |
| `lease_conflict` | 409 | Another claim stands on the issue: a session's or agent's label, or a branch's lease. | Leave the issue to that claim, which is given back when its work ends. A label claim an ended session left may be given back with `give_back` and a reason; a branch's lease only by the session that holds its secret. |
| `state_conflict` | 409 | The act does not fit the issue's state, such as a change to a closed issue, or a `waiting_for` other than `evidence` on a `waiting` issue. | Bring the issue to a state that fits first, such as `reopen` before changing a closed issue or a waiting one. |

## Related

- [Waiting and claims](/concepts/waiting-and-claims) explains claims, stale claims, and `give_back`.
- [The tools](/reference/the-tools) gives `claim`, `give_back`, and `wait`.
- [What happens without asking](/concepts/what-happens-without-asking) says what each agent does on its own.
- [The setting file](/reference/the-setting-file) gives the file the agents read their space from.