세밀한 도구 호출

Claude에서 도구 사용과 스트리밍을 결합하면 AI가 도구 인자를 생성하는 동안 실시간 업데이트를 받을 수 있습니다. 이는 더 반응성 있는 사용자 경험을 만들어내지만, 내부적으로 어떻게 작동하는지에 대해 이해해야 할 몇 가지 중요한 세부 사항이 있습니다.

기본 도구 스트리밍

스트리밍이 활성화되면 Claude는 요청을 처리하면서 다양한 유형의 이벤트를 다시 보냅니다. 일반 텍스트 생성을 위한 ContentBlockDelta와 같은 이벤트는 이미 익숙하실 것입니다. 도구 사용의 경우, InputJsonEvent라는 새로운 이벤트 유형도 처리해야 합니다.

각 InputJsonEvent에는 두 가지 주요 속성이 포함됩니다:

partial_json - 도구 인자의 일부를 나타내는 JSON 청크
snapshot - 지금까지 수신된 모든 청크로부터 누적된 JSON

스트리밍 파이프라인에서 이러한 이벤트를 처리하는 방법은 다음과 같습니다:

python

for chunk in stream:
    if chunk.type == "input_json":
        # 부분 JSON 청크를 처리합니다
        print(chunk.partial_json)
        # 또는 지금까지의 전체 스냅샷을 사용합니다
        current_args = chunk.snapshot

JSON 검증이 작동하는 방식

여기서부터 흥미로워집니다. Anthropic API는 Claude가 생성하는 즉시 모든 청크를 바로 전송하지 않습니다. 대신, 청크를 버퍼링하고 먼저 검증합니다.

API는 무언가를 전송하기 전에 완전한 최상위 키-값 쌍을 기다립니다. 예를 들어, 도구가 다음과 같은 구조를 예상한다면:

json

{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

API는 다음과 같이 동작합니다:

전체 abstract 값이 완성될 때까지 대기
해당 키-값 쌍을 스키마에 대해 검증
abstract에 대해 버퍼링된 모든 청크를 한 번에 전송
meta 객체에 대해 이 과정을 반복

이 검증 과정은 스트리밍이 활성화되어 있어도 지연 후 텍스트가 한꺼번에 쏟아지는 현상이 나타나는 이유를 설명합니다. 청크는 완전하고 유효한 최상위 키-값 쌍이 준비될 때까지 보류됩니다.

더 빠르고 세밀한 스트리밍이 필요한 경우 - 예를 들어 사용자에게 즉각적인 업데이트를 보여주거나 부분 결과를 빠르게 처리하기 시작하려는 경우 - 세밀한 도구 호출을 활성화할 수 있습니다.

세밀한 도구 호출은 한 가지 주요 작업을 수행합니다: API 측의 JSON 검증을 비활성화합니다. 이는 다음을 의미합니다:

Claude가 생성하는 즉시 청크를 받습니다
최상위 키 사이에 버퍼링 지연이 없습니다
더 전통적인 스트리밍 동작
중요: JSON 검증이 비활성화되므로 코드가 유효하지 않은 JSON을 처리해야 합니다

API 호출에 fine_grained=True를 추가하여 활성화하세요:

python

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=True
)

세밀한 도구 호출을 사용하면 전체 meta 객체가 완성되기를 기다리지 않고도 스트림에서 훨씬 더 일찍 word_count 값을 받을 수 있습니다.

유효하지 않은 JSON 처리하기

세밀한 도구 호출을 사용할 때, Claude는 적절한 숫자 대신 "word_count": undefined와 같은 유효하지 않은 JSON을 생성할 수 있습니다. 애플리케이션은 이러한 경우를 적절하게 처리해야 합니다:

python

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # 잘못된 JSON을 적절히 처리하세요
    print("Received invalid JSON, continuing...")

세밀한 도구 호출을 사용하지 않으면, API의 검증이 이 오류를 포착하고 문제가 되는 값을 문자열로 감쌀 수 있는데, 이는 예상한 스키마와 일치하지 않을 수 있습니다.

세밀한 도구 호출을 사용해야 하는 경우

다음과 같은 경우 세밀한 도구 호출 활성화를 고려하세요:

사용자에게 도구 인자 생성에 대한 실시간 진행 상황을 보여줘야 하는 경우
부분 도구 결과를 가능한 한 빠르게 처리하기 시작하려는 경우
버퍼링 지연이 사용자 경험에 부정적인 영향을 미치는 경우
견고한 JSON 오류 처리를 구현하는 데 익숙한 경우

대부분의 애플리케이션에서는 검증이 포함된 기본 동작으로 충분합니다. 하지만 그 이상의 반응성이 필요할 때, 세밀한 도구 호출은 Claude가 생성할 수 있는 만큼 빠르게 청크를 받을 수 있는 제어권을 제공합니다.