로드 중
로드 중

도구 함수를 만든 후 다음 단계는 이를 설명하는 JSON schema를 작성하는 것입니다. 이 schema는 Claude에게 함수가 어떤 인자를 기대하는지, 그리고 이를 올바르게 사용하는 방법을 알려줍니다. 처음에는 구성이 복잡해 보일 수 있지만, 과정을 이해하고 나면 사실 매우 간단합니다.

JSON Schema 이해하기

JSON Schema는 AI 도구를 위해 새로 발명된 것이 아닙니다 - 데이터를 검증하는 표준 방식으로 수년간 존재해 왔습니다. schema는 두 가지 주요 부분으로 구성됩니다: 상단의 이름과 설명(Claude가 언제 도구를 사용해야 하는지 이해하는 데 도움을 줌), 그리고 함수의 인자를 설명하는 실제 schema입니다.

상단에 이름과 설명이 박스로 표시되고 아래에 "location"을 요구하는 inputSchema가 박스로 표시된 get_weather toolSpec.

상단 섹션에는 도구의 이름과 설명이 포함되어 있으며, 이는 Claude가 언제 도구를 사용해야 하는지 이해하는 데 도움을 줍니다. 하단 섹션은 함수의 인자를 자세히 설명하는 실제 schema입니다.

JSON Schema 만들기: 단계별 가이드

다음은 모든 함수에 대한 JSON schema를 만드는 가장 간단한 방법입니다:

1단계: 샘플 데이터로 딕셔너리 작성하기

함수를 가져와서 모든 키워드 인자에 대한 샘플 데이터로 딕셔너리를 만듭니다. 예를 들어, 다음과 같은 함수가 있다면:

python
def process_data(ids, profile, primary_id, value):
    pass

샘플 값으로 딕셔너리를 만듭니다:

process_data를 위한 딕셔너리: "ids"는 1을 포함하는 리스트, "profile"은 "active"가 True, "primary_id"는 "abc", "value"는 20.

2단계: JSON으로 변환하기

Python 딕셔너리를 적절한 JSON 형식으로 변환합니다. 주된 차이점은 Python의 True를 JSON의 true로 바꾸는 것입니다.

1단계의 딕셔너리를 JSON으로 표현한 것: ids 1, primary_id "abc", value 20은 동일하지만 "active"는 이제 소문자 true.

3단계: 온라인 변환기 사용하기

"JSON to JSON Schema converter"를 검색하여 무료 온라인 도구 중 하나를 사용하세요. JSON 데이터를 붙여넣으면 schema가 자동으로 생성됩니다.

온라인 JSON to JSON Schema 변환기: 붙여넣은 샘플 JSON, Generate Schema 버튼, 그리고 그 아래에 추론된 schema.

도구가 샘플 데이터를 분석하여 적절한 schema 구조를 생성합니다. 출력에서 $schema 선언은 제거하세요 - 필요하지 않습니다.

4단계: 설명 추가하기

가장 중요한 단계는 각 속성에 상세한 설명을 추가하는 것입니다. 이러한 설명은 Claude가 각 인자가 정확히 무엇을 하는지, 그리고 이를 어떻게 사용해야 하는지 이해하는 데 도움이 됩니다.

숫자 배열인 ids와 문자열인 primary_id가 각각 세 개의 점으로 설정된 "description" 키를 갖게 된 JSON schema.

좋은 설명 작성하기

도구와 속성에 대한 설명을 작성할 때는 다음의 모범 사례를 따르세요:

  • 도구가 무엇을 하는지, 언제 사용해야 하는지, 그리고 무엇을 반환하는지 설명하세요
  • 도구 설명은 3-4 문장을 목표로 하세요
  • 각 속성에 대해 매우 상세한 설명을 제공하세요
  • 막히는 경우, 함수를 Claude에 붙여넣고 설명을 작성해 달라고 요청하세요

다음은 잘 설명된 도구 schema의 예입니다:

온도, 날씨 상태, 습도를 반환하는 get_weather의 JSON Schema, "London,UK"와 같은 필수 "location"이 있습니다.

설명이 날씨 도구가 무엇을 하는지, 언제 사용해야 하는지, 어떤 데이터를 반환하는지 명확히 설명하고, 유효한 location 형식의 구체적인 예시를 제공하는 방식을 주목하세요.

모든 것을 종합하기

최종 JSON schema는 다음과 같은 구조를 가져야 합니다. toolSpec에는 이름, 설명, 그리고 상세한 인자 명세가 담긴 inputSchema가 포함됩니다:

get_weather toolSpec schema: 이름, 여러 문장으로 된 설명, 그리고 필수 location 문자열을 갖는 inputSchema.

schema는 코드와 Claude 사이의 계약 역할을 하며, Claude가 도구를 사용하기로 결정했을 때 정확히 어떤 정보를 어떤 형식으로 제공해야 하는지 알 수 있도록 보장합니다. 이러한 명확한 소통이 도구 사용을 신뢰할 수 있고 효과적으로 만듭니다.