Оглавление: риски · минимальный список · JSON Schema · таймауты и предохранитель · поля логов · матрица · шаги · чек-лист · FAQ
Материал для команд которые выводят PydanticAI в прод на арендованном удалённом Mac и хотят одинаковые гарантии для Python сервисов и для соседних репозиториев. Смежный контур без PydanticAI но с той же идеей схемы на границе — гайд по Instructor и OpenClaw; плагины Semantic Kernel — отдельная статья; мультиагент и семафоры — CrewAI за шлюзом; наблюдаемость полей — матрица OpenTelemetry GenAI. Публичные покупка и тарифы открываются без входа.
Три риска до первого инцидента
- Неограниченный каталог инструментов: модель предлагает имя вне политики и шлюз успевает инициировать побочный эффект до отказа.
- Две схемы: Pydantic модель обновили а JSON Schema на шлюзе забыли — получите зелёный юнит-тест и красный прод.
- Один таймаут на всё: смешение ожидания первого токена и дорогой валидации маскирует причину и провоцирует шторм ретраев на unified memory.
Минимальный список инструментов и наименьшие привилегии
Зафиксируйте явный JSON перечень разрешённых имён инструментов версии политики tools_policy_version в репозитории. Каждая запись описывает имя аргументов по схеме и класс побочного эффекта чтение запись сеть. Шлюз сравнивает имя до маршрутизации к исполнителю; всё вне списка получает отказ TOOL_DENIED без вызова внешних API. На файловой системе держите только чтение кода и отдельный каталог scratch с квотой; ключи и токены в Keychain или файле 0600. Для обзора моста IDE и health проб см. материал про IDE-мост.
Проверка структурированного вывода по JSON Schema
Вынесите каноническую JSON Schema финального ответа агента в schemas/agent_final.json и прогоняйте её на шлюзе после извлечения чистого JSON из completion. PydanticAI должен импортировать модель сгенерированную из того же файла или из общего пакета чтобы не было расхождения полей. Любое изменение полей проходит через один merge request и артефакт в CI. При отклонении возвращайте тело с кодом SCHEMA_REJECT и указателем jsonschema без сырого текста модели наружу.
Таймауты и предохранитель цепи
Задайте два бюджета времени: мягкий на HTTP клиенте PydanticAI и жёсткий на шлюзе с запасом в несколько секунд чтобы клиент получил структурированный отказ а не обрыв сокета. Накопите в скользящем окне число последовательных SCHEMA_REJECT и пятисотых ошибок маршрута; после порога переведите маршрут в полуоткрытый breaker с пробным трафиком и джиттером бэкоффа. Идемпотентность для инструментов с записью обязательна иначе повторы удвоят эффекты. Соседний контур маршрутизации моделей описан в LiteLLM Proxy и OpenClaw.
Поля журналирования для разборов
Минимальный набор полей на каждый запрос: request_id сквозной trace_id route model_alias tools_policy_version schema_revision latency_model_ms latency_validate_ms tool_calls_allowed счётчик tool_calls_executed и итоговый outcome с подкодом отказа. Для стриминга фиксируйте first_token_ms отдельно от полного времени. Эти имена стыкуются с рекомендациями из GenAI наблюдаемости и упрощают корреляцию с шлюзом.
Матрица где резать отказы
| Слой | Инвариант | Цена пропуска |
|---|---|---|
| Клиент PydanticAI | Типизированный ответ и ранние проверки аргументов инструментов | Удобная разработка без защиты чужих языков и CLI |
| Шлюз OpenClaw | Белый список инструментов и JSON Schema из git | Побочные эффекты и порча данных вниз по цепочке |
| Надёжность | Двойной таймаут полуоткрытый breaker идемпотентность ретраев | Своп на Apple Silicon и зависание воркеров шлюза |
# контракт границы: одна schema_revision на весь кластер
# export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
# breaker: schema_reject_streak >= 5 -> half_openВоспроизводимые шаги
1) Песочница пользователя. Создайте сервисного пользователя каталог ~/pydantic-edge подкаталоги config logs schemas права на репозиторий только чтение scratch на запись с лимитом размера.
2) OpenClaw на loopback. Поднимите шлюз на 127.0.0.1 задайте Bearer в файле chmod 0600 выполните openclaw doctor --json до нагрузки.
3) Политика инструментов. Загрузите JSON белого списка в шлюз и включите отказ до исполнения для любых имён вне списка зафиксируйте tools_policy_version в логах.
4) Схема ответа. Подключите schemas/agent_final.json к валидации на шлюзе и к модели в PydanticAI через общий пакет или кодогенерацию.
5) Таймауты. Разведите лимиты первого токена полного ответа и блока валидации клиентский HTTP таймаут оставьте ниже жёсткого лимита шлюза.
6) Breaker и ретраи. Настройте окно счётчиков полуоткрытие и джиттер для повторов запретите бесконечные циклы на агентском уровне.
7) Failure summary. На любой ошибке шлюза формируйте компактный JSON с request_id stage code hint без сырого completion и без пользовательского ввода отдайте тот же контур клиенту и в лог.
Чек-лист перед нагрузкой
- В git одна ревизия схемы и она же в переменной
schema_revisionшлюза и агента. - Белый список инструментов загружен версия политики совпадает с артефактом CI.
- Таймауты согласованы клиент ниже шлюза лимит на валидацию отдельно от лимита модели.
- Breaker считает
SCHEMA_REJECTи 5xx раздельно пороги задокументированы в runbook. - Логи содержат полный минимальный набор полей тестовый запрос находится по
request_idв шлюзе и в агенте. - Soak минимум два часа на удалённом Mac без параллельного тяжёлого десктопа на том же пуле памяти.
Краткие ответы
Нужен ли дубль валидации в клиенте и на шлюзе? Да: клиент ускоряет обратную связь разработчику шлюз защищает периметр и чужие клиенты.
Как жить с markdown фенсами вокруг JSON? Шлюз обязан вычищать оболочку до jsonschema иначе стабильные ложные отказы.
Где крутить продовые пробы? На выделенном узле из каталога аренды с фиксированным профилем железа.
Публичные страницы без логина: главная, блог, помощь, тарифы, покупка.
Итог: белый список инструментов и одна JSON Schema на границе плюс дисциплина таймаутов и логов даёт воспроизводимый контур PydanticAI за OpenClaw на удалённом Mac без утечки секретов в сводках ошибок.