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

Databricks Appsでマルチエージェントシステムを構築する

すべてを実行する 1 つのエージェントを構築する代わりに、マルチエージェント オーケストレーターは、単一のエントリ ポイントから専門のサブエージェントにリクエストをルーティングします。

たとえば、非構造化ドキュメントをクエリする RAG エージェントと、構造化データをクエリする Genie エージェントを組み合わせることで、ユーザーは複数のソースから回答を得ることができます。

オーケストレーターは各サブエージェントをツールとして扱い、その指示を使用してリクエストを適切なサブエージェントにルーティングします。オーケストレーターは、次のサブエージェント タイプをサポートします。

  • Databricks Appsエージェント : Databricks Appsとしてデプロイされ、Responses APIを通じて呼び出されるその他のエージェント。
  • Genie spaces :組み込みDatabricks MCP サーバーを介してクエリを実行する自然言語データ。
  • サービス提供エンドポイント : Responses APIをサポートするモデルサービング上のナレッジ アシスタント、エージェント、またはモデル。

要件​

まずはエージェントスーパーバイザーを試す​

カスタム オーケストレーターを構築する前に、エージェント ブリック: スーパーバイザー エージェントを使用して、調整されたマルチエージェント システムを作成することを検討してください。UI を通じてマルチエージェント システムを構築および管理します。Genie spaces 、エージェントエンドポイント、 Unity Catalog機能、MCP サーバーを接続し、専門家からの自然言語フィードバックを使用して、時間の経過とともに調整の品質を向上させることができます。

Agent Supervisor がサポートしていないカスタム ルーティング ロジックやオーケストレーション動作が必要な場合は、 Databricks Appsでマルチエージェント システムを構築します。

マルチエージェントオーケストレーターテンプレートのクローンを作成する​

マルチエージェント オーケストレーター テンプレートは、 OpenAI Agents SDKを使用してプロジェクト構造とオーケストレーション ロジックのスキャフォールディングを提供します。また、AI コーディング アシスタントにオーケストレーターの開発方法を教えるスキル ファイルも含まれています。

テンプレートを複製し、次のフォルダに移動します。

Bash
git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk-multiagent

サブエージェントを構成する​

オーケストレーターが呼び出すことができる各バックエンドは、 agent_server/agent.pyのSUBAGENTSリストでサブエージェントとして定義されます。

必要なエントリのコメントを解除して構成します。サブエージェントをより詳しく説明するために説明を更新します。説明の品質は、オーケストレーターがリクエストを適切なサブエージェントにルーティングできるかどうかに直接関係します。

Python
SUBAGENTS = [
    {
        "name": "genie",
        "type": "genie",
        "space_id": "<YOUR-GENIE-SPACE-ID>",
        "description": (
            "Query a Genie space for structured data analysis. "
            "Use this for questions about data, metrics, and tables."
        ),
    },
    {
        "name": "app_agent",
        "type": "app",
        "endpoint": "<YOUR-APP-AGENT-NAME>",
        "description": (
            "Query a specialist agent deployed as a Databricks App. "
            "Use this for questions the specialist app agent handles."
        ),
    },
    {
        "name": "knowledge_assistant",
        "type": "serving_endpoint",
        "endpoint": "<YOUR-ENDPOINT>",
        "description": (
            "Query the knowledge-assistant endpoint on Model Serving. "
            "Use this for knowledge-base and documentation lookups. "
            "The endpoint must have task type agent/v1/responses."
        ),
    },
]

各エントリは自動的にオーケストレーターが呼び出すことができるツールになります。少なくとも 1 つのサブエージェントを有効にする必要があります。

次の表では、各サブエージェント タイプについて説明します。

Type

どのように接続するか

要件

app

レスポンスAPI経由 apps/<name>

OAuth 認証、対象アプリのCAN_USE権限

genie

組み込みのDatabricks MCPサーバー

GenieスペースID、 CAN_RUN権限

serving_endpoint

エンドポイント名経由のレスポンスAPI

エンドポイントには、サービス UI 上でタスク タイプ エージェント (応答) が必要です。ナレッジ アシスタント、エージェント、モデルが含まれます。

オーケストレーターをカスタマイズする​

オーケストレーター エージェントはcreate_orchestrator_agent()関数で作成されます。特定のツールと、それぞれのツールをいつ使用するかを説明するように手順を更新します。

Python
Agent(
    name="Orchestrator",
    instructions=(
        "You are an orchestrator agent. Route the user's request to the "
        "most appropriate tool or data source:\n"
        "- Use the Genie MCP tools for questions about structured data in <dataset_name> that contains information about <topic>\n"
        "- Use query_app_agent for questions or tasks that the specialist app agent handles for ...\n"
        "- Use query_knowledge_assistant for knowledge-base lookups about <topic>.\n"
        "If unsure, ask the user for clarification."
    ),
    model="databricks-claude-sonnet-4-5",
    mcp_servers=[mcp_server] if mcp_server else [],
    tools=subagent_tools,
)
ヒント

オーケストレーターの指示が具体的であればあるほど、リクエストのルーティングはより正確になります。各ツールの目的と、処理する質問の種類について説明します。

リソースと権限を構成する​

オーケストレーターに必要なリソースをdatabricks.ymlで宣言します。各サブエージェント タイプには独自のリソース エントリが必要です。

YAML
resources:
  - name: 'genie_space'
    genie_space:
      name: 'Genie Space'
      space_id: '<YOUR-GENIE-SPACE-ID>'
      permission: 'CAN_RUN'

  - name: 'serving_endpoint'
    serving_endpoint:
      name: '<YOUR-ENDPOINT>'
      permission: 'CAN_QUERY'

agent_server/agent.pyで構成したサブエージェントと一致するように、 databricks.ymlのプレースホルダー値を更新します。

オーケストレーターに対象の Databricks アプリへのアクセスを許可する​

オーケストレーターがサブエージェントDatabricksアプリを呼び出す場合は、ターゲット アプリに対するオーケストレーター アプリのサービスプリンシパルCAN_USE権限を手動で付与する必要があります。 この権限はバンドル リソースとして宣言することはできず、デプロイ後に適用する必要があります。

注記

権限リクエストのservice_principal_nameフィールドは、表示名ではなく、サービスプリンシパルのクライアント ID (UUID) である必要があります。 表示名を使用すると、暗黙的に成功しますが、権限は付与されません。databricks apps getコマンドはこの値をservice_principal_client_idとして返します。

  1. オーケストレーター アプリのサービスプリンシパル クライアント ID を見つけます。

    Bash
    databricks apps get <YOUR-ORCHESTRATOR-APP-NAME> --output json | jq -r '.service_principal_client_id'

  2. ターゲット アプリに対するオーケストレーター アプリのサービスプリンシパルCAN_USE権限を付与します。

    Bash
    databricks apps update-permissions <TARGET-APP-NAME> \
      --json '{"access_control_list": [{"service_principal_name": "<SP-CLIENT-ID>", "permission_level": "CAN_USE"}]}'

ローカルでテストする​

ローカル環境をセットアップし、エージェントを起動します。

Bash
uv run quickstart
uv run start-app

quickstartスクリプトはDatabricks認証を構成し、トレース用のMLflowエクスペリメントを作成します。 セットアップ後、 start-appエージェント サーバーとチャット UI をhttp://localhost:8000で起動します。

Databricks Appsにデプロイする​

宣言型自動化バンドルを使用してオーケストレーターをデプロイします。

  1. バンドル構成を検証します。

    Bash
    databricks bundle validate

  2. バンドルをワークスペースにデプロイします。

    Bash
    databricks bundle deploy

  3. アプリを起動：

    Bash
    databricks bundle run agent_openai_agents_sdk_multiagent
重要

bundle deploy ファイルをアップロードしますが、アプリは起動しません。アプリを起動するにはbundle runを実行します。

次のステップ​

オーケストレーターをデプロイした後、次のリソースを調べてください。