v1.3.11
首頁 GitHub

自建 AI 工具

最後更新


Agenvoy 支援三種在內建集合之外新增工具的方式：從 capability gap 自動生成、script tool 與 MCP tool。使用者自訂的 API tool 已移除於 v1.3.2（見下文）。由 extension 安裝的工具落在 ~/.config/agenvoy/tools/.extension/，並以 ext_ 前綴註冊；v1.3.2 起只來自 script。

自動生成（Capability Gap）


當 user request 需要即時外部資料（天氣、匯率、股票、geocoding、翻譯等）且無現有 tool 涵蓋時，agent 先查找免金鑰的公開 API 並直接呼叫，只有在目錄中沒有合適的 API 時才當場建立 script tool，隨即執行以回答。無需寫程式。自 v1.3.1 起，設定 decision model 時每輪會先問它：這個需求是否需要現有工具名稱都沒涵蓋的能力 —— 對週期性即時資料而言，http_request、run_command、fetch_page、search_web 這類通用工具不算涵蓋；以 0.7 以上信心判為缺少時，turn context 會帶一行 Tool gap，要求 agent 在任何其他工具前先呼叫 reasoning_guide(topics=["tool_generate"])。reasoning_guide 或 edit_tool 被排除時不做此檢查。
reasoning_guide(topics=[tool_generate]) 承載建置契約（v1.0.26 起此工具改收 topics 陣列，一次呼叫可載入多份 guide；之前為單一 topic）；同一份文字也透過 MCP server 以 tool_generate_guide 對外部 agent 曝露。序列如下：
步驟動作
1. 找 APIpublic_api_list() 取得分類名稱 → 挑選最多 3 個相關分類 → 逐一呼叫 public_api_list(category)；列出的 API 皆免金鑰，偏好 HTTPS
2. 有合適的 API以 fetch_page 讀取候選的文件 URL，確認 base URL、端點、參數與回應格式 → http_request（依答案需要呼叫多次）→ 回答。不建工具；下次同樣走這套流程
3. 建 script tool只在公開目錄之外：使用者提供、需要金鑰的 API（沙箱內的 get_key() 讓金鑰不進入對話，放在 http_request headers 則會進入），或 Python（stdlib、公開資料檔、套件）能產出答案。edit_tool(mode=write) 搭配 tag=json + tag=script
4. 驗證test_tool 於沙箱執行 script.py；失敗以 edit_tool(mode=patch) 修正後重測（最多重試 3 次）
5. 回答呼叫新工具，並以其輸出回答；既無 API 也無 Python 途徑時，退回 search_web / fetch_page，並說明資料來源

v1.3.2 之前，步驟 1 呼叫 API tool api_public_api_list(type=category)，步驟 2 可為單一 REST 端點選擇宣告式 API tool（tag=api）；兩者皆已移除於 v1.3.2。
建立後，工具持久化於 ~/.config/agenvoy/tools/script/<name>/，在所有未來 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 → 同名環境變數。
關鍵限制：
  • 自 v1.3.2 起，免金鑰的公開 API 直接以 http_request 回答，不存成工具；原本「每個資料請求都必須以寫入磁碟的可重用工具回答」的規則已移除於 v1.3.2。只有走 script tool 路徑（步驟 3）時才寫入工具。一次性的驗證或除錯（探測端點、參數或旗標）透過 run_command inline 執行，不存成工具
  • fetch_page 用於讀取 API 文件；只有在既無 API 也無 Python 途徑的退路中，才與 search_web 一起抓取回答資料，並註明來源
  • 名稱採 snake_case 動詞 + 名詞（fetch_weather、calculate_rsi）且不帶前綴——runtime 會自動加上 script_

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> 註冊。
  1. ~/.config/agenvoy/tools/script/my_tool/
  2. ├── tool.json     # name, description, parameter schema
  3. └── script.py     # actual script (or script.js)

API tool（api_*）


使用者自訂的 API tool 已移除於 v1.3.2；請改以 http_request 呼叫端點，或改寫成 script tool。~/.config/agenvoy/tools/api/、專案本地的 <cwd>/.config/agenvoy/tools/api/ 與 tools/.extension/api/ 下的 JSON descriptor 不再載入：殘留的 .json 檔會逐一略過，並在 log 留下 [Invalid] api tool 警告。內建的 extensions/apis/ 也已不存在；其中的 api_public_api_list 改為內建工具 public_api_list —— 不帶 category 時回傳分類名稱，帶 category（不分大小寫）時回傳該分類下每個免金鑰 API 的名稱、說明、HTTPS 旗標與文件 URL。http_request 的 GET 不需確認即執行；其他 method 一律經過確認 gate。

MCP tool（mcp__*）


由 MCP server 曝露的 tool 自動註冊為 mcp__<server>__<tool>。v1.3.7 起每輪的 Tools 清單依 server 分組寫成 mcp__<server>__{a, b}，find_tools 與 run_tool 仍使用完整名稱；server 提供的 instructions 則渲染在主 system prompt 內，不再作為第二則 system message。MCP tool output 每次呼叫上限 1 MiB，以將 tool result 保持在 provider 限制內。
EN