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 een query uit te voeren op niet-gestructureerde gegevens of het promptregister om dynamische prompts te laden.

Op deze pagina worden de verificatiemethoden beschreven die beschikbaar zijn bij het ontwikkelen en implementeren van agents met behulp van Mosaic AI Agent Framework.

Verificatiemethoden

In de volgende tabel worden de beschikbare verificatiemethoden vergeleken. U kunt een van deze benaderingen combineren en vergelijken:

Methode	Description	Beveiligingspostuur	Complexiteit van installatie
Doorgave voor automatische verificatie	Agent wordt uitgevoerd met de machtigingen van de gebruiker die deze heeft geïmplementeerd Databricks beheert automatisch tijdelijke inloggegevens voor gedeclareerde resources.	Referenties met korte levensduur, automatische rotatie	Laag - afhankelijkheden declareren tijdens logboekregistratie
Authenticatie namens de gebruiker (OBO)	Agent wordt uitgevoerd met de machtigingen van de eindgebruiker die de aanvraag indient	Maakt gebruik van referenties van eindgebruikers met beperkte toegangsrechten	Gemiddeld: vereist bereikdeclaratie en runtime-initialisatie
Handmatige verificatie	Expliciet referenties opgeven met behulp van omgevingsvariabelen	Langdurige referenties hebben rotatiebeheer nodig	Hoog: vereist handmatig referentiebeheer

Verifiëren bij externe systemen en MCP-servers

Zie Ai-agenthulpprogramma's verbinden met externe services voor hulp bij verificatie bij externe API's en MCP-servers van uw agent. Deze resources kunnen ook worden opgevraagd namens de agent of gebruiker, zoals beschreven in verificatiemethoden.

De juiste verificatiemethode voor uw resource kiezen

Gebruik dit stroomdiagram om de juiste verificatiemethode voor elke resource te kiezen. U kunt methoden indien nodig combineren en een agent kan een andere methode voor elke resource gebruiken, afhankelijk van de use-case.

1. Is toegangsbeheer per gebruiker of door de gebruiker toegewezen controle vereist?

   • Ja → Gebruik verificatie namens gebruiker
   • Geen → Doorgaan naar stap 2

2. Ondersteunen alle resources automatische authenticatie?

   • Ja → Automatische verificatiepassthrough gebruiken (aanbevolen)
   • Geen → Handmatige verificatie gebruiken

Passthrough voor automatische verificatie

Automatische verificatiedoorgifte is de eenvoudigste methode voor toegang tot door Databricks beheerde bronnen. Declareer resourceafhankelijkheden bij het loggen van de agent, en Databricks verstrekt, roteert en beheert automatisch tijdelijke referenties wanneer de agent wordt geïmplementeerd.

Dit verificatiegedrag is vergelijkbaar met het gedrag 'Als eigenaar uitvoeren' voor Databricks-dashboards. Nederstroombronnen zoals Unity Catalog-tabellen worden geopend met behulp van de referentiegegevens van een service principal met minimaal bevoegde toegang tot alleen de bronnen die de agent nodig heeft.

Hoe automatische verificatiepassthrough werkt

Wanneer een agent achter een eindpunt wordt geleverd via automatische authenticatie-passthrough, voert Databricks de volgende stappen uit:

1. Machtigingsverificatie: Databricks controleert of de maker van het eindpunt toegang heeft tot alle afhankelijkheden die zijn opgegeven tijdens het registreren van agents.

2. Service-principalcreatie en -rechten: Er wordt een service-principal gemaakt voor de versie van het agentmodel en deze krijgt automatisch leestoegang tot de agentresources.

   Opmerking

   De service-principal die door het systeem is gegenereerd, verschijnt niet in API- of UI-lijsten. Als de versie van het agentmodel wordt verwijderd van het endpoint, wordt de service-principal ook verwijderd.

3. Referenties inrichten en roulatie: Kortstondige referenties (een M2M OAuth-token) voor de service-principal worden in het eindpunt geïnjecteerd, zodat agentcode toegang kan verkrijgen tot de resources van Databricks. Databricks roteert ook de referenties, zodat uw agent veilige toegang kan blijven houden tot afhankelijke middelen.

Ondersteunde resources voor automatische authenticatiedoorgifte

De volgende tabel bevat de Databricks-resources die ondersteuning bieden voor automatische verificatie via passthrough en de machtigingen die de auteur van het eindpunt moet hebben voor de implementatie van de agent.

Opmerking

Unity Catalog-resources vereisen tevens USE SCHEMA in het bovenliggende schema en USE CATALOG in de bovenliggende catalogus.

Hulpmiddeltype	Toestemming	Minimale MLflow-versie
SQL Warehouse	Use Endpoint	2.16.1 of hoger
Eindpunt voor modelservice	Can Query	2.13.1 of hoger
Unity Catalog-functie	EXECUTE	2.16.1 of hoger
Genieruimte	Can Run	2.17.1 of hoger
Vectorzoekindex	Can Use	2.13.1 of hoger
tabel van Unity Catalog	SELECT	2.18.0 of hoger
Unity Catalog-verbinding	Use Connection	2.17.1 of hoger
Lakebase	databricks_superuser	3.3.2 of hoger

Automatische authenticatie-passthrough implementeren

Als u automatische verificatiepassthrough wilt inschakelen, geeft u afhankelijke resources op wanneer u de agent aanmeldt. Gebruik de resources parameter van de log_model() API:

Opmerking

Vergeet niet om ook alle downstreamafhankelijke resources te registreren. Als u bijvoorbeeld een Genie Space aanmeldt, moet u ook de tabellen, SQL Warehouses en Unity Catalog-functies registreren.

import mlflow
from mlflow.models.resources import (
  DatabricksVectorSearchIndex,
  DatabricksServingEndpoint,
  DatabricksSQLWarehouse,
  DatabricksFunction,
  DatabricksGenieSpace,
  DatabricksTable,
  DatabricksUCConnection,
  DatabricksApp,
  DatabricksLakebase
)

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model="agent.py",
    artifact_path="agent",
    input_example=input_example,
    example_no_conversion=True,
    # Specify resources for automatic authentication passthrough
    resources=[
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksServingEndpoint(endpoint_name="databricks-bge-large-en"),
      DatabricksSQLWarehouse(warehouse_id="your_warehouse_id"),
      DatabricksFunction(function_name="ml.tools.python_exec"),
      DatabricksGenieSpace(genie_space_id="your_genie_space_id"),
      DatabricksTable(table_name="your_table_name"),
      DatabricksUCConnection(connection_name="your_connection_name"),
      DatabricksApp(app_name="app_name"),
      DatabricksLakebase(database_instance_name="lakebase_instance_name"),
    ]
  )

Authenticatie namens de gebruiker

Belangrijk

Deze functie bevindt zich in openbare preview-versie.

Met verificatie namens de gebruiker (OBO) kan een agent fungeren als de Databricks-gebruiker die de query uitvoert. Dit biedt:

• Toegang per gebruiker tot gevoelige gegevens
• Verfijnde gegevensbesturingselementen die worden afgedwongen door Unity Catalog
• Beveiligingstokens worden beperkt ('downscoped') tot alleen de API's die uw agent declareert, waardoor het risico op misbruik wordt verminderd

Requirements

• Voor verificatie namens de gebruiker is MLflow 2.22.1 en hoger vereist.
• Verificatie namens de gebruiker is standaard uitgeschakeld en moet worden ingeschakeld door een werkruimtebeheerder. Bekijk de beveiligingsoverwegingen voordat u deze functie inschakelt.

Ondersteunde resources voor OBO

Agents met OBO-verificatie hebben toegang tot de volgende Databricks-resources:

Databricks-resource	Compatibele clients
Vectorzoekindex	databricks_langchain.VectorSearchRetrieverTool, databricks_openai.VectorSearchRetrieverToolVectorSearchClient
Eindpunt voor modeluitvoering	databricks.sdk.WorkspaceClient
SQL Warehouse	databricks.sdk.WorkspaceClient
UC-verbindingen	databricks.sdk.WorkspaceClient
UC-tabellen en functies	databricks.sdk.WorkspaceClient (Voor toegang tot UC-tabellen moet u SQL-query's gebruiken met behulp van de SQL-instructieuitvoerings-API)
Genie Space	databricks.sdk.WorkspaceClient (aanbevolen), databricks_langchain.GenieAgentof databricks_ai_bridge.GenieAgent
Model Context Protocol (MCP)	databricks_mcp.DatabricksMCPClient

OBO-verificatie implementeren

Voer de volgende stappen uit om verificatie namens de gebruiker in te schakelen:

1. Werk SDK-aanroepen bij om op te geven dat resources namens de eindgebruiker worden geopend.
2. Werk agentcode bij om OBO-toegang binnen de predict functie te initialiseren, niet in __init__, omdat de gebruikersidentiteit alleen tijdens runtime bekend is.
3. Bij het vastleggen van de agent voor implementatie declareert u de Databricks REST API-bereiken die de agent nodig heeft.

De volgende codefragmenten laten zien hoe u namens de gebruiker toegang tot verschillende Databricks-resources configureert. Bij het initialiseren van hulpprogramma's kunt u machtigingsfouten probleemloos afhandelen door initialisatie in een try-except blok te verpakken.

Vector Zoekophaal Tool

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain import VectorSearchRetrieverTool

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy = ModelServingUserCredentials())

vector_search_tools = []
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  tool = VectorSearchRetrieverTool(
    index_name="<index_name>",
    description="...",
    tool_name="...",
    workspace_client=user_client # Specify the user authorized client
    )
    vector_search_tools.append(tool)
except Exception as e:
    _logger.debug("Skipping adding tool as user does not have permissions")

Vector Search client

from databricks.vector_search.client import VectorSearchClient
from databricks.vector_search.utils import CredentialStrategy

# Configure a VectorSearch Client to use on behalf of end
# user authentication
user_authenticated_vsc = VectorSearchClient(credential_strategy=CredentialStrategy.MODEL_SERVING_USER_CREDENTIALS)
# Exclude exception handling if the agent should fail when
# users lack access to all required Databricks resources
try:
  vs_index = user_authenticated_vsc.get_index(endpoint_name="endpoint_name", index_name="index_name")
  ...
except Exception as e:
  _logger.debug("Skipping Vector Index because user does not have permissions")

MCP

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_mcp import DatabricksMCPClient

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

mcp_client = DatabricksMCPClient(
    server_url="<mcp_server_url>",
    workspace_client=user_client, # Specify the user client here
  )

Eindpunt voor modeluitvoering

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  user_client.serving_endpoints.query("endpoint_name", input="")
except Exception as e:
  _logger.debug("Skipping Model Serving Endpoint due to no permissions")

UC-verbindingen

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod
from databricks_ai_bridge import ModelServingUserCredentials

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

user_client.serving_endpoints.http_request(
  conn="connection_name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra_header_key": "extra_header_value"},
)

Genie Spaces (WorkspaceClient)

from databricks_langchain.genie import GenieAgent
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials


# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())


genie_agent = GenieAgent(
    genie_space_id="space-id",
    genie_agent_name="Genie",
    description="This Genie space has access to sales data in Europe"
    client=user_client
)

# Use the Genie SDK methods available through WorkspaceClient
try:
    response = agent.invoke("Your query here")
except Exception as e:
    _logger.debug("Skipping Genie due to no permissions")

Genie Spaces (LangChain)

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain.genie import GenieAgent

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

genie_agent = GenieAgent(
    genie_space_id="<genie_space_id>",
    genie_agent_name="Genie",
    description="Genie_description",
    client=user_client, # Specify the user client here
  )

Initialiseer de agent in de voorspellingsfunctie

Omdat de identiteit van de gebruiker alleen bekend is tijdens de query, moet u toegang krijgen tot OBO-resources binnen predict of predict_streamniet in de methode van __init__ de agent. Dit zorgt ervoor dat resources worden geïsoleerd tussen aanroepen.

from mlflow.pyfunc import ResponsesAgent

class OBOResponsesAgent(ResponsesAgent):
  def initialize_agent():
    user_client = WorkspaceClient(
      credentials_strategy=ModelServingUserCredentials()
    )
    system_authorized_client = WorkspaceClient()
    ### Use the clients above to access resources with either system or user authentication

  def predict(
    self, request
  ) -> ResponsesAgentResponse:
    agent = initialize_agent() # Initialize the Agent in Predict

    agent.predict(request)
    ...

REST API-bereiken declareren bij het vastleggen van de agent

Wanneer u uw OBO-agent voor implementatie aanmeldt, moet u de Databricks REST API-bereiken vermelden die uw agent namens de gebruiker aanroept. Dit zorgt ervoor dat de agent het principe van minimale bevoegdheden volgt: tokens zijn beperkt tot alleen de API's die uw agent nodig heeft, waardoor de kans op onbevoegde acties of tokenmisbruik wordt beperkt.

Hieronder vindt u een lijst met scopes die vereist zijn voor toegang tot verschillende gebruikelijke typen Databricks-resources.

Hulpmiddeltype	Vereist API-bereik
Eindpunten voor modelbediening	serving.serving-endpoints
Vector Search-eindpunten	vectorsearch.vector-search-endpoints
Vector Search-indexen	vectorsearch.vector-search-indexes
SQL-magazijnen	sql.warehouses, sql.statement-execution
Genie-ruimten	dashboards.genie
UC-verbindingen	catalog.connections en serving.serving-endpoints
Apps van Databricks	apps.apps
MCP Genie-ruimten	mcp.genie
MCP UC-functies	mcp.functions
MCP Vector Search	mcp.vectorsearch
MCP DBSQL	mcp.sql, sql.warehousessql.statement-execution
EXTERNE MCP-functies	mcp.external

Als u verificatie namens de gebruiker wilt inschakelen, geeft u een MLflow AuthPolicy door aan log_model():

import mlflow
from mlflow.models.auth_policy import AuthPolicy, SystemAuthPolicy, UserAuthPolicy
from mlflow.models.resources import DatabricksServingEndpoint

# System policy: resources accessed with system credentials
system_policy = SystemAuthPolicy(
    resources=[DatabricksServingEndpoint(endpoint_name="my_endpoint")]
)

# User policy: API scopes for OBO access
user_policy = UserAuthPolicy(api_scopes=[
    "serving.serving-endpoints",
    "vectorsearch.vector-search-endpoints",
    "vectorsearch.vector-search-indexes"
])

# Log the agent with both policies
with mlflow.start_run():
    mlflow.pyfunc.log_model(
        name="agent",
        python_model="agent.py",
        auth_policy=AuthPolicy(
            system_auth_policy=system_policy,
            user_auth_policy=user_policy
        )
    )

OBO-verificatie voor OpenAI-clients

Voor agents die gebruikmaken van de OpenAI-client, gebruikt u de Databricks SDK om automatisch te verifiëren tijdens de implementatie. Databricks SDK heeft een wrapper voor het bouwen van de OpenAI-client met automatisch geconfigureerde verificatie, get_open_ai_client():

% pip install databricks-sdk[openai]

from databricks.sdk import WorkspaceClient
def openai_client(self):
  w = WorkspaceClient()
  return w.serving_endpoints.get_open_ai_client()

Geef vervolgens eindpunt Model Serving op als onderdeel van resources voor automatische authenticatie tijdens implementatie.

Beveiligingsoverwegingen voor OBO

Houd rekening met de volgende beveiligingsoverwegingen voordat u met agents verificatie namens gebruikers inschakelt.

Uitgebreide resourcetoegang: agents hebben namens gebruikers toegang tot gevoelige resources. Hoewel bereiken API's beperken, kunnen eindpunten meer acties toestaan dan uw agent expliciet aanvraagt. Het API-bereik verleent bijvoorbeeld serving.serving-endpoints een agentmachtiging voor het uitvoeren van een service-eindpunt namens de gebruiker. Het servereindpunt heeft echter toegang tot aanvullende API-bereiken die de oorspronkelijke agent niet mag gebruiken.

OBO-voorbeeldnotebooks

In het volgende notebook ziet u hoe u een agent maakt met Vector Search, waarbij autorisatie namens de gebruiker wordt gebruikt.

Namens gebruikersautorisatie met Vector Search

Notebook krijgen

In het volgende notebook ziet u hoe u een agent maakt die ondersteuning biedt voor SQL-uitvoering in een SQL Warehouse met behulp van autorisatie namens de gebruiker. Hierdoor kan de agent veilig Unity Catalog-functies aanroepen met behulp van gebruikersreferenties. Opmerking: dit is momenteel de aanbevolen manier om UC Functions uit te voeren met OBO omdat Serverless Spark Execution met OBO nog niet wordt ondersteund.

Namens gebruikersautorisatie bij SQL-uitvoering

Notebook krijgen

Handmatige verificatie

Met handmatige authenticatie kunt u expliciet inloggegevens opgeven tijdens de implementatie van de agent. Deze methode heeft de meeste flexibiliteit, maar vereist meer instellingen en doorlopend referentiebeheer. Gebruik deze methode wanneer:

• De afhankelijke resource biedt geen ondersteuning voor automatische verificatiepassthrough
• De agent moet andere referenties gebruiken dan die van de agent-deployer
• De agent heeft toegang tot externe resources of API's buiten Databricks
• De uitgerolde agent benadert het promptregister

Belangrijk

Als u omgevingsvariabelen voor beveiliging overschrijft, wordt automatische passthrough uitgeschakeld voor andere resources waarvan uw agent afhankelijk is.

OAuth-verificatie (aanbevolen)

OAuth is de aanbevolen methode voor handmatige verificatie omdat deze beveiligde verificatie op basis van tokens heeft voor service-principals met mogelijkheden voor automatisch vernieuwen van tokens:

1. Maak een service-principal en genereer OAuth-referenties.

2. Verleen de service-principal machtigingen voor elke Databricks-resource waar de agent toegang toe heeft bevoegdheden voor toegang tot Databricks-resources. Als u toegang wilt krijgen tot het promptregister, verleent CREATE FUNCTION, EXECUTEen MANAGE machtigingen voor het Unity Catalog-schema voor het opslaan van prompts.

3. Maak databricks-geheimen voor de OAuth-referenties.

4. Stel de OAuth-referenties in binnen de agentcode.

   import os
   
   # Configure OAuth authentication for Prompt Registry access
   # Replace with actual secret scope and key names
   secret_scope_name = "your-secret-scope"
   client_id_key = "oauth-client-id"
   client_secret_key = "oauth-client-secret"
   
   os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
   os.environ["DATABRICKS_CLIENT_ID"] = dbutils.secrets.get(scope=secret_scope_name, key=client_id_key)
   os.environ["DATABRICKS_CLIENT_SECRET"] = dbutils.secrets.get(scope=secret_scope_name, key=client_secret_key)
   

5. Gebruik de geheimen om verbinding te maken met de werkruimte:

   w = WorkspaceClient(
     host=os.environ["DATABRICKS_HOST"],
     client_id=os.environ["DATABRICKS_CLIENT_ID"],
     client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
   )
   

6. Bij het implementeren met agents.deploy(), neem de OAuth-referenties op als omgevingsvariabelen.

   agents.deploy(
       UC_MODEL_NAME,
       uc_registered_model_info.version,
       environment_vars={
           "DATABRICKS_HOST": "https://<your-workspace-url>",
           "DATABRICKS_CLIENT_ID": f"{{{{secrets/{secret_scope_name}/{client_id_key}}}}}",
           "DATABRICKS_CLIENT_SECRET": f"{{{{secrets/{secret_scope_name}/{client_secret_key}}}}}"
       },
   )
   

PAT-verificatie

Verificatie van persoonlijke toegangstokens (PAT) biedt een eenvoudigere configuratie voor ontwikkel- en testomgevingen, maar vereist meer handmatig referentiebeheer:

1. Haal een PAT op met behulp van een service-principal of persoonlijk account:

   Serviceprincipal (aanbevolen voor beveiliging):

   1. Maak een service-principal.
   2. Verleen de service-principal machtigingen voor elke Databricks-resource waar de agent toegang toe heeft bevoegdheden voor toegang tot Databricks-resources. Om toegang te krijgen tot het promptregister, verlenen CREATE FUNCTIONen EXECUTEMANAGE machtigingen voor het Unity Catalog-schema dat wordt gebruikt om prompts op te slaan.
   3. Maak een PAT voor de service-principal.

   Persoonlijk account:

   1. Maak een PAT voor een persoonlijk account.

2. Sla de PAT veilig op door een Databricks-geheim voor de PAT te maken.

3. PAT-verificatie configureren in de agentcode:

   import os
   
   # Configure PAT authentication for Prompt Registry access
   # Replace with your actual secret scope and key names
   secret_scope_name = "your-secret-scope"
   secret_key_name = "your-pat-key"
   
   os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
   os.environ["DATABRICKS_TOKEN"] = dbutils.secrets.get(scope=secret_scope_name, key=secret_key_name)
   
   # Validate configuration
   assert os.environ["DATABRICKS_HOST"], "DATABRICKS_HOST must be set"
   assert os.environ["DATABRICKS_TOKEN"], "DATABRICKS_TOKEN must be set"
   

4. Wanneer u de agent implementeert met behulp agents.deploy()van, neemt u de PAT op als een omgevingsvariabele:

   agents.deploy(
       UC_MODEL_NAME,
       uc_registered_model_info.version,
       environment_vars={
           "DATABRICKS_HOST": "https://<your-workspace-url>",
           "DATABRICKS_TOKEN": f"{{{{secrets/{secret_scope_name}/{secret_key_name}}}}}"
       },
   )