Regionale Secrets für externe Dienste im Agent Development Kit verwalten

Agent Development Kit (ADK)-Agents interagieren mit externen Diensten außerhalb von Cloud de Confiance by S3NS. Sowohl Agent-Identitäten als auch Identity and Access Management (IAM) ermöglichen die Authentifizierung bei Cloud de Confiance by S3NS-Diensten. Sie können jedoch ihre Identität nicht gegenüber externen Plattformen nachweisen, die die Identitätsföderation von Google nicht unterstützen.

ADK-Agenten benötigen Zugriff auf verschiedene Anmeldedaten, um mit externen Einheiten wie MCP-Diensten, ADK-Tools und APIs interagieren zu können. Hier einige Beispiele:

• API-Schlüssel für Zahlungsabwicklungsplattformen
• Kombinationen aus Nutzernamen und Passwörtern für Legacy-On-Premise-Datenbanken
• Private Schlüssel für gegenseitige TLS-Verbindungen (mTLS)

Vorteile der Verwendung von Secret Manager mit dem ADK

Die manuelle Verwaltung von Secrets kann Sicherheitsrisiken mit sich bringen und den Arbeitsaufwand für Entwickler erhöhen. Secret Manager kann diese Probleme auf folgende Weise beheben:

• Wenn Sie Secrets in den Agent-Code einbetten, entsteht ein erhebliches Sicherheitsrisiko. Diese Vorgehensweise kann zu unbefugtem Zugriff auf Produktionssysteme führen. Durch die Verwendung von Secret Manager werden vertrauliche Daten aus Ihrem Quellcode entfernt. So wird Ihre Anwendung sicherer.
• Wenn Sie statische Secrets über Umgebungsvariablen einbetten, wird die Rotation von Anmeldedaten kompliziert. Damit Updates angewendet werden, müssen Sie die Bereitstellungscontainer neu starten. Secret Manager ruft Anmeldedaten dynamisch zur Laufzeit ab. So sind Aktualisierungen ohne Systemausfallzeiten möglich.
• Wenn Sie für jedes Tool benutzerdefinierten SecretManagerServiceClient-Boilerplate-Code schreiben, erhöhen Sie den Aufwand für Entwickler und das Fehlerrisiko. Die standardisierte ADK-Integration bietet einen sauberen, wiederverwendbaren Ansatz zum Abrufen von Anmeldedaten.

Hinweis

Bevor Sie Secret Manager in das ADK einbinden, müssen Sie Folgendes tun:

1. KI-Agent mit dem ADK einrichten Für diese Funktion ist ADK-Version 1.29 oder höher für Python erforderlich.
2. Weisen Sie der Agent-Identität die IAM-Rolle Secret Manager Secret Accessor zu. Mit dieser Rolle kann Ihr Agent zur Laufzeit Secrets abrufen.
3. Erstellen Sie das regionale Secret und fügen Sie eine regionale Secret-Version hinzu, z. B. einen API-Schlüssel, in Secret Manager.

So ruft ein ADK-Agent zur Laufzeit Secrets ab

Das Modul secret_client.SecretManagerClient ruft Anmeldedaten zur Laufzeit in der Python-Agent-Code-Logik ab. Die Orchestrierungslogik des Agents sendet Prompts an das Large Language Model (LLM), um zu entscheiden, welches Tool ausgeführt werden soll. Das System sendet das Secret jedoch nicht an das LLM.

Der KI-Agent führt während der Laufzeitphase die folgenden Schritte aus:

1. Bevor ein ADK-Agent ein Drittanbietertool aufruft, initialisiert er das SecretManagerClient-Modul und ruft die Funktion get_secret() auf.
2. Der ADK-Agent verwendet die Agentenidentität zur Authentifizierung bei Secret Manager.
3. Das Modul SecretManagerClient gibt das Secret im Klartext an den ADK-Agenten zurück.
4. Der ADK-Agent verwendet das Secret, um einen authentifizierten Aufruf an das Drittanbietertool zu senden.

Secrets während der Laufzeit in einem ADK-Agenten abrufen

Das folgende Codebeispiel zeigt, wie Sie das Modul SecretManagerClient verwenden können, um ein Secret sicher in einem ADK-Agenten abzurufen. Der Agent ruft das Secret intern ab, um zu verhindern, dass vertrauliche Anmeldedaten im Kontextfenster oder Unterhaltungsverlauf des LLM offengelegt werden.

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

Nächste Schritte

• Agent Development Kit