ניהול סודות לשירותים חיצוניים בערכת פיתוח סוכנים

סוכנים של Agent Development Kit (ADK) יוצרים אינטראקציה עם שירותים חיצוניים מחוץ ל- Google Cloud. גם זהויות של סוכנים וגם ניהול זהויות והרשאות גישה (IAM) מאפשרים לכם לבצע אימות בשירותים של Google Cloud. עם זאת, הם לא יכולים להוכיח את הזהות שלהם בפלטפורמות חיצוניות שלא תומכות באיחוד הזהויות של Google.

סוכני ADK צריכים גישה לפרטי כניסה שונים כדי ליצור אינטראקציה עם ישויות חיצוניות כמו שירותי MCP, כלי ADK וממשקי API. דוגמאות נפוצות:

  • מפתחות API לפלטפורמות לעיבוד תשלומים
  • שילובי שם משתמש וסיסמה למסדי נתונים מדור קודם שפועלים בשרתים מקומיים
  • מפתחות פרטיים לחיבורים של פרוטוקול TLS הדדי (mTLS)
כדי לתמוך בתרחישי השימוש האלה, ADK מספק את המודול SecretManagerClient בחבילה google.adk.integrations.secret_manager.secret_client. המודול הזה מספק ממשק סטנדרטי לסוכנים לאחזור סודות מ-Secret Manager בזמן הריצה. במאמר הזה מוסבר איך לנהל סודות של שירותים חיצוניים ב-ADK באמצעות Secret Manager.

היתרונות של שימוש ב-Secret Manager עם ADK

ניהול ידני של סודות עלול ליצור סיכוני אבטחה ולהגדיל את העומס על המפתחים. Secret Manager יכול לעזור לפתור את הבעיות האלה באמצעות הפעולות הבאות:

  • אם מטמיעים סודות בקוד של הסוכן, נוצר סיכון אבטחה משמעותי. השימוש בשיטה הזו עלול להוביל לגישה לא מורשית למערכות ייצור. השימוש ב-Secret Manager מסיר נתונים רגישים מקוד המקור. כך האפליקציה שלכם תהיה מאובטחת יותר.
  • אם מטמיעים סודות סטטיים באמצעות משתני סביבה, סיבוב פרטי הכניסה הופך למורכב. כדי להחיל את העדכונים, צריך להפעיל מחדש את קובצי ה-deployment. מנהל הסודות מאחזר את פרטי הכניסה באופן דינמי בזמן הריצה, כך שאפשר לבצע עדכונים בלי להשבית את המערכת.
  • אם כותבים קוד שחוזר על עצמו (boilerplate) בהתאמה אישית לכל כלי, מגדילים את הטרחה של המפתחים ואת הסיכון לשגיאות.SecretManagerServiceClient שילוב ה-ADK התקני מספק גישה ברורה וניתנת לשימוש חוזר לאחזור פרטי כניסה.

לפני שמתחילים

לפני שמשלבים את Secret Manager עם ADK, צריך לבצע את הפעולות הבאות:

  1. הגדרת סוכן באמצעות ADK כדי להשתמש בתכונה הזו צריך ADK בגרסה 1.29 ואילך ל-Python.
  2. מקצים את תפקיד ה-IAM‏ Secret Manager Secret Accessor לזהות של הסוכן. התפקיד הזה מאפשר לסוכן לאחזר סודות בזמן ריצה.
  3. יוצרים סוד ומוסיפים גרסה של הסוד, כמו מפתח API, ב-Secret Manager.

איך סוכן ADK מאחזר סודות בזמן ריצה

מודול secret_client.SecretManagerClient מאחזר פרטי כניסה ללוגיקה של קוד הסוכן של Python בזמן הריצה. הלוגיקה של תזמור הסוכנים שולחת הנחיות למודל שפה גדול (LLM) כדי להחליט איזה כלי להפעיל, אבל המערכת לא שולחת את הסוד למודל השפה הגדול.

הסוכן מבצע את השלבים הבאים במהלך שלב זמן הריצה:

  1. לפני שאגנט ADK מפעיל כלי של צד שלישי, האגנט מאתחל את מודול SecretManagerClient ומפעיל את הפונקציה get_secret().
  2. סוכן ה-ADK משתמש בזהות הסוכן כדי לבצע אימות מול Secret Manager.
  3. מודול SecretManagerClient מחזיר את הסוד בטקסט לא מוצפן לסוכן ADK.
  4. הסוכן של ADK משתמש בסוד כדי לבצע קריאה מאומתת לכלי של צד שלישי.

שליפת סודות בסוכן ADK בזמן ריצה

בדוגמת הקוד הבאה אפשר לראות איך משתמשים במודול SecretManagerClient כדי לאחזר סוד בצורה מאובטחת בסוכן ADK. הסוכן מאחזר את הסוד באופן פנימי כדי למנוע חשיפה של פרטי כניסה רגישים לחלון ההקשר או להיסטוריית השיחות של ה-LLM.

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח בשפת Python ולהתקין את Secret Manager Python SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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.")

המאמרים הבאים