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

1. Введение

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

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

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

2. Обзор

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

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

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

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

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

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

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

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

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

Основы работы с инструментами

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

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

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

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

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

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

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

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

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

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

Open Cloud Shell Editor

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 for 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 здесь .

Создайте базу данных Cloud 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 через API Vertex.

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 , которая будет использоваться в качестве инструмента Function.

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

Откройте файл 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

Для включения функции search_tool вы можете заменить agent.py следующим кодом:

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 Search! 🎉

Переходим к следующему типу инструментов 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

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

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 для PostgreSQL, используемая для поиска внутренних программных ошибок. Мы хотим создать инструменты ADK, чтобы наш агент мог выполнять определенные запросы к нашей базе данных.

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

В состав Toolbox входят:

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

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

Развертывание MCP Toolbox для сервера баз данных в облаке.

Сначала мы развернем 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" \
    --labels=dev-tutorial=codelab-toolbox \
    --no-invoker-iam-check

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

Убедитесь, что 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

Для включения toolbox_tools в файл agent.py можно заменить следующим кодом:

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

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

Для аутентификации на сервере GitHub MCP вам потребуется персональный токен доступа GitHub .

Для его приобретения выполните следующие шаги:

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 (PAT) в определении MCPToolset , точно так же, как вы указываете токен аутентификации при настройке стандартного API-клиента в вашем коде. Этот PAT предназначен только для доступа к общедоступным данным репозитория и не распространяется на конфиденциальные действия пользователей или репозитория.

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

cloudshell edit software_bug_assistant/agent.py

Для включения mcp_tools в файл agent.py можно заменить следующим кодом:

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. Затем мы можем использовать один из инструментов GitHub MCP, search_issues , чтобы определить, когда и как эта уязвимость была исправлена:

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

• 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.
• Как использовать сторонние инструменты из таких фреймворков, как LangChain, в рамках ADK.
• Как использовать инструменты MCP для взаимодействия с базами данных (Cloud SQL) и API.

Уборка

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

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

При желании вы можете удалить проект:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Также вы можете удалить ненужные ресурсы с диска Cloudshell. Для этого выполните следующие действия:

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

   rm -rf ~/quantum-roast
   

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

   sudo rm -rf $HOME