Administra secretos para servicios externos en el Kit de desarrollo de agentes

Los agentes del Kit de desarrollo de agentes (ADK) interactúan con servicios externos fuera de Cloud de Confiance by S3NS. Tanto las identidades de los agentes como Identity and Access Management (IAM) te permiten autenticarte con Cloud de Confiance by S3NSlos servicios. Sin embargo, no pueden demostrar la identidad a plataformas externas que no admiten la federación de identidades de Google.

Los agentes del ADK requieren acceso a varias credenciales para interactuar con entidades externas, como servicios de MCP, herramientas del ADK y APIs. Algunos ejemplos comunes incluyen los siguientes:

• Claves de API para plataformas de procesamiento de pagos
• Combinaciones de nombre de usuario y contraseña para bases de datos heredadas locales
• Claves privadas para conexiones TLS mutuas (mTLS)

Ventajas de usar Secret Manager con el ADK

La administración manual de secretos puede generar riesgos de seguridad y aumentar el esfuerzo de los desarrolladores. Secret Manager puede ayudar a resolver estos problemas de la siguiente manera:

• Si incorporas secretos en el código del agente, creas un riesgo de seguridad significativo. Esta práctica puede generar acceso no autorizado a los sistemas de producción. El uso de Secret Manager quita los datos sensibles de tu código fuente. Esto ayuda a que tu aplicación sea más segura.
• Si incorporas secretos estáticos a través de variables de entorno, la rotación de credenciales se vuelve complicada. Para aplicar actualizaciones, debes reiniciar los contenedores de implementación. Secret Manager recupera las credenciales de forma dinámica en el tiempo de ejecución, lo que permite realizar actualizaciones sin tiempo de inactividad del sistema.
• Si escribes código estándar SecretManagerServiceClient personalizado para cada herramienta, aumentas el esfuerzo de los desarrolladores y el riesgo de errores. La integración estandarizada del ADK proporciona un enfoque limpio y reutilizable para recuperar credenciales.

Antes de comenzar

Antes de integrar Secret Manager con el ADK, completa lo siguiente:

1. Configura un agente con el ADK. Esta función requiere la versión 1.29 del ADK o una posterior para Python.
2. Otorga el Secret Manager Secret Accessor rol de IAM a la identidad del agente. Este rol permite que tu agente recupere secretos en el tiempo de ejecución.
3. Crea un secreto y agrega una versión secreta, como una clave de API, en Secret Manager.

Cómo un agente del ADK recupera secretos en el tiempo de ejecución

El módulo secret_client.SecretManagerClient recupera credenciales en la lógica del código del agente de Python en el tiempo de ejecución. La lógica de organización del agente envía mensajes al modelo de lenguaje grande (LLM) para decidir qué herramienta ejecutar, pero el sistema no envía el secreto al LLM.

El agente ejecuta los siguientes pasos durante la fase de tiempo de ejecución:

1. Antes de que un agente del ADK invoque una herramienta de terceros, el agente inicializa el SecretManagerClient módulo y llama a la get_secret() función.
2. El agente del ADK usa la identidad del agente para autenticarse con Secret Manager.
3. El módulo SecretManagerClient devuelve el secreto de texto simple al agente del ADK.
4. El agente del ADK usa el secreto para realizar una llamada autenticada a la herramienta de terceros.

Recupera secretos dentro de un agente del ADK en el tiempo de ejecución

En el siguiente muestra de código, se muestra cómo puedes usar el módulo SecretManagerClient para recuperar un secreto de forma segura dentro de un agente del ADK. El agente recupera el secreto de forma interna para evitar exponer credenciales sensibles a la ventana de contexto o al historial de conversaciones del 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.")

¿Qué sigue?

• Explora el Kit de desarrollo de agentes.