メインコンテンツまでスキップ

ユーザー代理承認を使用してエージェントをデプロイする

備考

プレビュー

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

ユーザー代理 (OBO) 承認により、エージェントはクエリを実行する Databricks ユーザーとして動作できます。これにより、次のことが提供されます。

  • 機密データへのユーザーごとのアクセス
  • Unity Catalog によって適用されるきめ細かなデータ制御
  • エージェントが宣言した APIs のみに制限 (「ダウンスコープ」) され、悪用のリスクが軽減されるトークン

必要条件​

ヒント

Databricks では、エージェントを開発するときに、最新バージョンの MLflow Python クライアントをインストールすることをお勧めします。

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

サポートされているリソース​

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

ユーザー代理認証の有効化​

エージェント コードでは、使い慣れた Databricks SDK とツール (ベクトル検索インデックスなど) を引き続き使用できます。OBO 認証を有効にするには:

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

完全なチュートリアルについては、 エンドツーエンドの例を参照してください。

SDK の構成​

次のスニペットは、さまざまな Databricks リソースへのユーザーに代わってアクセスを構成する方法を示しています。

ツールを初期化するときは、権限エラーを適切に処理します。初期化を try-except ブロックでラップして、ユーザーがアクセスできない場合でもエージェントが応答できるようにします。エラーを処理しない場合、必要なリソースが欠落しているときにエージェントは失敗します。

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 authorization
user_client = WorkspaceClient(credentials_strategy = ModelServingUserCredentials())

vector_search_tools = []
# Exclude exception handling if you want the agent to 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")

predict関数でエージェントを初期化します​

ユーザー代理認証は、 ResponsesAgent インターフェイスと互換性があります。

ユーザーの 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 authorization

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

    agent.predict(request)
    ...

エージェントのログ記録時に REST API スコープを宣言する​

デプロイのために OBO エージェントをログに記録する場合は、エージェントがユーザーに代わって呼び出す Databricks REST API スコープを一覧表示する必要があります。これにより、ユーザートークンは、エージェントが実際に必要とする APIs のみに制限されます。

これにより、エージェントは最小権限の原則に従うことができます: トークン エージェントが必要とする APIs のみに制限され、不正なアクションやトークンの悪用の可能性が減ります。

いくつかの一般的な種類の Databricks リソースにアクセスするために必要なスコープの一覧を次に示します。

リソースタイプ

必要な API スコープ

モデルサービングエンドポイント

serving.serving-endpoints

ベクトル検索エンドポイント

vectorsearch.vector-search-endpoints

ベクトル検索インデックス

vectorsearch.vector-search-indexes

SQLウェアハウス

sql.warehouses

UC 接続

catalog.connections そして serving.serving-endpoints

MCP Genie spaces

mcp.genie

MCP UC 関数

mcp.functions

MCP ベクトル検索

mcp.vectorsearch

MCPの外部機能

mcp.external

ユーザーに代わって承認を有効にするには、次の例に示すように、MLflow AuthPolicyを log_model()に渡します。

MLflow AuthPolicy には、次の 2 つのコンポーネントがあります。

  • system_auth_policy: システム認証でアクセスするリソースを指定します。システム認証を使用する 共有リソース クエリなど モデルサービング エンドポイント、ユーザーごとのリソースまたは APIsにアクセスするためのユーザー代理承認と組み合わせて使用します。
  • user_auth_policy: エージェントがユーザーに代わって承認するために必要な API スコープを指定します。これらのスコープは、エージェントがエンドユーザーに代わって実行できる操作を決定します。
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
        )
    )

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

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

  • 拡張されたリソースアクセス: エージェントは、ユーザーに代わって機密性の高いリソースにアクセスできます。 スコープは APIsを制限しますが、エンドポイントでは、エージェントが明示的に要求するよりも多くのアクションを許可する場合があります。

    たとえば、 serving.serving-endpoints API スコープは、ユーザーに代わってサービングエンドポイントを実行する権限をエージェントに付与します。ただし、サービスエンドポイント自体は、元のエージェントが使用を許可されていない追加の API スコープにアクセスできる場合があります。

ノートブックの例​

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

ベクトル検索によるユーザー認証の代理

Open notebook in new tab
に最終更新