도구 함수

Stephen Grider · Anthropic 기술 스태프

첫 번째 도구 작업을 시작해 봅니다. 이 도구는 Claude가 현재 날짜·시각을 가져오게 해 줍니다. 더 진행하기 전에, 여러분이 쓸 새 노트북을 만들어 두었다는 걸 알려 드립니다. 이 노트북은 001_tools라는 제목이고 이 강의에 첨부돼 있습니다. 안에는 코스에서 이미 작성한 코드가 많이 들어 있고, 추가로 ‘Tools and Schemas’라는 셀을 새로 넣어 두었습니다. 그 셀에는 시간을 아끼기 위한 보일러플레이트 코드가 많습니다 — 특히 나중에 쓸 add_duration_to_datetime 함수가 들어 있습니다. 이 노트북을 받아 출발점으로 쓰세요.

이제 첫 도구 ‘현재 날짜·시각 가져오기’ 구현에 집중합니다. 전체 과정을 단계별로 안내합니다. 노트북에 코드를 꽤 많이 쓰겠지만, 거기 설정해 둔 헬퍼 함수(add_user_message, add_assistant_message 등)는 쓰지 않습니다. 그 함수들은 도구에 맞게 조금 리팩터링해야 하는데, 그걸 도구 학습과 동시에 하면 헷갈리기 때문입니다. 그래서 지금은 헬퍼 없이 도구 호출 자체에만 집중합니다.

전체 과정을 여러 단계로 나눴습니다. 1단계는 도구를 추가할 때마다 늘 하는 일 — 도구 함수를 작성하는 것입니다. 도구 함수는 Claude가 사용자를 돕기 위해 추가 정보가 필요하다고 판단할 때 어느 시점에 자동으로 실행되는, 평범한 파이썬 함수입니다. 오른쪽에 예시로 get_weather 함수를 두었습니다 — Claude가 세계 어느 위치의 현재 날씨를 가져올 때 쓸 수 있는 함수죠.

도구 함수에는 몇 가지 모범 사례가 있습니다. 첫째, 이름이 잘 붙고 설명적인 인자를 씁니다. 함수 자체와 받는 인자가 적당히 잘 명명돼 무엇에 관한 것인지 힌트를 줘야 합니다. 둘째, 입력을 검증하고 뭔가 잘못되면 에러를 냅니다. 예를 들어 location을 못 받았거나 빈 문자열이면 즉시 에러를 냅니다. 셋째, 에러를 낼 때는 의미 있는 에러 메시지를 담습니다.

에러 메시지가 중요한 이유가 있습니다. 도구 함수 호출이 에러로 끝나면, Claude는 그 에러 메시지를 그대로 봅니다. 그리고 에러를 바로잡으려고 도구를 살짝 다르게 다시 호출하기도 합니다. 예를 들어 get_weather에 빈 문자열을 넘겨 맨 위 검증이 실패하고 “location cannot be empty” 에러가 나면, Claude는 그 메시지를 보고 이번엔 빈 문자열이 아닌 값을 넘겨 다시 호출할 수 있습니다.

이제 노트북으로 돌아가 첫 도구 함수를 만듭니다. 목표는 현재 날짜·시각을 가져오는 것입니다. 맨 아래에 새 셀을 추가하고 get_current_datetime이라는 함수를 정의합니다. 인자로 date_format을 받고 기본값을 줍니다 — 조금 복잡한 문자열인데 %Y %m %d 그리고 공백, %H:%M:%S 입니다. 이 문자열은 까다로우니 영상을 멈추고 정확히 같은지 확인하세요.

함수 안에서는 그 date_format으로 현재 날짜·시각을 가져와 형식에 맞춰 반환합니다 — datetime.now().strftime(date_format). 예를 들어 그냥 get_current_datetime()을 호출하면 연-월-일 시:분:초 형식이 나오고, '%H:%M' 같은 커스텀 포맷을 넘기면 시:분만 출력됩니다.

이 함수를 개선하려면 date_format 인자에 검증을 더하면 좋습니다. 형식 문자열이 유효한지 정확히 검사하긴 어렵지만, 적어도 빈 문자열은 아닌지는 확인할 수 있습니다. if not date_format: 으로 빈 값이면 ValueError를 내고 “date_format cannot be empty”라고 알려 줍니다. 솔직히 Claude가 빈 문자열을 넘길 가능성은 낮지만, 혹시라도 그러면 Claude에게 신호를 줘서 어떻게 고칠지 — 빈 값이 아닌 포맷으로 다시 호출하라고 — 알려 주는 셈입니다.