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

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

برای لیست مدل‌های پشتیبانی‌شده، به نسخه‌های مدل مراجعه کنید. مدل‌های Gemini 3.x از چندین قابلیت پیشرفته پشتیبانی می‌کنند:

  • پشتیبانی از چند محیط: ساخت عامل‌ها برای محیط‌های مرورگر، موبایل و دسکتاپ .
  • اقدامات ساده‌شده با اهداف: اقدامات شامل یک فیلد intent هستند که استدلال مدل را در پشت هر مرحله توضیح می‌دهد.
  • سیاست‌های ایمنی قابل تنظیم: تنظیم دقیق رفتار ایمنی با دسته‌ها و لغوهای سیاست‌های داخلی.
  • تشخیص تزریق سریع: اسکن اسکرین‌شات با قابلیت انتخاب برای شناسایی دستورالعمل‌های خصمانه‌ی پنهان.

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

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

در اینجا یک مثال ساده از مقداردهی اولیه کلاینت و ارسال اعلان به مدل با ابزار computer_use فعال برای محیط مرورگر آورده شده است:

پایتون 

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Search for 'Gemini API' on Google.",
    tools=[{"type": "computer_use", "environment": "browser"}]
)

print(interaction)

جاوا اسکریپت 

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.8-flash',
  input: "Search for 'Gemini API' on Google.",
  tools: [{ type: "computer_use", environment: "browser" }]
});

console.log(interaction);

جاوا 

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Click the Submit button on the screen."))
        .tools(Arrays.asList(new ComputerUse()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));


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

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

  1. ارسال درخواست به مدل
    • برنامه شما یک درخواست API حاوی ابزار Computer Use، تنظیمات پیکربندی شما (مانند محیط هدف)، اعلان کاربر و یک اسکرین‌شات از صفحه فعلی ارسال می‌کند.
  2. پاسخ مدل را دریافت کنید
    • این مدل صفحه نمایش و اعلان را تجزیه و تحلیل می‌کند و پاسخی را برمی‌گرداند که شامل یک function_call پیشنهادی است که نشان‌دهنده یک عمل رابط کاربری (مانند کلیک، اسکرول یا فشردن کلید) است.
    • برای مدل‌های Gemini 3.x ، پاسخ همچنین شامل یک intent استدلالی است که توضیح می‌دهد چرا مدل آن اقدام را انتخاب کرده است.
    • این پاسخ همچنین ممکن است شامل یک safety_decision از یک سیستم ایمنی داخلی باشد که اقدام را به عنوان منظم/مجاز، require_confirmation تأیید کاربر یا مسدود شده طبقه‌بندی می‌کند.
  3. اجرای اکشن دریافتی
    • اگر عمل مجاز باشد (یا کاربر آن را تأیید کند)، کد سمت کلاینت شما function_call تجزیه می‌کند، مختصات نرمال‌شده را برای مطابقت با نمای شما مقیاس‌بندی می‌کند و عمل را در محیط هدف شما با استفاده از ابزارهای اتوماسیون (مانند Playwright) اجرا می‌کند. اگر عمل مسدود شده باشد، کلاینت شما باید اجرا را متوقف کند یا وقفه را مدیریت کند.
  4. ثبت وضعیت جدید محیط
    • پس از اتمام اجرای اکشن، برنامه شما یک اسکرین‌شات جدید می‌گیرد و آن را در یک function_result به مدل ارسال می‌کند تا مرحله بعدی را درخواست کند.

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

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

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

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

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

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

0. تنظیم نمایشنامه نویس

ابتدا بسته‌های مورد نیاز را نصب کنید:

pip install google-genai playwright
playwright install chromium

سپس، یک نمونه مرورگر Playwright را برای اجرا، مقداردهی اولیه کنید:

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.

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

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

جمینی ۳.x

پایتون

از google-genai Python SDK (نسخه 2.7.0 یا بالاتر) برای پیکربندی درخواستی که محیط مرورگر را هدف قرار می‌دهد، استفاده کنید:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input="Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th",
    tools=[
        {
            "type": "computer_use",
            "environment": "browser",
            "enable_prompt_injection_detection": True
        }
    ]
)

print(interaction)

جاوا اسکریپت

از SDK نود.جی‌اس @google/genai برای پیکربندی درخواستی که محیط مرورگر را هدف قرار می‌دهد، استفاده کنید:

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.8-flash',
  input: "Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th",
  tools: [
    {
      type: "computer_use",
      environment: "browser",
      enable_prompt_injection_detection: true
    }
  ]
});

console.log(interaction);

جاوا 

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Click the Submit button on the screen."))
        .tools(Arrays.asList(new ComputerUse()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

استراحت

برای ارسال درخواست از curl استفاده کنید:

curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Find me a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th. Start by navigating directly to flights.google.com",
    "tools": [
      {
        "type": "computer_use",
        "environment": "browser",
        "enable_prompt_injection_detection": true
      }
    ]
  }'

جمینی ۲.۵ (لگسی)

پایتون 

from google import genai

client = genai.Client()

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

interaction = client.interactions.create(
    model='gemini-2.5-computer-use-preview-10-2025',
    input="Search for highly rated smart fridges on Google Shopping.",
    tools=[
        {
            "type": "computer_use",
            "environment": "browser",
            "excluded_predefined_functions": excluded_functions
        }
    ]
)

print(interaction)

جاوا اسکریپت 

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

// Specify predefined functions to exclude (optional)
const excludedFunctions = ["drag_and_drop"];

const interaction = await ai.interactions.create({
  model: 'gemini-2.5-computer-use-preview-10-2025',
  input: "Search for highly rated smart fridges on Google Shopping.",
  tools: [
    {
      type: "computer_use",
      environment: "browser",
      excluded_predefined_functions: excludedFunctions
    }
  ]
});

console.log(interaction);

جاوا 

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Click the Submit button on the screen."))
        .tools(Arrays.asList(new ComputerUse()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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

مدل پاسخ، فراخوانی یک تابع را پیشنهاد می‌دهد. برای مدل‌های Gemini 3.x ، پاسخ شامل یک هدف استدلالی متناسب با مختصات است. در زیر نمونه‌هایی از هر دو پاسخ نشان داده شده است:

جمینی ۳.x 

{
  "steps": [
    {
      "type": "function_call",
      "name": "click",
      "arguments": {
        "x": 450,
        "y": 120,
        "intent": "Click the search box to type the destination."
      }
    }
  ]
}

جمینی ۲.۵ (لگسی) 

{
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I will type the search query into the search bar."
        }
      ]
    },
    {
      "type": "function_call",
      "name": "type_text_at",
      "arguments": {
        "x": 371,
        "y": 470,
        "text": "highly rated smart fridges",
        "press_enter": true
      }
    }
  ]
}

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

برنامه شما باید مختصات پاسخ را تجزیه کند، عمل را اجرا کند و آنها را از مختصات نرمال شده ۱۰۰۰x۱۰۰۰ مقیاس بندی کند.

کد زیر هم دستورات ابزار قدیمی ( click_at ، type_text_at ) و هم دستورات ساده و مدرن ( click ، type ) را مدیریت می‌کند.

پایتون 

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)