Lo strumento di utilizzo del computer di Gemini ti consente di creare agenti di controllo per browser, dispositivi mobili e computer che interagiscono con le Graphic User Interface (GUI) e automatizzano le attività. Quando l'utilizzo del computer è abilitato, il modello utilizza gli screenshot per osservare lo schermo e agire generando azioni specifiche della UI, come clic del mouse, scorrimento e input da tastiera.
Gemini supporta diverse funzionalità avanzate di utilizzo del computer:
- Supporto di più ambienti: crea agenti per ambienti browser, mobile e desktop.
- Azioni semplificate con intent: le azioni includono un campo
intentche spiega il ragionamento del modello alla base di ogni passaggio. - Policy di sicurezza configurabili: perfeziona il comportamento di sicurezza con categorie di policy e override integrati.
- Rilevamento di prompt injection: scansione degli screenshot con attivazione per rilevare istruzioni avversarie nascoste.
Puoi utilizzare l'uso del computer per creare agenti in grado di:
- Automatizza l'inserimento ripetitivo di dati o la compilazione di moduli su siti web e applicazioni desktop.
- Esegui test automatici dei flussi utente web, mobile e desktop.
- Navigare su siti web e applicazioni per raccogliere ricerche (ad esempio, confrontare informazioni sui prodotti, prezzi e recensioni).
- Assistere gli utenti eseguendo sequenze di azioni in più passaggi tra le applicazioni.
Questa guida include:
- Come funziona l'utilizzo del computer
- Come attivare l'uso del computer
- Come configurare l'ambiente, inviare richieste, ricevere risposte e creare loop dell'agente
- Ambienti e funzioni personalizzate supportati
- Azioni del computer supportate
- Assistenza per la protezione e la sicurezza
- Prezzi
Analogamente alla chiamata di funzione, devi scrivere il codice dell'applicazione lato client per ricevere la chiamata di funzione per l'uso del computer ed eseguire le azioni corrispondenti.
Questa guida presuppone che tu stia utilizzando l'SDK Google Gen AI per Python e che tu abbia familiarità con l'API Playwright.
Puoi trovare l'implementazione di riferimento per l'utilizzo del computer su GitHub.
Modelli supportati
L'utilizzo del computer è supportato nei seguenti modelli:
Fai clic per espandere i modelli supportati
Come funziona l'uso del computer
Anziché generare risposte di testo, l'utilizzo del computer determina quando eseguire azioni specifiche della UI, come i clic del mouse, e restituisce i parametri necessari per eseguire queste azioni. Devi scrivere il codice dell'applicazione lato client per ricevere l'utilizzo del computer function_call ed eseguire le azioni corrispondenti.
Le interazioni di utilizzo del computer seguono un processo di loop dell'agente:
Invia una richiesta al modello
- Aggiungi l'uso del computer (e facoltativamente eventuali strumenti aggiuntivi) alla tua richiesta API.
- Invia un prompt al modello con la richiesta dell'utente e uno screenshot che rappresenta lo stato attuale della GUI.
Ricevi la risposta del modello
- Il modello analizza la richiesta dell'utente e lo screenshot e genera una risposta che include un
function_callsuggerito che rappresenta un'azione dell'interfaccia utente (ad esempio, "fai clic sulla coordinata (x,y)" o "digita 'testo'"). Consulta Azioni supportate per l'elenco di tutte le azioni che puoi utilizzare con il modello. - La risposta dell'API potrebbe includere anche un
safety_decisiondi un sistema di sicurezza interno che ha controllato l'azione proposta dal modello.safety_decisionclassifica l'azione come:- Normale o consentita: l'azione è considerata sicura. Questo può anche essere rappresentato dall'assenza di
safety_decision. - Richiede conferma: il modello sta per eseguire un'azione che potrebbe essere rischiosa (ad esempio, fare clic su un banner "Accetta i cookie").
- Normale o consentita: l'azione è considerata sicura. Questo può anche essere rappresentato dall'assenza di
- Il modello analizza la richiesta dell'utente e lo screenshot e genera una risposta che include un
Esegui l'azione ricevuta
- Il codice lato client riceve
function_calle gli eventualisafety_decisionassociati. - Se
safety_decisionindica "regular" o "allowed" (o se non è presentesafety_decision), il codice lato client può eseguirefunction_callspecificato nell'ambiente di destinazione (ad esempio un browser web). - Se
safety_decisionindica che è necessaria la conferma, l'applicazione deve chiedere all'utente finale di confermare prima di eseguirefunction_call. Se l'utente conferma, procedi con l'esecuzione dell'azione. Se l'utente nega l'autorizzazione, non eseguire l'azione.
- Il codice lato client riceve
Acquisisci lo stato del nuovo ambiente
- Se l'azione è stata eseguita, il client acquisisce un nuovo screenshot della GUI e l'URL corrente da inviare al modello come parte di un
function_response. - Se un'azione è stata bloccata dal sistema di sicurezza o l'utente ha negato la conferma, l'applicazione potrebbe inviare un feedback diverso al modello o terminare l'interazione.
- Se l'azione è stata eseguita, il client acquisisce un nuovo screenshot della GUI e l'URL corrente da inviare al modello come parte di un
Al modello viene inviata una nuova richiesta con lo stato aggiornato. Il processo si ripete dal passaggio 2, con il modello che utilizza il nuovo screenshot (se fornito) e l'obiettivo in corso per suggerire l'azione successiva. Il loop continua fino al completamento dell'attività, al verificarsi di un errore o alla terminazione del processo (ad esempio, se una risposta viene bloccata dai filtri di sicurezza o dalla decisione dell'utente).
Il seguente diagramma illustra il funzionamento dell'utilizzo del computer:
Attiva l'uso del computer
Per abilitare l'uso del computer, assicurati che la tua applicazione utilizzi uno dei modelli supportati e aggiungi l'uso del computer all'elenco degli strumenti abilitati:
Python
from google import genai from google.genai import types from google.genai.types import Content, Part client = genai.Client( enterprise=True, project="PROJECT_ID", location="global", ) # Add computer use to the list of tools generate_content_config = types.GenerateContentConfig( tools=[ types.Tool( computer_use=types.ComputerUse( environment=types.Environment.ENVIRONMENT_BROWSER, ) ), ] ) contents = [ Content( role="user", parts=[ Part(text="Go to google.com and search for 'weather in New York'"), ], ) ] response = client.models.generate_content( model="gemini-3.8-flash", contents=contents, config=generate_content_config, ) print(response)
Node.js
import { GoogleGenAI, Environment } from '@google/genai'; const ai = new GoogleGenAI({ enterprise: true, project: 'PROJECT_ID', location: 'global', }); const response = await ai.models.generateContent({ model: 'gemini-3.8-flash', contents: "Go to google.com and search for 'weather in New York'", config: { tools: [ { computerUse: { environment: Environment.ENVIRONMENT_BROWSER, }, }, ], }, }); console.log(response);
API REST
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash:generateContent" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "Go to google.com and search for '\''weather in New York'\''" } ] } ], "tools": [ { "computer_use": { "environment": "ENVIRONMENT_BROWSER" } } ] }'
Configura l'ambiente di esecuzione
Prima di creare con lo strumento di utilizzo del computer, configura:
- Un ambiente di esecuzione sicuro: esegui l'agente in una macchina virtuale (VM) o un container (come Docker) in modalità sandbox per isolarlo dal sistema host.
- Un gestore di azioni lato client: implementa la logica client per eseguire i clic del mouse, le pressioni dei tasti della tastiera e l'acquisizione di screenshot.
Innanzitutto, installa l'SDK e le dipendenze del browser, quindi configura l'ambiente:
pip install --upgrade google-genai playwright termcolor playwright install chromium export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_CLOUD_LOCATION="global" export GOOGLE_GENAI_USE_ENTERPRISE=True
Successivamente, inizializza un'istanza del browser Playwright con dimensioni esplicite dell'area visibile in modo che le coordinate normalizzate (0-1000) vengano scalate con precisione:
from playwright.sync_api import sync_playwright SCREEN_WIDTH = 1440 SCREEN_HEIGHT = 900 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() page.goto("https://www.google.com")
Invia una richiesta
Dopo aver configurato lo strumento per l'utilizzo del computer, invia un prompt al modello che includa l'obiettivo dell'utente e uno screenshot iniziale della GUI.
Se vuoi, puoi anche aggiungere quanto segue:
- Azioni escluse: se non vuoi che il modello esegua alcune azioni dell'elenco di azioni della UI supportate, specificale in
excluded_predefined_functions. - Funzioni definite dall'utente: oltre all'utilizzo del computer, potresti voler includere funzioni personalizzate definite dall'utente.
Il seguente codice campione attiva l'utilizzo del computer e invia la richiesta al modello:
Python
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"] # Configuration for computer use with browser environment 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 (need to defined above) # types.Tool( # function_declarations=custom_functions # ) ], ) # Create the content with user message contents: list[Content] = [ 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-3.8-flash', contents=contents, config=generate_content_config, ) # Print the response output print(response.text)
Puoi anche includere funzioni definite dall'utente personalizzate per estendere la funzionalità del modello. Consulta Gemini 3.5 Flash o versioni successive e casi d'uso per dispositivi mobili o computer per informazioni su come configurare l'uso del computer per i casi d'uso per dispositivi mobili aggiungendo azioni come open_app, long_press_at e go_home ed escludendo le azioni specifiche del browser.
Ricevi le risposte
Il modello risponde con uno o più FunctionCalls se determina che sono necessarie azioni dell'interfaccia utente o funzioni definite dall'utente per completare l'attività. Il codice dell'applicazione deve analizzare queste azioni, eseguirle e raccogliere i risultati.
L'utilizzo del computer supporta la chiamata di funzione parallela, il che significa che il modello può restituire più azioni indipendenti in un singolo turno.
Per Gemini 3.5 Flash e modelli successivi, ogni azione include un argomento intent che spiega il ragionamento del modello alla base di quel passaggio:
{ "content": { "parts": [ { "function_call": { "name": "type", "args": { "x": 450, "y": 320, "text": "smart fridge touchscreen 2 doors 25 cu ft under $4000", "press_enter": true, "intent": "Type the search query into the Google search box and submit." } } } ] } }
A seconda dell'azione, la risposta dell'API potrebbe anche restituire un safety_decision
all'interno degli argomenti della chiamata di funzione:
{ "content": { "parts": [ { "function_call": { "name": "click", "args": { "x": 60, "y": 100, "intent": "Click the 'I'm not a robot' verification checkbox.", "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" } } } } ] } }
Esegui le azioni ricevute
Dopo aver ricevuto una risposta, analizza function_call, scala le coordinate dalla griglia normalizzata 0-1000 alle dimensioni effettive dei pixel dell'area visibile ed esegui l'azione:
import time
from typing import Any, Dict, List, Tuple
import termcolor
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 get_safety_confirmation(safety_decision: Dict[str, Any]) -> str:
"""Prompt user for confirmation when safety check is triggered."""
termcolor.cprint("Safety service requires explicit confirmation!", color="red")
print(safety_decision.get("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(
response, page, screen_width: int, screen_height: int
) -> List[Tuple[str, Dict[str, Any]]]:
"""Extract and execute modern and legacy function calls from Gemini response."""
candidate = response.candidates[0]
function_calls = []
thoughts = []
for part in candidate.content.parts:
if hasattr(part, "function_call") and part.function_call:
function_calls.append(part.function_call)
elif hasattr(part, "text") and part.text:
thoughts.append(part.text)
if thoughts:
print(f"Model Reasoning: {' '.join(thoughts)}")
results: List[Tuple[str, Dict[str, Any]]] = []
for function_call in function_calls:
fname = function_call.name
args = function_call.args or {}
action_result: Dict[str, Any] = {}
print(f" -> Executing: {fname} (Intent: {args.get('intent', 'N/A')})")
# Check for safety decision before executing
if "safety_decision" in args:
decision = get_safety_confirmation(args["safety_decision"])
if decision == "TERMINATE":
print("Terminating agent loop")
break
action_result["safety_acknowledgement"] = "true"
try:
if fname in ("open_web_browser", "open_app", "take_screenshot"):
pass
elif fname in (
"click",
"click_at",
"double_click",
"triple_click",
"middle_click",
"right_click",
"mouse_down",
"mouse_up",
"move",
"hover_at",
):
actual_x = denormalize_x(args["x"], screen_width)
actual_y = denormalize_y(args["y"], screen_height)
if fname in ("click", "click_at"):
page.mouse.click(actual_x, actual_y)
elif fname == "double_click":
page.mouse.dblclick(actual_x, actual_y)
elif fname == "triple_click":
page.mouse.click(actual_x, actual_y, click_count=3)
elif fname == "middle_click":
page.mouse.click(actual_x, actual_y, button="middle")
elif fname == "right_click":
page.mouse.click(actual_x, actual_y, button="right")
elif fname == "mouse_down":
page.mouse.move(actual_x, actual_y)
page.mouse.down()
elif fname == "mouse_up":
page.mouse.move(actual_x, actual_y)
page.mouse.up()
elif fname in ("move", "hover_at"):
page.mouse.move(actual_x, actual_y)
elif fname in ("type", "type_text_at"):
actual_x = denormalize_x(args["x"], screen_width) if "x" in args else None
actual_y = denormalize_y(args["y"], screen_height) if "y" in args else None
text = args["text"]
press_enter = args.get("press_enter", False)
clear_before_typing = args.get("clear_before_typing", True)
if actual_x is not None and actual_y is not None:
page.mouse.click(actual_x, actual_y)
time.sleep(0.1)
if clear_before_typing:
page.keyboard.press("ControlOrMeta+A")
page.keyboard.press("Backspace")
page.keyboard.type(text)
if press_enter:
page.keyboard.press("Enter")
elif fname in ("scroll", "scroll_at", "scroll_document"):
if "x" in args and "y" in args:
page.mouse.move(denormalize_x(args["x"], screen_width), denormalize_y(args["y"], screen_height))
direction = args.get("direction", "down")
magnitude = args.get("magnitude_in_pixels", args.get("magnitude", 300))
dx, dy = 0, 0
if direction == "down":
dy = magnitude
elif direction == "up":
dy = -magnitude
elif direction == "right":
dx = magnitude
elif direction == "left":
dx = -magnitude
page.mouse.wheel(dx, dy)
elif fname == "drag_and_drop":
start_x = denormalize_x(args.get("start_x", args.get("x", 0)), screen_width)
start_y = denormalize_y(args.get("start_y", args.get("y", 0)), screen_height)
end_x = denormalize_x(args.get("end_x", args.get("destination_x", 0)), screen_width)
end_y = denormalize_y(args.get("end_y", args.get("destination_y", 0)), screen_height)
page.mouse.move(start_x, start_y)
page.mouse.down()
page.mouse.move(end_x, end_y)
page.mouse.up()
elif fname == "press_key":
page.keyboard.press(args["key"])
elif fname == "key_down":
page.keyboard.down(args["key"])
elif fname == "key_up":
page.keyboard.up(args["key"])
elif fname == "hotkey":
page.keyboard.press("+".join(args.get("keys", [])))
elif fname == "key_combination":
page.keyboard.press(args["keys"])
elif fname == "navigate":
page.goto(args["url"])
elif fname == "search":
page.goto("https://www.google.com")
elif fname == "go_back":
page.go_back()
elif fname == "go_forward":
page.go_forward()
elif fname in ("wait", "wait_5_seconds"):
time.sleep(5 if fname == "wait_5_seconds" else args.get("seconds", 1))
else:
action_result["warning"] = f"unhandled_function: {fname}"
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
Se il valore safety_decision restituito è require_confirmation, devi chiedere all'utente di confermare prima di procedere con l'esecuzione dell'azione. In base ai Termini di servizio, non è consentito ignorare le richieste di conferma umana.
Acquisisci il nuovo stato
Dopo aver eseguito le azioni, pacchettizza ogni risultato dell'azione e lo screenshot aggiornato in un FunctionResponse da restituire al modello:
from google.genai import types from google.genai.types import Content, FunctionResponse, Part def get_function_responses( page, results: List[Tuple[str, Dict[str, Any]]] ) -> Content: """Capture screenshot and URL and package them as FunctionResponses.""" screenshot = page.screenshot(type="png") current_url = page.url function_response_parts = [] for name, action_result in results: function_response_parts.append( Part( function_response=FunctionResponse( name=name, response={ "url": current_url, **action_result, }, parts=[ types.FunctionResponsePart( inline_data=types.FunctionResponseBlob( mime_type="image/png", data=screenshot, ) ) ], ) ) ) return Content( role="user", parts=function_response_parts, )
Crea un loop dell'agente
Combina questi passaggi in un ciclo end-to-end che esegue iterazioni continue tra il modello e l'ambiente di esecuzione:
Python
from google import genai from google.genai import types from google.genai.types import Content, Part from playwright.sync_api import sync_playwright def has_function_calls(response) -> bool: """Check if model response contains any function calls.""" candidate = response.candidates[0] return any( hasattr(part, "function_call") and part.function_call for part in candidate.content.parts ) def main(): client = genai.Client( enterprise=True, project="PROJECT_ID", location="global", ) generate_content_config = types.GenerateContentConfig( tools=[ types.Tool( computer_use=types.ComputerUse( environment=types.Environment.ENVIRONMENT_BROWSER, enable_prompt_injection_detection=True, ) ) ], ) screen_width, screen_height = 1440, 900 with sync_playwright() as p: browser = p.chromium.launch(headless=False) context = browser.new_context( viewport={"width": screen_width, "height": screen_height} ) page = context.new_page() page.goto("https://www.google.com") initial_screenshot = page.screenshot(type="png") contents: list[Content] = [ Content( role="user", parts=[ Part(text="Search for flights from San Francisco to Honolulu departing June 30 and returning July 6."), Part.from_bytes(data=initial_screenshot, mime_type="image/png"), ], ) ] # Agent loop: iterate until model provides a final text response for iteration in range(10): print(f"\n--- Iteration {iteration + 1} ---") response = client.models.generate_content( model="gemini-3.8-flash", contents=contents, config=generate_content_config, ) contents.append(response.candidates[0].content) if not has_function_calls(response): print(f"FINAL RESPONSE:\n{response.text}") break results = execute_function_calls(response, page, screen_width, screen_height) if not results: break user_feedback_content = get_function_responses(page, results) contents.append(user_feedback_content) browser.close() if __name__ == "__main__": main()
Gemini 3.5 Flash o versioni successive e casi d'uso su dispositivi mobili o computer
L'utilizzo del computer supporta l'impostazione di ambienti mobile (ENVIRONMENT_MOBILE), desktop (ENVIRONMENT_DESKTOP) o browser (ENVIRONMENT_BROWSER). Il valore predefinito è ENVIRONMENT_BROWSER.
I seguenti esempi mostrano come configurare l'ambiente di esecuzione per l'utilizzo del computer con Gemini 3.5 Flash o versioni successive:
API REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
Metodo HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent
Corpo JSON della richiesta:
{
"contents": [
{
"role": "user",
"parts": {
"text": "find me a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th. start by navigating directly to flights.google.com"
}
}
],
"generation_config": {
"candidateCount": 1
},
"tools": [
{
"computer_use": {
"environment": "ENVIRONMENT_BROWSER"
}
}
]
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.
Python
L'esempio seguente richiede python-genai versione 2.7.0 o successive.
from google import genai
from google.genai.types import (
Part,
GenerateContentConfig,
Content,
Tool,
ComputerUse,
Environment,
ThinkingConfig,
)
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.6-flash",
contents=[
Content(
role="user",
parts=[
Part(text="find me a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th"),
],
)
],
config=GenerateContentConfig(
temperature=1,
top_p=0.95,
top_k=40,
max_output_tokens=8192,
tools=[
Tool(
computer_use=ComputerUse(
environment=Environment.ENVIRONMENT_MOBILE
),
),
],
thinking_config=ThinkingConfig(
include_thoughts=True
),
)
)
Funzioni definite dall'utente personalizzate
Puoi estendere la funzionalità del modello combinando computer_use con funzioni definite dall'utente (function_declarations). Ad esempio, negli scenari human-in-the-loop (HITL), puoi escludere azioni predefinite specifiche utilizzando excluded_predefined_functions e registrare una funzione yield_to_user personalizzata in modo che l'agente possa restituire il controllo a un essere umano quando incontra prompt di autenticazione a due fattori (2FA) o schermate ambigue:
Python
from google import genai from google.genai import types from google.genai.types import Content, Part client = genai.Client() def yield_to_user(reason: str) -> dict[str, str]: """Yields control back to the user for assistance or verification when an automated action is unsafe or ambiguous. Args: reason: The reason why the agent is yielding control to the human. """ return {"status": "yielded", "reason": reason} generate_content_config = types.GenerateContentConfig( tools=[ types.Tool( computer_use=types.ComputerUse( environment=types.Environment.ENVIRONMENT_BROWSER, excluded_predefined_functions=["drag_and_drop"], ) ), types.Tool( function_declarations=[ types.FunctionDeclaration.from_callable( client=client, callable=yield_to_user ) ] ), ] ) response = client.models.generate_content( model="gemini-3.8-flash", contents=[ Content( role="user", parts=[ Part( text="Click the submit button. If you need a second-factor authentication code, ask me." ), ], ) ], config=generate_content_config, ) print(response)
Azioni supportate
Lo strumento di utilizzo del computer consente al modello di richiedere le seguenti azioni utilizzando un FunctionCall. Il codice lato client deve implementare la logica di esecuzione di queste azioni. Per esempi, consulta l'implementazione di riferimento. La tabella seguente mostra le azioni supportate per l'ambiente del browser.
I modelli Gemini 3 Flash e Gemini 3.5 Flash o modelli successivi hanno
set di nomi FunctionCall diversi.
Gemini 3.5 Flash o versioni successive
Gemini 3.5 Flash: hai accesso a diversi set di chiamate di funzione a seconda dell'ambiente selezionato:Ambiente del browser
| Nome del comando | Descrizione | Argomenti (nella chiamata di funzione) |
|---|---|---|
click |
Esegue un clic con il tasto sinistro del mouse sulla coordinata specificata. |
y: int (0-999)x: int (0-999)intent: str
|
double_click |
Esegue un doppio clic sulla coordinata specificata. |
y: int (0-999)x: int (0-999)intent: str
|
triple_click |
Esegue un triplo clic sulle coordinate specificate. |
y: int (0-999)x: int (0-999)intent: str
|
middle_click |
Esegue un clic centrale alle coordinate specificate. |
y: int (0-999)x: int (0-999)intent: str
|
right_click |
Fai clic con il tasto destro del mouse sulla coordinata specificata. |
y: int (0-999)x: int (0-999)intent: str
|
mouse_down |
Tiene premuto il tasto del mouse in corrispondenza della coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
mouse_up |
Rilascia il pulsante del mouse in corrispondenza della coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
move |
Sposta il cursore nella posizione specificata. |
y: int (0-999)x: int (0-999)intent: str
|
type |
Digita il testo (facoltativamente facendo prima clic su x, y). |
y: int (0-999, facoltativo)x: int (0-999, facoltativo)text: strpress_enter: bool (facoltativo, valore predefinito false)intent: str
|
drag_and_drop |
Trascina un elemento da (start_x, start_y) a (end_x, end_y). |
start_y: int (0-999)start_x: int (0-999)end_y: int (0-999)end_x: int (0-999)intent: str
|
wait |
Attende per il numero di secondi specificato. |
seconds: int (facoltativo, valore predefinito 1)intent: str
|
press_key |
Premere il tasto specificato e rilasciarlo. |
key: strintent: str
|
key_down |
Tiene premuto il tasto specificato. |
key: strintent: str
|
key_up |
Rilascia il tasto specificato. |
key: strintent: str
|
hotkey |
Premi la combinazione di tasti specificata. |
keys: List[str]intent: str
|
take_screenshot |
Restituisce uno screenshot della schermata corrente. | intent: str |
scroll |
Scorre verso l'alto, verso il basso, a sinistra o a destra in una coordinata in base a una distanza in pixel. |
y: int (0-999)x: int (0-999)direction: str ("up", "down", "left", "right")magnitude_in_pixels: int (0-999, facoltativo, predefinito 300)intent: str
|
open_web_browser |
Apre il browser web. | intent: str |
navigate |
Indirizza il browser direttamente all'URL specificato. |
url: strintent: str
|
go_back |
Torna alla pagina web precedente nella cronologia del browser. | intent: str |
go_forward |
Consente di passare alla pagina web successiva nella cronologia di navigazione del browser. | intent: str |
Ambiente mobile
| Nome del comando | Descrizione | Argomenti (nella chiamata di funzione) |
|---|---|---|
open_app |
Apre un'applicazione in base al nome. | intent: str |
click |
Clic sinistro sulla coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
list_apps |
Elenca le applicazioni disponibili sul dispositivo, restituendo i relativi nomi e nomi dei pacchetti. | intent: str |
wait |
Attende per il numero di secondi specificato. |
intent: strseconds: int(facoltativo, valore predefinito 1)
|
go_back |
Torna alla pagina web precedente nella cronologia del browser. | intent: str |
type |
Consente di digitare il testo. |
text: strintent: strpress_enter: bool(facoltativo, valore predefinito false)
|
drag_and_drop |
Trascina l'elemento da start_y e start_x a end_y ed end_x |
start_y: int (0-999)start_x: int (0-999)end_y: int (0-999)end_x: int (0-999)intent: str
|
long_press |
Esegue una pressione prolungata in una coordinata y (0-999), x (0-999) specifica sullo schermo. |
y: int (0-999)x: int (0-999)intent: strseconds: int (facoltativo, valore predefinito 2)
|
press_key |
Premi il tasto specificato e rilascialo. |
key: strintent: str
|
take_screenshot |
Restituisce uno screenshot della schermata corrente. | intent: str |
Ambiente desktop
| Nome del comando | Descrizione | Argomenti (nella chiamata di funzione) |
|---|---|---|
click |
Clic sinistro sulla coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
double_click |
Esegue un doppio clic sulle coordinate. |
y: int (0-999)x: int (0-999)intent: str
|
triple_click |
Triplo clic sulla coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
middle_click |
Clic con tasto centrale sulle coordinate. |
y: int (0-999)x: int (0-999)intent: str
|
right_click |
Fai clic con il tasto destro del mouse sulla coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
mouse_down |
Tiene premuto il tasto del mouse in corrispondenza della coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
mouse_up |
Rilascia il pulsante del mouse in corrispondenza della coordinata. |
y: int (0-999)x: int (0-999)intent: str
|
move |
Sposta il cursore nella posizione specificata. |
y: int (0-999)x: int (0-999)intent: str
|
type |
Consente di digitare il testo. |
text: strintent: strpress_enter: bool(facoltativo, valore predefinito false)
|
drag_and_drop |
Trascina l'elemento da start_y e start_x a end_y e end_x. |
start_y: int (0-999)start_x: int (0-999)end_y: int (0-999)end_x: int (0-999)intent: str
|
wait |
Attendi per il numero di secondi specificato. |
intent: strseconds: int(facoltativo, valore predefinito 1)
|
press_key |
Premere il tasto specificato e rilasciarlo. |
key: strintent: str
|
key_down |
Tiene premuto il tasto specificato. |
key: strintent: str
|
key_up |
Rilascia il tasto specificato. |
key: strintent: str
|
hotkey |
Premi la combinazione di tasti specificata. |
keys: List[str]intent: str
|
take_screenshot |
Restituisce uno screenshot della schermata corrente. | intent: str |
scroll |
Scorre verso l'alto, verso il basso, a sinistra o a destra in corrispondenza di una coordinata in base a una distanza in pixel. |
y: int (0-999)x: int (0-999)direction: str ("up", "down", "left", "right")intent: strmagnitude_in_pixels: int (0-999, facoltativo, valore predefinito 300)
|
Gemini 3 Flash
| Nome comando | Descrizione | Argomenti (nella chiamata di funzione) | Esempio di chiamata di funzione |
|---|---|---|---|
| open_web_browser | Apre il browser web. | Nessuno | {"name": "open_web_browser", "args": {}} |
| wait_5_seconds | Mette in pausa l'esecuzione per 5 secondi per consentire il caricamento dei contenuti dinamici o il completamento delle animazioni. | Nessuno | {"name": "wait_5_seconds", "args": {}} |
| go_back | Consente di passare alla pagina precedente della cronologia del browser. | Nessuno | {"name": "go_back", "args": {}} |
| go_forward | Consente di passare alla pagina successiva della cronologia del browser. | Nessuno | {"name": "go_forward", "args": {}} |
| search | Consente di accedere alla home page del motore di ricerca predefinito (ad esempio Google). Utile per avviare una nuova attività di ricerca. | Nessuno | {"name": "search", "args": {}} |
| navigate | Indirizza il browser direttamente all'URL specificato. | url: str |
{"name": "navigate", "args": {"url": "https://www.wikipedia.org"}}
|
| click_at | Fa clic su una coordinata specifica della pagina web. I valori x e y si basano su una griglia 1000 x 1000 e vengono ridimensionati in base alle dimensioni dello schermo. | y: int (0-999), x: int (0-999) |
{"name": "click_at", "args": {"y": 300, "x": 500}}
|
| hover_at | 521963309 Passa il mouse su una coordinata specifica della pagina web. Utile per mostrare i sottomenu. x e y si basano su una griglia 1000 x 1000. | y: int (0-999) x: int (0-999) |
{"name": "hover_at", "args": {"y": 150, "x": 250}}
|
| type_text_at | Digita il testo in una coordinata specifica. Per impostazione predefinita, il campo viene prima cancellato e poi viene premuto INVIO dopo la digitazione, ma queste azioni possono essere disattivate. x e y si basano su una griglia 1000 x 1000. |
y: int (0-999), x: int (0-999),
text: str, press_enter: bool (facoltativo,
valore predefinito True), clear_before_typing: bool (facoltativo,
valore predefinito True)
|
{"name": "type_text_at", "args": {"y": 250, "x": 400,
"text": "search query", "press_enter": false}}
|
| key_combination | Premere tasti o combinazioni di tasti della tastiera, ad esempio "Ctrl+C" o "Invio". Utile per attivare azioni (come l'invio di un modulo con "Invio") o operazioni sugli appunti. |
keys: str (ad esempio, "enter", "control+c"). Consulta il riferimento API per l'elenco completo delle chiavi consentite)
|
{"name": "key_combination", "args": {"keys":
"Control+A"}}
|
| scroll_document | Scorre l'intera pagina web "verso l'alto", "verso il basso", "a sinistra" o "a destra". | direction: str ("up", "down", "left" o "right") |
{"name": "scroll_document", "args": {"direction": "down"}}
|
| scroll_at | Scorre un elemento o un'area specifica alle coordinate (x, y) nella direzione specificata di una determinata grandezza. Le coordinate e la magnitudo (valore predefinito 800) si basano su una griglia 1000 x 1000. |
y: int (0-999), x: int (0-999),
direction: str ("up", "down", "left", "right"),
magnitude: int (0-999, facoltativo, predefinito 800)
|
{"name": "scroll_at", "args": {"y": 500, "x": 500,
"direction": "down", "magnitude": 400}}
|
| drag_and_drop | Trascina un elemento da una coordinata iniziale (x, y) e lo rilascia in una coordinata di destinazione (destination_x, destination_y). Tutte le coordinate si basano su una griglia 1000 x 1000. |
y: int (0-999), x: int (0-999),
destination_y: int (0-999),
destination_x: int (0-999)
|
{"name": "drag_and_drop", "args": {"y": 100, "x": 100,
"destination_y": 500, "destination_x": 500}}
|
Protezione e sicurezza
Questa sezione descrive le misure di salvaguardia adottate dallo strumento di utilizzo del computer per migliorare il controllo da parte dell'utente e la sicurezza. Descrive inoltre le best practice per mitigare i potenziali nuovi rischi che lo strumento potrebbe presentare.
Conferma la decisione sulla sicurezza
A seconda dell'azione, la risposta del modello potrebbe includere un
safety_decision da un sistema di sicurezza interno. Questa decisione verifica la sicurezza dell'azione proposta dallo strumento.
{
"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"
}
}
}
}
]
}
}
Se safety_decision è require_confirmation, devi chiedere all'utente finale di confermare prima di procedere con l'esecuzione dell'azione.
Il seguente esempio di codice chiede conferma all'utente finale prima di eseguire l'azione. Se l'utente non conferma l'azione, il loop termina. Se l'utente conferma l'azione, questa viene eseguita e il campo safety_acknowledgement viene contrassegnato come 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(response, page, screen_width: int, screen_height: int):
# ... 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 ...
Se l'utente conferma, devi includere la conferma di sicurezza nel tuo 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
)
)
]
)
)
Rilevamento di prompt injection
L'utilizzo del computer in Gemini 3.5 Flash o versioni successive supporta
un meccanismo di sicurezza avanzato per rilevare gli attacchi di prompt injection. Quando è attiva, questa funzionalità controlla se uno screenshot incluso potrebbe introdurre un attacco di prompt injection. Puoi impostare questa funzionalità nella configurazione dell'utilizzo del computer. Il valore predefinito è false.
I seguenti esempi mostrano come abilitare la configurazione dell'utilizzo del computer per attivare il rilevamento di prompt injection:
API REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
Metodo HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent
Corpo JSON della richiesta:
{
"contents": [
{
"role": "user",
"parts": {
"text": "find me a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th. start by navigating directly to flights.google.com"
}
}
],
"generation_config": {
"candidateCount": 1
},
"tools": [
{
"computer_use": {
"environment": "ENVIRONMENT_BROWSER",
"enable_prompt_injection_detection": true
}
}
]
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.
Python
L'esempio seguente richiede python-genai versione 2.7.0 o successive.
from google import genai
from google.genai.types import (
Part,
GenerateContentConfig,
Content,
Tool,
ComputerUse,
Environment,
ThinkingConfig,
)
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.6-flash",
contents=[
Content(
role="user",
parts=[
Part(text="find me a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th"),
],
)
],
config=GenerateContentConfig(
temperature=1,
top_p=0.95,
top_k=40,
max_output_tokens=8192,
tools=[
Tool(
computer_use=ComputerUse(
environment=Environment.ENVIRONMENT_MOBILE,
enable_prompt_injection_detection=True
),
),
],
thinking_config=ThinkingConfig(
include_thoughts=True
),
)
)
Best practice per la sicurezza
L'utilizzo del computer presenta rischi di cui gli sviluppatori devono essere consapevoli:
- Contenuti non attendibili e frodi:mentre il modello cerca di raggiungere l'obiettivo dell'utente, potrebbe fare affidamento su fonti di informazioni e istruzioni non attendibili sullo schermo.
- Azioni occasionali non intenzionali: il modello può interpretare erroneamente l'obiettivo di un utente o i contenuti di una pagina web, causando azioni errate come il clic sul pulsante sbagliato o la compilazione del modulo sbagliato.
- Violazioni delle norme: le funzionalità dell'API potrebbero essere utilizzate per attività che violano i termini e le norme di Google, come l'elusione dei CAPTCHA o la compromissione dell'integrità del sistema.
Per far fronte a questi rischi, devi implementare le seguenti misure di sicurezza e best practice:
- Human-in-the-loop (HITL):
- Implementa la conferma dell'utente: quando la risposta di sicurezza indica
require_confirmation, devi implementare la conferma dell'utente prima dell'esecuzione. - Fornisci istruzioni di sicurezza personalizzate:oltre ai controlli di conferma dell'utente integrati, gli sviluppatori possono facoltativamente aggiungere un'istruzione di sistema personalizzata che applica le proprie policy di sicurezza, per bloccare determinate azioni del modello o richiedere la conferma dell'utente prima che il modello esegua determinate azioni irreversibili ad alto rischio.
Fai clic per visualizzare un esempio di istruzione di sistema di sicurezza personalizzata
## **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. **USER_CONFIRMATION Categories:** * **Consent and Agreements:** Terms of Service, Privacy Policies, Cookie banners. * **Robot Detection:** CAPTCHAs of any kind. * **Financial Transactions:** Completing purchases or moving funds. * **Sending Communications:** Emails, forum posts, or chat messages. * **Accessing/Modifying Sensitive Information:** Healthcare, financial, or ID records. * **User Data Management:** Downloading files, transferring user data. * **Browser Data Usage:** Chrome history, bookmarks, autofill passwords. * **Security and Identity:** Logging into accounts or impersonation. ## **RULE 2: Default Behavior (ACTUATE)** If an action does NOT fall under USER_CONFIRMATION, proactively perform all necessary steps to move the user's request forward.
- Implementa la conferma dell'utente: quando la risposta di sicurezza indica
- Ambiente di esecuzione sicuro: esegui l'agente in un ambiente sicuro e in sandbox per limitarne il potenziale impatto (ad esempio, una macchina virtuale (VM) in sandbox, un container come Docker o un profilo del browser dedicato con autorizzazioni limitate).
- Sanitizzazione degli input: sanitizza tutto il testo generato dagli utenti nei prompt per ridurre il rischio di istruzioni indesiderate o prompt injection. Si tratta di un livello di sicurezza utile, ma non sostituisce un ambiente di esecuzione sicuro.
- Guardrail dei contenuti: utilizza i guardrail e le API di sicurezza dei contenuti (come Model Armor) per valutare l'appropriatezza degli input degli utenti, degli input e degli output degli strumenti di immissione e delle risposte dell'agente, nonché per rilevare prompt injection e jailbreak.
- Liste consentite e liste bloccate: implementa meccanismi di filtro per controllare dove il modello può navigare e cosa può fare. Una lista bloccata di siti web vietati è un buon punto di partenza, mentre una lista consentita più restrittiva è ancora più sicura.
- Osservabilità e logging: mantieni log dettagliati per il debug, l'audit e la risposta agli incidenti. Il client deve registrare i prompt, gli screenshot, le azioni suggerite dal modello (
function_call), le risposte di sicurezza e tutte le azioni eseguite dal client. - Gestione dell'ambiente: assicurati che l'ambiente della GUI sia coerente. Popup imprevisti, notifiche di sistema o spostamenti del layout possono confondere il modello. Quando possibile, inizia ogni nuova attività da uno stato noto e pulito.
Conferme human-in-the-loop (HITL)
Le conferme human-in-the-loop (HITL) sono il processo di richiesta di conferma da parte dell'utente prima di eseguire un'azione suggerita dal modello. Questo processo è necessario quando il modello non può eseguire un'azione per motivi di sicurezza.
Lo strumento per l'utilizzo del computer di Gemini fornisce i seguenti meccanismi per controllare le conferme HITL:
- A livello di sviluppatore: gli sviluppatori possono configurare se applicare o meno alcune o tutte le conferme HITL predefinite.
- A livello di organizzazione: gli amministratori dell'organizzazione possono creare una policy a livello di organizzazione che impedisce ai singoli sviluppatori di disattivare alcune o tutte le conferme HITL. Questa policy prevale su qualsiasi impostazione a livello di sviluppatore.
Ignora le conferme HITL
Puoi eseguire l'override delle seguenti conferme HITL predefinite:
FINANCIAL_TRANSACTIONS: completamento del passaggio finale di una transazione finanziaria (ad esempio pagamenti, trasferimenti di fondi, emissione di un vaglia, avvio o modifica di un abbonamento o completamento di una prenotazione).SENSITIVE_DATA_MODIFICATION: modifica di informazioni sensibili, come dati sanitari, finanziari o governativi.COMMUNICATION_TOOL: accesso o utilizzo di strumenti di comunicazione per inviare, condividere, pubblicare o trasmettere in altro modo comunicazioni.ACCOUNT_CREATION: interazione con i flussi di registrazione o iscrizione che creano o eseguono il provisioning di nuovi account utente o di servizio.DATA_MODIFICATION: modifica, gestione, condivisione, archiviazione, invio o eliminazione di dati di navigazione o file.USER_CONSENT_MANAGEMENT: interazione con le finestre di dialogo o i banner per il consenso dell'utente prendendo una decisione.LEGAL_TERMS_AND_AGREEMENTS: interazione con finestre di dialogo di accordi legalmente vincolanti, come l'accettazione dei Termini di servizio, le finestre di dialogo delle norme sulla privacy o le note legali.
Puoi eseguire l'override di una o tutte queste conferme HITL elencandole nel campo disabled_safety_policies della configurazione dell'utilizzo del computer:
Python
API GenerateContent
generate_content_config = genai.types.GenerateContentConfig(
tools=[
types.Tool(
computer_use=types.ComputerUse(
environment=types.Environment.ENVIRONMENT_MOBILE,
disabled_safety_policies=[
types.SafetyPolicy.FINANCIAL_TRANSACTIONS,
types.SafetyPolicy.COMMUNICATION_TOOL,
]
)
),
],
)
contents = [
types.Content(
role="user",
parts=[
types.Part(text="Open the Maps app and find the nearest coffee shop."),
],
)
]
response = client.models.generate_content(
model='gemini-3.5-flash',
contents=contents,
config=generate_content_config,
)API Interactions
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model='gemini-3.5-flash',
input='Open the Maps app and find the nearest coffee shop.',
tools=[
{
'type': 'computer_use',
'environment': 'mobile',
'disabled_safety_policies': [
'financial_transactions',
'communication_tool',
],
}
]
)REST
API GenerateContent
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Open the Maps app and find the nearest coffee shop."
}
]
}
],
"tools": [
{
"computer_use": {
"environment": "ENVIRONMENT_MOBILE",
"disabled_safety_policies" : [
"FINANCIAL_TRANSACTIONS",
"COMMUNICATION_TOOL"
]
}
}
]
}API Interactions
{
"model": "gemini-3.5-flash",
"input": "Open the Maps app and find the nearest coffee shop.",
"tools": [
{
"type": "computer_use",
"environment": "mobile",
"disabled_safety_policies": [
"financial_transactions",
"communication_tool"
]
}
]
}Crea policy dell'organizzazione
Se sei un amministratore dell'organizzazione, puoi creare una policy a livello di organizzazione utilizzando il servizio policy dell'organizzazione che impedisce ai singoli sviluppatori di disattivare alcune o tutte le conferme HITL. Questa policy prevale su qualsiasi impostazione a livello di sviluppatore.
Puoi creare una policy utilizzando la
consoleGoogle Cloud
o
Google Cloud CLI.
L'ID del vincolo è vertexai.configurableComputerUseToolSafetyPolicies.
La propagazione delle modifiche alle policy dell'organizzazione può richiedere fino a un'ora.
Per informazioni dettagliate su come creare e gestire le policy dell'organizzazione, consulta Crea policy dell'organizzazione.
Prezzi
L'utilizzo del computer ha lo stesso prezzo di Gemini e utilizza gli stessi SKU. Per suddividere i costi di utilizzo del computer, utilizza le etichette dei metadati personalizzati. Per saperne di più sull'utilizzo delle etichette dei metadati personalizzati per il monitoraggio dei costi, consulta Etichette dei metadati personalizzati.