Como construir um agente de IA para automação de computador com Qwen 3.7 Plus

Qwen 3.7 Plus pontua 79.0 no ScreenSpot Pro, benchmark que avalia a capacidade de analisar uma captura de tela e retornar coordenadas exatas em pixels para clicar. Essa habilidade permite transformar um modelo de chat em um agente de uso de computador: um loop que vê a tela, decide a próxima ação e executa essa ação com automação.

Experimente o Apidog hoje

Neste guia, você vai implementar esse loop em Python usando Qwen 3.7 Plus e Playwright. O fluxo cobre prompt, saída JSON, execução de ações, limites de custo, segurança e depuração. Se quiser revisar o contexto do modelo, veja a visão geral do Qwen 3.7 Plus. Para payloads multimodais, consulte o guia da API do Qwen 3.7 Plus. Você também pode testar as chamadas do agente no Apidog durante a implementação.

TL;DR

Um agente de uso de computador executa um ciclo simples:

1. Captura a tela.
2. Envia a imagem e o objetivo para o Qwen 3.7 Plus.
3. Recebe uma ação estruturada, como click(x, y).
4. Executa a ação com Playwright ou outro driver.
5. Repete até concluir o objetivo ou atingir um limite.

O Qwen 3.7 Plus é adequado para esse fluxo por causa da fundamentação em GUI e do custo multimodal baixo. A parte crítica da implementação não é apenas chamar o modelo, mas controlar o loop: limitar etapas, mapear coordenadas corretamente, reduzir tokens e isolar ações perigosas.

O que um agente de uso de computador faz

Na prática, o agente é um loop com quatro fases:

1. Perceber: capturar a tela ou a página atual.
2. Decidir: enviar a captura e o objetivo ao modelo.
3. Agir: executar a ação retornada.
4. Verificar: capturar a tela novamente e validar o progresso.

O modelo faz a decisão. O restante é infraestrutura: captura, automação, validação, limites e logs.

<video src="https://assets.apidog.com/blog-next/2026/06/V1tXD8Bnm5DAtobB.mp4" poster="https://img.spacergif.org/v1/1920x1080/0a/spacer.png" width="1920" height="1080" loop="" autoplay="" muted="" playsinline="" preload="metadata"></video>

Por que usar Qwen 3.7 Plus nesse fluxo

O Qwen 3.7 Plus se encaixa bem em agentes de GUI por três motivos:

• Fundamentação visual em GUI: o modelo consegue retornar coordenadas utilizáveis em vez de apenas descrever a tela.
• Fluxos híbridos GUI e CLI: o mesmo agente pode clicar em uma interface e também orientar comandos quando necessário.
• Custo multimodal baixo: a US$ 0,40 por milhão de tokens de entrada, fica viável executar várias chamadas de visão em um loop.

Para uma comparação com o modelo principal somente de texto, veja Qwen 3.7 Plus vs Max.

Etapa 1: defina um esquema de ação

Não deixe o modelo responder com texto livre. Para automação, você precisa de uma saída previsível.

Use um vocabulário pequeno:

{"action": "click", "x": 100, "y": 200}
{"action": "type", "text": "texto"}
{"action": "scroll", "dy": 500}
{"action": "done", "reason": "objetivo concluído"}

Isso facilita validação, execução e retry.

Etapa 2: implemente a chamada ao Qwen 3.7 Plus

O exemplo abaixo envia uma captura de tela como imagem base64 e pede ao modelo uma única ação JSON.

import os
import json
import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

SYSTEM = """Você é um agente de GUI. Você vê uma captura de tela e um objetivo.

Responda com UMA ação JSON e nada mais.

Formatos permitidos:
{"action": "click", "x": <int>, "y": <int>}
{"action": "type", "text": "<string>"}
{"action": "scroll", "dy": <int>}
{"action": "done", "reason": "<string>"}

As coordenadas são pixels na captura de tela recebida.
"""

def next_action(goal, png_bytes):
    b64 = base64.b64encode(png_bytes).decode()

    resp = client.chat.completions.create(
        model="qwen3.7-plus",
        messages=[
            {
                "role": "system",
                "content": SYSTEM,
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": f"Goal: {goal}",
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": f"data:image/png;base64,{b64}"
                        },
                    },
                ],
            },
        ],
    )

    content = resp.choices[0].message.content
    return json.loads(content)

Antes de implantar, confirme o ID exato do modelo na documentação do Model Studio, pois identificadores podem mudar.

Etapa 3: conecte o modelo ao Playwright

O Playwright controla um navegador real. Para evitar problemas de escala, configure a viewport com a mesma resolução usada na captura de tela. Assim, as coordenadas retornadas pelo modelo mapeiam diretamente para a página.

from playwright.sync_api import sync_playwright

goal = "Abra a página de preços e encontre o plano mais barato"

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)

    page = browser.new_page(
        viewport={
            "width": 1280,
            "height": 800,
        }
    )

    page.goto("https://example.com")

    for step in range(15):  # limite rígido de etapas
        shot = page.screenshot()  # PNG 1280x800
        action = next_action(goal, shot)

        print(step, action)

        if action["action"] == "done":
            print("Concluído:", action.get("reason"))
            break

        if action["action"] == "click":
            page.mouse.click(action["x"], action["y"])

        elif action["action"] == "type":
            page.keyboard.type(action["text"])

        elif action["action"] == "scroll":
            page.mouse.wheel(0, action["dy"])

        else:
            raise ValueError(f"Ação desconhecida: {action}")

        page.wait_for_timeout(800)  # aguarde a UI estabilizar

    browser.close()

Esse é o agente mínimo funcional: ele captura, decide, age e verifica. O mesmo padrão pode ser aplicado a aplicativos desktop se você substituir o Playwright por um driver de automação de desktop e capturar a janela do sistema operacional.

Etapa 4: valide a resposta antes de executar

Nunca execute a saída do modelo sem validação. Adicione uma camada simples de segurança:

def validate_action(action, width=1280, height=800):
    allowed = {"click", "type", "scroll", "done"}

    if not isinstance(action, dict):
        raise ValueError("A ação precisa ser um objeto JSON")

    if action.get("action") not in allowed:
        raise ValueError(f"Ação inválida: {action}")

    if action["action"] == "click":
        x = action.get("x")
        y = action.get("y")

        if not isinstance(x, int) or not isinstance(y, int):
            raise ValueError("Click precisa de x e y inteiros")

        if not (0 <= x <= width and 0 <= y <= height):
            raise ValueError("Coordenadas fora da viewport")

    if action["action"] == "type":
        if not isinstance(action.get("text"), str):
            raise ValueError("Type precisa de text string")

    if action["action"] == "scroll":
        if not isinstance(action.get("dy"), int):
            raise ValueError("Scroll precisa de dy inteiro")

    return action

Use no loop:

action = validate_action(next_action(goal, shot))

Custo e confiabilidade

Capturas de tela são a parte mais cara do loop. Cada imagem é convertida em tokens, e uma tela de 1280 pixels de largura pode consumir alguns milhares de tokens. Um loop de 15 etapas faz várias chamadas multimodais.

Para controlar custo e confiabilidade:

• Reduza a imagem: envie a menor captura que ainda seja legível.
• Recorte regiões relevantes: se o objetivo está em um painel, não envie a tela inteira.
• Limite o número de etapas: use for step in range(15) ou menor.
• Aguarde a interface estabilizar: use pequenos delays após cliques e rolagens.
• Verifique depois de agir: a próxima captura confirma se a ação funcionou.
• Pare em repetição: se o agente repetir a mesma ação várias vezes, interrompa.

Para mais detalhes, veja o guia sobre redução de custos de tokens de agente e as notas sobre padrões e armadilhas de fiação de fluxo de trabalho de agente.

Como lidar com falhas comuns

1. O modelo retorna prosa em vez de JSON

Faça uma tentativa de reparo com um prompt curto:

def repair_json(raw_text):
    resp = client.chat.completions.create(
        model="qwen3.7-plus",
        messages=[
            {
                "role": "system",
                "content": "Converta a resposta em uma única ação JSON válida. Não adicione explicações.",
            },
            {
                "role": "user",
                "content": raw_text,
            },
        ],
    )

    return json.loads(resp.choices[0].message.content)

Use apenas uma tentativa de reparo. Se ainda falhar, pare o loop.

2. O clique não muda nada

A próxima captura de tela deve mostrar se houve progresso. Se não houver mudança, não repita cegamente as mesmas coordenadas. Capture novamente e peça uma nova decisão ao modelo.

3. O agente entra em loop

Rastreie as últimas ações:

recent_actions = []

def is_repeating(action):
    recent_actions.append(action)

    if len(recent_actions) > 5:
        recent_actions.pop(0)

    return len(recent_actions) == 5 and all(a == recent_actions[0] for a in recent_actions)

No loop:

if is_repeating(action):
    print("Loop detectado. Encerrando para revisão humana.")
    break

Segurança

Um agente de uso de computador clica em elementos reais. Antes de apontá-lo para qualquer sistema importante:

• Execute em sandbox ou em um perfil de navegador descartável.
• Não use sua sessão de produção logada.
• Exija confirmação humana para ações destrutivas, como excluir, enviar, comprar ou pagar.
• Registre cada ação com a captura de tela correspondente.
• Defina domínios permitidos quando possível.
• Pare o loop ao detectar repetição, erro de JSON ou ação fora da viewport.

Um exemplo simples de confirmação para ações sensíveis:

SENSITIVE_WORDS = ["delete", "excluir", "pay", "pagar", "submit", "enviar"]

def requires_human_confirmation(goal, action):
    text = json.dumps(action).lower() + " " + goal.lower()
    return any(word in text for word in SENSITIVE_WORDS)

Teste as chamadas do agente com Apidog

A pergunta principal ao depurar esse tipo de agente é: o modelo retornou uma ação válida?

Antes de conectar o Playwright, use o Apidog para:

1. Enviar uma captura de tela de exemplo ao Qwen 3.7 Plus.
2. Inspecionar o JSON bruto retornado.
3. Ajustar o prompt de sistema.
4. Validar se o esquema volta limpo.
5. Simular endpoints para testar o loop sem gastar tokens em toda execução.
6. Separar chaves do Model Studio por ambiente.

Quando o loop completo estiver encadeando várias chamadas, o depurador de agente de IA do Apidog ajuda a visualizar a sequência e encontrar a etapa que falhou.

Para gerar código de interface a partir de um design, em vez de controlar a interface existente, veja o guia complementar sobre captura de tela para código com Qwen 3.7 Plus.

Baixe o Apidog para testar e depurar as chamadas do modelo por trás do seu agente.

FAQ

O que é um agente de uso de computador?

É um software que captura a tela, envia a imagem para um modelo, recebe uma ação e executa essa ação com um driver de automação. O processo se repete até atingir um objetivo.

O Qwen 3.7 Plus controla meu desktop diretamente?

Não. O modelo retorna ações. Você executa essas ações com Playwright, para navegadores, ou com uma biblioteca de automação de desktop, para aplicativos nativos.

Quanto custa cada etapa?

O custo vem principalmente da captura de tela. Uma imagem pode consumir alguns milhares de tokens de entrada a US$ 0,40 por milhão. Reduzir a imagem, recortar regiões e limitar o loop são as principais formas de controle.

É confiável para produção?

Pode ser confiável para tarefas delimitadas, com verificação após cada etapa e limites claros. Para sistemas críticos ou ações destrutivas, mantenha um humano no circuito e execute tudo em sandbox.

Preciso escalar coordenadas?

Não, se a resolução da captura de tela for igual à viewport. Se forem diferentes, escale as coordenadas pela proporção entre a imagem enviada ao modelo e a tela real.

Resultado final

Um agente de uso de computador é um loop curto em torno de um modelo multimodal capaz. Com Qwen 3.7 Plus, você pode capturar a tela, obter uma ação fundamentada em coordenadas, executar essa ação com Playwright e repetir com verificação.

Para implementar com segurança:

1. Force saída JSON.
2. Valide cada ação.
3. Mantenha a captura e a viewport na mesma resolução.
4. Limite o número de etapas.
5. Registre tudo.
6. Use sandbox.
7. Teste as chamadas no Apidog antes de deixar o agente clicar.