Configurazione dell'uso del computer nelle API
In questa pagina
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’ambienteOPENAI_API_KEYe lo strumento{"type": "computer"}nelle API Responses. Non si basa più sull’SDK di Anthropic né sullo strumento legacycomputer_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,playwrightepillowin un ambiente virtuale dedicato, quindi eseguiplaywright install chromium - Mantieni
OPENAI_API_KEYin una variabile d’ambiente, mai nel codice - Dichiara lo strumento con
tools=[{"type": "computer"}]usando un modello supportato (gli esempi OpenAI usanogpt-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