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

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

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

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

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

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

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

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