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

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

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

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

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

Вы также можете получить доступ к этому практическому занятию по сокращенной ссылке: goo.gle/adk-foundation .

Предварительные требования

Что вы узнаете

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

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

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

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» . Не беспокойтесь, если вы не видите этот вариант. Просто перейдите к следующему шагу.
  1. Скопируйте сгенерированный идентификатор проекта , он понадобится вам позже.

9cc4a060b8c46fb0.png

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

Настройка Cloud Shell

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

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

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

186bc51f8f3ae589.png

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

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

gcloud config set project <your-project-id>

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

479ae540d1828559.png

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

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

gcloud services enable aiplatform.googleapis.com

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

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

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

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

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

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

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

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

6512ff43e8f5aa04.png

3. Установите страницу ADK. 

uv pip install google-adk

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
  • Нажмите ОК .

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

8d092e1c07966b24.png

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

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

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

ff4c617fa62e2da2.png

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

agent.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, как он должен действовать и какова его основная цель. В данном случае она определяет агента как «полезного помощника». Эта инструкция является ключевой для формирования стиля общения и возможностей агента.

init.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, что вы намерены использовать сервис Google Vertex AI для операций генеративного ИИ. Это важно для использования управляемых сервисов 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 для управления платежами из предложенных вариантов.

d9eb6361fd573427.png

f304212def88d3a3.png

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 --allow_origins "regex:https://.*\.cloudshell\.dev"

В терминале должен отобразиться вывод, похожий на этот: 

...
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 ).
  • Нажмите «Изменить» и «Предварительный просмотр» .

43b8b9beedbb1766.png

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

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

e845ab685af1ad90.png

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: расширение возможностей с помощью инструментов» , проведет вас через этот процесс.