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

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

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

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

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

  • Databricks Appsエージェント ：Databricks Appsとしてデプロイされ、応答APIを介して呼び出されるその他のエージェント。
  • **Genie Spaces:** 組み込みのDatabricks MCPサーバーを介した自然言語データクエリ。
  • Servingエンドポイント : Responses APIをサポートするModel Serving上の知識アシスタント、エージェント、またはモデル。

要件​

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

マルチエージェント オーケストレーター テンプレートは、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

Responses API 経由 apps/<name>

OAuth認証、ターゲットアプリでのCAN_USE権限

genie

組み込み Databricks MCP サーバー

Genie Space 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'

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

オーケストレーターにターゲットの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 はエージェント サーバーと http://localhost:8000 のチャット UI を起動します。

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を実行します。

その他のリソース​

オーケストレーターをデプロイした後、以下のリソースをご覧ください：

このページの見出し