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

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

備考

ベータ版

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

独自のコードでエージェントループを管理する代わりに、Supervisor API (Beta) をオーケストレーションに利用する Databricks Apps エージェントを構築できます。結果は、カスタムエージェントを作成する場合と同じです。つまり、チャット UI、/invocations エンドポイント、および認証を備えたデプロイ済みの App です。その違いは、Databricks がエージェントループを代わりに実行することです。agent.py は単一の API コールを実行し、Databricks がツール選択、実行、および応答の合成を処理します。

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

Supervisor API を使用する場合​

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

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

API リファレンス全文とサポートされているパラメーターについては、Supervisor API（Beta） を参照してください。

要件​

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

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

テンプレートから新しいアプリを作成するには、「AIエージェントを作成してDatabricks Appsにデプロイする」を参照してください。

最新のテンプレートからアプリが設定されたら、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 エンドポイントを備えたデプロイ済みの同じアプリですが、エージェントコードはよりシンプルになっています。完全なデプロイワークフロー (Appsへのデプロイ、ツールの追加、評価) については、AIエージェントを作成してDatabricks Appsにデプロイするを参照してください。

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

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

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

ホスト型ツールの承認​

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

  • アプリの承認 (デフォルト)：ツールはアプリの Databricks サービスプリンシパルとして実行されます。エージェントが使用する各ツールで Databricks サービスプリンシパルに権限を付与します。アプリの承認を参照してください。
  • ユーザー認可 ：ツールは、リクエストを送信したユーザーとして実行されるため、Unity Catalog のアクセス許可、行フィルター、列マスクはユーザーごとに適用されます。以下のセクションを参照してください。

リクエストしているユーザーとしてツールを実行​

備考

プレビュー

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

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

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

ツールの種類

必須スコープ

すべてのツール

ai-gateway

genie_space

genie

uc_function

mcp.functions

knowledge_assistant

model-serving

uc_connection

catalog.connections

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

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__ またはアプリの起動時には呼び出しません。転送されたトークンがない場合、結果のクライアントは要求しているユーザーとして認証されません。アプリの Databricks サービスプリンシパルではなく、呼び出し元としてエージェントが実行されることを確認する方法については、ユーザー承認を参照してください。 3. エージェントを実行する各ユーザーに、GenieスペースでのCAN_RUNや知識アシスタントエンドポイントでのCAN_QUERYなど、各ツールで必要な権限を付与します。

その他のリソース​

このページの見出し