Создайте мультиагентное приложение с помощью MCP Toolbox для AlloyDB & АДК

1. Обзор

Агент — это автономная программа, которая взаимодействует с моделью искусственного интеллекта для выполнения целенаправленной операции, используя имеющиеся у неё инструменты и контекст, и способна принимать автономные решения, основанные на истине!

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

Комплект для разработки агентов (ADK)

Комплект разработки агентов (ADK) — это гибкая и модульная платформа для разработки и развертывания агентов искусственного интеллекта. ADK поддерживает создание сложных приложений путем объединения нескольких отдельных экземпляров агентов в многоагентную систему (MAS).

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

Что следует учитывать при проектировании многоагентной системы

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

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

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

Что вы построите

Давайте создадим многоагентную систему для управления ремонтом кухни, используя MCP Toolbox для AlloyDB и ADK.

1. Агент по подготовке предложений по реконструкции
2. Агент по проверке разрешений и соответствия требованиям
3. Проверка статуса заказа (инструмент, использующий MCP Toolbox для баз данных)

Специалист по подготовке предложений по ремонту, занимающийся составлением проектной документации на ремонт кухни.

Специалист по выдаче разрешений и соблюдению нормативных требований, занимающийся вопросами, связанными с разрешениями и соблюдением нормативных требований.

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

2. MCP

MCP расшифровывается как Model Context Protocol (протокол контекста модели) — открытый стандарт, разработанный компанией Anthropic, который обеспечивает согласованный способ взаимодействия агентов ИИ с внешними инструментами, сервисами и данными. По сути, он функционирует как общий стандарт для приложений ИИ, позволяя им беспрепятственно взаимодействовать с различными источниками данных и инструментами.

1. В ней используется клиент-серверная модель, где приложения искусственного интеллекта (хост-серверы) запускают клиент MCP, который взаимодействует с серверами MCP.
2. Когда агенту ИИ необходимо получить доступ к определенному инструменту или данным, он отправляет структурированный запрос клиенту MCP, который перенаправляет его на соответствующий сервер MCP.
3. Позволяет моделям ИИ получать доступ к внешним данным и инструментам без необходимости написания собственного кода для каждой интеграции.
4. Упрощает процесс создания агентов и сложных рабочих процессов на основе больших языковых моделей (LLM).

MCP Toolbox для баз данных

Google MCP Toolbox for Databases — это MCP-сервер с открытым исходным кодом для работы с базами данных. Он разработан с учетом требований корпоративного и производственного уровня. Он позволяет разрабатывать инструменты проще, быстрее и безопаснее, обрабатывая такие сложные процессы, как пулы соединений, аутентификация и многое другое.

Предоставьте вашим агентам доступ к данным в вашей базе данных!!! Как?

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

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

Повышенная безопасность: интегрированная аутентификация для более безопасного доступа к вашим данным.

Сквозная мониторинговая возможность: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.

Необходимо отметить, что это предшествовало появлению MCP!!!

MCP Toolbox for Databases находится между системой оркестрации вашего агентского приложения и вашей базой данных, предоставляя плоскость управления, используемую для изменения, распространения или вызова инструментов. Он упрощает управление инструментами, предоставляя централизованное место для хранения и обновления инструментов, позволяя обмениваться инструментами между агентами и приложениями и обновлять эти инструменты без необходимости повторного развертывания приложения.

У нас будет корневой агент, который будет координировать работу этих агентов в зависимости от потребностей.

Требования

• Браузер, например Chrome или Firefox.
• Проект Google Cloud с включенной функцией выставления счетов.

3. Прежде чем начать

Создать проект

1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Также, если вы читаете это и хотели бы получить бонусы, которые помогут вам начать работу с Google Cloud и использовать ADK, воспользуйтесь этой ссылкой для активации бонусов. Вы можете следовать инструкциям здесь, чтобы активировать их. Обратите внимание, что эта ссылка действительна только до конца мая.

3. Активируйте Cloud Shell, перейдя по этой ссылке . Вы можете переключаться между терминалом Cloud Shell (для выполнения облачных команд) и редактором (для сборки проектов), нажав соответствующую кнопку в Cloud Shell.
4. После подключения к Cloud Shell необходимо проверить, прошли ли вы аутентификацию и установлен ли идентификатор вашего проекта, используя следующую команду:

gcloud auth list

5. Выполните следующую команду в Cloud Shell, чтобы убедиться, что команда gcloud знает о вашем проекте.

gcloud config list project

6. Если ваш проект не задан, используйте следующую команду для его установки:

gcloud config set project <YOUR_PROJECT_ID>

7. Включите следующие API, выполнив следующие команды:

gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com \alloydb.googleapis.com

8. Убедитесь, что у вас установлен Python 3.9 или более поздней версии.
9. Для получения информации о командах gcloud и их использовании обратитесь к документации .

4. Настройка ADK

1. Создание и активация виртуальной среды (рекомендуется)

Создайте виртуальную среду в терминале Cloud Shell:

python -m venv .venv

Активируйте виртуальную среду:

source .venv/bin/activate

2. Установите ADK

pip install google-adk

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

3. В терминале Cloud Shell выполните следующие команды по очереди, чтобы создать корневую папку и папку проекта:

mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent

4. Перейдите в редактор Cloud Shell и создайте следующую структуру проекта, создав файлы (изначально пустые):

renovation-agent/
        __init__.py
        agent.py
        .env

6. Исходный код

1. Перейдите в файл init.py и обновите его следующим содержимым:

from . import agent

2. Перейдите в файл agent.py и обновите его, добавив следующее содержимое из следующего пути:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

В файле agent.py мы импортируем необходимые зависимости, получаем параметры конфигурации из файла .env и определяем root_agent, который использует 1 инструмент для вызова инструмента из панели инструментов.

3. Перейдите в файл requirements.txt и обновите его, добавив содержимое из следующего списка:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

7. Настройка базы данных

В одном из инструментов, используемых ordering_agent, называемом "check_status", мы обращаемся к базе данных заказов AlloyDB, чтобы получить статус заказов. В этом разделе мы настроим кластер и экземпляр базы данных AlloyDB .

Создайте кластер и экземпляр.

1. Перейдите на страницу AlloyDB в Cloud Console. Большинство страниц в Cloud Console легко найти, используя строку поиска консоли.
2. На этой странице выберите пункт «СОЗДАТЬ КЛАСТЕР» :

3. Вы увидите экран, похожий на тот, что показан ниже. Создайте кластер и экземпляр со следующими значениями (убедитесь, что значения совпадают, если вы клонируете код приложения из репозитория):

• идентификатор кластера : " vector-cluster "
• пароль : " alloydb "
• Рекомендуется использовать PostgreSQL, совместимый с версией 16 , или любую последнюю версию.
• Регион : " us-central1 "
• Сетевые настройки : " default "

4. При выборе сети по умолчанию вы увидите экран, похожий на тот, что показан ниже.

Выберите «НАСТРОЙКА СОЕДИНЕНИЯ» .

5. Затем выберите « Использовать автоматически выделенный диапазон IP-адресов » и продолжите. После проверки информации выберите «СОЗДАТЬ СОЕДИНЕНИЕ».

6. ВАЖНОЕ ПРИМЕЧАНИЕ: Обязательно измените идентификатор экземпляра (который можно найти во время настройки кластера/экземпляра) на

vector-instance . Если вы не можете его изменить, не забудьте использовать свой идентификатор экземпляра во всех последующих ссылках.

7. В рамках подготовки к настройке Toolbox давайте включим подключение по публичному IP-адресу в нашем экземпляре AlloyDB, чтобы новый инструмент мог получить доступ к базе данных.
8. Перейдите в раздел «Подключение по общедоступному IP-адресу», установите флажок «Включить общедоступный IP-адрес» и введите IP-адрес вашей машины Cloud Shell.
9. Чтобы узнать IP-адрес вашей машины Cloud Shell, перейдите в терминал Cloud Shell и введите команду `ifconfig`. В результате найдите IP-адрес eth0 и замените последние 2 цифры на 0.0 с маской '/16'. Например, это будет выглядеть так: "XX.XX.0.0/16", где XX — числа.
10. Вставьте этот IP-адрес в текстовое поле «Авторизованные внешние сети» в разделе «Сети» на странице редактирования экземпляра.

4. После настройки сети вы можете продолжить создание кластера. Нажмите кнопку «СОЗДАТЬ КЛАСТЕР», чтобы завершить настройку кластера, как показано ниже:

Обратите внимание, что создание кластера займет около 10 минут. После успешного завершения процесса вы увидите экран с обзором только что созданного кластера.

Ввод данных

Теперь пришло время добавить таблицу с данными о магазине. Перейдите в AlloyDB, выберите основной кластер, а затем AlloyDB Studio:

Возможно, вам потребуется дождаться завершения создания экземпляра. После этого войдите в AlloyDB, используя учетные данные, которые вы создали при создании кластера. Для аутентификации в PostgreSQL используйте следующие данные:

• Имя пользователя: " postgres "
• База данных: " postgres "
• Пароль: " alloydb "

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

Команды для AlloyDB будут вводиться в окнах редактора, используя при необходимости параметры «Выполнить», «Форматировать» и «Очистить».

Создайте таблицу

В AlloyDB Studio можно создать таблицу, используя приведенный ниже оператор DDL:

-- Table DDL for Procurement Material Order Status

CREATE TABLE material_order_status (
    order_id VARCHAR(50) PRIMARY KEY,
    material_name VARCHAR(100) NOT NULL,
    supplier_name VARCHAR(100) NOT NULL,
    order_date DATE NOT NULL,
    estimated_delivery_date DATE,
    actual_delivery_date DATE,
    quantity_ordered INT NOT NULL,
    quantity_received INT,
    unit_price DECIMAL(10, 2) NOT NULL,
    total_amount DECIMAL(12, 2),
    order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
    delivery_address VARCHAR(255),
    contact_person VARCHAR(100),
    contact_phone VARCHAR(20),
    tracking_number VARCHAR(100),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    quality_check_passed BOOLEAN,  -- Indicates if the material passed quality control
    quality_check_notes TEXT,        -- Notes from the quality control check
    priority VARCHAR(20),            -- e.g., "High", "Medium", "Low"
    project_id VARCHAR(50),          -- Link to a specific project
    receiver_name VARCHAR(100),        -- Name of the person who received the delivery
    return_reason TEXT,               -- Reason for returning material if applicable
    po_number VARCHAR(50)             -- Purchase order number
);

Вставить записи

Скопируйте оператор запроса insert из указанного выше скрипта database_script.sql в редактор.

Нажмите «Выполнить» .

Теперь, когда набор данных готов, давайте настроим MCP Toolbox for Databases, чтобы он выступал в качестве управляющей плоскости для всех наших взаимодействий с базой данных заказов в AlloyDB!!!

8. MCP Toolbox для настройки баз данных

Toolbox выступает посредником между системой оркестрации вашего приложения и базой данных, предоставляя плоскость управления, используемую для изменения, распространения или вызова инструментов. Он упрощает управление инструментами, предоставляя централизованное место для хранения и обновления инструментов, позволяя обмениваться инструментами между агентами и приложениями и обновлять эти инструменты без необходимости повторного развертывания приложения .

Как видите, одной из баз данных, поддерживаемых MCP Toolbox for Databases, является AlloyDB, и поскольку мы уже настроили её в предыдущем разделе, давайте перейдём к настройке Toolbox.

1. Откройте терминал Cloud Shell и убедитесь, что ваш проект выбран и отображается в командной строке. Выполните следующую команду в терминале Cloud Shell, чтобы перейти в каталог вашего проекта:

cd adk-renovation-agent

2. Выполните следующую команду, чтобы загрузить и установить Toolbox в новую папку:

# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. Перейдите в редактор Cloud Shell (для режима редактирования кода) и в корневой папке проекта добавьте файл с именем "tools.yaml".

sources:
    alloydb-orders:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "<<YOUR_ALLOYDB_CLUSTER>>"
        instance: "<<YOUR_ALLOYDB_INSTANCE>>"
        database: "<<YOUR_ALLOYDB_DATABASE>>"
        user: "<<YOUR_ALLOYDB_USER>>"
        password: "<<YOUR_ALLOYDB_PASSWORD>>"

tools:
  get-order-data:
    kind: postgres-sql
    source: alloydb-orders
    description: Get the status of an order based on the material description.
    parameters:
      - name: description
        type: string
        description: A description of the material to search for its order status.
    statement: |
      select order_status from material_order_status where lower(material_name) like lower($1) 
      LIMIT 1;

В части запроса (см. параметр "statement" выше) мы просто извлекаем значение поля order_status, когда название материала совпадает с поисковым запросом пользователя.

Давайте разберемся с файлом tools.yaml.

Источники представляют собой различные источники данных, с которыми может взаимодействовать инструмент. Источник — это источник данных, с которым может взаимодействовать инструмент. Вы можете определить источники в виде карты в разделе sources файла tools.yaml. Как правило, конфигурация источника содержит всю информацию, необходимую для подключения к базе данных и взаимодействия с ней.

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

Для получения более подробной информации о настройке файла tools.yaml обратитесь к этой документации .

Давайте запустим MCP Toolbox для серверов баз данных.

Для запуска сервера выполните следующую команду (из папки mcp-toolbox):

./toolbox --tools-file "tools.yaml"

Теперь, если вы откроете сервер в режиме веб-просмотра в облаке, вы сможете увидеть, что сервер Toolbox запущен и работает с вашим новым инструментом под названием get-order-data.

Сервер MCP Toolbox по умолчанию работает на порту 5000. Давайте протестируем это с помощью Cloud Shell.

В Cloud Shell нажмите на кнопку «Предварительный просмотр веб-страницы», как показано ниже:

Нажмите «Изменить порт» и установите порт на 5000, как показано ниже, затем нажмите «Изменить и просмотреть».

В результате должно получиться следующее:

В описании MCP Toolkit for Databases представлен Python SDK для проверки и тестирования инструментов, документация к которому находится здесь . Мы пропустим этот раздел и сразу перейдем к Agent Development Kit (ADK) в следующем разделе, где будут использоваться эти инструменты.

Давайте развернем наш Toolbox в Cloud Run.

Для начала мы можем разместить сервер MCP Toolbox на платформе Cloud Run. Это даст нам общедоступную конечную точку, которую мы сможем интегрировать с любыми другими приложениями и/или приложениями агентов. Инструкции по размещению на Cloud Run приведены здесь . Теперь рассмотрим основные шаги.

1. Запустите новый терминал Cloud Shell или используйте существующий. Перейдите в папку проекта, где находятся исполняемый файл toolbox и файл tools.yaml, в данном случае это adk-renovation-agent.
2. Установите переменную PROJECT_ID так, чтобы она указывала на идентификатор вашего проекта в Google Cloud.

export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"

3. Включите эти сервисы Google Cloud.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

4. Давайте создадим отдельную учетную запись службы, которая будет выступать в качестве идентификатора для службы Toolbox, которую мы будем развертывать в Google Cloud Run.

gcloud iam service-accounts create toolbox-identity

5. Мы также обеспечиваем наличие у этой учетной записи службы необходимых ролей, то есть возможности доступа к Secret Manager и взаимодействия с AlloyDB.

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/alloydb.client

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/serviceusage.serviceUsageConsumer

6. Мы загрузим файл tools.yaml в качестве секретного файла:

gcloud secrets create tools --data-file=tools.yaml

Если у вас уже есть секретный ключ и вы хотите обновить его версию, выполните следующие действия:

gcloud secrets versions add tools --data-file=tools.yaml

Установите переменную среды, указывающую на образ контейнера, который вы хотите использовать для Cloud Run:

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

7. Последний шаг в знакомой команде развертывания в Cloud Run:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

Это запустит процесс развертывания сервера Toolbox с настроенным файлом tools.yaml в Cloud Run. После успешного развертывания вы должны увидеть сообщение, похожее на следующее:

Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.                                                                                                                                                                                     
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
  OK Setting IAM Policy...                                                                                                                                                                                            
Done.                                                                                                                                                                                                                 
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app

Теперь вы полностью готовы использовать свой недавно развернутый инструмент в своем агентском приложении!!!

Давайте подключим инструмент Toolbox к нашему агенту!!!

Мы уже создали исходный код для нашего агентского приложения. Давайте обновим его, добавив новый инструмент MCP Toolbox for Databases, который мы только что развернули в Cloud Run.

1. Проверяйте содержимое файла requirements.txt, используя исходный код из репозитория:

Мы добавляем зависимость для MCP Toolbox for Databases в файл requirements.txt.

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

2. Проанализируйте файл agent.py с помощью кода из репозитория:

Мы добавляем инструмент, который вызывает конечную точку панели инструментов для получения данных о заказе конкретного материала.

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

9. Настройка модели

Способность вашего агента понимать запросы пользователей и генерировать ответы обеспечивается использованием модели большого языка (LLM). Вашему агенту необходимо совершать защищенные вызовы к этой внешней службе LLM, что требует аутентификации. Без действительной аутентификации служба LLM отклонит запросы агента, и агент не сможет работать.

1. Получите ключ API в Google AI Studio .
2. На следующем шаге, где вы будете настраивать файл .env, замените <<your API KEY>> на фактическое значение вашего API-ключа.

10. Настройка переменных окружения

1. Задайте значения параметров в файле шаблона .env. В моем случае файл .env содержит следующие переменные:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION=us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT=<<your project id>>
PROJECT_ID=<<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>

Замените заполнители своими ценностями.

11. Запустите своего агента

2. С помощью терминала перейдите в родительский каталог вашего проекта агента:

cd renovation-agent

3. Установите зависимости:

pip install -r requirements.txt

4. Для запуска агента в терминале Cloud Shell выполните следующую команду:

adk run .

5. Для запуска в веб-интерфейсе, подготовленном с помощью ADK, можно выполнить следующие действия:

adk web

6. Проверьте работу, используя следующие подсказки:

user>> 

Hello. Check order status for Cement Bags.

12. Результат

13. Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, использованные в этой статье, выполните следующие действия:

1. В консоли Google Cloud перейдите на страницу «Управление ресурсами» .
2. В списке проектов выберите проект, который хотите удалить, и нажмите кнопку «Удалить» .
3. В диалоговом окне введите идентификатор проекта, а затем нажмите «Завершить» , чтобы удалить проект.

14. Поздравляем!

Поздравляем! Вы успешно создали многоагентное приложение с использованием ADK и MCP Toolbox for Databases! Для получения дополнительной информации обратитесь к документации по продукту: Agent Development Kit и MCP Toolbox for Databases .