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

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

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

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

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

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

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

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

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

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

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

2. Введение

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

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

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

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

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

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

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

Вариант А: Продолжение курса Foundation Codelab.

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

Путь Б: Начать все заново

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

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

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

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

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

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

7b3c502f88e8ab80.png

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

Для решения этой проблемы мы реализуем функцию на Python для получения обменных курсов через REST API и интегрируем её в качестве инструмента Function Tool для агента.

Завершите запущенный процесс агента, используя сочетание клавиш Ctrl + C в окне терминала.

Создайте файл custom_functions.py

Выполните эту команду в терминале, чтобы создать файл Python с именем custom_functions.py в папке personal_assistant , а также откройте его в редакторе кода .

cloudshell edit 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()

Теперь отредактируйте файл 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)]
)

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

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

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

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

76b1647fbfc0687a.png

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

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

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

399f40c4ea3e0bb3.png

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

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

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

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

Выполните эту команду в терминале, чтобы создать файл Python с именем custom_agents.py в папке personal_assistant и откройте его в редакторе кода :

cloudshell edit personal_assistant/custom_agents.py

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

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.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.agent_tool import AgentTool

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), 
        AgentTool(agent=google_search_agent),
    ]
)

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

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

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

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

Теперь введите эту команду в терминале, чтобы запустить экземпляр: 

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

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

8a2a6d9532b54301.png

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

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

ff3739a0b5ede6c2.png

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

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

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

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

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

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

uv pip install langchain-community wikipedia

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

Следующая команда создаст файл Python с именем third_party_tools.py в папке personal_assistant и откроет его в облачном редакторе : 

cloudshell edit 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 : 

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.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

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), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Теперь введите эту команду в терминале, чтобы запустить экземпляр: 

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

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

9098274a483dee32.png

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

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

eb2cdb9806cd3734.png

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

119d55bfb0b36e17.png

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 , вы сделали первый шаг от создания одного агента к управлению простой, но мощной многоагентной системой.

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