Mengelola secret untuk layanan eksternal di Agent Development Kit

Agen Agent Development Kit (ADK) berinteraksi dengan layanan eksternal di luar Google Cloud. Baik identitas agen maupun Identity and Access Management (IAM) memungkinkan Anda melakukan autentikasi dengan layanan Google Cloud. Namun, mereka tidak dapat membuktikan identitas ke platform eksternal yang tidak mendukung federasi identitas Google.

Agen ADK memerlukan akses ke berbagai kredensial untuk berinteraksi dengan entitas eksternal seperti layanan MCP, alat ADK, dan API. Contoh umum meliputi:

• Kunci API untuk platform pemrosesan pembayaran
• Kombinasi nama pengguna dan sandi untuk database lokal lama
• Kunci pribadi untuk koneksi mutual TLS (mTLS)

Keuntungan menggunakan Secret Manager dengan ADK

Pengelolaan secret secara manual dapat menimbulkan risiko keamanan dan meningkatkan kesulitan developer. Secret Manager dapat membantu mengatasi masalah ini melalui hal berikut:

• Jika menyematkan secret dalam kode agen, Anda akan menimbulkan risiko keamanan yang signifikan. Praktik ini dapat menyebabkan akses tidak sah ke sistem produksi. Menggunakan Secret Manager akan menghapus data sensitif dari kode sumber Anda. Hal ini membantu membuat aplikasi Anda lebih aman.
• Jika Anda menyematkan secret statis melalui variabel lingkungan, rotasi kredensial menjadi rumit. Untuk menerapkan update, Anda harus memulai ulang penampung deployment. Secret Manager mengambil kredensial secara dinamis saat runtime, yang memungkinkan pembaruan tanpa waktu non-operasional sistem.
• Jika Anda menulis kode boilerplate SecretManagerServiceClient kustom untuk setiap alat, Anda meningkatkan kerja keras developer dan risiko error. Integrasi ADK yang standar memberikan pendekatan yang bersih dan dapat digunakan kembali untuk mengambil kredensial.

Sebelum memulai

Sebelum Anda mengintegrasikan Secret Manager dengan ADK, selesaikan langkah-langkah berikut:

1. Siapkan agen menggunakan ADK. Fitur ini memerlukan ADK versi 1.29 atau yang lebih baru untuk Python.
2. Berikan peran IAM Secret Manager Secret Accessor ke identitas agen. Peran ini memungkinkan agen Anda mengambil secret saat runtime.
3. Buat secret dan tambahkan versi secret, seperti kunci API, di Secret Manager.

Cara agen ADK mengambil secret saat runtime

Modul secret_client.SecretManagerClient mengambil kredensial ke dalam logika kode agen Python saat runtime. Logika orkestrasi agen mengirimkan perintah ke model bahasa besar (LLM) untuk memutuskan alat mana yang akan dijalankan, tetapi sistem tidak mengirimkan rahasia ke LLM.

Agen menjalankan langkah-langkah berikut selama fase runtime:

1. Sebelum agen ADK memanggil alat pihak ketiga, agen menginisialisasi modul SecretManagerClient dan memanggil fungsi get_secret().
2. Agen ADK menggunakan identitas agen untuk mengautentikasi dengan Secret Manager.
3. Modul SecretManagerClient menampilkan secret teks biasa ke agen ADK.
4. Agen ADK menggunakan rahasia untuk melakukan panggilan yang diautentikasi ke alat pihak ketiga.

Mengambil secret dalam agen ADK saat runtime

Contoh kode berikut menunjukkan cara menggunakan modul SecretManagerClient untuk mengambil rahasia secara aman dalam agen ADK. Agen mengambil rahasia secara internal untuk mencegah tereksposnya kredensial sensitif ke jendela konteks atau histori percakapan 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.")

Langkah berikutnya

• Jelajahi Agent Development Kit.