Tutorial: Building a Deep Research Agent

Relevant source files

The following files were used as context for generating this wiki page:

• apps/deep-research/README.md
• apps/deep-research/agents/lead.py
• apps/deep-research/agents/researcher.py
• apps/deep-research/loom.toml
• ARCHITECTURE.md
• loom-py/src/loom/cognitive/README.md

The DeepResearch demo is a multi-agent system designed to perform in-depth research on a given topic. It showcases the core capabilities of the Loom runtime for building sophisticated, collaborative AI systems, including context isolation, true parallel execution via an event-driven architecture, dynamic agent spawning, and report aggregation. The system is inspired by research from Anthropic and LangChain's DeepAgents.

This tutorial breaks down the architecture, agent roles, communication flow, and configuration of the DeepResearch system, providing a guide to understanding and running this advanced multi-agent application.

Sources: apps/deep-research/README.md:3-12

Architecture Overview

The DeepResearch system follows a hierarchical, event-driven architecture. A user's query is first processed by a Lead Agent, which acts as an orchestrator. The Lead Agent decomposes the main query into several sub-queries and dynamically spawns multiple Researcher Agents to handle them in parallel. Each Researcher Agent conducts its own research, including web searches, and generates a report section. These sections are then sent back to the Lead Agent, which aggregates them into a final, comprehensive report.

Sources: apps/deep-research/README.md:14-15, apps/deep-research/agents/lead.py, apps/deep-research/agents/researcher.py

The following diagram illustrates the high-level architecture and data flow:

This diagram shows the flow from the initial user query to the final aggregated report, highlighting the parallel nature of the research tasks.
Sources: apps/deep-research/README.md:17-49

Core Concepts

The DeepResearch demo is built on two fundamental principles that are central to Loom's design philosophy.

Sources: apps/deep-research/README.md:62-63

Context Isolation

Each Researcher Agent operates within its own isolated context window. This is a critical feature that prevents information from one research topic from "bleeding" into another, which avoids context pollution and potential token budget conflicts. The Lead Agent only aggregates the final, structured report sections, ensuring the integrity of each sub-task.

Sources: apps/deep-research/README.md:65-76

True Parallel Execution

Loom's event-driven architecture enables genuine parallelism. The Lead Agent emits all research requests simultaneously. The Researcher Agents receive these requests and begin their work concurrently, without waiting for each other. They process events as they arrive, leading to a significant speed-up in the overall research process compared to a sequential approach.

Sources: apps/deep-research/README.md:78-89

Agent Roles and Responsibilities

The system is composed of two primary agent types: the Lead Agent and the Researcher Agent.

Lead Agent

The Lead Agent is the orchestrator of the entire research process. Its responsibilities are:

1. Decomposing the Query: It receives the initial user query and uses an LLM to break it down into distinct sub-queries or focus areas.
2. Dispatching Researchers: It emits research.request events for each sub-query, effectively spawning and dispatching Researcher Agents to work on them in parallel.
3. Aggregating Reports: It listens for researcher.report events. Once all research sections are collected (or a timeout is reached), it synthesizes them into a single, coherent final report.
4. Saving the Output: The final report is saved to the workspace.

Sources: apps/deep-research/README.md:93-99, apps/deep-research/agents/lead.py:15-20

Researcher Agent

The Researcher Agent is a specialized worker that executes a single research task. Each researcher runs its own cognitive loop.

1. Perceive: It receives a research.request event containing a specific sub-query.
2. Think & Act (Search): It plans a search strategy and executes a web search by calling the web-search MCP (Model-Context-Protocol) tool.
3. Think & Act (Analyze): It analyzes the search results, using an LLM to synthesize the information and generate a structured report section with a title, content, key points, and sources.
4. Emit Report: It sends the completed section back to the Lead Agent by emitting a researcher.report event.

Sources: apps/deep-research/README.md:101-112, apps/deep-research/agents/researcher.py:19-24

The internal process of a Researcher Agent can be visualized as follows:

This flowchart shows the step-by-step cognitive loop executed by each Researcher Agent.
Sources: apps/deep-research/agents/researcher.py:202-232

Data Flow and Communication

Communication between agents is handled entirely through Loom's event bus, a core component of the Rust runtime. Agents publish and subscribe to specific topics to send and receive messages.

Sources: ARCHITECTURE.md:63-72

The sequence of events for a typical research task is as follows:

This sequence diagram illustrates the asynchronous, event-driven communication between the Lead and Researcher agents.
Sources: apps/deep-research/agents/lead.py:162-172, apps/deep-research/agents/researcher.py:261-266

Configuration

The behavior of the DeepResearch agents and their dependencies is configured in the loom.toml file. This includes agent settings, LLM provider details, and MCP tool configurations.

Sources: apps/deep-research/loom.toml

Section	Key	Description
[agents.lead-agent]	topics	List of topics the agent subscribes to (user.query, researcher.report).
	llm_provider	The LLM provider to use for decomposition and aggregation (e.g., "deepseek").
	max_researchers	The maximum number of parallel researcher agents to spawn.
	aggregation_timeout_sec	Timeout in seconds to wait for all reports before aggregating.
[agents.researcher-agent]	topics	Dynamically assigned by the Lead Agent.
	llm_provider	The LLM provider for analysis and summarization.
	max_sources	The maximum number of web search results to use.
[llm.deepseek]	api_key, api_base, model	Configuration for the DeepSeek LLM provider. API keys are loaded from environment variables.
[mcp.web-search]	command, args	Defines the command to run the Brave Search MCP tool.
	env.BRAVE_API_KEY	Specifies the environment variable for the search tool's API key.
[workspace]	root, reports_dir	Defines the paths for the workspace and where to save final reports.

Sources: apps/deep-research/loom.toml:1-45

Quick Start Guide

To run the DeepResearch demo, follow these steps:

1. Set up API Keys: Export your API keys for the LLM provider and the web search tool.

   export DEEPSEEK_API_KEY="sk-..."
   export BRAVE_API_KEY="BSA..."
   

   Sources: apps/deep-research/README.md:52-54

2. Run the Demo: Navigate to the demo directory and use the loom run command. This single command starts the Loom runtime (Core, Bridge, Dashboard) and launches all defined agents.

   cd apps/deep-research
   loom run
   

   Sources: apps/deep-research/README.md:57-58

3. Send a Query: In a separate terminal, use the provided query.py script to send a research question to the Lead Agent.

   python query.py "What are the latest developments in AI agents?"
   

   Sources: apps/deep-research/README.md:65-66

4. View the Report: The final aggregated report will be saved as a Markdown file in the workspace/reports/ directory.

   cat workspace/reports/latest.md
   

   Sources: apps/deep-research/README.md:70-71

Conclusion

The DeepResearch application serves as a powerful demonstration of Loom's event-driven, multi-agent runtime. It effectively illustrates how to build complex, collaborative systems where agents with specialized roles can work in parallel. Key architectural patterns like context isolation and dynamic agent spawning are not just theoretical but are practically implemented, showcasing a robust model for developing production-ready AI agent systems.

Sources: apps/deep-research/README.md:3-12, ARCHITECTURE.md:3-11