Korzystanie z komputera

Narzędzie Computer Use umożliwia tworzenie agentów sterujących przeglądarką, urządzeniami mobilnymi i komputerami, którzy wchodzą w interakcje z użytkownikiem i automatyzują zadania. Na podstawie zrzutów ekranu model może „widzieć” ekran komputera i „działać”, generując określone działania interfejsu, takie jak kliknięcia myszą i wpisywanie z klawiatury. Podobnie jak w przypadku wywoływania funkcji musisz wdrożyć środowisko wykonawcze po stronie klienta, aby otrzymywać i wykonywać działania związane z korzystaniem z komputera.

Listę obsługiwanych modeli znajdziesz w sekcji Wersje modeli. Modele Gemini 3.x obsługują kilka zaawansowanych funkcji:

• Obsługa wielu środowisk: twórz agentów dla środowisk przeglądarki, urządzeń mobilnych i komputerów.
• Uproszczone działania z intencjami: działania zawierają pole intent, które wyjaśnia uzasadnienie modelu dla każdego kroku.
• Konfigurowalne zasady bezpieczeństwa: dostosuj zachowanie związane z bezpieczeństwem za pomocą wbudowanych kategorii zasad i zastąpień.
• Wykrywanie wstrzykiwania promptów: włącz skanowanie zrzutów ekranu, aby wykrywać ukryte instrukcje.

Za pomocą funkcji Korzystanie z komputera możesz tworzyć agentów, którzy:

• automatyzować powtarzające się wprowadzanie danych lub wypełnianie formularzy w witrynach;
• Przeprowadzanie automatycznych testów aplikacji internetowych i ścieżek użytkownika
• prowadzić wyszukiwanie w różnych witrynach (np. zbierać informacje o produktach, cenach i opiniach w witrynach e-commerce, aby podjąć decyzję o zakupie);

Oto minimalny przykład inicjowania klienta i wysyłania prompta do modelu z narzędziem computer_use włączonym w środowisku przeglądarki:

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);

Jak działa korzystanie z komputera

Aby utworzyć agenta z modelem Computer Use, musisz skonfigurować ciągłą pętlę między aplikacją a interfejsem API. Oto, co Twój kod będzie robić na każdym etapie:

1. Wysyłanie żądania do modelu
   • Aplikacja wysyła żądanie do interfejsu API zawierające narzędzie Computer Use, ustawienia konfiguracji (np. środowisko docelowe), prompt użytkownika i zrzut ekranu.
2. Otrzymywanie odpowiedzi od modelu
   • Model analizuje ekran i prompt, a następnie zwraca odpowiedź, która zawiera sugerowany function_call reprezentujący działanie w interfejsie (np. kliknięcie, przewinięcie lub naciśnięcie klawisza).
   • W przypadku modeli Gemini 3.x odpowiedź zawiera też uzasadnienie intent, które wyjaśnia, dlaczego model wybrał to działanie.
   • Odpowiedź może też zawierać safety_decision z wewnętrznego systemu bezpieczeństwa, który klasyfikuje działanie jako zwykłe/dozwolone, require_confirmation (wymagające zatwierdzenia przez użytkownika) lub zablokowane.
3. Wykonaj otrzymane działanie
   • Jeśli działanie jest dozwolone (lub użytkownik je potwierdzi), kod po stronie klienta analizuje function_call, skaluje znormalizowane współrzędne, aby dopasować je do widocznego obszaru, i wykonuje działanie w środowisku docelowym za pomocą narzędzi do automatyzacji (takich jak Playwright). Jeśli działanie jest zablokowane, klient powinien wstrzymać wykonanie lub obsłużyć przerwanie.
4. Zapisz stan nowego środowiska
   • Po wykonaniu działania aplikacja robi nowy zrzut ekranu i wysyła go z powrotem do modelu w function_result, aby poprosić o kolejny krok.

Proces ten powtarza się od kroku 2, stale prosząc model o wykonanie kolejnej czynności, dopóki zadanie nie zostanie ukończone lub przerwane.

Jak wdrożyć korzystanie z komputera

Zanim zaczniesz korzystać z narzędzia do używania komputera, musisz skonfigurować:

• Bezpieczne środowisko wykonawcze: uruchamiaj agenta w piaskownicy w maszynie wirtualnej lub kontenerze, aby odizolować go od systemu hosta i ograniczyć jego potencjalny wpływ. Implementacja referencyjna zawiera gotową do użycia piaskownicę opartą na Dockerze, której możesz użyć jako punktu początkowego.
• Obsługa działań po stronie klienta: wdróż logikę po stronie klienta, aby wykonywać działania związane z współrzędnymi, wpisywać tekst i robić zrzuty ekranu.

W przykładach poniżej jako środowiska wykonawczego używamy przeglądarki internetowej, a jako modułu obsługi po stronie klienta – Playwright.

0. Konfigurowanie Playwright

Najpierw zainstaluj wymagane pakiety:

pip install google-genai playwright
playwright install chromium

Następnie zainicjuj instancję przeglądarki Playwright, która będzie używana do wykonywania:

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. Wysyłanie żądania do modelu

Zainicjuj bibliotekę klienta i skonfiguruj narzędzie Computer Use. Pamiętaj, że podczas wysyłania żądania nie musisz określać rozmiaru wyświetlacza. Model przewiduje współrzędne pikseli przeskalowane do wysokości i szerokości ekranu.

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=