Staff Developer Advocate, Google

Соавторы: Stenal Jolly, Strategic Cloud Engineer, Google; Anubhav Dhawan, Software Engineer, Google

Вслед за знаковым анонсом MCP Toolbox v1.0 мы рады сообщить, что MCP Toolbox Java SDK официально достиг версии 1.0.

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

В этой статье мы расскажем о новинках Java SDK v1.0, покажем пример из реальной практики и поможем вам начать работу с собственной реализацией.

MCP: Универсальный интерфейс

Сегодня разработчики сталкиваются с растущим «бутылочным горлышком» интеграции: если у вас есть N различных ИИ-моделей и M корпоративных источников данных, вам приходится создавать, защищать и поддерживать N × M специализированных пользовательских подключений. Отсутствие унифицированного уровня интеграции вынуждает инженерные команды полагаться на фрагментированную сеть разрозненных конвейеров. В результате масштабирование агентной архитектуры быстро становится неустойчивым, подвергая чувствительные корпоративные базы данных серьезным угрозам безопасности, фрагментированному контролю доступа и огромным накладным расходам на обслуживание.

Устранение этой фрагментированной сети пользовательских интеграций — основная проблема, которую решает Model Context Protocol (MCP). Выступая в качестве универсального интерфейса — «USB Type-C» для ИИ-оркестрации — MCP отделяет модели от источников данных. Вместо написания пользовательского или управляемого кода интеграции API для каждой новой модели или базы данных, разработчики пишут код для единого стандартизированного протокола. Такой подход позволяет любому агенту, совместимому с MCP, безопасно и мгновенно взаимодействовать с любой системой, поддерживающей MCP. Подключение через MCP позволяет разработчикам связывать агентов с реальными системами без создания специализированных интеграций для каждой новой модели.

Что нового в Java SDK v1.0: Создан для промышленных нагрузок

Когда мы анонсировали публичную бета-версию MCP Toolbox Java SDK, нашей целью было внедрение первоклассной, типобезопасной оркестрации агентов в корпоративные среды Java. С тех пор мы сотрудничали с разработчиками и участниками open-source сообщества, чтобы укрепить наши API.

Релиз v1.0 знаменует собой стабильную, обратно совместимую основу, подходящую для корпоративных нагрузок. Вот что нового и улучшенного появилось с момента релиза v0.2:

Абстракция транспортного уровня и HttpMcpTransport: Мы представили чистую абстракцию транспортного уровня наряду с HttpMcpTransport. Эта функция отделяет логику основного протокола от базовых HTTP-клиентов, упрощая замену сетевых реализаций или настройку пула соединений.

Абстракция транспортного уровня и HttpMcpTransport: Мы представили чистую абстракцию транспортного уровня наряду с HttpMcpTransport. Эта функция отделяет логику основного протокола от базовых HTTP-клиентов, упрощая замену сетевых реализаций или настройку пула соединений.

Разделение аутентификации клиента: Для упрощения соблюдения корпоративных требований безопасности аутентификация клиента теперь отделена с помощью классов CredentialsProvider и AuthMethods. Учетные данные разрешаются асинхронно при каждом запросе, поэтому команды могут динамически обновлять токены или подключать свой собственный источник токенов (Google OIDC через ADC поставляется «из коробки», для всего остального достаточно реализовать интерфейс из одного метода).

Разделение аутентификации клиента: Для упрощения соблюдения корпоративных требований безопасности аутентификация клиента теперь отделена с помощью классов CredentialsProvider и AuthMethods. Учетные данные разрешаются асинхронно при каждом запросе, поэтому команды могут динамически обновлять токены или подключать свой собственный источник токенов (Google OIDC через ADC поставляется «из коробки», для всего остального достаточно реализовать интерфейс из одного метода).

Поддержка параметров по умолчанию: Встроенная поддержка значений по умолчанию в параметрах инструментов, что уменьшает размер полезной нагрузки промптов и повышает надежность агентов.

Поддержка параметров по умолчанию: Встроенная поддержка значений по умолчанию в параметрах инструментов, что уменьшает размер полезной нагрузки промптов и повышает надежность агентов.

Удаление привязанных параметров: Чувствительные параметры, которые привязываются на стороне сервера (например, tenant_id), теперь автоматически удаляются из определений инструментов, чтобы LLM не могла ими манипулировать.

Удаление привязанных параметров: Чувствительные параметры, которые привязываются на стороне сервера (например, tenant_id), теперь автоматически удаляются из определений инструментов, чтобы LLM не могла ими манипулировать.

Выбор версии и отслеживание сессий: Стандартизированный выбор версии MCP и надежное отслеживание сессий обеспечивают согласованное согласование протокола и жизненные циклы состояния диалога.

Выбор версии и отслеживание сессий: Стандартизированный выбор версии MCP и надежное отслеживание сессий обеспечивают согласованное согласование протокола и жизненные циклы состояния диалога.

Предупреждения об открытой передаче учетных данных HTTP: Добавлено встроенное обнаружение, которое предупреждает вас во время выполнения, если учетные данные передаются через незашифрованное HTTP-соединение.

Предупреждения об открытой передаче учетных данных HTTP: Добавлено встроенное обнаружение, которое предупреждает вас во время выполнения, если учетные данные передаются через незашифрованное HTTP-соединение.

Универсальная карта заголовков клиента: Легко добавляйте пользовательские корпоративные прокси-заголовки, идентификаторы трассировки транзакций или метаданные корреляции ко всем исходящим запросам.

Универсальная карта заголовков клиента: Легко добавляйте пользовательские корпоративные прокси-заголовки, идентификаторы трассировки транзакций или метаданные корреляции ко всем исходящим запросам.

Начало работы с Java SDK v1.0

Мы разработали MCP Toolbox Java SDK так, чтобы он был максимально удобным для корпоративных команд. Просто добавьте следующую зависимость в ваш pom.xml:

Пример из реальной практики: Автономный консьерж по транспорту

Чтобы продемонстрировать возможности Java SDK в сочетании с AlloyDB, давайте рассмотрим корпоративный сценарий использования.

Знакомьтесь: Cymbal Transit, вымышленная сеть междугородних автобусов. Клиенты не хотят кликать по вложенным выпадающим меню, чтобы спланировать поездку. Они хотят спросить:

«Мне нужно добраться из Нью-Йорка в Бостон завтра утром. Могу ли я взять с собой золотистого ретривера? Если да, забронируй мне самый быстрый рейс».

Чтобы ответить на этот вопрос, ИИ-агент должен сопоставить неструктурированные данные (правила перевозки животных) со структурированными данными (расписания и наличие мест) и выполнить транзакцию (бронирование) — и все это при сохранении контекста диалога.

Основа: Схема AlloyDB с нативными эмбеддингами

Мы использовали AlloyDB для этой реализации, потому что он нативно обрабатывает реляционные данные и многомерные векторы. Настройте таблицы базы данных с помощью этих инструкций:

lang-sql

Сопоставление намерений с SQL: tools.yaml

MCP Toolbox позволяет безопасно определять пользовательские инструменты. Вместо предоставления LLM прямого доступа к базе данных, конфигурация tools.yaml сопоставляет намерения на естественном языке напрямую с параметризованными, безопасными запросами:

Полный YAML-файл можно найти в файле в репозитории mcp-toolbox-sdk-java.

Архитектура агента с сохранением состояния в Spring Boot

Самая сложная часть создания разговорного ИИ в корпоративных приложениях — это управление состоянием: когда пользователь спрашивает: «Какие есть свободные часы?», а затем добавляет: «Забронируй на 8 утра», агент должен помнить предыдущий контекст на протяжении всего диалога.

Используя Java MCP Toolbox SDK вместе со Spring Boot и LangChain4j, мы можем аккуратно поддерживать историю диалога в HTTP-сессии и четко разделить агента на два декларативных компонента:

Декларативный интерфейс агента, который управляет промптом, инструментами и историей диалога через HTTP-сессию.

Декларативный интерфейс агента, который управляет промптом, инструментами и историей диалога через HTTP-сессию.

Сервис выполнения инструментов, который направляет запросы агента напрямую к серверу MCP Toolbox.

Сервис выполнения инструментов, который направляет запросы агента напрямую к серверу MCP Toolbox.

Обратите внимание, как аннотация @MemoryId абстрагирует отслеживание сессии: Spring Boot автоматически сопоставляет контекст диалога с HTTP-сессией пользователя. Тем временем LangChain4j и MCP Toolbox берут на себя преобразование схем и маршрутизацию инструментов — никакого ручного разбора намерений через if/else не требуется.

Сочетая Java SDK для MCP Toolbox с LangChain4j, мы достигаем четкого разделения ответственности и простого управления состоянием:

Управление сессиями без лишнего кода: параметр @MemoryId String sessionId привязывает историю диалога напрямую к HTTP-сессии пользователя.

Управление сессиями без лишнего кода: параметр @MemoryId String sessionId привязывает историю диалога напрямую к HTTP-сессии пользователя.

Декларативный контракт агента: интерфейс TransitAgent определяет личность модели и системные инструкции без сложных шаблонов промптов.

Декларативный контракт агента: интерфейс TransitAgent определяет личность модели и системные инструкции без сложных шаблонов промптов.

Типобезопасное выполнение инструментов: Spring-сервис TransitAgentTools оборачивает удаленные инструменты базы данных MCP в виде нативных методов Java.

Типобезопасное выполнение инструментов: Spring-сервис TransitAgentTools оборачивает удаленные инструменты базы данных MCP в виде нативных методов Java.

Эта архитектура гарантирует модульность вашего агента: вы можете уточнять инструкции промпта в интерфейсе, автоматически управлять пользовательскими сессиями и выполнять безопасные запросы к базе данных через MCP Toolbox без жесткой связности.

Соединяем точки: перечисление, вызов и выполнение инструментов в Java v1.0

Теперь давайте заглянем «под капот» интерфейса TransitAgentTools. Внутри методов @Tool библиотеки LangChain4j в нашем Spring @Service, Java SDK для MCP Toolbox берет на себя всю тяжелую работу, связывая методы вашего Java-сервиса с инструментами MCP, определенными в файле tools.yaml. Всего за несколько строк типобезопасного кода мы можем инициализировать наш клиент, используя новые абстракции для аутентификации и заголовков версии 1.0:

Безопасность по умолчанию: аутентификация и развертывание

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

Application Default Credentials (ADC) и безопасность

Используя сервис GoogleCredentialsProvider, ваше Java-приложение наследует безопасную идентификацию от среды выполнения (локально или в Google Cloud) через Application Default Credentials (ADC) — никаких жестко закодированных ключей, а OIDC-токены создаются и кэшируются для каждой аудитории автоматически. Кроме того, версия 1.0 предлагает предупреждения об утечке учетных данных по HTTP, которые автоматически обнаруживают попытки передачи учетных данных через незашифрованное HTTP-соединение и выдают предупреждение во время выполнения, предлагая переключиться на HTTPS.

Развертывание парка агентов на Cloud Run

Поскольку MCP Toolbox и агент на Spring Boot полностью разделены, они масштабируются независимо на Google Cloud Run, чтобы соответствовать требованиям высокой параллельности и сохранения состояния диалогов.

Чтобы настроить Toolbox на Cloud Run, скачайте open-source версию MCP Toolbox для баз данных, а затем следуйте руководству по развертыванию.

Начните сегодня

С Java SDK для MCP Toolbox версии 1.0 корпоративные Java-команды могут подключать агентов на Spring Boot и LangChain4j к серверу Toolbox, а через него — к AlloyDB и любому другому поддерживаемому источнику данных. Когда вы используете toolbox, аргументы проверяются на соответствие определению инструмента до того, как они покинут JVM, аутентификация отделена, а пользовательские заголовки добавляются к каждому исходящему запросу. Следующие шаги помогут вам начать работу.

Шаг 1: Добавьте зависимость

Чтобы начать разработку с использованием SDK, добавьте следующую зависимость в файл pom.xml вашего Maven-проекта:

Автоматическое отслеживание версий

Если вы копируете эту настройку в автоматизированные внутренние репозитории, сохраните XML-комментарий  без изменений. Он необходим скриптам развертывания менеджера релизов для автоматического обновления версий.

Теперь, когда вы можете интегрировать современные агентские инструменты и серверы в свои корпоративные Java-приложения с помощью стабильного Java SDK для MCP Toolbox, начните работу уже сегодня!