Teams

A team is a session tree that coordinates through a shared task board. The root agent, called the leader, posts tasks. Teammates, which are copies of the leader, join automatically, claim tasks, do the work in the shared sandbox, and mark tasks done. The leader reads the results, records a decision, and assembles the final answer. You can watch the board live and read it through the API.

You need an agent and an environment. No roster is required: every agent can run as a team of its own copies. Starting sessions needs the Developer or Admin role; the User role can read the board. See Organizations and roles. Teammates follow the same delegation, inheritance, and limit rules as any copy of the root; see Multi-agent.

When to use a team

Use a team when the work has two or more independent pieces that each take real effort, or when the result should be checked by someone other than its author. For one precise hand-off, use delegation instead. Every teammate is a full agent that runs its own model calls, so a team of four costs roughly four times as much per minute as one agent. It pays off when the pieces are substantial and would otherwise run one after another.

Good and poor fits

Good fits:

Competing approaches. Try three ways to speed up a query, each with its own benchmark, then pick the best one.
Separate components. Build an API client, a CLI, and their docs, each with its own tests.
Separate questions. Research three vendors, each from its own sources.
Independent review. Have a second teammate check each result before the decision.

Poor fits:

Steps that must happen in order, where each step needs the last one’s output.
Pieces that take a few minutes each. The coordination costs more than it saves.
One precise hand-off. Use delegation instead.

Choose a team mode

The team mode decides whether a session forms a team.

Mode	Console label	Behavior
`auto`	When the work calls for it	The default. The agent works alone and forms a team only if it decides the work warrants one, by posting its first task.
`on`	Always	A team from the first turn. The leader posts the work rather than doing it itself.
`off`	Never	No board. The agent can still delegate to children and wait for them.

Set the agent’s default under Multiagent on the agent’s Configuration tab, or with multiagent.team.mode. Override it for one session with team.mode when you start the session:

Console
cURL

In the sidebar, click Sessions, then click Launch session.
Choose the Agent and Environment.
Under Task, write the brief in Opening message.
Under Team, set Work as a team to Always.
Click Launch session.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Idempotency-Key: caching-comparison-2026-09-25' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
    "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
    "message": "Compare in-process LRU, Redis, and CDN caching for the catalog API and recommend one.",
    "team": {"mode": "on"}
  }'

The API answers 202 Accepted with the new session id. Next, watch the board.

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status_path": "/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38"
}

Write a good team brief

The brief is your opening message. The leader turns it into tasks, and each teammate sees only its own task body, so the brief has to make the split obvious.

Name the independent pieces. “Compare three approaches: an in-process LRU, Redis, and CDN edge caching.”
Say where each piece writes. “Put each prototype in /workspace/proto/<approach>/ and its findings in /workspace/research/<approach>.md.” Separate paths keep teammates from overwriting each other.
Give the shared rules once. The test command, the data set, and the format every piece must follow.
Ask for review when it matters. “Have a different teammate check each result’s numbers.”
Say how results will be judged and what the final deliverable is. “Pick one approach by p95 latency under the load in /workspace/bench/run.sh. Save the recommendation as caching-recommendation.md with the numbers for all three.”

The research team tutorial shows a complete example.

Read the board

The board shows every task with its status, owner, notes, and result summary, plus notices, recommendations, and the decision. It’s the authoritative state; refresh from it rather than rebuilding the board from events.

Console
cURL

In the sidebar, click Sessions, then open the root session.
Open the Work tab. The Board lists tasks by status with their owners.
Click a task to see its body, result summary, output paths, and notes.
In the transcript, choose the Team filter to see board changes in order.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38/board' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

Any session id in the tree works; the read resolves to the root. Read tasks[].status and owner_session_id for who holds what, tasks[].outcome for finished work, and the decision post for the leader’s call.

Example board

A board midway through a round looks like this:

{
  "as_of": "2026-09-25T17:41:08Z",
  "members": [
    {"session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38", "name": "leader", "leader": true, "state": "running"},
    {"session_id": "4a9f2c61-0e3b-4d87-b5a2-7c1e6f9d3b40", "name": "self-1", "leader": false, "state": "idle"},
    {"session_id": "e3c7a915-6b2d-4f08-9a41-2d5b8c0f7e66", "name": "self-2", "leader": false, "state": "running"}
  ],
  "tasks": [
    {
      "task_id": "7d2e4b19-3a5c-4e81-b6f0-9c1a2d7e5b43",
      "seq": 1,
      "kind": "explore",
      "title": "Prototype and benchmark an in-process LRU cache",
      "body": "Build an LRU cache in /workspace/proto/lru/. Run /workspace/bench/run.sh and write p50 and p95 latency to /workspace/research/lru.md.",
      "status": "done",
      "owner_session_id": "4a9f2c61-0e3b-4d87-b5a2-7c1e6f9d3b40",
      "claim_generation": 1,
      "artifacts": ["/workspace/research/lru.md"],
      "outcome": {
        "summary": "p95 fell from 182 ms to 41 ms. RAM use grew by 310 MB per instance.",
        "confidence": "high",
        "artifacts": ["/workspace/research/lru.md"]
      },
      "created_by": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
      "created_at": "2026-09-25T17:08:02Z",
      "updated_at": "2026-09-25T17:33:47Z"
    },
    {
      "task_id": "a18f6c02-9e4b-4d3a-8c75-1b0e2f9d6a38",
      "seq": 4,
      "kind": "review",
      "title": "Check the LRU benchmark numbers",
      "body": "Rerun /workspace/bench/run.sh against /workspace/proto/lru/ and confirm the p95 in /workspace/research/lru.md. Leave your findings as a note on T1.",
      "status": "claimed",
      "owner_session_id": "e3c7a915-6b2d-4f08-9a41-2d5b8c0f7e66",
      "claim_generation": 1,
      "blocked_on": ["7d2e4b19-3a5c-4e81-b6f0-9c1a2d7e5b43"],
      "created_by": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
      "created_at": "2026-09-25T17:08:02Z",
      "updated_at": "2026-09-25T17:35:10Z"
    }
  ],
  "posts": [
    {
      "post_id": "c5b1e8a4-2f73-4d96-a0e7-8d3c6b1f4a29",
      "kind": "notice",
      "text": "The load test reads /workspace/bench/catalog-sample.json. Don't edit it.",
      "created_by": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
      "created_at": "2026-09-25T17:09:15Z"
    }
  ]
}

What each board field tells you

Field	What to read
`tasks[].status` and `owner_session_id`	Who holds what. A task claimed for a long time with no update may be stuck.
`tasks[].outcome`	The owner’s summary, confidence (`low`, `medium`, or `high`), and output paths, once the task is done.
`tasks[].notes`	Reviewers’ findings, blockers, and hand-over details, in order.
`posts[]` with `kind` `recommendation`	A teammate’s pick and rationale.
`posts[]` with `kind` `decision`	The leader’s call: `task_ids` names the winners, `text` explains why.
`members[]`	Everyone on the board. The leader is named `leader`. Teammates are named after the leader’s copies, such as `self-1`.

What success means

A team session is finished when the leader has integrated the results and ended its work, the same as any session. Along the way, a round is over when no task is open or claimed, and an exploratory round ends with a decision post. Deliverables that teammates write count as the root session’s deliverables. See Deliverables and artifacts.

How a team works

The leader posts tasks, teammates claim and finish them, and the leader records one decision. As tasks become claimable, copies of the leader join to take them, up to the team size: the roster’s max_concurrent_threads, which defaults to 8 and can be at most 25. Teammates are copies of the leader, so they have the leader’s model, prompt, skills, MCP servers, and exactly the same vault and credential grants. See What a child inherits.

Tasks, statuses, and team rules

Tasks. Each task has a label such as T1, a kind, a self-contained body, and the output paths it will write. Kinds are task (work with a named output), explore (one approach to an open question), and review (check another task’s output and leave findings in a note). A task can wait on others with blocked_on.
Statuses. open (posted and not held; claimable once every task in its blocked_on is done), claimed (in progress), blocked (the owner can’t proceed and says why in a note), done (finished, with a result summary), and dropped (withdrawn).
One owner per task. A claim belongs to one teammate. A teammate that joined from the board can change the shared sandbox only while it holds a claimed task. A teammate can’t claim the review of a task it did.
Shared state. Notices are facts every member must know, such as a moved path; the latest 10 stay in front of every member. Teammates can message each other directly, up to 20 messages per assignment, and put what they agree on the board.
One decision stands. Teammates post recommendations. Only the leader records a decision, which names the winning tasks and the reason. If the leader records another, the newest one stands.

What can go wrong

The most common problems:

The board is empty under auto. The agent decided to work alone. Use on when you want a team regardless.
Two teammates overwrote one file. The brief didn’t give each piece its own path. Name a distinct output path for every piece.
The cost is higher than expected. Every teammate runs its own model calls. Use a team only for substantial parallel pieces, and check the session’s cost in Usage and cost.

Every team error

Symptom or code	Cause	Fix
`404 not_found` from the board	The session runs with team mode `off`.	Start the session with `team.mode` `auto` or `on`.
The board is empty under `auto`	The agent decided to work alone.	Use `on` when you want a team regardless.
Two teammates overwrote one file	The brief didn’t give each piece its own path.	Name a distinct output path for every piece.
Teammates report conflicting formats	The shared rules weren’t in the brief.	State the format, test command, and data once in the brief.
A task stays `claimed` with no progress	The owner is stuck on a long step or waiting on something.	Read its notes in the Work tab. The leader can message the owner or post an alternative.
Fewer teammates than tasks	The team is at its size, `max_concurrent_threads`.	Expected. Teammates take the rest as they finish. Raise the limit if the pieces are all substantial.
The cost is higher than expected	Every teammate runs its own model calls.	Use a team only for substantial parallel pieces, and check the session’s cost. See Usage and cost.

Limits

Limit	Value
Team size	The roster’s `max_concurrent_threads`: default 8, maximum 25
Notices kept in front of every member	The latest 10
Direct messages from a teammate to other teammates	20 per assignment
Tasks on one board	200
Notices and recommendations on one board	200

See Limits for every product limit.

Next steps

Research team tutorial

Run a research team session end to end.

Multi-agent

Delegation, rosters, inheritance, and limits.

Usage and cost

See what a team session cost.

Deliverables and artifacts

How team outputs are kept.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

When to use a team

Choose a team mode

Write a good team brief

Read the board

What success means

How a team works

What can go wrong

Limits

Next steps

Research team tutorial

Multi-agent

Usage and cost

Deliverables and artifacts

​When to use a team

​Choose a team mode

​Write a good team brief

​Read the board

​What success means

​How a team works

​What can go wrong

​Limits

​Next steps

Research team tutorial

Multi-agent

Usage and cost

Deliverables and artifacts

When to use a team

Choose a team mode

Write a good team brief

Read the board

What success means

How a team works

What can go wrong

Limits

Next steps