# 1. Docker-контейнеризация AI-агента

Первый шаг к продакшену — упаковка агента в Docker-контейнер. Это гарантирует, что ваш код будет работать одинаково на локальной машине разработчика, staging-сервере и в Kubernetes-кластере. В контейнер помещается не только сам Python-код агента, но и все зависимости, системные библиотеки и переменные окружения. Docker-образ становится атомарной единицей деплоя, которую можно версионировать, откатывать и переиспользовать между средами.

Ключевой принцип: multi-stage build. На первом этапе (builder) мы устанавливаем зависимости и компилируем всё необходимое, а на втором (runtime) копируем только артефакты и код. Это уменьшает финальный размер образа и сокращает поверхность атаки — в рантайме не нужны компиляторы и dev-заголовки.

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

# Dockerfile — мультистейдж-сборка AI-агента
FROM python:3.12-slim-bookworm AS builder

# Системные зависимости для сборки
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc libpq-dev && rm -rf /var/lib/apt/lists/*

WORKDIR /build
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# === Рантайм-образ ===
FROM python:3.12-slim-bookworm AS runtime

# Только рантайм-зависимости (без компиляторов)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 ca-certificates && rm -rf /var/lib/apt/lists/*

# Создаём непривилегированного пользователя
RUN useradd --create-home --shell /bin/bash appuser

# Копируем установленные пакеты из builder-стадии
COPY --from=builder /root/.local /home/appuser/.local

WORKDIR /app
COPY --chown=appuser:appuser . .

# Переключаемся на непривилегированного пользователя
USER appuser

# Добавляем локальные пакеты в PATH
ENV PATH="/home/appuser/.local/bin:${PATH}"

# Healthcheck — проверка живости агента
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

EXPOSE 8000
CMD ["uvicorn", "agent.main:app", "--host", "0.0.0.0", "--port", "8000"]

Для локальной разработки и staging-окружений удобно использовать docker-compose. Он позволяет поднять агента вместе со всеми зависимыми сервисами (Redis для очередей, Postgres для хранения состояния) одной командой. Ниже — минимальный compose-файл, готовый к использованию.

# docker-compose.yml
version: "3.9"

services:
  agent:
    build: .
    container_name: ai-agent-prod
    ports:
      - "8000:8000"
    env_file:
      - .env.production
    environment:
      - REDIS_URL=redis://redis:6379/0
      - DATABASE_URL=postgresql://agent:secret@postgres:5432/agent_db
      - LOG_LEVEL=INFO
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: agent
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: agent_db
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U agent"]
      interval: 10s

volumes:
  pgdata:

# 2. Продакшен-деплой через Docker + systemd

Не каждому проекту с порога нужен Kubernetes. Для многих команд идеальным первым шагом в продакшен будет связка Docker + systemd на одном или нескольких VPS. systemd управляет жизненным циклом контейнера: запуск при старте системы, автоматический перезапуск при падении, сбор логов через journald и лимиты по CPU/памяти.

Преимущества systemd перед docker-compose в продакшене: нативный менеджер процессов ОС, единый механизм логирования (journalctl), интеграция с системами мониторинга хоста, возможность задать жесткие лимиты ресурсов через cgroups. Ниже — готовый unit-файл, который можно разместить в /etc/systemd/system/ai-agent.service.

# /etc/systemd/system/ai-agent.service
[Unit]
Description=AI Agent Production Service
After=docker.service network-online.target
Requires=docker.service
Wants=network-online.target

[Service]
Type=notify
NotifyAccess=all
Restart=always
RestartSec=10
TimeoutStartSec=60
TimeoutStopSec=30

# Лимиты ресурсов (cgroups v2)
MemoryMax=2G
CPUQuota=200%

# Запуск Docker-контейнера
ExecStartPre=-/usr/bin/docker stop ai-agent-prod
ExecStartPre=-/usr/bin/docker rm ai-agent-prod
ExecStartPre=/usr/bin/docker pull registry.example.com/ai-agent:latest
ExecStart=/usr/bin/docker run \
  --name ai-agent-prod \
  --env-file /opt/ai-agent/.env.production \
  -p 8000:8000 \
  --memory=2g --cpus=2 \
  --health-cmd="curl -f http://localhost:8000/health || exit 1" \
  --health-interval=30s --health-timeout=5s --health-retries=3 \
  registry.example.com/ai-agent:latest

ExecStop=/usr/bin/docker stop -t 30 ai-agent-prod
ExecStopPost=/usr/bin/docker rm ai-agent-prod

# Безопасность
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/log/ai-agent

[Install]
WantedBy=multi-user.target

После создания unit-файла активируем его стандартными командами systemd. Сервис будет автоматически запускаться при загрузке сервера и перезапускаться при любых сбоях.

# Активация сервиса
sudo systemctl daemon-reload
sudo systemctl enable ai-agent.service
sudo systemctl start ai-agent.service

# Просмотр статуса и логов
sudo systemctl status ai-agent
sudo journalctl -u ai-agent -f --no-pager

# 3. Мониторинг с LangSmith и Prometheus

AI-агент в продакшене — это чёрный ящик, если вы не настроили наблюдаемость. Вам нужно видеть: сколько токенов расходует каждый вызов, какова задержка ответа, какие инструменты вызываются чаще всего и где происходят ошибки. Для этого мы используем связку LangSmith (трассировка цепочек LLM-вызовов) и Prometheus (системные и бизнес-метрики).

LangSmith автоматически перехватывает все вызовы LangChain/LangGraph и строит дерево выполнения: от входного промпта до финального ответа, включая все промежуточные вызовы инструментов. Вы видите, на каком шаге агент «задумался» дольше обычного, какой тул вернул ошибку и сколько токенов ушло на каждый этап. Prometheus, в свою очередь, собирает числовые метрики — latency, throughput, error rate — которые нужны для алертов и дашбордов.

# agent/monitoring.py — настройка трассировки и метрик
import os
import time
from prometheus_client import Counter, Histogram, Gauge, generate_latest
from langsmith import Client, traceable

# === LangSmith клиент ===
langsmith_client = Client(api_key=os.getenv("LANGSMITH_API_KEY"))

# === Prometheus метрики ===
agent_requests_total = Counter(
    "agent_requests_total",
    "Общее количество запросов к агенту",
    ["status", "agent_type"]
)

agent_latency_seconds = Histogram(
    "agent_request_duration_seconds",
    "Время обработки запроса в секундах",
    buckets=[0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0]
)

agent_tokens_used = Counter(
    "agent_tokens_used_total",
    "Общее количество использованных токенов",
    ["direction"]  # input или output
)

agent_active_requests = Gauge(
    "agent_active_requests",
    "Количество запросов в обработке прямо сейчас"
)

tool_call_counter = Counter(
    "agent_tool_calls_total",
    "Вызовы инструментов по названиям",
    ["tool_name", "status"]
)

# === Декоратор для трассировки выполнения агента ===
@traceable(run_type="chain", name="agent-execute")
async def execute_agent(query: str, agent_type: str = "default") -> dict:
    """Выполнить запрос агентом с полным мониторингом."""
    agent_active_requests.inc()
    start_time = time.monotonic()
    
    try:
        # ... логика вызова агента и LLM ...
        result = {"answer": "...", "tokens_input": 150, "tokens_output": 80}
        
        agent_requests_total.labels(status="success", agent_type=agent_type).inc()
        agent_tokens_used.labels(direction="input").inc(result["tokens_input"])
        agent_tokens_used.labels(direction="output").inc(result["tokens_output"])
        
        return result
    except Exception as e:
        agent_requests_total.labels(status="error", agent_type=agent_type).inc()
        raise
    finally:
        duration = time.monotonic() - start_time
        agent_latency_seconds.observe(duration)
        agent_active_requests.dec()

В FastAPI-приложении добавляем эндпоинт /metrics для сбора метрик Prometheus. Также настраиваем переменные окружения для LangSmith — трассировка включится автоматически для всех вызовов LangChain.

# agent/main.py — FastAPI с метриками
from fastapi import FastAPI, Response
from agent.monitoring import generate_latest, execute_agent

app = FastAPI(title="AI Agent API", version="1.0.0")

@app.get("/metrics")
def metrics():
    return Response(content=generate_latest(), media_type="text/plain")

@app.get("/health")
def health():
    return {"status": "healthy", "timestamp": time.time()}

@app.post("/agent/run")
async def run_agent(query: str):
    result = await execute_agent(query)
    return result

Для Prometheus настраиваем сбор метрик с нашего эндпоинта каждые 15 секунд:

# prometheus.yml (фрагмент scrape_configs)
scrape_configs:
  - job_name: "ai-agent"
    scrape_interval: 15s
    static_configs:
      - targets: ["ai-agent-prod:8000"]
    metrics_path: /metrics

# 4. Масштабирование: Kubernetes + HPA

Когда одиночный сервер перестаёт справляться с нагрузкой, пора переезжать на Kubernetes. Оркестратор берёт на себя распределение подов по нодам, автоматический рестарт упавших контейнеров и — что самое важное — горизонтальное масштабирование через Horizontal Pod Autoscaler (HPA). Агенты масштабируются отлично, потому что каждый запрос к LLM не зависит от других — это идеальный stateless-ворклоад.

При проектировании Kubernetes-деплоя учитывайте специфику AI-ворклоадов. В отличие от классических веб-приложений, агенты могут удерживать соединение с LLM-провайдером десятки секунд, потребляя при этом минимальные ресурсы CPU, но значительный объём памяти под контекст диалога. Это означает, что скейлинг по CPU не всегда отражает реальную нагрузку — рассмотрите кастомные метрики на основе количества активных запросов к LLM. Также критически важно настроить правильные таймауты: если агент ждёт ответа от LLM дольше определённого порога, Kubernetes должен иметь возможность перезапустить под, не теряя незавершённые запросы благодаря механизму graceful shutdown.

Ниже — полноценный Kubernetes-манифест: Deployment (с ресурсами, пробами и стратегией обновления), Service (для внутренней маршрутизации) и HPA (автоскейлинг по CPU и кастомным метрикам). Всё готово к применению через kubectl apply.

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-agent
  labels:
    app: ai-agent
spec:
  replicas: 2
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: ai-agent
  template:
    metadata:
      labels:
        app: ai-agent
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "8000"
        prometheus.io/path: "/metrics"
    spec:
      serviceAccountName: ai-agent-sa
      containers:
        - name: agent
          image: registry.example.com/ai-agent:v1.2.3
          ports:
            - containerPort: 8000
              name: http
          envFrom:
            - secretRef:
                name: ai-agent-secrets
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              cpu: "2"
              memory: "2Gi"
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 15
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 5

# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: ai-agent-svc
spec:
  type: ClusterIP
  selector:
    app: ai-agent
  ports:
    - port: 80
      targetPort: 8000
      name: http

# k8s/hpa.yaml — горизонтальное масштабирование
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: ai-agent-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: ai-agent
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 50
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 30
        - type: Pods
          value: 2
          periodSeconds: 30
      selectPolicy: Max

# 5. Безопасность: API-ключи, sandbox, rate limiting

Безопасность AI-агента в продакшене — это многослойная защита. На внешнем периметре — API Gateway с аутентификацией и рейт-лимитами. Внутри контейнера — изоляция через sandbox для выполнения сгенерированного кода. На уровне secrets — инжект API-ключей через Kubernetes Secrets или HashiCorp Vault, но никогда не через переменные окружения в коде или Dockerfile.

Особая боль AI-агентов — инъекции через промпты (prompt injection). Злоумышленник может попытаться заставить агента выполнить произвольный код, раскрыть системный промпт или эксфильтровать данные. Защита здесь — это комбинация изоляции выполнения (sandbox) и строгой валидации выходных данных агента перед тем, как они попадут в вызываемые инструменты.

Отдельно стоит упомянуть защиту от утечки данных через LLM. Никогда не отправляйте чувствительные данные пользователя в промпт без предварительной очистки и маскирования. Используйте прокси-слой между агентом и LLM-провайдером, который фильтрует PII (персональные данные), ключи доступа и внутренние идентификаторы. Для OpenAI и Anthropic настройте политики хранения данных — отключите использование ваших запросов для обучения моделей через соответствующие флаги API. Помните: каждый вызов LLM потенциально может логироваться на стороне провайдера.

# agent/security.py — песочница и защита
import subprocess
import tempfile
import os
import resource
from slowapi import Limiter
from slowapi.util import get_remote_address

# === Rate Limiter (Redis-backed) ===
limiter = Limiter(key_func=get_remote_address, default_limits=["100/minute"])

def set_resource_limits():
    """Ограничения CPU/памяти для дочерних процессов."""
    # 512 MB памяти, 10 секунд CPU-времени
    resource.setrlimit(resource.RLIMIT_AS, (512 * 1024 * 1024, -1))
    resource.setrlimit(resource.RLIMIT_CPU, (10, 10))

def execute_in_sandbox(code: str, timeout: int = 5) -> dict:
    """Выполнить Python-код в изолированной песочнице."""
    with tempfile.TemporaryDirectory() as tmpdir:
        script_path = os.path.join(tmpdir, "script.py")
        with open(script_path, "w") as f:
            f.write(code)
        
        try:
            result = subprocess.run(
                ["python3", "-I", script_path],    # -I = изолированный режим
                capture_output=True,
                text=True,
                timeout=timeout,
                preexec_fn=set_resource_limits,   # лимиты до выполнения
                cwd=tmpdir,
                env={"PATH": "/usr/bin"}         # чистый env
            )
            return {
                "stdout": result.stdout[:10000],
                "stderr": result.stderr[:5000],
                "exit_code": result.returncode
            }
        except subprocess.TimeoutExpired:
            return {"error": "execution_timeout", "exit_code": -1}

Управление секретами через Kubernetes Secrets — это минимальный стандарт. Ниже — создание секрета и монтирование его в под:

# Создание Kubernetes Secret из файла .env.production
kubectl create secret generic ai-agent-secrets \
  --from-env-file=.env.production \
  --namespace=production

# Хранение секретов в Vault (рекомендуемый подход)
vault kv put secret/ai-agent/production \
  OPENAI_API_KEY="sk-..." \
  LANGSMITH_API_KEY="lsv2_..." \
  DATABASE_URL="postgresql://..."

# 6. Логирование и алертинг

В продакшене логи — это не просто print(), а структурированные JSON-записи, которые парсятся системами агрегации (Loki, ELK) и служат основой для алертов. Каждая запись должна содержать: timestamp, уровень (INFO/WARN/ERROR), идентификатор трейса для корреляции с LangSmith, идентификатор запроса и контекстную информацию. Никаких многострочных трейсбеков как plain text — только сериализованные структуры.

# agent/logging_config.py — структурированное логирование
import logging
import json
import sys
import uuid
from datetime import datetime, timezone
from contextvars import ContextVar

request_id_var: ContextVar[str] = ContextVar("request_id", default="")
trace_id_var: ContextVar[str] = ContextVar("trace_id", default="")

class JSONFormatter(logging.Formatter):
    """Форматирует логи в JSON для Loki/ELK."""
    def format(self, record: logging.LogRecord) -> str:
        log_entry = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
            "request_id": request_id_var.get(),
            "trace_id": trace_id_var.get(),
            "module": record.module,
            "function": record.funcName,
        }
        if record.exc_info and record.exc_info[1]:
            log_entry["exception"] = {
                "type": type(record.exc_info[1]).__name__,
                "message": str(record.exc_info[1]),
            }
        return json.dumps(log_entry, ensure_ascii=False)

def setup_logging(level: str = "INFO") -> None:
    handler = logging.StreamHandler(sys.stdout)
    handler.setFormatter(JSONFormatter())
    root = logging.getLogger()
    root.setLevel(getattr(logging, level.upper()))
    root.handlers = [handler]

Алертинг настраивается в Prometheus Alertmanager. Правила покрывают три критических сценария: высокая частота ошибок, рост задержки выше порога и аномальный расход токенов (признак потенциальной атаки или бесконечного цикла агента).

# prometheus-rules.yaml — правила алертинга
groups:
  - name: ai-agent-alerts
    rules:
      # Алерт: высокая частота ошибок
      - alert: AgentHighErrorRate
        expr: |
          rate(agent_requests_total{status="error"}[5m])
          / rate(agent_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: critical
          channel: slack-alerts
        annotations:
          summary: "Error rate > 5% for 5 minutes"
          description: "Current: {{ $value | humanizePercentage }}"

      # Алерт: высокая задержка (P95)
      - alert: AgentHighLatency
        expr: |
          histogram_quantile(0.95,
            rate(agent_request_duration_seconds_bucket[5m])) > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "P95 latency > 10s"

      # Алерт: аномальный расход токенов
      - alert: AgentTokenSpendingSpike
        expr: |
          rate(agent_tokens_used_total[15m]) > 100000
        for: 15m
        labels:
          severity: critical
        annotations:
          summary: "Token spending spike detected"

      # Алерт: нет активных подов
      - alert: AgentNoPodsRunning
        expr: |
          kube_deployment_status_replicas_available{
            deployment="ai-agent"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "No AI agent pods are running!"

# 7. Чеклист продакшен-готовности

Перед тем как нажать кнопку «деплой» и направить реальный трафик на вашего AI-агента, пройдитесь по этому чеклисту. Каждый пункт — это урок, выученный на чьих-то продакшен-инцидентах. Пропуск любого из них рано или поздно приведёт к инциденту.

1. Healthcheck работает и проверяет реальную готовность. Не просто «порт открыт», а полная проверка: доступность LLM API, Redis, базы данных. Если healthcheck падает — Kubernetes перезапустит под.
2. Все секреты вынесены в Kubernetes Secrets или Vault. Проверьте kubectl get secrets — все ли ключи там? Ни одного хардкода в коде или конфигах.
3. Rate limiting включён на всех уровнях. API Gateway (100 req/min на пользователя), агент (макс 5 одновременных LLM-вызовов), внешние API (соблюдение лимитов провайдера).
4. Логи пишутся в JSON на stdout и собираются в Loki. Никаких файлов внутри контейнера — только stdout/stderr. JSON-формат обязателен для парсинга.
5. Трассировка LangSmith включена для 100% запросов. Вы должны видеть полное дерево вызовов для каждого запроса. Sampling включайте только при огромных объёмах.
6. Алерты настроены и протестированы. Отправьте тестовый запрос с ошибкой — пришёл ли алерт в Slack? Все члены команды знают, где лежит runbook?
7. Настроен Graceful Shutdown. При SIGTERM агент должен: перестать принимать новые запросы, завершить текущие (с таймаутом), закрыть соединения с БД. Таймаут terminationGracePeriodSeconds в Kubernetes — минимум 30 секунд.
8. Лимиты ресурсов заданы и проверены. Без limits один «плохой» запрос может занять всю память ноды. Начните с 512Mi/0.5 CPU на под и корректируйте по метрикам.
9. HPA протестирован под нагрузкой. Запустите стресс-тест (например, через Locust) и убедитесь, что поды масштабируются, а после спада нагрузки — схлопываются обратно.
10. Есть план отката. Храните минимум 3 последних образа в registry. Деплой-стратегия RollingUpdate с maxUnavailable=0. Команда kubectl rollout undo должна быть отрепетирована.