도구 사용 (함수 호출)

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

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

​

도구 사용 방법

다음 단계에 따라 Claude와 외부 도구를 통합합니다:

참고: 3단계와 4단계는 선택 사항입니다. 일부 워크플로의 경우 Claude의 도구 사용 요청(2단계)이 결과를 Claude로 다시 보내지 않고도 필요한 전부일 수 있습니다.

​

도구 사용을 구현하는 방법

​

모델 선택

일반적으로 복잡한 도구와 모호한 쿼리에는 Claude 3 Opus를 사용하세요. 여러 도구를 더 잘 처리하고 필요할 때 명확성을 추구합니다.

간단한 도구에는 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"]
  }
}

​

도구 정의를 위한 모범 사례

도구를 사용할 때 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가 도구를 사용하지 않고 답변을 제공할 수 있다고 생각하더라도 사용자의 질문에 답하기 위해 특정 도구를 사용하도록 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 콘텐츠 블록 앞에 chain-of-thought text 콘텐츠 블록을 내보내지 않음을 의미합니다.

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

​

JSON 출력

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

​

사고의 연쇄

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

예를 들어 “지금 San Francisco의 날씨는 어떤가요? 그리고 거기 시간은 몇 시인가요?”라는 프롬프트가 주어지면 Claude는 다음과 같이 응답할 수 있습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>이 질문에 답하기 위해 다음을 수행합니다: 1. get_weather 도구를 사용하여 San Francisco의 현재 날씨를 가져옵니다. 2. get_time 도구를 사용하여 San Francisco, 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가 제공한 도구 중 하나를 사용하기로 결정하면 API 응답에 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록과 함께 tool_use의 stop_reason이 있는 응답을 반환합니다:

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "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이고 content 블록에 다음 정보가 포함된 tool_result 유형이 포함된 새 메시지를 보내 대화를 계속합니다:
   • 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-20240620",
  "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-20240620",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "현재 San Francisco의 날씨는 섭씨 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 메트릭의 일부로 입력 및 출력 토큰 수가 모두 출력됩니다.

​

다음 단계

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