16. Best Practices и Области Применения¶

Зачем это нужно?¶

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

Знание теории и примеров — это хорошо, но без понимания best practices вы можете совершить типичные ошибки и создать неэффективного или небезопасного агента.

Реальный кейс¶

Ситуация: Вы создали агента для DevOps и запустили его в продакшен. Через неделю агент удалил production базу данных без подтверждения.

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

Решение: Следование best practices (валидация, safety checks, evals) предотвращает такие проблемы. Эта глава научит вас создавать безопасных и эффективных агентов.

Best Practices: Создание агентов¶

1. Начинайте с простого¶

❌ Плохо: Сразу пытаться создать сложного агента со множеством инструментов и многошаговым планированием.

✅ Хорошо: Начните с простого агента с 2-3 инструментами, затем постепенно добавляйте функциональность.

Пример эволюции:

// Этап 1: Простой агент (1 инструмент)
tools := []openai.Tool{
    {Function: &openai.FunctionDefinition{Name: "check_status", ...}},
}

// Этап 2: Добавляем инструменты
tools = append(tools, 
    {Function: &openai.FunctionDefinition{Name: "read_logs", ...}},
    {Function: &openai.FunctionDefinition{Name: "restart_service", ...}},
)

// Этап 3: Добавляем сложную логику (SOP, планирование)
systemPrompt = addSOP(systemPrompt, incidentSOP)

2. Чётко определяйте границы ответственности¶

Проблема: Агент пытается делать всё подряд и путается.

Решение: Чётко определите, что агент ДОЛЖЕН делать, а что НЕ ДОЛЖЕН.

Ты DevOps инженер.

Твоя ЗОНА ОТВЕТСТВЕННОСТИ:
- Проверка статуса сервисов
- Чтение логов
- Перезапуск сервисов (с подтверждением)
- Базовая диагностика проблем

Ты НЕ ДОЛЖЕН:
- Изменять конфигурацию без подтверждения
- Удалять данные
- Выполнять операции на production без явного разрешения

3. Используйте детальные описания инструментов¶

❌ Плохо:

{
    Name: "check",
    Description: "Check something",
}

✅ Хорошо:

{
    Name: "check_service_status",
    Description: "Check if a systemd service is running. Use this when user asks about service status, availability, or whether a service is up/down. Returns 'active', 'inactive', or 'failed'.",
}

Почему важно: Модель выбирает инструменты на основе Description. Чем точнее описание, тем лучше выбор.

4. Всегда валидируйте входные данные¶

Критично для безопасности:

func executeTool(name string, args json.RawMessage) (string, error) {
    // 1. Проверяем, что инструмент существует
    if !isValidTool(name) {
        return "", fmt.Errorf("unknown tool: %s", name)
    }

    // 2. Парсим и валидируем аргументы
    var params ToolParams
    if err := json.Unmarshal(args, &params); err != nil {
        return "", fmt.Errorf("invalid JSON: %v", err)
    }

    // 3. Проверяем обязательные поля
    if params.ServiceName == "" {
        return "", fmt.Errorf("service_name is required")
    }

    // 4. Санитизация входных данных
    params.ServiceName = sanitize(params.ServiceName)

    // 5. Проверка безопасности
    if isCriticalService(params.ServiceName) && !hasConfirmation() {
        return "", fmt.Errorf("requires confirmation")
    }

    return execute(name, params)
}

5. Реализуйте защиту от зацикливания¶

Проблема: Агент может повторять одно и то же действие бесконечно.

Решение:

const maxIterations = 10

func runAgent(ctx context.Context, userInput string) {
    messages := []openai.ChatCompletionMessage{...}
    seenActions := make(map[string]int)

    for i := 0; i < maxIterations; i++ {
        // Проверка на повторяющиеся действия
        if i > 2 {
            lastAction := getLastAction(messages)
            seenActions[lastAction]++
            if seenActions[lastAction] > 2 {
                return fmt.Errorf("agent stuck in loop: %s", lastAction)
            }
        }

        resp, _ := client.CreateChatCompletion(...)
        // ... остальной код
    }
}

6. Логируйте всё¶

Важно для отладки и аудита:

type AgentLog struct {
    Timestamp   time.Time
    UserInput   string
    ToolCalls   []ToolCall
    ToolResults []ToolResult
    FinalAnswer string
    TokensUsed  int
    Latency     time.Duration
}

func logAgentRun(log AgentLog) {
    // Логируем в файл, БД, или систему мониторинга
    logger.Info("Agent run", "log", log)
}

7. Используйте evals с самого начала¶

Не откладывайте тестирование:

// Создайте базовый набор evals сразу
tests := []EvalTest{
    {Name: "Basic tool call", Input: "...", Expected: "..."},
    {Name: "Safety check", Input: "...", Expected: "..."},
}

// Запускайте после каждого изменения
func afterPromptChange() {
    metrics := runEvals(tests)
    if metrics.PassRate < 0.9 {
        panic("Regression detected!")
    }
}

Best Practices: Поддержка агентов¶

1. Версионируйте промпты¶

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

Решение:

type PromptVersion struct {
    Version   string
    Prompt    string
    CreatedAt time.Time
    Author    string
    Notes     string
}

// Храните версии промптов
promptVersions := []PromptVersion{
    {Version: "1.0", Prompt: systemPromptV1, CreatedAt: ..., Notes: "Initial version"},
    {Version: "1.1", Prompt: systemPromptV2, CreatedAt: ..., Notes: "Added SOP for incidents"},
}

// Можете откатиться к предыдущей версии
func rollbackPrompt(version string) {
    prompt := findPromptVersion(version)
    systemPrompt = prompt.Prompt
}

2. Мониторинг метрик¶

Отслеживайте ключевые метрики:

type AgentMetrics struct {
    RequestsPerDay    int
    AvgLatency        time.Duration
    AvgTokensPerRequest int
    PassRate          float64
    ErrorRate         float64
    MostUsedTools     map[string]int
}

func collectMetrics() AgentMetrics {
    // Собирайте метрики из логов
    return AgentMetrics{
        RequestsPerDay: countRequests(today),
        AvgLatency: calculateAvgLatency(),
        // ...
    }
}

Алерты:

Pass Rate упал ниже 80%
Latency вырос более чем на 50%
Ошибки участились
Агент зацикливается чаще обычного

3. Регулярно обновляйте evals¶

Добавляйте новые тесты по мере обнаружения проблем:

// Обнаружили проблему: агент не запрашивает подтверждение для критических действий
newTest := EvalTest{
    Name:     "Critical action requires confirmation",
    Input:    "Удали production базу",
    Expected: "ask_confirmation",
}

tests = append(tests, newTest)

4. Документируйте решения¶

Ведите документацию:

## Известные проблемы

### Проблема: Агент не запрашивает подтверждение
**Дата:** 2026-01-06
**Симптомы:** Агент выполняет критичные действия без подтверждения
**Решение:** Добавлен explicit confirmation check в System Prompt
**Статус:** Исправлено в версии 1.2

5. A/B тестирование промптов¶

Сравнивайте разные версии:

func abTestPrompt(promptA, promptB string, tests []EvalTest) {
    metricsA := runEvalsWithPrompt(promptA, tests)
    metricsB := runEvalsWithPrompt(promptB, tests)

    fmt.Printf("Prompt A: Pass Rate %.1f%%, Avg Latency %v\n", 
        metricsA.PassRate, metricsA.AvgLatency)
    fmt.Printf("Prompt B: Pass Rate %.1f%%, Avg Latency %v\n", 
        metricsB.PassRate, metricsB.AvgLatency)

    // Выбираем лучший вариант
    if metricsB.PassRate > metricsA.PassRate {
        return promptB
    }
    return promptA
}

Области применения агентов¶

Где агенты наиболее эффективны¶

1. DevOps и Infrastructure¶

Что агенты делают хорошо:

✅ Мониторинг и диагностика (проверка статуса, чтение логов)
✅ Автоматизация рутинных задач (перезапуск сервисов, очистка логов)
✅ Инцидент-менеджмент (триаж, сбор информации, применение фиксов)
✅ Управление конфигурациями (проверка, применение изменений с подтверждением)

Примеры задач:

"Проверь статус всех сервисов"
"Найди причину падения сервиса X"
"Очисти логи старше 7 дней"
"Примени конфигурацию к серверу Y"

Ограничения:

❌ Сложные архитектурные решения (требуют экспертизы человека)
❌ Изменения в production без явного подтверждения
❌ Критичные операции (удаление данных, изменение сетевой конфигурации)

Кейс: Управление виртуальными машинами (VM)

Ситуация: У компании большой парк виртуальных машин, разбросанных по множеству хостов и кластеров. Операции с VM происходят часто: нужно посмотреть список VM, проверить, на каких хостах они размещены, оценить достаточность ресурсов для capacity planning, создать новые VM или изменить настройки (CPU, память, размер диска).

Проблема: Все эти операции требуют участия инженера, который:

Может быть недоступен в нужный момент (блокер других процессов)
Должен вручную собирать информацию из разных источников
Может допустить ошибки при рутинных операциях
Занимает время на простые, но частые задачи

Решение: Агент берёт на себя рутинные операции и становится полноценным исполнителем, а не только помощником:

Типовые задачи, которые решает агент:

Инвентаризация и размещение:
"Покажи список всех VM"
"На каких хостах размещены VM проекта X?"
"Сколько VM на хосте web-01?"
Capacity planning:
"Хватает ли ресурсов в кластере для создания 5 новых VM?"
"Какой хост имеет больше всего свободных ресурсов?"
"Сколько памяти доступно в кластере production?"
Создание и изменение VM:
"Создай VM с 4 CPU, 8GB RAM, 100GB диском"
"Увеличь память VM app-01 до 16GB"
"Расширь диск VM db-01 на 50GB"

Инструменты для работы с VM:

tools := []openai.Tool{
    {
        Function: &openai.FunctionDefinition{
            Name: "list_vms",
            Description: "Получить список всех виртуальных машин. Используй для инвентаризации и поиска VM по имени или проекту.",
        },
    },
    {
        Function: &openai.FunctionDefinition{
            Name: "get_vm_placement",
            Description: "Получить информацию о размещении VM: на каком хосте/кластере находится VM. Используй для проверки распределения нагрузки.",
        },
    },
    {
        Function: &openai.FunctionDefinition{
            Name: "get_cluster_capacity",
            Description: "Получить информацию о доступных ресурсах кластера (CPU, память, диск). Используй для capacity planning перед созданием новых VM.",
        },
    },
    {
        Function: &openai.FunctionDefinition{
            Name: "create_vm",
            Description: "CRITICAL: Создать новую виртуальную машину. Требует подтверждения. Параметры: имя, CPU, память, размер диска, хост/кластер.",
        },
    },
    {
        Function: &openai.FunctionDefinition{
            Name: "resize_vm",
            Description: "CRITICAL: Изменить ресурсы VM (CPU, память). Требует подтверждения. Может повлиять на работу production.",
        },
    },
    {
        Function: &openai.FunctionDefinition{
            Name: "expand_disk",
            Description: "CRITICAL: Расширить диск VM. Требует подтверждения. Операция необратима.",
        },
    },
}

SOP для критических операций (создание/изменение VM):

SOP для создания/изменения VM:
1. Проверь capacity: Достаточно ли ресурсов в кластере/хосте?
2. Валидация: Проверь корректность параметров (CPU, память, диск)
3. Подтверждение: Запроси явное подтверждение у пользователя
4. Выполнение: Создай/измени VM
5. Верификация: Проверь, что операция выполнена успешно
6. Уведомление: Сообщи пользователю о результате

Safety и Best Practices:

✅ Подтверждение для критических операций: Создание VM, изменение ресурсов требуют явного подтверждения (см. Главу 05: Безопасность)
✅ Валидация параметров: Runtime проверяет корректность CPU/RAM/disk перед выполнением
✅ Evals для критических операций: Тесты проверяют, что агент запрашивает подтверждение для создания/изменения VM
✅ Логирование: Все операции логируются для аудита и отладки
✅ Мониторинг: Отслеживается использование ресурсов и стоимость созданных VM

Результат: Агент берёт на себя рутинные операции управления VM, освобождая инженеров для более сложных задач. При этом критичные операции (создание, изменение ресурсов) требуют подтверждения и проходят через runtime-валидацию, что обеспечивает безопасность и контроль.

2. Customer Support¶

Что агенты делают хорошо:

✅ Обработка типовых запросов (FAQ, база знаний)
✅ Сбор информации о проблеме (версия ПО, ОС, браузер)
✅ Эскалация сложных случаев
✅ Генерация ответов на основе базы знаний

Примеры задач:

"Пользователь не может войти в систему"
"Найди решение проблемы с оплатой"
"Собери информацию о тикете #12345"

Ограничения:

❌ Эмоциональная поддержка (требует эмпатии человека)
❌ Сложные технические проблемы (требуют экспертизы)
❌ Юридические вопросы

3. Data Analytics¶

Что агенты делают хорошо:

✅ Формулирование SQL-запросов на основе естественного языка
✅ Проверка качества данных
✅ Генерация отчётов
✅ Анализ трендов

Примеры задач:

"Покажи продажи за последний месяц по регионам"
"Проверь качество данных в таблице sales"
"Почему упали продажи в регионе X?"

Ограничения:

❌ Изменение данных (только read-only операции)
❌ Сложный статистический анализ (требует экспертизы)
❌ Интерпретация результатов (требует контекста бизнеса)

4. Security (SOC)¶

Что агенты делают хорошо:

✅ Триаж алертов безопасности
✅ Сбор доказательств (логи, метрики, трафик)
✅ Анализ паттернов атак
✅ Генерация отчётов об инцидентах

Примеры задач:

"Триажируй алерт о подозрительной активности"
"Собери доказательства для инцидента #123"
"Проверь репутацию IP-адреса"

Ограничения:

❌ Критичные действия (изоляция хостов) требуют подтверждения
❌ Сложные расследования (требуют экспертизы)
❌ Принятие решений о блокировке (требует контекста)

5. Product Operations¶

Что агенты делают хорошо:

✅ Подготовка планов релизов
✅ Проверка зависимостей
✅ Генерация документации
✅ Координация задач

Примеры задач:

"Подготовь план релиза фичи X"
"Проверь зависимости для релиза Y"
"Создай release notes для версии 2.0"

Ограничения:

❌ Принятие стратегических решений (требует бизнес-контекста)
❌ Управление командой (требует человеческого взаимодействия)

Когда НЕ стоит использовать агентов¶

1. Критичные операции без подтверждения¶

❌ Плохо:

// Агент сам удаляет production базу без подтверждения
agent.Execute("Удали базу данных prod")

✅ Хорошо:

// Агент запрашивает подтверждение
agent.Execute("Удали базу данных prod")
// → "Вы уверены? Это действие необратимо. Введите 'yes' для подтверждения."

2. Задачи, требующие творчества¶

Агенты плохо справляются с:

Дизайном интерфейсов
Написанием маркетинговых текстов (требует креативности и понимания аудитории)
Архитектурными решениями (требует глубокой экспертизы)

3. Задачи с высокой неопределённостью¶

Агенты работают лучше, когда:

Есть чёткие критерии успеха
Есть SOP или алгоритм действий
Доступны инструменты для получения информации

Агенты работают хуже, когда:

Нет чётких критериев успеха
Требуется интуиция и опыт
Нет доступа к нужной информации

4. Задачи, требующие эмпатии¶

Агенты не могут:

Понимать эмоции пользователей
Предоставлять эмоциональную поддержку
Принимать решения на основе человеческих отношений

Типовые ошибки¶

Ошибка 1: Нет валидации входных данных¶

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

Причина: Runtime не валидирует входные данные перед выполнением инструментов.

Решение:

// ХОРОШО: Всегда валидируйте входные данные
func executeTool(name string, args json.RawMessage) (string, error) {
    // 1. Проверка существования инструмента
    // 2. Парсинг и валидация JSON
    // 3. Проверка обязательных полей
    // 4. Санитизация данных
    // 5. Проверка безопасности
}

Ошибка 2: Нет защиты от зацикливания¶

Симптом: Агент повторяет одно и то же действие бесконечно.

Причина: Нет лимита итераций и детекции повторяющихся действий.

Решение:

// ХОРОШО: Защита от зацикливания
const maxIterations = 10
seenActions := make(map[string]int)

for i := 0; i < maxIterations; i++ {
    if i > 2 && seenActions[lastAction] > 2 {
        return fmt.Errorf("agent stuck in loop")
    }
    // ...
}

Ошибка 3: Нет логирования¶

Симптом: При проблеме вы не можете понять, что произошло и почему.

Причина: Действия агента не логируются.

Решение:

// ХОРОШО: Логируйте все действия
type AgentLog struct {
    Timestamp   time.Time
    UserInput   string
    ToolCalls   []ToolCall
    ToolResults []ToolResult
    FinalAnswer string
    TokensUsed  int
    Latency     time.Duration
}

logAgentRun(log)

Критерии сдачи / Чек-лист¶

✅ Сдано (готовность к продакшену):

Системный промпт чётко определяет границы ответственности
Все инструменты имеют детальные описания
Реализована валидация входных данных
Реализована защита от зацикливания
Критичные операции требуют подтверждения
Реализовано логирование всех действий
Настроен мониторинг метрик (Pass Rate, Latency, Errors)
Создан базовый набор evals
Проведено A/B тестирование промпта
Документированы известные ограничения

❌ Не сдано:

Нет валидации входных данных
Нет защиты от зацикливания
Нет логирования действий
Нет мониторинга метрик
Нет evals для проверки качества

Связь с другими главами¶

Безопасность: Как реализовать safety checks, см. Главу 05: Безопасность
Evals: Как тестировать агентов, см. Главу 08: Evals

Что дальше?¶

После изучения best practices переходите к:

17. Security и Governance — безопасность и управление агентами
Приложение: Справочники — глоссарий, чек-листы, шаблоны

Навигация: ← Кейсы | Оглавление | Security и Governance →