도구 함수를 만든 후 다음 단계는 이를 설명하는 JSON schema를 작성하는 것입니다. 이 schema는 Claude에게 함수가 어떤 인자를 기대하는지, 그리고 이를 어떻게 올바르게 사용해야 하는지 알려줍니다. 처음에는 설정이 복잡해 보일 수 있지만, 과정을 이해하면 실제로는 간단합니다.
JSON Schema 이해하기
JSON Schema는 AI 도구를 위해 새로 만들어진 것이 아니라, 데이터를 검증하는 표준 방식으로 수년간 사용되어 온 것입니다. Schema는 두 가지 주요 부분으로 구성됩니다: 상단의 이름과 설명(Claude가 도구를 언제 사용해야 하는지 이해하는 데 도움이 됨), 그리고 함수의 인자를 설명하는 실제 schema입니다.
상단 섹션에는 도구의 이름과 설명이 포함되어 있으며, 이는 Claude가 언제 이를 사용해야 하는지 이해하는 데 도움이 됩니다. 하단 섹션은 함수의 인자를 자세히 설명하는 실제 schema입니다.
JSON Schema 만들기: 단계별 가이드
다음은 어떤 함수든 JSON schema를 만드는 가장 간단한 방법입니다:
1단계: 샘플 데이터로 딕셔너리 작성하기
함수를 가져와서 샘플 데이터가 포함된 모든 키워드 인자의 딕셔너리를 만드세요. 예를 들어, 다음과 같은 함수가 있다면:
샘플 값이 포함된 딕셔너리를 만드세요:
2단계: JSON으로 변환하기
Python 딕셔너리를 올바른 JSON 형식으로 변환하세요. 주요 차이점은 Python의 True를 JSON의 true로 바꾸는 것입니다.
3단계: 온라인 변환기 사용하기
"JSON to JSON Schema converter"를 검색하여 무료로 제공되는 여러 온라인 도구 중 하나를 사용하세요. JSON 데이터를 붙여넣으면 schema가 자동으로 생성됩니다.
이 도구는 샘플 데이터를 분석하여 적절한 schema 구조를 생성합니다. 출력 결과에서 $schema 선언은 제거하세요 - 필요하지 않습니다.
4단계: 설명 추가하기
가장 중요한 단계는 각 속성에 자세한 설명을 추가하는 것입니다. 이러한 설명은 Claude가 각 인자가 정확히 무엇을 하는지, 그리고 어떻게 사용해야 하는지 이해하는 데 도움이 됩니다.
좋은 설명 작성하기
도구와 속성에 대한 설명을 작성할 때는 다음 모범 사례를 따르세요:
- 도구가 무엇을 하는지, 언제 사용해야 하는지, 그리고 무엇을 반환하는지 설명하세요
- 도구 설명은 3-4문장 정도로 작성하세요
- 각 속성에 대해 매우 자세한 설명을 제공하세요
- 막히면 함수를 Claude에 붙여넣고 설명을 작성해 달라고 요청하세요
다음은 잘 설명된 도구 schema의 예시입니다:
날씨 도구의 설명이 이 도구가 무엇을 하는지, 언제 사용해야 하는지, 어떤 데이터를 반환하는지를 명확하게 설명하고, 유효한 위치 형식의 구체적인 예시를 제공하는 방식을 주목하세요.
모두 종합하기
최종 JSON schema는 다음과 같은 구조를 가져야 하며, toolSpec에는 이름, 설명, 그리고 자세한 인자 명세가 포함된 inputSchema가 들어갑니다:
이 schema는 코드와 Claude 사이의 계약 역할을 하며, Claude가 도구를 사용하기로 결정했을 때 정확히 어떤 정보를 어떤 형식으로 제공해야 하는지 알 수 있도록 보장합니다. 이러한 명확한 소통이 도구 사용을 신뢰할 수 있고 효과적으로 만드는 요소입니다.