Next ‘26 デベロッパー基調講演: エージェントのデバッグを大規模に行う

1. はじめに

この Codelab では、Google Cloud で実行されている AI エージェントをデバッグする方法について説明します。シミュレータエージェントを Agent Runtime にデプロイし、Cloud Observability を使用して問題を検出し、Gemini Cloud Assist と Antigravity IDE を使用してエラーの根本原因を特定し、リアルタイムで修正します。

arch

このデモでは、Simulator Agent に ADK EventCompaction を追加したばかりであることを前提としています。これにより、シミュレータは Gemini を使用してワークフローを定期的に要約し、各ターンのモデルに送信されるコンテキストの総量を減らすことができます。これにより、レスポンスの品質が向上し、総費用が削減されます。しかし、EventCompactionConfig にバグがあり、エージェントでエラーが発生していることがわかります。この Codelab では、このような問題を見つけて迅速に修正する方法について説明します。

コンパクション

演習内容

Marathon Simulator エージェントを Agent Runtime にデプロイします。
エージェントエラーを検出するように Cloud Monitoring アラートを設定します。
Cloud Trace と Gemini Cloud Assist を使用してエラーを調査します。
Antigravity と MCP を使用して、エージェントの根本原因を特定し、パッチを適用します。

必要なもの

ウェブブラウザ（Chrome など）。
Google アカウント
Antigravity（Mac、Linux、Windows をサポート）
Python 3.13 以降。
uv（Python パッケージマネージャー）

所要時間の目安: 45 分

推定費用: 5 米ドル未満

2. 始める前に

Google Cloud プロジェクトの作成

Google Cloud コンソールで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトで課金が有効になっていることを確認します。

環境の設定

Antigravity を開いてログインします。次に、cmd-shift-P（または ctrl-shift-P）を押して [ターミナル] を開き、「新しいターミナルを作成」と入力します。

ターミナル

ターミナルから Google Cloud で認証します。

gcloud auth login
gcloud auth application-default login

プロジェクト 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

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

3. シミュレータエージェントを設定する

このステップでは、デモリポジトリのクローンを作成し、Simulator Agent の環境変数を構成します。

リポジトリのクローンを作成する

next-26-keynotes リポジトリのクローンを作成し、デモディレクトリに移動します。

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

環境変数を構成する

Simulator Agent は、構成に .env ファイルを使用します。

Antigravity ウィンドウ（エクスプローラ）の左側にある sample.env ファイルを見つけます。

explorer

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

4. シミュレータエージェントを Agent Runtime にデプロイする

次に、Agent Development Kit（ADK）を使用して、エージェントを Agent Runtime にデプロイします。

依存関係のインストール

uv sync

Agent Runtime にデプロイする

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 コンソールを開きます。エージェントランタイムで simulator_agent が実行され、テレメトリー収集が有効になっていることがわかります。

5. アラートポリシーを設定する

エージェントランタイムエラーを自動的に検出するには、Google Cloud コンソールでログベースのアラートを作成します。

Cloud Monitoring - アラート コンソールに移動します。

[通知チャンネルの編集] をクリックします。[メール] タイプまでスクロールし、個人用メールアドレスに送信するメール通知チャンネルを作成します。[Save] をクリックします。

アラートダッシュボードに戻り、[ポリシーを作成] をクリックします。
画面の右側にある [ログベースのアラートを作成] をクリックします。

[ログエクスプローラ] にリダイレクトされます。次のログクエリを貼り付けます。は実際のプロジェクト ID に置き換えます。

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

[RUN QUERY] をクリックします。まだログは表示されませんが、これは想定どおりです。
結果ツールバーで [アクション] をクリックし、[ログアラートの作成] をクリックします。

ログベースのアラートを構成します。アラートに名前（任意）を付け、重大度を [エラー] に設定します。

[通知頻度を設定] セクションで [次へ] をクリックします（デフォルトのままにします）。

[通知するユーザー] で、設定したメール通知チャンネル（例: My Email）。
[保存] をクリックします。

6. インシデントをトリガーする

エージェントがデプロイされ、モニタリングされているので、エラーがスローされるようにマラソンシミュレーションを呼び出してみましょう。

Google Cloud コンソールで、[エージェントランタイム] コンソールに移動します。
simulator_agent をクリックします。
上部のツールバーで [Playground] をクリックします。これにより、ADK エージェントとの新しいセッションが開始されます。

セッションのチャットウィンドウで「Test Simulation」と入力し、Enter キーを押してプロンプトを送信します。

これにより、マラソンシミュレーションが開始され、計画されたルートに沿って数千人のシミュレートされたランナーが追跡されます。シミュレーションでレースの複数の「ゾーン」が評価されるため、get_runner_telemetry と analyze_medical_risk への複数のツール呼び出しが表示されます。

1 分ほどで、エージェント内の新しいインシデントを知らせるメールが受信トレイに届きます。

[インシデントを表示] をクリックして、Cloud Monitoring コンソールを開きます。次のページに進んで、コンソールで問題を調査します。

7. コンソールでインシデントを調査する

Cloud Monitoring コンソールでインシデントを表示します。Simulator Agent からのエラーログが表示されます。

このビューでは、エージェントがどの時点で失敗したかを正確に把握することは困難です。エージェントの基盤となるツール呼び出しと推論フローを確認するには、エージェントのトレースを調べます。

Agent Runtime コンソールをもう一度開きます。[simulator_agent] をクリックし、[トレース] タブを開きます。

リストで最新のトレースをクリックします。右上の [タイムライン] をクリックします。個々の「スパン」を含むトレースビューが表示されます。1 つのスパンは、エージェントのワークフロー内のモデルまたはツールの呼び出しを表します。

トレースビューの最後のスパンをクリックします。赤色になっているはずです。
[スタックトレース] をクリックします。Gemini API モデル呼び出しに関連するエラーログが表示されます。具体的には、400: Invalid Argument エラーです。これは、シミュレータエージェントが Gemini API に送信したペイロードに関するリクエストレベルの問題を示します。

8. [省略可] Cloud Assist Investigations を使用してデバッグする

失敗したスパン内で、[ログとイベント] をクリックします。横にスパークルボタンが付いている [例外] ログを見つけます。[Investigate Log]（ログを調査）をクリックします。

これにより、画面の右側のサイドバーから Cloud Assist の調査が開始されます。読み込みには 3 ～ 5 分ほどかかります。

完了したら、調査を開きます。

調査の概要を表示します。

下にスクロールして [仮説] を確認します。Gemini Cloud Assist は、Gemini API 400 エラーをスローしている Simulator Agent の agent.py ファイルの特定の行を特定しているはずです。

エージェントのソースコードを開き、Antigravity を使用して問題の根本原因を特定してみましょう。次のページに進みます。

9. Antigravity を使用して問題の根本原因を特定し、パッチを適用する

Antigravity を再度開きます。
画面右上の [Agent Manager] を開きます。

モデルが Gemini 3 Flash と Planning モードに設定されていることを確認します。

次のプロンプトを入力して、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 万）を超えていることです。この問題が発生する理由は、Simulator Agents ツール呼び出しからの巨大なレスポンスを効果的に要約するために、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,
    ),
)

10. 修正を再デプロイして検証する

ADK エージェントの EventCompactionConfig に token_threshold の修正を適用したので、シミュレータエージェントを Agent ランタイムに再デプロイできます。

Antigravity を開く -> [New Terminal] を選択します。
環境変数を設定します。AGENT_RUNTIME_ID は、simulator_agent の完全なリソース名である必要があります。これは、Agent Runtime コンソールのエージェントリストで確認できます。

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

エージェントを再デプロイします。

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...

Agent Runtime コンソールを開きます。simulator_agent を再度開きます。[Playground] をクリックします。
同じプロンプト（Test Simulation）を入力して、Enter キーを押します。
バックエンドの Marathon シミュレーション全体を実行するには数分かかります。複数のツール呼び出しが表示されます。最終的に、次のようなレスポンスが表示されます。

これは、シミュレータが正常に実行されたことを示します。✅

その ADK セッションのトレースビューを開きます。
赤いエラーがなく、すべてのスパンが「青」になっていることを確認します。セッションの合計トークン数が Gemini API の 100 万コンテキストトークン上限を超えていることに注目してください。これは問題ありません。EventCompaction は各呼び出し内で十分な頻度で実行されるため、個々のモデル呼び出しのコンテキスト上限を超えることはありません。

🎊 おめでとうございます。Simulator エージェントのエラーを修正しました。

11. クリーンアップ

Google Cloud アカウントに課金されないようにするには、この Codelab で作成したリソースを削除します。

エージェントランタイムアプリを削除する

Reasoning Engine インスタンスは、コンソールまたは gcloud コマンドを使用して削除できます（リソース名がある場合）。わかりやすくするために、コンソールを使用します。

[エージェントランタイム] ページに移動します。
simulator_agent を選択し、右側のその他アイコンをクリックします。
[削除] をクリックします。

Cloud Monitoring ポリシーを削除する

Cloud Monitoring コンソール -> アラートに移動します。
[ポリシー] までスクロールし、三点リーダーボタンをクリックしてポリシーを削除します。

12. 🎊 おめでとうございます。

おめでとうございます！これで、Google Cloud で AI エージェントのデバッグが正常に完了しました。

学習した内容

エージェントランタイムにエージェントをデプロイする方法。
Cloud Monitoring アラートを使用してエラーを検出する方法。
Cloud Logging と Agent Runtime のトレースビューを使用して、アクティブなインシデントを調査する方法。
Gemini Cloud Assist を使用して障害を調査する方法。
Antigravity を使用してエージェントのバグの根本原因を特定し、パッチを適用する方法。
長時間実行されるツールを多用するエージェントのターンを処理するために、ADK イベントの圧縮を微調整する方法。

次のステップ

Agent Runtime の詳細を確認する。
Agent Development Kit の詳細を確認する。
Cloud Monitoring のアラートの詳細を確認する。
Gemini Cloud Assist の詳細を確認する。