Lo strumento Utilizzo del computer ti consente di creare agenti di controllo per browser, dispositivi mobili e computer che interagiscono con le attività e le automatizzano. Utilizzando gli screenshot, il modello può "vedere" uno schermo del computer e "agire" generando azioni specifiche della UI come clic del mouse e input da tastiera. Come per la chiamata di funzioni, devi implementare l'ambiente di esecuzione lato client per ricevere ed eseguire le azioni di Utilizzo del computer.
Gemini 3.5 Flash è il modello consigliato per l'utilizzo del computer e introduce diverse nuove funzionalità:
- Supporto multi-ambiente:crea agenti per ambienti browser, mobile e desktop.
- Le azioni semplificate con intent 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 e override delle policy integrate.
- Rilevamento di prompt injection:attiva la scansione degli screenshot per rilevare istruzioni avversarie nascoste.
Con Utilizzo del computer, puoi creare agenti che:
- Automatizza l'inserimento di dati ripetitivi o la compilazione di moduli sui siti web.
- Eseguire test automatici di applicazioni web e flussi utente
- Condurre ricerche su vari siti web (ad es. raccogliere informazioni, prezzi e recensioni sui prodotti da siti di e-commerce per informare un acquisto)
Ecco un esempio minimo di inizializzazione del client e invio di un prompt al modello con lo strumento computer_use abilitato per un ambiente browser:
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.6-flash",
input="Search for 'Gemini API' on Google.",
tools=[{"type": "computer_use", "environment": "browser"}]
)
print(interaction)
JavaScript
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI();
const interaction = await ai.interactions.create({
model: 'gemini-3.6-flash',
input: "Search for 'Gemini API' on Google.",
tools: [{ type: "computer_use", environment: "browser" }]
});
console.log(interaction);
Come funziona Uso del computer
Per creare un agente con il modello Computer Use, devi configurare un ciclo continuo tra la tua applicazione e l'API. Ecco cosa farà il tuo codice in ogni passaggio:
- Invia una richiesta al modello
- La tua applicazione invia una richiesta API contenente lo strumento Utilizzo del computer, le impostazioni di configurazione (come l'ambiente di destinazione), il prompt dell'utente e uno screenshot della schermata corrente.
- Ricevi la risposta del modello
- Il modello analizza lo schermo e il prompt, restituendo una risposta
che include un
function_callsuggerito che rappresenta un'azione dell'interfaccia utente (ad esempio un clic, uno scorrimento o una sequenza di tasti). - Per Gemini 3.5 Flash, la risposta include anche un ragionamento
intentche spiega perché il modello ha scelto quell'azione. - La risposta può includere anche un
safety_decisiondi un sistema di sicurezza interno che classifica l'azione come regolare/consentita,require_confirmation(che richiede l'approvazione dell'utente) o bloccata.
- Il modello analizza lo schermo e il prompt, restituendo una risposta
che include un
- Esegui l'azione ricevuta
- Se l'azione è consentita (o l'utente la conferma), il codice lato client analizza
function_call, ridimensiona le coordinate normalizzate in modo che corrispondano alla finestra e esegue l'azione nell'ambiente di destinazione utilizzando strumenti di automazione (come Playwright). Se l'azione è bloccata, il client deve interrompere l'esecuzione o gestire l'interruzione.
- Se l'azione è consentita (o l'utente la conferma), il codice lato client analizza
- Acquisizione del nuovo stato dell'ambiente
- Al termine dell'esecuzione dell'azione, l'applicazione acquisisce un nuovo
screenshot e lo invia di nuovo al modello in un
function_resultper richiedere il passaggio successivo.
- Al termine dell'esecuzione dell'azione, l'applicazione acquisisce un nuovo
screenshot e lo invia di nuovo al modello in un
Questo processo si ripete quindi dal passaggio 2, sollecitando continuamente l'azione successiva dal modello finché l'attività non viene completata o interrotta.

Come implementare l'uso del computer
Prima di creare con lo strumento Utilizzo del computer, devi configurare:
- Ambiente di esecuzione sicuro:esegui l'agente in una VM o in un container sandbox per isolarlo dal sistema host e limitarne il potenziale impatto. L'implementazione di riferimento include una sandbox basata su Docker pronta all'uso che puoi utilizzare come punto di partenza.
- Gestore di azioni lato client: implementa la logica lato client per eseguire le coordinate, digitare il testo e acquisire screenshot.
Gli esempi riportati di seguito utilizzano un browser web come ambiente di esecuzione e Playwright come gestore lato client.
0. Configurare Playwright
Innanzitutto, installa i pacchetti richiesti:
pip install google-genai playwright
playwright install chromium
Quindi, inizializza un'istanza del browser Playwright da utilizzare per l'esecuzione:
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.
1. Inviare una richiesta al modello
Inizializza la libreria client e configura lo strumento Utilizzo del computer. Tieni presente che non è necessario specificare le dimensioni di visualizzazione quando invii una richiesta. Il modello prevede le coordinate dei pixel scalate in base all'altezza e alla larghezza dello schermo.
Gemini 3.5 Flash (consigliato)
Python
Utilizza l'SDK Python google-genai (versione 2.7.0 o successive) per configurare una richiesta che ha come target l'ambiente del browser:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model='gemini-3.6-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)
JavaScript
Utilizza l'SDK Node.js @google/genai per configurare una richiesta che ha come target l'ambiente browser:
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI();
const interaction = await ai.interactions.create({
model: 'gemini-3.6-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);
REST
Utilizza curl per inviare una richiesta:
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.6-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
}
]
}'
Gemini 2.5 (legacy)
Python
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)
JavaScript
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);
2. Ricevere la risposta del modello
Il modello di risposta suggerisce una chiamata di funzione. Per Gemini 3.5 Flash, la risposta contiene un intento di ragionamento personalizzato insieme alle coordinate. Di seguito sono riportati esempi di entrambe le risposte:
Gemini 3.5 Flash
{
"steps": [
{
"type": "function_call",
"name": "click",
"arguments": {
"x": 450,
"y": 120,
"intent": "Click the search box to type the destination."
}
}
]
}
Gemini 2.5 (legacy)
{
"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
}
}
]
}
3. Esegui le azioni ricevute
L'applicazione deve analizzare le coordinate della risposta, eseguire l'azione e ridimensionarle dalle coordinate normalizzate 1000x1000.
Il codice riportato di seguito gestisce sia i comandi degli strumenti legacy (click_at, type_text_at) sia i comandi semplificati di Gemini 3.5 Flash (click, type).
Python
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(interaction, page, screen_width, screen_height):
results = []
function_calls = [
step for step in interaction.steps if step.type == "function_call"
]
for function_call in function_calls:
action_result = {}
fname = function_call.name
args = function_call.arguments
print(f" -> Executing: {fname} (Intent: {args.get('intent', 'N/A')})")
try:
if fname in ("open_web_browser", "open_app"):
pass # Handled / already open
elif fname in ("click", "click_at", "double_click", "triple_click", "middle_click", "right_click", "move", "long_press"):
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 == "right_click":
page.mouse.click(actual_x, actual_y, button="right")
elif fname == "middle_click":
page.mouse.click(actual_x, actual_y, button="middle")
elif fname == "move":
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)
if actual_x is not None and actual_y is not None:
page.mouse.click(actual_x, actual_y)
# Clear field first
page.keyboard.press("Meta+A")
page.keyboard.press("Backspace")
page.keyboard.type(text)
if press_enter:
page.keyboard.press("Enter")
elif fname == "navigate":
page.goto(args["url"])
elif fname == "go_back":
page.go_back()
elif fname == "go_forward":
page.go_forward()
elif fname == "wait":
time.sleep(args.get("seconds", 1))
else:
print(f"Warning: Custom or 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, function_call.id, action_result))
return results
JavaScript
function denormalizeX(x, screenWidth) {
// Convert normalized x coordinate (0-1000) to actual pixel coordinate.
return Math.floor((x / 1000) * screenWidth);
}
function denormalizeY(y, screenHeight) {
// Convert normalized y coordinate (0-1000) to actual pixel coordinate.
return Math.floor((y / 1000) * screenHeight);
}
async function executeFunctionCalls(interaction, page, screenWidth, screenHeight) {
const results = [];
const functionCalls = interaction.steps.filter(step => step.type === "function_call");
for (const functionCall of functionCalls) {
const actionResult = {};
const fname = functionCall.name;
const args = functionCall.arguments;
console.log(` -> Executing: ${fname} (Intent: ${args.intent || 'N/A'})`);
try {
if (fname === "open_web_browser" || fname === "open_app") {
// Handled / already open
} else if (["click", "click_at", "double_click", "triple_click", "middle_click", "right_click", "move", "long_press"].includes(fname)) {
const actualX = denormalizeX(args.x, screenWidth);
const actualY = denormalizeY(args.y, screenHeight);
if (fname === "click" || fname === "click_at") {
await page.mouse.click(actualX, actualY);
} else if (fname === "double_click") {
await page.mouse.dblclick(actualX, actualY);
} else if (fname === "right_click") {
await page.mouse.click(actualX, actualY, { button: "right" });
} else if (fname === "middle_click") {
await page.mouse.click(actualX, actualY, { button: "middle" });
} else if (fname === "move") {
await page.mouse.move(actualX, actualY);
}
} else if (fname === "type" || fname === "type_text_at") {
const actualX = args.x !== undefined ? denormalizeX(args.x, screenWidth) : null;
const actualY = args.y !== undefined ? denormalizeY(args.y, screenHeight) : null;
const text = args.text;
const pressEnter = args.press_enter || false;
if (actualX !== null && actualY !== null) {
await page.mouse.click(actualX, actualY);
}
// Clear field first
await page.keyboard.press("Meta+A");
await page.keyboard.press("Backspace");
await page.keyboard.type(text);
if (pressEnter) {
await page.keyboard.press("Enter");
}
} else if (fname === "navigate") {
await page.goto(args.url);
} else if (fname === "go_back") {
await