메시지 블록 처리하기

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")
• JSON 스키마에 따라 형식화된 입력 매개변수
• "tool_use"라는 유형 지정

다중 블록 콘텐츠로 메시지 기록 처리하기

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

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

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

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

전체 흐름

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

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

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

헬퍼 함수 업데이트하기

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