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

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

只要搭配使用 Agents CLI 和偏好的 AI 輔助開發人員工具 (例如 Gemini CLI、Claude Code 或 Codex)，就能透過自然語言提示詞定義、在本機測試，並將原型代理部署至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，將預設代理程式替換為原始人壓縮器邏輯。這項工作會運用 google-agents-cli-adk-code 技能，瞭解 ADK 設計模式。

產生的代理定義大致如下：

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 開發人員工具提供修正意見。例如：

問候測試的回應太過禮貌。Make it more brusque.

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 呼叫和工具執行的 span。

如要啟用更詳細的觀測能力，請指示 AI 開發人員工具：

Set up observability infrastructure for my agent.

您的 AI 開發人員工具會佈建服務帳戶、Cloud Storage bucket 和 BigQuery 資料集，並更新已部署的服務，以便使用這些資源。詳情請參閱觀測能力指南。

動作摘要

下表彙整提示和 AI 開發人員工具執行的對應動作：

使用者操作說明 AI 開發人員工具動作
「建構原始人壓縮器代理」 建構專案、編寫代理程式碼、在本機測試。
「編寫並執行評估」 建立評估集、設定 LLM-as-judge，並執行 agents-cli eval run。
「將這個項目部署至 Cloud Run」 新增部署目標設定，部署至 Cloud Run。
「設定觀測能力」 佈建服務帳戶、Cloud Storage bucket 和 BigQuery 資料集。

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

後續步驟

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

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

進一步瞭解 Agent Platform：