Verificatie voor AI-agents

AI-agents moeten vaak worden geverifieerd bij andere resources om taken te voltooien. Een geïmplementeerde agent moet bijvoorbeeld toegang krijgen tot een Vector Search-index om ongestructureerde gegevens op te vragen, een dienend eindpunt om een basismodel aan te roepen of unity catalog-functies om aangepaste logica uit te voeren.

Op deze pagina worden verificatiemethoden beschreven voor agents die zijn geïmplementeerd in Databricks-apps. Zie voor agents die zijn geïmplementeerd op eindpunten voor Model Serving Authenticatie voor AI-agents (Model Serving).

Databricks Apps biedt twee verificatiemethoden voor agents. Elke methode dient verschillende gebruiksvoorbeelden:

U kunt beide methoden in één agent combineren. Gebruik bijvoorbeeld app-autorisatie voor toegang tot een gedeelde Vector Search-index terwijl u gebruikersautorisatie gebruikt om query's uit te voeren op gebruikersspecifieke tabellen.

Verificatie configureren met de gebruikersinterface van de werkruimte of declaratieve Automation-bundels

U kunt alle verificatie-instellingen op twee manieren configureren:

• Werkruimte-UI: bewerkt u de app en beheert u de resources en scopes vanuit de stap Configureren. Aanbevolen wanneer u op één app binnen de werkruimte itereren.
• Declaratieve Automatiseringsbundels: Resources, bereiken en omgevingsvariabelen declareren in een databricks.yml bestand en implementeren met databricks bundle deploy. Aanbevolen wanneer u versiebeheer op basis van Git, CI/CD of dezelfde agent wilt verzenden in werkruimten. Alle agentsjablonen worden geleverd met een databricks.yml.

Beide paden produceren dezelfde runtimeconfiguratie. In de rest van deze pagina ziet u elke instructie in beide formulieren, zodat u er een kunt selecteren en consistent kunt blijven binnen uw project.

Als u via beide paden een resource aan de app wilt toevoegen, moet u gemachtigd zijn Can Manage voor zowel de resource als de app.

Zie app resource en app.resources voor de volledige bundelreferentie. Zie voor een stapsgewijze handleiding van end-to-end bundels Databricks-apps beheren met behulp van declaratieve Automation-bundels.

App-autorisatie

Databricks-apps worden standaard geverifieerd met behulp van app-autorisatie. Databricks maakt automatisch een service-principal wanneer u de app maakt en fungeert als de identiteit van de app.

Alle gebruikers die met de app werken, delen dezelfde machtigingen die zijn gedefinieerd voor de service-principal. Dit model werkt goed wanneer u wilt dat alle gebruikers dezelfde gegevens zien of wanneer de app gedeelde bewerkingen uitvoert die niet zijn gekoppeld aan gebruikersspecifieke toegangsbeheer.

Zie App-autorisatie voor gedetailleerde informatie over app-autorisatie.

Machtigingen verlenen aan het MLflow-experiment

Uw agent heeft toegang nodig tot een MLflow-experiment om traceringen en evaluatieresultaten te registreren. Verleen aan de service-principal Can Edit toestemming voor het experiment.

Gebruikersinterface van werkruimte

1. Klik op Bewerken op de startpagina van uw app.
2. Ga naar de stap Configureren .
3. Voeg in de sectie App-resources de MLflow-experimentresource met Can Edit machtiging toe.

Zie Een MLflow-experimentresource toevoegen aan een Databricks-app.

Declaratieve automatiseringsbundels

1. Declareer het experiment onder de lijst van uw app resources in databricks.yml. De name die u aan de bron toewijst, wordt later gebruikt wanneer u omgevingsvariabelen koppelt.

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

2. Implementeer de bundel opnieuw:

   databricks bundle deploy
   databricks bundle run my_agent
   

Zie app.resources.experiment voor alle velden.

Machtigingen verlenen aan andere Databricks-resources

Als uw agent andere Databricks-resources gebruikt, zoals Genie Spaces, Vector Search-indexen of SQL-warehouses, verleent u de service-principal machtigingen voor elke resource.

Als u toegang wilt krijgen tot het promptregister, verleent CREATE FUNCTION, EXECUTEen MANAGE machtigingen voor het Unity Catalog-schema voor het opslaan van prompts.

Wanneer u toegang verleent tot Unity Catalog-resources, moet u ook machtigingen verlenen aan alle downstreamafhankelijke resources. Als u bijvoorbeeld toegang verleent tot een Genie Space, moet u ook toegang verlenen tot de onderliggende tabellen, SQL-magazijnen en Unity Catalog-functies.

Gebruikersinterface van werkruimte

Voeg resources toe aan de app via de sectie App-resources wanneer u de app in de Databricks-werkruimte maakt of bewerkt.

1. Klik op Bewerken op de startpagina van uw app.
2. Ga naar de stap Configureren .
3. Klik in App-resources op + Resource toevoegen voor elke resource die de agent gebruikt en stel de machtiging in.

Zie Resources toevoegen aan een Databricks-app voor de volledige lijst met ondersteunde resources en schermopnamen.

Declaratieve automatiseringsbundels

1. Declareer elke resource die de agent gebruikt in de resources lijst onder uw app in databricks.yml. In het onderstaande voorbeeld ziet u een agent die gebruikmaakt van een MLflow-experiment, een dienend eindpunt, een Genie Space, een SQL-magazijn, een Vector Search-index, een Unity Catalog-functie en een Lakebase-exemplaar. Er wordt naar elke resource name verwezen vanuit config.env via value_from, zodat de agent tijdens uitvoeringstijd de opgeloste identificator ontvangt.

   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
   

   Belangrijk

   Elke value_from waarde in config.env moet overeenkomen met een name veld in de resources lijst. Niet-overeenkomendheden zorgen ervoor dat de omgevingsvariabele wordt geresolved naar None in de uitgerolde app.

2. De bundel implementeren en starten:

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy upload de bron en configureert bronnen. bundle run start of start de app opnieuw op met de meest recente bron. Het argument hiervoor bundle run is de YAML-sleutel onder resources.apps (hier my_agent), niet het veld van name de geïmplementeerde app.

Zie app.resources voor het volledige schema van elk resourcesubtype.

De volgende tabel bevat de minimale machtigingen die worden gebruikt in de bovenstaande voorbeelden en de equivalente declaratieve Automation Bundles-waarde voor elk resourcetype:

Volg het principe van minimale bevoegdheden. Geef de service-principal alleen de machtigingen die de agent nodig heeft en gebruik een specifieke service-principal per app. Zie best practices voor beveiliging voor de volledige lijst.

Gebruikersautorisatie

Met gebruikersautorisatie kan een agent handelen met de identiteit van de gebruiker die de aanvraag indient. Dit biedt:

• Toegang per gebruiker tot gevoelige gegevens
• Verfijnde gegevenscontrolemechanismen die worden gehandhaafd door Unity Catalog
• Gebruikersspecifieke audittrails
• Automatische afdwinging van filters op rijniveau en kolommaskers

Gebruik gebruikersautorisatie wanneer uw agent toegang nodig heeft tot resources met behulp van de identiteit van de gebruiker die het verzoek doet in plaats van de service-principal van de app.

Hoe gebruikersautorisatie werkt

Wanneer u gebruikersautorisatie configureert voor uw agent:

1. API-bereiken toevoegen aan uw app: definieer welke Databricks-API's de app namens gebruikers kan openen. Zie Bereiken toevoegen aan een app.
2. Gebruikersgegevens worden beperkt in reikwijdte: Databricks neemt de gebruikersgegevens en beperkt deze tot de API-bereiken die u hebt gedefinieerd.
3. Token doorsturen: het downscoped-token wordt beschikbaar gesteld aan uw app via de x-forwarded-access-token HTTP-header.
4. MLflow AgentServer slaat het token op: De agentserver slaat dit token automatisch op per aanvraag voor handige toegang in agentcode.

Stel gebruikersautorisatie in door scopes toe te voegen in de Databricks Apps-gebruikersinterface wanneer u uw app maakt of bewerkt, of programmeerbaar met behulp van de API. Zie Bereiken toevoegen aan een app voor gedetailleerde instructies.

Agents met gebruikersautorisatie hebben toegang tot de volgende Databricks-resources:

• SQL Warehouse
• Genie Space
• Bestanden en mappen
• Eindpunt voor modeluitvoering
• Vectorzoekindex
• Unity Catalog-verbindingen
• Unity Catalog-tabellen

Gebruikersautorisatie implementeren

Als u gebruikersautorisatie wilt implementeren, moet u autorisatiebereiken toevoegen aan uw app. Bereiken beperken wat de app namens de gebruiker kan doen. Zie Scope-gebaseerde beveiliging en bevoegdheidsescalatie voor de lijst met beschikbare scopes en scopemantics.

Gebruikersinterface van werkruimte

1. Ga in de Databricks-gebruikersinterface naar de autorisatie-instellingen van uw app.
2. Klik onder Gebruikersautorisatie op + Bereik toevoegen en selecteer de bereiken die de app namens de gebruiker nodig heeft voor toegang tot resources.
3. Sla de wijzigingen op en start de app opnieuw op.

Declaratieve automatiseringsbundels

1. Scope declareren onder user_api_scopes op de app-resource in 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. Implementeer de bundel opnieuw en start de app opnieuw op:

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   Nadat u gebruikersautorisatie voor de eerste keer hebt ingeschakeld voor een werkruimte, moet u bestaande apps opnieuw starten voordat ze scopes kunnen gebruiken. Zie Bereiken toevoegen aan een app.

Als u gebruikersautorisatie in uw agentcode wilt configureren, haalt u de header voor deze aanvraag op uit de AgentServer en maakt u een werkruimteclient met deze referenties.

1. Importeer het verificatiehulpprogramma in uw agentcode:

   Als u een van de meegeleverde sjablonen uit databricks/app-sjablonen gebruikt, importeert u het opgegeven hulpprogramma:

   from databricks_app.utils import get_user_workspace_client
   

   Anders importeert u vanuit de agentserverhulpprogramma's:

   from agent_server.utils import get_user_workspace_client
   

   De get_user_workspace_client() functie gebruikt de Agent Server om de x-forwarded-access-token header vast te leggen en een werkruimte-client samen te stellen met die gebruikersreferenties, en het beheer van authenticatie tussen de gebruiker, app en Agent Server te behandelen.

2. Initialiseer de werkruimteclient tijdens het uitvoeren van query's, niet tijdens het opstarten van de app:

   Belangrijk

   Roep get_user_workspace_client() aan binnen de invoke- en stream-handlers, niet in __init__ of tijdens het opstarten van de app. Gebruikersreferenties zijn alleen beschikbaar op het moment dat een gebruiker een aanvraag indient. Initialiseren tijdens het opstarten van de app mislukt omdat er nog geen gebruikerscontext bestaat.

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

Zie voor een volledige handleiding over het toevoegen van bereiken en het begrijpen van bereikgebaseerde beveiliging, Bereikgebaseerde beveiliging en bevoegdheidsuitbreiding. Vraag alleen de minimale bevoegdheden aan die uw agent nodig heeft en registreer elke actie die namens een gebruiker wordt uitgevoerd; zie Best Practices voor Gebruikersautorisatie.

Verifiëren bij Databricks MCP-servers

Door Databricks beheerde MCP-servers maken Vector Search-indexen en Unity Catalog-functies beschikbaar als hulpprogramma's via URL's van het formulier https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> en https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Zie Databricks beheerde MCP-servers gebruiken voor de lijst met beschikbare servers en hun URL-patronen.

Als u zich wilt verifiëren, verleent u de service-principal van de agent (of de gebruiker, als deze gebruikmaakt van gebruikersautorisatie) toegang tot elke downstreamresource in deze schema's.

Als uw agent bijvoorbeeld de volgende MCP-server-URL's gebruikt:

• 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

U moet toegang verlenen tot elke vectorzoekindex in prod.customer_support en prod.billing, en elke Unity Catalog-functie in prod.billing.

Gebruikersinterface van werkruimte

Voeg elke index toe en functioneer als een resource onder App-resources. Volg dezelfde stappen als Machtigingen verlenen aan andere Databricks-resources.

Declaratieve automatiseringsbundels

1. Voeg één uc_securable vermelding per index en per functie toe onder de lijst van resources uw app:

   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. Implementeer de bundel opnieuw:

   databricks bundle deploy
   databricks bundle run my_agent
   

Aangepaste MCP-servers die worden gehost als hun eigen Databricks-apps (app-namen voorafgegaan door mcp-) worden nog niet ondersteund als bundelresources. Verleen de service-principal Can Use van de agent handmatig op de MCP-server-app met databricks apps update-permissions. Zie de custom-mcp-server-vaardigheid in de opslagplaats met agentsjablonen.

Volgende stappen

• Een AI-agent ontwerpen en implementeren in Databricks-apps
• Databricks-apps beheren met Declaratieve Automatiseringsbundels
• Autorisatie configureren in een Databricks-app
• Resources toevoegen aan een Databricks-app
• app-resourceverwijzing