От прототипов к агентам с ADK

От прототипов к агентам с ADK

О практической работе

Последнее обновление: июн. 12, 2025

Авторы: Author: Abirami Sukumaran

1. Обзор

С чего начинается строительство с использованием ИИ сегодня? Для большинства из нас это часто начинается с простого вопроса: «Может ли модель действительно помочь решить эту проблему, о которой я думал?». Именно здесь вступает в дело Google AI Studio. Это место, где вы можете быстро создать прототип чего угодно. Я давно хотел переделать свою кухню, и я уверен, что Gemini может помочь, но я инженер, а не генеральный подрядчик. Я даже не уверен, что просить — нужно так много всего учесть: правила, приспособления и т. д. Так что давайте разберем это и попросим Gemini сгенерировать для нас суперподробную подсказку, затем сгенерировать полный план реконструкции, а также визуализировать реконструкцию! Но подождите. Как я могу на самом деле помочь бизнесу масштабироваться отсюда? Вступайте в АГЕНТСТВА!!!

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

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

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

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

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

Готовы перейти от нашего прототипа PROMPT к созданию агента??? Мы создадим агента, который поможет сгенерировать документ предложения для проекта по ремонту кухни. В рамках этой лабораторной работы вы:

1. Создайте простой агент для создания документа предложения по реконструкции с помощью ADK
2. Сохраните созданный документ с предложением по реконструкции в облачном хранилище.
3. Тестирование агента в Cloud Shell и в веб-выводе агента

Требования

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

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

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

1. В Google Cloud Console на странице выбора проекта выберите или создайте проект Google Cloud.
2. Убедитесь, что биллинг включен для вашего проекта Cloud. Узнайте, как проверить, включен ли биллинг в проекте .
3. Кроме того, если вы читаете это и хотите получить кредиты, которые помогут вам начать работу с Google Cloud и использовать ADK, воспользуйтесь этой ссылкой для погашения кредитов .
4. Вы можете следовать инструкциям здесь , чтобы выкупить его. Обратите внимание, что эта ссылка действительна только до 15 июля 2025 года для выкупа.
5. Активируйте Cloud Shell, нажав на эту ссылку . Вы можете переключаться между Cloud Shell Terminal (для запуска облачных команд) и Editor (для создания проектов), нажав на соответствующую кнопку в Cloud Shell.
6. После подключения к Cloud Shell вы проверяете, что вы уже аутентифицированы и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

7. Убедитесь, что у вас установлен Python 3.9+.

Информацию о других командах gcloud и их использовании см. в документации .

3. Прототип

Перейдите в Google AI Studio . Начните вводить подсказку. Вот моя подсказка:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

Отрегулируйте и настройте параметры с правой стороны, чтобы получить оптимальный отклик.

На основе этого простого описания Gemini сделал мне невероятно подробную подсказку для начала моего обновления! По сути, мы используем Gemini, чтобы получить еще лучшие ответы от AI Studio и наших моделей. Вы также можете выбрать различные модели для использования в зависимости от вашего варианта использования.

Мы выбрали Gemini 2.5 Pro. Это модель Thinking, что означает, что мы получаем еще больше выходных токенов, в данном случае до 65 тыс. токенов, для длинных анализов и подробных документов. Gemini thinking box появляется, когда вы включаете Gemini 2.5 Pro, который имеет собственные возможности рассуждения и может принимать длинные контекстные запросы.

Фрагмент ответа смотрите ниже:

AI Studio проанализировала мои данные и создала все эти вещи, такие как шкафы, столешницы, фартук, пол, раковину, связность, цветовую палитру и выбор материалов. Gemini даже ссылается на источники!

А теперь попробуйте воплотить эту идею в жизнь с помощью другой подсказки.

1. Скопируйте эту подсказку и вставьте ее в редактор подсказок:

Add flat and circular light accessories above the island area for my current kitchen in the attached image.

2. Прикрепите изображение вашей нынешней кухни (или вы можете использовать мое изображение-образец кухни ).
3. Измените модель на «Gemini 2.0 Flash Preview Image Generation», чтобы получить доступ к генерации изображений.

Я получил такой результат:

Вот в чем сила Близнецов!

От понимания видео до создания собственных изображений и обоснования реальной информации с помощью поиска Google — есть вещи, которые можно реализовать только с помощью Gemini.

Из AI Studio вы можете взять этот прототип, получить ключ API и масштабировать его в полноценное агентское приложение, используя возможности Vertex AI ADK.

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

Теперь перейдем к Cloud Shell Terminal, который мы активировали в разделе «Прежде чем начать»:

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

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

python -m venv .venv

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

source .venv/bin/activate

2. Установить АДК

pip install google-adk

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

3. В Cloud Shell Terminal создайте корневой каталог для ваших агентских приложений в желаемом месте проекта:

mkdir agentic-apps

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

mkdir renovation-agent

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

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

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

6. Перейдите в « init .py» и обновите следующим содержимым:

from . import agent

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

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

В agent.py мы импортируем необходимые зависимости, извлекаем параметры конфигурации из файла .env и определяем root_agent, который генерирует документ предложения и сохраняет его в Cloud Storage Bucket. Для выполнения шага Cloud Storage мы используем инструмент под названием store_pdf.

8. Убедитесь, что у вас есть Cloud Storage Bucket

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

https://cloud.google.com/storage/docs/creating-buckets#console

Назовите ваш контейнер " next-demo-store ". Если вы назовете его как-то иначе, не забудьте обновить значение STORAGE_BUCKET в файле .env (на этапе настройки переменных ENV).

9. Чтобы настроить доступ к хранилищу, перейдите в консоль Cloud Storage и выберите свое хранилище Storage Bucket (в нашем случае имя хранилища — «next-demo-storage»: https://console.cloud.google.com/storage/browser/next-demo-storage ).

Перейдите в Разрешения -> Просмотр участников -> Предоставить доступ. Выберите участников как "allUsers" и роль как "Пользователь объекта хранения".

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.

10. Создать список зависимостей

Список всех зависимостей в requirements.txt . Вы можете скопировать его из репозитория .

Объяснение исходного кода системы с одним агентом

Файл agent.py определяет структуру и поведение нашей многоагентной системы для ремонта кухни с использованием Agent Development Kit (ADK). Давайте разберем ключевые компоненты:

Определение агента

Корневой агент (Оркестратор): proposal_agent

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

Затем root_agent собирает ответы от инструментов и объединяет их, чтобы предоставить пользователю комплексный ответ. В этом случае у нас есть только один инструмент "store_pdf".

7. Поток данных и ключевые концепции

Пользователь инициирует запрос через интерфейс ADK (терминал или веб-интерфейс).

1. Запрос получен root_agent.
2. Root_agent анализирует запрос и направляет его инструменту по мере необходимости.
3. Инструмент «store_pdf» предназначен для записи отреставрированного текстового содержимого в PDF-файл, а затем его загрузки в облачное хранилище Google.
4. Затем ответ возвращается root_agent.
5. Root_agent объединяет ответы и предоставляет пользователю окончательный результат.

LLM (большие языковые модели)

Агенты в значительной степени полагаются на LLM для генерации текста, ответов на вопросы и выполнения задач по рассуждению. LLM — это «мозги», стоящие за способностью агентов понимать и отвечать на запросы пользователей. В этом приложении мы используем Gemini 2.5.

Облачное хранилище Google

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

Облачный запуск (необязательно)

OrderingAgent использует функцию Cloud Run для взаимодействия с AlloyDB. Cloud Run предоставляет бессерверную среду для выполнения кода в ответ на HTTP-запросы.

AlloyDB

Если вы используете OrderingAgent, вам необходимо настроить базу данных AlloyDB для хранения информации о заказах.

Файл .env

Файл .env хранит конфиденциальную информацию, такую ​​как ключи API, учетные данные базы данных и имена контейнеров. Крайне важно сохранить этот файл в безопасности и не передавать его в репозиторий. Он также хранит параметры конфигурации для агентов и вашего проекта Google Cloud. root_agent или вспомогательные функции обычно считывают значения из этого файла. Убедитесь, что все требуемые переменные правильно заданы в файле .env. Это включает имя контейнера Cloud Storage

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

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

1. Получите ключ API от Google AI Studio .
2. На следующем этапе настройки файла .env замените <<your API KEY>> на фактическое значение API KEY.

9. Настройка переменных ENV

3. Установите значения параметров в файле шаблона .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>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

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

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

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

cd agentic-apps/renovation-agent

5. Установить все зависимости

pip install -r requirements.txt

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

adk run .

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

adk web

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

user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Результат

Для команды adk run результат будет следующим:

...

Вы можете проверить, создан ли документ «Предложение о реконструкции» в облачном хранилище.

12. Очистить

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

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

13. Поздравления

Поздравляем! Вы успешно создали и взаимодействовали с вашим многоагентным приложением с помощью ADK! Многоагентная система предназначена для оптимизации процесса ремонта кухни путем автоматизации таких задач, как генерация предложений, проверка разрешений и отслеживание статуса заказа. У каждого агента есть определенная роль, а root_agent координирует их действия для предоставления комплексного решения. Система использует LLM, сервисы Google Cloud и потенциально внешние API для предоставления своей функциональности. Вот ссылка на документацию по продукту.