コンピューター使用ツール

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

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

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

セキュリティに関する考慮事項

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

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

Anthropicは、これらのプロンプトインジェクションに抵抗するようにモデルを訓練し、追加の防御層を設けています。コンピューター使用ツールを使用する場合、分類器がスクリーンショットなどツールが返す内容を自動的にスキャンし、潜在的なプロンプトインジェクションにフラグを立てます。これらの分類器が潜在的なプロンプトインジェクションを特定すると、指示に基づいて行動する前に、その指示が本当にあなたからのものかどうかを確認するよう、モデルを自動的に誘導します。

この追加の保護は、すべてのユースケース（たとえば、人間が介在しないユースケース）に最適とは限らないため、オプトアウトして無効にしたい場合はサポートにお問い合わせください。これらの分類器が導入されていても、上記の予防措置は引き続き重要です。

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

クイックスタート

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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-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を繰り返すことを、「agent loop」（エージェントループ）と呼びます（つまり、Claudeがツール使用リクエストで応答し、アプリケーションがそのリクエストを評価した結果でClaudeに応答することです）。

バッチアクション

Claudeは、クリック、入力、スクリーンショットの取得といった短い一連のアクションを計画し、1つのレスポンスでまとめて返すことができます。これをバッチアクションと呼びます。これは並列ツール使用と同じレスポンス形式を使用しますが、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ブロックごとに1つのtool_resultブロックをtool_use_idで対応付けて、すべて次の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に現れる順序で逐次実行し、いずれかが失敗した場合は残りを実行しないでください。すべての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. 仮想ディスプレイ： デスクトップインターフェースをレンダリングする仮想X11ディスプレイサーバー（Xvfbを使用）。Claudeはこれをスクリーンショットを通じて確認し、マウス/キーボードアクションで制御します。

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は、アクションの結果を明示的に確認せずに、その結果を想定してしまうことがあります。これを防ぐには、ClaudeにAfter each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, 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を実装していない環境向けにそれを無効にし、ツールセット定義にキャッシュブレークポイントを設定します。

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

エージェントループが1回の往復で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：zoomはconfigsで制御するメンバーツールです。

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

思考との組み合わせ

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

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

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

Webページ内で完結するタスクについては、同じリクエストでブラウザ使用ツールを宣言することもできます。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

   Python

   

   # プレースホルダーの画像データ。実際のエグゼキューターは画面をキャプチャして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):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate は省略可能です。指定がない場合は現在のカーソル位置をクリックします
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # 必要に応じて他のアクションを処理します
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

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

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

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

スクリーンショット履歴を管理する

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

コンテキストを制限しながら「prompt caching」（プロンプトキャッシング）の効果を維持するには、次のようにします。

• 「system prompt」（システムプロンプト）とツール定義の後にcache_controlブレークポイントを1つ配置し、直近の各ターンの最後のtool_resultブロックに最大3つまで追加で配置して、ターンごとにそれらを進めます。バッチアクション内では、複数のブロックに付けたマーカーは1つのブレークポイントとして機能しますが、それぞれが4つという上限にカウントされるため、1ターンにつき1つを使用してください。
• 古いスクリーンショットは、毎ターン1枚ずつではなくまとめて削除します。毎ターンスクリーンショットを削除すると、毎ターンプレフィックスが変わり、キャッシュが無効になります。妥当なデフォルトは、直近3枚のスクリーンショットを保持し、25ターンごとに削除することです。これにより、削除のタイミングの間でプレフィックスがバイト単位で同一に保たれます。スクリーンショットのいずれかの辺が2000 pxを超える場合は、各リクエストの画像が20枚以下に収まる間隔を選択してください。
• Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5、Claude Haiku 5.5では、クライアント側での削除は避けてください。以前のスクリーンショットを削除すると、それらのターンをまだ含むすべてのリクエストで、それ以降のすべての思考ブロックが無効になります。代わりに、スクリーンショットを1辺あたり2000 px以下にリサイズし、サーバー側の「tool result clearing」（ツール結果のクリア）を使用して古いものをコンテキストから削除してください。どうしても削除する必要がある場合は、それ以降 prefix_mismatch_behavior: "drop_block" を設定したままにしてください。削除のたびに、Claudeはそのリクエストおよびそれ以降のすべてのリクエストで、削除されたスクリーンショット以降に生成された思考なしで処理を続行します。Claude Sonnet 5.5では、block_binding は thinking: {"type": "adaptive"} の場合にのみ機能します。between_tools を使用する場合は、履歴を追記のみに保つか、編集したターン以降の思考ブロックを取り除いてください。Claude Haiku 5.5では、block_binding は thinking: {"type": "adaptive"} の場合にのみ機能します。thinking: {"type": "disabled"} を使用する場合は、履歴を追記のみに保つか、編集したターン以降の思考ブロックを取り除いてください。

クリックの問題を診断する

クリックが対象から外れる場合、原因は通常次のいずれかです。

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

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向けに記載されているモデルは、そのベータヘッダーとともに引き続きこれを受け付けるため、既存の統合は変更するまで動作し続けます。例外はClaude APIおよびGoogle Cloud上のClaude 5.5以降のモデルで、これらはツールセットのみを受け付けます。統合をそれらのモデルに移行する前にアップグレードしてください。Amazon Bedrockでは、Claude Opus 5.5、Claude Sonnet 5.5、Claude Haiku 5.5は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ブロックを反復処理するようにし、input.actionではなくブロックのnameとtoolset_nameに基づいてディスパッチするようにします。メンバーの入力にはactionフィールドが含まれなくなりました。残りのフィールドは変更されていません。
5. ブロックを順番に実行し、停止テキストを使用します。 バッチアクションで説明されているように、ブロックを順番に実行し、最初の失敗で停止し、残りのブロックにはNot executed: an earlier computer action in this turn failed.で応答します。ループがまだバッチを実行できない場合は、ツールパラメータで、Claudeを1ターンにつき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. 「latency」（レイテンシ）： 人間とAIのインタラクションにおける現在のコンピューター使用のレイテンシは、人間が直接行う通常のコンピューター操作と比べて遅すぎる場合があります。信頼できる環境で、速度が重要ではないユースケース（たとえば、バックグラウンドでの情報収集、自動化されたソフトウェアテスト）に焦点を当ててください。
2. コンピュータービジョンの精度と信頼性： Claudeは、アクションを生成する際に特定の座標を出力するときに、誤りを犯したり「hallucination」（ハルシネーション）を起こしたりする可能性があります。Claudeの要約された思考の出力は、モデルの推論を理解し、潜在的な問題を特定するのに役立ちます。ツールセットをサポートするモデルはデフォルトで思考テキストを省略するため、思考の設定でdisplay: "summarized"を設定してください。
3. ツール選択の精度と信頼性： Claudeは、アクションを生成する際にツールを選択するときに誤りを犯したりハルシネーションを起こしたりする可能性があり、また問題を解決するために予期しないアクションを取る可能性があります。さらに、ニッチなアプリケーションや複数のアプリケーションを同時に操作する場合、信頼性が低下する可能性があります。複雑なタスクを依頼する場合は、モデルに慎重にプロンプトを与えてください。
4. スクロールの信頼性： スクロールアクションは、方向の制御（上、下、左、右）と指定した量をサポートしています。スクロールが効かないアプリケーションでは、Page Downなどのキーボードによる代替手段が役立つ場合があります。
5. スプレッドシートの操作： 個々のセルを選択するには、きめ細かなマウス制御アクション（left_mouse_down、left_mouse_up）と修飾キーの組み合わせを使用してください。複雑なスプレッドシート操作では、依然として複数回の試行が必要になる場合があります。
6. ソーシャルおよびコミュニケーションプラットフォームでのアカウント作成とコンテンツ生成： Claudeはウェブサイトにアクセスしますが、ソーシャルメディアのウェブサイトやプラットフォーム全体でアカウントを作成したり、コンテンツを生成・共有したり、その他の方法で人間になりすましたりする能力は制限されています。
7. 脆弱性： 「jailbreak」（ジェイルブレイク）や「prompt injection」（プロンプトインジェクション）は、あらゆる最先端のAIシステムと同様に、ウェブページや画像に埋め込まれた指示を通じたものも含め、コンピューター使用に影響を与える可能性があります。セキュリティに関する考慮事項の予防措置を適用してください。
8. 不適切または違法なアクション： Anthropicの利用規約に基づき、法律または利用ポリシーに違反するためにコンピューター使用を利用してはなりません。

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

データ保持

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

コンピューター使用のデータをどこにどのように保存するかはお客様のアプリケーションが制御するため、コンピューター使用はZDRの対象となります。すべての機能におけるZDRの対象については、APIとデータ保持を参照してください。

料金

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

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

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

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

追加のトークン消費：

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

次のステップ

Compatibility