Secrets für externe Dienste im Agent Development Kit verwalten

Agenten des Agent Development Kit (ADK) interagieren mit externen Diensten außerhalb von Google Cloud. Sowohl Agentenidentitäten als auch Identity and Access Management (IAM) ermöglichen die Authentifizierung bei Google Cloud Diensten. Sie können jedoch die 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 Entitäten wie MCP-Diensten, ADK-Tools und APIs zu interagieren. Häufige Beispiele sind:

• API-Schlüssel für Plattformen zur Zahlungsabwicklung
• Kombinationen aus Nutzernamen und Passwörtern für ältere lokale Datenbanken
• Private Schlüssel für Verbindungen mit gegenseitiger TLS-Authentifizierung (mTLS)

Vorteile der Verwendung von Secret Manager mit dem ADK

Die manuelle Secret-Verwaltung kann Sicherheitsrisiken mit sich bringen und den Aufwand für Entwickler erhöhen. Secret Manager kann diese Probleme durch Folgendes beheben:

• Wenn Sie Secrets in den Agentencode 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. Dadurch wird Ihre Anwendung sicherer.
• Wenn Sie statische Secrets über Umgebungsvariablen einbetten, wird die Rotation von Anmeldedaten kompliziert. Um Updates anzuwenden, müssen Sie Bereitstellungscontainer neu starten. Secret Manager ruft Anmeldedaten zur Laufzeit dynamisch ab, sodass Updates ohne Systemausfallzeiten möglich sind.
• 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

Führen Sie vor der Einbindung von Secret Manager in das ADK die folgenden Schritte aus:

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

So ruft ein ADK-Agent Secrets zur Laufzeit ab

Das Modul secret_client.SecretManagerClient ruft Anmeldedaten in die Python-Agentenlogik zur Laufzeit ab. Die Agentenorchestrierungslogik sendet Prompts an das Large Language Model (LLM), um zu entscheiden, welches Tool ausgeführt werden soll. Das Secret wird jedoch nicht an das LLM gesendet.

Der 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 get_secret() Funktion auf.
2. Der ADK-Agent verwendet die Agentenidentität, um sich bei Secret Manager zu authentifizieren.
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 zur 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 im 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 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.")

Nächste Schritte

• Agent Development Kit