Agentgram: единый API-шлюз для всех AI-агентов

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

Я раз за разом ловил себя на том, что для каждого нового агента открываю отдельное окно чата — одно для агента Kubernetes, другое для логов, третье для метрик, и каждый говорит на своём протоколе. Agentgram — это та самая единая точка входа, которой мне не хватало: один чат, один API, все агенты, независимо от того, как каждый из них устроен под капотом.

API работает как мультиплексор (multiplexer): берёт на себя аутентификацию, права доступа и хранение сессий, общается с каждым агентом на его родном протоколе, а результат преобразует в единый поток событий AG-UI. Веб-клиент просто отрисовывает этот поток — ему совершенно не важно, пришёл ответ с REST-эндпоинта, от A2A-пира или из приложения на Google ADK.

Совет

Главная фишка — централизуйте всё под RBAC. Подключите к Agentgram все агенты и MCP-серверы своей компании — на ADK, A2A или любом другом протоколе — и откройте к ним доступ через один API-эндпоинт и один MCP-эндпоинт. Ролевая модель доступа (RBAC) точно определяет, кто до какого агента или MCP может добраться, так что одна интеграция выдаёт каждому пользователю ровно те инструменты, которые ему положены, — и ничего лишнего. Никаких N интеграций, N логинов и N инструментов на каждого клиента.

Возможности

🏢 Централизация N агентов и N MCP-серверов — зарегистрируйте всё, что работает в компании, и обращайтесь ко всему через один API-эндпоинт и один MCP-эндпоинт.
🛡️ RBAC — детальное управление доступом к каждому агенту и каждому MCP по группам или пользователям. Каждый вызывающий видит только то, что ему разрешено.
🔌 Независимость от протокола — за одним интерфейсом скрываются агенты на Custom REST/SSE, A2A (JSON-RPC) и Google ADK.
📡 Нативный AG-UI — API отдаёт стандартные AG-UI SSE-события (RUN_STARTED, TEXT_MESSAGE_*, TOOL_CALL_*, RUN_FINISHED).
🧵 Персистентные сессии — история переписки для каждого агента хранится в Redis и управляется API (сами агенты остаются без состояния).
👥 Мультиагентные чаты — общайтесь с несколькими агентами в одном треде и передавайте контекст между ними.
🤝 Совместная работа — делитесь беседами по отзываемым ссылкам с ограниченным временем жизни (просмотр или клонирование), создавайте общие мультиагентные группы для командной работы.
🔐 Аутентификация — опциональный вход через Keycloak (OIDC/JWT); пользователи и группы (например, Google Workspace) участвуют в RBAC.
🛠️ MCP-сервер — открывает ваших агентов как инструменты внутри Claude Code и Cursor, с полной поддержкой OAuth и Dynamic Client Registration (без ручной настройки).
💬 Интеграция со Slack — те же агенты доступны прямо из Slack.
📊 Встроенная наблюдаемость — метрики использования, дашборды задержек и стоимости из коробки.
🧰 Панель администратора — регистрируйте агентов, MCP-серверы, LLM и права доступа через UI.

Скриншоты

Чат с одним агентом — потоковые AG-UI ответы с вызовами инструментов.

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

Панель администратора — регистрация агентов, MCP-серверов, LLM и прав доступа.

Наблюдаемость — дашборды использования, задержек и стоимости из коробки.

Архитектура

┌──────────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│        Web           │────>│        API          │────>│  Agent (Custom) │
│  (Next.js + AG-UI)   │<────│   (Go Multiplexer)  │<────│  REST · SSE     │
└──────────────────────┘     │                     │     └─────────────────┘
         ↑                   │  - JWT / OIDC auth  │     ┌─────────────────┐
    AG-UI events             │  - Permissions      │────>│  Agent (A2A)    │
    over SSE                 │  - Session store    │<────│  JSON-RPC       │
                             │  - AG-UI conversion │     └─────────────────┘
                             │  - MCP server       │     ┌─────────────────┐
                             └─────────────────────┘────>│  Agent (ADK)    │
                                       │            <────│  REST · SSE     │
                                  Redis · PostgreSQL     └─────────────────┘

Подробнее о том, как каждый протокол отображается на AG-UI, читайте в docs/PROTOCOLS_OVERVIEW.md.

Быстрый старт

Требования: Node.js 22+, Go 1.25+, Docker и Docker Compose.

git clone https://github.com/dfradehubs/agentgram.git
cd agentgram
make install        # установить зависимости web и Go
make docker-up      # API + mock-агент + Redis + PostgreSQL + тестовый фронтенд

После запуска доступны следующие сервисы:

Сервис	URL
API	http://localhost:8080
Mock-агент	http://localhost:9000
Тестовый фронтенд	http://localhost:3001

Сервис

URL

API

http://localhost:8080

Mock-агент

http://localhost:9000

Тестовый фронтенд

http://localhost:3001

Чтобы запустить настоящий веб-интерфейс против этого стека:

make web            # dev-сервер Next.js на http://localhost:3000

Запустите make help, чтобы увидеть все доступные цели.

Как это работает

Запрос чата представляет собой список сообщений и необязательный идентификатор сессии:

POST /api/agents/{agentId}/chat
Content-Type: application/json
Authorization: Bearer <jwt>     # только если включена аутентификация

{
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "session_id": "optional-uuid"
}

Ответ — поток AG-UI событий по SSE, одинаковой структуры вне зависимости от протокола агента:

data: {"type":"RUN_STARTED","threadId":"...","runId":"..."}
data: {"type":"TEXT_MESSAGE_START","messageId":"...","role":"assistant"}
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"Hello"}
data: {"type":"TEXT_MESSAGE_END","messageId":"..."}
data: {"type":"RUN_FINISHED","threadId":"...","runId":"..."}

Полная справка по API: docs/API.md. Контракты агентов: REST · A2A · ADK.

Развёртывание

Готовые рецепты развёртывания лежат в examples/:

Docker Compose — самостоятельный хостинг всего стека (API + web + Redis + PostgreSQL) с опубликованными образами. Самый быстрый способ поднять Agentgram на сервере.
Kubernetes (Helm) — production-значения для чарта bjw-s app-template и Ingress, который правильно маршрутизирует веб-приложение и эндпоинты MCP/OAuth.

Образы контейнеров публикуются в GitHub Container Registry при каждом релизе:

ghcr.io/dfradehubs/agentgram-api
ghcr.io/dfradehubs/agentgram-web

Конфигурация

API настраивается через единый YAML-файл (CONFIG_PATH, например api/configs/config.yaml), в котором описаны сервер, аутентификация, Redis, PostgreSQL, метрики, трассировка и MCP-сервер. Секреты никогда не прописываются напрямую — каждое чувствительное значение задаётся через ${ENV:VAR} и подставляется из переменных окружения:

auth:
  enabled: true          # false — запуск без логина (локально / в доверенных сетях)
  keycloak:
    enabled: true
    issuer: "${ENV:KEYCLOAK_ISSUER}"
    client_id: "${ENV:OIDC_CLIENT_ID}"
    client_secret: "${ENV:OIDC_CLIENT_SECRET}"

redis:
  addr: "${ENV:REDIS_ADDR}"
  password: "${ENV:REDIS_PASSWORD}"

Полный список переменных смотрите в api/.env.example.

Агенты управляются в режиме реального времени через встроенную панель администратора (/admin) и хранятся в PostgreSQL — перезапуск для добавления агента не нужен. Для каждого агента выбирается протокол (Custom / A2A / ADK), эндпоинт и список тех, кто может к нему обращаться (группы Google Workspace или отдельные пользователи).

Model Context Protocol (MCP)

Agentgram поставляется со стандартным MCP-сервером, который превращает ваших агентов в инструменты для любой MCP-совместимой IDE или CLI — Claude Code, Cursor и любого другого клиента, поддерживающего спецификацию. Реализован полный поток обнаружения и авторизации по стандарту: метаданные защищённого ресурса (RFC 9728), обнаружение сервера авторизации (RFC 8414) и Dynamic Client Registration (RFC 7591) — так что совместимый клиент подключается только по URL, никакой ручной настройки не требуется:

claude mcp add --transport http agentgram https://agentgram.example.com/mcp

Клиент автоматически выполнит OAuth + DCR поток. После этого можно спрашивать:

Ask logs-agent for the errors in the last 30 minutes of the payment-api service.

Эндпоинт открывает доступ и к агентам (ask_<agent-id>), и к инструментам любых MCP-серверов, зарегистрированных в Agentgram, к которым у вас есть права — Agentgram агрегирует эти вышестоящие серверы и переэкспортирует их инструменты, применяя ваши права доступа.

Полное руководство (настройка клиента, автоматизация, тюнинг): docs/MCP.md.

Технологический стек

API — Go 1.25 · Chi router · Redis (сессии + pub/sub) · PostgreSQL · OpenTelemetry · структурированное логирование.

Web — Next.js 16 (App Router) · TypeScript · Tailwind CSS 4 · SSE/AG-UI напрямую через fetch + ReadableStream · Pino logging · двуязычный интерфейс (English / Spanish).

Структура проекта

agentgram/
├── api/        # Go API (мультиплексор) — proxy, agents, auth, mcp, store, repository
├── web/        # Next.js веб-клиент (AG-UI over SSE)
├── docs/       # Архитектура, API и контракты протоколов
├── examples/   # Рецепты развёртывания Docker Compose и Kubernetes
└── Makefile    # Команды для разработки и сборки

Подробнее: docs/ARCHITECTURE.md · api/CLAUDE.md · web/CLAUDE.md.

Участие в проекте

Задачи (issues) и пул-реквесты приветствуются. Для нетривиальных изменений сначала откройте issue, чтобы обсудить направление. Держите PR сфокусированными, перед отправкой запускайте make test и make lint, придерживайтесь Conventional Commits (feat:, fix:, docs:, …).