feat: limit number of user-provided BigQuery job labels and reserve internal prefixes

google-genai-bot · copybara-github · commit 8c4ff74e7d70 · 2026-03-06T22:11:07.000-08:00
PiperOrigin-RevId: 879973232
diff --git a/src/google/adk/tools/bigquery/config.py b/src/google/adk/tools/bigquery/config.py
@@ -82,8 +82,12 @@ class BigQueryToolConfig(BaseModel):
   By default, no particular application name will be set in the BigQuery
   interaction. But if the tool user (agent builder) wants to differentiate
   their application/agent for tracking or support purpose, they can set this
-  field. If set, this value will be added to the user_agent in BigQuery API calls, and also to the BigQuery job labels with the key
+  field. If set, this value will be added to the user_agent in BigQuery API
+  calls, and also to the BigQuery job labels with the key
   "adk-bigquery-application-name".
+
+  Note: This field is for usage discovery and tracking purposes only and should
+  not be used for security-sensitive decisions.
   """
 
   compute_project_id: Optional[str] = None
@@ -108,8 +112,13 @@ class BigQueryToolConfig(BaseModel):
   These labels will be added to all BigQuery jobs executed by the tools.
   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 
+  For more information about labels, see
   https://cloud.google.com/bigquery/docs/labels-intro.
+
+  Note: These labels are for usage discovery and tracking purposes only and
+  should not be used for security-sensitive decisions. The number of
+  user-provided labels is restricted to 20, and keys starting with
+  "adk-bigquery-" are reserved for internal usage.
   """
 
   @field_validator('maximum_bytes_billed')
@@ -136,9 +145,16 @@ def validate_application_name(cls, v):
   @field_validator('job_labels')
   @classmethod
   def validate_job_labels(cls, v):
-    """Validate that job_labels keys are not empty."""
+    """Validate the job labels."""
     if v is not None:
+      if len(v) > 20:
+        raise ValueError('Only up to 20 job labels can be provided')
       for key in v.keys():
         if not key:
           raise ValueError('Label keys cannot be empty.')
+        if key.startswith('adk-bigquery-'):
+          raise ValueError(
+              'Label key cannot start with "adk-bigquery-" as it is'
+              f' reserved for internal usage, found "{key}".'
+          )
     return v
diff --git a/tests/unittests/tools/bigquery/test_bigquery_tool_config.py b/tests/unittests/tools/bigquery/test_bigquery_tool_config.py
@@ -130,6 +130,16 @@ def test_bigquery_tool_config_valid_labels(labels):
             "Label keys cannot be empty",
             id="empty-label-key",
         ),
+        pytest.param(
+            {"adk-bigquery-test": "value"},
+            'Label key cannot start with "adk-bigquery-"',
+            id="internal-label-key",
+        ),
+        pytest.param(
+            {f"key_{i}": "value" for i in range(21)},
+            "Only up to 20 job labels can be provided",
+            id="too-many-labels",
+        ),
     ],
 )
 def test_bigquery_tool_config_invalid_labels(labels, message):
