Autentikasi untuk agen AI

Agen AI sering kali perlu mengautentikasi ke sumber daya lain untuk menyelesaikan tugas. Misalnya, agen yang disebarkan mungkin perlu mengakses indeks Pencarian Vektor untuk mengkueri data yang tidak terstruktur, titik akhir penyajian untuk memanggil model fondasi, atau fungsi Katalog Unity untuk menjalankan logika kustom.

Halaman ini mencakup metode autentikasi untuk agen yang disebarkan di Aplikasi Databricks. Untuk agen yang disebarkan pada titik akhir Model Serving, lihat Autentikasi untuk agen AI (Model Serving).

Aplikasi Databricks menyediakan dua metode autentikasi untuk agen. Setiap metode melayani kasus penggunaan yang berbeda:

Metode	Description	Kapan harus menggunakan
Otorisasi aplikasi	Agen mengautentikasi menggunakan perwakilan layanan yang dibuat secara otomatis dengan izin yang konsisten. Sebelumnya disebut autentikasi Perwakilan Layanan.	Kasus penggunaan yang paling umum. Gunakan saat semua pengguna harus memiliki akses yang sama ke sumber daya.
Otorisasi pengguna	Agen mengautentikasi menggunakan identitas pengguna yang membuat permintaan. Sebelumnya disebut autentikasi On-Behalf-Of (OBO).	Gunakan saat Anda memerlukan izin khusus pengguna, jejak audit, atau kontrol akses halus dengan Katalog Unity.

Anda dapat menggabungkan kedua metode dalam satu agen. Misalnya, gunakan otorisasi aplikasi untuk mengakses indeks pencarian vektor bersama saat menggunakan otorisasi pengguna untuk melakukan kueri pada tabel khusus pengguna.

Mengonfigurasi autentikasi dengan UI ruang kerja atau Bundel Otomatisasi Deklaratif

Anda dapat mengonfigurasi semua pengaturan autentikasi dengan dua cara:

UI Ruang Kerja: Edit aplikasi dan kelola sumber daya dan cakupan dari langkah Konfigurasikan . Disarankan saat Anda melakukan iterasi pada satu aplikasi di ruang kerja.
Bundel Otomatisasi Deklaratif: Mendeklarasikan sumber daya, cakupan, dan variabel lingkungan dalam databricks.yml file dan sebarkan dengan databricks bundle deploy. Disarankan saat Anda ingin penerapan versi berbasis Git, CI/CD, atau mengirim agen yang sama di seluruh ruang kerja. Semua templat agen dikirim dengan databricks.yml.

Kedua jalur menghasilkan konfigurasi runtime yang sama. Sisa halaman ini menunjukkan setiap instruksi dalam kedua formulir sehingga Anda dapat memilih satu dan tetap konsisten dalam proyek Anda.

Untuk menambahkan sumber daya ke aplikasi melalui salah satu jalur, Anda harus memiliki Can Manage izin pada sumber daya dan aplikasi.

Untuk referensi bundel lengkap, lihat sumber daya aplikasi dan app.resources. Untuk panduan bundel end-to-end, lihat Mengelola aplikasi Databricks menggunakan Bundel Otomatisasi Deklaratif.

Otorisasi aplikasi

Secara default, Databricks Apps mengautentikasi menggunakan otorisasi aplikasi. Databricks secara otomatis membuat service principal saat Anda membuat aplikasi, dan bertindak sebagai identitas aplikasi.

Semua pengguna yang berinteraksi dengan aplikasi berbagi izin yang sama yang ditentukan untuk prinsipal layanan. Model ini berfungsi dengan baik ketika Anda ingin semua pengguna melihat data yang sama atau ketika aplikasi melakukan operasi bersama yang tidak terkait dengan kontrol akses khusus pengguna.

Untuk informasi terperinci tentang otorisasi aplikasi, lihat Otorisasi aplikasi.

Memberikan izin ke eksperimen MLflow

Agen Anda memerlukan akses ke eksperimen MLflow untuk mencatat jejak dan hasil evaluasi. Berikan perwakilan layanan Can Edit izin pada eksperimen.

Antarmuka Pengguna Ruang Kerja

Klik Edit di beranda aplikasi Anda.
Buka langkah Konfigurasikan .
Di bagian Sumber daya aplikasi , tambahkan sumber daya eksperimen MLflow dengan Can Edit izin.

Lihat Menambahkan sumber daya eksperimen MLflow ke aplikasi Databricks.

Paket Otomatisasi Deklaratif

Deklarasikan eksperimen di bawah daftar aplikasi resources Anda di databricks.yml. name yang Anda tetapkan ke sumber daya akan dijadikan referensi kemudian saat Anda mengonfigurasi variabel lingkungan.

resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

Terapkan ulang bundel:

databricks bundle deploy
databricks bundle run my_agent

Lihat app.resources.experiment untuk semua bidang.

Memberikan izin ke sumber daya Databricks lainnya

Jika agen Anda menggunakan sumber daya Databricks lainnya, seperti Ruang Genie, indeks Pencarian Vektor, atau gudang SQL, berikan izin perwakilan layanan pada masing-masing sumber daya.

Untuk mengakses registri prompt, berikan izin pada CREATE FUNCTION, EXECUTE, dan MANAGE dalam skema Katalog Unity untuk menyimpan prompt.

Saat memberikan akses ke sumber daya Katalog Unity, Anda juga harus memberikan izin ke semua sumber daya dependen hilir. Misalnya, jika Anda memberikan akses ke Genie Space, Anda juga harus memberikan akses ke tabel yang mendasar, gudang SQL, dan fungsi Unity Catalog.

Antarmuka Pengguna Ruang Kerja

Tambahkan sumber daya ke aplikasi melalui bagian Sumber daya aplikasi saat Anda membuat atau mengedit aplikasi di ruang kerja Databricks.

Klik Edit di beranda aplikasi Anda.
Buka langkah Konfigurasikan .
Di Sumber daya aplikasi, klik + Tambahkan sumber daya untuk setiap sumber daya yang digunakan agen dan atur izin.

Lihat Menambahkan sumber daya ke aplikasi Databricks untuk daftar lengkap sumber daya dan cuplikan layar yang didukung.

Paket Otomatisasi Deklaratif

Deklarasikan setiap sumber daya yang digunakan agen dalam resources daftar di bawah aplikasi Anda di databricks.yml. Contoh di bawah ini menunjukkan agen yang menggunakan eksperimen MLflow, titik akhir penyajian, Ruang Genie, gudang SQL, indeks Pencarian Vektor, fungsi Katalog Unity, dan instans Lakebase. Setiap sumber daya name dirujuk dari config.env melalui value_from sehingga agen menerima pengidentifikasi yang diselesaikan saat runtime.

bundle:
  name: my_agent

resources:
  apps:
    my_agent:
      name: 'my-agent'
      description: 'Custom agent deployed on Databricks Apps'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
          - name: LAKEBASE_INSTANCE_NAME
            value_from: 'database'

      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

        - name: 'sales-genie'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

        - name: 'warehouse'
          sql_warehouse:
            id: '<warehouse-id>'
            permission: 'CAN_USE'

        - name: 'docs-index'
          uc_securable:
            securable_full_name: 'main.docs.chunks_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'lookup-function'
          uc_securable:
            securable_full_name: 'main.tools.order_lookup'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

        - name: 'database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'databricks_postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

targets:
  dev:
    mode: development
    default: true

Penting

Setiap value_from nilai di config.env harus cocok dengan name bidang dalam resources daftar. Ketidakcocokan menyebabkan variabel lingkungan berpindah menjadi None di aplikasi yang disebarkan.

Terapkan dan mulai bundel:
```
databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent
```
bundle deploy mengunggah sumber dan mengonfigurasi sumber daya. bundle run memulai atau memulai ulang aplikasi dengan sumber terbaru. Argumen untuk bundle run adalah kunci YAML di bawah resources.apps (contohnya my_agent), bukan kolom name dari aplikasi yang telah diterapkan.

Untuk skema lengkap setiap subjenis sumber daya, lihat app.resources.

Tabel berikut mencantumkan izin minimum yang digunakan dalam contoh di atas dan nilai Bundel Otomatisasi Deklaratif yang setara untuk setiap jenis sumber daya:

Jenis sumber daya	Izin antarmuka ruang kerja	Sumber daya dan izin Bundel Otomatisasi Deklaratif
Gudang SQL	`Can Use`	`sql_warehouse` dengan `CAN_USE`
Titik akhir Layanan Model	`Can Query`	`serving_endpoint` dengan `CAN_QUERY`
Fungsi Katalog Unity	`Can Execute`	`uc_securable` dengan `securable_type: FUNCTION` dan `EXECUTE`
Ruang Angkasa Genie	`Can Run`	`genie_space` dengan `CAN_RUN`
Indeks Pencarian Vektor	`Can Select`	`uc_securable` dengan `securable_type: TABLE` dan `SELECT`
Tabel Unity Catalog	`SELECT`	`uc_securable` dengan `securable_type: TABLE` dan `SELECT`
Koneksi Katalog Unity	`Use Connection`	`uc_securable` dengan `securable_type: CONNECTION` dan `USE_CONNECTION`
Katalog Unity Volume	`Can Read` atau `Can Read and Write`	`uc_securable` dengan `securable_type: VOLUME` dan `READ_VOLUME` atau `WRITE_VOLUME`
Lakebase (disediakan)	`Can Connect and Create`	`database` dengan `CAN_CONNECT_AND_CREATE`
Lakebase (penyesuaian otomatis)	`Can Connect and Create`	`postgres` dengan `CAN_CONNECT_AND_CREATE`

Ikuti prinsip hak istimewa terendah. Berikan perwakilan layanan hanya izin yang dibutuhkan agen, dan gunakan perwakilan layanan khusus per aplikasi. Untuk daftar lengkapnya, lihat Praktik terbaik keamanan.

Otorisasi pengguna

Penting

Otorisasi pengguna ada di Pratinjau Umum. Admin ruang kerja Anda harus mengaktifkannya sebelum Anda dapat menggunakan otorisasi pengguna.

Otorisasi pengguna memungkinkan agen untuk bertindak dengan identitas pengguna yang membuat permintaan. Ini menyediakan:

Akses per pengguna ke data sensitif
Kontrol data yang mendetail yang diterapkan oleh Unity Catalog
Jejak audit khusus pengguna
Penerapan otomatis filter tingkat baris dan masker kolom

Gunakan otorisasi pengguna saat agen Anda perlu mengakses sumber daya menggunakan identitas pengguna yang meminta alih-alih perwakilan layanan aplikasi.

Cara kerja otorisasi pengguna

Saat Anda mengonfigurasi otorisasi pengguna untuk agen Anda:

Menambahkan cakupan API ke aplikasi Anda: Tentukan API Databricks mana yang dapat diakses aplikasi atas nama pengguna. Lihat Menambahkan cakupan ke aplikasi.
Kredensial pengguna dikurangi cakupannya: Databricks mengambil kredensial pengguna dan membatasinya hanya untuk cakupan API yang Anda tentukan.
Penerusan Token: Token yang cakupannya dikurangi tersedia untuk aplikasi Anda melalui x-forwarded-access-token header HTTP.
MLflow AgentServer menyimpan token: Server Agen secara otomatis menyimpan token ini per permintaan untuk akses mudah dalam kode agen.

Konfigurasikan otorisasi pengguna dengan menambahkan cakupan di antarmuka pengguna Aplikasi Databricks saat membuat atau mengedit aplikasi Anda, atau secara terprogram menggunakan API. Lihat Menambahkan cakupan ke aplikasi untuk instruksi terperinci.

Agen dengan otorisasi pengguna dapat mengakses sumber daya Databricks berikut:

Gudang SQL
Ruang Angkasa Genie
File dan direktori
Titik Akhir Penyajian Model
Indeks Pencarian Vektor
Koneksi Katalog Unity
Tabel Katalog Unity

Menerapkan otorisasi pengguna

Untuk menerapkan otorisasi pengguna, Anda harus menambahkan cakupan otorisasi ke aplikasi Anda. Cakupan membatasi apa yang dapat dilakukan aplikasi atas nama pengguna. Untuk daftar cakupan dan semantik cakupan yang tersedia, lihat Eskalasi keamanan dan hak istimewa berbasis cakupan.

Antarmuka Pengguna Ruang Kerja

Di UI Databricks, buka pengaturan Otorisasi aplikasi Anda.
Di bawah Otorisasi pengguna, klik + Tambahkan cakupan dan pilih cakupan yang diperlukan aplikasi untuk mengakses sumber daya atas nama pengguna.
Simpan perubahan dan mulai ulang aplikasi.

Paket Otomatisasi Deklaratif

Deklarasikan cakupan di bawah user_api_scopes pada sumber daya aplikasi di databricks.yml:

resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

Sebarkan ulang bundel dan mulai ulang aplikasi:
```
databricks bundle deploy
databricks bundle run my_agent
```
Nota

Setelah mengaktifkan otorisasi pengguna di ruang kerja untuk pertama kalinya, Anda perlu memulai ulang aplikasi yang ada agar mereka dapat mengakses area yang ditentukan. Lihat Menambahkan cakupan ke aplikasi.

Untuk mengonfigurasi otorisasi pengguna dalam kode agen Anda, ambil header untuk permintaan ini dari AgentServer dan buat klien ruang kerja dengan kredensial tersebut.

Dalam kode agen Anda, impor utilitas autentikasi:

Jika menggunakan salah satu templat yang disediakan dari databricks/app-templates, impor utilitas yang disediakan:
```
from databricks_app.utils import get_user_workspace_client
```
Jika tidak, impor dari utilitas Server Agen:
```
from agent_server.utils import get_user_workspace_client
```
Fungsi get_user_workspace_client() ini menggunakan Server Agen untuk mengambil x-forwarded-access-token header dan membangun klien ruang kerja menggunakan kredensial pengguna, serta menangani autentikasi antara pengguna, aplikasi, dan server agen.
Inisialisasi klien ruang kerja pada waktu kueri, bukan selama pengaktifan aplikasi:

Penting

Panggil get_user_workspace_client() di dalam handler invoke dan stream, bukan dalam __init__ atau saat startup aplikasi. Kredensial pengguna hanya tersedia saat permintaan dilakukan ketika pengguna mengajukan permintaan. Inisialisasi selama startup aplikasi akan gagal karena belum ada konteks pengguna.
```
# In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
```

Untuk panduan lengkap tentang menambahkan cakupan dan memahami keamanan berbasis cakupan, lihat Eskalasi keamanan dan hak istimewa berbasis cakupan. Minta hanya cakupan minimum yang dibutuhkan agen Anda dan catat setiap tindakan yang dilakukan atas nama pengguna; lihat Praktik terbaik untuk otorisasi pengguna.

Mengautentikasi pada server Databricks MCP

Server MCP terkelola Databricks mengekspos indeks Pencarian Vektor dan fungsi Unity Catalog sebagai alat melalui URL formulir https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> dan https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Untuk daftar server yang tersedia dan pola URL-nya, lihat Menggunakan server MCP terkelola Databricks.

Untuk mengautentikasi, berikan akses perwakilan layanan agen (atau pengguna, jika menggunakan otorisasi pengguna) ke setiap sumber daya hilir dalam skema tersebut.

Misalnya, jika agen Anda menggunakan URL server MCP berikut:

https://<your-workspace>/api/2.0/mcp/vector-search/prod/customer_support
https://<your-workspace>/api/2.0/mcp/vector-search/prod/billing
https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Anda harus memberikan akses ke setiap indeks pencarian vektor di prod.customer_support dan prod.billing, dan setiap fungsi Katalog Unity di prod.billing.

Antarmuka Pengguna Ruang Kerja

Tambahkan setiap indeks dan fungsi sebagai sumber daya di bawah Sumber daya aplikasi. Ikuti langkah yang sama seperti Memberikan izin ke sumber daya Databricks lainnya.

Paket Otomatisasi Deklaratif

Tambahkan satu uc_securable entri per indeks dan per fungsi di bawah daftar aplikasi resources Anda:

resources:
  apps:
    my_agent:
      resources:
        - name: 'support-index'
          uc_securable:
            securable_full_name: 'prod.customer_support.tickets_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'billing-index'
          uc_securable:
            securable_full_name: 'prod.billing.invoices_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'refund-function'
          uc_securable:
            securable_full_name: 'prod.billing.process_refund'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

Terapkan ulang bundel:

databricks bundle deploy
databricks bundle run my_agent

Server MCP kustom yang dihosting sebagai aplikasi Databricks mereka sendiri (nama aplikasi yang diawali dengan mcp-) belum didukung sebagai sumber daya bundel. Berikan prinsipal layanan agen Can Use pada aplikasi server MCP secara manual dengan databricks apps update-permissions. Lihat kemampuan custom-mcp-server di repositori templat agen.

Langkah selanjutnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-27

Autentikasi untuk agen AI

Mengonfigurasi autentikasi dengan UI ruang kerja atau Bundel Otomatisasi Deklaratif

Otorisasi aplikasi

Memberikan izin ke eksperimen MLflow

Antarmuka Pengguna Ruang Kerja

Paket Otomatisasi Deklaratif

Memberikan izin ke sumber daya Databricks lainnya

Antarmuka Pengguna Ruang Kerja

Paket Otomatisasi Deklaratif

Otorisasi pengguna

Cara kerja otorisasi pengguna

Menerapkan otorisasi pengguna

Antarmuka Pengguna Ruang Kerja

Paket Otomatisasi Deklaratif

Mengautentikasi pada server Databricks MCP

Antarmuka Pengguna Ruang Kerja

Paket Otomatisasi Deklaratif

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: