Uwierzytelnianie agentów sztucznej inteligencji

Agenci sztucznej inteligencji często muszą uwierzytelniać się w innych zasobach, aby wykonywać zadania. Na przykład wdrożony agent może wymagać dostępu do indeksu wyszukiwania wektorowego w celu zapytań o dane niestrukturalne, serwującego punktu końcowego do wywołania modelu podstawowego lub funkcji Katalogu Unity do wykonania niestandardowej logiki.

Na tej stronie opisano metody uwierzytelniania dla agentów wdrożonych w usłudze Databricks Apps. Dla agentów wdrożonych na punktach końcowych obsługujących model, zobacz Authentication for AI agents (Model Serving) (Uwierzytelnianie agentów sztucznej inteligencji).

Usługa Databricks Apps udostępnia dwie metody uwierzytelniania dla agentów. Każda metoda obsługuje różne przypadki użycia:

Metoda Description Kiedy należy używać
Autoryzacja aplikacji Agent uwierzytelnia się przy użyciu automatycznie utworzonej głównej usługi ze spójnymi uprawnieniami. Wcześniej nazywane uwierzytelnianiem Service Principal. Najbardziej typowy przypadek użycia. Użyj polecenia gdy wszyscy użytkownicy powinni mieć taki sam dostęp do zasobów.
Autoryzacja użytkownika Agent uwierzytelnia się przy użyciu tożsamości użytkownika wysyłającego żądanie. Wcześniej nazywane uwierzytelnianiem w imieniu (OBO). Używaj, gdy potrzebujesz uprawnień specyficznych dla użytkownika, ścieżek audytu lub kontroli dostępu szczegółowej z Unity Catalog.

Obie metody można połączyć w jednym agencie. Na przykład użyj autoryzacji aplikacji, aby uzyskać dostęp do udostępnionego indeksu wyszukiwania wektorowego podczas używania autoryzacji użytkownika do wykonywania zapytań dotyczących tabel specyficznych dla użytkownika.

Skonfiguruj uwierzytelnianie za pomocą interfejsu użytkownika obszaru roboczego lub Deklaratywnych Pakietów Automatyzacji

Wszystkie ustawienia uwierzytelniania można skonfigurować na dwa sposoby:

  • Interfejs użytkownika obszaru roboczego: edytuj aplikację i zarządzaj zasobami i zakresami w kroku Konfigurowanie . Zalecane, gdy iterujesz w ramach jednej aplikacji w środowisku roboczym.
  • Pakiety automatyzacji deklaratywnej: deklarowanie zasobów, zakresów i zmiennych środowiskowych w databricks.yml pliku i wdrażanie za pomocą polecenia databricks bundle deploy. Zalecane, gdy chcesz używać wersjonowania opartego na Git, CI/CD lub gdy potrzebne jest udostępnianie tego samego agenta w różnych przestrzeniach roboczych. Wszystkie szablony agentów są dostarczane z elementem databricks.yml.

Obie ścieżki tworzą tę samą konfigurację środowiska uruchomieniowego. Pozostała część tej strony zawiera każdą instrukcję w obu formularzach, dzięki czemu można wybrać jedną i zachować spójność w projekcie.

Aby dodać zasób do aplikacji za pomocą obu ścieżek, musisz mieć Can Manage uprawnienie zarówno do zasobu, jak i aplikacji.

Aby uzyskać pełne odniesienie do pakietu, zobacz zasób aplikacji i app.resources. Aby uzyskać szczegółowy przewodnik po pakiecie, zobacz Manage Databricks apps using Declarative Automation Bundles (Zarządzanie aplikacjami usługi Databricks przy użyciu pakietów deklaratywnej automatyzacji).

Autoryzacja aplikacji

Domyślnie usługa Databricks Apps uwierzytelnia się przy użyciu autoryzacji aplikacji. Usługa Databricks automatycznie tworzy jednostkę usługi podczas tworzenia aplikacji i działa jako tożsamość aplikacji.

Wszyscy użytkownicy, którzy wchodzą w interakcję z aplikacją, mają te same uprawnienia zdefiniowane dla jednostki usługi. Ten model działa dobrze, gdy chcesz, aby wszyscy użytkownicy widzieli te same dane lub gdy aplikacja wykonuje udostępnione operacje, które nie są powiązane z kontrolą dostępu specyficzną dla użytkownika.

Aby uzyskać szczegółowe informacje na temat autoryzacji aplikacji, zobacz Autoryzacja aplikacji.

Udzielanie uprawnień do eksperymentu MLflow

Agent musi mieć dostęp do eksperymentu MLflow w celu rejestrowania śladów i wyników oceny. Przyznaj jednostce usługi Can Edit uprawnienie do eksperymentu.

Interfejs użytkownika obszaru roboczego

  1. Kliknij pozycję Edytuj na stronie głównej aplikacji.
  2. Przejdź do kroku Konfigurowanie .
  3. W sekcji Zasoby aplikacji dodaj zasób eksperymentu MLflow z uprawnieniami Can Edit .

Zobacz Dodawanie zasobu eksperymentu MLflow do aplikacji usługi Databricks.

Pakiety automatyzacji deklaratywnej

  1. Zadeklaruj eksperyment na liście resources w swojej aplikacji databricks.yml. Przypisanie name do zasobu jest przywołyne później podczas nawiązywania połączenia ze zmiennymi środowiskowymi.

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

  2. Ponownie wdróż pakiet:

    databricks bundle deploy
databricks bundle run my_agent

Zobacz app.resources.experiment dla wszystkich pól.

Udzielanie uprawnień innym zasobom usługi Databricks

Jeśli agent używa innych zasobów platformy Databricks, takich jak Genie spaces, indeksy wyszukiwania wektorowego lub magazyny SQL, przyznaj obiektowi zasadniczemu usługi uprawnienia do każdego z nich.

Aby uzyskać dostęp do rejestru monitów, udziel CREATE FUNCTION, EXECUTE, i MANAGE uprawnień w schemacie Unity Catalog do przechowywania monitów.

W przypadku udzielania dostępu do zasobów Unity Catalog należy również udzielić uprawnień do wszystkich zasobów zależnych. Jeśli na przykład przyznasz dostęp do obszaru Genie, musisz również udzielić dostępu do jego bazowych tabel, magazynów SQL i funkcji katalogu Unity.

Interfejs użytkownika obszaru roboczego

Dodaj zasoby do aplikacji za pomocą sekcji Zasoby aplikacji podczas tworzenia lub edytowania aplikacji w obszarze roboczym usługi Databricks.

  1. Kliknij pozycję Edytuj na stronie głównej aplikacji.
  2. Przejdź do kroku Konfigurowanie .
  3. W obszarze Zasoby aplikacji kliknij pozycję + Dodaj zasób dla każdego zasobu używanego przez agenta i ustaw uprawnienie.

Zobacz Dodawanie zasobów do aplikacji usługi Databricks , aby uzyskać pełną listę obsługiwanych zasobów i zrzutów ekranu.

Pakiety automatyzacji deklaratywnej

  1. Zadeklaruj każdy zasób używany przez agenta w liście resources w databricks.yml pod Twoją aplikacją. W poniższym przykładzie pokazano agenta korzystającego z eksperymentu MLflow, punktu końcowego usługi, obszaru Genie, hurtowni SQL, indeksu wyszukiwania wektorowego, funkcji katalogu Unity i instancji Lakebase. Każdy zasób name jest przywoływany z config.env poprzez value_from, więc agent otrzymuje rozpoznany identyfikator w czasie wykonywania.

    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

    Ważne

    Każda value_from wartość na config.env liście musi być zgodna z polem name na resources liście. Niezgodności powodują, że zmienna środowiskowa jest rozpoznawana jako None w ramach wdrożonej aplikacji.

  2. Wdróż i uruchom pakiet:

    databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent

    bundle deploy przekazuje źródło i konfiguruje zasoby. bundle run uruchamia lub uruchamia ponownie aplikację przy użyciu najnowszego źródła. Kluczem YAML pod resources.apps (tutaj my_agent) jest argument przekazywany do bundle run, a nie pole w wdrożonej aplikacji name.

Aby uzyskać pełny schemat każdego podtypu zasobu, zobacz app.resources.

W poniższej tabeli wymieniono minimalne uprawnienia używane w przykładach powyżej oraz równoważną wartość Deklaratywnych Pakietów Automatyzacji dla każdego typu zasobu:

Typ zasobu Uprawnienie interfejsu użytkownika obszaru roboczego Deklaratywne pakiety automatyzacji zasobów i uprawnień
SQL Warehouse Can Use sql_warehouse z CAN_USE
Punkt końcowy serwisowania modelu Can Query serving_endpoint z CAN_QUERY
Funkcja Katalogu Unity Can Execute uc_securablez i securable_type: FUNCTIONEXECUTE
Genie Space Can Run genie_space z CAN_RUN
Indeks wyszukiwania wektorowego Can Select uc_securablez i securable_type: TABLESELECT
Tabela katalogu Unity SELECT uc_securablez i securable_type: TABLESELECT
Połączenie katalogu Unity Use Connection uc_securablez i securable_type: CONNECTIONUSE_CONNECTION
Wolumen katalogu Unity Can Read lub Can Read and Write uc_securable z securable_type: VOLUME i READ_VOLUME lub WRITE_VOLUME
Lakebase (zaprovisioningowana) Can Connect and Create database z CAN_CONNECT_AND_CREATE
Lakebase (skalowanie automatyczne) Can Connect and Create postgres z CAN_CONNECT_AND_CREATE

Przestrzegaj reguły najmniejszych uprawnień. Przyznaj jednostce usługi tylko uprawnienia wymagane przez agenta i użyj dedykowanej jednostki usługi na aplikację. Aby uzyskać pełną listę, zobacz Najlepsze rozwiązania dotyczące zabezpieczeń.

Autoryzacja użytkownika

Ważne

Autoryzacja użytkownika jest dostępna w publicznej wersji zapoznawczej. Administrator obszaru roboczego musi go włączyć przed użyciem autoryzacji użytkownika.

Autoryzacja użytkownika umożliwia agentowi działanie przy użyciu tożsamości użytkownika wysyłającego żądanie. Zapewnia to:

  • Dostęp poszczególnych użytkowników do poufnych danych
  • Szczegółowe kontrole danych egzekwowane przez Unity Catalog
  • Dzienniki inspekcji specyficzne dla użytkownika
  • Automatyczne wymuszanie filtrów na poziomie wiersza i masek kolumn

Użyj autoryzacji użytkownika, gdy agent musi uzyskać dostęp do zasobów przy użyciu tożsamości użytkownika żądającego zamiast głównego składnika usługi aplikacji.

Jak działa autoryzacja użytkownika

Podczas konfigurowania autoryzacji użytkownika dla agenta:

  1. Dodawanie zakresów interfejsu API do aplikacji: określ, do których interfejsów API usługi Databricks aplikacja może uzyskiwać dostęp w imieniu użytkowników. Zobacz Dodawanie zakresów do aplikacji.
  2. Poświadczenia użytkownika są ograniczone: usługa Databricks pobiera poświadczenia użytkownika i ogranicza je tylko do zdefiniowanych zakresów API.
  3. Przekazywanie tokenu: token o ograniczonym zakresie jest udostępniany aplikacji za pośrednictwem nagłówka x-forwarded-access-token HTTP.
  4. Serwer MLflow AgentServer przechowuje token: Serwer agenta automatycznie przechowuje ten token na żądanie wygodnego dostępu w kodzie agenta.

Skonfiguruj autoryzację użytkownika, dodając zakresy w interfejsie użytkownika usługi Databricks Apps podczas tworzenia lub edytowania aplikacji albo programowo przy użyciu interfejsu API. Aby uzyskać szczegółowe instrukcje, zobacz Dodawanie zakresów do aplikacji .

Agenci z autoryzacją użytkownika mogą uzyskiwać dostęp do następujących zasobów usługi Databricks:

  • SQL Warehouse
  • Genie Space
  • Pliki i katalogi
  • Punkt końcowy obsługi modelu
  • Indeks wyszukiwania wektorowego
  • Połączenia Katalogu Unity
  • Tabele katalogu Unity

Implementowanie autoryzacji użytkownika

Aby zaimplementować autoryzację użytkownika, musisz dodać zakresy autoryzacji do aplikacji. Zakresy ograniczają działania aplikacji w imieniu użytkownika. Aby uzyskać listę dostępnych zakresów i semantyki zakresu, zobacz Eskalacja zabezpieczeń i uprawnień opartych na zakresie.

Interfejs użytkownika obszaru roboczego

  1. W interfejsie użytkownika usługi Databricks przejdź do ustawień autoryzacji aplikacji.
  2. W obszarze Autoryzacja użytkownika kliknij pozycję + Dodaj zakres i wybierz zakresy, do których aplikacja musi mieć dostęp w imieniu użytkownika, aby uzyskać dostęp do zasobów.
  3. Zapisz zmiany i uruchom ponownie aplikację.

Pakiety automatyzacji deklaratywnej

  1. Zadeklaruj zakresy w obszarze user_api_scopes w zasobie aplikacji w pliku 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'

  2. Ponownie wdróż pakiet i uruchom ponownie aplikację:

    databricks bundle deploy
databricks bundle run my_agent

    Note

    Po pierwszym włączeniu autoryzacji użytkownika w obszarze roboczym należy ponownie uruchomić istniejące aplikacje, zanim będą mogły korzystać z zakresów. Zobacz Dodawanie zakresów do aplikacji.

Aby skonfigurować autoryzację użytkownika w kodzie agenta, pobierz nagłówek dla tego żądania z AgentServer i skonstruuj klienta przestrzeni roboczej wykorzystując te poświadczenia.

  1. W kodzie agenta zaimportuj narzędzie uwierzytelniania:

    Jeśli używasz jednego z podanych szablonów z usługi databricks/app-templates, zaimportuj podane narzędzie:

    from databricks_app.utils import get_user_workspace_client

    W przeciwnym razie zaimportuj z narzędzi Agent Server.

    from agent_server.utils import get_user_workspace_client

    Funkcja get_user_workspace_client() używa serwera agenta do przechwytywania nagłówka x-forwarded-access-token i konstruowania klienta dla obszaru roboczego przy użyciu tych poświadczeń użytkownika, zarządzając uwierzytelnianiem między użytkownikiem, aplikacją i serwerem agenta.

  2. Zainicjuj klienta obszaru roboczego w czasie wykonywania zapytania, a nie podczas uruchamiania aplikacji:

    Ważne

    Wywołaj get_user_workspace_client() wewnątrz obsługi invoke i stream, a nie w __init__ ani podczas uruchamiania aplikacji. Poświadczenia użytkownika są dostępne tylko w czasie wykonywania zapytania, gdy użytkownik wysyła żądanie. Inicjowanie podczas uruchamiania aplikacji zakończy się niepowodzeniem, ponieważ nie istnieje jeszcze żaden kontekst użytkownika.

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

Pełny przewodnik dotyczący dodawania zakresów i rozumienia zabezpieczeń opartych na zakresie można znaleźć w temacie Eskalacja zabezpieczeń i uprawnień opartych na zakresie. Zażądaj tylko minimalnych zakresów wymaganych przez agenta i zarejestruj każdą akcję wykonywaną w imieniu użytkownika; Zobacz Najlepsze rozwiązania dotyczące autoryzacji użytkownika.

Uwierzytelnić się do serwerów MCP Databricks

Zarządzane serwery MCP usługi Databricks uwidaczniają indeksy wyszukiwania wektorowego i funkcje Unity Catalog jako narzędzia przez adresy URL w postaci https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> i https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Aby uzyskać listę dostępnych serwerów i ich wzorców adresów URL, zobacz Używanie serwerów MCP zarządzanych przez usługę Databricks.

Aby przeprowadzić uwierzytelnianie, przyznaj jednostce usługi agenta (lub użytkownikowi, jeśli używasz autoryzacji użytkownika) dostęp do każdego zasobu podrzędnego w tych schematach.

Jeśli na przykład agent używa następujących adresów URL serwera MCP:

  • 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

Należy udzielić dostępu do każdego indeksu wyszukiwania wektorów w prod.customer_support i prod.billing, oraz każdej funkcji Katalogu Unity w prod.billing.

Interfejs użytkownika obszaru roboczego

Dodaj każdy indeks i funkcję jako zasób w obszarze Zasoby aplikacji. Wykonaj te same kroki, jak Udzielanie uprawnień innym zasobom usługi Databricks.

Pakiety automatyzacji deklaratywnej

  1. Dodaj jeden uc_securable wpis dla każdego indeksu i funkcji na liście Twojej aplikacji resources.

    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'

  2. Ponownie wdróż pakiet:

    databricks bundle deploy
databricks bundle run my_agent

Niestandardowe serwery MCP hostowane jako własne aplikacje usługi Databricks (nazwy aplikacji poprzedzone prefiksem mcp-) nie są jeszcze obsługiwane jako zasoby pakietu. Udziel głównego konta usługi agenta Can Use w aplikacji serwera MCP ręcznie za pomocą databricks apps update-permissions. Zobacz funkcję custom-mcp-server w repozytorium agentów z szablonami.

Dalsze kroki

  • Last updated on