Menggunakan tampilan berparameter dalam aplikasi berbasis agen

Untuk menjalankan tampilan berparameter secara aman di aplikasi Bigtable yang menggunakan agen AI atau model bahasa besar (LLM), Anda harus menetapkan kontrol akses yang ketat dan meneruskan parameter di luar band.

Menyiapkan kontrol akses

Tampilan logis Bigtable beroperasi pada model keamanan hak penentu. Artinya, saat Anda membuat kueri tampilan, kueri akan dieksekusi dengan izin pengguna yang menentukan tampilan, bukan pengguna yang menjalankan kueri. Untuk menerapkan prinsip hak istimewa terendah, berikan izin akun layanan aplikasi Anda untuk mengakses hanya tampilan, sambil menahan izin ke tabel sumber pokok.

Ikuti langkah-langkah berikut untuk menyiapkan kontrol akses:

1. Buat peran IAM khusus untuk aplikasi Anda yang memiliki izin minimal, seperti peran bigtable.reader.
2. Berikan izin peran ini hanya lihat. Anda dapat menggunakan kondisi IAM untuk membatasi izin bigtable.logicalViews.readRows ke tampilan tertentu Anda.
3. Untuk kontrol akses yang lebih ketat, tolak secara eksplisit peran aplikasi apa pun izin pada tabel dasar yang mendasarinya menggunakan kebijakan penolakan IAM.

Untuk mengetahui informasi selengkapnya, lihat Kontrol akses Bigtable dengan IAM.

Menyuntikkan parameter tampilan

Dalam aplikasi agentik, nilai parameter untuk tampilan logis berparameter, seperti kredensial pengguna atau batas tenant, harus diberikan oleh kode aplikasi tepercaya Anda, bukan oleh LLM atau pengguna akhir. Hal ini mengisolasi input pengguna yang tidak tepercaya dan string kueri yang dihasilkan model dari input database Anda.

Untuk membangun agen AI, Anda dapat menggunakan framework Agent Development Kit (ADK). ADK menyediakan komponen berikut yang membantu Anda mengintegrasikan tampilan berparameter:

• BigtableToolset: Kumpulan alat database ADK yang mengonfigurasi dan menyediakan alat yang berinteraksi dengan database (khususnya execute_sql_parameterized) yang berkomunikasi dengan Bigtable. Rangkaian alat ini secara otomatis mengekstrak parameter tampilan di luar band dan menjalankan kueri SQL terhadap data Anda.
• ToolContext: Mekanisme runtime yang menyandbox status dan properti infrastruktur khusus sesi, sehingga alat dapat menyelesaikan parameter pemfilteran sensitif tanpa mengeksposnya ke LLM.

Gambar berikut menunjukkan cara kerja komponen bersama-sama untuk menyuntikkan parameter ke Bigtable:

Gambar 1. Proses mengintegrasikan tampilan berparameter ke dalam aplikasi agentic (klik untuk memperbesar).

Langkah-langkah berikut menjelaskan lebih lanjut proses injeksi parameter:

1. Aplikasi Anda mengautentikasi pengguna akhir dan mendapatkan kredensial pengguna terverifikasi dan organisasi tenant-nya.
2. Aplikasi menerima kueri bahasa alami dari pengguna.
3. Aplikasi menjalankan agen ADK, meneruskan pengguna yang diautentikasi dan ID tenant dalam status sesi yang aman.
4. Saat agen memutuskan untuk membuat kueri database, agen hanya menentukan argumen pemfilteran bahasa alami, seperti kota, dan memanggil alat execute_sql_parameterized.
5. Alat database yang mendasarinya mengambil kredensial pengguna sensitif dan batas tenant dengan aman dari ToolContext dan menjalankan kueri terhadap Bigtable.

Contoh berikut menunjukkan cara menyiapkan aplikasi berorientasi agen menggunakan ADK untuk membuat kueri histori pembelian pengguna.

Mengonfigurasi toolset Bigtable

Di aplikasi Python Anda, konfigurasi ADK BigtableToolset dengan nama parameter yang ingin Anda selesaikan di luar band (view_parameter_names). Ini memetakan properti infrastruktur framework, seperti user_id, dan variabel sesi aplikasi, seperti tenant_id, langsung ke kueri database Anda.

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

Melakukan inisialisasi agen dengan toolset

Teruskan toolset langsung ke daftar tools agen. Agen akan otomatis mendeteksi dan mengekspos alat execute_sql_parameterized yang memiliki jenis data yang kuat.

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

Ganti MODEL_NAME dengan nama model yang ingin Anda gunakan—misalnya, gemini-2.5-flash.

Menjalankan aplikasi berbasis agen

Saat menjalankan agen, inisialisasi sesi aktif dengan identitas pengguna infrastruktur dan status organisasi aplikasi Anda.

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

Hasilnya adalah daftar catatan histori pembelian untuk pengguna yang diautentikasi, yang difilter menurut kota yang ditentukan dalam kueri dan dibatasi ke batas tenant-nya.

Proses ini memastikan bahwa parameter keamanan disisipkan di luar band dan tetap tersembunyi sepenuhnya dari manipulasi model bahasa.