メインコンテンツまでスキップ
に最終更新

AIエージェントの認証（Model Serving）

備考

新しいユースケースの場合、Databricksは、エージェントのコード、サーバー設定、およびデプロイワークフローを完全に制御するために、Databricks Appsへのエージェントのデプロイを推奨しています。AIエージェントを作成してDatabricks Appsにデプロイするを参照してください。既存のエージェントを移行するには、Model ServingからDatabricks Appsにエージェントを移行するを参照してください。

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

このページでは、カスタムエージェントを使用してエージェントを開発およびデプロイする際に利用可能な認証方法について説明します。

認証方法​

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

手法

説明

セキュリティ態勢

セットアップの複雑さ

自動認証パススルー

エージェントは、デプロイしたユーザーの権限で実行されます。

Databricksは、宣言されたリソースの有効期間が短い資格情報を自動的に管理します。

有効期間の短い資格情報、自動ローテーション

Low - ロギング時の依存関係の宣言

ユーザー代理認証（OBO）

エージェントは、リクエストを行ったエンドユーザーの権限で実行されます。

制限されたスコープでエンドユーザーの認証情報を使用します。

中 - スコープ宣言とランタイムの初期化が必要です

手動認証

環境変数を使用して資格情報を明示的に提供する

有効期間の長い資格情報にはローテーション管理が必要です。

高：手動での資格情報管理が必要です

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

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

  1. ユーザーごとのアクセス制御またはユーザーに帰属する監査が必要ですか？

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

Databricks MCP サーバーへの認証​

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

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

  • https://<your-workspace-hostname>/api/2.0/mcp/ai-search/prod/customer_support
  • https://<your-workspace-hostname>/api/2.0/mcp/ai-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の一覧には表示されません。エージェントモデルバージョンがエンドポイントから削除されると、サービスプリンシパルも削除されます。

  1. **資格情報のプロビジョニングとローテーション**: サービスプリンシパル向けの有効期間の短い資格情報（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以上

AI Searchインデックス

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スペースをログに記録する場合、そのテーブル、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 がサポートするリソース​

Model Servingエンドポイントでは、OBO認証を持つエージェントは、次の表に記載されているDatabricksリソースのみにアクセスできます。ここに記載されていないリソース (Unity Catalog ボリューム (ファイルのアップロード/ダウンロード) など) は、Model Serving の OBO ではサポートされていません。

注記

エージェントがより広範なリソースセットへのOBOアクセスを必要とする場合、Databricksは追加のOAuthスコープをサポートするDatabricks Appsへのエージェントのデプロイを推奨しています。エージェントをModel ServingからDatabricks Appsに移行するを参照してください。

Databricksリソース

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

AI Search インデックス

databricks_langchain.VectorSearchRetrieverTool、databricks_openai.VectorSearchRetrieverTool、 VectorSearchClient

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

databricks.sdk.WorkspaceClient

SQLウェアハウス

databricks.sdk.WorkspaceClient

UC接続

databricks.sdk.WorkspaceClient

UCテーブルおよび関数

databricks.sdk.WorkspaceClient （UCテーブルにアクセスするには、SQL Statement Execution APIを使用したSQLクエリを使用する必要があります）

Genieスペース

databricks.sdk.WorkspaceClient (推奨)、databricks_langchain.GenieAgent、または databricks_ai_bridge.GenieAgent

モデルコンテキストプロトコル (MCP)

databricks_mcp.DatabricksMCPClient

OBO認証を実装する​

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

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

次のスニペットは、さまざまな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 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")

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

ユーザーの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 のみに制限され、不正なアクションやトークンの誤用の可能性を低減します。

Model Serving エンドポイントでは、上記に記載されている OBO がサポートするリソースに対応するスコープのみを使用できます。

ユーザー代理認証を有効にするには、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=[
    "model-serving",
    "ai-search"
])

# 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 で Model Serving エンドポイントを指定します。

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

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

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

OBO ノートブックの例​

以下のノートブックでは、ユーザー代理認証を使用してAI Searchでエージェントを作成する方法を示します。

AI Search と連携するユーザー代理認証

ノートブックを新しいタブで開く

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

注記

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

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

ノートブックを新しいタブで開く

手動認証​

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

  • 依存リソースは自動認証パススルーをサポートしていません
  • エージェントは、エージェントのデプロイヤー以外の資格情報を使用する必要があります。
  • エージェントは、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={
         &quot;DATABRICKS_HOST&quot;: &quot;https://&lt;your-workspace-url&gt;&quot;,
         &quot;DATABRICKS_CLIENT_ID&quot;: f&quot;{secrets/{secret_scope_name}/{client_id_key}}",
            "DATABRICKS_CLIENT_SECRET": f"{secrets/{secret_scope_name}/{client_secret_key}}"
        },
    )

PAT認証​

個人用アクセストークン（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={
         &quot;DATABRICKS_HOST&quot;: &quot;https://&lt;your-workspace-url&gt;&quot;,
         &quot;DATABRICKS_TOKEN&quot;: f&quot;{secrets/{secret_scope_name}/{secret_key_name}}"
        },
    )
このページの見出し