Vytvoření systému s více agenty v Databricks Apps

Místo vytváření jednoho agenta, který dělá všechno, orchestrátor pro více agentů směruje požadavky z jednoho vstupního bodu na specializované subagenty.

Můžete například zkombinovat agenta RAG, který dotazuje nestrukturované dokumenty s agentem Genie, který se dotazuje na strukturovaná data, takže uživatelé získají odpovědi z více zdrojů.

Orchestrátor zachází s jednotlivými dílčími agenty jako s nástrojem a pomocí jeho pokynů směruje požadavky na ten správný. Orchestrátor podporuje následující typy podagentů:

  • Agenti Databricks Apps: Další agenti jsou nasazeni jako Databricks Apps a volají prostřednictvím Responses API.
  • Agenti Genie: Dotazování dat v přirozeném jazyce prostřednictvím integrovaného serveru Azure Databricks MCP.
  • Obsluha koncových bodů: Asistenti znalostí, agenti nebo modely při poskytování modelů, které podporují rozhraní API pro odpovědi.

Požadavky

Nejprve vyzkoušejte Agent Supervisor.

Před vytvořením vlastního orchestrátoru zvažte použití agenta správce k vytvoření koordinovaného systému s více agenty. Sestavuje a spravuje systém s více agenty za vás prostřednictvím uživatelského rozhraní. Pomocí zpětné vazby z přirozeného jazyka od odborníků na danou problematiku můžete připojit Genie Agents, koncové body agenta, funkce katalogu Unity, servery MCP a vlastní agenty a pak zlepšit kvalitu koordinace v průběhu času.

Pokud potřebujete vlastní logiku směrování nebo chování orchestrace, které správce agenta nepodporuje, vytvořte v Databricks Apps systém s více agenty.

Klonujte šablonu více-agentového orchestrátoru

Víceagentní orchestrátorová šablona poskytuje základ pro strukturu projektu a logiku orchestrace pomocí sady OpenAI Agents SDK. Obsahuje také soubory dovedností, které učí pomocníky pro kódování AI, jak vyvíjet orchestrátor.

Naklonujte šablonu a přejděte do složky:

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

Konfigurace podagentů

Každý back-end, který může orchestrátor volat, je definován jako podagent v seznamu v SUBAGENTSagent_server/agent.py.

Odkomentujte a nakonfigurujte položky, které potřebujete. Aktualizujte popis, aby byl podagent podrobněji popsán. Kvalita popisu přímo souvisí s tím, jak dobře může orchestrátor směrovat požadavky do správného podagentu:

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

Každá položka se automaticky stane nástrojem, který může orchestrátor vyvolat. Musíte povolit aspoň jednoho podagenta.

Následující tabulka popisuje každý typ podagenta:

Type Jak se připojuje Požadavky
app Rozhraní API pro odpovědi skrze apps/<name> Ověřování OAuth, CAN_USE oprávnění k cílové aplikaci
genie Integrovaný server MCP v Azure Databricks ID agenta Genie, CAN_RUN oprávnění
serving_endpoint Rozhraní API pro odpovědi využívající názvy koncových bodů Koncový bod musí mít v uživatelském rozhraní služby typ úlohy Agent (Odpovědi). Zahrnuje znalostní asistenty, agenty a modely.

Přizpůsobení orchestrátoru

Agent orchestrátoru je vytvořen ve funkci create_orchestrator_agent(). Aktualizujte pokyny, abyste popsali konkrétní nástroje a kdy je použít:

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

Tip

Čím konkrétnější jsou pokyny orchestrátoru, tím přesněji směruje požadavky. Popište účel jednotlivých nástrojů a typy otázek, které zpracovává.

Konfigurace prostředků a oprávnění

Deklarujte prostředky, které váš orchestrátor potřebuje v databricks.yml. Každý typ podagenta vyžaduje vlastní položku prostředku.

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'

Hodnoty zástupných znaků databricks.yml aktualizujte tak, aby odpovídaly subagentům, které jste nakonfigurovali v agent_server/agent.py.

Udělení přístupu orchestrátoru k cílové aplikaci Databricks

Pokud orchestrátor volá podagent aplikaci Databricks, musíte ručně udělit instančnímu objektu CAN_USE aplikace orchestrátoru oprávnění k cílové aplikaci. Toto oprávnění nelze deklarovat jako prostředek sady a musí být použito po nasazení.

Note

Pole service_principal_name v žádosti o oprávnění musí být ID klienta servisního principálu (UUID), nikoli zobrazovaný název. Použití zobrazovaného názvu tiše proběhne úspěšně, ale neudělí oprávnění. Příkaz databricks apps get vrátí tuto hodnotu jako service_principal_client_id.

  1. Vyhledejte ID klienta instančního objektu aplikace orchestratoru:

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

  2. Udělte principálu služby aplikace orchestrátoru CAN_USE oprávnění k cílové aplikaci.

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

Místní testování

Nastavte místní prostředí a spusťte agenta:

uv run quickstart
uv run start-app

Skript quickstart nakonfiguruje ověřování Azure Databricks a vytvoří experiment MLflow pro trasování. Po nastavení start-app spustí server agenta a uživatelské rozhraní chatu na adrese http://localhost:8000.

Nasazení do aplikací Databricks

Nasaďte orchestrátor pomocí deklarativních automatizačních sad:

  1. Ověřte konfiguraci sady:

    databricks bundle validate

  2. Nasazení sady do pracovního prostoru:

    databricks bundle deploy

  3. Spusťte aplikaci:

    databricks bundle run agent_openai_agents_sdk_multiagent

Important

bundle deploy nahraje soubory, ale nespustí aplikaci. Spusťte bundle run, abyste mohli spustit aplikaci.

Další zdroje informací

Po nasazení orchestrátoru prozkoumejte následující zdroje informací:

  • Last updated on