> ## 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. The TypeScript samples assume the `rl` client from [Client setup](/managed-agents/api#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](/managed-agents/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](/managed-agents/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](/managed-agents/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. ## How a team works ```mermaid theme={"theme":"css-variables"} flowchart TD start["You start the session with a brief"] post["Leader posts tasks to the board"] join["Teammates join, one per claimable task"] claim["Each teammate claims one task"] work["Teammate works in the shared sandbox and writes to the task's paths"] done["Teammate marks the task done with a summary and confidence"] review["Another teammate claims the review task and leaves a verdict as a note"] recommend["Teammates recommend which tasks should win"] decide["Leader records the decision"] finish["Leader integrates the results and finishes"] start --> post --> join --> claim --> work --> done done --> review --> recommend --> decide --> finish done -->|"more tasks open"| claim ``` 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](/managed-agents/multi-agent#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. 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**. ```typescript theme={"theme":"css-variables"} 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' }, }, }); ``` ```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. ```json theme={"theme":"css-variables"} { "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. 1. **Name the independent pieces.** "Evaluate 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." Pair the brief with an [outcome](/managed-agents/outcomes) so the final deliverable is graded before the session completes. The [research team tutorial](/managed-agents/use-cases/research-team) 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. 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, outcome, output paths, and notes. 4. In the transcript, choose the **Team** filter to see board changes in order. ```typescript theme={"theme":"css-variables"} const board = await rl.managedAgents.getSessionBoard({ session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38', }); ``` ```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. 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. 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](/managed-agents/outcomes). Deliverables that teammates write count as the root session's deliverables. See [Deliverables and artifacts](/managed-agents/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](/managed-agents/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](/managed-agents/limits) for every product limit. ## Next steps Run a graded team session end to end. Delegation, rosters, inheritance, and limits. Grade the team's final deliverable. How team outputs are kept.