DOCSEARCHbyAlgolia
Submit Docs

ThinkDepth.ai Deep Research

repository·main·Indexed 41 days ago

https://github.com/thinkdepthai/deep_research

An open-source deep research agent for complex, long-horizon tasks using a 'Self-Balancing Agentic AI' paradigm. It utilizes a multi-agent supervisor orchestration built with LangGraph to balance information gathering via web search (Tavily) and report generation. The system features a structured workflow including user clarification, research brief writing, parallel researcher agent delegation, and final report synthesis.

Tokens
6.1K
Snippets
20
Records
25
Agent score
52%

What's inside ThinkDepth.ai Deep Research

  1. How Self-Balancing Agentic AI works

    main

    ThinkDepth.ai uses a paradigm called Self-Balancing Agentic AI, which utilizes a Self-Balancing Test-Time Diffusion Deep Research algorithm.

    Instead of treating all tasks equally, the agent explicitly reasons about self-balancing rules to manage the interaction between two primary goals at different stages:

    1. Information Gap Closing: Focuses on making external web search tool calls to gather missing data. This occurs primarily during the information collection stage.
    2. Generation Gap Closing: Focuses on refining the draft report and optimizing the final output. This becomes the primary focus during the final report generation stage.

    By transitioning between these stages based on whether the information gap is fully closed, the agent achieves better performance on long-horizon and complex tasks.

  2. Setup ThinkDepth.ai Deep Research

    main

    To run the deep research demo, you need to install uv, configure your API keys, synchronize dependencies, and launch the Jupyter notebook.

    Prerequisites

    You must have access to an OpenAI API key and a Tavily API key for web search capabilities.

    # 1. Install uv
pip install uv

# 2. Set environment variables (add to ~/.zshrc or ~/.bashrc)
export OPENAI_API_KEY='Your OpenAI API Key'
export TAVILY_API_KEY='Your Tavily API Key'

# 3. Install all packages
uv sync

# 4. Run the demo notebook
uv run jupyter notebook thinkdepthai_deepresearch.ipynb

  3. Understand the Research Scoping Workflow

    main

    The research scoping phase is a LangGraph-based workflow designed to assess user requests and prepare them for deep research. It follows a three-step process:

    1. clarify_with_user: Evaluates the conversation history to determine if the user's request is sufficiently detailed. If more information is needed, it generates a clarification question and ends the workflow. If sufficient, it routes to the next step.
    2. write_research_brief: Transforms the conversation history into a structured ResearchQuestion (research brief) to guide the subsequent research agents.
    3. write_draft_report: Synthesizes the research brief into an initial DraftReport.

    The workflow is constructed using a StateGraph initialized with AgentState and AgentInputState.

  4. How the multi-agent supervisor orchestration works

    main

    The multi-agent supervisor implements a coordination pattern to manage complex research tasks. It operates through three main stages:

    1. Coordination: A central supervisor agent analyzes the research brief and current progress to decide on next steps (e.g., identifying new topics or deciding when research is complete).
    2. Delegation: The supervisor uses ConductResearch tool calls to launch multiple specialized researcher_agent instances in parallel. Each researcher works on a specific sub-topic independently to maintain isolated context windows.
    3. Aggregation: Results from sub-agents (compressed findings) are returned as ToolMessage objects. The supervisor then aggregates these findings and uses tools like refine_draft_report to compile the final report.

    This architecture improves efficiency by allowing parallel execution while preventing context window saturation.

  5. Understand the Research Agent workflow

    main

    The research agent is implemented as a stateful graph using langgraph. It follows an iterative loop of analysis, tool execution, and synthesis to answer complex questions.

    The Workflow Lifecycle:

    1. llm_call: The agent analyzes the current ResearcherState and decides whether to call tools (like tavily_search) or provide a final answer.
    2. Routing (should_continue):
      • If the LLM generates tool_calls, the graph routes to tool_node.
      • If no tool calls are present, the agent has reached a conclusion and routes to compress_research.
    3. tool_node: Executes the requested tools and appends the results back to the message history.
    4. Loop: After tool execution, the graph loops back to llm_call for further reasoning.
    5. compress_research: Once the research loop finishes, this node synthesizes all findings into a concise summary and extracts raw notes.
    6. END: The process terminates, returning the ResearcherOutputState.

  6. The Deep Research Workflow Orchestration

    main

    The research system is implemented as a StateGraph using LangGraph, orchestrating a multi-agent workflow from initial user clarification to final report generation. The workflow follows a linear and hierarchical progression through several specialized nodes:

    1. clarify_with_user: Initial step to scope the research request.
    2. write_research_brief: Generates a formal research brief based on the clarified request.
    3. write_draft_report: Creates an initial draft based on the brief.
    4. supervisor_subgraph: A multi-agent supervisor node that conducts deep research and refines findings.
    5. final_report_generation: Synthesizes all findings, the draft, and the brief into a comprehensive final report.

    The graph is initialized with AgentState and accepts AgentInputState as its input schema.

    from langgraph.graph import StateGraph, START, END
from deep_research.state_scope import AgentState, AgentInputState

deep_researcher_builder = StateGraph(AgentState, input_schema=AgentInputState)

# Workflow structure:
# START -> clarify_with_user -> write_research_brief -> write_draft_report -> supervisor_subgraph -> final_report_generation -> END

agent = deep_researcher_builder.compile()

  7. Initialize the Deep Research agent

    main

    To use the deep research capabilities, use the deep_researcher_builder to compile a full agent. You should provide an InMemorySaver as a checkpointer to manage state and conversation history. You can visualize the agent's internal graph using the .get_graph(xray=True).draw_mermaid_png() method.

    from langgraph.checkpoint.memory import InMemorySaver
from deep_research.research_agent_full import deep_researcher_builder

checkpointer = InMemorySaver()
full_agent = deep_researcher_builder.compile(checkpointer=checkpointer)

  9. Configure supervisor research depth and concurrency

    main

    The supervisor's behavior regarding research depth and parallelism is controlled by two system constants. These constants are used to construct the system prompt and manage execution loops:

    • max_researcher_iterations: The maximum number of tool call iterations (including think_tool, ConductResearch, and refine_draft_report) allowed for individual researcher agents. This prevents infinite loops.
    • max_concurrent_researchers: The maximum number of parallel research tasks the supervisor can launch simultaneously. This value is passed to the lead_researcher_prompt to constrain the agent's planning.

    Note: The current implementation uses max_researcher_iterations = 15 and max_concurrent_researchers = 3.

  10. Configure the Research Agent models and tools

    main

    The agent's behavior is driven by model binding and tool availability. While the implementation uses init_chat_model, you can customize the agent by providing different models and tools.

    Available Tools:

    • tavily_search: For web searching.
    • think_tool: For internal reasoning/thought processes.

    Model Configuration:

    • The agent uses a primary model_with_tools for decision making.
    • A summarization_model is used for synthesis.
    • A compress_model (often with a high max_tokens limit, e.g., 32000 or 64000) is used to condense large amounts of research data into a final summary.
    # Example of how models and tools are initialized in the source
tools = [tavily_search, think_tool]
model = init_chat_model(model="openai:gpt-5")
model_with_tools = model.bind_tools(tools)
compress_model = init_chat_model(model="openai:gpt-5", max_tokens=32000)

  12. Run a research task with the Deep Research agent

    main

    Execute a research task by calling await full_agent.ainvoke().

    Pass a dictionary containing a list of HumanMessage objects under the messages key.

    Use the config parameter to pass a thread dictionary. The thread must include a thread_id within a configurable key to maintain state, and you can optionally set a recursion_limit to control the depth of the research process. Note that complex research tasks can take between 10 to 30 minutes to complete.

    from langchain_core.messages import HumanMessage

# Define the thread configuration
thread = {"configurable": {"thread_id": "1", "recursion_limit": 50}}

# Invoke the agent with a research prompt
result = await full_agent.ainvoke(
    {
        "messages": [
            HumanMessage(content="Write a paper to discuss the influence of AI interaction on interpersonal relations...")
        ]
    }, 
    config=thread
)