Përdorimi i kompjuterit

Modeli dhe mjeti Gemini 2.5 Computer Use Preview ju mundëson të ndërtoni agjentë kontrolli të shfletuesit që ndërveprojnë dhe automatizojnë detyrat. Duke përdorur pamjet e ekranit, modeli i Përdorimit të Kompjuterit mund të "shohë" një ekran kompjuteri dhe "të veprojë" duke gjeneruar veprime specifike të UI, si klikimet e miut dhe hyrjet e tastierës. Ngjashëm me thirrjen e funksionit, duhet të shkruani kodin e aplikacionit nga ana e klientit për të marrë dhe ekzekutuar veprimet e përdorimit të kompjuterit.

Me përdorimin e kompjuterit, mund të ndërtoni agjentë që:

• Automatizoni futjen e përsëritur të të dhënave ose plotësimin e formularit në faqet e internetit.
• Kryeni testimin e automatizuar të aplikacioneve në ueb dhe flukseve të përdoruesve
• Kryeni kërkime nëpër uebsajte të ndryshme (p.sh., mbledhja e informacionit të produktit, çmimet dhe rishikimet nga faqet e tregtisë elektronike për të informuar një blerje)

Mënyra më e lehtë për të testuar modelin e përdorimit të kompjuterit Gemini është përmes zbatimit të referencës ose mjedisit demo të Browserbase .

Si funksionon përdorimi i kompjuterit

Për të ndërtuar një agjent kontrolli të shfletuesit me modelin e përdorimit të kompjuterit, zbatoni një lak agjenti që bën sa më poshtë:

1. Dërgoni një kërkesë tek modeli

   • Shtoni mjetin e përdorimit të kompjuterit dhe opsionalisht çdo funksion të personalizuar të përcaktuar nga përdoruesi ose funksione të përjashtuara në kërkesën tuaj API.
   • Kërkoni modelin e përdorimit të kompjuterit me kërkesën e përdoruesit dhe një pamje të ekranit që përfaqëson gjendjen aktuale të GUI-së.

2. Merrni përgjigjen e modelit

   • Modeli i Përdorimit të Kompjuterit analizon kërkesën e përdoruesit dhe pamjen e ekranit, dhe gjeneron një përgjigje e cila përfshin një function_call të sugjeruar që përfaqëson një veprim të ndërfaqes së përdoruesit (p.sh., "kliko në koordinatë (x,y)" ose "shkruani 'tekst'"). Për një përshkrim të të gjitha veprimeve të ndërfaqes së përdoruesit të mbështetur nga modeli i përdorimit të kompjuterit, shihni Veprimet e mbështetura .
   • Përgjigja API mund të përfshijë gjithashtu një safety_decision nga një sistem i brendshëm sigurie që kontrollon veprimin e propozuar të modelit. Ky safety_decision e klasifikon veprimin si:
     • E rregullt / e lejuar: Veprimi konsiderohet i sigurt. Kjo mund të përfaqësohet edhe nga mungesa e safety_decision .
     • Kërkon konfirmim ( require_confirmation ): Modeli është gati të kryejë një veprim që mund të jetë i rrezikshëm (p.sh., duke klikuar mbi një "pranoni flamurin e cookie-ve").

3. Ekzekutoni veprimin e marrë

   • Kodi juaj nga ana e klientit merr function_call dhe çdo vendim shoqërues safety_decision .
     • I rregullt / i lejuar: Nëse safety_decision tregon të rregullt / të lejuar (ose nëse nuk është prezent safety_decision ), kodi juaj nga ana e klientit mund të ekzekutojë function_call e specifikuar në mjedisin tuaj të synuar (p.sh., një shfletues ueb).
     • Kërkon konfirmim: Nëse safety_decision tregon se kërkon konfirmim, aplikacioni juaj duhet t'i kërkojë përdoruesit fundor për konfirmim përpara se të ekzekutojë function_call . Nëse përdoruesi konfirmon, vazhdoni të ekzekutoni veprimin. Nëse përdoruesi mohon, mos e ekzekutoni veprimin.

4. Kapni gjendjen e re të mjedisit

   • Nëse veprimi është ekzekutuar, klienti juaj kap një pamje të re të GUI-së dhe URL-në aktuale për t'ia dërguar përsëri modelit të përdorimit të kompjuterit si pjesë e një function_response .
   • Nëse një veprim bllokohet nga sistemi i sigurisë ose refuzohet konfirmimi nga përdoruesi, aplikacioni juaj mund t'i dërgojë modelit një formë tjetër reagimi ose të përfundojë ndërveprimin.

Ky proces përsëritet nga hapi 2 me modelin e përdorimit të kompjuterit duke përdorur pamjen e re të ekranit dhe qëllimin e vazhdueshëm për të sugjeruar veprimin tjetër. Cikli vazhdon derisa detyra të përfundojë, të ndodhë një gabim ose të përfundojë procesi (p.sh., për shkak të një reagimi "bllokimi" të sigurisë ose vendimit të përdoruesit).

Si të zbatohet përdorimi i kompjuterit

Përpara se të ndërtoni me modelin dhe mjetin e Përdorimit të Kompjuterit, do t'ju duhet të konfiguroni sa vijon:

• Mjedisi i sigurt i ekzekutimit: Për arsye sigurie, duhet të përdorni agjentin tuaj të përdorimit të kompjuterit në një mjedis të sigurt dhe të kontrolluar (p.sh., një makinë virtuale me sandbox, një kontejner ose një profil të dedikuar shfletuesi me leje të kufizuara).
• Trajtuesi i veprimeve nga ana e klientit: Do t'ju duhet të zbatoni logjikën e klientit për të ekzekutuar veprimet e krijuara nga modeli dhe për të kapur pamjet e ekranit të mjedisit pas çdo veprimi.

Shembujt në këtë seksion përdorin një shfletues si mjedis ekzekutimi dhe Playwright si mbajtës të veprimeve nga ana e klientit. Për të ekzekutuar këto mostra, duhet të instaloni varësitë e nevojshme dhe të inicializoni një shembull të shfletuesit 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.
    

Shembulli i kodit për shtrirjen në një mjedis Android përfshihet në seksionin Përdorimi i funksioneve të personalizuara të përcaktuara nga përdoruesi .

1. Dërgoni një kërkesë modelit

Shtoni mjetin "Përdorimi i kompjuterit" në kërkesën tuaj API dhe dërgoni një kërkesë te modeli "Përdorimi i kompjuterit" që përfshin qëllimin e përdoruesit dhe një pamje fillestare të GUI-së. Duhet të përdorni modelin Gemini Computer Use, gemini-2.5-computer-use-preview-10-2025 . Nëse përpiqeni të përdorni mjetin "Përdorimi i kompjuterit" me një model tjetër, do të merrni një gabim.

Ju gjithashtu mund të shtoni opsionalisht parametrat e mëposhtëm:

• Veprimet e përjashtuara: Nëse ka ndonjë veprim nga lista e veprimeve të ndërfaqes së përdoruesit të mbështetur që nuk dëshironi që modeli të kryejë, specifikoni këto veprime si excluded_predefined_functions .
• Funksionet e përcaktuara nga përdoruesi: Përveç veglës Përdorimi i kompjuterit, mund të dëshironi të përfshini funksione të personalizuara të përcaktuara nga përdoruesi.

Vini re se nuk ka nevojë të specifikoni madhësinë e ekranit kur lëshoni një kërkesë; modeli parashikon koordinatat e pikselit të shkallëzuara në lartësinë dhe gjerësinë e ekranit.

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."),
            # Optional: include a screenshot of the initial state
            #Part.from_bytes(
                #data=screenshot_image_bytes,
                #mime_type='image/png',
            #),
        ],
    )
]

# 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)

Për një shembull me funksionet e personalizuara, shihni Përdorimi i funksioneve të personalizuara të përcaktuara nga përdoruesi .

2. Merrni përgjigjen e modelit

Modeli i përdorimit të kompjuterit do të përgjigjet me një ose më shumë FunctionCalls nëse përcakton se veprimet e ndërfaqes së përdoruesit janë të nevojshme për të përfunduar detyrën. Përdorimi i kompjuterit mbështet thirrjen e funksioneve paralele, që do të thotë se modeli mund të kthejë veprime të shumta në një kthesë të vetme.

Këtu është një shembull i përgjigjes së modelit.

{
  "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
          }
        }
      }
    ]
  }
}

3. Ekzekutoni veprimet e marra

Kodi i aplikacionit tuaj duhet të analizojë përgjigjen e modelit, të ekzekutojë veprimet dhe të mbledhë rezultatet.

Shembulli i kodit më poshtë nxjerr thirrjet e funksionit nga përgjigja e modelit të Përdorimit të Kompjuterit dhe i përkthen ato në veprime që mund të ekzekutohen me Playwright. Modeli nxjerr koordinatat e normalizuara (0-999) pavarësisht nga dimensionet e imazhit të hyrjes, kështu që pjesë e hapit të përkthimit është konvertimi i këtyre koordinatave të normalizuara përsëri në vlerat aktuale të pikselit.

Madhësia e rekomanduar e ekranit për përdorim me modelin e përdorimit të kompjuterit është (1440, 900). Modeli do të funksionojë me çdo rezolutë, megjithëse cilësia e rezultateve mund të ndikohet.

Vini re se ky shembull përfshin vetëm zbatimin për 3 veprimet më të zakonshme të UI: open_web_browser , click_at dhe type_text_at . Për rastet e përdorimit të prodhimit, do t'ju duhet të zbatoni të gjitha veprimet e tjera të ndërfaqes së përdoruesit nga lista e veprimeve të mbështetura, përveç nëse i shtoni ato në mënyrë eksplicite si 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

4. Kapni gjendjen e re të mjedisit

Pas ekzekutimit të veprimeve, dërgoni rezultatin e ekzekutimit të funksionit përsëri te modeli në mënyrë që ai të mund të përdorë këtë informacion për të gjeneruar veprimin tjetër. Nëse janë ekzekutuar veprime të shumta (thirrje paralele), duhet të dërgoni një FunctionResponse për secilin në kthesën pasuese të përdoruesit.

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

Ndërtoni një lak agjenti

Për të mundësuar ndërveprime me shumë hapa, kombinoni katër hapat nga seksioni Si të zbatoni përdorimin e kompjuterit në një lak. Mos harroni të menaxhoni saktë historikun e bisedave duke shtuar si përgjigjet e modelit ashtu edhe përgjigjet e funksionit tuaj.

Për të ekzekutuar këtë mostër kodi ju duhet:

• Instaloni varësitë e nevojshme të Dramaturgut .

• Përcaktoni funksionet ndihmëse nga hapat (3) Ekzekutoni veprimet e marra dhe (4) Kapni gjendjen e re të mjedisit .

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()

Përdorimi i funksioneve të personalizuara të përcaktuara nga përdoruesi

Mund të përfshini opsionalisht funksione të përcaktuara nga përdoruesi në kërkesën tuaj për të zgjeruar funksionalitetin e modelit. Shembulli i mëposhtëm përshtat modelin dhe mjetin e përdorimit të kompjuterit për rastet e përdorimit celular duke përfshirë veprime të personalizuara të përcaktuara nga përdoruesi si open_app , long_press_at dhe go_home , duke përjashtuar veprimet specifike të shfletuesit. Modeli mund t'i thërrasë në mënyrë inteligjente këto funksione të personalizuara së bashku me veprimet standarde të UI për të përfunduar detyrat në mjedise jo shfletues.

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."),
            # optional screenshot attachment
            Part.from_bytes(
                data=screenshot_image_bytes,
                mime_type="image/png",
            ),
        ],
    )
]

# 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)

Veprimet e UI të mbështetura

Modeli i përdorimit të kompjuterit mund të kërkojë veprimet e mëposhtme të ndërfaqes së përdoruesit nëpërmjet një FunctionCall . Kodi juaj nga ana e klientit duhet të zbatojë logjikën e ekzekutimit për këto veprime. Shih zbatimin e referencës për shembuj.

Siguria dhe siguria

Pranoni vendimin e sigurisë

Në varësi të veprimit, përgjigja e modelit mund të përfshijë gjithashtu një safety_decision nga një sistem i brendshëm sigurie që kontrollon veprimin e propozuar të modelit.

{
  "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"
            }
          }
        }
      }
    ]
  }
}

Nëse safety_decision është require_confirmation , duhet t'i kërkoni përdoruesit fundor të konfirmojë përpara se të vazhdoni me ekzekutimin e veprimit. Sipas kushteve të shërbimit , nuk ju lejohet të anashkaloni kërkesat për konfirmim njerëzor.

Ky mostër kodi kërkon konfirmimin e përdoruesit përfundimtar përpara se të ekzekutojë veprimin. Nëse përdoruesi nuk e konfirmon veprimin, cikli përfundon. Nëse përdoruesi konfirmon veprimin, veprimi ekzekutohet dhe fusha e_konfirmimit safety_acknowledgement shënohet si 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 ...

Nëse përdoruesi konfirmon, ju duhet të përfshini konfirmimin e sigurisë në FunctionResponse tuaj.

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
                )
             )
           ]
         )
       )

Praktikat më të mira të sigurisë

Computer Use API është një API e re dhe paraqet rreziqe të reja që zhvilluesit duhet të kenë parasysh:

• Përmbajtje dhe mashtrime jo të besueshme: Ndërsa modeli përpiqet të arrijë qëllimin e përdoruesit, ai mund të mbështetet në burime informacioni dhe udhëzime jo të besueshme nga ekrani. Për shembull, nëse qëllimi i përdoruesit është të blejë një telefon Pixel dhe modeli ndeshet me një mashtrim "Free-Pixel nëse përfundon një sondazh", ka disa mundësi që modeli të përfundojë sondazhin.
• Veprime të rastësishme të paqëllimshme: Modeli mund të keqinterpretojë qëllimin e një përdoruesi ose përmbajtjen e faqes në internet, duke e bërë atë të ndërmarrë veprime të pasakta si klikimi i butonit të gabuar ose plotësimi i formularit të gabuar. Kjo mund të çojë në detyra të dështuara ose ekfiltrim të të dhënave.
• Shkeljet e politikave: Aftësitë e API-së mund të drejtohen, me dashje ose pa dashje, drejt aktiviteteve që shkelin politikat e Google ( Politika e përdorimit të ndaluar të Gen AI dhe Kushtet shtesë të shërbimit të Gemini API . Kjo përfshin veprime që mund të ndërhyjnë me integritetin e një sistemi, rrezikojnë sigurinë, anashkalojnë masat e sigurisë, pajisjet mjekësore, etj.

Për të adresuar këto rreziqe, mund të zbatoni masat e mëposhtme të sigurisë dhe praktikat më të mira:

1. Human-in-the-Loop (HITL):

   • Zbatimi i konfirmimit të përdoruesit: Kur përgjigja e sigurisë tregon require_confirmation , duhet të zbatoni konfirmimin e përdoruesit përpara ekzekutimit. Shihni Prano vendimin e sigurisë për kodin e mostrës.

   • Siguroni udhëzime të personalizuara të sigurisë: Përveç kontrolleve të integruara të konfirmimit të përdoruesit, zhvilluesit mund të shtojnë opsionalisht një udhëzim të personalizuar të sistemit që zbaton politikat e tyre të sigurisë, ose për të bllokuar veprime të caktuara të modelit ose për të kërkuar konfirmimin e përdoruesit përpara se modeli të ndërmarrë disa veprime të pakthyeshme me aksione të larta. Këtu është një shembull i një udhëzimi të sistemit të sigurisë me porosi që mund të përfshini kur ndërveproni me modelin.

     Shembull udhëzimesh sigurie

     Vendosni rregullat tuaja të personalizuara të sigurisë si një udhëzim sistemi:

         ## **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. Mjedisi i sigurt i ekzekutimit: Drejtoni agjentin tuaj në një mjedis të sigurt, me sandbox për të kufizuar ndikimin e tij të mundshëm (p.sh., një makinë virtuale me sandbox (VM), një kontejner (p.sh., Docker) ose një profil i dedikuar shfletuesi me leje të kufizuara).

3. Sanitizimi i hyrjes: Sanitizoni të gjithë tekstin e krijuar nga përdoruesi në kërkesat për të zbutur rrezikun e udhëzimeve të paqëllimshme ose injektimit të menjëhershëm. Kjo është një shtresë e dobishme sigurie, por jo një zëvendësim për një mjedis të sigurt ekzekutimi.

4. Mbrojtësit e përmbajtjes: Përdorni parmakët dhe API-të e sigurisë së përmbajtjes për të vlerësuar hyrjet e përdoruesit, hyrjen dhe daljen e veglave, përgjigjen e një agjenti për përshtatshmërinë, injektimin e menjëhershëm dhe zbulimin e jailbreak-it.

5. Listat e lejimeve dhe listat e bllokimit: Zbatoni mekanizmat e filtrimit për të kontrolluar se ku mund të lundrojë modeli dhe çfarë mund të bëjë. Një listë e bllokuar e faqeve të internetit të ndaluara është një pikënisje e mirë, ndërsa një listë lejesh më kufizuese është edhe më e sigurt.

6. Vëzhgueshmëria dhe regjistrimi: Mbani regjistra të detajuar për korrigjimin, auditimin dhe reagimin ndaj incidentit. Klienti juaj duhet të regjistrojë kërkesat, pamjet e ekranit, veprimet e sugjeruara nga modeli (function_call), përgjigjet e sigurisë dhe të gjitha veprimet e ekzekutuara përfundimisht nga klienti.

7. Menaxhimi i mjedisit: Sigurohuni që mjedisi GUI të jetë i qëndrueshëm. Dritaret kërcyese, njoftimet ose ndryshimet e papritura në paraqitje mund të ngatërrojnë modelin. Filloni nga një gjendje e njohur dhe e pastër për çdo detyrë të re nëse është e mundur.

Versionet e modelit

Çfarë është më pas

• Eksperimentoni me përdorimin e kompjuterit në mjedisin demonstrues të Browserbase .
• Shikoni zbatimin e Referencës për shembull kodin.
• Mësoni rreth mjeteve të tjera të Gemini API:
  • Thirrja e funksionit
  • Tokëzimi me Google Search