Создание ИИ-агентов с помощью ADK: расширение возможностей с помощью инструментов

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

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

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

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

Предпосылки

• Понимание концепций генеративного ИИ
• Базовые навыки программирования на Python
• Выполнено задание по созданию агентов ИИ с использованием ADK: The Foundation codelab или аналогичное.

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

• Дайте своему агенту новые навыки, создав пользовательские функции Python в качестве инструментов.
• Подключите своего агента к информации в режиме реального времени с помощью встроенных инструментов, таких как Google Search.
• Структурируйте многофункциональный агент, создав специализированные субагенты для сложных задач.
• Интегрируйте инструменты из популярных фреймворков ИИ, таких как LangChain, для быстрого расширения возможностей.

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

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

2. Введение

Базовый агент, созданный с помощью ADK, обладает мощным LLM-мозгом, но у него есть и ограничения: он не может получить доступ к информации, созданной после даты обучения, и не может взаимодействовать с внешними сервисами. Он подобен блестящему, осведомлённому помощнику, запертому в библиотеке без телефона и интернета. Чтобы сделать агента по-настоящему полезным, нам нужно дать ему инструменты.

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

ADK предлагает три категории инструментов:

1. Функциональные инструменты: пользовательские инструменты, которые вы разрабатываете для удовлетворения уникальных требований вашего приложения, такие как предопределенные функции и агенты.
2. Встроенные инструменты: готовые к использованию инструменты, предоставляемые фреймворком для выполнения распространенных операций, таких как поиск Google и выполнение кода.
3. Сторонние инструменты: популярные внешние библиотеки, такие как Serper , и инструменты от LangChain и CrewAI.

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

3. Начало работы: ваш базовый агент

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

Путь A: Продолжение работы над базовой практической работой

Если вы только что завершили практическую работу « Создание агентов ИИ с помощью ADK: Основы », то всё готово. Вы можете продолжить работу в каталоге вашего проекта ai-agents-adk .

Путь B: Начать с чистого листа

Если вы сразу приступаете к работе над этой лабораторной работой, выполните следующие 4 шага, чтобы настроить свою среду и создать необходимый начальный агент.

1. Настройка облачных сервисов Google
2. Создать виртуальную среду Python
3. Создать агента
4. Запустите агент в интерфейсе разработки

После выполнения этих шагов вы готовы приступить к обучению.

4. Создайте собственный инструмент для обмена валют

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

Представьте, что вы собираетесь в Японию в следующем месяце и вам нужно узнать текущий курс обмена валюты. Спросите у агента: «Какой курс обмена сингапурских долларов на японские иены?»

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

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

Завершите запущенный процесс агента, нажав сочетание клавиш Ctrl + C (для Windows/Linux) или Cmd + C (для macOS) в окне терминала.

Создать файл custom_functions.py **:**

Примечание: Прежде чем продолжить, убедитесь, что вы находитесь в правильном каталоге (ai-agents-adk). Выполните команду pwd (вывести рабочий каталог) в терминале, чтобы подтвердить своё текущее местоположение.

Создайте файл Python с именем custom_functions.py в папке personal_assistant , введя эту команду в терминале .

touch personal_assistant/custom_functions.py

Вот как должна выглядеть структура вашей папки:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

Откройте файл custom_functions.py в редакторе кода . Этот файл будет содержать функцию Python, отвечающую за получение данных о курсе валют из внешнего API.

Скопируйте и вставьте внутрь следующий код:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

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

Базовый LLM агента считывает имя функции и эту строку документации, чтобы понять, что делает инструмент, что означают его аргументы (в данном случае base и target ) и когда его следует использовать.

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

Теперь отредактируйте файл agent.py : импортируйте функцию get_fx_rate и назначьте ее как FunctionTool .

Обновить файл agent.py **:**

Скопируйте этот блок кода и замените существующее содержимое файла agent.py :

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

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

После внесения изменений запустите агент снова, введя:

uv run adk web

Когда агент появится, задайте тот же вопрос еще раз: «Каков курс обмена сингапурских долларов на японские йены?»

На этот раз вы должны увидеть реальный обменный курс, предоставленный инструментом get_fx_rate .

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

5. Интеграция со встроенным инструментом поиска Google

Теперь, когда агент может предоставлять курсы валют, следующая задача — получить прогноз погоды на следующий месяц. Задайте агенту вопрос: «Какой прогноз погоды в Токио, Япония, на следующий месяц?»

Как и следовало ожидать, для прогноза погоды требуется информация в режиме реального времени, которой у нашего агента нет. Хотя мы могли бы написать новые функции на Python для каждого фрагмента необходимых данных в режиме реального времени, быстрое добавление всё новых и новых инструментов делает агента слишком сложным и трудным в управлении.

К счастью, Agent Development Kit (ADK) предоставляет набор встроенных инструментов , включая готовый к использованию поиск Google, что упрощает взаимодействие нашего агента с внешним миром. Давайте добавим к нашему агенту инструмент поиска Google.

Для этого вам необходимо отредактировать файл agent.py следующим образом:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import google_search

from .custom_functions import get_fx_rate

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',
    tools=[
        FunctionTool(get_fx_rate), 
        google_search,
    ]
)

После редактирования файла перезапустите экземпляр adk web . Если вы забыли,

1. Щелкните по терминалу и нажмите Ctrl+C или Cmd+C, чтобы остановить экземпляр.
2. uv run adk web для запуска экземпляра
3. Попробуйте задать тот же вопрос: «Какой прогноз погоды в Токио, Япония, на следующий месяц?»

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

Рекомендуемый подход — использовать модель с несколькими агентами: создать специализированного агента, единственной задачей которого будет выполнение поиска в Google. Затем мы назначаем этого нового агента поиска Google нашему основному personal_assistant в качестве инструмента.

Создать файл custom_agents.py

Примечание: Прежде чем продолжить, убедитесь, что вы находитесь в правильном каталоге ( ai-agents-adk ). Выполните команду pwd (вывести рабочий каталог) в терминале, чтобы подтвердить своё текущее местоположение.

Теперь создайте файл Python с именем custom_agents.py в папке personal_assistant .

touch personal_assistant/custom_agents.py

Вот как теперь должна выглядеть структура ваших папок:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

Этот файл будет содержать код для специализированного google_search_agent . Скопируйте следующий код в файл custom_agents.py с помощью редактора кода .

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

После создания файла обновите файл agent.py , как показано ниже.

Обновить файл agent.py

Скопируйте этот блок кода и замените существующее содержимое файла agent.py :

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

Давайте разберем новый мощный шаблон в коде:

• Новый специализированный агент : мы определили совершенно нового агента, google_search_agent . Обратите внимание на его конкретное описание и на то, что его единственный инструмент — google_search . Это специалист по поиску.
• agent_tool.AgentTool : Это специальная оболочка из ADK. Она берёт целый агент (наш google_search_agent) и упаковывает его так, чтобы он выглядел и работал как стандартный инструмент.
• Более умный ** root_agent **: У нашего root_agent теперь есть новый инструмент: agent_tool.AgentTool(agent=google_search_agent) . Он не умеет искать в интернете, но знает, что у него есть инструмент, которому он может делегировать задачи поиска.

Обратите внимание, что поле «instruction» исчезло из root_agent . Его инструкции теперь неявно определяются доступными ему инструментами.

root_agent стал своего рода оркестратором или маршрутизатором, чья основная задача — распознавать запросы пользователя и передавать их нужному инструменту: функции get_fx_rate или google_search_agent . Такая децентрализованная архитектура играет ключевую роль в создании сложных, удобных в обслуживании систем агентов.

Теперь перезагрузите

adk web

например , и задайте этот вопрос агенту еще раз: «Какой прогноз погоды в Токио, Япония, на следующий месяц?»

Агент теперь использует google_search_agent для получения актуальной информации.

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

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

6. Используйте инструмент Википедии LangChain

Наш агент обещает стать отличным помощником в путешествиях. Он умеет обменивать валюту с помощью инструмента get_fx_rate и управлять логистикой с помощью инструмента google_search_agent . Но отличное путешествие — это не только логистика, но и понимание культуры и истории страны назначения.

Хотя google_search_agent может находить культурные и исторические факты, информация из специализированного источника, такого как Wikipedia, часто более структурирована и надежна.

К счастью, ADK обладает высокой расширяемостью, что позволяет легко интегрировать инструменты из других фреймворков ИИ-агентов, таких как CrewAI и LangChain. Эта совместимость критически важна, поскольку она ускоряет разработку и позволяет повторно использовать существующие инструменты. В данном случае мы воспользуемся инструментами из Википедии из LangChain.

Сначала остановите запущенный процесс агента ( Ctrl+C или Cmd+C ) и установите дополнительные библиотеки в текущую виртуальную среду Python, введя следующие команды в Терминале .

uv add langchain-community
uv add wikipedia

Создать файл third_party_tools.py

Примечание: Прежде чем продолжить, убедитесь, что вы находитесь в правильном каталоге ( ai-agents-adk ). Выполните команду pwd (вывести рабочий каталог) в терминале, чтобы подтвердить своё текущее местоположение.

Теперь создайте файл Python с именем third_party_tools.py в папке personal_assistant .

touch personal_assistant/third_party_tools.py

Вот как теперь должна выглядеть структура ваших папок:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

Этот файл будет содержать реализацию инструмента LangChain Wikipedia. Скопируйте следующий код в файл third_party_tools.py с помощью Cloud Editor:

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

Обновить файл agent.py

Теперь обновите файл agent.py , указав следующее содержимое:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool
from google.adk.tools import langchain_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

Теперь перезапустите экземпляр adk web и задайте агенту следующий вопрос: «Расскажите мне об истории Киото».

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

Чтобы точно увидеть, как агент сделал этот выбор, воспользуйтесь инспектором событий в веб- интерфейсе adk web . Перейдите на вкладку «События» и выберите последнее событие functionCall .

Инспектор показывает список всех доступных инструментов и выделяет tool_code для того, который был выполнен агентом.

7. Уборка (необязательно)

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

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

Поздравляем! Вы успешно наделили личного помощника специальными функциями и доступом к поиску Google в режиме реального времени. Ознакомьтесь с официальной документацией по использованию инструментов с Google ADK .

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

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