2026.07.17 コラム
【テックコラム】Google ADK のパラメータを Parameter Manager で管理してみる
DataCurrent の金子です。今回は、Google Cloud の Parameter Manager を使って、Google ADK の パラメータをコードの外に出せるかを検証してみました。
※ この記事は、2026年7月時点の Google Cloud の仕様に基づいています。
検証したこと
Google ADK でエージェントを作っていると、エージェントの挙動に関わる値をどこで管理するかが気になります。
たとえばシステム プロンプトは、開発中に何度も調整します。コードに直接書いておくこともできますが、プロンプトを変えるたびにコードを修正することになります。また、検証環境と本番環境でどのプロンプトを使っているのか、あとから確認しづらくなることもあります。
そこで今回は、Google ADK のパラメータを Parameter Manager から読み取る構成を試しました。例として、システム プロンプトを Parameter Manager に保存し、Google ADK エージェントの実行時に読み取って使ってみます。
あわせて、Parameter Manager に新しいバージョンを追加したときに、コードを変更せず次回実行から新しいプロンプトに切り替わるかも確認しました。
構成は以下のイメージです。
Parameter Manager 側の準備
今回は Parameter Manager のパラメータ リソースは Google Cloud コンソールで事前に作成しておきました。
想定した Parameter Manager パラメータ リソースは以下です。
- Parameter ID:
pm-adk-system-prompt - Location:
global - Format:
unformatted
システム プロンプトの本文をそのまま保存したいので、format は unformatted にしています。
パラメータの値そのものはパラメータのバージョンとして追加します。コンソールでは、対象のパラメータを開き、+ New version を押します。
バージョン追加画面では、バージョン名を入力し、ペイロードにプロンプト本文を入力します。プロンプトをファイルで管理している場合は、ファイルをアップロードしてからペイロード エディタで確認することもできます。
今回は検証用に、たとえば以下のようなシステム プロンプトを登録しました。
あなたは Parameter Manager のプロンプト検証用エージェントです。 ユーザーの依頼内容に関係なく、次の 1 行だけを正確に返してください。 PM_PROMPT_VERSION=v1 それ以外のテキストは含めないでください。
このプロンプトを v1 として登録し、その後 PM_PROMPT_VERSION=v2 に変えたバージョン v2 を追加して、エージェントの応答が切り替わるかを見ます。
Google ADK エージェントから読み取る
Google ADK 側では、google-adk[extensions] に含まれる ParameterManagerClient を使って Parameter Manager の値を取得します。
今回の例では、before_agent_callback で Parameter Manager からプロンプトを読み取り、state に保存します。そのうえで、instruction に指定した関数から state の値を返し、モデルへの指示として使います。
from google.adk.agents import LlmAgent
from google.adk.integrations.parameter_manager.parameter_client import ParameterManagerClient
PROJECT_ID = "YOUR_PROJECT_ID"
PARAMETER_LOCATION = "global"
PARAMETER_VERSION = "latest"
PROMPT_PARAMETER_ID = "pm-adk-system-prompt"
PROMPT_PARAMETER_NAME = (
f"projects/{PROJECT_ID}/locations/{PARAMETER_LOCATION}/parameters/"
f"{PROMPT_PARAMETER_ID}/versions/{PARAMETER_VERSION}"
)
PROMPT_STATE_KEY = "parameter_prompt"
_parameter_client = ParameterManagerClient()
def prompt_text():
payload = _parameter_client.get_parameter(PROMPT_PARAMETER_NAME)
return payload.decode("utf-8") if isinstance(payload, bytes) else str(payload)
def load_parameter_prompt(callback_context):
callback_context.state[PROMPT_STATE_KEY] = prompt_text()
def instruction_provider(readonly_context):
return readonly_context.state.get(PROMPT_STATE_KEY, "")
root_agent = LlmAgent(
name="pm_prompt_agent",
model="gemini-3.5-flash",
instruction=instruction_provider,
before_agent_callback=load_parameter_prompt,
)
ポイントは、プロンプト本文はキャッシュせず、versions/latest を毎回読み取ることです。これにより、Parameter Manager 側で新しいバージョンを追加した後の実行では、新しいプロンプトが使われます。
一方で、ParameterManagerClient() は毎回作らずに使い回すようにしました。今回のローカル実測では、クライアントを使い回した Parameter Manager の読み取り自体は p50 で約 70ms でしたが、毎回クライアントを生成すると p50 で約 375ms まで増えました。コールバックのたびにクライアントを作らない方がよさそうです。
ローカルで ADK エージェントを動かす場合は、必要なライブラリを入れて adk run を実行します。
uv run \ --with 'google-adk[extensions]>=1.30.0' \ --with 'google-cloud-parametermanager>=0.1.0' \ adk run pm_prompt_agent
実行ユーザーには、対象 Parameter を読み取るための roles/parametermanager.parameterAccessor 相当の権限が必要です。
検証結果
結論として、Google ADK のパラメータを Parameter Manager から読み取ることはできました。今回のシステム プロンプトの例では、Parameter Manager の versions/latest を参照することで、コンソールから新しいバージョンを追加した後、次回実行から即座にエージェントの応答が切り替わることを確認できました。
たとえば v1 のプロンプトでは以下の応答になるようにしておきます。
PM_PROMPT_VERSION=v1
その後、同じパラメータに v2 のプロンプトを新しいバージョンとして追加します。
PM_PROMPT_VERSION=v2
エージェント側は versions/latest を参照しているため、コードを変更せずに次回実行から v2 のプロンプトが使われます。システム プロンプトのように調整頻度が高い値を、コードから切り離して管理できることが分かりました。
良かった点
まず、プロンプト本文をコードから外に出せるのは分かりやすいです。コード側にはパラメータのリソース名だけを持たせ、実際のプロンプトは Parameter Manager 側で管理できます。
次に、コンソールでバージョンを確認できる点も便利でした。どのバージョンが存在するのか、ペイロードがどうなっているのかをコンソールから確認できます。また、Parameter Manager にはバージョンの比較画面があり、プロンプトの差分も確認できます。
環境ごとの使い分けもしやすいです。検証環境では pm-adk-system-prompt-stg/versions/latest、本番環境では pm-adk-system-prompt-prod/versions/latest のように Parameter を分ける運用にすれば、検証中のプロンプトが本番に混ざることを避けられます。
気になった点
versions/latest は便利ですが、本番では扱いに注意が必要です。新しいバージョンを追加すると、それが latest になります。つまり、本番エージェントが versions/latest を見ている場合、バージョン追加のタイミングでプロンプトが切り替わります。
理想を言うと、バージョンとは別に prod や current のようなタグを付け替えられると運用しやすいと感じました。今回は latest を使いましたが、本番反映の承認フローを厳密にしたい場合は、環境ごとにパラメータを分ける、あるいは本番だけ明示的なバージョン ID を参照する、といった設計を検討した方がよさそうです。
ロールバックも少し手間があります。latest を以前のバージョンに付け替えるのではなく、戻したいペイロードと同じ内容で新しいバージョンを作る形になります。つまり、前の良品プロンプトをコピーして、新しいバージョンのペイロードとして貼り付ける必要があります。
また、開発中はシステム プロンプトを細かく調整するため、バージョンが増えやすいです。Parameter Manager はバージョン数や access operations に応じて課金されるため、試行錯誤で作った不要なバージョンは残しすぎない方がよいです。一方で、ロールバック用に残すべきバージョンまで消してしまわないよう、削除前にはバージョン一覧とペイロードを確認しておく必要があります。
運用するなら
今回の検証を踏まえると、システム プロンプトを Parameter Manager で管理するなら、次のような運用がよさそうです。
- 検証環境用と本番環境用でパラメータを分ける
- エージェントは基本的に
versions/latestを参照する
- 検証環境でプロンプトを調整し、期待する応答になることを確認する
- 本番反映時は、検証済みのペイロードを本番用パラメータの新しいバージョンとして追加する
- ロールバックが必要な場合は、戻したいペイロードを新しいバージョンとして追加する
- 不要な検証用バージョンは定期的に削除する
この流れであれば、開発中のプロンプト更新のしやすさと、本番環境への反映管理のバランスを取りやすいと感じました。
まとめ
Google ADK のパラメータを Parameter Manager で外だしできるかを検証し、今回はシステム プロンプトを例に実際に動かしてみました。
結果として、Parameter Manager に保存したプロンプトを Google ADK エージェントから読み取り、before_agent_callback 経由で instruction に反映する構成は問題なく使えました。versions/latest を参照すれば、コンソールから新しいバージョンを追加するだけでプロンプトを切り替えられます。
一方で、latest の即時反映、ロールバック時のコピー作業、バージョンの増加、軽いレイテンシは意識しておく必要があります。特に本番運用では、検証環境と本番環境でパラメータを分けて、どのペイロードを本番に反映するかを明確にしておくのがよさそうです。
参考
最後に
自社に専門人材がいない、リソースが足りない等の課題をお持ちの方に、エンジニア領域の支援サービス（Data Engineer Hub）をご提供しています。お困りごとがございましたら是非お気軽にご相談ください。
本件に関するお問い合わせは下記にて承ります。
株式会社DataCurrent
info@datacurrent.co.jp