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

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

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

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

  1. מפעילים את ממשקי ה-API‏ Agent Identity API,‏ Agent Platform API,‏ Agent Registry API ו-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. כדי להפעיל את הזהות של הסוכן, יוצרים קובץ תצורה:

    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. פריסת הסוכן ב Google Cloud:

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

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

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

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

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

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

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

      מעבר לדף Deployments

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

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