Gerenciar Secrets para serviços externos no Kit de Desenvolvimento de Agente

Os agentes do Kit de Desenvolvimento de Agente (ADK, na sigla em inglês) interagem com serviços externos fora do Cloud de Confiance by S3NS. As identidades de agente e Identity and Access Management (IAM) permitem que você faça a autenticação com Cloud de Confiance by S3NS serviços. No entanto, eles não podem comprovar a identidade para plataformas externas que não oferecem suporte à federação de identidade do Google.

Os agentes do ADK exigem acesso a várias credenciais para interagir com entidades externas, como serviços do MCP, ferramentas do ADK e APIs. Confira alguns exemplos comuns:

• Chaves de API para plataformas de processamento de pagamentos
• Combinações de nome de usuário e senha para bancos de dados legados locais
• Chaves privadas para conexões TLS mútuas (mTLS)

Vantagens de usar o Secret Manager com o ADK

O gerenciamento manual de secrets pode gerar riscos de segurança e aumentar o trabalho dos desenvolvedores. O Secret Manager pode ajudar a resolver esses problemas das seguintes maneiras:

• Se você incorporar secrets no código do agente, vai criar um risco de segurança significativo. Essa prática pode levar a acessos não autorizados a sistemas de produção. O uso do Secret Manager remove dados sensíveis do código-fonte. Isso ajuda a tornar o aplicativo mais seguro.
• Se você incorporar secrets estáticos usando variáveis de ambiente, a rotação de credenciais se torna complicada. Para aplicar atualizações, é necessário reiniciar os contêineres de implantação. O Secret Manager recupera credenciais de forma dinâmica no ambiente de execução, o que permite atualizações sem tempo de inatividade do sistema.
• Se você escrever um SecretManagerServiceClientcódigo boilerplate personalizado para cada ferramenta, vai aumentar o trabalho dos desenvolvedores e o risco de erros. A integração padronizada do ADK oferece uma abordagem limpa e reutilizável para recuperar credenciais.

Antes de começar

Antes de integrar o Secret Manager ao ADK, faça o seguinte:

1. Configure um agente usando o ADK. Esse recurso exige a versão 1.29 ou mais recente do ADK para Python.
2. Conceda o Secret Manager Secret Accessor papel do IAM à identidade do agente. Esse papel permite que o agente recupere secrets no ambiente de execução.
3. Crie um secret e adicione uma versão dele, como uma chave de API, no Secret Manager.

Como um agente do ADK recupera secrets no ambiente de execução

O módulo secret_client.SecretManagerClient recupera credenciais na lógica do código do agente Python no ambiente de execução. A lógica de orquestração do agente envia comandos ao modelo de linguagem grande (LLM) para decidir qual ferramenta executar, mas o sistema não envia o secret ao LLM.

O agente executa as etapas a seguir durante a fase de execução:

1. Antes que um agente do ADK invoque uma ferramenta de terceiros, ele inicializa o SecretManagerClient módulo e chama a get_secret() função.
2. O agente do ADK usa a identidade do agente para fazer a autenticação com Secret Manager.
3. O módulo SecretManagerClient retorna o secret de texto simples ao agente do ADK.
4. O agente do ADK usa o secret para fazer uma chamada autenticada para a ferramenta de terceiros.

Recuperar secrets em um agente do ADK no ambiente de execução

O exemplo de código a seguir mostra como usar o módulo SecretManagerClient para recuperar um secret com segurança em um agente do ADK. O agente recupera o secret internamente para evitar a exposição de credenciais sensíveis à janela de contexto ou ao histórico de conversas do 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.")

A seguir

• Conheça o Kit de Desenvolvimento de Agente.