DEV Community

Cover image for Qwen 3.7 Plus ile Bilgisayar Ajanı Nasıl Yapılır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Qwen 3.7 Plus ile Bilgisayar Ajanı Nasıl Yapılır

Qwen 3.7 Plus, bir ekran görüntüsüne bakıp tıklanacak tam piksel koordinatlarını döndürme kıyaslama testi olan ScreenSpot Pro'da 79.0 puan aldı. Bu özellik, modeli yalnızca sohbet eden bir sistem olmaktan çıkarıp ekranı gören, sonraki adımı seçen ve otomasyon sürücüsüyle uygulayan bir bilgisayar kullanım aracısının karar katmanı haline getirir. Bu yazıda Python, Qwen 3.7 Plus ve Playwright ile çalışan bir tarayıcı aracısı oluşturacağız.

Apidog'u bugün deneyin

Aracı döngüsünü, modelden güvenilir eylemler almak için kullanılacak istemi, Playwright ile tarayıcı otomasyonunu ve gerçek bir sisteme bağlamadan önce eklemeniz gereken maliyet/güvenlik kontrollerini adım adım kuracağız. Modelin arka planı için Qwen 3.7 Plus genel bakışımıza, ham istek formatı için Qwen 3.7 Plus API kılavuzuna bakabilirsiniz. Aracı çağrılarını geliştirirken Apidog ile test edeceğiz.

TL;DR

Bir bilgisayar kullanım aracısı şu döngüyü çalıştırır:

  1. Ekran görüntüsü alır.
  2. Görüntüyü ve hedefi Qwen 3.7 Plus'a gönderir.
  3. Modelden click, type, scroll veya done gibi yapılandırılmış bir eylem alır.
  4. Eylemi Playwright ile uygular.
  5. Yeni ekran görüntüsüyle sonucu doğrular.

Qwen 3.7 Plus, GUI temellendirmesi ve düşük çok modlu maliyeti nedeniyle bu iş için uygundur. Ancak üretimde asıl kritik noktalar model seçimi değil; adım sınırı, koordinat ölçekleme, token maliyeti, JSON doğrulama ve güvenli çalışma alanıdır.

Bilgisayar kullanım aracısı ne yapar?

Abartıyı çıkarırsak bir GUI aracısı dört adımdan oluşur:

  1. Algıla: Mevcut ekranın veya web sayfasının ekran görüntüsünü yakala.
  2. Karar ver: Ekran görüntüsünü ve hedefi modele gönder.
  3. Eyleme geç: Modelin döndürdüğü eylemi otomasyon sürücüsüyle uygula.
  4. Kontrol et: Yeni ekran görüntüsüyle hedefe ulaşılıp ulaşılmadığını doğrula.

Model yalnızca karar katmanıdır. Tarayıcıyı açmak, ekran görüntüsü almak, tıklamak, yazmak, kaydırmak, limitlemek ve loglamak sizin altyapınızın sorumluluğudur.

            <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>


                    <svg xmlns="http://www.w3.org/2000/svg">
                        <path d="M23.14 10.608 2.253.164A1.559 1.559 0 0 0 0 1.557v20.887a1.558 1.558 0 0 0 2.253 1.392L23.14 13.393a1.557 1.557 0 0 0 0-2.785Z"></path>
                    </svg>





                        <svg xmlns="http://www.w3.org/2000/svg">
                            <path d="M23.14 10.608 2.253.164A1.559 1.559 0 0 0 0 1.557v20.887a1.558 1.558 0 0 0 2.253 1.392L23.14 13.393a1.557 1.557 0 0 0 0-2.785Z"></path>
                        </svg>


                        <svg xmlns="http://www.w3.org/2000/svg">
                            <rect width="7" height="22" rx="1.5" ry="1.5"></rect>
                            <rect width="7" height="22" rx="1.5" ry="1.5"></rect>
                        </svg>

                    <span>0:00</span>

                        /<span>1:26</span>


                    1×

                        <svg xmlns="http://www.w3.org/2000/svg">
                            <path d="M15.189 2.021a9.728 9.728 0 0 0-7.924 4.85.249.249 0 0 1-.221.133H5.25a3 3 0 0 0-3 3v2a3 3 0 0 0 3 3h1.794a.249.249 0 0 1 .221.133 9.73 9.73 0 0 0 7.924 4.85h.06a1 1 0 0 0 1-1V3.02a1 1 0 0 0-1.06-.998Z"></path>
                        </svg>


                        <svg xmlns="http://www.w3.org/2000/svg">
                            <path d="M16.177 4.3a.248.248 0 0 0 .073-.176v-1.1a1 1 0 0 0-1.061-1 9.728 9.728 0 0 0-7.924 4.85.249.249 0 0 1-.221.133H5.25a3 3 0 0 0-3 3v2a3 3 0 0 0 3 3h.114a.251.251 0 0 0 .177-.073ZM23.707 1.706A1 1 0 0 0 22.293.292l-22 22a1 1 0 0 0 0 1.414l.009.009a1 1 0 0 0 1.405-.009l6.63-6.631A.251.251 0 0 1 8.515 17a.245.245 0 0 1 .177.075 10.081 10.081 0 0 0 6.5 2.92 1 1 0 0 0 1.061-1V9.266a.247.247 0 0 1 .073-.176Z"></path>
                        </svg>
Enter fullscreen mode Exit fullscreen mode

Qwen 3.7 Plus neden uygun?

Bu kullanım senaryosu için üç pratik avantajı var:

  • GUI temellendirmesi güçlüdür. Ekrandaki öğeleri yorumlayıp koordinat döndürebilir.
  • GUI ve CLI akışlarını birlikte yönetebilir. Aynı aracı hem düğme tıklama hem de komut çalıştırma senaryolarında kullanılabilir.
  • Çok modlu çağrı maliyeti düşüktür. Milyon giriş token'ı başına 0,40 dolar seviyesindeki fiyat, çok adımlı ekran görüntüsü döngülerini daha uygulanabilir hale getirir.

Yalnızca metin amiral gemisiyle farklarını görmek için Qwen 3.7 Plus vs Max karşılaştırmamıza bakabilirsiniz.

1. Karar adımı: modelden temiz JSON eylemi al

Model çıktısını serbest metin bırakmayın. Aracının çalıştırabileceği küçük bir eylem kümesi tanımlayın:

  • click
  • type
  • scroll
  • done

Aşağıdaki fonksiyon ekran görüntüsünü base64 olarak gönderir ve tek bir JSON eylemi bekler.

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 = """You are a GUI agent. You see a screenshot and a goal.
Reply with ONE JSON action and nothing else:
{"action": "click", "x": <int>, "y": <int>}
{"action": "type", "text": "<string>"}
{"action": "scroll", "dy": <int>}
{"action": "done", "reason": "<string>"}
Coordinates are pixels in the screenshot you were given."""
Enter fullscreen mode Exit fullscreen mode 
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}"
                        },
                    },
                ],
            },
        ],
    )

    return json.loads(resp.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Yayına almadan önce model kimliğini Model Studio belgelerinden doğrulayın; tanımlayıcılar zamanla değişebilir.

2. JSON doğrulama ve onarım ekle

Model çıktısı her zaman temiz JSON olmayabilir. Bu yüzden çalıştırmadan önce doğrulayın.

VALID_ACTIONS = {"click", "type", "scroll", "done"}

def validate_action(action):
    if not isinstance(action, dict):
        raise ValueError("Action must be a JSON object")

    if action.get("action") not in VALID_ACTIONS:
        raise ValueError(f"Invalid action: {action}")

    if action["action"] == "click":
        if not isinstance(action.get("x"), int) or not isinstance(action.get("y"), int):
            raise ValueError("Click action requires integer x and y")

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

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

    return action
Enter fullscreen mode Exit fullscreen mode

Basit kullanım:

action = validate_action(next_action(goal, shot))
Enter fullscreen mode Exit fullscreen mode

Eğer JSON parse hatası alırsanız aynı ekran görüntüsüyle tek bir yeniden deneme yapın. Sonsuz yeniden deneme eklemeyin; bu hem maliyet hem de güvenlik riskidir.

3. Playwright ile tarayıcı döngüsünü kur

Playwright gerçek bir tarayıcıyı yönetir. Kritik ayrıntı: ekran görüntüsü çözünürlüğü ile viewport boyutunu aynı tutun. Böylece modelin döndürdüğü koordinatları doğrudan page.mouse.click(x, y) ile kullanabilirsiniz.

from playwright.sync_api import sync_playwright

goal = "Open the pricing page and find the cheapest plan"

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):  # Mutlaka adım sınırı koyun
        shot = page.screenshot()  # 1280x800 PNG
        action = validate_action(next_action(goal, shot))

        print(step, action)

        if action["action"] == "done":
            print("Goal completed:", 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"])

        # UI'ın güncellenmesi için kısa bekleme
        page.wait_for_timeout(800)

    browser.close()
Enter fullscreen mode Exit fullscreen mode

Bu döngü gerçek bir tarayıcı aracısıdır. Sayfayı hedefe doğru adım adım yönlendirir. Aynı desen, Playwright yerine masaüstü otomasyon kütüphanesi kullanarak yerel uygulamalara da uygulanabilir.

4. Koordinat ölçekleme gerekiyorsa ekle

Viewport ile ekran görüntüsü boyutu aynıysa ölçekleme gerekmez. Farklıysa koordinatları oranlayın.

def scale_coordinates(x, y, screenshot_size, viewport_size):
    screenshot_w, screenshot_h = screenshot_size
    viewport_w, viewport_h = viewport_size

    scaled_x = int(x * viewport_w / screenshot_w)
    scaled_y = int(y * viewport_h / screenshot_h)

    return scaled_x, scaled_y
Enter fullscreen mode Exit fullscreen mode

Örnek:

if action["action"] == "click":
    x, y = scale_coordinates(
        action["x"],
        action["y"],
        screenshot_size=(1920, 1200),
        viewport_size=(1280, 800),
    )
    page.mouse.click(x, y)
Enter fullscreen mode Exit fullscreen mode

Mümkünse bunu yapmayın; en kolay çözüm ekran görüntüsü ile viewport'u baştan aynı boyutta tutmaktır.

5. Maliyeti kontrol et

Ekran görüntüleri token'a dönüştürüldüğü için maliyetin ana kaynağıdır. 1280 genişliğinde bir görüntü birkaç bin giriş token'ına denk gelebilir. 15 adımlık bir döngüde bu hızla birikir.

Pratik önlemler:

  • Görüntüyü küçültün. Modelin okuyabileceği en küçük çözünürlüğü kullanın.
  • İlgili alanı kırpın. Tüm sayfa yerine form, modal veya panel gönderin.
  • Adım sınırı koyun. Örnekteki range(15) gibi sabit üst sınır kullanın.
  • Her eylemden sonra doğrulayın. Bir sonraki ekran görüntüsü, eylemin işe yarayıp yaramadığını kontrol eder.
  • Tekrarlayan eylemleri durdurun. Aynı tıklama veya kaydırma tekrar ediyorsa insan müdahalesine geçin.

Daha detaylı maliyet optimizasyonu için aracı token maliyetlerini azaltma rehberimize, aracı bağlantı desenleri için aracı iş akışı bağlantıları notlarımıza bakabilirsiniz.

6. Aracı takıldığında hata ayıkla

En sık görülen üç hata şunlardır:

Model JSON yerine metin döndürür

Çözüm:

  • Çıktıyı parse edin.
  • Hata varsa bir kez yeniden isteyin.
  • İkinci deneme de başarısızsa döngüyü durdurun. 
def safe_next_action(goal, shot):
    for attempt in range(2):
        try:
            return validate_action(next_action(goal, shot))
        except Exception as exc:
            print(f"Action parse failed on attempt {attempt + 1}: {exc}")

    raise RuntimeError("Model did not return a valid action")
Enter fullscreen mode Exit fullscreen mode

Tıklama hedefi ıskalar

Çözüm:

  • Aynı koordinatı körlemesine tekrar etmeyin.
  • Yeni ekran görüntüsü alın.
  • Modelden yeniden karar isteyin.

Döngü ilerlemeden dönmeye devam eder

Çözüm:

  • Son birkaç eylemi saklayın.
  • Aynı eylemler tekrarlanıyorsa durun.
  • Ekran görüntüsünü insana gösterin. 
recent_actions = []

def is_repeating(action):
    recent_actions.append(action)
    recent_actions[:] = recent_actions[-5:]

    if len(recent_actions) < 5:
        return False

    return all(a == recent_actions[0] for a in recent_actions)
Enter fullscreen mode Exit fullscreen mode

Döngü içinde:

if is_repeating(action):
    raise RuntimeError("Agent appears to be stuck")
Enter fullscreen mode Exit fullscreen mode

7. Güvenlik kurallarını baştan ekle

Bilgisayar kullanım aracısı gerçekten tıklar, yazar ve gönderir. Bu yüzden üretim oturumlarında doğrudan çalıştırmayın.

Minimum güvenlik kontrolleri:

  • Tek kullanımlık tarayıcı profili kullanın.
  • Üretim hesabınızla oturum açmayın.
  • Silme, gönderme, ödeme veya veri değiştirme işlemlerinde insan onayı isteyin.
  • Her adımı ekran görüntüsüyle birlikte loglayın.
  • Adım sınırı ve zaman aşımı ekleyin.
  • Testleri sandbox ortamında çalıştırın.

Basit log örneği:

import pathlib
import json

log_dir = pathlib.Path("agent-runs/run-001")
log_dir.mkdir(parents=True, exist_ok=True)

def log_step(step, shot, action):
    (log_dir / f"{step:03d}.png").write_bytes(shot)

    with open(log_dir / f"{step:03d}.json", "w", encoding="utf-8") as f:
        json.dump(action, f, ensure_ascii=False, indent=2)
Enter fullscreen mode Exit fullscreen mode

Döngüde:

shot = page.screenshot()
action = safe_next_action(goal, shot)
log_step(step, shot, action)
Enter fullscreen mode Exit fullscreen mode

Aracının model çağrılarını Apidog ile test edin

Çoğu aracı hatası şu soruya iner: model geçerli bir eylem döndürdü mü?

Playwright döngüsünü kurmadan önce bunu izole edin. Apidog ile Qwen 3.7 Plus'a örnek bir ekran görüntüsü gönderin, dönen ham JSON'u inceleyin ve sistem isteminizi eylem şeması tutarlı dönene kadar ayarlayın.

Pratik test akışı:

  1. Model Studio anahtarınızı ortam değişkeni olarak saklayın.
  2. Apidog'da Qwen 3.7 Plus endpoint'ini tanımlayın.
  3. Örnek ekran görüntüsüyle istek gönderin.
  4. Dönen JSON'u doğrulayın.
  5. click, type, scroll, done dışında çıktı varsa istemi sıkılaştırın.
  6. Döngü çağrılarını zincirlediğinizde Apidog'un yapay zeka aracı hata ayıklayıcısı ile hangi adımın bozulduğunu bulun.

Bir tasarımı yönlendirmek yerine UI kodu üretmek istiyorsanız Qwen 3.7 Plus ile ekran görüntüsünden koda kılavuzuna bakabilirsiniz.

Aracınızın arkasındaki model çağrılarını test etmek ve hata ayıklamak için Apidog'u indirin.

SSS

Bilgisayar kullanım aracısı nedir?

Ekran görüntüsüyle ekranı algılayan, bir modelle sonraki eyleme karar veren ve bu eylemi otomasyon sürücüsüyle uygulayan yazılımdır. Hedef tamamlanana kadar döngü çalıştırır.

Qwen 3.7 Plus masaüstümü doğrudan kontrol eder mi?

Hayır. Model yalnızca eylem önerir. Eylemi Playwright, masaüstü otomasyon kütüphanesi veya başka bir sürücüyle siz uygularsınız.

Her adımın maliyeti neye bağlıdır?

Çoğunlukla ekran görüntüsünün token maliyetine bağlıdır. Görüntü boyutu, adım sayısı ve yeniden denemeler toplam maliyeti belirler.

Üretim için yeterince güvenilir mi?

Sınırlı, iyi tanımlanmış görevlerde ve her adımdan sonra doğrulama yapıldığında kullanılabilir. Kritik sistemlerde insan onayı, sandbox ve ayrıntılı loglama gerekir.

Koordinatları ölçeklendirmem gerekiyor mu?

Ekran görüntüsü çözünürlüğü ile viewport aynıysa gerekmez. Farklıysa koordinatları iki boyut arasındaki oranla ölçeklendirin.

Sonuç

Qwen 3.7 Plus ile bilgisayar kullanım aracısı kurmak için karmaşık bir mimari gerekmez: ekran görüntüsü al, hedefle birlikte modele gönder, JSON eylemi doğrula, Playwright ile uygula ve sonucu tekrar kontrol et.

Üretime yaklaşırken üç şeyi zorunlu tutun:

  • Döngüyü sınırlayın.
  • Her eylemi doğrulayın ve loglayın.
  • Model çağrılarını aracı tıklamaya başlamadan önce Apidog'da test edin.

Top comments (0)