Erstellen eines Multi-Agent-Systems auf Databricks-Apps

Anstatt einen Agent zu erstellen, der alles erledigt, leitet ein Multi-Agent Orchestrator Anforderungen an spezialisierte Subagenten von einem einzigen Einstiegspunkt aus weiter.

Sie können beispielsweise einen RAG-Agent kombinieren, der unstrukturierte Dokumente mit einem Genie-Agent abfragt, der strukturierte Daten abfragt, sodass Benutzer Antworten aus mehreren Quellen erhalten.

Der Orchestrator behandelt jeden Subagenten als Werkzeug und verwendet dessen Anweisungen, um Anfragen an den richtigen Subagenten zu leiten. Der Orchestrator unterstützt die folgenden Subagenttypen:

• Databricks-Apps-Agents: Andere Agents, die als Databricks-Apps bereitgestellt wurden, werden über die Antwort-API aufgerufen.
• Genie Spaces: Abfrage von Daten in natürlicher Sprache über den integrierten Azure Databricks MCP-Server.
• Die Bereitstellung von Endpunkten: Wissensassistenten, Agents oder Modelle für die Modellbereitstellung, die die Antwort-API unterstützen.

Anforderungen

• Die Databricks CLI wurde installiert und authentifiziert. Für App-zu-App-Aufrufe ist OAuth erforderlich. Siehe Installieren oder Aktualisieren der Databricks CLI.
• Python 3.11 oder höher.
• Der uv Paket-Manager. Siehe UV-Montage.
• Databricks-Apps, die in Ihrem Arbeitsbereich aktiviert sind. Weitere Informationen finden Sie unter Einrichten ihres Databricks-Apps-Arbeitsbereichs und ihrer Entwicklungsumgebung.
• Mindestens ein Subagent zum Orchestrieren: ein Genie Space, eine andere Databricks-App, ein Wissensassistent oder ein bedienter Endpunkt.

Agent-Supervisor zuerst testen

Bevor Sie einen benutzerdefinierten Orchestrator erstellen, sollten Sie den Supervisor-Agent verwenden, um ein koordiniertes Multi-Agent-System zu erstellen. Es erstellt und verwaltet das Multi-Agent-System für Sie über eine Benutzeroberfläche. Sie können Genie Spaces, Agent-Endpunkte, Unity Catalog-Funktionen, MCP-Server und benutzerdefinierte Agents verbinden und dann die Koordinationsqualität im Laufe der Zeit verbessern, indem Sie Feedback von Experten für natürliche Sprache verwenden.

Erstellen Sie ein Multi-Agent-System auf Databricks-Apps, wenn Sie benutzerdefiniertes Routinglogik- oder Orchestrierungsverhalten benötigen, das agent Supervisor nicht unterstützt.

Klonen Sie die Multi-Agent-Orchestratorvorlage

Die Multi-Agent Orchestrator-Vorlage stellt das Gerüst für die Projektstruktur und Die Orchestrierungslogik mithilfe des OpenAI Agents SDK bereit. Es enthält auch Qualifikationsdateien, die KI-Codierungsassistenten beibringen, wie der Orchestrator entwickelt wird.

Klonen Sie die Vorlage, und wechseln Sie zum Ordner:

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

Konfigurieren von Subagenten

Jedes Backend, das der Orchestrator aufrufen kann, wird als Subagent in der SUBAGENTS-Liste innerhalb von agent_server/agent.py definiert.

Entfernen Sie die Kommentierung und passen Sie die erforderlichen Einträge an. Aktualisieren Sie die Beschreibung, um den Subagent ausführlicher zu beschreiben. Die Beschreibungsqualität hängt direkt damit zusammen, wie gut der Orchestrator Anforderungen an den richtigen Subagent weiterleiten kann:

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."
        ),
    },
]

Jeder Eintrag wird automatisch zu einem Tool, das der Orchestrator aufrufen kann. Sie müssen mindestens einen Subagent aktivieren.

In der folgenden Tabelle werden die einzelnen Subagententypen beschrieben:

Anpassen des Orchestrators

Der Orchestrator-Agent wird in der create_orchestrator_agent() Funktion erstellt. Aktualisieren Sie die Anweisungen, um Ihre spezifischen Tools zu beschreiben und wann jedes einzeln verwendet werden soll.

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,
)

Konfigurieren von Ressourcen und Berechtigungen

Deklarieren Sie die Ressourcen, die Ihr Orchestrator in databricks.yml benötigt. Jeder Subagenttyp erfordert einen eigenen Ressourceneintrag:

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'

Aktualisieren Sie die Platzhalterwerte databricks.yml so, dass sie den von Ihnen konfigurierten agent_server/agent.pySubagenten entsprechen.

Gewähren Sie dem Orchestrator Zugriff auf eine Databricks-Ziel-App

Wenn Ihr Orchestrator eine Subagent-Databricks-App aufruft, müssen Sie dem Service Principal der Orchestrator-App manuell die Berechtigung auf die Ziel-App erteilen. Diese Berechtigung kann nicht als Bundleressource deklariert werden und muss nach der Bereitstellung angewendet werden.

1. Suchen Sie die Dienstprinzipalclient-ID der Orchestrator-App:

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

2. Erteilen Sie dem Dienstprinzipal der Orchestrator-App CAN_USE Berechtigungen für die Ziel-App.

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

Lokales Testen

Richten Sie Ihre lokale Umgebung ein, und starten Sie den Agent:

uv run quickstart
uv run start-app

Das quickstart Skript konfiguriert die Azure Databricks-Authentifizierung und erstellt ein MLflow-Experiment für die Ablaufverfolgung. Nach dem Setup, start-app startet der Agent-Server und eine Chat-UI unter http://localhost:8000.

Bereitstellen für Databricks-Apps

Bereitstellung des Orchestrators mit Deklarativen Automatisierungspaketen:

1. Überprüfen der Bundlekonfiguration:

   databricks bundle validate
   

2. Stellen Sie das Bundle in Ihrem Arbeitsbereich bereit:

   databricks bundle deploy
   

3. Starten Sie die App:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Nächste Schritte

Erkunden Sie nach der Bereitstellung Ihres Orchestrators die folgenden Ressourcen:

• Erstellen eines KI-Agents und Bereitstellen auf Databricks-Apps
• Authentifizierung für KI-Agents
• Debuggen eines bereitgestellten KI-Agents