세밀한 도구 스트리밍
도구 사용이 이제 매개변수 값에 대한 세밀한 스트리밍을 지원합니다. 이를 통해 개발자는 버퍼링/JSON 검증 없이 도구 사용 매개변수를 스트리밍할 수 있어 대용량 매개변수 수신을 시작하는 지연 시간을 줄일 수 있습니다.
세밀한 도구 스트리밍은 베타 기능입니다. 프로덕션에서 사용하기 전에 응답을 평가해 주시기 바랍니다.
모델 응답의 품질, API 자체, 또는 문서의 품질에 대한 피드백을 제공하려면 이 양식을 사용해 주세요. 여러분의 의견을 듣기를 기대합니다!
세밀한 도구 스트리밍을 사용할 때 잠재적으로 유효하지 않거나 부분적인 JSON 입력을 받을 수 있습니다. 코드에서 이러한 예외 상황을 고려해 주시기 바랍니다.
세밀한 도구 스트리밍 사용 방법
이 베타 기능을 사용하려면 도구 사용 요청에 베타 헤더 fine-grained-tool-streaming-2025-05-14를 추가하고 스트리밍을 켜기만 하면 됩니다.
다음은 API와 함께 세밀한 도구 스트리밍을 사용하는 방법의 예시입니다:
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: fine-grained-tool-streaming-2025-05-14" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 65536,
"tools": [
{
"name": "make_file",
"description": "Write text to a file",
"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?"
}
],
"stream": true
}' | jq '.usage'import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.stream(
max_tokens=65536,
model="claude-sonnet-4-5",
tools=[{
"name": "make_file",
"description": "Write text to a file",
"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?"
}],
betas=["fine-grained-tool-streaming-2025-05-14"]
)
print(response.usage)import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic();
const message = await anthropic.beta.messages.stream({
model: "claude-sonnet-4-5",
max_tokens: 65536,
tools: [{
"name": "make_file",
"description": "Write text to a file",
"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?"
}],
betas: ["fine-grained-tool-streaming-2025-05-14"]
});
console.log(message.usage);이 예시에서 세밀한 도구 스트리밍은 Claude가 lines_of_text 매개변수가 유효한 JSON인지 검증하기 위해 버퍼링하지 않고 긴 시의 줄들을 도구 호출 make_file로 스트리밍할 수 있게 합니다. 이는 전체 매개변수가 버퍼링되고 검증될 때까지 기다릴 필요 없이 매개변수가 도착하는 대로 스트림을 볼 수 있음을 의미합니다.
세밀한 도구 스트리밍을 사용하면 도구 사용 청크가 더 빠르게 스트리밍을 시작하며, 종종 더 길고 단어 구분이 적습니다. 이는 청킹 동작의 차이 때문입니다.
예시:
세밀한 스트리밍 없이 (15초 지연):
청크 1: '{"'
청크 2: 'query": "Ty'
청크 3: 'peScri'
청크 4: 'pt 5.0 5.1 '
청크 5: '5.2 5'
청크 6: '.3'
청크 8: ' new f'
청크 9: 'eatur'
...세밀한 스트리밍과 함께 (3초 지연):
청크 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
청크 2: ' new features comparison'세밀한 스트리밍은 버퍼링이나 JSON 검증 없이 매개변수를 전송하기 때문에 결과 스트림이 유효한 JSON 문자열로 완료된다는 보장이 없습니다.
특히 중지 이유 max_tokens에 도달하면 스트림이 매개변수 중간에 끝날 수 있으며 불완전할 수 있습니다. 일반적으로 max_tokens에 도달했을 때를 처리하기 위한 특별한 지원을 작성해야 합니다.
도구 응답에서 유효하지 않은 JSON 처리
세밀한 도구 스트리밍을 사용할 때 모델로부터 유효하지 않거나 불완전한 JSON을 받을 수 있습니다. 이 유효하지 않은 JSON을 오류 응답 블록에서 모델에 다시 전달해야 하는 경우, 적절한 처리를 보장하기 위해 JSON 객체로 감쌀 수 있습니다(합리적인 키와 함께). 예를 들어:
{
"INVALID_JSON": "<your invalid json string>"
}이 접근 방식은 모델이 콘텐츠가 유효하지 않은 JSON임을 이해하도록 도우면서 디버깅 목적으로 원본 잘못된 형식의 데이터를 보존합니다.
유효하지 않은 JSON을 감쌀 때 래퍼 객체에서 유효한 JSON 구조를 유지하기 위해 유효하지 않은 JSON 문자열의 따옴표나 특수 문자를 적절히 이스케이프해야 합니다.