도구 사용 - Amazon Bedrock
세분화된 도구 스트리밍컴퓨터 사용(베타)Anthropic 정의된 도구도구 사용에 대한 비용 고려 사항

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

도구 사용

Anthropic Claude 모델을 사용하면 모델이 메시지에 응답하는 데 사용할 수 있는 도구를 지정할 수 있습니다. 예를 들어, 라디오 방송국에서 가장 인기 있는 노래를 가져오는 도구를 지정할 수 있습니다. 사용자가 WZPZ에서 가장 인기 있는 노래는 무엇입니까?라는 메시지를 전달하면 모델은 지정한 도구가 질문에 답하는 데 도움이 될 수 있다고 판단합니다. 응답에서 모델은 사용자에게 해당 도구를 실행해 달라고 요청합니다. 사용자가 도구를 실행하고 도구 결과를 모델에 전달하면 원래 메시지에 대한 응답이 생성됩니다. 자세한 내용은 Anthropic Claude 설명서의 도구 사용(함수 호출)을 참조하세요.

작은 정보

API를 사용하여 도구 사용을 애플리케이션에 Converse 통합하는 것이 좋습니다. 자세한 내용은 도구를 사용하여 Amazon Bedrock 모델 응답 완성 단원을 참조하십시오.

tools 필드에서 모델이 사용할 수 있게 하려는 도구를 지정합니다. 다음 예제는 라디오 방송국에서 가장 인기 있는 노래를 가져오는 도구입니다.

[
    {
        "name": "top_song",
        "description": "Get the most popular song played on a radio station.",
        "input_schema": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                }
            },
            "required": [
                "sign"
            ]
        }
    }
]

모델에 메시지에 대한 응답을 생성하는 도구가 필요한 경우, 요청된 도구에 대한 정보와 도구에 대한 입력이 메시지 content 필드에 반환됩니다. 모델은 tool_use에 대한 응답의 중지 이유도 설정합니다.

{
    "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 375,
        "output_tokens": 36
    },
    "content": [
        {
            "type": "tool_use",
            "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "name": "top_song",
            "input": {
                "sign": "WZPZ"
            }
        }
    ],
    "stop_reason": "tool_use"
}

코드에서 사용자가 도구를 대신하여 도구를 직접 호출합니다. 그런 다음 사용자 메시지의 도구 결과(tool_result)를 모델에 전달합니다.

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "content": "Elemental Hotel"
        }
    ]
}

응답에서 모델은 도구 결과를 사용하여 원본 메시지에 대한 응답을 생성합니다.

{
    "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "content": [
        {
            "type": "text",
            "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"."
        }
    ],
    "stop_reason": "end_turn"
}

세분화된 도구 스트리밍

세분화된 도구 스트리밍은 Claude Sonnet 4, 및 Claude Opus 4에서 사용할 수 있는 Anthropic Claude 모델 기능입니다. 개발자는 세분화된 도구 스트리밍을 통해 버퍼링 또는 JSON 검증 없이 파라미터를 사용하여 도구를 스트리밍하여 대규모 파라미터 수신을 시작하는 지연 시간을 줄일 Claude 수 있습니다.

참고

세분화된 도구 스트리밍을 사용하는 경우 유효하지 않거나 부분적인 JSON 입력을 수신할 수 있습니다. 코드에서 이러한 엣지 케이스를 고려해야 합니다.

이 기능을 사용하려면 도구 사용 요청에 헤더를 추가하기만 fine-grained-tool-streaming-2025-05-14 하면 됩니다.

다음은 세분화된 도구 스트리밍 헤더를 지정하는 방법의 예입니다.

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 1024,
  "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"],
  "messages": [
    {
      "role": "user",
      "content": "Can you write a long poem and make a file called poem.txt?"
    }
  ],
  "tools": [
    {
      "name": "make_file",
      "description": "Write text to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The filename to write text to"
          },
          "lines_of_text": {
            "type": "array",
            "description": "An array of lines of text to write to the file"
          }
        },
        "required": [
          "filename",
          "lines_of_text"
        ]
      }
    }
  ]
}

이 예제에서는 세분화된 도구 스트리밍을 통해 Claude는 lines_of_text 파라미터가 유효한 JSON인지 검증하기 위해 버퍼링 make_file 없이 긴 시의 라인을 도구 호출로 스트리밍할 수 있습니다. 즉, 전체 파라미터가 버퍼링되고 검증될 때까지 기다릴 필요 없이 파라미터 스트림이 도착하면 볼 수 있습니다.

세분화된 도구 스트리밍을 사용하면 도구 사용 청크가 더 빠르게 스트리밍을 시작하고, 종종 더 길고 단어 나누기가 적습니다. 이는 청킹 동작의 차이 때문입니다.

예를 들어 세분화된 스트리밍(15초 지연)이 없는 경우:

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

세분화된 스트리밍(3초 지연):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'
참고

세분화된 스트리밍은 버퍼링 또는 JSON 검증 없이 파라미터를 전송하므로 결과 스트림이 유효한 JSON 문자열에서 완료된다는 보장은 없습니다. 특히 중지 이유에 도달하면 스트림max_tokens이 파라미터 중간에 종료되어 불완전할 수 있습니다. 일반적으로에 도달하면 처리하려면 특정 지원을 작성해야 max_tokens 합니다.

컴퓨터 사용(베타)

컴퓨터 사용은 Claude 3.5 Sonnet v2, Claude 3.7 Sonnet, Claude Sonnet 4및 Claude Opus4에서 사용할 수 있는 Anthropic Claude 모델 기능(베타)입니다. 컴퓨터 사용 기능을 사용하면 Claude가 기본 GUI 작업을 통해 작업을 자동화하는 데 도움을 줍니다.

주의

컴퓨터 사용 기능은 서비스 약관에 정의된 대로 '베타 AWS 서비스'로 사용할 수 있습니다. 여기에는 계약 AWS 및 AWS 서비스 약관과 해당 모델 EULA가 적용됩니다. Computer Use API는 표준 API 기능 또는 채팅 인터페이스와는 다른 고유한 위험을 초래한다는 점에 유의하세요. 이러한 위험은 Computer Use API를 사용하여 인터넷과 상호 작용할 때 더욱 커집니다. 위험을 최소화하려면 다음과 같은 예방 조치를 취하는 것이 좋습니다.

  • 전용 가상 머신 또는 컨테이너에서 컴퓨터 사용 기능을 최소한의 권한으로 작동하여 직접 시스템 공격 또는 사고를 방지합니다.

  • 정보 도난을 방지할 수 있도록 민감한 계정 또는 데이터에 대한 Computer Use API 액세스 권한을 부여하지 마세요.

  • 컴퓨터 사용 APIs 인터넷 액세스를 필요한 도메인으로 제한하여 악성 콘텐츠에 대한 노출을 줄입니다.

  • 적절한 감독이 이루어질 수 있도록, 민감한 작업(예: 의미 있는 실제 결과로 이어질 수 있는 의사 결정)과 긍정적인 동의가 필요한 모든 작업(예: 쿠키 허용, 금융 거래 실행 또는 서비스 약관 동의)에 대해 사람을 루프에 관여시킵니다.

Claude가 확인하거나 액세스할 수 있도록 설정한 모든 콘텐츠로 인해 지침이 재정의되거나, Claude의 실수 또는 의도하지 않은 작업 수행이 발생할 수 있습니다. 프롬프트 인젝션과 관련된 위험을 방지하기 위해서는 민감한 표면에서 Claude를 격리하는 등 적절한 예방 조치를 취하는 것이 중요합니다. 자체 제품에서 컴퓨터 사용 기능을 설정하는 데 필요한 권한을 활성화하거나 요청하기 전에 최종 사용자에게 관련 위험을 알리고 필요한 경우 동의를 얻으시기 바랍니다.

컴퓨터 사용 API는 사용자가 사용할 수 있도록 사전 정의된 여러 컴퓨터 사용 도구를 제공합니다. 그런 다음 “지난 회의의 메모가 포함된 이메일을 Ben에게 전송해 줘” 같은 프롬프트와 스크린샷(필요한 경우)과 같은 프롬프트를 작성할 수 있습니다. 응답에는 JSON 형식의 tool_use 작업 목록이 포함됩니다(예: scroll_down, left_button_press, screenshot). 코드는 컴퓨터 작업을 실행하고, Claude에 요청 시 출력을 보여주는 스크린샷을 제공합니다.

Claude 3.5 v2 릴리스 이후 다형성 도구 유형을 허용하도록 도구 파라미터가 업데이트되었습니다. tool.type 속성을 추가하여 이를 구분했습니다. type는 선택 사항입니다. 생략할 경우 도구는 사용자 지정 도구(이전에는 유일하게 지원되는 도구 유형)로 간주됩니다. 컴퓨터 사용에 액세스하려면 파라미터를 사용 중인 모델 버전에 따라 값이 달라지는 해당 열거형과 anthropic_beta 함께 사용해야 합니다. 자세한 정보는 다음 표를 참조하세요.

이 파라미터 및 열거형으로 이루어진 요청만 컴퓨터 사용 도구를 사용할 수 있습니다. 이렇게 지정할 수 있습니다. "anthropic_beta": ["computer-use-2025-01-24"]

모델 베타 헤더

Claude Opus 4.1

Claude Opus 4

Claude Sonnet 4

Claude 3.7 Sonnet

 컴퓨터 사용-2025-01-24
Claude 3.5 Sonnet v2 컴퓨터 사용-2024-10-22

자세한 내용은 Anthropic 설명서의 컴퓨터 사용(베타)을 참조하세요.

다음은 Firefox 아이콘이 있는 바탕 화면의 스크린샷이 요청에 포함되어 있다고 가정한 응답 예제입니다.

{
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "content": [
        {
            "type": "text",
            "text": "I see the Firefox icon. Let me click on it and then navigate to a weather website."
        },
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "computer",
            "input": {
                "action": "mouse_move",
                "coordinate": [
                    708,
                    736
                ]
            }
        },
        {
            "type": "tool_use",
            "id": "toolu_234",
            "name": "computer",
            "input": {
                "action": "left_click"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 3391,
        "output_tokens": 132
    }
}

Anthropic 정의된 도구

Anthropic는 특정 Claude 모델이 컴퓨터를 효과적으로 사용할 수 있도록 일련의 도구를 제공합니다. Anthropic 정의된 도구를 지정할 때 description 및 tool_schema 필드는 필요하지 않거나 허용되지 않습니다. Anthropic 정의된 도구는에서 정의Anthropic하지만 도구의 결과를 명시적으로 평가하고를 tool_results에 반환해야 합니다Claude. 다른 도구와 마찬가지로 모델은 도구를 자동으로 실행하지 않습니다. Anthropic 정의된 각 도구에는 특정 모델Claude 3.5 Sonnet(신규) 및에 최적화된 버전이 Claude 3.7 Sonnet있습니다.

모델

도구

Notes

Claude Claude Opus 4.1

Claude Claude Opus 4

Claude Sonnet 4

 
{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_based_edit_tool" 
}

기존 str_replace_editor 도구 업데이트

Claude 3.7 Sonnet

 
{ 
    "type": "computer_20250124", 
    "name": "computer" 
}

보다 정확한 제어를 위한 새로운 작업 포함

Claude 3.7 Sonnet

 
{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_editor"
}

20241022 버전과 동일한 기능

Claude 3.5 Sonnet v2

 
{ 
    "type": "bash_20250124", 
    "name": "bash" 
}

20241022 버전과 동일한 기능

Claude 3.5 Sonnet v2

 
{ 
    "type": "text_editor_20241022", 
    "name": "str_replace_editor"
}

Claude 3.5 Sonnet v2

 
{ 
    "type": "bash_20241022", 
    "name": "bash"
}

Claude 3.5 Sonnet v2

 
{ 
    "type": "computer_20241022", 
    "name": "computer"
}

type 필드는 검증을 위해 도구와 해당 파라미터를 식별하며, name 필드는 모델에 노출된 도구 이름입니다.

이러한 도구 중 하나를 사용하도록 모델에 프롬프트를 표시하려면 name 필드별로 도구를 명시적으로 참조할 수 있습니다. name 필드는 도구 목록 내에서 고유해야 합니다. 동일한 API 호출에서 Anthropic 정의된 도구와 동일한 name 로 도구를 정의할 수 없습니다.

도구 사용에 대한 비용 고려 사항

도구 사용 요청은 다음 요인에 따라 요금이 책정됩니다.

  1. 모델로 전송된 총 입력 토큰 수(도구 파라미터에 포함).

  2. 생성된 출력 토큰 수입니다.

도구는 다른 모든 Claude API 요청과 가격이 동일하지만 요청당 추가 토큰을 포함합니다. 도구 사용의 추가 토큰은 다음에서 가져옵니다.

  • API 요청의 tools 파라미터입니다. 예: 도구 이름, 설명 및 스키마.

  • API 요청 및 응답의 모든 tool_use 콘텐츠 블록.

  • API 요청의 모든 tool_result 콘텐츠 블록.

도구를 사용하면 Anthropic 모델에는 도구 사용을 활성화하는 특수 시스템 프롬프트가 자동으로 포함됩니다. 각 모델에 필요한 도구 사용 토큰 수는 다음 표에 나와 있습니다. 이 표에는 앞서 설명한 추가 토큰이 제외됩니다. 이 표는 하나 이상의 도구가 제공되었다고 가정합니다. 도구가 제공되지 않은 경우 아무것도 선택하지 않으면 0개의 추가 시스템 프롬프트 토큰이 사용됩니다.

모델 도구 선택 도구 사용 시스템 프롬프트 토큰 수

Claude Opus 4.1

Claude Opus 4

Claude Sonnet 4

Claude 3.7 Sonnet

Claude 3.5 Sonnet v2

 auto 또는 none 346

Claude Opus 4.1

Claude Opus 4

Claude Sonnet 4

Claude 3.7 Sonnet

Claude 3.5 Sonnet v2

 any 또는 tool 313

Claude 3.5 Sonnet

 auto 또는 none 294

Claude 3.5 Sonnet

 any 또는 tool 261

Claude 3 Opus

 auto 또는 none 530

Claude 3 Opus

 any 또는 tool 281

Claude 3 Sonnet

 auto 또는 none 159

Claude 3 Sonnet

 any 또는 tool 235

Claude 3 Haiku

 auto 또는 none 264

Claude 3 Haiku

 any 또는 tool 340