Streaming и рендер tools
agent.run() устроен честно и неудобно: он молчит, пока
прогон не закончится целиком. На простом вопросе это незаметно, а
вот на задаче с тремя инструментами терминал уже полминуты выглядит
мёртвым. И вы сидите и гадаете: он думает, он ушёл в цикл или он
упал, а сообщение об ошибке где-то застряло. Знакомое чувство и
совершенно лишнее.
Стрим убирает эту неопределённость. Текст течёт кусками по мере генерации, вызов инструмента виден в момент вызова, результат - как только вернулся. Пользователь видит движение, а вы наконец видите, чем агент занят на самом деле, а не что он решил рассказать в финальном абзаце.
run_stream: финальный текст уходит в
stdout по кускам, а вызовы и результаты инструментов - в stderr.
Сам агент, его инструменты и песочница остаются нетронутыми.
Слова, которые встретятся
-
stream_text(delta=True) - выдаёт только новый
кусок текста с прошлого тика. Без
deltaвам каждый раз прилетает вся накопленная строка, и в терминале получается лестница из повторов. - event_stream_handler - колбэк, которому harness рассказывает о событиях прогона: инструмент пошёл, инструмент вернулся, приехала очередная часть ответа.
- stdout и stderr - два потока вывода. Ответ модели пойдёт в первый, служебная возня с инструментами во второй. Разделение бесплатное, а пользы много: шум всегда можно отключить одним перенаправлением.
Быстрый путь
- Написать
event_stream_handlerдля tool-событий → stderr. - Заменить
agent.runнаrun_stream+ handler. - Писать финальный текст через
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()
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 не менялась ради стрима