AIエージェントの認証（モデルサービング）

備考

新しいユースケースの場合、 Databricks 、エージェント コード、サーバー構成、展開ワークフローを完全に制御するために、 Databricks Appsにエージェントを展開することをお勧めします。 「 AIエージェントを作成してDatabricks Appsにデプロイする」を参照してください。

AI エージェントは、タスクを完了するために他のリソースに対して認証する必要があることがよくあります。たとえば、デプロイされたエージェントは、非構造化データをクエリするためのクエリ検索インデックスにアクセスしたり、動的プロンプトを読み込むためにプロンプト レジストリにアクセスしたりする必要がある場合があります。

このページでは、エージェント フレームワークを使用してエージェントを開発および展開するときに使用できる認証方法について説明します。

認証方法

次の表は、利用可能な認証方法を比較したものです。以下のアプローチを組み合わせて使用できます。

手法	説明	セキュリティ体制	セットアップの複雑さ
自動認証パススルー	エージェントはそれを展開したユーザーの権限で実行されます Databricksは宣言されたリソースの短命な資格情報を自動的に管理します	有効期間の短い認証情報、自動ローテーション	低 - ログ時に依存関係を宣言する
ユーザー代理認証（OBO）	エージェントは、リクエストを行うエンドユーザーの権限で実行されます。	制限されたスコープでエンドユーザーの資格情報を使用する	中 - スコープ宣言とランタイム初期化が必要
手動認証	環境変数を使用して資格情報を明示的に提供する	長期間有効な認証情報にはローテーション管理が必要	高 - 手動の認証情報管理が必要

リソースに適した認証方法を選択してください

このフローチャートを使用して、各リソースに適切な認証方法を選択します。必要に応じてメソッドを組み合わせることができ、エージェントはユースケースに応じて各リソースに異なるメソッドを使用できます。

1. ユーザーごとのアクセス制御またはユーザー属性の監査は必要ですか?

   • はい →ユーザー代理認証を使用する
   • いいえ → ステップ 2 に進みます

2. すべてのリソースは自動認証をサポートしていますか?

   • はい →自動認証パススルーを使用する（推奨）
   • いいえ →手動認証を使用する

Databricks MCP サーバーへの認証

Databricks MCP サーバーに認証するには、ログ記録時にエージェントに必要なすべてのリソースを指定します。

たとえば、エージェントが以下にリストされている MCP サーバー URL を使用している場合、 prod.customer_supportスキーマとprod.billingスキーマですべてのトラフィック検索インデックスを指定する必要があります。 prod.billingですべてのUnity Catalog関数を指定する必要があります。

• https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_support
• https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billing
• https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

管理対象 MCP サーバーのすべての依存リソースを識別するプロセスを簡素化するには、 databricks-mcp PyPI パッケージdatabricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>)を使用して、管理対象 MCP サーバーに必要なリソースを取得します。

エージェントがDatabricks アプリでホストされているカスタム MCP サーバーをクエリする場合は、モデルをログに記録するときにサーバーをリソースとして明示的に含めることで承認を構成できます。

自動認証パススルー

自動認証パススルーは、Databricks が管理するリソースにアクセスする最も簡単な方法です。エージェントのログ記録時にリソースの依存関係を宣言すると、エージェントのデプロイ時に Databricks によって有効期間の短い資格情報が自動的にプロビジョニング、ローテーション、管理されます。

この認証動作は、Databricks ダッシュボードの「所有者として実行」動作に似ています。Unity Catalogテーブルなどのダウンストリーム リソースには、エージェントが必要とするリソースのみへの最小限の特権アクセスを持つサービスプリンシパルの資格情報を使用してアクセスされます。

自動認証パススルーの仕組み

自動認証パススルーを使用してエンドポイントの背後でエージェントが提供される場合、 Databricks次の手順を実行します。

1. 権限の検証 : Databricks は、エンドポイント作成者がエージェントのログ記録中に指定されたすべての依存関係にアクセスできることを確認します。

2. サービスプリンシパルの作成と権限付与 : エージェント モデル バージョンに対してサービスプリンシパルが作成され、エージェント リソースへの読み取りアクセスが自動的に付与されます。

注記

システム生成のサービスプリンシパルは、 APIまたは UI リストには表示されません。 エージェント モデルのバージョンがエンドポイントから削除されると、サービスプリンシパルも削除されます。

3. 資格情報のプロビジョニングとローテーション : サービス プリンシパルの有効期間の短い資格情報 ( M2M OAuth VPN ) がエンドポイントに挿入され、エージェント コードがDatabricksリソースにアクセスできるようになります。 Databricks は資格情報もローテーションし、エージェントが依存リソースに安全にアクセスし続けることを保証します。

自動認証パススルーでサポートされているリソース

次の表は、自動認証パススルーをサポートする Databricks リソースと、エージェントを展開するときにエンドポイント作成者が持つ必要があるアクセス許可を示しています。

注記

Unity Catalogリソースでは、親スキーマにUSE SCHEMA 、親カタログにUSE CATALOGも必要です。

リソースタイプ	権限	MLflowの最小バージョン
SQLウェアハウス	Use Endpoint	2.16.1以上
モデルサービングエンドポイント	Can Query	2.13.1以上
Unity Catalog 関数	EXECUTE	2.16.1以上
Genieスペース	Can Run	2.17.1以上
ベクトル検索インデックス	Can Use	2.13.1以上
Unity Catalogテーブル	SELECT	2.18.0以上
Unity Catalog接続	Use Connection	2.17.1以上
Lakebase	databricks_superuser	3.3.2またはそれ以上

自動認証パススルーを実装する

自動認証パススルーを有効にするには、エージェントをログに記録するときに依存リソースを指定します。log_model() APIのresources問題を使用します。

注記

下流の依存リソースもすべてログに記録することを忘れないでください。たとえば、 Genie Space をログに記録する場合は、そのテーブル、 SQLウェアハウス、およびUnity Catalog関数もログに記録する必要があります。

Python

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

ユーザー代理認証

備考

プレビュー

この機能は パブリック プレビュー段階です。

ユーザー代理 (OBO) 認証を使用すると、エージェントはクエリを実行する Databricks ユーザーとして機能できます。これにより、次のことが実現されます。

• 機密データへのユーザーごとのアクセス
• Unity Catalog によって強制されるきめ細かなデータ制御
• セキュリティ トークン は、エージェントが宣言するAPIsのみに制限（「ダウンスコープ」）されるため、誤用リスクが軽減されます。

要件

• ユーザー代理認証には MLflow 2.22.1 以上が必要です。
• ユーザー代理認証はデフォルトで無効になっており、ワークスペース管理者が有効にする必要があります。この機能を有効にする前に、セキュリティに関する考慮事項を確認してください。

OBOがサポートするリソース

OBO 認証を持つエージェントは、次の Databricks リソースにアクセスできます。

Databricksブリック リソース	互換性のあるクライアント
ベクトル検索インデックス	databricks_langchain.VectorSearchRetrieverTool、databricks_openai.VectorSearchRetrieverTool、 VectorSearchClient
モデルサービングエンドポイント	databricks.sdk.WorkspaceClient
SQLウェアハウス	databricks.sdk.WorkspaceClient
UCコネクション	databricks.sdk.WorkspaceClient
UC テーブルと関数	databricks.sdk.WorkspaceClient (UC テーブルにアクセスするには、 SQL ステートメント実行 APIを使用した SQL クエリを使用する必要があります)
Genieスペース	databricks.sdk.WorkspaceClient (推奨)、 databricks_langchain.GenieAgent 、または databricks_ai_bridge.GenieAgent
モデルコンテキストプロトコル（MCP）	databricks_mcp.DatabricksMCPClient

OBO認証を実装する

ユーザーの代理認証を有効にするには、次のステップを完了します。

1. SDK 呼び出しを更新して、エンド ユーザーに代わってリソースにアクセスするように指定します。
2. ユーザー ID は でのみ認識されるため、エージェント コードを更新して、 __init__ではなくpredict関数内で OBO アクセスを初期化します。
3. エージェントを展開用にログに記録するときに、エージェントに必要な Databricks REST API スコープを宣言します。

次のスニペットは、さまざまな Databricks リソースへのユーザー代理アクセスを構成する方法を示しています。ツールを初期化するときは、初期化をtry-exceptブロックでラップして、権限エラーを適切に処理します。

Vector Search Retriever Tool

Python

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

Python

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

Python

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
  )

Model Serving Endpoint

Python

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 Connections

Python

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)

Python

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)

Python

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
  )

予測関数でエージェントを初期化する

ユーザーの ID はクエリ時にのみ判明するため、エージェントの__init__メソッドではなく、 predictまたはpredict_stream内の OBO リソースにアクセスする必要があります。これにより、呼び出し間でリソースが分離されることが保証されます。

Python

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スコープを宣言する

展開のために OBO エージェントをログに記録する場合、エージェントがユーザーに代わって呼び出す Databricks REST API スコープを一覧表示する必要があります。これにより、エージェントは最小権限の原則に従うことが保証されます。 はエージェントに必要なAPIsのみに制限されるため、不正なアクションや 誤用の可能性が軽減されます。

以下は、いくつかの一般的なタイプの Databricks リソースにアクセスするために必要なスコープのリストです。

リソースタイプ	必要なAPIスコープ
モデルサービングエンドポイント	serving.serving-endpoints
ベクトル検索エンドポイント	vectorsearch.vector-search-endpoints
人気検索インデックス	vectorsearch.vector-search-indexes
SQLウェアハウス	sql.warehouses, sql.statement-execution
Genieスペース	dashboards.genie
UC接続	catalog.connections そして serving.serving-endpoints
Databricks Apps	apps.apps
MCP Genie spaces	genie
MCP UC機能	unity-catalog
MCP サーチ	vector-search
MCP DBSQL	sql
MCP外部関数	unity-catalog

ユーザー代理認証を有効にするには、MLflow AuthPolicyをlog_model()に渡します。

Python

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

OpenAIクライアントのOBO認証

OpenAI クライアントを使用するエージェントの場合は、Databricks SDK を使用して、デプロイ中に自動的に認証します。Databricks SDK には、認証が自動的に構成された OpenAI クライアントを構築するためのラッパーがありますget_open_ai_client() )。

Python

% pip install databricks-sdk[openai]

Python

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

次に、デプロイ時に自動的に認証されるように、 resourcesでモデルビングサー エンドポイントを指定します。

OBOのセキュリティに関する考慮事項

エージェントによるユーザー代理認証を有効にする前に、次のセキュリティ上の考慮事項を考慮してください。

リソース アクセスの拡張 : エージェントはユーザーに代わって機密リソースにアクセスできます。 スコープはAPIsを制限しますが、エンドポイントはエージェントが明示的に要求するよりも多くのアクションを許可する場合があります。 たとえば、 serving.serving-endpoints API スコープは、ユーザーに代わってサービス エンドポイントを実行する権限をエージェントに付与します。ただし、サービス エンドポイントは、元のエージェントが使用を許可されていない追加の API スコープにアクセスできます。

OBOサンプルノートブック

次のノートブックでは、ユーザーの代理認証を使用して、追跡検索でエージェントを作成する方法を示しています。

ユーザー認証に代わって「一斉検索」

Open notebook in new tab

次のノートブックでは、ユーザーの代理承認を使用してSQLウェアハウスでのSQL実行をサポートするエージェントを作成する方法を示しています。 これにより、エージェントはユーザー資格情報を使用してUnity Catalog機能を安全に呼び出すことができます。

注記

OBO を使用したサーバーレスSpark実行はまだサポートされていないため、現在、OBO を使用して UC 関数を実行する場合はこれが推奨される方法です。

SQL実行によるユーザー認証の代理実行

Open notebook in new tab

手動認証

手動認証では、エージェントの展開時に資格情報を明示的に指定できます。この方法は最も柔軟性が高いですが、より多くのセットアップと継続的な資格情報の管理が必要です。次の場合にこの方法を使用します。

• 依存リソースは自動認証パススルーをサポートしていません
• エージェントはエージェントデプロイヤーの資格情報以外の資格情報を使用する必要があります
• エージェントがDatabricksの外部の外部リソースまたはAPIsにアクセスする
• 展開されたエージェントはプロンプトレジストリにアクセスします

重要

セキュリティ環境変数を上書きすると、エージェントが依存する他のリソースへの自動パススルーが無効になります。

OAuth認証（推奨）

OAuth 、自動セキュリティ更新機能を備えたサービスプリンシパルの安全なウォークベースの認証を備えているため、手動認証の推奨アプローチです。

1. サービスプリンシパルを作成し、 OAuth資格情報を生成します。

2. エージェントがDatabricksリソースにアクセスする権限を持っているすべてのDatabricksリソースに、サービス プリンシパル アクセス許可を付与します。 プロンプト レジストリにアクセスするには、プロンプトを保存するためのUnity Catalogスキーマに対するCREATE FUNCTION 、 EXECUTE 、およびMANAGE権限を付与します。

3. OAuth 資格情報用のDatabricks シークレットを作成します。

4. エージェント コードで OAuth 資格情報を設定します。

   Python

   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. シークレットを使用してワークスペースに接続します。

   Python

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

6. agents.deploy()を使用してデプロイする場合は、OAuth 資格情報を環境変数として含めます。

   Python

   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認証

Personal ACCESS (PAT) 認証は、より手動の資格情報管理を必要としますが、開発およびテスト環境のセットアップをより簡単にします。

1. サービスプリンシパルまたは個人アカウントを使用して PAT を取得します。

   サービスシプリンパル (セキュリティのために推奨):

   1. サービスプリンシパルを作成します。
   2. エージェントがDatabricksリソースにアクセスする権限を持っているすべてのDatabricksリソースに、サービスプリンシパルのアクセス許可を付与します。 プロンプト レジストリにアクセスするには、プロンプトの保存に使用される Unity Catalog スキーマに対するCREATE FUNCTION 、 EXECUTE 、およびMANAGE権限を付与します。
   3. サービスプリンシパルの PAT を作成します。

   個人アカウント:

   1. 個人アカウント用の PAT を作成します。

2. PAT のDatabricks シークレットを作成して、PAT を安全に保存します。

3. エージェント コードで PAT 認証を構成します。

   Python

   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. agents.deploy()を使用してエージェントをデプロイする場合は、PAT を環境変数として含めます。

   Python

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