로드 중
로드 중

Claude의 도구 기능을 사용할 때, 이전에 보았던 단순한 텍스트 응답과는 다른 새로운 유형의 응답 구조를 접하게 됩니다. 단순히 하나의 텍스트 블록만 돌려받는 대신, Claude는 텍스트와 도구 사용 정보를 모두 포함하는 멀티 블록 메시지를 반환할 수 있습니다.

도구 사용이 가능한 API 호출 만들기

Claude가 도구를 사용할 수 있도록 하려면 API 호출에 tools 매개변수를 포함해야 합니다. 다음은 요청을 구성하는 방법입니다:

python
messages = []
messages.append({
    "role": "user",
    "content": "What is the exact time, formatted as HH:MM:SS?"
})

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema],
)

tools 매개변수는 Claude가 호출할 수 있는 사용 가능한 함수를 설명하는 JSON 스키마 목록을 받습니다.

멀티 블록 메시지 이해하기

Claude가 도구를 사용하기로 결정하면, content 목록에 여러 블록이 포함된 어시스턴트 메시지를 반환합니다. 이는 이전에 다루었던 단순 텍스트 전용 응답과는 상당히 다른 변화입니다.

input date_format "%H:%M:%S"를 가진 어시스턴트 메시지의 Text Block과 ToolUse Block; 블록은 "parts"라고도 불립니다.

멀티 블록 메시지는 일반적으로 다음을 포함합니다:

  • Text Block - Claude가 무엇을 하고 있는지 설명하는 사람이 읽을 수 있는 텍스트(예: "현재 시간을 알아봐 드릴 수 있습니다. 그 정보를 찾아보겠습니다")
  • ToolUse Block - 어떤 도구를 호출하고 어떤 매개변수를 사용할지에 대한 코드에 대한 지침

ToolUse 블록에는 다음이 포함됩니다:

  • 도구 호출을 추적하기 위한 ID
  • 호출할 함수의 이름(예: "get_current_datetime")
  • JSON 스키마에 따라 형식이 지정된 입력 매개변수
  • 타입 지정 "tool_use"

멀티 블록 콘텐츠로 메시지 기록 처리하기

여기서 중요한 부분이 있습니다: Claude는 대화 기록을 저장하지 않으므로, 이를 직접 수동으로 관리해야 합니다. 도구 응답을 다룰 때는 모든 블록을 포함하여 전체 콘텐츠 구조를 보존해야 합니다.

단순히 텍스트만 추출하는 대신, 전체 응답 콘텐츠를 추가해야 합니다:

python
messages.append({
    "role": "assistant",
    "content": response.content
})

이렇게 하면 텍스트 블록과 도구 사용 블록이 모두 보존되어, 향후 API 호출을 위한 전체 대화 컨텍스트가 유지됩니다.

전체 흐름

도구 사용 과정은 다음과 같은 패턴을 따릅니다:

add_user_message와 add_assistant_message가 "role"과 "content" 딕셔너리를 추가하는 노트북 셀, 그리고 chat 함수.

  1. 도구 스키마가 포함된 사용자 메시지를 Claude에게 전송
  2. 멀티 블록 어시스턴트 메시지(텍스트 + 도구 사용) 수신
  3. 도구 호출 정보를 추출하고 함수 실행
  4. 전체 메시지 기록과 함께 도구 결과를 Claude에게 다시 전송
  5. Claude로부터 최종 응답 수신

각 단계는 대화의 연속성을 유지하기 위해 메시지 구조를 신중하게 처리해야 합니다. 핵심은 도구 사용이 가능한 대화에는 더 복잡한 메시지 형식이 관여하지만, 전체 메시지 기록을 유지한다는 근본적인 원칙은 동일하게 유지된다는 점입니다.

헬퍼 함수 업데이트하기

add_user_message와 add_assistant_message 같은 헬퍼 함수를 사용해 왔다면, 멀티 블록 콘텐츠를 처리할 수 있도록 업데이트해야 합니다. 현재 버전은 아마도 단일 텍스트 블록만 지원할 것이지만, 이제는 도구 사용 블록을 포함하는 더 복잡한 콘텐츠 구조를 수용해야 합니다.