Qwen 3.7 Plus mencetak 79.0 pada ScreenSpot Pro, benchmark untuk melihat tangkapan layar dan mengembalikan koordinat piksel yang tepat untuk diklik. Keterampilan tunggal itulah yang mengubah model obrolan menjadi agen penggunaan komputer: perangkat lunak yang melihat layar, memutuskan apa yang harus dilakukan, dan melakukannya. Panduan ini membangun satu yang berfungsi di Python, dari awal hingga akhir.
Kami akan membahas alur agen, perintah yang menghasilkan tindakan yang andal dari model, contoh browser yang dapat dijalankan dengan Playwright, serta batasan biaya dan keamanan yang Anda butuhkan sebelum mengarahkannya ke hal yang nyata. Jika Anda ingin latar belakang model terlebih dahulu, lihat Ikhtisar Qwen 3.7 Plus kami; untuk format permintaan mentah, panduan API Qwen 3.7 Plus mencakup muatan multimodal. Anda akan menguji panggilan agen di Apidog seiring berjalannya waktu.
TL;DR
Agen penggunaan komputer menjalankan sebuah siklus: mengambil tangkapan layar, mengirimkannya ke Qwen 3.7 Plus dengan sebuah tujuan, mendapatkan kembali tindakan terstruktur seperti click (x, y), mengeksekusi tindakan tersebut dengan driver seperti Playwright, kemudian mengulanginya hingga tujuan tercapai. Plus sangat cocok karena dasar GUI-nya dan harga multimodal yang rendah. Bagian yang sulit bukanlah modelnya; melainkan membatasi siklus, menskalakan koordinat, mengontrol biaya token, dan melakukan sandboxing tindakan sehingga klik yang salah tidak dapat menimbulkan kerusakan.
Apa yang sebenarnya dilakukan oleh agen penggunaan komputer
Singkirkan gembar-gembornya dan ini adalah empat langkah yang diulang:
- Melihat/Mempersepsi: mengambil tangkapan layar dari layar atau halaman saat ini.
- Memutuskan: mengirim tangkapan layar dan tujuan ke model, dan mendapatkan tindakan selanjutnya.
- Bertindak: mengeksekusi tindakan tersebut (klik, ketik, gulir) melalui driver otomatisasi.
- Memeriksa: mengambil tangkapan layar baru dan memutuskan apakah tujuan telah tercapai.
Model adalah langkah "memutuskan". Segala sesuatu yang lain adalah perpipaan yang Anda kendalikan.
Mengapa Qwen 3.7 Plus cocok
Ada tiga alasan. Dasaran GUI-nya berada di tingkat terdepan, sehingga mengembalikan koordinat yang dapat digunakan alih-alih deskripsi yang samar. Ini menangani alur kerja hybrid GUI-dan-CLI, sehingga agen yang sama dapat mengklik tombol dan menjalankan perintah shell. Dan dengan biaya $0.40 per juta token masukan, ini cukup murah untuk menjalankan banyak panggilan visi yang dibutuhkan oleh alur agen. Untuk perbandingannya dengan flagship teks-saja, lihat perbandingan Qwen 3.7 Plus vs Max kami.
Langkah memutuskan: mendapatkan tindakan yang bersih
Triknya adalah membatasi model pada kosakata tindakan yang kecil dan memaksa keluaran JSON. Prosa bebas sulit dieksekusi; skema yang ketat tidak.
import os, json, 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."""
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)
Konfirmasi ID model yang tepat di dokumen Model Studio sebelum menerapkan, karena pengidentifikasi dapat berubah.
Siklus penuh dengan Playwright
Playwright menggerakkan browser nyata, sehingga agen bertindak pada halaman aktual. Satu detail akan menghemat banyak masalah: buat resolusi tangkapan layar cocok dengan viewport, sehingga koordinat yang dikembalikan model bermapping satu-ke-satu dan Anda melewatkan perhitungan penskalaan.
from playwright.sync_api import sync_playwright
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")
goal = "Open the pricing page and find the cheapest plan"
for step in range(15): # hard cap on steps
shot = page.screenshot() # 1280x800 PNG, matches viewport
action = next_action(goal, shot)
print(step, action)
if action["action"] == "done":
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"])
page.wait_for_timeout(800) # let the UI settle
browser.close()
Itu adalah agen sungguhan. Ini akan menavigasi situs menuju tujuan, satu tindakan yang mendasar pada satu waktu. Pola yang sama berlaku untuk aplikasi desktop jika Anda mengganti Playwright dengan driver desktop dan mengambil tangkapan layar jendela OS sebagai gantinya.
Biaya dan keandalan
Tangkapan layar adalah bagian yang mahal. Setiap tangkapan layar dikonversi menjadi token, dan gambar selebar 1280 piksel dapat mencapai beberapa ribu token, sehingga siklus 15 langkah mengirimkan uang sungguhan melalui API. Kurangi biayanya:
- Perkecil dan pangkas. Kirim gambar terkecil yang masih bisa dibaca model. Pangkas ke panel yang relevan bila memungkinkan.
- Batasi siklus. Selalu batasi jumlah langkah, seperti yang dilakukan contoh, agar agen yang bingung tidak dapat berjalan selamanya.
- Verifikasi setelah bertindak. Perlakukan setiap tindakan sebagai hipotesis. Tangkapan layar berikutnya mengonfirmasi apakah itu berhasil, dan siklus mengoreksi diri.
Panduan kami tentang mengurangi biaya token agen membahas lebih dalam, dan catatan kami tentang pengkabelan alur kerja agen mencakup di mana siklus ini gagal dalam praktik.
Saat agen macet
Tiga kegagalan muncul secara terus-menerus, dan masing-masing memiliki perbaikan yang murah:
- Model mengembalikan prosa alih-alih JSON. Minta ulang dengan pengingat singkat "balas hanya dengan JSON" dan coba lagi sekali sebelum menyerah. Skema yang ketat ditambah langkah perbaikan menangani hampir semua kasus ini.
- Klik meleset dari targetnya. Tangkapan layar berikutnya menunjukkan tidak ada perubahan, jadi tambahkan aturan yang mencoba kembali dengan tangkapan layar baru daripada secara membabi buta mengulangi koordinat yang sama.
- Siklus berputar tanpa kemajuan. Lacak beberapa tindakan terakhir; jika berulang, hentikan dan tampilkan tangkapan layar kepada manusia. Batas langkah adalah perlindungan terakhir Anda.
Keamanan
Agen penggunaan komputer benar-benar mengklik berbagai hal. Sebelum menyentuh hal-hal penting:
- Jalankan di lingkungan sandbox atau profil browser sekali pakai, jangan pernah di sesi produksi yang Anda masuki.
- Perlukan konfirmasi manusia untuk tindakan destruktif seperti menghapus, mengirim, atau membayar.
- Catat setiap tindakan dengan tangkapan layarnya sehingga Anda dapat mengaudit apa yang dilakukan agen dan mengapa.
Uji panggilan agen dengan Apidog
Sebagian besar kegagalan agen berawal dari satu pertanyaan: apakah model mengembalikan tindakan yang valid? Sebelum Anda menyambungkan Playwright, pastikan hal itu. Gunakan Apidog untuk mengirim contoh tangkapan layar ke Qwen 3.7 Plus, periksa JSON mentah yang dikembalikannya, dan sesuaikan prompt sistem Anda hingga skema tindakan kembali bersih setiap saat. Simpan kunci Model Studio Anda per lingkungan, dan buat mock endpoint sehingga Anda dapat membangun siklus tanpa membuang token pada setiap pengujian. Ketika siklus penuh merangkai panggilan, debugger agen AI Apidog menunjukkan urutan tersebut sehingga Anda dapat menemukan langkah yang salah.
Untuk menghasilkan kode UI dari desain alih-alih mengoperasikannya, lihat panduan pendamping kami tentang screenshot-to-code dengan Qwen 3.7 Plus.
Unduh Apidog untuk menguji dan men-debug panggilan model di balik agen Anda.
FAQ
Apa itu agen penggunaan komputer? Perangkat lunak yang melihat layar melalui tangkapan layar, memutuskan tindakan dengan model, dan mengeksekusinya melalui driver otomatisasi, berulang hingga tujuan tercapai.
Bisakah Qwen 3.7 Plus mengontrol desktop saya? Model hanya mengembalikan tindakan. Anda mengeksekusinya dengan driver. Pasangkan dengan Playwright untuk browser atau pustaka otomatisasi desktop untuk aplikasi native.
Berapa biaya setiap langkah? Sebagian besar adalah tangkapan layar. Satu gambar layar dapat mencapai beberapa ribu token masukan dengan biaya $0.40 per juta, jadi penskalaan bawah dan pembatasan siklus adalah pengungkit biaya utama.
Apakah cukup andal untuk produksi? Untuk tugas terbatas dan terdefinisi dengan baik dengan verifikasi setelah setiap langkah, ya. Untuk kontrol sistem kritis yang tidak terbatas, libatkan manusia dalam proses dan lakukan sandboxing pada semuanya.
Apakah saya perlu menskalakan koordinat? Tidak, jika resolusi tangkapan layar Anda cocok dengan viewport Anda. Jika berbeda, skalakan koordinat yang dikembalikan dengan rasio di antaranya.
Intinya
Agen penggunaan komputer adalah siklus pendek di sekitar satu model yang mumpuni, dan Qwen 3.7 Plus memberi Anda dasar dan harga untuk menjalankannya. Bangun siklusnya, batasi, sandboxing, dan verifikasi setiap langkah. Kemudian uji panggilan model di Apidog agar langkah "memutuskan" kokoh sebelum agen mulai mengklik.
Tombol