Web surface
У нашего агента нет своего интерфейса, и это его сильная сторона.
Терминал - одна поверхность, чат в браузере - другая, а завтра
кто-нибудь приделает бота в мессенджер. Самое приятное в этой
картине: код агента между ними не меняется вообще. Меняется обёртка -
куда лить куски текста, где хранить разговор, чем рисовать результат
grep: списком ссылок или строчкой в stderr.
Урок чисто теоретический - код писать не нужно. Рабочая демка курса остаётся в терминале, а веб мы разбираем как чертёж: чтобы в субботу вечером можно было собрать себе UI и ни разу не залезть внутрь Agent. Если по ходу чтения возникнет мысль «а вот тут бы я добавил флажок в harness» - остановитесь, это как раз тот момент, который урок и должен предотвратить.
Слова, которые встретятся
- SSE (Server-Sent Events) - способ, которым сервер сам подкидывает события клиенту по одному открытому HTTP-соединению. Для стрима кусков текста подходит идеально и стоит дешевле websocket-хозяйства.
- Сессия - единица разговора: сообщения, которые лежат на диске или в базе, и к которым можно вернуться после того, как вкладку закрыли. В терминале аналога нет: там сессия умирает вместе с процессом.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
| проект ученика | Не трогать. Урок чисто теоретический - код писать не нужно. Рабочий код модуля - CLI. |
Две поверхности рядом
Разложим обе поверхности в одну таблицу. Смотрите на неё не как на список различий, а как на список того, что придётся написать в обёртке - и только в ней.
| CLI | Web | |
|---|---|---|
| Вывод | текст в терминале | пузыри чата |
| Tools | строки в stderr | карточки / спиннеры |
| Approval | строка-блок / stdin | кнопки «разрешить / нет» |
| Жизнь | пока жив процесс | сессия в хранилище |
| Стрим | stdout.write | SSE / chunked HTTP |
| Ввод | один раз из argv | поле ввода снова и снова |
Обратите внимание, чего в таблице нет: строчки «инструменты», «промпт», «песочница». Они одинаковые в обоих столбцах, поэтому и не попали в перечень различий. Ровно об этом и урок.
Что добавляет web
1. Хранение сессий (persistence)
Закрыли терминал - и разговора больше нет, никто по этому поводу не расстраивается. В браузере такое поведение уже воспринимается как баг: пользователь ждёт, что переписка его дождётся. Значит, поверхность должна уметь сохранять и поднимать историю.
# идея, не копировать в main.py
await save_messages(session_id, messages)
messages = await load_messages(session_id)
# дальше тот же agent.run_stream(prompt, message_history=messages, ...)
И заметьте, кто про что знает. Агент про базу не слышал: ему либо передали историю сообщений, либо нет. Решение «загрузить, потом сохранить» целиком принимает поверхность. Это не педантизм, а практика: с таким разделением ту же самую логику можно завтра позвать из cron-скрипта, где никаких сессий вообще не бывает.
2. Стрим по HTTP
В терминале мы писали куски прямо в TTY. Здесь их надо доставить в браузер, и самый непритязательный способ - SSE. Набросок на FastAPI, но подойдёт любой ASGI-фреймворк:
# псевдокод поверхности, не урок build-along
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import json
app = FastAPI()
@app.post("/run")
async def run(body: dict):
prompt = body["prompt"]
session_id = body["session_id"]
messages = await load_messages(session_id)
async def gen():
async with agent.run_stream(
prompt,
message_history=messages,
# deps / event handler - как в CLI
) as run:
async for chunk in run.stream_text(delta=True):
yield f"data: {json.dumps({'type': 'text', 'delta': chunk})}\n\n"
# tool-события можно слать тем же каналом из handler
yield "data: {\"type\": \"done\"}\n\n"
return StreamingResponse(gen(), media_type="text/event-stream")
Присмотритесь: внутри та же петля по кускам, что была в
main.py, только теперь каждый кусок уезжает по
проводу, а рисует его клиент. Событие про инструмент можно слать
тем же каналом из хендлера - в терминале оно шло в stderr, здесь
станет карточкой в интерфейсе.
3. Инструменты как компоненты
Событие от одного и того же инструмента в терминале выглядит строкой, а в браузере может стать чем угодно. Сравните:
| Tool | CLI | Web |
|---|---|---|
read |
путь + строки | блок кода с подсветкой |
grep |
счётчик + первые матчи | список с ссылками на файлы |
bash |
команда + exit | «терминал» + бейдж кода |
ask_user |
текст вопроса | кнопки с вариантами |
Агент во всех строках таблицы шлёт абсолютно одинаковые события. Вид выбирает поверхность. Поэтому и полезно, чтобы события имели стабильную форму: имя инструмента, аргументы, результат. Тогда новый рендер - это работа фронтендера, а не повод править harness.
4. Возобновляемый стрим
Самый неприятный сценарий выглядит так: вкладку закрыли на середине ответа, а открыли через пять минут. Веб на это может ответить двумя способами - подключиться к живому стриму, если прогон ещё идёт, или показать сохранённое состояние, если всё уже закончилось. В терминале такой развилки нет просто потому, что возвращаться некуда: процесса больше не существует. Тут и встречаются два предыдущих пункта: сессия - это единица работы, а стрим - всего лишь один её показ.
if is_web внутри агента и инструментов. На
входе промпт и, возможно, история. На выходе поток событий.
Авторизация, вёрстка, база, кнопки подтверждения - всё это живёт в
поверхности. Как только вы поймали себя на мысли «а это же для
браузера» посреди файла с инструментом, шов поехал: выносите
наружу, пока таких мест не стало пять.
Проверьте (без кода)
Кода нет, поэтому проверяем понимание. Три вопроса, отвечать лучше вслух или на бумаге - так сразу видно, где объяснение расползается.
- Без подглядывания: что меняется между CLI и web?
- Набросайте поток одного промпта в web: где save/load, где стрим пересекает сеть.
- Возьмите один свой tool: как выглядит в stderr CLI и каким был бы компонент в UI? Один и тот же shape события?
Готово, если:
- Объясняете, почему код агента не меняется между поверхностями
- Можете набросать persistence, HTTP-стрим и рендер tools для web
- Чётко делите: что в агенте, что в surface