# `LangChain.Tools.DeepResearch`
[🔗](https://github.com/brainlid/langchain/blob/v0.13.0/lib/tools/deep_research.ex#L1)

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.

# `execute`
[🔗](https://github.com/brainlid/langchain/blob/v0.13.0/lib/tools/deep_research.ex#L150)

```elixir
@spec execute(args :: %{required(String.t()) => any()}, context :: map()) ::
  {:ok, String.t()} | {:error, String.t()}
```

Executes the deep research request. This function handles the long-running nature
of deep research by creating a request and polling for completion.

Returns the research findings with inline citations and source metadata.

# `new`
[🔗](https://github.com/brainlid/langchain/blob/v0.13.0/lib/tools/deep_research.ex#L75)

```elixir
@spec new() :: {:ok, LangChain.Function.t()} | {:error, Ecto.Changeset.t()}
```

Define the "deep_research" function. Returns a success/failure response.

# `new!`
[🔗](https://github.com/brainlid/langchain/blob/v0.13.0/lib/tools/deep_research.ex#L132)

```elixir
@spec new!() :: LangChain.Function.t() | no_return()
```

Define the "deep_research" function. Raises an exception if function creation fails.

---

*Consult [api-reference.md](api-reference.md) for complete listing*