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 (async: true).

Default behavior: The library defaults to :infinity timeout, so Deep Research will run to completion without timing out. This is appropriate for human-interactive agents where the user can manually stop execution if needed.

For automated agents: If running unattended, you may want to configure a maximum timeout:

# Application-level (config/runtime.exs)
config :langchain, async_tool_timeout: 35 * 60 * 1000  # 35 minutes

# Or per-agent
{:ok, agent} = Agent.new(%{
  model: model,
  async_tool_timeout: 35 * 60 * 1000
})

# Or per-chain
{:ok, chain} = LLMChain.new(%{
  llm: model,
  async_tool_timeout: 35 * 60 * 1000
})

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
  }
  |> 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. With the default :infinity timeout, the tool will run to completion without timing out.