로드 중
로드 중

도구 함수를 작성한 후 다음 단계는 Claude에게 함수가 어떤 인자를 기대하는지와 이를 어떻게 사용해야 하는지 알려주는 JSON 스키마를 만드는 것입니다. 이 스키마는 Claude가 도구를 언제 어떻게 호출할지 이해하기 위해 읽는 문서 역할을 합니다.

JSON 스키마 이해하기

JSON Schema는 AI나 도구 호출에만 국한된 것이 아니라, 오랫동안 사용되어 온 널리 쓰이는 데이터 검증 사양입니다. AI 커뮤니티는 함수 매개변수를 설명하고 데이터를 검증하는 편리한 방법이기 때문에 이를 채택했습니다.

get_weather 도구를 위한 JSON 스키마: input_schema는 필수 문자열 속성 "location"을 가진 객체입니다.

완전한 도구 명세는 세 가지 주요 부분으로 구성됩니다:

  • name - 도구에 대한 명확하고 설명적인 이름(예: "get_weather")
  • description - 도구가 무엇을 하는지, 언제 사용해야 하는지, 무엇을 반환하는지
  • input_schema - 함수의 인자를 설명하는 실제 JSON 스키마

효과적인 설명 작성하기

도구 설명은 Claude가 여러분의 함수를 언제 사용해야 하는지 이해하는 데 매우 중요합니다. 모범 사례는 다음과 같습니다:

  • 도구가 무엇을 하는지 설명하는 3~4문장을 목표로 하세요
  • Claude가 언제 이를 사용해야 하는지 설명하세요
  • 어떤 종류의 데이터를 반환하는지 설명하세요
  • 각 인자에 대해 상세한 설명을 제공하세요

이름, 설명, 그리고 필수 location 문자열을 설명하는 input_schema가 주석으로 표시된 get_weather 도구 스키마.

스키마를 생성하는 쉬운 방법

JSON 스키마를 처음부터 작성하는 대신, Claude 자체를 사용하여 생성할 수 있습니다. 과정은 다음과 같습니다:

  1. 도구 함수 코드를 복사합니다
  2. Claude로 이동하여 도구 호출용 JSON 스키마를 작성해 달라고 요청합니다
  3. 도구 사용에 관한 Anthropic 문서를 컨텍스트로 포함시킵니다
  4. Claude가 모범 사례를 따르는 올바른 형식의 스키마를 생성하도록 합니다

프롬프트는 다음과 같은 형태여야 합니다: "이 함수에 대한 도구 호출 목적의 유효한 JSON 스키마 사양을 작성해 주세요. 첨부된 문서에 나열된 모범 사례를 따라 주세요."

메시지 박스에 프롬프트와 get_current_datetime 함수가 있는 Claude.ai의 새 채팅, 그리고 도구 사용 문서 탭.

코드에 스키마 구현하기

Claude가 스키마를 생성하면, 이를 코드 파일에 복사해 넣으세요. 다음은 따라야 할 좋은 명명 패턴입니다:

python
def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

스키마를 체계적으로 정리하고 해당 함수와 쉽게 매칭할 수 있도록 function_name 뒤에 function_name_schema가 오는 패턴을 사용하세요.

타입 안전성 추가하기

더 나은 타입 검사를 위해 Anthropic 라이브러리에서 ToolParam 타입을 가져와 사용하세요:

python
from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    # ... 스키마의 나머지 부분
})

기능상 반드시 필요한 것은 아니지만, 이는 Claude의 API와 함께 스키마를 사용할 때 타입 오류를 방지하고 코드를 더 견고하게 만들어 줍니다.