Claude 3.7 Sonnet 和 Claude 3.5 Sonnet(新版)能夠與可以操作電腦桌面環境的工具互動。Claude 3.7 Sonnet 引入了額外的工具,並允許您啟用思考功能,讓您更深入了解模型的推理過程。

電腦使用是一項測試版功能。請注意,電腦使用會帶來與標準 API 功能或聊天介面不同的獨特風險。當使用電腦使用功能來與網際網路互動時,這些風險會更加顯著。為了降低風險,請考慮採取以下預防措施:

  1. 使用具有最小權限的專用虛擬機器或容器,以防止直接系統攻擊或意外。
  2. 避免讓模型存取敏感資料(如帳戶登入資訊),以防止資訊被盜。
  3. 將網際網路存取限制在允許清單中的域名,以減少接觸惡意內容的機會。
  4. 對於可能導致重要現實世界後果的決定,以及任何需要明確同意的任務(如接受 cookies、執行金融交易或同意服務條款),請讓人類進行確認。

在某些情況下,Claude 會遵循內容中的命令,即使這些命令與使用者的指示相衝突。例如,網頁上的 Claude 指令或圖片中包含的指令可能會覆蓋指示或導致 Claude 出錯。我們建議採取預防措施,將 Claude 與敏感資料和操作隔離,以避免與提示注入相關的風險。

我們已經訓練模型來抵抗這些提示注入,並增加了額外的防禦層。如果您使用我們的電腦使用工具,我們會自動對您的提示運行分類器,以標記潛在的提示注入實例。當這些分類器在截圖中識別出潛在的提示注入時,它們會自動引導模型在執行下一個動作之前請求使用者確認。我們認識到這種額外的保護並不適合每種使用情況(例如,沒有人在迴圈中的使用情況),所以如果您想要選擇退出並關閉它,請聯繫我們

我們仍然建議採取預防措施,將 Claude 與敏感資料和操作隔離,以避免與提示注入相關的風險。

最後,在您自己的產品中啟用電腦使用功能之前,請告知終端使用者相關風險並獲得他們的同意。

電腦使用參考實現

使用我們的電腦使用參考實現快速入門,其中包括網頁介面、Docker 容器、示例工具實現和代理迴圈。

注意: 該實現已更新,包含了 Claude 3.7 Sonnet 的新工具。請務必拉取最新版本的儲存庫以使用這些新功能。

請使用此表單提供關於模型回應品質、API 本身或文檔品質的反饋 - 我們迫不及待想聽到您的意見!

以下是如何使用 Messages API 為 Claude 提供電腦使用工具的示例:


電腦使用的工作原理

1. 為 Claude 提供電腦使用工具和使用者提示

  • 在您的 API 請求中添加 Anthropic 定義的電腦使用工具。
  • 包含可能需要這些工具的使用者提示,例如「將一張貓的圖片保存到我的桌面。」

2. Claude 決定使用工具

  • Claude 載入已儲存的電腦使用工具定義,並評估是否有工具可以幫助處理使用者的查詢。
  • 如果有,Claude 會構建一個格式正確的工具使用請求。
  • API 回應的 stop_reasontool_use,表示 Claude 的意圖。

3. 提取工具輸入,在電腦上評估工具,並返回結果

  • 在您的端點,從 Claude 的請求中提取工具名稱和輸入。
  • 在容器或虛擬機器上使用工具。
  • 使用包含 tool_result 內容區塊的新 user 訊息繼續對話。

4. Claude 繼續呼叫電腦使用工具,直到完成任務

  • Claude 分析工具結果,以確定是否需要更多工具使用或任務已完成。
  • 如果 Claude 決定需要另一個工具,它會以另一個 tool_use stop_reason 回應,您應該返回步驟 3。
  • 否則,它會為使用者製作文字回應。

我們將步驟 3 和 4 在沒有使用者輸入的情況下的重複稱為「代理迴圈」 - 即 Claude 以工具使用請求回應,而您的應用程式以評估該請求的結果回應 Claude。

計算環境

電腦使用需要一個沙箱計算環境,Claude 可以在其中安全地與應用程式和網路互動。這個環境包括:

  1. 虛擬顯示器:虛擬 X11 顯示伺服器(使用 Xvfb),Claude 可以通過截圖查看桌面介面並通過滑鼠/鍵盤動作控制。

  2. 桌面環境:在 Linux 上運行的輕量級 UI,帶有視窗管理器(Mutter)和面板(Tint2),為 Claude 提供一致的圖形介面。

  3. 應用程式:預先安裝的 Linux 應用程式,如 Firefox、LibreOffice、文字編輯器和檔案管理器,Claude 可以使用這些應用程式來完成任務。

  4. 工具實現:整合程式碼,將 Claude 的抽象工具請求(如「移動滑鼠」或「截圖」)轉換為虛擬環境中的實際操作。

  5. 代理迴圈:處理 Claude 與環境之間通信的程式,將 Claude 的動作發送到環境並將結果(截圖、命令輸出)返回給 Claude。

當您使用電腦使用功能時,Claude 不會直接連接到這個環境。相反,您的應用程式:

  1. 接收 Claude 的工具使用請求
  2. 將它們轉換為您的計算環境中的動作
  3. 捕獲結果(截圖、命令輸出等)
  4. 將這些結果返回給 Claude

為了安全和隔離,參考實現將所有這些都運行在一個 Docker 容器內,並具有適當的端口映射以查看和與環境互動。


如何實現電腦使用

從我們的參考實現開始

我們已經建立了一個參考實現,其中包含了您快速開始使用電腦使用所需的一切:

理解多代理迴圈

電腦使用的核心是「代理迴圈」 - 一個 Claude 請求工具動作、您的應用程式執行它們並將結果返回給 Claude 的循環。以下是一個簡化的示例:

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # 添加迭代限制以防止無限迴圈
):
    """
    一個簡單的 Claude 電腦使用互動代理迴圈。

    此函數處理以下來回:
    1. 向 Claude 發送使用者訊息
    2. Claude 請求使用工具
    3. 您的應用程式執行這些工具
    4. 將工具結果發送回 Claude
    """
    # 設置工具和 API 參數
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # 配置工具 - 您應該已經在其他地方初始化了這些
    tools = [
        {"type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"}
    ]

    # 主代理迴圈(帶有迭代限制以防止 API 成本失控)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # 設置可選的思考參數(用於 Claude 3.7 Sonnet)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # 呼叫 Claude API
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking
        )

        # 將 Claude 的回應添加到對話歷史中
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # 檢查 Claude 是否使用了任何工具
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # 在實際應用中,您會在這裡執行工具
                # 例如:result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # 為 Claude 格式化結果
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # 如果沒有使用工具,Claude 已完成 - 返回最終訊息
        if not tool_results:
            return messages

        # 將工具結果添加到訊息中,用於下一次與 Claude 的迭代
        messages.append({"role": "user", "content": tool_results})

迴圈會一直持續,直到 Claude 回應時沒有請求任何工具(任務完成)或達到最大迭代限制。這個保護措施可以防止可能導致意外 API 成本的潛在無限迴圈。

對於每個版本的工具,您必須在 API 請求中使用相應的測試版標誌:

我們建議在閱讀本文檔的其餘部分之前先試用參考實現。

使用提示優化模型性能

以下是一些如何獲得最佳品質輸出的提示:

  1. 指定簡單、明確定義的任務,並為每個步驟提供明確的指示。
  2. Claude 有時會在不明確檢查結果的情況下假設其動作的結果。為了防止這種情況,您可以用以下方式提示 Claude:在每個步驟之後,截圖並仔細評估您是否達到了正確的結果。明確展示您的思考:「我已評估步驟 X...」如果不正確,請重試。只有在您確認步驟已正確執行後才能繼續下一步。
  3. 某些 UI 元素(如下拉選單和滾動條)可能難以用滑鼠移動操作。如果遇到這種情況,請嘗試提示模型使用鍵盤快捷鍵。
  4. 對於可重複的任務或 UI 互動,在您的提示中包含成功結果的示例截圖和工具呼叫。
  5. 如果您需要模型登入,請在您的提示中使用 xml 標籤提供使用者名稱和密碼,如 <robot_credentials>。在需要登入的應用程式中使用電腦使用會增加由於提示注入而導致不良結果的風險。在提供模型登入憑證之前,請查看我們的防止提示注入指南

如果您反覆遇到一組明確的問題,或預先知道 Claude 需要完成的任務,請使用系統提示為 Claude 提供明確的提示或說明,以成功完成任務。

系統提示

當通過 Anthropic API 請求 Anthropic 定義的工具之一時,會生成一個特定於電腦使用的系統提示。它類似於工具使用系統提示,但以以下內容開始:

您可以使用一組函數來回答使用者的問題。這包括存取沙箱計算環境。您目前無法檢查檔案或與外部資源互動,除非通過調用以下函數。

與常規工具使用一樣,使用者提供的 system_prompt 欄位仍然受到尊重,並用於構建組合系統提示。

理解 Anthropic 定義的工具

作為測試版,這些工具定義可能會發生變化。

我們提供了一組工具,使 Claude 能夠有效地使用電腦。在指定 Anthropic 定義的工具時,不需要也不允許使用 descriptiontool_schema 欄位。

Anthropic 定義的工具由使用者執行

Anthropic 定義的工具由 Anthropic 定義,但您必須明確評估工具的結果並將 tool_results 返回給 Claude。與任何工具一樣,模型不會自動執行工具。

我們提供了一組 Anthropic 定義的工具,每個工具都有針對 Claude 3.5 Sonnet(新版)和 Claude 3.7 Sonnet 優化的版本:

type 欄位用於識別工具及其驗證參數,name 欄位是暴露給模型的工具名稱。

如果您想提示模型使用這些工具之一,您可以明確引用 name 欄位中的工具。name 欄位在工具列表中必須是唯一的;您不能在同一個 API 呼叫中定義一個與 Anthropic 定義的工具同名的工具。

我們不建議定義與 Anthropic 定義的工具同名的工具。雖然您仍然可以重新定義這些名稱的工具(只要工具名稱在您的 tools 區塊中是唯一的),但這樣做可能會導致模型性能下降。

在 Claude 3.7 Sonnet 中啟用思考功能

Claude 3.7 Sonnet 引入了一個新的「思考」功能,讓您可以看到模型在處理複雜任務時的推理過程。這個功能幫助您理解 Claude 如何處理問題,對於調試或教育目的特別有價值。

要啟用思考,請在您的 API 請求中添加 thinking 參數:

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

budget_tokens 參數指定 Claude 可以用於思考的令牌數。這會從您的總體 max_tokens 預算中扣除。

當啟用思考時,Claude 會在回應中包含其推理過程,這可以幫助您:

  1. 理解模型的決策過程
  2. 識別潛在的問題或誤解
  3. 從 Claude 的問題解決方法中學習
  4. 更好地了解複雜的多步驟操作

以下是思考輸出的示例:

[思考]
我需要將一張貓的圖片保存到桌面。讓我將這個任務分解為步驟:

1. 首先,我要截圖看看桌面上有什麼
2. 然後我要尋找網頁瀏覽器來搜索貓的圖片
3. 找到合適的圖片後,我需要將它保存到桌面

讓我先截圖看看有什麼可用的...

將電腦使用與其他工具結合

您可以將常規工具使用與 Anthropic 定義的電腦使用工具結合使用。

建立自定義電腦使用環境

參考實現旨在幫助您開始使用電腦使用功能。它包含了讓 Claude 使用電腦所需的所有組件。但是,您可以根據自己的需求建立自己的電腦使用環境。您需要:

  • 一個適合 Claude 電腦使用的虛擬化或容器化環境
  • 至少一個 Anthropic 定義的電腦使用工具的實現
  • 一個與 Anthropic API 互動並使用您的工具實現執行 tool_use 結果的代理迴圈
  • 一個允許使用者輸入以啟動代理迴圈的 API 或 UI

理解電腦使用的限制

電腦使用功能處於測試版階段。雖然 Claude 的功能處於前沿水平,但開發者應該意識到其限制:

  1. 延遲:目前的電腦使用延遲對於人機互動來說可能太慢,與常規的人類直接電腦操作相比。我們建議專注於速度不是關鍵的使用場景(例如,背景資訊收集、自動化軟體測試)在受信任的環境中。
  2. 電腦視覺準確性和可靠性:Claude 在生成動作時輸出特定座標時可能會出錯或產生幻覺。Claude 3.7 Sonnet 引入的思考功能可以幫助您理解模型的推理並識別潛在問題。
  3. 工具選擇準確性和可靠性:Claude 在生成動作時選擇工具可能會出錯或產生幻覺,或採取意外的動作來解決問題。此外,在與小眾應用程式或同時與多個應用程式互動時,可靠性可能較低。我們建議使用者在請求複雜任務時謹慎提示模型。
  4. 滾動可靠性:雖然 Claude 3.5 Sonnet(新版)在滾動方面有限制,但 Claude 3.7 Sonnet 引入了帶有方向控制的專用滾動動作,提高了可靠性。模型現在可以明確地向任何方向(上/下/左/右)滾動指定的數量。
  5. 電子表格互動:在 Claude 3.7 Sonnet 中,通過添加更精確的滑鼠控制動作(如 left_mouse_downleft_mouse_up)和新的修飾鍵支援,電子表格的滑鼠點擊已有改進。通過使用這些精細的控制和結合修飾鍵與點擊,單元格選擇可以更可靠。
  6. 在社交和通訊平台上創建帳戶和生成內容:雖然 Claude 會訪問網站,但我們限制其在社交媒體網站和平台上創建帳戶或生成和分享內容或以其他方式進行人類模仿的能力。我們可能會在未來更新這個功能。
  7. 漏洞:像越獄或提示注入這樣的漏洞可能會在前沿 AI 系統中持續存在,包括測試版電腦使用 API。在某些情況下,Claude 會遵循內容中的命令,有時甚至與使用者的指示相衝突。例如,網頁上的 Claude 指令或圖片中包含的指令可能會覆蓋指示或導致 Claude 出錯。我們建議: a. 將電腦使用限制在受信任的環境中,如具有最小權限的虛擬機器或容器 b. 避免在沒有嚴格監督的情況下讓電腦使用存取敏感帳戶或資料 c. 在您的應用程式中啟用或請求電腦使用功能所需的權限之前,告知終端使用者相關風險並獲得他們的同意
  8. 不當或非法動作:根據 Anthropic 的服務條款,您不得使用電腦使用功能違反任何法律或我們的可接受使用政策。

始終仔細審查和驗證 Claude 的電腦使用動作和日誌。在沒有人類監督的情況下,不要使用 Claude 執行需要完美精確度或敏感使用者資訊的任務。


定價

請參閱工具使用定價文檔,了解 Claude 工具使用 API 請求如何定價的詳細說明。

作為工具使用請求的一個子集,電腦使用請求的定價與任何其他 Claude API 請求相同。

我們還自動為模型包含一個特殊的系統提示,以啟用電腦使用。

模型工具選擇系統提示令牌數
Claude 3.5 Sonnet(新版)auto
any, tool
466 令牌
499 令牌
Claude 3.7 Sonnetauto
any, tool
466 令牌
499 令牌

除了基本令牌外,Anthropic 定義的工具還需要以下額外的輸入令牌:

工具額外輸入令牌
computer_20241022(Claude 3.5 Sonnet)683 令牌
computer_20250124(Claude 3.7 Sonnet)735 令牌
text_editor_20241022(Claude 3.5 Sonnet)700 令牌
text_editor_20250124(Claude 3.7 Sonnet)700 令牌
bash_20241022(Claude 3.5 Sonnet)245 令牌
bash_20250124(Claude 3.7 Sonnet)245 令牌

如果您在 Claude 3.7 Sonnet 中啟用思考,用於思考的令牌將根據您在思考參數中指定的 budget_tokens 計入您的 max_tokens 預算。