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. The TypeScript samples assume the rl client from Client setup.

Before you begin

To start sessions, you need the Developer or Admin role in the organization. The User role can read the board. See Organizations and roles.
You need an agent and an environment. No roster is required: every agent can run as a team of its own copies.
Read Multi-agent for delegation, inheritance, and limits. Teammates follow the same rules as any copy of the root.

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. 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.

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.

How a team works

What to expect:

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 a verdict). 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 an outcome), and dropped (withdrawn).
Teammates join on their own. As tasks become claimable, copies of the leader join to take them, up to the team size. The team size is the roster’s max_concurrent_threads, which defaults to 8 and can be at most 25.
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.

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.

Choose a team mode

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
TypeScript
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.

const started = await rl.managedAgents.startSession({
  'Idempotency-Key': 'caching-comparison-2026-09-25',
  body: {
    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' },
  },
});

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.

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status_path": "/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. “Evaluate 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.”

Pair the brief with an outcome so the final deliverable is graded before the session completes. The research team tutorial shows a complete example.

Read the board

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

Console
TypeScript
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, outcome, output paths, and notes.
In the transcript, choose the Team filter to see board changes in order.

const board = await rl.managedAgents.getSessionBoard({
  session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
});

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. 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. Memory 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 verdict 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"
    }
  ]
}

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’ verdicts, 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.
An exploratory round ends with a decision post.
With an outcome, the session completes only when the grader is satisfied: the outcome’s terminal_result is satisfied and the session’s stop_reason is outcome_satisfied. See Outcomes.

Deliverables that teammates write count as the root session’s deliverables. See Deliverables and artifacts.

What can go wrong

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 cost per session. 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 graded team session end to end.

Multi-agent

Delegation, rosters, inheritance, and limits.

Outcomes

Grade the team’s final deliverable.

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

Before you begin

When to use a team

How a team works

Choose a team mode

Write a good team brief

Read the board

What success means

What can go wrong

Limits

Next steps

Research team tutorial

Multi-agent

Outcomes

Deliverables and artifacts

​Before you begin

​When to use a team

​How a team works

​Choose a team mode

​Write a good team brief

​Read the board

​What success means

​What can go wrong

​Limits

​Next steps

Research team tutorial

Multi-agent

Outcomes

Deliverables and artifacts

Before you begin

When to use a team

How a team works

Choose a team mode

Write a good team brief

Read the board

What success means

What can go wrong

Limits

Next steps