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가 도구를 사용하기로 결정하면, 콘텐츠 목록에 여러 블록을 포함한 어시스턴트 메시지를 반환합니다. 이는 이전에 다뤄온 단순한 텍스트 전용 응답과 비교했을 때 상당한 변화입니다.

멀티블록 메시지는 일반적으로 다음을 포함합니다:
- Text Block - Claude가 무엇을 하고 있는지 설명하는 사람이 읽을 수 있는 텍스트(예: "현재 시각을 알아보는 데 도움을 드릴 수 있습니다. 해당 정보를 찾아보겠습니다")
- ToolUse Block - 어떤 도구를 호출하고 어떤 매개변수를 사용할지에 대해 코드에 전달하는 지시사항
ToolUse 블록에는 다음이 포함됩니다:
- 도구 호출을 추적하기 위한 ID
- 호출할 함수의 이름(예: "get_current_datetime")
- 딕셔너리 형식으로 표현된 입력 매개변수
- "tool_use"라는 타입 지정
멀티블록 메시지로 대화 기록 관리하기
Claude는 대화 기록을 저장하지 않으므로 직접 수동으로 관리해야 한다는 점을 기억하세요. 도구 응답을 다룰 때는 모든 블록을 포함한 전체 콘텐츠 구조를 보존해야 합니다.
멀티블록 어시스턴트 메시지를 대화 기록에 올바르게 추가하는 방법은 다음과 같습니다:
messages.append({
"role": "assistant",
"content": response.content
})이렇게 하면 텍스트 블록과 도구 사용 블록이 모두 보존되며, 이는 이후 API 호출을 할 때 대화 컨텍스트를 유지하는 데 매우 중요합니다.
전체 도구 사용 흐름

도구 사용 프로세스는 다음과 같은 패턴을 따릅니다:
- 도구 스키마가 포함된 사용자 메시지를 Claude에 전송합니다
- 텍스트 블록과 도구 사용 블록이 포함된 어시스턴트 메시지를 받습니다
- 도구 정보를 추출하고 실제 함수를 실행합니다
- 전체 대화 기록과 함께 도구 결과를 Claude에 다시 전송합니다
- Claude로부터 최종 응답을 받습니다
각 단계에서는 Claude가 정확한 응답을 제공하는 데 필요한 전체 컨텍스트를 갖도록 메시지 구조를 세심하게 처리해야 합니다.
헬퍼 함수 업데이트하기
add_user_message()와 add_assistant_message() 같은 헬퍼 함수를 사용해 왔다면, 멀티블록 콘텐츠를 처리할 수 있도록 이를 업데이트해야 합니다. 현재 버전은 아마도 단일 텍스트 블록만 지원할 가능성이 높지만, 이제는 도구 사용 블록을 포함한 더 복잡한 콘텐츠 구조를 수용해야 합니다.
이러한 멀티블록 메시지 처리는 적절한 대화 흐름을 유지하면서 Claude의 도구 기능을 원활하게 통합할 수 있는 견고한 애플리케이션을 구축하는 데 필수적입니다.