Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 Agents CLI 將 ADK 代理部署至 Agent Runtime

1. 總覽

在本程式碼研究室中，您會將 ADK 2.0 代理從本機開發環境轉換為正式版部署項目。您將使用 agents-cli，在 Google Cloud 的 Agent Runtime 上封裝、驗證及代管以圖表為基礎的工作流程。

如要瞭解這項部署程序，請先從頭建構 Ambient Expense Agent 的本機原型，再將其部署至雲端。(如要深入瞭解如何設計這個代理程式的核心邏輯，請參閱 Kaggle 活動網站上的基礎程式碼研究室)。Ambient Expense Agent 可即時核准標準申請，並標記較大的支出以供人工審查，簡化員工費用報表流程。在幕後，這項功能會使用 ADK 2.0 圖表式工作流程，協調這些自動核准和風險分析步驟。

課程內容

如何準備本機 Ambient Expense Agent 專案，以便在雲端代管。
如何架構必要的部署描述元和生產包裝函式。
如何執行試運轉，並將程式碼直接部署至 Agent Runtime。
如何使用 Cloud Trace 監控正式版代理程式的執行追蹤記錄。

軟硬體需求

已啟用計費功能的有效 Google Cloud 專案。
已安裝並驗證 gcloud SDK。
已安裝 uv 套件管理工具。
已安裝 Google Antigravity IDE。

必要條件

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

使用終端機瀏覽系統。
Python 開發基本概念。
Google Cloud 基本概念。

2. 設定 Google Cloud 環境

部署前，請務必設定 Google Cloud 專案並啟用必要的 API。

👉 提示 Antigravity：

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Antigravity 執行這項提示時，會建議並執行必要的 gcloud 終端機指令，以設定專案並啟用服務。在驗證步驟中，Antigravity 會在終端機中顯示授權網址。按一下連結，透過網路瀏覽器登入並授予存取權。完成瀏覽器登入後，Antigravity 會繼續執行，設定專案環境變數並啟用必要 API。

3. 設定 Agents CLI 和 ADK Skills

為確保 Antigravity 能順利建構及部署 ADK 代理，需要 ADK 技能組合。這些是 ADK API、專案架構、agents-cli 部署工作流程和評估的組合參考資料。安裝 agents-cli 工具鍊時，這些技能也會一併安裝到程式碼編寫代理中，讓代理能夠管理完整生命週期，從本機架構到雲端部署作業都能一手包辦。

👉 將下列提示詞複製並貼到 Antigravity：

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Antigravity 執行這項提示時，會在終端機中執行 uvx google-agents-cli setup，安裝 CLI 和相關技能。接著執行 agents-cli info 驗證安裝作業，並直接在對話中列出新安裝的網域技能 (例如 google-agents-cli-deploy 和 google-agents-cli-workflow)。

4. 建立代理專案

設定雲端環境並安裝 CLI 技能後，即可為代理產生本機程式碼庫。在這個步驟中，您將使用 Antigravity 搭建與 ADK 2.0 相容的 Ambient Expense Agent 原型，並提供完整功能。

👉 提示 Antigravity：

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Antigravity 執行這項提示時，會運用新安裝的架構技能，在終端機中執行 agents-cli scaffold create expense-agent --adk。然後驗證及調整產生的原型程式碼，確保 expense-agent 在 Agent Development Kit (ADK) 圖形工作流程中，正確實作 $100 自動核准門檻和專人參與審查流程。

5. 準備部署至正式環境

Agent Runtime 是全代管的 Google Cloud 服務，可讓您在正式環境中部署、管理及調度 AI 代理。Agent Runtime 可處理主機的運作複雜性，並提供具狀態的環境，以及工作階段管理、長期記憶體和安全執行程式碼沙箱等功能。

為何要部署至 Agent Runtime？

使用 Antigravity 在本機建構代理程式時，代理程式會在您的本機電腦上針對 localhost 執行。雖然本機代理程式很適合快速原型設計，但只要關閉筆電，就會停止執行。

將代理部署至 Agent Runtime 後，工作流程就會移至全代管的 Google Cloud 環境，隨時都能運作。這會建立安全無虞的即時後端端點，並全天候保持運作。在下一個程式碼研究室中，您將建構直接連線至這個雲端端點的網頁前端，為代理程式提供公開網址。

此外，Agent Runtime 提供專為 AI 代理程式最佳化的專屬基礎架構，並內建下列功能：

受管理有狀態執行：內建工作階段管理功能，並在對話輪次中保留長期記憶。
安全沙箱：在隔離環境中安全執行動態工具呼叫和代理生成的程式碼。
企業級可觀測性：直接將遙測資料串流傳輸至 Cloud Trace 和 Cloud Logging。

如要在 Agent Runtime 上代管代理，您必須使用正式版描述元、結構定義和端點包裝函式，強化本機專案目錄。

👉 提示 Antigravity：

Scaffold the production deployment files for Agent Runtime.

Antigravity 執行這項提示時，會在專案根目錄中執行 agents-cli scaffold enhance --deployment-target agent_runtime --yes。這項指令會掃描目錄，並自動產生下列項目：

app/agent_runtime_app.py：適用於正式環境的服務包裝函式。
deployment_metadata.json：Agent Runtime 用於啟動資源的版面配置結構定義。

app/agent.py 中的核心代理程式邏輯完全不受影響。

6. 封裝和本機驗證

發起雲端上傳前，請鎖定套件並執行本機試運轉，找出潛在的依附元件衝突。

👉 提示 Antigravity：

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Antigravity 執行這項提示時，會先在終端機中執行 uv lock，產生確定性鎖定檔，確保雲端中的程式庫版本一致。接著執行 agents-cli deploy --dry-run，驗證設定是否有效，並預覽部署步驟，但不會佈建雲端資源。您可以在終端機中查看試執行輸出內容，確認所有檔案和設定都正確無誤。

7. 部署至 Agent Runtime

將 Ambient Expense Agent 部署至 Agent Runtime。

👉 提示 Antigravity：

Deploy this agent to Agent Runtime.

Antigravity 執行這則提示時，會啟用 google-agents-cli-deploy 技能並執行 agents-cli deploy --project YOUR_PROJECT_ID --region us-west1。封裝、上傳及佈建 Agent Runtime 的過程通常需要 5 到 10 分鐘。Antigravity 會在終端機中監控部署進度，完成後會顯示即時端點網址。

💡 專業提示 (管理逾時視窗)：如果不想在長時間部署期間鎖定終端機，可以指示 Antigravity 使用 --no-wait 旗標非同步啟動部署作業，並在稍後使用 agents-cli deploy --status 檢查進度。

8. 測試代理

部署代理程式後，您可以確認代理程式會自動核准小額支出，並適當標記較大金額的支出，以供專人驗證。

👉 提示 Antigravity 驗證已部署的引擎：

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

或者，您也可以使用 Cloud Console Playground 預覽版手動測試代理程式。如要開啟 Playground，請按照下列步驟操作：

前往 Google Cloud 控制台，依序選取導覽選單中的「Agent Platform」 >「Deployments」。
從部署清單中選取已部署的代理程式。
按一下「Playground」按鈕，開啟互動式測試對話介面。

👉 如要測試自動核准 (低於 $100)，請將下列 JSON 酬載貼到對話方塊中：

{"data": {"amount": 50.0, "submitter": "user@example.com", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

您應該會收到 JSON 回應，顯示 auto_approve 節點的輸出內容，狀態為「已核准」。

JSON 回應，顯示 $50 美元的費用已自動核准。

👉 如要測試人機迴圈 (HITL) 流程，請貼上下列 JSON 酬載。

{"data": {"amount": 150.0, "submitter": "user@example.com", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

這會觸發 review_agent、發出警告快訊，然後暫停執行作業，產生 RequestInput (Human-in-the-loop) 要求核准。

JSON 回應，要求提供 $150 美元費用的詳細資訊。

9. 監控及觀察正式版代理程式

使用 Agent Runtime 時，系統會自動連線遙測資料。每次互動、模型呼叫和工具執行作業都會將即時記錄和範圍串流至專案。

檢查追蹤記錄：開啟 Cloud Trace 控制台，稽核即時交易地圖、模型延遲和工具執行步驟。
稽核記錄：使用 Cloud Logging 檢查即時標準輸出和診斷堆疊追蹤。

Cloud Logging 控制台顯示已核准的 $50 美元費用。

匯總 Analytics：如果在架構期間啟用 --bq-analytics 標記，請使用 SQL 在 BigQuery 中查詢記錄，查看核准率和對話輪次趨勢。

以下 SQL 查詢提供計算核准率的範例。您可以提示 Antigravity，根據特定專案和 BigQuery 資料集自訂這項查詢：

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (選用) 在 Agent Registry 中驗證註冊

如要讓貴機構的其他服務、開發人員或代理安全地探索及使用費用代理，必須在企業 Agent Registry (Gemini Enterprise) 中註冊。

由於您已將代理部署至 Agent Runtime，因此系統會自動在 Agent Registry 中註冊該代理。日後在 Agent Runtime 中更新或刪除代理程式時，Agent Registry 也會自動同步。

👉 提示 Antigravity 驗證代理商的自動註冊：

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Antigravity 執行這項提示時，會在終端機中執行 agents-cli publish gemini-enterprise --list。這會查詢 Agent Registry，並列出專案中所有已註冊的 Gemini Enterprise 代理，方便您確認 Ambient Expense Agent 是否已啟用，且貴機構可搜尋到該代理。

11. 清理

如要避免 Google Cloud 帳戶持續產生費用，請在完成後關閉並清除已部署的資源。

👉 提示 Antigravity：

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Antigravity 執行這項提示時，會自動完成整個資源清除程序：

刪除已部署的代理：讀取 deployment_metadata.json 取得遠端代理執行階段 ID，然後以程式輔助方式從 Vertex AI 刪除即時引擎執行個體。
清理本機工作區：從專案根目錄移除過時的 deployment_metadata.json 檔案。
清理 Artifact Registry：執行 gcloud artifacts docker images delete 從 Artifact Registry 移除建構的容器映像檔，釋出雲端儲存空間。

12. 恭喜

恭喜！您已在 Google Cloud 成功部署及驗證生產環境適用的 Ambient Expense Agent。

您學到的內容

Google Cloud 設定：已設定專案憑證，並啟用必要的平台 API。
工具和技能：已安裝 agents-cli，並將 ADK 隨附技能載入 Antigravity。
正式環境架構：為 ADK 2.0 代理生成的 Agent Runtime 架構。
本機驗證：建立確定性鎖定檔 (uv lock) 並執行試運轉檢查。
雲端部署：在受管理的 Agent Runtime 基礎架構中，代管您的代理。
觀測能力與數據分析：在 Cloud Trace 中追蹤執行作業，並在 BigQuery 中分析遙測資料。
企業探索：在企業代理程式登錄服務中自動完成驗證和註冊。

後續步驟

執行 BigQuery 數據分析：在 BigQuery 中查詢代理程式的遙測記錄，分析一段時間內的核准率和對話輪次趨勢。
Vibe to Live Codelab：使用 Google Antigravity 在 Cloud Run 上開發前端用戶端，並直接連結至即時 Agent Runtime 後端端點。

贏得 Kaggle 5 天 AI 代理徽章 🎉

您是否已完成這項實驗室，並參加 Kaggle 的五天 AI 代理：Google 直覺式程式設計密集課程？領取完成徽章：

取得 5 天 AI 虛擬服務專員徽章