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

도구 사용은 이제 Anthropic Messages API, Amazon Bedrock 및 Google Vertex AI를 사용하는 개발자를 위해 Claude 3 모델 제품군 전체에서 일반적으로 사용할 수 있습니다! 이 양식을 사용하여 계속 아이디어와 제안을 공유해 주세요.

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "주어진 위치의 현재 날씨를 가져옵니다",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "도시와 주, 예: San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "샌프란시스코의 날씨는 어떤가요?"
      }
    ]
  }'

​
도구 사용 방법

Claude와 도구를 사용하는 것은 다음 단계를 포함합니다:

  1. Claude에 도구와 사용자 프롬프트 제공: (API 요청)
    • Claude가 액세스할 도구 세트를 정의하고 이름, 설명 및 입력 스키마를 포함합니다.
    • “샌프란시스코의 날씨는 어떤가요?”와 같이 이러한 도구 중 하나 이상을 사용해야 할 수 있는 사용자 프롬프트를 제공합니다.
  2. Claude가 도구 사용: (API 응답)
    • Claude는 사용자 프롬프트를 평가하고 사용 가능한 도구 중 사용자의 질의나 작업에 도움이 될 도구가 있는지 결정합니다. 그렇다면 어떤 도구를 사용할지와 어떤 입력을 사용할지도 결정합니다.
    • Claude는 적절한 형식의 도구 사용 요청을 구성합니다.
    • API 응답에는 Claude가 외부 도구를 사용하려고 함을 나타내는 tool_use의 stop_reason이 포함됩니다.
  3. 도구 입력 추출, 코드 실행 및 결과 반환: (API 요청)
    • 클라이언트 측에서 Claude의 도구 사용 요청에서 도구 이름과 입력을 추출해야 합니다.
    • 클라이언트 측에서 실제 도구 코드를 실행합니다.
    • tool_result 콘텐츠 블록이 포함된 새로운 user 메시지로 대화를 계속하여 결과를 Claude에 반환합니다.
  4. Claude가 도구 결과를 사용하여 응답 구성: (API 응답)
    • 도구 결과를 받은 후 Claude는 해당 정보를 사용하여 원래 사용자 프롬프트에 대한 최종 응답을 구성합니다.

(3)단계와 (4)단계는 선택 사항입니다. 일부 워크플로의 경우 Claude가 도구를 사용하는 것이 필요한 모든 정보일 수 있으며 도구 결과를 Claude에 반환할 필요가 없을 수 있습니다.

모든 도구는 사용자가 제공합니다

Claude에는 내장된 서버 측 도구에 액세스할 수 없다는 점에 유의하는 것이 중요합니다. 모든 도구는 각 API 요청에서 사용자가 명시적으로 제공해야 합니다. 이를 통해 Claude가 사용할 수 있는 도구에 대한 완전한 제어와 유연성을 제공합니다.

​
도구 지정

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

  • name: 도구의 이름. 정규식 ^[a-zA-Z0-9_-]{1,64}$와 일치해야 합니다.
  • description: 도구가 수행하는 작업, 사용해야 할 시기 및 동작 방식에 대한 자세한 일반 텍스트 설명입니다.
  • input_schema: 도구에 대한 예상 매개변수를 정의하는 JSON 스키마 객체입니다.

간단한 도구 정의의 예시입니다:

JSON
{
  "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"]
  }
}

get_weather라는 이 도구는 필수 location 문자열과 “celsius” 또는 “fahrenheit” 중 하나여야 하는 선택적 unit 문자열이 있는 입력 객체를 예상합니다.

​
도구 정의를 위한 모범 사례

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

  • 매우 자세한 설명을 제공하세요. 이것은 도구 성능에 가장 중요한 요소입니다. 설명에는 다음을 포함하여 도구에 대한 모든 세부 정보를 설명해야 합니다:
    • 도구가 수행하는 작업
    • 사용해야 할 시기(및 사용하지 말아야 할 시기)
    • 각 매개변수의 의미와 도구의 동작에 미치는 영향
    • 도구 이름이 명확하지 않은 경우 도구가 반환하지 않는 정보와 같은 중요한 주의 사항이나 제한 사항 Claude에 도구에 대해 더 많은 맥락을 제공할수록 도구를 사용할 시기와 방법을 더 잘 결정할 수 있습니다. 도구 설명당 최소 3-4 문장을 목표로 하고, 도구가 복잡한 경우 더 많이 설명하세요.
  • 예제보다 설명에 우선순위를 두세요. 도구 설명이나 함께 제공되는 프롬프트에 도구 사용 방법의 예를 포함할 수 있지만, 이는 도구의 목적과 매개변수에 대한 명확하고 포괄적인 설명보다 덜 중요합니다. 설명을 완전히 보완한 후에만 예제를 추가하세요.

좋은 도구 설명의 예시입니다:

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

반면에 다음은 좋지 않은 도구 설명의 예시입니다:

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

좋은 설명은 도구가 수행하는 작업, 사용 시기, 반환되는 데이터 및 ticker 매개변수의 의미를 명확하게 설명합니다. 좋지 않은 설명은 너무 간단하며 도구의 동작과 사용법에 대해 Claude에게 많은 의문을 남깁니다.

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

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

  • id: 이 특정 도구 사용 블록에 대한 고유 식별자입니다. 이는 나중에 도구 결과를 일치시키는 데 사용됩니다.
  • name: 사용 중인 도구의 이름입니다.
  • input: 도구의 input_schema에 맞는 도구에 전달되는 입력이 포함된 객체입니다.

tool_use 콘텐츠 블록이 포함된 API 응답의 예시입니다:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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. [선택 사항] user의 role과 다음 정보가 포함된 tool_result 유형의 content 블록이 포함된 새 메시지를 보내 대화를 계속합니다:
    • tool_use_id: 이 결과에 대한 도구 사용 요청의 id입니다.
    • content: 문자열(예: "content": "15도") 이나 중첩된 콘텐츠 블록 목록(예: "content": [{"type": "text", "text": "15도"}])으로 된 도구의 결과입니다. 이러한 콘텐츠 블록은 text 또는 image 유형을 사용할 수 있습니다.
    • is_error (선택 사항): 도구 실행 결과 오류가 발생한 경우 true로 설정합니다.

성공적인 도구 결과를 반환하는 예시입니다:

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

content에서 이미지도 지원됩니다:

JSON
{
  "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...",
          }
        }
      ]
    }
  ]
}

오류 결과를 반환하는 예시입니다:

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

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

출력 없이 도구가 성공적으로 실행되었음을 나타내는 빈 content로 오류가 없는 도구 결과를 반환할 수도 있습니다:

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

다른 API와의 차이점

도구 사용이 모델의 기본 출력과 별도로 반환되거나 특수 목적의 tool 또는 function 메시지 role을 사용하는 다른 API에 익숙할 수 있습니다.

반면에 Anthropic의 모델과 API는 user와 assistant 메시지가 번갈아 가며 각 메시지가 text, image, tool_use 및 tool_result와 같은 풍부한 콘텐츠 블록의 배열인 것을 중심으로 구축됩니다.

이 형식에서 user 메시지는 클라이언트 측 및 사용자/인간이 관리하는 콘텐츠를 나타내고 assistant 메시지는 서버 측 및 AI가 관리하는 콘텐츠를 나타냅니다. 따라서 특별한 tool 또는 function 메시지 role이 없으며 user 메시지의 content에 tool_result 블록을 포함해야 합니다.

​
도구 사용 강제

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

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

get_weather 도구를 사용하도록 Claude에 명시적으로 지시함으로써 원하는 도구를 사용하도록 유도할 수 있습니다. 이 기술은 도구 통합을 테스트하고 디버깅하거나 입력에 관계없이 항상 도구를 사용해야 하는 경우에 유용할 수 있습니다.

또한 {"type": "any"}를 통해 제공된 도구 중 하나를 사용하도록 Claude에 지시할 수 있습니다. 기본 tool_choice는 {"type": "auto"}로, Claude가 도구를 사용할지 여부를 결정할 수 있습니다.

tool_choice가 any 또는 tool일 때 도구를 강제로 사용하도록 assistant 메시지를 미리 채운다는 점에 유의하세요. 이는 명시적으로 요청하더라도 모델이 tool_use 콘텐츠 블록 앞에 사고 연쇄 text 콘텐츠 블록을 내보내지 않음을 의미합니다. 테스트에 따르면 이로 인해 성능이 저하되지 않아야 합니다. 특정 도구를 사용하도록 요청하면서 사고 연쇄(특히 Opus에서)를 유지하려면 tool_choice에 {"type": "auto"}를 사용하고(기본값) user 메시지에 명시적 지침을 추가할 수 있습니다. 예를 들어 런던의 날씨는 어떤가요? 응답에서 get_weather 도구를 사용하세요.와 같이 할 수 있습니다.

​
JSON 출력

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

​
오류 처리

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

​
도구 실행 오류

도구 실행 중 도구 자체에서 오류가 발생하면(예: 날씨 데이터를 가져올 때 네트워크 오류) "is_error": true와 함께 content에 오류 메시지를 반환할 수 있습니다:

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

그러면 Claude는 이 오류를 사용자에 대한 응답에 통합합니다(예: “죄송합니다. 날씨 서비스 API를 사용할 수 없어 현재 날씨를 검색할 수 없습니다. 나중에 다시 시도해 주세요.”).

​
최대 토큰 초과

Claude의 응답이 max_tokens 제한에 도달하여 잘리고 잘린 응답에 불완전한 도구 사용 블록이 포함된 경우 max_tokens 값을 높여 요청을 다시 시도하여 전체 도구 사용을 얻어야 합니다.

​
잘못된 도구 사용

Claude의 도구 사용 시도가 잘못된 경우(예: 필수 매개변수 누락) 일반적으로 Claude가 도구를 올바르게 사용하기에 충분한 정보가 없음을 의미합니다. 개발 중에는 도구 정의에서 더 자세한 description 값으로 요청을 다시 시도하는 것이 가장 좋습니다.

그러나 오류를 나타내는 tool_result로 대화를 계속 진행할 수도 있으며 Claude는 누락된 정보를 채워 도구를 다시 사용하려고 시도합니다:

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

​
사고 연쇄 도구 사용

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

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

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>이 질문에 답하기 위해 다음을 수행합니다: 1. get_weather 도구를 사용하여 샌프란시스코의 현재 날씨를 가져옵니다. 2. get_time 도구를 사용하여 샌프란시스코를 포함하는 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와 도구를 사용할 때는 다음과 같은 제한 사항과 모범 사례를 염두에 두세요:

  • 복잡한 도구 사용 탐색에는 Claude 3 Opus를, 간단한 도구를 다룰 때는 Haiku를 사용하세요: Opus는 다른 모델에 비해 가장 많은 동시 도구를 처리할 수 있으며 누락된 인수를 더 잘 포착합니다. 인수가 명시적으로 제공되지 않거나 도구가 사용자 요청을 완료하는 데 필요하지 않을 수 있는 모호한 경우 명확히 하도록 요청할 가능성이 더 높습니다. Haiku는 기본적으로 도구를 더 자주 사용하려고 시도하며(쿼리와 관련이 없더라도) 명시적으로 제공되지 않은 경우 누락된 매개변수를 추론합니다.
  • 도구 수: 모든 Claude 3 모델은 수백 개의 간단한 도구와 더 적은 수의 복잡한 도구로 작업할 때도 90% 이상의 정확도를 유지할 수 있습니다. “복잡한” 도구는 많은 수의 매개변수 또는 복잡한 스키마(예: 중첩된 객체)가 있는 매개변수가 있는 도구입니다.
  • 복잡하고 깊이 중첩된 도구: 사람과 마찬가지로 Claude는 더 간단한 인터페이스와 더 간단한 도구로 더 잘 작동할 수 있습니다. Claude가 도구를 올바르게 사용하는 데 어려움을 겪는 경우 입력 스키마를 깊이 중첩된 JSON 객체에서 평면화하고 입력 수를 줄이세요.
  • 순차적 도구 사용: Claude는 일반적으로 한 번에 하나의 도구를 사용한 다음 해당 도구의 출력을 사용하여 다음 작업을 알리는 것을 선호합니다. 프롬프트와 도구를 신중하게 설계하여 Claude가 여러 도구를 병렬로 사용하도록 프롬프트할 수 있지만, 이로 인해 Claude가 이전 도구 사용 결과에 따라 달라지는 매개변수에 더미 값을 채울 수 있습니다. 최상의 결과를 얻으려면 워크플로와 도구를 설계하여 Claude에서 일련의 순차적 도구 사용을 유도하고 이를 활용하세요.
  • 재시도: Claude의 도구 사용 요청이 잘못되었거나 필수 매개변수가 누락된 경우 오류 응답을 반환하면 Claude는 일반적으로 누락된 정보를 채워 요청을 다시 시도합니다. 그러나 2-3번의 실패한 시도 후에는 Claude가 더 이상 재시도하지 않고 사용자에게 사과를 반환할 수 있습니다.
  • 디버깅: 예기치 않은 도구 사용 동작을 디버깅할 때는 Claude의 사고 연쇄 출력(있는 경우)에 주의를 기울여 선택한 이유를 이해하세요. 또한 Claude에 특정 도구를 사용하도록 프롬프트하여 예상 동작으로 이어지는지 확인할 수 있습니다. Claude가 도구를 잘못 사용하는 경우 도구 설명과 스키마가 명확하고 모호하지 않은지 다시 확인하세요.
  • <search_quality_reflection> 태그: 검색 도구를 사용할 때 모델이 응답에서 <search_quality_reflection> XML 태그와 검색 품질 점수를 반환할 수 있습니다. 모델이 이를 수행하지 않도록 하려면 프롬프트 끝에 “응답에서 반환된 검색 결과의 품질을 반영하지 마세요.”라는 문장을 추가하세요.

이러한 제한 사항과 지침을 염두에 두면 Claude의 기능을 크게 확장하여 다양한 작업을 처리할 수 있는 효과적인 도구와 에이전트 오케스트레이션을 설계할 수 있습니다.

​
다음 단계

도구 사용은 Claude를 외부 데이터 소스 및 기능에 연결하여 Claude의 기능을 확장하는 강력한 기술입니다. 잘 설계된 도구 세트를 사용하면 Claude가 기본 지식만으로는 불가능한 다양한 작업을 처리할 수 있습니다.

몇 가지 잠재적인 다음 단계는 다음과 같습니다:

  • 도구 사용 요리책 탐색: 다음과 같은 바로 구현할 수 있는 도구 사용 코드 예제 저장소를 탐색하세요:
  • 도구 사용 품질 및 신뢰성 향상: Claude에서 더 안정적이고 정확한 도구 사용을 유도하기 위해 도구 설명과 프롬프트를 반복하고 개선하세요
  • Claude의 기능 확장:
    • 다양한 도구와 스키마를 실험하여 Claude가 다양한 유형의 입력 및 출력 형식을 어떻게 처리하는지 확인하세요.
    • 복잡한 작업을 일련의 더 간단한 단계로 분해하기 위해 여러 도구를 함께 연결하세요.
    • Claude가 에이전트인 것처럼 다양한 작업을 처음부터 끝까지 완료할 수 있는 에이전트 오케스트레이션을 구축하세요.
    • Claude에 RAG 검색을 수행하거나 Haiku와 같은 더 작은 모델 하위 에이전트를 호출하여 대신 작업을 수행하는 도구를 제공하는 등 복잡한 도구 사용 아키텍처를 탐색하세요

도구 사용으로 구축할 때 피드백을 듣고 여러분이 만든 것을 보고 싶습니다! 개발자 Discord에 가입하여 프로젝트를 공유하고 다른 개발자와 팁과 기술을 논의하세요.

도구 사용을 통해 Claude로 가능한 것의 한계를 뛰어넘는 방법을 보고 싶습니다. 즐겁게 구축하세요!

Google Sheets 애드온도구 사용 예시