在 Agent Platform 中，使用 ADK 和 Agents CLI 建構代理

本文說明如何使用 Agent Development Kit (ADK) 和 Agent Platform 中的 Agents CLI，建構、評估及部署 AI 代理原型。ADK 是以程式碼為優先的開放原始碼框架，用於建構精密的 AI 代理。Agents CLI 提供統一的機器可讀介面，供 AI 開發工具與 ADK 互動，實現端對端代理生命週期管理。這項工具封裝了 ADK、代理評估和部署的專業知識，可讓 AI 開發工具根據自然語言提示詞執行複雜動作。Google Cloud

搭配您偏好的 AI 輔助開發工具 (例如 Gemini CLI、Claude Code 或 Codex) 使用 Agents CLI，即可透過自然語言提示定義代理程式、在本機測試，並將原型代理程式部署至Google Cloud 執行階段。

本教學課程會引導您建立「洞穴人壓縮器」代理程式，將冗長的文字轉換為簡潔的摘要，靈感來自洞穴人。

事前準備

完成下列必要條件：

  1. 請確認您有 Google Cloud 專案，且已啟用 Agent Platform API。 如果還不熟悉，請完成下列其中一個快速入門導覽課程：

  2. 安裝 AI 輔助開發工具，例如 Antigravity、Gemini CLI、Claude Code 或 Codex。這是與 Agents CLI 互動的必要工具。

設定

  1. 安裝 Python 套件安裝程式 uv。如需操作說明，請參閱 uv 安裝指南。

  2. 使用 uvx (隨附於 uv) 執行 Agents CLI 設定指令。這是您直接執行的唯一 Agents CLI 指令：

    uvx google-agents-cli setup

  3. 開啟 AI 開發工具，例如 Antigravity。

Scaffold 專案

使用下列提示指示 AI 開發工具：

Use agents-cli to build an agent that compresses verbose text into concise, caveman-style summaries.

AI 開發工具會啟用 google-agents-cli-workflow 和 google-agents-cli-scaffold 技能。這個指令會執行下列動作：

  • 提出釐清問題，例如部署目標和安全限制。
  • 撰寫 DESIGN_SPEC.md 檔案，擷取代理程式的用途。

  • 架構專案：

    agents-cli create caveman-agent --prototype --yes
cd caveman-agent && agents-cli install

這個程序會建立專案，其中包含樣板代理程式碼、測試和評估集。

建構代理

AI 開發工具會編輯 app/agent.py，以洞穴人壓縮器邏輯取代預設代理程式。這項技能會運用 ADK 設計模式。google-agents-cli-adk-code

產生的代理程式定義如下所示：

root_agent = Agent(
   name="caveman_agent",
   model=Gemini(model="gemini-3.5-flash"),
   instruction="""You are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules:
   - Omit articles, filler words, and politeness.
   - Use short sentences and simple words.
   - Preserve technical terms.
   - The tone should be abrupt and funny, but the core meaning must be retained.

   Example input:  "I would like to deploy the application to production environment."
   Example output: "Me deploy. Production. Now."
   """,
)

接著，AI 開發工具會執行基本功能測試：

agents-cli run "Please help me understand the deployment options available for my project"

這項測試的預期輸出內容如下：

「部署選項：Agent Runtime、Cloud Run、GKE。請選擇其中一個。Ship」。

評估代理

如要評估代理，請對 AI 開發工具下達下列提示：

Write evaluations for the caveman agent and run them.

AI 開發工具會啟用 google-agents-cli-eval 技能，並執行下列工作：

  • 建立tests/eval/evalsets/caveman.evalset.json，其中包含壓縮品質、技術用語保留和語氣等測試案例。
  • 在 tests/eval/eval_config.json 中設定 LLM 做為評估標準的條件。

  • 執行評估作業：

    agents-cli eval run

如果測試案例失敗，請向 AI 開發工具提供修正意見回饋。 例如：

問候測試的回覆過於客氣。語氣要更生硬。

AI 開發工具會調整代理的指令、重新執行 agents-cli eval run，並反覆運作，直到達到所需品質為止。

部署代理

如要在 Google Cloud上部署及執行代理程式，請按照下列指示操作 AI 開發工具：

Deploy this agent to Cloud Run.

AI 開發工具會啟用 google-agents-cli-deploy 技能，並執行下列操作：

  • 新增必要的部署基礎架構設定：

    agents-cli scaffold enhance --deployment-target cloud_run

  • 部署代理程式：

    agents-cli deploy

代理程式現已部署至 Cloud Run。輸出內容會包含服務網址，您可透過該網址存取代理程式。

觀察代理

Cloud Trace 預設為啟用。如要查看追蹤記錄，請在 Google Cloud 控制台中開啟 Cloud Trace 探索工具，然後將要求傳送至已部署的代理程式。您會看到 LLM 呼叫和工具執行的範圍。

如要啟用更詳細的可觀測性，請指示 AI 開發工具：

Set up observability infrastructure for my agent.

AI 開發工具會佈建服務帳戶、Cloud Storage 儲存空間和 BigQuery 資料集，並更新已部署的服務，以使用這些資源。詳情請參閱可觀測性指南。

動作摘要

下表列出提示，以及 AI 開發工具執行的對應動作：

使用者操作說明 AI 開發工具動作
「Build a caveman compressor agent」(建立穴居人壓縮機代理程式) 搭建專案架構、編寫代理程式碼，並在本機進行測試。
「Write evals and run them」(撰寫並執行評估) 建立評估集、設定 LLM 做為評估者，並執行 agents-cli eval run。
「Deploy this to Cloud Run」(將這個項目部署至 Cloud Run) 新增部署目標設定，並部署至 Cloud Run。
「設定可觀測性」 佈建服務帳戶、Cloud Storage bucket 和 BigQuery 資料集。

Agents CLI 技能會為 AI 開發工具提供必要的脈絡，以便使用適當的 ADK 模式、評估結構，以及設定部署作業。

後續步驟

使用下列提示探索更複雜的代理程式設計：

  • 新增工具：「整合 Google 搜尋工具，讓代理程式可以存取最新資訊。」
  • 多代理系統：「使用 adk_a2a 範本建立可與其他代理互動的代理。」
  • RAG：「使用 agentic_rag 範本，根據我們的說明文件建立代理程式，回答問題。」

進一步瞭解 Agent Platform：