MODULE_10 · УРОК 10.3

Web surface

У нашего агента нет своего интерфейса, и это его сильная сторона. Терминал - одна поверхность, чат в браузере - другая, а завтра кто-нибудь приделает бота в мессенджер. Самое приятное в этой картине: код агента между ними не меняется вообще. Меняется обёртка - куда лить куски текста, где хранить разговор, чем рисовать результат grep: списком ссылок или строчкой в stderr.

Урок чисто теоретический - код писать не нужно. Рабочая демка курса остаётся в терминале, а веб мы разбираем как чертёж: чтобы в субботу вечером можно было собрать себе UI и ни разу не залезть внутрь Agent. Если по ходу чтения возникнет мысль «а вот тут бы я добавил флажок в harness» - остановитесь, это как раз тот момент, который урок и должен предотвратить.

ЧТО ПОЛУЧИТСЯ Сможете объяснить, как веб переиспользует того же самого агента, что добавляет от себя поверхность (хранение сессий, стрим по HTTP, компоненты вместо строк) и где именно проходит граница между агентом и поверхностью. Урок чисто теоретический - код писать не нужно.

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

  • 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. Возобновляемый стрим

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

АГЕНТ НЕ ЗНАЕТ ПРО WEB Никаких if is_web внутри агента и инструментов. На входе промпт и, возможно, история. На выходе поток событий. Авторизация, вёрстка, база, кнопки подтверждения - всё это живёт в поверхности. Как только вы поймали себя на мысли «а это же для браузера» посреди файла с инструментом, шов поехал: выносите наружу, пока таких мест не стало пять.
ПОЧЕМУ В КУРСЕ НЕТ ГОТОВОГО UI Потому что приличный фронтенд - это отдельный курс, и мы бы полтора модуля обсуждали состояние компонентов вместо агента. Ценность здесь в границе, а не в React. Проверка простая: код модулей 1-9 без единой правки должен работать и под терминалом, и под HTTP-обёрткой. Если не работает, вы нашли себе задачу на вечер.

Проверьте (без кода)

Кода нет, поэтому проверяем понимание. Три вопроса, отвечать лучше вслух или на бумаге - так сразу видно, где объяснение расползается.

  1. Без подглядывания: что меняется между CLI и web?
  2. Набросайте поток одного промпта в web: где save/load, где стрим пересекает сеть.
  3. Возьмите один свой tool: как выглядит в stderr CLI и каким был бы компонент в UI? Один и тот же shape события?

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

  • Объясняете, почему код агента не меняется между поверхностями
  • Можете набросать persistence, HTTP-стрим и рендер tools для web
  • Чётко делите: что в агенте, что в surface
ДАЛЬШЕ - МОДУЛЬ 11 С поверхностями разобрались. Последний модуль про расширяемость: skills как подгружаемые знания, реестр для своих инструментов и точки расширения. Туда же приедут события approval и нормальный рендер результатов, которые мы дважды обещали по ходу курса.