Ollama Research Agent MVP

此專案實作了 Plan → Search → Fetch → Codegen → Execute → Synthesize 迴路， 使用 Ollama 的 gpt-oss 模型搭配 web_search、web_fetch 工具，並透過 Docker 沙箱安全執行模型產生的 Python 程式碼。

專案內容

• agent.py：核心編排程式，負責與 Ollama 溝通、註冊工具並管理回圈。
• sandbox/Dockerfile：建立無網路的 Python 3.11 執行環境，預先安裝常見資料處理套件。
• requirements.txt：最低限度的 Python 依賴 (ollama>=0.6.0)。
• artifacts/：自動保存 AI 產生的程式碼和檔案。

先決條件

1. Ollama 已安裝，且本機可執行 gpt-oss 模型。
2. Docker 已安裝並啟動。
3. Python 3.11 (或相容版本) 與 pip。
4. 具備可用的 Ollama API Key（請自行設定環境變數，專案不會內建金鑰）。
5. 本機已啟動 ollama serve（若未啟動會出現 Failed to connect to Ollama）。

安裝步驟

# 安裝 Python 依賴
pip install -r requirements.txt

# 下載需要的模型（範例使用 20B，可依需求替換）
ollama pull gpt-oss:20b

# 建立 Docker 沙箱映像（包含視覺化套件）
docker build -t py-sandbox:latest sandbox/

# 升級 Python 版 ollama，確保支援 web_search / web_fetch
pip install --upgrade "ollama>=0.6.0"

若安裝的是舊版 ollama Python SDK，執行時會收到 Installed ollama package lacks web_search/web_fetch 警告。 請升級到 0.6.0 以上或自行提供搜尋/抓取工具再重試。

必要環境變數

export OLLAMA_API_KEY="<your_ollama_api_key>"
# 可選：覆寫預設模型或回圈限制
export OLLAMA_AGENT_MODEL="gpt-oss:120b"
export OLLAMA_AGENT_MAX_TURNS=16
export OLLAMA_AGENT_SANDBOX_TIMEOUT=90

⚠️ 安全提示：請勿把 API Key 寫入程式碼或版本控制中；在終端或 CI/CD 環境自行設定即可。

使用方式

# 直接執行預設驗證任務（intro.md 第 8 節的案例）
python agent.py

# 執行自訂指令
python agent.py "替我搜尋最新的 gpt-oss 教學並整理成表格"

# 如果 Ollama 不支援 think 參數，可加上 --no-think
python agent.py --no-think "請比較 3 篇文章的 license 敘述"

# 視覺化範例 1：程式語言市場分析
python agent.py "請搜尋全球前 5 大程式語言的市場佔有率數據，然後用 Python 產生長條圖和圓餅圖"
# artifacts/execution_20250929_011902/
# ├── generated_code.py
# ├── programming_languages_bar.png
# └── programming_languages_pie.png

# 視覺化範例 2：股市資料分析  
python agent.py "請寫 Python 程式碼來產生一個關於股市數據的時間序列圖表，使用 matplotlib 和 seaborn，並將圖表和 CSV 資料都儲存到檔案中"
# artifacts/execution_20250929_012327/
# ├── generated_code.py
# ├── stock_chart.png
# └── stock_data.csv

# 視覺化範例 3：人口統計報告
python agent.py "請產生台灣人口統計分析報告，包含長條圖、圓餅圖和趨勢圖，使用虛擬資料，並將所有圖表和資料都儲存為檔案"
# artifacts/execution_20250929_012556/
# ├── generated_code.py
# ├── output_age_bar_chart.png
# ├── output_age_distribution.csv
# ├── output_gender_distribution.csv
# ├── output_gender_pie_chart.png
# ├── output_population_trend.csv
# └── output_population_trend.png

執行時代理會自動：

1. 解讀指令並規劃需要的工具。
2. 呼叫 web_search 和 web_fetch 取得資料。
3. 產生 Python 程式並透過 run_python 在 Docker 沙箱內執行。
4. 自動保存程式碼和產生的檔案到 artifacts/ 目錄。
5. 將分析結果（建議為 JSON）回傳到主控流程。

工件保存功能：每次執行 Python 程式都會自動保存到 artifacts/execution_時間戳記/ 目錄，包含 AI 產生的原始程式碼和所有輸出檔案（圖表、CSV、JSON 等），使用時間戳記命名避免檔案覆蓋。執行完成後可用 ls -la artifacts/execution_*/ 檢視產生的檔案。

客製與延伸

• 若需要額外 Python 套件，請修改 sandbox/Dockerfile 並重新建置映像。
• 想紀錄工具呼叫或實作重新嘗試機制，可在 agent.py 中的訊息回合迴圈加上額外邏輯。
• 若要部署為服務，可在 agent.py 基礎上加入 Web API、任務列隊或持久化儲存。

驗證建議

• 先執行預設驗證任務測試確保搜尋、抓取、程式執行皆正常。
• 使用 python -m compileall agent.py 檢查語法；必要時加上單元測試確保工具錯誤處理與訊息格式。
• 檢查 artifacts/ 目錄確認工件保存功能正常。