Эта страница переведена с помощью Cloud Translation API.

Создание ИИ-агентов с помощью 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 с включенным биллингом
Любопытный ум и стремление к обучению

2. Введение

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

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

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

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

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

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

Выберите или создайте проект Google Cloud

Перейдите в Google Cloud Console .
В верхней части нажмите на раскрывающийся список выбора проекта (рядом с логотипом Google Cloud).
Выберите существующий проект или создайте новый.

Включить биллинг

Убедитесь, что для выбранного вами проекта Google Cloud включена функция выставления счетов.
Вы можете узнать, как проверить, включена ли оплата в проекте, следуя инструкциям в документации по Google Cloud Billing .

Настроить Cloud Shell

Теперь давайте убедимся, что вы правильно настроили Cloud Shell — удобный интерфейс командной строки непосредственно в Google Cloud Console.

Запустить Cloud Shell

В правом верхнем углу консоли Google Cloud Console вы увидите значок, похожий на терминал ( >_ ). Нажмите на него, чтобы активировать Cloud Shell.

Разрешить доступ

При появлении запроса нажмите «Авторизовать» , чтобы предоставить Cloud Shell необходимые разрешения для взаимодействия с вашим проектом Google Cloud.

Подтвердите свою учетную запись:

После загрузки Cloud Shell убедитесь, что вы используете правильную учётную запись Google Cloud. Выполните следующую команду:

gcloud auth list

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

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Сменить учетные записи (при необходимости):

Если активная учетная запись не та, которую вы собираетесь использовать для этой лабораторной работы, переключитесь на нужную учетную запись с помощью этой команды, заменив <your_desired_account@example.com> на ваш фактический адрес электронной почты, который вы будете использовать для этой лабораторной работы:

gcloud config set account <your_desired_account@example.com

Подтвердите свой проект

Далее проверим, что Cloud Shell настроен на использование правильного проекта Google Cloud. Выполните:

gcloud config list project

Вы увидите список конфигураций. Найдите раздел [core] и убедитесь, что значение проекта совпадает с идентификатором проекта Google Cloud, который вы хотите использовать для этой практической работы:

[core]
project = <current-project-id>

Настройте свой проект (при необходимости)

Если значение project ID неверно, задайте ему нужный проект с помощью следующей команды:

gcloud config set project <your-desired-project-id>

Включить требуемые API

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

gcloud services enable aiplatform.googleapis.com

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

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

Перед запуском любого проекта на Python рекомендуется создать виртуальную среду. Это изолирует зависимости проекта, предотвращая конфликты с другими проектами или глобальными пакетами Python в системе. Поскольку для Agent Development Kit (ADK) требуется Python версии 3.9 или выше, мы будем использовать такой инструмент, как uv для управления виртуальной средой и обеспечения использования правильной версии Python.

uv — это современный, быстрый и эффективный инструмент для управления проектами и средами Python, сочетающий в себе функциональность, традиционно присущую таким инструментам, как pip , venv , pip-tools и pipx . Он написан на Rust для повышения скорости.

В Cloud Shell уже есть uv , так что мы можем начать прямо сейчас.

Проверьте правильность установки УФ-излучения.

uv --version

Создайте новую папку проекта для вашего ИИ-агента

uv init ai-agents-adk
cd ai-agents-adk

Создайте виртуальную среду с помощью Python 3.12

uv venv --python 3.12

Установите библиотеку Google ADK в вашей виртуальной среде

uv add google-adk

Проверьте, успешно ли установлен пакет google-adk.

uv pip list | grep google-adk

Если вы видите строку вывода с google-adk и ее версией, вы можете перейти к следующему шагу.

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

Теперь, когда ваша среда разработки настроена и готова, пришло время заложить основу для вашего ИИ-агента. Комплект разработки агентов (ADK) упрощает этот процесс, требуя всего нескольких необходимых файлов для определения базовой логики и конфигурации вашего агента.

Эти три файла работают вместе, делая ваш агент обнаруживаемым, запускаемым и настраиваемым:

agent.py : это сердце вашего агента. Он содержит основной код Python, определяющий поведение агента, включая его имя, большую языковую модель (LLM), которую он использует в качестве своего «мозга», и основные инструкции, управляющие его реакциями.
__init__.py : В Python файл __init__.py отмечает каталог как пакет Python. Для ADK это критически важно, поскольку помогает фреймворку обнаружить и загрузить определение агента из agent.py . В простых проектах ADK он часто содержит одну строку для импорта модуля agent , что делает агент доступным для исполнителя ADK.
.env : Этот файл (сокращение от «environment») используется для хранения конфиденциальной информации и переменных конфигурации, необходимых вашему агенту, таких как ключи API, идентификаторы проектов и географические местоположения. Хранение этих данных в отдельном файле .env — наилучший способ обеспечения безопасности и переносимости, поскольку это позволяет избежать жёсткого кодирования конфиденциальных данных непосредственно в коде. Это также позволяет легко изменять конфигурации, не изменяя основную логику агента.

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

uv run 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

Наконец, вам будет предложено подтвердить идентификатор и регион вашего проекта Google Cloud. Если вы планируете использовать предустановленные значения ( current-project-id и current-region ), просто нажмите Enter в каждом вопросе.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

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

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

Теперь нажмите кнопку «Открыть редактор» в верхней части окна Cloud Shell . Нажатие этой кнопки откроет окно редактора , что значительно упростит просмотр содержимого ваших файлов. Переключение может занять некоторое время; если экран загрузки отображается дольше нескольких минут, попробуйте обновить страницу браузера.

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

Если вы не видите файл .env в папке, перейдите в меню в верхней части экрана, нажмите «Вид» и выберите «Скрыть файлы» . Это распространённая настройка, поскольку файлы .env часто скрыты по умолчанию, чтобы предотвратить их случайное появление.

Давайте рассмотрим содержимое каждого файла.

агент.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="personal_assistant" : уникальный идентификатор вашего агента. Именно по нему 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 в этом регионе.

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

После установки всех трёх файлов вы готовы запустить агент прямо из терминала. Для этого необходимо открыть окно терминала. Нажав «Терминал» в строке меню, а затем выбрав « Новый терминал» , вы сделаете это!

Как только терминал станет доступен, вы можете запустить агент с помощью команды adk run . Поскольку это новое окно терминала, а мы используем uv , сначала необходимо перейти в папку ai-agent-adk , а затем добавить uv adk run uv run .

Введите эти команды в терминал:

cd ai-agents-adk
uv run adk run personal_assistant

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

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

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

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

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

uv run 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)

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

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

Ctrl + Click или Cmd + Click на URL-адресах (например, http://localhost:8000 ) из терминала.

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

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

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

8. Уборка

Поскольку эта лабораторная работа не включает в себя долго выполняемые продукты, достаточно просто остановить сеансы активного агента (например, экземпляра adk web в вашем терминале) нажатием клавиш Ctrl + 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, обратитесь к официальному руководству за подробными инструкциями.

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

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

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