# How the Deep Research Loop (I-3) Works: Intent Clarification, Multi-Turn Search, and Server-Side Code Execution

> Uncover how the Deep Research loop (I-3) clarifies intent, uses multi-turn search, and executes server-side code for effective AI agent research. Learn more now.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: deep-dive
- Published: 2026-08-23

---

**The Deep Research loop (I-3) transforms vague user requests into concrete research plans through three tightly coupled phases: clarifying intent via follow-up questions, executing multi-turn web searches in a ReAct-style loop, and processing results with server-side Python code execution.**

The Deep Research loop (I-3) represents the third operational stage in the AI agent lifecycle defined in the `bojieli/ai-agent-book` repository, following stages I-1 and I-2 as outlined in [`slides/lesson-02.md`](https://github.com/bojieli/ai-agent-book/blob/main/slides/lesson-02.md). This pattern enables autonomous agents to refuse ambiguous instructions, instead employing structured reasoning cycles to gather evidence and compute answers. As implemented in the **GPT-5 Native Tool Agent** located in [`chapter1/search-codegen/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/main.py), the loop coordinates Large Language Model reasoning with external tools like `web_search` and `code_interpreter` to handle complex, open-ended research tasks.

## The Three Phases of the Deep Research Loop (I-3)

The Deep Research loop (I-3) operates as a continuous cycle that terminates only when the accumulated evidence satisfies the original research goal. According to the conceptual overview in [`book/chapter1.md`](https://github.com/bojieli/ai-agent-book/blob/main/book/chapter1.md) and the implementation in [`chapter1/search-codegen/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/main.py), the workflow divides into three distinct phases.

### Intent Clarification

When a user first submits a research-type question, the agent does **not** immediately execute a search. Instead, it generates targeted follow-up questions to disambiguate the request. For example, the agent might ask, "Which data source do you prefer?" or "What specific metrics are you interested in?" These clarification questions are implemented in the **GPT-5 Native Tool Agent** in [`chapter1/search-codegen/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/main.py) at line 336. The user’s answers feed back into the context window, refining the problem definition before any external tools are invoked. This step mirrors the "clarify intent" pattern documented in the chapter 1 overview.

### Multi-Turn Web Search

With a clear, self-contained task description, the agent enters a ReAct-style reasoning loop consisting of four steps:

1. **Plan** – The LLM decides which search query to issue next, adjusting strategy based on previous results.
2. **Tool Call** – The agent invokes the built-in `web_search` tool (hosted by the provider) to fetch latest web pages or API data.
3. **Observe** – Raw HTML or JSON responses append directly to the agent's context.
4. **Iterate** – If results are insufficient, the agent generates a new query or asks additional clarification questions.

This iterative process continues until accumulated evidence satisfies the research goal. The slide deck `slides/chapter1-pilot.mjs` visualizes the "Deep Research" block as an open-ended tool pipeline at lines 82-90, emphasizing its non-linear, exploratory nature.

### Server-Side Code Execution

Once web search yields raw data (tables, JSON, PDFs), the agent transitions from information gathering to computation using the `code_interpreter` tool. This phase executes Python snippets on the server to:

- **Transform** – Parse fetched data, perform calculations (e.g., distance computations, technical-analysis indicators), or generate visualizations.
- **Return** – Insert resulting data structures or figures back into the context for subsequent reasoning.
- **Decision** – Enable the LLM to examine processed output and determine whether additional searches are required or if final report assembly can begin.

The loop terminates when the agent determines that evidence is sufficient and produces a concise, structured markdown report.

## Implementation: The GPT-5 Native Tool Agent

The concrete implementation of the Deep Research loop (I-3) resides in [`chapter1/search-codegen/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/main.py), demonstrating how the **GPT-5 Native Tool Agent** orchestrates the three phases. The following pattern illustrates the complete workflow:

```python

# 1️⃣ Intent clarification – the agent asks follow-up questions

agent.ask("Which data source would you like to use for Bitcoin price data?")

# ← user replies → context updated

# 2️⃣ Search phase – iterative web_search calls

result = agent.tool_call(
    name="web_search",
    arguments={"query": "latest Bitcoin price API"}
)

# result is appended to the context; the agent may decide to search again

# 3️⃣ Server-side processing – code_interpreter runs Python on the result

processed = agent.tool_call(
    name="code_interpreter",
    arguments={"code": """
import pandas as pd, requests, json
data = requests.get("<API-URL>").json()
df = pd.DataFrame(data)

# compute SMA, RSI, etc.

print(df.head())
"""}
)

# processed output is fed back to the LLM for final synthesis

final_report = agent.generate_report()

```

This implementation mirrors the "GPT-5.6 Sol Deep Research" experiment documented in [`chapter1/search-codegen/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/README.md), which explicitly outlines the multi-turn search plus code-interpreter workflow.

## Context Management and Loop Termination

Throughout the Deep Research loop (I-3), the agent maintains a compact context window to prevent token overflow. Intermediate raw pages are compressed or stored offline, while the reasoning trace—including clarification questions, search queries, and code output—remains in the active window for the LLM to reason over. The loop concludes only when the agent's internal evaluator determines that the accumulated evidence satisfies the initial research question, triggering the final report generation phase.

## Summary

- **Intent Clarification:** The Deep Research loop (I-3) begins with targeted follow-up questions to disambiguate user requests before executing any searches, as implemented in [`chapter1/search-codegen/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/main.py).
- **Multi-Turn Search:** A ReAct-style cycle of planning, tool invocation (`web_search`), observation, and iteration continues until sufficient evidence is gathered, visualized in `slides/chapter1-pilot.mjs`.
- **Server-Side Execution:** Raw data transforms into insights through the `code_interpreter` tool, which executes Python snippets server-side to perform calculations and generate visualizations.
- **Termination:** The loop ends when the agent confirms evidence sufficiency, producing a structured markdown report while maintaining compact context through selective compression.

## Frequently Asked Questions

### How does the Deep Research loop (I-3) differ from single-turn search patterns?

Single-turn search executes one query and returns results, while the Deep Research loop (I-3) employs a multi-turn ReAct cycle that plans iteratively, observes results, and adjusts queries dynamically. This allows the agent to handle ambiguous or evolving research goals that require multiple evidence-gathering steps before synthesis.

### What determines when the agent stops searching and generates a final answer?

The agent evaluates context sufficiency based on whether the accumulated evidence—processed through `web_search` results and `code_interpreter` outputs—answers the clarified research question. When the LLM determines no additional information is required to address the user's intent, it exits the loop and assembles the final markdown report.

### Can the server-side code execution access external APIs or only process local data?

The `code_interpreter` tool can execute arbitrary Python code, including `requests` calls to external APIs, as demonstrated in the Bitcoin price example from [`chapter1/search-codegen/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/main.py). The server-side environment supports standard data science libraries like `pandas` and `numpy`, enabling complex data transformation and analysis workflows.

### Is the Deep Research loop (I-3) limited to specific domains like finance or coding?

No, the Deep Research loop (I-3) is domain-agnostic. While the `bojieli/ai-agent-book` examples demonstrate financial data analysis (Bitcoin prices) and code generation, the underlying pattern of clarify-search-execute applies to any research task requiring external information gathering and computational validation.