Qwen 3.7 Plusを使ったPC操作エージェントの作り方

Qwen 3.7 Plusは、スクリーンショットを見てクリックする正確なピクセル座標を返すベンチマークであるScreenSpot Proで79.0点を獲得しました。この単一のスキルが、チャットモデルをコンピューター使用エージェント（画面を見て、何をすべきかを決定し、実行するソフトウェア）に変えます。このガイドでは、Pythonでそのエージェントを最初から最後まで構築します。

エージェントループ、モデルから信頼性の高いアクションを引き出すプロンプト、Playwrightを使用した実行可能なブラウザの例、そして実世界で利用する前に必要なコストと安全性のガードレールについて説明します。モデルの背景を先に知りたい場合は、Qwen 3.7 Plusの概要をご覧ください。生の要求形式については、Qwen 3.7 Plus APIガイドでマルチモーダルペイロードを扱っています。進行中にApidogでエージェントの呼び出しをテストします。

要点

コンピューター使用エージェントはループを実行します。画面をスクリーンショットし、Qwen 3.7 Plusに目標とともに送信し、click (x, y)のような構造化されたアクションを受け取り、Playwrightなどのドライバーでそのアクションを実行し、目標が達成されるまで繰り返します。PlusはそのGUIの基礎と低いマルチモーダル価格のため、非常に適しています。難しいのはモデルではなく、ループの制限、座標のスケーリング、トークンコストの制御、誤ったクリックが損傷を与えないようにアクションをサンドボックス化することです。

コンピューター使用エージェントが実際にすること

誇張を省くと、以下の4つのステップの繰り返しです。

認識: 現在の画面またはページのスクリーンショットをキャプチャします。
決定: スクリーンショットと目標をモデルに送信し、次のアクションを取得します。
実行: そのアクション（クリック、入力、スクロール）を自動化ドライバーを介して実行します。
確認: 新しいスクリーンショットを撮り、目標が達成されたかどうかを判断します。

モデルは「決定」ステップです。その他のすべては、あなたが制御する配管です。

0:00

/1:26

Qwen 3.7 Plusが適している理由

理由は3つあります。そのGUIの基礎は最先端であり、曖昧な説明ではなく使用可能な座標を返します。GUIとCLIのハイブリッドなワークフローを処理できるため、同じエージェントがボタンをクリックしたり、シェルコマンドを実行したりできます。そして、入力トークン100万あたり0.40ドルと、エージェントループが必要とする多くの視覚呼び出しを実行するのに十分なほど安価です。テキストのみの主力モデルとの比較については、Qwen 3.7 Plus vs Maxの比較をご覧ください。

決定ステップ：クリーンなアクションを取得する

秘訣は、モデルを小さなアクションボキャブラリに制約し、JSON出力を強制することです。曖昧な散文は実行が困難ですが、厳密なスキーマはそうではありません。

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 = """あなたはGUIエージェントです。スクリーンショットと目標を見ます。
一つのJSONアクションのみで返答してください：
{"action": "click", "x": <int>, "y": <int>}
{"action": "type", "text": "<string>"}
{"action": "scroll", "dy": <int>}
{"action": "done", "reason": "<string>"}
座標は与えられたスクリーンショットのピクセルです。"""

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)

識別子は変更される可能性があるため、デプロイする前にModel Studioのドキュメントで正確なモデルIDを確認してください。

Playwrightによる完全なループ

Playwrightは実際のブラウザを駆動するため、エージェントは実際のページで動作します。一つの詳細が多くの苦痛を軽減してくれます。スクリーンショットの解像度をビューポートと一致させることで、モデルが返す座標が1対1で対応し、スケーリング計算をスキップできます。

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 = "価格ページを開き、最も安いプランを見つける"

    for step in range(15):                 # ステップ数の上限
        shot = page.screenshot()           # 1280x800 PNG、ビューポートと一致
        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)         # UIが安定するのを待つ

    browser.close()

これが実際の（動作する）エージェントです。それは目標に向かって、一度に一つの具体的なアクションでサイトをナビゲートします。Playwrightをデスクトップドライバーに置き換え、代わりにOSウィンドウをスクリーンショットすれば、デスクトップアプリでも同じパターンが機能します。

コストと信頼性

スクリーンショットがコストのかかる部分です。それぞれがトークンに変換され、幅1280の画像は数千トークンに達するため、15ステップのループではAPIを通じてかなりの費用が発生します。これを抑えるには：

ダウンスケールとクロップ。モデルがまだ読み取れる最小の画像を送信します。可能な場合は、関連するパネルにクロップします。
ループの制限。例のように、常にステップ数を制限してください。これにより、混乱したエージェントが永遠に実行されるのを防ぎます。
実行後の検証。各アクションを仮説として扱います。次のスクリーンショットでそれが機能したかどうかを確認し、ループは自己修正します。

エージェントトークンコストの削減に関するガイドで詳しく説明されており、エージェントワークフローの配線に関するメモでは、これらのループが実際にどこで壊れるかをカバーしています。

エージェントが停止した場合

常に3つの障害が発生しますが、それぞれ安価な解決策があります。

モデルがJSONではなく散文を返す。「JSONのみで返答してください」という短いリマインダーで再プロンプトし、諦める前に一度再試行します。厳密なスキーマと修復ステップで、ほとんどすべてを捕捉できます。
クリックがターゲットを外れる。次のスクリーンショットで何も変化がないことが示されるため、同じ座標を盲目的に繰り返すのではなく、新しいスクリーンショットで再試行するルールを追加します。
ループが進行せずにスピンする。直近のいくつかのアクションを追跡し、それが繰り返される場合は停止して、人間がスクリーンショットを確認できるようにします。ステップ制限があなたの最終手段です。

安全性

コンピューター使用エージェントは実際に物をクリックします。重要なものに触れる前に：

サンドボックスまたは使い捨てのブラウザプロファイルで実行し、ログイン中の本番セッションでは決して使用しないでください。
削除、送信、支払いなどの破壊的なアクションには人間の確認を求めます。
エージェントが何をして、なぜしたのかを監査できるように、各アクションをスクリーンショットとともにログに記録します。

Apidogでエージェントの呼び出しをテストする

ほとんどのエージェントの失敗は、「モデルは有効なアクションを返したか？」という一つの疑問に遡ります。Playwrightを配線する前に、それを明確にしてください。Apidogを使用して、サンプルスクリーンショットをQwen 3.7 Plusに送信し、それが返す生のJSONを検査し、アクションスキーマが毎回クリーンに戻るまでシステムプロンプトを調整します。環境ごとにModel Studioキーを保存し、エンドポイントをモックすることで、テスト実行ごとにトークンを消費することなくループを構築できます。フルループが呼び出しを連鎖している場合、ApidogのAIエージェントデバッガーがシーケンスを表示し、どのステップで失敗したかを見つけることができます。

デザインからUIコードを生成する方法については、Qwen 3.7 Plusによるスクリーンショットからコードへの変換に関する付随ガイドをご覧ください。

エージェントの背後にあるモデル呼び出しをテストおよびデバッグするには、Apidogをダウンロードしてください。

よくある質問

コンピューター使用エージェントとは何ですか？ スクリーンショットを通じて画面を認識し、モデルでアクションを決定し、自動化ドライバーを通じてそれを実行し、目標が達成されるまでループするソフトウェアです。

Qwen 3.7 Plusは私のデスクトップを制御できますか？ モデルはアクションを返すだけです。ドライバーを使用してそれらを実行します。ブラウザの場合はPlaywrightと、ネイティブアプリの場合はデスクトップ自動化ライブラリと組み合わせてください。

各ステップのコストはどれくらいですか？ ほとんどはスクリーンショットにかかります。1つの画面画像は、100万トークンあたり0.40ドルで数千入力トークンに達する可能性があるため、ダウンスケールとループの制限が主なコスト削減策となります。

本番環境で十分信頼できますか？ 各ステップの後に検証を伴う、限定的で明確に定義されたタスクであれば可能です。重要なシステムのオープンエンドな制御には、人間を介在させ、すべてをサンドボックス化してください。

座標をスケーリングする必要がありますか？ スクリーンショットの解像度がビューポートと一致している場合は必要ありません。異なる場合は、その比率で返された座標をスケーリングしてください。

結論

コンピューター使用エージェントは、一つの強力なモデルを中心とした短いループであり、Qwen 3.7 Plusはそれを実行するための基礎と価格を提供します。ループを構築し、制限を設け、サンドボックス化し、各ステップを検証してください。そして、エージェントがクリックを開始する前に「決定」ステップが確実であるように、Apidogでモデル呼び出しをテストしてください。

ボタン