Usar visualizações parametrizadas em aplicativos de agente

Para executar visualizações parametrizadas com segurança em aplicativos do Bigtable que usam agentes de IA ou modelos de linguagem grandes (LLMs), é necessário estabelecer um controle de acesso rigoroso e transmitir parâmetros fora da banda.

Configurar o controle de acesso

As visualizações lógicas do Bigtable operam em um modelo de segurança de direitos do definidor. Isso significa que, ao consultar uma visualização, a consulta é executada com as permissões do usuário que definiu a visualização, não do usuário que está executando a consulta. Para aplicar o princípio de privilégio mínimo, conceda permissões da conta de serviço do aplicativo para acessar apenas a visualização, retendo permissões para a tabela de origem subjacente.

Siga estas etapas para configurar o controle de acesso:

1. Crie um papel dedicado do IAM para seu aplicativo que tenha permissões mínimas, como o papel bigtable.reader.
2. Conceda permissões a esse papel apenas para a visualização. Você pode usar uma condição do IAM para limitar a permissão bigtable.logicalViews.readRows à sua visualização específica.
3. Para um controle de acesso mais rigoroso, negue explicitamente ao papel do aplicativo todas as permissões na tabela de base subjacente usando uma política de negação do IAM.

Para mais informações, consulte Controle de acesso do Bigtable com o IAM.

Inserir um parâmetro de visualização

Em aplicativos de agente, os valores de parâmetro para a visualização lógica parametrizada, como credenciais de usuário ou limites de locatário, precisam ser fornecidos pelo código do aplicativo confiável, não pelo LLM ou pelo usuário final. Isso isola a entrada do usuário não confiável e as strings de consulta geradas pelo modelo das entradas do banco de dados.

Para criar um agente de IA, você pode usar o framework do Kit de Desenvolvimento de Agente (ADK). O ADK fornece os seguintes componentes que ajudam a integrar visualizações parametrizadas:

• BigtableToolset: o conjunto de ferramentas de banco de dados do ADK que configura e fornece ferramentas voltadas para o banco de dados (especificamente execute_sql_parameterized) que se comunicam com o Bigtable. Esse conjunto de ferramentas extrai automaticamente os parâmetros de visualização fora da banda e executa a consulta SQL nos seus dados.
• ToolContext: o mecanismo de execução que coloca em sandbox o estado específico da sessão e as propriedades da infraestrutura, permitindo que as ferramentas resolvam parâmetros de filtragem sensíveis sem expô-los ao LLM.

A imagem a seguir mostra como os componentes funcionam juntos para inserir um parâmetro no Bigtable:

Figura 1. O processo de integração de visualizações parametrizadas em um aplicativo de agente (clique para ampliar).

As etapas a seguir explicam melhor o processo de injeção de parâmetros:

1. O aplicativo autentica o usuário final e recebe as credenciais de usuário verificadas e a organização do locatário.
2. O aplicativo recebe uma consulta em linguagem natural do usuário.
3. O aplicativo executa o agente do ADK, transmitindo o usuário autenticado e os identificadores de locatário no estado de sessão segura.
4. Quando o agente decide consultar o banco de dados, ele determina apenas os argumentos de filtragem de linguagem natural, como uma cidade, e invoca a ferramenta execute_sql_parameterized.
5. A ferramenta de banco de dados subjacente recupera com segurança as credenciais de usuário sensíveis e os limites de locatário do ToolContext e executa a consulta no Bigtable.

O exemplo a seguir mostra como configurar um aplicativo de agente usando o ADK para consultar o histórico de compras de um usuário.

Configurar o conjunto de ferramentas do Bigtable

No aplicativo Python, configure o BigtableToolset do ADK com os nomes de parâmetros que você quer resolver fora da banda (view_parameter_names). Isso mapeia as propriedades da infraestrutura do framework, como user_id, e as variáveis de sessão do aplicativo, como tenant_id, diretamente para a consulta do banco de dados.

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"],
)

Inicializar o agente com o conjunto de ferramentas

Transmita o conjunto de ferramentas diretamente para a lista tools do agente. O agente vai detectar e expor automaticamente a ferramenta execute_sql_parameterized com tipo forte.

# 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],
)

Substitua MODEL_NAME pelo nome do modelo que você quer usar, por exemplo, gemini-2.5-flash.

Executar o aplicativo de agente

Ao executar o agente, inicialize a sessão ativa com a identidade do usuário da infraestrutura e o estado da organização do aplicativo.

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())

O resultado é uma lista de registros de histórico de compras do usuário autenticado, filtrada pela cidade especificada na consulta e restrita ao limite do locatário.

Esse processo garante que os parâmetros de segurança sejam injetados fora da banda e permaneçam completamente ocultos da manipulação do modelo de linguagem.