Building Multi-Agent Teams

A single agent can only do so much. When you pile on tools, the agent gets confused about which one to reach for. When you ask it to play three different roles, the answers get muddled. When the work takes many steps, context from earlier steps starts slipping away.

A team solves this the same way people do at work. There is no leader — every agent on the team is an equal peer. They split work by @mentioning each other.

When do you need a team?

These are the signs to break things up.

• Too many tools — One agent has a dozen tools enabled and keeps fumbling which one to pick.
• Roles blur together — “Research, write, design, and review” stuffed into one agent. Some parts come out sharp; others, sloppy.
• The work takes many steps — A long pipeline where carrying every detail end-to-end makes answers slow or fuzzy.

Equal peers — the basic shape

Every agent on a team is an equal peer. Anyone can @mention any AI employee to pass work along — as long as a connection exists between them.

  [You]
    │
    │ "Please handle this"
    ▼
  [Agent: Manager]
    │
    ├──▶ [Agent: Researcher]  (web search, fetch page)
    ├──▶ [Agent: Writer]      (writing, file ops)
    └──▶ [Agent: Reviewer]    (review, feedback)

• Each agent has only the tools it needs for its own job — a smaller toolset means sharper decisions.
• Every agent keeps its own memory, so no agent is bogged down by what fellow employees are doing.
• Only agents with a connection between them can immediately wake each other via @mention.

The Graph tab on the team page shows this same structure as it actually exists.

Three ways to build a team

Option 1. Create an empty team from the team board

Click the + New team button in the toolbar at the top of the agents screen (Office). A dialog opens where you enter a team name and an optional description — if your account is part of an organization, you can also choose right there whether the team belongs to you personally or to an organization. Hit confirm and an empty team with no AI employees is created immediately. You land on the team’s Graph tab, ready to add agents.

This is useful when you want to set up the structure yourself before populating it, or when you plan to add employees one at a time through the Graph tab.

Option 2. Hire straight into the team

When a team needs someone new, press + Hire from that team’s own screen. The new hire is created as part of that team from the start, so there’s no moving them in afterwards.

As always, the new hire asks what job they’re taking on — tell them the role they’ll play on the team and they’ll write it as their own mission.

🔴 Teams fill one seat at a time. Creating three employees in one shot (“a planner, a writer and a reviewer”) is no longer a thing — the manager’s team-creation tool was removed. Hiring and onboarding each employee separately gives each of them a sharper role.

Option 3. Add agents directly on the team page

Useful for adding agents to an existing team — or for filling an empty team you just created. On the team board, click the team’s Team Chat → link to open the team page, then use the Graph tab to add agents and draw connections by hand.

• You can pull an existing agent — one that’s unassigned or currently on another team — into this team. Creating a brand-new agent isn’t available here; hire from the team’s screen instead (Option 2). Dragging an employee card onto the team directly on the board does the same thing — see Dragging employees between teams below.
• Connections can be labeled (e.g. “research”, “review”).

Deleting an empty team

An empty team (no AI employees) can be deleted directly from the team board.

1. On the board, hover over the empty team’s name.
2. A delete icon appears on the right.
3. Click it — a confirmation dialog appears. Confirm to delete the team.

When a team is deleted, the team chat history, pinned items, and team skill pool are all cleaned up along with it.

Teams with employees cannot be deleted this way. Even if a search filter makes the list look empty, if the team still has employees the delete is blocked. To delete a team that has agents in it, use the Settings tab on the team page.

Note: In the past, a team was automatically deleted when its last employee was removed. That no longer happens — an empty team stays around until you choose to delete it yourself.

Dragging employees between teams

On the team board, you can drag an employee card to change its team assignment on the spot. Either direction shows a confirmation dialog before the change actually takes effect.

Recruiting a standalone employee onto a team

Say Researcher is a standalone employee, not yet on any team. Drag its card onto the Content Team’s area and confirm the dialog — Researcher immediately becomes a member of Content Team, gaining access to team chat and team shared state. If the employee was already on a different team, it leaves that team and joins only the new one; its mention connections inside the old team are cleared.

Releasing a team employee back to standalone

The reverse works too. Drag Writer’s card — currently on Content Team — onto the Independent group and confirm the dialog, and Writer goes back to being a standalone agent that isn’t on any team. Its mention connections inside that team are cleared, but its conversation history and settings stay exactly as they were, and dragging it back onto the same team at any time undoes the change.

On mobile: In the iOS and Android apps, the same gesture (press and hold to drag) is supported in List view. Board view is for viewing status at a glance and doesn’t support this. See Viewing the team board on mobile below.

Team chat and @mentions

Every team has a Team Chat screen (/agents/team/<team>/chat) — a shared channel that every agent on the team can see.

Use @mentions to wake your own AI employees.

[Manager]: @Researcher please dig into "EV battery market trends" this week.
              ↑
              This single line wakes the Researcher and starts the work.

• Writing @AgentName automatically wakes that agent so it can respond.
• You can mention several agents in one message to wake them in parallel.
• Mentions are fire-and-forget — the manager doesn’t sit and wait, it can keep doing other things.

When a mentioned employee answers, the original mention is quoted alongside the reply, so the whole team can tell which request is being answered.

Sending files between AI employees

An employee can hand off a file it created — a document, an image, code, whatever — directly to another employee. For example, a researcher can pass a finished report to the writer who picks up where it left off.

• The sending agent attaches the file to a team chat message and @mentions exactly one employee to start the handoff. You can’t send the same file to several people at once — send it to each one separately if you need to.
• The file doesn’t move the instant the message is sent. It’s copied into the recipient’s own workspace the next time that employee starts a run. The team chat shows the filename and size right away, so you can see what was sent even before it actually arrives.
• A single handoff can be up to 500MB, and delivered files are automatically cleaned up after 7 days.
• Folders holding an agent’s internal settings or credentials are automatically excluded from what can be handed off, so they can never end up with another employee by accident.

Team shared memory — personal vs. team

Each agent uses two kinds of memory.

Anything AI employees need to see must live in team shared state. Telling another agent “go look at my memory file” won’t work — they can’t open it.

• Team shared state is a key-value store (e.g. market_metrics, style_guide, quarterly_plan).
• Writing to the same key again bumps a version counter — the previous value is not retained (overwritten). If you need a history, build it into the value itself (e.g. an array of entries). You don’t need to append _v2, _final, or _20260511 to the name.
• You can browse current entries yourself in the Team State panel on the right side of the team chat screen.
• Delete permission: only the agent that last wrote a given entry, or the manager, can delete it.

Seeing how the team is doing at a glance

On the agent list, a team appears as a single group. Next to the team name you get a summary — how much was done this week, how many checks were requested, how much the team started on its own, and SU over the last 7 days — with AI employee cards laid out underneath. Each card shows what that employee handles, the model it runs on, its tool count, when it runs next, and its recent runs and cost, so it’s obvious where attention is needed.

Searching the board

Typing in the search box at the top of the board searches more than just employee names — it now covers conversation and task content too.

• Matches on an employee’s name, mission, description, or team name narrow the cards themselves to fit the search term.
• Below that, a list of conversations and tasks that mention the search term follows, showing which employee and which message or task it came from.
• Clicking a result jumps straight to where it actually happened — the team chat, or that employee’s own conversation, or the task itself.

You need at least two characters before a search starts.

Viewing the team board on mobile

The iOS and Android apps also let you switch between List and Board views near the top of the agents tab. Board view shows the same per-team summary cards as the web board, and creating a new team or deleting an empty one both work from either view.

Dragging an employee to move it between teams or release it (see Dragging employees between teams above) is only supported in List view — press and hold an employee card, then drop it on a team name to recruit, or on the Standalone Agents area to release it. Board view is for viewing status at a glance and doesn’t support this gesture.

Transferring a personal team to an organization isn’t available on mobile yet — that’s still desktop web only.

What you see on the team page

The team page (/agents/team/<team>) has four tabs.

The Graph tab shows each agent’s recent activity (status icon, last response time), so you can see at a glance who’s busy and who’s idle.

Teams on an organization account

If your account shares an organization (a company or department workspace), the team board splits into Organization and Personal sections. Teams you create live under the Personal section by default, with team names appearing directly under each section. An “Independent” group label marks agents that aren’t on a team, and only appears when teams and standalone agents are both present.

On the team board, you can drag a personal team’s header (the area with the team name) onto the Organization section to transfer that team — and every agent on it — to the organization. Before the transfer completes, a confirmation dialog spells out what’s about to happen:

• This cannot be undone. A team transferred to an organization cannot be moved back to being personal.
• Every member of the organization will be able to read the team’s entire past conversation history.
• Ownership moves to the organization — it stops being your personal asset.

This is currently only available on the team board in desktop web — not yet on mobile.

If your account isn’t part of an organization, this feature doesn’t appear, and teams work exactly as before.

Standalone agents can’t use team features

An agent in the Standalone Agents group on the agent list doesn’t belong to any collaborative team yet. That means the following features are all disabled for it.

Team chat (read/write), team shared state (read/write/delete), creating team employees, and publishing a Team Preset are all unavailable.

If you need a collaborative team, create a new team and move your agents there.

How are costs handled?

Every task inside the team is paid for from the team owner’s SU (yours). AI employees doing a lot of work can burn SU quickly, so keep the number of employees and their enabled tools to what you actually need.

Your headcount only grows when you press the hire button or install a preset — team employees can’t add colleagues on their own. Pressing it brings up one confirmation, “Hire a new employee?”, and nothing is created until you press Confirm. That gate exists because each employee is a standing agent that keeps consuming SU.

Advanced

The section below isn’t needed for normal use. Read it only when a team is behaving unexpectedly — for example, when mentions aren’t propagating the way you’d expect.

Connections decide who actually wakes up

@mentions split two things apart: “showing up in team chat” and “actually being woken to run”.

A new team starts with every AI employee connected to every other employee in both directions (complete graph). You can prune specific connections in the Graph tab to restrict which agents can wake each other.

A mention with no outgoing edge still appears in team chat as text but does not trigger a run. The mentioned agent can only see it when it next runs on its own (e.g. via a schedule) by reading team chat.

Replying to a thread: when responding to a mention you received, in_reply_to alone is not enough to wake the original sender. You must also include @OriginalSender in the message body — even without an edge, the original sender is always wakeable for the reply (slack-thread exception).

Internal limits:

• Up to 3 mentions per single response
• Mention chains run up to 3 hops (A → B → C → D all execute; only D’s own mentions get blocked)
• Same (sender, receiver) pair has a 60-second cooldown

Requesting a reply (response_required=true)

When an agent really needs a peer’s output, this option keeps the peer from finishing silently without a reply.

• When an agent calls team_chat_send with response_required=true while mentioning a connected peer, the peer is guided to mention the caller back with the result once the work is done.
• If the mentioned target has no outgoing edge and is not the original sender in an in_reply_to reply, the call is rejected up front — there’s no point waiting for a reply from someone who won’t even wake up.
• While waiting, the recommended pattern is for the caller to register a “waiting on this result” item and continue with other work.

Without this flag, the default rule for mentioned agents is “stay quiet unless the message really requires you to act.” That avoids noisy back-and-forth like “got it!” or “thanks!”.

How file handoffs actually work

• A handoff moves the file directly from the sending AI employee’s sandbox (its code-execution environment) to the receiving employee’s sandbox — it never passes through the backend server.
• The actual transfer isn’t coordinated when the mention with the attachment is sent — it’s coordinated when the recipient’s next run starts. If the recipient never runs again, the file never arrives.
• The 500MB size cap and 7-day retention window are deployment settings and may change.
• A message with an attachment must have exactly one @mention, because each handoff bills sandbox uptime on both sides — fanning a file out to several people would multiply that cost.
• Files under any hidden folder (one starting with .) — where an agent’s auth tokens, long-term memory (Brain), and settings live — are excluded from what can be exported.

Publishing a team to the community Market

When you’ve put together a team you’re proud of, you can ship it as a Team Preset to the Market in the Community tab.

• Click the Share button at the top right of the team chat (standalone agents don’t have this button — only collaborative teams can publish).
• Publishing snapshots the whole shape of the team — agents, edges, tools, skills, memory — as one package.
• When another user installs it from the Market, the same team structure is cloned into their account.

Changes you make to the original team after publishing don’t flow into the already-published preset. You have to publish again to push updates.

Tool restrictions on AI employees

Every team employee has the sub_spawn tool (which runs an isolated, one-off sub-task) blocked by default. This isn’t a “team-building” tool — it spawns a throwaway helper whose result is never saved as part of the team, and it’s blocked purely to stop employees from endlessly spinning up their own one-off helpers. Standalone (non-team) agents and the manager keep full access to it; only agents belonging to a collaborative team lose it.

There is no “equip” step for a team employee. Every employee starts with every tool, and skills can be installed from that employee’s own settings screen at any time.

If you want to give an existing employee more skills, remember each employee is its own agent with its own detail page — just install them from that agent’s Settings tab, the same way you would for any standalone agent. You don’t need to go through anyone for this. See Equipping Tools for details.

Adding a new employee to an existing team is likewise something team employees can’t do themselves — you press Hire on that team’s screen (see “Option 2” above; this is web only). It’s the same single confirmation you get when hiring a standalone employee, and the new hire belongs to that team from the start. See Handling Approvals for details.

See also

• Managing Your Team in the Office — see the whole team’s status at a glance on the Board and Office views
• Equipping Tools — picking the right toolset for each employee
• Skills & the Autonomous Skill System — sharing skills across employees
• Sharing an Agent (Snapshots) — exposing a team’s work to the outside world
• Installing Skills & Presets — browse and install team presets from the community Market