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. Противоположность - «процесс умер, а песочница живёт и капает в счёт».
Быстрый путь
- Заменить разбор argv на
argparse. - Вынести
sandbox_from_flag(local / memory). - Модель брать из
--model. - 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. Пользователь нажал
Ctrl-C - прерывание часто рвёт цикл так, что до
finally дело не доходит, и остановку зовёт
обработчик сигнала. На local вы разницы почти не заметите. На
cloud разница называется «забытая виртуалка в счёте за месяц».
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
- Запуск с флагами отрабатывает