Agent Development Kit で外部サービスのシークレットを管理する

Agent Development Kit（ADK）エージェントは、 Google Cloudの外部にある外部サービスとやり取りします。エージェント ID と Identity and Access Management（IAM）の両方で、 Google Cloudサービスを使用して認証できます。ただし、Google の ID 連携をサポートしていない外部プラットフォームに対して ID を証明することはできません。

ADK エージェントは、MCP サービス、ADK ツール、API などの外部エンティティとやり取りするために、さまざまな認証情報へのアクセスを必要とします。一般的な例は次のとおりです。

  • 決済処理プラットフォームの API キー
  • 以前のオンプレミス データベースのユーザー名とパスワードの組み合わせ
  • 相互 TLS（mTLS）接続の秘密鍵
これらのユースケースをサポートするために、ADK は google.adk.integrations.secret_manager.secret_client パッケージ内に SecretManagerClient モジュールを提供します。このモジュールは、エージェントが実行時に Secret Manager からシークレットを取得するための標準インターフェースを提供します。このドキュメントでは、Secret Manager を使用して ADK の外部サービスのシークレットを管理する方法について説明します。

ADK で Secret Manager を使用するメリット

シークレットを手動で管理すると、セキュリティ リスクが生じ、デベロッパーのトイルが増加する可能性があります。Secret Manager は、次の方法でこれらの問題の解決に役立ちます。

  • シークレットをエージェント コードに埋め込むと、重大なセキュリティ リスクが生じます。この方法では、本番環境システムへの不正アクセスにつながる可能性があります。Secret Manager を使用すると、ソースコードから機密データが削除されます。これにより、アプリケーションのセキュリティが強化されます。
  • 環境変数を使用して静的シークレットを埋め込むと、認証情報のローテーションが複雑になります。更新を適用するには、デプロイ コンテナを再起動する必要があります。Secret Manager は実行時に認証情報を動的に取得するため、システムのダウンタイムなしで更新できます。
  • ツールごとにカスタム SecretManagerServiceClient ボイラープレート コードを作成すると、デベロッパーのトイルが増え、エラーのリスクが高まります。標準化された ADK 統合により、認証情報を取得するためのクリーンで再利用可能なアプローチが提供されます。

始める前に

Secret Manager を ADK と統合する前に、次の操作を行います。

  1. ADK を使用してエージェントを設定します。この機能には、Python 用の ADK バージョン 1.29 以降が必要です。
  2. エージェント ID に Secret Manager Secret Accessor IAM ロールを付与します。このロールにより、エージェントは実行時にシークレットを取得できます。
  3. Secret Manager で シークレットを作成し、API キーなどのシークレット バージョンを追加します。

ADK エージェントがランタイムにシークレットを取得する方法

secret_client.SecretManagerClient モジュールは、実行時に Python エージェント コードのロジックに認証情報を取得します。エージェント オーケストレーション ロジックは、実行するツールを決定するために大規模言語モデル（LLM）にプロンプトを送信しますが、システムはシークレットを LLM に送信しません。

エージェントは、ランタイム フェーズで次の手順を実行します。

  1. ADK エージェントがサードパーティ ツールを呼び出す前に、エージェントは SecretManagerClient モジュールを初期化し、get_secret() 関数を呼び出します。
  2. ADK エージェントは、エージェント ID を使用して Secret Manager で認証を行います。
  3. SecretManagerClient モジュールは、平文のシークレットを ADK エージェントに返します。
  4. ADK エージェントは、このシークレットを使用してサードパーティ製ツールへの認証済み呼び出しを行います。

実行時に ADK エージェント内のシークレットを取得する

次のコードサンプルは、SecretManagerClient モジュールを使用して ADK エージェント内でシークレットを安全に取得する方法を示しています。エージェントは、機密性の高い認証情報が LLM のコンテキスト ウィンドウや会話履歴に公開されないように、シークレットを内部的に取得します。

Python

このコードを実行するには、まず Python 開発環境を設定し、Secret Manager Python SDK をインストールします。Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

#!/usr/bin/env python

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
"""
ADK agent for accessing secrets from global Secret Manager.
"""

import os

from google.adk import Agent
from google.adk.integrations.secret_manager.secret_client import SecretManagerClient

# Fetch secret from global Secret Manager
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
secret_id = os.environ.get("ADK_TEST_SECRET_ID")
secret_version = os.environ.get("ADK_TEST_SECRET_VERSION", "latest")

if not project_id or not secret_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT and ADK_TEST_SECRET_ID environment variables must be set.")

resource_name = f"projects/{project_id}/secrets/{secret_id}/versions/{secret_version}"

print("Fetching secret from global Secret Manager...")
# Initialize Secret Manager Client (Global)
client = SecretManagerClient()

# Fetch secret
try:
    secret_payload = client.get_secret(resource_name)
    print("Successfully fetched secret.")
    # The secret_payload can now be used by the agent or its tools as required.
except Exception as e:
    print(f"Error fetching secret: {e}")
    raise e

# Initialize Agent
root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

print("Agent initialized successfully.")

次のステップ