Gérer les secrets régionaux pour les services externes dans le kit de développement d'agent

Les agents Agent Development Kit (ADK) interagissent avec des services externes en dehors de Cloud de Confiance by S3NS. Les identités d'agent et Identity and Access Management (IAM) vous permettent de vous authentifier auprès des services Cloud de Confiance by S3NS. Toutefois, ils ne peuvent pas prouver leur identité auprès de plates-formes externes qui ne sont pas compatibles avec la fédération d'identité de Google.

Les agents ADK ont besoin d'accéder à différents identifiants pour interagir avec des entités externes telles que les services MCP, les outils ADK et les API. Voici quelques exemples courants :

• Clés API pour les plates-formes de traitement des paiements
• Combinaisons de nom d'utilisateur et de mot de passe pour les anciennes bases de données sur site
• Clés privées pour les connexions TLS mutuelles (mTLS)

Avantages de l'utilisation de Secret Manager avec ADK

La gestion manuelle des secrets peut entraîner des risques de sécurité et augmenter la charge de travail des développeurs. Secret Manager peut vous aider à résoudre ces problèmes grâce aux fonctionnalités suivantes :

• Si vous intégrez des secrets dans le code de l'agent, vous créez un risque de sécurité important. Cette pratique peut entraîner un accès non autorisé aux systèmes de production. L'utilisation de Secret Manager permet de supprimer les données sensibles de votre code source. Cela permet de renforcer la sécurité de votre application.
• Si vous intégrez des secrets statiques via des variables d'environnement, la rotation des identifiants devient compliquée. Pour appliquer les mises à jour, vous devez redémarrer les conteneurs de déploiement. Secret Manager récupère les identifiants de manière dynamique au moment de l'exécution, ce qui permet de les mettre à jour sans temps d'arrêt du système.
• Si vous écrivez du code SecretManagerServiceClient standard personnalisé pour chaque outil, vous augmentez le travail fastidieux des développeurs et le risque d'erreurs. L'intégration standardisée de l'ADK fournit une approche propre et réutilisable pour récupérer les identifiants.

Avant de commencer

Avant d'intégrer Secret Manager à ADK, procédez comme suit :

1. Configurez un agent à l'aide d'ADK. Cette fonctionnalité nécessite l'ADK version 1.29 ou ultérieure pour Python.
2. Attribuez le rôle IAM Secret Manager Secret Accessor à l'identité de l'agent. Ce rôle permet à votre agent de récupérer des secrets au moment de l'exécution.
3. Créez le secret régional et ajoutez une version du secret régional, par exemple une clé API, dans Secret Manager.

Comment un agent ADK récupère les secrets au moment de l'exécution

Le module secret_client.SecretManagerClient récupère les identifiants dans la logique du code de l'agent Python au moment de l'exécution. La logique d'orchestration de l'agent envoie des requêtes au grand modèle de langage (LLM) pour décider quel outil exécuter, mais le système n'envoie pas le secret au LLM.

L'agent exécute les étapes suivantes pendant la phase d'exécution :

1. Avant qu'un agent ADK n'appelle un outil tiers, il initialise le module SecretManagerClient et appelle la fonction get_secret().
2. L'agent ADK utilise l'identité de l'agent pour s'authentifier auprès de Secret Manager.
3. Le module SecretManagerClient renvoie le secret en texte brut à l'agent ADK.
4. L'agent ADK utilise le secret pour effectuer un appel authentifié à l'outil tiers.

Récupérer des secrets dans un agent ADK au moment de l'exécution

L'exemple de code suivant montre comment utiliser le module SecretManagerClient pour récupérer un secret de manière sécurisée dans un agent ADK. L'agent récupère le secret en interne pour éviter d'exposer des identifiants sensibles à la fenêtre de contexte ou à l'historique des conversations du LLM.

#!/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 regional Secret Manager.
"""

import os

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

# Fetch secret from regional Secret Manager
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_PROJECT_LOCATION")
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 location or not secret_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_PROJECT_LOCATION, and ADK_TEST_SECRET_ID environment variables must be set.")

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

print(f"Fetching secret from regional Secret Manager ({location})...")
# Initialize Secret Manager Client (Regional)
client = SecretManagerClient(location=location)

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

Étapes suivantes

• Découvrez Agent Development Kit.