도구 사용 응답 처리 · Amazon Bedrock와 함께하는 Claude

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

도구 선택 구성

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

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

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

다중 부분 메시지 구조

Claude가 도구를 사용하려고 할 때, 단순 텍스트가 아닌 여러 콘텐츠 부분을 포함하는 어시스턴트 메시지를 반환합니다:

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

Text Part - "현재 시간을 알려드릴 수 있습니다. 해당 정보를 찾아보겠습니다"와 같은 사람이 읽을 수 있는 설명
ToolUse Part - 어떤 도구를 실행할지와 어떤 인수로 실행할지를 알려주는 구조화된 데이터

ToolUse Part 이해하기

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

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

도구를 사용한 대화 흐름

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

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

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

헬퍼 함수 업데이트

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

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)

또한 텍스트와 전체 parts 목록을 모두 반환하도록 chat 함수를 업데이트하는 것이 좋습니다:

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

Stop Reason 확인하기

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

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