컴퓨터 사용 도구

Claude는 컴퓨터 사용 도구를 통해 컴퓨터 환경과 상호작용할 수 있습니다. 이 도구는 자율적인 데스크톱 상호작용을 위한 스크린샷 기능과 마우스/키보드 제어를 제공합니다.

컴퓨터 사용 도구는 Anthropic이 정의한 client toolset(클라이언트 도구 세트)입니다. tools에 {"type": "computer_toolset_20260801"} 항목 하나를 추가하면 Claude에게 screenshot, left_click, type, zoom 등 17개의 멤버 도구가 제공되며, 모든 호출은 여러분이 제어하는 환경에서 여러분의 애플리케이션이 실행합니다. 현재 Claude Managed Agents에서는 사용할 수 없습니다. Claude의 호출은 name이 멤버이고 "toolset_name": "computer"를 포함하는 tool_use 블록이며, 한 턴에 여러 개가 포함되는 경우가 많습니다(배치 액션).

웹페이지 내에서만 이루어지는 작업에는 브라우저 사용 도구가 더 적합합니다. 해당 도구의 멤버 도구는 페이지 자체를 읽고 조작하며, 전체 데스크톱 환경이 필요하지 않습니다.

보안 고려 사항

컴퓨터 사용에는 표준 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-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이며 하나 이상의 멤버 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 블록당 하나의 tool_result 블록을 반환한 다음 API를 다시 호출합니다. 컴퓨터 사용 작동 방식에서 이 루프를 설명하며, 이 페이지의 나머지 부분에서는 이를 구현하는 방법을 보여줍니다.

컴퓨터 사용 작동 방식

1. 1

   Claude에게 컴퓨터 사용 도구와 사용자 프롬프트 제공

   • API 요청의 tools 배열에 컴퓨터 사용 도구 세트(및 선택적으로 다른 도구)를 추가합니다.
   • 데스크톱 상호작용이 필요한 사용자 프롬프트를 포함합니다. 예: "고양이 사진을 내 데스크톱에 저장해 줘."
2. 2

   Claude가 멤버 도구 호출로 응답

   • Claude는 데스크톱에서 작업하는 것이 사용자의 질의에 도움이 될 수 있는지 평가합니다.
   • 도움이 된다면 Claude는 screenshot, left_click, type 등 하나 이상의 멤버 tool_use 블록으로 응답하며, 각 블록은 "toolset_name": "computer"를 포함합니다. 이러한 블록이 여러 개 포함된 응답이 배치 액션입니다.
   • API 응답의 stop_reason은 tool_use이며, 이는 도구 사용 요청을 나타냅니다.
3. 3

   호출을 순서대로 실행하고 결과 반환

   • 응답의 모든 tool_use 블록을 순서대로 반복합니다. 각 블록에 대해 멤버 name과 toolset_name을 함께 기준으로 디스패치하고, 블록의 input을 사용하여 컨테이너 또는 가상 머신에서 해당 작업을 수행합니다.
   • tool_use 블록당 하나의 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는 클릭, 입력, 스크린샷 촬영과 같은 짧은 작업 시퀀스를 계획하고 하나의 응답으로 함께 반환할 수 있습니다. 이를 "batch action"(배치 액션)이라고 합니다. 병렬 도구 사용과 동일한 응답 형태를 사용하지만 한 가지 차이점이 있습니다. 블록을 동시에 실행하는 것이 아니라 순서대로 실행합니다.

세 개의 작업으로 구성된 배치가 포함된 응답은 다음과 같습니다:

{
  "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 블록을 하나씩, 모두 다음 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로 거부되므로, 첫 번째 블록만 읽는 에이전트 루프는 다음 호출에서 실패합니다. 애플리케이션이 중대한 작업에 대해 사람에게 확인을 요청하는 경우, 배치가 한 턴 내에 다단계 작업을 완료할 수 있으므로 각 블록이 실행되기 전에 해당 확인을 수행하세요.

Claude는 일반적으로 다음에 무엇을 할지 결정하기 전에 결과를 관찰할 수 있도록 screenshot으로 배치를 마무리합니다. 배치가 스크린샷으로 끝나지 않는 경우, 애플리케이션이 배치의 마지막 결과에 추가 image 블록으로 스크린샷을 첨부하여 Claude가 항상 화면의 현재 상태를 볼 수 있도록 할 수 있습니다. 이렇게 하면 Claude가 요청할 때까지 기다리는 것에 비해 왕복 한 번을 절약할 수 있습니다. 또한 모든 배치를 스크린샷으로 끝내도록 Claude에게 프롬프트할 수도 있습니다(프롬프팅으로 모델 성능 최적화 참조).

컴퓨팅 환경

컴퓨터 사용에는 Claude가 애플리케이션 및 웹과 안전하게 상호작용할 수 있는 샌드박스 컴퓨팅 환경이 필요합니다. 이 환경에는 다음이 포함됩니다:

1. 가상 디스플레이: Claude가 스크린샷을 통해 보고 마우스/키보드 작업으로 제어할 데스크톱 인터페이스를 렌더링하는 가상 X11 디스플레이 서버(Xvfb 사용).

2. 데스크톱 환경: Linux에서 실행되는 윈도우 매니저(Mutter)와 패널(Tint2)을 갖춘 경량 UI로, Claude가 상호작용할 수 있는 일관된 그래픽 인터페이스를 제공합니다.

3. 애플리케이션: Claude가 작업을 완료하는 데 사용할 수 있는 Firefox, LibreOffice, 텍스트 편집기, 파일 관리자 등 사전 설치된 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

        # 모든 결과를 단일 user 메시지로 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. 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 배열의 도구 세트 항목은 네 가지 매개변수를 허용합니다. 브라우저 사용 도구 세트와 공유하는 규칙은 클라이언트 도구 세트에 나열되어 있습니다.

예를 들어, 이 항목은 zoom을 구현하지 않는 환경을 위해 이를 제외하고 도구 세트 정의에 캐시 중단점을 설정합니다:

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

에이전트 루프가 왕복당 하나의 작업만 실행할 수 있다면 tool_choice에서 disable_parallel_tool_use를 true로 설정하세요. 그러면 Claude는 턴당 최대 하나의 멤버 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 도구 및 텍스트 편집기 도구와 함께 이 패턴을 보여줍니다. 자체 사용자 정의 도구 정의도 같은 방식으로 추가할 수 있습니다.

웹페이지 내에서만 이루어지는 작업의 경우, 동일한 요청에서 브라우저 사용 도구를 선언할 수도 있습니다. 두 도구 세트는 각각 자체 좌표 프레임에서 독립적으로 작동하며, 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):
       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

   

   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

   에이전트 루프 구현

   앞의 두 단계를 결과를 다시 보내고 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,000–1,800 입력 토큰). API의 요청 제한도 적용됩니다. 단일 요청에 20개가 넘는 이미지가 포함되면, 그 안의 모든 이미지에 더 엄격한 변당 제한이 적용됩니다. 스크린샷 기록을 유지하는 루프는 수십 턴 안에 그 개수에 도달하므로, 각 스크린샷의 어느 변도 2000 px를 넘지 않도록 크기를 조정하거나 오래된 스크린샷을 정리하여 요청 내 이미지를 20개 이하로 유지하세요.

컨텍스트를 제한하면서 프롬프트 캐싱(prompt caching)의 효과를 유지하려면 다음을 따르세요.

• 시스템 프롬프트와 도구 정의 뒤에 cache_control 중단점을 하나 배치하고, 가장 최근 턴들 각각의 마지막 tool_result 블록에 최대 세 개를 더 배치한 뒤 매 턴마다 이를 앞으로 이동하세요. 배치 액션 내에서는 여러 블록에 있는 마커가 하나의 중단점으로 동작하지만 각각이 여전히 네 개 제한에 포함되므로, 턴당 하나만 사용하세요.
• 오래된 스크린샷은 매 턴 하나씩이 아니라 일괄적으로 정리하세요. 매 턴 스크린샷을 하나씩 제거하면 매 턴 접두사가 바뀌어 캐시가 무효화됩니다. 합리적인 기본값은 마지막 세 개의 스크린샷을 유지하고 25턴마다 정리하는 것이며, 이렇게 하면 정리 시점 사이에 접두사가 바이트 단위로 동일하게 유지됩니다. 스크린샷의 어느 한 변이라도 2000 px를 초과한다면, 각 요청이 20개 이하의 이미지를 유지하도록 간격을 선택하세요.
• Claude Fable 5.1 및 Claude Opus 5.5에서는 클라이언트 측 정리를 피하세요. 이전 스크린샷을 제거하면 해당 턴들을 여전히 포함하는 모든 요청에서 이후의 모든 사고 블록이 무효화됩니다. 대신 스크린샷을 변당 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용으로 나열된 모델은 해당 베타 헤더와 함께 이를 계속 허용하므로, 기존 통합은 변경하기 전까지 계속 작동합니다. 단, Claude API 및 Google Cloud에서 Claude 5.5 이상 모델은 예외로, 도구 세트만 허용합니다. 통합을 이러한 모델 중 하나로 옮기기 전에 업그레이드하세요. Amazon Bedrock에서는 Claude Opus 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. zoom을 활성화 상태로 유지할지 선택하세요. 툴셋에서는 zoom이 기본적으로 활성화되어 있는 반면, enable_zoom의 기본값은 false입니다. 환경에서 zoom을 구현하지 않는다면 "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를 턴당 하나의 액션으로 제한하는 방법을 설명합니다.
6. 결과에 toolset_name을 반영하세요. 멤버 호출에 응답하는 모든 tool_result에 "toolset_name": "computer"를 추가하세요. 결과에는 text 및 image 콘텐츠만 포함될 수 있습니다.
7. key에서 repeat를 지원하세요. key 멤버는 1에서 100까지의 선택적 repeat 횟수를 수락합니다. 인식되지 않는 필드를 무시하는 핸들러는 키를 한 번만 누르게 되므로, key 핸들러가 repeat를 준수하도록 만드세요.
8. 스크린샷 크기를 직접 조정하세요. 툴셋은 모델의 이미지 제한을 초과하는 스크린샷이나 zoom 이미지를 다운스케일링하는 대신 거부합니다. 이미지를 반환하기 전에 크기를 조정하고, 이미지 제한에 맞게 스크린샷 크기 조정에 설명된 대로 좌표 스케일링을 계속하세요.
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을 설정하지 않은 이전 항목과 일치하도록 zoom을 꺼 둡니다. 기본값을 수락하고 Claude가 zoom을 사용하도록 하려면 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] }
}

이전 도구 버전

컴퓨터 사용 도구의 두 가지 이전 버전은 기존 통합, 툴셋을 지원하지 않는 모델, 그리고 현재 툴셋을 사용할 수 없는 플랫폼을 위해 베타로 계속 제공됩니다. 각각은 모든 요청에 해당 베타 헤더가 필요하며, 매개변수는 베타 Messages API 레퍼런스에 문서화되어 있습니다. SDK에서는 betas 매개변수를 통해 헤더를 전달하고 베타 네임스페이스를 사용하세요. 헤더는 컴퓨터 사용 도구에만 필요하며, 같은 요청의 bash 또는 텍스트 편집기 도구에는 필요하지 않습니다.

제한 사항

1. Latency(지연 시간): 현재 인간-AI 상호작용에서의 컴퓨터 사용 latency는 일반적인 인간 주도 컴퓨터 액션에 비해 너무 느릴 수 있습니다. 신뢰할 수 있는 환경에서 속도가 중요하지 않은 사용 사례(예: 백그라운드 정보 수집, 자동화된 소프트웨어 테스트)에 집중하세요.
2. 컴퓨터 비전 정확도 및 신뢰성: Claude는 액션을 생성하면서 특정 좌표를 출력할 때 실수하거나 환각을 일으킬 수 있습니다. Claude의 요약된 사고 출력은 모델의 추론을 이해하고 잠재적 문제를 식별하는 데 도움이 될 수 있습니다. 툴셋을 지원하는 모델은 기본적으로 사고 텍스트를 생략하므로, 사고 구성에서 display: "summarized"를 설정하세요.
3. 도구 선택 정확도 및 신뢰성: Claude는 액션을 생성하면서 도구를 선택할 때 실수하거나 환각을 일으킬 수 있으며, 문제를 해결하기 위해 예상치 못한 액션을 취할 수 있습니다. 또한 틈새 애플리케이션이나 여러 애플리케이션과 동시에 상호작용할 때 신뢰성이 낮아질 수 있습니다. 복잡한 작업을 요청할 때는 모델에 신중하게 프롬프트를 작성하세요.
4. 스크롤 신뢰성: 스크롤 액션은 방향 제어(위, 아래, 왼쪽, 오른쪽)와 지정된 양을 지원합니다. 스크롤이 적용되지 않는 애플리케이션에서는 Page Down과 같은 키보드 대안이 도움이 될 수 있습니다.
5. 스프레드시트 상호작용: 개별 셀을 선택하려면 세밀한 마우스 제어 액션(left_mouse_down, left_mouse_up)과 수정자 키 조합을 사용하세요. 복잡한 스프레드시트 작업은 여전히 여러 번의 시도가 필요할 수 있습니다.
6. 소셜 및 커뮤니케이션 플랫폼에서의 계정 생성 및 콘텐츠 생성: Claude가 웹사이트를 방문하기는 하지만, 소셜 미디어 웹사이트 및 플랫폼 전반에서 계정을 생성하거나, 콘텐츠를 생성 및 공유하거나, 기타 방식으로 인간을 사칭하는 능력은 제한되어 있습니다.
7. 취약점: 탈옥(jailbreak)과 프롬프트 인젝션은 웹페이지나 이미지에 포함된 지시를 통하는 경우를 포함하여, 모든 프런티어 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_toolset_20260801이 아닌 computer_20251124 및 computer_20250124 도구 버전에 적용됩니다:

• 시스템 프롬프트 오버헤드: 시스템 프롬프트에 466–499개의 토큰 추가
• 도구 정의: 도구 정의당 약 735개의 입력 토큰(computer_20250124로 측정)

추가 토큰 소비:

• 도구 결과로 반환되는 스크린샷 및 확대 이미지는 이미지 입력으로 청구됩니다(비전 가격 참조)
• Claude에 반환되는 도구 실행 결과

다음 단계

Compatibility