Computer Useツールを自前実装する最小構成

Computer Useツールは何をしてくれるのか — Coworkとの違い

Computer Useツールは、Claudeにスクリーンショットの取得とマウス・キーボード操作を許可する、Anthropic定義のクライアントツールセットです。tools配列に{"type": "computer_toolset_20260801"}を1つ追加するだけで、screenshotやleft_click、typeなど17個のメンバーツールがClaudeに使えるようになります。呼び出しの実行環境は完全に自分のアプリケーション側です。Anthropicはtool_useブロックを返すだけで、画面操作そのものは一切代行しません。

ここが、同じ「Computer Use」という名前を持つClaude Coworkとの決定的な違いです。Coworkは隔離されたVMをAnthropic側が用意し、その上でComputer Useを動かします。開発者は環境構築を意識せずに済む代わりに、動く場所も挙動もCowork任せになります。対してMessages APIから直接呼ぶComputer Useツールは、仮想ディスプレイもエージェントループもスクリーンショット取得コードも、すべて自分で書く前提です。Claude CoworkのComputer Use・VMサンドボックスがプロダクトとして完結した体験を提供するのに対し、本記事が扱うのは「Claudeに画面操作させる仕組みそのものを自分のインフラへ組み込みたい」開発者向けの実装です。

対応モデルはclaude-fable-5-1 / claude-mythos-5-1 / claude-fable-5 / claude-mythos-5 / claude-opus-5 / claude-sonnet-5 / claude-opus-4-8の7つに限られます。Opus 4.7・Opus 4.6・Sonnet 4.6・Opus 4.5はこの新しいツールセットに対応しておらず、ベータヘッダーが必要な旧バージョンcomputer_20251124でのみ動きます。プラットフォームもモデルと同様に一様ではありません。新ツールセットが使えるのはClaude APIとGoogle Cloudの2つだけで、Claude Platform on AWS・Amazon Bedrock・Microsoft Foundryは旧ベータバージョンに限定されています。導入前にこの面ごとの対応状況を確認しておくと、後で作り直す手戻りを避けられます。

実装前に用意する4つの要素

自前実装が必要とする要素は4つに整理できます。

1. Computer Useと相性の良い仮想化・コンテナ環境
2. 17個のメンバーツールそれぞれの動作実装
3. Claude APIを呼び、tool_useの結果を実行するエージェントループ
4. エージェントループを起動するAPIまたはUI

公式のリファレンス実装はanthropic-quickstartsとしてGitHubに公開されています。Dockerコンテナ・ツール実装・エージェントループ・Web UIが一式そろっており、自作の出発点として動くコードを読めます。ゼロから設計するより、まずこのリポジトリを動かしてから自社要件に合わせて差し替える方が近道です。

17個のメンバーツール一覧

computer_toolset_20260801が持つメンバーツールは17個です。実装するときは次の4グループで捉えると漏れを防げます。

サンドボックス環境をXvfbで構築する

Computer Useが実際に操作する画面は、Xvfb(X Virtual Framebuffer)が描く仮想ディスプレイです。公式のコンピューティング環境は次の5層で構成されています。

セキュリティの観点でも、この環境は独立させる必要があります。推奨される対策は次の4点です。

• 専用の仮想マシンかコンテナで、最小権限で動かす
• アカウントのログイン情報のような機微データにアクセスさせない
• インターネットアクセスをドメイン許可リストで絞る
• 金銭取引や利用規約への同意のような重大な結果を招く操作は、人間の確認を挟む

プロンプトインジェクション対策として、Computer Useツールを使うリクエストには分類器が自動的に走ります。スクリーンショット内に疑わしい指示を検知すると、次のアクションの前に確認を挟むようClaudeを誘導する仕組みが標準で有効になっています。人間の確認が挟めないユースケースでオプトアウトしたい場合は、Anthropicのサポート経由での依頼が必要です。

Computer Useはクライアントサイドのツールという扱いです。スクリーンショットやキーボード入力、セッション内で扱うファイルは自分の環境に保存され、Anthropicが保持するのはAPI呼び出しの処理過程だけです。この構造により、Computer UseはZDR(ゼロデータ保持)の対象になります。

エージェントループの中身 — tool_useを処理してtool_resultを返す

エージェントループは「Claudeがツール実行を要求する→アプリケーションが実行して結果を返す」を繰り返す仕組みです。実装の骨格はシンプルです。

def sampling_loop(model, messages, max_iterations=10):
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )
        messages.append({"role": "assistant", "content": response.content})
 
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # tool_useが無ければ完了
 
        messages.append({"role": "user", "content": tool_results})
 
    return messages

max_iterationsは安全装置です。上限を設けないと、Claudeが判断を誤り続けるループが無限にAPI課金を発生させるリスクがあります。ループはClaudeがツール実行を要求しないメッセージを返した時点で自然終了します。ここに到達しない限りタスクは終わりません。

メンバーツールをtoolset_nameで振り分ける

新しいツールセットでは、Claudeの応答はtool_useブロックのnameにメンバー名(left_click、typeなど)が入り、"toolset_name": "computer"が必ず付きます。旧バージョンのcomputer_20251124ではnameが常にcomputer固定で、実際のアクション名はinput.actionに入っていました。この違いが移行時に見落としやすいポイントです。

def handle_computer_action(name, tool_input):
    if name == "screenshot":
        return capture_screenshot()
    elif name == "left_click":
        return click(tool_input.get("coordinate"))
    elif name == "type":
        return type_text(tool_input["text"])
    raise ValueError(f"Unknown or unimplemented member: {name}")

ディスパッチはnameだけでなくtoolset_nameとのペアで行います。同じリクエストに独自定義のツールを混在させたとき、メンバー名が偶然重複する可能性があるためです。toolset_nameを見ずにnameだけで分岐すると、意図しないツールが実行される事故につながります。zoomを実装できない環境では、有効なまま放置してエラーを返し続けるのではなく、configsで明示的に無効化します。

screenshotとzoomの結果は画像ブロックで返し、それ以外のメンバーは"OK"のような短いテキストで十分です。cursor_positionだけは座標をテキストとして返します。座標系はすべて、あなたが返したスクリーンショット画像のピクセル空間で統一されています。

バッチアクションでつまずきやすい3つの落とし穴

Claudeは「クリック→入力→スクリーンショット」のような一連の操作を1回の応答にまとめて返すことがあります。これがバッチアクションです。実装で見落としやすい点が3つあります。

1つ目はブロックの実行順序です。バッチ内の後続アクションは先行アクションの結果に依存します。上の例で言えば、typeは直前のleft_clickでフォーカスした要素に文字を入力します。順不同や並列で実行すると壊れます。

2つ目は失敗時の後始末です。あるアクションが失敗したら、そこで実行を止め、バッチ内の残りのブロックにはis_error: trueと決まった文言(Not executed: an earlier computer action in this turn failed.)を返します。バッチ内のtool_useブロックを1つでも無回答のまま次のリクエストを送ると、invalid_request_errorで拒否されます。最初のブロックだけ読んで応答するループは、この時点で壊れます。

3つ目は人間の確認を挟むタイミングです。重大な結果を招く操作の確認を挟みたい場合、バッチが完了してからではなく、各ブロックの実行前に確認する設計にします。1回のターンでバッチが複数ステップの操作を完了させてしまうためです。

Claudeは通常、バッチの最後をscreenshotで締めくくり、実行結果を確認してから次を判断します。締めくくらない応答があった場合、最後の結果に画像ブロックを追加で添えておくと、Claudeが改めてスクリーンショットを要求する往復を1回省けます。

3つの落とし穴に共通する回避策がtool_choiceのdisable_parallel_tool_use: trueです。エージェントループが1往復で1アクションしか処理できない設計であれば、これをtrueにすることでClaudeは1ターンにつきメンバーツールのtool_useブロックを1つしか返さなくなります。実行順序の管理も失敗時の後始末も、バッチが発生しなければ考える必要自体がなくなります。

料金 — ツールセットを宣言するだけで約4,500トークン

Computer Useの課金は通常のツール使用料金と同じ体系ですが、ツールセットを宣言した時点でのオーバーヘッドを把握しておくと、想定外のコストに驚かずに済みます。computer_toolset_20260801をデフォルトのメンバー構成で宣言すると、メンバーツールの定義とツール使用のシステムプロンプト分として、1リクエストあたり約4,500入力トークンが加算されます。内訳はモデルによって細かく異なります。

zoomをconfigsで無効化すると、この中から約410トークンが減ります。正確な値はレスポンスのusageに毎回返るので、事前見積もりが必要ならトークンカウントAPIで確認できます。

ここに加えて、tool_resultとして返すスクリーンショットやzoom画像は画像入力として別途課金されます。BashツールやText editorツールを併用する場合は、それぞれのツール定義分がさらに加算される点も見積もりに入れておきます。

まとめ — 自前実装とCoworkのどちらを選ぶか

Webページの中だけで完結するタスクなら、フルデスクトップ環境を用意しなくても済むブラウザ操作ツールの方が実装コストは小さくなります。デスクトップ全体の操作が必要で、かつ実行環境を自社側で握りたい開発者だけが、本記事の自前実装ルートを選ぶ理由になります。Agent SDKのように組み込みツールとセッション管理まで一式そろった基盤が欲しいだけなら、Computer Useを自分で組む前にAgent SDKの守備範囲を確認しておく価値もあります。

座標のズレやクリック精度でつまずいた場合は、Computer Useの座標ズレを直すスケーリング計算式とクリックが外れる4パターンの診断表を続けて参照してください。