도구 사용 (함수 호출)

Claude는 외부 클라이언트 측 도구 및 함수와 상호작용할 수 있어, 더 다양한 작업을 수행할 수 있도록 Claude에 사용자 지정 도구를 장착할 수 있습니다.

다음은 Messages API를 사용하여 Claude에 도구를 제공하는 방법의 예시입니다:

​

도구 사용 작동 방식

다음 단계로 외부 도구를 Claude와 통합하세요:

참고: 3단계와 4단계는 선택사항입니다. 일부 워크플로우의 경우 Claude의 도구 사용 요청(2단계)만으로도 충분할 수 있으며, Claude에 결과를 다시 보낼 필요가 없습니다.

​

도구 사용 구현 방법

​

모델 선택

일반적으로 복잡한 도구와 모호한 쿼리에는 Claude 3.5 Sonnet 또는 Claude 3 Opus를 사용하세요; 이들은 여러 도구를 더 잘 처리하고 필요할 때 명확한 설명을 요청합니다.

간단한 도구에는 Claude 3.5 Haiku 또는 Claude 3 Haiku를 사용하세요. 단, 누락된 매개변수를 추론할 수 있다는 점에 유의하세요.

​

도구 지정

도구는 API 요청의 최상위 tools 매개변수에 지정됩니다. 각 도구 정의에는 다음이 포함됩니다:

{
  "name": "get_weather",
  "description": "주어진 위치의 현재 날씨를 가져옵니다",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "도시와 주, 예: San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "온도 단위, 'celsius' 또는 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

도구 사용 시스템 프롬프트

Anthropic API를 tools 매개변수와 함께 호출하면, 도구 정의, 도구 구성 및 사용자가 지정한 시스템 프롬프트에서 특별한 시스템 프롬프트를 구성합니다. 구성된 프롬프트는 모델에게 지정된 도구를 사용하도록 지시하고 도구가 제대로 작동하는 데 필요한 컨텍스트를 제공하도록 설계되었습니다:

이 환경에서는 사용자의 질문에 답하는 데 사용할 수 있는 도구 세트에 접근할 수 있습니다.
{{ 형식 지정 지침 }}
문자열과 스칼라 매개변수는 있는 그대로 지정해야 하며, 리스트와 객체는 JSON 형식을 사용해야 합니다. 문자열 값의 공백은 제거되지 않습니다. 출력은 유효한 XML일 필요가 없으며 정규식으로 구문 분석됩니다.
다음은 JSONSchema 형식으로 사용 가능한 함수입니다:
{{ JSON SCHEMA의 도구 정의 }}
{{ 사용자 시스템 프롬프트 }}
{{ 도구 구성 }}

​

도구 정의 모범 사례

도구를 사용할 때 Claude에서 최상의 성능을 얻으려면 다음 지침을 따르세요:

• 매우 자세한 설명을 제공하세요. 이것이 도구 성능에서 가장 중요한 요소입니다. 설명에는 다음과 같은 모든 세부 사항이 포함되어야 합니다:
  • 도구가 하는 일
  • 언제 사용해야 하는지(그리고 언제 사용하지 말아야 하는지)
  • 각 매개변수가 의미하는 바와 도구의 동작에 어떤 영향을 미치는지
  • 도구 이름이 불분명한 경우 도구가 반환하지 않는 정보와 같은 중요한 주의사항이나 제한사항. Claude에게 도구에 대한 더 많은 컨텍스트를 제공할수록 도구를 언제 어떻게 사용할지 더 잘 결정할 수 있습니다. 도구 설명당 최소 3-4문장을 목표로 하고, 도구가 복잡한 경우 더 많이 작성하세요.
• 예시보다 설명을 우선시하세요. 도구 설명이나 동반되는 프롬프트에 도구 사용 예시를 포함할 수 있지만, 이는 도구의 목적과 매개변수에 대한 명확하고 포괄적인 설명을 갖는 것보다 덜 중요합니다. 설명을 완전히 작성한 후에만 예시를 추가하세요.

{
  "name": "get_stock_price",
  "description": "주어진 티커 심볼에 대한 현재 주가를 검색합니다. 티커 심볼은 NYSE나 NASDAQ과 같은 주요 미국 증권거래소에 상장된 공개 기업의 유효한 심볼이어야 합니다. 이 도구는 USD로 최신 거래 가격을 반환합니다. 특정 주식의 현재 또는 가장 최근 가격에 대해 사용자가 문의할 때 사용해야 합니다. 주식이나 회사에 대한 다른 정보는 제공하지 않습니다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "주식 티커 심볼, 예: Apple Inc.의 경우 AAPL"
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "티커에 대한 주가를 가져옵니다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

좋은 설명은 도구가 하는 일, 언제 사용해야 하는지, 어떤 데이터를 반환하는지, ticker 매개변수가 의미하는 바를 명확하게 설명합니다. 나쁜 설명은 너무 간단하여 도구의 동작과 사용에 대해 Claude에게 많은 의문을 남깁니다.

​

Claude의 출력 제어

​

도구 사용 강제

경우에 따라 Claude가 도구 없이도 답변할 수 있다고 생각하더라도 사용자의 질문에 답하기 위해 특정 도구를 사용하도록 하고 싶을 수 있습니다. 다음과 같이 tool_choice 필드에서 도구를 지정하여 이를 수행할 수 있습니다:

tool_choice = {"type": "tool", "name": "get_weather"}

tool_choice 매개변수를 사용할 때 세 가지 옵션이 있습니다:

• auto는 Claude가 제공된 도구를 호출할지 여부를 결정하도록 합니다. 이것이 기본값입니다.
• any는 Claude에게 제공된 도구 중 하나를 반드시 사용해야 한다고 알려주지만, 특정 도구를 강제하지는 않습니다.
• tool을 사용하면 Claude가 항상 특정 도구를 사용하도록 강제할 수 있습니다.

이 다이어그램은 각 옵션이 어떻게 작동하는지 보여줍니다:

tool_choice가 any 또는 tool일 때, 도구가 사용되도록 강제하기 위해 assistant 메시지를 미리 채웁니다. 이는 모델이 명시적으로 요청받더라도 tool_use 콘텐츠 블록 전에 사고 과정 text 콘텐츠 블록을 출력하지 않는다는 것을 의미합니다.

우리의 테스트에 따르면 이것이 성능을 저하시키지 않아야 합니다. 특정 도구를 사용하도록 요청하면서도 사고 과정을 유지하고 싶다면(특히 Opus의 경우), tool_choice에 대해 {"type": "auto"}를 사용하고(기본값) user 메시지에 명시적인 지침을 추가할 수 있습니다. 예: 런던의 날씨는 어떤가요? 응답에서 get_weather 도구를 사용하세요.

​

JSON 출력

도구가 반드시 클라이언트 측 함수일 필요는 없습니다 — 제공된 스키마를 따르는 JSON 출력을 모델이 반환하기를 원할 때마다 도구를 사용할 수 있습니다. 예를 들어, 특정 스키마가 있는 record_summary 도구를 사용할 수 있습니다. 전체 작동 예시는 도구 사용 예시를 참조하세요.

​

사고 과정

도구를 사용할 때 Claude는 종종 “사고 과정”, 즉 문제를 분석하고 어떤 도구를 사용할지 결정하는 데 사용하는 단계별 추론을 보여줍니다. Claude 3 Opus 모델은 tool_choice가 auto로 설정된 경우 이를 수행하며(이것이 기본값입니다. 도구 사용 강제 참조), Sonnet과 Haiku는 프롬프트를 통해 이를 수행하도록 할 수 있습니다.

예를 들어, “지금 샌프란시스코의 날씨는 어떻고 거기는 몇 시인가요?”라는 프롬프트가 주어지면 Claude는 다음과 같이 응답할 수 있습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>이 질문에 답하기 위해: 1. get_weather 도구를 사용하여 샌프란시스코의 현재 날씨를 확인합니다. 2. get_time 도구를 사용하여 샌프란시스코, CA가 포함된 America/Los_Angeles 시간대의 현재 시간을 확인합니다.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

이 사고 과정은 Claude의 추론 과정에 대한 통찰을 제공하고 예상치 못한 동작을 디버깅하는 데 도움이 될 수 있습니다.

Claude 3 Sonnet 모델의 경우, 기본적으로 사고 과정이 덜 일반적이지만 사용자 메시지나 시스템 프롬프트에 "답변하기 전에 태그 안에서 단계별로 추론을 설명하세요."와 같은 내용을 추가하여 Claude가 추론을 보여주도록 프롬프트할 수 있습니다.

<thinking> 태그가 Claude가 사고 과정을 나타내는 데 사용하는 일반적인 규칙이지만, 정확한 형식(예: 이 XML 태그의 이름)은 시간이 지남에 따라 변경될 수 있다는 점에 유의하는 것이 중요합니다. 코드는 사고 과정을 다른 assistant 생성 텍스트처럼 취급해야 하며, <thinking> 태그의 존재나 특정 형식에 의존해서는 안 됩니다.

​

병렬 도구 사용 비활성화

기본적으로 Claude는 사용자 쿼리에 답하기 위해 여러 도구를 사용할 수 있습니다. tool_choice 필드에서 disable_parallel_tool_use=true를 설정하여 이 동작을 비활성화할 수 있습니다.

• tool_choice 유형이 auto인 경우, Claude가 최대 하나의 도구를 사용하도록 보장합니다
• tool_choice 유형이 any 또는 tool인 경우, Claude가 정확히 하나의 도구를 사용하도록 보장합니다

​

도구 사용 및 도구 결과 콘텐츠 블록 처리

Claude가 제공된 도구 중 하나를 사용하기로 결정하면, stop_reason이 tool_use인 응답과 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록을 API 응답으로 반환합니다:

• id: 이 특정 도구 사용 블록의 고유 식별자. 이는 나중에 도구 결과를 매칭하는 데 사용됩니다.
• name: 사용 중인 도구의 이름.
• input: 도구의 input_schema를 준수하는 도구에 전달되는 입력이 포함된 객체.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weather를 사용해야 하고, 사용자가 원하는 SF는 아마도 San Francisco, CA일 것입니다.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

도구 사용 응답을 받으면 다음을 수행해야 합니다:

1. tool_use 블록에서 name, id, input을 추출합니다.
2. 해당 도구 이름에 해당하는 코드베이스의 실제 도구를 실행하고 도구 input을 전달합니다.
3. [선택사항] role이 user인 새 메시지를 보내고 다음 정보가 포함된 tool_result 유형의 content 블록으로 대화를 계속합니다:
   • tool_use_id: 이것이 결과인 도구 사용 요청의 id.
   • content: 문자열(예: "content": "15도") 또는 중첩된 콘텐츠 블록 리스트(예: "content": [{"type": "text", "text": "15도"}])로 된 도구의 결과. 이러한 콘텐츠 블록은 text 또는 image 유형을 사용할 수 있습니다.
   • is_error (선택사항): 도구 실행이 오류로 결과된 경우 true로 설정.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15도"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15도"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

도구 결과를 받은 후, Claude는 해당 정보를 사용하여 원래 사용자 프롬프트에 대한 응답을 계속 생성합니다.

​

오류 해결

Claude와 도구를 사용할 때 발생할 수 있는 몇 가지 유형의 오류가 있습니다:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 날씨 서비스 API를 사용할 수 없습니다 (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "오류: 필수 'location' 매개변수 누락",
      "is_error": true
    }
  ]
}

​

도구 사용 예시

다음은 다양한 도구 사용 패턴과 기술을 보여주는 몇 가지 코드 예시입니다. 간단히 하기 위해 도구는 단순한 도구이며, 최상의 성능을 보장하기 위해 도구 설명은 이상적인 것보다 짧습니다.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weather 함수를 호출해야 하고, 사용자가 원하는 SF는 아마도 San Francisco, CA일 것입니다.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "샌프란시스코의 현재 날씨는 섭씨 15도(화씨 59도)입니다. 베이 에어리어의 시원한 날이네요!"
    }
  ]
}

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

​

가격 책정

도구 사용 요청은 모델에 전송된 총 입력 토큰 수(tools 매개변수 포함)와 생성된 출력 토큰 수를 기준으로 다른 Claude API 요청과 동일하게 가격이 책정됩니다.”

도구 사용으로 인한 추가 토큰은 다음에서 발생합니다:

• API 요청의 tools 매개변수(도구 이름, 설명 및 스키마)
• API 요청 및 응답의 tool_use 콘텐츠 블록
• API 요청의 tool_result 콘텐츠 블록

tools를 사용할 때 도구 사용을 가능하게 하는 특별한 시스템 프롬프트도 모델에 자동으로 포함됩니다. 각 모델에 필요한 도구 사용 토큰 수는 아래에 나열되어 있습니다(위에 나열된 추가 토큰 제외):

이러한 토큰 수는 요청의 총 비용을 계산하기 위해 일반 입력 및 출력 토큰에 추가됩니다. 현재 모델별 가격은 모델 개요 표를 참조하세요.

도구 사용 프롬프트를 보낼 때, 다른 API 요청과 마찬가지로 응답은 보고된 usage 메트릭의 일부로 입력 및 출력 토큰 수를 모두 출력합니다.

​

다음 단계

쿡북에서 바로 구현할 수 있는 도구 사용 코드 예시 저장소를 살펴보세요: