Open Deep Research

To run the Open Deep Research agent locally using the LangGraph server, follow these steps:

1. Clone and Setup Environment:

   git clone https://github.com/langchain-ai/open_deep_research.git
   cd open_deep_research
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Install Dependencies:

   uv sync
   # or
   uv pip install -r pyproject.toml

3. Configure Environment Variables: Create a .env file from the example to set up model providers, search tools, and other settings:

   cp .env.example .env

4. Launch the LangGraph Server: Run the following command to start the server and open the LangGraph Studio UI:

   uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.11 langgraph dev --allow-blocking

Once launched, you can access:

• Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
• API: http://127.0.0.1:2024
• API Docs: http://127.0.0.1:2024/docs

In the Studio UI, enter a question in the messages input field and click Submit. You can manage different configurations in the "Manage Assistants" tab.

To evaluate the agent against the Deep Research Bench (a dataset of 100 PhD-level tasks), follow these steps:

1. Run Evaluation: Execute the evaluation script which runs the agent against the LangSmith dataset:

   python tests/run_evaluate.py

   This will generate a LangSmith experiment name (e.g., YOUR_EXPERIMENT_NAME).

2. Extract Results: Convert the LangSmith experiment results into a JSONL file compatible with the Deep Research Bench:

   python tests/extract_langsmith_data.py --project-name "YOUR_EXPERIMENT_NAME" --model-name "you-model-name" --dataset-name "deep_research_bench"

3. Submission: The resulting file will be located at tests/expt_results/deep_research_bench_model-name.jsonl. This file can then be submitted to the Deep Research Bench repository for official ranking.

# Run evaluation
python tests/run_evaluate.py

# Extract results
python tests/extract_langsmith_data.py --project-name "YOUR_EXPERIMENT_NAME" --model-name "you-model-name" --dataset-name "deep_research_bench"

LangGraph provides event hooks to manage access control and metadata for different resources. You can use these hooks to ensure users can only interact with their own data.

Thread Hooks

• @auth.on.threads.create and @auth.on.assistants.create: Use these to inject ownership metadata into the resource during creation. You modify the value object's metadata dictionary.
• @auth.on.threads.read, .delete, .update, .search: Use these to return a filter object (e.g., {"owner": user_id}) that restricts the operation to resources matching that metadata.

Assistant Hooks

• @auth.on.assistants.create: Injects ownership metadata.
• @auth.on.assistants.read, .delete, .update, .search: Returns a filter to restrict access.

Store Hooks

• @auth.on.store(): Used to authorize access to items in the LangGraph store. You can validate that the item's namespace matches the user's identity.

Note: If the user is a StudioUser, these hooks should typically return early to allow full access.

# Example: Setting ownership on thread creation
@auth.on.threads.create
async def on_thread_create(ctx: Auth.types.AuthContext, value: Auth.types.on.threads.create.value):
    if isinstance(ctx.user, StudioUser):
        return
    metadata = value.setdefault("metadata", {})
    metadata["owner"] = ctx.user.identity

# Example: Filtering threads on read
@auth.on.threads.read
async def on_thread_read(ctx: Auth.types.AuthContext, value: Auth.types.on.threads.read.value):
    if isinstance(ctx.user, StudioUser):
        return
    return {"owner": ctx.user.identity}

The override_reducer is a custom reducer function used in the state definitions to control how new data merges with existing state.

By default, many state fields use operator.add (which appends to lists). However, override_reducer allows a node to explicitly replace a value. If the new_value is a dictionary containing {"type": "override"}, the reducer will return the value associated with the "value" key instead of appending it.

Logic:

• If new_value is a dict with type == "override": Return new_value.get("value", new_value).
• Otherwise: Return operator.add(current_value, new_value) (standard list/sequence appending).

def override_reducer(current_value, new_value):
    """Reducer function that allows overriding values in state."""
    if isinstance(new_value, dict) and new_value.get("type") == "override":
        return new_value.get("value", new_value)
    else:
        return operator.add(current_value, new_value)

The deep_researcher is a LangGraph-based agent that follows a multi-stage lifecycle to transform a user query into a comprehensive research report:

1. Clarification (clarify_with_user): The agent analyzes the user's request. If allow_clarification is enabled in the configuration and the scope is unclear, it asks the user for more details. Otherwise, it proceeds.
2. Planning (write_research_brief): The agent transforms the user's messages into a structured research_brief and initializes the supervisor with specific instructions.
3. Execution (research_supervisor): A supervisor subgraph manages the research process. It breaks the brief into tasks and delegates them to multiple researcher subgraphs in parallel. The supervisor can use think_tool for planning, ConductResearch to delegate, or ResearchComplete to finish.
4. Researching (researcher): Individual researchers use tools (search, MCP, think_tool) to gather information. Once a researcher finishes its task, it runs compress_research to synthesize its findings into a concise summary.
5. Reporting (final_report_generation): The agent collects all compressed findings from all researchers and synthesizes them into a final, well-structured report.