Supervisor API (ベータ)

Important

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

Supervisor API は、Azure Databricksでビルド カスタム エージェントを簡略化し、実行時間の長いタスクのバックグラウンド モードをサポートします。 モデル、ツール、および命令は、OpenResponses 互換エンドポイント (POST /mlflow/v1/responses) に対する 1 つの要求で定義し、エージェント ループを実行Azure Databricks。モデルの繰り返し呼び出し、ツールの選択と実行、最終的な応答の合成を行います。

Azure Databricksでカスタマイズされたツール呼び出しエージェントを構築するには、次の 3 つの方法があります。

  • Agent Bricks Supervisor Agent (推奨): 高品質を目指して人間のフィードバックを活用した最適化による完全な宣言型方式。
  • Supervisor API: カスタム エージェントをプログラムで構築する —実行時にモデルを選択し、要求ごとに使用するツールを制御するか、開発中に反復処理します。 また、エージェント ループ管理をAzure Databricksにオフロードするときに、モデルの選択を制御する必要がある場合にも適しています。
  • AI Gateway 統合 API またはネイティブ API: 独自のエージェント ループを記述します。 Azure Databricksは LLM 推論レイヤーのみを提供します。 モデルの切り替え、またはプロバイダー固有のネイティブ API (/openai、/anthropic、/gemini) を有効にするには、可能な場合は統合 API を使用して、既存のコードをAzure Databricksに移植するか、プロバイダー固有の機能を使用します。

必要条件

手順 1: 1 ターン LLM 呼び出しを作成する

ツールなしで基本的な呼び出しから始めます。 DatabricksOpenAI クライアントは、ワークスペースのベース URL と認証を自動的に構成します。

from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  stream=False
)

print(response.output_text)

手順 2: ホストされているツールを追加してエージェント ループを実行する

要求にツールを含めると、Azure Databricksは、ユーザーの代わりに複数回の対話ループを管理します。モデルがどのツールを呼び出すかを決定し、Azure Databricksがそれを実行して、結果をモデルにフィードバックし、モデルが最終回答を生成するまでこれを繰り返します。

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Summarize recent customer reviews and flag any urgent issues."}],
  tools=[
    {
      "type": "genie_space",
      "genie_space": {
        "id": "<genie-space-id>",
        "description": "Answers customer review questions using SQL"
      }
    },
    {
      "type": "uc_function",
      "uc_function": {
        "name": "<catalog>.<schema>.<function_name>",
        "description": "Flags a review as requiring urgent attention"
      }
    },
    {
      "type": "knowledge_assistant",
      "knowledge_assistant": {
        "knowledge_assistant_id": "<knowledge-assistant-id>",
        "description": "Answers questions from internal documentation"
      }
    },
    {
      "type": "app",
      "app": {
        "name": "<app-name>",
        "description": "Custom application endpoint"
      }
    },
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "<uc-connection-name>",
        "description": "Searches the web for current information"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

手順 3: トレースを有効にする

要求本文に trace_destination を渡して、エージェント ループから Unity カタログ テーブルにトレースを送信します。 各要求は、モデル呼び出しとツール実行の完全なシーケンスをキャプチャするトレースを生成します。 trace_destinationを設定しない場合、トレースは書き込まれません。 セットアップの詳細については、「 MLflow トレースを Unity カタログに格納する」を参照してください。

databricks-openai Python クライアントを使用して、extra_body 経由で渡します。

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  extra_body={
    "trace_destination": {
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_prefix": "<table-prefix>"
    }
  }
)

また、API 応答でトレースを直接返すには、"databricks_options": {"return_trace": True}でextra_bodyを渡します。

MLflow 分散トレースを使用して、アプリケーション コードと Supervisor API エージェント ループからのトレースを 1 つのエンド ツー エンド トレースに結合することもできます。 extra_headers フィールドを使用してトレース コンテキスト ヘッダーを伝達します。

import mlflow
from mlflow.tracing import get_tracing_context_headers_for_http_request

with mlflow.start_span("client-root") as root_span:
  root_span.set_inputs({"input": "Tell me about Databricks"})

  trace_headers = get_tracing_context_headers_for_http_request()

  response = client.responses.create(
    model="databricks-claude-sonnet-4-5",
    input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
    tools=[...],
    extra_body={
      "trace_destination": {
        "catalog_name": "<catalog>",
        "schema_name": "<schema>",
        "table_prefix": "<table-prefix>"
      }
    },
    extra_headers=trace_headers,
  )

バックグラウンド モード

バックグラウンド モードを使用すると、複数のツール呼び出しと複雑な推論を伴う実行時間の長いエージェント ワークフローを、同期的に完了するのを待たずに実行できます。 background=Trueで要求を送信し、すぐに応答 ID を受け取り、準備ができたら結果をポーリングします。 これは、複数のデータ ソースに対してクエリを実行したり、1 つの要求で複数のツールを連結したりするエージェントに特に役立ちます。

バックグラウンド要求を作成する

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  background=True,
)

print(response.id)     # Use this ID to poll for the result
print(response.status) # "queued" or "in_progress"

結果を問い合わせる

responses.retrieve()を使用して、終了状態になるまで状態を確認します。

from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

MCP を使用したバックグラウンド モード

セキュリティを確保するために、Supervisor API では、バックグラウンド モードで MCP ツール呼び出しを実行する前に、明示的なユーザー承認が必要です。 エージェント ループが MCP ツールを選択すると、応答は mcp_approval_requestで完了します。 モデルが渡すツール名、サーバー ラベル、および引数を確認できます。

{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

ツール呼び出しを承認してエージェント ループを続行するには、 mcp_approval_response を input フィールドに渡し、会話履歴全体を表示します。

{
  "type": "mcp_approval_response",
  "id": "<tool-call-id>",
  "approval_request_id": "<tool-call-id>",
  "approve": true
}

Note

バックグラウンド モードの応答は、データベースに最大 30 日間保持されます。

サポートされているツール

要求の tools 配列にツールを定義します。 各エントリは、同じキーを持つ type と構成オブジェクトを指定します。 たとえば、Genie 空間ツールには "type": "genie_space" と "genie_space": {...} オブジェクトがあります。 API では、次の種類のツールがサポートされています。

ツールの種類 説明 Scope
genie_space Genie 空間にクエリを実行して、データに関する質問に回答します。 パラメーター: id、 description。 genie
uc_function エージェント ツールとして Unity カタログ関数 を呼び出します。 パラメーター: name、 description。 unity-catalog
uc_connection Unity カタログ接続を介して 外部 MCP サーバー に接続します。 パラメーター: name、 description。 注: アプリ上の カスタム MCP サーバー はまだサポートされていません。 unity-catalog
app Azure Databricks アプリ エンドポイントを呼び出します。 パラメーター: name、 description。 apps
knowledge_assistant Knowledge Assistant エンドポイントを呼び出します。 パラメーター: knowledge_assistant_id、 description。 model-serving

サポートされているパラメーター

Supervisor API に対する各要求は、次のパラメーターを受け入れます。

  • input: 送信する会話メッセージ。
  • tools: ホストされるツール定義 (genie_space、 uc_function、 knowledge_assistant、 app、 uc_connection)。
  • instructions: スーパーバイザーの動作をガイドするシステム プロンプト。
  • stream: ストリーム応答に true に設定します。
  • background: 要求を非同期的に実行する true に設定します。 responses.retrieve()でポーリングする応答 ID を返します。 背景モードを参照してください。
  • trace_destination: catalog_name、 schema_name、および table_prefix フィールドを持つ省略可能なオブジェクト。 設定すると、Supervisor API は完全なエージェント ループのトレースを指定された Unity カタログ テーブルに書き込みます。 Python クライアントで extra_body 経由で渡します。

API では、 temperatureなどの推論パラメーターはサポートされていません。 サーバーは、内部的にこれらを管理します。

制限事項

Supervisor API には、次の制限があります。

  • バックグラウンド モード ランタイム: バックグラウンド モード要求の最大実行時間は 30 分です。
  • クライアント側の関数呼び出し: ホストされているツールのみがサポートされています。 クライアント function 実行するツール定義を渡すことはできません。また、ホストされているツールとクライアント側の function ツールを同じ要求に混在させることはありません。
  • バックグラウンド モードでのストリーミング: stream と background の両方を同じ要求で true することはできません。
  • 永続的な実行: エージェント ループに対して 1 回だけ実行が保証されたエラーまたは中断からの自動復旧はサポートされていません。
  • Azure Databricks Apps OBO はサポートされていません: Supervisor API では、ユーザーの代理承認はサポートされていません。 Azure Databricks Apps で Supervisor API を使用するには、system authorization を使用し、ツールのアクセス許可を付与します。

次のステップ

  • Last updated on