| name | rmi-dataagent-helper |
| description | Use this skill to configure, optimize, and ground BigQuery Conversational Data Agents for RMI. When invoked, helps users select a persona profile (TOM, Urban Planner, BQ Admin, Data Engineer, Data Scientist, or RMI Planner) to receive tailored grounding mantras, glossary definitions, and verified golden queries. |
| dependencies | ["api-geminidataanalytics","rmi-sql"] |
RMI BigQuery Data Agent Helper
[!NOTE]
Conceptual Layer vs. NLP Implementation Layer:
rmi-personas serves as the Conceptual Layer, defining high-level business challenges, quantitative SLAs, and cross-persona lifecycles.rmi-dataagent-helper serves as the NLP Implementation Layer. It translates those conceptual personas into machine-readable prompts, grounding indices, glossary terms, and verified golden queries (rmi-sql) to optimize BigQuery Conversational Data Agents.
This skill provides expert guidance and tooling to configure, ground, and programmatically manage BigQuery Conversational Data Agents for Roads Management Insights.
1. Persona-Driven Activation Workflow
When assisting a user with configuring a BigQuery Data Agent:
- Identify Target Persona: Determine which of the 6 GA personas (or preview roles) the agent is being configured for:
- Traffic Operations Manager (TOM): Real-time incidents, bottlenecks, detour detection.
- Urban Planner (UP): Infrastructure ROI, before-and-after studies, TTI/PTI indices.
- BigQuery Admin (BQA): Spend governance, slot contention, zero-cost audits.
- Data Engineer (DE): Ingestion lag, geometry validation, 2-stage SRI pre-aggregations.
- Data Scientist (DS): Z-score anomalies, predictive forecasting (TimesFM/ARIMA_PLUS), reliability ranking.
- RMI Planner (RMIP): Total Addressable Monitoring (TAM) coverage, commercial tier SLAs, compute growth budgeting.
- Retrieve Grounding Mantra & Glossary: Load the corresponding section from
references/persona_setup_guides.md.
- Inject Verified Golden Queries: Map the corresponding SQL assets from
rmi-sql into the Data Agent's sampleQueries field.
2. Global Grounding & Schema Annotation Principles
Regardless of persona, all RMI Conversational Data Agents require strong metadata grounding:
2.1 Metadata-Enriched Views
Annotate views and underlying physical tables using ALTER VIEW ... SET OPTIONS so the LLM semantic parser accurately interprets column semantics:
ALTER VIEW `my_project.rmi.cleaned_routes`
SET OPTIONS (
description="Main analytical view for RMI route performance, travel times, and SRI sub-segment speeds."
);
ALTER COLUMN duration_in_seconds
SET OPTIONS(description="Traffic-aware actual trip duration in seconds.")
ON `my_project.rmi.cleaned_routes`;
2.2 Standard Job ID Headers
Instruct the Data Agent to prepend standardized rmica_ Job IDs to all generated SQL:
3. Grounding Index & Golden Query Assets
To prevent hallucinated column names and unpartitioned scans, ground the conversational agent with verified golden queries from rmi-sql:
| Persona | Primary Grounding Focus | Key Golden Queries (rmi-sql) | Reference Guide |
|---|
| Traffic Ops Manager | Incidents, SRIs, Detour Fingerprints | tom1_peak_hour_delay.sql, tom2_persistent_bottlenecks.sql, tom6_dynamic_detour_detection.sql | TOM Guide |
| Urban Planner | Before/After ROI, TTI/PTI, Emissions | up1_corridor_trend.sql, up2_impact_analysis.sql, up4_weekend_vs_weekday.sql | UP Guide |
| BigQuery Admin | Spend, Slots, INFORMATION_SCHEMA | bqa0_metadata_inventory.sql, bqa1_scan_volume.sql, bqa2_cost_attribution.sql, bqa5_partition_pruning.sql | BQA Guide |
| Data Engineer | Geometry Integrity, SRI Flattening | de1_materialized_view.sql, de2_data_cleaning.sql, de3_sri_flattening.sql, de6_hourly_preaggregation.sql | DE Guide |
| Data Scientist |
4. Multi-Persona Provisioning & Execution (scripts/provision_data_agent.sh)
Automate the lifecycle, provisioning, and conversational querying of all 6 RMI persona Data Agents using scripts/provision_data_agent.sh (which leverages api-geminidataanalytics):
Option A: Direct CLI Provisioning
Provision any of the 6 RMI personas in a single shell command:
bash scripts/provision_data_agent.sh --persona tom --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga
bash scripts/provision_data_agent.sh --persona up --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga
bash scripts/provision_data_agent.sh --persona bqa --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga
bash scripts/provision_data_agent.sh --persona de --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga
bash scripts/provision_data_agent.sh --persona ds --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga
bash scripts/provision_data_agent.sh --persona rmip --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga
Option B: Sourced Bash Operations
source scripts/provision_data_agent.sh
setup_persona_agent "tom" "projects/my-project/locations/us-central1" "my-project" "src_boston_ga"
chat_with_rmi_agent \
"projects/my-project/locations/us-central1" \
"projects/my-project/locations/us-central1/dataAgents/rmi-tom-agent" \
"Which corridors are experiencing severe congestion (TTR > 1.5) right now?" \
"my-project"
5. Tooling & Reasoning Safety Patterns
- SQL Transparency: Instruct the conversational agent to always display the generated SQL so users can verify partition pruning before execution.
- Iterative Context Hinting: When schema drift occurs, inject "Contextual Hints" via the BigQuery console or API patch operations.
- Partition Bounds Enforcement: Alert users whenever a query omits
record_time bounds on high-volume partitioned tables.
References
Related Skills
rmi-personas: Conceptual definitions, business challenges, and SLAs for RMI personas.rmi-sql: Production SQL asset library and golden queries.bigquery-practices: Foundational BigQuery performance, security, and governance best practices.
