# 網路工具

網頁搜尋、抓取頁面、公開 API 查詢、HTTP 請求與下載的工具。

| 工具 | 併發 | 說明 |
|---|---|---|
| `search_web` | ✓ | 即時網路查詢，同時回傳 DuckDuckGo 結果與 Google News 標題，格式為 `{"web":[...],"news":[...]}`。`source` 可選 `all` / `web` / `news`；`time_range` 對兩個來源套用回溯區間（新聞上限 7 天）；`edition` 設定新聞地區（`TW:zh-Hant`、`US:en`）；`cdp=true` 強制以瀏覽器擷取（HTTP 202 時自動啟用）；另有旗標可跳過結果快取。自 v1.3.1 起，設定 decision model 時會逐一判斷結果標題與當前需求是否相關，信心 0.7 以上判為不相關者移除；快取存的是未過濾的清單，因此命中快取時也會重新過濾。全部結果都不相關時，改回傳提示要求調整查詢。未設定 decision model 或判斷失敗時回傳全部結果。上限 90 秒 |
| `fetch_page` | ✓ | 擷取單一網頁並以 `markdown`、`html` 或 `json` 回傳（readability + 透過 ToriiDB 的 4xx/5xx skip cache）。預設帶上持久 Chrome profile 的 cookie，需登入的站台可透明存取；優先嘗試 headless，失敗才改用可見視窗重試；`headless: false` 在有顯示器時直接開啟可見視窗（v1.1.4 前反而被強制為僅 headless）。`scroll`（v1.3.6 新增；0-20，預設 3，超過 20 會被夾到 20）決定捲動幾次以載入延遲內容，頁面不再變化就提早停止 —— 動態牆、時間軸與長留言串用 10-20，只要頁面頂端用 0。`keep_links` 保留同網域連結以支援遞迴文件研究；`force` 跳過 30 分鐘快取，並重試先前標記為失敗的 URL。`save` 與 `save_to` 參數已移除於 v1.3.6：把網頁存到本地改用 `download_file(render=true)`。自 v1.3.1 起工具要求 agent 抓某網站第一頁前先抓其 `/llms.txt`，若其中列出要找的頁面，就改抓列出的 `.md` URL。設定 decision model 時，未帶 `keep_links` 的 `markdown` 輸出會先切成區塊，移除頁面雜訊（廣告、導覽選單、分享或訂閱提示、cookie 告示、頁尾、相關文章連結）後才寫入快取；接著判斷頁面與當前需求是否相關，不相關的頁面不交給模型，改回傳提示要求換來源，從快取取出時同樣會檢查。判斷失敗時保留原內容。上限 90 秒 |
| `http_request` | ✓ | 原始 HTTP 請求（GET/POST/PUT/DELETE/PATCH），回傳 status + headers + body。`content_type` 可選 `json` / `form` / `multipart`；multipart 接受 `{"fields":{...},"files":[{"name","path","content_type"}]}`，路徑須為絕對路徑並以二進位讀入。timeout 上限 300 秒。`GET` 不需確認即執行；其他 method 一律經過確認 gate。內建 SSRF 防護（DNS 解析後比對 loopback / private / link-local），特定主機可透過 `net_white_list` 放行。自 v1.3.2 起，經 `public_api_list` 找到的公開 API 直接以它取得答案 —— 不建工具；使用者提供、需要金鑰的 API 則應建成 `script_*` 工具，由 script 以 `get_key()` 讀取金鑰，金鑰因此不會進入對話。原本「重複呼叫的端點建成 `api_*` 工具」的建議已隨 API 工具移除於 v1.3.2 |
| `public_api_list` | ✓ | v1.3.2 起為內建工具（原為 API 工具 `api_public_api_list`）。公開 API 目錄：不帶 `category` 時回傳分類名稱；帶 `category`（不分大小寫，例如 `Weather`）時回傳該分類下每個 API 的名稱、說明、HTTPS 旗標與文件 URL。v1.3.8 起需求明確對應某分類時直接帶入該分類；分類不存在時回傳 `[Not found]` 並附完整分類清單；工具呼叫行顯示為 `API(<category>)`。目錄只收錄免金鑰的 API。用於沒有既有工具能處理的即時資料需求：選定 API → 以 `fetch_page` 讀其文件 → `http_request`；沒有合適的 API → `reasoning_guide(topics=["tool_generate"])`。上限 30 秒 |
| `download_file` | ✓ | 把 URL 下載到本地：二進位檔案原樣存檔（tar.gz、圖片、壓縮檔、安裝檔），或自 v1.3.6 起以帶著使用者 Chrome 登入狀態的瀏覽器渲染網頁，存成 `markdown`、`html` 或 `json`。`url` 與 `output_file` 必填；絕對路徑的 `output_file` 直接使用，相對路徑併入輸出目錄（`output_dir`，否則 `~/Downloads`，再否則 `~/.config/agenvoy/download/`，不是工作目錄），父目錄自動建立，既有檔案會被覆寫。`render`（v1.3.6 新增，預設 `false`）切換到瀏覽器路徑；`type`（v1.3.6 新增：預設 `markdown`，另有 `html`、`json`）只在 `render=true` 時生效。`timeout`（預設 120 秒，上限 600 秒）只套用於一般下載，渲染網頁時改用瀏覽器擷取本身的時限。只讀網頁不存檔 → `fetch_page`；JSON 或 API 回應 → `http_request` |
| `html_template` | ✓ | v1.0.17 新增。來自 `https://view.agenvoy.com` 的 HTML 頁面範例庫：`mode=list` 回傳每個範本的 `name`、`category`、`title`、`desc`；`mode=read` 依 `name` 回傳單一範本的完整 HTML。在 `reasoning_guide(topics=["html_render"])` 之後建構 HTML 產出時使用，完成後以 `write_result(format="html")` 存檔。取代過去以 `http_request` / `fetch_page` 讀取同一範例庫的做法。其他網頁 → `fetch_page`。上限 30 秒 |

`run_websocket`（v1.3.0 新增）已移除於 v1.3.2，沒有替代工具；單次請求 → `http_request` 或 `fetch_page`。