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

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

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

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

ツールセットをサポートするモデルとプラットフォームについては、APIサポートを参照してください。以前のツールバージョンには、以前の各バージョンのベータヘッダーと、それを使用するモデルが記載されています。

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

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

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

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

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

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

クイックスタート

Messages APIAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。リクエストの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つのレスポンスでまとめて返すことができます。これを「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ブロックに対して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に現れる順序で順次実行し、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. 仮想ディスプレイ： デスクトップインターフェースをレンダリングする仮想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,
        )

        # Add Claude's response to the conversation history
        messages.append({"role": "assistant", "content": response.content})

        # Run the actions Claude requested, in order, and collect the results
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Send every result back to Claude in a single user message
        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つのメンバー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、ストリーミング、および呼び出し元の制限については、クライアントツールセットを参照してください。

思考との組み合わせ

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

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

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

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

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

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

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

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

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

1. 1

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

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

2. 2

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

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # Placeholder image data; a real executor captures the screen and returns the PNG bytes
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot answers with an image block rather than text: return the result content list
       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 is optional; without it, click where the cursor already is
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Handle other actions as needed
       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:
           # Only the computer toolset is declared; route other tools here if you add them
           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:
                   # A string, or a list of content blocks such as the screenshot image
                   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辺あたりの制限が適用されます。スクリーンショット履歴を保持するループは数十ターン以内にその枚数に達するため、各スクリーンショットをその制限内に収まるようにリサイズするか、古いスクリーンショットを削除してリクエスト内の画像を20枚以下に保ってください。

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

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

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

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

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

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の統合は、以前のツールバージョンでそのバージョンについて記載されているモデルでは、変更なしで動作します。Claude API上のClaude 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リファレンスAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。に記載されています。SDKを使用する場合は、betasを通じてヘッダーを渡し、ベータ名前空間を使用します。ヘッダーが必要なのはコンピューター使用ツールのみで、同じリクエスト内のbashツールやテキストエディターツールには不要です。

Amazon Bedrockでは、Claude Fable 5.2、Claude Mythos 5.2、Claude Opus 5.5、Claude Sonnet 5.5、およびClaude Haiku 5.5も、computer-use-2025-11-24ベータヘッダーとともにcomputer_20251124ツールを受け付けます。Amazon BedrockのInvokeModel APIを使用する場合は、computer-use-2025-11-24をヘッダーではなくリクエスト本文のanthropic_beta配列で送信してください。このAPIについては、Amazon Bedrock上のClaude（bedrock-runtime）を参照してください。

制限事項

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

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

データ保持

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

コンピューター使用のデータをどこにどのように保存するかはアプリケーションが制御するため、コンピューター使用はZDRの対象です。

料金

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

ツールセット定義のオーバーヘッド： 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に返されるツール実行結果

次のステップ

利用可能状況