はじめに

これまでの Google Cloud Agent Engine での開発では、エージェントをデプロイした後、その動作確認やデバッグのために 自身でテスト用スクリプトを用意する必要 がありました。
しかし、この度、ついに Google Cloud Console から直接、エージェントの動作確認（プレイグラウンド機能）や、実行状況を詳細に追跡・分析できる テレメトリー機能 が統合されました！
このアップデートにより、エージェント開発のデバッグや運用監視が劇的に簡単になります。本記事では、この新機能の使い方と、特に強力な テレメトリー の詳細を徹底解説します。

Google Cloud Consoleから動作確認をしてみる

まずは簡単にagent engineのデプロイ方法をご紹介します。

from google.adk.agents.llm_agent import Agent
import os
import vertexai
from vertexai import agent_engines

# システムプロンプト
ROOT_PROMPT = """
あなたは天気予報アシスタントです。
ユーザーから都市名を聞かれたら、get_weather()関数を使って天気情報を取得してください。
"""

# 環境設定
AGENT_NAME = "simple_weather_agent"
DESCRIPTION = "シンプルな天気予報エージェント"
PROJECT = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION")
MODEL = os.getenv("MODEL", "gemini-2.5-flash-exp")


# ツール関数の定義
def get_weather(city: str) -> dict:
    """
    指定された都市の天気情報を取得します。

    Args:
        city: 都市名（例: 東京、大阪、福岡）

    Returns:
        dict: 天気情報を含む辞書
            weather: 天気（晴れ、曇り、雨など）
            temperature: 気温（摂氏）
            humidity: 湿度（%）
    """
    # 動作確認用にサンプルデータを返す
    weather_data = {
        "東京": {"weather": "晴れ", "temperature": 18, "humidity": 55},
        "大阪": {"weather": "曇り", "temperature": 16, "humidity": 60},
        "福岡": {"weather": "雨", "temperature": 15, "humidity": 75},
        "札幌": {"weather": "雪", "temperature": 2, "humidity": 70},
        "沖縄": {"weather": "晴れ", "temperature": 24, "humidity": 65},
    }

    # 都市名が見つからない場合のデフォルト
    if city not in weather_data:
        return {
            "weather": "晴れ",
            "temperature": 20,
            "humidity": 50,
            "note": f"{city}の詳細データはありませんが、一般的な天気情報です"
        }

    return weather_data[city]



# Vertex AIの初期化
vertexai.init(
    project=PROJECT,
    location=LOCATION,
    staging_bucket=f'gs://{PROJECT}'
)

os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = 'True'

# エージェントの作成
root_agent = Agent(
    model=MODEL,
    name=AGENT_NAME,
    description=DESCRIPTION,
    instruction=ROOT_PROMPT,
    tools=[get_weather],  # 天気取得関数をツールとして登録
)

# Agent Engineへのデプロイ
# このコードを実行すると、エージェントがGoogle Cloudにデプロイされます
if __name__ == "__main__":
    remote_agent = agent_engines.create(
        agent_engine=root_agent,
        display_name='simple_weather_agent3',
        description='天気情報を提供するシンプルなエージェント',
        env_vars={
            "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
            "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
        },
        requirements=[
            "google-cloud-aiplatform[adk,agent_engines]",
        ]
    )

    print(f"✅ デプロイ完了!")
    print(f"エージェント名: {remote_agent.name}")
    print(f"リソース名: {remote_agent.resource_name}")

ここがデプロイするために必要なコードとなります。

    remote_agent = agent_engines.create(
        agent_engine=root_agent,
        display_name='simple_weather_agent3',
        description='天気情報を提供するシンプルなエージェント',
        env_vars={
            "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
            "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
        },
        requirements=[
            "google-cloud-aiplatform[adk,agent_engines]",
        ]
    )

デプロイ後の動作確認（プレイグラウンド）

デプロイした Agent Engine にアクセスすると、以下のような画面が表示されます。

「プレイグラウンド」という画面が追加されています。この画面から、チャット形式でデプロイしたエージェントと直接会話しながら、手軽に動作確認を行うことができます。

テレメトリー機能について

次に、エージェントの実行状況を深く洞察できる強力な機能「テレメトリー」を見ていきましょう。
この機能を使うには、デプロイ時に env_vars パラメーターで以下の環境変数を設定する必要があります。

env_vars={
    "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
    "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
}

実際にソースに組み込むと以下のような形になります。

    remote_agent = agent_engines.create(
        agent_engine=root_agent,
        display_name='simple_weather_agent3',
        description='天気情報を提供するシンプルなエージェント',
        env_vars={
            "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
            "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
        },
        requirements=[
            "google-cloud-aiplatform[adk,agent_engines]",
        ]
    )

テレメトリーを有効化する環境変数の意味

それぞれの環境変数は以下の役割を持ちます。

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: テレメトリー（実行トレース、メトリクスなど）の収集を有効にします。
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: トレース情報に LLMへの入力（プロンプト）や応答（メッセージ）の具体的な内容を含める ようにします。

それぞれのパラメーターの違いがわかりやすいよう３つのエージェントを用意

テレメトリー設定の違いの比較表

エージェント名 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 結果
simple_weather_agent true true 完全なテレメトリーが有効（トレース、パフォーマンス、会話のメッセージ内容の記録が可能）
simple_weather_agent2 true false トレースは有効だが、会話のメッセージ内容が記録されないためコンソールに警告が表示される
simple_weather_agent3 false true テレメトリー収集自体が無効なため、機能しない


※simple_weather_agent3についてはテレメトリー収集が無効になっています。

simple_weather_agent2にアクセスしてみるとトレースを有効にしてくれという告知が

simple_weather_agent3にアクセスしてみるとTelemetryが使えないという警告が出ています

この結果から、二つのパラメーターを両方ともtrueに設定しないと、テレメトリー機能は完全には利用できないことがわかります。

実際にテレメトリーではどういった機能が使えるか見てみる

ダッシュボード

ログの確認や使用状況をメトリクスで確認することができます。

トレース

エージェントがどのような動きをしたのか細かく確認できるようになっています。

セッション

特定のセッションにアクセスしてみるとどのような会話が行われたか見ることができます。

ざっくりまとめると以下のようなことができるようになっています。

  • 実行トレース：エージェントの処理フロー全体
  • パフォーマンスメトリクス：各処理にかかった時間
  • ツール呼び出し情報：どのツールがいつ呼ばれたか
  • エラー情報：発生した例外やエラーの詳細
  • ユーザーの入力メッセージ：実際にどんな質問をしたか
  • エージェントの応答：どのように返答したか
  • プロンプトの内容：LLMに送信された完全なプロンプト
  • ツールの入出力：関数呼び出しの引数と戻り値

最後に従来のスクリプトベースで接続するとどうなるか見てみましょう

プレイグラウンドだけでなく、従来のスクリプトからエージェントを呼び出した場合も、同様にセッションとテレメトリーが記録されます。

"""
デプロイされた天気予報エージェントをテストするスクリプト
"""
import os
from vertexai import agent_engines

PROJECT = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION")

def test_weather_agent():
    """デプロイされたエージェントと対話"""

    # デプロイされたエージェントのリソース名
    AGENT_RESOURCE_NAME = "{agent engineのリソース名}"

    # エージェントに接続
    remote_agent = agent_engines.get(AGENT_RESOURCE_NAME)

    print("=" * 60)
    print("天気予報エージェントテスト")
    print("=" * 60)

    # テストクエリ
    test_queries = [
        "東京の天気を教えて",
        "大阪は今日雨ですか？",
        "福岡と札幌の天気を比較して",
    ]

    for i, query in enumerate(test_queries, 1):
        print(f"\n[テスト {i}]")
        print(f"質問: {query}")
        print("-" * 60)
        print("回答: ", end="", flush=True)

        USER_ID = "test_user01"

        # エージェントにクエリを送信（ストリーミング）
        events = remote_agent.stream_query(
            user_id=USER_ID,
            message=query
        )

        # ストリームからテキストを取得して表示
        for event in events:
            if 'content' in event and 'parts' in event['content']:
                for part in event['content']['parts']:
                    if 'text' in part:
                        print(part['text'], end="", flush=True)

if __name__ == "__main__":
    test_weather_agent()

セッションが追加されプレイグラウンドで実際の会話の内容も確認可能になっています。

まとめ

今回の Google Cloud Agent Engine のアップデートは、エージェント開発のワークフローに変革をもたらします。

  1. コンソールでの即時動作確認（プレイグラウンド）： デプロイ後すぐに 手軽なテスト が可能となり、開発サイクルのスピードアップに貢献します。
  2. テレメトリー機能による深い洞察： 本番環境での ユーザーとの実際の会話内容 や、エージェント内部の 実行トレース、パフォーマンスメトリクス を詳細に確認できるようになりました。
    これにより、エージェントが「なぜその応答をしたのか」を簡単に分析し、改善点を迅速に特定 できます。

自前のログ収集やテストスクリプト作成の手間が大幅に削減され、Agent Engineはさらに 使いやすく、運用しやすい プラットフォームへと進化しました。

この強力な新機能を活用し、皆様のエージェント開発をより一層 活発化 させていきましょう！