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

ADK: от основ до многофункциональных агентов

1. Введение

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

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

Если магистр права — это высококвалифицированный консультант, способный дать вам совет, то ИИ-агент — это инициативный инженер, который может использовать инструменты для реализации этих советов.

Магистр права против агентов

Мозг (LLM): обеспечивает рассуждения, планирование и понимание естественного языка. Он принимает решения о том, что необходимо сделать.

«Руки» (Инструменты): Это API, SDK и пользовательские функции, которые позволяют агенту взаимодействовать с реальным миром. Он выполняет план.

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

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

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

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

В этом практическом занятии вы создадите агента «Полезные советы» — интеллектуального консультанта по питанию, который переходит от простого текстового анализа к многофункциональному инструменту. Вы начнете с создания базового разговорного агента, понимающего концепции питания, а затем постепенно оснастите его инструментом Storage SDK для архивирования изображений ингредиентов и инструментом Vision для «чтения» и анализа этих изображений. К концу занятия у вас будет полностью функциональный оркестратор, который сможет взять загруженное фото этикетки продукта, сохранить его в облачном хранилище для учета и немедленно предоставить «Полезные советы» для каждого ингредиента.

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

Проект в Google Cloud с включенной функцией выставления счетов.
веб-браузер

Создайте свой проект

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

Активировать Cloud Shell

Вы будете использовать Cloud Shell — среду командной строки, работающую в Google Cloud Console, которая поставляется с предустановленными необходимыми языками. В Cloud Console нажмите «Активировать Cloud Shell» в правом верхнем углу:

После подключения к Cloud Shell вы увидите, что ваша аутентификация пройдена и проект настроен на ваш идентификатор. Для подтверждения аутентификации выполните следующую команду в Cloud Shell:

gcloud auth list

Выполните следующую команду в Cloud Shell, чтобы убедиться, что команда gcloud знает о вашем проекте:

gcloud config list project

Если ваш проект не задан, используйте следующую команду для его настройки:

gcloud config set project <YOUR_PROJECT_ID>

Для получения информации о командах gcloud и их использовании обратитесь к документации .

Открытый редактор

Для этого практического занятия мы будем использовать встроенный облачный редактор. В окне облачной оболочки нажмите кнопку «Открыть редактор» в правом верхнем углу. Это откроет для вас редактор VSCode.

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

Перейдём к терминалу Cloud Shell, который мы активировали в предыдущем разделе:

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

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

python -m venv .venv

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

source .venv/bin/activate

Установите ADK

pip install google-adk

4. Ключ API Google

Создайте ключ Google API с помощью AI Studio:

Перейдите по ссылке https://aistudio.google.com/ и в меню в левом нижнем углу нажмите « Get API Key .

Вы увидите окно «Ключи API», нажмите в этом окне кнопку «Создать ключ API»:

Вы увидите всплывающее окно для создания нового ключа. Назовите ключ следующим образом: healthy-hints-key

Перейдите в выпадающее меню «Выберите импортированный проект».

Нажмите Import Project . Откроется боковое окно со списком всех ваших проектов Google Cloud. Выберите тот, с которым хотите работать.

Нажмите «Импорт».

Теперь выпадающее меню обновится, отобразив только что импортированный проект. Выберите проект из выпадающего списка. Нажмите «Создать ключ». Вы увидите список созданных ключей API. Нажмите на значок копирования только что созданного ключа API.

5. Агент по отбору проб

В терминале Cloud Shell создайте корневой каталог для вашего агента в нужном месте расположения проекта:

adk create healthy_hints

Вы можете выбрать любую модель, но для этой практической работы мы будем использовать gemini-2.5-flash.

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

Давайте откроем только что созданную папку. В самом левом меню нажмите на значок Нажмите «Файл» -> «Открыть папку». Выберите только что созданную папку healthy_hints ; обычно она находится в папке /home/<username> .
Структура папки healthy_hints обычно выглядит следующим образом:

Вы увидите файл .env, содержащий ваш ключ API Google. Вы можете использовать этот файл для установки любых переменных окружения.
Также создаётся ещё один файл с именем agent.py , и это наш основной файл агента. Здесь создаётся пример корневого агента. Давайте внимательно рассмотрим содержимое этого файла: сначала мы импортируем llm_agent из ADK. Затем мы используем DSL ADK для создания корневого агента. Мы указываем имя модели как Gemini-2.5-flash , даём имя агенту и предоставляем его подробное описание. Инструкция — это самое важное здесь, здесь мы указываем агенту, что ему нужно делать, на естественном языке.
Этот пример агента довольно универсальный, он просто ответит на любой вопрос пользователя.
Теперь давайте запустим этот агент локально. Взаимодействовать с ним можно двумя способами: через командную строку и через веб-интерфейс.
CLI : Выполните следующую команду вне каталога healthy_hints

adk run healthy_hints

Или, если вы находитесь в каталоге healthy_hints , выполните следующую команду:

adk run .

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

Смело пишите «привет» или задавайте любые вопросы. Ответ может быть разным для каждого, такова природа искусственного интеллекта.

В веб-версии : выполните следующую команду из родительского каталога healthy_hints :

adk web

6. Многофункциональный агент

Инструмент — это модульный фрагмент кода, как правило, функция или API, который позволяет агенту взаимодействовать с окружающим миром за пределами его внутренних знаний.

Типы инструментов в ADK

Функциональные инструменты: Настраиваемая логика, которую вы пишете сами. Например, функция, которая подключается к вашей конкретной базе данных, или пользовательский «анализатор логов» для уникального формата вашей компании.
Встроенные инструменты: готовые к использованию возможности, предоставляемые Google или ADK, такие как Google Search , интерпретатор кода или Google RAG Engine .
Агенты как инструменты: В продвинутых системах с "многофункциональными инструментами" или "многоагентных системах" один специализированный агент может выступать в качестве инструмента для другого. Например, "агент поиска" может быть инструментом, используемым "агентом управления исследованиями".

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

Давайте добавим новый метод ` get_weather в файл `agent.py`.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Давайте изменим файл agent.py и изменим имя, описание и инструкции агента:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

До сих пор мы создали только один инструмент. Теперь давайте создадим несколько инструментов:

Давайте создадим ещё один метод под названием get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Давайте изменим нашего агента, чтобы он также мог вызывать этот инструмент:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

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

7. Интеграция SDK

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

Давайте сначала создадим хранилище (bucket) для загрузки изображения в Google Cloud Storage. Откроем новую вкладку и перейдем по адресу https://console.cloud.google.com/ , а в строке поиска введем «Cloud Storage». Теперь выберем «Cloud Storage» в разделе «Продукты и страницы»:

Это переведет вас на страницу обзора Google Cloud Storage. Нажмите кнопку Create bucket . На странице создания корзины введите имя корзины. Имя может быть любым, но для этого примера мы используем healthy-hints-bucket-kolkata . Оставьте все остальные поля как есть и нажмите кнопку Create .

Давайте создадим новый файл с именем requirements.txt и добавим в него google-cloud-storage . Мы будем использовать Python Storage SDK для загрузки образа в хранилище.

Для начала установим зависимости:

pip install -r requirements.txt

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

gcloud services enable storage.googleapis.com

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

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Теперь давайте обновим нашего агента, чтобы он использовал новый инструмент:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Теперь добавим ещё один инструмент для считывания состава с изображения. Добавим google-cloud-vision в requirements.txt и установим новую зависимость.

pip install -r requirements.txt

Повторюсь, возможно, сначала потребуется включить Vision API. Для этого выполните следующую команду в терминале:

gcloud services enable vision.googleapis.com

Теперь добавим новый инструмент read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

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

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

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

Поздравляем с завершением практического задания Healthy Hints! Вы успешно превратили стандартный ИИ из генератора текста в проактивного многофункционального агента. Используя ADK для интеграции Vision API и Cloud Storage SDK, вы наделили своего агента «глазами» для чтения меток и «памятью» для их архивирования. Вы увидели, как агент автономно решает, когда сохранить файл, и как интерпретировать необработанные данные для предоставления реальных рекомендаций по здоровью.

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