Run a research team

In this tutorial, a team compares three vector databases for a semantic search service. The leader splits the work into one research task per database plus a review of each, teammates work in parallel, and the leader writes one recommendation as a named deliverable.

You need the Developer or Admin role in the organization; see Organizations and roles. Read Teams for how the board works. A team runs several agents at once, so it costs more than a single agent. This tutorial caps the team at four teammates.

Step 1: Create the research agent

The agent needs web search, which is on by default, and a team size. The team size is max_concurrent_threads. No roster entries are needed, because teammates are copies of this agent.

Console
cURL

In the sidebar, click Agents, then click Create agent and choose Blank.
Enter a Name, choose a model, and paste the system value from the cURL tab into System prompt. Click Create agent.
On the Configuration tab, under Multiagent, set Work as a team to Always.
Under Tools, confirm Web search is on.
Click Save new version.

The console doesn’t set the team size, so the team uses the default of 8. Use the API to cap it.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Research lead",
    "model": "<model-id>",
    "system": "You research technical choices for an engineering team.\nCite a source URL for every factual claim, and prefer official documentation and independent benchmarks.\nKeep working notes in /workspace/research. Save final reports as deliverables.",
    "multiagent": {
      "type": "coordinator",
      "agents": [],
      "team": {"mode": "on"},
      "limits": {"max_concurrent_threads": 4}
    }
  }'

{
  "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
  "latest_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
  "name": "Research lead",
  "web_search_enabled": true,
  "multiagent": {
    "type": "coordinator",
    "agents": [],
    "team": {"mode": "on"},
    "limits": {"max_concurrent_threads": 4}
  }
}

Step 2: Create an environment

Web search and web fetch run outside the sandbox, so they work even when the environment blocks internet access. The team only needs a sandbox for its notes and the deliverable, so the default closed environment is enough.

Console
cURL

In the sidebar, click Environments, then click Create environment.
Enter a Name, such as research, and leave Internet access at No access.
Click Create environment.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/environments' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "research", "provider": "runs"}'

{
  "organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d",
  "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
  "name": "research",
  "scope": "organization",
  "provider": "runs",
  "computer_use": false,
  "created_at": "2026-09-25T16:50:31Z",
  "updated_at": "2026-09-25T16:50:31Z"
}

Step 3: Start the team session

The message is the brief the leader splits into tasks. It also carries the context every agent needs and names the deliverable, so the leader knows what to save. A good brief names the independent pieces, where each one writes, the review you want, how the result is judged, and the deliverable. See Write a good team brief.

Console
cURL

In the sidebar, click Sessions, then click Launch session.
Choose the Research lead agent and the research environment.
In Opening message, paste the message value from the cURL tab.
Under Team, confirm Work as a team is 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: vector-db-review-2026-09-25' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
    "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
    "message": "Recommend one vector database for our semantic search service: Qdrant, Weaviate, or Milvus. Research each one in its own task from official docs and at least one independent benchmark, writing notes to /workspace/research/<name>.md. Have a different teammate check each set of notes. Save the recommendation as vector-db-recommendation.md, and end with its comparison table and recommendation. Context: we run on Kubernetes, index about 40 million 768-dimension embeddings, filter every query by tenant, and have two engineers for operations.",
    "team": {"mode": "on"}
  }'

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

Step 4: Watch the board

The leader posts the round, and teammates join to claim it. You’ll typically see three research tasks and three reviews that wait on them.

Console
cURL

In the sidebar, click Sessions, then open the session.
Open the Work tab. The Board shows each task, its status, and its owner.
Click a task to read its body, its result, and the reviewer’s notes.

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

Midway through, the board shows tasks like these:

T1 explore done Research Qdrant for 40M tenant-filtered embeddings
T2 explore claimed Research Weaviate for 40M tenant-filtered embeddings
T3 explore done Research Milvus for 40M tenant-filtered embeddings
T4 review done Check the Qdrant notes
T5 review open Check the Weaviate notes
T6 review claimed Check the Milvus notes

When every task is done, the board holds the teammates’ recommendations and then the leader’s decision:

{
  "post_id": "c5b1e8a4-2f73-4d96-a0e7-8d3c6b1f4a29",
  "kind": "decision",
  "task_ids": ["7d2e4b19-3a5c-4e81-b6f0-9c1a2d7e5b43"],
  "text": "Qdrant: payload-indexed tenant filtering without per-tenant collections, a maintained Helm chart, and the lowest operational effort for two engineers. The reviewer confirmed the RAM estimate in T1.",
  "created_by": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "created_at": "2026-09-25T17:26:04Z"
}

Step 5: Wait for the leader to finish

After the decision, the leader writes vector-db-recommendation.md and ends its turn. The deliverable is kept with the root session, and the session goes idle.

Console
cURL

Stay on the session page. The transcript shows the leader’s final message when it ends its turn.
Open the Files tab to see vector-db-recommendation.md under Outputs.

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

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status": "completed",
  "execution_state": "idle",
  "stop_reason": "end_turn"
}

What success means

The root session’s execution_state is idle and its stop_reason is end_turn.
vector-db-recommendation.md is kept as a deliverable of the root session.
The board has a decision post, and no task is open or claimed.

end_turn means the leader finished, not that the recommendation is right. Read it before you act on it, and send a follow-up message if something is missing.

Step 6: Read the recommendation

The brief asks the leader to end with the comparison table and recommendation, so the final message carries the result. Any files the team saved as deliverables are on the session’s Files tab; see Download session deliverables.

In the console: the leader’s last message in the transcript holds the table and the recommendation.
Through the API: page the root timeline with listSessionEvents and read the last message event whose role is assistant.
In a later session: start a session that references this one. It can read vector-db-recommendation.md and, for example, turn it into a design doc or open a pull request with it.

The whole team’s cost is one figure: read costUsd on the root session, and record it once costState is final. See Usage and cost.

What can go wrong

Symptom	Cause	Fix
The board read returns `404 not_found`	The session started with team mode `off`.	Start with `team.mode` `on`.
The leader researches everything itself	The brief didn’t name separate pieces.	Name each option and its output path in the brief.
Two teammates wrote the same notes file	The brief didn’t give each piece its own path.	Give each piece a distinct path, as with `/workspace/research/<name>.md`.
No sources in the notes	Web search is off for the agent.	Turn on Web search in the agent’s Tools, save a new version, and start a new session.
The recommendation has claims without sources	The brief didn’t ask for citations strongly enough.	Send a follow-up message asking for a source URL on every row.
`vector-db-recommendation.md` isn’t on the Files tab	The report was saved outside the deliverables folder.	Keep “Save the recommendation as `vector-db-recommendation.md`” in the brief, or ask for it in a follow-up message. See Deliverables and artifacts.
The session costs more than expected	Each teammate runs its own model calls.	Lower `max_concurrent_threads`, or split fewer pieces.

Limits

Team size is max_concurrent_threads: default 8, maximum 25. This tutorial uses 4.
A deliverable can be at most 64 MiB. See Deliverables and artifacts.
See Limits for every product limit.

Next steps

Teams

Team modes, the board, and writing briefs.

Multi-agent

Delegation, rosters, and the session tree.

Deliverables and artifacts

What gets kept, and how to get results out.

Referenced sessions

Let a later session read this one’s deliverables.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Run a research team

Step 1: Create the research agent

Step 2: Create an environment

Step 3: Start the team session

Step 4: Watch the board

Step 5: Wait for the leader to finish

What success means

Step 6: Read the recommendation

What can go wrong

Limits

Next steps

Teams

Multi-agent

Deliverables and artifacts

Referenced sessions

​Step 1: Create the research agent

​Step 2: Create an environment

​Step 3: Start the team session

​Step 4: Watch the board

​Step 5: Wait for the leader to finish

​What success means

​Step 6: Read the recommendation

​What can go wrong

​Limits

​Next steps

Teams

Multi-agent

Deliverables and artifacts

Referenced sessions

Step 1: Create the research agent

Step 2: Create an environment

Step 3: Start the team session

Step 4: Watch the board

Step 5: Wait for the leader to finish

What success means

Step 6: Read the recommendation

What can go wrong

Limits

Next steps