메시지 블록 처리하기

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

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

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

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가 도구를 사용하기로 결정하면, 콘텐츠 목록에 여러 블록이 포함된 어시스턴트 메시지를 반환합니다. 이는 이전에 다루었던 단순한 텍스트 전용 응답과는 크게 다른 변화입니다.

다중 블록 메시지에는 일반적으로 다음이 포함됩니다:

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

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

• 도구 호출을 추적하기 위한 ID
• 호출할 함수의 이름(예: "get_current_datetime")
• 딕셔너리 형식으로 포맷된 입력 매개변수
• "tool_use" 유형 지정

다중 블록 메시지로 대화 기록 관리하기

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

다중 블록 어시스턴트 메시지를 대화 기록에 올바르게 추가하는 방법은 다음과 같습니다:

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

이렇게 하면 텍스트 블록과 도구 사용 블록이 모두 보존되며, 이는 이후 API 호출을 할 때 대화 컨텍스트를 유지하는 데 매우 중요합니다.

전체 도구 사용 흐름

도구 사용 프로세스는 다음과 같은 패턴을 따릅니다:

1. 도구 스키마가 포함된 사용자 메시지를 Claude에 전송합니다
2. 텍스트 블록과 도구 사용 블록이 포함된 어시스턴트 메시지를 받습니다
3. 도구 정보를 추출하고 실제 함수를 실행합니다
4. 전체 대화 기록과 함께 도구 결과를 Claude에 다시 전송합니다
5. Claude로부터 최종 응답을 받습니다

각 단계는 Claude가 정확한 응답을 제공하는 데 필요한 전체 컨텍스트를 확보할 수 있도록 메시지 구조를 신중하게 처리해야 합니다.

헬퍼 함수 업데이트하기

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

이러한 다중 블록 메시지 처리는 적절한 대화 흐름을 유지하면서 Claude의 도구 기능을 원활하게 통합할 수 있는 견고한 애플리케이션을 구축하는 데 필수적입니다.