コンピュータ使用ツール

Claude は「computer use tool」（コンピュータ使用ツール）を通じてコンピュータ環境と対話できます。このツールは、自律的なデスクトップ操作のためのスクリーンショット機能とマウス／キーボード制御を提供します。

コンピュータ使用ツールは、Anthropic が定義したクライアントツールセットです。tools に {"type": "computer_toolset_20260801"} エントリを1つ追加するだけで、Claude は screenshot、left_click、type、zoom など17個のメンバーツールを利用できるようになり、すべての呼び出しはあなたが管理する環境でアプリケーションが実行します。現在、Claude Managed Agents では利用できません。Claude の呼び出しは、name がメンバー名で "toolset_name": "computer" を持つ tool_use ブロックであり、1ターンに複数含まれることがよくあります（バッチアクション）。

ウェブページ内で完結するタスクには、ブラウザ使用ツールのほうが適しています。そのメンバーツールはページ自体を読み取って操作し、完全なデスクトップ環境を必要としません。

セキュリティ上の考慮事項

コンピュータ使用には、標準的な API 機能とは異なる固有のリスクがあります。これらのリスクは、インターネットとやり取りする際に高まります。

状況によっては、Claude はあなたの指示と矛盾する場合でも、コンテンツ内に見つかったコマンドに従うことがあります。たとえば、ウェブページ上の指示や画像に含まれる指示が、あなたの指示を上書きしたり、Claude にミスをさせたりする可能性があります。プロンプトインジェクションに関連するリスクを避けるため、Claude を機密データや機密性の高いアクションから隔離する予防措置を講じてください。

Anthropic はこれらのプロンプトインジェクションに抵抗するようモデルを訓練し、さらに追加の防御層を加えています。コンピュータ使用ツールを使用すると、プロンプトインジェクションの可能性がある事例にフラグを立てるため、プロンプトに対して分類器が自動的に実行されます。これらの分類器がスクリーンショット内にプロンプトインジェクションの可能性を検出すると、次のアクションに進む前にユーザーの確認を求めるようモデルを自動的に誘導します。この追加の保護はすべてのユースケースに理想的というわけではないため（たとえば、人間が介在しないユースケース）、オプトアウトして無効にしたい場合はサポートにお問い合わせください。

分類器による防御層があっても、これらの予防措置は依然として重要です。

自社製品でコンピュータ使用を有効にする前に、エンドユーザーに関連するリスクを知らせ、同意を得てください。

クイックスタート

Messages API リクエストの tools 配列に、コンピュータ使用ツールセットを {"type": "computer_toolset_20260801"} として追加します。リクエストにベータヘッダーは必要ありません。この例では、Claude が通常コンピュータ使用と併用するテキストエディタツールと bash ツールも宣言しています。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
)
print(response)

Claude がデスクトップ上で操作を行うとき、レスポンスの stop_reason は tool_use になり、1つ以上のメンバー tool_use ブロックが含まれます。各ブロックはメンバーツールの名前を持ち、"toolset_name": "computer" を伴います。このタスクの途中、Claude がデスクトップのスクリーンショットを見た後のレスポンスは次のようになります。

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

アプリケーションは各呼び出しを自身の環境で順番に実行し、tool_use ブロックごとに1つの tool_result ブロックを返して、再度 API を呼び出します。コンピュータ使用の仕組みでそのループを説明し、このページの残りの部分でその実装方法を示します。

コンピュータ使用の仕組み

1. 1

   Claude にコンピュータ使用ツールとユーザープロンプトを提供する

   • API リクエストの tools 配列に、コンピュータ使用ツールセット（および必要に応じて他のツール）を追加します。
   • デスクトップ操作を必要とするユーザープロンプトを含めます。たとえば「猫の写真をデスクトップに保存して」などです。
2. 2

   Claude がメンバーツール呼び出しで応答する

   • Claude は、デスクトップ上での操作がユーザーのクエリに役立つかどうかを判断します。
   • 役立つ場合、Claude は screenshot、left_click、type などの1つ以上のメンバー tool_use ブロックで応答し、それぞれが "toolset_name": "computer" を伴います。これらのブロックを複数含むレスポンスがバッチアクションです。
   • API レスポンスの stop_reason は tool_use となり、ツール使用リクエストであることを示します。
3. 3

   呼び出しを順番に実行して結果を返す

   • レスポンス内のすべての tool_use ブロックを順番に反復処理します。それぞれについて、メンバーの name と toolset_name の組み合わせでディスパッチし、ブロックの input を使ってコンテナまたは仮想マシン上でそのアクションを実行します。
   • tool_use ブロックごとに1つの tool_result ブロックを含む新しい user メッセージで会話を続けます。各ブロックは tool_use_id で対応付けられ、それぞれ "toolset_name": "computer" をエコーします。screenshot と zoom には画像を返し、その他のアクションには OK などの短いテキストで十分です。
   • アクションが失敗した場合は、そのブロックに is_error: true を返し、バッチの残りにはバッチアクションで説明するとおりに応答します。
4. 4

   タスクが完了するまで Claude が続行する

   • Claude はツール結果を分析し、さらにアクションが必要か、タスクが完了したかを判断します。
   • さらにアクションが必要と判断した場合、Claude は再び tool_use の stop_reason で応答するので、ステップ3に戻ります。
   • そうでなければ、ユーザーにテキストレスポンスを返します。

ユーザー入力なしでステップ3と4を繰り返すことを「エージェントループ」と呼びます（つまり、Claude がツール使用リクエストで応答し、アプリケーションがそのリクエストを評価した結果を Claude に返すことです）。

バッチアクション

Claude は、クリック、入力、そしてスクリーンショット撮影といった短い一連のアクションを計画し、それらを1つのレスポンスでまとめて返すことができます。これを「batch action」（バッチアクション）と呼びます。並列ツール使用と同じレスポンス形式を使いますが、1つ違いがあります。ブロックを同時にではなく順番に実行するという点です。

3つのアクションからなるバッチを含むレスポンスは次のようになります。

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

各 tool_use ブロックに対して、tool_use_id で対応付けた tool_result ブロックを1つずつ、すべて次の user メッセージで返します。メンバーツールのすべての結果には "toolset_name": "computer" が必要です。これを省略した結果や、対応する tool_use ブロックと異なるツールセット名を指定した結果は拒否されます。画像が必要なのは screenshot と zoom の結果だけで、その他のメンバーには OK などの短いテキストの確認応答で十分です（cursor_position は座標をテキストで返します）。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

ブロックを順番に実行し、最初の失敗で停止してください。 バッチ内の後続のアクションは通常、先行するアクションに依存します。この例の type は、直前のクリックでフォーカスされた場所にテキストを入力します。ブロックは content に現れる順序で逐次実行し、1つが失敗したら残りは実行しないでください。それでもすべての tool_use ブロックに tool_result が必要なので、バッチには次のように応答します。

• 成功した各アクションには、通常の結果を返します。
• 失敗したアクションには、何が問題だったかを説明するテキストとともに is_error: true を返します。
• バッチ内のそれ以降のすべてのアクションには、正確に次のテキストとともに is_error: true を返します（ブラウザ使用ツールは独自の停止テキストを使用します）。

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

これにより Claude は、どのアクションが成功し、どれが失敗し、どれがスキップされたかを把握し、次のターンで計画を立て直します。バッチ内のいずれかの tool_use ブロックに応答しないリクエストは invalid_request_error で拒否されるため、最初のブロックしか読まないエージェントループは次の呼び出しで失敗します。アプリケーションが重大なアクションについて人間に確認を求める場合は、各ブロックを実行する前にそのチェックを行ってください。バッチは1ターン内で複数ステップのアクションを完了できるためです。

Claude は通常、次に何をするか決める前に結果を観察できるよう、バッチを screenshot で終えます。バッチがスクリーンショットで終わらない場合、アプリケーションはバッチの最後の結果に追加の image ブロックとしてスクリーンショットを添付できます。これにより Claude は常に画面の現在の状態を確認でき、Claude が要求するのを待つ場合と比べてラウンドトリップを1回節約できます。また、すべてのバッチをスクリーンショットで終えるよう Claude にプロンプトで指示することもできます（プロンプトによるモデルパフォーマンスの最適化を参照）。

コンピューティング環境

コンピュータ使用には、Claude がアプリケーションやウェブと安全にやり取りできるサンドボックス化されたコンピューティング環境が必要です。この環境には以下が含まれます。

1. 仮想ディスプレイ: Claude がスクリーンショットを通じて見て、マウス／キーボードアクションで制御するデスクトップインターフェースをレンダリングする仮想 X11 ディスプレイサーバー（Xvfb を使用）。

2. デスクトップ環境: Linux 上で動作するウィンドウマネージャー（Mutter）とパネル（Tint2）を備えた軽量 UI。Claude が操作するための一貫したグラフィカルインターフェースを提供します。

3. アプリケーション: Firefox、LibreOffice、テキストエディタ、ファイルマネージャーなど、Claude がタスクを完了するために使用できるプリインストール済みの Linux アプリケーション。

4. ツール実装: Claude の抽象的なツールリクエスト（「マウスを移動」や「スクリーンショットを撮る」など）を仮想環境での実際の操作に変換する統合コード。

5. エージェントループ: Claude と環境の間の通信を処理するプログラム。Claude のアクションを環境に送信し、結果（スクリーンショット、コマンド出力）を Claude に返します。

コンピュータ使用を利用する際、Claude はこの環境に直接接続しません。代わりに、アプリケーションが次のことを行います。

1. Claude のツール使用リクエストを受け取る
2. それらをコンピューティング環境でのアクションに変換する
3. 結果（スクリーンショットやコマンド出力など）を取得する
4. これらの結果を Claude に返す

セキュリティと隔離のため、リファレンス実装はこれらすべてを Docker コンテナ内で実行し、環境の表示と操作のための適切なポートマッピングを行います。

コンピュータ使用の実装方法

既存の computer_20251124 統合をアップグレードする場合は、computer_20251124 からの移行から始めてください。このセクションの残りの部分は、新規の統合と移行した統合の両方に適用されます。

エージェントループを理解する

コンピュータ使用の中核は「エージェントループ」です。Claude がツールアクションを要求し、アプリケーションがそれを実行し、結果を Claude に返すというサイクルです。このループは、クイックスタートで作成したクライアント、コンピュータ使用ツールセットのみを宣言する tools 配列、そしてコンピュータ使用ツールを実装するにあるツール呼び出し処理ヘルパーを使用します。クイックスタートの bash ツールやテキストエディタツールなど他のツールも宣言する場合は、それらの tool_use ブロックも同じパスでディスパッチしてください。ヘルパーはコンピュータ使用のメンバー呼び出しにのみ応答し、ループは応答された呼び出しがないターンを完了として扱います。簡略化した例を次に示します。

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # Claudeの応答を会話履歴に追加します
        messages.append({"role": "assistant", "content": response.content})

        # Claudeが要求したアクションを順番に実行し、結果を収集します
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # すべての結果を1つのユーザーメッセージでClaudeに送り返します
        messages.append({"role": "user", "content": tool_results})

    return messages

ループは、Claude がツールを要求せずに応答する（タスク完了）か、最大反復回数に達するまで続きます。この安全策により、予期しない API コストにつながる可能性のある無限ループを防ぎます。

プロンプトによるモデルパフォーマンスの最適化

1. シンプルで明確に定義されたタスクを指定し、各ステップに明示的な指示を与えてください。
2. Claude は、結果を明示的に確認せずにアクションの結果を仮定することがあります。これを防ぐには、After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one. のようにプロンプトで指示できます。
3. 一部の UI 要素（ドロップダウンやスクロールバーなど）は、Claude がマウス操作で扱うのが難しい場合があります。そのような場合は、キーボードショートカットを使うようモデルにプロンプトで指示してみてください。
4. 繰り返し可能なタスクや UI 操作については、成功した結果のスクリーンショットとツール呼び出しの例をプロンプトに含めてください。
5. モデルにログインさせる必要がある場合は、<robot_credentials> などの XML タグ内にユーザー名とパスワードを入れてプロンプトで提供してください。ログインが必要なアプリケーション内でコンピュータ使用を利用すると、プロンプトインジェクションによる悪い結果のリスクが高まります。モデルにログイン認証情報を提供する前に、ジェイルブレイクとプロンプトインジェクションの軽減を確認してください。
6. ユーザーターンの content 配列を構築する際は、指示テキストをスクリーンショット画像の前に配置してください。画像が処理される前にターゲットの説明を提供すると、クリック精度が向上します。
7. Claude は、サイドバーのファイル名、タブのタイトル、ステータスバーのテキスト、行番号、ボタンのラベルなど、スクリーンショットのデフォルト解像度では判読できない小さなテキストや特定の UI 要素について尋ねられたとき、zoom アクションを使って領域をフル解像度で調べます。期待どおりに Claude がズームしない場合は、画面全体ではなく特定の領域や要素について尋ねてください。
8. すべてのバッチアクションをスクリーンショットで終えたい場合は、システムプロンプトでそう指示してください。たとえば End each group of actions with a screenshot so you can verify the result before continuing. のようにします。

システムプロンプト

リクエストにコンピュータ使用ツールを含めると、API はコンピュータ使用専用のシステムプロンプトを生成します。これはツール使用のシステムプロンプトに似ていますが、次の文で始まります。

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

通常のツール使用と同様に、ユーザーが提供した system パラメータは引き続き尊重され、結合されたシステムプロンプトの構築に使用されます。

利用可能なアクション

各アクションはコンピュータ使用ツールセットのメンバーツールです。Claude は "toolset_name": "computer" を持つ tool_use ブロックでメンバー名を指定し、ブロックの input にはそのメンバーのパラメータのみが含まれ、action フィールドはありません。ツールセットには17個のメンバーツールがあります。

メンバーを実装する際は、次の点に留意してください。

• 座標はスクリーンショットのピクセル単位です。 すべての coordinate、start_coordinate、region の値、および cursor_position が報告する位置は、あなたが返すディスプレイ全体のスクリーンショットのピクセル空間で表され、原点は左上です。ズーム画像はこれを変更しません。zoom の後も、Claude は座標を全体スクリーンショットの空間で表現し、ズーム画像に対する相対座標では決して表現しません。スクリーンショットを縮小してから返す場合は、Claude の座標を実際のディスプレイに適用する前に拡大し直してください（画像制限に合わせてスクリーンショットのサイズを調整するを参照）。
• zoom を含め、すべてのメンバーはデフォルトで有効です。 環境がズーム画像を生成できない場合は、有効のままにしてエラーを返すのではなく、configs でそのメンバーを除外してください（ツールパラメータを参照）。除外したメンバーや実装していないメンバーを Claude が呼び出した場合は、そのブロックに対して is_error: true の tool_result を返してください。
• （toolset_name、name）のペアでディスパッチしてください。 toolset_name こそがブロックをコンピュータアクションとして識別するものです。同じリクエスト内のカスタムツールがメンバーと同じ名前を持つことがあり、また後のツールセットバージョンでメンバーが追加されることもあります（クライアントツールセットを参照）。

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

ツールパラメータ

tools 配列内のツールセットエントリは4つのパラメータを受け付けます。ブラウザ使用ツールセットと共通のルールはクライアントツールセットに記載されています。

たとえば、次のエントリは zoom を実装していない環境向けに zoom を除外し、ツールセット定義にキャッシュブレークポイントを設定します。

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

エージェントループがラウンドトリップごとに1つのアクションしか実行できない場合は、tool_choice で disable_parallel_tool_use を true に設定してください。そうすると Claude は1ターンにつき最大1つのメンバー tool_use ブロックを返します（並列ツール使用を無効にするを参照）。

このエントリは以前のツールバージョンの次のパラメータを拒否し、これらのいずれかを含むリクエストは invalid_request_error を返します。

• name: メンバー名はツールセットバージョンによって固定されています。
• display_width_px、display_height_px、display_number: 座標は常にあなたが返すスクリーンショットのピクセル空間で表されます。
• enable_zoom: ズームは configs を通じて制御するメンバーツールです。

また、このエントリは computer_20251124 エントリや computer という名前の別のツールと同じリクエスト内で宣言することもできません。strict、input_examples、defer_loading の配置、tool_choice、ストリーミング、呼び出し元の制限については、クライアントツールセットを参照してください。

思考との組み合わせ

コンピュータ使用を思考と組み合わせるには、思考を参照してください。

他のツールによるコンピュータ使用の拡張

コンピュータ使用と並んで他のツールを追加するには、同じ tools 配列にそれらを含めます。クイックスタートセクションでは、bash ツールとテキストエディタツールでこのパターンを示しています。独自のカスタムツール定義も同じ方法で追加できます。

ウェブページ内で完結するタスクには、同じリクエストでブラウザ使用ツールを宣言することもできます。2つのツールセットはそれぞれ独自の座標系で独立して動作し、screenshot や key のように名前を共有するメンバーへの呼び出しは toolset_name で区別されます。

カスタムのコンピュータ使用環境を構築する

リファレンス実装は、コンピュータ使用を始める手助けとなることを目的としています。Claude にコンピュータを使わせるために必要なすべてのコンポーネントが含まれています。ただし、ニーズに合わせて独自のコンピュータ使用環境を構築することもできます。必要なものは次のとおりです。

• Claude によるコンピュータ使用に適した仮想化またはコンテナ化された環境
• コンピュータ使用ツールのアクションの実装
• Claude API とやり取りし、ツール実装を使って tool_use の結果を実行するエージェントループ
• エージェントループを開始するためのユーザー入力を受け付ける API または UI

コンピュータ使用ツールを実装する

コンピュータ使用ツールはスキーマレスツールとして実装されています。このツールを使用する際、他のツールのように入力スキーマを提供する必要はありません。スキーマは Claude のモデルに組み込まれており、変更できません。

1. 1

   コンピューティング環境をセットアップする

   Claude が操作する仮想ディスプレイを作成するか、既存のディスプレイに接続します。これには通常、Xvfb（X Virtual Framebuffer）または同様の技術のセットアップが含まれます。

2. 2

   アクションハンドラを実装する

   Claude が要求する可能性のある各アクションタイプを処理する関数を作成します。

   PythonTypeScriptC#GoJavaPHPRuby

   

   # プレースホルダーの画像データ。実際のエグゼキューターは画面をキャプチャしてPNGバイトを返します
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshotはテキストではなく画像ブロックで応答するため、結果のコンテンツリストを返します
       return [
           {
               "type": "image",
               "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       if name == "screenshot":
           return capture_screenshot()
       elif name == "left_click":
           # coordinateは省略可能。指定がない場合はカーソルの現在位置でクリックします
           return click(tool_input.get("coordinate"))
       elif name == "type":
           return type_text(tool_input["text"])
       # 必要に応じて他のアクションを処理します
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Claude のツール呼び出しを処理する

   Claude のレスポンスからツール呼び出しを抽出して実行します。

   PythonTypeScriptC#GoJavaPHPRuby

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # 宣言されているのはcomputerツールセットのみ。他のツールを追加する場合はここでルーティングします
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # 文字列、またはスクリーンショット画像などのコンテンツブロックのリスト
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   エージェントループを実装する

   前の2つのステップをループでラップし、結果を送り返して、Claude がメンバーツール呼び出しを返さなくなるまで繰り返します。エージェントループを理解するで各言語でのこのループを示しています。

エラーを処理する

失敗したアクションは、is_error: true と短い説明を持つ tool_result として Claude に報告し、他のメンバー結果と同様に "toolset_name": "computer" を含めてください。失敗したアクションがバッチアクションの一部だった場合は、バッチ内の残りのブロックを実行せず、そこで示した停止テキストで応答してください。

たとえば、スクリーンショットのキャプチャが失敗した場合は次のようになります。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

ディスプレイの範囲外の座標や実行に失敗したアクションにも同じ形式を使い、何が問題だったかを示すメッセージを付けてください。

画像制限に合わせてスクリーンショットのサイズを調整する

コンピュータ使用ツールセットに返すスクリーンショットとズーム画像は、あらかじめモデルの画像サイズ制限内に収まっている必要があります。ツールセットはディスプレイ寸法を受け取らず、API も縮小を行わないため、サイズ超過の tool_result 画像は検証エラーで拒否されます。Claude は自身が見た画像のピクセル空間で座標を返すため、使用したスケール係数を保持しておき、それらの座標を画面にマッピングし直せるようにしてください。

画面が制限より大きい場合は、各スクリーンショットを返す前にリサイズし、Claude が返した座標を元の画面空間にスケーリングし直してください。ツールセットはディスプレイ寸法を受け取らないため、アプリケーションコードでのリサイズと座標スケーリングだけで十分です。

import math

screen_width, screen_height = 1512, 982


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# スクリーンショットをキャプチャする際
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Claudeに送信する前に画像をスケーリング後のサイズにリサイズ
screenshot = capture_and_resize(scaled_width, scaled_height)


# Claudeの座標を扱う際は、元のサイズにスケールアップして戻す
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

ディスプレイ解像度を選択してスクリーンショットを返す際は、次の点に注意してください。

• 一般的なデスクトップタスクには 1024x768 または 1280x720 を、ウェブアプリケーションには 1280x800 または 1366x768 を使用してください。
• パフォーマンスの問題を防ぐため、1920x1080 を超える解像度は避けてください。
• スクリーンショットは base64 の PNG または JPEG としてエンコードし、パフォーマンス向上のため大きなスクリーンショットは圧縮を検討してください。
• タイムスタンプやディスプレイの状態など、関連するメタデータを含めてください。
• より高い解像度を使用する場合は、座標が正確にスケーリングされていることを確認してください。

スクリーンショット履歴の管理

長いエージェントループでは、スクリーンショットが急速に蓄積されます（1枚あたりおよそ1,000～1,800入力トークン）。APIのリクエスト制限も適用されます。1つのリクエストに20枚を超える画像が含まれると、そのリクエスト内のすべての画像に、より厳しい辺ごとの制限が適用されます。スクリーンショット履歴を保持するループは数十ターン以内にその枚数に達するため、各スクリーンショットをどちらの辺も2000 pxを超えないようにリサイズするか、古いスクリーンショットを削除してリクエスト内の画像を20枚以下に保ってください。

コンテキストを制限しつつプロンプトキャッシングを効果的に保つには、次のようにします。

• cache_control ブレークポイントを1つ、システムプロンプトとツール定義の後に配置し、さらに最大3つを直近の各ターンの最後の tool_result ブロックに配置して、ターンごとに前進させます。バッチアクション内では、複数のブロックに付けたマーカーは単一のブレークポイントとして機能しますが、それぞれが4つという上限にカウントされるため、ターンごとに1つだけ使用してください。
• 古いスクリーンショットは、ターンごとに1枚ずつではなく、バッチで削除します。ターンごとにスクリーンショットを1枚削除すると、ターンごとにプレフィックスが変わり、キャッシュが無効になります。妥当なデフォルトは、直近3枚のスクリーンショットを保持し、25ターンごとに削除することです。これにより、削除イベント間でプレフィックスがバイト単位で同一に保たれます。スクリーンショットのいずれかの辺が2000 pxを超える場合は、各リクエストの画像が20枚以下に保たれる間隔を選んでください。
• Claude Fable 5.1では、クライアント側での削除を避けてください。以前のスクリーンショットを削除すると、それらのターンをまだ含んでいるすべてのリクエストで、それ以降のすべての思考ブロックが無効になります。代わりに、スクリーンショットを各辺2000 px以下にリサイズし、サーバー側のツール結果クリアを使用して古いものをコンテキストから削除してください。どうしても削除する必要がある場合は、それ以降 prefix_mismatch_behavior: "drop_block" を設定したままにしてください。各削除の後、Claudeはそのリクエストおよびそれ以降のすべてのリクエストで、削除されたスクリーンショット以降に生成された思考なしで続行します。

クリックの問題の診断

クリックがターゲットを外す場合、原因は通常次のいずれかです。

実装のベストプラクティスに従う

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

computer_20251124 からの移行

computer_20251124 からツールセットへのアップグレードは任意です。以前のツールバージョンで computer_20251124 向けに記載されているモデルは、ベータヘッダー付きで引き続きこれを受け付けるため、既存の統合は変更するまで動作し続けます。アップグレードするには、次の変更をまとめて行ってください。

1. ベータヘッダーを削除する。 リクエストから anthropic-beta: computer-use-2025-11-24 を削除します。SDKでは、betas パラメータを削除し、ベータ名前空間ではなく標準クライアントを通じてMessages APIを呼び出します。
2. tools エントリを変更する。 type を computer_toolset_20260801 に設定し、name、display_width_px、display_height_px、display_number、enable_zoom を削除します。ツールセットはこれらの各フィールドを拒否します。
3. ズームを有効のままにするかどうかを選択する。 ツールセットではズームがデフォルトで有効ですが、enable_zoom のデフォルトは false です。環境がズームを実装していない場合は、"configs": {"zoom": {"enabled": false}} を追加して以前の動作を維持してください。そうでなければ実装してください（利用可能なアクションを参照）。
4. ターン内のすべてのブロックを処理する。 エージェントループを更新し、レスポンス内の最初の tool_use ブロックだけを読むのではなくすべての tool_use ブロックを反復処理し、input.action ではなくブロックの name と toolset_name の組み合わせでディスパッチするようにします。メンバーの入力には action フィールドが含まれなくなりました。残りのフィールドは変更ありません。
5. ブロックを順番に実行し、停止テキストを使用する。 バッチアクションで説明されているように、ブロックを順次実行し、最初の失敗で停止し、残りのブロックには Not executed: an earlier computer action in this turn failed. で応答します。ループがまだバッチを実行できない場合は、ツールパラメータでClaudeをターンごとに1つのアクションに制限する方法を説明しています。
6. 結果に toolset_name をエコーする。 メンバー呼び出しに応答するすべての tool_result に "toolset_name": "computer" を追加します。結果には text と image のコンテンツのみを含めることができます。
7. key で repeat をサポートする。 key メンバーは、1から100までのオプションの repeat カウントを受け付けます。認識できないフィールドを無視するハンドラーはキーを1回しか押さないため、key ハンドラーが repeat を尊重するようにしてください。
8. スクリーンショットを自分でリサイズする。 ツールセットは、モデルの画像制限を超えるスクリーンショットやズーム画像をダウンスケールせずに拒否します。画像を返す前にリサイズし、画像制限に合わせたスクリーンショットのサイズ調整で説明されているように座標のスケーリングを続けてください。
9. サポートされていないオプションを削除する。 defer_loading があればエントリから configs に移動し、有効なすべてのメンバーに同じ値を設定します。ツールセットエントリでサポートされていないその他のオプションは、クライアントツールセットに記載されています。

以下は変更前の tools エントリで、anthropic-beta: computer-use-2025-11-24 ヘッダー付きで送信されます。

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

以下は変更後の tools エントリで、ベータヘッダーなしで送信されます。configs オブジェクトは、enable_zoom を設定していない以前のエントリに合わせてズームをオフに保っています。デフォルトを受け入れてClaudeにズームさせるには、configs を完全に省略してください。

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

次のペアは、変更前と変更後の tool_use ブロックを示しています。アクション名は input.action から name に移動し、ブロックには toolset_name が追加されます。

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

以前のツールバージョン

コンピュータ使用ツールの以前の2つのバージョンは、既存の統合向け、ツールセットをサポートしないモデル向け、およびツールセットが現在利用できないプラットフォーム向けに、引き続きベータで利用可能です。それぞれ、すべてのリクエストにベータヘッダーが必要で、パラメータはベータMessages APIリファレンスに記載されています。SDKでは、betas パラメータを通じてヘッダーを渡し、ベータ名前空間を使用してください。ヘッダーが必要なのはコンピュータ使用ツールのみで、同じリクエスト内のbashツールやテキストエディタツールには必要ありません。

制限事項

1. レイテンシ： 人間とAIのインタラクションにおける現在のコンピュータ使用の「latency」（レイテンシ）は、通常の人間によるコンピュータ操作と比べて遅すぎる可能性があります。信頼できる環境で、速度が重要でないユースケース（例：バックグラウンドでの情報収集、自動化されたソフトウェアテスト）に焦点を当ててください。
2. コンピュータビジョンの精度と信頼性： Claudeは、アクション生成時に特定の座標を出力する際に、間違いを犯したりハルシネーションを起こしたりする可能性があります。Claudeの要約された思考出力は、モデルの推論を理解し、潜在的な問題を特定するのに役立ちます。ツールセットをサポートするモデルはデフォルトで思考テキストを省略するため、思考設定で display: "summarized" を設定してください。
3. ツール選択の精度と信頼性： Claudeは、アクション生成時にツールを選択する際に間違いを犯したりハルシネーションを起こしたり、問題を解決するために予期しないアクションを取ったりする可能性があります。さらに、ニッチなアプリケーションや複数のアプリケーションを同時に操作する場合、信頼性が低下する可能性があります。複雑なタスクを要求する際は、モデルに慎重にプロンプトを与えてください。
4. スクロールの信頼性： スクロールアクションは、方向制御（上、下、左、右）と指定量をサポートしています。スクロールが効かないアプリケーションでは、Page Downなどのキーボードによる代替手段が役立ちます。
5. スプレッドシートの操作： 個々のセルを選択するには、きめ細かいマウス制御アクション（left_mouse_down、left_mouse_up）と修飾キーの組み合わせを使用してください。複雑なスプレッドシート操作には、依然として複数回の試行が必要になる場合があります。
6. ソーシャルおよびコミュニケーションプラットフォームでのアカウント作成とコンテンツ生成： Claudeはウェブサイトを訪問しますが、ソーシャルメディアのウェブサイトやプラットフォーム全般において、アカウントを作成したり、コンテンツを生成・共有したり、その他の方法で人間になりすましたりする能力は制限されています。
7. 脆弱性： ジェイルブレイクやプロンプトインジェクションは、あらゆるフロンティアAIシステムと同様に、ウェブページや画像に埋め込まれた指示を通じたものを含め、コンピュータ使用に影響を与える可能性があります。セキュリティに関する考慮事項の予防措置を適用してください。
8. 不適切または違法なアクション： Anthropicの利用規約に基づき、法律または利用規定（Acceptable Use Policy）に違反するためにコンピュータ使用を用いてはなりません。

Claudeのコンピュータ使用アクションとログは、常に慎重に確認・検証してください。完璧な精度や機密性の高いユーザー情報を必要とするタスクに、人間の監督なしでClaudeを使用しないでください。

データ保持

コンピュータ使用はクライアント側のツールです。セッションに関わるすべてのスクリーンショット、マウスアクション、キーボード入力、およびファイルは、Anthropicではなくお客様の環境でキャプチャおよび保存されます。Anthropicは、API呼び出しの一部としてスクリーンショット画像とアクションリクエストをリアルタイムで処理します。これらのAPIリクエストの保持は、APIとデータ保持によって規定されます。

コンピュータ使用データの保存場所と保存方法はお客様のアプリケーションが制御するため、コンピュータ使用はZDRの対象です。すべての機能にわたるZDRの対象可否については、APIとデータ保持を参照してください。

料金

コンピュータ使用は標準のツール使用の料金に従います。コンピュータ使用ツールを使用する場合：

ツールセット定義のオーバーヘッド： computer_toolset_20260801 をデフォルトのメンバーとともに宣言すると、リクエストに約4,500入力トークンが追加されます（Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Opus 4.8では約4,520、Claude Sonnet 5では約4,590）。これにはメンバーツールの定義とツール使用のシステムプロンプトが含まれます。configs で zoom を無効にすると、そのうち約410トークンが削減されます。リクエストの正確なトークン数はレスポンスの usage で報告され、トークンカウントエンドポイントを使用して事前に見積もることができます。

以前のツールバージョン： 以下の数値は computer_20251124 および computer_20250124 ツールバージョンに適用され、computer_toolset_20260801 には適用されません：

• システムプロンプトのオーバーヘッド：システムプロンプトに466〜499トークンが追加されます
• ツール定義：ツール定義ごとに約735入力トークン（computer_20250124 で測定）

追加のトークン消費：

• ツール結果で返されるスクリーンショットおよびズーム画像。画像入力として課金されます（ビジョンの料金を参照）
• Claudeに返されるツール実行結果

次のステップ

Compatibility