feat(bigquery): Add labels support to BigQueryToolConfig for job tracking and monitoring

contributing/samples/gepa/experiment.py

@@ -43,7 +43,6 @@
 from tau_bench.types import EnvRunResult
 from tau_bench.types import RunConfig
 import tau_bench_agent as tau_bench_agent_lib
-
 import utils
 
 

contributing/samples/gepa/run_experiment.py

@@ -25,7 +25,6 @@
 from absl import flags
 import experiment
 from google.genai import types
-
 import utils
 
 _OUTPUT_DIR = flags.DEFINE_string(

src/google/adk/tools/bigquery/config.py

@@ -99,6 +99,16 @@ class BigQueryToolConfig(BaseModel):
   locations, see https://cloud.google.com/bigquery/docs/locations.
   """
 
+  labels: Optional[dict[str, str]] = None
+  """Labels to apply to BigQuery jobs for tracking and monitoring.
+
+  These labels will be added to all BigQuery jobs executed by the execute_sql
+  function. Labels must be key-value pairs where both keys and values are
+  strings. Labels can be used for billing, monitoring, and resource organization.
+  For more information about labels, see 
+  https://cloud.google.com/bigquery/docs/labels-intro.
+  """
+
   @field_validator('maximum_bytes_billed')
   @classmethod
   def validate_maximum_bytes_billed(cls, v):
@@ -119,3 +129,17 @@ def validate_application_name(cls, v):
     if v and ' ' in v:
       raise ValueError('Application name should not contain spaces.')
     return v
+
+  @field_validator('labels')
+  @classmethod
+  def validate_labels(cls, v):
+    """Validate the labels dictionary."""
+    if v is not None:
+      if not isinstance(v, dict):
+        raise ValueError('Labels must be a dictionary.')
+      for key, value in v.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+          raise ValueError('Label keys and values must be strings.')
+        if not key:
+          raise ValueError('Label keys cannot be empty.')
+    return v

src/google/adk/tools/bigquery/query_tool.py

@@ -68,7 +68,7 @@ def _execute_sql(
     bq_connection_properties = []
 
     # BigQuery job labels if applicable
-    bq_job_labels = {}
+    bq_job_labels = settings.labels if settings and settings.labels else {}
     if caller_id:
       bq_job_labels["adk-bigquery-tool"] = caller_id
 

tests/unittests/tools/bigquery/test_bigquery_tool_config.py

@@ -77,3 +77,57 @@ def test_bigquery_tool_config_invalid_maximum_bytes_billed():
       ),
   ):
     BigQueryToolConfig(maximum_bytes_billed=10_485_759)
+
+
+def test_bigquery_tool_config_valid_labels():
+  """Test BigQueryToolConfig accepts valid labels."""
+  config = BigQueryToolConfig(labels={"environment": "test", "team": "data"})
+  assert config.labels == {"environment": "test", "team": "data"}
+
+
+def test_bigquery_tool_config_empty_labels():
+  """Test BigQueryToolConfig accepts empty labels dictionary."""
+  config = BigQueryToolConfig(labels={})
+  assert config.labels == {}
+
+
+def test_bigquery_tool_config_none_labels():
+  """Test BigQueryToolConfig accepts None for labels."""
+  config = BigQueryToolConfig(labels=None)
+  assert config.labels is None
+
+
+def test_bigquery_tool_config_invalid_labels_type():
+  """Test BigQueryToolConfig raises exception with invalid labels type."""
+  with pytest.raises(
+      ValueError,
+      match="Input should be a valid dictionary",
+  ):
+    BigQueryToolConfig(labels="invalid")
+
+
+def test_bigquery_tool_config_invalid_label_key_type():
+  """Test BigQueryToolConfig raises exception with non-string label keys."""
+  with pytest.raises(
+      ValueError,
+      match="Input should be a valid string",
+  ):
+    BigQueryToolConfig(labels={123: "value"})
+
+
+def test_bigquery_tool_config_invalid_label_value_type():
+  """Test BigQueryToolConfig raises exception with non-string label values."""
+  with pytest.raises(
+      ValueError,
+      match="Input should be a valid string",
+  ):
+    BigQueryToolConfig(labels={"key": 123})
+
+
+def test_bigquery_tool_config_empty_label_key():
+  """Test BigQueryToolConfig raises exception with empty label key."""
+  with pytest.raises(
+      ValueError,
+      match="Label keys cannot be empty",
+  ):
+    BigQueryToolConfig(labels={"": "value"})