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

Supervisor API (ベータ版) を使用してカスタム エージェントを構築します

備考

ベータ版

この機能はベータ版です。アカウント管理者は、 [プレビュー] ページからこの機能へのアクセスを制御できます。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 (ベータ版) を参照してください。

要件​

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

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

Templateから新しいアプリを作成するには、AIエージェントを作成して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 を備えた同じデプロイ済み App ですが、エージェント コードはよりシンプルになっています。完全なデプロイ ワークフロー（Apps へのデプロイ、ツールの追加、評価）については、AI エージェントを作成して 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のような、各ツールに必要な権限を付与してください。

その他のリソース​

このページの見出し