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.")

次のステップ