# 工具擴充

Agenvoy 支援四種在內建集合之外新增工具的方式：從 capability gap 自動生成、script tool、API tool 與 MCP tool。由 extension 安裝的工具落在 `~/.config/agenvoy/tools/.extension/`，並以 `ext_` 前綴註冊。

## 自動生成（Capability Gap）

當 user request 需要即時外部資料（天氣、匯率、股票、geocoding、翻譯等）且無現有 tool 涵蓋時，agent 當場建立該 tool，隨即執行以回答。無需寫程式。

`reasoning_guide(topics=[tool_generate])` 承載建置契約（v1.0.26 起此工具改收 `topics` 陣列，一次呼叫可載入多份 guide；之前為單一 `topic`）；同一份文字也透過 MCP server 以 `tool_generate_guide` 對外部 agent 曝露。序列如下：

| 步驟 | 動作 |
|---|---|
| 1. 找到合適的 API | `api_public_api_list(type=category)` 挑選相關類別，選出最佳候選（偏好 no-auth + HTTPS），再 `fetch_page` 文件 |
| 2. 決定工具型態 | 多步驟邏輯或需運算 → script tool（`tool.json` + `script.py`）；單一 REST 端點且無運算 → API tool（單一 JSON） |
| 3. 寫入 | `edit_tool(mode=write)` 搭配 `tag=json` + `tag=script`，或宣告式的 `tag=api` |
| 4. 驗證 | `test_tool` 於沙箱執行 `script.py`；失敗以 `edit_tool(mode=patch)` 修正 |
| 5. 回答 | 呼叫新工具，並以其輸出回答 |

建立後，工具持久化於 `~/.config/agenvoy/tools/script/<name>/`（或 `tools/api/<name>.json`），在所有未來 session 及所有連線的 MCP agent 中皆可用。憑證絕不硬編碼：命名慣例為 `{BRAND}_API_KEY`，以 `store_secret` 取得。本機金鑰查詢端點 `GET /v1/key?key=<KEY_NAME>` 已於 v1.0.23 移除：script tool 改為自行讀取（guide 提供的 `get_key()` helper），順序為 OS keychain（service `agenvoy`）→ Linux 上的 `~/.config/agenvoy/.secrets` → 同名環境變數；API tool 則在 `auth.env` 指定 key 名，由 runtime 解析。

關鍵限制：

- agent 絕不可用裸 `http_request` 或 inline `python3 -c` 回答資料請求；必須將可重用工具寫入磁碟。v1.0.23 起一次性的驗證或除錯（探測端點、參數或旗標）為例外：透過 `run_command` inline 執行，不存成工具
- `fetch_page` 僅允許用於讀取 API 文件，不用於抓取回答資料
- 名稱採 `snake_case` 動詞 + 名詞（`fetch_weather`、`calculate_rsi`）且不帶前綴——runtime 會自動加上 `script_` 或 `api_`

## Script tool（`script_*`）

在 `~/.config/agenvoy/tools/script/<name>/`（或專案本地的 `<cwd>/.config/agenvoy/tools/script/<name>/`）放入 `tool.json` descriptor 與 `script.py`（Python）或 `script.js`（JavaScript）。Agenvoy 自動註冊為 `script_<name>`。原本的 `extensions/scripts/<name>/` + `run.py` 佈局不會被掃描；由 extension 安裝在 `tools/.extension/script/` 的 script 以 `ext_<name>` 註冊。

```
~/.config/agenvoy/tools/script/my_tool/
├── tool.json     # name, description, parameter schema
└── script.py     # actual script (or script.js)
```

## API tool（`api_*`）

在 `~/.config/agenvoy/tools/api/<name>.json`（或專案本地的 `<cwd>/.config/agenvoy/tools/api/`）放入描述 REST 端點的 JSON 檔。它自動註冊為 `api_<name>`。`extensions/apis/*.json` 則編譯進 binary 作為內建 API tool（例如 `public-api-list.json` → `api_public_api_list`）。

**Confirm gate** —— `api_*` tool 不因前綴而豁免確認。使用者可能定義破壞性 endpoint（DELETE / POST 寫入），因此除非 descriptor 設定 `"always_allow": true`，每次呼叫都依當前權限模式確認。需要批次自動核准時，開啟 auto 模式（`Shift+Tab`）或在請求帶上 `allow_all: true`。

## MCP tool（`mcp__*`）

由 MCP server 曝露的 tool 自動註冊為 `mcp__<server>__<tool>`。MCP tool output 每次呼叫上限 **1 MiB**，以將 tool result 保持在 provider 限制內。