Defines an OpenAI Deep Research tool for conducting comprehensive research on complex topics.

This tool leverages OpenAI's o3-deep-research and o4-mini-deep-research models to perform multi-step research analysis that can take 5-30 minutes to complete. The models can find, analyze, and synthesize hundreds of sources to create comprehensive reports at the level of a research analyst.

The Deep Research tool is designed for complex analysis and research tasks such as:

• Legal or scientific research
• Market analysis
• Reporting on large bodies of data

Important Notes

• Deep Research requests are long-running operations (5-30 minutes)
• The tool will return a request ID immediately, then poll for completion
• Research results include inline citations and source metadata
• Requires an OpenAI API key with access to Deep Research models

Timeout Configuration

Deep Research runs as an async tool with a default timeout of 2 minutes, which is insufficient for Deep Research operations. You must configure the async_tool_timeout when using this tool:

{:ok, chain} =
  %{
    llm: model,
    verbose: true,
    async_tool_timeout: 35 * 60 * 1000  # 35 minutes in milliseconds
  }
  |> LLMChain.new!()
  |> LLMChain.add_tools(DeepResearch.new!())

Without this configuration, you may encounter timeout errors after 2 minutes.

Example

The following example shows how to use the Deep Research tool in a chain:

{:ok, updated_chain, %Message{} = message} =
  %{
    llm: ChatOpenAI.new!(%{temperature: 0}), 
    verbose: true,
    async_tool_timeout: 35 * 60 * 1000  # 35 minutes for Deep Research
  }
  |> LLMChain.new!()
  |> LLMChain.add_message(
    Message.new_user!("Research the economic impact of renewable energy adoption on job markets.")
  )
  |> LLMChain.add_functions(DeepResearch.new!())
  |> LLMChain.run(mode: :until_success)

The tool will initiate a research request and return comprehensive findings with citations.