Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configurazione dell'uso del computer nelle API

Lezione 3 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Prerequisiti
  2. Installazione delle dipendenze
  3. Impostazione della chiave API
  4. Dichiarazione dello strumento computer
  5. Configurazione del browser
  6. Organizzazione del progetto
  7. Verifica dell’installazione
  8. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base della guida Computer use di OpenAI e delle ricette di integrazione per l’uso del computer: la configurazione utilizza ora l’SDK openai, la variabile d’ambiente OPENAI_API_KEY e lo strumento {"type": "computer"} nelle API Responses. Non si basa più sull’SDK di Anthropic né sullo strumento legacy computer_20241022. Lo strumento di OpenAI non richiede le dimensioni dello schermo; le coordinate si riferiscono allo screenshot che fornisci. Fonti: Computer use · Ricette di integrazione.

Prerequisiti

Prima di scrivere una singola riga di codice, la tua workstation ha bisogno di quattro elementi: una versione recente di Python 3, un account OpenAI con una chiave API attiva e accesso a un modello che supporti lo strumento computer, un browser Chromium guidato da Playwright per le interazioni web e Docker se prevedi di isolare l’agente. Docker è opzionale mentre stai imparando, ma OpenAI raccomanda un browser isolato o una macchina virtuale non appena l’agente interagisce con qualcosa di più complesso di un sito demo.

Per il modello, la documentazione di OpenAI utilizza gpt-6.1-sol nei suoi esempi dello strumento computer. Controlla la scheda del modello (sotto Strumenti) per confermare che l’uso del computer sia elencato e che il tuo progetto abbia accesso.

Installazione delle dipendenze

Lavora in un ambiente virtuale dedicato. Un agente di uso del computer blocca versioni specifiche di Playwright e dei suoi browser. Mescolarle con gli altri tuoi progetti Python porterà a conflitti difficili da diagnosticare.

# Crea e attiva l'ambiente
python -m venv computer-use-env
source computer-use-env/bin/activate  # Linux/Mac
# computer-use-env\Scripts\activate   # Windows

# Installa le dipendenze
pip install openai playwright pillow

# Installa il browser Playwright
playwright install chromium

Ogni pacchetto svolge un ruolo distinto: openai fornisce il client che comunica con il modello, playwright guida il browser ed esegue le azioni, e pillow gestisce la manipolazione delle immagini quando necessario. L’ultimo comando è quello che le persone dimenticano più spesso. Senza playwright install chromium, il pacchetto viene installato ma nessun browser viene scaricato, causando il fallimento della prima esecuzione.

Impostazione della chiave API

Memorizza la tua chiave in una variabile d’ambiente, mai codificata direttamente in uno script. Un segreto scritto nel codice finisce inevitabilmente in un repository Git.

export OPENAI_API_KEY="your-key"

In produzione, utilizza un gestore di segreti. Il client legge la variabile automaticamente:

from openai import OpenAI

client = OpenAI()  # legge OPENAI_API_KEY

Dichiarazione dello strumento computer

Un modello non controlla uno schermo per impostazione predefinita. Devi abilitare lo strumento computer nella richiesta e descrivere il risultato atteso.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-sol",
    tools=[{"type": "computer"}],
    input=(
        "Controlla se il pannello Filtri è aperto. In caso contrario, "
        "clicca su Mostra Filtri, quindi digita penguin nel campo di ricerca. "
        "Usa lo strumento computer per interagire con l'interfaccia."
    ),
)
print(response.output)

La dichiarazione è semplicemente {"type": "computer"}. A differenza della versione anteprima iniziale (computer_use_preview), non richiede né dimensioni dello schermo né un tipo di ambiente, e la troncatura automatica non è più necessaria. Le coordinate restituite dal modello si riferiscono allo screenshot che invii. Cattura esattamente l’area su cui intendi cliccare, alla stessa scala. Se ridimensioni uno screenshot prima di inviarlo, converti le coordinate prima di agire.

Configurazione del browser

Lato Playwright, racchiudi la logica di avvio in una funzione riutilizzabile per vari compiti.

from playwright.sync_api import sync_playwright

def launch_browser(width=1280, height=720):
    """Avvia un browser isolato per l'uso del computer."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=True)  # False per osservare l'agente
    context = browser.new_context(viewport={"width": width, "height": height})
    page = context.new_page()
    return pw, browser, page

page.screenshot() cattura il viewport, quindi le coordinate del modello si applicano direttamente a page.mouse. L’opzione headless=True esegue il browser senza interfaccia grafica, essenziale su un server. Durante lo sviluppo, imposta questo valore su False per osservare il lavoro dell’agente. È il modo più veloce per capire perché commette errori.

Organizzazione del progetto

Separa fin dall’inizio la logica del browser, il ciclo dell’agente e l’esecuzione delle azioni.

computer-use-project/
├── .env                  # OPENAI_API_KEY (non fare mai commit)
├── requirements.txt      # openai, playwright, pillow
├── src/
│   ├── __init__.py
│   ├── browser.py        # Avvio e cattura
│   ├── agent.py          # Ciclo di uso del computer
│   └── actions.py        # Esecuzione delle azioni
└── tasks/
    └── example.py        # Script dei compiti

Verifica dell’installazione

Non costruire un flusso di lavoro complesso su una configurazione non validata. Se la prima esecuzione fallisce, non saprai se il problema risiede nella chiave, nel browser o nel tuo prompt. Questo script minimale testa l’intera catena: client, browser, cattura e trasmissione dell’immagine al modello.

import base64

from openai import OpenAI
from playwright.sync_api import sync_playwright

def test_installation():
    """Verifica che chiave, browser e caricamento immagine funzionino."""
    client = OpenAI()

    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=True)
    page = browser.new_page(viewport={"width": 1280, "height": 720})
    page.goto("https://example.com")
    capture = base64.b64encode(page.screenshot()).decode("utf-8")

    response = client.responses.create(
        model="gpt-6.1-sol",
        input=[{
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Descrivi cosa vedi."},
                {"type": "input_image", "image_url": f"data:image/png;base64,{capture}"},
            ],
        }],
    )
    print("Risposta:", response.output_text)

    browser.close()
    pw.stop()

if __name__ == "__main__":
    test_installation()

Se la console visualizza una descrizione della pagina example.com, la tua configurazione è pronta e puoi procedere a costruire un agente completo.

Punti chiave

  • Installa openai, playwright e pillow in un ambiente virtuale dedicato, quindi esegui playwright install chromium
  • Mantieni OPENAI_API_KEY in una variabile d’ambiente, mai nel codice
  • Dichiara lo strumento con tools=[{"type": "computer"}] usando un modello supportato (gli esempi OpenAI usano gpt-6.1-sol)
  • Le coordinate del modello si riferiscono allo screenshot inviato: cattura l’area su cui agisci alla stessa scala
  • Testa sempre con uno script minimale prima di costruire flussi di lavoro complessi