Глава 16. Базовая схема среды исполнения¶

1. Зачем нужна эталонная схема среды исполнения, если у тебя уже есть архитектура¶

Архитектурные главы полезны, потому что они дают язык и рамку. Но в какой-то момент почти у всех возникает один и тот же вопрос: “Хорошо, а как это должно выглядеть как система, которую реально можно собрать?”

Именно в этом состоит главная задача этой главы. Она должна помочь читателю перейти через важную границу: от согласия с аргументом книги к пониманию того, как этот аргумент превращается в работающую структуру системы.

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

Вот тут и нужна эталонная схема среды исполнения.

Ее задача не в том, чтобы стать единственной возможной реализацией. Ее задача:

• зафиксировать основные модули;
• показать поток одного запуска;
• отделить обязательные слои от необязательных улучшений;
• дать команде отправную точку без лишней магии.

Поэтому эту главу полезно читать не только как главу про границы модулей, но и как главу про работающую структуру под давлением изменений. Настоящий вопрос в том, появилась ли у среды исполнения такая форма, которая выдержит новые политики, новые инструменты, длинные запуски, прерывания и давление поэтапного выпуска, не распадаясь снова на обработчики и исключения.

2. Минимально взрослая среда исполнения уже состоит не из одной модели¶

Очень полезно сразу отказаться от образа “агент = один вызов модели плюс инструменты”.

Минимально взрослая среда исполнения обычно включает:

• слой входа;
• координатор запуска;
• проверки политик;
• слой доступа к памяти;
• слой исполнения инструментов и возможностей;
• эмиттер телеметрии;
• сборку результата.

То есть среда исполнения — это не “место, где вызывается LLM”. Это управляемый цикл вокруг модели.

3. Как выглядит базовый поток одного запуска¶

Для эталонной реализации удобно мыслить один запуск примерно так:

1. принять запрос и построить контекст запуска;
2. выполнить предварительные проверки политик;
3. собрать нужный контекст из памяти и извлечения;
4. вызвать модель;
5. если нужен вызов инструмента, прогнать его через слой исполнения;
6. записать телеметрию;
7. собрать финальный результат;
8. запланировать фоновые обновления.

Это уже очень далеко от “просто чат с функциями”, и именно так и должно быть.

flowchart LR
    A["Вход"] --> B["Контекст запуска"]
    B --> C["Предварительная проверка политик"]
    C --> D["Память / извлечение"]
    D --> E["Шаг модели"]
    E --> F{"Нужен инструмент?"}
    F -->|Нет| G["Сборка результата"]
    F -->|Да| H["Слой исполнения"]
    H --> I["Результат инструмента"]
    I --> E
    G --> J["Телеметрия + фоновые задачи"]

4. Какие модули полезно держать отдельными сразу¶

Есть несколько границ, которые выгодно выделить в коде уже в первой версии:

• runtime.py или orchestrator.py для основного цикла;
• policy.py для решений политик;
• memory.py для извлечения и записей памяти;
• catalog.py для реестра возможностей;
• execution.py для вызова инструментов;
• telemetry.py для spans и structured events.

Когда все это слеплено в один большой обработчик, первые демо получаются быстро, но взросление системы становится болезненным почти сразу.

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

5. Не смешивай оркестрацию и бизнес-адаптеры¶

Одна из самых дорогих ошибок стартовой реализации: среда исполнения напрямую знает слишком много про конкретные внешние системы.

Тогда код оркестрации начинает содержать:

• условную логику по конкретным инструментам;
• знание о внешних формах payload;
• локальные ретраи под конкретный API;
• разовое маскирование данных;
• специальные обходы для отдельных интеграций.

Эталонная среда исполнения должна показывать обратную идею: оркестрация работает через контракты, а адаптеры живут на краю системы.

6. Пример минимальной структуры проекта¶

Ниже очень приземленный вариант стартовой структуры:

agent_runtime/
  orchestrator.py
  policy.py
  memory.py
  catalog.py
  execution.py
  telemetry.py
  models.py
  background.py

Это не “единственно правильная” структура. Но она уже помогает не свалить все в один файл и не смешать контрольные слои между собой.

7. Простой кодовый каркас оркестратора¶

Ниже не промышленная среда исполнения, а именно каркас-схема. Он показывает, как разделяются шаги запуска и где должны проходить ключевые контрольные точки.

from dataclasses import dataclass


@dataclass
class RunRequest:
    user_input: str
    tenant_id: str
    principal_id: str


@dataclass
class RunResult:
    output_text: str
    status: str


def run_agent(request: RunRequest) -> RunResult:
    policy_check(request)
    context = retrieve_context(request)
    model_output = call_model(request, context)

    if model_output.get("tool_request"):
        tool_result = execute_tool(model_output["tool_request"])
        emit_event("tool_execution", tool_result)
        model_output = call_model(request, context + [tool_result])

    schedule_background_updates(request, model_output)
    return RunResult(output_text=model_output["text"], status="success")

Идея здесь очень простая: даже базовая среда исполнения уже должна явно показывать проверки политик, извлечение, исполнение инструментов и фоновые обновления как отдельные этапы.

8. Длинные запуски — не необязательная надстройка, а часть базового контура¶

Частая ошибка рантайма в том, что команда молча предполагает: любой полезный запуск должен завершаться в одном синхронном запросе. Это верно только пока система остается заточенной под демо.

В реальном сценарии поддержки часть запусков по природе длиннее:

• ожидание подтверждения;
• ожидание инструментов с нестабильной задержкой;
• ожидание второго прохода модели после исполнения инструментов;
• ожидание отложенного продолжения или фонового обновления.

Свежий материал OpenAI полезен тем, что рассматривает фоновое исполнение как самостоятельную заботу среды исполнения, а не как обход проблем с ограничением времени.⁴

Именно так на это и стоит смотреть в базовой среде исполнения. Рантайм должен уже на старте различать:

• синхронные запуски, которые безопасно завершаются в одном активном проходе;
• фоновые запуски, которые продолжаются после первого ответа;
• возобновляемые запуски, которые ставятся на паузу из-за подтверждения, внешнего ввода или отложенной работы.

Таксономия схем рабочих процессов у Anthropic делает это еще острее, потому что разные схемы оркестрации создают разные потребности в контрольных точках.² У prompt chaining контрольная точка обычно нужна между фиксированными стадиями, у routing она часто нужна только на границе классификации и передачи, параллельное исполнение требует видимости состояния объединения, а схема orchestrator-workers требует состояния координации оркестратора и рабочих агентов, которое переживает частичное завершение.

Механизм сохранения состояния LangGraph показывает тот же принцип на уровне детализации контрольных точек: долговечное состояние организуется по потоку, контрольные точки сохраняются на границах надшага, а успешные записи узлов внутри упавшего надшага могут сохраняться как ожидающие записи, чтобы при продолжении не пересчитывать уже выполненные узлы.⁵ Архитектурный вывод: контрольные точки — это не один логический флаг. Среда исполнения должна явно назвать курсор для продолжения, границу допустимого повторного проигрывания и частичные записи, которые нельзя продублировать после сбоя.

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

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

Если у рантайма нет явной формы для этих случаев, длинная работа почти всегда утекает в несистемные повторы, дублирующиеся запросы и скрытые переходы состояния.

8.1. Состояние сессии песочницы тоже является состоянием среды исполнения¶

У Sandbox Agents в OpenAI Agents SDK есть полезное разделение, которое стоит перенести в дизайн базовой среды исполнения: Manifest описывает контракт свежего рабочего пространства, а конкретный запуск может получить живую сессию песочницы, сериализованный session_state или стартовать из снимка snapshot.¹¹

Для эталонного рантайма это означает, что состояние песочницы нельзя прятать внутри адаптера инструмента. Минимально полезная модель должна уметь хранить рядом с run_id и trace_id хотя бы:

• sandbox_session_id;
• sandbox_manifest_version;
• sandbox_permissions_profile;
• snapshot_id, если запуск стартовал из сохраненного рабочего пространства;
• список материализованных записей рабочего пространства или ссылку на проверенный манифест;
• признак, можно ли эту песочницу продолжить, сохранить снимком или нужно пересоздать.

Тогда длительная работа с файлами, командной оболочкой и памятью не превращается в непрозрачную папку на диске. Она становится частью того же слоя управления средой исполнения, где уже живут подтверждения, фоновые запуски, сессии возможностей и доказательства трасс.

8.2. Именованный агент с состоянием как отдельная топология среды исполнения¶

Cloudflare Agents SDK показывает другую полезную базовую схему: агент может быть не только временным циклом исполнения, но и именованным долговечным объектом среды исполнения. В их модели каждый экземпляр агента работает поверх Durable Object: у него есть собственное долговечное состояние SQL/ключ-значение, WebSocket-соединения, запланированные задачи, возможность проснуться по событию и снова перейти в спящий режим, когда он простаивает.¹⁰

В книгу это стоит переносить не как рекомендацию “используйте именно Cloudflare”, а как архитектурную форму. Если агент привязан к стабильному имени реальной сущности — обращению клиента, проекту, устройству, рабочему пространству клиента, комнате, ветке обсуждения или исследовательскому досье, — среда исполнения должна явно разделять:

• agent_instance_id, который живет дольше одного run;
• run_id, который описывает конкретное выполнение;
• session_id, который описывает пользовательскую или транспортную сессию;
• долговечное состояние агента, которое переживает разрыв соединения, выкладку, спящий режим и фоновое пробуждение;
• внешнее хранилище знаний, которое не является частным изменяемым состоянием одного экземпляра.

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

Поэтому эталонный рантайм не обязан реализовывать Durable Objects, но ему нужна абстракция вроде хранилища экземпляров агента AgentInstanceStore и границы планировщика SchedulerBoundary: место, где видно, какой именованный экземпляр владеет состоянием, какие запуски его меняли, какие запланированные задачи могут его разбудить и какие трассы доказывают безопасное продолжение.

Сторона расписания особенно важна: Cloudflare показывает отложенные, запланированные, cron- и интервальные задачи, которые переживают перезапуск, сохраняются в SQLite и будят агента через сигналы Durable Object.⁹ Архитектурный вывод для книги: расписание нельзя оставлять невидимым обратным вызовом. Его нужно отражать как долговечную контрольную запись с экземпляром-владельцем, схемой полезной нагрузки, ключом идемпотентности, политикой пересечения запусков, временем следующего срабатывания и связью с трассой.

Сторона реального времени добавляет еще одну границу: состояние соединения не равно состоянию агента. В WebSocket-модели Cloudflare Agents у соединения есть собственный id, uri, состояние на уровне соединения, метки, обработчики жизненного цикла и возможность выключить протокольные сообщения вроде identity/state/MCP для конкретного соединения.⁷ Для базовой среды исполнения это означает, что широковещательные сообщения, присутствие пользователя, интерфейс подтверждения и потоковые обновления должны проходить через авторизацию в области соединения и трассируемую рассылку, а не напрямую читать все долговечное состояние агента.

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

Антипаттерн здесь — скрытая долговечная память: именованный агент копит приватное состояние, позже извлекает его или действует на его основе как на проверенное знание, а у операторов нет экспорта, аудиторского следа, пути миграции схемы или истории удаления. Долговечное состояние актора полезно только тогда, когда его владение и жизненный цикл явно описаны.

8.3. Оболочка агента и долговечный стержень рабочего процесса¶

Следующий полезный паттерн Cloudflare — не складывать всю долгую работу в один цикл событий агента. Агент может быть границей взаимодействия с состоянием: держать идентичность экземпляра, WebSocket- или HTTP-сессию, локальное состояние, пользовательские обратные вызовы и текущую картину диалога. Рабочий процесс при этом становится долговечной границей выполнения: хранит шаги, повторы, ожидание внешних событий, длительные шлюзы подтверждения и восстановление после падения.⁸

flowchart LR
    S["Сессия / хранилище состояния"] --> A["Оболочка среды выполнения агента"]
    A --> W["Долговечный стержень рабочего процесса"]
    W --> E["Инструмент / внешнее событие / шаг подтверждения"]
    W --> L["Журнал аудита и доказательств"]
    A --> U["Пользовательский поток / WebSocket"]
    E --> L

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

8.4. Проверяемое завершение как обязанность среды исполнения¶

Один практический урок из Claude Code переносится почти напрямую в базовую среду исполнения: автономному агенту нужен не только цикл действий, но и цикл проверки.¹ Если рантайм знает только “агент вернул финальный ответ”, оператор снова становится единственным контуром качества. Если же рантайм хранит условие завершения и результат проверки, запуск можно безопаснее оставлять без постоянного наблюдения.

Минимально полезная модель запуска поэтому должна уметь не только исполнять инструменты, но и фиксировать:

• stop_condition: какое проверяемое условие должно быть истинным перед завершением;
• verification_command или другой проверяемый механизм;
• verification_result: pass, fail, warning или blocked;
• verifier_actor: сам агент, детерминированный gate, отдельный verifier/subagent или человек;
• evidence_refs: ссылки на тестовый вывод, трассу, снимок экрана, diff или другой артефакт.

Это не обязательно значит, что каждый запуск должен тащить полный CI. Но рантайм должен иметь место для доказательства завершения. Иначе “done” остается свободным текстом, который плохо подходит для регрессионных шлюзов, ревью раскатки и последующего расследования.

9. Сессии инструментов с состоянием тоже должны входить в базовый контур¶

Как только слой исполнения начинает работать с MCP-подобными возможностями с состоянием, у базовой среды исполнения появляется еще одна обязательная граница: состояние видимого пользователю запуска не равно состоянию сессии возможности.³

Это важно потому, что один пользовательский запуск теперь может включать:

• один run_id среды исполнения;
• один или несколько MCP session_id для внешних возможностей;
• уведомления о ходе выполнения до финального ответа;
• промежуточные запросы данных, которые ставят запуск на паузу до нового ввода;
• повторную инициализацию, если сессия возможности истекла до завершения запуска.

Если все это слепить в один непрозрачный объект состояния, оператор уже не сможет объяснить, что именно продолжилось, что истекло и что надо повторить заново.

9.1. Среда исполнения должна относиться к сессии возможности как к состоянию первого класса¶

Минимально зрелый рантайм обычно уже должен уметь хранить хотя бы:

• run_id;
• trace_id;
• capability_session_id;
• capability_session_status;
• expires_at;
• resume_token или другой дескриптор продолжения;
• approval_state, если поток инструмента с состоянием был поставлен на паузу из-за подтверждения.

Это не означает, что каждому инструменту нужна тяжелая модель сессии. Это означает, что у рантайма должно быть место, где такое состояние сессии можно выразить, когда протокол этого требует.

9.2. Ход выполнения и промежуточные запросы должны входить в ту же модель управления продолжением¶

Еще один полезный вывод из материалов о MCP-состоянии: события хода выполнения и промежуточные запросы данных нельзя считать экзотическим побочным каналом. Они должны входить в ту же модель управления средой исполнения, что подтверждения и фоновое продолжение.

Это становится еще важнее, когда рантайм поддерживает несколько схем оркестрации. Ход выполнения из ветки параллельного исполнения, из рабочего агента, делегированного через схему orchestrator-workers, или из стадии prompt chaining со шлюзом не должен пропадать внутри адаптеров, привязанных к конкретной схеме. Он должен попадать в одну общую поверхность управления для статуса, продолжения, истечения и видимости для оператора.

На практике базовая среда исполнения выигрывает от одной общей модели состояний для:

• in_progress работы, которая еще жива внутри сессии возможности;
• пауз waiting_for_input или waiting_for_approval;
• resumable работы, которую можно продолжить в той же сессии возможности;
• reinitialize_required работы, где сессия возможности истекла и ее нужно поднять заново перед продолжением.

Без этих различий истечение сессии обычно выглядит как случайная ошибка, хотя на деле это нормальное событие жизненного цикла.

10. Что важно встроить в базовый контур с самого начала¶

Есть вещи, которые кажется соблазнительным “добавить потом”, но на деле их лучше заложить сразу:

• trace_id на каждый запуск;
• контекст клиента и принципала;
• обработчики решений политики;
• реестр возможностей вместо прямых вызовов;
• структурированную телеметрию;
• базовую точку подключения фоновых задач;
• явную модель статусов запуска вроде queued / in_progress / completed / failed / canceled;
• способ опросить, продолжить или отменить длинную работу без изобретения второго скрытого рантайма.

Если этого нет в базовой версии, потом система обычно дорастает до этого через болезненную переделку.

11. Минимальный каркас для фоновой и возобновляемой работы¶

Даже базовая среда исполнения должна иметь простой способ представлять работу, которая живет дольше первого запроса.

from dataclasses import dataclass


@dataclass
class RunHandle:
    run_id: str
    status: str


def start_run(request: RunRequest) -> RunHandle:
    run_id = create_run_record(request)
    enqueue_run(run_id)
    return RunHandle(run_id=run_id, status="queued")


def continue_run(run_id: str):
    run = load_run(run_id)
    if run.status in {"canceled", "completed", "failed"}:
        return run

    update_status(run_id, "in_progress")
    result = execute_run_steps(run)
    update_status(run_id, result.status)
    return result

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

12. Что можно не усложнять в первой эталонной версии¶

На старте не обязательно сразу добавлять:

• сложный planner с множеством режимов;
• многоступенчатый конвейер сжатия памяти;
• сложную стратегию маршрутизации модели;
• полный контур самовосстановления;
• десяток золотых путей.

Эталонный runtime полезен не максимальной мощностью, а ясностью формы. Лучше небольшая, но чистая реализация, чем “универсальный комбайн”, который никто не понимает.

13. Пример конфигурации рантайма¶

Ниже пример конфигурации, которая задает форму рантайма, не вшивая все решения в код:

runtime:
  max_tool_hops: 3
  require_trace_id: true
  enable_background_updates: true
  default_model: gpt-5.4
  policy:
    precheck_required: true
  telemetry:
    emit_structured_events: true
  execution:
    gateway_required: true
  background:
    enabled: true
    resumable_runs: true
    allow_cancel: true
  capability_sessions:
    track_session_ids: true
    emit_progress_events: true
    support_reinit_on_expiry: true

Это полезно, потому что помогает держать контракт рантайма явным и переносимым между средами.

14. Частые ошибки¶

Очень типовые проблемы:

• оркестрация и адаптеры слеплены вместе;
• проверки политик вызываются не на каждом нужном пути;
• память подключена как случайный помощник;
• вызовы инструментов идут мимо реестра и шлюза;
• фоновые обновления отсутствуют;
• телеметрия добавлена по остаточному принципу;
• длинная работа спрятана за ретраями, а не смоделирована явно;
• фоновое исполнение вроде бы есть, но операторы не могут нормально опрашивать, продолжать или отменять работу.

То есть система вроде бы “работает”, но форма рантайма уже мешает ее взрослению.

15. Быстрый тест зрелости для базовой среды исполнения¶

Команде не стоит думать, что у нее уже есть эталонный рантайм, только потому, что у нее есть рабочий агент, несколько модулей и успешные демо.

Более сильная планка такая:

• оркестрация, политики, память, исполнение и телеметрия видимы как отдельные слои;
• контекст запуска с самого начала несет идентичность и контрольные метаданные;
• исполнение возможностей идет через контракты, а не через прямые вызовы адаптеров;
• трассировка и фоновые точки подключения встроены в базовый путь, а не появляются как переделка;
• длинная работа имеет явную модель статусов и продолжения, а не прячется в скрытых ретраях;
• один запуск можно объяснить как устойчивый каркас, а не как рассыпанную локальную логику.

Если большинство этих условий не выполняется, у команды уже может быть реализация, но реального чертежа базовой среды исполнения у нее пока нет.

16. Что сделать сразу¶

Сначала пройди по короткому списку и отдельно отметь все ответы «нет»:

• Видны ли отдельные слои оркестрации, политик, памяти, исполнения и телеметрии?
• Есть ли единый контекст запуска с метаданными клиента и принципала?
• Есть ли реестр возможностей вместо прямых вызовов?
• Встроены ли точки подключения трассировки в базовый путь?
• Есть ли безопасная точка для фоновых обновлений?
• Можно ли длинную работу явно поставить в очередь, наблюдать, продолжить и отменить?
• Можно ли объяснить поток одного запуска без чтения десяти файлов сразу?

Если на несколько вопросов подряд ответ “нет”, у тебя пока не эталонный рантайм, а просто ранняя интеграция модели в продукт.

17. Что делать дальше¶

Сначала зафиксируй форму рантайма, а потом добавляй поверх него слой политик и контракты возможностей.

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

• Глава 15. Золотые пути, общие шлюзы и антизоопарк-подходы
• Глава 17. Слой политик и каталог возможностей
• Часть VII. Эталонная реализация
• Источники