DEV Community

Cover image for Hướng dẫn xây dựng Agent điều khiển máy tính với Qwen 3.7 Plus
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng dẫn xây dựng Agent điều khiển máy tính với Qwen 3.7 Plus

Qwen 3.7 Plus đạt 79.0 điểm trên ScreenSpot Pro, một benchmark đánh giá khả năng đọc ảnh chụp màn hình và trả về tọa độ pixel chính xác để nhấp. Khả năng này là nền tảng để biến một mô hình trò chuyện thành tác nhân sử dụng máy tính: tác nhân nhìn màn hình, quyết định bước tiếp theo và thực thi hành động. Bài viết này hướng dẫn cách xây dựng một tác nhân hoạt động được bằng Python.

Dùng thử Apidog ngay hôm nay

Bạn sẽ triển khai vòng lặp tác nhân gồm: chụp ảnh màn hình, gửi mục tiêu và ảnh đến Qwen 3.7 Plus, nhận hành động dạng JSON, thực thi bằng Playwright, rồi lặp lại cho đến khi hoàn thành. Nếu cần nền tảng về mô hình, xem Tổng quan về Qwen 3.7 Plus. Nếu cần định dạng request thô, xem hướng dẫn API Qwen 3.7 Plus. Trong quá trình triển khai, bạn có thể kiểm tra request/response bằng Apidog.

Tóm tắt

Một tác nhân sử dụng máy tính chạy theo vòng lặp:

  1. Chụp ảnh màn hình.
  2. Gửi ảnh và mục tiêu đến Qwen 3.7 Plus.
  3. Nhận hành động có cấu trúc, ví dụ click(x, y).
  4. Thực thi bằng trình điều khiển như Playwright.
  5. Chụp lại màn hình và kiểm tra tiến độ.

Qwen 3.7 Plus phù hợp vì có khả năng định vị GUI tốt và chi phí đa phương thức thấp. Phần khó nằm ở phần kỹ thuật xung quanh mô hình: giới hạn số bước, ánh xạ tọa độ, kiểm soát token, xác thực JSON và chặn các hành động nguy hiểm.

Tác nhân sử dụng máy tính thực sự làm gì?

Về triển khai, tác nhân chỉ cần bốn bước lặp lại:

  1. Nhận diện: chụp ảnh màn hình hoặc trạng thái trang hiện tại.
  2. Quyết định: gửi ảnh và mục tiêu đến mô hình để lấy hành động tiếp theo.
  3. Thực hiện: nhấp, gõ hoặc cuộn bằng công cụ tự động hóa.
  4. Kiểm tra: chụp ảnh mới để xác nhận tác vụ đã hoàn thành hay chưa.

Mô hình chỉ đảm nhiệm bước “quyết định”. Phần còn lại là logic ứng dụng mà bạn phải kiểm soát.

    <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>
Enter fullscreen mode Exit fullscreen mode

Tại sao Qwen 3.7 Plus phù hợp?

Qwen 3.7 Plus hữu ích cho tác nhân GUI vì ba lý do:

  • Định vị giao diện tốt: mô hình có thể trả về tọa độ pixel thay vì chỉ mô tả bằng văn bản.
  • Hỗ trợ workflow GUI + CLI: cùng một tác nhân có thể vừa nhấp nút vừa chạy lệnh shell nếu bạn cung cấp driver phù hợp.
  • Chi phí đầu vào thấp: với mức 0.40 USD cho mỗi triệu token đầu vào, việc gọi nhiều lần trong vòng lặp tác nhân khả thi hơn về chi phí.

Để xem so sánh với phiên bản chỉ văn bản hàng đầu, đọc thêm so sánh Qwen 3.7 Plus và Max.

Qwen 3.7 Plus

Bước quyết định: ép mô hình trả về hành động rõ ràng

Không nên để mô hình trả lời bằng văn xuôi tự do. Hãy giới hạn đầu ra vào một tập hành động nhỏ và yêu cầu JSON.

Ví dụ schema hành động:

{"action": "click", "x": 120, "y": 340}
{"action": "type", "text": "hello"}
{"action": "scroll", "dy": 500}
{"action": "done", "reason": "Goal completed"}
Enter fullscreen mode Exit fullscreen mode

Ví dụ gọi Qwen 3.7 Plus bằng Python:

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

Hàm lấy hành động tiếp theo:

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

Trước khi triển khai, hãy xác nhận ID mô hình trong tài liệu Model Studio, vì định danh mô hình có thể thay đổi.

Vòng lặp hoàn chỉnh với Playwright

Playwright điều khiển trình duyệt thật, nên tác nhân có thể thao tác trên trang web thực tế.

Điểm quan trọng: đặt kích thước viewport trùng với kích thước ảnh chụp màn hình. Khi đó tọa độ mô hình trả về có thể dùng trực tiếp, không cần scale.

Cài Playwright:

pip install playwright openai
playwright install chromium
Enter fullscreen mode Exit fullscreen mode

Vòng lặp tác nhân tối thiểu:

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):  # giới hạn cứng số bước
        shot = page.screenshot()  # PNG 1280x800, khớp viewport
        action = next_action(goal, shot)

        print(step, action)

        if action["action"] == "done":
            print("Done:", 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"Unsupported action: {action}")

        page.wait_for_timeout(800)  # đợi UI cập nhật

    browser.close()
Enter fullscreen mode Exit fullscreen mode

Đây là một tác nhân hoạt động được: nó nhìn trang, chọn hành động, thực thi và tự kiểm tra sau mỗi bước.

Nếu muốn điều khiển ứng dụng desktop, bạn có thể giữ nguyên vòng lặp này nhưng thay Playwright bằng driver desktop và thay page.screenshot() bằng ảnh chụp cửa sổ hệ điều hành.

Thêm lớp kiểm tra JSON

Trong thực tế, mô hình đôi khi trả về JSON không hợp lệ hoặc thêm văn bản ngoài JSON. Đừng đưa trực tiếp kết quả đó vào driver. Hãy validate trước.

Ví dụ đơn giản:

ALLOWED_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 ALLOWED_ACTIONS:
        raise ValueError(f"Invalid action: {action}")

    if action["action"] == "click":
        if not isinstance(action.get("x"), int):
            raise ValueError("click.x must be int")
        if not isinstance(action.get("y"), int):
            raise ValueError("click.y must be int")

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

    if action["action"] == "scroll":
        if not isinstance(action.get("dy"), int):
            raise ValueError("scroll.dy must be int")

    return action
Enter fullscreen mode Exit fullscreen mode

Dùng trong vòng lặp:

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

Chi phí và độ tin cậy

Ảnh chụp màn hình là phần tốn kém nhất. Mỗi ảnh được chuyển thành token. Một ảnh rộng 1280 pixel có thể tiêu tốn vài nghìn token, và vòng lặp 15 bước sẽ tạo ra chi phí API thực tế.

Để kiểm soát chi phí:

  • Giảm kích thước ảnh: gửi ảnh nhỏ nhất mà mô hình vẫn đọc được.
  • Cắt vùng liên quan: nếu tác vụ chỉ nằm trong một panel, chỉ gửi panel đó.
  • Giới hạn số bước: luôn có for step in range(...).
  • Dừng khi lặp hành động: nếu tác nhân nhấp cùng một tọa độ nhiều lần, hãy dừng.
  • Xác minh sau mỗi hành động: ảnh chụp tiếp theo phải cho thấy tiến triển.

Đọc thêm hướng dẫn giảm chi phí token tác nhân và các lưu ý về kết nối quy trình làm việc của tác nhân.

Khi tác nhân bị kẹt

Ba lỗi thường gặp:

1. Mô hình trả về văn xuôi thay vì JSON

Cách xử lý:

  • Nhắc lại một lần với prompt ngắn hơn.
  • Yêu cầu “JSON only”.
  • Nếu vẫn lỗi, dừng vòng lặp.

Ví dụ:

try:
    action = validate_action(next_action(goal, shot))
except Exception:
    # retry một lần với cùng screenshot
    action = validate_action(next_action(goal + "\nReply JSON only.", shot))
Enter fullscreen mode Exit fullscreen mode

2. Cú nhấp không trúng mục tiêu

Đừng lặp lại cùng tọa độ mù quáng. Hãy chụp ảnh mới và hỏi lại mô hình.

previous_action = None

# sau khi nhận action
if action == previous_action:
    print("Repeated action detected. Stopping.")
    break

previous_action = action
Enter fullscreen mode Exit fullscreen mode

3. Vòng lặp không có tiến triển

Theo dõi vài hành động gần nhất. Nếu chúng lặp lại hoặc không làm thay đổi màn hình, dừng và chuyển cho con người kiểm tra.

recent_actions = []

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

if len(recent_actions) == 5 and len({json.dumps(a, sort_keys=True) for a in recent_actions}) == 1:
    print("Agent appears stuck.")
    break
Enter fullscreen mode Exit fullscreen mode

An toàn

Tác nhân sử dụng máy tính có thể nhấp thật, nhập thật và gửi form thật. Trước khi chạy trên tác vụ quan trọng:

  • Chạy trong sandbox hoặc profile trình duyệt dùng một lần.
  • Không chạy trong phiên production đang đăng nhập.
  • Yêu cầu xác nhận của con người trước hành động phá hủy như xóa, gửi, thanh toán.
  • Ghi log từng hành động kèm ảnh chụp màn hình.
  • Chặn domain hoặc vùng màn hình nhạy cảm nếu cần.

Ví dụ kiểm soát hành động nguy hiểm ở mức ứng dụng:

DANGEROUS_WORDS = ["delete", "remove", "pay", "submit", "confirm"]

def requires_human_confirmation(action, screenshot_text=""):
    if action["action"] != "click":
        return False

    text = screenshot_text.lower()
    return any(word in text for word in DANGEROUS_WORDS)
Enter fullscreen mode Exit fullscreen mode

Kiểm tra các lệnh gọi của tác nhân bằng Apidog

Phần dễ lỗi nhất là bước “mô hình có trả về hành động hợp lệ không?”. Trước khi nối Playwright, hãy kiểm tra riêng request/response của mô hình.

Bạn có thể dùng Apidog để:

  • Gửi một ảnh chụp màn hình mẫu đến Qwen 3.7 Plus.
  • Xem JSON thô mà mô hình trả về.
  • Điều chỉnh system prompt cho đến khi schema ổn định.
  • Lưu khóa Model Studio theo từng môi trường.
  • Mock endpoint để test vòng lặp mà không tốn token trong mỗi lần chạy.
  • Kiểm tra chuỗi request khi tác nhân thực hiện nhiều bước.

Khi vòng lặp đã nối nhiều lệnh gọi, trình gỡ lỗi tác nhân AI của Apidog giúp quan sát chuỗi hành động và tìm bước bị lỗi.

Apidog AI agent debugger

Nếu mục tiêu của bạn là tạo mã giao diện từ thiết kế thay vì điều khiển giao diện, xem thêm hướng dẫn chuyển đổi ảnh chụp màn hình sang mã với Qwen 3.7 Plus.

Bạn cũng có thể tải xuống Apidog để kiểm tra và gỡ lỗi các lệnh gọi mô hình phía sau tác nhân.

Câu hỏi thường gặp

Tác nhân sử dụng máy tính là gì?

Là phần mềm đọc màn hình qua ảnh chụp, dùng mô hình để quyết định hành động, rồi thực thi hành động đó bằng driver tự động hóa cho đến khi đạt mục tiêu.

Qwen 3.7 Plus có thể điều khiển máy tính để bàn của tôi không?

Mô hình không tự điều khiển máy tính. Nó chỉ trả về hành động. Bạn cần driver như Playwright cho trình duyệt hoặc thư viện tự động hóa desktop cho ứng dụng gốc.

Mỗi bước tốn bao nhiêu?

Chi phí chủ yếu đến từ ảnh chụp màn hình. Một ảnh màn hình có thể tiêu tốn vài nghìn token đầu vào với giá 0.40 USD/triệu token. Vì vậy, giảm kích thước ảnh và giới hạn vòng lặp là hai cách kiểm soát chi phí quan trọng nhất.

Có đủ tin cậy để dùng production không?

Có thể dùng cho tác vụ giới hạn rõ ràng, có xác minh sau mỗi bước và có vùng an toàn. Với hệ thống quan trọng hoặc tác vụ mở, luôn cần con người giám sát.

Có cần scale tọa độ không?

Không, nếu độ phân giải ảnh chụp màn hình khớp với viewport. Nếu khác nhau, bạn phải scale tọa độ theo tỷ lệ giữa ảnh gửi cho mô hình và màn hình thực thi.

Kết luận

Một tác nhân sử dụng máy tính chỉ là một vòng lặp ngắn quanh một mô hình có khả năng nhìn GUI. Qwen 3.7 Plus cung cấp nền tảng phù hợp để triển khai vòng lặp đó với chi phí hợp lý. Khi xây dựng, hãy tập trung vào phần kỹ thuật: ép JSON, giới hạn số bước, kiểm soát tọa độ, ghi log, tạo vùng an toàn và xác minh từng hành động.

Trước khi để tác nhân nhấp chuột thật, hãy kiểm tra bước “quyết định” trong Apidog để đảm bảo mô hình luôn trả về hành động hợp lệ.

Top comments (0)