nikkie-ftnextの日記

イベントレポートや読書メモを発信

Python の Agent Development Kit はデフォルトで Gemini API の安定版エンドポイントを呼び出す。◯か☓か

LLM 魔法少女マルカバツカ

答えは、☓ 🙅 ❌

安定版エンドポイントを呼び出す方法を書いていきます！

この記事は ADK Advent Calendar 2025 7日目の記事です。
このブログに ADK の記事を書く中で「ADK、使ってる人いるのかな」と感じてたのですが、カレンダーのフォロワー40名超え！
企画ありがとうございます。届け！

はじめに

七尾百合子さん、お誕生日 265日目 おめでとうございます！1 nikkieです。

タイトルは最近知った ADK Python の真実です。すべてをお話しします

目次

google-genai はデフォルトでベータ版エンドポイントに向いている

ことの発端は、google-genai のドキュメントを見ていて2。

https://googleapis.github.io/python-genai/#api-selection

By default, the SDK uses the beta API endpoints provided by Google to support preview features in the APIs.

安定版エンドポイントを呼び出すには

The stable API endpoints can be selected by setting the API version to v1.

from google import genai
from google.genai import types

client = genai.Client(
    # 省略
    http_options=types.HttpOptions(api_version='v1')
)

BaseApiClient3の実装を抜粋します。
https://github.com/googleapis/python-genai/blob/v1.53.0/google/genai/_api_client.py#L608-L689

class BaseApiClient:
  def __init__(...):
    if self.vertexai:
      self._http_options.api_version = 'v1beta1'
    else:
      self._http_options.api_version = 'v1beta'

この処理の後「Update the http options with the user provided http options.」して、ユーザが指定したHttpOptionsを優先します4。
https://github.com/googleapis/python-genai/blob/v1.53.0/google/genai/_api_client.py#L696-L700

ADK で Client 初期化時に HttpOptions を渡せる？

ADK は google-genai に依存しています。
https://github.com/google/adk-python/blob/v1.20.0/pyproject.toml#L44

google.genai.Clientの初期化の様子を覗いてみると5
https://github.com/google/adk-python/blob/v1.20.0/src/google/adk/models/google_llm.py#L234-L248

class Gemini(BaseLlm):
  def api_client(self) -> Client:
    # 省略
    return Client(
        http_options=types.HttpOptions(
            headers=self._tracking_headers(),
            retry_options=self.retry_options,
        )
    )

HttpOptionsがすでに渡されてしまっています。
ということは、beta endpoint から stable に切り替えられない...？

ADK を Gemini API の安定版エンドポイントに向ける方法

Client初期化時にHttpOptions(api_version="v1")を渡す方法は使えませんが、別の方法があります。

google-genai のGenerateContentConfig

client.models.generate_content()には GenerateContentConfig が渡せます。
https://googleapis.github.io/python-genai/#system-instructions-and-other-configs

GenerateContentConfigにはHttpOptionsを渡せます。
https://googleapis.github.io/python-genai/genai.html#genai.types.GenerateContentConfig.http_options
ADK ではこれを使います。

この実装になっているのは、同じClientで beta と stable 両方のエンドポイントを呼び出したいというニーズに応えるためなんでしょうか？

LlmAgentにGenerateContentConfigを渡す

LlmAgent には上述のGenerateContentConfigを渡せます6。
https://google.github.io/adk-docs/agents/llm-agents/#fine-tuning-llm-generation-generate_content_config

from google.adk.agents import LlmAgent
from google.genai import types

agent = LlmAgent(
    # 略
    generate_content_config=types.GenerateContentConfig(
        http_options=types.HttpOptions(api_version="v1")
    )
)

LlmAgentに渡したGenerateContentConfigがLlmRequestのconfigに渡される箇所（gpt-5.1-codex 調べ。flow は初見で私の理解が追いついてないです）
https://github.com/google/adk-python/blob/v1.20.0/src/google/adk/flows/llm_flows/basic.py#L47-L51

動作確認：Gemini API の叩き分け

adk-python リポジトリの samples からgoogle_search_agentを動かします。
https://github.com/google/adk-python/tree/v1.20.0/contributing/samples/google_search_agent

from google.adk import Agent
from google.adk.tools.google_search_tool import google_search
+from google.genai import types

root_agent = Agent(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
    name='root_agent',
    description="""an agent whose job it is to perform Google search queries and answer questions about the results.""",
    instruction="""You are an agent whose job is to perform Google search queries and answer questions about the results.
""",
    tools=[google_search],
+    generate_content_config=types.GenerateContentConfig(
+        http_options=types.HttpOptions(api_version="v1")
+    ),
)

DeepMind による無料で使える Gemini API と、Google Cloud の Vertex AI の Gemini API を環境変数で切り替えます7。
ref:「Using environment variables」 https://googleapis.github.io/python-genai/#create-a-client

adk webのログ出力で確認します8。
google-genai が依存する HTTPX のログを見ています。
https://github.com/encode/httpx/blob/0.28.1/httpx/_client.py#L1740-L1747

Gemini Developer API

samples から model だけ変えた状態

2025-12-07 15:14:41,455 - INFO - _client.py:1740 - HTTP Request: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent "HTTP/1.1 200 OK"

GenerateContentConfigで安定版エンドポイントを指定

2025-12-07 15:15:25,445 - INFO - _client.py:1740 - HTTP Request: POST https://generativelanguage.googleapis.com/v1/models/gemini-2.5-flash:generateContent "HTTP/1.1 400 Bad Request"

google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Invalid JSON payload received. Unknown name "systemInstruction": Cannot find field.\nInvalid JSON payload received. Unknown name "tools": Cannot find field.', 'status': 'INVALID_ARGUMENT', 'details': [{'@type': 'type.googleapis.com/google.rpc.BadRequest', 'fieldViolations': [{'description': 'Invalid JSON payload received. Unknown name "systemInstruction": Cannot find field.'}, {'description': 'Invalid JSON payload received. Unknown name "tools": Cannot find field.'}]}]}}

叩けませんでした（なにか誤解していそうですが、普段使うの Vertex AI なので深堀りしていません）

Vertex AI

samples から model だけ変えた状態

2025-12-07 15:18:12,711 - INFO - _client.py:1740 - HTTP Request: POST https://aiplatform.googleapis.com/v1beta1/projects/adk-practice-480404/locations/global/publishers/google/models/gemini-2.5-flash:generateContent "HTTP/1.1 200 OK"

GenerateContentConfigで安定版エンドポイントを指定

2025-12-07 15:18:49,650 - INFO - _client.py:1740 - HTTP Request: POST https://aiplatform.googleapis.com/v1/projects/adk-practice-480404/locations/global/publishers/google/models/gemini-2.5-flash:generateContent "HTTP/1.1 200 OK"

叩けました！（Google 検索ツールも使えます）

終わりに

ADK Python はデフォルトでは Gemini API のベータ版エンドポイントを呼び出しています。

  • 依存する google-genai がデフォルトでベータ版エンドポイントを使うため
  • 安定版エンドポイントに向けるには、LlmAgentにGenerateContentConfig(http_options=HttpOptions(api_version="v1"))を渡す
  • samples のgoogle_search_agentを使って Vertex AI の Gemini API の安定版エンドポイントを呼び出せることを確認した

半年くらいは ADK で開発していますが、「プロンプト触ってないのに、昨日できたことが今日はできなくなった〜」や「土日を挟んだら同じプロンプトなのに再現しない〜」をちょこちょこ経験してきました。
ベータ版のエンドポイントに向いていたというのは一定説明になっていると、私は納得しています。

なお、開発しているエージェントを安定版エンドポイントに本格的に向けるのはこれからなので、今回試したサンプル以上に複雑なエージェントで問題にぶつかったなど学びがあったら続編を書きます

ADK Advent Calendar 2025 明日の8日目は、na0さんです。
発表資料をいつも参考にさせていただいているので楽しみです！

  1. アドカレはいつも読まない方もいらっしゃると思うので、この書き出しについて ↩
  2. きっかけになった記事 ↩
  3. Clientは（ほとんどの場合）BaseApiClientを持ちます https://github.com/googleapis/python-genai/blob/v1.53.0/google/genai/client.py#L318↩
  4. ユーザが指定した API バージョンになる様子 https://github.com/googleapis/python-genai/blob/v1.53.0/google/genai/tests/client/test_http_options.py#L46↩
  5. 1日目のサントリーさんの解説も合わせてどうぞ。「例えば Gemini 系のモデルであれば、google.adk.models.google_llm.Gemini の（略）」 [ADK] 今更 LlmAgentの各種プロパティを詳しく説明する ~ ADK LlmAgent Property Maniax ~↩
  6. 再びサントリーさん1日目 [ADK] 今更 LlmAgentの各種プロパティを詳しく説明する ~ ADK LlmAgent Property Maniax ~↩
  7. Vertex AI の方が本番アプリケーション向けの認識です ↩
  8. このログの実装について意見があります ↩