Claude API: streaming и tool use — практический обзор

Streaming и tool use — две функции Claude API, без которых сложно сделать удобное приложение. Streaming показывает ответ по мере генерации, а tool use позволяет Claude вызывать ваши функции: искать в базе, получать погоду, создавать задачи. Разберём, как они работают.

Зачем нужен streaming

Без streaming пользователь ждёт, пока Claude сгенерирует весь ответ, — иногда 10–20 секунд. Со streaming текст появляется сразу и дописывается по частям, как в чате на claude.ai. Для длинных ответов это ещё и защита от тайм-аутов.

Как это работает

Добавьте в запрос stream=True (или используйте client.messages.stream() в Python SDK). API возвращает поток событий:

message_start — начало ответа;
content_block_delta — очередной кусок текста;
message_delta — итоговая информация, например причина остановки и расход токенов;
message_stop — конец ответа.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Расскажи про MCP"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Предусмотрите обработку обрыва соединения: сохраняйте полученный текст и показывайте пользователю понятное сообщение.

Что такое tool use

Вы описываете инструменты — функции вашей программы — с названием, описанием и схемой параметров. Claude решает, когда инструмент нужен, и возвращает запрос на вызов. Ваш код выполняет функцию и отправляет результат обратно, а Claude формирует ответ.

Вы отправляете сообщение и список инструментов.
Claude отвечает блоком tool_use с названием инструмента и параметрами, stop_reason равен tool_use.
Ваш код вызывает функцию.
Вы отправляете результат в блоке tool_result с тем же tool_use_id.
Claude даёт итоговый ответ пользователю.

Как описывать инструменты

Понятное название: get_order_status, а не func1.
Подробное описание: что делает инструмент и когда его вызывать.
Строгая схема параметров с типами и обязательными полями.
Небольшой набор: 5 хорошо описанных инструментов лучше 30 похожих.

Безопасность

Проверяйте параметры, которые пришли от модели, как любой пользовательский ввод.
Действия с последствиями — оплата, удаление, отправка писем — только с подтверждением человека.
Давайте инструментам минимально необходимые права.
Учитывайте промпт-инъекции: данные, которые вернул инструмент, могут содержать текст, похожий на команды.

Если инструментов много и они нужны в разных приложениях, посмотрите на стандарт MCP — см. Claude MCP.