Gemini 2.5 Deep Research モード接入完全ガイド：多段階研究 Agent の作り方

你是否曾經想要建立一個能像研究者一樣思考的 AI Agent？讓我分享我在專案中使用 Gemini 2.5 Deep Research 模式的實際經驗。這項功能讓 AI 不僅僅是回答問題，而是能夠執行多步驟的研究流程，自動規劃、分解問題、收集資訊，最終產出高品質的分析報告。

Deep Research 模式是什麼？

Deep Research 模式是一種特殊的 AI 推理方式。普通模式下，AI 收到問題後直接回答。但在 Deep Research 模式下，AI 會像人類研究者一樣：

• 分析問題：理解用戶真正想知道的是什麼
• 制定計畫：規劃需要哪些步驟來回答
• 逐步執行：每個步驟都會暫停，等待確認或自動繼續
• 整合結果：將所有研究結果組合成完整的報告

例如，如果你問「分析电动车市場的發展趨勢」，Deep Research Agent 可能會先研究市場數據，然後分析主要廠商，接著預測未來發展，最後產出完整報告。

為什麼選擇 HolySheep AI？

我在多個平台測試後選擇了 HolySheep AI，有以下原因：

• 85% 費用節省：官方匯率是 ¥7.3=$1，但 HolySheep 的費率是 ¥1=$1，成本大幅降低
• 支援微信支付和支付寶：對中文用戶非常友好
• 延遲低於 50ms：實際使用中響應速度非當快
• 註冊即送免費額度：可以先試用再決定
• Gemini 2.5 Flash 極優惠：2026 年定價每百萬輸出 tokens 只需 $2.50（對比 GPT-4.1 的 $8）

開始之前的準備

在開始之前，你需要準備以下內容：

• Python 3.8 或更高版本
• 一個 HolySheep AI 帳戶（註冊後獲得 API Key）
• 基本的 Python 程式撰寫概念（我會詳細說明每一步）

步驟一：安裝必要的套件

首先，打開你的終端機（Windows 使用命令提示字元或 PowerShell，Mac/Linux 使用終端機），輸入以下命令：

pip install openai requests

💡 小提示：pip 是 Python 的套件管理工具，安裝完成後會顯示「Successfully installed」

步驟二：設定 API Key

登入 HolySheep AI 後，在儀表板找到你的 API Key看起來像這樣：sk-xxxxxxxxxxxxxxxx

為了安全起見，我們不要直接把 Key 寫在程式碼裡。我建議建立一個設定檔案：

# config.py
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"
MODEL = "gemini-2.5-flash"

💡 小提示：把「YOUR_HOLYSHEEP_API_KEY」替換成你在 HolySheep AI 獲得的真實 Key

步驟三：建立基本的 API 連接

讓我們先測試一下連接是否正常：

import openai
from config import API_KEY, BASE_URL, MODEL

設定 API 客戶端
client = openai.OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL
)

簡單測試：讓 AI 說你好
response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": "你好，請用一句話介紹你自己"}
    ],
    max_tokens=100
)

print("AI 回應：", response.choices[0].message.content)

執行這個程式，如果看到 AI 的回應，恭喜你！連接成功了。

步驟四：實現 Deep Research Agent

現在我們來實現真正的多步驟研究 Agent。我會把程式碼分成幾個部分說明：

4.1 研究規劃器（Research Planner）

這個部分負責分析問題並制定研究計畫：

import json
from typing import List, Dict

class ResearchPlanner:
    """研究規劃器：分析問題並制定研究步驟"""
    
    def __init__(self, client):
        self.client = client
    
    def create_research_plan(self, query: str) -> List[Dict]:
        """
        分析用戶問題，生成研究計畫
        返回格式：[{"step": 1, "task": "具體任務", "purpose": "為什麼要做"}]
        """
        prompt = f"""分析以下研究問題，將其分解為 3-5 個邏輯步驟。
以 JSON 陣列格式輸出，每個步驟包含：step（順序）、task（具體任務）、purpose（目的）。

研究問題：{query}

只輸出 JSON，不要其他文字。"""

        response = self.client.chat.completions.create(
            model=MODEL,
            messages=[{"role": "user", "content": prompt}],
            max_tokens=500,
            temperature=0.7
        )
        
        try:
            plan = json.loads(response.choices[0].message.content)
            return plan
        except:
            # 如果 JSON 解析失敗，返回預設計畫
            return [
                {"step": 1, "task": "收集基本資訊", "purpose": "建立基礎理解"},
                {"step": 2, "task": "深入分析", "purpose": "獲取詳細資料"},
                {"step": 3, "task": "整合結論", "purpose": "形成完整報告"}
            ]

4.2 研究執行器（Research Executor）

這個部分負責執行每個研究步驟：

class ResearchExecutor:
    """研究執行器：執行每個研究步驟並記錄結果"""
    
    def __init__(self, client):
        self.client = client
        self.research_history = []
    
    def execute_step(self, step: Dict, context: str) -> str:
        """
        執行單個研究步驟
        step: 包含 task 和 purpose 的字典
        context: 之前步驟的研究結果
        """
        prompt = f"""你是研究團隊的一員，負責執行當前步驟。

當前任務：{step['task']}
任務目的：{step['purpose']}

之前的相關研究：
{context}

請深入執行當前任務，提供詳細、有根據的資訊。
回答時要：1) 引用具體數據 2) 說明資訊來源 3) 保持邏輯連貫"""

        response = self.client.chat.completions.create(
            model=MODEL,
            messages=[{"role": "user", "content": prompt}],
            max_tokens=1500,
            temperature=0.5
        )
        
        result = response.choices[0].message.content
        self.research_history.append({
            "step": step['step'],
            "task": step['task'],
            "result": result
        })
        
        return result
    
    def get_full_context(self) -> str:
        """獲取所有研究結果作為上下文"""
        if not self.research_history:
            return "尚無研究記錄"
        
        context = "=== 研究歷史 ===\n"
        for item in self.research_history:
            context += f"\n[步驟 {item['step']}] {item['task']}\n"
            context += f"結果：{item['result']}\n"
        return context

4.3 完整的多步驟研究 Agent

現在把規劃器和執行器組合成完整的 Agent：

class DeepResearchAgent:
    """多步驟研究 Agent"""
    
    def __init__(self, client):
        self.planner = ResearchPlanner(client)
        self.executor = ResearchExecutor(client)
    
    def research(self, query: str, auto_continue: bool = True) -> Dict:
        """
        執行完整的研究流程
        
        參數：
        - query: 研究問題
        - auto_continue: 是否自動執行所有步驟（設為 False 可手動審核每步）
        
        返回：包含所有研究步驟和最終報告的字典
        """
        print(f"\n{'='*50}")
        print(f"🔍 開始研究：{query}")
        print(f"{'='*50}\n")
        
        # 步驟 1：制定研究計畫
        print("📋 制定研究計畫...")
        plan = self.planner.create_research_plan(query)
        print(f"   將執行 {len(plan)} 個研究步驟\n")
        
        # 步驟 2：逐步執行研究
        for step_info in plan:
            print(f"   [{step_info['step']}/{len(plan)}] 執行：{step_info['task']}")
            
            context = self.executor.get_full_context()
            result = self.executor.execute_step(step_info, context)
            
            print(f"   ✅ 完成\n")
            
            # 如果不是自動模式，顯示結果並等待確認
            if not auto_continue:
                print("─"*40)
                print("結果預覽：")
                print(result[:200] + "..." if len(result) > 200 else result)
                print("─"*40)
                confirm = input("繼續下一個步驟？(y/n): ")
                if confirm.lower() != 'y':
                    break
        
        # 步驟 3：生成最終報告
        print("📝 生成最終研究報告...")
        final_report = self._generate_report(query)
        
        return {
            "query": query,
            "plan": plan,
            "steps": self.executor.research_history,
            "final_report": final_report
        }
    
    def _generate_report(self, original_query: str) -> str:
        """基於所有研究步驟生成最終報告"""
        context = self.executor.get_full_context()
        
        prompt = f"""基於以下研究結果，為用戶生成一份完整、結構化的研究報告。

原始問題：{original_query}

研究過程：
{context}

報告要求：
1. 摘要（100字內）
2. 主要發現（3-5個要點）
3. 深入分析
4. 結論與建議
5. 使用清晰的分段和標題"""

        response = self.client.chat.completions.create(
            model=MODEL,
            messages=[{"role": "user", "content": prompt}],
            max_tokens=2000,
            temperature=0.6
        )
        
        return response.choices[0].message.content


使用範例
if __name__ == "__main__":
    # 初始化 Agent
    agent = DeepResearchAgent(client)
    
    # 執行研究
    result = agent.research(
        "分析 2024 年全球 AI 晶片市場的競爭格局與發展趨勢",
        auto_continue=True  # 設為 False 可手動審核每步
    )
    
    # 顯示最終報告
    print("\n" + "="*50)
    print("📊 研究報告")
    print("="*50)
    print(result["final_report"])

實際應用範例

假設我想研究「電動車充電基礎設施的發展前景」，執行程式後，研究 Agent 會：

1. 制定計畫：分為市場現況、主要廠商、技術趨勢、投資分析等步驟
2. 逐步執行：每步都會根據前面的結果調整研究方向
3. 整合報告：自動生成結構化的研究報告

成本分析

使用 HolySheep AI 的費用非常實惠。以這個研究 Agent 為例：

• 完成一次完整研究（大約 5-7 個步驟）
• 預計花費 tokens：約 15,000 輸入 + 8,000 輸出
• 使用 Gemini 2.5 Flash 成本：約 $0.02（不到兩毛錢！）

對比官方定價，同樣的任務在 Google AI Studio 可能需要花費好幾倍。

常見問題

Q: 為什麼我的 API 請求失敗了？
A: 首先檢查 API Key 是否正確設定，確認網路連線正常。如果仍有问题，可以查看 HolySheep AI 的狀態頁面。

Q: 回應速度變慢怎麼辦？
A: 嘗試減少 max_tokens 參數，或使用快取機制避免重複請求。

まとめ

我在這個專案中使用 HolySheep AI 的體驗非常滿意。85% 的費用節省、微信支付和支付寶的便利性，以及低於 50ms 的延遲，讓我可以輕鬆地實驗和部署多步驟研究 Agent。

如果你有興趣嘗試，可以從小的研究任務開始，逐步擴展到更複雜的應用場景。HolySheep AI 的免費額度足夠你完成多次測試。

有任何問題，歡迎在評論區交流！

👉 HolySheep AI に登録して無料クレジットを獲得