Инструменты

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

Использование инструментов теперь поддерживает детализированную потоковую передачу для значений параметров. Это позволяет разработчикам передавать параметры использования инструментов в потоковом режиме без буферизации / валидации 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'

В этом примере детализированная потоковая передача инструментов позволяет Claude передавать строки длинного стихотворения в вызов инструмента make_file без буферизации для проверки того, является ли параметр lines_of_text действительным JSON. Это означает, что вы можете видеть поток параметров по мере его поступления, не дожидаясь буферизации и валидации всего параметра.

С детализированной потоковой передачей инструментов фрагменты использования инструментов начинают передаваться быстрее и часто бывают длиннее и содержат меньше разрывов слов. Это связано с различиями в поведении фрагментации.

Пример:

Без детализированной потоковой передачи (задержка 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": "<ваша недействительная json строка>"
}

Этот подход помогает модели понять, что содержимое является недействительным JSON, сохраняя при этом исходные искаженные данные для целей отладки.

При обертывании недействительного JSON убедитесь, что правильно экранируете любые кавычки или специальные символы в недействительной строке JSON для поддержания действительной структуры JSON в объекте-обертке.

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

Вот пример того, как использовать детализированную потоковую передачу инструментов с 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'

Пример:

Без детализированной потоковой передачи (задержка 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 в ответах инструментов

{
  "INVALID_JSON": "<ваша недействительная json строка>"
}