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

Supervisor API (非推奨) を使用したカスタムエージェントの構築

警告

Supervisor APIのサポート期間は2026年9月30日に終了しました。これは利用できなくなりました。カスタムエージェントを構築するには、独自のエージェントループを作成し、Agent Bricks CLIを使用してデプロイします。Databricksへのエージェントのデプロイを参照してください。

独自コードでのエージェントループの管理に代えて、Supervisor API (非推奨) を使用する Databricks Apps エージェントを構築できます。結果は、カスタムエージェントの作成と同じであり、チャット UI、/invocations Endpoint、および認証を備えたデプロイ済みアプリになります。違いは、Databricks がユーザーに代わってエージェントループを実行する点です。お客様の agent.py が 1 回の API 呼び出しを行い、Databricks がツールの選択、実行、および応答の合成を処理します。

Supervisor APIは、サポートされている基盤モデルのいずれとも連携します。modelフィールドを変更して、ツール定義やハンドラーロジックを変更せずにプロバイダーを切り替えます。

スーパーバイザー API を使用する場合​

Supervisor APIは、エージェントがDatabricksホスト型ツールのみを使用し、ツール呼び出し間にカスタムロジックを必要としない場合にうまく機能します。エージェントが以下のいずれかを必要とする場合は、代わりにカスタムエージェントループを使用してください。

  • クライアント側の関数ツール（Supervisor APIは、ホストされたツールとクライアント側のツールを1つのリクエストで混在させることはできません）
  • Agent Bricks: Knowledge Assistant Endpoint以外のエージェント Endpoint
  • カスタムリトリーバー、カスタム入出力、またはきめ細やかなストリーミング制御
  • ツール呼び出し間のカスタムPythonロジック (条件分岐や状態管理など)
  • 推論パラメーターの制御： temperature

完全な API リファレンスおよびサポートされているパラメーターについては、Supervisor API (非推奨) を参照してください。

要件​

  • ワークスペースで Databricks Apps が有効になっています。レガシーエージェントサーバーを使用した Databricks Apps でのエージェントの実行については、ラン agents on Databricks Apps using the legacy agent server を参照してください。
  • databricks-openaiパッケージ： pip install databricks-openai

Supervisor API を使用してカスタム エージェントを構築する​

推奨される開始点は、最新の Databricks アプリケーション Template から新しいアプリケーションを作成することです。最新の Template には、AI コーディングアシスタント用の組み込み use-supervisor-api スキルと、ホストされたツールを追加するための add-tools スキルが含まれています。

テンプレートから新しいアプリを作成するには、レガシーエージェントサーバーを使用したDatabricks Appsでのエージェントのランを参照してください。

最新のTemplateからアプリがセットアップされたら、AIコーディングアシスタントでプロジェクトを開き、次を実行します:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

このスキルは、あなたのagent_server/agent.pyを更新してホストされているツールでDatabricksOpenAI().responses.create()を呼び出し、手動のエージェントループを置き換えます。また、databricks-openaiの依存関係を追加し、ベータ版の制限事項についても言及しています。

結果は、チャットUI、認証、および /invocations Endpoint を備えた同じデプロイ済みアプリになりますが、エージェントコードがよりシンプルになります。完全なデプロイワークフロー（アプリへのデプロイ、ツールの追加、評価）については、レガシーエージェントサーバーを使用した Databricks Apps でのランを参照してください。

サポートされているツールとパラメーター​

サポートされているツールタイプ、リクエストパラメーター、およびコード例の完全なリストについては、Supervisor API (非推奨) を参照してください。

追加する各ツールに対し、databricks.yml で対応するリソース権限も付与します。例については、.claude/skills/ の add-tools スキルを参照してください。

ホストされているツールの承認​

Supervisor API がエージェントループを実行すると、アプリの ID または要求しているユーザーの ID のいずれかを使用して、ホストされているツールを実行します。アプリのすべてのユーザーがツールへの同じアクセス権を共有すべきか、または各ユーザーが自身のアクセス権限で許可されているもののみにアクセスすべきかに基づいて選択します。

  • アプリの認可 (default): ツールは、アプリのDatabricks Service Principalとして実行されます。エージェントが使用する各ツールに対してDatabricks Service Principalのアクセス許可を付与します。アプリの認可を参照してください。
  • ユーザー認可 : ツールはリクエストを送信したユーザーとして実行されるため、Unity Catalogのアクセス許可、行フィルター、列マスクはユーザーごとに適用されます。次のセクションを参照してください。

要求元のユーザーとしてツールを実行する​

備考

プレビュー

ユーザー認証はパブリックプレビュー段階です。アプリにスコープを追加する前に、ワークスペース管理者がそれを有効にする必要があります。アプリにスコープを追加するを参照してください。

リクエスト元のユーザーに代わってホストされたツールを実行するには、ユーザーのトークンをDatabricksOpenAIクライアントに転送し、ツールが必要とするユーザー承認スコープを追加します。

  1. アプリが必要とするユーザー認証スコープを追加します。ai-gatewayは、すべてのスーパーバイザーAPIアクセスに必要です。エージェントが使用する各ツールタイプに対するツールごとのスコープを追加します。

ツールタイプ

必須スコープ

すべてのツール

ai-gateway

genie_space

genie

uc_function

mcp.functions

knowledge_assistant

model-serving

uc_connection

catalog.connections

ツールタイプ

必須スコープ

すべてのツール

ai-gateway

genie_space

genie

uc_function

mcp.functions

knowledge_assistant

model-serving

uc_connection

catalog.connections

appツールタイプはユーザー認可ではサポートされていません。App Endpointをツールとして呼び出すには、代わりにアプリ認可を使用してください。ワークスペースUIまたは宣言型オートメーションバンドルを介してスコープを追加する方法については、ユーザー認可を参照してください。 2. agent.pyハンドラーで、ユーザーワークスペースクライアントをDatabricksOpenAIに渡します。これはスーパーバイザーに固有の唯一の配線です。リソースをユーザークライアントで直接呼び出す代わりに、エージェントループを実行するクライアントに渡します。

Python
from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

get_user_workspace_client() 転送されたユーザー トークンをリクエストヘッダーから読み取ります。リクエストヘッダーはクエリー時にのみ投入されます。それをinvokeおよびstreamハンドラー内で呼び出してください。__init__またはアプリのStartup時には呼び出さないでください。転送されたトークンがない場合、結果として生成されるクライアントは、リクエスト元のユーザーとして認証されません。エージェントがアプリのDatabricks Service Principalとしてではなく、呼び出し元として実行されることを確認する方法については、ユーザー認可を参照してください。 3. エージェントを実行する各ユーザーに、Genie AgentのCAN_RUNのような、またはナレッジアシスタントEndpointのCAN_QUERYのような、各ツールに必要な権限を付与してください。

その他のリソース​

このページの見出し