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

Configurar o Computer Use na API

Aula 3 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Pré-requisitos
  2. Instalação das dependências
  3. Definir a chave da API
  4. Declarar a ferramenta computer
  5. Configurar o navegador
  6. Organizar o projeto
  7. Verificar a instalação
  8. Pontos-chave

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 ambiente OPENAI_API_KEY e a ferramenta {"type": "computer"} na API de Respostas. Já não depende do SDK da Anthropic nem da ferramenta legada computer_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, playwright e pillow num ambiente virtual dedicado e, em seguida, execute playwright install chromium
  • Mantenha a OPENAI_API_KEY numa variável de ambiente, nunca no código
  • Declare a ferramenta com tools=[{"type": "computer"}] utilizando um modelo suportado (os exemplos da OpenAI usam gpt-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