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

Supervisor API（ベータ版）

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能を有効にできます。Databricksのプレビューを管理するを参照してください。

Supervisor API は、Databricks での カスタムエージェントの構築を簡素化し、長時間実行されるタスクのバックグラウンドモードをサポートします。モデル、ツール、および命令は、OpenResponses互換エンドポイント (POST ai-gateway/mlflow/v1/responses) への 1 回のリクエストで定義します。Databricks がエージェント ループを実行し、モデルを繰り返し呼び出し、ツールを選択して実行し、最終的な応答を合成します。

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

  • Agent Bricksスーパーバイザーエージェント （推奨）：完全な宣言型で、人間によるフィードバック最適化により最高の品質を実現します。
  • Supervisor API ：カスタムエージェントをプログラムで構築します。ランタイムでモデルを選択し、リクエストごとに使用するツールを制御したり、開発中に反復処理を行ったりできます。エージェントループ管理をDatabricksにオフロードしながら、モデル選択を制御する必要がある場合にも最適な選択肢です。
  • AI Gateway unified or native 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",
      "name": "Customer reviews",
      "description": "Answers customer review questions using SQL",
      "genie_space": {"space_id": "<genie-space-id>"}
    },
    {
      "type": "dashboard",
      "name": "Customer reviews dashboard",
      "description": "Answers questions about the customer reviews dashboard",
      "dashboard": {"dashboard_id": "<dashboard-id>"}
    },
    {
      "type": "uc_function",
      "name": "Flag urgent review",
      "description": "Flags a review as requiring urgent attention",
      "uc_function": {"name": "<catalog>.<schema>.<function_name>"}
    },
    {
      "type": "table",
      "table": {
        "name": "<catalog>.<schema>.<table_name>",
        "description": "Reads from the customer reviews table"
      }
    },
    {
      "type": "vector_search_index",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index_name>",
        "description": "Searches the product documentation index for relevant passages"
      }
    },
    {
      "type": "knowledge_assistant",
      "name": "Internal docs",
      "description": "Answers questions from internal documentation",
      "knowledge_assistant": {"knowledge_assistant_id": "<knowledge-assistant-id>"}
    },
    {
      "type": "serving_endpoint",
      "name": "Custom agent",
      "description": "Calls a custom agent served from a Databricks model serving endpoint",
      "serving_endpoint": {"name": "<serving-endpoint-name>"}
    },
    {
      "type": "vector_search_index",
      "name": "Product docs",
      "description": "Looks up product documentation by semantic search",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index>",
        "columns": ["title", "content"]
      }
    },
    {
      "type": "app",
      "name": "Support agent",
      "description": "Custom application endpoint",
      "app": {"name": "<app-name>"}
    },
    {
      "type": "uc_connection",
      "name": "GitHub",
      "description": "Searches GitHub for issues and pull requests",
      "uc_connection": {"name": "<uc-connection-name>"}
    },
    {
      "type": "web_search",
      "name": "Web search",
      "description": "Searches the public web for current information and returns a synthesized answer with citations",
      "web_search": {}
    },
    {
      "type": "volume",
      "volume": {
        "name": "<catalog>.<schema>.<volume>",
        "description": "Searches files in a Unity Catalog volume"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

ステップ3 (オプション): システム管理接続でサードパーティサービスに接続する​

Databricks は、Google ドライブ、GitHub、アトラシアン、シェアポイント、グリーンなどの人気のサードパーティサービス向けにシステム管理接続を提供しています。これらの接続は、独自の外部MCPサーバーを設定する迅速な代替手段です。— 自分で構成した任意の外部MCPサーバーに接続するために uc_connection ツールタイプを引き続き使用できます。

システム管理接続には、ワークスペースで Third Party Connectors for Agents (ベータ版) を有効にする必要があります。「Databricks プレビューの管理」を参照してください。

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

コネクター

説明

system_ai_agent_google_drive

Google Drive からファイルを検索して読み取ります。

system_ai_agent_github_mcp

GitHubリポジトリ、課題、およびプルリクエストにアクセスします。

system_ai_agent_atlassian_mcp

Atlassianリソース (Jira, Confluence) を検索および管理する。

system_ai_agent_sharepoint

SharePointからファイルを検索して読み取ります。

system_ai_agent_glean_mcp

Gleanによってインデックス付けされたエンタープライズコンテンツを検索します。

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

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 (オプション): クライアント側の関数ツールを追加します​

アプリケーションでDatabricksがホストするツールと連携してカスタムロジックを実行する場合は、functionツールを使用してください。type: "function"、name、オプションのdescription、およびJSONスキーマparametersオブジェクトで関数ツールを宣言します。

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "<user prompt>"}],
  tools=[
    {
      "type": "function",
      "name": "<client-side-function-name>",
      "description": "<description of what this function does>",
      "parameters": {
        "type": "object",
        "properties": {"<param-name>": {"type": "string"}},
        "required": ["<param-names>"],
        "additionalProperties": False,
      },
    }
  ],
)

The Supervisor API doesn't store conversation state between requests, so a client-side function call takes two turns:

  1. ターン 1。 モデルは最終的な回答ではなく、function_callの項目（例：「get_weatherをlocation=Parisで呼び出す」）を返します。
  2. コード は関数をローカルで実行し、結果を生成します。
  3. ターン 2. responses.create() を再度呼び出し、元の入力とモデルの function_call、および結果を含む新しい function_call_output を渡します。モデルは結果を使用して最終的な回答を生成します。

クライアントサイド関数ツール例

Python
import json
from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)
MODEL = "databricks-claude-sonnet-4-5"

GET_WEATHER = {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
}

def run_get_weather(args):
    return json.dumps({
        "location": args["location"],
        "temp_c": 18,
        "condition": "sunny",
    })

CLIENT_TOOLS = {"get_weather": run_get_weather}
TOOLS = [GET_WEATHER]

input_list = [{"role": "user", "content": "What's the weather in Paris?"}]

# Turn 1 — model emits a function_call
resp = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)

# Echo the model's turn into history, then execute pending client function_calls
input_list += [item.model_dump() for item in resp.output]
for item in resp.output:
    if item.type == "function_call" and item.name in CLIENT_TOOLS:
        args = json.loads(item.arguments)
        # Execute the client-side function with the model's arguments
        # and append the result so the model can use it on the next turn.
        tool_output = CLIENT_TOOLS[item.name](args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": tool_output,
        })

# Turn 2 — model produces the final answer using the tool result
final = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)
print(final.output_text)

詳細なパターン（ストリーミング、ホスト型およびクライアントツール、MCP 承認、トラブルシューティング）については、Supervisor API クライアント側の関数呼び出しスキルを参照してください。

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

リクエストボディでtrace_destinationを渡して、エージェントループからUnity Catalogテーブルにトレースを送信します。各リクエストは、モデル呼び出しとツール実行の全シーケンスをキャプチャするトレースを生成します。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={
    &quot;trace_destination&quot;: {
      &quot;catalog_name&quot;: &quot;&lt;catalog&gt;&quot;,
      &quot;schema_name&quot;: &quot;&lt;schema&gt;&quot;,
      &quot;table_prefix&quot;: &quot;&lt;table-prefix&gt;&quot;
    }
  }
)

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={
      &quot;trace_destination&quot;: {
        &quot;catalog_name&quot;: &quot;&lt;catalog&gt;&quot;,
        &quot;schema_name&quot;: &quot;&lt;schema&gt;&quot;,
        &quot;table_prefix&quot;: &quot;&lt;table-prefix&gt;&quot;
      }
    },
    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 配列でツールを定義します。すべてのツールオブジェクトは、3つのトップレベルフィールドを共有します。

  • type (文字列、必須)：ツールタイプを選択する識別子です。
  • name (文字列、オプション): モデルに表示される表示名です。
  • description （文字列、オプション）：このツールを呼び出すタイミングに関するモデルへのヒント。

さらに、すべてのツールオブジェクトは、そのキーが type の値と一致するネストされた構成オブジェクトを保持しています。下記の表は、サポートされている各ツールタイプのネストされた構成を記述しています。

ツールタイプ

例

スコープ

genie_space

JSON
{
  "type": "genie_space",
  "name": "Customer reviews",
  "genie_space": {
    "space_id": "<id>"
  }
}

genie

dashboard

JSON
{
  "type": "dashboard",
  "name": "Sales dashboard",
  "dashboard": {
    "dashboard_id": "<id>"
  }
}

dashboards

uc_function

JSON
{
  "type": "uc_function",
  "name": "Flag urgent review",
  "uc_function": {
    "name": "<catalog>.<schema>.<function>"
  }
}

unity-catalog

table

JSON
{
  "type": "table",
  "name": "Customer reviews",
  "table": {
    "name": "<catalog>.<schema>.<table_name>"
  }
}

unity-catalog

knowledge_assistant

JSON
{
  "type": "knowledge_assistant",
  "name": "Internal docs",
  "knowledge_assistant": {
    "knowledge_assistant_id": "<id>"
  }
}

model-serving

serving_endpoint

JSON
{
  "type": "serving_endpoint",
  "name": "Custom agent",
  "serving_endpoint": {
    "name": "<endpoint-name>"
  }
}

model-serving

web_search

JSON
{
  "type": "web_search",
  "name": "Web search",
  "web_search": {}
}

model-serving

vector_search_index

JSON
{
  "type": "vector_search_index",
  "name": "Product docs",
  "vector_search_index": {
    "name": "<catalog>.<schema>.<index>",
    "columns": ["title", "content"]
  }
}

vector-search

volume

JSON
{
  "type": "volume",
  "volume": {
    "name": "<catalog>.<schema>.<volume>",
    "description": "Searches files in a Unity Catalog volume"
  }
}

unity-catalog

app

JSON
{
  "type": "app",
  "name": "Support agent",
  "app": {
    "name": "<app-name>"
  }
}

apps

uc_connection

JSON
{
  "type": "uc_connection",
  "name": "GitHub",
  "uc_connection": {
    "name": "system_ai_agent_github_mcp"
  }
}

unity-catalog

function

JSON
{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a location.",
  "parameters": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

なし

serving_endpointについては、ResponseAgent、ChatCompletions、ChatAgentエンドポイントのみがサポートされています。

app の場合、MCP アプリ（mcp- プレフィックス付き）のみ、およびカスタム ResponseAgent アプリ（agent- プレフィックス付き）がサポートされています。

uc_connectionの場合は、外部MCPサーバー用に作成した接続名、またはsystem_ai_agent_*のシステム管理コネクタを使用します (ステップ3 (オプション): システム管理接続を使用してサードパーティサービスに接続するを参照)。カスタムMCPサーバーはアプリではサポートされていません。

コードの実行​

リクエストで計算が必要な場合、Supervisorはモデル生成されたコードをサンドボックス化されたサーバレスコンピュートセッションで実行し、データを分析したり、ファイルを変換したり、計算を実行したりします。Python (デフォルト)、SQL、およびシェルコマンドをサポートしています。Supervisorは必要に応じてコードを記述し、実行します。そのため、コードを有効にしたり、設定したり、提供したりする必要はありません。

コードの実行は、ロックダウンされたサンドボックスで以下を伴って行われます。

  • インターネットアクセスなし。 ワークスペースのネットワークポリシーに関係なく、すべての送信ネットワークエグレスをブロックします。そのため、サンドボックスで実行されているコードは外部エンドポイントに到達できません。
  • スコープ設定されたDatabricksアクセスのみ。 独自のデータアクセスはありません。同じリクエストでtableツールを使用して宣言したUnity Catalogテーブルを読み取ることができます。

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

Supervisor 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、dashboard、uc_function、table、knowledge_assistant、serving_endpoint、web_search、vector_search_index、volume、app、uc_connection) とクライアント側の関数ツール (function)。ステップ 4 (オプション): クライアント側の関数ツールを追加するを参照してください。

  • 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 は、呼び出し元の認証情報でエージェント ループを実行するため、呼び出すツールは、呼び出し元の Unity Catalog 権限を尊重します。APIを直接呼び出すと、DatabricksOpenAIクライアントはユーザーとして認証されます。

Databricks App から Supervisor API を呼び出す場合、アプリの Databricks サービスプリンシパル（アプリ承認）として、またはリクエスト元のユーザー（ユーザー承認）としてツールを実行できます。アプリ承認の場合、アプリの Databricks サービスプリンシパルに各ツールへの権限を付与します。ユーザー承認の場合、ユーザーのトークンを DatabricksOpenAI クライアントに転送し、必要なユーザー承認スコープを追加します。リクエスト元のユーザーとしてツールを実行するを参照してください。

制限事項​

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

  • バックグラウンドモードランタイム ：バックグラウンドモードのリクエストは、最大実行時間が 30 分です。
  • バックグラウンドモードでのストリーミング ：同じリクエスト内でstream とbackground trueの両方を同時に にすることはできません。
  • 永続的な実行 ：エージェントループに対する厳密に1回の実行保証を伴う、障害または中断からの自動回復はサポートされていません。
  • Web web_search検索ワークスペースの適格性：HIPAA/BAA コンプライアンスが有効なワークスペースでは、 ツールは利用できません。Web 検索対応のネイティブモデル、または地理横断処理が有効になっているリージョンでのみ利用可能です。対象外のワークスペースからのweb_searchを含むリクエストは拒否されます。

その他のリソース​

このページの見出し