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

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

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

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

  1. מפעילים את Agent Identity Connector API.

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

    כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

    להפעלת ה-API

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

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

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

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

    pip install google-agents-cli uv
agents-cli setup

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

    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):

    mv app AGENT_NAME

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

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

  4. כדי להפעיל את הזהות של הסוכן, יוצרים קובץ תצורה:

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

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

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

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

    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

    אימות הנציג באופן מקומי:

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

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

    1. עוברים אל http://localhost:8501.
    2. בממשק הצ'אט, שולחים הנחיית בדיקה כדי לוודא שהתשובה נכונה.

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

  8. מאחזרים את מזהה ה-SPIFFE של הסוכן (זהות הסוכן) מהמסוףGoogle Cloud :

    1. נכנסים לדף Agent Platform במסוף Google Cloud .
    2. לוחצים על הכרטיסייה פריסות ובוחרים את הסוכן שנפרס.
    3. מעתיקים את הערך של Agent Identity (לדוגמה, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

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