Анализируйте выполнение агента ADK с помощью плагина BigQuery Agent Analytics

1. Введение

В этом практическом занятии вы создадите многоагентную систему, используя комплект разработки агентов (ADK), и включите функцию мониторинга агентов с помощью плагина BigQuery Agent Analytics. Вы зададите агенту ряд вопросов , а затем используете BigQuery для анализа трассировки разговоров и использования инструментов агентом.

c8d3754ee87af43f.png

Что вы будете делать

  • Создайте многоагентного розничного ассистента с помощью ADK.
  • Инициализируйте плагин BigQuery Agent Analytics для сбора и сохранения данных трассировки о выполнении этого агента в BigQuery.
  • Проанализируйте данные журналов агента в BigQuery.

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

  • Веб-браузер, например Chrome.
  • Проект Google Cloud с включенной функцией выставления счетов, или
  • Аккаунт Gmail. В следующем разделе вы узнаете, как получить бесплатный кредит в размере 5 долларов на этот практический курс и создать новый проект.

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

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

Создайте проект в Google Cloud.

  1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .

c745d833b0ed52b0.png

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

Запустить Cloud Shell

Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами.

  1. В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» :

404e4cce0f23e5c5.png

  1. После подключения к Cloud Shell выполните следующую команду для проверки аутентификации в Cloud Shell: 
gcloud auth list
  1. Выполните следующую команду, чтобы убедиться, что ваш проект настроен для использования с gcloud: 
gcloud config get project
  1. Если ваш проект настроен не так, как ожидалось, используйте следующую команду для его настройки: 
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Включить API

  1. Выполните эту команду, чтобы включить все необходимые API и сервисы: 
gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com
  1. После успешного выполнения команды вы должны увидеть сообщение, похожее на показанное ниже:

Операция "операции/..." успешно завершена.

3. Установка и настройка

Вернитесь в Cloud Shell и убедитесь, что вы находитесь в своей домашней директории.

Выполните следующую команду в Cloud Shell, чтобы создать новый набор данных с именем adk_logs в BigQuery:

bq mk --dataset --location=US adk_logs

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

  1. Откройте новую вкладку терминала в Cloud Shell и выполните эту команду, чтобы создать папку с именем adk-agent-observability и перейти в неё: 
mkdir adk-agent-observability
cd adk-agent-observability
  1. Создайте виртуальную среду Python: 
python -m venv .venv
  1. Активируйте виртуальную среду: 
source .venv/bin/activate
  1. Установите ADK: 
pip install --upgrade google-adk

4. Создайте приложение ADK.

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

  1. Выполните команду утилиты adk create , чтобы создать новое приложение-агент с необходимыми папками и файлами: 
adk create retail_assistant_app

Следуйте инструкциям:

  1. Выберите модель gemini-2.5-flash .
  2. Выберите Vertex AI для бэкэнда.
  3. Подтвердите свой идентификатор проекта Google Cloud по умолчанию и регион.

Пример взаимодействия показан ниже:

acc9c6bb436f7025.png

  1. Нажмите кнопку «Открыть редактор» в Cloud Shell, чтобы открыть редактор Cloud Shell и просмотреть созданные папки и файлы:

a940b7eaf3c9f4b3.png

Обратите внимание на сгенерированные файлы: 

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env
  • init.py: Помечает папку как модуль Python.
  • agent.py: Содержит исходное определение агента.
  • .env: Возможно, вам потребуется нажать «Вид» > «Отключить отображение скрытых файлов», чтобы просмотреть этот файл.

16a1a92b33f78e6b.png

  • Файл .env содержит переменные окружения для вашего проекта. Обновите все переменные, которые были установлены неправильно, в ответ на подсказки: 
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Определите своего агента.

Теперь давайте определим иерархическую многоагентную систему.

  1. Агент трендов в реальном времени: использует поиск Google для поиска актуальных модных тенденций.
  2. Агент данных об инвентаризации: использует набор инструментов BigQuery для запроса общедоступного набора данных thelook_ecommerce на предмет наличия товаров.
  3. Помощник продавца (Корневой) Агент: Организует рабочий процесс, обращаясь за советом к Агенту трендов и к Агенту инвентаризации для подбора соответствующих товаров.

Замените все содержимое файла retail_assistant_app/agent.py следующим кодом. 

import os
import uuid
import asyncio
import google.auth
import dotenv
from google.genai import types
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.adk.tools import AgentTool, google_search
from google.adk.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

dotenv.load_dotenv()

# --- Configuration ---

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
DATASET_ID = "adk_logs"
TABLE_ID = "retail_assistant_agent_logs"
APP_NAME = "retail_assistant_agent"
USER_ID = "test_user"

# --- Toolsets ---

credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(
 credentials_config=credentials_config
)

# --- Agents ---

# 1. Trend Spotter
real_time_agent = Agent(
   name="real_time_agent",
   model="gemini-2.5-flash",
    description="Researches external factors like weather, local events, and current fashion trends.",
   instruction="""
       You are a real-time research agent.
       Use Google Search to find real-time information relevant to the user's request,
       such as the current weather in their location or trending styles.
   """,
   tools=[google_search]
)

# 2. Inventory Manager
inventory_data_agent = Agent(
   name="inventory_data_agent",
   model="gemini-2.5-flash",
   description="Oversees product inventory in the BigQuery `thelook_ecommerce` dataset to find available items and prices.",
   instruction=f"""
   You manage the inventory. You have access to the `bigquery-public-data.thelook_ecommerce` dataset via the BigQuery toolset.
   Run all BigQuery queries the project id of: '{PROJECT_ID}'
  
   Your workflow:
   1. Look at the products table.
   2. Find items that match the requirements, factor in the results from the trend_setter agent if there are any.
   3. Return with a user friendly response, including the list of specific products and prices.
   """,
   tools=[bigquery_toolset]
)

# 3. Root Orchestrator
root_agent = Agent(
   name="retail_assistant",
   model="gemini-2.5-flash",   
   description="The primary orchestrator, responsible for handling user input, delegating to sub-agents, and synthesizing the final product recommendation.",
   instruction="""
   You are a Retail Assistant.   
   You can ask the 'real_time_agent' agent for any realtime information needed, or style advice, include any information provided by the user.
   You should ask the 'inventory_data_agent' agent to find a maximum of 3 available items matching that style.
   Combine the results into a recommendation.
   """,
   tools=[AgentTool(agent=real_time_agent)],
   sub_agents=[inventory_data_agent]
)

6. Создавайте журналы с помощью плагина BigQuery Agent Analytics.

Теперь давайте настроим плагин BigQuery Agent Analytics для сбора данных о выполнении запросов.

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

Приведённый ниже код:

  • Инициализирует плагин логирования: создает объект BigQueryAgentAnalyticsPlugin с необходимыми данными для подключения.
  • Интегрирует плагин: передает инициализированный плагин BigQuery в конструктор App , обеспечивая автоматический захват и регистрацию событий выполнения агента.
  • Запуск и регистрация выполнения агента: выполняет диалоговый процесс с помощью runner.run_async , при этом плагин одновременно собирает и отправляет всю последовательность событий в BigQuery, прежде чем закрыть свои ресурсы.

Скопируйте и вставьте этот код ниже определений агентов в файле agent.py : 

async def main(prompt: str):
    """Runs a conversation with the BigQuery agent using the ADK Runner."""
    bq_logger_plugin = BigQueryAgentAnalyticsPlugin(
        project_id=PROJECT_ID, dataset_id=DATASET_ID, table_id=TABLE_ID
    )
    app = App(name=APP_NAME, root_agent=root_agent, plugins=[bq_logger_plugin])
    runner = InMemoryRunner(app=app)

    try:
        session_id = f"{USER_ID}_{uuid.uuid4().hex[:8]}"

        my_session = await runner.session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID, session_id=session_id
        )

        async for event in runner.run_async(
            user_id=USER_ID,
            new_message=types.Content(
                role="user", parts=[types.Part.from_text(text=prompt)]
            ),
            session_id=my_session.id,
        ):
            if event.content.parts and event.content.parts[0].text:
                print(f"** {event.author}: {event.content.parts[0].text}")

    except Exception as e:
        print(f"Error in main: {e}")
    finally:
        print("Closing BQ Plugin...")
        await bq_logger_plugin.close()
        print("BQ Plugin closed.")

async def run_all_prompts():
    """Runs all prompts in a single event loop."""
    prompts = [
        "what outfits do you have available that are suitable for the weather in london this week?",
        "You are such a cool agent! I need a gift idea for my friend who likes yoga.",
        "I'd like to complain - the products sold here are not very good quality!"
    ]
    for prompt in prompts:
        await main(prompt)

if __name__ == "__main__":
    asyncio.run(run_all_prompts())

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

python retail_assistant_app/agent.py

Вы должны увидеть, как продавец-консультант организует рабочий процесс:

  1. Программа запрашивает у агента анализа трендов в реальном времени (real_time_agent) информацию о погоде в Лондоне и поиск подходящих модных тенденций.
  2. Затем система делегирует запрос агенту данных инвентаризации (inventory_data_agent) для поиска в наборе данных BigQuery thelook_ecommerce конкретных товаров, соответствующих этим тенденциям.
  3. В заключение, Root Orchestrator обобщает результаты и формирует окончательную рекомендацию.

При этом плагин передает трассировку выполнения агента в BigQuery.

7. Анализ журналов агентов

Использование инструментов

Теперь мы можем видеть, чем занимался наш агент за кулисами! Данные переданы в BigQuery и готовы к анализу:

  1. В консоли Google Cloud найдите BigQuery .
  2. В панели «Проводник» найдите свой проект.
  3. Разверните набор данных adk_logs .
  4. Откройте таблицу retail_assitant_agent_logs и нажмите кнопку «Запрос» .

a2de3b52da21855f.png

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

SELECT
  -- Extract the tool name directly from the JSON key "tool"
  JSON_VALUE(content, '$.tool') AS tool_name,
  -- Count every time a tool finished (successfully or with an error)
  COUNT(*) AS total_finished_runs,
  -- Count as a failure if  event_type is ERROR, result object contains a status of 'ERROR', or error_details exist
  COUNTIF(
    event_type = 'TOOL_ERROR' OR
    JSON_VALUE(content, '$.result.status') = 'ERROR' OR
    JSON_VALUE(content, '$.result.error_details') IS NOT NULL
  ) AS failure_count
FROM
  `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
  1;

Нажмите на кнопку «Визуализация», чтобы просмотреть результаты в виде диаграммы ( ваши результаты могут отличаться ):

2e8d009e3e0459ed.png

Использование токенов

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

SELECT
 t.agent,
 SUM(LAX_INT64(t.content.usage.prompt)) AS prompt_tokens,
 SUM(LAX_INT64(t.content.usage.completion)) AS completion_tokens
FROM
 `adk_logs.retail_assistant_agent_logs` AS t
WHERE
 t.event_type = 'LLM_RESPONSE'
 -- Filter for records that actually contain usage metadata
 AND t.content.usage IS NOT NULL
GROUP BY 1;

Нажмите на кнопку «Визуализация», чтобы просмотреть результаты в виде диаграммы ( ваши результаты могут отличаться ):

134dc090ba55372d.png

8. [Бонус] Анализ пользовательских настроений

Теперь давайте проанализируем эмоциональное содержание пользовательского ввода, предоставленного агенту.

  1. В Cloud Shell создайте подключение к облачному ресурсу , чтобы BigQuery мог взаимодействовать с сервисами Vertex AI: 
bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

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

Соединение 517325854360.us.test_connection успешно установлено.

  1. Создайте подключение к облачному ресурсу: 
export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)
  1. Выполните эту команду, чтобы убедиться в успешном создании учетной записи службы: 
echo $SERVICE_ACCOUNT_EMAIL

Вы должны увидеть свою учетную запись службы:

c4a155d9d005e3d8.jpeg

  1. Предоставьте учетной записи службы подключения к ресурсам необходимые разрешения на уровне проекта для взаимодействия с Vertex AI: 
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/bigquery.connectionUser' && \
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/aiplatform.user'

Подождите несколько минут, пока обработаются разрешения. Затем вернитесь в BigQuery и выполните следующий запрос, содержащий функцию AI.SCORE для анализа настроения пользователей: 

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', JSON_VALUE(content.text_summary),
   'Use a scale from 1 to 5.'),
 connection_id => 'us.test_connection') AS user_sentiment
FROM
 `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type = 'USER_MESSAGE_RECEIVED'
ORDER BY
 user_sentiment DESC;

Функция AI.SCORE присвоит каждому пользовательскому вводу значение эмоциональной окраски от 1 до 5. Вы должны увидеть результаты, похожие на эти:

4e345b703b86cde8.jpeg

9. Уборка

Чтобы избежать дальнейших списаний средств с вашего аккаунта Google Cloud, удалите ресурсы, созданные в ходе этого семинара.

Удалите набор данных логирования, созданный скриптом: 

bq rm -r -f -d $PROJECT_ID:adk_logs

Удалите подключение к облачному ресурсу: 

bq rm --connection --project_id=$PROJECT_ID --location=us test_connection

Чтобы удалить каталог bigquery-adk-codelab и его содержимое: 

cd .. 
rm -rf adk-agent-observability

10. Поздравляем!

Поздравляем! Вы создали многоагентную систему с помощью Agent Development Kit (ADK) и успешно интегрировали плагин BigQuery Agent Analytics для отслеживания и аудита поведения ваших агентов.

Справочная документация