Parametrisierte Ansichten in agentenbasierten Anwendungen verwenden

Wenn Sie parametrisierte Ansichten in Bigtable-Anwendungen, die KI-Agenten oder Large Language Models (LLMs) verwenden, sicher ausführen möchten, müssen Sie eine strenge Zugriffssteuerung einrichten und Parameter außerhalb des Bandes übergeben.

Zugriffssteuerung einrichten

Bigtable-Ansichten arbeiten mit einem Sicherheitsmodell mit den Rechten des Definierers. Wenn Sie eine Ansicht abfragen, wird die Abfrage mit den Berechtigungen des Nutzers ausgeführt, der die Ansicht definiert hat, nicht mit den Berechtigungen des Nutzers, der die Abfrage ausführt. Um das Prinzip der geringsten Berechtigung durchzusetzen, gewähren Sie dem Dienstkonto Ihrer Anwendung nur Berechtigungen für den Zugriff auf die Ansicht und nicht auf die zugrunde liegende Quelltabelle.

So richten Sie die Zugriffssteuerung ein:

1. Erstellen Sie eine dedizierte IAM-Rolle für Ihre Anwendung mit minimalen Berechtigungen, z. B. die Rolle bigtable.reader.
2. Gewähren Sie dieser Rolle nur Berechtigungen für die Ansicht. Mit einer IAM-Bedingung können Sie die Berechtigung bigtable.logicalViews.readRows auf Ihre spezifische Ansicht beschränken.
3. Für eine strengere Zugriffssteuerung können Sie der Anwendungsrolle mit einer IAM-Richtlinie zum Ablehnen explizit alle Berechtigungen für die zugrunde liegende Basistabelle verweigern.

Weitere Informationen finden Sie unter Bigtable-Zugriffssteuerung mit IAM.

Ansichtsparameter einfügen

In agentenbasierten Anwendungen müssen Parameterwerte für die parametrisierte logische Ansicht, z. B. Anmeldedaten oder Mandantengrenzen, von Ihrem vertrauenswürdigen Anwendungscode und nicht vom LLM oder Endnutzer bereitgestellt werden. Dadurch werden nicht vertrauenswürdige Nutzereingaben und vom Modell generierte Abfragestrings von Ihren Datenbankeingaben isoliert.

Sie können das Agent Development Kit (ADK) Framework verwenden, um einen KI-Agenten zu erstellen. Das ADK bietet die folgenden Komponenten, mit denen Sie parametrisierte Ansichten einbinden können:

• BigtableToolset: Das ADK-Datenbanktoolset, mit dem datenbankseitige Tools konfiguriert und bereitgestellt werden (insbesondere execute_sql_parameterized), die mit Bigtable kommunizieren. Dieses Toolset extrahiert Ansichtsparameter automatisch außerhalb des Bandes und führt die SQL-Abfrage für Ihre Daten aus.
• ToolContext: Der Laufzeitmechanismus, der sitzungsspezifische Status- und Infrastruktureigenschaften in einer Sandbox ausführt, sodass Tools vertrauliche Filterparameter auflösen können, ohne sie dem LLM preiszugeben.

Die folgende Abbildung zeigt, wie die Komponenten zusammenarbeiten, um einen Parameter in Bigtable einzufügen:

Abbildung 1 Der Prozess der Einbindung parametrisierter Ansichten in eine agentenbasierte Anwendung (zum Vergrößern klicken).

Die folgenden Schritte erläutern den Prozess der Parametereinfügung genauer:

1. Ihre Anwendung authentifiziert den Endnutzer und ruft seine bestätigten Anmeldedaten und die Mandantenorganisation ab.
2. Die Anwendung erhält eine Abfrage in natürlicher Sprache vom Nutzer.
3. Die Anwendung führt den ADK-Agenten aus und übergibt die authentifizierten Nutzer- und Mandanten-IDs im sicheren Sitzungsstatus.
4. Wenn der Agent die Datenbank abfragen möchte, bestimmt er nur die Filterargumente in natürlicher Sprache, z. B. eine Stadt, und ruft das Tool execute_sql_parameterized auf.
5. Das zugrunde liegende Datenbanktool ruft die vertraulichen Anmeldedaten und Mandantengrenzen sicher aus dem ToolContext ab und führt die Abfrage für Bigtable aus.

Im folgenden Beispiel wird gezeigt, wie Sie eine agentische Anwendung mit dem ADK einrichten, um die bisherigen Käufe eines Nutzers abzufragen.

Bigtable-Toolset konfigurieren

Konfigurieren Sie in Ihrer Python-Anwendung das ADK BigtableToolset mit den Parameternamen, die Sie außerhalb des Bandes auflösen möchten (view_parameter_names). Dadurch werden sowohl Eigenschaften der Framework-Infrastruktur wie user_id als auch Anwendungssitzungsvariablen wie tenant_id direkt Ihrer Datenbankabfrage zugeordnet.

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

Agenten mit dem Toolset initialisieren

Übergeben Sie das Toolset direkt an die Liste tools des Agenten. Der Agent erkennt das Tool execute_sql_parameterized automatisch und macht es verfügbar.

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

Ersetzen Sie MODEL_NAME durch den Namen des Modells, das Sie verwenden möchten, z. B. gemini-2.5-flash.

Agentenbasierte Anwendung ausführen

Initialisieren Sie beim Ausführen des Agenten die aktive Sitzung sowohl mit der Nutzeridentität der Infrastruktur als auch mit dem Organisationsstatus Ihrer Anwendung.

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

Das Ergebnis ist eine Liste mit Bisherige Käufe-Datensätzen für den authentifizierten Nutzer, gefiltert nach der Stadt, die er in seiner Abfrage angegeben hat, und beschränkt auf seine Mandantengrenze.

Dieser Prozess sorgt dafür, dass Sicherheitsparameter außerhalb des Bandes eingeschleust werden und vollständig vor Manipulationen durch das Language Model verborgen bleiben.