agents-cli 是 Google 推出的指令列工具，讓開發者透過編碼代理（如 Antigravity、Claude Code、Codex）建立、評估並部署 AI 代理專案。這篇 agents-cli 教學 會帶你走過安裝、初始設定到第一個範例的完整流程。

查看相關日報

AI 代理開發常卡在同一個地方：模型寫得出來，但整合進實際應用、穩定上線卻很花時間。手動寫基礎設施程式碼、設定雲端環境、處理部署腳本，這些步驟本身就佔掉大半開發時間。

agents-cli 想解決的正是這一段。根據官方說明，它是「你的編碼代理用來交付代理的 CLI」——不是聊天機器人本身，而是開發者拿來建構、測試、部署這些代理的工具。無論你慣用 Antigravity、Claude Code 或 Codex，都能透過它完成專案骨架建立（Scaffold）、真實信號評估（Evaluate），最後部署到 Google Cloud 的 Agent Runtime、Cloud Run、GKE，或其他環境。

agents-cli 是什麼？核心概念與定位

官方將 agents-cli 定義為「你的編碼代理用來交付代理」的指令列工具。這句話拆開來看，代表它的使用者不是最終使用者，而是開發者與開發者手上的編碼代理——工具設計上假設操作者是 AI 輔助的編碼流程，而非人類手動逐行下指令。

根據官網 Product Hunt 頁面的說明，agents-cli 的核心功能圍繞三個動作：

第一，建立專案骨架。一個指令生成生產環境等級的專案結構，省去手動配置的步驟。第二，執行評估。在部署前用「真實信號」測試代理行為，確認邏輯是否符合預期，而不只是程式碼能跑而已。第三，部署上線。支援推送到 Agent Runtime、Cloud Run、GKE，官方也稱可以部署到其他任意環境。

這套工具的設計理念是「讓工具配合開發者」，而不是反過來。你不需要為了用 agents-cli 改變原本的編碼習慣或工具鏈，它是嵌進你既有的編碼代理工作流裡運作的一層。

事前準備：環境安裝與需求檢查

開始 agents-cli 教學 前，先確認環境是否符合基本需求。

官方支援平台為 CLI（指令列環境），實際支援的作業系統版本、記憶體需求、Node.js 或 Python 版本要求，目前並無官方公開資訊可查證，請以官方網站或 GitHub 頁面的說明為準，安裝前先確認清楚，避免因版本落差導致依賴套件安裝失敗。

在開始安裝前，你需要具備能執行 npm 或 pip 指令的環境。若計畫使用 Google Cloud 的部署功能（Agent Runtime、Cloud Run、GKE），也需要先準備好對應的 Google Cloud 帳戶與權限。

小提醒：安裝過程中工具可能需要從遠端下載依賴套件，建議先確認網路連線穩定，避免中途安裝失敗。

Step 1：安裝 agents-cli 與初始設定

步驟 1.1：使用套件管理工具安裝

多數開發者會用 npm 或 pip 安裝。實際安裝指令、套件名稱與版本號，請以官方 GitHub 頁面或官網文件公告為準，安裝前務必核對清楚，避免執行到錯誤或過時的指令。

安裝完成後，可透過查詢版本號的方式確認安裝是否成功，具體指令請參考官方文件。

步驟 1.2：首次執行與環境變數配置

首次執行 agents-cli 時，工具通常會需要初始設定，包含環境變數（如 API 金鑰、雲端專案 ID）。這部分請依照官方文件的初始化步驟操作，並將包含金鑰的設定檔妥善保管，不要上傳到公開的 GitHub 倉庫。

步驟 1.3：中文介面支援程度

agents-cli 是否支援繁體中文介面切換，目前沒有官方公開說明可以確認。若你需要中文操作環境，建議先查閱官方文件是否有語言參數或 locale 設定選項；若未提供，多數 CLI 工具的核心指令仍需以英文操作，建議先熟悉基本指令的英文含義，避免卡在語言問題上反而拖慢學習進度。

注意：設定環境變數時，金鑰格式錯誤是常見的失敗原因。若遇到連接或部署錯誤，優先檢查金鑰格式與網路連線狀況。

Step 2：第一個實作範例：建立與執行代理

步驟 2.1：建立專案與撰寫代理邏輯

根據官方說明，agents-cli 的核心流程是「Scaffold（建立骨架）→ Evaluate（評估）→ Ship（部署）」。實際的建立專案指令、資料夾結構與檔案命名規則，請以官方文件為準；不同版本的 CLI 可能有不同的指令名稱與參數。

以下是一個簡化的代理邏輯範例，用來說明「代理任務腳本」大致長什麼樣子，實際專案結構仍需依官方文件調整：

# 簡單的代理邏輯範例
def run_agent(task):
這裡定義你的代理核心邏輯
print(f"正在處理任務：{task}")
return f"任務 {task} 已完成"
if __name__ == "__main__":
result = run_agent("資料分析")
print(result)

步驟 2.2：執行評估與監控輸出

寫好代理邏輯後，依照官方文件執行評估流程。評估階段會針對「真實信號」測試代理行為，執行過程通常會即時輸出日誌，包含執行狀態與錯誤訊息，這部分請留意終端機輸出內容，確認代理是否如預期處理任務。

步驟 2.3：確認執行結果

若評估過程沒有錯誤訊息，且代理回傳了預期結果，代表這一輪測試通過。若出現錯誤，先檢查腳本邏輯與設定檔，多數問題都出在這兩個地方。

小提醒：評估階段可能需要下載模型權重或相關依賴，若下載異常緩慢，先排查網路狀況，而非直接懷疑工具本身有問題。

Step 3：定價與效能：目前能確認的資訊

步驟 3.1：定價模式

agents-cli 的官方定價資訊目前未公開，或截稿時無法確認完整內容。Product Hunt 頁面標示為「Free」，但這不代表所有進階功能或雲端部署資源都不需要額外付費——尤其是透過 Google Cloud 部署後，Cloud Run、GKE 等服務本身可能會依 Google Cloud 的計費規則產生費用。建議實際使用前，先查看官網 Pricing 頁面，確認免費額度、專案數量限制與付費項目的界線。

步驟 3.2：效能優化建議

在缺乏官方公開的效能規格前提下，以下是一般性的優化方向，不代表 agents-cli 官方承諾的效能表現：

保持代理腳本邏輯精簡，減少不必要的重複運算；若任務有重複執行的情況，留意工具是否提供快取機制（需查官方文件確認）；在腳本中加入錯誤處理，讓代理遇到異常時能回傳明確訊息，而不是直接中斷。

步驟 3.3：實測資料

目前沒有公開、可查證的 agents-cli 效能 Benchmark 數字。建議你在自己的專案中實際測試執行時間與準確性，並與既有的手動部署流程做對比，這樣得出的資料才貼近你實際的使用情境，也比網路上未經驗證的數字可靠。

常見問題 FAQ

agents-cli 完全免費嗎？

Product Hunt 頁面上標示為「Free」，但官方完整的定價模式、是否有付費方案、免費額度上限等資訊目前未公開。實際使用時，透過 Google Cloud 部署的資源（如 Cloud Run、GKE）通常會依 Google Cloud 本身的計費規則另外計費，建議先查看官網 Pricing 頁面確認完整費用結構。

遇到中文編碼錯誤如何解決？

先確認終端機編碼設定為 UTF-8，並確保腳本與設定檔皆以 UTF-8 格式儲存。若問題持續發生，可查閱官方文件是否提供編碼相關參數；不同版本工具的參數命名可能不同，建議以官方最新文件為準，而非套用未經確認的指令參數。

如何整合現有開發流程？

agents-cli 的設計目標是搭配編碼代理（如 Antigravity、Claude Code、Codex）使用，理論上可以整合進 CI/CD 流程中執行 Scaffold、Evaluate、Ship 三個階段。實際整合方式、支援的 CI/CD 平台與指令參數，請以官方 GitHub 頁面的說明為準，避免自行猜測指令格式導致流程中斷。

下一步：延伸學習與資源

這篇 agents-cli 教學 涵蓋了安裝、初始設定與第一個範例的基本流程。要深入了解自訂評估指標、多代理協作或雲端部署細節，建議直接查閱 agents-cli 的官方 GitHub 頁面與官網文件，掌握最新且最準確的資訊——CLI 工具的指令與參數變動速度快，官方文件永遠是最可靠的依據。

免責聲明：本文依官方公開資料整理撰寫，非合作推廣。工具品質與安全性請讀者自行評估，使用前建議查證官方最新資訊。