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

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

備考

ベータ版

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

警告

一方、ユーザー認証は、機密データへの安全なアクセスを強制するための強力なツールです。これにより、ワークスペース ユーザーは、Databricks で他のユーザーに代わって動作するエージェントを作成できます。ベータ版では、デフォルトでは無効になっており、ワークスペース管理者が有効にする必要があります。この機能を有効にする前に、ユーザー代理認証のセキュリティ に関する考慮事項 を確認してください。

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

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

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

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

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

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

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

エージェントの初期化​

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

Python
from mlflow.pyfunc import ChatAgent


class LangGraphChatAgent(ChatAgent):
  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,
    messages: list[ChatAgentMessage],
    context: Optional[ChatContext] = None,
    custom_inputs: Optional[dict[str, Any]] = None,
  ) -> ChatAgentResponse:
    agent = initialize_agent() # Initialize the Agent in Predict
    request = {"messages": self._convert_messages_to_dict(messages)}

    messages = []
    for event in self.agent.stream(request, stream_mode="updates"):
      for node_data in event.values():
        messages.extend(
          ChatAgentMessage(**msg) for msg in node_data.get("messages", [])
        )
    return ChatAgentResponse(messages=messages)

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

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

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

エンドツーエンドの例​

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

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

Open notebook in new tab
に最終更新