יצירה ופריסה של סוכן באמצעות Agent CLI ו-Agent Identity

במדריך הזה נסביר איך ליצור ולפרוס סוכן ב-Agent Runtime ב-Gemini Enterprise Agent Platform עם Agent Identity מופעלת.

Agent Identity מקצה זהות SPIFFE מאובטחת לסוכן הפרוס. הסוכן משתמש בזהות הזו כדי לבצע אימות מול שירותי Cloud de Confiance by S3NS ולשלוף פרטי כניסה ממנהל האימות של Agent Identity.

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

  1. מפעילים את ממשקי ה-API ‏Agent Identity API,‏ Agent Platform API,‏ Agent Registry API ו-App Hub API (מרכז האפליקציות), אם הם עדיין לא מופעלים.

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    הפעלת ממשקי ה-API

  2. מוודאים שיש לכם את התפקיד Agent Platform User (roles/aiplatform.user) בפרויקט.

יצירה ופריסה של הסוכן

יצירת סוכן לדוגמה באמצעות google-agents-cli ופריסתו באמצעות Agent Identity:

  1. מתקינים את uv ומריצים את ההגדרה של google-agents-cli:

    pip install uv
uvx google-agents-cli setup

  2. יוצרים פרויקט של סוכן באמצעות תבנית אב טיפוס:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    מחליפים את AGENT_PROJECT בשם של ספריית הפרויקט החדשה של הסוכן (לדוגמה, maps-agent).

    הפקודה הזו יוצרת את מבנה ספריית הפרויקט הבא:

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. משנים את השם של תיקיית האפליקציה שמוגדרת כברירת מחדל (app) כך שיתאים לשם הסוכן (לדוגמה, AGENT_NAME, maps_agent). שמות הסוכנים צריכים להיות מזהה Python תקין: הם צריכים להתחיל באות ולכלול רק אותיות, מספרים וקווים תחתונים.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. מעדכנים את קובץ ההגדרות agent.py כך שישקף את השם החדש:

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. בוחרים מודל לשימוש על סמך הזמינות האזורית שלו. מעדכנים את הערך של MODEL ב-agent.py כך שיתאים למודל שבחרתם.

    פתרון עקיף למודלים שזמינים רק באזור global

    כדי להשתמש במודל שזמין רק באזור global, צריך לשנות את agent.py כך שהסוכן יוכל לגשת אליו.

    1. מוסיפים את ההצהרות הבאות של ייבוא:

      from functools import cached_property
from google.genai import Client

    2. מוסיפים את מחלקת המשנה הבאה אחרי הייבוא:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. מחפשים את הקוד הבא:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      משנים את ההפניה למחלקת המשנה החדשה:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. כדי להפעיל את Agent Identity, יוצרים קובץ תצורה:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. יוצרים קובץ requirements.txt לתלות בפריסה:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. אימות מבנה ספריית הפרויקט:

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. בודקים את הסוכן באופן מקומי:

    ‫
    uv run adk web . --port 8501 --reload_agents

    כדי לאמת את הנציג:

    1. עוברים אל http://localhost:8501. אפשרות אחרת: אם אתם משתמשים ב-Cloud Shell, לוחצים על הקישור שמופיע בפלט של שרת האינטרנט.

    2. בממשק הצ'אט, שולחים הנחיית בדיקה כדי לוודא שהתשובה נכונה.

  10. מפסיקים את השרת באמצעות CTRL+C.

  11. פריסת הסוכן ב Cloud de Confiance:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance .

    • ‫LOCATION: האזור הנתמך שבו רוצים לפרוס את הסוכן (לדוגמה, us-west1).

    הפריסה יכולה להימשך כמה דקות. בסיום התהליך, ממשק שורת הפקודה (CLI) מציג הודעת אישור וקישור לארגז החול של הנציג ב Cloud de Confiance מסוף.

  12. אחזור מזהה ה-SPIFFE של הסוכן (Agent Identity):

    1. נכנסים לדף Deployments במסוף Cloud de Confiance .

      מעבר לדף Deployments

    2. כדי להעתיק את מזהה ה-SPIFFE של הסוכן ללוח, מאתרים את השורה שבה נמצא הסוכן שהופעל, ובעמודה זהות של השורה הזו לוחצים על העתקה ללוח. הזהות תיראה בערך כך: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

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