استفاده از کامپیوتر

استفاده از کامپیوتر شما را قادر می‌سازد تا عوامل کنترل مرورگری بسازید که با وظایف تعامل داشته و آنها را خودکار می‌کنند. با استفاده از تصاویر، مدل می‌تواند صفحه کامپیوتر را "ببیند" و با تولید اقدامات خاص رابط کاربری مانند کلیک ماوس و ورودی‌های صفحه کلید "عمل" کند. مشابه فراخوانی تابع، شما باید کد برنامه سمت کلاینت را برای دریافت و اجرای اقدامات استفاده از کامپیوتر بنویسید.

با استفاده از کامپیوتر، می‌توانید عامل‌هایی بسازید که:

• خودکارسازی ورود اطلاعات تکراری یا پر کردن فرم در وب‌سایت‌ها.
• انجام تست خودکار برنامه‌های وب و جریان‌های کاربری
• انجام تحقیقات در وب‌سایت‌های مختلف (مثلاً جمع‌آوری اطلاعات محصول، قیمت‌ها و نظرات از سایت‌های تجارت الکترونیک برای اطلاع‌رسانی در مورد خرید)

ساده‌ترین راه برای آزمایش قابلیت استفاده از کامپیوتر، از طریق پیاده‌سازی مرجع یا محیط نمایشی Browserbase است.

نحوه استفاده از کامپیوتر

برای ساخت یک عامل کنترل مرورگر با مدل استفاده از کامپیوتر، یک حلقه عامل پیاده‌سازی کنید که موارد زیر را انجام دهد:

1. ارسال درخواست به مدل

   • ابزار استفاده از کامپیوتر و در صورت تمایل، هر تابع تعریف‌شده توسط کاربر یا توابع مستثنی‌شده را به درخواست API خود اضافه کنید.
   • مدل استفاده از کامپیوتر را با درخواست کاربر فعال کنید.

2. پاسخ مدل را دریافت کنید

   • مدل استفاده از کامپیوتر، درخواست کاربر و تصویر صفحه را تجزیه و تحلیل می‌کند و پاسخی تولید می‌کند که شامل یک function_call پیشنهادی است که نشان‌دهنده یک عمل رابط کاربری است (مثلاً "کلیک در مختصات (x، y)" یا "تایپ 'متن'"). برای شرح تمام اعمال رابط کاربری پشتیبانی شده توسط مدل استفاده از کامپیوتر، به اقدامات پشتیبانی شده مراجعه کنید.
   • پاسخ API همچنین ممکن است شامل یک safety_decision از یک سیستم ایمنی داخلی باشد که اقدام پیشنهادی مدل را بررسی می‌کند. این safety_decision اقدام را به صورت زیر طبقه‌بندی می‌کند:
     • منظم / مجاز: این اقدام ایمن در نظر گرفته می‌شود. این مورد همچنین می‌تواند با عدم وجود safety_decision نشان داده شود.
     • نیاز به تأیید ( require_confirmation ): مدل در شرف انجام عملی است که ممکن است پرخطر باشد (مثلاً کلیک روی "بنر پذیرش کوکی").

3. اجرای اکشن دریافتی

   • کد سمت کلاینت شما تابع function_call و هرگونه safety_decision همراه آن را دریافت می‌کند.
     • Regular / allowed: اگر safety_decision مقدار regular / allowed را نشان دهد (یا اگر هیچ safety_decision وجود نداشته باشد)، کد سمت کلاینت شما می‌تواند function_call مشخص شده را در محیط هدف شما (مثلاً یک مرورگر وب) اجرا کند.
     • نیاز به تأیید: اگر safety_decision نشان دهد که نیاز به تأیید دارد، برنامه شما باید قبل از اجرای function_call از کاربر نهایی تأییدیه بخواهد. اگر کاربر تأیید کرد، اقدام را اجرا کنید. اگر کاربر رد کرد، اقدام را اجرا نکنید.

4. ثبت وضعیت جدید محیط

   • اگر اکشن اجرا شده باشد، کلاینت شما یک اسکرین‌شات جدید از رابط کاربری گرافیکی و URL فعلی می‌گیرد تا آن را به عنوان بخشی از یک function_response به مدل Computer Use ارسال کند.
   • اگر عملی توسط سیستم ایمنی مسدود شده باشد یا تأیید آن توسط کاربر رد شده باشد، برنامه شما ممکن است نوع دیگری از بازخورد را به مدل ارسال کند یا تعامل را پایان دهد.

این فرآیند از مرحله ۲ با استفاده از تصویر جدید و هدف فعلی برای پیشنهاد اقدام بعدی توسط مدل تکرار می‌شود. این حلقه تا زمانی که وظیفه تکمیل شود، خطایی رخ دهد یا فرآیند خاتمه یابد (مثلاً به دلیل پاسخ ایمنی "مسدود" یا تصمیم کاربر) ادامه می‌یابد.

نحوه پیاده‌سازی استفاده از کامپیوتر

قبل از ساخت با ابزار Computer Use، باید موارد زیر را تنظیم کنید:

• محیط اجرای امن: به دلایل ایمنی، شما باید عامل استفاده از رایانه خود را در یک محیط امن و کنترل‌شده اجرا کنید (مثلاً یک ماشین مجازی سندباکس شده، یک کانتینر یا یک پروفایل مرورگر اختصاصی با مجوزهای محدود).
• کنترل‌کننده‌ی عملیات سمت کلاینت: شما باید منطق سمت کلاینت را پیاده‌سازی کنید تا عملیات تولید شده توسط مدل را اجرا کند و پس از هر عملیات، از محیط اسکرین‌شات بگیرد.

مثال‌های این بخش از یک مرورگر به عنوان محیط اجرا و Playwright به عنوان کنترل‌کننده‌ی اکشن سمت کلاینت استفاده می‌کنند. برای اجرای این نمونه‌ها باید وابستگی‌های لازم را نصب کرده و یک نمونه‌ی مرورگر Playwright را مقداردهی اولیه کنید.

    pip install google-genai playwright
    playwright install chromium
    

    from playwright.sync_api import sync_playwright

    # 1. Configure screen dimensions for the target environment
    SCREEN_WIDTH = 1440
    SCREEN_HEIGHT = 900

    # 2. Start the Playwright browser
    # In production, utilize a sandboxed environment.
    playwright = sync_playwright().start()
    # Set headless=False to see the actions performed on your screen
    browser = playwright.chromium.launch(headless=False)

    # 3. Create a context and page with the specified dimensions
    context = browser.new_context(
        viewport={"width": SCREEN_WIDTH, "height": SCREEN_HEIGHT}
    )
    page = context.new_page()

    # 4. Navigate to an initial page to start the task
    page.goto("https://www.google.com")

    # The 'page', 'SCREEN_WIDTH', and 'SCREEN_HEIGHT' variables
    # will be used in the steps below.
    

نمونه کد برای گسترش به محیط اندروید در بخش « استفاده از توابع سفارشی تعریف‌شده توسط کاربر» گنجانده شده است.

۱. ارسال درخواست به مدل

ابزار Computer Use را به درخواست API خود اضافه کنید و یک اعلان به مدلی که شامل هدف کاربر است ارسال کنید. شما باید از یکی از مدل‌های پشتیبانی شده توسط Computer Use استفاده کنید، در غیر این صورت با خطا مواجه خواهید شد:

• gemini-2.5-computer-use-preview-10-2025
• gemini-3-pro-preview
• gemini-3-flash-preview

همچنین می‌توانید پارامترهای زیر را به صورت اختیاری اضافه کنید:

• اقدامات مستثنی: اگر اقداماتی از لیست اقدامات رابط کاربری پشتیبانی شده وجود دارد که نمی‌خواهید مدل انجام دهد، این اقدامات را به عنوان excluded_predefined_functions مشخص کنید.
• توابع تعریف‌شده توسط کاربر: علاوه بر ابزار استفاده از کامپیوتر، ممکن است بخواهید توابع تعریف‌شده توسط کاربر سفارشی را نیز اضافه کنید.

توجه داشته باشید که هنگام صدور درخواست، نیازی به مشخص کردن اندازه نمایشگر نیست؛ مدل، مختصات پیکسلی را که با ارتفاع و عرض صفحه نمایش مقیاس‌بندی شده‌اند، پیش‌بینی می‌کند.

from google import genai
from google.genai import types
from google.genai.types import Content, Part

client = genai.Client()

# Specify predefined functions to exclude (optional)
excluded_functions = ["drag_and_drop"]

generate_content_config = genai.types.GenerateContentConfig(
    tools=[
        # 1. Computer Use tool with browser environment
        types.Tool(
            computer_use=types.ComputerUse(
                environment=types.Environment.ENVIRONMENT_BROWSER,
                # Optional: Exclude specific predefined functions
                excluded_predefined_functions=excluded_functions
                )
              ),
        # 2. Optional: Custom user-defined functions
        #types.Tool(
          # function_declarations=custom_functions
          #   )
          ],
  )

# Create the content with user message
contents=[
    Content(
        role="user",
        parts=[
            Part(text="Search for highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping. Create a bulleted list of the 3 cheapest options in the format of name, description, price in an easy-to-read layout."),
        ],
    )
]

# Generate content with the configured settings
response = client.models.generate_content(
    model='gemini-2.5-computer-use-preview-10-2025',
    contents=contents,
    config=generate_content_config,
)

# Print the response output
print(response)

برای مثالی با توابع سفارشی، به استفاده از توابع سفارشی تعریف شده توسط کاربر مراجعه کنید.

۲. پاسخ مدل را دریافت کنید

وقتی ابزار Computer Use فعال باشد، مدل در صورت تشخیص اقدامات رابط کاربری برای تکمیل وظیفه، با یک یا چند FunctionCalls پاسخ خواهد داد. Computer Use از فراخوانی موازی توابع پشتیبانی می‌کند، به این معنی که مدل می‌تواند چندین اقدام را در یک نوبت واحد برگرداند.

در اینجا یک نمونه پاسخ مدل ارائه شده است.

{
  "content": {
    "parts": [
      {
        "text": "I will type the search query into the search bar. The search bar is in the center of the page."
      },
      {
        "function_call": {
          "name": "type_text_at",
          "args": {
            "x": 371,
            "y": 470,
            "text": "highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping",
            "press_enter": true
          }
        }
      }
    ]
  }
}

۳. اقدامات دریافتی را اجرا کنید

کد برنامه شما باید پاسخ مدل را تجزیه و تحلیل کند، اقدامات را اجرا کند و نتایج را جمع‌آوری کند.

کد نمونه زیر فراخوانی‌های تابع را از پاسخ مدل Computer Use استخراج می‌کند و آنها را به اقداماتی تبدیل می‌کند که می‌توانند با Playwright اجرا شوند. مدل، مختصات نرمال‌شده (0-999) را صرف نظر از ابعاد تصویر ورودی، خروجی می‌دهد، بنابراین بخشی از مرحله ترجمه، تبدیل این مختصات نرمال‌شده به مقادیر پیکسل واقعی است.

اندازه صفحه نمایش توصیه شده برای استفاده با مدل Computer Use (1440، 900) است. این مدل با هر رزولوشنی کار خواهد کرد، اگرچه کیفیت نتایج ممکن است تحت تأثیر قرار گیرد.

توجه داشته باشید که این مثال فقط شامل پیاده‌سازی ۳ مورد از رایج‌ترین اقدامات رابط کاربری است: open_web_browser ، click_at و type_text_at . برای موارد استفاده در محیط عملیاتی، باید تمام اقدامات رابط کاربری دیگر را از لیست اقدامات پشتیبانی‌شده پیاده‌سازی کنید، مگر اینکه صریحاً آنها را به عنوان excluded_predefined_functions اضافه کنید.

from typing import Any, List, Tuple
import time

def denormalize_x(x: int, screen_width: int) -> int:
    """Convert normalized x coordinate (0-1000) to actual pixel coordinate."""
    return int(x / 1000 * screen_width)

def denormalize_y(y: int, screen_height: int) -> int:
    """Convert normalized y coordinate (0-1000) to actual pixel coordinate."""
    return int(y / 1000 * screen_height)

def execute_function_calls(candidate, page, screen_width, screen_height):
    results = []
    function_calls = []
    for part in candidate.content.parts:
        if part.function_call:
            function_calls.append(part.function_call)

    for function_call in function_calls:
        action_result = {}
        fname = function_call.name
        args = function_call.args
        print(f"  -> Executing: {fname}")

        try:
            if fname == "open_web_browser":
                pass # Already open
            elif fname == "click_at":
                actual_x = denormalize_x(args["x"], screen_width)
                actual_y = denormalize_y(args["y"], screen_height)
                page.mouse.click(actual_x, actual_y)
            elif fname == "type_text_at":
                actual_x = denormalize_x(args["x"], screen_width)
                actual_y = denormalize_y(args["y"], screen_height)
                text = args["text"]
                press_enter = args.get("press_enter", False)

                page.mouse.click(actual_x, actual_y)
                # Simple clear (Command+A, Backspace for Mac)
                page.keyboard.press("Meta+A")
                page.keyboard.press("Backspace")
                page.keyboard.type(text)
                if press_enter:
                    page.keyboard.press("Enter")
            else:
                print(f"Warning: Unimplemented or custom function {fname}")

            # Wait for potential navigations/renders
            page.wait_for_load_state(timeout=5000)
            time.sleep(1)

        except Exception as e:
            print(f"Error executing {fname}: {e}")
            action_result = {"error": str(e)}

        results.append((fname, action_result))

    return results

۴. ثبت وضعیت جدید محیط

پس از اجرای اقدامات، نتیجه اجرای تابع را به مدل ارسال کنید تا بتواند از این اطلاعات برای تولید اقدام بعدی استفاده کند. اگر چندین اقدام (فراخوانی‌های موازی) اجرا شده باشد، باید برای هر یک از آنها در نوبت بعدی کاربر، یک FunctionResponse ارسال کنید.

def get_function_responses(page, results):
    screenshot_bytes = page.screenshot(type="png")
    current_url = page.url
    function_responses = []
    for name, result in results:
        response_data = {"url": current_url}
        response_data.update(result)
        function_responses.append(
            types.FunctionResponse(
                name=name,
                response=response_data,
                parts=[types.FunctionResponsePart(
                        inline_data=types.FunctionResponseBlob(
                            mime_type="image/png",
                            data=screenshot_bytes))
                ]
            )
        )
    return function_responses

یک حلقه عامل بسازید

برای فعال کردن تعاملات چند مرحله‌ای، چهار مرحله از بخش « نحوه پیاده‌سازی استفاده از کامپیوتر» را در یک حلقه ترکیب کنید. به یاد داشته باشید که با افزودن پاسخ‌های مدل و پاسخ‌های تابع خود، تاریخچه مکالمه را به درستی مدیریت کنید.

برای اجرای این نمونه کد باید:

• وابستگی‌های لازم Playwright را نصب کنید.

• توابع کمکی را از مراحل (3) اجرای اقدامات دریافتی و (4) ثبت وضعیت جدید محیط تعریف کنید.

import time
from typing import Any, List, Tuple
from playwright.sync_api import sync_playwright

from google import genai
from google.genai import types
from google.genai.types import Content, Part

client = genai.Client()

# Constants for screen dimensions
SCREEN_WIDTH = 1440
SCREEN_HEIGHT = 900

# Setup Playwright
print("Initializing browser...")
playwright = sync_playwright().start()
browser = playwright.chromium.launch(headless=False)
context = browser.new_context(viewport={"width": SCREEN_WIDTH, "height": SCREEN_HEIGHT})
page = context.new_page()

# Define helper functions. Copy/paste from steps 3 and 4
# def denormalize_x(...)
# def denormalize_y(...)
# def execute_function_calls(...)
# def get_function_responses(...)

try:
    # Go to initial page
    page.goto("https://ai.google.dev/gemini-api/docs")

    # Configure the model (From Step 1)
    config = types.GenerateContentConfig(
        tools=[types.Tool(computer_use=types.ComputerUse(
            environment=types.Environment.ENVIRONMENT_BROWSER
        ))],
        thinking_config=types.ThinkingConfig(include_thoughts=True),
    )

    # Initialize history
    initial_screenshot = page.screenshot(type="png")
    USER_PROMPT = "Go to ai.google.dev/gemini-api/docs and search for pricing."
    print(f"Goal: {USER_PROMPT}")

    contents = [
        Content(role="user", parts=[
            Part(text=USER_PROMPT),
            Part.from_bytes(data=initial_screenshot, mime_type='image/png')
        ])
    ]

    # Agent Loop
    turn_limit = 5
    for i in range(turn_limit):
        print(f"\n--- Turn {i+1} ---")
        print("Thinking...")
        response = client.models.generate_content(
            model='gemini-2.5-computer-use-preview-10-2025',
            contents=contents,
            config=config,
        )

        candidate = response.candidates[0]
        contents.append(candidate.content)

        has_function_calls = any(part.function_call for part in candidate.content.parts)
        if not has_function_calls:
            text_response = " ".join([part.text for part in candidate.content.parts if part.text])
            print("Agent finished:", text_response)
            break

        print("Executing actions...")
        results = execute_function_calls(candidate, page, SCREEN_WIDTH, SCREEN_HEIGHT)

        print("Capturing state...")
        function_responses = get_function_responses(page, results)

        contents.append(
            Content(role="user", parts=[Part(function_response=fr) for fr in function_responses])
        )

finally:
    # Cleanup
    print("\nClosing browser...")
    browser.close()
    playwright.stop()

استفاده از توابع سفارشی تعریف شده توسط کاربر

شما می‌توانید به صورت اختیاری توابع سفارشی تعریف‌شده توسط کاربر را در درخواست خود بگنجانید تا عملکرد مدل را گسترش دهید. مثال زیر مدل و ابزار Computer Use را برای موارد استفاده موبایل با گنجاندن اقدامات سفارشی تعریف‌شده توسط کاربر مانند open_app ، long_press_at و go_home تطبیق می‌دهد، در حالی که اقدامات خاص مرورگر را حذف می‌کند. این مدل می‌تواند به طور هوشمندانه این توابع سفارشی را در کنار اقدامات استاندارد رابط کاربری فراخوانی کند تا وظایف را در محیط‌های غیر مرورگر انجام دهد.

from typing import Optional, Dict, Any

from google import genai
from google.genai import types
from google.genai.types import Content, Part

client = genai.Client()

SYSTEM_PROMPT = """You are operating an Android phone. Today's date is October 15, 2023, so ignore any other date provided.
* To provide an answer to the user, *do not use any tools* and output your answer on a separate line. IMPORTANT: Do not add any formatting or additional punctuation/text, just output the answer by itself after two empty lines.
* Make sure you scroll down to see everything before deciding something isn't available.
* You can open an app from anywhere. The icon doesn't have to currently be on screen.
* Unless explicitly told otherwise, make sure to save any changes you make.
* If text is cut off or incomplete, scroll or click into the element to get the full text before providing an answer.
* IMPORTANT: Complete the given task EXACTLY as stated. DO NOT make any assumptions that completing a similar task is correct.  If you can't find what you're looking for, SCROLL to find it.
* If you want to edit some text, ONLY USE THE `type` tool. Do not use the onscreen keyboard.
* Quick settings shouldn't be used to change settings. Use the Settings app instead.
* The given task may already be completed. If so, there is no need to do anything.
"""

def open_app(app_name: str, intent: Optional[str] = None) -> Dict[str, Any]:
    """Opens an app by name.

    Args:
        app_name: Name of the app to open (any string).
        intent: Optional deep-link or action to pass when launching, if the app supports it.

    Returns:
        JSON payload acknowledging the request (app name and optional intent).
    """
    return {"status": "requested_open", "app_name": app_name, "intent": intent}

def long_press_at(x: int, y: int) -> Dict[str, int]:
    """Long-press at a specific screen coordinate.

    Args:
        x: X coordinate (absolute), scaled to the device screen width (pixels).
        y: Y coordinate (absolute), scaled to the device screen height (pixels).

    Returns:
        Object with the coordinates pressed and the duration used.
    """
    return {"x": x, "y": y}

def go_home() -> Dict[str, str]:
    """Navigates to the device home screen.

    Returns:
        A small acknowledgment payload.
    """
    return {"status": "home_requested"}

#  Build function declarations
CUSTOM_FUNCTION_DECLARATIONS = [
    types.FunctionDeclaration.from_callable(client=client, callable=open_app),
    types.FunctionDeclaration.from_callable(client=client, callable=long_press_at),
    types.FunctionDeclaration.from_callable(client=client, callable=go_home),
]

#Exclude browser functions
EXCLUDED_PREDEFINED_FUNCTIONS = [
    "open_web_browser",
    "search",
    "navigate",
    "hover_at",
    "scroll_document",
    "go_forward",
    "key_combination",
    "drag_and_drop",
]

#Utility function to construct a GenerateContentConfig
def make_generate_content_config() -> genai.types.GenerateContentConfig:
    """Return a fixed GenerateContentConfig with Computer Use + custom functions."""
    return genai.types.GenerateContentConfig(
        system_instruction=SYSTEM_PROMPT,
        tools=[
            types.Tool(
                computer_use=types.ComputerUse(
                    environment=types.Environment.ENVIRONMENT_BROWSER,
                    excluded_predefined_functions=EXCLUDED_PREDEFINED_FUNCTIONS,
                )
            ),
            types.Tool(function_declarations=CUSTOM_FUNCTION_DECLARATIONS),
        ],
    )

# Create the content with user message
contents: list[Content] = [
    Content(
        role="user",
        parts=[
            # text instruction
            Part(text="Open Chrome, then long-press at 200,400."),
        ],
    )
]

# Build your fixed config (from helper)
config = make_generate_content_config()

# Generate content with the configured settings
response = client.models.generate_content(
        model='gemini-2.5-computer-use-preview-10-2025',
        contents=contents,
        config=config,
    )

print(response)

اقدامات رابط کاربری پشتیبانی شده

مدل می‌تواند اقدامات رابط کاربری زیر را از طریق یک FunctionCall درخواست کند. کد سمت کلاینت شما باید منطق اجرای این اقدامات را پیاده‌سازی کند. برای مثال‌ها به پیاده‌سازی مرجع مراجعه کنید.

ایمنی و امنیت

تصمیم ایمنی را تصدیق کنید

بسته به اقدام، پاسخ مدل ممکن است شامل یک safety_decision از یک سیستم ایمنی داخلی نیز باشد که اقدام پیشنهادی مدل را بررسی می‌کند.

{
  "content": {
    "parts": [
      {
        "text": "I have evaluated step 2. It seems Google detected unusual traffic and is asking me to verify I'm not a robot. I need to click the 'I'm not a robot' checkbox located near the top left (y=98, x=95).",
      },
      {
        "function_call": {
          "name": "click_at",
          "args": {
            "x": 60,
            "y": 100,
            "safety_decision": {
              "explanation": "I have encountered a CAPTCHA challenge that requires interaction. I need you to complete the challenge by clicking the 'I'm not a robot' checkbox and any subsequent verification steps.",
              "decision": "require_confirmation"
            }
          }
        }
      }
    ]
  }
}

اگر safety_decision require_confirmation باشد، باید قبل از ادامه‌ی اجرای عملیات، از کاربر نهایی بخواهید که آن را تأیید کند. طبق شرایط خدمات ، شما مجاز به نادیده گرفتن درخواست‌های تأیید انسانی نیستید.

این نمونه کد قبل از اجرای عمل، از کاربر نهایی تأیید می‌خواهد. اگر کاربر عمل را تأیید نکند، حلقه خاتمه می‌یابد. اگر کاربر عمل را تأیید کند، عمل اجرا می‌شود و فیلد safety_acknowledgement با مقدار True علامت‌گذاری می‌شود.

import termcolor

def get_safety_confirmation(safety_decision):
    """Prompt user for confirmation when safety check is triggered."""
    termcolor.cprint("Safety service requires explicit confirmation!", color="red")
    print(safety_decision["explanation"])

    decision = ""
    while decision.lower() not in ("y", "n", "ye", "yes", "no"):
        decision = input("Do you wish to proceed? [Y]es/[N]o\n")

    if decision.lower() in ("n", "no"):
        return "TERMINATE"
    return "CONTINUE"

def execute_function_calls(candidate, page, screen_width, screen_height):

    # ... Extract function calls from response ...

    for function_call in function_calls:
        extra_fr_fields = {}

        # Check for safety decision
        if 'safety_decision' in function_call.args:
            decision = get_safety_confirmation(function_call.args['safety_decision'])
            if decision == "TERMINATE":
                print("Terminating agent loop")
                break
            extra_fr_fields["safety_acknowledgement"] = "true" # Safety acknowledgement

        # ... Execute function call and append to results ...

اگر کاربر تأیید کرد، باید تأییدیه ایمنی را در FunctionResponse خود وارد کنید.

function_response_parts.append(
    FunctionResponse(
        name=name,
        response={"url": current_url,
                  **extra_fr_fields},  # Include safety acknowledgement
        parts=[
            types.FunctionResponsePart(
                inline_data=types.FunctionResponseBlob(
                    mime_type="image/png", data=screenshot
                )
             )
           ]
         )
       )

بهترین شیوه‌های ایمنی

استفاده از کامپیوتر ابزاری جدید است که خطرات جدیدی را ایجاد می‌کند که توسعه‌دهندگان باید از آنها آگاه باشند:

• محتوای غیرقابل اعتماد و کلاهبرداری‌ها: همانطور که مدل سعی می‌کند به هدف کاربر دست یابد، ممکن است به منابع اطلاعاتی و دستورالعمل‌های غیرقابل اعتماد از روی صفحه نمایش تکیه کند. به عنوان مثال، اگر هدف کاربر خرید گوشی پیکسل باشد و مدل با کلاهبرداری "پیکسل رایگان در صورت تکمیل نظرسنجی" مواجه شود، این احتمال وجود دارد که مدل نظرسنجی را تکمیل کند.
• اقدامات ناخواسته گاه به گاه: مدل می‌تواند هدف کاربر یا محتوای صفحه وب را اشتباه تفسیر کند و باعث شود اقدامات نادرستی مانند کلیک روی دکمه اشتباه یا پر کردن فرم اشتباه انجام شود. این می‌تواند منجر به شکست وظایف یا خروج داده‌ها شود.
• نقض سیاست‌ها: قابلیت‌های API می‌تواند عمداً یا سهواً به سمت فعالیت‌هایی هدایت شود که سیاست‌های گوگل ( سیاست استفاده ممنوعه Gen AI و شرایط خدمات اضافی Gemini API) را نقض می‌کنند. این شامل اقداماتی می‌شود که می‌توانند در یکپارچگی سیستم اختلال ایجاد کنند، امنیت را به خطر بیندازند، اقدامات امنیتی را دور بزنند، دستگاه‌های پزشکی را کنترل کنند و غیره.

برای مقابله با این خطرات، می‌توانید اقدامات ایمنی و بهترین شیوه‌های زیر را اجرا کنید:

1. انسان در حلقه (HITL):

   • پیاده‌سازی تأیید کاربر: وقتی پاسخ ایمنی نشان‌دهنده‌ی require_confirmation است، باید قبل از اجرا، تأیید کاربر را پیاده‌سازی کنید. برای نمونه کد، به بخش تأیید تصمیم ایمنی مراجعه کنید.

   • ارائه دستورالعمل‌های ایمنی سفارشی: علاوه بر بررسی‌های تأیید کاربر داخلی، توسعه‌دهندگان می‌توانند به صورت اختیاری یک دستورالعمل سیستمی سفارشی اضافه کنند که سیاست‌های ایمنی خودشان را اعمال می‌کند، یا برای مسدود کردن اقدامات خاص مدل یا درخواست تأیید کاربر قبل از انجام اقدامات برگشت‌ناپذیر و پرخطر توسط مدل. در اینجا مثالی از یک دستورالعمل سیستم ایمنی سفارشی آورده شده است که می‌توانید هنگام تعامل با مدل، آن را لحاظ کنید.

     نمونه دستورالعمل‌های ایمنی

     قوانین ایمنی سفارشی خود را به عنوان دستورالعمل سیستم تنظیم کنید:

         ## **RULE 1: Seek User Confirmation (USER_CONFIRMATION)**
     
         This is your first and most important check. If the next required action falls
         into any of the following categories, you MUST stop immediately, and seek the
         user's explicit permission.
     
         **Procedure for Seeking Confirmation:**  * **For Consequential Actions:**
         Perform all preparatory steps (e.g., navigating, filling out forms, typing a
         message). You will ask for confirmation **AFTER** all necessary information is
         entered on the screen, but **BEFORE** you perform the final, irreversible action
         (e.g., before clicking "Send", "Submit", "Confirm Purchase", "Share").  * **For
         Prohibited Actions:** If the action is strictly forbidden (e.g., accepting legal
         terms, solving a CAPTCHA), you must first inform the user about the required
         action and ask for their confirmation to proceed.
     
         **USER_CONFIRMATION Categories:**
     
         *   **Consent and Agreements:** You are FORBIDDEN from accepting, selecting, or
             agreeing to any of the following on the user's behalf. You must ask the
             user to confirm before performing these actions.
             *   Terms of Service
             *   Privacy Policies
             *   Cookie consent banners
             *   End User License Agreements (EULAs)
             *   Any other legally significant contracts or agreements.
         *   **Robot Detection:** You MUST NEVER attempt to solve or bypass the
             following. You must ask the user to confirm before performing these actions.
         *   CAPTCHAs (of any kind)
             *   Any other anti-robot or human-verification mechanisms, even if you are
                 capable.
         *   **Financial Transactions:**
             *   Completing any purchase.
             *   Managing or moving money (e.g., transfers, payments).
             *   Purchasing regulated goods or participating in gambling.
         *   **Sending Communications:**
             *   Sending emails.
             *   Sending messages on any platform (e.g., social media, chat apps).
             *   Posting content on social media or forums.
         *   **Accessing or Modifying Sensitive Information:**
             *   Health, financial, or government records (e.g., medical history, tax
                 forms, passport status).
             *   Revealing or modifying sensitive personal identifiers (e.g., SSN, bank
                 account number, credit card number).
         *   **User Data Management:**
             *   Accessing, downloading, or saving files from the web.
             *   Sharing or sending files/data to any third party.
             *   Transferring user data between systems.
         *   **Browser Data Usage:**
             *   Accessing or managing Chrome browsing history, bookmarks, autofill data,
                 or saved passwords.
         *   **Security and Identity:**
             *   Logging into any user account.
             *   Any action that involves misrepresentation or impersonation (e.g.,
                 creating a fan account, posting as someone else).
         *   **Insurmountable Obstacles:** If you are technically unable to interact with
             a user interface element or are stuck in a loop you cannot resolve, ask the
             user to take over.
         ---
     
         ## **RULE 2: Default Behavior (ACTUATE)**
     
         If an action does **NOT** fall under the conditions for `USER_CONFIRMATION`,
         your default behavior is to **Actuate**.
     
         **Actuation Means:**  You MUST proactively perform all necessary steps to move
         the user's request forward. Continue to actuate until you either complete the
         non-consequential task or encounter a condition defined in Rule 1.
     
         *   **Example 1:** If asked to send money, you will navigate to the payment
             portal, enter the recipient's details, and enter the amount. You will then
             **STOP** as per Rule 1 and ask for confirmation before clicking the final
             "Send" button.
         *   **Example 2:** If asked to post a message, you will navigate to the site,
             open the post composition window, and write the full message. You will then
             **STOP** as per Rule 1 and ask for confirmation before clicking the final
             "Post" button.
     
             After the user has confirmed, remember to get the user's latest screen
             before continuing to perform actions.
     
         # Final Response Guidelines:
         Write final response to the user in the following cases:
         - User confirmation
         - When the task is complete or you have enough information to respond to the user
         

2. محیط اجرای امن: عامل خود را در یک محیط امن و محافظت‌شده اجرا کنید تا تأثیر بالقوه آن محدود شود (مثلاً یک ماشین مجازی (VM) محافظت‌شده، یک کانتینر (مثلاً داکر) یا یک پروفایل مرورگر اختصاصی با مجوزهای محدود).

3. پاکسازی ورودی: تمام متن‌های تولید شده توسط کاربر در اعلان‌ها را پاکسازی کنید تا خطر دستورالعمل‌های ناخواسته یا تزریق اعلان را کاهش دهید. این یک لایه امنیتی مفید است، اما جایگزینی برای یک محیط اجرای امن نیست.

4. محافظان محتوا: از محافظان و APIهای ایمنی محتوا برای ارزیابی ورودی‌های کاربر، ورودی و خروجی ابزار، پاسخ عامل برای بررسی مناسب بودن، تزریق سریع و تشخیص فرار از زندان استفاده کنید.

5. لیست‌های مجاز و لیست‌های مسدود: مکانیزم‌های فیلترینگ را برای کنترل اینکه مدل کجا می‌تواند پیمایش کند و چه کاری می‌تواند انجام دهد، پیاده‌سازی کنید. یک لیست مسدود از وب‌سایت‌های ممنوعه نقطه شروع خوبی است، در حالی که یک لیست مجاز محدودتر، حتی امن‌تر نیز هست.

6. قابلیت مشاهده و ثبت وقایع: گزارش‌های دقیقی را برای اشکال‌زدایی، حسابرسی و پاسخ به حوادث نگهداری کنید. کلاینت شما باید اعلان‌ها، تصاویر، اقدامات پیشنهادی مدل (function_call)، پاسخ‌های ایمنی و تمام اقداماتی که در نهایت توسط کلاینت اجرا می‌شود را ثبت کند.

7. مدیریت محیط: اطمینان حاصل کنید که محیط رابط کاربری گرافیکی (GUI) سازگار است. پنجره‌های بازشو، اعلان‌ها یا تغییرات غیرمنتظره در طرح‌بندی می‌تواند مدل را گیج کند. در صورت امکان، برای هر کار جدید از یک حالت شناخته شده و تمیز شروع کنید.

نسخه‌های مدل

قدم بعدی چیست؟

• استفاده از کامپیوتر را در محیط آزمایشی Browserbase آزمایش کنید.
• برای مثال، پیاده‌سازی مرجع را بررسی کنید.
• درباره سایر ابزارهای API Gemini اطلاعات کسب کنید:
  • فراخوانی تابع
  • اتصال به زمین با جستجوی گوگل