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

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

備考

ベータ版

この機能は ベータ版です。

警告

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

ユーザー代理認証では、 Mosaic AI モデルサービングを介してデプロイされたエージェントは、エージェント Databricks クエリを実行した Databricks エンドユーザーのIDを使用してリソースにアクセスできます。 これにより、ユーザーごとに機密情報にアクセスできるようになり、Unity Catalog でのデータ アクセス制御がきめ細かく実施されます。

ユーザー代理認証は、ダウンスコープによって受信ユーザートークンをさらに制限し、エージェントコードに公開されるトークンがエージェント作成者によって定義された特定の API のみにアクセスするように制限されるようにします。 これにより、不正なアクションを防ぎ、トークンの誤用のリスクを減らすことで、セキュリティが向上します。

エージェントを作成するときは、既存の SDK を引き続き使用して、ベクトル検索インデックスなどの Databricks リソースにアクセスできます。リソースへのユーザー代理アクセスを有効にするには、次のようにします。

  1. エージェント コードで、SDK 呼び出しを更新して、エージェントのエンド ユーザーに代わってリソースがアクセスされることを示します
  2. エージェントのログ記録時 (エージェントのデプロイ前) に、エージェントに必要なエンドユーザーの REST API スコープを指定します。詳細については、「ユーザー代理認証」を参照してください

ユーザー代理認証のエンドツーエンドの例については、 エンドツーエンドの例を参照してください。

必要条件​

ヒント

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

ユーザー代理認証には、 mlflow 2.22.1以降が必要です

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

次のリソースは、エージェントによるユーザー代理認証と互換性があります。

Databricks リソース

互換性のあるクライアント

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

databricks_langchain.VectorSearchRetrieverTool、 databricks_openai.VectorSearchRetrieverTool 、または VectorSearchClient

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

databricks.sdk.WorkspaceClient

SQLウェアハウス

databricks.sdk.WorkspaceClient

UC接続

databricks.sdk.WorkspaceClient

UC テーブルと UC 関数

Databricks は現在、ユーザー代理認証を使用して UC テーブルまたは UC 関数に直接アクセスするクライアントをサポートしていません。代わりに、ユーザーにはGenieを使用して、ユーザーに代わって認証で構造化データにアクセスすることをお勧めします

Genieスペース

databricks_langchain.GenieAgent または databricks_openai.GenieAgent

ユーザー代理クライアントを使用してツールを初期化する場合、ツールの初期化を try-except ブロックでラップするか、エラーをユーザーに公開することができます。エラーを処理することで、エージェントは、エンド ユーザーが必要なすべてのツールにアクセスできない場合でも、ベストエフォート型の応答を行うことができます。ただし、ツールの初期化中にエラーを処理しないことを選択した場合、ユーザーに必要なリソースが不足している場合、エージェントはエラーをスローします。

SDK の構成​

以下のスニペットは、さまざまな SDK を使用して、さまざまな Databricks リソースへのユーザー代理アクセスを構成する方法を示しています

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 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 authenticated client
    )
    vector_search_tools.append(tool)
except Exception as e:
    _logger.debug("Skipping adding tool as user does not have permissions)

エージェントの初期化​

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

ユーザー代理認証を使用する場合、エンドユーザーの ID は、デプロイされたエージェントがクエリされたとき、つまり ResponsesAgent インターフェイスの predict および predict_stream 機能内でのみ認識されます。そのため、リソースへのユーザーアクセスに代わって any を実行する必要があります (たとえば、エンドユーザーがアクセスできるベクトル検索インデックスのリストなど)、ResponsesAgent 実装の __init__ メソッド内から実行する必要があります。これにより、呼び出し間でリソースが分離されます

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

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

エージェントによるユーザー代理認証を有効にする前に、セキュリティへの影響を考慮する必要があります。

  1. 機密 Databricks リソースへのアクセス: ユーザーに代わって認証を有効にすると、エージェントは機密 Databricks リソースにアクセスできるようになります。 開発者がアクセスできるリソースを制限し、トークンの悪用のリスクを軽減するために API スコープを実装しましたが、いくつかのリスクはまだ残っています。たとえば、 serving.serving-endpoints API スコープは、ユーザーに代わってサービングエンドポイントを実行する権限をエージェントに付与します。ただし、サービスエンドポイント自体は、元のエージェントが使用を許可されていない追加の API スコープにアクセスできる場合があります。
  2. エンド ユーザーの同意はサポートされていません: 現在のベータ フェーズでは、エージェント ユーザーは、エージェントに必要な Databricks REST API スコープを表示したり、同意したりすることはできません。ユーザーは、サービスエンドポイントに対する "Can Manage" 権限を持つユーザーが、ユーザーに代わって Databricks でアクションを実行することを信頼する責任があります。

エンドツーエンドの例​

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

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

Open notebook in new tab
に最終更新