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

電腦使用是一項測試版功能。請注意,電腦使用會帶來與標準 API 功能或聊天界面不同的獨特風險。當使用電腦使用功能來訪問互聯網時,這些風險會更高。為了最小化風險,請考慮採取以下預防措施:

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

在某些情況下,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 Tool Use 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 預算中扣除。