---
title: 컴퓨터 사용 도구
url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool
description: computer_toolset_20260801 클라이언트 도구 세트인 컴퓨터 사용 도구를 사용하여 Claude에게 데스크톱 환경의 스크린샷, 마우스 및 키보드 제어 권한을 부여하세요.
featureMetadata:
betaHeader: computer-use-2025-11-24, computer-use-2025-01-24
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). 스크린샷과 파일이 Anthropic이 아닌 사용자 환경에서 캡처되고 저장되는 클라이언트 측 도구입니다.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Amazon Bedrock: stable
Amazon Bedrock (InvokeModel): beta
Claude Models on Google Cloud (Google managed): stable
Microsoft Foundry: stable
details:
- Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 및 Claude Haiku 5.5는 `computer_toolset_20260801` 도구 세트를 통해 컴퓨터 사용을 지원합니다. 이러한 모델은 Claude API의 `computer_20251124`처럼 허용하지 않는 컴퓨터 사용 도구 버전에 대해 400 오류를 반환합니다. `computer_20251124` 통합을 도구 세트로 옮기려면 [`computer_20251124`에서 마이그레이션](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)을 참조하세요. `computer_20250124`에서 옮기려면 Claude Haiku 5.5 마이그레이션 가이드의 [컴퓨터 사용을 도구 세트로 이전](https://platform.claude.com/docs/ko/models/haiku-5-5/migration-guide#computer-use-toolset)을 참조하세요.
- Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 및 Claude Opus 4.5는 베타 헤더가 필요한 `computer_20251124` 도구 버전을 통해서만 컴퓨터 사용을 지원합니다. [이전 도구 버전](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions)을 참조하세요.
---
**SDK 도구 세트로 시작하세요:** `computer_toolset_20260801`의 경우 Python 및 TypeScript SDK에 베타로 제공되는 컴퓨터 도구 세트 클래스가 있습니다. [파트너 통합](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-sdk#partner-integrations)에서 시작하거나, SDK 도구 세트 페이지의 [컴퓨터 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-sdk#computer-toolset) 섹션을 참조하세요. 이 페이지는 도구 레퍼런스로 사용하거나, 도구 호출을 직접 처리할 때 사용하세요.
Claude는 “computer use”(컴퓨터 사용) 도구를 통해 컴퓨터 환경과 상호작용할 수 있으며, 이 도구는 자율적인 데스크톱 상호작용을 위한 스크린샷 기능과 마우스/키보드 제어를 제공합니다.
컴퓨터 사용 도구는 Anthropic이 정의한 [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets)입니다. `tools`에 `{"type": "computer_toolset_20260801"}` 항목 하나를 추가하면 Claude는 `screenshot`, `left_click`, `type`, `zoom` 같은 17개의 멤버 도구를 사용할 수 있으며, 애플리케이션은 모든 호출을 사용자가 제어하는 환경에서 실행합니다. 현재 [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/tools)에서는 사용할 수 없습니다. Claude의 호출은 `name`이 멤버 이름이고 `"toolset_name": "computer"`를 포함하는 `tool_use` 블록이며, 한 턴에 여러 개가 포함되는 경우가 많습니다([배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions)).
웹페이지 내에서만 이루어지는 작업에는 [브라우저 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool)가 더 적합합니다. 이 도구의 멤버 도구는 페이지 자체를 읽고 조작하며, 완전한 데스크톱 환경이 필요하지 않습니다.
도구 세트를 지원하는 모델과 플랫폼은 [API 지원](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#availability-feature-support)을 참조하세요. [이전 도구 버전](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions)에는 각 이전 버전의 베타 헤더와 함께 사용할 모델이 나와 있습니다.
## 보안 고려 사항
컴퓨터 사용에는 표준 API 기능과는 다른 고유한 위험이 있습니다. 이러한 위험은 인터넷과 상호작용할 때 더욱 커집니다.
위험을 최소화하려면 다음과 같은 예방 조치를 고려하세요:
1. 직접적인 시스템 공격이나 사고를 방지하기 위해 최소 권한을 가진 전용 가상 머신이나 컨테이너를 사용합니다.
2. 정보 도용을 방지하기 위해 계정 로그인 정보와 같은 민감한 데이터에 모델이 접근하지 못하도록 합니다.
3. 악성 콘텐츠에 대한 노출을 줄이기 위해 인터넷 접근을 허용 목록의 도메인으로 제한합니다.
4. 실제 세계에 의미 있는 결과를 초래할 수 있는 결정이나, 쿠키 수락, 금융 거래 완료, 서비스 약관 동의와 같이 명시적인 동의가 필요한 작업은 사람에게 확인을 요청합니다.
경우에 따라 Claude는 사용자의 지시와 충돌하더라도 콘텐츠에서 발견한 명령을 따릅니다. 예를 들어, 웹페이지의 지시나 이미지에 포함된 지시가 사용자의 지시를 무시하게 하거나 Claude가 실수하도록 만들 수 있습니다. “prompt injection”(프롬프트 인젝션)과 관련된 위험을 피하기 위해 Claude를 민감한 데이터와 작업으로부터 격리하는 예방 조치를 취하세요.
Anthropic은 이러한 프롬프트 인젝션에 저항하도록 모델을 학습시켰으며, 추가적인 방어 계층을 더했습니다. 컴퓨터 사용 도구를 사용하면 분류기가 스크린샷과 같은 도구 반환 결과를 자동으로 검사하여 잠재적인 프롬프트 인젝션을 표시합니다. 이러한 분류기가 잠재적인 프롬프트 인젝션을 식별하면, 모델이 해당 지시에 따라 행동하기 전에 그 지시가 실제로 사용자로부터 온 것인지 확인하도록 유도합니다.
이 추가 보호 기능은 모든 사용 사례에 이상적이지는 않으므로(예: 사람이 개입하지 않는 사용 사례), 이를 선택 해제하고 끄려면 [지원팀에 문의](https://support.claude.com/en/)하세요. 이러한 분류기가 있더라도 앞서 나열한 예방 조치는 여전히 중요합니다.
자체 제품에서 컴퓨터 사용을 활성화하기 전에 최종 사용자에게 관련 위험을 알리고 동의를 받으세요.
## 빠른 시작
[Messages API](https://platform.claude.com/docs/ko/api/messages/create) 요청의 `tools` 배열에 컴퓨터 사용 도구 세트를 `{"type": "computer_toolset_20260801"}`로 추가하세요. 이 요청에는 베타 헤더가 필요하지 않습니다. 이 예제는 Claude가 일반적으로 컴퓨터 사용과 함께 사용하는 [텍스트 편집기 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/text-editor-tool)와 [bash 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/bash-tool)도 선언합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"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."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
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.
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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." }]
});
console.log(response);
```
```csharp C#
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ComputerToolset20260801(),
new ToolTextEditor20250728(),
new ToolBash20250124(),
],
Messages = [new UserMessageParam { Content = "Save a picture of a cat to my desktop." }],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
{OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Save a picture of a cat to my desktop.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.ComputerToolset20260801;
// ...
import com.anthropic.models.messages.ToolBash20250124;
import com.anthropic.models.messages.ToolTextEditor20250728;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(ComputerToolset20260801.builder().build())
.addTool(ToolTextEditor20250728.builder().build())
.addTool(ToolBash20250124.builder().build())
.addUserMessage("Save a picture of a cat to my desktop.")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'Save a picture of a cat to my desktop.'],
],
model: Model::CLAUDE_OPUS_5_5,
tools: [
['type' => 'computer_toolset_20260801'],
[
'type' => 'text_editor_20250728',
'name' => 'str_replace_based_edit_tool',
],
[
'type' => 'bash_20250124',
'name' => 'bash',
],
],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: Anthropic::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." }
]
)
puts response
```
Claude가 데스크톱에서 작업을 수행할 때, 응답의 `stop_reason`은 `tool_use`이며 하나 이상의 멤버 `tool_use` 블록을 포함하고, 각 블록은 멤버 도구의 이름을 지정하고 `"toolset_name": "computer"`를 포함합니다. 이 작업 도중 Claude가 데스크톱 스크린샷을 받은 후의 응답은 다음과 같을 수 있습니다:
```json Output
{
"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를 다시 호출합니다. [컴퓨터 사용의 작동 방식](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#how-computer-use-works)에서 이 루프를 설명하며, 이 페이지의 나머지 부분에서 이를 구현하는 방법을 보여줍니다.
***
## 컴퓨터 사용의 작동 방식
* API 요청의 `tools` 배열에 컴퓨터 사용 도구 세트(및 선택적으로 다른 도구)를 추가합니다.
* 데스크톱 상호작용이 필요한 사용자 프롬프트를 포함합니다. 예: "고양이 사진을 내 데스크톱에 저장해 줘."
* Claude는 데스크톱에서 작업을 수행하는 것이 사용자의 질의에 도움이 되는지 평가합니다.
* 그렇다면 Claude는 `screenshot`, `left_click`, `type` 같은 하나 이상의 멤버 `tool_use` 블록으로 응답하며, 각 블록은 `"toolset_name": "computer"`를 포함합니다. 이러한 블록이 여러 개 포함된 응답이 [배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions)입니다.
* API 응답의 `stop_reason`은 `tool_use`이며, 이는 도구 사용 요청을 나타냅니다.
* 응답의 모든 `tool_use` 블록을 순서대로 순회합니다. 각 블록에 대해 멤버 `name`과 `toolset_name`을 함께 기준으로 분기하고, 블록의 `input`으로 컨테이너나 가상 머신에서 해당 작업을 수행합니다.
* 각 `tool_use` 블록마다 하나의 `tool_result` 블록을 포함하는 새 `user` 메시지로 대화를 이어갑니다. 각 결과는 `tool_use_id`로 매칭되며 `"toolset_name": "computer"`를 그대로 포함합니다. `screenshot`과 `zoom`에는 이미지를 반환하고, 다른 작업에는 `OK` 같은 짧은 텍스트로 충분합니다.
* 작업이 실패하면 해당 블록에 `is_error: true`를 반환하고, 배치의 나머지 블록에는 [배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions)에 설명된 대로 응답합니다.
* Claude는 도구 결과를 분석하여 추가 작업이 필요한지 또는 작업이 완료되었는지 판단합니다.
* 추가 작업이 필요하다고 판단하면 Claude는 다시 `tool_use` `stop_reason`으로 응답합니다. 3단계로 돌아가세요.
* 그렇지 않으면 사용자에게 텍스트 응답을 반환합니다.
사용자 입력 없이 3단계와 4단계를 반복하는 것을 “agent loop”(에이전트 루프)라고 합니다. 즉, Claude가 도구 사용 요청으로 응답하고, 애플리케이션이 해당 요청을 평가한 결과로 Claude에게 응답하는 것입니다.
### 배치 작업
Claude는 클릭, 입력, 스크린샷 촬영과 같은 짧은 작업 시퀀스를 계획하여 하나의 응답에 함께 반환할 수 있습니다. 이를 “batch action”(배치 작업)이라고 합니다. 이는 [병렬 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/parallel-tool-use)과 동일한 응답 형태를 사용하지만 한 가지 차이가 있습니다. 블록을 동시에 실행하는 대신 순서대로 실행합니다.
세 가지 작업으로 구성된 배치가 포함된 응답은 다음과 같습니다:
```json
{
"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`은 좌표를 텍스트로 반환합니다):
```json
{
"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`를 반환합니다(브라우저 사용 도구는 자체 [중단 텍스트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool#batch-actions)를 사용합니다):
```json
{
"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에게 모든 배치를 스크린샷으로 마치도록 프롬프트할 수도 있습니다([프롬프트로 모델 성능 최적화](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting) 참조).
### 컴퓨팅 환경
컴퓨터 사용에는 Claude가 애플리케이션 및 웹과 안전하게 상호작용할 수 있는 샌드박스 컴퓨팅 환경이 필요합니다. 이 환경에는 다음이 포함됩니다:
1. **가상 디스플레이:** Claude가 스크린샷으로 받고 마우스/키보드 작업으로 제어하는 데스크톱 인터페이스를 렌더링하는 가상 X11 디스플레이 서버(Xvfb 사용).
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`에서 마이그레이션](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)부터 시작하세요. 이 섹션의 나머지 내용은 새 통합과 마이그레이션된 통합 모두에 적용됩니다.
[컴퓨터 사용 레퍼런스 구현](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo)은 완전히 작동하는 예제입니다. 여기에는 컴퓨터 사용에 적합한 [컨테이너화된 환경](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/Dockerfile), [컴퓨터 사용 도구](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools)의 구현, Claude API를 호출하고 도구를 실행하는 [에이전트 루프](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py), 그리고 컨테이너, 루프, 도구를 위한 웹 인터페이스가 포함되어 있습니다. `computer_toolset_20260801`을 사용하려면 [이를 지원하는 모델](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#availability-feature-support)을 선택한 다음, 웹 인터페이스 사이드바의 **Tool Versions**에서 도구 세트를 선택하세요.
### 에이전트 루프 이해하기
컴퓨터 사용의 핵심은 "에이전트 루프"입니다. 이는 Claude가 도구 작업을 요청하고, 애플리케이션이 이를 실행하여 결과를 Claude에게 반환하는 주기입니다. 이 루프는 [빠른 시작](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#quick-start)에서 만든 클라이언트, 컴퓨터 사용 도구 세트만 선언하는 `tools` 배열, 그리고 [컴퓨터 사용 도구 구현](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#implement-the-computer-use-tool)에 있는 도구 호출 처리 헬퍼를 사용합니다. 빠른 시작의 bash 및 텍스트 편집기 도구처럼 다른 도구도 선언한다면, 같은 처리 과정에서 해당 `tool_use` 블록도 분기하여 처리하세요. 헬퍼는 컴퓨터 사용 멤버 호출에만 응답하며, 루프는 응답한 호출이 없는 턴을 완료된 것으로 간주합니다. 다음은 간단한 예제입니다:
```python Python
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
```
```typescript TypeScript
async function samplingLoop(
model: string,
messages: Anthropic.MessageParam[],
maxIterations = 10
): Promise {
// Claude가 도구 요청을 멈추거나 반복 한도에 도달할 때까지
// 컴퓨터 사용 에이전트 루프를 실행합니다.
for (let i = 0; i < maxIterations; i++) {
const response = await client.messages.create({
model,
max_tokens: 4096,
messages,
tools
});
// Claude의 응답을 대화 기록에 추가합니다
messages.push({ role: "assistant", content: response.content });
// Claude가 요청한 도구를 실행하고 결과를 수집합니다
const toolResults = processToolCalls(response);
if (toolResults.length === 0) {
return messages; // No more tool use; task complete
}
// 다음 반복을 위해 도구 결과를 Claude에게 다시 보냅니다
messages.push({ role: "user", content: toolResults });
}
return messages;
}
```
```csharp C#
async Task> SamplingLoop(
Model model,
List messages,
int maxIterations = 10
)
{
// Claude가 도구 요청을 멈추거나 반복 한도에 도달할 때까지
// 컴퓨터 사용 에이전트 루프를 실행합니다.
for (var i = 0; i < maxIterations; i++)
{
var response = await client.Messages.Create(
new MessageCreateParams
{
Model = model,
MaxTokens = 4096,
Messages = messages,
Tools = tools,
}
);
// Claude의 응답을 대화 기록에 추가합니다
messages.Add(
new AssistantMessageParam
{
Content = response
.Content.Select(block => new ContentBlockParam(block.Json))
.ToList(),
}
);
// Claude가 요청한 도구를 실행하고 결과를 수집합니다
var toolResults = ProcessToolCalls(response);
if (toolResults.Count == 0)
{
return messages; // No more tool use; task complete
}
// 다음 반복을 위해 도구 결과를 Claude에 다시 보냅니다
messages.Add(new UserMessageParam { Content = toolResults });
}
return messages;
}
```
```go Go
// samplingLoop는 Claude가 도구 요청을 멈추거나
// 반복 한도에 도달할 때까지 컴퓨터 사용 에이전트 루프를 실행합니다.
func samplingLoop(ctx context.Context, model anthropic.Model, messages []anthropic.MessageParam, maxIterations int) ([]anthropic.MessageParam, error) {
for range maxIterations {
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: model,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
return nil, err
}
// Claude의 응답을 대화 기록에 추가합니다
messages = append(messages, response.ToParam())
// Claude가 요청한 액션을 순서대로 실행하고 결과를 수집합니다
toolResults := processToolCalls(response)
if len(toolResults) == 0 {
return messages, nil // No more tool use; task complete
}
// 모든 결과를 단일 user 메시지로 Claude에 다시 보냅니다
messages = append(messages, anthropic.NewUserMessage(toolResults...))
}
return messages, nil
}
```
```java Java
/**
* Run the computer-use agent loop until Claude stops requesting tools
* or the iteration limit is reached.
*/
List samplingLoop(Model model, List messages, int maxIterations) {
for (int i = 0; i < maxIterations; i++) {
Message response = client.messages().create(MessageCreateParams.builder()
.model(model)
.maxTokens(4096)
.messages(messages)
.addTool(COMPUTER_TOOLSET)
.build());
// Claude의 응답을 대화 기록에 추가합니다
messages.add(response.toParam());
// Claude가 요청한 도구를 실행하고 결과를 수집합니다
List toolResults = processToolCalls(response);
if (toolResults.isEmpty()) {
return messages; // No more tool use; task complete
}
// 다음 반복을 위해 도구 결과를 Claude에 다시 전송합니다
messages.add(MessageParam.ofUserOfContentBlockParams(toolResults));
}
return messages;
}
```
```php PHP
/**
* Run the computer-use agent loop until Claude stops requesting tools
* or the iteration limit is reached.
*/
function samplingLoop(string $model, array $messages, int $maxIterations = 10): array
{
global $client, $tools;
for ($i = 0; $i < $maxIterations; $i++) {
$response = $client->messages->create(
model: $model,
maxTokens: 4096,
messages: $messages,
tools: $tools,
);
// Claude의 응답을 대화 기록에 추가합니다
$messages[] = MessageParam::with(role: Role::ASSISTANT, content: $response->content);
// Claude가 요청한 도구를 실행하고 결과를 수집합니다
$toolResults = processToolCalls($response);
if ($toolResults === []) {
return $messages; // No more tool use; task complete
}
// 다음 반복을 위해 도구 결과를 Claude에 다시 보냅니다
$messages[] = MessageParam::with(role: Role::USER, content: $toolResults);
}
return $messages;
}
```
```ruby Ruby
# Claude가 도구 요청을 멈추거나 반복 한도에 도달할 때까지
# 컴퓨터 사용 에이전트 루프를 실행합니다.
def sampling_loop(model, messages, max_iterations: 10)
max_iterations.times do
response = CLIENT.messages.create(
model: model,
max_tokens: 4096,
messages: messages,
tools: TOOLS
)
# Claude의 응답을 대화 기록에 추가합니다
messages << { role: "assistant", content: response.content }
# Claude가 요청한 액션을 순서대로 실행하고 결과를 수집합니다
tool_results = process_tool_calls(response)
return messages if tool_results.empty? # No more tool use; task complete
# 모든 결과를 하나의 user 메시지로 Claude에 다시 보냅니다
messages << { role: "user", content: tool_results }
end
messages
end
```
루프는 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. 모델이 로그인해야 한다면 `` 같은 XML 태그 안에 사용자 이름과 비밀번호를 넣어 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 사용하면 프롬프트 인젝션으로 인한 나쁜 결과의 위험이 커집니다. 모델에 로그인 자격 증명을 제공하기 전에 [탈옥 및 프롬프트 인젝션 완화](https://platform.claude.com/docs/ko/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)를 검토하세요.
6. 사용자 턴의 `content` 배열을 구성할 때 지시 텍스트를 스크린샷 이미지 *앞에* 배치하세요. 이미지가 처리되기 전에 대상 설명을 제공하면 클릭 정확도가 향상됩니다.
7. Claude는 사이드바의 파일 이름, 탭 제목, 상태 표시줄 텍스트, 줄 번호, 버튼 레이블처럼 스크린샷의 기본 해상도에서 읽을 수 없는 작은 텍스트나 특정 UI 요소에 대해 질문을 받으면 `zoom` 작업을 사용하여 해당 영역을 전체 해상도로 검사합니다. Claude가 예상대로 확대하지 않는다면, 화면 전체가 아니라 특정 영역이나 요소에 대해 질문하세요.
8. 모든 [배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions)이 스크린샷으로 끝나기를 원한다면 시스템 프롬프트에 그렇게 명시하세요. 예: `End each group of actions with a screenshot so you can verify the result before continuing.`
명확한 일련의 문제가 반복적으로 발생하거나 Claude가 완료해야 할 작업을 미리 알고 있다면, 시스템 프롬프트를 사용하여 작업을 성공적으로 수행하는 방법에 대한 명시적인 팁이나 지시를 Claude에게 제공하세요.
여러 세션에 걸친 에이전트의 경우, 구현 후뿐만 아니라 각 세션 시작 시에도 엔드투엔드 검증을 실행하세요. 브라우저 기반 검사는 코드 수준 검토만으로는 놓치는 이전 세션의 회귀를 잡아냅니다. 자세한 내용은 [장기 실행 에이전트를 위한 효과적인 하네스](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)를 참조하세요.
### 시스템 프롬프트
요청에 컴퓨터 사용 도구를 포함하면 API는 컴퓨터 사용 전용 시스템 프롬프트를 생성합니다. 이는 [도구 사용 시스템 프롬프트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools#tool-use-system-prompt)와 유사하지만 다음으로 시작합니다:
> 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개의 멤버 도구가 있습니다:
| 멤버 | 입력 | 설명 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `screenshot` | 없음(`{}`) | 전체 디스플레이를 캡처하여 이미지로 반환합니다. |
| `zoom` | `region`: `[x0, y0, x1, y1]`, 검사할 영역의 왼쪽 위와 오른쪽 아래 모서리 | 디스플레이의 해당 영역만 전체 해상도로 캡처하여, 종횡비를 유지한 채 일반 스크린샷 크기에 맞게 조정한 이미지로 반환합니다. 이를 통해 Claude는 축소된 전체 스크린샷에서 읽을 수 없는 작은 텍스트나 밀집된 UI를 읽을 수 있습니다. |
| `left_click` | `coordinate`(선택 사항): `[x, y]`; `text`(선택 사항): 클릭하는 동안 누르고 있을 수정자 키: `shift`, `ctrl`, `alt`, `super`(Command 또는 Windows 키), 또는 `ctrl+shift` 같은 `+`로 연결된 조합 | `coordinate`에서, 또는 `coordinate`가 생략된 경우 현재 커서 위치에서 왼쪽 마우스 버튼을 클릭합니다. |
| `right_click`, `middle_click`, `double_click`, `triple_click` | `left_click`과 동일 | 다른 마우스 버튼 및 다중 클릭. |
| `left_click_drag` | `start_coordinate`: `[x, y]`; `coordinate`: `[x, y]`; `text`(선택 사항): 수정자 키 | `start_coordinate`에서 누르고, `coordinate`까지 드래그한 후 놓습니다. |
| `mouse_move` | `coordinate`: `[x, y]` | 클릭하지 않고 커서를 이동합니다(예: 호버). |
| `left_mouse_down`, `left_mouse_up` | 없음(`{}`) | `left_click_drag`로 표현할 수 없는 드래그를 위해 현재 커서 위치에서 왼쪽 마우스 버튼을 누르거나 놓습니다. 먼저 `mouse_move`로 커서를 이동하세요. |
| `cursor_position` | 없음(`{}`) | 커서의 현재 `[x, y]` 위치를 텍스트로 보고합니다. |
| `scroll` | `scroll_direction`: `"up"`, `"down"`, `"left"`, 또는 `"right"`; `scroll_amount`: 스크롤 휠 클릭 수; `coordinate`(선택 사항): `[x, y]`; `text`(선택 사항): 수정자 키 | `coordinate`에서, 또는 현재 커서 위치에서 스크롤합니다. |
| `type` | `text`: 입력할 문자열 | 현재 키보드 포커스에 리터럴 텍스트를 입력합니다. |
| `key` | `text`: `"Return"`, `"ctrl+s"`, `"alt+Tab"` 같은 키 또는 `+`로 연결된 조합; `repeat`(선택 사항): 1\~100, 기본값 1 | 키 또는 키 조합을 `repeat`회 누릅니다. |
| `hold_key` | `text`: 키 또는 조합; `duration`: 초, 최대 300 | 지정된 시간 동안 키를 누르고 있습니다. |
| `wait` | `duration`: 초, 최대 300 | 다음 작업 전에 일시 중지합니다(예: 애플리케이션이 로드되는 동안). |
멤버를 구현할 때 다음 사항에 유의하세요:
* **좌표는 스크린샷 픽셀 단위입니다.** 모든 `coordinate`, `start_coordinate`, `region` 값과 `cursor_position`이 보고하는 위치는 반환하는 전체 디스플레이 스크린샷의 픽셀 공간에 있으며, 원점은 왼쪽 위입니다. 확대 이미지는 이를 바꾸지 않습니다. `zoom` 이후에도 Claude는 확대된 이미지 기준이 아니라 항상 전체 스크린샷 공간에서 좌표를 표현합니다. 스크린샷을 반환하기 전에 축소한다면, 실제 디스플레이에 적용하기 전에 Claude의 좌표를 다시 확대하세요([이미지 제한에 맞게 스크린샷 크기 조정](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) 참조).
* **`zoom`을 포함한 모든 멤버가 기본적으로 활성화되어 있습니다.** 환경에서 확대 이미지를 생성할 수 없다면, 활성화된 상태로 두고 오류를 반환하는 대신 `configs`로 해당 멤버를 제외하세요([도구 매개변수](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#tool-parameters) 참조). Claude가 여러분이 제외했거나 구현하지 않은 멤버를 호출하면 해당 블록에 `is_error: true`가 포함된 `tool_result`를 반환하세요.
* **(`toolset_name`, `name`) 쌍을 기준으로 분기하세요.** `toolset_name`은 블록을 컴퓨터 작업으로 표시하는 요소입니다. 같은 요청의 커스텀 도구가 멤버와 같은 이름을 가질 수 있으며, 이후 도구 세트 버전에서 멤버가 추가될 수 있습니다([클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets) 참조).
각 예시는 Claude의 응답에 나타나는 완전한 `tool_use` 블록입니다.
특정 위치에서 Shift+클릭(예: 선택 영역 확장). `hold_key`와 달리 `text`는 해당 클릭이나 스크롤 동안에만 수정자 키를 누르고 있습니다:
```json
{
"type": "tool_use",
"id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [500, 300], "text": "shift" }
}
```
한 지점에서 다른 지점으로 드래그:
```json
{
"type": "tool_use",
"id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
"name": "left_click_drag",
"toolset_name": "computer",
"input": {
"start_coordinate": [200, 300],
"coordinate": [600, 300]
}
}
```
휠을 세 번 클릭하여 아래로 스크롤:
```json
{
"type": "tool_use",
"id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
"name": "scroll",
"toolset_name": "computer",
"input": {
"coordinate": [500, 400],
"scroll_direction": "down",
"scroll_amount": 3
}
}
```
Tab을 네 번 누르기:
```json
{
"type": "tool_use",
"id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
"name": "key",
"toolset_name": "computer",
"input": { "text": "Tab", "repeat": 4 }
}
```
영역을 전체 해상도로 검사하기 위해 확대:
```json
{
"type": "tool_use",
"id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
"name": "zoom",
"toolset_name": "computer",
"input": { "region": [100, 200, 400, 350] }
}
```
커서 위치 보고. 이 호출에는 스크린샷 픽셀 단위의 위치를 제공하는 짧은 텍스트 결과로 응답하세요. 예: `X=512, Y=384`:
```json
{
"type": "tool_use",
"id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
"name": "cursor_position",
"toolset_name": "computer",
"input": {}
}
```
### 도구 매개변수
`tools` 배열의 도구 세트 항목은 네 가지 매개변수를 허용합니다. 브라우저 사용 도구 세트와 공유하는 규칙은 [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets)에 나와 있습니다.
| 매개변수 | 필수 | 설명 |
| ----------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | 예 | `computer_toolset_20260801` |
| `configs` | 아니요 | 멤버 이름을 키로 하는 멤버별 설정. 각 멤버는 `enabled`(`zoom`을 포함한 17개 모두 기본값 `true`)와 `defer_loading`([도구 검색](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool#deferred-tool-loading)용, 기본값 `false`)을 허용하며, 생략한 멤버는 기본값을 유지합니다. |
| `cache_control` | 아니요 | 도구 세트 정의 지점의 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) 중단점. 항목에만 지정합니다. 배치의 `tool_use` 또는 `tool_result` 블록에 있는 중단점은 해당 배치의 끝에서 적용됩니다. [프롬프트 캐싱과 함께 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)을 참조하세요. |
| `allowed_callers` | 아니요 | `["direct"]`만 가능. |
예를 들어, 다음 항목은 `zoom`을 구현하지 않는 환경을 위해 이를 제외하고 도구 세트 정의 지점에 캐시 중단점을 설정합니다:
```json
{
"type": "computer_toolset_20260801",
"configs": {
"zoom": { "enabled": false }
},
"cache_control": { "type": "ephemeral" }
}
```
에이전트 루프가 왕복마다 하나의 작업만 실행할 수 있다면 `tool_choice`에서 `disable_parallel_tool_use`를 `true`로 설정하세요. 그러면 Claude는 턴마다 최대 하나의 멤버 `tool_use` 블록을 반환합니다([병렬 도구 사용 비활성화](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use) 참조).
이 항목은 이전 도구 버전의 다음 매개변수를 거부하며, 이 중 하나라도 포함된 요청은 `invalid_request_error`를 반환합니다:
* `name`: 멤버 이름은 도구 세트 버전에 의해 고정됩니다.
* `display_width_px`, `display_height_px`, `display_number`: 좌표는 항상 반환하는 스크린샷의 픽셀 공간에 있습니다.
* `enable_zoom`: 확대는 `configs`를 통해 제어하는 멤버 도구입니다.
또한 이 항목은 `computer_20251124` 항목이나 `computer`라는 이름의 다른 도구와 같은 요청에서 선언할 수 없습니다. `strict`, `input_examples`, `defer_loading` 배치, `tool_choice`, 스트리밍, 호출자 제한에 대해서는 [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets)를 참조하세요.
### 사고와 결합하기
컴퓨터 사용을 사고와 결합하려면 [사고](https://platform.claude.com/docs/ko/build-with-claude/thinking)를 참조하세요.
`computer_20251124` 도구의 경우, 이를 사용하는 모델에 대한 내부 벤치마크에서는 다음 `effort` 설정을 권장합니다:
* **Claude Opus 4.7:** 기본값으로 `high`를 사용하세요. 높은 처리량이나 비용에 민감한 워크로드에는 `low`를 사용하세요.
* **Claude Sonnet 4.6 및 Claude Opus 4.6:** 기본값으로 `medium`을 사용하세요(정확도 대비 비용 비율이 가장 좋음). `max`는 UI 작업의 정확도를 높이지 않으면서 토큰 비용만 추가하므로 피하세요. 이 모델들에서 `low`는 사고를 완전히 비활성화하는 것보다 *더 적은* 출력 토큰을 사용하므로(실수가 적으면 재시도도 적음), 비용에 민감한 루프에 좋은 선택입니다.
### 다른 도구로 컴퓨터 사용 보강하기
컴퓨터 사용과 함께 다른 도구를 추가하려면 같은 `tools` 배열에 포함하세요. [빠른 시작](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#quick-start) 섹션에서 [bash 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/bash-tool)와 [텍스트 편집기 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/text-editor-tool)를 사용한 이 패턴을 보여줍니다. 자체 [커스텀 도구 정의](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools)도 같은 방식으로 추가할 수 있습니다.
웹페이지 내에서만 이루어지는 작업의 경우 [같은 요청에서 브라우저 사용 도구를 선언](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool#combine-with-other-tools)할 수도 있습니다. 두 도구 세트는 각자의 좌표계에서 독립적으로 작동합니다. `toolset_name` 값은 `screenshot`이나 `key`처럼 이름이 같은 멤버에 대한 호출을 구분합니다.
### 커스텀 컴퓨터 사용 환경 구축
[레퍼런스 구현](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo)은 컴퓨터 사용을 시작하는 데 도움을 주기 위한 것입니다. 여기에는 Claude가 컴퓨터를 사용하는 데 필요한 모든 구성 요소가 포함되어 있습니다. 그러나 필요에 맞게 컴퓨터 사용을 위한 자체 환경을 구축할 수도 있습니다. 다음이 필요합니다:
* Claude와의 컴퓨터 사용에 적합한 가상화 또는 컨테이너화된 환경
* 컴퓨터 사용 도구 작업의 구현
* Claude API와 상호작용하고 도구 구현을 사용하여 `tool_use` 결과를 실행하는 에이전트 루프
* 사용자 입력으로 에이전트 루프를 시작할 수 있는 API 또는 UI
### 컴퓨터 사용 도구 구현
컴퓨터 사용 도구는 스키마 없는 도구로 구현됩니다. 이 도구를 사용할 때는 다른 도구처럼 입력 스키마를 제공할 필요가 없습니다. 스키마는 Claude의 모델에 내장되어 있으며 수정할 수 없습니다.
Claude가 상호작용할 가상 디스플레이를 만들거나 기존 디스플레이에 연결합니다. 이는 일반적으로 Xvfb(X Virtual Framebuffer) 또는 유사한 기술을 설정하는 것을 포함합니다.
Claude가 요청할 수 있는 각 작업 유형을 처리하는 함수를 만듭니다:
```python Python
# 플레이스홀더 이미지 데이터; 실제 실행기는 화면을 캡처하여 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}")
```
```typescript TypeScript
// 플레이스홀더 이미지 데이터; 실제 실행기는 화면을 PNG 바이트로 캡처합니다
const PLACEHOLDER_PNG =
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshot은 텍스트 대신 이미지 블록으로 응답합니다
return [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: PLACEHOLDER_PNG
}
}
];
}
function clickAt(x: number, y: number): string {
return `clicked at (${x}, ${y})`;
}
function clickAtCursor(): string {
return "clicked at the current cursor position";
}
function typeText(text: string): string {
return `typed: ${text}`;
}
function handleComputerAction(
action: string,
input: unknown
): string | Anthropic.ImageBlockParam[] {
const params: object = typeof input === "object" && input !== null ? input : {};
switch (action) {
case "screenshot":
return captureScreenshot();
case "left_click":
// 이 도구 세트에서 coordinate는 선택 사항입니다. 없으면 커서 위치를 클릭합니다
if ("coordinate" in params && Array.isArray(params.coordinate)) {
const [x, y] = params.coordinate;
return clickAt(x, y);
}
return clickAtCursor();
case "type":
if ("text" in params) {
return typeText(String(params.text));
}
break;
}
// 필요에 따라 다른 액션을 처리합니다
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// 플레이스홀더 이미지 데이터; 실제 실행기는 화면을 캡처하여 PNG 바이트를 반환합니다
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
// screenshot은 텍스트가 아닌 이미지 블록으로 응답합니다: 결과 콘텐츠 목록을 반환합니다
List CaptureScreenshot() =>
[
new ImageBlockParam(
new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
),
];
string ClickAt(int x, int y) => $"clicked at ({x}, {y})";
string ClickAtCursor() => "clicked at the current cursor position";
string TypeText(string text) => $"typed: {text}";
ToolResultBlockParamContent HandleComputerAction(
string action,
IReadOnlyDictionary input
) =>
action switch
{
"screenshot" => CaptureScreenshot(),
// coordinate는 click 멤버에서 선택 사항입니다; 없으면 커서 위치에서 클릭합니다
"left_click" when input.TryGetValue("coordinate", out var xy) => ClickAt(
xy[0].GetInt32(),
xy[1].GetInt32()
),
"left_click" => ClickAtCursor(),
"type" => TypeText(input["text"].GetString()!),
// 필요에 따라 다른 액션을 처리합니다
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG는 실제 캡처를 대신합니다: 실행기는
// 화면을 base64로 인코딩된 PNG 데이터로 반환합니다.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// captureScreenshot은 텍스트가 아닌 이미지 블록을 반환합니다.
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
// textContent는 텍스트를 tool_result 콘텐츠로 감쌉니다.
func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfText: &anthropic.TextBlockParam{Text: text}},
}
}
func clickAt(x, y int) string {
return fmt.Sprintf("clicked at (%d, %d)", x, y)
}
func clickAtCursor() string {
return "clicked at the current cursor position"
}
func typeText(text string) string {
return fmt.Sprintf("typed: %s", text)
}
func handleComputerAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
switch action {
case "screenshot":
return captureScreenshot(), nil
case "left_click":
// coordinate는 선택 사항입니다. 없으면 커서가 이미 있는 위치를 클릭합니다
coord, ok := params["coordinate"].([]any)
if !ok {
return textContent(clickAtCursor()), nil
}
if len(coord) == 2 {
x, xok := coord[0].(float64)
y, yok := coord[1].(float64)
if xok && yok {
return textContent(clickAt(int(x), int(y))), nil
}
}
case "type":
if text, ok := params["text"].(string); ok {
return textContent(typeText(text)), nil
}
// 필요에 따라 다른 액션을 처리합니다
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// 멤버의 입력에 필드가 누락되었거나 필드 타입이 잘못된 경우 도달합니다
return nil, fmt.Errorf("invalid input for %s", action)
}
```
```java Java
/** Placeholder pixels; a real executor captures the screen and base64-encodes the PNG. */
static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
ToolResultBlockParam.Content captureScreenshot() {
ImageBlockParam image = ImageBlockParam.builder()
.source(Base64ImageSource.builder()
.mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
.data(PLACEHOLDER_PNG)
.build())
.build();
return ToolResultBlockParam.Content.ofBlocks(
List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
}
String clickAt(long x, long y) {
return "clicked at (" + x + ", " + y + ")";
}
String clickAtCursor() {
return "clicked at current cursor";
}
String typeText(String text) {
return "typed: " + text;
}
/** Runs one computer toolset member; {@code action} is the tool_use block's name. */
ToolResultBlockParam.Content handleComputerAction(String action, Map input) {
if (action.equals("screenshot")) {
return captureScreenshot(); // the one member here that answers with an image block
}
String output = switch (action) {
case "left_click" -> {
JsonValue coordinate = input.get("coordinate"); // optional on the toolset
if (coordinate == null) {
yield clickAtCursor();
}
List point = (List) coordinate.asArray().get();
long x = ((Number) point.get(0).asNumber().get()).longValue();
long y = ((Number) point.get(1).asNumber().get()).longValue();
yield clickAt(x, y);
}
case "type" -> typeText(input.get("text").asStringOrThrow());
// 필요에 따라 다른 액션을 처리합니다
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// 실제 PNG 바이트의 대체물; 실제 실행기는 화면을 캡처합니다
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function captureScreenshot(): array
{
// screenshot은 텍스트가 아닌 이미지 블록으로 응답하므로 결과 콘텐츠 목록을 반환합니다
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function clickAt(?array $coordinate): string
{
// left_click은 coordinate를 생략할 수 있으며, 이 경우 커서가 이미 있는 위치에서 클릭됩니다
if ($coordinate === null) {
return 'clicked at current cursor';
}
[$x, $y] = $coordinate;
return "clicked at ({$x}, {$y})";
}
function typeText(string $text): string
{
return "typed: {$text}";
}
function handleComputerAction(string $name, array $input): string|array
{
return match ($name) {
'screenshot' => captureScreenshot(),
'left_click' => clickAt($input['coordinate'] ?? null),
'type' => typeText($input['text']),
// 필요에 따라 다른 액션을 처리합니다
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# 대체용 이미지 데이터입니다. 실제 실행기는 화면을 PNG로 캡처합니다.
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
# screenshot은 텍스트가 아닌 이미지 블록으로 응답합니다
def capture_screenshot
[
{
type: "image",
source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
}
]
end
def click(coordinate = nil)
return "clicked at current cursor" if coordinate.nil?
x, y = coordinate
"clicked at (#{x}, #{y})"
end
def type_text(text)
"typed: #{text}"
end
def handle_computer_action(name, input)
case name
when "screenshot"
capture_screenshot
when "left_click"
# coordinate는 선택 사항입니다. 없으면 현재 커서 위치에서 클릭합니다
click(input[:coordinate])
when "type"
type_text(input[:text])
# 필요에 따라 다른 액션을 처리합니다
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
Claude의 응답에서 도구 호출을 추출하고 실행합니다:
```python 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:
# 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
```
```typescript TypeScript
const HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";
function computerResult(
toolUseId: string,
content: string | Anthropic.ImageBlockParam[],
isError?: boolean
): Anthropic.ToolResultBlockParam {
return {
type: "tool_result",
tool_use_id: toolUseId,
toolset_name: "computer",
content,
is_error: isError
};
}
function processToolCalls(response: Anthropic.Message): Anthropic.ToolResultBlockParam[] {
const toolResults: Anthropic.ToolResultBlockParam[] = [];
let failed = false;
for (const block of response.content) {
if (block.type !== "tool_use") {
continue;
}
if (block.toolset_name !== "computer") {
// 이 예제는 computer 툴셋만 선언합니다; 다른 도구를 추가하면
// 여기서 라우팅하세요.
continue;
}
if (failed) {
// 배치는 첫 번째 실패에서 중단됩니다. 이후 액션은 실행하지 않고 응답하세요
toolResults.push(computerResult(block.id, HALT_TEXT, true));
continue;
}
try {
// 문자열, 또는 screenshot이 반환하는 이미지 블록 목록
const result = handleComputerAction(block.name, block.input);
toolResults.push(computerResult(block.id, result));
} catch (error) {
failed = true;
const message = error instanceof Error ? error.message : String(error);
toolResults.push(computerResult(block.id, `Error: ${message}`, true));
}
}
return toolResults;
}
```
```csharp C#
const string HaltText = "Not executed: an earlier computer action in this turn failed.";
List ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "computer")
{
// 이 예제는 computer 도구 세트만 선언합니다; 다른 도구를 추가하는 경우
// 여기서 라우팅하세요.
continue;
}
if (failed)
{
// 배치는 첫 번째 실패에서 중단됩니다; 이후 액션은 실행하지 않고 응답합니다
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "computer",
}
);
continue;
}
try
{
// 문자열 또는 screenshot이 반환하는 이미지 블록 목록
var result = HandleComputerAction(toolUse.Name, toolUse.Input);
toolResults.Add(
new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "computer" }
);
}
catch (Exception e)
{
failed = true;
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = $"Error: {e.Message}",
IsError = true,
ToolsetName = "computer",
}
);
}
}
return toolResults;
}
```
```go Go
const notExecuted = "Not executed: an earlier computer action in this turn failed."
// computerToolResult는 하나의 컴퓨터 액션에 대한 결과를 생성합니다.
// 일반 도구 결과와 달리 toolset 이름을 그대로 반환해야 합니다.
func computerToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
result := anthropic.ToolResultBlockParam{
ToolUseID: toolUseID,
ToolsetName: anthropic.String("computer"),
Content: content,
}
if isError {
result.IsError = anthropic.Bool(true)
}
return anthropic.ContentBlockParamUnion{OfToolResult: &result}
}
// processToolCalls는 Claude 응답의 computer 작업을 순서대로 실행하고
// 각 tool_use 블록마다 tool_result를 하나씩 만듭니다. 첫 실패 이후에는 나머지를
// 건너뜁니다: Claude는 앞선 작업이 성공했다고 가정하고 계획했기 때문입니다.
func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
var toolResults []anthropic.ContentBlockParamUnion
failed := false
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.ToolUseBlock:
// 이 예제는 computer toolset만 선언합니다. 다른 도구를 추가하면 여기서 라우팅하세요.
if variant.ToolsetName != "computer" {
continue
}
if failed {
toolResults = append(toolResults, computerToolResult(variant.ID, textContent(notExecuted), true))
continue
}
var input map[string]any
var content []anthropic.ToolResultBlockParamContentUnion
err := json.Unmarshal(variant.Input, &input)
if err == nil {
// 텍스트 또는 screenshot이 반환하는 이미지 블록
content, err = handleComputerAction(variant.Name, input)
}
if err != nil {
failed = true
content = textContent("Error: " + err.Error())
}
toolResults = append(toolResults, computerToolResult(variant.ID, content, err != nil))
}
}
return toolResults
}
```
```java Java
/** The exact text the toolset contract prescribes for member calls skipped after a failure. */
static final String HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";
/** Every result answering a computer toolset member echoes toolset_name. */
ToolResultBlockParam.Builder computerResult(ToolUseBlock toolUse) {
return ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.toolsetName("computer");
}
/**
* Run the computer actions in Claude's response in order and build one
* tool_result for each tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// 이 예제는 computer 도구 세트만 선언합니다. 다른 도구를 추가하는 경우 여기서 라우팅하세요.
if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("computer"))) {
continue;
}
ToolUseBlock toolUse = block.asToolUse();
ToolResultBlockParam result;
if (failed) {
result = computerResult(toolUse)
.content(HALT_TEXT)
.isError(true)
.build();
} else {
try {
Map input =
(Map) toolUse._input().asObject().get();
// 문자열 또는 screenshot이 반환하는 이미지 블록
ToolResultBlockParam.Content output = handleComputerAction(toolUse.name(), input);
result = computerResult(toolUse)
.content(output)
.build();
} catch (RuntimeException e) {
failed = true;
result = computerResult(toolUse)
.content("Error: " + e.getMessage())
.isError(true)
.build();
}
}
toolResults.add(ContentBlockParam.ofToolResult(result));
}
return toolResults;
}
```
```php PHP
const HALT_TEXT = 'Not executed: an earlier computer action in this turn failed.';
function processToolCalls(Message $response): array
{
$toolResults = [];
$failed = false;
foreach ($response->content as $block) {
// 이 예제는 computer 도구 세트만 선언합니다; 다른 도구를 추가하면 여기서 라우팅하세요.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'computer') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'computer'];
if ($failed) {
// 배치는 첫 번째 실패에서 중단되며, 나머지 액션은 실행 없이 응답됩니다
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// 문자열 또는 screenshot이 반환하는 이미지 블록 목록
$toolResults[] = [...$result, 'content' => handleComputerAction($block->name, $block->input)];
} catch (\Throwable $e) {
$failed = true;
$toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
}
}
return $toolResults;
}
```
```ruby Ruby
NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
# Claude의 응답에 있는 computer 액션을 순서대로 실행하고, 각 tool_use 블록마다
# tool_result를 하나씩 생성합니다. 첫 번째 실패 이후에는 나머지를 건너뜁니다:
# Claude는 이전 액션이 성공했다고 가정하고 이를 계획했기 때문입니다.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# 이 예제는 computer 도구 세트만 선언합니다. 다른 도구를 추가한다면
# 여기서 라우팅하세요.
next unless block.type == :tool_use && block.toolset_name == "computer"
result = { type: "tool_result", tool_use_id: block.id, toolset_name: "computer" }
if failed
result.update(content: NOT_EXECUTED, is_error: true)
else
begin
# String 또는 screenshot이 반환하는 이미지 콘텐츠 블록
result[:content] = handle_computer_action(block.name, block.input)
rescue => e
result.update(content: "Error: #{e.message}", is_error: true)
failed = true
end
end
tool_results << result
end
tool_results
end
```
이전 두 단계를 결과를 다시 보내고 Claude가 더 이상 멤버 도구 호출을 반환하지 않을 때까지 반복하는 루프로 감쌉니다. [에이전트 루프 이해하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop)에서 이 루프를 보여줍니다.
### 오류 처리
실패한 작업은 `is_error: true`와 짧은 설명이 포함된 `tool_result`로 Claude에게 보고하고, 다른 멤버 결과와 마찬가지로 `"toolset_name": "computer"`를 포함하세요. 실패한 작업이 [배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions)의 일부였다면, 배치의 나머지 블록은 실행하지 말고 해당 섹션에 나온 중단 텍스트로 응답하세요.
예를 들어, 스크린샷 캡처가 실패한 경우:
```json
{
"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
}
]
}
```
디스플레이 범위를 벗어난 좌표나 실행에 실패한 작업에도 무엇이 잘못되었는지 설명하는 메시지와 함께 같은 형태를 사용하세요.
### 이미지 제한에 맞게 스크린샷 크기 조정
컴퓨터 사용 도구 세트에 반환하는 스크린샷과 확대 이미지는 이미 모델의 [이미지 크기 제한](https://platform.claude.com/docs/ko/build-with-claude/vision#evaluate-image-size) 내에 맞아야 합니다. 도구 세트는 디스플레이 크기를 받지 않고 API가 대신 축소해 주지 않으므로, 크기가 초과된 `tool_result` 이미지는 유효성 검사 오류와 함께 거부됩니다. Claude는 전달받은 이미지의 픽셀 공간 기준으로 좌표를 반환하므로, 해당 좌표를 화면에 다시 매핑할 수 있도록 사용한 배율을 보관하세요.
제한은 모델마다 다릅니다. Claude Opus 4.7 이후 모델(`computer_toolset_20260801`을 지원하는 모든 모델 포함)은 긴 변 기준 최대 2,576픽셀, 총 4,784 visual token(`⌈width / 28⌉ × ⌈height / 28⌉`, 약 3.75메가픽셀)까지 허용합니다. 이전 모델은 긴 변 기준 최대 1,568픽셀, 총 약 1.15메가픽셀까지 허용합니다(각 모델의 등급은 [해상도 및 토큰 비용](https://platform.claude.com/docs/ko/build-with-claude/vision#evaluate-image-size)을 참조하세요). 다음 예제는 이전 모델의 1,568 px / 1.15 MP 제한을 사용합니다. 고해상도 등급 모델의 경우 총 픽셀 수가 아니라 visual token 제한에 맞게 크기를 조정하세요. 예를 들어 [업로드 전에 이미지 크기 조정](https://platform.claude.com/docs/ko/build-with-claude/vision-coordinates#resize-your-image-before-uploading)의 크기 조정 헬퍼를 사용할 수 있습니다.
화면이 제한보다 크다면 각 스크린샷을 반환하기 전에 크기를 조정하고, Claude가 반환한 좌표를 원래 화면 공간으로 다시 변환하세요. 도구 세트는 디스플레이 크기를 받지 않으므로, 애플리케이션 코드에서의 크기 조정과 좌표 변환만 있으면 됩니다.
```python Python
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)
```
```typescript TypeScript
const screenWidth = 1512;
const screenHeight = 982;
const MAX_LONG_EDGE = 1568;
const MAX_PIXELS = 1_150_000;
function getScaleFactor(width: number, height: number): number {
const longEdge = Math.max(width, height);
const totalPixels = width * height;
const longEdgeScale = MAX_LONG_EDGE / longEdge;
const totalPixelsScale = Math.sqrt(MAX_PIXELS / totalPixels);
return Math.min(1.0, longEdgeScale, totalPixelsScale);
}
// 스크린샷을 캡처할 때
const scale = getScaleFactor(screenWidth, screenHeight);
const scaledWidth = Math.floor(screenWidth * scale);
const scaledHeight = Math.floor(screenHeight * scale);
// Claude에 보내기 전에 이미지를 조정된 크기로 리사이즈합니다
const screenshot = captureAndResize(scaledWidth, scaledHeight);
// Claude의 좌표를 처리할 때는 원래 크기로 다시 확대합니다
function executeClick(x: number, y: number): void {
const screenX = x / scale;
const screenY = y / scale;
performClick(screenX, screenY);
}
```
```csharp C#
int screenWidth = 1512, screenHeight = 982;
double GetScaleFactor(int width, int height)
{
// API 제약 조건을 충족하도록 배율을 계산합니다.
int longEdge = Math.Max(width, height);
int totalPixels = width * height;
double longEdgeScale = 1568.0 / longEdge;
double totalPixelsScale = Math.Sqrt(1_150_000.0 / totalPixels);
return Math.Min(1.0, Math.Min(longEdgeScale, totalPixelsScale));
}
// 스크린샷을 캡처할 때
double scale = GetScaleFactor(screenWidth, screenHeight);
int scaledWidth = (int)(screenWidth * scale);
int scaledHeight = (int)(screenHeight * scale);
// Claude에 보내기 전에 이미지를 배율이 적용된 크기로 조정합니다
var screenshot = CaptureAndResize(scaledWidth, scaledHeight);
// Claude의 좌표를 처리할 때는 다시 원래 배율로 확대합니다
void ExecuteClick(int x, int y)
{
double screenX = x / scale;
double screenY = y / scale;
PerformClick(screenX, screenY);
}
```
```go Go
func getScaleFactor(width, height int) float64 {
longest := float64(max(width, height))
area := float64(width * height)
return min(1.0, 1568/longest, math.Sqrt(1_150_000/area))
}
// ...
screenWidth, screenHeight := 1512, 982
// 스크린샷을 캡처할 때
scale := getScaleFactor(screenWidth, screenHeight)
scaledWidth := int(float64(screenWidth) * scale)
scaledHeight := int(float64(screenHeight) * scale)
// Claude에 보내기 전에 이미지를 조정된 크기로 리사이즈합니다
screenshot := captureAndResize(scaledWidth, scaledHeight)
// Claude의 좌표를 처리할 때는 원래 크기로 다시 확대합니다
executeClick := func(x, y int) {
performClick(float64(x)/scale, float64(y)/scale)
}
```
```java Java
static double getScaleFactor(int width, int height) {
return Math.min(
1.0,
Math.min(
1568.0 / Math.max(width, height),
Math.sqrt(1_150_000.0 / (width * height))
)
);
}
void main() {
int screenWidth = 1512, screenHeight = 982;
// 스크린샷을 캡처할 때
double scale = getScaleFactor(screenWidth, screenHeight);
int scaledWidth = (int)(screenWidth * scale);
int scaledHeight = (int)(screenHeight * scale);
// Claude에 보내기 전에 이미지를 조정된 크기로 리사이즈합니다
var screenshot = captureAndResize(scaledWidth, scaledHeight);
// Claude의 좌표를 처리할 때는 원래 크기로 다시 확대합니다
BiConsumer executeClick =
(x, y) -> performClick(x / scale, y / scale);
// ...
}
```
```php PHP
function getScaleFactor(int $width, int $height): float
{
return min(
1.0,
1568 / max($width, $height),
sqrt(1_150_000 / ($width * $height)),
);
}
$screenWidth = 1512;
$screenHeight = 982;
// 스크린샷을 캡처할 때
$scale = getScaleFactor($screenWidth, $screenHeight);
$scaledWidth = (int)($screenWidth * $scale);
$scaledHeight = (int)($screenHeight * $scale);
// Claude에 보내기 전에 이미지를 조정된 크기로 리사이즈합니다
$screenshot = captureAndResize($scaledWidth, $scaledHeight);
// Claude의 좌표를 처리할 때는 원래 크기로 다시 확대합니다
$executeClick = fn(int $x, int $y) => performClick($x / $scale, $y / $scale);
```
```ruby Ruby
def get_scale_factor(width, height)
[1.0, 1568.0 / [width, height].max, Math.sqrt(1_150_000.0 / (width * height))].min
end
screen_width, screen_height = 1512, 982
# 스크린샷을 캡처할 때
scale = get_scale_factor(screen_width, screen_height)
scaled_width = (screen_width * scale).to_i
scaled_height = (screen_height * scale).to_i
# Claude에 보내기 전에 이미지를 축소된 크기로 조정합니다
screenshot = capture_and_resize(scaled_width, scaled_height)
# Claude의 좌표를 처리할 때는 원래 크기로 다시 확대합니다
execute_click = ->(x, y) { perform_click(x / scale, y / scale) }
```
**macOS Retina 디스플레이**는 기기 픽셀 비율 2로 스크린샷을 캡처하므로, 이미지 해상도가 논리적 화면 좌표의 두 배가 됩니다. 전송하기 전에 스크린샷을 2배 축소하거나, 클릭을 실행하기 전에 Claude가 반환한 좌표를 절반으로 줄이세요.
디스플레이 해상도를 선택하고 스크린샷을 반환할 때는 다음을 따르세요.
* 일반적인 데스크톱 작업에는 1024x768 또는 1280x720을, 웹 애플리케이션에는 1280x800 또는 1366x768을 사용하세요.
* 성능 문제를 방지하려면 1920x1080보다 높은 해상도는 피하세요.
* 스크린샷은 base64 PNG 또는 JPEG로 인코딩하고, 성능 향상을 위해 큰 스크린샷은 압축하는 것을 고려하세요.
* 타임스탬프나 디스플레이 상태 같은 관련 메타데이터를 포함하세요.
* 더 높은 해상도를 사용하는 경우 좌표가 정확하게 변환되는지 확인하세요.
### 스크린샷 기록 관리
긴 에이전트 루프에서는 스크린샷이 빠르게 누적됩니다(각각 약 1,000–1,800 입력 토큰). API의 [요청 제한](https://platform.claude.com/docs/ko/build-with-claude/vision#request-limits)도 적용됩니다. 단일 요청에 20개를 초과하는 이미지가 포함되면, 그 안의 모든 이미지에 더 엄격한 변당 제한이 적용됩니다. 스크린샷 기록을 유지하는 루프는 수십 턴 이내에 그 개수에 도달하므로, 각 스크린샷의 크기를 조정하여 해당 제한 이하로 유지하거나, 이전 스크린샷을 정리하여 요청에 20개 이하로 유지하세요.
컨텍스트를 제한하면서 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching)의 효과를 유지하려면 다음을 따르세요.
* 시스템 프롬프트와 도구 정의 뒤에 `cache_control` 중단점 하나를 두고, 가장 최근 턴들의 마지막 `tool_result` 블록에 최대 세 개를 더 두되, 매 턴마다 이를 앞으로 이동시키세요. [배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions) 내에서는 여러 블록의 마커가 하나의 중단점으로 작동하지만, 각각이 여전히 네 개 제한에 포함되므로 한 턴에는 최대 하나만 사용하세요.
* 이전 스크린샷은 매 턴 하나씩이 아니라 *일괄*로 정리하세요. 매 턴 스크린샷을 제거하면 매 턴 접두사가 바뀌어 캐시가 무효화됩니다. 합리적인 기본값은 마지막 스크린샷 세 개를 유지하고 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에서는 클라이언트에서 정리하지 마세요. 요청에서 이전 스크린샷을 제거하면 해당 요청과 이후의 모든 요청에서 [그 이후의 모든 사고 블록이 무효화됩니다](https://platform.claude.com/docs/ko/build-with-claude/thinking#preserved-in-conversation). 대신 스크린샷의 크기를 조정하여 더 엄격한 제한 이하로 유지하고, 서버 측 [도구 결과 정리](https://platform.claude.com/docs/ko/build-with-claude/context-editing#tool-result-clearing)를 사용하여 컨텍스트에서 오래된 스크린샷을 제거하세요. 반드시 정리해야 하는 경우, 그 시점부터 [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/ko/build-with-claude/thinking#preserved-thinking-controls)을 계속 설정해 두세요. 각 정리 후에 Claude는 해당 요청과 이후의 모든 요청에서 정리된 스크린샷 이후에 생성된 사고 없이 계속 진행합니다. Claude Sonnet 5.5와 Claude Haiku 5.5에서 `block_binding`은 `thinking: {"type": "adaptive"}`에서만 작동합니다. 해당 모델에서 다른 사고 설정을 사용하는 경우, 기록을 추가 전용(append-only)으로 유지하거나 정리된 스크린샷 이후의 모든 `thinking` 및 `redacted_thinking` 블록을 제거하세요.
### 클릭 문제 진단
클릭이 대상을 빗나간다면 원인은 보통 다음 중 하나입니다.
| 증상 | 가능한 원인 | 시도할 방법 |
| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 클릭이 일관되게 한 방향으로 어긋남 | 반환한 스크린샷의 픽셀 공간 기준인 Claude의 좌표가 변환 없이 크기가 다른 디스플레이에 적용되고 있음 | 클릭하기 전에 각 좌표를 화면 크기와 스크린샷 크기의 비율로 변환하세요([이미지 제한에 맞게 스크린샷 크기 조정](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) 참조). macOS Retina 디스플레이에서는 2배 기기 픽셀 비율을 고려하세요 |
| 클릭이 올바른 영역에 떨어지지만 대상을 빗나감 | 대상이 매우 작거나, 4K 이상 원본을 축소하면서 세부 정보가 손실되었거나, 종횡비가 왜곡됨 | `zoom` 멤버를 활성화된 상태로 유지하고 구현하여 Claude가 해당 영역을 전체 해상도로 검사할 수 있게 하세요. 더 낮은 DPI로 캡처하거나 관련 영역만 잘라내세요. 크기 조정 시 종횡비를 유지하세요 |
| Claude가 완전히 다른 요소를 클릭함 | 모호한 지시, 또는 근처에 시각적으로 유사한 요소가 있음 | 위치 기반 프롬프트를 사용하세요("오른쪽 하단의 파란색 Submit 버튼"). 상호작용을 더 작은 단계로 나누세요 |
| 정확도가 일관되게 낮음 | 해상도가 너무 낮음 | 기준으로 1280x720을 시도해 보세요 |
**모델 선택은 클릭 정밀도에 영향을 줍니다.** `computer_20251124` 도구를 사용하는 모델 중에서 Claude Sonnet 4.6은 Claude Opus 4.6보다 클릭의 기계적 정밀도가 높고, 스크린샷을 크게 축소해야 할 때 더 견고합니다. Claude Opus 4.7은 그 격차를 좁혔습니다. 클릭 정밀도가 Sonnet 4.6과 대체로 비슷하며, 더 높은 해상도 제한 덕분에 필요한 축소가 줄어듭니다.
### 구현 모범 사례 따르기
일부 애플리케이션은 작업에 응답하는 데 시간이 필요합니다.
```python Python
def click_and_wait(x, y, wait_time=0.5):
click_at(x, y)
time.sleep(wait_time) # Allow UI to update
```
```typescript TypeScript
async function clickAndWait(x: number, y: number, waitMs = 500): Promise {
clickAt(x, y);
await new Promise((resolve) => setTimeout(resolve, waitMs)); // Allow UI to update
}
```
```csharp C#
static void ClickAndWait(int x, int y, double waitSeconds = 0.5)
{
ClickAt(x, y);
Thread.Sleep(TimeSpan.FromSeconds(waitSeconds)); // Allow UI to update
}
```
```go Go
func clickAndWaitFor(x, y int, wait time.Duration) {
clickAt(x, y)
time.Sleep(wait) // Allow UI to update
}
func clickAndWait(x, y int) {
clickAndWaitFor(x, y, 500*time.Millisecond)
}
```
```java Java
void clickAndWait(int x, int y) throws InterruptedException {
clickAndWait(x, y, 500);
}
void clickAndWait(int x, int y, long waitTimeMillis) throws InterruptedException {
clickAt(x, y);
Thread.sleep(waitTimeMillis); // Allow UI to update
}
```
```php PHP
function clickAndWait(int $x, int $y, float $waitSeconds = 0.5): void
{
clickAt($x, $y);
usleep((int) ($waitSeconds * 1_000_000)); // Allow UI to update
}
```
```ruby Ruby
def click_and_wait(x, y, wait_time: 0.5)
click_at(x, y)
sleep(wait_time) # Allow UI to update
end
```
요청된 작업이 안전하고 유효한지 확인하세요.
```python Python
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
```
```typescript TypeScript
const displayWidth = 1024;
const displayHeight = 768;
interface ActionParams {
coordinate?: [number, number];
}
function validateAction(actionType: string, params: ActionParams): [boolean, string | null] {
if (actionType === "left_click" && params.coordinate) {
const [x, y] = params.coordinate;
if (!(x >= 0 && x < displayWidth && y >= 0 && y < displayHeight)) {
return [false, "Coordinates out of bounds"];
}
}
return [true, null];
}
```
```csharp C#
const int DisplayWidth = 1024;
const int DisplayHeight = 768;
// ...
static (bool IsValid, string? Error) ValidateAction(string actionType, IReadOnlyDictionary parameters)
{
if (actionType == "left_click" && parameters.TryGetValue("coordinate", out JsonElement coordinate))
{
int x = coordinate[0].GetInt32();
int y = coordinate[1].GetInt32();
if (x is < 0 or >= DisplayWidth || y is < 0 or >= DisplayHeight)
{
return (false, "Coordinates out of bounds");
}
}
return (true, null);
}
```
```go Go
const (
displayWidth = 1024
displayHeight = 768
)
func validateAction(actionType string, params map[string]any) (bool, string) {
raw, hasCoordinate := params["coordinate"]
if actionType == "left_click" && hasCoordinate {
coord, ok := raw.([]any)
if !ok || len(coord) != 2 {
return false, "Invalid coordinate"
}
x, y := int(coord[0].(float64)), int(coord[1].(float64))
if !(0 <= x && x < displayWidth && 0 <= y && y < displayHeight) {
return false, "Coordinates out of bounds"
}
}
return true, ""
}
```
```java Java
static final int DISPLAY_WIDTH = 1024;
static final int DISPLAY_HEIGHT = 768;
record Validation(boolean valid, String error) {}
Validation validateAction(String actionType, Map params) {
if (actionType.equals("left_click") && params.containsKey("coordinate")) {
List coord = (List) params.get("coordinate").asArray().get();
long x = ((Number) coord.get(0).asNumber().get()).longValue();
long y = ((Number) coord.get(1).asNumber().get()).longValue();
if (!(0 <= x && x < DISPLAY_WIDTH && 0 <= y && y < DISPLAY_HEIGHT)) {
return new Validation(false, "Coordinates out of bounds");
}
}
return new Validation(true, null);
}
```
```php PHP
const DISPLAY_WIDTH = 1024;
const DISPLAY_HEIGHT = 768;
/** @return array{bool, ?string} */
function validateAction(string $actionType, array $params): array
{
if ($actionType === 'left_click' && isset($params['coordinate'])) {
[$x, $y] = $params['coordinate'];
if (!(0 <= $x && $x < DISPLAY_WIDTH && 0 <= $y && $y < DISPLAY_HEIGHT)) {
return [false, 'Coordinates out of bounds'];
}
}
return [true, null];
}
```
```ruby Ruby
DISPLAY_WIDTH = 1024
DISPLAY_HEIGHT = 768
def validate_action(action_type, params)
if action_type == "left_click" && params.key?(:coordinate)
x, y = params[:coordinate]
unless (0...DISPLAY_WIDTH).cover?(x) && (0...DISPLAY_HEIGHT).cover?(y)
return [false, "Coordinates out of bounds"]
end
end
[true, nil]
end
```
문제 해결을 위해 모든 작업의 로그를 보관하세요.
```python Python
import logging
def log_action(action_type, params, result):
logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")
```
```typescript TypeScript
function logAction(actionType: string, params: unknown, result: unknown): void {
console.error(
`Action: ${actionType}, Params: ${JSON.stringify(params)}, Result: ${JSON.stringify(
result
)}`
);
}
```
```csharp C#
static void LogAction(string actionType, object? parameters, object? result)
{
Console.Error.WriteLine($"Action: {actionType}, Params: {parameters}, Result: {result}");
}
```
```go Go
func logAction(actionType string, params map[string]any, result any) {
log.Printf("Action: %s, Params: %v, Result: %v", actionType, params, result)
}
```
```java Java
import static java.lang.System.Logger.Level.INFO;
static final System.Logger LOGGER = System.getLogger("computer-use");
void logAction(String actionType, Object params, Object result) {
LOGGER.log(INFO, "Action: {0}, Params: {1}, Result: {2}", actionType, params, result);
}
```
```php PHP
function logAction(string $actionType, array $params, mixed $result): void
{
error_log(sprintf(
'Action: %s, Params: %s, Result: %s',
$actionType,
json_encode($params),
json_encode($result),
));
}
```
```ruby Ruby
require "logger"
LOGGER = Logger.new($stderr)
def log_action(action_type, params, result)
LOGGER.info("Action: #{action_type}, Params: #{params}, Result: #{result}")
end
```
***
## `computer_20251124`에서 마이그레이션
`computer_20251124` 통합은 [이전 도구 버전](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions)에서 해당 버전에 대해 나열된 모델에서 변경 없이 작동합니다. Claude API의 Claude 5.5 모델처럼 `computer_20251124`를 허용하지 않는 모델로 통합을 옮기기 전에 통합을 업그레이드하세요.
업그레이드하려면 다음 변경 사항을 함께 적용하세요:
1. **베타 헤더를 제거하세요.** 요청에서 `anthropic-beta: computer-use-2025-11-24`를 삭제하세요. SDK를 사용하는 경우 `betas` (csharp, go: `Betas`; java: `.addBeta()`)를 제거하고, 베타 네임스페이스가 아닌 표준 클라이언트를 통해 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}}`를 추가하고, 그렇지 않다면 이를 구현하세요([사용 가능한 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#available-actions) 참조).
4. **한 턴의 모든 블록을 처리하세요.** 응답에서 첫 번째 블록만 읽는 대신 모든 `tool_use` 블록을 순회하도록 에이전트 루프를 업데이트하고, `input.action` 대신 블록의 `name`과 `toolset_name`을 함께 기준으로 디스패치하세요. 멤버 입력에는 더 이상 `action` 필드가 포함되지 않으며, 나머지 필드는 변경되지 않습니다.
5. **블록을 순서대로 실행하고 중단 텍스트를 사용하세요.** [배치 작업](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions)에 설명된 대로 블록을 순차적으로 실행하고, 첫 번째 실패에서 멈추며, 나머지 블록에는 `Not executed: an earlier computer action in this turn failed.`로 응답하세요. 루프가 아직 배치 작업을 실행할 수 없다면, [도구 매개변수](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#tool-parameters)에서 Claude를 턴당 하나의 작업으로 제한하는 방법을 설명합니다.
6. **결과에 `toolset_name`을 그대로 포함하세요.** 멤버 호출에 응답하는 모든 `tool_result`에 `"toolset_name": "computer"`를 추가하세요. 결과에는 `text` 및 `image` 콘텐츠만 포함될 수 있습니다.
7. **`key`에서 `repeat`를 지원하세요.** `key` 멤버는 1에서 100 사이의 선택적 `repeat` 횟수를 허용합니다. 인식하지 못하는 필드를 무시하는 핸들러는 키를 한 번만 누르게 되므로, `key` 핸들러가 `repeat`를 따르도록 하세요.
8. **스크린샷 크기를 직접 조정하세요.** 도구 세트는 모델의 이미지 제한을 초과하는 스크린샷이나 확대 이미지를 축소하는 대신 거부합니다. 이미지를 반환하기 전에 크기를 조정하고, [이미지 제한에 맞게 스크린샷 크기 조정](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)에 설명된 대로 좌표 변환을 계속하세요.
9. **지원되지 않는 옵션을 제거하세요.** `defer_loading`이 있다면 항목에서 `configs`로 옮기고, 활성화된 모든 멤버에 동일한 값을 지정하세요. 도구 세트 항목에서 지원되지 않는 다른 옵션은 [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets)에 나열되어 있습니다.
다음은 `anthropic-beta: computer-use-2025-11-24` 헤더와 함께 전송되는 변경 전 `tools` 항목입니다.
```json
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
"display_number": 1
}
```
다음은 베타 헤더 없이 전송되는 변경 후 `tools` 항목입니다. `enable_zoom`을 설정하지 않은 이전 항목과 일치하도록 `configs` 객체가 확대 기능을 끈 상태로 유지합니다. 기본값을 받아들여 Claude가 확대할 수 있게 하려면 `configs`를 완전히 생략하세요.
```json
{
"type": "computer_toolset_20260801",
"configs": {
"zoom": { "enabled": false }
}
}
```
다음 쌍은 변경 전후의 `tool_use` 블록을 보여 줍니다. 작업 이름이 `input.action`에서 `name`으로 옮겨지고, 블록에 `toolset_name`이 추가됩니다.
```json
{
"type": "tool_use",
"id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
"name": "computer",
"input": { "action": "left_click", "coordinate": [500, 300] }
}
```
```json
{
"type": "tool_use",
"id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [500, 300] }
}
```
## 이전 도구 버전
컴퓨터 사용 도구의 이전 버전 두 가지가 베타로 제공됩니다. 각 버전은 모든 요청에 해당 [베타 헤더](https://platform.claude.com/docs/ko/api/beta-headers)가 필요하며, 매개변수는 [베타 Messages API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/messages/create)에 문서화되어 있습니다. SDK를 사용하는 경우 `betas` (csharp, go: `Betas`; java: `.addBeta()`)를 통해 헤더를 전달하고 베타 네임스페이스를 사용하세요. 헤더가 필요한 것은 컴퓨터 사용 도구뿐이며, 같은 요청에 있는 bash 또는 텍스트 편집기 도구에는 필요하지 않습니다.
| 도구 버전 | 베타 헤더 | 사용 대상 | 매개변수 |
| ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `computer_20251124` | `computer-use-2025-11-24` | Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 및 Claude Opus 4.5 | [API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/messages/create) |
| `computer_20250124` | `computer-use-2025-01-24` | Claude Sonnet 4.5 ([지원 중단](https://platform.claude.com/docs/ko/about-claude/model-deprecations)), Claude Haiku 4.5, Claude Opus 4.1 ([종료, Claude Models on Google Cloud (Google managed) 및 Bedrock 제외](https://platform.claude.com/docs/ko/about-claude/model-deprecations)), Claude Sonnet 4 ([종료, Claude Models on Google Cloud (Google managed) 및 Bedrock 제외](https://platform.claude.com/docs/ko/about-claude/model-deprecations)) 및 Claude Opus 4 ([종료, Claude Models on Google Cloud (Google managed) 제외](https://platform.claude.com/docs/ko/about-claude/model-deprecations)) | [API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/messages/create) |
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` 도구를 허용합니다.
***
## 제한 사항
1. **“Latency”(지연 시간):** 인간-AI 상호작용에서 컴퓨터 사용의 지연 시간은 사람이 직접 수행하는 일반적인 컴퓨터 작업에 비해 너무 느릴 수 있습니다. 신뢰할 수 있는 환경에서 속도가 중요하지 않은 사용 사례(예: 백그라운드 정보 수집, 자동화된 소프트웨어 테스트)에 집중하세요.
2. **컴퓨터 비전 정확도 및 신뢰성:** Claude는 작업을 생성하면서 특정 좌표를 출력할 때 실수하거나 환각을 일으킬 수 있습니다. Claude의 [요약된 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking#summarized-thinking) 출력은 모델의 추론을 이해하고 잠재적인 문제를 식별하는 데 도움이 될 수 있습니다. 도구 세트를 지원하는 모델은 기본적으로 사고 텍스트를 생략하므로, 사고 구성에서 `display: "summarized"`를 설정하세요.
3. **도구 선택 정확도 및 신뢰성:** Claude는 작업을 생성하면서 도구를 선택할 때 실수하거나 환각을 일으킬 수 있으며, 문제를 해결하기 위해 예상치 못한 작업을 수행할 수 있습니다. 또한 특수한 애플리케이션이나 여러 애플리케이션과 동시에 상호작용할 때 신뢰성이 낮아질 수 있습니다. 복잡한 작업을 요청할 때는 모델에 신중하게 프롬프트를 작성하세요.
4. **스크롤 신뢰성:** 스크롤 작업은 방향 제어(위, 아래, 왼쪽, 오른쪽)와 지정된 양을 지원합니다. 스크롤이 적용되지 않는 애플리케이션에서는 Page Down 같은 키보드 대안이 도움이 될 수 있습니다.
5. **스프레드시트 상호작용:** 개별 셀을 선택하려면 세밀한 마우스 제어 작업(`left_mouse_down`, `left_mouse_up`)과 수정자 키 조합을 사용하세요. 복잡한 스프레드시트 작업은 여전히 여러 번의 시도가 필요할 수 있습니다.
6. **소셜 및 커뮤니케이션 플랫폼에서의 계정 생성 및 콘텐츠 생성:** Claude는 웹사이트를 방문하지만, 소셜 미디어 웹사이트와 플랫폼 전반에서 계정을 생성하거나, 콘텐츠를 생성 및 공유하거나, 기타 방식으로 사람을 사칭하는 능력은 제한되어 있습니다.
7. **취약점:** 탈옥(jailbreak)과 프롬프트 인젝션은 다른 모든 최첨단 AI 시스템과 마찬가지로 컴퓨터 사용에 영향을 줄 수 있으며, 여기에는 웹페이지나 이미지에 포함된 지시를 통한 경우도 포함됩니다. [보안 고려 사항](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#security-considerations)의 예방 조치를 적용하세요.
8. **부적절하거나 불법적인 작업:** Anthropic의 서비스 약관에 따라, 컴퓨터 사용을 이용하여 법률이나 허용 사용 정책을 위반해서는 안 됩니다.
Claude의 컴퓨터 사용 작업과 로그를 항상 신중하게 검토하고 확인하세요. 사람의 감독 없이 완벽한 정밀도가 필요한 작업이나 민감한 사용자 정보가 관련된 작업에 Claude를 사용하지 마세요.
## 데이터 보존
컴퓨터 사용은 클라이언트 측 도구입니다. 세션에 관련된 모든 스크린샷, 마우스 작업, 키보드 입력 및 모든 파일은 Anthropic이 아닌 사용자의 환경에서 캡처되고 저장됩니다. Anthropic은 API 호출의 일부로 스크린샷 이미지와 작업 요청을 실시간으로 처리합니다. 이러한 API 요청의 보존은 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)에 따라 관리됩니다.
애플리케이션이 컴퓨터 사용 데이터의 저장 위치와 방식을 제어하므로, 컴퓨터 사용은 ZDR 적용 대상입니다.
## 가격
컴퓨터 사용은 표준 [도구 사용 가격](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview#pricing)을 따릅니다. 컴퓨터 사용 도구를 사용할 때:
**도구 세트 정의 오버헤드:** 기본 멤버와 함께 `computer_toolset_20260801`을 선언하면 요청에 약 4,500개의 입력 토큰이 추가되며(Claude Sonnet 5에서는 약 4,590개, 기타 지원 모델에서는 약 4,520개), 여기에는 멤버 도구 정의와 도구 사용 시스템 프롬프트가 포함됩니다. `configs`로 `zoom`을 비활성화하면 이 중 약 410개의 토큰이 제거됩니다. 요청의 정확한 토큰 수는 응답의 `usage`에 보고되며, [토큰 카운팅 엔드포인트](https://platform.claude.com/docs/ko/build-with-claude/token-counting)를 사용하여 미리 추정할 수 있습니다.
**이전 도구 버전:** 다음 수치는 `computer_toolset_20260801`이 아닌 `computer_20251124` 및 `computer_20250124` 도구 버전에 적용됩니다:
* 시스템 프롬프트 오버헤드: 시스템 프롬프트에 466–499개의 토큰 추가
* 도구 정의: 도구 정의당 약 735개의 입력 토큰(`computer_20250124`로 측정)
**추가 토큰 소비:**
* 도구 결과로 반환되는 스크린샷 및 확대 이미지는 이미지 입력으로 청구됩니다([비전 가격](https://platform.claude.com/docs/ko/build-with-claude/vision#evaluate-image-size) 참조)
* Claude에 반환되는 도구 실행 결과
컴퓨터 사용과 함께 bash 또는 텍스트 편집기 도구도 사용하는 경우, 해당 도구들은 각각의 페이지에 문서화된 대로 자체적인 토큰 비용이 있습니다.
## 다음 단계
파트너의 드라이버로 시작하거나, Python 또는 TypeScript로 직접 작성하세요. SDK가 루프와 사용자가 전달한 승인 콜백을 실행합니다.
증상별 해결 방법 진단 표로 가장 흔한 도구 사용 오류를 해결하세요.
완전한 Docker 기반 구현으로 시작하세요.
Claude를 외부 도구 및 API에 연결하세요. 도구가 실행되는 위치, Claude가 도구를 호출하는 시점, 작업에 적합한 도구를 확인하세요.
해상도, 사고 노력 수준, 컨텍스트 관리에 대한 벤치마크 기반 권장 사항.
브라우저 내에서 끝나는 작업의 경우, Claude가 여러분의 브라우저 환경에서 웹페이지를 탐색하고, 읽고, 상호작용하도록 하세요.
## 제공 여부
컴퓨터 사용 도구은(는) 일부 모델에서 사용 가능 또는 베타 상태이며 제로 데이터 보존 및 HIPAA 대비에 적격합니다.
### API 지원
#### [Messages API](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages)
* 제공 여부: 사용 가능
| 상태 | 클라우드 플랫폼 | 모델 |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 사용 가능 | Claude API, [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/ko/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/ko/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/ko/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/ko/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/ko/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/ko/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/ko/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/ko/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/ko/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/ko/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/ko/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/ko/models/opus-4-8/overview) |
| 사용 가능 | [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock), [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/ko/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/ko/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/ko/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/ko/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/ko/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/ko/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/ko/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/ko/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/ko/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/ko/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/ko/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/ko/models/opus-4-8/overview) |
| 베타 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) | [Claude Haiku 4.5](https://platform.claude.com/docs/ko/models/haiku-4-5/overview), [Claude Opus 4.7](https://platform.claude.com/docs/ko/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/ko/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/ko/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/ko/models/opus-4-5/overview), [Claude Sonnet 4.5](https://platform.claude.com/docs/ko/models/sonnet-4-5/overview) |
#### [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)
* 제공 여부: 사용 불가
### 필수 베타 헤더
[베타 헤더 개요](https://platform.claude.com/docs/ko/api/beta-headers)
베타 헤더를 사용하면 실험적 기능과 새로운 모델 기능이 표준 API에 포함되기 전에 액세스할 수 있습니다.
| 헤더 | 모델 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `computer-use-2025-11-24` | [Claude Opus 4.7](https://platform.claude.com/docs/ko/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/ko/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/ko/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/ko/models/opus-4-5/overview) |
| `computer-use-2025-01-24` | [Claude Haiku 4.5](https://platform.claude.com/docs/ko/models/haiku-4-5/overview), [Claude Sonnet 4.5](https://platform.claude.com/docs/ko/models/sonnet-4-5/overview) |
### 데이터 처리
[데이터 처리 개요](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#feature-eligibility)
| 항목 | 제로 데이터 보존 | HIPAA |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| 상태 | 적격([적용 모델](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) 제외) | 적격 |
| 세부 정보 | 스크린샷과 파일이 Anthropic이 아닌 사용자 환경에서 캡처되고 저장되는 클라이언트 측 도구입니다. [자세히 알아보기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#data-retention) | — |
적용 엔드포인트:
* `/v1/messages` `computer` 도구 세트 또는 도구 사용 시