Budowanie systemu wieloagentowego na platformie Databricks Apps

Zamiast tworzyć jednego agenta, który wykonuje wszystko, orkiestrator wielu agentów kieruje żądania do wyspecjalizowanych podagentów z jednego punktu wejścia.

Można na przykład połączyć agenta RAG, który wysyła zapytania do dokumentów bez struktury za pomocą agenta Genie, który wysyła zapytania o dane ustrukturyzowane, dzięki czemu użytkownicy uzyskują odpowiedzi z wielu źródeł.

** Orkiestrator traktuje każdego subagenta jako narzędzie i używa jego instrukcji do kierowania żądań do właściwego. Orkiestrator obsługuje następujące typy subagentów:

• Agenci aplikacji Databricks: inni agenci wdrożeni jako aplikacje Databricks, wywoływani za pośrednictwem Responses API.
• Genie Agents: odpytywanie danych w języku naturalnym za pomocą wbudowanego serwera Azure Databricks MCP.
• Obsługa punktów końcowych: Asystenci wiedzy, agenci lub modele w usłudze Model Serving, które obsługują interfejs API odpowiedzi.

Requirements

• CLI Databricks został zainstalowany i uwierzytelniony. Połączenia między aplikacjami wymagają uwierzytelniania OAuth. Zobacz Instalowanie lub aktualizowanie interfejsu wiersza poleceń Databricks.
• Środowisko Python w wersji 3.11 lub nowszej.
• uv Menedżer pakietów. Zobacz instalację UV.
• Aplikacje Databricks są włączone w obszarze roboczym. Zobacz Konfigurowanie obszaru roboczego usługi Databricks Apps i środowiska programistycznego.
• Wymagany jest co najmniej jeden podagent do orkiestracji: agent Genie, inna aplikacja Databricks, asystent wiedzy lub punkt końcowy udostępniania.

Najpierw wypróbuj Agent Supervisor.

Przed zbudowaniem niestandardowego orchestratora rozważ Use Supervisor Agent to create a coordinated multi-agent system (legacy). Kompiluje system z wieloma agentami i zarządza nim za pośrednictwem interfejsu użytkownika. Możesz połączyć agentów Genie, punkty końcowe agentów, funkcje Unity Catalog, serwery MCP i niestandardowe agenty, a następnie z czasem poprawiać jakość koordynacji przy użyciu informacji zwrotnych w języku naturalnym od ekspertów dziedzinowych.

Zbuduj system wieloagentowy w aplikacjach Databricks, jeśli potrzebujesz niestandardowej logiki routingu lub zachowania orkiestracji, których nie obsługuje Superwizor Agenta.

Klonowanie szablonu orkiestratora z wieloma agentami

Szablon orkiestratora z wieloma agentami udostępnia szkielet dla struktury projektu i logiki aranżacji przy użyciu zestawu SDK agentów OpenAI. Zawiera również pliki związane z umiejętnościami, które uczą asystentów programowania AI, jak projektować i rozwijać orkiestrator.

Sklonuj szablon i przejdź do folderu:

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

Konfigurowanie podagentów

Każde zaplecze, które może wywołać orkiestrator, jest definiowane jako subagent na SUBAGENTS liście agent_server/agent.py.

Usuń komentarz i skonfiguruj potrzebne wpisy. Zaktualizuj opis, aby bardziej szczegółowo przedstawić subagenta. Jakość opisu jest bezpośrednio związana z tym, jak skutecznie orkiestrator może kierować żądania do właściwego 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żdy wpis automatycznie staje się narzędziem, które może wywołać orkiestrator. Należy włączyć co najmniej jeden subagent.

W poniższej tabeli opisano każdy rodzaj podagenta:

Dostosowywanie orkiestratora

Agent orkiestratora jest tworzony w funkcji create_orchestrator_agent(). Zaktualizuj instrukcje, aby opisać określone narzędzia i kiedy należy używać każdego z nich:

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

Konfigurowanie zasobów i uprawnień

Określ zasoby wymagane przez orkiestratora w pliku databricks.yml. Każdy typ podrzędny wymaga własnego wpisu zasobu:

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'

Zaktualizuj wartości symboli zastępczych w pliku databricks.yml , aby odpowiadały podagentom skonfigurowanym w programie agent_server/agent.py.

Udzielanie orkiestratorowi dostępu do docelowej aplikacji usługi Databricks

Jeśli orkiestrator wywołuje aplikację usługi Databricks podrzędnej, musisz ręcznie przyznać jednostce usługi CAN_USE orkiestratora uprawnienie do aplikacji docelowej. Nie można zadeklarować tego uprawnienia jako zasobu pakietu i należy je zastosować po wdrożeniu.

1. Znajdź identyfikator klienta jednostki usługi aplikacji orkiestratora:

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

2. Nadaj zasadniczemu kontu usługi aplikacji orkiestratora CAN_USE uprawnienia do aplikacji docelowej.

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

Testowanie lokalne

Skonfiguruj środowisko lokalne i uruchom agenta:

uv run quickstart
uv run start-app

Skrypt quickstart konfiguruje uwierzytelnianie usługi Azure Databricks i tworzy eksperyment MLflow na potrzeby śledzenia. Po zakończeniu instalacji start-app uruchomi serwer agenta i interfejs użytkownika czatu pod adresem http://localhost:8000.

Wdrażanie w usłudze Databricks Apps

Wdróż orkiestrator przy użyciu pakietów deklaratywnej automatyzacji:

1. Zweryfikuj konfigurację pakietu:

   databricks bundle validate
   

2. Wdróż pakiet w obszarze roboczym:

   databricks bundle deploy
   

3. Uruchom aplikację:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Dodatkowe zasoby

Po wdrożeniu orkiestratora zapoznaj się z następującymi zasobami:

• Uruchamiaj agentów w aplikacjach Databricks z wykorzystaniem starszego serwera agentów
• Uwierzytelnianie agentów
• Debugowanie niestandardowego agenta kodu