Gestire i segreti per i servizi esterni in Agent Development Kit

Gli agenti Agent Development Kit (ADK) interagiscono con servizi esterni al di fuori di Google Cloud. Sia le identità agent sia Identity and Access Management (IAM) ti consentono di autenticarti con i servizi Google Cloud. Tuttavia, non possono dimostrare la propria identità a piattaforme esterne che non supportano la federazione delle identità di Google.

Gli agenti ADK richiedono l'accesso a varie credenziali per interagire con entità esterne come servizi MCP, strumenti ADK e API. Ecco alcuni esempi comuni:

• Chiavi API per piattaforme di elaborazione dei pagamenti
• Combinazioni di nome utente e password per database on-premise legacy
• Chiavi private per le connessioni mutual TLS (mTLS)

Vantaggi dell'utilizzo di Secret Manager con ADK

La gestione manuale dei secret può introdurre rischi per la sicurezza e aumentare il lavoro manuale degli sviluppatori. Secret Manager può aiutarti a risolvere questi problemi nei seguenti modi:

• Se incorpori i secret nel codice dell'agente, crei un rischio per la sicurezza significativo. Questa pratica può portare a un accesso non autorizzato ai sistemi di produzione. L'utilizzo di Secret Manager rimuove i dati sensibili dal codice sorgente. In questo modo, la tua applicazione sarà più sicura.
• Se incorpori secret statici tramite variabili di ambiente, la rotazione delle credenziali diventa complicata. Per applicare gli aggiornamenti, devi riavviare i container di deployment. Secret Manager recupera le credenziali in modo dinamico in fase di runtime, il che consente di eseguire aggiornamenti senza tempi di inattività del sistema.
• Se scrivi codice SecretManagerServiceClient boilerplate personalizzato per ogni strumento, aumenti il lavoro degli sviluppatori e il rischio di errori. L'integrazione standardizzata dell'ADK fornisce un approccio pulito e riutilizzabile per recuperare le credenziali.

Prima di iniziare

Prima di integrare Secret Manager con ADK, completa i seguenti passaggi:

1. Configura un agente utilizzando ADK. Questa funzionalità richiede ADK versione 1.29 o successive per Python.
2. Concedi il ruolo IAM Secret Manager Secret Accessor all'identità dell'agente. Questo ruolo consente all'agente di recuperare i secret in fase di runtime.
3. Crea un secret e aggiungi una versione del secret, ad esempio una chiave API, in Secret Manager.

Come un agente ADK recupera i secret in fase di runtime

Il modulo secret_client.SecretManagerClient recupera le credenziali nella logica del codice dell'agente Python in fase di runtime. La logica di orchestrazione dell'agente invia prompt al modello linguistico di grandi dimensioni (LLM) per decidere quale strumento eseguire, ma il sistema non invia il secret all'LLM.

L'agente esegue i seguenti passaggi durante la fase di runtime:

1. Prima che un agente ADK richiami uno strumento di terze parti, inizializza il modulo SecretManagerClient e chiama la funzione get_secret().
2. L'agente ADK utilizza l'identità dell'agente per autenticarsi con Secret Manager.
3. Il modulo SecretManagerClient restituisce il secret in testo non crittografato all'agente ADK.
4. L'agente ADK utilizza il secret per effettuare una chiamata autenticata allo strumento di terze parti.

Recuperare i secret all'interno di un agente ADK in fase di runtime

Il seguente esempio di codice mostra come utilizzare il modulo SecretManagerClient per recuperare in modo sicuro un secret all'interno di un agente ADK. L'agente recupera il secret internamente per evitare di esporre credenziali sensibili alla finestra contestuale o alla cronologia delle conversazioni dell'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 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.")

Passaggi successivi

• Esplora l'Agent Development Kit.