Modelo e ferramenta de utilização do computador

O modelo e a ferramenta de utilização do computador do Gemini 2.5 permitem-lhe ativar as suas aplicações para interagir com tarefas e automatizá-las no navegador. Através de capturas de ecrã, o modelo de utilização do computador pode inferir informações sobre um ecrã do computador e realizar ações gerando ações específicas da IU, como cliques do rato e introduções de teclado. Semelhante à chamada de função, tem de escrever o código da aplicação do lado do cliente para receber o modelo de utilização do computador e a chamada de função da ferramenta, e executar as ações correspondentes.

Com o modelo e a ferramenta de utilização do computador, pode criar agentes que podem:

  • Automatizar a introdução de dados repetitiva ou o preenchimento de formulários em Websites.
  • Navegar em Websites para recolher informações.
  • Ajudar os utilizadores através da realização de sequências de ações em aplicações Web.

Este guia aborda o seguinte:

Este guia pressupõe que está a usar o SDK de IA gen para Python e que tem conhecimentos da API Playwright.

O modelo e a ferramenta de utilização do computador não são suportados nos outros idiomas do SDK nem na consola Google Cloud durante esta pré-visualização.

Além disso, pode ver a implementação de referência para o modelo e a ferramenta de utilização do computador no GitHub.

Como funcionam o modelo e a ferramenta de utilização do computador

Em vez de gerar respostas de texto, o modelo e a ferramenta de utilização do computador determinam quando devem ser tomadas ações específicas da IU, como cliques do rato, e devolvem os parâmetros necessários para executar estas ações. Tem de escrever o código da aplicação do lado do cliente para receber o modelo e a ferramenta de utilização do computador function_call e executar as ações correspondentes.

O modelo de utilização do computador e as interações com ferramentas seguem um processo de ciclo de agente:

  1. Envie um pedido ao modelo

    • Adicione o modelo e a ferramenta de utilização do computador e, opcionalmente, quaisquer ferramentas adicionais ao seu pedido de API.
    • Comande o modelo e a ferramenta de utilização do computador com o pedido do utilizador e uma captura de ecrã que represente o estado atual da GUI.
  2. Receba a resposta do modelo

    • O modelo analisa o pedido do utilizador e a captura de ecrã, e gera uma resposta que inclui um function_call sugerido que representa uma ação da IU (por exemplo, "clicar na coordenada (x,y)" ou "escrever 'texto'"). Consulte as ações suportadas para ver a lista de todas as ações que pode usar com o modelo.
    • A resposta da API também pode incluir um safety_response de um sistema de segurança interno que verificou a ação proposta pelo modelo. Este parâmetro safety_response classifica a ação como:
      • Regular ou permitida: a ação é considerada segura. Isto também pode ser representado pela ausência de safety_response.
      • Requer confirmação: o modelo está prestes a realizar uma ação que pode ser arriscada (por exemplo, clicar num "banner de aceitação de cookies").
  3. Execute a ação recebida

    • O seu código do lado do cliente recebe o function_call e quaisquer safety_response que o acompanhem.
    • Se o safety_response indicar regular ou permitido (ou se não existir nenhum safety_response), o código do lado do cliente pode executar o function_call especificado no ambiente de destino (como um navegador de Internet).
    • Se o safety_response indicar que é necessária confirmação, a sua aplicação tem de pedir confirmação ao utilizador final antes de executar o function_call. Se o utilizador confirmar, avance para a execução da ação. Se o utilizador recusar, não execute a ação.
  4. Capture o novo estado do ambiente

    • Se a ação tiver sido executada, o seu cliente captura uma nova captura de ecrã da GUI e o URL atual para enviar de volta para o modelo e a ferramenta de utilização do computador como parte de um function_response.
    • Se uma ação foi bloqueada pelo sistema de segurança ou a confirmação foi recusada pelo utilizador, a sua aplicação pode enviar uma forma diferente de feedback ao modelo ou terminar a interação.

É enviado um novo pedido ao modelo com o estado atualizado. O processo repete-se a partir do passo 2, com o modelo e a ferramenta de utilização do computador a usar a nova captura de ecrã (se fornecida) e o objetivo contínuo para sugerir a ação seguinte. O ciclo continua até que a tarefa seja concluída, ocorra um erro ou o processo seja terminado (por exemplo, se uma resposta for bloqueada por filtros de segurança ou pela decisão do utilizador).

O diagrama seguinte ilustra o funcionamento do modelo e da ferramenta de utilização do computador:

Vista geral do modelo e da ferramenta de utilização do computador

Ative o modelo e a ferramenta de utilização do computador

Para ativar o modelo e a ferramenta de utilização do computador, use gemini-2.5-computer-use-preview-10-2025 como modelo e adicione o modelo e a ferramenta de utilização do computador à sua lista de ferramentas ativadas:

Python

from google import genai
from google.genai import types
from google.genai.types import Content, Part, FunctionResponse

client = genai.Client()

# Add Computer Use model and tool to the list of tools
generate_content_config = genai.types.GenerateContentConfig(
    tools=[
        types.Tool(
            computer_use=types.ComputerUse(
                environment=types.Environment.ENVIRONMENT_BROWSER,
                )
              ),
            ]
          )

# Example request using the Computer Use model and tool
contents = [
    Content(
        role="user",
        parts=[
            Part(text="Go to google.com and search for 'weather in New York'"),
          ],
        )
      ]

response = client.models.generate_content(
    model="gemini-2.5-computer-use-preview-10-2025",
    contents=contents,
    config=generate_content_config,
  )
      

Envie uma solicitação

Depois de configurar o modelo e a ferramenta de utilização do computador, envie um comando ao modelo que inclua o objetivo do utilizador e uma captura de ecrã inicial da GUI.

Também pode adicionar opcionalmente o seguinte:

  • Ações excluídas: se existirem ações da lista de ações da IU suportadas que não quer que o modelo execute, especifique-as em excluded_predefined_functions.
  • Funções definidas pelo utilizador: além do modelo e da ferramenta de utilização do computador, pode querer incluir funções personalizadas definidas pelo utilizador.

O seguinte exemplo de código ativa o modelo e a ferramenta de utilização do computador e envia o pedido ao modelo:

Python

from google import genai
from google.genai import types
from google.genai.types import Content, Part

client = genai.Client()

# Specify predefined functions to exclude (optional)
excluded_functions = ["drag_and_drop"]

# Configuration for the Computer Use model and tool with browser environment
generate_content_config = genai.types.GenerateContentConfig(
    tools=[
        # 1. Computer Use model and tool with browser environment
        types.Tool(
            computer_use=types.ComputerUse(
                environment=types.Environment.ENVIRONMENT_BROWSER,
                # Optional: Exclude specific predefined functions
                excluded_predefined_functions=excluded_functions
                )
              ),
        # 2. Optional: Custom user-defined functions (need to defined above)
        # types.Tool(
           # function_declarations=custom_functions
           #   )
    ],
)

# Create the content with user message
contents: list[Content] = [
    Content(
        role="user",
        parts=[
            Part(text="Search for highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping. Create a bulleted list of the 3 cheapest options in the format of name, description, price in an easy-to-read layout."),
            # Optional: include a screenshot of the initial state
            # Part.from_bytes(
                 # data=screenshot_image_bytes,
                 # mime_type='image/png',
            # ),
        ],
    )
]

# Generate content with the configured settings
response = client.models.generate_content(
    model='gemini-2.5-computer-use-preview-10-2025',
    contents=contents,
    config=generate_content_config,
)

# Print the response output
print(response.text)
      

Também pode incluir funções personalizadas definidas pelo utilizador para expandir a funcionalidade do modelo. Consulte o artigo Use o modelo e a ferramenta de utilização do computador para exemplos de utilização em dispositivos móveis para ver informações sobre como pode configurar a utilização do computador para exemplos de utilização em dispositivos móveis adicionando ações como open_app, long_press_at e go_home, ao mesmo tempo que exclui ações específicas do navegador.

Receba respostas

O modelo responde com um ou mais FunctionCalls se determinar que são necessárias ações da IU ou funções definidas pelo utilizador para concluir a tarefa. O código da aplicação tem de analisar estas ações, executá-las e recolher os resultados. O modelo e a ferramenta de utilização do computador suportam a chamada de funções paralela, o que significa que o modelo pode devolver várias ações independentes num único turno.

{
  "content": {
    "parts": [
      {
        "text": "I will type the search query into the search bar. The search bar is in the center of the page."
      },
      {
        "function_call": {
          "name": "type_text_at",
          "args": {
            "x": 371,
            "y": 470,
            "text": "highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping",
            "press_enter": true
          }
        }
      }
    ]
  }
}

Consoante a ação, a resposta da API também pode devolver um safety_response:

{
  "content": {
    "parts": [
      {
        "text": "I have evaluated step 2. It seems Google detected unusual traffic and is asking me to verify I'm not a robot. I need to click the 'I'm not a robot' checkbox located near the top left (y=98, x=95)."
      },
      {
        "function_call": {
          "name": "click_at",
          "args": {
            "x": 60,
            "y": 100,
            "safety_decision": {
              "explanation": "I have encountered a CAPTCHA challenge that requires interaction. I need you to complete the challenge by clicking the 'I'm not a robot' checkbox and any subsequent verification steps.",
              "decision": "require_confirmation"
            }
          }
        }
      }
    ]
  }
}

Executar ações recebidas

Depois de receber uma resposta, o modelo tem de executar as ações recebidas.

O código seguinte extrai chamadas de funções de uma resposta do Gemini, converte coordenadas do intervalo de 0 a 1000 em píxeis reais, executa ações do navegador com o Playwright e devolve o estado de êxito ou falha de cada ação:

import time
from typing import Any, List, Tuple


def normalize_x(x: int, screen_width: int) -> int:
    """Convert normalized x coordinate (0-1000) to actual pixel coordinate."""
    return int(x / 1000 * screen_width)


def normalize_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(response, page, screen_width: int, screen_height: int) -> List[Tuple[str, Any]]:
    """
    Extract and execute function calls from Gemini response.

    Args:
        response: Gemini API response object
        page: Playwright page object
        screen_width: Screen width in pixels
        screen_height: Screen height in pixels

    Returns:
        List of tuples: [(function_name, result), ...]
    """
    # Extract function calls and thoughts from the model's response
    candidate = response.candidates[0]
    function_calls = []
    thoughts = []

    for part in candidate.content.parts:
        if hasattr(part, 'function_call') and part.function_call:
            function_calls.append(part.function_call)
        elif hasattr(part, 'text') and part.text:
            thoughts.append(part.text)

    if thoughts:
        print(f"Model Reasoning: {' '.join(thoughts)}")

    # Execute each function call
    results = []
    for function_call in function_calls:
        result = None

        try:
            if function_call.name == "open_web_browser":
                print("Executing open_web_browser")
                # Browser is already open via Playwright, so this is a no-op
                result = "success"

            elif function_call.name == "click_at":
                actual_x = normalize_x(function_call.args["x"], screen_width)
                actual_y = normalize_y(function_call.args["y"], screen_height)

                print(f"Executing click_at: ({actual_x}, {actual_y})")
                page.mouse.click(actual_x, actual_y)
                result = "success"

            elif function_call.name == "type_text_at":
                actual_x = normalize_x(function_call.args["x"], screen_width)
                actual_y = normalize_y(function_call.args["y"], screen_height)
                text = function_call.args["text"]
                press_enter = function_call.args.get("press_enter", False)
                clear_before_typing = function_call.args.get("clear_before_typing", True)

                print(f"Executing type_text_at: ({actual_x}, {actual_y}) text='{text}'")

                # Click at the specified location
                page.mouse.click(actual_x, actual_y)
                time.sleep(0.1)

                # Clear existing text if requested
                if clear_before_typing:
                    page.keyboard.press("Control+A")
                    page.keyboard.press("Backspace")

                # Type the text
                page.keyboard.type(text)

                # Press enter if requested
                if press_enter:
                    page.keyboard.press("Enter")

                result = "success"

            else:
                # For any functions not parsed above
                print(f"Unrecognized function: {function_call.name}")
                result = "unknown_function"

        except Exception as e:
            print(f"Error executing {function_call.name}: {e}")
            result = f"error: {str(e)}"

        results.append((function_call.name, result))

    return results

Se o valor safety_decision devolvido for require_confirmation, tem de pedir ao utilizador que confirme antes de prosseguir com a execução da ação. De acordo com os Termos de Utilização, não tem autorização para ignorar os pedidos de confirmação humana.

O seguinte adiciona lógica de segurança ao código anterior:

import termcolor


def get_safety_confirmation(safety_decision):
    """Prompt user for confirmation when safety check is triggered."""
    termcolor.cprint("Safety service requires explicit confirmation!", color="red")
    print(safety_decision["explanation"])

    decision = ""
    while decision.lower() not in ("y", "n", "ye", "yes", "no"):
        decision = input("Do you wish to proceed? [Y]es/[N]o\n")

    if decision.lower() in ("n", "no"):
        return "TERMINATE"
    return "CONTINUE"


def execute_function_calls(response, page, screen_width: int, screen_height: int):
    # ... Extract function calls from response ...

    for function_call in function_calls:
        extra_fr_fields = {}

        # Check for safety decision
        if 'safety_decision' in function_call.args:
            decision = get_safety_confirmation(function_call.args['safety_decision'])
            if decision == "TERMINATE":
                print("Terminating agent loop")
                break
            extra_fr_fields["safety_acknowledgement"] = "true"

        # ... Execute function call and append to results ...

Capture o novo estado

Após executar as ações, envie o resultado da execução da função de volta para o modelo para que possa usar estas informações para gerar a próxima ação. Se tiverem sido executadas várias ações (chamadas paralelas), tem de enviar um FunctionResponse para cada uma no turno do utilizador subsequente. Para funções definidas pelo utilizador, o elemento FunctionResponse deve conter o valor de devolução da função executada.

function_response_parts = []

for name, result in results:
    # Take screenshot after each action
    screenshot = page.screenshot()
    current_url = page.url

    function_response_parts.append(
        FunctionResponse(
            name=name,
            response={"url": current_url},  # Include safety acknowledgement
            parts=[
                types.FunctionResponsePart(
                    inline_data=types.FunctionResponseBlob(
                       mime_type="image/png", data=screenshot
                    )
                )
            ]
        )
    )

# Create the user feedback content with all responses
user_feedback_content = Content(
    role="user",
    parts=function_response_parts
)

# Append this feedback to the 'contents' history list for the next API call
contents.append(user_feedback_content)

Crie um loop de agente

Combine os passos anteriores num ciclo para ativar interações de vários passos. O ciclo tem de processar chamadas de funções paralelas. Lembre-se de gerir corretamente o histórico de conversas (matriz de conteúdos) anexando as respostas do modelo e as respostas da função.

Python

from google import genai
from google.genai.types import Content, Part
from playwright.sync_api import sync_playwright


def has_function_calls(response):
    """Check if response contains any function calls."""
    candidate = response.candidates[0]
    return any(hasattr(part, 'function_call') and part.function_call
               for part in candidate.content.parts)


def main():
    client = genai.Client()

    # ... (config setup from "Send a request to model" section) ...

    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()
        page.goto("https://www.google.com")
        
        screen_width, screen_height = 1920, 1080
        
        # ... (initial contents setup from "Send a request to model" section) ...

        # Agent loop: iterate until model provides final answer
        for iteration in range(10):
            print(f"\nIteration {iteration + 1}\n")

            # 1. Send request to model (see "Send a request to model" section)
            response = client.models.generate_content(
                model='gemini-2.5-computer-use-preview-10-2025',
                contents=contents,
                config=generate_content_config,
            )

            contents.append(response.candidates[0].content)

            # 2. Check if done - no function calls means final answer
            if not has_function_calls(response):
                print(f"FINAL RESPONSE:\n{response.text}")
                break

            # 3. Execute actions (see "Execute the received actions" section)
            results = execute_function_calls(response, page, screen_width, screen_height)
            time.sleep(1)

            # 4. Capture state and create feedback (see "Capture the New State" section)
            contents.append(create_feedback(results, page))

        input("\nPress Enter to close browser...")
        browser.close()


if __name__ == "__main__":
    main()
      

Modelo e ferramenta de utilização de computadores para casos de utilização de dispositivos móveis

O exemplo seguinte demonstra como definir funções personalizadas (como open_app, long_press_at e go_home), combiná-las com a ferramenta de utilização do computador integrada do Gemini e excluir funções específicas do navegador desnecessárias. Ao registar estas funções personalizadas, o modelo pode chamá-las de forma inteligente juntamente com as ações da IU padrão para concluir tarefas em ambientes que não sejam navegadores.

from typing import Optional, Dict, Any

from google import genai
from google.genai import types
from google.genai.types import Content, Part


client = genai.Client()

def open_app(app_name: str, intent: Optional[str] = None) -> Dict[str, Any]:
    """Opens an app by name.

    Args:
        app_name: Name of the app to open (any string).
        intent: Optional deep-link or action to pass when launching, if the app supports it.

    Returns:
        JSON payload acknowledging the request (app name and optional intent).
    """
    return {"status": "requested_open", "app_name": app_name, "intent": intent}


def long_press_at(x: int, y: int, duration_ms: int = 500) -> Dict[str, int]:
    """Long-press at a specific screen coordinate.

    Args:
        x: X coordinate (absolute), scaled to the device screen width (pixels).
        y: Y coordinate (absolute), scaled to the device screen height (pixels).
        duration_ms: Press duration in milliseconds. Defaults to 500.

    Returns:
        Object with the coordinates pressed and the duration used.
    """
    return {"x": x, "y": y, "duration_ms": duration_ms}


def go_home() -> Dict[str, str]:
    """Navigates to the device home screen.

    Returns:
        A small acknowledgment payload.
    """
    return {"status": "home_requested"}


#  Build function declarations
CUSTOM_FUNCTION_DECLARATIONS = [
    types.FunctionDeclaration.from_callable(client=client, callable=open_app),
    types.FunctionDeclaration.from_callable(client=client, callable=long_press_at),
    types.FunctionDeclaration.from_callable(client=client, callable=go_home),
]

# Exclude browser functions

EXCLUDED_PREDEFINED_FUNCTIONS = [
    "open_web_browser",
    "search",
    "navigate",
    "hover_at",
    "scroll_document",
    "go_forward",
    "key_combination",
    "drag_and_drop",
]

# Utility function to construct a GenerateContentConfig

def make_generate_content_config() -> genai.types.GenerateContentConfig:
    """Return a fixed GenerateContentConfig with Computer Use + custom functions."""
    return genai.types.GenerateContentConfig(
        tools=[
            types.Tool(
                computer_use=types.ComputerUse(
                    environment=types.Environment.ENVIRONMENT_BROWSER,
                    excluded_predefined_functions=EXCLUDED_PREDEFINED_FUNCTIONS,
                )
            ),
            types.Tool(function_declarations=CUSTOM_FUNCTION_DECLARATIONS),
        ]
    )


# Create the content with user message
contents: list[Content] = [
    Content(
        role="user",
        parts=[
            # text instruction
            Part(text="Open Chrome, then long-press at 200,400."),
            # optional screenshot attachment
            Part.from_bytes(
                data=screenshot_image_bytes,
                mime_type="image/png",
            ),
        ],
    )
]

# Build your fixed config (from helper)
config = make_generate_content_config()

# Generate content with the configured settings
response = client.models.generate_content(
        model="gemini-2.5-computer-use-preview-10-2025",
        contents=contents,
        config=generate_content_config,
    )

    print(response)

Ações suportadas

O modelo e a ferramenta de utilização do computador permitem que o modelo peça as seguintes ações através de um FunctionCall. O seu código do lado do cliente tem de implementar a lógica de execução para estas ações. Consulte a implementação de referência para ver exemplos.

Nome do comando Descrição Argumentos (na chamada de função) Exemplo de chamada de função
open_web_browser Abre o navegador de Internet. Nenhum {"name": "open_web_browser", "args": {}}
wait_5_seconds Pausa a execução durante 5 segundos para permitir o carregamento de conteúdo dinâmico ou a conclusão de animações. Nenhum {"name": "wait_5_seconds", "args": {}}
go_back Navega para a página anterior no histórico do navegador. Nenhum {"name": "go_back", "args": {}}
go_forward Navega para a página seguinte no histórico do navegador. Nenhum {"name": "go_forward", "args": {}}
search Navega para a página inicial do motor de pesquisa predefinido (por exemplo, o Google). Útil para iniciar uma nova tarefa de pesquisa. Nenhum {"name": "search", "args": {}}
navegar Navega diretamente no navegador para o URL especificado. url: str {"name": "navigate", "args": {"url": "https://www.wikipedia.org"}}
click_at Cliques numa coordenada específica na página Web. Os valores x e y baseiam-se numa grelha de 1000 x 1000 e são dimensionados para as dimensões do ecrã. y: int (0-999), x: int (0-999) {"name": "click_at", "args": {"y": 300, "x": 500}}
hover_at Passa o cursor do rato numa coordenada específica na página Web. Útil para revelar submenus. x e y baseiam-se numa grelha de 1000 x 1000. y: int (0-999) x: int (0-999) {"name": "hover_at", "args": {"y": 150, "x": 250}}
type_text_at Escreve texto numa coordenada específica. Por predefinição, limpa primeiro o campo e prime ENTER depois de escrever, mas estas ações podem ser desativadas. x e y baseiam-se numa grelha de 1000 x 1000. y: int (0-999), x: int (0-999), text: str, press_enter: bool (Opcional, predefinição True), clear_before_typing: bool (Opcional, predefinição True) {"name": "type_text_at", "args": {"y": 250, "x": 400, "text": "search query", "press_enter": false}}
key_combination Prima teclas ou combinações de teclas do teclado, como "Control+C" ou "Enter". Útil para acionar ações (como enviar um formulário com "Enter") ou operações da área de transferência. keys: str (por exemplo, "enter", "control+c". Consulte a referência da API para ver a lista completa de chaves permitidas) {"name": "key_combination", "args": {"keys": "Control+A"}}
scroll_document Desloca toda a página Web "para cima", "para baixo", "para a esquerda" ou "para a direita". direction: str ("up", "down", "left" ou "right") {"name": "scroll_document", "args": {"direction": "down"}}
scroll_at Desloca um elemento ou uma área específica na coordenada (x, y) na direção especificada por uma determinada magnitude. As coordenadas e a magnitude (predefinição: 800) baseiam-se numa grelha de 1000 x 1000. y: int (0-999), x: int (0-999), direction: str ("up", "down", "left", "right"), magnitude: int (0-999, opcional, predefinição 800) {"name": "scroll_at", "args": {"y": 500, "x": 500, "direction": "down", "magnitude": 400}}
drag_and_drop Arrasta um elemento de uma coordenada inicial (x, y) e deixa-o cair numa coordenada de destino (destination_x, destination_y). Todas as coordenadas baseiam-se numa grelha de 1000 x 1000. y: int (0-999), x: int (0-999), destination_y: int (0-999), destination_x: int (0-999) {"name": "drag_and_drop", "args": {"y": 100, "x": 100, "destination_y": 500, "destination_x": 500}}

Segurança

Esta secção descreve as salvaguardas que o modelo e a ferramenta de utilização do computador têm implementadas para melhorar o controlo do utilizador e a segurança. Também descreve as práticas recomendadas para mitigar potenciais novos riscos que a ferramenta possa apresentar.

Confirme a decisão de segurança

Consoante a ação, a resposta do modelo e da ferramenta de utilização do computador pode incluir um safety_decision de um sistema de segurança interno. Esta decisão valida a ação proposta pela ferramenta para garantir a segurança.

{
  "content": {
    "parts": [
      {
        "text": "I have evaluated step 2. It seems Google detected unusual traffic and is asking me to verify I'm not a robot. I need to click the 'I'm not a robot' checkbox located near the top left (y=98, x=95)."
      },
      {
        "function_call": {
          "name": "click_at",
          "args": {
            "x": 60,
            "y": 100,
            "safety_decision": {
              "explanation": "I have encountered a CAPTCHA challenge that requires interaction. I need you to complete the challenge by clicking the 'I'm not a robot' checkbox and any subsequent verification steps.",
              "decision": "require_confirmation"
            }
          }
        }
      }
    ]
  }
}

Se o valor de safety_decision for require_confirmation, tem de pedir ao utilizador final que confirme antes de continuar com a execução da ação.

O seguinte exemplo de código pede ao utilizador final a confirmação antes de executar a ação. Se o utilizador não confirmar a ação, o ciclo termina. Se o utilizador confirmar a ação, a ação é executada e o campo safety_acknowledgement é marcado como True.

import termcolor

def get_safety_confirmation(safety_decision):
    """Prompt user for confirmation when safety check is triggered."""
    termcolor.cprint("Safety service requires explicit confirmation!", color="red")
    print(safety_decision["explanation"])

    decision = ""
    while decision.lower() not in ("y", "n", "ye", "yes", "no"):
        decision = input("Do you wish to proceed? [Y]es/[N]o\n")

    if decision.lower() in ("n", "no"):
        return "TERMINATE"
    return "CONTINUE"

def execute_function_calls(response, page, screen_width: int, screen_height: int):

    # ... Extract function calls from response ...

    for function_call in function_calls:
        extra_fr_fields = {}

        # Check for safety decision
        if 'safety_decision' in function_call.args:
            decision = get_safety_confirmation(function_call.args['safety_decision'])
            if decision == "TERMINATE":
                print("Terminating agent loop")
                break
            extra_fr_fields["safety_acknowledgement"] = "true" # Safety acknowledgement

        # ... Execute function call and append to results ...

Se o utilizador confirmar, tem de incluir a confirmação de segurança no seu FunctionResponse.

function_response_parts.append(
    FunctionResponse(
        name=name,
        response={"url": current_url,
                  **extra_fr_fields},  # Include safety acknowledgement
        parts=[
            types.FunctionResponsePart(
                inline_data=types.FunctionResponseBlob(
                    mime_type="image/png", data=screenshot
                )
             )
           ]
         )
       )

Práticas recomendadas de segurança

O modelo e a ferramenta de utilização do computador são uma ferramenta inovadora e apresentam novos riscos que os programadores devem ter em atenção:

  • Conteúdo não fidedigno e esquemas: à medida que o modelo tenta alcançar o objetivo do utilizador, pode basear-se em fontes de informações e instruções não fidedignas do ecrã. Por exemplo, se o objetivo do utilizador for comprar um telemóvel Pixel e o modelo encontrar um esquema "Pixel grátis se concluir um inquérito", existe alguma probabilidade de o modelo concluir o inquérito.
  • Ações não intencionais ocasionais: o modelo pode interpretar incorretamente o objetivo de um utilizador ou o conteúdo da página Web, o que faz com que tome ações incorretas, como clicar no botão errado ou preencher o formulário errado. Isto pode levar a tarefas falhadas ou exfiltração de dados.
  • Violações de políticas: as capacidades da API podem ser direcionadas, de forma intencional ou não intencional, para atividades que violem as políticas da Google (Política de Utilização Proibida da IA gen e Termos de Utilização Adicionais da API Gemini). Isto inclui ações que possam interferir com a integridade de um sistema, comprometer a segurança, contornar medidas de segurança, como CAPTCHAs, controlar dispositivos médicos, etc.

Para resolver estes riscos, pode implementar as seguintes medidas de segurança e práticas recomendadas:

  1. Humano no circuito (HITL):
    • Implemente a confirmação do utilizador: quando a resposta de segurança indica require_confirmation, tem de implementar a confirmação do utilizador antes da execução.
    • Forneça instruções de segurança personalizadas: além das verificações de confirmação do utilizador incorporadas, os programadores podem, opcionalmente, adicionar uma instrução do sistema personalizada que aplique as respetivas políticas de segurança, quer para bloquear determinadas ações do modelo, quer para exigir a confirmação do utilizador antes de o modelo realizar determinadas ações irreversíveis de alto risco. Segue-se um exemplo de uma instrução do sistema de segurança personalizada que pode incluir quando interage com o modelo.

    Clique para ver um exemplo de criação de uma associação

    ## **RULE 1: Seek User Confirmation (USER_CONFIRMATION)**
    
    This is your first and most important check. If the next required action falls
    into any of the following categories, you MUST stop immediately, and seek the
    user's explicit permission.
    
    **Procedure for Seeking Confirmation:**  * **For Consequential Actions:**
    Perform all preparatory steps (e.g., navigating, filling out forms, typing a
    message). You will ask for confirmation **AFTER** all necessary information is
    entered on the screen, but **BEFORE** you perform the final, irreversible action
    (e.g., before clicking "Send", "Submit", "Confirm Purchase", "Share").  * **For
    Prohibited Actions:** If the action is strictly forbidden (e.g., accepting legal
    terms, solving a CAPTCHA), you must first inform the user about the required
    action and ask for their confirmation to proceed.
    
    **USER_CONFIRMATION Categories:**
    
    *   **Consent and Agreements:** You are FORBIDDEN from accepting, selecting, or
        agreeing to any of the following on the user's behalf. You must ask th e
        user to confirm before performing these actions.
        *   Terms of Service
        *   Privacy Policies
        *   Cookie consent banners
        *   End User License Agreements (EULAs)
        *   Any other legally significant contracts or agreements.
    *   **Robot Detection:** You MUST NEVER attempt to solve or bypass the
        following. You must ask the user to confirm before performing these actions.
    *   CAPTCHAs (of any kind)
        *   Any other anti-robot or human-verification mechanisms, even if you are
            capable.
    *   **Financial Transactions:**
        *   Completing any purchase.
        *   Managing or moving money (e.g., transfers, payments).
        *   Purchasing regulated goods or participating in gambling.
    *   **Sending Communications:**
        *   Sending emails.
        *   Sending messages on any platform (e.g., social media, chat apps).
        *   Posting content on social media or forums.
    *   **Accessing or Modifying Sensitive Information:**
        *   Health, financial, or government records (e.g., medical history, tax
            forms, passport status).
        *   Revealing or modifying sensitive personal identifiers (e.g., SSN, bank
            account number, credit card number).
    *   **User Data Management:**
        *   Accessing, downloading, or saving files from the web.
        *   Sharing or sending files/data to any third party.
        *   Transferring user data between systems.
    *   **Browser Data Usage:**
        *   Accessing or managing Chrome browsing history, bookmarks, autofill data,
            or saved passwords.
    *   **Security and Identity:**
        *   Logging into any user account.
        *   Any action that involves misrepresentation or impersonation (e.g.,
            creating a fan account, posting as someone else).
    *   **Insurmountable Obstacles:** If you are technically unable to interact with
        a user interface element or are stuck in a loop you cannot resolve, ask the
        user to take over.
    ---
    
    ## **RULE 2: Default Behavior (ACTUATE)**
    
    If an action does **NOT** fall under the conditions for `USER_CONFIRMATION`,
    your default behavior is to **Actuate**.
    
    **Actuation Means:**  You MUST proactively perform all necessary steps to move
    the user's request forward. Continue to actuate until you either complete the
    non-consequential task or encounter a condition defined in Rule 1.
    
    *   **Example 1:** If asked to send money, you will navigate to the payment
        portal, enter the recipient's details, and enter the amount. You will then
        **STOP** as per Rule 1 and ask for confirmation before clicking the final
        "Send" button.
    *   **Example 2:** If asked to post a message, you will navigate to the site,
        open the post composition window, and write the full message. You will then
        **STOP** as per Rule 1 and ask for confirmation before clicking the final
        "Post" button.
    
        After the user has confirmed, remember to get the user's latest screen
        before continuing to perform actions.
    
    # Final Response Guidelines:
    Write final response to the user in these cases:
    - User confirmation
    - When the task is complete or you have enough information to respond to the user
        
  2. Ambiente de execução seguro: execute o seu agente num ambiente seguro e em sandbox para limitar o respetivo impacto potencial (por exemplo, uma máquina virtual (VM) em sandbox, um contentor [como o Docker] ou um perfil do navegador dedicado com autorizações limitadas).
  3. Limpeza de entradas: limpe todo o texto gerado pelo utilizador nos comandos para mitigar o risco de instruções não intencionais ou injeção de comandos. Esta é uma camada de segurança útil, mas não substitui um ambiente de execução seguro.
  4. Listas de autorizações e listas de bloqueios: implemente mecanismos de filtragem para controlar onde o modelo pode navegar e o que pode fazer. Uma lista de bloqueios de Websites proibidos é um bom ponto de partida, enquanto uma lista de autorizações mais restritiva é ainda mais segura.
  5. Observabilidade e registo: mantenha registos detalhados para depuração, auditoria e resposta a incidentes. O seu cliente deve registar comandos, capturas de ecrã, ações sugeridas pelo modelo (function_call), respostas de segurança e todas as ações executadas pelo cliente.

Preços

O modelo e a ferramenta de utilização do computador têm os mesmos preços que o Gemini 2.5 Pro e usam os mesmos SKUs. Para dividir os custos do modelo de utilização de computadores e das ferramentas, use etiquetas de metadados personalizados. Para mais informações sobre a utilização de etiquetas de metadados personalizados para a monitorização de custos, consulte o artigo Etiquetas de metadados personalizados.