Uso del computer

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. Analogamente alla chiamata di funzioni, devi implementare l'ambiente di esecuzione lato client per ricevere ed eseguire le azioni di Utilizzo del computer.

Per l'elenco dei modelli supportati, consulta Versioni dei modelli. I modelli Gemini 3.x supportano diverse funzionalità avanzate:

• Supporto multi-ambiente:crea agenti per ambienti browser, mobile e desktop.
• Le azioni semplificate con intent includono un campo intent che 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:

from google import genai

client = genai.Client()

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

print(interaction)

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

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.7-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:

1. 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.
2. Ricevi la risposta del modello
   • Il modello analizza lo schermo e il prompt, restituendo una risposta che include un function_call suggerito che rappresenta un'azione dell'interfaccia utente (ad esempio un clic, uno scorrimento o una sequenza di tasti).
   • Per i modelli Gemini 3.x, la risposta include anche un ragionamento intent che spiega perché il modello ha scelto quell'azione.
   • La risposta può includere anche un safety_decision di un sistema di sicurezza interno che classifica l'azione come regolare/consentita, require_confirmation (che richiede l'approvazione dell'utente) o bloccata.
3. 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 tua area visibile ed 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.
4. 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_result per richiedere il passaggio successivo.

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.

from google import genai

client = genai.Client()

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