ADK エージェント用の Google Gemini モデル

Supported in ADKPython v0.1.0Typescript v0.2.0Go v0.1.0Java v0.2.0

ADK は、幅広い機能を備えた Google Gemini 系の生成 AI モデルをサポートします。 ADK は次のような豊富な Gemini 機能をサポートしています。 コード実行、 Google Search、 コンテキストキャッシュ、 コンピュータ使用、 および Interactions API を含みます。

はじめに

以下のコード例は、エージェントで Gemini モデルを使用する基本実装を示します。

PythonTypeScriptGoJava

from google.adk.agents import LlmAgent

# --- Example using a stable Gemini Flash model ---
agent_gemini_flash = LlmAgent(
    # Use the latest stable Flash model identifier
    model="gemini-2.5-flash",
    name="gemini_flash_agent",
    instruction="You are a fast and helpful Gemini assistant.",
    # ... other agent parameters
)

import {LlmAgent} from '@google/adk';

// --- Example #2: using a powerful Gemini Pro model with API Key in model ---
export const rootAgent = new LlmAgent({
  name: 'hello_time_agent',
  model: 'gemini-2.5-flash',
  description: 'Gemini flash agent',
  instruction: `You are a fast and helpful Gemini assistant.`,
});

import (
    "google.golang.org/adk/agent/llmagent"
    "google.golang.org/adk/model/gemini"
    "google.golang.org/genai"
)

// --- Example using a stable Gemini Flash model ---
modelFlash, err := gemini.NewModel(ctx, "gemini-2.0-flash", &genai.ClientConfig{})
if err != nil {
    log.Fatalf("failed to create model: %v", err)
}
agentGeminiFlash, err := llmagent.New(llmagent.Config{
    // Use the latest stable Flash model identifier
    Model:       modelFlash,
    Name:        "gemini_flash_agent",
    Instruction: "You are a fast and helpful Gemini assistant.",
    // ... other agent parameters
})
if err != nil {
    log.Fatalf("failed to create agent: %v", err)
}

// --- Example #1: using a stable Gemini Flash model with ENV variables---
LlmAgent agentGeminiFlash =
    LlmAgent.builder()
        // Use the latest stable Flash model identifier
        .model("gemini-2.5-flash") // Set ENV variables to use this model
        .name("gemini_flash_agent")
        .instruction("You are a fast and helpful Gemini assistant.")
        // ... other agent parameters
        .build();

Gemini モデル認証

このセクションでは、Google AI Studio（迅速な開発）または Google Cloud Vertex AI （エンタープライズ用途）による Gemini モデルの認証を説明します。 これは ADK 内で Google の主要モデルを利用する最も直接的な方法です。

統合方法: 下記いずれかで認証を完了すると、LlmAgent の model パラメータにモデル識別子文字列を直接渡せるようになります。

Tip

ADK が Gemini モデルで内部的に使用する google-genai ライブラリは、 Google AI Studio または Vertex AI のどちらでも接続できます。

音声/動画ストリーミングのサポート

ADK で音声/動画ストリーミングを使用するには、Live API をサポートする Gemini モデルを使用してください。Gemini Live API をサポートする モデル ID は以下を参照してください。

• Google AI Studio: Gemini Live API
• Vertex AI: Gemini Live API

Google AI Studio

最もシンプルな方法で、すぐに始める場合に推奨します。

• 認証方法: API Key

• セットアップ:

  1. API キーを取得: Google AI Studio からキーを取得します。

  2. 環境変数を設定: プロジェクトのルートディレクトリに .env（Python） または .properties（Java）を作成し、次の行を追加します。ADK はこのファイルを自動的に読み込みます。

     export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
     export GOOGLE_GENAI_USE_VERTEXAI=FALSE
     

     （または）

     モデル初期化時に Client 経由で変数を渡します（後述）。

• モデル: 利用可能モデル一覧は Google AI for Developers を参照してください。

Google Cloud Vertex AI

スケーラブルで本番利用向けには Vertex AI を推奨します。 Vertex AI 上の Gemini はエンタープライズ向け機能、セキュリティ、コンプライアンス制御を提供します。 開発環境とユースケースに応じて、以下の方法のいずれかで認証します。

事前要件: Vertex AI が有効化された Google Cloud プロジェクトが必要です。

方法 A: ユーザー認証情報（ローカル開発向け）

1. gcloud CLI のインストール: 公式 インストール手順に従います。
2. ADC でログイン: このコマンドでブラウザーが開き、ローカル開発のユーザーアカウント認証が行われます。

   gcloud auth application-default login
   

3. 環境変数を設定:

   export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
   export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # e.g., us-central1
   

   ライブラリに Vertex AI の使用を明示します。

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE
   

4. モデル: 利用可能なモデル ID は Vertex AI ドキュメント で確認してください。

方法 B: Vertex AI Express Mode

Vertex AI Express Mode は API キー ベースの簡易セットアップで、迅速なプロトタイピングに適しています。

1. Express Mode にサインアップして API キーを取得します。
2. 環境変数を設定:

   export GOOGLE_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
   export GOOGLE_GENAI_USE_VERTEXAI=TRUE
   

方法 C: サービスアカウント（本番/自動化向け）

デプロイ済みアプリケーションでは、サービスアカウントが標準的な方法です。

1. サービスアカウントを作成 し、 Vertex AI User ロールを付与します。
2. アプリケーションへ認証情報を設定:
   • Google Cloud 内: Cloud Run、GKE、VM、または他の Google Cloud サービスで エージェントを実行している場合、サービスアカウント認証情報は環境で自動提供されるため キーファイルは不要です。
   • それ以外: サービスアカウントキーファイルを作成し、 環境変数でそのパスを指定します。

     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
     

     キーファイルの代わりに Workload Identity で認証できますが、このガイドでは扱いません。

認証情報の保護

サービスアカウント認証情報や API キーは高権限資格情報です。 公開しないでください。運用では Google Cloud Secret Manager などを使って 安全に保管・参照してください。

Gemini モデルのバージョン

常に公式 Gemini ドキュメントで最新のモデル名を確認してください。 プレビュー版は利用可能性やクォータ制限が異なる場合があります。

トラブルシューティング

エラーコード 429 - RESOURCE_EXHAUSTED

このエラーは、リクエスト数が処理能力として割り当てられた上限を超えると発生します。

以下のいずれかを実施して対処できます。

1. 使用するモデルのクォータ上限を引き上げる申請をします。

2. クライアント側リトライを有効にします。リトライにより、一時的なクォータ不足時に 一定時間待機して自動再送することで回避可能です。

   リト라이オプションの設定には2通りあります。

   オプション 1: generate_content_config 内でエージェントに対してリトライを設定します。

   この方法はこのモデルアダプターを直接インスタンス化する場合に適しています。

   PythonJava

   root_agent = Agent(
       model='gemini-2.5-flash',
       # ...
       generate_content_config=types.GenerateContentConfig(
           # ...
           http_options=types.HttpOptions(
               # ...
               retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
               # ...
           ),
           # ...
       )
   

   import com.google.adk.agents.LlmAgent;
   import com.google.genai.types.GenerateContentConfig;
   import com.google.genai.types.HttpOptions;
   import com.google.genai.types.HttpRetryOptions;
   
   // ...
   
   LlmAgent rootAgent = LlmAgent.builder()
       .model("gemini-2.5-flash")
       // ...
       .generateContentConfig(GenerateContentConfig.builder()
           // ...
           .httpOptions(HttpOptions.builder()
               // ...
               .retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
               // ...
               .build())
           // ...
           .build())
       .build();
   

   オプション 2: このモデルアダプター自体のリトライオプションを設定します。

   この方法はこのモデルアダプターのインスタンスを自分で生成する場合に適しています。

   PythonJava

   from google.genai import types
   
   # ...
   
   agent = Agent(
       model=Gemini(
       retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
       )
   )
   

   import com.google.adk.agents.LlmAgent;
   import com.google.adk.models.Gemini;
   import com.google.genai.Client;
   import com.google.genai.types.HttpOptions;
   import com.google.genai.types.HttpRetryOptions;
   
   // ...
   
   LlmAgent agent = LlmAgent.builder()
       .model(Gemini.builder()
           .modelName("gemini-2.5-flash")
           .apiClient(Client.builder()
               .httpOptions(HttpOptions.builder()
                   .retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
                   .build())
               .build())
           .build())
       .build();
   

Gemini Interactions API

Supported in ADKPython v1.21.0

Gemini の Interactions API は、generateContent 推論 API の代替で、ステートフルな会話を可能にします。 各リクエストで会話履歴全体を送信する代わりに previous_interaction_id を用いてやり取りを連結できるため、長い会話に対して効率的です。

次のコード断片のように、Gemini モデル設定で use_interactions_api=True を設定すると Interactions API を有効化できます。

PythonJava

from google.adk.agents.llm_agent import Agent
from google.adk.models.google_llm import Gemini
from google.adk.tools.google_search_tool import GoogleSearchTool

root_agent = Agent(
    model=Gemini(
        model="gemini-2.5-flash",
        use_interactions_api=True,  # Interactions API を有効化
    ),
    name="interactions_test_agent",
    tools=[
        GoogleSearchTool(bypass_multi_tools_limit=True),  # 関数ツールに変換
        get_current_weather,  # カスタム関数ツール
    ],
)

import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Gemini;
import com.google.adk.tools.GoogleSearchTool;

// 注: Java ADK の Interactions API サポートは現在開発中です。
LlmAgent rootAgent = LlmAgent.builder()
    .model(Gemini.builder()
        .modelName("gemini-2.5-flash")
        .build())
    .name("interactions_test_agent")
    .tools(
        GoogleSearchTool.INSTANCE, // 検索ツール
        getCurrentWeather // カスタム関数ツール
    )
    .build();

完全なサンプルは Interactions API サンプルを参照してください。

既知の制限

Interactions API は、Google Search のような カスタム関数呼び出しツールと、同じエージェント内の組み込みツールを混在して使用することをサポートしません。 bypass_multi_tools_limit パラメータで組み込みツールをカスタムツールとして動作させることで 回避できます。

PythonJava

# Use bypass_multi_tools_limit=True to convert google_search to a function tool
GoogleSearchTool(bypass_multi_tools_limit=True)

// 注: bypassMultiToolsLimit は Python 専用です。
// Java ではツールインスタンスをそのまま使用します。
GoogleSearchTool.INSTANCE;

この例では、組み込み google_search を関数呼び出しツール（GoogleSearchAgentTool） へ変換し、カスタム関数ツールと共存できるようにします。