מדריך למתחילים בנושא ארגז חול של Shell

ארגז חול של מעטפת הוא קונטיינר מבודד ומנוהל של Linux שמצורף למופע של Agent Platform. ארגז החול מריץ פקודת מעטפת שנשלחת על ידי הסוכן ומחזיר stdout,‏ stderr וקוד יציאה. שום דבר לא פועל בתשתית שלכם, והמאגר מושמד כשמסירים את ארגז החול.

משתמשים בארגז חול של מעטפת כשסוכן צריך להריץ פקודות מעטפת לא מהימנות או שנוצרו על ידי AI, להתקין חבילות, לשנות קבצים או להפעיל כלים של שורת פקודה בלי לחשוף את הסביבה שלכם.

מגבלות

• ‫send_command() ו-execute_code() לא פועלים עם ארגז חול של Shell. השיטות האלה מכוונות לארגזי חול של הפעלת קוד ושולחות מטען ייעודי (payload) של Python, שהקונטיינר של המעטפת לא מקבל. שימוש ב-/exec עם ארגזי חול של מעטפת.

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

מגדירים את הפרויקט ואת הסביבה.

הגדרת הפרויקט

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

קבלת התפקידים הנדרשים

כדי להשתמש בארגז החול, צריך את התפקיד הבא:

• משתמש ב-Agent Platform‏ (roles/aiplatform.user) בפרויקט.

התקנת ספריות

מתקינים את ה-SDK באמצעות המודול Agent Platform:

pip install "google-cloud-aiplatform[agent_engines]"

אמת

כדי לבצע אימות באמצעות Application Default Credentials:

gcloud auth application-default login

יצירת מופע של Agent Platform

כדי להשתמש בארגז חול של מעטפת, קודם צריך ליצור מופע של Agent Platform. לא צריך לפרוס סוכן כדי להשתמש בארגז חול של מעטפת. יצירת מופע של Agent Platform אמורה להימשך כמה שניות, בלי פריסה.

import vertexai

client = vertexai.Client(project='PROJECT_ID', location='LOCATION')

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

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

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

• ‫LOCATION: האזור Google Cloud של מופע Agent Platform. אזורים נתמכים

יצירת ארגז חול של מעטפת

כשיוצרים ארגז חול, צריך לספק לפחות אחד מהפרטים הבאים:

• ‫spec עם סביבה מוגדרת (shell_environment)
• ‫config.sandbox_environment_template (אם לא מציינים תבנית, נוצרת תבנית ברירת מחדל. מידע נוסף זמין במאמר שימוש חוזר בתבניות בארגזי חול שונים.
• config.sandbox_environment_snapshot

בדוגמה הבאה, הערך shell_environment מועבר במפרט של ארגז החול:

engine = (
    "projects/PROJECT_ID/locations/LOCATION"
    "/reasoningEngines/INSTANCE_ID"
)

operation = client.agent_engines.sandboxes.create(
    name=engine,
    spec={"shell_environment": {}},
    config={
        "display_name": "my-shell-sandbox",
        "wait_for_completion": True,
        "ttl": "3600s",
    },
)
sandbox = operation.response
print(sandbox.name, sandbox.state)

כשהארגז חול מוכן, מודפסת תגובה שדומה לתגובה הבאה:

projects/.../sandboxEnvironments/1035360621853409280 SandboxState.STATE_RUNNING

בדרך כלל, ארגז חול מגיע ל-STATE_RUNNING תוך כ-20 שניות.

הרצת פקודה

כדי להריץ פקודת shell בארגז החול, משתמשים בפונקציית העזר execute_bash(), ששולחת את הפקודה לקונטיינר:

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="echo hello && whoami && pwd",
)
print(result)

הפקודה מחזירה את הערכים stdout, stderr, returncode ו-duration_ms:

{'stdout': 'hello\nappuser\n/workspace\n', 'stderr': '', 'returncode': 0, 'duration_ms': 8}

‫execute_bash() מאמת את עצמו באמצעות פרטי הכניסה שלכם, כך שלא צריך חשבון שירות או JWT חתום.

אופציונלי: אפשר להגדיר במפורש את cwd כדי לבחור את ספריית העבודה ואת timeout כדי להגביל את משך הזמן שבו הפקודה יכולה לפעול. אחרת, ארגז החול ישתמש בערכי ברירת המחדל שלו (/workspace ומגבלת הזמן של ארגז החול):

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="pytest -q",
    cwd="/workspace/app",
    timeout=120,
)

כדי לגלות אם פקודה נכשלה, בודקים את returncode ואת stderr:

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="ls /nope",
)
print(result)

{'stdout': '', 'stderr': "ls: cannot access '/nope': No such file or directory\n", 'returncode': 2, 'duration_ms': 5}

כשמשתמשים בסביבת הקונטיינר, חשוב להביא בחשבון את הנקודות הבאות:

• הפקודות מופעלות כמשתמש ללא הרשאות appuser; אין sudo.
• כל פקודה מופעלת במעטפת חדשה, ולכן cd ומשתני מעטפת לא מועברים בין קריאות. אפשר לשרשר אותן בפקודה אחת, או לכתוב את המצב לקובץ מתחת ל-/workspace.
• הגישה לאינטרנט יוצאת מושבתת, אלא אם התבנית מאפשרת אותה.

הסרת המשאבים

כדי למחוק את ארגז החול ולהפסיק את החיובים, מריצים את הפקודה הבאה:

client.agent_engines.sandboxes.delete(name=sandbox.name)
print("Sandbox deleted.")

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

• ניהול ארגזי חול
• ניהול תבניות של ארגז חול