Primeiro fluxo de trabalho: navegar e interagir
Nesta página
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
computerda API Responses, um gestor de ações modelado segundo a documentação (ações agrupadas,keypress,scroll_x/scroll_y, trajetórias dedrag) e o encadeamento viaprevious_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_outputcom o mesmocall_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_checkse utilizeheadless=Falsedurante o desenvolvimento run_agent(task, page=page)reutiliza este ciclo para uma página já aberta; é isto que as lições seguintes utilizam