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

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

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

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

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

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

要件​

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

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

Templateをクローンして、フォルダーに移動します。

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 Agent 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 Agent ID, CAN_RUNのアクセス許可

serving_endpoint

Endpoint名経由のResponses API

Endpointには、Serving UI で エージェント（応答） タスクタイプである必要があります。ナレッジアシスタント、エージェント、およびモデルが含まれます。

Type

接続方法

要件

app

Responses API 経由 apps/<name>

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

genie

組み込み Databricks MCP サーバー

Genie Agent ID, CAN_RUNのアクセス許可

serving_endpoint

Endpoint名経由のResponses API

Endpointには、Serving 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 Agent'
      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アプリを呼び出す場合、オーケストレーターアプリのService Principalにターゲットアプリに対するCAN_USE権限を手動で付与する必要があります。この権限はバンドルリソースとして宣言できず、デプロイ後に適用する必要があります。

注記

アクセス許可リクエストの service_principal_name フィールドは、表示名ではなく Service Principal のクライアント ID（UUID）である必要があります。表示名を使用するとサイレントに成功しますが、アクセス許可は付与されません。databricks apps get コマンドはこの値を service_principal_client_id として返します。

  1. オーケストレーターアプリのService PrincipalクライアントIDを見つける：

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

  2. ターゲット アプリケーションのオーケストレーター アプリケーションの Service Principal に 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 upload files but doesn't 起動 the app.アプリを起動するには、bundle runを実行します。

その他のリソース​

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

このページの見出し