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 Spaces: Wykonywanie zapytań dotyczących danych języka naturalnego za pośrednictwem wbudowanego serwera MCP Azure Databricks.
  • Obsługa punktów końcowych: Asystenci wiedzy, agenci lub modele w usłudze Model Serving, które obsługują interfejs API odpowiedzi.

Wymagania

Najpierw wypróbuj Agent Supervisor.

Przed utworzeniem niestandardowego orkiestratora rozważ utworzenie skoordynowanego systemu wielo agenta za pomocą agenta nadzorcy. Kompiluje system z wieloma agentami i zarządza nim za pośrednictwem interfejsu użytkownika. Możesz połączyć Genie Spaces, punkty końcowe agentów, funkcje Unity Catalog, serwery MCP i agentów niestandardowych, a następnie z czasem poprawić jakość koordynacji, korzystając z opinii ekspertów merytorycznych wyrażonych w języku naturalnym.

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

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:

Typ Jak się łączy Wymagania
app Interfejs API odpowiedzi za pośrednictwem apps/<name> Uwierzytelnianie OAuth, CAN_USE uprawnienie dla aplikacji docelowej
genie Wbudowany serwer MCP usługi Azure Databricks Genie Space ID, CAN_RUN uprawnienia
serving_endpoint API Odpowiedzi przez nazwę punktu końcowego Punkt końcowy musi mieć typ zadania Agent (odpowiedzi) w interfejsie obsługi. Obejmuje asystentów wiedzy, agentów i modeli.

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

Wskazówka

Bardziej szczegółowe instrukcje orkiestratora, tym dokładniej kieruje żądania. Opisz przeznaczenie każdego narzędzia i typy pytań, które obsługuje.

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 Space'
      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.

Uwaga / Notatka

Pole service_principal_name w żądaniu uprawnień musi być identyfikatorem klienta jednostki usługi (UUID), a nie nazwą wyświetlaną. Użycie nazwy wyświetlanej w trybie dyskretnym kończy się powodzeniem, ale nie przyznaje uprawnień. Polecenie databricks apps get zwraca tę wartość jako service_principal_client_id.

  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

Ważna

bundle deploy przekazuje pliki, ale nie uruchamia aplikacji. Uruchom polecenie bundle run , aby uruchomić aplikację.

Następne kroki

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

  • Last updated on