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

1. Введение

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

c8d3754ee87af43f.png

Что ты будешь делать?

  • Создайте многоагентного помощника по розничной торговле с помощью ADK
  • Инициализируйте плагин аналитики BigQuery Agent для сбора и сохранения данных трассировки о выполнении этих агентов в 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. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud:

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. При успешном выполнении команды вы должны увидеть сообщение, похожее на показанное ниже:

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

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 Editor и просмотреть вновь созданные папки и файлы:

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. Real Time Trend Agent: использует поиск 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 для сбора данных о выполнении.

Для этого вам нужно создать экземпляр класса 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.")

if __name__ == "__main__":
   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, prompt in enumerate(prompts):
       asyncio.run(main(prompt))

Теперь, когда всё необходимое готово, пора увидеть агента в действии. Запустите скрипт, чтобы запустить рабочий процесс беседы. 

python retail_assistant_app/agent.py

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

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

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

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

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

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

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

a2de3b52da21855f.png

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

SELECT
   -- Extract text between "Tool Name: " and the next comma (or end of line)
   REGEXP_EXTRACT(content, r'Tool Name: ([^,]+)') AS tool_name,
   -- Count every time a tool finished (successfully or with an error)
   COUNT(*) AS total_finished_runs,
   -- Count it as a failure if it's an explicit system error OR contains "error" in the text
   COUNTIF(event_type = 'TOOL_ERROR' OR REGEXP_CONTAINS(content, r'(?i)\berror\b')) 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(CAST(REGEXP_EXTRACT(t.content, r'prompt:\s*(\d+)') AS INT64)) AS prompt_tokens,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'candidates:\s*(\d+)') AS INT64)) AS candidate_tokens
   FROM
     `adk_logs.retail_assistant_agent_logs` AS t
   WHERE
     t.event_type = 'LLM_RESPONSE'
     AND t.content LIKE '%Token Usage: %'
   GROUP BY 1

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

134dc090ba55372d.png

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

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

  1. Создайте подключение к облачному ресурсу , чтобы 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:', content,
   '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

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

cd .. 
rm -rf adk-agent-observability

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

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

Справочные документы