За межами панелей керування: створення автономного агента-аналітика даних 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 зазнають невдачі
Під час роботи над етапом 1 «Вузьке місце останньої дистанції» спочатку запишіть угоду: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як угоду між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безпроблемного часткового виконання. Робіть контрольні пункти після дорогих кроків. Система відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор намагається знову виконати пізнішу операцію.
Чому традиційні панелі BI припиняють працювати
Під час роботи над етапом «Чому традиційні панелі BI?» спочатку запишіть умови використання: необхідні вхідні дані, сигнал успіху та наслідки часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Ясність щодо витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ. Робіть контрольні пункти після дорогих кроків. Система не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізніший етап.
Чому наївні інструменти типу «Текст-до-SQL» на основі LLM зазнають невдач у корпоративних середовищах
Під час роботи над етапом «Чому Naive Text-to-SQL LLM» спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретів та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною витрат ресурсів. Під час роботи над етапом «Чому Naive Text-to-SQL LLM» спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Віддавайте перевагу малим, тестованим одиницям коду перед величезними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій.
2. Архітектура агентів: фреймворк Google ADK
Архітектура агентів працює найкраще, коли її розглядають як вимірювану поверхню. Збережіть один ідеальний зразок роботи, один випадок невдачі та примітки щодо скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Зберігайте стан графа у простій та типованій формі. Вкладені структури приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв.
3. Основа інженерії 1: закріплення знань та кешування контексту Vertex AI
Етап 1 з 3 інженерних стовпів працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ. Зберігайте стан графа у випрямленому та типованому форматі. Вкладені блоки приховують інформацію про те, який вузол заповнив яке поле, та ускладнюють продовження роботи після перерв.
Компіляція словників 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-му етапі 5-го енжинерного стовпа необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь код. Встановлюйте людське схвалення для кроків, які спричиняють витрати грошей або змінюють дані в продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функцій. На 3-му етапі 5-го енжинерного стовпа необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру процесів.
Необхідно.
Реальний слід виробництва: самовідновлювальний цикл у дії
Під час роботи з етапом «Реальний слід виробництва» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте елементи, визначте критерії успіху та не допускайте беззвучного часткового виконання. Робіть контрольні пункти після дорогих кроків. Система відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор перезапускає пізнішу ланку.
Питання бізнес-користувача
Під час роботи над етапом «Бізнес-користувач» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ. Робіть контрольні пункти після дорогих кроків. Система повторного запуску не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перепробовує пізніший етап.
Крок 1: Початкова спроба та відхилення компілятором
Під час виконання етапу «Перша спроба, крок 1», спочатку запишіть умови використання: необхідні дані вхіду, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Робіть контрольні точки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізнішу ланку. Під час виконання етапу «Перша спроба, крок 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: Перевірка витрат перед запуском
Етап оцінки витрат перед запуском на 3-му кроці найефективніше функціонує, якщо його розглядати як вимірювану характеристику. Збережіть один ідеальний зразок роботи системи, один випадок збою та запис про повернення до попереднього стану перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ. Зберігайте стан графа у простому та типованому вигляді. Вкладені структури приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв.
Крок 4: Обмежене виконання та синтез результатів
Етап обмеженої екзекуції кроку 4 працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретів та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф. Тримайте стан графа простим та типованим. Вкладені блоки приховують інформацію про те, який вузол записав яке поле, і ускладнюють продовження роботи після перерв. Етап обмеженої екзекуції кроку 4 працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу. Віддавайте перевагу малим, тестованим одиницям перед величезними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.
6. Від терміналу CLI до інтерактивного веб-інтерфейсу
На етапі 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)
Для етапу Interaktивний веб режиму 2 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Зберігайте конфігурацію поза кодом додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь алгоритм. Встановлюйте людське схвалення для дій, які спричиняють витрати грошей чи змінюють дані у продакшені. Підключення під час компіляції не є гарантією повноти бізнес-процесу. Для етапу Interaktивний веб режиму 2 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Віддавайте перевагу малим, тестованим одиницям перед величезними скриптами. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру процесу.
Необхідно.
adk web --port 8001 c360_agent --reload
Підсумок: Чек-лист автономного агента підприємства
Під час роботи над етапом «Автономне підприємство» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей чек-лист допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безповідомного часткового виконання. Робіть контрольні пункти після дорогих кроків. Система повернення до виконання не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається виконати наступний етап.
Завершення трилогії: Сучасна база даних підприємства
Під час роботи над етапом «Трилогія завершена» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із результатами функціонування. Відображення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ. Робіть контрольні пункти після дорогих кроків. Функція відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізніший етап.
Перелік операційних кроків
Етап переліку операційних кроків працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи.
Документуйте як успішний, так і відновлювальний сценарії. Перезапуски, людські перевірки та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки.
Зберігайте стан графа у вигляді плоскої структури з типизованими елементами. Вкладені блоки приховують інформацію про те, який вузол заповнив певне поле, і ускладнюють продовження роботи після перерв.
Додайте тест на базову функціональність, який перевіряє критичний шлях у процесі інтеграційного тестування за допомогою фікстур, а не реальних платних API, коли це дозволяють бюджетні обмеження.
Віддавайте перевагу невеликим, тестованим одиницям коду перед складними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій.
Зберігайте стан графа у вигляді плоскої структури з типизованими елементами. Вкладені блоки приховують інформацію про те, який вузол заповнив певне поле, і ускладнюють продовження роботи після перерв.