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

‫Agent Identity מאפשר לכם להקצות זהות מנוהלת לסוכנים שאתם יוצרים ופורסים ב-Agent Runtime ב-Gemini Enterprise Agent Platform באמצעות Agent CLI והערכה לפיתוח סוכנים (ADK). הסוכן שנפרס יכול לבצע אימות לשירותיGoogle Cloud ולאחזר פרטי כניסה ממנהל האימות של Agent Identity בלי ניהול ידני של פרטי הכניסה.

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

  1. מפעילים את ממשקי ה-API הבאים, אם הם עדיין לא מופעלים: Agent Identity API,‏ Agent Platform API,‏ Agent Registry API ו-App Hub API.

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

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

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

  2. מוודאים שיש לכם את התפקיד משתמש בפלטפורמת הסוכנים (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. פורסים את הסוכן ב- 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 של הסוכן (Agent Identity):

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

      מעבר אל Deployments

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

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