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

スーパーバイザーAPI（ベータ版）

備考

ベータ版

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

Supervisor API を使用すると、Databricks 上でカスタム エージェントを簡単に構築でき、長時間実行されるタスク向けのバックグラウンド モードもサポートされます。OpenResponses互換エンドポイント（ POST /mlflow/v1/responses ）への1つのリクエストでモデル、ツール、および手順を定義すると、Databricksがエージェントループを実行します。つまり、モデルを繰り返し呼び出し、ツールを選択して実行し、最終的な応答を合成します。

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

  • Agent Bricks Supervisor Agent （推奨）：最高品質を実現するために、人間のフィードバックによる最適化を備えた完全宣言型。
  • スーパーバイザーAPI ：カスタムエージェントをプログラムで構築します。モデルは で選択し、リクエストごとに使用するツールを制御したり、開発中に反復したりできます。 また、エージェントループの管理をDatabricksに任せつつ、モデル選択を制御する必要がある場合にも最適な選択肢です。
  • AI Gatewayの統合APIまたはネイティブAPIs ：独自のエージェントループを作成します。 DatabricksはLLM推論レイヤーのみを提供します。可能な限り統一されたAPIsを使用してモデルの切り替えを可能にするか、既存のコードをDatabricksに移植する場合やプロバイダー固有の機能を使用する場合は、プロバイダー固有のネイティブAPIs ( /openai 、 /anthropic 、 /gemini ) を使用してください。

要件​

ステップ 1: シングルターンLLMコールを作成する​

まずはツールを使わない基本的な通話から始めましょう。DatabricksOpenAIクライアントは、ワークスペースのベースURLと認証を自動的に構成します。

Python
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: ホストされたツールを追加してエージェント ループを実行する​

リクエストにツールを含めると、Databricks がユーザーに代わって複数回のループ処理を管理します。モデルが呼び出すツールを決定し、Databricks がそれらを実行し、結果をモデルにフィードバックし、モデルが最終的な回答を生成するまでこのプロセスを繰り返します。

Python
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 (オプション): システム管理の接続を使用してサードパーティのサービスに接続します​

Databricksは、Google Drive、GitHub、Atlassian、SharePointといった人気のあるサードパーティサービス向けに、システム管理された接続を提供します。これらの接続は、独自の外部 MCP サーバーをセットアップするよりも手軽な代替手段です。 uc_connectionツール タイプを使用すれば、自分で構成した任意の外部 MCP サーバーに接続することもできます。

システム管理接続を使用するには、ワークスペースで エージェントベータ版用のサードパーティコネクタを 有効にする必要があります。Databricksのプレビューを管理するを参照してください。

以下のコネクタがサポートされています。

コネクター

説明

system_ai_agent_google_drive

Googleドライブからファイルを検索して閲覧できます。

system_ai_agent_github_mcp

GitHubのリポジトリ、イシュー、プルリクエストにアクセスできます。

system_ai_agent_atlassian_mcp

Atlassianのリソース（Jira、Confluence）を検索および管理します。

system_ai_agent_sharepoint

SharePointからファイルを検索して閲覧する。

tools配列内のコネクタを、 uc_connectionツールタイプを使用して渡します。 nameフィールドにはコネクタ名を設定してください。

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "List my open GitHub pull requests."}],
  tools=[
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "system_ai_agent_github_mcp"
      }
    }
  ],
)

ユーザー対マシン（U2M）認証​

各ユーザーは個別に認証を行う。OAuthクラウドはユーザー間で共有されません。 ユーザーが認証していないコネクタを使用する最初のリクエストでは、レスポンスはstatus: "failed"とログインURLを含むoauthエラーで完了します。

JSON
{
  "status": "failed",
  "error": {
    "code": "oauth",
    "message": "Failed request to <connector>. Please login first at <login-url>."
  }
}

ブラウザでURLを開き、OAuth認証フローを完了させた後、同じリクエストを再度実行してください。

ステップ 4: トレースを有効にする​

エージェントループからのトレースをUnity Catalogテーブルに送信するには、リクエストボディにtrace_destinationを渡してください。 各リクエストは、モデル呼び出しとツール実行の全シーケンスをキャプチャしたトレースを生成します。trace_destinationを設定しない場合、トレースは書き込まれません。設定の詳細については、 Unity CatalogにOpenTelemetryトレースを保存する」を参照してください。

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

Python
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レスポンスにトレースを直接返すには、 extra_bodyに"databricks_options": {"return_trace": True}を渡します。

MLflowの分散トレーシングを使用すると、アプリケーションコードとSupervisor APIエージェントループからのトレースを組み合わせて、単一のエンドツーエンドトレースを作成することもできます。extra_headersフィールドを使用してトレースコンテキストヘッダーを伝播します。

Python
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 が返され、準備ができたら結果をポーリングできます。これは、複数のデータソースにクエリを実行したり、複数のツールを単一のリクエストで連携させたりするエージェントにとって特に役立ちます。

バックグラウンドリクエストを作成する​

Python
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()を使用して状態を確認します。

Python
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で完了します。モデルが渡そうとしているツール名、サーバーラベル、および引数を確認できます。

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

ツール呼び出しを承認してエージェントループを続行するには、会話履歴全体とともにinputフィールドにmcp_approval_responseを返してください。

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

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

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

リクエストのtools配列でツールを定義します。各エントリは、 typeと、同じキーを持つ構成オブジェクトを指定します。例えば、Genie Spaceツールには"type": "genie_space"と"genie_space": {...}オブジェクトがあります。APIは以下のツールタイプをサポートしています。

ツールタイプ

説明

スコープ

genie_space

Genie Spaceに問い合わせて、データに関する質問に答えます。問題: id 、 description 。

genie

uc_function

エージェントツールとしてUnity Catalog関数を呼び出します。 問題: name 、 description 。

unity-catalog

uc_connection

Unity Catalog接続を介して外部MCPサーバーに接続します。 問題: name 、 description 。 Databricks で管理されるシステム接続の場合は、 name system_ai_agent_*コネクタに設定します (ステップ 3 (オプション): システム管理接続を使用してサードパーティ サービスに接続するを参照)。注：アプリ上のカスタムMCPサーバーはまだサポートされていません。

unity-catalog

app

Databricksアプリのエンドポイントを呼び出します。問題: name 、 description 。

apps

knowledge_assistant

ナレッジアシスタントのエンドポイントを呼び出します。問題: knowledge_assistant_id 、 description 。

model-serving

サポートされている​

スーパーバイザーAPIへの各リクエストは、以下を受け入れます。

  • model: 以下のサポート対象モデルのいずれか。このフィールドを変更すると、コードの他の部分を変更せずにプロバイダーを切り替えることができます。

  • GPT-5 ( databricks-gpt-5 )

  • GPT-5.1 ( databricks-gpt-5-1 )

  • GPT-5.2 ( databricks-gpt-5-2 )

  • GPT-5.4 ( databricks-gpt-5-4 )

  • 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 Catalogテーブルに書き込みます。 Pythonクライアントでextra_body経由で渡します。

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

制限事項​

Supervisor APIには以下の制限事項があります。

  • バックグラウンド モードの実行時間 : バックグラウンド モードのリクエストの最大実行時間は 30 分です。
  • クライアント側からの関数呼び出し ：ホスト型ツールのみがサポートされています。クライアントに実行させるためのfunction定義を渡すことはできませんし、ホスト型ツールとクライアント側functionツールを同じリクエスト内で混在させることもできません。
  • バックグラウンドモードでのストリーミング : streamとbackgroundは、同じリクエストで両方ともtrueになることはできません。
  • 永続的な実行 ：エージェントループの実行が一度だけ保証される、障害や中断からの自動回復はサポートされていません。
  • Databricks Apps OBO はサポートされていません : Supervisor API では、ユーザーに代わって認証を行うことはサポートされていません。Databricks AppsでSupervisor APIを使用するには、システム認証を使用してツールに権限を付与してください。

次のステップ​

このページの見出し