세분화된 도구 스트리밍

세분화된 도구 스트리밍은 모든 모델과 모든 플랫폼에서 사용할 수 있습니다. 이 기능은 버퍼링이나 JSON 검증 없이 도구 사용 매개변수 값의 스트리밍을 가능하게 하여, 대용량 매개변수를 수신하기 시작하는 데 걸리는 "latency"(지연 시간)를 줄입니다.



세분화된 도구 스트리밍 사용 방법

세분화된 도구 스트리밍은 Claude API, AWS의 Claude Platform, Amazon Bedrock, Vertex AI, Microsoft Foundry에서 지원됩니다. 이를 사용하려면 세분화된 스트리밍을 활성화하려는 사용자 정의 도구에서 eager_input_streaming을 true로 설정하고, 요청에서 스트리밍을 활성화하세요.

다음은 API에서 세분화된 도구 스트리밍을 사용하는 방법의 예시입니다:

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=65536,
    model="claude-opus-4-8",
    tools=[
        {
            "name": "make_file",
            "description": "Write text to a file",
            "eager_input_streaming": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "filename": {
                        "type": "string",
                        "description": "The filename to write text to",
                    },
                    "lines_of_text": {
                        "type": "array",
                        "description": "An array of lines of text to write to the file",
                    },
                },
                "required": ["filename", "lines_of_text"],
            },
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you write a long poem and make a file called poem.txt?",
        }
    ],
) as stream:
    final_message = stream.get_final_message()

print(f"Input tokens: {final_message.usage.input_tokens}")
print(f"Output tokens: {final_message.usage.output_tokens}")

이 예시에서 세분화된 도구 스트리밍은 Claude가 lines_of_text 매개변수가 유효한 JSON인지 검증하기 위해 버퍼링하지 않고, 긴 시의 각 행을 make_file 도구 호출로 스트리밍할 수 있게 합니다. 즉, 전체 매개변수가 버퍼링되고 검증될 때까지 기다릴 필요 없이 매개변수가 도착하는 대로 스트림을 확인할 수 있습니다.



도구 입력 델타 누적하기

tool_use 콘텐츠 블록이 스트리밍될 때, 초기 content_block_start 이벤트에는 input: {}(빈 객체)가 포함됩니다. 이는 플레이스홀더입니다. 실제 입력은 각각 partial_json 문자열 조각을 담고 있는 일련의 input_json_delta 이벤트로 도착합니다. 전체 입력을 조립하려면 이러한 조각들을 연결하고 블록이 닫힐 때 결과를 파싱하세요.

SDK가 누적기 헬퍼를 제공하는 경우(이 페이지의 첫 번째 예시에서 사용된 것처럼), 이 작업을 자동으로 처리해 줍니다. 수동 패턴은 헬퍼가 없는 SDK를 사용하거나, 블록이 닫히기 전에 부분 입력에 반응해야 할 때 사용합니다.

누적 규칙은 다음과 같습니다:

1. type: "tool_use"인 content_block_start에서 빈 문자열을 초기화합니다: input_json = ""
2. type: "input_json_delta"인 각 content_block_delta마다 추가합니다: input_json += event.delta.partial_json
3. content_block_stop에서 누적된 문자열을 파싱합니다: json.loads(input_json)

초기 input: {}(객체)와 partial_json(문자열) 간의 타입 불일치는 의도된 설계입니다. 빈 객체는 콘텐츠 배열에서 슬롯을 표시하고, 델타 문자열이 실제 값을 구성합니다.



도구 응답에서 유효하지 않은 JSON 처리하기

세분화된 도구 스트리밍을 사용할 때 모델로부터 유효하지 않거나 불완전한 JSON을 받을 수 있습니다. 이 유효하지 않은 JSON을 오류 응답 블록으로 모델에 다시 전달해야 하는 경우, 적절한 처리를 위해 JSON 객체로 감쌀 수 있습니다(적절한 키를 사용하여). 예를 들면 다음과 같습니다:

{
  "INVALID_JSON": "<your invalid json string>"
}

이 접근 방식은 디버깅 목적으로 원본의 잘못된 형식의 데이터를 보존하면서 모델이 해당 콘텐츠가 유효하지 않은 JSON임을 이해하도록 돕습니다.



다음 단계