Claude 3.7 Sonnet과 Claude 3.5 Sonnet (신규)는 컴퓨터 데스크톱 환경을 조작할 수 있는 도구와 상호작용할 수 있습니다. Claude 3.7 Sonnet은 추가 도구를 도입하고 사고 기능을 활성화하여 모델의 추론 과정에 대한 더 많은 통찰력을 제공합니다.

컴퓨터 사용은 베타 기능입니다. 컴퓨터 사용은 표준 API 기능이나 채팅 인터페이스와는 다른 고유한 위험이 있다는 점을 유의하시기 바랍니다. 이러한 위험은 인터넷과 상호작용하는 컴퓨터 사용 시 더욱 높아집니다. 위험을 최소화하기 위해 다음과 같은 예방 조치를 고려하세요:

  1. 직접적인 시스템 공격이나 사고를 방지하기 위해 최소한의 권한을 가진 전용 가상 머신이나 컨테이너를 사용하세요.
  2. 정보 도난을 방지하기 위해 계정 로그인 정보와 같은 민감한 데이터에 대한 접근 권한을 모델에 제공하지 마세요.
  3. 악성 콘텐츠에 대한 노출을 줄이기 위해 인터넷 접근을 허용 목록의 도메인으로 제한하세요.
  4. 쿠키 수락, 금융 거래 실행, 서비스 약관 동의와 같이 적극적인 동의가 필요한 작업뿐만 아니라 실제 세계에서 의미 있는 결과를 초래할 수 있는 결정에 대해서는 사람의 확인을 요청하세요.

일부 상황에서는 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. 가상 디스플레이: 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 컨테이너 내부에서 실행합니다.


컴퓨터 사용 구현 방법

참조 구현으로 시작하기

컴퓨터 사용을 빠르게 시작하는 데 필요한 모든 것이 포함된 참조 구현을 만들었습니다:

멀티 에이전트 루프 이해하기

컴퓨터 사용의 핵심은 “에이전트 루프” - 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": "도구가 성공적으로 실행됨"}
                
                # 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. 모델이 로그인해야 하는 경우, <robot_credentials> XML 태그 안에 사용자 이름과 비밀번호를 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션에서 컴퓨터 사용을 하면 프롬프트 주입으로 인한 나쁜 결과의 위험이 증가합니다. 로그인 자격 증명을 모델에 제공하기 전에 프롬프트 주입 완화 가이드를 검토하시기 바랍니다.

반복적으로 명확한 문제 세트가 발생하거나 Claude가 완료해야 할 작업을 미리 알고 있는 경우, 시스템 프롬프트를 사용하여 작업을 성공적으로 수행하는 방법에 대한 명시적인 팁이나 지시사항을 Claude에 제공하세요.

시스템 프롬프트

Anthropic이 정의한 도구 중 하나가 Anthropic API를 통해 요청되면 컴퓨터 사용 관련 시스템 프롬프트가 생성됩니다. 이는 도구 사용 시스템 프롬프트와 비슷하지만 다음과 같이 시작됩니다:

사용자의 질문에 답하는 데 사용할 수 있는 함수 세트에 액세스할 수 있습니다. 여기에는 샌드박스 컴퓨팅 환경에 대한 액세스가 포함됩니다. 현재 아래 함수를 호출하는 것을 제외하고는 파일을 검사하거나 외부 리소스와 상호작용할 수 있는 기능이 없습니다.

일반적인 도구 사용과 마찬가지로 사용자가 제공한 system_prompt 필드는 여전히 존중되며 결합된 시스템 프롬프트 구성에 사용됩니다.

Anthropic이 정의한 도구 이해하기

베타 버전이므로 이러한 도구 정의는 변경될 수 있습니다.

Claude가 컴퓨터를 효과적으로 사용할 수 있게 하는 도구 세트를 제공했습니다. Anthropic이 정의한 도구를 지정할 때 descriptiontool_schema 필드는 필요하지 않거나 허용되지 않습니다.

Anthropic이 정의한 도구는 사용자가 실행

Anthropic이 정의한 도구는 Anthropic이 정의하지만 도구의 결과를 명시적으로 평가하고 tool_results를 Claude에 반환해야 합니다. 다른 도구와 마찬가지로 모델이 자동으로 도구를 실행하지 않습니다.

Claude 3.5 Sonnet (신규)와 Claude 3.7 Sonnet 모두에 최적화된 버전이 있는 Anthropic이 정의한 도구 세트를 제공합니다:

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. 복잡한 다단계 작업에 대한 더 많은 가시성 확보

다음은 사고 출력의 예시입니다:

[Thinking]
데스크톱에 고양이 사진을 저장해야 합니다. 이를 단계별로 나누어 보겠습니다:

1. 먼저 데스크톱에 무엇이 있는지 보기 위해 스크린샷을 찍습니다
2. 그런 다음 고양이 이미지를 검색할 웹 브라우저를 찾습니다
3. 적절한 이미지를 찾은 후 데스크톱에 저장해야 합니다

스크린샷을 찍어 무엇이 있는지 보겠습니다...

컴퓨터 사용과 다른 도구 결합하기

일반 도구 사용을 컴퓨터 사용을 위한 Anthropic이 정의한 도구와 결합할 수 있습니다.

사용자 지정 컴퓨터 사용 환경 구축하기

참조 구현은 컴퓨터 사용을 시작하는 데 도움을 주기 위한 것입니다. Claude가 컴퓨터를 사용하는 데 필요한 모든 구성 요소가 포함되어 있습니다. 그러나 필요에 맞게 자체 컴퓨터 사용 환경을 구축할 수 있습니다. 다음이 필요합니다:

  • Claude와 함께 컴퓨터 사용에 적합한 가상화되거나 컨테이너화된 환경
  • Anthropic이 정의한 컴퓨터 사용 도구 중 하나 이상의 구현
  • Anthropic API와 상호작용하고 도구 구현을 사용하여 tool_use 결과를 실행하는 에이전트 루프
  • 에이전트 루프를 시작하기 위한 사용자 입력을 허용하는 API 또는 UI

컴퓨터 사용 제한 사항 이해하기

컴퓨터 사용 기능은 베타 버전입니다. Claude의 기능이 최첨단이지만 개발자는 다음과 같은 제한 사항을 알아야 합니다:

  1. 지연 시간: 현재 인간-AI 상호작용을 위한 컴퓨터 사용 지연 시간은 일반적인 인간 지시 컴퓨터 작업에 비해 너무 느릴 수 있습니다. 신뢰할 수 있는 환경에서 속도가 중요하지 않은 사용 사례(예: 백그라운드 정보 수집, 자동화된 소프트웨어 테스트)에 집중하는 것을 권장합니다.
  2. 컴퓨터 비전 정확도 및 신뢰성: Claude는 작업을 생성하는 동안 특정 좌표를 출력할 때 실수를 하거나 환각을 일으킬 수 있습니다. Claude 3.7 Sonnet은 모델의 추론을 이해하고 잠재적인 문제를 식별하는 데 도움이 되는 사고 기능을 도입합니다.
  3. 도구 선택 정확도 및 신뢰성: Claude는 작업을 생성하는 동안 도구를 선택할 때 실수를 하거나 환각을 일으킬 수 있으며 문제를 해결하기 위해 예상치 못한 작업을 수행할 수 있습니다. 또한 틈새 애플리케이션이나 여러 애플리케이션을 동시에 사용할 때 신뢰성이 낮을 수 있습니다. 복잡한 작업을 요청할 때 사용자가 모델을 신중하게 프롬프트하는 것을 권장합니다.
  4. 스크롤 신뢰성: Claude 3.5 Sonnet (신규)는 스크롤에 제한이 있었지만 Claude 3.7 Sonnet은 방향 제어가 있는 전용 스크롤 작업을 도입하여 신뢰성을 향상시켰습니다. 이제 모델은 지정된 양만큼 모든 방향(위/아래/왼쪽/오른쪽)으로 명시적으로 스크롤할 수 있습니다.
  5. 스프레드시트 상호작용: Claude 3.7 Sonnet에서는 left_mouse_down, left_mouse_up과 같은 더 정밀한 마우스 제어 작업과 새로운 수정자 키 지원의 추가로 스프레드시트 상호작용을 위한 마우스 클릭이 개선되었습니다. 이러한 세밀한 제어를 사용하고 수정자 키를 클릭과 결합하여 셀 선택의 신뢰성을 높일 수 있습니다.
  6. 소셜 및 커뮤니케이션 플랫폼에서의 계정 생성 및 콘텐츠 생성: Claude는 웹사이트를 방문하지만 소셜 미디어 웹사이트와 플랫폼에서 계정을 만들거나 콘텐츠를 생성하고 공유하거나 다른 방식으로 인간 사칭에 참여하는 능력을 제한하고 있습니다. 향후 이 기능을 업데이트할 수 있습니다.
  7. 취약점: 베타 컴퓨터 사용 API를 포함한 프론티어 AI 시스템에서는 탈옥이나 프롬프트 주입과 같은 취약점이 지속될 수 있습니다. 일부 상황에서는 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 예산에서 차감됩니다.