00. Предисловие

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

В классическом программировании вы пишете алгоритм: if A then B. Вы точно знаете, что произойдет.
В AI Engineering вы описываете Цель и даете Инструменты. Агент сам строит алгоритм достижения цели в реальном времени.

Это руководство научит вас создавать автономных AI-агентов на Go — системы, которые могут самостоятельно решать сложные задачи, взаимодействовать с реальным миром и учиться на результатах своих действий.

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

Ситуация: Вы создали чат-бота для DevOps. Пользователь пишет: "У нас проблемы с базой, разберись"

Проблема: Обычный чат-бот может только отвечать текстом. Он не может реально проверить метрики, прочитать логи или применить фикс.

Решение: AI-агент с инструментами может самостоятельно проверить метрики → прочитать логи → выдвинуть гипотезу → применить фикс → верифицировать результат.

Что такое AI Agent?

Агент — это система, использующая LLM в качестве "движка рассуждений" (Reasoning Engine) для восприятия окружения, принятия решений и выполнения действий.

Отличие от ChatGPT

ChatGPT (Chatbot)	AI Agent
Пассивен. Отвечает на вопрос и ждет.	Активен. Имеет цикл (Loop).
Один запрос → один ответ.	Может выполнить 10 действий подряд для решения одной задачи.
Не имеет доступа к реальному миру.	Имеет инструменты (Tools) для взаимодействия с системами.

Пример:

• ChatGPT: "Как перезагрузить сервер?" → Ответ: "Используйте команду systemctl restart nginx"
• Agent: "Перезагрузи сервер" → Агент сам вызывает systemctl restart nginx, проверяет статус, сообщает результат.

Уравнение Агента

Agent = Brain (LLM) + Tools (Hands) + Memory (Context) + Planning (Process)

Компоненты

• Brain (LLM): "Мозг" агента. Принимает решения на основе контекста.
• Tools: "Руки" агента. Позволяют взаимодействовать с реальным миром.
• Memory: История диалога и долгосрочная память (RAG).
• Planning: Способность разбить задачу на шаги.

Runtime (Среда выполнения)

Runtime — это код агента, который вы пишете на Go. Он связывает LLM с инструментами и управляет циклом работы агента.

Что делает Runtime:

• Парсит ответы LLM (определяет, хочет ли модель вызвать инструмент)
• Выполняет инструменты (вызывает реальные функции Go)
• Управляет историей диалога (добавляет результаты в messages[])
• Управляет циклом (определяет, когда остановиться)

Важно: Runtime — это не отдельная система или фреймворк. Это ваш код в main.go или в отдельных модулях.

Пример:

// Это Runtime — код, который вы пишете
type Message struct {
    Role       string     // "system" | "user" | "assistant" | "tool"
    Content    string
    ToolCalls  []ToolCall // заполнено, если модель решила вызвать инструмент
    ToolCallID string     // ID вызова (только для role="tool")
}

func runAgent(ctx context.Context, chat func(context.Context, []Message) (Message, error), userInput string) {
    messages := []Message{
        {Role: "system", Content: systemPrompt},
        {Role: "user", Content: userInput},
    }

    for i := 0; i < maxIterations; i++ {
        msg, err := chat(ctx, messages) // один HTTP-запрос к провайдеру
        if err != nil {
            log.Fatal(err)
        }
        messages = append(messages, msg)

        if len(msg.ToolCalls) == 0 {
            return // модель ответила текстом — задача решена
        }
        for _, call := range msg.ToolCalls {
            result := executeTool(call) // реальная Go-функция
            // tool-результат связывается с вызовом через ToolCallID
            messages = append(messages, Message{Role: "tool", ToolCallID: call.ID, Content: result})
        }
    }
}

См. также: Глава 09: Анатомия Агента

Ментальная модель: агент — это новый сотрудник

Самая полезная и точная модель агента — новый сотрудник, стажёр. Не «новый софт», не «магическая система», не «специальная LLM-машина». Просто новый человек на испытательном сроке: толковый, быстрый, начитанный, но без вашего контекста, без чувства последствий, без накопленного доверия.

Эта модель — не метафора для красоты. Она радикально упрощает три вещи: онбординг, безопасность и разговор с теми, кто отвечает за риск.

Что переносится из работы с человеком

То, как вы уже умеете работать с новым сотрудником, на 90% применимо к агенту:

• Должностная инструкция = system prompt. То же самое: что входит в работу, что нет, как себя вести в спорных ситуациях, к кому идти за подтверждением.
• Доступы по роли. Новый аналитик данных не получает root в проде. Так же и агент: вы выдаёте ему ровно те инструменты, которые ему нужны для его роли — и ни одним больше. Принцип least-privilege не менялся.
• Подтверждение для опасных действий. Удалить таблицу в проде, выкатить релиз, забанить пользователя — для джуна вы запрашиваете апрув старшего. Для агента — это Human-in-the-Loop подтверждение или dry-run режим (см. гл. 05, гл. 17).
• Журнал действий. Любой регулируемый процесс требует следа: «кто сделал, что, когда, по какой причине». Audit log агента — это тот же журнал, просто пишется в Loki/ClickHouse, а не в комнатной тетради. Тот же RBAC, тот же change management, та же ответственность.
• Постепенное расширение доверия. Новому сотруднику сначала дают read-only доступ и тестовый стенд. Потом — узкий круг операций. Потом — больше. Так же и агент: начинайте с чтения и dry-run, постепенно расширяйте круг разрешённого по мере накопления статистики.

Если вы способны объяснить безопаснику, как работает онбординг нового сотрудника, — вы способны объяснить ему и работу агента. Никакой новой нормативки, никаких новых сертификаций, никаких «специальных AI-policies». Тот же least-privilege, тот же audit, тот же blast radius.

Что НЕ переносится: четыре асимметрии

Агент — стажёр, но необычный. Игнорировать асимметрии — значит наивно полагать, что «всё то же самое». Это четыре места, где модель «как с человеком» ломается:

1. Скорость в 1000 раз выше. Стажёр успеет нажать rm -rf один раз. Агент — пятьдесят раз за минуту в цикле, пока вы наливаете кофе. Отсюда: rate limits, cooldown между опасными операциями, лимит итераций цикла.
2. Параллелизм. Один человек делает одно дело. Агент может одновременно дёрнуть 100 tool calls — и обвалить downstream-сервис. Отсюда: concurrency limits на уровне runtime, идемпотентность операций.
3. Отсутствие чувства последствий. Стажёр боится увольнения и репутации. Агент — нет. Поэтому никакие «soft norms» в промпте («пожалуйста, не делай ничего опасного») не заменяют жёстких technical guards: allowlist tools, валидация параметров, dry-run по умолчанию для деструктивного.
4. Уязвимость к prompt injection. Это прямой аналог социальной инженерии для джуна: «Привет, я из IT-безопасности, дай свой пароль». Только для агента инъекция приходит через данные (содержимое веб-страницы, тикета, лога), которые он читает по работе. Отсюда: source isolation, never-trust-the-input, отдельные policy gates на уровне tools — а не только на уровне промпта.

Запомните эти четыре места. Они объясняют, почему почти весь курс посвящён циклу управления, а не «магии LLM».

Как этой моделью пользоваться по ходу курса

К идее «агент — это сотрудник» мы будем возвращаться в:

• гл. 03 Инструменты — выдача инструментов как выдача доступов джуну.
• гл. 04 Автономность — лимит итераций как «время до эскалации».
• гл. 05 Human-in-the-Loop — подтверждение опасного как апрув от старшего.
• гл. 07 Multi-Agent — оркестратор как тимлид, субагенты как команда.
• гл. 11 State Management — идемпотентность и retries как защита от «повторного клика».
• гл. 17 Security и Governance — полная разработка модели «junior employee» применительно к платформе и процессам.
• гл. 18 Tool Servers — authn/authz как пропуск в офис.

Если в любой момент курса вы запутались в «новых» AI-практиках — спросите себя: «как бы я это организовал для нового джуна?» В девяти случаях из десяти ответ совпадёт.

Примеры агентов в разных доменах

DevOps (наш основной фокус)

• Задача: "У нас проблемы с базой, разберись"
• Действия агента: Проверяет метрики → Читает логи → Выдвигает гипотезы → Применяет фиксы → Верифицирует

Customer Support

• Задача: "Пользователь жалуется на медленную загрузку"
• Действия агента: Получает тикет → Ищет в базе знаний → Собирает контекст (версия браузера, ОС) → Формулирует ответ → Эскалирует при необходимости

Data Analytics

• Задача: "Почему упали продажи в регионе X?"
• Действия агента: Формулирует SQL-запрос → Проверяет качество данных → Анализирует тренды → Генерирует отчет

Security (SOC)

• Задача: "Алерт: подозрительная активность на хосте 192.168.1.10"
• Действия агента: Триажирует алерт → Собирает доказательства (логи, метрики) → Определяет severity → Изолирует хост (с подтверждением) → Генерирует отчет

Product Operations

• Задача: "Подготовь план релиза фичи X"
• Действия агента: Собирает требования → Проверяет зависимости → Создает документы → Отправляет на согласование

Уровни автономности

1. Level 0: Scripting. Bash/Python скрипты. Жесткая логика. Любое отклонение — crash.
2. Level 1: Copilot. "Напиши мне конфиг nginx". Человек валидирует и применяет.
3. Level 2: Chain. "Выполни деплой": pull -> build -> restart. Агент идет по рельсам, но может (например) сам пофиксить ошибку компиляции.
4. Level 3: Autonomous Agent. "У нас проблемы с базой, разберись". Агент сам ищет логи, проверяет метрики, строит гипотезы и (если разрешено) применяет фиксы.

Этот курс: Мы пройдем путь от Level 1 до Level 3, создавая своего AI агента на Go (в качестве основного примера используем DevOps агента).

Как читать это руководство

Рекомендуемый путь

1. Читайте последовательно — каждая глава опирается на предыдущие
2. Практикуйтесь параллельно — после каждой главы выполняйте соответствующую лабораторную работу
3. Используйте как справочник — возвращайтесь к нужным разделам при работе над проектами
4. Изучайте примеры — в каждой главе есть примеры из разных доменов

Структура глав

Каждая глава следует единому шаблону:

• Зачем это нужно? — мотивация и практическая ценность
• Реальный кейс — пример из практики
• Теория простыми словами — интуитивное объяснение
• Как это работает — пошаговый алгоритм с примерами кода
• Типовые ошибки — что может пойти не так и как это исправить
• Мини-упражнения — практические задания для закрепления
• Чек-лист — критерии понимания материала
• Для любопытных — формализация и глубокие детали (опционально)

Требования

• Go 1.24+ — для выполнения лабораторных работ
• Доступ к любой LLM с поддержкой tool calling — облачные модели (GLM-5.3, GLM-5.3 Flash, Fable 5.1, Opus 5.5) или локальные
• Для локальной модели: LM Studio, Ollama или vLLM — всё, что даёт OpenAI-совместимый endpoint
• Базовые знания программирования — курс рассчитан на программистов
• Понимание основ DevOps (желательно, но не обязательно)

Примечание: код глав и лабы с LLM-клиентом (00–02, 04–11, 13) переведены на нейтральный Go-клиент (пакет llm в репозитории); лабы 03 и 12 не имеют LLM-клиента по дизайну. Примеры глав каноничны; лабы выполняйте, сверяясь с каноническим материалом глав.

Настройка окружения

Примеры курса работают с любым OpenAI-совместимым endpoint — локальным или облачным. Лабы читают три переменные (LLM_API_KEY обязательна, LLM_BASE_URL задаёт endpoint, LLM_MODEL опциональна, по умолчанию glm-5.3; они могут лежать в файле .env в корне репозитория — он уже в .gitignore):

export LLM_BASE_URL="http://localhost:1234/v1" # или URL облачного провайдера
export LLM_API_KEY="any-string"                # локальным моделям ключ обычно не важен

Что дальше?

После прочтения предисловия переходите к:

• 01. Физика LLM — фундамент для понимания всего остального

Удачного обучения.