# AI agent team: a manager, roles and handoffs

URL: https://agentvera.dev/en/blog/ai-agent-team/ · Published: 2026-10-18

Build an AI agent team with a manager, clear roles and reporting lines: when a team beats one agent or a parallel run, and how to set one up step by step.

**In short:**

- An agent team has four parts: a manager, roles, reporting lines and handoffs; it can hold up to 24 members, but 3 to 5 agents is the practical size.
- Saving a team starts nothing; work begins when you give a task to the team, which goes to the manager by default, and agents message each other across different CLIs.
- A parallel team is different: it splits one job into up to 8 parts, each in its own worktree, and merges them into an integration branch.

One coding agent is a great pair programmer. Once the job has several kinds of work in it (planning, writing code, reviewing it, testing it), a single agent starts juggling. It loses track of the plan while it fixes a test, or it reviews its own code and finds nothing wrong. An AI agent team splits that load the way a human team does: one agent leads, the others own a role, and everyone knows who to hand work to.

In this post I cover what a multi-agent team actually is, when it is worth the extra setup compared with one agent or a parallel run, and how to build one in AgentVera’s team view.

## What an AI agent team is

An AI agent team is several coding agents working toward one goal with a structure around them. The structure is what separates a team from a few terminals that happen to be open at the same time. It has four parts:

- **A manager:** one agent receives the request, splits it into pieces, hands the pieces out and checks what comes back.
- **Roles:** each member has a job, such as researcher, developer, reviewer or tester, plus instructions that say what it should and should not touch.
- **Reporting lines:** every member reports to someone. If you do not set it, it reports to the manager.
- **Handoffs:** a member can also have a fixed next stop for its finished work, for example the developer hands to the reviewer and the reviewer hands to the tester.

The agents talk to each other directly. A tester that finds a bug does not wait for you to copy the failure into the developer’s terminal; it sends the message itself.

## When a team beats one agent

A team costs more tokens and more attention than a single agent, so it should earn its place. This table is how I decide:

| Situation | Best fit | Why |
| --- | --- | --- |
| A small fix in one or two files | One agent | Splitting adds overhead and nothing to split |
| A feature with planning, code, review and tests | Agent team | Each stage has a different goal and a fresh pair of eyes helps |
| One big job with clearly separate parts | Parallel team | Parts run in their own worktrees and merge into one branch |
| Ongoing work over hours or days | Agent team | The team stays open and keeps its roles between tasks |
| Comparing two approaches to one problem | Two agents side by side | You want independent answers, not coordination |

The short version: reach for a team when the work has **different kinds of steps** that benefit from separate roles, and when you want the agents to keep coordinating as the work changes. If you only need raw throughput on independent pieces, a parallel run is simpler. I wrote about that side in [Parallel coding agents](/en/blog/parallel-coding-agents/) and [Running multiple Claude Code agents](/en/blog/run-multiple-claude-code-agents/).

### Agent team vs parallel team

Both appear in AgentVera, and they solve different problems:

- **The team view** arranges agents that are already open into a lasting team. They keep their roles, talk to each other and share a task list and a board.
- **A [parallel team](/en/features/parallel-team/)** is started by an agent for one job. It splits the job into up to 8 parts, runs each part in its own git worktree, merges the finished parts into an integration branch and runs a final check. It ends there, and you decide whether to open a pull request.

They also combine well: the manager of a team can start a parallel team when one of its tasks is big enough to split.

## Designing the team

Before you open any window, sketch the team on paper. Three questions cover most of it.

### 1. Who leads?

The manager should be the agent you trust most with planning. It reads the request, breaks it down and decides who does what. Give it instructions about how you want work checked, for example “do not mark a task done until the tester has run the tests”.

### 2. Which roles does the work really need?

Start small. A developer, a reviewer and a tester under a manager cover most feature work. Add a researcher when the work needs reading before coding, or a documentation role when the change touches public APIs. Every extra agent is another context to fill and another set of tokens to spend.

### 3. Where does the work flow?

Draw two kinds of lines:

1. **Reports to:** who answers to whom. This decides who the agent asks when it is stuck.
2. **Hands its work to:** the next stop for finished work. A typical chain is developer → reviewer → tester.

Keep the chain short. A long chain means a small change waits on many turns before anyone tells you it is done.

## Building it in AgentVera’s team view

The [team view](/en/features/team-view/) turns that sketch into a working team. You open it from the team icon on a group or from the top of the sidebar.

### Step 1: place the agents

The window shows **Team structure** next to a pool called **Agents in the workspace**. Drag agents from the pool into the structure, or use **Open a new agent** to start one for a role you do not have yet. The first agent you mark as **Manager** leads the team. A team has one manager and up to 24 members, and every member must be an agent of the group’s project. Terminal sessions are left out.

If you would rather not start from scratch, **Ready-made teams** gives you a full kit:

- **Software team:** a tech lead with a planner, developer, reviewer and tester.
- **Research team:** a research lead with a researcher and a report writer.
- **Social media team:** a social media manager with a trend researcher, copywriter, visual designer and ads specialist. It drafts and asks you before anything is published or any money is spent.

A kit opens the new agents it needs for you.

### Step 2: give each agent a role

Select an agent and set its **Role** and **Instructions**. **Ready-made roles** fill in a name and instructions for you: researcher, planner, developer, reviewer, tester, DevOps, designer, documentation and security. Several agents can share a role, which is handy when two developers split the front end and the back end.

### Step 3: draw the lines

Each member has **Reports to** and **Hands its work to**. You can set them from the fields or by dragging one agent onto another and choosing “Report to…”, “Hand its work to…” or “Swap places with…”. **Arrange automatically** tidies the layout. A member with no reporting line reports to the manager, and if you accidentally create a loop, it is pointed back to the manager.

### Step 4: give the team its tools

Under **Team’s MCP servers** you pick servers every member gets. Each role can add its own on top, for example Playwright for the tester or a design tool for the designer. An agent can opt out in its own settings. If a suggested server is not installed yet, you get a warning and can add it from the catalog. Agents whose tools changed restart once their current turn is over, so nothing is cut off mid-task. I explain MCP servers in more detail in [What is an MCP server](/en/blog/what-is-mcp-server/).

### Step 5: save and give the team work

**Save and open the team** puts the agents in the group, so they can message each other and share the task list and board. Saving does not start anything. Work starts when you use **Give to the team**: the request goes to the manager by default, or to any agent you pick. Each agent is briefed on its role, and the briefing is repeated only when the team changes. If agent messaging was off, it is turned on.

## Watching the team work

The **Team** tab shows the structure live. Working agents glow, messages travel as light along the lines and a speech bubble appears over the agent that is talking. Alongside it:

- **Team status** shows each agent’s current step: editing, reading, running a command, searching, planning or messaging.
- **Activity** is the feed of messages, work and agent events, with filters for All, Messages, Work and Agents.
- **Tasks** is the shared list the agents add to, claim and finish.
- **Waiting for you** collects permission requests, which you can approve or refuse there.

When you need to steer, **Status report** asks the manager for a short summary of what each agent is doing, what is done and where the team is stuck. When you write to one agent, **Interrupt and redirect** stops what it is doing and passes your message on right away, while **Queue** passes it on when its current work is done. **Interrupt all** interrupts every working agent after a confirmation.

### How the agents talk

Under the hood, [agent messaging](/en/features/agent-messaging/) gives each agent tools to list the others, send a message (and optionally wait for the reply), reply and work with the shared task list. A busy agent receives a message when its turn ends, so nobody is interrupted mid-edit. Messages are marked as coming from another agent, and each sender has a rate limit so two agents cannot loop forever. It works across CLIs: Claude Code, Codex, Gemini CLI and the others use the same tools.

## Common mistakes

- **Too many agents on day one.** Five agents on a small change spend most of their turns reading each other’s messages. Start with three and add roles when a gap shows up.
- **Vague roles.** “Help with the code” is not a role. Say what the agent owns, which folders it may change and what “done” means for it.
- **No reviewer or tester.** A team where the developer checks its own work is just one agent with extra steps.
- **Overlapping file ownership.** Two developers in the same files will step on each other. Split by folder, or let the manager start a [parallel team](/en/features/parallel-team/) so each part gets its own worktree. See [Git worktrees for parallel agents](/en/blog/git-worktree-parallel-agents/).
- **Giving work to every agent at once.** Let the manager split it. That is the whole point of having one.
- **Ignoring the approvals.** An agent waiting on a permission request blocks everyone downstream. Keep an eye on the attention bar.

## Checklist

- [ ] One manager with instructions on how to check work
- [ ] Each role has a clear owner, scope and definition of done
- [ ] Reporting lines and handoffs drawn, chain kept short
- [ ] A reviewer or tester somewhere in the chain
- [ ] Team and role MCP servers chosen and installed
- [ ] The first request written for the manager, not for each agent

## Wrapping up

An AI agent team is worth it when the work has distinct steps and you want them handled by agents that keep coordinating without you relaying messages. The structure is simple: a manager, a few well-described roles, and short lines for reporting and handoffs. Start small, watch the first run in the Team tab, and tighten the roles where you see agents waiting or repeating each other. If you prefer to think in fixed stages instead, [AI agent workflow pipelines](/en/blog/ai-agent-workflow-pipeline/) covers that approach.

AgentVera lets you build the team from the agents you already have open, whatever CLI they run. You can [start for free](/en/) and check the [plans](/en/pricing/) when you need more.

## Frequently asked questions

**What is an AI agent team?** It is a group of coding agents that work on one goal with a clear structure: one manager that splits and checks the work, members with roles such as developer or tester, and defined lines for who reports to whom and who hands work to whom.

**Can an AI agent team mix Claude Code, Codex and other CLIs?** Yes. In AgentVera any agent open in the project can join the team, whatever CLI it runs. Agents message each other through the same tools, so Claude Code can ask Codex a question and get the answer back.

**How many agents can be in one team?** An AgentVera team holds up to 24 members with one manager. In practice a small team of three to five agents is easier to follow and costs fewer tokens.

**How is an agent team different from a parallel team?** An agent team is a lasting group of open agents that keep talking to each other. A parallel team splits one job into parts, runs each part in its own git worktree and ends as one merged branch you can open a pull request from.

**Does the team start working as soon as I save it?** No. Saving only sets up the structure and the group. Nothing starts until you give the team work, which goes to the manager by default or to any agent you pick.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/