Ověřování pro agenty AI

Agenti umělé inteligence se často potřebují ověřit v jiných prostředcích, aby mohli provádět úlohy. Nasazený agent může například potřebovat přístup k indexu vektorového vyhledávání pro dotazování nestrukturovaných dat nebo registru výzvy k načtení dynamických výzev.

Tato stránka se zabývá metodami ověřování, které jsou k dispozici při vývoji a nasazování agentů pomocí architektury agentů Mosaic AI.

Metody ověřování

Následující tabulka porovnává dostupné metody ověřování. Můžete kombinovat a libovolně míchat různé z těchto přístupů:

Metoda	Description	Stav zabezpečení	Složitost nastavení
Průchozí ověřování	Agent běží s oprávněními uživatele, který ho nasadil. Databricks automaticky spravuje krátkodobé přihlašovací údaje pro deklarované prostředky.	Krátkodobé přihlašovací údaje, automatická obměna	Nízká – deklarujte závislosti v době protokolování.
Ověřování jménem uživatele (OBO)	Agent běží s oprávněními koncového uživatele provádějícího požadavek.	Používá přihlašovací údaje koncového uživatele s omezenými obory.	Střední – vyžaduje deklaraci oboru a inicializaci modulu runtime.
Ruční ověřování	Explicitní zadání přihlašovacích údajů pomocí proměnných prostředí	Dlouhodobé přihlašovací údaje vyžadují správu rotace.	Vysoká – vyžaduje ruční správu přihlašovacích údajů.

Ověřování u externích systémů a serverů MCP

Pokyny k ověřování externích rozhraní API a serverů MCP z vašeho agenta najdete v tématu Připojení nástrojů agenta AI k externím službám. Tyto prostředky lze rovněž dotazovat jménem uživatele nebo agenta, jak je popsáno v metodách ověřování.

Volba správné metody ověřování pro váš prostředek

Pomocí tohoto vývojového diagramu můžete pro každý prostředek zvolit správnou metodu ověřování. Metody můžete podle potřeby kombinovat a agent může pro každý prostředek v závislosti na případu použití použít jinou metodu.

Vyžaduje se řízení přístupu pro jednotlivé uživatele nebo auditování s atributy uživatele?
- Ano → Použít ověřování jménem uživatele
- Žádná → Pokračovat krokem 2
Podporují všechny prostředky automatické ověřování?
- Ano → Použít Automatické předávání ověření (doporučeno)
- Nepoužívat → ruční ověřování

Automatický průchod ověřením

Automatické předávání ověřování je nejjednodušší metoda pro přístup k prostředkům spravovaným službou Databricks. Stanovte závislosti zdrojů při zaznamenávání aktivit agenta a Databricks automaticky zřizuje, obměňuje a spravuje krátkodobé přihlašovací údaje během nasazení agenta.

Toto chování ověřování je podobné chování přihlášení jako vlastník u řídicích panelů Databricks. Podřízené prostředky, jako jsou tabulky katalogu Unity, jsou přístupné pomocí přihlašovacích údajů služebního účtu s minimálními oprávněními pouze k prostředkům, které agent potřebuje.

Jak funguje automatické předávání ověřování

Když je agent obsluhován za koncovým bodem s využitím automatického předávání ověřování, Databricks provede tyto kroky:

Ověření oprávnění: Databricks ověřuje, že tvůrce koncového bodu má přístup ke všem závislostem zadaným během protokolování agenta.
Vytváření a udělování oprávnění služebního účtu: Služební účet je vytvořen pro verzi modelu agenta a automaticky mu je udělen přístup k prostředkům agenta pro čtení.

Poznámka:

Objekt "service principal" generovaný systémem se nezobrazuje v seznamech API ani uživatelského rozhraní. Pokud je z koncového bodu odstraněna verze modelu agenta, bude odstraněn také principál služby.
Zřizování a rotace přihlašovacích údajů: Krátkodobé přihlašovací údaje (token OAuth M2M) pro principál služby jsou vloženy do koncového bodu, což agentovému kódu umožňuje přistupovat k prostředkům Databricks. Databricks také obměňuje přihlašovací údaje, což zajišťuje, že váš agent má nepřetržitý a zabezpečený přístup k závislým prostředkům.

Podporované zdroje pro automatický přenos ověřování

Následující tabulka uvádí prostředky Databricks, podporující automatické předávání ověřování, a oprávnění, která musí mít tvůrce koncového bodu při nasazování agenta.

Poznámka:

Prostředky katalogu Unity rovněž potřebují USE SCHEMA na nadřazeném schématu a USE CATALOG na nadřazeném katalogu.

Typ zdroje	Povolení	Minimální verze MLflow
SQL Warehouse	`Use Endpoint`	2.16.1 nebo novější
Koncový bod pro obsluhu modelu	`Can Query`	2.13.1 nebo novější
Funkce katalogu Unity	`EXECUTE`	2.16.1 nebo novější
Genie space	`Can Run`	2.17.1 nebo vyšší
Index vektorové vyhledávání	`Can Use`	2.13.1 nebo novější
Tabulka katalogu Unity	`SELECT`	2.18.0 nebo vyšší
Připojení katalogu Unity	`Use Connection`	2.17.1 nebo vyšší
Lakebase	`databricks_superuser`	3.3.2 nebo vyšší

Implementace automatického předávání ověřování

Pokud chcete povolit automatické přeposílání ověřování, zadejte závislé prostředky při logování agenta. Použijte parametr resources rozhraní log_model() API.

Poznámka:

Nezapomeňte také protokolovat všechny podřízené závislé prostředky. Pokud například zaznamenáte Genie Space, musíte také zaznamenat jeho tabulky, SQL sklady a funkce katalogu Unity Catalog.

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

Ověřování jménem uživatele

Důležité

Tato funkce je ve verzi Public Preview.

Ověřování jménem uživatele (OBO) umožňuje agentovi jednat jako uživatel Databricks, který spouští dotaz. To poskytuje:

Přístup jednotlivých uživatelů k citlivým datům
Jemně odstupňované ovládací prvky dat vynucované katalogem Unity
Tokeny zabezpečení jsou omezené ("downscoped") pouze na rozhraní API, která váš agent deklaruje, což snižuje riziko zneužití.

Požadavky

Ověřování na základě pověření uživatele vyžaduje MLflow 2.22.1 a vyšší.
Ověřování jménem uživatele je ve výchozím nastavení zakázané a musí ho povolit správce pracovního prostoru. Před povolením této funkce si projděte důležité informace o zabezpečení .

Podporované prostředky OBO

Agenti s ověřováním OBO mají přístup k následujícím prostředkům Databricks:

Prostředek Databricks	Kompatibilní klienti
Index vektorové vyhledávání	`databricks_langchain.VectorSearchRetrieverTool` `databricks_openai.VectorSearchRetrieverTool` `VectorSearchClient`
Koncový bod obsluhy modelu	`databricks.sdk.WorkspaceClient`
SQL Warehouse	`databricks.sdk.WorkspaceClient`
Spojení UC	`databricks.sdk.WorkspaceClient`
Tabulky a funkce UC	`databricks.sdk.WorkspaceClient` (Pokud chcete získat přístup k tabulkám UC, musíte použít dotazy SQL pomocí rozhraní API pro spouštění příkazů SQL).
Genie Space	`databricks.sdk.WorkspaceClient` (doporučeno), `databricks_langchain.GenieAgent`nebo `databricks_ai_bridge.GenieAgent`
Model Context Protocol (MCP)	`databricks_mcp.DatabricksMCPClient`

Implementace ověřování OBO

Pokud chcete povolit ověřování jménem uživatele, proveďte následující kroky:

Aktualizujte volání sady SDK a určete, že k prostředkům se přistupuje jménem koncového uživatele.
Aktualizace kódu agenta pro inicializaci přístupu OBO uvnitř predict funkce, ne v __init__, protože identita uživatele je známa pouze za běhu.
Při protokolování agenta pro nasazení deklarujte obory rozhraní REST API Databricks, které agent vyžaduje.

Následující fragmenty kódu ukazují, jak nakonfigurovat přístup uživatele jménem uživatele k různým prostředkům Databricks. Při inicializaci nástrojů zpracujte chyby oprávnění elegantně zabalením inicializace do try-except bloku.

Nástroj pro vyhledávání vektorů

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

Klient vektorové vyhledávání

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
  )

Koncový bod obsluhy modelu

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

Spojení UC

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
  )

Inicializujte agenta ve funkci předpovědi

Vzhledem k tomu, že identita uživatele je známa pouze v době dotazu, musíte přistupovat k prostředkům OBO uvnitř predict nebo predict_streamne v metodě agenta __init__ . Tím se zajistí izolace prostředků mezi vyvoláním.

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

Deklarace rozsahů rozhraní REST API při protokolování agenta

Při protokolování agenta OBO pro nasazení musíte uvést rozsahy rozhraní REST API Databricks, které agent volá jménem uživatele. Tím se zajistí, že se agent řídí principem nejnižších oprávnění: tokeny jsou omezené jenom na rozhraní API, která vyžaduje váš agent, což snižuje pravděpodobnost neoprávněné akce nebo zneužití tokenu.

Níže je seznam oborů potřebných pro přístup k několika běžným typům prostředků Databricks:

Typ zdroje	Požadovaný obor rozhraní API
Koncové body obsluhy modelů	`serving.serving-endpoints`
Koncové body vektorového vyhledávání	`vectorsearch.vector-search-endpoints`
Indexy vektorových vyhledávání	`vectorsearch.vector-search-indexes`
sklady SQL	`sql.warehouses`, `sql.statement-execution`
prostředí Genie	`dashboards.genie`
Připojení UC	`catalog.connections` a `serving.serving-endpoints`
Aplikace Databricks	`apps.apps`
McP Genie spaces	`mcp.genie`
Funkce MCP UC	`mcp.functions`
MCP Vector Search	`mcp.vectorsearch`
MCP DBSQL	`mcp.sql` `sql.warehouses` `sql.statement-execution`
Externí funkce MCP	`mcp.external`

Pokud chcete povolit ověřování jménem uživatele, předejte MLflow AuthPolicy do 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
        )
    )

Ověřování OBO pro klienty OpenAI

Pro agenty, kteří používají klienta OpenAI, použijte sadu Databricks SDK k automatickému ověření během nasazování. Sada Databricks SDK obsahuje obálku pro vytvoření klienta OpenAI s automaticky nakonfigurovaným ověřováním: 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()

Pak určete jako součást resources koncový bod pro obsluhu modelu, který se automaticky autorizuje v době nasazení.

Důležité informace o zabezpečení OBO

Než povolíte ověřování jménem uživatele pomocí agentů, zvažte následující aspekty zabezpečení.

Rozšířený přístup k prostředkům: Agenti mají přístup k citlivým prostředkům jménem uživatelů. Zatímco obory omezují rozhraní API, koncové body můžou umožňovat více akcí, než váš agent explicitně požaduje. Obor rozhraní API například serving.serving-endpoints uděluje agentům oprávnění ke spuštění koncového bodu obsluhy jménem uživatele. Koncový bod obsluhy ale má přístup k dalším oborům rozhraní API, které původní agent nemá oprávnění používat.

Ukázkové poznámkové bloky OBO

Následující poznámkový blok ukazuje, jak vytvořit agenta s vektorovým vyhledáváním pomocí autorizace jménem uživatele.

Autorizaci uživatele jménem uživatele s využitím vektorového vyhledávání

Pořiďte si notebook

Následující poznámkový blok ukazuje, jak vytvořit agenta, který podporuje spouštění SQL ve službě SQL Warehouse pomocí autorizace jménem uživatele. To umožňuje agentu bezpečně vyvolat funkce katalogu Unity pomocí uživatelských přihlašovacích údajů. Poznámka: V současné době se doporučuje spouštět funkce UC s OBO, protože bezserverové spouštění Sparku s OBO se zatím nepodporuje.

Zastupování uživatele při autorizaci pomocí SQL skriptů

Pořiďte si notebook

Ruční ověřování

Ruční ověřování umožňuje explicitně zadat přihlašovací údaje během nasazení agenta. Tato metoda má největší flexibilitu, ale vyžaduje větší nastavení a průběžnou správu přihlašovacích údajů. Tuto metodu použijte v těchto případech:

Závislý prostředek nepodporuje automatické předání ověření.
Agent musí používat jiné přihlašovací údaje, než jsou přihlašovací údaje nasazeného agenta.
Agent přistupuje k externím prostředkům nebo rozhraním API mimo Databricks.
Nainstalovaný agent přistupuje k prompt registru.

Důležité

Přepsání proměnných prostředí zabezpečení zakáže automatické předávání dalších prostředků, na které váš agent závisí.

Ověřování OAuth (doporučeno)

OAuth je doporučený postup ručního ověřování, protože má zabezpečené ověřování založené na tokenech pro služební identity s možností automatické obnovy tokenů.

Vytvořte instanční objekt a vygenerujte přihlašovací údaje OAuth.
Udělte principálovi služby oprávnění k jakémukoli prostředku Databricks, ke kterému má agent přístup, oprávnění pro přístup k prostředkům Databricks. Pokud chcete získat přístup k registru výzev, udělte oprávnění CREATE FUNCTION, EXECUTE, a MANAGE ke schématu katalogu Unity pro ukládání výzev.
Vytvořte tajné kódy databricks pro přihlašovací údaje OAuth.

Nakonfigurujte přihlašovací údaje OAuth v kódu agenta:

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)

Pomocí tajných kódů se připojte k pracovnímu prostoru:

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

Při nasazování pomocí agents.deploy()parametru zahrňte přihlašovací údaje OAuth jako proměnné prostředí:

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

Ověřování PAT

Ověřování PAT (Personal Access Token) poskytuje jednodušší nastavení pro vývojová a testovací prostředí, ačkoli vyžaduje více ruční správy přihlašovacích údajů:

Získejte osobní přístupový token pomocí služebního principála nebo osobního účtu:

Služební objekt (doporučeno pro zabezpečení):
1. Vytvořte instanční objekt.
2. Udělte principálovi služby oprávnění k jakémukoli prostředku Databricks, ke kterému má agent přístup, oprávnění pro přístup k prostředkům Databricks. Pokud chcete získat přístup k registru výzvy, udělte oprávnění CREATE FUNCTION, EXECUTE, a MANAGE ke schématu Unity Catalog, které se používá pro ukládání výzev.
3. Vytvořte pat pro instanční objekt.
Osobní účet:
1. Vytvořte PAT pro osobní účet.
Bezpečně uložte PAT vytvořením tajemství Databricks pro PAT.

Konfigurace ověřování PAT v kódu agenta:

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"

Při nasazování agenta pomocí agents.deploy() zahrňte PAT jako proměnnou prostředí:

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-09-22