2026 年 Next 大會開發人員主題演講：大規模偵錯代理程式

1. 簡介

在本程式碼研究室中，您將瞭解如何偵錯在 Google Cloud 上執行的 AI 代理程式。您將模擬器代理程式部署至 Agent Runtime、使用 Cloud Observability 偵測問題，並使用 Gemini Cloud Assist 和 Antigravity IDE 即時找出根本原因並修正錯誤。

本試用版的前提是，我們剛才已將 ADK EventCompaction 新增至模擬器代理程式。這樣一來，模擬器就能定期使用 Gemini 摘要說明工作流程，減少每次傳送至模型的總內容，進而提升回覆品質並降低總成本。不過，我們會發現 EventCompactionConfig 中有錯誤，導致代理程式發生錯誤！本程式碼研究室會逐步說明如何找出這類問題，並快速修正。

學習內容

• 將 Marathon Simulator Agent 部署至 Agent Runtime。
• 設定 Cloud Monitoring 快訊，偵測代理程式錯誤。
• 使用 Cloud Trace 和 Gemini Cloud Assist 找出錯誤。
• 使用 Antigravity 和 MCP 找出根本原因並修補代理程式。

注意：Gemini Cloud Assist 目前為不公開預先發布版，您不需要取得許可，即可執行本程式碼研究室的 Cloud Assist。所有 Cloud Assist 步驟都與「步驟 8 (選用)：使用 Cloud Assist Investigations」有關。如果您還無法存取 Cloud Assist，請略過這個頁面！

軟硬體需求

• 網路瀏覽器，例如 Chrome。
• 個人 Google 帳戶
• Antigravity (支援 Mac、Linux 和 Windows)
• Python 3.13 以上版本。
• uv (Python 套件管理員)

預估時間：45 分鐘

預估費用：不到 $5 美元

2. 事前準備

建立 Google Cloud 專案

1. 在 Google Cloud 控制台中，選取或建立 Google Cloud 專案。
2. 確認 Cloud 專案已啟用計費功能。

設定環境

開啟 Antigravity 並登入。接著按下 cmd-shift-P (或 ctrl-shift-P) 開啟「終端機」，然後輸入「Create New Terminal」(建立新終端機)。

1. 在終端機中，透過 Google Cloud 進行驗證：

gcloud auth login
gcloud auth application-default login

2. 設定專案 ID：

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

啟用 API

執行下列指令，啟用必要的 Google Cloud API：

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

如果您已加入 Gemini Cloud Assist (不公開預先發布版) 的許可清單，請啟用下列額外 API：

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. 設定模擬器代理程式

在這個步驟中，您將複製範例存放區，並為模擬器代理程式設定環境變數。

複製存放區

複製 next-26-keynotes 存放區，然後前往示範目錄：

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

設定環境變數

模擬器代理程式會使用 .env 檔案進行設定。

在 Antigravity 視窗左側 (Explorer) 找到 sample.env 檔案：

開啟 sample.env，並將 GCP_PROJECT_ID 欄位更新為實際的 Google Cloud 專案 ID。檔案應如下所示：

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

我們正在啟用 OpenTelemetry 整合，以擷取代理程式工具呼叫和推論流程的精細追蹤記錄。

4. 將模擬工具代理部署至 Agent Runtime

現在，您將使用 Agent Development Kit (ADK)，將代理部署至 Agent Runtime。

安裝依附元件

uv sync

部署至 Agent Runtime

1. 執行 adk deploy 指令。這個步驟會封裝代理程式，並部署至 Google Cloud (Agent Runtime)。

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

這項作業最多可能需要 5 分鐘才能完成。最終會看到類似以下的輸出內容：

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

記下產生的 Agent Runtime ID。稍後會用到！

2. 在網路瀏覽器中開啟 Agent Runtime 控制台。您應該會看到 simulator_agent 在 Agent Runtime 上執行，且遙測資料收集功能已啟用。

5. 設定快訊政策

如要自動偵測 Agent Runtime 錯誤，請在 Google Cloud 控制台中建立記錄快訊。

1. 前往「Cloud Monitoring - Alerting」(Cloud Monitoring 快訊) 控制台。

2. 按一下「編輯通知管道」。向下捲動至「電子郵件」類型，然後建立電子郵件通知管道，將通知傳送至您的個人電子郵件地址。按一下 [儲存]。

3. 返回「快訊」資訊主頁，然後按一下「建立政策」。
4. 按一下畫面右側的「建立以記錄為準的快訊」。

5. 系統會將您重新導向至「記錄檔探索工具」。貼上下列記錄查詢，並將 替換為您的專案 ID。

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

這項記錄查詢會在 Agent Runtime 代理程式中尋找 Error 記錄，其中 ReasoningEngine 是 Agent Runtime 的基礎 API 名稱。

6. 按一下 [Run query] (執行查詢)，您目前不會看到任何記錄，這是正常現象。
7. 在結果工具列中按一下「動作」，然後點選「建立記錄檔警告」。

8. 設定記錄型快訊。為快訊命名 (任何名稱皆可)，然後將嚴重性等級設為「錯誤」。

9. 按一下「設定通知頻率」部分的「下一步」 (保留預設值)。

10. 在「Who should be notified?」(應該通知誰？) 中，將快訊設為觸發剛設定的電子郵件通知管道 (即 My Email)。
11. 按一下 [儲存]。

6. 觸發事件

現在代理程式已部署並受到監控，讓我們嘗試以會擲回錯誤的方式叫用馬拉松模擬。

1. 在 Google Cloud 控制台中，前往「Agent Runtime」控制台。
2. 按一下 [simulator_agent]。
3. 按一下頂端工具列中的「Playground」。系統會啟動新的 ADK 代理工作階段。

4. 在工作階段即時通訊視窗中輸入 Test Simulation，然後按 Enter 鍵傳送提示。

系統會開始模擬馬拉松，追蹤數千名模擬跑者在規劃路線上的動態。您應該會看到對 get_runner_telemetry 和 analyze_medical_risk 的多個工具呼叫，因為模擬會評估賽事的「多個區域」。

幾分鐘後，您應該會看到代理程式停止執行，並未傳回任何回應。

5. 過一分鐘左右，您應該會在收件匣中看到一封電子郵件，通知您代理程式中發生新的事件。

按一下「查看事件」，開啟 Cloud Monitoring 控制台。前往下一頁，在 Play 管理中心調查問題。

7. 在控制台中調查事件

1. 在 Cloud Monitoring 控制台中查看事件。您應該會看到模擬器代理程式傳送的錯誤記錄。

從這個檢視畫面很難看出代理程式在哪個時間點發生錯誤。如要查看代理程式的基礎工具呼叫和推理流程，請檢查代理程式的追蹤記錄。

2. 再次開啟 Agent Runtime 控制台。點選「simulator_agent」，然後開啟「Traces」分頁。

3. 按一下清單中最新的追蹤記錄。然後按一下右上方的「時間軸」。您應該會看到含有個別「時距」的追蹤記錄檢視畫面。一個範圍代表代理程式工作流程中的模型或工具呼叫。

4. 在追蹤記錄檢視畫面中，按一下最後一個範圍。應為紅色。
5. 按一下「Stacktrace」。您應該會看到與 Gemini API 模型呼叫相關的錯誤記錄。具體來說，是 400: Invalid Argument 錯誤。這表示模擬器代理程式傳送至 Gemini API 的酬載有要求層級問題。

8. [選用] 使用 Cloud Assist Investigations 進行偵錯

只有在您已加入 Gemini Cloud Assist (不公開預先發布版) 的許可清單時，才需要按照下列步驟操作。否則，請前往下一頁。

1. 在失敗的範圍內，按一下「記錄和事件」。找到旁邊有閃亮按鈕的「例外狀況」記錄。然後按一下「Investigate Log」(調查記錄)。

2. 系統會在畫面右側的側欄啟動 Cloud Assist 調查。載入時間約需 3 至 5 分鐘。

3. 完成後，請開啟調查。

4. 查看「調查摘要」。

5. 向下捲動並查看「假設」。Gemini Cloud Assist 應該會找出 Simulator Agent agent.py 檔案中導致 Gemini API 400 錯誤的特定程式碼行。

讓我們開啟代理程式的原始碼，並使用 Antigravity 找出問題的根本原因。前往下一頁。

9. 使用 Antigravity 找出根本原因並修補問題

1. 重新開啟 Antigravity。
2. 開啟畫面右上方的「代理程式管理員」。

3. 確認模型已設為「Gemini 3 Flash」和「規劃」模式。

4. 輸入下列提示，然後按下 Enter 鍵。

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

您應該會看到 Antigravity 檢查 agent.py 中的程式碼，並在 GitHub 上搜尋相關問題：

Gemini API 400 錯誤的根本原因是，我們超過了 Gemini 3 Flash 的輸入脈絡權杖限制 (約 100 萬個)。發生這種情況的原因是，我們不常觸發 EventCompaction，因此無法有效摘要模擬器代理程式工具呼叫傳回的大量回應。

如要修正這個問題，Antigravity 應建議在 EventsCompactionConfig 中加入 token_threshold 參數，以便在達到特定詞元數量後，定期壓縮每次叫用中的內容。

這與這項 GitHub 問題中建議的修正方式一致。

將修正建議套用至 agent.py.

確認您看到類似下列內容：

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

請務必設定 token_threshold 和 event_retention_size！

10. 重新部署並驗證修正內容

現在我們已將 token_threshold 修復程式套用至 ADK 代理的 EventCompactionConfig，可以將模擬器代理重新部署至 Agent Runtime。

1. 開啟 Antigravity –>「New Terminal」(新增終端機)。
2. 設定環境變數。AGENT_RUNTIME_ID 應為 simulator_agent 的完整資源名稱。您可以在 Agent Runtime 控制台的代理程式清單中找到這項資訊。

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. 重新部署代理程式：

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

這項作業會在幾分鐘內完成。成功後，您應該會看到：

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. 開啟 Agent Runtime 控制台。重新開啟 simulator_agent。按一下「Playground」。
5. 輸入相同的提示：Test Simulation，然後按 Enter 鍵。
6. 完整的後端 Marathon 模擬作業應會在幾分鐘內執行完畢。您應該會看到多個工具呼叫。最終畫面應會顯示類似以下的回應：

這表示模擬器已順利執行！✅

7. 開啟該 ADK 工作階段的追蹤記錄檢視畫面。
8. 您應該會看到所有「藍色」跨度，且沒有紅色錯誤。請注意，工作階段的詞元總數超過 Gemini API 的脈絡詞元上限 (100 萬個)。沒關係，因為現在 EventCompaction 在每次叫用中執行的頻率已足夠，可避免超出個別模型叫用的整體脈絡限制。

🎊 太棒了！我們已修正 Simulator 代理程式中的錯誤！

11. 清理

如要避免系統向您的 Google Cloud 帳戶收取費用，請刪除本程式碼研究室中建立的資源。

刪除 Agent Runtime 應用程式

您可以透過控制台或使用 gcloud 指令 (如果您有資源名稱) 刪除 Reasoning Engine 執行個體。為求簡單起見，請使用控制台：

1. 前往「Agent Runtime」頁面。
2. 選取 simulator_agent –> 按一下右側的三點按鈕。
3. 按一下「刪除」。

刪除 Cloud Monitoring 政策

1. 前往 Cloud Monitoring 控制台 ->「快訊」。
2. 向下捲動至「政策」，然後點按三點按鈕「刪除」政策。

12. 🎊 恭喜！

恭喜！您剛才已成功在 Google Cloud 中偵錯 AI 代理程式。

目前所學內容

• 如何將代理部署至 Agent Runtime。
• 如何使用 Cloud Monitoring 快訊偵測錯誤。
• 如何使用 Cloud Logging 和 Agent Runtime 的追蹤檢視畫面探索進行中的事件。
• 如何使用 Gemini Cloud Assist 調查失敗情形。
• 如何使用 Antigravity 找出根本原因並修正代理程式錯誤。
• 如何微調 ADK 事件壓縮，處理長時間執行的工具密集型代理回合。

後續步驟

• 進一步瞭解 Agent Runtime。
• 進一步瞭解 Agent Development Kit。
• 進一步瞭解 Cloud Monitoring 中的快訊。
• 進一步瞭解 Gemini Cloud Assist。