MODULE_10 · УРОК 10.1

CLI entry point

С первого модуля вы запускаете uv run python main.py . "промпт". Формально это уже CLI. Просто невоспитанный: позиционные аргументы тащат на себе слишком много смысла, песочница переключается переменной SANDBOX=..., модель зашита в код гвоздями. Пока вы один пользователь своего harness, терпимо. Но привычка «запомню, в каком порядке аргументы» ломается ровно в тот день, когда вы вернётесь к проекту через месяц.

Есть и вторая, менее уютная деталь. Нажмите Ctrl-C посередине прогона: local-песочница пожмёт плечами, а cloud оставит гореть виртуалку, за которую кто-то платит. Так что этот урок не про красоту флагов, а про то, чтобы вход и выход из агента были предсказуемыми.

ЧТО ПОЛУЧИТСЯ main.py читает --sandbox, --model, каталог и промпт через argparse. А sandbox.stop() вместе с lifecycle гарантированно вызывается и в finally, и на SIGINT.

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

  • Агент без UI (headless) - ядро, у которого нет своего интерфейса: только логика и инструменты. А то, через что с ним разговаривают, называется поверхностью (surface): тонкая обёртка в виде CLI, веб-чата или бота. Агент один, рендер у каждой поверхности свой.
  • Чистый выход - когда stop() случается при любом исходе: и при штатном завершении, и при исключении, и при Ctrl-C. Противоположность - «процесс умер, а песочница живёт и капает в счёт».

Быстрый путь

  1. Заменить разбор argv на argparse.
  2. Вынести sandbox_from_flag (local / memory).
  3. Модель брать из --model.
  4. SIGINT + try/finally со stop.

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

Файл Что делать
main.py Править. argparse, фабрика sandbox, SIGINT, finally.
tools / prompts / sandbox_* Не трогать. Меняется только входная оболочка.

Шаг 1. argparse вместо самодельного argv

Открывайте main.py и найдите то место в начале файла, где вы вручную разбираете sys.argv и лезете в os.environ["SANDBOX"]. Всё это (до создания песочницы) заменяем на честный парсер:

main.py - разбор аргументов

import argparse
import asyncio
import signal
import sys
from pathlib import Path

from sandbox_local import create_local_sandbox
from sandbox_memory import create_memory_sandbox
# ... остальные импорты как были ...

parser = argparse.ArgumentParser(description="AI coding agent harness")
parser.add_argument(
    "--sandbox",
    default="local",
    choices=["local", "memory"],
    help="бэкенд песочницы (по умолчанию local)",
)
parser.add_argument(
    "--model",
    default="deepseek:deepseek-chat",
    help="строка модели для Pydantic AI",
)
parser.add_argument("cwd", nargs="?", default=".", help="рабочий каталог")
parser.add_argument(
    "prompt_parts",
    nargs="*",
    default=[],
    help="текст задания (остальные слова)",
)
args = parser.parse_args()

cwd = Path(args.cwd).resolve()
prompt = " ".join(args.prompt_parts) or "Привет!"

Шаг 2. Фабрика sandbox по флагу

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

def sandbox_from_flag(name: str, directory: Path):
    if name == "memory":
        return create_memory_sandbox(directory)
    return create_local_sandbox(directory)


sandbox = sandbox_from_flag(args.sandbox, cwd)
print(f"Sandbox: {sandbox.type}", file=sys.stderr)

Одна тонкость, о которой легко забыть: в build_system_prompt по-прежнему передаём sandbox.working_directory и sandbox.type, а не сырой cwd. Для memory-песочницы это разные вещи, и агент должен знать, где он на самом деле работает.

Шаг 3. Модель из флага

Самая дешёвая правка урока: там, где создаётся Agent(...), вместо зашитой строки подставляем флаг. Пригодится в первый же раз, когда захочется сравнить две модели на одной задаче.

agent = Agent(
    args.model,
    deps_type=Sandbox,
    tools=[...],
    instructions=instructions,
    # ProcessHistory / остальное - как было
)

Шаг 4. SIGINT и finally

Lifecycle из урока 4.5 остаётся как есть, мы его не переписываем. Добавляем обработчик сигнала и следим, чтобы остановка жила в finally, а не в счастливой ветке кода:

main.py - main() и сигнал

lifecycle = EmptyLifecycle()  # или ваш LoggingLifecycle

def _install_sigint(loop: asyncio.AbstractEventLoop) -> None:
    def _handler() -> None:
        print("\nShutting down...", file=sys.stderr)
        loop.create_task(_shutdown())

    async def _shutdown() -> None:
        try:
            await lifecycle.before_stop(sandbox)
            await sandbox.stop()
        finally:
            sys.exit(0)

    try:
        loop.add_signal_handler(signal.SIGINT, _handler)
    except NotImplementedError:
        # Windows / редкие окружения - finally всё равно спасёт
        signal.signal(signal.SIGINT, lambda *_: sys.exit(0))


async def main() -> None:
    loop = asyncio.get_running_loop()
    _install_sigint(loop)

    await lifecycle.after_start(sandbox)
    try:
        result = await agent.run(prompt, deps=sandbox)
        print(result.output)
    finally:
        await lifecycle.before_stop(sandbox)
        await sandbox.stop()


if __name__ == "__main__":
    asyncio.run(main())
ЗАЧЕМ И finally, И SIGINT Кажется, что это дублирование, но случаи разные. Агент упал с исключением - спасает finally. Пользователь нажал Ctrl-C - прерывание часто рвёт цикл так, что до finally дело не доходит, и остановку зовёт обработчик сигнала. На local вы разницы почти не заметите. На cloud разница называется «забытая виртуалка в счёте за месяц».
CLI - ТОНКАЯ ОБЁРТКА Посмотрите на main.py целиком: почти весь файл - это сборка агента из прошлых модулей. Собственно «командной строкой» здесь являются argparse и обработчик сигнала, десяток строк. Если завтра вместо терминала будет браузер или Slack, поменяются именно они, а инструменты, промпт и песочница останутся на своих местах. Это и есть признак того, что шов проведён правильно.

Проверьте

uv run python main.py --sandbox=memory --model=deepseek:deepseek-chat . "Прочитай pyproject.toml"

В stderr должно мелькнуть Sandbox: memory, в stdout - ответ модели. Флаги работают, порядок аргументов больше не надо держать в голове.

Теперь проверим выход. Запустите что-нибудь заведомо долгое и прервите Ctrl-C на середине.

uv run python main.py . "Найди все TODO и коротко перескажи"

Ожидаем Shutting down... и мгновенный выход, без зависшего процесса и без «а он там ещё что-то делает?». Старый способ через SANDBOX=memory ... можно спокойно похоронить: один явный флаг лучше двух способов сделать одно и то же.

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

  • --sandbox и --model читаются через argparse
  • cwd и prompt - позиционные аргументы
  • sandbox.stop() в finally при нормальном / ошибочном выходе
  • SIGINT тоже останавливает sandbox
  • Запуск с флагами отрабатывает
ДАЛЬШЕ Вход в порядке, а вот вывод пока молчит до самого конца прогона. В следующем уроке включим стрим: текст пойдёт по мере появления, а вызовы инструментов - отдельным потоком в stderr.