Инструменты для создания агента: от нуля до помощника с ADK

1. Введение

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

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

• Как настроить проект Python для разработки ADK.
• Как создать базовый агент ADK.
• Как реализовать и использовать функциональные инструменты.
• Как интегрировать встроенные инструменты, такие как Google Search.
• Как использовать сторонние инструменты из таких фреймворков, как LangChain, в ADK.
• Как использовать инструменты MCP для взаимодействия с базами данных (Cloud SQL) и API.

2. Обзор

Представьте, что вы менеджер проектов в QuantumRoast, международной компании по производству кофемашин.

Вы помогаете своим коллегам ориентироваться в море инженерных планов, внезапных поворотов стратегии (сейчас мы делаем матча!) и входящих заявок от клиентов — от глючной системы выставления счетов до кофемашины, которая издает пронзительный звук 24/7.

В обычный день у вас открыто около пятидесяти вкладок браузера: внутренняя система тикетов, электронная почта, чат, GitHub, Google Search, StackOverflow и многое другое. Вам нравится ваша работа и ваши коллеги, но иногда вы просто перегружены.

Что, если бы мы могли создать помощника, который поможет вам создавать и сортировать заявки на исправление ошибок, а также устранять неполадки? ИИ-агент делает это возможным.

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

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

ADK имеет полностью открытый исходный код в репозитории adk-python на GitHub !

Если вы хотите сообщить о проблеме, предложить новую функцию или внести свой вклад, вы можете сделать это на GitHub.

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

Инструменты 101

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

Инструмент — это возможность, помогающая ИИ-агенту взаимодействовать с миром. Инструментом может быть практически что угодно: встроенная функция, размещённая база данных, сторонний API или даже другой агент. Фреймворки ИИ-агентов, такие как Agent Development Kit (ADK), имеют встроенную поддержку инструментов, включая различные типы инструментов, которые мы рассмотрим чуть позже.

Но как агент узнает не только, когда вызывать тот или иной инструмент, но и как это сделать? Модель агента играет здесь несколько ключевых ролей.

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

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

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

Чтобы увидеть все это в действии, пришло время создать агента-помощника по ошибкам QuantumRoast с использованием ADK Python .

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

Настройка проекта Google Cloud

1. Если у вас еще нет учетной записи Google, вам необходимо ее создать .
   • Используйте личную учётную запись вместо рабочей или учебной. Рабочие и учебные учётные записи могут иметь ограничения, которые не позволят вам включить API, необходимые для этой лабораторной работы.
2. Войдите в Google Cloud Console .
3. Включите выставление счетов в Cloud Console.
   • Выполнение этой лабораторной работы обойдется менее чем в 1 доллар США в виде облачных ресурсов.
   • Вы можете следовать инструкциям в конце этой лабораторной работы, чтобы удалить ресурсы и избежать дальнейших расходов.
   • Новые пользователи имеют право на бесплатную пробную версию стоимостью 300 долларов США .
4. Создайте новый проект или выберите повторное использование существующего проекта.

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

1. Перейдите в редактор Cloud Shell.
2. Если терминал не отображается внизу экрана, откройте его:
   • Нажмите на меню гамбургера.
   • Нажмите «Терминал»
   • Нажмите «Новый терминал».
3. В терминале настройте свой проект с помощью этой команды (заменив YOUR_PROJECT_ID ):
   • Формат:

     gcloud config set project YOUR_PROJECT_ID
     

   • Пример:

     gcloud config set project lab-project-id-example
     

   • Если вы не можете вспомнить идентификатор своего проекта:
     • Вы можете перечислить все идентификаторы своих проектов с помощью:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Если будет предложено авторизоваться, нажмите «Авторизовать» , чтобы продолжить.
5. Вы должны увидеть это сообщение:

   Updated property [core/project].
   

   Если вы видите WARNING и вопрос Do you want to continue (Y/N)? , вероятно, вы неправильно ввели идентификатор проекта. Нажмите N , затем Enter и попробуйте снова выполнить команду gcloud config set project .
6. В терминале задайте переменную среды PROJECT_ID , которая будет использоваться на последующих этапах.

   export PROJECT_ID=$(gcloud config get project)
   

Включить API

В терминале выполните следующую команду, чтобы включить необходимые API Google Cloud:

gcloud services enable sqladmin.googleapis.com \
   compute.googleapis.com \
   cloudresourcemanager.googleapis.com \
   secretmanager.googleapis.com \
   servicenetworking.googleapis.com \
   aiplatform.googleapis.com \
   run.googleapis.com \
   artifactregistry.googleapis.com \
   cloudbuild.googleapis.com

Создайте экземпляр Cloud SQL для PostgreSQL

В QuantumRoast есть база данных тикетов ошибок, в которой хранятся все внутренние тикеты. Давайте настроим её, создав экземпляр Cloud SQL для PostgreSQL .

gcloud sql instances create software-assistant \
   --database-version=POSTGRES_16 \
   --tier=db-custom-1-3840 \
   --region=us-central1 \
   --edition=ENTERPRISE \
   --enable-google-ml-integration \
   --database-flags cloudsql.enable_google_ml_integration=on \
   --root-password=admin

Дождитесь создания экземпляра (это может занять несколько минут).

Для этой практической работы мы используем пароль базы данных admin . Однако для производственной среды рекомендуется использовать более надёжный пароль.

После создания вы можете просмотреть свой экземпляр в Cloud Console здесь .

Создать облачную базу данных SQL

Создайте базу данных SQL ( tickets-db ) и предоставьте учетной записи службы Cloud SQL доступ к Vertex AI (чтобы мы могли создавать вложения для выполнения поиска по сходству).

gcloud sql databases create tickets-db --instance=software-assistant

SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe software-assistant --format="value(serviceAccountEmailAddress)")
echo $SERVICE_ACCOUNT_EMAIL

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" --role="roles/aiplatform.user"

Настройте стол tickets

В консоли Cloud Console (Cloud SQL) откройте Cloud SQL Studio для экземпляра software-assistant .

Войдите в базу данных tickets-db используя имя пользователя postgres и пароль admin .

Откройте новую вкладку Editor .

Затем вставьте следующий SQL-код для настройки таблицы и создания векторных вложений. Нажмите кнопку Run , чтобы выполнить команду.

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector CASCADE;
GRANT EXECUTE ON FUNCTION embedding TO postgres;

CREATE TABLE tickets (
    ticket_id SERIAL PRIMARY KEY,             -- PostgreSQL's auto-incrementing integer type (SERIAL is equivalent to INT AUTO_INCREMENT)
    title VARCHAR(255) NOT NULL,              -- A concise summary or title of the bug/issue.
    description TEXT,                         -- A detailed description of the bug.
    assignee VARCHAR(100),                    -- The name or email of the person/team assigned to the ticket.
    priority VARCHAR(50),                     -- The priority level (e.g., 'P0 - Critical', 'P1 - High').
    status VARCHAR(50) DEFAULT 'Open',        -- The current status of the ticket (e.g., 'Open', 'In Progress', 'Resolved'). Default is 'Open'.
    creation_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, -- Timestamp when the ticket was first created. 'WITH TIME ZONE' is recommended for clarity and compatibility.
    updated_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP  -- Timestamp when the ticket was last updated. Will be managed by a trigger.
);

Таблица tickets создана, нажмите Clear , чтобы очистить старый запрос.

Теперь вставьте образец данных и еще раз нажмите кнопку « Run .

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Login Page Freezes After Multiple Failed Attempts', 'Users are reporting that after 3 failed login attempts, the login page becomes unresponsive and requires a refresh. No specific error message is displayed.', '[e-mail]', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Dashboard Sales Widget Intermittent Data Loading Failure', 'The "Sales Overview" widget on the main dashboard intermittently shows a loading spinner but no data. Primarily affects Chrome browser users.', '[e-mail]', 'P1 - High', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Broken Link in Footer - Privacy Policy', 'The "Privacy Policy" hyperlink located in the website footer leads to a 404 "Page Not Found" error.', '[e-mail]', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('UI Misalignment on Mobile Landscape View (iOS)', 'On specific iOS devices (e.g., iPhone 14 models), the top navigation bar shifts downwards when the device is viewed in landscape orientation, obscuring content.', '[e-mail]', 'P2 - Medium', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Critical XZ Utils Backdoor Detected in Core Dependency (CVE-2024-3094)', 'Urgent: A sophisticated supply chain compromise (CVE-2024-3094) has been identified in XZ Utils versions 5.6.0 and 5.6.1. This malicious code potentially allows unauthorized remote SSH access by modifying liblzma. Immediate investigation and action required for affected Linux/Unix systems and services relying on XZ Utils.', '[e-mail]', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Database Connection Timeouts During Peak Usage', 'The application is experiencing frequent database connection timeouts, particularly during peak hours (10 AM - 12 PM EDT), affecting all users and causing service interruptions.', '[e-mail]', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Export to PDF Truncates Long Text Fields in Reports', 'When generating PDF exports of reports containing extensive text fields, the text is abruptly cut off at the end of the page instead of wrapping or continuing to the next page.', '[e-mail]', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Search Filter "Date Range" Not Applying Correctly', 'The "Date Range" filter on the search results page does not filter records accurately; results outside the specified date range are still displayed.', '[e-mail]', 'P2 - Medium', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Typo in Error Message: "Unathorized Access"', 'The error message displayed when a user attempts an unauthorized action reads "Unathorized Access" instead of "Unauthorized Access."', '[e-mail]', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Intermittent File Upload Failures for Large Files', 'Users are intermittently reporting that file uploads fail without a clear error message or explanation, especially for files exceeding 10MB in size.', '[e-mail]', 'P1 - High', 'Open');

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

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

Нажмите Clear , а затем вставьте следующий SQL-код для реализации триггера.

Нажмите кнопку Run , чтобы выполнить команду.

CREATE OR REPLACE FUNCTION update_updated_time_tickets()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_time = NOW();  -- Set the updated_time to the current timestamp
    RETURN NEW;                -- Return the new row
END;
$$ language 'plpgsql';        

CREATE TRIGGER update_tickets_updated_time
BEFORE UPDATE ON tickets
FOR EACH ROW                  -- This means the trigger fires for each row affected by the UPDATE statement
EXECUTE PROCEDURE update_updated_time_tickets();

Создайте векторные вложения из поля description . Это позволит нашему агенту выполнять поиск по схожести в нашей базе данных. Например, «Есть ли какие-либо нерешённые вопросы, связанные с главной страницей сайта?».

ALTER TABLE tickets ADD COLUMN embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005',description)) STORED;

Теперь вы можете отправить запрос в базу данных, чтобы убедиться в ее готовности.

SELECT * FROM tickets;

Вы должны увидеть 10 возвращенных строк, похожих на следующие:

Теперь вы готовы перейти к самой интересной части — коду!

4. Настройка проекта Python

Прежде чем приступить к созданию агента, необходимо убедиться, что у нас есть корректная настройка проекта Python. Всё это мы сделаем в Cloud Shell!

Сначала создайте папку quantum-roast и cd в нее:

mkdir quantum-roast && cd quantum-roast

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

Мы будем использовать uv (чрезвычайно быстрый менеджер пакетов и проектов Python), который предустановлен в Cloud Shell для управления нашим проектом и зависимостями. UV поможет нам настроить некоторые файлы, а также управлять виртуальными средами, зависимостями и т. д. Так что нам не придётся этим заниматься!

Инициализируйте новый проект с помощью uv init :

uv init --description "QuantumRoast Software Bug Assistant with ADK" --bare --python 3.10

После выполнения команды у нас должен появиться файл pyproject.toml для нашего проекта. Для проверки выполните команду cat pyproject.toml в терминале Cloud Shell:

cat pyproject.toml

В качестве вывода следует рассматривать следующее:

[project]
name = "quantum-roast"
version = "0.1.0"
description = "QuantumRoast Software Bug Assistant with ADK"
requires-python = ">=3.10"
dependencies = []

Пришло время добавить google-adk (ADK) в качестве зависимости к нашему проекту с помощью uv add .

uv add google-adk==1.11.0

Это добавляет google-adk в список dependencies в нашем pyproject.toml .

ADK ожидает определенной структуры проекта для достижения наилучших результатов.

quantum-roast/
    software_bug_assistant/
        __init__.py
        agent.py
        .env

Создайте папку software_bug_assistant и файлы в ней:

mkdir software_bug_assistant && touch software_bug_assistant/__init__.py \
software_bug_assistant/agent.py \
software_bug_assistant/tools.py \
software_bug_assistant/.env

Проверьте создание файлов с помощью ls :

ls -a software_bug_assistant/

Вы должны увидеть следующее:

__init__.py	 .  ..	 .env	 agent.py    tools.py

Теперь нужно заполнить файл .env переменными окружения, необходимыми для корректного вызова моделей Gemini в ADK. Мы будем обращаться к Gemini через Vertex API.

echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_LOCATION=us-central1" >> software_bug_assistant/.env

Чтобы проверить правильность заполнения .env , выполните следующее:

cat software_bug_assistant/.env

Вы должны увидеть следующее, где your-project-id — это идентификатор вашего проекта:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

Теперь мы готовы приступить к созданию нашего агента ADK.

5. Базовый агент ADK

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

Откройте agent.py в редакторе Cloud Shell:

cloudshell edit software_bug_assistant/agent.py

Вставьте следующий код в agent.py и сохраните файл Ctrl + s :

from google.adk.agents import Agent

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[],
)

Запустите созданный агент, запустив интерфейс разработчика ADK ( adk web ). При использовании команды uv run виртуальная среда с установленным ADK будет автоматически создана.

Использование флага --port 8080 запустит adk web на порту Cloud Shell по умолчанию.

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

uv run adk web --port 8080 --reload_agents

В консоли вы должны увидеть успешный запуск веб-сервера ADK.

INFO:     Started server process [1557]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Откройте веб-превью Cloud Shell, чтобы увидеть пользовательский интерфейс.

Вы должны увидеть веб-интерфейс ADK.

Попробуйте пообщаться с агентом ADK.

Спросите агента What day is it today? .

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

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

Оставьте веб-просмотр открытым, мы будем обращаться к нашему агенту на каждом этапе лабораторной работы!

6. Функциональный инструмент

Первый и самый простой тип инструмента ADK — это инструмент-функция . Его название буквально отражает суть: функция Python, вызываемая агентом!

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

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

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

Оставьте веб-терминал ADK запущенным! Поскольку мы использовали --reload_agents , мы можем оставить агент запущенным, и он автоматически подхватит новые инструменты по мере их добавления. 😊

Файл tools.py в папке /software_bug_assistant — это место, где мы будем организовывать все инструменты, которые создадим в ходе этой лабораторной работы.

Откройте НОВЫЙ терминал, нажав значок + .

Теперь в новом терминале задайте PROJECT_ID и откройте tools.py :

cd quantum-roast
export PROJECT_ID=$(gcloud config get project)
cloudshell edit software_bug_assistant/tools.py

Теперь определите функцию get_current_date , которая будет использоваться как инструмент функции.

from datetime import datetime

# ----- Example of a Function tool -----
def get_current_date() -> dict:
    """
    Get the current date in the format YYYY-MM-DD
    """
    return {"current_date": datetime.now().strftime("%Y-%m-%d")}

Функция определена! Пора передать её агенту в качестве инструмента.

Откройте agent.py в редакторе Cloud Shell:

cloudshell edit software_bug_assistant/agent.py

Мы хотим импортировать функцию get_current_date из tools.py и передать функцию аргументу tools агента.

Обновленный agent.py выглядит следующим образом:

from google.adk.agents import Agent

from .tools import get_current_date

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date],
)

Теперь, если вы вернетесь на вкладку «Веб-просмотр», запустив веб-интерфейс ADK, и снова спросите: What day is it today? »...

Агент может успешно узнать дату, вызвав инструмент функции get_current_date ! 🎉

Пришло время изучить следующий тип инструментов ADK.

7. Встроенный инструмент

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

Откройте файл tools.py , чтобы добавить поддержку встроенного инструмента поиска Google.

cloudshell edit software_bug_assistant/tools.py

Добавьте следующее в конец tools.py :

# ----- Built-in Tool Imports -----
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

# ----- Example of a Built-in Tool -----
search_agent = Agent(
    model="gemini-2.5-flash",
    name="search_agent",
    description="A specialist in Google Search.",
    instruction="""
    You're a specialist in Google Search.
    """,
    tools=[google_search],
)

search_tool = AgentTool(search_agent)

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

Теперь мы можем импортировать и передать search_tool корневому агенту в agent.py :

cloudshell edit software_bug_assistant/agent.py

Вы можете заменить agent.py следующим кодом, чтобы включить search_tool :

from google.adk.agents import Agent

from .tools import get_current_date, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool],
)

Сохраните файл и вернитесь в открытое окно, на котором запущен веб-интерфейс ADK.

Если вы случайно закрыли терминал, на котором запущен веб-пользовательский интерфейс ADK, вы можете перезапустить его, выполнив команду uv run adk web --port 8080 --reload_agents .

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

Выполните следующий запрос: Do a web search for 5 of the most recent CVEs? .

Наш агент должен вызвать search_agent для поиска в Интернете.

Наш агент успешно разблокировал возможность поиска в Интернете с помощью встроенного инструмента ADK для поиска Google! 🎉

Переходим к следующему типу инструмента ADK.

8. Сторонний инструмент

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

Чтобы подключить наш агент ошибок к мощным данным вопросов и ответов StackOverflow , мы можем использовать обширную библиотеку инструментов LangChain , а именно инструмент StackExchange API Wrapper . ADK поддерживает сторонние инструменты, такие как LangChain , поэтому для добавления этого инструмента в наш агент ADK потребуется всего несколько строк кода!

Во-первых, мы должны добавить в наш проект новые зависимости для LangChain и StackOverflow ( langchain-community и stackapi ):

uv add langchain-community==0.3.27 stackapi==0.3.1

Откройте файл tools.py , чтобы добавить поддержку инструмента LangChain StackExchange.

cloudshell edit software_bug_assistant/tools.py

Добавьте следующее в конец tools.py :

# ----- Example of a Third-Party Tool -----
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import StackExchangeTool
from langchain_community.utilities import StackExchangeAPIWrapper

stack_exchange_tool = StackExchangeTool(api_wrapper=StackExchangeAPIWrapper())
langchain_tool = LangchainTool(stack_exchange_tool)

Теперь мы можем импортировать и передать langchain_tool корневому агенту в agent.py :

cloudshell edit software_bug_assistant/agent.py

Вы можете заменить agent.py следующим кодом, чтобы включить langchain_tool :

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool],
)

Сохраните файл и вернитесь на открытую вкладку с веб-интерфейсом ADK.

Если вы случайно закрыли терминал, на котором запущен веб-пользовательский интерфейс ADK, вы можете перезапустить его, выполнив команду uv run adk web --port 8080 --reload_agents .

Попробуйте спросить агента что-нибудь о предыдущих CVE, например: "Are there similar issues on stack exchange?" , или что-нибудь новое, например "Our database queries with SQLAlchemy seem to be timing out, is there anything on StackExchange relevant to this?" .

Наш агент успешно применил инструмент LangChain в ADK для отправки запросов в StackOverflow. 🥳

Пришло время для следующего типа инструментов ADK... инструментов MCP!

9. Инструмент MCP (база данных)

MCP ( Model Context Protocol) — это открытый протокол, представленный компанией Anthropic в 2024 году. MCP обеспечивает уровень абстракции между вашим ИИ-агентом и инструментами (API, базами данных).

MCP обладает рядом уникальных спецификаций . В отличие от стандартного HTTP, MCP обеспечивает двустороннее соединение между клиентом и сервером с сохранением состояния. Он использует собственный способ определения инструментов и сообщений об ошибках, специфичных для каждого инструмента. Поставщик инструментов может затем создавать серверы MCP на основе своих API, предоставляя разработчикам и пользователям один или несколько готовых инструментов . Затем фреймворки агентов могут инициализировать клиенты MCP внутри агентского приложения для обнаружения и вызова этих инструментов.

В QuantumRoast у нас есть база данных Cloud SQL for PostgreSQL для поиска внутренних ошибок в программном обеспечении. Мы хотим создать инструменты ADK, чтобы наш агент мог выполнять определённые запросы к нашей базе данных.

Проще всего это сделать с помощью MCP Toolbox for Databases , MCP-сервера с открытым исходным кодом для баз данных! Toolbox поддерживает более 15 баз данных , одна из которых — Cloud SQL!

Toolbox обеспечивает:

• Упрощенная разработка : интегрируйте инструменты в свой агент менее чем в 10 строк кода, повторно используйте инструменты между несколькими агентами или фреймворками и с легкостью развертывайте новые версии инструментов.
• Лучшая производительность : лучшие практики, такие как пул соединений, аутентификация и многое другое.
• Повышенная безопасность : интегрированная аутентификация для более безопасного доступа к вашим данным.
• Сквозное наблюдение : готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.

ADK поддерживает инструменты MCP Toolbox for Database, что ускоряет интеграцию.

Развертывание MCP Toolbox for Databases Server в облаке

Сначала мы развернем MCP Toolbox for Databases Server в Cloud Run и настроим его на наш экземпляр Cloud SQL.

Для настройки Toolbox необходим файл YAML, в котором описывается исходная база данных и инструменты для настройки.

Создайте файл tools.yaml для развертывания.

cloudshell edit tools.yaml

Вставьте следующее содержимое в tools.yaml :

sources:
  postgresql:
    kind: cloud-sql-postgres
    project: ${PROJECT_ID}
    region: us-central1
    instance: software-assistant
    database: tickets-db
    user: postgres
    password: admin

tools:
  search-tickets:
    kind: postgres-sql
    source: postgresql
    description: Search for similar tickets based on their descriptions.
    parameters:
      - name: query
        type: string
        description: The query to perform vector search with.
    statement: |
      SELECT ticket_id, title, description, assignee, priority, status, (embedding <=> embedding('text-embedding-005', $1)::vector) as distance
      FROM tickets
      ORDER BY distance ASC
      LIMIT 3;
  get-ticket-by-id:
    kind: postgres-sql
    source: postgresql
    description: Retrieve a ticket's details using its unique ID.
    parameters:
      - name: ticket_id
        type: string
        description: The unique ID of the ticket.
    statement: SELECT * FROM tickets WHERE ticket_id = $1;
  get-tickets-by-assignee:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on assignee (email).
    parameters:
      - name: assignee
        type: string
        description: The email of the assignee.
    statement: SELECT * FROM tickets WHERE assignee ILIKE '%' || $1 || '%';
  update-ticket-priority:
    kind: postgres-sql
    source: postgresql
    description: Update the priority of a ticket based on its ID.
    parameters:
      - name: priority
        type: string
        description: The priority of the ticket. Can be one of 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'.
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET priority = $1 WHERE ticket_id = $2;
  update-ticket-status:
    kind: postgres-sql
    source: postgresql
    description: Update the status of a ticket based on its ID.
    parameters:
      - name: status
        type: string
        description: The new status of the ticket (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET status = $1 WHERE ticket_id = $2;
  get-tickets-by-status:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their current status.
    parameters:
      - name: status
        type: string
        description: The status of the tickets to retrieve (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
    statement: SELECT * FROM tickets WHERE status ILIKE '%' || $1 || '%';
  get-tickets-by-priority:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their priority.
    parameters:
      - name: priority
        type: string
        description: The priority of the tickets to retrieve (e.g., 'P0 - Critical', 'P1 - High', 'P2 - Medium', 'P3 - Low').
    statement: SELECT * FROM tickets WHERE priority ILIKE '%' || $1 || '%';
  create-new-ticket:
    kind: postgres-sql
    source: postgresql
    description: Create a new software ticket.
    parameters:
      - name: title
        type: string
        description: The title of the new ticket.
      - name: description
        type: string
        description: A detailed description of the bug or issue.
      - name: assignee
        type: string
        description: (Optional) The email of the person to whom the ticket should be assigned.
      - name: priority
        type: string
        description: (Optional) The priority of the ticket. Can be 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'. Default is 'P3 - Low'.
      - name: status
        type: string
        description: (Optional) The initial status of the ticket. Default is 'Open'.
    statement: INSERT INTO tickets (title, description, assignee, priority, status) VALUES ($1, $2, $3, COALESCE($4, 'P3 - Low'), COALESCE($5, 'Open')) RETURNING ticket_id;
  get-tickets-by-date-range:
    kind: postgres-sql
    source: postgresql
    description: Retrieve tickets created or updated within a specific date range.
    parameters:
      - name: start_date
        type: string
        description: The start date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: end_date
        type: string
        description: The end date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: date_field
        type: string
        description: The date field to filter by ('creation_time' or 'updated_time').
    statement: SELECT * FROM tickets WHERE CASE WHEN $3 = 'creation_time' THEN creation_time ELSE updated_time END BETWEEN $1::timestamp AND $2::timestamp;

toolsets:
  tickets_toolset:
    - search-tickets
    - get-ticket-by-id
    - get-tickets-by-assignee
    - get-tickets-by-status
    - get-tickets-by-priority
    - get-tickets-by-date-range
    - update-ticket-priority
    - update-ticket-status
    - create-new-ticket

Файл YAML определяет 9 инструментов , связанных с базой данных тикетов QuantumRoast.

Пришло время настроить учетную запись службы для службы Toolbox Cloud Run, предоставить ей разрешение на доступ к Cloud SQL и Secret Manager, а также создать секрет Secret Manager для нашего файла tools.yaml .

Secret Manager — это место, где мы будем хранить наш файл tools.yaml , поскольку он содержит конфиденциальные учетные данные Cloud SQL.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudsql.client

gcloud secrets create tools --data-file=tools.yaml

Пришло время развернуть MCP Toolbox for Databases в Cloud Run. Мы будем использовать последнюю версию образа контейнера MCP Toolbox.

gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --set-env-vars="PROJECT_ID=$PROJECT_ID" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --allow-unauthenticated

Дождитесь завершения развертывания...

Убедитесь, что Toolbox запущен, выполнив запрос к журналам Cloud Run:

gcloud run services logs read toolbox --region us-central1 --limit 10

Вы должны увидеть:

2025-08-20 18:03:55 2025-08-20T18:03:55.465847801Z INFO "Initialized 1 sources."
2025-08-20 18:03:55 2025-08-20T18:03:55.466152914Z INFO "Initialized 0 authServices."
2025-08-20 18:03:55 2025-08-20T18:03:55.466374245Z INFO "Initialized 9 tools."
2025-08-20 18:03:55 2025-08-20T18:03:55.466477938Z INFO "Initialized 2 toolsets."
2025-08-20 18:03:55 2025-08-20T18:03:55.467492303Z INFO "Server ready to serve!"

Сохраните URL-адрес Cloud Run для службы Toolbox как переменную среды, чтобы агент ADK знал, где его найти.

export MCP_TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format "value(status.url)")
echo MCP_TOOLBOX_URL=$MCP_TOOLBOX_URL >> software_bug_assistant/.env

Обновление агента QuantumRoast

Во-вторых, мы должны добавить в наш проект зависимость для MCP Toolbox for Databases SDK ( toolbox-core ):

uv add toolbox-core==0.5.0

Откройте файл tools.py , чтобы добавить поддержку инструментов MCP Toolbox.

cloudshell edit software_bug_assistant/tools.py

Добавьте следующее в конец tools.py :

# ----- Example MCP Toolbox for Databases tools -----
import os
from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = os.getenv("MCP_TOOLBOX_URL", "http://127.0.0.1:5000")

# Initialize Toolbox client
toolbox = ToolboxSyncClient(TOOLBOX_URL)
# Load all the tools from toolset
toolbox_tools = toolbox.load_toolset("tickets_toolset")

Теперь мы можем импортировать и передать toolbox_tools корневому агенту в agent.py :

cloudshell edit software_bug_assistant/agent.py

Вы можете заменить agent.py следующим кодом, чтобы включить toolbox_tools :

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools],
)

Сохраните файл и вернитесь на открытую вкладку с веб-интерфейсом ADK.

Если вы случайно закрыли терминал, на котором запущен веб-пользовательский интерфейс ADK, вы можете перезапустить его, выполнив команду uv run adk web --port 8080 --reload_agents .

Теперь вы можете задавать вопросы о билетах, хранящихся в нашей внутренней базе данных билетов Cloud SQL!

Задайте вопрос, подобный одному из следующих:

• I am seeing an issue with database timeouts, has anyone else seen a similar issue?
• How many bugs are assigned to [e-mail]? Show a table.
• Can you bump the priority of ticket with ID 6 to to P0 - Critical priority
• Create a new ticket (позвольте агенту провести вас через процесс создания ошибки)

Наш агент ADK успешно выполнил запрос к нашей базе данных с помощью инструментов MCP Toolbox for Databases !🚀

10. Дополнительно: инструмент MCP (API)

А как насчет подключения нашего агента ADK к инструментам MCP, у которых нет собственного SDK, как у MCP Toolbox for Database?

ADK поддерживает универсальные инструменты MCP через класс MCPToolset . Класс MCPToolset — это основной механизм ADK для интеграции инструментов с сервера MCP.

MCPToolset можно использовать для подключения к локальным или удалённым серверам MCP. В QuantumRoast мы хотим подключить нашего агента к удалённому серверу MCP GitHub , чтобы легко вызывать API GitHub. Это позволит нашему агенту получать информацию о проблемах из публичных репозиториев программного обеспечения или даже из наших собственных кодовых баз. Сервер MCP GitHub предоставляет доступ к различным функциям GitHub, от запросов на исправление и извлечения изменений до уведомлений и безопасности кода.

Персональный токен доступа GitHub (PAT)

Для аутентификации на сервере GitHub MCP вам понадобится GitHub Personal Access Token .

Чтобы его приобрести, выполните следующие действия:

1. Перейдите в настройки разработчика GitHub.
2. Нажмите «Персональные токены доступа» -> «Токены (классические)».
3. Нажмите «Сгенерировать новый токен» -> «Сгенерировать новый токен (классический)».
4. Дайте вашему токену описательное имя.
5. Установите срок действия вашего токена.
6. Важно : в целях безопасности предоставьте вашему токену максимально ограниченные возможности. Для доступа только на чтение к репозиториям обычно достаточно возможностей repo:status , public_repo и read:user . Не предоставляйте полные права доступа к репозиторию или права администратора без крайней необходимости.
7. Нажмите Generate token .
8. Скопируйте сгенерированный токен.

В терминале Cloud Shell выполните следующую команду, чтобы настроить PAT GitHub для использования агентом. Замените YOUR_GITHUB_PAT на сгенерированный PAT.

export GITHUB_PAT=YOUR_GITHUB_PAT

Обновление агента QuantumRoast

Для нашего помощника по ошибкам мы предоставим доступ только к некоторым инструментам GitHub, доступным только для чтения , чтобы сотрудники QuantumRoast могли находить проблемы, связанные с зависимостями с открытым исходным кодом, и посмотреть, поможет ли это выявить первопричины ошибок, которые они видят во внутренней системе тикетов. Для настройки мы будем использовать MCPToolset из ADK с tool_filter . tool-filter отображает только необходимые нам инструменты GitHub, что не только скрывает инструменты, к которым пользователи не должны получать доступ (например, конфиденциальные действия с репозиторием), но и защищает модель агента от перегрузки при выборе подходящего инструмента для работы.

Откройте файл tools.py , чтобы добавить поддержку инструментов GitHub.

cloudshell edit software_bug_assistant/tools.py

Добавьте следующее в конец tools.py :

# ----- Example MCP Tools with MCPToolset (GitHub) -----
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://api.githubcopilot.com/mcp/",
        headers={
            "Authorization": "Bearer " + os.getenv("GITHUB_PAT"),
        },
    ),
    # Read only tools
    tool_filter=[
        "search_repositories",
        "search_issues",
        "list_issues",
        "get_issue",
        "list_pull_requests",
        "get_pull_request",
    ],
)

Обратите внимание, что нам также необходимо предоставить токен доступа GitHub Personal Access Token (PAT) для определения MCPToolset , подобно тому, как вы предоставляете токен авторизации при настройке стандартного API-клиента в вашем коде. Этот PAT предназначен только для доступа к данным публичного репозитория, без доступа к конфиденциальным действиям пользователей или репозитория.

Теперь мы можем импортировать и передать mcp_tools корневому агенту в agent.py :

cloudshell edit software_bug_assistant/agent.py

Вы можете заменить agent.py следующим кодом, чтобы включить mcp_tools :

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, mcp_tools, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools, mcp_tools],
)

Сохраните файл и вернитесь на открытую вкладку с веб-интерфейсом ADK.

Если вы случайно закрыли терминал, на котором запущен веб-пользовательский интерфейс ADK, вы можете перезапустить его, выполнив команду uv run adk web --port 8080 --reload_agents .

Теперь у нас есть набор инструментов GitHub MCP, к которым может обращаться наш агент. Сервисы QuantumRoast используют XZ utils, инструмент сжатия данных . Наша внутренняя система отслеживания ошибок отслеживает CVE (уязвимость безопасности) прошлого года, которую мы можем отследить до репозитория XZ Utils GitHub с помощью инструментов StackOverflow и Google Search. Затем мы можем использовать один из инструментов GitHub MCP, search_issues , чтобы определить, когда и как эта CVE была исправлена:

Задайте агенту следующие вопросы:

• Find the official XZ Utils GitHub repository
• Search the repository for issues related to CVE-2024-3094

Вы должны увидеть, как агент вызывает инструменты GitHub.

Агент QuantumRoast ADK теперь может взаимодействовать с инструментами сервера GitHub MCP ! 🤩

11. Поздравления

Поздравляем! Вы успешно создали агент-помощник по обнаружению ошибок QuantumRoast с помощью Agent Development Kit (ADK) и интегрировали различные типы инструментов для расширения его возможностей. Вы начали с базового агента и постепенно добавляли инструменты функций, встроенные инструменты, сторонние инструменты и инструменты MCP.

Что мы рассмотрели

• Как настроить проект Python для разработки ADK.
• Как создать базовый агент ADK.
• Как реализовать и использовать функциональные инструменты.
• Как интегрировать встроенные инструменты, такие как Google Search.
• Как использовать сторонние инструменты из таких фреймворков, как LangChain, в ADK.
• Как использовать инструменты MCP для взаимодействия с базами данных (Cloud SQL) и API.

Очистка

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

Хотя Cloud Run не взимает плату, когда сервис не используется, с вас может взиматься плата за хранение образа контейнера в Artifact Registry. Удаление проекта Cloud прекращает выставление счетов за все ресурсы, используемые в этом проекте.

Если хотите, удалите проект:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Вы также можете удалить ненужные ресурсы с диска CloudShell. Вы можете:

1. Удалить каталог проекта codelab:

   rm -rf ~/quantum-roast
   

2. Внимание! Следующее действие нельзя отменить! Если вы хотите удалить всё из Cloud Shell, чтобы освободить место, вы можете удалить весь домашний каталог . Убедитесь, что всё, что вы хотите сохранить, сохранено где-то ещё.

   sudo rm -rf $HOME