エージェントの認証

多くの場合、エージェントはタスクを完了するために他のリソースに対して認証を行う必要があります。 たとえば、デプロイされたエージェントは、AI Search インデックスにアクセスして非構造化データのクエリを実行したり、基盤モデルを呼び出すサービス エンドポイント、カスタム ロジックを実行する Unity カタログ関数にアクセスしたりする必要がある場合があります。

このページでは、Databricks Apps にデプロイされたエージェントの認証方法について説明します。 モデル サービス エンドポイントにデプロイされたエージェントについては、「エージェントの 認証 (モデル サービス)」を参照してください。

Databricks Apps には、エージェント用の 2 つの認証方法が用意されています。 各メソッドは、さまざまなユース ケースに対応します。

1 つのエージェントで両方のメソッドを組み合わせることができます。 たとえば、アプリの承認を使用して共有 AI Search インデックスにアクセスし、ユーザー承認を使用してユーザー固有のテーブルにクエリを実行します。

ワークスペース UI または宣言型オートメーション バンドルを使用して認証を構成する

すべての認証設定は、次の 2 つの方法で構成できます。

• ワークスペース UI: アプリを編集し、[ 構成] ステップからリソースとスコープを管理します。 ワークスペース内の 1 つのアプリを反復処理する場合にお勧めします。
• 宣言型オートメーション バンドル: databricks.yml ファイル内のリソース、スコープ、環境変数を宣言し、 databricks bundle deployを使用してデプロイします。 Git ベースのバージョン管理、CI/CD、またはワークスペース間で同じエージェントを配布する場合に推奨されます。 すべてのエージェント テンプレートには、databricks.ymlが付属しています。

どちらのパスでも、同じランタイム構成が生成されます。 このページの残りの部分では、両方のフォームの各指示が表示されるので、1 つを選択してプロジェクト内で一貫性を保つことができます。

いずれかのパスを使用してアプリにリソースを追加するには、リソースとアプリの両方に対する Can Manage アクセス許可が必要です。

完全なバンドル リファレンスについては、 app resource と app.resources を参照してください。 エンドツーエンドのバンドルチュートリアルについては、「 宣言型オートメーション バンドルを使用した Databricks アプリの管理」を参照してください。

アプリの承認

既定では、Databricks Apps はアプリの承認を使用して認証します。 Databricks は、アプリの作成時にサービス プリンシパルを自動的に作成し、アプリの ID として機能します。

アプリを操作するすべてのユーザーは、サービス プリンシパルに対して定義されているのと同じアクセス許可を共有します。 このモデルは、すべてのユーザーに同じデータを表示させる場合、またはアプリがユーザー固有のアクセス制御に関連付けられていない共有操作を実行する場合に適切に機能します。

アプリの承認の詳細については、「アプリの 承認」を参照してください。

MLflow 実験にアクセス許可を付与する

トレースと評価結果をログに記録するには、エージェントが MLflow 実験にアクセスする必要があります。 実験に対するアクセス許可 Can Edit サービス プリンシパルに付与します。

ワークスペース UI

1. アプリのホーム ページで [ 編集] をクリックします。
2. [構成] ステップに移動します。
3. [ アプリ リソース ] セクションで、 Can Edit アクセス許可を持つ MLflow 実験リソースを追加します。

Databricks アプリへの MLflow 実験リソースの追加を参照してください。

宣言型オートメーション バンドル

1. databricks.yml の アプリの resources リストで、宣言して実験を行います。 リソースに割り当てる name は、後で環境変数を接続するときに参照されます。

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. バンドルを再デプロイします。

   databricks bundle deploy
   databricks bundle run my_agent
   

すべてのフィールドについては 、app.resources.experiment を参照してください。

他の Databricks リソースにアクセス許可を付与する

エージェントが Genie エージェント、AI 検索インデックス、SQL ウェアハウスなどの他の Databricks リソースを使用している場合は、それぞれにサービス プリンシパルのアクセス許可を付与します。

プロンプト レジストリにアクセスするには、プロンプトを格納するために Unity カタログ スキーマに対する CREATE FUNCTION、 EXECUTE、および MANAGE のアクセス許可を付与します。

Unity カタログ リソースへのアクセスを許可する場合は、すべてのダウンストリーム依存リソースにアクセス許可を付与する必要もあります。 たとえば、Genie エージェントへのアクセス権を付与する場合は、基になるテーブル、SQL ウェアハウス、Unity カタログ関数へのアクセス権も付与する必要があります。

ワークスペース UI

Databricks ワークスペースでアプリを作成または編集するときに、[ アプリ リソース ] セクションからアプリにリソースを追加します。

1. アプリのホーム ページで [ 編集] をクリックします。
2. [構成] ステップに移動します。
3. [アプリ リソース] で、エージェントが使用する各リソースの [+ リソースの追加] をクリックし、アクセス許可を設定します。

サポートされているリソースとスクリーンショットの完全な一覧については、「 Databricks アプリ へのリソースの追加」を参照してください。

宣言型オートメーション バンドル

1. エージェントが使用するすべてのリソースを、resourcesのアプリのdatabricks.yml一覧で宣言します。 次の例は、MLflow 実験、サービス エンドポイント、Genie エージェント、SQL ウェアハウス、AI 検索インデックス、Unity カタログ関数、および Lakebase インスタンスを使用するエージェントを示しています。 各リソース name は config.env から value_from 経由で参照されるため、エージェントは実行時に解決された識別子を受け取ります。

   bundle:
     name: my_agent
   
   resources:
     apps:
       my_agent:
         name: 'my-agent'
         description: 'Custom agent deployed on Databricks Apps'
         source_code_path: ./
         config:
           command: ['uv', 'run', 'start-app']
           env:
             - name: MLFLOW_EXPERIMENT_ID
               value_from: 'experiment'
             - name: LAKEBASE_INSTANCE_NAME
               value_from: 'database'
   
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   
           - name: 'llm'
             serving_endpoint:
               name: 'databricks-claude-sonnet-4-5'
               permission: 'CAN_QUERY'
   
           - name: 'sales-genie'
             genie_space:
               space_id: '<genie-space-id>'
               permission: 'CAN_RUN'
   
           - name: 'warehouse'
             sql_warehouse:
               id: '<warehouse-id>'
               permission: 'CAN_USE'
   
           - name: 'docs-index'
             uc_securable:
               securable_full_name: 'main.docs.chunks_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'lookup-function'
             uc_securable:
               securable_full_name: 'main.tools.order_lookup'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   
           - name: 'database'
             database:
               instance_name: '<lakebase-instance-name>'
               database_name: 'databricks_postgres'
               permission: 'CAN_CONNECT_AND_CREATE'
   
   targets:
     dev:
       mode: development
       default: true
   

   Important

   value_fromのすべてのconfig.env値は、name リストのresources フィールドと一致する必要があります。 不一致により、デプロイされたアプリで環境変数が None に解決されます。

2. バンドルをデプロイして開始します。

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy はソースをアップロードし、リソースを構成します。 bundle run は、最新のソースでアプリを起動または再起動します。 bundle runする引数は、デプロイされたアプリの resources.apps フィールドではなく、my_agent (ここではname) の YAML キーです。

すべてのリソース サブタイプの完全なスキーマについては、 app.resources を参照してください。

次の表に、上記の例で使用されている最小限のアクセス許可と、リソースの種類ごとに同等の宣言型オートメーション バンドルの値を示します。

最小限の特権の原則に従います。 エージェントに必要なアクセス許可のみをサービス プリンシパルに付与し、アプリごとに専用のサービス プリンシパルを使用します。 完全な一覧については、「 セキュリティのベスト プラクティス」を参照してください。

ユーザーの承認

ユーザー承認を使用すると、エージェントは要求を行うユーザーの ID を使用して動作できます。 これにより、次の機能が提供されます。

• 機密データへのユーザーごとのアクセス
• Unity カタログによって適用されるきめ細かいデータ コントロール
• ユーザー固有の監査証跡
• 行レベルフィルターと列マスクの自動適用

エージェントがアプリのサービス プリンシパルではなく要求元ユーザーの ID を使用してリソースにアクセスする必要がある場合は、ユーザー承認を使用します。

ユーザー承認のしくみ

エージェントのユーザー承認を構成する場合:

1. アプリに API スコープを追加する: アプリがユーザーに代わってアクセスできる Databricks API を定義します。 「アプリにスコープを追加する」を参照してください。
2. ユーザー資格情報はダウンスコープです。Databricks はユーザーの資格情報を受け取り、定義した API スコープのみに制限します。
3. トークン転送: ダウンスコープ トークンは、 x-forwarded-access-token HTTP ヘッダーを介してアプリで使用できるようになります。
4. MLflow AgentServer はトークンを格納します。エージェント サーバーは、エージェント コードに簡単にアクセスできるように、要求ごとにこのトークンを自動的に格納します。

アプリの作成時または編集時に Databricks Apps UI にスコープを追加するか、API を使用してプログラムでスコープを追加して、ユーザー承認を構成します。 詳細な手順については、「 アプリにスコープを追加する 」を参照してください。

ユーザー承認を持つエージェントは、次の Databricks リソースにアクセスできます。

• SQL ウェアハウス
• Genie エージェント
• ファイルとディレクトリ
• モデル サービング エンドポイント
• AI Search インデックス
• Unity カタログ接続
• Unity カタログ テーブル

ユーザー承認を実装する

ユーザー承認を実装するには、承認スコープをアプリに追加する必要があります。 スコープによって、アプリがユーザーに代わって実行できる操作が制限されます。 使用可能なスコープとスコープセマンティクスの一覧については、「 スコープベースのセキュリティと特権のエスカレーション」を参照してください。

ワークスペース UI

1. Databricks UI で、アプリの 承認 設定に移動します。
2. [ ユーザーの承認] で 、[ + スコープの追加 ] をクリックし、アプリがユーザーの代わりにリソースにアクセスするために必要なスコープを選択します。
3. 変更を保存し、アプリを再起動します。

宣言型オートメーション バンドル

1. アプリリソースのuser_api_scopesでdatabricks.ymlのスコープを宣言します。

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         user_api_scopes:
           - sql
           - genie
           - model-serving
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. バンドルを再デプロイし、アプリを再起動します。

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   ワークスペースでユーザー承認を初めて有効にした後は、スコープを使用する前に既存のアプリを再起動する必要があります。 「アプリにスコープを追加する」を参照してください。

エージェント コードでユーザー承認を構成するには、AgentServer からこの要求のヘッダーを取得し、それらの資格情報を使用してワークスペース クライアントを構築します。

1. エージェント コードで、認証ユーティリティをインポートします。

   databricks/app-templates から提供されたテンプレートのいずれかを使用する場合は、提供されたユーティリティをインポートします。

   from databricks_app.utils import get_user_workspace_client
   

   それ以外の場合は、エージェント サーバー ユーティリティからインポートします。

   from agent_server.utils import get_user_workspace_client
   

   get_user_workspace_client()関数は、エージェント サーバーを使用してx-forwarded-access-token ヘッダーをキャプチャし、それらのユーザー資格情報を使用してワークスペース クライアントを構築し、ユーザー、アプリ、およびエージェント サーバー間の認証を処理します。

2. アプリの起動時ではなく、クエリ時にワークスペース クライアントを初期化します。

   Important

   get_user_workspace_client()ハンドラーとinvokeハンドラー内でstreamを呼び出し、__init__やアプリの起動時では呼び出さないようにします。 ユーザー資格情報は、ユーザーが要求を行った場合にのみクエリ時に使用できます。 ユーザー コンテキストがまだ存在しないため、アプリの起動時に初期化に失敗します。

   # In your agent code (inside invoke or stream handler)
   user_client = get_user_workspace_client()
   
   
   # Use user_client to access Databricks resources with user permissions
   response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
   

スコープの追加とスコープベースのセキュリティの理解に関する完全なガイドについては、 スコープベースのセキュリティと特権のエスカレーションに関する説明を参照してください。 エージェントが必要とする最小スコープのみを要求し、ユーザーに代わって実行されたすべてのアクションをログに記録します。 ユーザー承認のベスト プラクティスを参照してください。

ユーザー認証を確認する

スコープを追加して get_user_workspace_client()を呼び出した後、エージェントがアプリのサービス プリンシパルではなく、呼び出し元として実行されたことを確認します。 転送されたトークンが見つからない場合、get_user_workspace_client() は例外を発生させずにサービス プリンシパルにフォールバックするため、エージェントは引き続きアプリとして動作しながら、一見通常どおりの応答を返すことができます。 確認するには、 whoami ツールを追加し、自分で呼び出します。 ユーザー名が返された場合、ユーザー承認は機能しています。

current_user.me() は既定の iam.current-user:read スコープでカバーされるため、このテストのスコープを追加する必要はありません。

from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

エージェントを再デプロイします。 詳細は、レガシーエージェント サーバーを使用して Databricks Apps でエージェントを実行するを参照してください。

ワークスペース UI

ワークスペース UI テストは最も迅速なサニティ チェックであり、OAuth トークンは必要ありません。

1. スコープの変更はすぐに有効になりますが、内部キャッシュの更新には最大 5 分かかる場合があります。テストの前にしばらく待ちます (アプリの再起動は必要ありません)。 アプリの URL のブラウザー Cookie を常にクリアします (手順については、以下のドロップダウンを参照してください)。それ以外の場合、セッションはスコープの変更前に発行されたトークンを再利用します。
2. アプリに CAN USE アクセス許可があることを確認します。 Databricks アプリのアクセス許可の構成を参照してください。
3. ブラウザーでアプリの URL を開きます。 初回アクセス時に、要求されたスコープに対する同意プロンプトを承認してください。
4. チャットで、 Who am I? に質問し、エージェントがユーザー名 (たとえば、 you@your-company.com) を返すのを確認します。

Python

CLI プロファイルまたはサービス プリンシパルの資格情報を使用してエージェントを呼び出します。 クエリ オプションについてはレガシー MLflow を使用するエージェントへのクエリAgentServerを、OAuth トークンの生成方法についてはトークン認証を使用した API Databricks アプリへの接続を参照してください。

1. スコープの変更はすぐに有効になりますが、内部キャッシュの更新には最大 5 分かかる場合があるため、テストする前に待機します (アプリの再起動は必要ありません)。

2. エージェントを自分で呼び出します。

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   app_name = "<your-app-name>"
   prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]
   
   w = WorkspaceClient(profile="<your-profile>")
   client = DatabricksOpenAI(workspace_client=w)
   response = client.responses.create(model=f"apps/{app_name}", input=prompt)
   print(response.output_text)
   

   出力はユーザー名 (たとえば、 you@your-company.com) である必要があります。

ツールがユーザー名ではなく UUID を返した場合、 x-forwarded-access-token ヘッダーはツールに到達せず、エージェントはアプリのサービス プリンシパル (UUID はアプリのサービス プリンシパル クライアント ID) にフォールバックします。 診断するには、次の各内容を確認します。

1. ワークスペースでユーザー承認が有効になっています。
2. アプリにはスコープが構成されています。
3. get_user_workspace_client() は、アプリの起動時ではなく、 @invoke または @stream ハンドラー内で呼び出されます。
4. このコードでは、get_user_workspace_client()ではなくWorkspaceClient()が使用されます。

注意すべき点がいくつかあります。

• 本番環境に移行する前に、whoami ツールを削除してください。 診断のみであり、エージェントを呼び出すことができるすべてのユーザーにユーザー ID を公開します。
• 2 番目のユーザーでテストします。 シングル ユーザー チェックでは、トークンが転送されていることを確認します。2 番目の呼び出し元は、各要求が共有フォールバックではなく独自の ID を取得することを確認します。
• 転送されたトークンをログに記録しないでください。 ユーザー承認のベスト プラクティスを参照してください。
• 特定のスコープを確認するには、 current_user.me() をそのスコープを必要とする呼び出しに置き換えます。 たとえば、倉庫に対する SELECT current_user() ステートメントは、 sql スコープをエンドツーエンドで実行します。

レガシーワークスペースのMCPエンドポイントに認証する

レガシーワークスペースのMCPエンドポイントは AI SearchインデックスとUnity Catalogの関数を、https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> や https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema> の形式のURLを通じてツールとして公開します。 以前の /api/2.0/mcp/vector-search/ URLプレフィックスは後方互換性のために引き続き機能しています。

認証するには、エージェントのサービス プリンシパル (またはユーザー承認を使用している場合はユーザー) に、これらのスキーマ内のすべてのダウンストリーム リソースへのアクセス権を付与します。

たとえば、エージェントが次の MCP サーバー URL を使用している場合です。

• https://<your-workspace>/api/2.0/mcp/ai-search/prod/customer_support
• https://<your-workspace>/api/2.0/mcp/ai-search/prod/billing
• https://<your-workspace>/api/2.0/mcp/functions/prod/billing

prod.customer_supportおよびprod.billing内のすべての AI Search インデックスと、prod.billing内のすべての Unity カタログ関数へのアクセス権を付与する必要があります。

ワークスペース UI

各インデックスと関数をリソースとして [アプリ リソース] に追加します。 他の Databricks リソースにアクセス許可を付与するのと同じ手順に従います。

宣言型オートメーション バンドル

1. アプリの uc_securable リストに、インデックスと関数ごとに 1 つのresources エントリを追加します。

   resources:
     apps:
       my_agent:
         resources:
           - name: 'support-index'
             uc_securable:
               securable_full_name: 'prod.customer_support.tickets_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'billing-index'
             uc_securable:
               securable_full_name: 'prod.billing.invoices_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'refund-function'
             uc_securable:
               securable_full_name: 'prod.billing.process_refund'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   

2. バンドルを再デプロイします。

   databricks bundle deploy
   databricks bundle run my_agent
   

MCPサービスへの認証

前回のセクションでは、独自のUnityカタログデータや機能を公開するマネージドMCPサーバーについて説明しました。 MCPサービスは異なります。登録した外部MCPサーバーと、サードパーティのSaaSツール向けにAzure Databricksが提供するsystem.ai.*サービス(system.ai.google_calendarなど)をカバーします。 両タイプは https://<workspace>/ai-gateway/mcp-services/<catalog>.<schema>.<mcp-service>時にUnity Gatewayを通じて呼び出され、認証方式も同じです。

各 MCP サービスは、それぞれが個別の Unity Catalog のセキュリティ保護対象であるため、アクセス権はサービスごとに付与します。

発信者にサービスへのアクセスを許可します

サービスを呼び出すには、呼び出し元はそのサービスに EXECUTE と、親カタログおよびスキーマの USE CATALOG と USE SCHEMA が必要です。 EXECUTE 単独では不十分で、Unity Catalogは親チェーンもチェックします(チーム メイトへのアクセス権限を参照)。

組み込みの system.ai.* サービスでは、アカウントユーザーがデフォルトでこれらの権限を持っているため、通常は何も付与する必要はありません。

独自のカタログとスキーマ内のサービスについては、呼び出し元として自分で権限を付与します。アプリ ID ベースのアクセスにはアプリのサービス プリンシパルを、代理実行アクセスには呼び出し元のユーザーまたはグループを指定します。 カタログエクスプローラーの 権限 タブかREST APIをご利用ください(ご自身のもの <catalog>.<schema>.<service>を代替してください):

databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/<catalog>.<schema>.<service>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'
databricks api patch "/api/2.1/unity-catalog/permissions/catalog/<catalog>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["USE_CATALOG"] } ] }'
databricks api patch "/api/2.1/unity-catalog/permissions/schema/<catalog>.<schema>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["USE_SCHEMA"] } ] }'

ユーザーに代わってアクセスするために、ユーザーのトークンを転送する

代理アクセスは通話を発信者として実行するため、アプリはそのユーザーのトークンをUnity Gatewayに転送することを許可しなければなりません。 これを有効にするには、アプリのリソースに ai-gateway ユーザー API スコープ:user_api_scopes: [ai-gateway] を宣言を追加し (アプリへのスコープの追加を参照)、その後、レガシー エージェント サーバーを使用した Databricks アプリでのエージェントの実行に記載の手順に従って、ユーザーごとのクライアント (get_user_workspace_client()) を使用してサービスを呼び出します。

各ユーザーが初めてサービスに電話をかける際、必ず承認しなければなりません。 それまでは、この呼び出しは、error.data.elicitations[] 内のログイン url を含む JSON-RPC エラー -32042 を返します。 Surface リンクを表示して、ユーザーがアプリ内で認証できるようにするか、カタログエクスプローラーでサービスを開きログインをクリックさせてください。

独自の Databricks アプリ ( mcp- でプレフィックスが付いたアプリ名) としてホストされているカスタム MCP サーバーは、バンドル リソースとしてまだサポートされていません。 Can Useを使用して、MCP サーバー アプリでエージェントのサービス プリンシパル databricks apps update-permissionsを手動で付与します。 エージェント テンプレート リポジトリの custom-mcp-server スキル を参照してください。

次のステップ

• エージェントを作成して Databricks Apps にデプロイする
• 宣言型オートメーション バンドルを使用して Databricks アプリを管理する
• Databricks アプリで承認を構成する
• Databricks アプリにリソースを追加する
• アプリ リソース リファレンス