文件 v1.1.2
首頁 GitHub

REST API

·

Daemon 僅綁定 127.0.0.1:17989——區網 client 無法連到。Port 固定，不可設定。

同一個 daemon 在 / 提供 web 儀表板。儀表板在編譯時內嵌進執行檔，因此 http://127.0.0.1:17989 就是全部介面——沒有託管在外的前端。開發時可用 AGENVOY_PAGE_DIR 把內嵌版本換成磁碟上的檔案（make dev）。

自 v1.0.1 起儀表板可離線運作。GET /sw.js 提供 service worker，把內嵌資產預先快取到帶版本號的 cache；GET /vendor/* 則從 ~/.config/agenvoy/vendor/ 提供第三方資產（QuickUI、Font Awesome、Material Symbols，以及 nanomd／voice 腳本），該目錄由 daemon 啟動時下載一次，執行檔版本變動時重新下載。頁面載入不會向 CDN 取任何東西。在 AGENVOY_PAGE_DIR 模式下 /sw.js 改為提供一支自我卸載的 worker，清掉自己的 cache 並解除註冊，避免開發版被舊快取蓋掉。

標記 local 的端點另外要求請求來自 127.0.0.1/::1（localhostOnly() 守門）。這些端點管理憑證、設定檔或行程生命週期，設計對象是同機儀表板，不是遠端 client。未匹配的路由也套用同一道守門：未知的 /v1/ 路徑回 JSON 404，其他未知路徑則回退到儀表板首頁。

Agent 執行

Method 路徑 說明
POST /v1/send 執行一次 agent 請求
POST /v1/chat/completions 無狀態、相容 OpenAI 的 chat completion
GET /v1/info/version 編譯時寫入的版本（{version, dev}）；未打 tag 的組建 dev 為 true
GET /v1/log SSE 串流。不帶 query 時只送 daemon slog 記錄（EventDaemonLog frame，source 即 level）——與 TUI 標題列同一路資料。其中包含新對話驗證碼，因此 daemon frame 只提供給 loopback 呼叫端。?sessions=a,b 在同一條連線附加這些 session 的事件；replay=0 跳過回補、daemon=0 去掉 daemon frame。遠端呼叫端必須帶 sessions
GET /v1/daemon local — daemon.log 原始內容
GET /v1/system/update local — v1.0.11 新增。回 {version, latest, update_available}；latest 以追蹤 GitHub releases/latest/download/x 轉址取得（查不到時回 502 並附目前執行中的 version）
POST /v1/system/update local — v1.0.11 新增。開一個終端機視窗執行 agen update，回 202 {status:"opened"}；更新本身跑在該終端機內，不在 daemon 內。macOS 用 Terminal.app、WSL 啟動 Windows 終端機、Linux 依序嘗試 xdg-terminal-exec、x-terminal-emulator、gnome-terminal、konsole、xfce4-terminal、kitty、alacritty、wezterm、xterm。找不到可用終端機回 501
GET /v1/mcp/tools 列出已連線 MCP server 註冊進來的工具（mcp__*）

POST /v1/send 語意

Body 為 {content, session_id?, sse?, model?, skill?, work_dir?, system_prompt?, exclude_tools?, persist?}，content 必填。若 session 仍在執行中，新請求會以 steer 訊息附加到該次執行，而不是另起一次。

persist session_id 結果
false（預設） 空 建立 temp-<uuid>，30 分鐘無變動後刪除
true 空 建立 chat-<uuid>，保留
任意 有給 使用指定的 session_id（忽略 persist）

chat 旗標與 http- 前綴已於 v1.0.11 移除：以 HTTP 建立的持久 session 改用儀表板同樣的 chat- 前綴，所有非 CLI 的持久 session 統一成同一種前綴。既有的 http- session 仍可透過 session_id 指名繼續使用。

curl --fail-with-body -sS \
  -H 'Content-Type: application/json' \
  -d '{"content":"List the available tools","persist":false}' \
  http://127.0.0.1:17989/v1/send

/v1/chat/completions 為無狀態：需要延續脈絡時，每次請求都要帶上先前訊息。reasoning_effort 接受 none low medium high xhigh max（以及別名 minimal extra ultra）；省略或無法辨識的值會回退到該 session 的 reasoning 設定。

EN