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

תצוגה מקדימה

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

השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

בדף הזה נדגים איך לבצע קריאות ישירות ל-API כדי ליצור סביבת ארגז חול לשימוש במחשב ולהשתמש בה. במדריך למתחילים הזה תבצעו את הפעולות הבאות:

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

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

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

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

נכנסים לחשבון 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) בפרויקט.
• התפקיד 'יצירת אסימונים בחשבון שירות' (roles/iam.serviceAccountTokenCreator) בחשבון השירות שמשמש ליצירת האסימון.
• בנוסף, לחשבון השירות שמשמש ליצירת האסימון צריך להיות התפקיד Agent Platform User (roles/aiplatform.user) בפרויקט.

התקנת ספריות

מתקינים את Agent Platform SDK: posix-terminal pip install google-cloud-aiplatform>=1.112.0

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

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

import vertexai
client = vertexai.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
agent_instance = client.agent_engines.create()
agent_instance_name = agent_instance.api_resource.name

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

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: האזור של המכונה (למשל us-central1).

יצירת תבנית לשימוש במחשב

יוצרים תבנית של ארגז חול שתשמש אתכם כשתיצרו ארגז חול לשימוש במחשב.

# Create a default Computer Use sandbox template
templates_client = client.agent_engines.sandboxes.templates
tmplt_operation = templates_client.create(
    name=agent_instance_name,
    display_name='DISPLAY_NAME',
    config={
        "default_container_environment": {
            "default_container_category": "DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE",
        },
        "egress_control_config": {
            "internet_access": True,
        },
    },
)
template_name = tmplt_operation.response.name
print(f"Created template: {template_name}")

יצירת ארגז חול לשימוש במחשב

יוצרים סביבת ארגז חול מהתבנית.

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

# Create a sandbox environment referencing the template.
# To customize the lifetime, set `ttl` to a duration string in seconds (for example, "3600s" for 1 hour).
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
        "ttl": "3600s",  # Optional. Overrides the default 2-hour sandbox lifetime.
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")
print(f"Sandbox will expire at: {sandbox.expire_time}")

יצירת אסימון גישה

כדי ליצור אינטראקציה עם ארגז החול, צריך ליצור אסימון גישה מסוג JSON Web Token ‏ (JWT) באמצעות חשבון שירות.

service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.agent_engines.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

מחליפים את SERVICE_ACCOUNT_EMAIL בכתובת האימייל של חשבון השירות שיש לו את התפקיד 'יצירת אסימונים בחשבון שירות'.

שליחת בקשה ל-Sandbox

שולחים בקשת GET לשרת ה-API של ארגז החול כדי לבדוק את הסטטוס שלו.

response = client.agent_engines.sandboxes.send_command(
    http_method="GET",
    access_token=access_token,
    sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")

שליחת בקשת HTTP POST כדי לעבור לדף ספציפי.

data = {"command": "Page.navigate", "params": {"url": "https://example.com"}}

response = client.agent_engines.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

בטבלה הבאה מפורטים נתיבים ושיטות נוספים שאפשר לשלוח לארגז החול:

‏Method	נתיב	תיאור
GET	/	קבלת בדיקת תקינות של ארגז חול
POST	/tabs	יוצר כרטיסייה חדשה ומחזיר את הפרטים שלה.
GET	/tabs	מציג פרטים של כל הכרטיסיות הפתוחות.
POST	/tabs/{tab_id}/activate	הפונקציה מגדירה כרטיסייה כפעילה ומעבירה אותה לחזית.
מחיקה	/tabs/{tab_id}	סוגרת כרטיסייה ספציפית.
GET	/cdp_ws_endpoint	הפונקציה מחזירה את הנתיב של נקודת הקצה של CDP WebSocket.
POST	/cdp	מריץ פקודת CDP בכרטיסייה הפעילה.
POST	/cdps	מריץ כמה פקודות CDP בכרטיסייה הפעילה.

מידע נוסף על הפורמט והפקודות הנתמכות של CDP זמין באתר CDP.

הסרת המשאבים

כדי להימנע מחיובים, מוחקים את המשאבים שנוצרו במדריך למתחילים הזה.

client.agent_engines.sandboxes.delete(name=sandbox.name)
agent_instance.delete()

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

• אפשר לעיין בתמונות מצב לניהול מחזור החיים של ארגז חול.