Skapa ett system med flera agenter i Databricks-appar

I stället för att skapa en agent som gör allt, dirigerar en orkestratör för flera agenter begäranden till specialiserade underagenter från en gemensam startpunkt.

Du kan till exempel kombinera en RAG-agent som frågar ostrukturerade dokument med en Genie-agent som frågar efter strukturerade data, så att användarna får svar från flera källor.

Orchestratorn behandlar varje delagent som ett verktyg och använder sina instruktioner för att dirigera begäranden till rätt delagent. Orchestrator stöder följande subagenttyper:

• Databricks Apps-agenter: Andra agenter som distribueras som Databricks-appar, anropade via SVARS-API:et.
• Genie Spaces: Frågeställningar på naturligt språk via den inbyggda Azure Databricks MCP-servern.
• Serveringsslutpunkter: Kunskapsassistenter, agenter eller modeller på modellservern som stöder SVARS-API:et.

Requirements

• Databricks CLI har installerats och autentiserats. App-till-app-anrop kräver OAuth. Se Installera eller uppdatera Databricks CLI.
• Python 3.11 eller senare.
• Pakethanterare uv. Se UV-installation.
• Databricks-appar aktiverade på din arbetsyta. Se Konfigurera din Databricks Apps-arbetsyta och utvecklingsmiljö.
• Minst en underagent att orkestrera: en Genie Space, en annan Databricks-app, en kunskapsassistent eller en serveringsslutpunkt.

Prova agentövervakaren först

Innan du skapar en anpassad orkestrerare bör du överväga att använda övervakaragenten för att skapa ett samordnat system med flera agenter. Den skapar och hanterar systemet med flera agenter åt dig via ett användargränssnitt. Du kan ansluta Genie Spaces, agentslutpunkter, Unity Catalog-funktioner, MCP-servrar och anpassade agenter och sedan förbättra samordningskvaliteten över tid med hjälp av feedback om naturligt språk från ämnesexperter.

Skapa ett system med flera agenter i Databricks-appar om du behöver anpassad routningslogik eller orkestreringsbeteende som agentövervakaren inte stöder.

Klona mallen för orkestrerare för flera agenter

Mallen för dirigering med flera agenter tillhandahåller byggnadsställningar för projektstruktur och orkestreringslogik med hjälp av OpenAI Agents SDK. Den innehåller också kunskapsfiler som lär AI-kodningsassistenter hur man utvecklar orkestratorn.

Klona mallen och gå till mappen:

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

Konfigurera underagenter

Varje serverdel som orkestratorn kan anropa definieras som en underagent i SUBAGENTS listan i agent_server/agent.py.

Ta bort kommentarer och konfigurera de poster du behöver. Uppdatera beskrivningen för att beskriva underagenten mer detaljerat. Beskrivningskvaliteten är direkt relaterad till hur väl orkestreraren kan dirigera begäranden till rätt underagent:

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

Varje post blir automatiskt ett verktyg som orkestratorn kan anropa. Du måste aktivera minst en underagent.

I följande tabell beskrivs varje underagenttyp:

Anpassa orkestreraren

Orchestrator-agenten create_orchestrator_agent() skapas i funktionen. Uppdatera anvisningarna för att beskriva dina specifika verktyg och när du ska använda var och en:

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

Konfigurera resurser och behörigheter

Deklarera de resurser som orkestreringsenheten behöver i databricks.yml. Varje underagenttyp kräver en egen resurspost:

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'

Uppdatera platshållarvärdena i databricks.yml så att de matchar de underagenter som du konfigurerade i agent_server/agent.py.

Ge dirigeraren åtkomst till en Databricks-målapp

Om orkestratorn anropar en Databricks-app för subagenten måste du manuellt ge orkestrator-appens tjänsthuvudnamn CAN_USE behörighet för målappen. Den här behörigheten kan inte deklareras som en samlingsresurs och måste tillämpas efter distributionen.

1. Hitta orchestratorappens klient-ID för tjänstens huvudkonto.

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

2. Ge orchestrator-appens tjänstprincipalen CAN_USE behörighet åt målappen:

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

Testa lokalt

Konfigurera din lokala miljö och starta agenten:

uv run quickstart
uv run start-app

Skriptet quickstart konfigurerar Azure Databricks-autentisering och skapar ett MLflow-experiment för spårning. Efter installationen start-app startar agentservern och ett chattgränssnitt på http://localhost:8000.

Distribuera till Databricks Apps

Distribuera orkestratören med deklarativa automation-paket:

1. Verifiera paketkonfigurationen:

   databricks bundle validate
   

2. Distribuera paketet till din arbetsyta:

   databricks bundle deploy
   

3. Starta appen:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Nästa steg

När du har distribuerat orkestreraren kan du utforska följande resurser:

• Skapa en AI-agent och distribuera den i Databricks-appar
• Autentisering för AI-agenter
• Felsöka en distribuerad AI-agent