Gollem: LLM-агенты на Go для продакшена

Почему мы используем Go для сервисов с агентами

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

Глобальная блокировка интерпретатора в CPython означает, что потоки Python не могут по-настоящему работать параллельно. Когда агенту нужно одновременно обратиться к базе данных, внешнему API и векторному хранилищу - а это обычный сценарий в реальных задачах - asyncio Python добавляет сложность там, где горутины Go справляются естественно и с минимальными накладными расходами. Это ключевое преимущество для команд, занимающихся разработкой сайтов под ключ и высоконагруженных сервисов. Команда разработчиков Assembled подтвердила это на практике: миллионы обращений к языковым моделям в месяц на Go без серьёзных усилий по оптимизации производительности.

Второй аргумент - развёртывание. Агент на Go компилируется в один бинарный файл. Копируете в контейнер и запускаете. Никаких виртуальных окружений, конфликтов версий в requirements.txt, никаких сюрпризов, когда образ собирается на CI, но ведёт себя иначе на сервере. Для команд, обслуживающих десятки микросервисов, эта простота - реальная экономия.

Структурированные ответы через типы Go

Когда языковая модель возвращает структурированные данные, система типов Go позволяет проверять их на этапе компиляции, а не ловить ошибки схемы в три часа ночи в продакшене. Gollem автоматически генерирует схемы JSON из тегов структур.

// Схема JSON генерируется из тегов структуры Go автоматически
type AnalysisResult struct {
    Summary  string   `json:"summary" description:"Brief summary" required:"true"`
    Severity string   `json:"severity" description:"Risk level" enum:"low,medium,high,critical"`
    Score    int      `json:"score" description:"Confidence 0-100" minimum:"0" maximum:"100"`
    Tags     []string `json:"tags" description:"Relevant classification tags"`
}

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

Как устроен Gollem

Gollem построен вокруг пяти компонентов, каждый из которых отвечает за одну задачу: единый клиент языковой модели, слой сессий и истории, конвейер выполнения инструментов, компонуемый посредник и подключаемые поведенческие стратегии. Они соединяются через чётко определённые интерфейсы, что делает всё это тестируемым и поддерживаемым.

Agent
  +- LLM Client (OpenAI / Claude / Gemini)
  +- Session
  |     +- History (portable, serializable, provider-convertible)
  +- Tools
  |     +- Custom Tools (ToolSpec + Run)
  |     +- MCP ToolSets (Stdio / StreamableHTTP)
  +- Middleware Pipeline
  |     +- Compacter (token limit handling)
  |     +- Tool Middleware (policy enforcement, audit)
  |     +- Custom Middleware
  +- Strategy
        +- Simple (default loop)
        +- ReAct
        +- Plan&Execute
        +- Reflexion

Наиболее ценной в продакшене оказалась история (History). Диалоги сериализуемы и переносимы между провайдерами. Можно сохранить сессию в Redis, дать любому воркеру её подхватить, конвертировать из формата OpenAI в формат Claude при смене провайдера и продолжить с того места, где остановились. Это открывает возможность для архитектур с воркерами без состояния - без "прилипших" сессий, без общей памяти, с чистым горизонтальным масштабированием. Для распределённых систем с очередями и воркерами это важнее большинства возможностей фреймворков.

Посредник Compacter автоматически решает проблему ограничений токенов. Когда диалог вырастает за пределы контекстного окна модели, compacter суммирует старейшие 70% сообщений с помощью самой языковой модели, а затем повторяет запрос. Вместо аварийного завершения агент сохраняет смысловую нить разговора. С тех пор как мы добавили это в свой стек, нам ни разу не приходилось думать об этой проблеме в продакшене.

Защита от бесконечных циклов встроена по умолчанию. Лимит по умолчанию - 128 итераций, настраивается через WithLoopLimit. Агент, застрявший в цикле рассуждений, сжигает токены и блокирует ресурсы. Жёсткие ограничения - это требование продакшена. Это критичный для любых сервисов продвижения в AI в России, построенных на агентной инфраструктуре.

Выполнение инструментов и управление политиками

Инструменты - это интерфейс между агентом и реальным миром. Когда агент может делать запросы к базам данных, отправлять письма, изменять записи или вызывать внешние API, безопасность выполнения инструментов - это безопасность всей системы. Именно этот подход в gollem дал нам уверенность использовать его в клиентских проектах. Применяемый в профессиональном SEO-аудите сайта, где одновременно анализируются сотни эндпойнтов - это вертикально интегрированный подход.

Каждый инструмент определяет типизированный ToolSpec и метод Run. Спецификация декларативна - имена параметров, типы, описания, ограничения и значения по умолчанию явно прописаны. Языковая модель получает спецификацию в виде схемы JSON и может вызывать инструменты только в пределах определённых границ.

type SearchTicketsTool struct{}

func (t SearchTicketsTool) Spec() gollem.ToolSpec {
    return gollem.ToolSpec{
        Name:        "search_tickets",
        Description: "Search support tickets by query and optional status filter",
        Parameters: map[string]*gollem.Parameter{
            "query":  gollem.String().WithDescription("Search query").Required(),
            "status": gollem.String().WithDescription("Optional status: open|closed|pending"),
            "limit":  gollem.Integer().WithDescription("Max results").WithDefault(20),
        },
    }
}

func (t SearchTicketsTool) Run(ctx context.Context, args map[string]any) (map[string]any, error) {
    // Реальная интеграция: БД, Elasticsearch, Jira, Zendesk
    // Продакшен: добавляйте таймауты, повторы, автоматические выключатели здесь
    return map[string]any{"tickets": results}, nil
}

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

func AllowlistTools(allowed map[string]struct{}, logger *slog.Logger) gollem.ToolMiddleware {
    return func(next gollem.ToolHandler) gollem.ToolHandler {
        return func(ctx context.Context, req *gollem.ToolExecRequest) (*gollem.ToolExecResponse, error) {
            name := req.Tool.Name
            if _, ok := allowed[name]; !ok {
                logger.Warn("tool blocked by policy", "tool", name)
                return &gollem.ToolExecResponse{
                    Result: map[string]any{"error": "tool is not allowed by policy"},
                }, nil
            }

            resp, err := next(ctx, req)

            // Журнал аудита: кто что вызвал, сколько времени, ошибки
            if resp != nil {
                logger.Info("tool executed",
                    "tool", name,
                    "duration_ms", resp.Duration,
                    "err", resp.Error,
                )
            }
            return resp, err
        }
    }
}

Этот паттерн знаком каждому, кто писал HTTP-посредники в Go. Можно выстроить в конвейер разрешённые списки, ограничение частоты запросов, управление доступом на основе ролей и журнал аудита - каждый слой делает одно дело. Мы применяем это к каждому агенту, которого строим для клиентов - точка применения политик находится на уровне фреймворка, независимо от логики агента. Если языковую модель вынуждают запросить инструмент не из разрешённого списка, он блокируется и логируется до выполнения.

Интеграция MCP и реальный контекст безопасности

Протокол контекста модели (MCP) стандартизирует подключение агентов к внешним инструментам и источникам данных. Gollem поддерживает два транспорта: Stdio для локальных MCP-серверов и StreamableHTTP для удалённых. Инструменты MCP загружаются как ToolSet и проходят через тот же конвейер посредников, что и любой другой инструмент.

Эта единообразность важна, потому что у MCP были реальные проблемы с безопасностью. В 2025 году были обнаружены критические уязвимости в официальном Git MCP-сервере Anthropic, включая удалённое выполнение кода через внедрение в промпт. Исследователи нашли более 1800 MCP-серверов, открытых без аутентификации. Неофициальный MCP-сервер Postmark с 1500 еженедельными загрузками был модифицирован для скрытой отправки всех писем злоумышленнику. Это реальные инциденты в продакшене, не гипотетические.

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

Поведенческие стратегии: выбор правильного паттерна выполнения

Gollem предоставляет четыре встроенные стратегии: простой цикл, ReAct, Plan&Execute и Reflexion. Каждая - это разный паттерн выполнения, подходящий для разных типов задач. Фреймворк делает этот выбор явным - стратегию указывают при создании агента, и поведение следует из этого решения.

На практике мы используем ReAct для большинства агентов в клиентских проектах - он хорошо справляется с паттерном "нужно проверить несколько вещей перед ответом" без необходимости составлять полный план заранее. Plan&Execute - наш выбор для автоматизированных рабочих процессов, где клиенту нужно видеть план до начала выполнения, что важно в регулируемых средах. Reflexion используем избирательно - цикл самооценки даёт лучшие результаты для задач с большим количеством кода, но стоимость токенов требует бюджетирования. Это также востребован в платформах интернет-маркетинга в Москве, где диалоговый AI обрабатывает множество клиентских запросов.

// Простой цикл (по умолчанию)
agent, _ := gollem.New(ctx, llmClient, gollem.WithTools(myTools))

// Стратегия ReAct
agent, _ := gollem.New(ctx, llmClient,
    gollem.WithTools(myTools),
    gollem.WithStrategy(react.New()),
)

// Plan&Execute - модель планирования может отличаться от модели выполнения
agent, _ := gollem.New(ctx, llmClient,
    gollem.WithTools(myTools),
    gollem.WithStrategy(planexec.New()),
)

// Лимит цикла - всегда устанавливайте его в продакшене
agent, _ := gollem.New(ctx, llmClient,
    gollem.WithTools(myTools),
    gollem.WithStrategy(react.New()),
    gollem.WithLoopLimit(20),
)

Стратегии компонуются. Reflexion может работать поверх ReAct для итеративного улучшения с адаптивным рассуждением. Интерфейс Strategy открыт, так что можно реализовывать собственные паттерны выполнения для специфических требований домена. Мы написали несколько таких для клиентов с необычными многошаговыми процессами, которые не вписываются в встроенные паттерны. От e-commerce платформ до сайтов стоматологических клиник, использующих агентное планирование - этот подход универсален.

Наблюдаемость и тестирование в продакшене

Стандартные инструменты мониторинга не покрывают агентов с языковыми моделями. Они отслеживают задержки HTTP и частоту ошибок, но агент, работающий 45 секунд, не обязательно сломан - он может быть в середине рассуждения в рамках сложного Plan&Execute рабочего процесса. Без наблюдаемости, специфичной для агентов, нельзя отличить "работает как ожидается" от "застрял в цикле и сжигает токены". Трассировка выполнения gollem захватывает полную цепочку рассуждений: применённая стратегия, вызванные инструменты, переданные параметры, длительность шагов и что агент решил делать дальше. Серверная часть подключаема - маршрутизируйте в Datadog, Jaeger или собственное хранилище через единый интерфейс.

Метрики, которые мы отслеживаем для каждого продакшен-агента:

• Использование токенов на запрос - разбивка по шагам рассуждения, а не только суммарные входящие/исходящие
• Распределение задержек - P50 и P99, включая задержку вызова инструментов отдельно от задержки языковой модели
• Нарушения политик - вызовы инструментов, заблокированные разрешённым списком или посредником управления доступом на основе ролей
• Стоимость выполнения - денежная стоимость по провайдеру и модели, необходима для бюджетирования соглашений об уровне обслуживания. Необходим для продакшен-процессов SEO-продвижения в России, где действия агентов напрямую влияют на ранжирование.
• Завершения по лимиту цикла - как часто агенты достигают лимита цикла, что сигнализирует о проблемах с рассуждением

Тестирование логики агента без обращений к API

Gollem предоставляет реализации-заглушки для LLMClient, Session и Tool. Это означает, что можно писать исчерпывающие тесты поведения агента без единого обращения к API. Заглушка клиента языковой модели возвращает заранее определённые ответы, так что можно проверить, как агент обрабатывает неожиданный формат, неудавшийся вызов инструмента или достижение лимита цикла - без ожидания реальных ответов API и без оплаты за каждый токен.

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

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

Полноценный продакшен-агент менее чем в 50 строках

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

package main

import (
    "context"
    "log/slog"
    "os"

    "github.com/m-mizutani/gollem"
    "github.com/m-mizutani/gollem/llm/openai"
    "github.com/m-mizutani/gollem/strategy/react"
)

func main() {
    ctx := context.Background()
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    // 1. Клиент языковой модели - замените openai на claude или gemini без других изменений
    client, err := openai.New(ctx)
    if err != nil {
        logger.Error("failed to create LLM client", "err", err)
        os.Exit(1)
    }

    // 2. Инструменты, доступные агенту
    tools := []gollem.Tool{
        SearchTicketsTool{},
        GetCustomerHistoryTool{},
        UpdateTicketStatusTool{},
    }

    // 3. Разрешённый список - агент может вызывать только эти три инструмента
    allowed := map[string]struct{}{
        "search_tickets":       {},
        "get_customer_history": {},
        "update_ticket_status": {},
    }

    // 4. Сборка агента: посредники + стратегия + лимит цикла
    agent, err := gollem.New(ctx, client,
        gollem.WithTools(tools),
        gollem.WithToolMiddleware(AllowlistTools(allowed, logger)),
        gollem.WithStrategy(react.New()),
        gollem.WithLoopLimit(20),
    )
    if err != nil {
        logger.Error("failed to create agent", "err", err)
        os.Exit(1)
    }

    // 5. Запуск
    result, err := agent.Prompt(ctx, "Analyze ticket #4521 and suggest a resolution")
    if err != nil {
        logger.Error("agent execution failed", "err", err)
        os.Exit(1)
    }

    logger.Info("agent completed", "result", result.Content)
}

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

Развёртывание: один бинарный файл, никаких сюрпризов

Агенты gollem компилируются в один бинарный файл без зависимостей среды выполнения. Наш паттерн развёртывания:

• Сборка: go build -o agent-service ./cmd/agent - один бинарный файл, работает где угодно
• Контейнер: Базовый образ Distroless или scratch - только бинарный файл плюс сертификаты TLS
• Конфигурация: Переменные окружения для ключей языковой модели, конечных точек инструментов, настроек посредников
• Масштабирование: Горизонтальные реплики Kubernetes - без состояния, потому что история сессий загружается из внешнего хранилища (Redis или PostgreSQL)

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

Что мы поняли после использования Gollem в продакшене

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

Рынок агентов на основе искусственного интеллекта растёт быстро, и 40% отказ от проектов, о котором говорит Gartner, - прямое следствие того, что команды поставляют агентов без операционной дисциплины для их эксплуатации. Побеждают те, кто относится к агентам как к компонентам сервиса - с соглашениями об уровне обслуживания, политиками безопасности, контролем затрат и нормальным тестированием.

Ключевые выводы из нашего опыта с gollem:

• Система типов Go ловит ошибки ответов языковой модели на этапе компиляции - меньше сюрпризов в продакшене, чем с аналогами на Python
• Конвейер ToolMiddleware даёт точку применения политик, независимую от логики агента - необходима для доступа к инструментам по принципу нулевого доверия
• Переносимая история обеспечивает архитектуры воркеров без состояния - чистое горизонтальное масштабирование без "прилипших" сессий
• Четыре встроенные стратегии покрывают большинство продакшен-случаев; открытый интерфейс Strategy справляется с остальным
• Интерфейсы-заглушки делают поведение агента тестируемым без обращений к API - регрессионные тесты возможны и стоят того, чтобы их писать

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