MODULE_10 · УРОК 10.2

Streaming и рендер tools

agent.run() устроен честно и неудобно: он молчит, пока прогон не закончится целиком. На простом вопросе это незаметно, а вот на задаче с тремя инструментами терминал уже полминуты выглядит мёртвым. И вы сидите и гадаете: он думает, он ушёл в цикл или он упал, а сообщение об ошибке где-то застряло. Знакомое чувство и совершенно лишнее.

Стрим убирает эту неопределённость. Текст течёт кусками по мере генерации, вызов инструмента виден в момент вызова, результат - как только вернулся. Пользователь видит движение, а вы наконец видите, чем агент занят на самом деле, а не что он решил рассказать в финальном абзаце.

ЧТО ПОЛУЧИТСЯ CLI переезжает на run_stream: финальный текст уходит в stdout по кускам, а вызовы и результаты инструментов - в stderr. Сам агент, его инструменты и песочница остаются нетронутыми.

Слова, которые встретятся

  • stream_text(delta=True) - выдаёт только новый кусок текста с прошлого тика. Без delta вам каждый раз прилетает вся накопленная строка, и в терминале получается лестница из повторов.
  • event_stream_handler - колбэк, которому harness рассказывает о событиях прогона: инструмент пошёл, инструмент вернулся, приехала очередная часть ответа.
  • stdout и stderr - два потока вывода. Ответ модели пойдёт в первый, служебная возня с инструментами во второй. Разделение бесплатное, а пользы много: шум всегда можно отключить одним перенаправлением.

Быстрый путь

  1. Написать event_stream_handler для tool-событий → stderr.
  2. Заменить agent.run на run_stream + handler.
  3. Писать финальный текст через stream_text(delta=True) в stdout.

Какие файлы трогаем

Файл Что делать
main.py Править. Только способ запуска и печати - не сборку Agent.

Шаг 1. Рендер событий tools

Начнём с того, кто будет рисовать инструменты. Импорты событий и сам хендлер положите рядом с main или выше по файлу - главное, до создания агента:

from collections.abc import AsyncIterable
import json

from pydantic_ai import (
    AgentStreamEvent,
    FunctionToolCallEvent,
    FunctionToolResultEvent,
    RunContext,
)


async def event_stream_handler(
    ctx: RunContext[Sandbox],
    event_stream: AsyncIterable[AgentStreamEvent],
) -> None:
    async for event in event_stream:
        if isinstance(event, FunctionToolCallEvent):
            args = event.part.args
            if not isinstance(args, str):
                args = json.dumps(args, ensure_ascii=False)
            print(
                f"\n[tool] {event.part.tool_name}({args})",
                file=sys.stderr,
            )
        elif isinstance(event, FunctionToolResultEvent):
            content = event.part.content
            preview = (
                content[:100]
                if isinstance(content, str)
                else str(content)[:100]
            )
            print(f"  -> {preview}", file=sys.stderr)

Обратите внимание на обрезку результата до ста символов. Полный вывод read в stderr не нужен никому: вы там ищете не содержимое файла, а признаки жизни. Имя инструмента плюс короткий хвост результата дают ровно это.

Шаг 2. Заменить run на run_stream

Дальше в main() внутри try меняем пару строк: вместо «дождаться agent.run и напечатать result.output» открываем поток и печатаем по мере прихода.

main.py - фрагмент try

    await lifecycle.after_start(sandbox)
    try:
        async with agent.run_stream(
            prompt,
            deps=sandbox,
            event_stream_handler=event_stream_handler,
        ) as run:
            async for chunk in run.stream_text(delta=True):
                sys.stdout.write(chunk)
                sys.stdout.flush()
            print()  # перевод строки после ответа
    finally:
        await lifecycle.before_stop(sandbox)
        await sandbox.stop()
ЧТО НЕ МЕНЯЕТСЯ Сборка агента, инструменты, промпт, песочница и argparse остались точно такими, какими вы их оставили в 10.1. Менялась одна фраза: «подождать ответ» превратилось в «рисовать поток». Если ради стрима пришлось залезть внутрь Agent, значит, где-то поехал шов.
APPROVAL И СТРИМ Честное предупреждение: bash по-прежнему умеет вернуть строку «заблокировано» вместо живого диалога с человеком. Полноценная схема (поставить стрим на паузу, спросить, продолжить) - это отдельный цикл, и его удобнее собирать на событиях из модуля про расширяемость. Пока обходимся строкой отказа, и это нормально: агент хотя бы не делает вид, что команда прошла.

Как это выглядит

В терминале появляется примерно такая картина, и она уже читается как рассказ о работе, а не как пауза перед вердиктом:

[tool] grep({"pattern": "TODO", "glob": "*.py"})
  -> main.py:12: # TODO: ...
  -> prompts.py:40: # TODO: ...

Нашёл два TODO: ...

Строки [tool] идут в stderr, текст ответа - в stdout и по мере генерации. Визуально они смешаны в одном терминале, но технически это два разных потока, и сейчас мы этим воспользуемся.

Подсказка по рендеру (не обязательно сейчас)

Tool Удобный краткий вид
readпуть и число строк
grepчисло совпадений + первые 3
bashкоманда и exit code
taskтип субагента
ask_userвопрос целиком

Общий хендлер выше закрывает почти все случаи, так что бросаться писать формат под каждый инструмент не надо. Разумный повод появляется, когда какой-то один tool стабильно засоряет вывод: вот для него и сделайте отдельную короткую строчку.

Проверьте

uv run python main.py . "Найди все TODO-комментарии, потом прочитай файлы, где они есть"

Вызовы инструментов должны появляться по ходу работы, а ответ - набегать токенами, а не выпадать одним блоком в самом конце. Если текст всё ещё приходит целиком, скорее всего потерялось delta=True.

А теперь то, ради чего мы разводили потоки: оставим только речь агента и выключим служебный шум.

uv run python main.py . "Найди все TODO-комментарии" 2>/dev/null

В выводе остаётся чистый ответ, который можно спокойно передать дальше по пайпу или сохранить в файл. Тот же приём потом сработает и в скриптах: агент как обычная unix-команда, а не как приложение с собственным мнением о том, что печатать.

Готово, если:

  • run_stream вместо «тихого» run + print в конце
  • Текст идёт через stream_text(delta=True) в stdout
  • Tool call / result пишутся в stderr
  • 2>/dev/null оставляет в stdout только ответ
  • Сборка Agent / tools не менялась ради стрима
ДАЛЬШЕ Тот же самый поток кусков можно отдать не в терминал, а в браузер по HTTP. Следующий урок - про границу между агентом и поверхностью, и React для него учить не понадобится.