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

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

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

オーケストレーターは、各サブエージェントをツールとして扱い、その命令を使用して要求を適切なサブエージェントにルーティングします。 オーケストレーターでは、次のサブエージェント型がサポートされています。

• Databricks Apps エージェント: 応答 API を介して呼び出される、Databricks Apps としてデプロイされたその他のエージェント。
• Genie スペース: 組み込みの Azure Databricks MCP サーバーを使用した自然言語によるデータクエリ。
• エンドポイントの提供: 応答 API をサポートするモデル サービスのナレッジ アシスタント、エージェント、またはモデル。

必要条件

• Databricks CLI がインストールされ、認証されました。 アプリ間の呼び出しには OAuth が必要です。 「Databricks CLI のインストールまたは更新」を参照してください。
• Python 3.11 以降。
• uv パッケージ マネージャー。 uv のインストールを参照してください。
• ワークスペースで Databricks Apps が有効になっています。 Databricks Apps ワークスペースと開発環境を設定するを参照してください。
• 少なくとも 1 つのサブエージェントをオーケストレーションする: Genie スペース、別の Databricks アプリ、ナレッジ アシスタント、またはサービス エンドポイント。

エージェント スーパーバイザーを最初に試す

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

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

マルチエージェント オーケストレーター テンプレートを複製する

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

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

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

サブエージェントの構成

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

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

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 つのサブエージェントを有効にする必要があります。

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

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

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

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で宣言します。 各サブエージェントの種類には、独自のリソース エントリが必要です。

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 アクセス許可を手動で付与する必要があります。 このアクセス許可はバンドル リソースとして宣言できず、デプロイ後に適用する必要があります。

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

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

2. オーケストレーター アプリのサービス プリンシパルに、ターゲット アプリに対するアクセス許可 CAN_USE 付与します。

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

ローカルでテストする

ローカル環境を設定し、エージェントを起動します。

uv run quickstart
uv run start-app

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

Databricks Apps へのデプロイ

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

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

   databricks bundle validate
   

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

   databricks bundle deploy
   

3. アプリを起動します。

   databricks bundle run agent_openai_agents_sdk_multiagent
   

次のステップ

オーケストレーターをデプロイした後、次のリソースを確認します。

• AI エージェントを作成して Databricks Apps にデプロイする
• AI エージェントの認証
• デプロイされた AI エージェントをデバッグする