Configurar o Computer Use na API
Nesta página
Lição reescrita em 3 de novembro de 2026 com base no guia Computer use da OpenAI e nas receitas de integração do Computer use: a configuração utiliza agora o SDK
openai, a variável de ambienteOPENAI_API_KEYe a ferramenta{"type": "computer"}na API de Respostas. Já não depende do SDK da Anthropic nem da ferramenta legadacomputer_20241022. A ferramenta da OpenAI não requer dimensões de ecrã; as coordenadas referem-se à captura de ecrã que fornecer. Fontes: Computer use · Receitas de integração.
Pré-requisitos
Antes de escrever uma única linha de código, a sua estação de trabalho precisa de quatro elementos: uma versão recente do Python 3, uma conta OpenAI com uma chave de API ativa e acesso a um modelo que suporte a ferramenta computer, um navegador Chromium controlado pelo Playwright para interações web e Docker se planeiar isolar o agente. O Docker é opcional enquanto está a aprender, mas a OpenAI recomenda um navegador isolado ou uma máquina virtual assim que o agente interagir com algo além de um site de demonstração.
Para o modelo, a documentação da OpenAI utiliza gpt-6.1-sol nos seus exemplos da ferramenta computer. Consulte o cartão do modelo (sob Tools) para confirmar que o uso do computador está listado e que o seu projeto tem acesso.
Instalação das dependências
Trabalhe num ambiente virtual dedicado. Um agente de Computer Use fixa versões específicas do Playwright e dos seus navegadores. Misturar estas versões com os seus outros projetos Python levará a conflitos difíceis de diagnosticar.
# Criar e ativar o ambiente
python -m venv computer-use-env
source computer-use-env/bin/activate # Linux/Mac
# computer-use-env\Scripts\activate # Windows
# Instalar dependências
pip install openai playwright pillow
# Instalar o navegador Playwright
playwright install chromium
Cada pacote desempenha um papel distinto: openai fornece o cliente que comunica com o modelo, playwright controla o navegador e executa ações, e pillow gere a manipulação de imagens quando necessário. O último comando é aquele que as pessoas esquecem com mais frequência. Sem playwright install chromium, o pacote é instalado, mas nenhum navegador é descarregado, fazendo com que a primeira execução falhe.
Definir a chave da API
Guarde a sua chave numa variável de ambiente, nunca codificada diretamente num script. Um segredo escrito no código acaba inevitavelmente num repositório Git.
export OPENAI_API_KEY="your-key"
Em produção, utilize um gestor de segredos. O cliente lê a variável automaticamente:
from openai import OpenAI
client = OpenAI() # lê OPENAI_API_KEY
Declarar a ferramenta computer
Um modelo não controla um ecrã por predefinição. Deve ativar a ferramenta computer no pedido e descrever o resultado esperado.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6.1-sol",
tools=[{"type": "computer"}],
input=(
"Verifique se o painel de Filtros está aberto. Se não, "
"clique em Mostrar Filtros e, em seguida, escreva penguin no campo "
"de pesquisa. Utilize a ferramenta computer para interagir com a interface."
),
)
print(response.output)
A declaração é simplesmente {"type": "computer"}. Ao contrário da versão de pré-visualização inicial (computer_use_preview), não requer nem dimensões de ecrã nem um tipo de ambiente, e o truncamento automático já não é necessário. As coordenadas que o modelo devolve referem-se à captura de ecrã que envia. Capture exatamente a área onde pretende clicar, na mesma escala. Se redimensionar uma captura de ecrã antes de a enviar, converta as coordenadas de volta antes de atuar.
Configurar o navegador
Do lado do Playwright, envolva a lógica de inicialização numa função que possa reutilizar em várias tarefas.
from playwright.sync_api import sync_playwright
def launch_browser(width=1280, height=720):
"""Inicia um navegador isolado para o Computer Use."""
pw = sync_playwright().start()
browser = pw.chromium.launch(headless=True) # False para observar o agente
context = browser.new_context(viewport={"width": width, "height": height})
page = context.new_page()
return pw, browser, page
page.screenshot() captura a área visível (viewport), pelo que as coordenadas do modelo se aplicam diretamente a page.mouse. A opção headless=True executa o navegador sem interface gráfica, o que é essencial num servidor. Durante o desenvolvimento, defina isto como False para observar o agente a trabalhar. É a forma mais rápida de compreender por que razão comete erros.
Organizar o projeto
Separe desde o início a lógica do navegador, o ciclo do agente e a execução de ações.
computer-use-project/
├── .env # OPENAI_API_KEY (nunca faça commit)
├── requirements.txt # openai, playwright, pillow
├── src/
│ ├── __init__.py
│ ├── browser.py # Inicializar e capturar
│ ├── agent.py # Ciclo do Computer Use
│ └── actions.py # Execução de ações
└── tasks/
└── example.py # Scripts de tarefas
Verificar a instalação
Não construa um fluxo de trabalho complexo sobre uma configuração não validada. Se a primeira execução falhar, não saberá se o problema reside na chave, no navegador ou no seu prompt. Este script mínimo testa toda a cadeia: cliente, navegador, captura e transmissão da imagem para o modelo.
import base64
from openai import OpenAI
from playwright.sync_api import sync_playwright
def test_installation():
"""Verifica se a chave, o navegador e o carregamento de imagens funcionam."""
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": "Descreva o que vê."},
{"type": "input_image", "image_url": f"data:image/png;base64,{capture}"},
],
}],
)
print("Resposta:", response.output_text)
browser.close()
pw.stop()
if __name__ == "__main__":
test_installation()
Se a consola apresentar uma descrição da página example.com, a sua configuração está pronta e pode prosseguir para a construção de um agente completo.
Pontos-chave
- Instale
openai,playwrightepillownum ambiente virtual dedicado e, em seguida, executeplaywright install chromium - Mantenha a
OPENAI_API_KEYnuma variável de ambiente, nunca no código - Declare a ferramenta com
tools=[{"type": "computer"}]utilizando um modelo suportado (os exemplos da OpenAI usamgpt-6.1-sol) - As coordenadas do modelo referem-se à captura de ecrã enviada: capture a área onde atua na mesma escala
- Teste sempre com um script mínimo antes de construir fluxos de trabalho complexos