Autentisering för AI-agenter

AI-agenter behöver ofta autentisera till andra resurser för att slutföra uppgifter. En utplacerad agent kan till exempel behöva komma åt ett vektorsökningsindex för att utföra sökningar i ostrukturerade data eller Prompt Registry för att ladda dynamiska frågor.

Den här sidan beskriver de autentiseringsmetoder som är tillgängliga när du utvecklar och distribuerar agenter med hjälp av Mosaic AI Agent Framework.

Autentiseringsmetoder

I följande tabell jämförs tillgängliga autentiseringsmetoder. Du kan blanda och matcha någon av dessa metoder:

Autentisera till externa system och MCP-servrar

Vägledning om hur du autentiserar till externa API:er och MCP-servrar från din agent finns i Ansluta AI-agentverktyg till externa tjänster. Dessa resurser kan också frågas för agentens eller användarens räkning, enligt beskrivningen i Autentiseringsmetoder.

Välj rätt autentiseringsmetod för resursen

Använd det här flödesschemat för att välja rätt autentiseringsmetod för varje resurs. Du kan kombinera metoder efter behov och en agent kan använda en annan metod för varje resurs beroende på dess användningsfall.

1. Krävs användaråtkomstkontroll eller användarattribuerad revision?

   • Ja → Använd autentisering för användarens räkning
   • Ingen → Fortsätt till steg 2

2. Stöder alla resurser automatisk autentisering?

   • Ja → Använd automatisk autentiseringsgenomströmning (rekommenderas)
   • Ingen → Använd manuell autentisering

Automatisk autentiseringsöverbryggning

Automatisk autentiseringsgenomströmning är den enklaste metoden för att komma åt Databricks-hanterade resurser. Deklarera resursberoenden när du loggar agenten och Databricks etablerar, roterar och hanterar kortlivade autentiseringsuppgifter när agenten distribueras.

Det här autentiseringsbeteendet liknar beteendet "Kör som ägare" för Databricks-instrumentpaneler. Nedströmsresurser som Unity Catalog-tabeller används med autentiseringsuppgifterna för en tjänsthuvudman med minst behörighet till endast de resurser agenten behöver.

Så här fungerar automatisk autentiseringspassering

När en agent hanteras bakom en slutpunkt med automatisk autentiseringsgenomströmning utför Databricks följande steg:

1. Behörighetsverifiering: Databricks verifierar att slutpunktens skapare kan komma åt alla beroenden som anges under agentloggning.

2. Skapande och beviljande av tjänstens huvudnamn: Ett huvudnamn för tjänsten skapas för agentmodellversionen och beviljas automatiskt läsbehörighet till agentresurser.

   Anmärkning

   Det systemgenererade tjänstens huvudnamn visas inte i API- eller användargränssnittslistor. Om agentmodellversionen tas bort från slutpunkten, tas även tjänstens huvudprincip bort.

3. Etablering och rotation av autentiseringsuppgifter: Kortlivade autentiseringsuppgifter (en M2M OAuth-token) för tjänstens huvudnamn matas in i slutpunkten, vilket ger agentkoden åtkomst till Databricks-resurser. Databricks roterar också autentiseringsuppgifterna, vilket säkerställer att din agent har fortsatt säker åtkomst till beroende resurser.

Stödda resurser för automatisk genomsändning vid autentisering

I följande tabell visas de Databricks-resurser som stöder automatisk autentiseringsgenomströmning och de behörigheter som slutpunktens skapare måste ha när agenten distribueras.

Implementera automatisk autentiseringspassering

För att aktivera automatisk vidarebefordran för autentisering anger du beroende resurser när du loggar agenten. Använd parametern resources för API:et log_model() :

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"),
    ]
  )

Autentisering på uppdrag av användaren

Med OBO-autentisering (å användarens vägnar) kan en agent fungera som den Databricks-användare som kör frågan. Detta ger:

• Åtkomst per användare till känsliga data
• Detaljerade datakontroller som tillämpas av Unity Catalog
• Säkerhetstoken begränsas ("downscoped") till endast de API:er som din agent deklarerar, vilket minskar risken för missbruk

Kravspecifikation

• För användarautentisering krävs MLflow 2.22.1 och senare.
• Autentisering för användaren är inaktiverad som standard och måste aktiveras av en arbetsyteadministratör. Granska säkerhetsövervägandena innan du aktiverar den här funktionen.

Resurser som stöds av OBO

Agenter med OBO-autentisering kan komma åt följande Databricks-resurser:

Implementera OBO-autentisering

Utför följande steg för att aktivera autentisering för användarens räkning:

1. Uppdatera SDK-anrop för att ange att resurser ska nås för slutanvändarens räkning.
2. Uppdatera agentkoden för att initiera OBO-åtkomst i predict funktionen, inte i __init__, eftersom användaridentiteten bara är känd vid körning.
3. När du loggar agenten för distribution deklarerar du de Databricks REST API-omfång som agenten kräver.

Följande kodfragment visar hur du konfigurerar å användarens vägnar åtkomst till olika Databricks-resurser. När du initierar verktyg hanterar du behörighetsfel på ett korrekt sätt genom att omsluta initieringen i ett try-except block.

Vektorsökningsåterhämtningsverktyg

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

Vektorsökningsklient

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
  )

Modellserverendpunkt

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-anslutningar

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
  )

Initiera agenten i förutsägelsefunktionen

Eftersom användarens identitet bara är känd vid frågetillfället måste du komma åt OBO-resurser i predict eller predict_stream, inte i agentens __init__ -metod. Detta säkerställer att resurser isoleras mellan anrop.

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

Deklarera REST API-omfång när agenten loggas

När du loggar OBO-agenten för distribution måste du ange de Databricks REST API-omfång som agenten anropar för användarens räkning. Detta säkerställer att agenten följer principen om minsta behörighet: token är begränsade till bara de API:er som din agent kräver, vilket minskar risken för obehöriga åtgärder eller tokenmissbruk.

Nedan visas en lista över omfång som krävs för att få åtkomst till flera vanliga typer av Databricks-resurser:

Om du vill aktivera autentisering för användarens räkning skickar du ett MLflow AuthPolicy till 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-autentisering för OpenAI-klienter

För agenter som använder OpenAI-klienten använder du Databricks SDK för att autentisera automatiskt under distributionen. Databricks SDK har en omslutning för att konstruera OpenAI-klienten med automatiskt konfigurerad autentisering: 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()

Ange sedan slutpunkten Modellserver som en del av resources för att autentisera automatiskt vid distributionstillfället.

OBO-säkerhetsöverväganden

Tänk på följande säkerhetsöverväganden innan du aktiverar autentisering för användarens räkning med agenter.

Utökad resursåtkomst: Agenter kan komma åt känsliga resurser för användarnas räkning. Omfång begränsar API:er, men slutpunkter kan tillåta fler åtgärder än vad agenten uttryckligen begär. API-omfånget serving.serving-endpoints ger till exempel en agent behörighet att köra en serverslutpunkt för användarens räkning. Serverdelsslutpunkten kan dock komma åt ytterligare API-omfång som den ursprungliga agenten inte har behörighet att använda.

OBO-exempelanteckningsböcker

Följande anteckningsbok visar hur du skapar en agent med Vector Search med användarbehörighet.

För användarauktorisering med vektorsökning

Hämta anteckningsbok

Följande anteckningsbok visar hur du skapar en agent som stöder SQL-körning på ett SQL Warehouse med hjälp av auktorisering å en användares vägnar. Detta gör det möjligt för agenten att på ett säkert sätt anropa Unity Catalog-funktioner med hjälp av användarautentiseringsuppgifter. Obs! Det här är för närvarande det rekommenderade sättet att köra UC Functions med OBO eftersom Serverlös Spark-körning med OBO ännu inte stöds.

På uppdrag av användarauktorisering med SQL-exekvering

Hämta anteckningsbok

Manuell autentisering

Manuell autentisering gör det möjligt att uttryckligen ange autentiseringsuppgifter under agentdistributionen. Den här metoden har störst flexibilitet men kräver mer konfiguration och kontinuerlig hantering av autentiseringsuppgifter. Använd den här metoden när:

• Den beroende resursen stöder inte automatisk autentiseringsgenomströmning
• Agenten måste använda andra autentiseringsuppgifter än agentdistribuerarens autentiseringsuppgifter
• Agenten får åtkomst till externa resurser eller API:er utanför Databricks
• Den distribuerade agenten får åtkomst till promptregistret

OAuth-autentisering (rekommenderas)

OAuth är den rekommenderade metoden för manuell autentisering eftersom den har säker, tokenbaserad autentisering för tjänstens huvudnamn med funktioner för automatisk tokenuppdatering:

1. Skapa ett huvudnamn för tjänsten och generera OAuth-autentiseringsuppgifter.

2. Ge tjänsthuvudmannen behörighet till alla Databricks-resurser som agenten har tillgång till behörighet att få åtkomst till Databricks-resurser. 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.

3. Skapa databricks-hemligheter för OAuth-autentiseringsuppgifterna.

4. Konfigurera OAuth-autentiseringsuppgifterna i agentkoden:

   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. Använd hemligheterna för att ansluta till arbetsytan:

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

6. När du distribuerar med agents.deploy() ska du inkludera OAuth-autentiseringsuppgifterna som miljövariabler.

   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-autentisering

Pat-autentisering (Personlig åtkomsttoken) ger en enklare konfiguration för utvecklings- och testmiljöer, även om det kräver mer manuell hantering av autentiseringsuppgifter:

1. Skaffa en PAT med ett huvudnamn för tjänsten eller ett personligt konto:

   Tjänstens huvudnamn (rekommenderas för säkerhet):

   1. Skapa ett huvudnamn för tjänsten.
   2. Ge tjänsthuvudmannen behörighet till alla Databricks-resurser som agenten har tillgång till behörighet att få åtkomst till Databricks-resurser. Om du vill komma åt promptregistret bevilja CREATE FUNCTION, EXECUTE, och MANAGE behörigheter för Unity Catalog-schemat som används för att lagra uppmaningar.
   3. Skapa en PAT för tjänstens huvudnamn.

   Personligt konto:

   1. Skapa en PAT för ett personligt konto.

2. Lagra PAT säkert genom att skapa en Databricks-hemlighet för PAT.

3. Konfigurera PAT-autentisering i agentkoden:

   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. När du distribuerar agenten med ska agents.deploy()du inkludera PAT som en miljövariabel:

   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}}}}}"
       },
   )