# 內建工具

26 個工具一律註冊，Linux 上另加 `pkg_manage`；還有 4 個僅在前置條件存在時才出現（`generate_audio`、`generate_image`、`list_chatbot`、`send_to_chatbot`），內建工具合計 31 個。`find_note` 已於 v1.0.23 隨 operator notes 一併移除；session 的常駐指示改寫在該 session 的 role（`/role`）。涵蓋多個相關動作的工具改以 `mode` 參數區分，而非拆成多個名稱 —— `edit_file` 取代原本的 `write_file` / `patch_file` / `remove_file` / `restore_file`，`find_files` 取代 `list_files` / `glob_files` / `search_files`，其餘類推。

自 v1.0.27 起所有工具 —— 內建、`script_*`、`api_*`、`ext_*`、`mcp__*` —— 在第一輪就帶完整參數 schema，並依名稱排序，讓工具區塊在各輪之間逐 byte 相同、provider 的 prompt cache 持續命中。`AlwaysLoad` 旗標仍標在 15 個工具上（`ask_user`、`calculate`、`chat_history`、`edit_file`、`fetch_page`、`find_files`、`find_tools`、`http_request`、`read_files`、`reasoning_guide`、`run_command`、`run_skill`、`search_web`、`write_result`、`write_todo`），但已不影響送出內容；原本只有名稱與描述的 stub 已移除。`find_tools(mode=search)` 將命中的 schema 作為工具輸出回傳，而不在執行中途改動工具清單，以免破壞快取。例外是 `claude-code` provider（以 `agen --enable-claude-code` 啟用）：它只收到工具名稱與 `find_tools` 的完整 schema，呼叫其他工具前先透過 `find_tools` 取得 schema。

## 條件註冊

以下工具僅在前置條件存在時註冊，否則 LLM 完全看不到它們。

| 工具 | 併發 | 說明 |
|---|---|---|
| `generate_audio` | | 以已設定的 text-to-speech 模型朗讀文字，寫入 output 目錄（`output_dir`，未設定則 `~/Downloads`，再不然 `~/.config/agenvoy/download/`）；回傳存檔路徑而非音訊資料。自 v1.0.13 起會向 provider 要求 `opus`，副檔名依回傳的 MIME 決定（opus/ogg 為 `.ogg`，另有 `.mp3`、`.aac`、`.flac`，預設回退 `.wav`）—— 附加到 Telegram 對話的 `.ogg` / `.oga` / `.opus` 會以語音訊息而非檔案送出。`voice` 指定 provider 的聲音名稱（OpenAI 用 `alloy`、Gemini 用 `Kore`），留空則用 provider 預設。上限 5 分鐘。*（未選擇 text-to-speech 模型時排除 —— 以 `/model tts` 或 `POST /v1/model` `{tts}` 設定）* |
| `generate_image` | | 由文字生成圖片並寫入磁碟；提供參考圖時亦可用於編修。回傳存檔路徑而非影像資料。上限 15 分鐘。*（圖像產生器未設定時排除 —— 以 `/model` 或 `POST /v1/model` `{image}` 設定。自 v1.0.13 起該設定填的是 `provider@model` 形式的圖像模型，由各個握有憑證的 provider 以 image-only filter 探查，v1.0.18 起快取 15 分鐘；`codex` 仍為裸 provider 名稱，舊版存下的裸 provider 名稱也仍可解析）* |
| `list_chatbot` | | 列出指定平台的已授權對話（`platform=telegram` 或 `platform=discord`）。*（需 `telegram_enabled` / `discord_enabled` 旗標與 keychain 憑證同時具備）* |
| `send_to_chatbot` | | 以 `target_id` 發送格式化訊息到已授權對話。Telegram：HTML + transient client。Discord：markdown + transient client。平台格式規則寫在 channel 的 system prompt，不透過工具取得 |

## 動態工具群組

除了內建註冊表，另有四種前綴在呼叫時才解析：

| 前綴 | 來源 |
|---|---|
| `script_*` | script 工具目錄下生成的工具 —— `script.py` 在沙箱中執行 |
| `api_*` | 生成的 API 工具 —— 每個端點一份 JSON 描述檔 |
| `ext_*` | 擴充工具，可為 API 或 script 實作 |
| `mcp__*` | 已連線 MCP 伺服器所暴露的工具 |

RAG 是透過這個途徑而非內建工具接入：KuraDB 以一般 MCP 伺服器身分註冊，其 `list_rag` / `search_rag` 工具會以 `mcp__` 前綴出現，未註冊或未連線時則完全消失。