От прототипов к агентам с 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 (для выполнения облачных команд) и редактором (для сборки проектов), нажав соответствующую кнопку в 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. Это модель Thinking, что означает, что мы получаем еще больше выходных токенов, в данном случае до 65 000 токенов, для длинных аналитических отчетов и подробной документации. Функция Thinking в 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, который мы активировали в разделе «Перед началом работы»:

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

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

python -m venv .venv

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

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

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

  1. В терминале Cloud Shell создайте корневой каталог для ваших агентских приложений в нужном месте расположения проекта: 
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, который генерирует документ с предложением и сохраняет его в хранилище Cloud Storage. Для выполнения шага с Cloud Storage мы используем инструмент под названием 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. Убедитесь, что у вас есть доступ к облачному хранилищу (Cloud Storage Bucket).

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

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

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

  1. Чтобы настроить доступ к хранилищу, перейдите в консоль Cloud 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 определяет структуру и поведение нашей многоагентной системы для ремонта кухни, использующей комплект разработки агентов (ADK). Давайте рассмотрим ключевые компоненты:

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

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

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

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

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

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

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

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

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

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

Используется для хранения сгенерированных документов по проектированию ремонта. Необходимо создать хранилище (bucket) и предоставить агентам необходимые права доступа к нему.

Запуск в облаке (необязательно)

Объект 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-ключа.

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

  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

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

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! Многоагентная система разработана для оптимизации процесса ремонта кухни путем автоматизации таких задач, как создание предложений, проверка разрешений и отслеживание статуса заказа. Каждый агент имеет определенную роль, а корневой агент координирует их действия для предоставления комплексного решения. Система использует LLM, сервисы Google Cloud и, возможно, внешние API для обеспечения своей функциональности. Вот ссылка на документацию по продукту.