За пределами панелей управления: создание автономного агента-аналитика данных BigQuery
Автономный агент-аналитик данных BigQuery с Google ADK и Gemini: почему панели управления и примитивные инструменты преобразования текста в SQL терпят неудачу на заключительном этапе, и как это исправить в CI/CD.
В этом руководстве пошагово описывается процесс создания системы, начиная с сырьевых материалов и заканчивая готовым решением для проекта «Beyond Dashboards: Building an Autonomous BigQuery Data Analyst Agent with Google ADK for Customer 360». Основное внимание уделяется практическим шагам, четким проверкам и коду, который можно просто добавить в репозиторий без необходимости догадываться о его назначении. На этапе обзора необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не пытаясь разобраться в скрытом состоянии системы. Рекомендуется использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой всего процесса.
1. Узкое место на завершающем этапе: почему традиционные инструменты BI и примитивные методы преобразования текста в SQL терпят неудачу
При работе над этапом «Узкое место на последнем этапе» сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безусловного частичного выполнения задачи. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Почему традиционные панели BI перестают работать
При работе над этапом «Почему традиционные панели BI?» сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и последствия частичной неудачи. Такой список поможет избежать ошибок при последующих изменениях кода. Рядом с функциональными результатами занесите информацию о времени выполнения и стоимости токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным. Устанавливайте контрольные точки после дорогостоящих операций — система не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить следующий шаг заново.
Почему наивные инструменты преобразования «текст в SQL» на основе больших языковых моделей терпят неудачу в корпоративной среде
При работе над этапом «Почему Naive Text-to-SQL LLM» сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Храните в кэше стабильные инструкции системы и схемы инструментов. Пересылка одинаковых данных несколько раз — распространённая причина ресурсозатрат. При работе над этапом «Почему Naive Text-to-SQL LLM» сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Воздерживайтесь от использования обширных скриптов в пользу небольших, тестируемых единиц. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
2. Архитектура агентов: фреймворк Google ADK
Архитектура агентов работает наилучшим образом, когда её рассматривают как измеримую структуру. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению последовательности выполнения операций после прерываний.
3. Основа инженерии 1: закрепление знаний и кэширование контекста в Vertex AI
Этап 1 третьего инженерного столпа работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.
Компиляция словарей Markdown в системный промпт
Процесс преобразования словарей Markdown в стадию разработки работает наилучшим образом, когда его рассматривают как измеримую сферу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Установите лимиты на количество токенов за один ход и за сессию. Инструменты типа агентов активно расширяют контекст; строгие ограничения предотвращают появление неожиданных счетов. Процесс преобразования словарей Markdown в стадию разработки работает наилучшим образом, когда его рассматривают как измеримую сферу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
# c360_agent/config.py
import os
import glob
def compile_knowledge_base(knowledge_dir: str) -> str:
"""Recursively compiles markdown architecture guides into structured agent context."""
context_chunks = []
guide_files = glob.glob(os.path.join(knowledge_dir, "**/*.md"), recursive=True)
for file_path in sorted(guide_files):
with open(file_path, "r", encoding="utf-8") as f:
rel_name = os.path.relpath(file_path, knowledge_dir)
content = f.read()
context_chunks.append(f"### KNOWLEDGE GUIDE: {rel_name}\n\n{content}\n")
return "\n---\n".join(context_chunks)
KNOWLEDGE_CONTEXT = compile_knowledge_base("c360_agent/knowledge")
SYSTEM_PROMPT = f"""
You are an expert BigQuery Data Analyst Agent for an Enterprise Customer 360 (C360) Lakehouse.
Your mission is to answer business and analytical questions by generating and executing accurate, cost-effective SQL queries.
CRITICAL OPERATIONAL RULES:
1. TARGET CONFORMED MARTS FIRST: Always query `c360_curated_unified` for golden demographics or cross-system questions. Use Spoke marts (`c360_curated_*`) only for system-specific line-item grain.
2. MANDATORY DRY RUN: You MUST execute `dry_run_bq_query` on every generated SQL statement before calling `execute_bq_query`. Inspect syntax and bytes scanned.
3. CLUSTER AWARENESS: Always filter or join on clustered keys (`UnifiedCustomerDimId`, `UnifiedOrderDimId`) to minimize BigQuery slot consumption.
4. STRICT READ-ONLY: You are strictly forbidden from executing INSERT, UPDATE, DELETE, DROP, or ALTER statements.
DOMAIN ARCHITECTURE CONTEXT:
{KNOWLEDGE_CONTEXT}
"""
Фактор, меняющий ситуацию с затратами: кэширование контекста Vertex AI
Для этапа Vertex, направленного на снижение затрат, необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым файлам, определите критерии успешного выполнения и не допускайте молчаливого частичного завершения задачи. Внедрите процедуру утверждения человеком для тех операций, которые влекут за собой расходы денег или изменение производственных данных. Простое подключение компонентов во время компиляции не гарантирует полноты выполнения бизнес-задач.
# c360_agent/agent.py
from google.adk.agents.llm_agent import Agent
from google.adk.apps import App
from google.adk.agents.context_cache_config import ContextCacheConfig
from .config import SYSTEM_PROMPT
from .tools import (
execute_bq_query,
dry_run_bq_query,
get_table_schema,
list_dataset_tables,
get_table_preview
)
# 1. Initialize the Google ADK Agent
root_agent = Agent(
name="c360_data_analyst",
model="projects/enterprise-c360-prod/locations/us-central1/publishers/google/models/gemini-2.5-flash",
description="Autonomous BigQuery Data Analyst for the Enterprise Customer 360 Lakehouse.",
instruction=SYSTEM_PROMPT,
tools=[
dry_run_bq_query,
execute_bq_query,
get_table_schema,
list_dataset_tables,
get_table_preview
]
)
# 2. Wrap in App with Vertex AI Context Caching
app = App(
name="c360_agent_app",
root_agent=root_agent,
context_cache_config=ContextCacheConfig(
ttl_seconds=1800, # Cache prompt for 30 minutes
cache_intervals=10 # Reuse across up to 10 conversational turns
)
)
4. Второй столп инженерии: безопасное выполнение инструментов с контролем затрат
Для 4-го этапа Engineering Pillar 2 необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токена или запроса. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Аутентификация производится у шлюза, а повторная авторизация — на уровне данных. Один только токен-носитель не является границей аренды.
# c360_agent/tools.py
import subprocess
import re
def dry_run_bq_query(query: str) -> str:
"""Dry-runs a BigQuery SQL query to validate syntax and estimate bytes scanned."""
clean_query = query.strip().upper()
# Layer 1: Strict Read-Only Guard
if not (clean_query.startswith("SELECT") or clean_query.startswith("WITH")):
return "SECURITY ERROR: Only SELECT queries are permitted. DDL/DML is strictly forbidden."
try:
# Executes 'bq query --dry_run' to inspect execution planner without billing slots
result = subprocess.run(
["bq", "query", "--use_legacy_sql=false", "--dry_run", query],
capture_output=True,
text=True,
check=True
)
# bq CLI outputs estimated bytes scanned to stderr on dry run
dry_run_output = result.stderr if result.stderr else result.stdout
return f"DRY_RUN SUCCESS: {dry_run_output.strip()}"
except subprocess.CalledProcessError as e:
return f"DRY_RUN SYNTAX ERROR: {e.stderr.strip()}"
def execute_bq_query(query: str) -> str:
"""Executes a validated BigQuery SQL query and returns the formatted tabular results."""
clean_query = query.strip().upper()
if not (clean_query.startswith("SELECT") or clean_query.startswith("WITH")):
return "SECURITY ERROR: Only SELECT queries are permitted."
try:
result = subprocess.run(
["bq", "query", "--use_legacy_sql=false", "--format=pretty", "--max_rows=50", query],
capture_output=True,
text=True,
check=True
)
return result.stdout
except subprocess.CalledProcessError as e:
return f"EXECUTION ERROR: {e.stderr.strip()}"
5. Engineering Pillar 3: Цикл автономной самокоррекции
На этапе 3 пяти основ инженерии необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. На этапе 3 пяти основ инженерии необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на запутанную цепочку операций.
Реальный след производства: самовосстанавливающийся цикл в действии
При работе с этапом «Реальный след производства» сначала запишите контракт: необходимые входные данные, сигнал о успехе и то, что происходит при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задач. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Вопрос бизнес-пользователя
При работе над этапом «Бизнес-пользователь» сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами занесите информацию о времени выполнения и стоимости токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить последующий узел.
Шаг 1: Первая попытка и отклонение компилятором
На этапе первой попытки в рамках Шага 1 сначала запишите условия работы: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список поможет сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы с настройками, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна повторно оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап. На этапе первой попытки в рамках Шага 1 сначала запишите условия работы: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список поможет сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое какого-либо этапа причина неудачи должна указывать на конкретную ответственность, а не на запутанную структуру обработки данных.
-- Attempt 1: Generated by Agent (Pre-Flight Dry Run)
SELECT
SUM(c.total_spent) AS total_vip_revenue
FROM `enterprise-c360-prod.c360_curated_shopify.dim_customer` c
JOIN `enterprise-c360-prod.c360_curated_shopify.CustomerWarranties` w
ON c.customer_id = w.customer_id;
Шаг 2: Автономная диагностика и самокоррекция
Этап автономной диагностики на шаге 2 работает наилучшим образом, если рассматривать его как измеримую структуру. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым объектам, определите критерии успешного выполнения и не допускайте молчаливого частичного завершения задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
SELECT SUM(c.total_spent) AS total_vip_revenue
FROM `enterprise-c360-prod.c360_curated_shopify.dim_customer` c
JOIN `enterprise-c360-prod.c360_curated_shopify.CustomerWarranties` w
- ON c.customer_id = w.customer_id;
+ ON c.UnifiedCustomerDimId = w.UnifiedCustomerDimId;
Шаг 3: Проверка затрат перед запуском
Этап оценки затрат перед запуском на третьем шаге работает наилучшим образом, если рассматриваться как измеримая величина. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на ранней стадии помогает избежать неожиданных счетов при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению последовательности выполнения после перерывов.
Шаг 4: Ограниченная экспекуция и синтез результатов
Этап ограниченной экспекуции шага 4 работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний. Этап ограниченной экспекуции шага 4 работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда происходит сбой на каком-либо этапе, он должен указывать на конкретную проблему, а не на запутанную цепочку операций.
6. От терминальной командной строки к интерактивному веб-интерфейсу
На этапе 6 «Использование терминала CLI» необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Укажите названия файлов, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Обязательно включайте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Настройки, сделанные во время компиляции, не гарантируют полноты выполнения бизнес-задач.
Режим 1: Терминал CLI для инженеров по данным и систем CI/CD
На этапе CLI-терминала режима 1 необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Для операций, связанных с расходами или изменением производственных данных, требуется утверждение человека. Настройки во время компиляции не гарантируют полноты обработки бизнес-логики.
python3 c360_agent/agent.py "Show me top 5 customers by SAP delivery volume in 2026"
Режим 2: Интерактивная веб-консоль отладки (adk web)
Для этапа интерактивного веб-интерфейса режима 2 необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Вводите ручное утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. Для этапа интерактивного веб-интерфейса режима 2 необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на запутанную структуру обработки данных.
Итог.
adk web --port 8001 c360_agent --reload
Краткое резюме: Чек-лист автономного агента в корпоративной среде
При работе над этапом автономных агентов в корпоративной среде сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия элементам, определите критерии успешности и не допускайте безответственного частичного выполнения задач. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Завершение трилогии: Современная основа данных для корпораций
При работе над этапом «Завершение трilogии» сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Очевидность затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить последующий узел.
Чек-лист операционной деятельности
Этап чек-листа операционной деятельности работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ.
Документируйте как успешный путь выполнения, так и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
Сохраняйте состояние графа в простом и типизированном виде. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
При наличии бюджета добавляйте тесты для проверки критического пути в процессе интеграционного тестирования с использованием фикстур, а не реальных платных API.
Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
Сохраняйте состояние графа в простом и типизированном виде. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.