Создание ИИ-агентов с помощью ADK: Основы

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

Добро пожаловать в первую часть серии «Создание ИИ-агентов с помощью ADK»! В этой серии практических занятий вы отправитесь в увлекательное путешествие по созданию собственного интеллектуального ИИ-агента с помощью набора инструментов Google Agent Development Kit (ADK).

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

Вы можете выполнить эту лабораторную работу как локально, так и в Google Cloud. Для наиболее стабильной работы рекомендуем использовать Cloud Shell из Google Cloud. Cloud Shell также предоставляет 5 ГБ постоянного хранилища в каталоге $HOME . Это удобно для хранения скриптов, файлов конфигурации или клонированных репозиториев.

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

Предпосылки

• Понимание концепций генеративного ИИ
• Базовые навыки программирования на Python
• Знакомство с командной строкой/терминалом

Чему вы научитесь

• Как настроить среду Python
• Как создать простого личного помощника с помощью ADK
• Как запустить, протестировать и отладить агент

Что вам понадобится

• Рабочий компьютер и надежный Wi-Fi
• Браузер, например Chrome , для доступа к Google Cloud Console
• Любопытный ум и стремление к обучению

Активируйте пробный платежный аккаунт

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

Для выполнения этой практической работы вам также понадобится активный платёжный аккаунт Google Cloud. Если у вас его ещё нет, выполните следующие действия, чтобы получить пробный платёжный аккаунт:

1. Откройте окно в режиме инкогнито в своем браузере.
2. Перейдите на этот портал выкупа
3. Войдите, используя свой личный аккаунт Gmail.
4. Следуйте пошаговым инструкциям портала.

2. Введение

Мир генеративного искусственного интеллекта (GenAI) стремительно развивается, и ИИ-агенты сейчас являются актуальной темой. ИИ-агент — это интеллектуальная компьютерная программа, разработанная для действий от вашего имени, подобно персональному помощнику. Он способен воспринимать цифровую среду, принимать решения и выполнять действия для достижения конкретных целей без прямого участия человека. Представьте его как проактивную, автономную сущность, способную обучаться и адаптироваться для достижения поставленных целей.

По сути, ИИ-агент использует большую языковую модель (LLM) в качестве своего «мозга» для понимания и рассуждения. Это позволяет ему обрабатывать информацию из различных источников, таких как текст, изображения и звуки. Затем агент использует это понимание для разработки плана и выполнения ряда задач для достижения заранее определённой цели.

Теперь вы можете легко создавать собственных ИИ-агентов, даже не обладая глубокими знаниями, благодаря готовым фреймворкам, таким как Agent Development Kit (ADK). Мы начнём этот путь с создания личного помощника-агента, который поможет вам в решении ваших задач. Начнём!

3. Настройте облачные сервисы Google

Создайте проект Google Cloud

Начните с создания нового проекта Google Cloud, чтобы действия из этой кодовой лаборатории были изолированы только в пределах этого нового проекта.

1. Перейдите на console.cloud.google.com/projectcreate
2. Введите необходимую информацию:

• Название проекта — вы можете ввести любое название (например, genai-workshop)
• Местоположение - оставьте « Нет организации»
• Платежный аккаунт — если вы видите этот параметр, выберите «Платежный аккаунт пробной версии Google Cloud Platform» . Не беспокойтесь, если этот параметр отсутствует. Просто перейдите к следующему шагу.

3. Скопируйте сгенерированный идентификатор проекта , он понадобится вам позже.

4. Если все в порядке, нажмите кнопку «Создать» .

Настроить Cloud Shell

После успешного создания проекта выполните следующие шаги для настройки Cloud Shell .

1. Запустите Cloud Shell

Перейдите на сайт shell.cloud.google.com и, если появится всплывающее окно с просьбой авторизоваться, нажмите «Авторизовать» .

2. Установите идентификатор проекта

Выполните следующую команду в терминале Cloud Shell, чтобы задать правильный идентификатор проекта . Замените <your-project-id> на фактический идентификатор вашего проекта, скопированный с шага создания проекта выше.

gcloud config set project <your-project-id>

Теперь вы должны увидеть, что в терминале Cloud Shell выбран нужный проект. Идентификатор выбранного проекта подсвечен жёлтым цветом.

3. Включите необходимые API.

Чтобы использовать сервисы Google Cloud, необходимо сначала активировать их API для вашего проекта. Выполните следующие команды в терминале Cloud Shell, чтобы включить сервисы для этой практической работы:

gcloud services enable aiplatform.googleapis.com

Если операция прошла успешно, на терминале появится сообщение Operation/... finished successfully .

4. Создайте виртуальную среду Python

Перед запуском любого проекта Python рекомендуется создать виртуальную среду. Это изолирует зависимости проекта, предотвращая конфликты с другими проектами или глобальными пакетами Python в системе.

Примечание: для создания виртуального окружения мы будем использовать uv вместо стандартного пакета venv . Это невероятно быстрый пакет Python и менеджер проектов, написанный на Rust.

Если вам интересно, вы можете узнать больше об этом в официальной документации uv .

1. Создайте каталог проекта и перейдите в него:

mkdir ai-agents-adk
cd ai-agents-adk

2. Создайте и активируйте виртуальную среду:

uv venv --python 3.12
source .venv/bin/activate

В качестве префикса в командной строке терминала вы увидите ( ai-agents-adk ), что означает, что виртуальная среда активна.

3. Установка страницы adk

uv pip install google-adk

Примечание: если вы случайно закрыли терминал, вам придется перейти в папку ai-agents-adk и снова выполнить source .venv/bin/activate .

5. Создайте агента

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

• agent.py : содержит основной код Python вашего агента, определяющий его имя, используемый им LLM и основные инструкции.
• __init__.py : отмечает каталог как пакет Python, помогая ADK обнаружить и загрузить определение вашего агента.
• .env : Хранит конфиденциальную информацию и переменные конфигурации, такие как ключ API, идентификатор проекта и местоположение.

Эта команда создаст новый каталог с именем personal_assistant , содержащий три основных файла.

adk create personal_assistant

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

На первом этапе выберите вариант 1 , чтобы использовать модель gemini-2.5-flash — быструю и эффективную модель, идеально подходящую для разговорных задач.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

На втором этапе выберите Vertex AI (вариант 2) — мощную управляемую платформу искусственного интеллекта от Google Cloud в качестве поставщика внутренних услуг.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

После этого необходимо убедиться, что идентификатор проекта, указанный в скобках [...], установлен правильно. Если да, нажмите Enter . Если нет, введите правильный идентификатор проекта в следующем запросе:

Enter Google Cloud project ID [your-project-id]:

Наконец, нажмите Enter на следующем вопросе, чтобы использовать us-central1 в качестве региона для этой кодовой лаборатории.

Enter Google Cloud region [us-central1]:

Вы должны увидеть аналогичный вывод в своем терминале.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. Изучите коды агентов

Чтобы просмотреть созданные файлы, откройте папку ai-agents-adk в редакторе Cloud Shell.

• Нажмите Файл > Открыть папку... в верхнем меню.
• Найдите и выберите папку ai-agents-adk
• Нажмите ОК .

Если верхняя строка меню не отображается, вы также можете нажать на значок папки и выбрать «Открыть папку».

Примечание: вы можете использовать редактор командной строки, например Vim , но вам нужно будет знать команды для самостоятельного выхода из Vim .

После полной загрузки окна редактора перейдите в папку «Personal-assistant» . Там вы увидите необходимые файлы, упомянутые выше ( agent.py , __init__.py и .env ).

Файл .env часто скрыт по умолчанию. Чтобы сделать его видимым в редакторе Cloud Shell :

• перейдите в панель меню вверху,
• нажмите «Просмотр» и
• выберите Переключить скрытые файлы .

Изучите содержимое каждого файла.

агент.py

Этот файл создает экземпляр вашего агента с использованием класса Agent из библиотеки google.adk.agents .

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent : эта строка импортирует необходимый класс Agent из библиотеки ADK.
• root_agent = Agent(...) : Здесь вы создаете экземпляр своего ИИ-агента.
• name="root_agent" : уникальный идентификатор вашего агента. Именно по нему ADK будет распознавать и называть вашего агента.
• model="gemini-2.5-flash" : этот важный параметр определяет, какую большую языковую модель (LLM) ваш агент будет использовать в качестве своего базового «мозга» для понимания, рассуждения и генерации ответов. gemini-2.5-flash — это быстрая и эффективная модель, подходящая для разговорных задач.
• description="..." : краткое описание назначения или возможностей агента. Описание предназначено для понимания человеком или другими агентами в многоагентной системе, чтобы они могли понять, что делает данный агент. Оно часто используется для ведения журнала, отладки или отображения информации об агенте.
• instruction="..." : Это системная подсказка, которая направляет поведение вашего агента и определяет его личность. Она сообщает LLM, как ему следует действовать и какова его основная цель. В данном случае она определяет агента как «полезного помощника». Эта инструкция играет ключевую роль в формировании стиля общения и возможностей агента.

инициализация .py

Этот файл необходим Python для распознавания personal-assistant как пакета, что позволяет ADK правильно импортировать ваш файл agent.py .

from . import agent

• from . import agent : Эта строка выполняет относительный импорт, сообщая Python о необходимости поиска модуля с именем agent (соответствующего agent.py ) в текущем пакете ( personal-assistant ). Эта простая строка гарантирует, что при попытке ADK загрузить ваш агент personal-assistant он сможет найти и инициализировать root_agent определённый в agent.py . Даже если каталог пуст, наличие __init__.py делает каталог пакетом Python.

.env

В этом файле хранятся конфигурации, специфичные для конкретной среды, и конфиденциальные учетные данные.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI : сообщает ADK, что вы намерены использовать сервис Vertex AI от Google для операций генеративного ИИ. Это важно для использования управляемых сервисов и расширенных моделей Google Cloud.
• GOOGLE_CLOUD_PROJECT : эта переменная будет содержать уникальный идентификатор вашего проекта Google Cloud. ADK необходимо это для корректной связи вашего агента с облачными ресурсами и включения биллинга.
• GOOGLE_CLOUD_LOCATION : определяет регион Google Cloud, где расположены ваши ресурсы Vertex AI (например, us-central1 ). Использование правильного местоположения гарантирует, что ваш агент сможет эффективно взаимодействовать со службами Vertex AI в этом регионе.

7. Запустите агент на Терминале.

После установки всех трёх файлов вы готовы запустить агент прямо из терминала. Для этого выполните в терминале следующую команду adk run :

adk run personal_assistant

Если всё настроено правильно, вы увидите похожий вывод в терминале. Пока не беспокойтесь о предупреждениях, главное, чтобы вы видели [user]: всё в порядке и можно продолжать.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Пообщайтесь с агентом! Напишите что-нибудь вроде : «Привет. Чем вы можете мне помочь?» , и вам обязательно ответят.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

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

Поиск неисправностей

Этот метод API требует включения биллинга.

Если вы получили сообщение {'message': 'This API method requires billing to be enabled'} , выполните следующие действия:

1. Проверьте, используете ли вы правильный идентификатор проекта в файле .env
2. Перейдите на страницу привязанного платежного аккаунта и проверьте, привязан ли уже платежный аккаунт.
3. Если нет, выберите пробную учетную запись Google Cloud Platform Biling Account из списка.

API Vertex AI не использовался в проекте

Если вы получили сообщение об ошибке, содержащее {'message': 'Vertex AI API has not been used in project...'} , включите Vertex AI API, введя в терминал следующее:

gcloud services enable aiplatform.googleapis.com

Если операция прошла успешно, на терминале появится сообщение Operation/... finished successfully .

Другие ошибки

Если вы получили какие-либо другие ошибки, не упомянутые выше, попробуйте перезагрузить вкладку Cloud Shell в браузере (и повторно авторизоваться, если будет предложено).

8. Запустите агент в веб-интерфейсе разработки.

Комплект разработки агентов также предлагает удобный способ запустить агента как чат-приложение, используя его интерфейс разработки. Просто используйте команду adk web вместо adk run.

Если ваш терминал все еще работает adk run , введите exit , чтобы закрыть его, прежде чем вводить следующую команду:

adk web

Вы должны увидеть аналогичный вывод в терминале:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

У вас есть два варианта доступа к пользовательскому интерфейсу разработки:

1. Открыть через Терминал

• Ctrl + Click или Cmd + Click на ссылке (например, http://localhost:8000 ), как показано в терминале.

2. Открыть через веб-просмотр

• Нажмите кнопку «Веб-просмотр» ,
• Выберите Изменить порт .
• Введите номер порта (например, 8000 )
• Нажмите «Изменить» и «Предварительный просмотр».

После этого в браузере появится интерфейс, похожий на чат-приложение. Общайтесь со своим персональным помощником через этот интерфейс!

Вы заметите, что форматирование Markdown теперь отображается корректно, а этот пользовательский интерфейс также позволяет отлаживать и анализировать каждое событие обмена сообщениями, состояние агента, запросы пользователей и многое другое. Приятного общения!

9. Уборка (по желанию)

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

Поскольку эта лабораторная работа не включает в себя долгосрочные продукты, достаточно просто остановить сеансы активного агента (например, экземпляра adk web в вашем терминале) нажатием клавиш Ctrl + C или Cmd + C в терминале.

Удалить папки и файлы проекта агента

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

cd ~
rm -rf ai-agents-adk

Отключить API Vertex AI

Чтобы отключить API Vertex AI, который был включен ранее, выполните следующую команду:

gcloud services disable aiplatform.googleapis.com

Закройте весь проект Google Cloud

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

10. Заключение

Поздравляем! Вы успешно создали простого личного помощника с помощью набора инструментов для разработки агентов (ADK). Теперь у вас есть прочная основа и понимание основных компонентов агента ADK.

На следующем этапе вы можете значительно расширить возможности своего агента, предоставив ему инструменты для доступа к информации в режиме реального времени и взаимодействия с внешними сервисами. Если вы хотите продолжить, следующая практическая работа из этой серии, «Создание агентов ИИ с помощью ADK: Расширение возможностей с помощью инструментов» , поможет вам в этом процессе.