Продакшн ИИ-агентов: от прототипа к надежному сервису

Harness: инфраструктура, а не только промпт

Агент — это не только LLM и промпт. Это программная инфраструктура (harness), которая оркестрирует работу агента: управляет контекстом, вызывает инструменты, хранит память, обеспечивает контроль. Качество агента определяется качеством harness.

Harness включает: среду запуска кода, реестр инструментов, сервисы безопасности, мониторинг и трейсинг, управление памятью. В корпоративной среде это часто выделяется в отдельную платформу (AI Hub).

Не начинайте с создания собственного harness. Используйте существующие фреймворки (LangGraph, LangChain) и адаптируйте их под свои требования. Собственная разработка оправдана только при специфических требованиях.

• Harness: инфраструктура для оркестрации агента.
• Включает: рантайм, инструменты, память, безопасность, мониторинг.
• В корпоративной среде — AI Hub.
• Используйте существующие фреймворки, не создавайте свой.

Рантайм, очередь, песочница и учетные данные

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

Очередь сообщений (queue) позволяет обрабатывать запросы асинхронно. Это важно для длительных задач. Агент получает задачу, ставит ее в очередь, и обработчик выполняет ее в фоне. Клиент может опрашивать статус.

Песочница (sandbox) — это изолированная среда для выполнения сгенерированного кода. Если агент может генерировать код, он должен выполняться в песочнице с ограниченными правами. Учетные данные (credentials) должны храниться в безопасном хранилище и не попадать в промпт.

• Рантайм: изолированная среда выполнения.
• Очередь: асинхронная обработка длительных задач.
• Песочница: изоляция сгенерированного кода.
• Учетные данные: безопасное хранилище, не в промпте.

• Определите среду выполнения: контейнер, serverless, VM.
• Настройте изоляцию рантайма.
• Добавьте очередь для длительных задач.
• Настройте песочницу для сгенерированного кода.
• Храните учетные данные в безопасном хранилище.

Внешние эффекты и идемпотентность

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

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

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

• Чекпойнтер не гарантирует exactly-once для внешних эффектов.
• Узел может выполниться повторно после сбоя.
• Внешние операции должны быть идемпотентными.
• Используйте уникальные ID операций.

FastAPI: синхронный вызов или длительная задача

Простой способ запустить агента — обернуть его в FastAPI эндпоинт. Клиент отправляет запрос, сервер запускает граф и возвращает результат. Это подходит для быстрых задач, которые выполняются за секунды.

Длительный запрос может столкнуться с тайм-аутами клиента, прокси и сервера. Отдельная задача в очереди с task_id, сохранённым состоянием и проверкой статуса часто надёжнее долгого HTTP-запроса. Это не то же самое, что просто объявить обработчик async: асинхронный синтаксис не обеспечивает сохранение и восстановление задания.

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

• FastAPI: синхронный вызов для быстрых задач.
• Длинные задачи: очередь + task_id + опрос статуса.
• Синхронный вызов не подходит для минутных задач.
• Асинхронный паттерн улучшает пользовательский опыт.

1. Клиент -> POST /run (запрос)
2. Сервер: запустить граф
3. Сервер -> Клиент: результат (синхронно)
4. Клиент -> POST /run (запрос)
5. Сервер: поставить в очередь, вернуть task_id
6. Клиент -> GET /status/{task_id}
7. Сервер -> Клиент: статус и результат

Стриминг против сохраненного результата

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

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

Стриминг — это способ доставки, а не хранения. Используйте оба механизма: стриминг для интерактивности, сохранение для надежности.

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

Конкуренция, backpressure и отмена

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

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

Отмена (cancellation) — возможность остановить выполнение задачи. Если клиент отменил запрос или задача превысила лимит времени, агент должен остановиться. Реализуйте механизм отмены через проверку флага в узлах графа.

• Конкуренция: сколько запросов обрабатывать одновременно.
• Backpressure: защита от перегрузки.
• Отмена: остановка выполнения задачи.
• Проверяйте флаг отмены в узлах графа.

Журналирование без утечки данных

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

Логи могут содержать чувствительные данные: персональную информацию, ключи, тексты писем. Поэтому перед записью в лог применяйте редактирование (redaction): заменяйте чувствительные значения на маски.

Наблюдаемость должна быть встроена в harness, а не добавлена постфактум. Используйте структурированное логирование и трейсинг.

• Логируйте вызовы инструментов и переходы.
• Логируйте использование токенов.
• Редактируйте чувствительные данные в логах.
• Наблюдаемость должна быть встроена в harness.

• Логируйте каждый вызов инструмента с параметрами и результатом.
• Логируйте переходы между узлами графа.
• Маскируйте персональные данные и ключи в логах.
• Настройте трейсинг для анализа end-to-end.

Метрики и оценки: precision, recall, pass@k

Для оценки качества агента используйте метрики. Precision (точность) — доля правильных положительных предсказаний среди всех предсказанных положительных. Recall (полнота) — доля правильных положительных среди всех истинных положительных. F1 — гармоническое среднее.

pass@k — вероятность того, что хотя бы один из k запусков агента даст правильный результат. Это полезно для задач, где достаточно одного успешного решения (например, генерация кода).

Метрики имеют ограничения. Precision и recall не учитывают стоимость ошибок. pass@k не учитывает качество частичных решений. Интерпретируйте метрики в контексте задачи.

• Precision: точность положительных предсказаний.
• Recall: полнота положительных предсказаний.
• F1: гармоническое среднее precision и recall.
• pass@k: вероятность успеха хотя бы одного из k запусков.
• Интерпретируйте метрики в контексте задачи.

Задержка, стоимость и токены

Каждый вызов LLM имеет стоимость и задержку. Оптимизация промптов (сокращение токенов) снижает стоимость и ускоряет ответ. Используйте few-shot примеры экономно, удаляйте нерелевантный контекст.

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

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

• Каждый вызов LLM имеет стоимость и задержку.
• Оптимизация промптов снижает стоимость.
• Отслеживайте использование токенов.
• Маршрутизация: простая модель для простых задач.

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

Успех агента определяется не количеством вызовов инструментов, а качеством результата. Задача решена — агент успешен. Задача не решена, даже если агент сделал 100 вызовов, — провал.

Определите критерии приемки для каждой задачи. Например, для задачи «ответить на вопрос о статусе заказа» критерий — правильный статус и дата. Для задачи «сформировать отчет» — наличие всех разделов и корректность данных.

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

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

Ограниченный пилот и разбор отказа

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

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

Разбор отказа (failure walkthrough) — это анализ инцидента: что произошло, почему, как предотвратить. Используйте логи и трейсинг для восстановления последовательности событий.

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