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

1. Обзор

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

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

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

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

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

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

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

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

Требования

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

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

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

  1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
  2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
  3. Кроме того, если вы читаете это и хотите получить кредиты, которые помогут вам начать работу с Google Cloud и использовать ADK, воспользуйтесь этой ссылкой для погашения кредитов .
  4. Инструкции по активации купона приведены здесь . Обратите внимание, что эта ссылка действительна только до 15 июля 2025 года.
  5. Активируйте Cloud Shell, перейдя по этой ссылке . Вы можете переключаться между Cloud Shell Terminal (для выполнения облачных команд) и Editor (для создания проектов), нажимая соответствующую кнопку в Cloud Shell.
  6. После подключения к Cloud Shell вы проверяете, что вы уже прошли аутентификацию и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды: 
gcloud auth list
  1. Выполните следующую команду в Cloud Shell, чтобы подтвердить, что команда gcloud знает о вашем проекте. 
gcloud config list project
  1. Если ваш проект не настроен, используйте следующую команду для его настройки: 
gcloud config set project <YOUR_PROJECT_ID>
  1. Убедитесь, что у вас установлен 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. Это модель «Мысли», которая позволяет получать ещё больше выходных токенов, в данном случае до 65 тысяч , для анализа длинных форм и создания подробных документов. Модуль «Мысли» Gemini доступен при включении Gemini 2.5 Pro, обладающего встроенными функциями рассуждений и способного обрабатывать длинные контекстные запросы.

Смотрите фрагмент ответа ниже:

4e4361663df80964.png

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

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

  1. Скопируйте эту подсказку и вставьте ее в редактор подсказок: 
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Прикрепите изображение вашей нынешней кухни (или вы можете использовать мое изображение-образец кухни ).
  2. Измените модель на «Gemini 2.0 Flash Preview Image Generation», чтобы получить доступ к генерации изображений.

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

fb33e7b1f6560a0c.png

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

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

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

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

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

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

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

python -m venv .venv

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

source .venv/bin/activate
  1. Установить ADK 
pip install google-adk

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

  1. В Cloud Shell Terminal создайте корневой каталог для ваших агентских приложений в желаемом месте проекта: 
mkdir agentic-apps
  1. Внутри основного каталога создайте одну папку, относящуюся к нашему текущему проекту: 
mkdir renovation-agent
  1. Перейдите в редактор Cloud Shell и создайте следующую структуру проекта, создав файлы (пустые для начала): 
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

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

  1. Перейдите в « init .py» и обновите следующим содержимым: 
from . import agent
  1. Перейдите в agent.py и обновите файл следующим содержимым по следующему пути:

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

ПРИМЕЧАНИЕ: В настоящее время PDF-файл НЕОТФОРМАТИРОВАН! В соответствии с запросом сообщества разработчиков , следующий фрагмент кода был добавлен сюда [не тестировался]. Можете смело добавлять его в метод store_pdf: 

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"
  1. Убедитесь, что у вас есть облачное хранилище.

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

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

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

  1. Чтобы настроить доступ к контейнеру, перейдите в консоль Cloud Storage и выберите ваш контейнер Storage (в нашем случае имя контейнера — «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.
  1. Создать список зависимостей

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

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

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

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

Корневой агент (Оркестратор): offer_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

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

Cloud Run (необязательно)

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

AlloyDB

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

.env-файл

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

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

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

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

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

  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>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

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

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

  1. Используя терминал, перейдите в родительский каталог вашего проекта агента: 
cd agentic-apps/renovation-agent
  1. Установить все зависимости 
pip install -r requirements.txt
  1. Для запуска агента вы можете выполнить следующую команду в терминале Cloud Shell: 
adk run .
  1. Для запуска в веб-интерфейсе, предоставляемом ADK, можно выполнить следующее:

Примечание: эту команду необходимо запустить ВНЕ папки проекта вашего агента, сделать один шаг за ее пределами и затем выполнить ее: 

adk web
  1. Протестируйте, используя следующие подсказки: 
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 результат будет следующим:

2703603a907329ae.png

ae56b38cc6da9afe.png

...

91452a4de933a75b.png

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

12. Развертывание в облаке.

  1. Создайте файл с именем Dockerfile внутри корневой папки проекта: 
cd agentic-apps/renovation-agent
  1. Скопируйте содержимое из репозитория GitHub 
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

в этот файл Dockerfile.

  1. Развертывание в Cloud Run с помощью следующей команды: 
adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

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

13. Уборка

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

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

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

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