Tool schemas · Claude API로 구축하기

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

JSON Schema 이해하기

JSON Schema는 AI나 도구 호출에만 특화된 것이 아니며, 수년간 널리 사용되어 온 데이터 검증 명세입니다. AI 커뮤니티는 함수 매개변수를 설명하고 데이터를 검증하는 편리한 방법이기 때문에 이를 채택했습니다.

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

name - 도구에 대한 명확하고 설명적인 이름(예: "get_weather")
description - 도구가 수행하는 작업, 사용 시점, 반환하는 내용
input_schema - 함수의 인자를 설명하는 실제 JSON 스키마

효과적인 설명 작성하기

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

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

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

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

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

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

코드에 스키마 구현하기

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와 함께 스키마를 사용할 때 타입 오류를 방지하고 코드를 더 견고하게 만들어 줍니다.