로드 중
로드 중

Claude가 도구를 사용하기로 결정하면, 신중한 처리가 필요한 특별한 응답 구조를 반환합니다. 이 응답 형식을 이해하고 적절한 대화 관리를 구현하는 것은 견고한 도구 지원 애플리케이션을 구축하는 데 매우 중요합니다.

도구 선택 구성

응답에 대해 자세히 알아보기 전에, Claude가 언제 도구를 사용하는지 제어하는 방법을 이해하는 것이 좋습니다. toolChoice 매개변수는 세 가지 옵션을 제공합니다:

JSON으로 작성된 세 가지 toolChoice 설정인 "auto", "any", 그리고 이름이 지정된 "tool"이 아래에 나열된 동작과 짝지어져 있습니다.

  • auto - Claude가 도구를 사용할지 여부를 결정합니다 (기본 동작)
  • any - Claude는 도구를 사용해야 하지만 어떤 도구를 사용할지는 선택할 수 있습니다
  • specific tool - 이름으로 특정 도구를 사용하도록 Claude에게 강제합니다

세 번째 옵션은 Claude가 특정 함수를 호출하도록 보장하고 싶을 때 테스트에 특히 유용합니다.

멀티파트 메시지 구조

Claude가 도구를 사용하려고 할 때, 단순한 텍스트 대신 여러 콘텐츠 부분으로 구성된 어시스턴트 메시지를 반환합니다:

어시스턴트 메시지 콘텐츠 목록: "Text" 부분과, date_format %H:%M:%S로 get_current_datetime을 호출하는 "toolUse" 부분.

응답은 두 부분으로 구성됩니다:

  • Text Part - "지금 몇 시인지 알려드릴 수 있습니다. 정보를 찾아보겠습니다"와 같은 사람이 읽을 수 있는 설명
  • ToolUse Part - 어떤 도구를 실행할지, 어떤 인자와 함께 실행할지 알려주는 구조화된 데이터

ToolUse 부분 이해하기

ToolUse 부분에는 세 가지 핵심 정보가 포함되어 있습니다:

도구 "get_current_datetime"과 입력 date_format "%H:%M:%S", 그리고 toolUseId를 지정하는 ToolUse 부분의 예시.

  • toolUseId - 도구 결과를 다시 보낼 때 필요한 고유 식별자
  • name - Claude가 호출하려는 JSON 스키마의 정확한 도구 이름
  • input - Claude가 도구 함수에 전달하려는 인자의 딕셔너리

도구를 사용한 대화 흐름

도구 사용은 완전한 메시지 기록을 유지해야 하는 특정 대화 패턴을 따릅니다:

서버가 Claude에게 전체 기록을 보냅니다: 사용자의 "What time is it?", 어시스턴트의 텍스트와 ToolUse 부분, 사용자의 ToolResult 부분.

도구 사용 요청을 받으면 다음을 수행해야 합니다:

  1. ToolUse 부분에서 도구 정보를 추출합니다
  2. 실제 도구 함수를 실행합니다
  3. 전체 대화 기록과 함께 ToolResult 메시지를 다시 보냅니다
  4. 원래 사용자 메시지와 어시스턴트의 도구 사용 메시지를 다음 요청에 포함합니다

헬퍼 함수 업데이트하기

멀티파트 메시지를 올바르게 처리하려면 메시지 처리 함수를 업데이트해야 합니다. 단순 텍스트와 복잡한 멀티파트 콘텐츠를 모두 처리할 수 있도록 함수를 유연하게 만드는 방법은 다음과 같습니다:

python
def add_user_message(messages, content):
    if isinstance(content, str):
        user_message = {"role": "user", "content": [{"text": content}]}
    else:
        user_message = {"role": "user", "content": content}
    messages.append(user_message)

def add_assistant_message(messages, content):
    if isinstance(content, str):
        assistant_message = {"role": "assistant", "content": [{"text": content}]}
    else:
        assistant_message = {"role": "assistant", "content": content}
    messages.append(assistant_message)

텍스트와 전체 부분 목록을 모두 반환하도록 채팅 함수도 업데이트하고 싶을 것입니다:

python
def chat(messages, system=None, temperature=1.0, stop_sequences=[], tools=None):
    # ... 기존 설정 코드 ...
    
    response = client.converse(**params)
    
    text = response["output"]["message"]["content"][0]["text"]
    parts = response["output"]["message"]["content"]
    
    return text, parts

중단 이유 확인하기

Claude의 응답에는 최상위 stopReason 필드도 포함되어 있습니다. 이 값이 "tool_use"와 같으면, Claude는 단순히 텍스트 응답을 제공하는 대신 도구를 호출하고자 하는 것입니다 — 이것이 도구 정보를 추출하고 요청된 함수를 실행하라는 신호입니다. 위의 chat() 헬퍼는 아직 이 필드를 노출하지 않으므로, 지금은 반환된 부분 목록에서 toolUse 키가 있는 항목을 확인하여 도구 사용을 감지할 수 있습니다. 이후 레슨에서 stopReason을 직접 반환하도록 chat()을 확장하게 됩니다.

이러한 패턴을 갖추면, Claude의 도구 사용 요청을 처리하고 멀티턴 도구 상호작용 전반에 걸쳐 적절한 대화 흐름을 유지할 준비가 된 것입니다.