Usa vistas con parámetros en aplicaciones de agentes

Para ejecutar de forma segura vistas con parámetros en aplicaciones de Bigtable que usan agentes de IA o modelos de lenguaje grandes (LLM), debes establecer un control de acceso estricto y pasar parámetros fuera de banda.

Configurar el control de acceso

Las vistas lógicas de Bigtable operan en un modelo de seguridad de derechos del definidor. Esto significa que, cuando consultas una vista, la consulta se ejecuta con los permisos del usuario que definió la vista, no del usuario que ejecuta la consulta. Para aplicar el principio de privilegio mínimo, otorga permisos de cuenta de servicio de tu aplicación para acceder solo a la vista, mientras retienes los permisos de la tabla de origen subyacente.

Sigue estos pasos para configurar el control de acceso:

1. Crea un rol de IAM dedicado para tu aplicación que tenga permisos mínimos, como el rol bigtable.reader.
2. Otorga permisos a este rol solo para la vista. Puedes usar una condición de IAM para limitar el permiso bigtable.logicalViews.readRows a tu vista específica.
3. Para un control de acceso más estricto, deniega explícitamente al rol de la aplicación cualquier permiso en la tabla base subyacente con una política de denegación de IAM.

Para obtener más información, consulta Control de acceso de Bigtable con IAM.

Cómo insertar un parámetro de vista

En las aplicaciones de agentes, los valores de los parámetros para la vista lógica con parámetros, como las credenciales de usuario o los límites del arrendatario, deben proporcionarse con el código de la aplicación de confianza, no con el LLM ni el usuario final. Esto aísla la entrada del usuario no confiable y las cadenas de consulta generadas por el modelo de las entradas de tu base de datos.

Para compilar un agente de IA, puedes usar el framework del Kit de desarrollo de agentes (ADK). El ADK proporciona los siguientes componentes que te ayudan a integrar vistas con parámetros:

• BigtableToolset: Es el conjunto de herramientas de base de datos del ADK que configura y proporciona herramientas orientadas a la base de datos (específicamente execute_sql_parameterized) que se comunican con Bigtable. Este conjunto de herramientas extrae automáticamente los parámetros de vista fuera de banda y ejecuta la consulta en SQL en tus datos.
• ToolContext: Es el mecanismo de tiempo de ejecución que aísla las propiedades de estado y de infraestructura específicas de la sesión, lo que permite que las herramientas resuelvan parámetros de filtrado sensibles sin exponerlos al LLM.

En la siguiente imagen, se muestra cómo funcionan los componentes en conjunto para insertar un parámetro en Bigtable:

Figura 1. Proceso de integración de vistas con parámetros en una aplicación de agentes (haz clic para ampliar)

En los siguientes pasos, se explica con más detalle el proceso de inserción de parámetros:

1. Tu aplicación autentica al usuario final y obtiene sus credenciales de usuario verificadas y la organización del arrendatario.
2. La aplicación recibe una consulta en lenguaje natural del usuario.
3. La aplicación ejecuta el agente del ADK y pasa los identificadores de usuario y arrendatario autenticados en el estado de sesión seguro.
4. Cuando el agente decide consultar la base de datos, determina solo los argumentos de filtrado en lenguaje natural, como una ciudad, e invoca la herramienta execute_sql_parameterized.
5. La herramienta de base de datos subyacente recupera de forma segura las credenciales de usuario sensibles y los límites del arrendatario de ToolContext y ejecuta la consulta en Bigtable.

En el siguiente ejemplo, se muestra cómo configurar una aplicación de agentes con el ADK para consultar el historial de compras de un usuario.

Configura el conjunto de herramientas de Bigtable

En tu aplicación de Python, configura el BigtableToolset del ADK con los nombres de los parámetros que deseas resolver fuera de banda (view_parameter_names). Esto asigna directamente las propiedades de infraestructura del framework, como user_id, y las variables de sesión de la aplicación, como tenant_id, a la consulta de tu base de datos.

import google.auth
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.bigtable.bigtable_credentials import BigtableCredentialsConfig
from google.adk.tools.bigtable.bigtable_toolset import BigtableToolset

# 1. Initialize credentials (using Application Default Credentials here)
credentials, _ = google.auth.default()
credentials_config = BigtableCredentialsConfig(credentials=credentials)

# 2. Configure the BigtableToolset
# Passing view_parameter_names=["user_id", "tenant_id"] instructs the toolset
# to automatically extract both parameters from the ToolContext at runtime
# and inject them into the query's view_parameters.
bigtable_toolset = BigtableToolset(
    credentials_config=credentials_config,
    view_parameter_names=["user_id", "tenant_id"],
)

Inicializa el agente con el conjunto de herramientas

Pasa el conjunto de herramientas directamente a la lista tools del agente. El agente detectará y expondrá automáticamente la herramienta execute_sql_parameterized con tipo seguro.

# 3. Create the agent and expose the toolset
agent = LlmAgent(
    model="MODEL_NAME",
    name="purchase_history_agent",
    description="An agent that retrieves multi-tenant purchase history.",
    instruction="You are an assistant that helps users find their purchase history within their tenant.",
    tools=[bigtable_toolset],
)

Reemplaza MODEL_NAME por el nombre del modelo que deseas usar, por ejemplo, gemini-2.5-flash.

Ejecuta la aplicación de agentes

Cuando ejecutes el agente, inicializa la sesión activa con la identidad de usuario de la infraestructura y el estado de la organización de tu aplicación.

import asyncio
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

async def main():
    # 4. Initialize session service
    session_service = InMemorySessionService()

    # 5. Create a session for the authenticated user and store their specific
    # organization tenant in the state.
    authenticated_user_id = "user-anwesha-123"
    organization_tenant_id = "tenant-corp-alpha"

    session = await session_service.create_session(
        user_id=authenticated_user_id, # Resolved from tool_context.user_id
        # Resolved from tool_context.state["tenant_id"]
        state={"tenant_id": organization_tenant_id},
        app_name="purchase_history_app",
    )

    runner = Runner(
        app_name="purchase_history_app",
        agent=agent,
        session_service=session_service,
    )

    # 6. Simulate a user query
    user_query = "What did I buy in New York?"
    content = types.Content(role="user", parts=[types.Part(text=user_query)])

    # The runner runs the agent.
    # When the agent calls execute_sql_parameterized, the ADK framework resolves
    # both "user_id" and "tenant_id" out-of-band and passes them to Bigtable
    # as view parameters, completely hidden from the LLM.
    events = runner.run(
        session_id=session.id,
        user_id=session.user_id,
        new_message=content,
    )

    for event in events:
        if event.content and event.content.parts:
            print(f"Agent: {event.content.parts[0].text}")

if __name__ == "__main__":
    asyncio.run(main())

El resultado es una lista de registros del historial de compras del usuario autenticado, filtrada por la ciudad que especificó en su consulta y restringida al límite de su arrendatario.

Este proceso garantiza que los parámetros de seguridad se inserten fuera de banda y permanezcan completamente ocultos de la manipulación del modelo de lenguaje.