Autentisering för AI-agenter

AI-agenter behöver ofta autentisera till andra resurser för att slutföra uppgifter. En distribuerad agent kan till exempel behöva komma åt ett vektorsökningsindex för att köra frågor mot ostrukturerade data, en serverslutpunkt för att anropa en grundmodell eller Unity Catalog-funktioner för att köra anpassad logik.

Den här sidan beskriver autentiseringsmetoder för agenter som distribueras i Databricks-appar. För agenter som distribueras på modelltjänstslutpunkter, se Autentisering för AI-agenter (modellservering).

Databricks Apps tillhandahåller två autentiseringsmetoder för agenter. Varje metod hanterar olika användningsfall:

Du kan kombinera båda metoderna i en enda agent. Använd till exempel appauktorisering för att få åtkomst till ett delat vektorsökningsindex när du använder användarauktorisering för att fråga efter användarspecifika tabeller.

Konfigurera autentisering med arbetsytans användargränssnitt eller deklarativa automationspaket

Du kan konfigurera alla autentiseringsinställningar på två sätt:

• Arbetsytegränssnitt: Redigera appen och hantera resurser och omfång från steget Konfigurera . Rekommenderas när du itererar på en enskild app i arbetsytan.
• Deklarativa Automation-paket: Deklarera resurser, omfång och miljövariabler i en databricks.yml fil och distribuera med databricks bundle deploy. Rekommenderas när du vill ha Git-baserad versionshantering, CI/CD eller för att skicka samma agent mellan arbetsytor. Alla agentmallar levereras med en databricks.yml.

Båda sökvägarna skapar samma körningskonfiguration. Resten av den här sidan visar varje instruktion i båda formulären så att du kan välja en och hålla dig konsekvent i projektet.

Om du vill lägga till en resurs i appen via någon av sökvägarna måste du ha Can Manage behörighet för både resursen och appen.

Den fullständiga paketreferensen finns i appresursen och app.resources. En genomgång av paket från början till slut finns i Hantera Databricks-appar med deklarativa automationspaket.

Appauktorisering

Som standard autentiserar Databricks Apps med appauktorisering. Databricks skapar automatiskt ett huvudnamn för tjänsten när du skapar appen och den fungerar som appens identitet.

Alla användare som interagerar med appen har samma behörigheter som definierats för tjänstens huvudnamn. Den här modellen fungerar bra när du vill att alla användare ska se samma data eller när appen utför delade åtgärder som inte är knutna till användarspecifika åtkomstkontroller.

Detaljerad information om appauktorisering finns i Appauktorisering.

Bevilja behörigheter till MLflow-experimentet

Din agent behöver åtkomst till ett MLflow-experiment för att logga spårningar och utvärderingsresultat. Ge tjänstens huvudnamn Can Edit behörighet för experimentet.

Användargränssnitt för arbetsutrymme

1. Klicka på Redigera på appens startsida.
2. Gå till steget Konfigurera .
3. I avsnittet Appresurser lägger du till MLflow-experimentresursen med Can Edit behörighet.

Se Lägga till en MLflow-experimentresurs i en Databricks-app.

Deklarativa automationspaket

1. Deklarera experimentet i appens resources-lista i databricks.yml. Du anger name för resursen och den refereras senare när du ansluter miljövariabler.

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

2. Distribuera om paketet:

   databricks bundle deploy
   databricks bundle run my_agent
   

Se app.resources.experiment för alla fält.

Bevilja behörigheter till andra Databricks-resurser

Om din agent använder andra Databricks-resurser, till exempel Genie Spaces, Vector Search-index eller SQL-lager, beviljar du tjänstens huvudnamn behörighet för var och en.

Om du vill komma åt promptregistret, bevilja behörighet för CREATE FUNCTION, EXECUTE och MANAGE i Unity Catalog-schemat för att lagra promptar.

När du beviljar åtkomst till Unity Catalog-resurser måste du även bevilja behörigheter till alla underordnade beroende resurser. Om du till exempel beviljar åtkomst till ett Genie Space måste du även ge åtkomst till dess underliggande tabeller, SQL-lager och Unity Catalog-funktioner.

Användargränssnitt för arbetsutrymme

Lägg till resurser i appen via avsnittet Appresurser när du skapar eller redigerar appen på Databricks-arbetsytan.

1. Klicka på Redigera på appens startsida.
2. Gå till steget Konfigurera .
3. I Appresurser klickar du på + Lägg till resurs för varje resurs som agenten använder och anger behörigheten.

Se Lägga till resurser i en Databricks-app för en fullständig lista över resurser som stöds och skärmbilder.

Deklarativa automationspaket

1. Deklarera varje resurs som agenten använder i resources listan under din app i databricks.yml. Exemplet nedan visar en agent som använder ett MLflow-experiment, en serverdelsslutpunkt, ett Genie Space, ett SQL-lager, ett Vector Search-index, en Unity Catalog-funktion och en Lakebase-instans. Varje resurs name refereras via config.env och value_from så att agenten tar emot den funna identifieraren vid körning.

   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
   

   Viktigt!

   Varje value_from värde i config.env måste matcha ett name fält i resources listan. Matchningsfel gör att miljövariabeln matchas till None i den distribuerade appen.

2. Distribuera och starta paketet:

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy laddar upp källan och konfigurerar resurser. bundle run startar eller startar om appen med den senaste källkoden. Argumentet till bundle run är YAML-nyckeln under resources.apps (här my_agent), inte den distribuerade appens name fält.

Det fullständiga schemat för varje resursundertyp finns i app.resources.

I följande tabell visas de minsta behörigheter som används i exemplen ovan och motsvarande värde för deklarativa Automation-paket för varje resurstyp:

Följ principen om lägsta behörighet. Bevilja tjänsthuvudnamnet endast de behörigheter som agenten behöver och använd ett dedikerat tjänsthuvudnamn per app. Den fullständiga listan finns i Metodtips för säkerhet.

Användarauktorisering

Med användarauktorisering kan en agent agera med identiteten för den användare som gör begäran. Detta ger:

• Åtkomst per användare till känsliga data
• Detaljerade datakontroller som tillämpas av Unity Catalog
• Användarspecifika granskningsloggar
• Automatisk tillämpning av filter på radnivå och kolumnmasker

Använd användarauktorisering när din agent behöver komma åt resurser med hjälp av den begärande användarens identitet i stället för appens tjänsthuvudnamn.

Så här fungerar användarauktorisering

När du konfigurerar användarauktorisering för din agent:

1. Lägg till API-omfång i din app: Definiera vilka Databricks-API:er som appen kan komma åt för användarnas räkning. Se Lägg till omfång i en app.
2. Användarautentiseringsuppgifterna är begränsade: Databricks tar användarens autentiseringsuppgifter och begränsar dem till endast de API-behörigheter som du har definierat.
3. Vidarebefordran av token: Den nedkoperade token görs tillgänglig för din app via x-forwarded-access-token HTTP-huvudet.
4. MLflow AgentServer lagrar token: Agentservern lagrar automatiskt denna token per begäran för bekväm åtkomst i agentkoden.

Konfigurera användarauktorisering genom att lägga till omfång i användargränssnittet för Databricks-appar när du skapar eller redigerar din app eller programmatiskt med hjälp av API:et. Mer information finns i Lägga till omfång i en app .

Agenter med användarauktorisering kan komma åt följande Databricks-resurser:

• SQL Warehouse
• Genie Space
• Filer och kataloger
• Modellserverendpunkt
• Vektorsökningsindex
• Unity Catalog-anslutningar
• Unity-katalogtabeller

Implementera användarauktorisering

Om du vill implementera användarauktorisering måste du lägga till auktoriseringsomfång i din app. Omfång begränsar vad appen kan göra för användarens räkning. En lista över tillgängliga omfång och omfångssemantik finns i Omfångsbaserad säkerhet och behörighetseskalering.

Användargränssnitt för arbetsutrymme

1. I Databricks-användargränssnittet går du till appens auktoriseringsinställningar .
2. Under Användarauktorisering klickar du på + Lägg till omfång och väljer de omfång som appen behöver för att få åtkomst till resurser åt användaren.
3. Spara ändringarna och starta om appen.

Deklarativa automationspaket

1. Deklarera omfång under user_api_scopes på appresursen i 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. Distribuera om paketet och starta om appen:

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   När du har aktiverat användarauktorisering på en arbetsyta för första gången måste du starta om befintliga appar innan de kan använda tillstånd. Se Lägg till omfång i en app.

Om du vill konfigurera användarauktorisering i agentkoden hämtar du huvudet för den här begäran från AgentServer och skapar en arbetsyteklient med dessa autentiseringsuppgifter.

1. Importera autentiseringsverktyget i agentkoden:

   Om du använder någon av de angivna mallarna från databricks/appmallar importerar du det tillhandahållna verktyget:

   from databricks_app.utils import get_user_workspace_client
   

   Annars importerar du från agentserververktygen:

   from agent_server.utils import get_user_workspace_client
   

   Funktionen get_user_workspace_client() använder agentservern för att fånga x-forwarded-access-token headern och skapar en arbetsplatsklient med dessa användaruppgifter, vilket hanterar autentiseringen mellan användaren, appen och agentservern.

2. Initiera arbetsyteklienten vid frågetillfället, inte under appstart:

   Viktigt!

   Anropa get_user_workspace_client() i hanterarna invoke och stream, inte i __init__ eller vid appstart. Användarautentiseringsuppgifter är endast tillgängliga vid frågetillfället när en användare gör en begäran. Det går inte att initiera under appstarten eftersom det inte finns någon användarkontext ännu.

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

En fullständig guide för att lägga till omfång och förstå omfångsbaserad säkerhet finns i Omfångsbaserad säkerhets- och behörighetseskalering. Begär endast de minsta omfång som agenten behöver och logga varje åtgärd som utförs för en användares räkning. Se Metodtips för användarauktorisering.

Autentisera till Databricks MCP-servrar

Databricks-hanterade MCP-servrar exponerar Vector Search-index och Unity Catalog-funktioner som verktyg via URL:er i formuläret https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> och https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. En lista över tillgängliga servrar och deras URL-mönster finns i Använda Databricks-hanterade MCP-servrar.

För att autentisera ger du agentens tjänsthuvudnamn (eller användaren, om användaren använder användarauktorisering) åtkomst till alla underordnade resurser i dessa scheman.

Om din agent till exempel använder följande MCP-server-URL:er:

• 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

Du måste ge åtkomst till varje vektorsökningsindex i prod.customer_support och prod.billingoch varje Unity Catalog-funktion i prod.billing.

Användargränssnitt för arbetsutrymme

Lägg till varje index och funktion som en resurs under Appresurser. Följ samma steg som Bevilja behörigheter till andra Databricks-resurser.

Deklarativa automationspaket

1. Lägg till en uc_securable postering per index och per funktion under appens resources-lista.

   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. Distribuera om paketet:

   databricks bundle deploy
   databricks bundle run my_agent
   

Anpassade MCP-servrar som hanteras som egna Databricks-appar (appnamn som är prefix med mcp-) stöds ännu inte som paketresurser. Bevilja agentens tjänsthuvudnamn (service principal) Can Use på MCP-serverappen manuellt med databricks apps update-permissions. Se kompetensen custom-mcp-server i lagringsplatsen för agentmallar.

Nästa steg

• Skapa en AI-agent och distribuera den i Databricks-appar
• Hantera Databricks-applikationer med deklarativ automationspaket
• Konfigurera auktorisering i en Databricks-app
• Lägga till resurser i en Databricks-app
• referens för appresurs