Gestire i segreti per i servizi esterni in Agent Development Kit

Gli agenti di Agent Development Kit (ADK) interagiscono con i servizi esterni Google Cloud. Sia le identità degli agenti sia Identity and Access Management (IAM) ti consentono di eseguire l'autenticazione con Google Cloud i servizi. Tuttavia, non possono dimostrare l'identità alle 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 i servizi MCP, gli strumenti ADK e le API. Ecco alcuni esempi comuni:

  • Chiavi API per le piattaforme di elaborazione dei pagamenti
  • Combinazioni di nome utente e password per i database on-premise legacy
  • Chiavi private per le connessioni mutual TLS (mTLS)
Per supportare questi casi d'uso, ADK fornisce il modulo SecretManagerClient all'interno del pacchetto google.adk.integrations.secret_manager.secret_client. Questo modulo fornisce un'interfaccia standard per gli agenti per recuperare i secret da Secret Manager in fase di runtime. Questo documento spiega come gestire i secret per i servizi esterni in ADK utilizzando Secret Manager.

Vantaggi dell'utilizzo di Secret Manager con ADK

La gestione manuale dei secret può comportare rischi per la sicurezza e aumentare il carico di lavoro degli sviluppatori. Secret Manager può aiutarti a risolvere questi problemi tramite quanto segue:

  • Se incorpori i secret nel codice dell'agente, crei un rischio per la sicurezza significativo. Questa pratica può portare ad accessi non autorizzati ai sistemi di produzione. L'utilizzo di Secret Manager rimuove i dati sensibili dal codice sorgente. In questo modo, l'applicazione è 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 gli aggiornamenti senza tempi di inattività del sistema.
  • Se scrivi codice boilerplate personalizzato SecretManagerServiceClient per ogni strumento, aumenti il carico di lavoro degli sviluppatori e il rischio di errori. L'integrazione ADK standardizzata 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 Secret Manager Secret Accessor ruolo IAM 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, l'agente inizializza il SecretManagerClient modulo e chiama la get_secret() funzione.
  2. L'agente ADK utilizza l'identità dell'agente per eseguire l'autenticazione 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 un secret in modo sicuro all'interno di un agente ADK. L'agente recupera il secret internamente per evitare di esporre le credenziali sensibili alla finestra contestuale o alla cronologia delle conversazioni dell'LLM.

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito 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.")

Passaggi successivi