Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Primeiro fluxo de trabalho: navegar e interagir

Aula 4 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Juntar as peças
  2. O gestor de ações
  3. O ciclo completo
  4. Lançar o fluxo de trabalho
  5. Uma função reutilizável para o resto do curso
  6. Três falhas que irá encontrar
  7. Pontos-chave

Lição reescrita a 3 de novembro de 2026 com base no guia Computer use da OpenAI e nas receitas de integração do Computer use: o agente utiliza a ferramenta computer da API Responses, um gestor de ações modelado segundo a documentação (ações agrupadas, keypress, scroll_x/scroll_y, trajetórias de drag) e o encadeamento via previous_response_id, substituindo o código escrito para a API da Anthropic. Fontes: Computer use · Receitas de integração.

Juntar as peças

Já tem o ciclo na mente e o ambiente configurado. Agora, precisa de os reunir num programa funcional: um agente que abre uma enciclopédia online, pesquisa um termo, abre o primeiro resultado e devolve o título da página alcançada. O cenário parece modesto, mas envolve os gestos fundamentais — navegação, digitação, clique, leitura de informação — e tudo o que construir a seguir será apenas uma variação mais longa disto.

O gestor de ações

O modelo decide, mas não executa nada por si próprio: devolve uma lista de ações e o seu código traduz essas ações em gestos do Playwright, pela ordem definida. Esta função segue o gestor publicado pela OpenAI nas suas receitas de integração, simplificado para um navegador.

import time

KEYS = {
    "ENTER": "Enter", "RETURN": "Enter", "ESC": "Escape", "ESCAPE": "Escape",
    "TAB": "Tab", "SPACE": "Space", "BACKSPACE": "Backspace", "DELETE": "Delete",
    "UP": "ArrowUp", "DOWN": "ArrowDown", "LEFT": "ArrowLeft", "RIGHT": "ArrowRight",
    "CTRL": "Control", "CONTROL": "Control", "SHIFT": "Shift", "ALT": "Alt",
    "CMD": "Meta", "META": "Meta",
}
BUTTONS = {"left": "left", "right": "right", "wheel": "middle"}

def execute_actions(page, actions):
    """Executa as ações de um computer_call pela ordem."""
    for action in actions:
        if action.type in ("click", "double_click", "drag", "move", "scroll") and getattr(action, "keys", None):
            raise ValueError("Ação do rato com tecla modificadora: não tratada aqui")
        match action.type:
            case "click":
                button = getattr(action, "button", "left")
                if button not in BUTTONS:  # back e forward não existem no Playwright
                    raise ValueError(f"Botão não suportado: {button}")
                page.mouse.click(action.x, action.y, button=BUTTONS[button])
            case "double_click":
                page.mouse.dblclick(action.x, action.y)
            case "drag":
                points = [(p.x, p.y) for p in action.path]
                page.mouse.move(*points[0])
                page.mouse.down()
                for x, y in points[1:]:
                    page.mouse.move(x, y)
                page.mouse.up()
            case "move":
                page.mouse.move(action.x, action.y)
            case "scroll":
                page.mouse.move(action.x, action.y)
                page.mouse.wheel(action.scroll_x, action.scroll_y)
            case "keypress":
                page.keyboard.press("+".join(KEYS.get(k, k) for k in action.keys))
            case "type":
                page.keyboard.type(action.text)
            case "wait":
                time.sleep(2)
            case "screenshot":
                continue  # a captura de ecrã é feita após cada lote de ações
            case _:
                raise ValueError(f"Ação não suportada: {action.type}")

Duas escolhas merecem explicação. Os nomes das teclas e dos botões devolvidos pelo modelo (ENTER, CTRL, wheel…) não são os que o Playwright espera (Enter, Control, middle…): as tabelas de mapeamento, retiradas da documentação, colmatam essa diferença, e os botões back e forward, que a API também pode solicitar, são rejeitados tal como no gestor da OpenAI. Além disso, uma ação desconhecida gera um erro em vez de ser ignorada silenciosamente: uma paragem brusca é preferível a um agente que pensa ter atuado quando nada fez.

O ciclo completo

O agente orquestra então o ciclo. A primeira chamada envia a tarefa; se contiver apenas um pedido de captura de ecrã, devolve simplesmente o ecrã. Cada captura de ecrã regressa ao modelo como resultado da chamada que a solicitou, referenciada pelo seu call_id, e o previous_response_id liga as sucessivas interações.

import base64

from openai import OpenAI
from playwright.sync_api import sync_playwright

client = OpenAI()
MODEL = "gpt-6.1-sol"
MAX_TURNS = 15

def launch_agent(task: str, start_url: str = "https://en.wikipedia.org"):
    """Lança um agente Computer Use numa tarefa dada."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=False)  # False para observar
    page = browser.new_page(viewport={"width": 1280, "height": 720})
    page.goto(start_url)
    page.wait_for_load_state("networkidle")

    try:
        response = client.responses.create(
            model=MODEL, tools=[{"type": "computer"}], input=task,
        )
        for turn in range(MAX_TURNS):
            call = next((i for i in response.output if i.type == "computer_call"), None)
            if call is None:
                print(f"Tarefa concluída: {response.output_text}")
                return response.output_text

            if call.pending_safety_checks:  # ver lição 12
                raise RuntimeError("Verificações de segurança pendentes: intervenção humana necessária")
            for action in call.actions:
                print(f"  Ação: {action.type}")
            execute_actions(page, call.actions)
            screenshot = base64.b64encode(page.screenshot()).decode("utf-8")

            response = client.responses.create(
                model=MODEL,
                tools=[{"type": "computer"}],
                previous_response_id=response.id,
                input=[{
                    "type": "computer_call_output",
                    "call_id": call.call_id,
                    "output": {
                        "type": "computer_screenshot",
                        "image_url": f"data:image/png;base64,{screenshot}",
                        "detail": "original",
                    },
                }],
            )
        raise RuntimeError("Número máximo de voltas atingido: verifique o estado da página")
    finally:
        browser.close()
        pw.stop()

Três salvaguardas já estão em vigor. MAX_TURNS limita o ciclo: sem este limite, um agente desorientado consumiria o seu orçamento até à exaustão. Uma chamada com verificações de segurança pendentes (pending_safety_checks) interrompe tudo, tal como no exemplo oficial da OpenAI: a lição 12 mostra como fazê-las validar por um humano. E a conclusão normal é assinalada pela ausência de um computer_call: o modelo deixou de atuar e está a responder-lhe, permitindo-lhe recuperar o título da página a partir de output_text.

Lançar o fluxo de trabalho

if __name__ == "__main__":
    launch_agent(
        "Pesquise por 'Computer Use' no motor de busca da Wikipedia, "
        "abra o primeiro resultado e indique-me o título da página. "
        "Utilize a ferramenta computer para atuar na interface."
    )

Com headless=False, o espetáculo é instrutivo: a janela abre, o clique ocorre no campo de pesquisa, o texto aparece, o primeiro link abre-se e o título regressa à sua consola. Observe a execução duas ou três vezes antes de avançar para tarefas mais ambiciosas; verá exatamente onde o agente hesita e o que as suas instruções devem abordar.

Uma função reutilizável para o resto do curso

As lições seguintes trabalham numa página já aberta — após um início de sessão, no meio de um fluxo de trabalho. Recorrem a run_agent(task, page=page): o mesmo ciclo, extraído de launch_agent, com instructions opcionais devolvidas em cada volta (a lição 5 explica porquê).

def run_agent(task: str, page, instructions: str | None = None, max_turns: int = MAX_TURNS) -> str:
    """Ciclo Computer Use numa página já aberta; devolve a mensagem final."""
    request = {"model": MODEL, "tools": [{"type": "computer"}]}
    if instructions:
        request["instructions"] = instructions  # a devolver em cada pedido

    response = client.responses.create(**request, input=task)
    for turn in range(max_turns):
        call = next((i for i in response.output if i.type == "computer_call"), None)
        if call is None:
            return response.output_text
        if call.pending_safety_checks:
            raise RuntimeError("Verificações de segurança pendentes: intervenção humana necessária")

        execute_actions(page, call.actions)
        screenshot = base64.b64encode(page.screenshot()).decode("utf-8")
        response = client.responses.create(
            **request,
            previous_response_id=response.id,
            input=[{
                "type": "computer_call_output",
                "call_id": call.call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot}",
                    "detail": "original",
                },
            }],
        )
    raise RuntimeError("Número máximo de voltas atingido: verifique o estado da página")

Três falhas que irá encontrar

O agente clica sistematicamente ao lado do alvo? O culpado é quase sempre uma discrepância de escala entre a captura de ecrã enviada e a página onde clica: captura redimensionada, zoom do navegador, ecrã de alta densidade. As coordenadas do modelo referem-se à imagem que recebeu; se a reduzir, converta as suas coordenadas na direção oposta.

O agente anda em círculos e repete o mesmo gesto? O limite de voltas acabará por o travar, mas é melhor detetar o ciclo mais cedo: se a mesma captura de ecrã regressar várias vezes seguidas, o agente não está a progredir e interrompê-lo poupa-lhe chamadas desnecessárias.

O agente atua numa página ainda vazia? Num site pesado, page.goto() regressa antes de a renderização terminar e a primeira captura de ecrã mostra apenas um fundo branco. Aguarde a inatividade da rede antes de tirar a fotografia:

page.goto(url)
page.wait_for_load_state("networkidle")

Pontos-chave

  • Um agente Computer Use combina um gestor de ações, um ciclo de controlo e o encadeamento de respostas
  • A primeira chamada envia a tarefa; cada captura de ecrã regressa num computer_call_output com o mesmo call_id
  • O gestor executa as ações pela ordem e rejeita o que não sabe fazer
  • Limite sempre o número de voltas, pare em caso de pending_safety_checks e utilize headless=False durante o desenvolvimento
  • run_agent(task, page=page) reutiliza este ciclo para uma página já aberta; é isto que as lições seguintes utilizam