Детализированная потоковая передача инструментов

«Fine-grained tool streaming» (детализированная потоковая передача инструментов) доставляет входные данные инструмента вашему клиенту по мере того, как Claude их генерирует, без буферизации на стороне сервера и без валидации JSON. Пропуск этапа буферизации сокращает время до получения первого фрагмента большого параметра, такого как документ или блок кода, а сами фрагменты поступают через те же события потоковой передачи сообщений, что и при стандартном использовании инструментов.



Как использовать детализированную потоковую передачу инструментов

Все модели поддерживают детализированную потоковую передачу инструментов в Claude API, Claude Platform на AWS, Amazon Bedrock, Google Cloud и Microsoft Foundry. Чтобы использовать её, установите eager_input_streaming в значение true для любого пользовательского инструмента, для которого вы хотите включить детализированную потоковую передачу, и включите потоковую передачу в вашем запросе.

Поле eager_input_streaming является необязательным. Установка его в true включает детализированную потоковую передачу для данного инструмента, а его отсутствие даёт вам стандартную буферизованную потоковую передачу, при которой API буферизует и валидирует каждое значение параметра перед его отправкой обратно. Исключение составляет запрос, который всё ещё отправляет устаревший бета-заголовок fine-grained-tool-streaming-2025-05-14: он включает детализированную потоковую передачу для инструментов, у которых это поле не задано. Поле на уровне инструмента заменяет этот заголовок, а явное значение false сохраняет буферизованную потоковую передачу для инструмента, даже если запрос всё ещё отправляет заголовок. Определение поля см. в справочнике по инструментам.

Следующий пример включает детализированную потоковую передачу для инструмента make_file и просит Claude написать длинное стихотворение, чтобы входные данные инструмента были достаточно большими и вы могли наблюдать их поступление в потоке:

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:
    for event in stream:
        if event.type == "input_json":
            print(event.partial_json, end="", flush=True)
    final_message = stream.get_final_message()

print()
for block in final_message.content:
    if block.type == "tool_use":
        print(f"Complete tool input: {block.input}")

Каждая вкладка включает детализированную потоковую передачу для инструмента make_file. Вкладки с SDK выводят каждый фрагмент входных данных в момент его поступления, а затем выводят полные накопленные входные данные после завершения потока. Вкладка cURL показывает необработанный поток событий, а вкладка CLI использует jq для вывода только фрагментов. Поскольку выведенные фрагменты складываются в полные входные данные инструмента, стихотворение заполняет ваш терминал по мере того, как Claude его пишет:

{"filename": "poem.txt", "lines_of_text": ["The Wanderer's Journey", "", "I.", "", "Beneath the vast and star-strewn sky,", "Where silver moonbeams softly lie,", ...
Complete tool input: {"filename": "poem.txt", "lines_of_text": ["The Wanderer's Journey", ...]}

Без eager_input_streaming API буферизует и валидирует каждое значение параметра перед его потоковой передачей обратно, поэтому для большого параметра ничего не выводится, пока Claude не закончит его генерировать. С этим параметром фрагменты начинают поступать, как только Claude приступает к параметру, и они, как правило, длиннее, с меньшим количеством разрывов посередине слов.



Накопление дельт входных данных инструмента

Контракт накопления такой же, как и для стандартной потоковой передачи при использовании инструментов, поэтому этот раздел применим как с eager_input_streaming, так и без него. Формат событий см. в разделе Input JSON delta документации по потоковой передаче сообщений. Детализированная потоковая передача инструментов меняет то, что вы можете предполагать о результате: сервер передаёт фрагменты потоком без их валидации, поэтому накопленная строка может оказаться невалидным JSON.

Когда блок содержимого tool_use передаётся потоком, начальное событие content_block_start содержит input: {} (пустой объект). Это заполнитель. Фактические входные данные поступают в виде серии событий input_json_delta, каждое из которых несёт строковый фрагмент partial_json. Чтобы собрать полные входные данные, конкатенируйте эти фрагменты и распарсите результат, когда блок закроется.

Там, где ваш SDK предоставляет вспомогательный аккумулятор (как это делают вкладки Python, TypeScript, Go, Java и Ruby в предыдущем примере), он обрабатывает это за вас. Ручной подход предназначен для SDK без такого помощника или для случаев, когда вам нужен полный контроль над тем, как собираются входные данные.

Контракт накопления:

1. При content_block_start с type: "tool_use" инициализируйте пустую строку: input_json = ""
2. Для каждого content_block_delta с type: "input_json_delta" добавляйте: input_json += event.delta.partial_json
3. При content_block_stop распарсите накопленную строку

Защищайте парсинг, как это делают следующие примеры SDK. Ответ также может остановиться на max_tokens посередине параметра. Проверьте причину остановки и решите, повторить ли запрос с более высоким значением max_tokens или восстановить частичные входные данные.

Несоответствие типов между начальным input: {} (объект) и partial_json (строка) является намеренным. Пустой объект отмечает место в массиве содержимого. Строки дельт формируют реальное значение.

client = anthropic.Anthropic()

tool_inputs: dict[int, str] = {}  # index -> accumulated JSON string

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "eager_input_streaming": True,
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
) as stream:
    for event in stream:
        match event.type:
            case "content_block_start" if event.content_block.type == "tool_use":
                tool_inputs[event.index] = ""
            case "content_block_delta" if event.delta.type == "input_json_delta":
                tool_inputs[event.index] += event.delta.partial_json
            case "content_block_stop" if event.index in tool_inputs:
                raw_input = tool_inputs[event.index]
                try:
                    parsed = json.loads(raw_input)
                except json.JSONDecodeError:
                    # Накопленная строка не гарантированно является валидным JSON.
                    # См. раздел «Обработка невалидного JSON в ответах инструментов» на этой странице.
                    print(f"Invalid tool input: {raw_input}")
                else:
                    print(f"Tool input: {parsed}")



Обработка невалидного JSON в ответах инструментов

При детализированной потоковой передаче инструментов накопленные входные данные для вызова инструмента могут оказаться невалидным или неполным JSON. В этом случае вы не можете выполнить инструмент, поэтому вместо этого сообщите о сбое обратно Claude. Поле content результата инструмента не обязано быть JSON, но оборачивание необработанной строки в JSON-объект под одним ключом однозначно даёт Claude понять, что вы получили невалидный JSON, и сохраняет исходные входные данные для отладки:

{
  "INVALID_JSON": "<the unparseable input you received>"
}

Верните эту обёртку, сериализованную в строку, в качестве content блока содержимого tool result с is_error, установленным в true:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "is_error": true,
  "content": "{\"INVALID_JSON\": \"<the unparseable input you received>\"}"
}



Дальнейшие шаги