> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Teams > Run copies of an agent on a shared task board so independent pieces of work happen in parallel, get reviewed, and end in one decision. 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](/recursion/organizations-and-roles). Teammates follow the same delegation, inheritance, and limit rules as any copy of the root; see [Multi-agent](/recursion/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](/recursion/multi-agent#how-delegation-works) 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 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](/recursion/multi-agent#how-delegation-works) 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: 1. In the sidebar, click **Sessions**, then click **Launch session**. 2. Choose the **Agent** and **Environment**. 3. Under **Task**, write the brief in **Opening message**. 4. Under **Team**, set **Work as a team** to **Always**. 5. Click **Launch session**. ```bash theme={"theme":"css-variables"} 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. ```json theme={"theme":"css-variables"} { "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. 1. **Name the independent pieces.** "Compare three approaches: an in-process LRU, Redis, and CDN edge caching." 2. **Say where each piece writes.** "Put each prototype in `/workspace/proto//` and its findings in `/workspace/research/.md`." Separate paths keep teammates from overwriting each other. 3. **Give the shared rules once.** The test command, the data set, and the format every piece must follow. 4. **Ask for review when it matters.** "Have a different teammate check each result's numbers." 5. **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](/recursion/use-cases/research-team) 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. 1. In the sidebar, click **Sessions**, then open the root session. 2. Open the **Work** tab. The **Board** lists tasks by status with their owners. 3. Click a task to see its body, result summary, output paths, and notes. 4. In the transcript, choose the **Team** filter to see board changes in order. ```bash theme={"theme":"css-variables"} 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. A board midway through a round looks like this: ```json theme={"theme":"css-variables"} { "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" } ] } ``` | 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](/recursion/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](/recursion/multi-agent#what-a-child-inherits). * **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](/recursion/usage-and-cost). | 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](/recursion/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](/recursion/limits) for every product limit. ## Next steps Run a research team session end to end. Delegation, rosters, inheritance, and limits. See what a team session cost. How team outputs are kept.