1414
1515from __future__ import annotations
1616
17+ from collections .abc import Awaitable
18+ from collections .abc import Mapping
19+ from contextvars import ContextVar
1720import inspect
1821import logging
1922from typing import Any
3942
4043logger = logging .getLogger ("google_adk." + __name__ )
4144
45+ _view_param_error : ContextVar [list [Exception ] | None ] = ContextVar (
46+ "_view_param_error" , default = None
47+ )
48+
49+
50+ def _validate_view_parameters (view_parameters : object ) -> None :
51+ if (
52+ view_parameters is not None
53+ and not callable (view_parameters )
54+ and not isinstance (view_parameters , Mapping )
55+ ):
56+ raise TypeError (
57+ "view_parameters must be a Mapping, callable, or None, got"
58+ f" { type (view_parameters ).__name__ } "
59+ )
60+
4261
4362class _BigtableQueryTool (GoogleTool ):
4463 """Plain execute_sql tool that keeps _view_parameters away from the model."""
@@ -74,9 +93,10 @@ class BigtableParameterizedViewTool(GoogleTool):
7493 """Wrapper FunctionTool for Bigtable execute_sql query tool that passes view parameters.
7594
7695 This tool wraps the Bigtable query tool to automatically resolve and inject
77- parameters from the ToolContext (e.g. user_id) into the query's
78- view_parameters. The parameter names to resolve are configured via
79- view_parameter_names.
96+ parameters into the query's `view_parameters`. Top-level `ToolContext`
97+ attribute names (e.g. `user_id`) are configured via `view_parameter_names`,
98+ and static or per-invocation resolved parameter values (e.g. `tenant_id`) are
99+ configured via `view_parameters`.
80100
81101 Example:
82102 If a parameterized view `purchase_history_pv` was created with the query:
@@ -87,6 +107,29 @@ class BigtableParameterizedViewTool(GoogleTool):
87107 pass it as `view_parameters={"user_id": user_id}`.
88108 This securely restricts query execution to the logged-in user's data
89109 without exposing the `user_id` parameter to the LLM.
110+
111+ Only names that resolve to an attribute of `tool_context` itself (such as
112+ `user_id`) are honored by `view_parameter_names`. `tool_context.state` is
113+ not consulted: state is writable by the caller, so a name that fell back
114+ to state could be overridden to run the query in a different user's scope,
115+ defeating the view's own row-level restriction. Additional parameters such
116+ as `tenant_id` should be supplied via `view_parameters` from a trusted
117+ source that the caller and model cannot write (for example, a lookup keyed
118+ on `tool_context.user_id`), and never from `tool_context.state` or
119+ `tool_context.custom_metadata`:
120+
121+ - Mapping: `view_parameters={"tenant_id": "tenant-abc"}`
122+ - Mapping of callables:
123+ `view_parameters={"tenant_id": lambda ctx: get_tenant(ctx.user_id)}`
124+ - Callable receiving `ToolContext`:
125+ `view_parameters=lambda ctx: {"tenant_id": get_tenant(ctx.user_id)}`
126+
127+ Attributes:
128+ view_parameter_names: Parameter names to resolve from `tool_context`'s own
129+ attributes (not `tool_context.state`) and pass into `view_parameters`.
130+ view_parameters: Mapping of parameter values or per-value callables, or a
131+ callable receiving `ToolContext` that returns a mapping of trusted
132+ parameter values (or `None`) resolved per invocation.
90133 """
91134
92135 def __init__ (
@@ -96,6 +139,14 @@ def __init__(
96139 credentials_config : BigtableCredentialsConfig | None = None ,
97140 tool_settings : BigtableToolSettings | None = None ,
98141 view_parameter_names : list [str ] | None = None ,
142+ view_parameters : (
143+ Mapping [str , Any ]
144+ | Callable [
145+ [ToolContext ],
146+ Mapping [str , Any ] | None | Awaitable [Mapping [str , Any ] | None ],
147+ ]
148+ | None
149+ ) = None ,
99150 ):
100151 """Initializes the BigtableParameterizedViewTool.
101152
@@ -104,9 +155,26 @@ def __init__(
104155 credentials_config: The credentials configuration.
105156 tool_settings: The tool settings.
106157 view_parameter_names: A list of parameter names to resolve from
107- tool_context and pass into view_parameters. This is configured on the
108- toolset (BigtableToolset) and forwarded here.
158+ `tool_context`'s own attributes (such as `user_id`, not
159+ `tool_context.state`) and pass into `view_parameters`. This is
160+ configured on `BigtableToolset` and forwarded here.
161+ view_parameters: A mapping of parameter values, a mapping of per-value
162+ callables (sync or async), or a callable (sync or async) receiving
163+ `ToolContext` that returns a mapping of parameter values (such as
164+ `tenant_id`). Values must come from a source that the caller and model
165+ cannot write (e.g. a lookup keyed on `ctx.user_id`), and must never be
166+ read from `ctx.state` or `ctx.custom_metadata`. Keys from
167+ `view_parameters` take precedence over and overwrite keys resolved
168+ from `view_parameter_names` (including `user_id`). If a top-level
169+ callable returns `None`, no parameters from `view_parameters` are
170+ merged; any key whose value or per-value callable resolves to `None`
171+ is omitted (and removes any value resolved from
172+ `view_parameter_names`); if a top-level callable returns a
173+ non-mapping value, a `TypeError` is raised. Any exception raised by a
174+ resolver callable propagates to the caller and fails the tool
175+ invocation.
109176 """
177+ _validate_view_parameters (view_parameters )
110178 super ().__init__ (
111179 func = func ,
112180 credentials_config = credentials_config ,
@@ -118,9 +186,80 @@ def __init__(
118186 " views to securely check permissions."
119187 )
120188 self .view_parameter_names = view_parameter_names
189+ self .view_parameters = view_parameters
121190 # Exclude from being parsed and exposed to the LLM when generating tool schemas
122191 self ._ignore_params .append ("_view_parameters" )
123192
193+ async def _resolve_view_parameters (
194+ self , tool_context : ToolContext
195+ ) -> dict [str , Any ]:
196+ view_params : dict [str , Any ] = {}
197+ for param_name in self .view_parameter_names or ():
198+ if (val := getattr (tool_context , param_name , None )) is not None :
199+ view_params [param_name ] = val
200+
201+ if self .view_parameters is not None :
202+ if callable (self .view_parameters ):
203+ resolved = self .view_parameters (tool_context )
204+ if inspect .isawaitable (resolved ):
205+ resolved = await resolved
206+ if resolved is not None :
207+ if not isinstance (resolved , Mapping ):
208+ raise TypeError (
209+ "view_parameters callable must return a Mapping or None,"
210+ f" got { type (resolved ).__name__ } "
211+ )
212+ for k , val in resolved .items ():
213+ if val is not None :
214+ view_params [k ] = val
215+ else :
216+ view_params .pop (k , None )
217+ elif isinstance (self .view_parameters , Mapping ):
218+ for k , v in self .view_parameters .items ():
219+ if callable (v ):
220+ val = v (tool_context )
221+ if inspect .isawaitable (val ):
222+ val = await val
223+ else :
224+ val = v
225+ if val is not None :
226+ view_params [k ] = val
227+ else :
228+ view_params .pop (k , None )
229+ else :
230+ raise TypeError (
231+ "view_parameters must be a Mapping, callable, or None, got"
232+ f" { type (self .view_parameters ).__name__ } "
233+ )
234+
235+ for param_name in self .view_parameter_names or ():
236+ if (
237+ param_name not in view_params
238+ and tool_context .state
239+ and param_name in tool_context .state
240+ ):
241+ logger .warning (
242+ "View parameter %r is no longer read from session state; pass"
243+ " it via view_parameters instead." ,
244+ param_name ,
245+ )
246+
247+ return view_params
248+
249+ @override
250+ async def run_async (
251+ self , * , args : dict [str , Any ], tool_context : ToolContext
252+ ) -> Any :
253+ error_holder : list [Exception ] = []
254+ token = _view_param_error .set (error_holder )
255+ try :
256+ result = await super ().run_async (args = args , tool_context = tool_context )
257+ finally :
258+ _view_param_error .reset (token )
259+ if error_holder :
260+ raise error_holder [0 ]
261+ return result
262+
124263 @override
125264 async def _run_async_with_credential (
126265 self ,
@@ -130,18 +269,19 @@ async def _run_async_with_credential(
130269 tool_context : ToolContext ,
131270 ) -> Any :
132271 args_to_call = args .copy ()
272+ args_to_call .pop ("_view_parameters" , None )
133273 signature = inspect .signature (self .func )
134- if "_view_parameters" in signature .parameters and self . view_parameter_names :
135- view_params = {}
136- for param_name in self . view_parameter_names :
137- # 1. Check if it's a strongly-typed top-level property (like 'user_id')
138- if ( val := getattr ( tool_context , param_name , None )) is not None :
139- view_params [ param_name ] = val
140- # 2. Fallback to checking application-level session state
141- elif tool_context . state and param_name in tool_context . state :
142- view_params [ param_name ] = tool_context . state [ param_name ]
143-
144- args_to_call [ "_view_parameters" ] = view_params
274+ if "_view_parameters" in signature .parameters and (
275+ self . view_parameter_names or self . view_parameters is not None
276+ ) :
277+ try :
278+ args_to_call [ "_view_parameters" ] = await self . _resolve_view_parameters (
279+ tool_context
280+ )
281+ except Exception as ex :
282+ if ( error_holder := _view_param_error . get ()) is not None :
283+ error_holder . append ( ex )
284+ raise
145285 return await super ()._run_async_with_credential (
146286 credentials , tool_settings , args_to_call , tool_context
147287 )
@@ -163,9 +303,33 @@ class BigtableToolset(BaseToolset):
163303 - bigtable_get_cluster_info
164304 - bigtable_execute_sql
165305
166- When view_parameter_names is configured, bigtable_execute_sql is replaced by
167- bigtable_execute_sql_parameterized, which fills the view parameters in from
168- the tool context.
306+ When view_parameter_names or view_parameters is configured,
307+ bigtable_execute_sql is replaced by bigtable_execute_sql_parameterized, which
308+ resolves view parameters from `tool_context`'s own attributes (such as
309+ `user_id`, never session state `tool_context.state`) and from
310+ `view_parameters`.
311+
312+ Attributes:
313+ view_parameter_names: Optional list of parameter names to resolve from
314+ `tool_context`'s own attributes (such as `user_id`, not
315+ `tool_context.state`) and pass into `view_parameters` for parameterized
316+ views.
317+ view_parameters: Optional mapping of parameter values, mapping of per-value
318+ callables (sync or async), or a callable (sync or async) receiving
319+ `ToolContext` that returns a mapping of trusted parameter values (such as
320+ `tenant_id`, or `None`) resolved per invocation for parameterized views:
321+ - Mapping: `view_parameters={"tenant_id": "tenant-abc"}`
322+ - Mapping of callables:
323+ `view_parameters={"tenant_id": lambda ctx: get_tenant(ctx.user_id)}`
324+ - Callable receiving `ToolContext`:
325+ `view_parameters=lambda ctx: {"tenant_id": get_tenant(ctx.user_id)}`
326+ Values must come from a source that the caller and model cannot write, and
327+ never from `tool_context.state` or `tool_context.custom_metadata`. Keys
328+ from `view_parameters` take precedence over keys resolved from
329+ `view_parameter_names`; `None` returns or `None` values are omitted (and
330+ remove any value resolved from `view_parameter_names`); a non-mapping
331+ callable return raises `TypeError`; and any exception raised by a resolver
332+ callable propagates to the caller and fails the tool invocation.
169333 """
170334
171335 def __init__ (
@@ -175,7 +339,16 @@ def __init__(
175339 credentials_config : BigtableCredentialsConfig | None = None ,
176340 bigtable_tool_settings : BigtableToolSettings | None = None ,
177341 view_parameter_names : list [str ] | None = None ,
342+ view_parameters : (
343+ Mapping [str , Any ]
344+ | Callable [
345+ [ToolContext ],
346+ Mapping [str , Any ] | None | Awaitable [Mapping [str , Any ] | None ],
347+ ]
348+ | None
349+ ) = None ,
178350 ):
351+ _validate_view_parameters (view_parameters )
179352 super ().__init__ (
180353 tool_filter = tool_filter ,
181354 tool_name_prefix = DEFAULT_BIGTABLE_TOOL_NAME_PREFIX ,
@@ -187,6 +360,7 @@ def __init__(
187360 else BigtableToolSettings ()
188361 )
189362 self .view_parameter_names = view_parameter_names
363+ self .view_parameters = view_parameters
190364
191365 def _is_tool_selected (
192366 self , tool : BaseTool , readonly_context : ReadonlyContext | None
@@ -203,16 +377,19 @@ def _is_tool_selected(
203377 return False
204378
205379 def _warn_on_filtered_out_query_tool (self ) -> None :
206- if not self .view_parameter_names or not isinstance (self .tool_filter , list ):
380+ if not (
381+ self .view_parameter_names or self .view_parameters
382+ ) or not isinstance (self .tool_filter , list ):
207383 return
208384 if (
209385 "execute_sql" in self .tool_filter
210386 and "execute_sql_parameterized" not in self .tool_filter
211387 ):
212388 logger .warning (
213- "tool_filter names execute_sql, which view_parameter_names replaces"
214- " with execute_sql_parameterized, so no query tool is returned. Add"
215- " execute_sql_parameterized to tool_filter."
389+ "tool_filter names execute_sql, which view_parameter_names or"
390+ " view_parameters replaces with execute_sql_parameterized, so no"
391+ " query tool is returned. Add execute_sql_parameterized to"
392+ " tool_filter."
216393 )
217394
218395 @override
@@ -237,13 +414,14 @@ async def get_tools(
237414 for func in tool_functions
238415 ]
239416 # Registering both would let the model pick its own view parameters.
240- if self .view_parameter_names :
417+ if self .view_parameter_names or self . view_parameters :
241418 all_tools .append (
242419 BigtableParameterizedViewTool (
243420 func = query_tool .execute_sql ,
244421 credentials_config = self ._credentials_config ,
245422 tool_settings = self ._tool_settings ,
246423 view_parameter_names = self .view_parameter_names ,
424+ view_parameters = self .view_parameters ,
247425 )
248426 )
249427 else :
0 commit comments