直覺式程式開發 AI 代理：使用 Agents CLI 和 ADK 2.0 管理代理生命週期

1. 總覽

這個實驗室是 Kaggle「5-Day AI Agents: Intensive Vibe Coding Course with Google」的一部分。如需其他程式碼研究室和資源，請前往活動網站。

在本程式碼研究室中，您將瞭解如何使用 Agents CLI 管理 AI 代理的完整本機開發生命週期。無論您是包裝現有的 Gemini 模型，還是使用 Agent Development Kit (ADK 2.0) 從頭建構自訂代理，Agents CLI 都提供相關工具，可在本機架構、建構、檢查及測試代理。

課程內容

• 如何安裝及設定 agents-cli 和相關技能。
• 如何架構新的代理程式專案。
• ADK 2.0 圖表工作流程代理程式專案的結構和重要檔案。
• 如何執行自動 Lint 檢查和程式碼清理作業。
• 如何啟動及使用本機網頁遊樂區，透過自動重新載入功能進行互動式測試。

需求條件

• Python 3.11 以上版本
• uv 套件管理工具
• Node.js 18 以上版本 (如要使用程式設計代理程式技能)
• Antigravity IDE (從 Google Antigravity 安裝及設定)

必要條件

本程式碼研究室假設您熟悉下列項目：

• 使用終端機和指令列。

無須具備 AI 代理或 ADK 2.0 相關經驗！

2. 設定驗證和環境

提供驗證憑證，讓代理程式呼叫 Gemini 模型。

選項 1：Gemini API 金鑰 (Google AI Studio)

如果您使用標準 Gemini API 金鑰 (可從 Google AI Studio 取得)，請在 IDE 終端機工作階段中匯出：

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

選項 2：Google Cloud 應用程式預設憑證

如果您在 Google Cloud 上使用 Vertex AI，請使用 Google Cloud 應用程式預設憑證 (ADC) 進行驗證，並設定有效的 Google Cloud 雲端專案：

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. 設定 Agents CLI 和技能

第一步是安裝 agents-cli 工具。這項工具可處理代理程式專案管理的大部分工作。

Antigravity 使用者注意事項：在本程式碼研究室中，Antigravity 可能會在執行指令或編寫程式碼前，產生實作計畫或顯示彈出式視窗。請務必檢查並核准這些計畫或彈出式視窗，允許 Antigravity 繼續執行工作。

配額提示：如果在測試或開發期間用盡配額，可以在 Antigravity 中將模型切換為其他可用模型。

安裝 Antigravity 後，直接在終端機中執行設定指令。

👉 開啟終端機並執行：

uvx google-agents-cli setup

這項指令會自動安裝下列項目：

1. 系統上的 Agents CLI 工具。
2. 七項領域專屬的程式碼助理技能，可供 Antigravity 用來協助您建構、架構、評估及部署代理程式。這些技能會全域安裝到 ~/.agents/skills/，並由 Antigravity 自動探索。

注意：技能會安裝到 ~/.agents/skills/，並由 Antigravity 自動選取。您可以使用 /skills 指令或 Antigravity 設定進行驗證。

預期輸出內容 (經過修剪)：

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. 建立代理專案

在本節中，您將使用原型範本建立完整結構化的專案目錄。

👉 提示 Antigravity：

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity 會自動執行架構指令 (agents-cli scaffold create customer-support-agent --prototype --yes)，並為您設定專案檔案。

反重力提示：反重力一開始可能只會提供實作計畫。如果是這樣，請務必點選或輸入「繼續」來執行計畫。請仔細閱讀輸出內容，並決定是否需要進一步提示反重力，因為反重力可能未完全達到以下預期輸出內容。

5. 探索代理程式碼

👉 要求 Antigravity 解釋生成的程式碼：

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

在 Antigravity IDE 中，新建立的專案檔案和構件會直接顯示在輔助窗格 (左側)。您可以在該處查看，或從 IDE 檔案總管開啟，探索架構程式碼。app/agent.py

注意：您現在看到的是 Antigravity 剛建立的代理程式碼。由於 Antigravity 會動態產生實作項目，因此 app/agent.py 檔案中的程式碼結構或格式可能與下方的範例程式碼片段不同。每個使用者的代理程式看起來會略有不同，但應會共用相同的主要概念。如果您覺得產生的指令碼不夠完善或缺少功能，請記住，您可以繼續提示 Antigravity 疊代及修正程式碼！

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

核心概念

• 工作流程和邊緣：在 ADK 2.0 中，代理程式應用程式會使用 Workflow 編排為圖表。edges 清單會定義執行流程，將節點從 START 鏈結在一起，並根據路徑啟用條件分支 (例如，在 "shipping" 上轉送至 faq_agent，或在 "unrelated" 上轉送至 handle_unrelated)。
• LlmAgent：定義 LLM 輔助工作的宣告式節點，包含特定指令、模型和結構化輸出內容 (output_schema)。
• 節點和內容：以 @node (或標準函式) 修飾的 Python 函式，可執行邏輯、透過 Context 存取執行狀態，並產生 Event 物件，以便在圖表中傳遞資料和路徑信號。
• 模型：`gemini-3.1-flash-lite' 是預設的快速推論模型。
• 應用程式包裝函式：頂層 App 物件會包裝根工作流程。透過這個標準化 app 介面，本機遊樂區、ADK 評估架構和 Agent Runtime 等外部工具，都能探索及執行工作流程。

6. 自動 Linting

執行或測試代理程式前，建議先確認程式碼乾淨且格式正確。

👉 提示 Antigravity：

Run linting on my agent project to verify its health.

Antigravity 會在幕後執行 agents-cli lint，以執行預先設定的檢查，驗證檔案中的匯入項目、語法和格式一致性。

7. 使用 Playground 進行互動式測試

如要快速驗證代理程式的行為，最簡單的方法就是使用本機網頁遊樂場。這個介面提供互動式聊天功能，方便您與代理對話，並即時檢查工具執行作業。

👉 提示 Antigravity：

Launch the local development playground for my agent.

Antigravity 會啟動本機開發伺服器 (agents-cli playground)。在網頁瀏覽器中開啟提供的網址 (通常是 http://127.0.0.1:8080/dev-ui/?app=app)，從下拉式選單選取 app 資料夾，即可開始與代理程式對話。

在網頁介面中與服務專員開始對話。請嘗試詢問運送相關問題：

How much is standard shipping?

請注意，工作流程會成功分類並轉送至 faq_agent 回答。此外，請嘗試詢問不相關的問題，確認工作流程會轉送至 handle_unrelated，並正確拒絕回答：

What is the weather like?

測試即時自動重新載入功能

您可以查看對代理程式的即時編輯內容，如何反映在 Playground 中。

1. 在 app/agent.py 中修改 faq_agent 指示，方法是詢問 Antigravity：

   Modify the faq_agent instruction in app/agent.py to make the shipping rates
   response more playful and enthusiastic. Add some emojis and highlight the
   free shipping threshold.
   

2. 在 Playground 中傳送新訊息給代理程式，測試自動重新載入功能：

   How much is standard shipping?
   

   遊樂區會自動重新載入並即時執行更新後的程式碼，無須重新啟動伺服器！您現在應該會在回應中看到一些表情符號。

8. 執行指令列

如要進行快速測試、自動化或編寫指令碼，可以要求 Antigravity 直接從終端機執行代理程式。

👉 提示 Antigravity：

Run a CLI query asking my agent how long standard delivery takes.

Antigravity 會執行查詢指令 (agents-cli run "How long does standard delivery take?")。這項指令會執行快速的單輪推論，並輸出代理的最終回覆和工具執行詳細資料。

9. 清除

為避免在本地環境中留下不必要的資源，請按照下列步驟進行清除作業：

1. 停止本機伺服器：如果 agents-cli playground 伺服器仍在執行，請在終端機中按下 Ctrl + C 停止執行。
2. 移除本機專案檔案：從本機電腦刪除架構代理程式專案目錄。

rm -rf customer-support-agent

10. 摘要與後續步驟

恭喜！您已使用 Agents CLI 和 ADK 2.0，成功管理 AI 代理的端對端本機開發生命週期。

您學到的內容

• 設定工具：安裝 Agents CLI，並為 Antigravity 設定網域專屬的工作流程技能。
• 專案架構：使用標準化範本建立完整結構的 customer-support-agent 專案。
• 分析 ADK 2.0 結構：探索圖形工作流程、LLM 代理、節點、邊緣和條件式轉送。
• 代管的本機健康狀態：使用 agents-cli lint 執行自動程式碼品質檢查。
• 已驗證的行為：透過測試區以即時熱重載方式與代理程式互動，並在指令列上執行快速測試。

後續步驟

您已熟悉本機開發迴圈，現在可以擴展代理程式並投入生產：

• 評估：使用 agents-cli eval run 針對評估集評估代理，藉此評估準確度並找出迴歸問題。
• 企業雲端規模：部署和可觀測性：使用 agents-cli deploy 將代理程式封裝並部署至實際工作環境，例如 Agent Runtime 或 Cloud Run。設定實際工作環境遙測功能，將記錄和執行追蹤記錄串流至 Cloud Trace 和 BigQuery。

其他資源

• Agents CLI GitHub 存放區
• Agent Development Kit (ADK) 說明文件
• Agent Platform 總覽