AI エージェントの認証

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

このページでは、Mosaic AI Agent Framework を使用してエージェントを開発およびデプロイするときに使用できる認証方法について説明します。

認証方法

次の表は、使用可能な認証方法を比較したものです。これらのアプローチのいずれかを組み合わせて組み合わせることができます。

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

リソースに適した認証方法を選択する

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

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

   • はい → ユーザー代理認証を使用する
   • →なし ステップ 2 に進む

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

   • はい → 自動認証パススルー を使用する (推奨)
   • 手動認証を使用する→なし

自動認証パススルー

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

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

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

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

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

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

注記

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

3. 資格情報プロビジョニングとローテーション : サービスプリンシパルの有効期間の短い資格情報 ( M2M OAuth トークン) がエンドポイントに挿入され、エージェント コードが 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 以降

自動認証パススルーの実装

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

Python

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

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

ユーザー代理認証

備考

プレビュー

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

ユーザー代理 (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 テーブルと関数	直接サポートされていません。構造化データへのアクセスには、OBOでGenieを使用します。
Genieスペース	databricks_langchain.GenieAgent, databricks_openai.GenieAgent
モデル コンテキスト プロトコル (MCP)	databricks_mcp.DatabricksMCPClient

OBO 認証の実装

ユーザー代理認証を有効にするには、以下のステップを実行します。

1. SDK 呼び出しを更新して、エンド ユーザーに代わってリソースにアクセスするように指定します。
2. エージェントコードを更新して、__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

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
  )

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

ユーザーの 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 Space	dashboards.genie
UC 接続	catalog.connections そして serving.serving-endpoints
Databricks Apps	apps.apps
MCP Genie spaces	mcp.genie
MCP UC 関数	mcp.functions
MCP ベクトル検索	mcp.vectorsearch
MCPの外部機能	mcp.external

ユーザーに代わって認証を有効にするには、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

手動認証

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

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

important

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

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

個人アクセストークン (PAT) 認証は、開発環境とテスト環境のセットアップをよりシンプルにしますが、より手動の資格情報管理が必要です。

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

   サービスプリンシパル (recommended for security):

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