Costruisci un sistema multi-agente su Databricks Apps

Invece di creare un agente che esegue tutte le operazioni, un agente di orchestrazione multi-agente instrada le richieste a subagenti specializzati da un singolo punto di ingresso.

Ad esempio, è possibile combinare un agente RAG che esegue query su documenti non strutturati con un agente Genie che esegue query su dati strutturati, in modo che gli utenti ottengano risposte da più origini.

L'agente di orchestrazione considera ogni subagente come strumento e usa le relative istruzioni per instradare le richieste a quella corretta. L'orchestratore supporta i seguenti tipi di subagente:

• Agenti Databricks Apps: altri agenti distribuiti come Databricks Apps, chiamati tramite la Responses API.
• Genie Spaces: interrogazione dei dati in linguaggio naturale tramite il server predefinito di Azure Databricks MCP.
• Gestione degli endpoint: assistenti, agenti o modelli di knowledge base su Model Serving che supportano l'API Risposte.

Requisiti

• CLI di Databricks installata e autenticata. Le chiamate da app a app richiedono OAuth. Consulta Installare o aggiornare la CLI di Databricks.
• Python 3.11 o versione successiva.
• Il gestore di pacchettiuv. Vedere installazione uv.
• Le App Databricks abilitate in area di lavoro. Vedere Configurare l'area di lavoro e l'ambiente di sviluppo di Databricks Apps.
• Almeno un subagente per orchestrare: un Genie Space, un'altra app Databricks, un assistente di conoscenza o un endpoint di servizio.

Provare prima Il supervisore dell'agente

Prima di creare un agente di orchestrazione personalizzato, prendere in considerazione l'uso dell'agente supervisore per creare un sistema multi-agente coordinato. Compila e gestisce automaticamente il sistema multi-agente tramite un'interfaccia utente. È possibile connettere Genie Spaces, endpoint degli agenti, funzioni del Catalogo Unity, server MCP e agenti personalizzati, migliorando nel tempo la qualità del coordinamento attraverso il feedback formulato in linguaggio naturale da esperti in materia.

Creare un sistema multi-agente su Databricks Apps se è necessaria una logica di routing personalizzata o un comportamento di orchestrazione non supportato da Agent Supervisor.

Clonare il modello dell'orchestratore multi-agente

Il modello di orchestrazione multi-agente fornisce l'impalcatura per la struttura del progetto e la logica di orchestrazione usando l'OpenAI Agents SDK. Include anche file di competenze che insegnano agli assistenti di codifica di intelligenza artificiale come sviluppare l'agente di orchestrazione.

Clonare il modello e passare alla cartella :

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

Configurare i subagenti

Ogni back-end che l'agente di orchestrazione può chiamare è definito come sottoagente nell'elenco SUBAGENTS in agent_server/agent.py.

Rimuovere il commento e configurare le voci necessarie. Aggiornare la descrizione per descrivere il subagent in modo più dettagliato. La qualità della descrizione è direttamente correlata al modo in cui l'agente di orchestrazione può instradare le richieste al subagent corretto:

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

Ogni voce diventa automaticamente uno strumento che l'orchestratore può chiamare. È necessario abilitare almeno un subagente.

La tabella seguente descrive ogni tipo di subagente:

Personalizzare l'orchestratore

L'agente di orchestrazione viene creato nella create_orchestrator_agent() funzione. Aggiornare le istruzioni per descrivere gli strumenti specifici e quando usarli:

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

Configurare risorse e autorizzazioni

Dichiara le risorse necessarie per l'orchestratore in databricks.yml. Ogni tipo di sottoagente richiede la propria voce di risorsa:

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'

Aggiornare i valori segnaposto in databricks.yml in in modo che corrispondano ai subagenti configurati in agent_server/agent.py.

Concedere all'orchestratore l'accesso a un'app Databricks di destinazione

Se il tuo orchestratore chiama un'app Databricks di tipo subagent, devi concedere manualmente al principale di servizio dell'app dell'orchestratore il permesso sull'app di destinazione. Questa autorizzazione non può essere dichiarata come risorsa bundle e deve essere applicata dopo la distribuzione.

1. Trovare l'ID client dell'entità servizio dell'app dell'orchestratore:

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

2. Concedere all'entità servizio dell'app orchestratore CAN_USE l'autorizzazione sull'app di destinazione.

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

Testare localmente

Configurare l'ambiente locale e avviare l'agente:

uv run quickstart
uv run start-app

Il quickstart script configura l'autenticazione di Azure Databricks e crea un esperimento MLflow per il tracciamento. Dopo l'installazione, start-app avvia il server agente e un'interfaccia utente di chat all'indirizzo http://localhost:8000.

Distribuire nelle Applicazioni Databricks

Distribuire l'orchestratore usando Bundle di automazione dichiarativa:

1. Convalidare la configurazione del bundle:

   databricks bundle validate
   

2. Distribuire il bundle nell'area di lavoro:

   databricks bundle deploy
   

3. Avviare l'app:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Passaggi successivi

Dopo aver distribuito l'orchestratore, si esplorino le risorse seguenti.

• Creare un agente di intelligenza artificiale e distribuirlo in Databricks Apps
• Autenticazione per gli agenti di intelligenza artificiale
• Eseguire il debug di un agente di intelligenza artificiale distribuito