О практической работе
1. Обзор
Агент — это автономная программа, которая взаимодействует с моделью искусственного интеллекта для выполнения целевой операции, используя имеющиеся у нее инструменты и контекст, и способна принимать автономные решения, основанные на истине!
Когда в вашем приложении несколько агентов работают автономно и сообща по мере необходимости для достижения его более масштабной цели, при этом каждый из агентов обладает независимыми знаниями и отвечает за определенную область деятельности, то ваше приложение становится многоагентной системой .
Комплект для разработки агента (ADK)
Agent Development Kit (ADK) — это гибкая и модульная структура для разработки и развертывания агентов ИИ. ADK поддерживает создание сложных приложений путем объединения нескольких отдельных экземпляров агентов в многоагентную систему (MAS).
В ADK многоагентная система — это приложение, в котором различные агенты, часто образующие иерархию, сотрудничают или координируют работу для достижения более крупной цели. Структурирование приложения таким образом дает значительные преимущества, включая улучшенную модульность, специализацию, возможность повторного использования, удобство обслуживания и возможность определять структурированные потоки управления с помощью выделенных агентов рабочих процессов.
Что следует учитывать при работе с многоагентной системой
Во-первых , важно иметь правильное понимание и обоснование специализации каждого агента. — «Знаете ли вы, почему вам нужен определенный субагент для чего-либо», выясните это в первую очередь.
Во-вторых , как объединить их с корневым агентом для маршрутизации и осмысления каждого из ответов.
В-третьих , существует несколько типов маршрутизации агентов, которые вы можете найти здесь, в этой документации. Убедитесь, что какой из них подходит потоку вашего приложения. Также какие различные контексты и состояния вам нужны для управления потоком вашей многоагентной системы.
Что вы построите
Давайте создадим многоагентную систему для управления ремонтом кухни с использованием MCP Toolbox для AlloyDB и ADK.
- Агент по предложениям по реконструкции
- Агент по проверке разрешений и соответствия
- Проверка статуса заказа (инструмент с использованием MCP Toolbox for Databases)
Агент по предложениям по ремонту, для составления документа предложения по ремонту кухни.
Агент по разрешениям и соблюдению нормативных требований, который будет заниматься вопросами, связанными с разрешениями и соблюдением нормативных требований.
Order Status Check Agent, для проверки статуса заказа материалов, работая с базой данных управления заказами, которую мы настроили в AlloyDB. Но для этой части базы данных мы будем использовать MCP Toolbox для AlloyDB для реализации логики поиска статуса для заказов.
2. МКП
MCP означает Model Context Protocol, открытый стандарт, разработанный Anthropic, который обеспечивает согласованный способ подключения агентов ИИ к внешним инструментам, сервисам и данным. По сути, он функционирует как общий стандарт для приложений ИИ, позволяя им беспрепятственно взаимодействовать с различными источниками данных и инструментами.
- Он использует модель клиент-сервер, в которой приложения ИИ (хосты) запускают клиент MCP, который взаимодействует с серверами MCP.
- Когда агенту ИИ требуется доступ к определенному инструменту или данным, он отправляет структурированный запрос клиенту MCP, который пересылает его на соответствующий сервер MCP.
- Позволяет моделям ИИ получать доступ к внешним данным и инструментам без необходимости написания специального кода для каждой интеграции.
- Упрощает процесс создания агентов и сложных рабочих процессов на основе больших языковых моделей (LLM).
MCP Toolbox для баз данных
MCP Toolbox for Databases от Google — это сервер MCP с открытым исходным кодом для баз данных. Он был разработан с учетом корпоративного уровня и качества производства. Он позволяет вам разрабатывать инструменты проще, быстрее и безопаснее, справляясь со сложностями, такими как пул соединений, аутентификация и т. д.
Позвольте вашим агентам получить доступ к данным в вашей базе данных!!! Как?
Упрощенная разработка: интегрируйте инструменты в свой агент менее чем в 10 строк кода, повторно используйте инструменты между несколькими агентами или фреймворками и с легкостью развертывайте новые версии инструментов.
Лучшая производительность: лучшие практики, такие как пул соединений, аутентификация и многое другое.
Повышенная безопасность: интегрированная аутентификация для более безопасного доступа к вашим данным
Сквозное наблюдение: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.
Приходится указывать на тот факт, что это предшествовало MCP!!!
MCP Toolbox for Databases располагается между фреймворком оркестровки вашего агентского приложения и вашей базой данных, предоставляя плоскость управления, которая используется для изменения, распространения или вызова инструментов. Он упрощает управление вашими инструментами, предоставляя вам централизованное место для хранения и обновления инструментов, позволяя вам совместно использовать инструменты между агентами и приложениями и обновлять эти инструменты без необходимости повторного развертывания вашего приложения.
У нас будет корневой агент, который будет координировать работу этих агентов в зависимости от требований.
Требования
3. Прежде чем начать
Создать проект
- В Google Cloud Console на странице выбора проекта выберите или создайте проект Google Cloud.
- Убедитесь, что для вашего проекта Cloud включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
Также, если вы читаете это и хотите получить кредиты, которые помогут вам начать работу с Google Cloud и использовать ADK, используйте эту ссылку для погашения кредитов. Вы можете следовать инструкциям здесь , чтобы погасить его. Обратите внимание, что эта ссылка действительна только до конца мая для погашения.
- Активируйте Cloud Shell, нажав на эту ссылку . Вы можете переключаться между Cloud Shell Terminal (для запуска облачных команд) и Editor (для создания проектов), нажав на соответствующую кнопку в Cloud Shell.
- После подключения к Cloud Shell вы проверяете, что вы уже аутентифицированы и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:
gcloud auth list
- Выполните следующую команду в Cloud Shell, чтобы подтвердить, что команда gcloud знает о вашем проекте.
gcloud config list project
- Если ваш проект не настроен, используйте следующую команду для его настройки:
gcloud config set project <YOUR_PROJECT_ID>
- Включите следующие API, выполнив следующие команды:
gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com \alloydb.googleapis.com
- Убедитесь, что у вас установлен Python 3.9+.
- Информацию о командах и использовании gcloud см. в документации .
4. Настройка ADK
- Создать и активировать виртуальную среду (рекомендуется)
Создайте виртуальную среду в терминале Cloud Shell:
python -m venv .venv
Активируйте виртуальную среду:
source .venv/bin/activate
- Установить АДК
pip install google-adk
5. Структура проекта
- В Cloud Shell Terminal выполните следующие команды одну за другой, чтобы создать корневые папки и папки проектов:
mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent
- Перейдите в редактор Cloud Shell и создайте следующую структуру проекта, создав файлы (пустые для начала):
renovation-agent/
__init__.py
agent.py
.env
6. Исходный код
- Перейдите в init .py и обновите следующим содержимым:
from . import agent
- Перейдите в agent.py и обновите файл следующим содержимым по следующему пути:
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py
В agent.py мы импортируем необходимые зависимости, извлекаем параметры конфигурации из файла .env и определяем root_agent, который использует 1 инструмент для вызова инструментария.
- Перейдите в файл requirements.txt и обновите его следующим содержимым:
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt
7. Настройка базы данных
В одном из инструментов, используемых ordering_agent, называемом "check_status", мы обращаемся к базе данных заказов AlloyDB, чтобы получить статус заказов. В этом разделе мы настроим кластер и экземпляр базы данных AlloyDB .
Создать кластер и экземпляр
- Перейдите на страницу AlloyDB в Cloud Console. Самый простой способ найти большинство страниц в Cloud Console — воспользоваться строкой поиска консоли.
- Выберите СОЗДАТЬ КЛАСТЕР на этой странице:
- Вы увидите экран, подобный показанному ниже. Создайте кластер и экземпляр со следующими значениями (убедитесь, что значения совпадают, если вы клонируете код приложения из репозитория):
- идентификатор кластера : "
vector-cluster" - пароль : "
alloydb" - Совместимость с PostgreSQL 16 / рекомендуется использовать последнюю версию
- Регион : "
us-central1" - Сетевое взаимодействие : "
default"
- При выборе сети по умолчанию вы увидите экран, подобный показанному ниже.
Выберите НАСТРОЙКА ПОДКЛЮЧЕНИЯ . 
- Оттуда выберите « Использовать автоматически выделенный диапазон IP-адресов » и «Продолжить». После просмотра информации выберите «СОЗДАТЬ ПОДКЛЮЧЕНИЕ».
6. ВАЖНОЕ ПРИМЕЧАНИЕ: Обязательно измените идентификатор экземпляра (который вы можете найти во время настройки кластера/экземпляра) на
vector-instance . Если вы не можете его изменить, не забудьте использовать идентификатор вашего экземпляра во всех последующих ссылках.
- В рамках подготовки к настройке Toolbox давайте включим подключение по публичному IP-адресу в нашем экземпляре AlloyDB, чтобы новый инструмент мог получить доступ к базе данных.
- Перейдите в раздел «Подключение по публичному IP», установите флажок «Включить публичный IP» и введите IP-адрес вашего компьютера Cloud Shell.
- Чтобы получить IP вашего компьютера Cloud Shell, перейдите в Cloud Shell Terminal и введите ifconfig. Из результата определите адрес eth0 inet и замените последние 2 цифры на 0.0 с размером маски '/16'. Например, это будет выглядеть как "XX.XX.0.0/16", где XX — это числа.
- Вставьте этот IP-адрес в текстовое поле «Сети» авторизованных внешних сетей на странице редактирования экземпляра.
- После настройки сети вы можете продолжить создание кластера. Нажмите CREATE CLUSTER, чтобы завершить настройку кластера, как показано ниже:
Обратите внимание, что создание кластера займет около 10 минут. После успешного завершения вы должны увидеть экран, на котором будет показан обзор вашего кластера, который вы только что создали.
Прием данных
Теперь пришло время добавить таблицу с данными о магазине. Перейдите в AlloyDB, выберите основной кластер, а затем AlloyDB Studio:
Возможно, вам придется подождать, пока ваш экземпляр не будет создан. После этого войдите в AlloyDB, используя учетные данные, которые вы создали при создании кластера. Используйте следующие данные для аутентификации в PostgreSQL:
- Имя пользователя: "
postgres" - База данных: "
postgres" - Пароль: "
alloydb"
После успешной аутентификации в AlloyDB Studio, команды SQL вводятся в редакторе. Вы можете добавить несколько окон редактора, используя плюс справа от последнего окна.
Команды для AlloyDB вы будете вводить в окнах редактора, используя при необходимости параметры «Выполнить», «Форматировать» и «Очистить».
Создать таблицу
Вы можете создать таблицу с помощью приведенного ниже оператора DDL в AlloyDB Studio:
-- 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.
- Перейдите в свой Cloud Shell Terminal и убедитесь, что ваш проект выбран и отображается в строке терминала. Выполните следующую команду из вашего Cloud Shell Terminal, чтобы перейти в каталог вашего проекта:
cd adk-renovation-agent
- Выполните следующую команду, чтобы загрузить и установить 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
- Перейдите в редактор 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
Источники представляют собой различные источники данных, с которыми может взаимодействовать инструмент. Источник представляет собой источник данных, с которым может взаимодействовать инструмент. Вы можете определить Источники как карту в разделе источников вашего файла tools.yaml. Обычно конфигурация источника будет содержать любую информацию, необходимую для подключения и взаимодействия с базой данных.
Инструменты определяют действия, которые может выполнять агент, например, чтение и запись в источник. Инструмент представляет действие, которое может выполнять ваш агент, например, выполнение оператора SQL. Вы можете определить Инструменты как карту в разделе инструментов вашего файла tools.yaml. Обычно инструменту требуется источник для выполнения действий.
Более подробную информацию о настройке tools.yaml можно найти в этой документации .
Давайте запустим MCP Toolbox for Databases Server.
Для запуска сервера выполните следующую команду (из папки 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. Это даст нам публичную конечную точку, которую мы сможем интегрировать с любым другим приложением и/или приложениями Agent. Инструкции по размещению этого в Cloud Run приведены здесь . Теперь мы рассмотрим основные шаги.
- Запустите новый Cloud Shell Terminal или используйте существующий Cloud Shell Terminal. Перейдите в папку проекта, где находятся бинарный файл toolbox и tools.yaml, в данном случае adk-renovation-agent
- Установите переменную PROJECT_ID так, чтобы она указывала на ваш идентификатор проекта Google Cloud.
export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"
- Включите эти службы Google Cloud
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
- Давайте создадим отдельную учетную запись службы, которая будет действовать как идентификатор для службы Toolbox, которую мы будем развертывать в Google Cloud Run.
gcloud iam service-accounts create toolbox-identity
- Мы также гарантируем, что эта учетная запись службы будет иметь правильные роли, т.е. возможность доступа к 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
- Мы загрузим файл 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
- Последний шаг в знакомой команде развертывания в 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 Server с нашим настроенным 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 Tool к нашему Агенту!!!
Мы уже создали источник для нашего агентского приложения. Давайте обновим его, включив новый инструмент MCP Toolbox for Databases, который мы только что развернули в Cloud Run.
- Ознакомьтесь с файлом requirements.txt с исходным кодом из репозитория:
Мы включаем зависимость для MCP Toolbox for Databases в requirements.txt
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt
- Проверьте ваш файл agent.py с кодом из репозитория:
Мы включаем инструмент, который вызывает конечную точку панели инструментов для извлечения данных о заказе на конкретный заказанном материале.
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py
9. Настройка модели
Способность вашего агента понимать запросы пользователей и генерировать ответы основана на Large Language Model (LLM). Вашему агенту необходимо совершать безопасные вызовы к этой внешней службе LLM, для чего требуются учетные данные аутентификации. Без действительной аутентификации служба LLM отклонит запросы агента, и агент не сможет функционировать.
- Получите ключ API от Google AI Studio .
- На следующем этапе настройки файла .env замените
<<your API KEY>>на фактическое значение API KEY.
10. Настройка переменных ENV
- Установите значения параметров в файле шаблона .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. Запустите своего агента
- Используя терминал, перейдите в родительский каталог вашего проекта агента:
cd renovation-agent
- Установите зависимости:
pip install -r requirements.txt
- Для запуска агента вы можете выполнить следующую команду в терминале Cloud Shell:
adk run .
- Для запуска в веб-интерфейсе, предоставленном ADK, можно выполнить следующую команду:
adk web
- Протестируйте, используя следующие подсказки:
user>>
Hello. Check order status for Cement Bags.
13. Очистить
Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, использованные в этой публикации, выполните следующие действия:
- В консоли Google Cloud перейдите на страницу Управление ресурсами .
- В списке проектов выберите проект, который вы хотите удалить, и нажмите Удалить .
- В диалоговом окне введите идентификатор проекта, а затем нажмите «Завершить работу» , чтобы удалить проект.
14. Поздравления
Поздравляем! Вы успешно создали многоагентное приложение с использованием ADK и MCP Toolbox for Databases! Для получения дополнительной информации обратитесь к документации по продукту: Agent Development Kit и MCP Toolbox for Databases .