Een systeem met meerdere agents bouwen in Databricks-apps

In plaats van één agent te bouwen die alles doet, stuurt een orchestrator met meerdere agents aanvragen naar gespecialiseerde subagenten vanaf één toegangspunt.

U kunt bijvoorbeeld een RAG-agent combineren waarmee ongestructureerde documenten worden opgevraagd met een Genie-agent die gestructureerde gegevens opvraagt, zodat gebruikers antwoorden krijgen uit meerdere bronnen.

De orchestrator behandelt elke subagent als een hulpprogramma en gebruikt de bijbehorende instructies om aanvragen naar de juiste te routeren. De orchestrator ondersteunt de volgende subagenttypen:

• Databricks Apps-agents: andere agents die zijn geïmplementeerd als Databricks-apps, aangeroepen via de Response-API.
• Genie Spaces: Vragen stellen in natuurlijke taal via de ingebouwde Azure Databricks MCP-server.
• Eindpunten leveren: Kennisassistenten, agents of modellen in Model Serving die ondersteuning bieden voor de Antwoorden-API.

Requirements

• De Databricks CLI is geïnstalleerd en geverifieerd. Voor app-naar-app-aanroepen is OAuth vereist. Zie De Databricks CLI installeren of bijwerken.
• Python 3.11 of hoger.
• De uv pakketbeheerder. Zie UV-installatie.
• Databricks-apps ingeschakeld in uw werkruimte. Zie Uw Databricks Apps-werkruimte en -ontwikkelomgeving instellen.
• Ten minste één subagent te orkestreren: een Genie Space, een Databricks-app, een kennisassistent of een dienend eindpunt.

Agent Supervisor eerst proberen

Voordat u een aangepaste orchestrator bouwt, kunt u supervisoragent gebruiken om een gecoördineerd multiagentsysteem te maken. Het bouwt en beheert het systeem met meerdere agents voor u via een gebruikersinterface. U kunt Genie Spaces, agenteindpunten, Unity Catalog-functies, MCP-servers en aangepaste agents verbinden en vervolgens de coördinatiekwaliteit in de loop van de tijd verbeteren met behulp van feedback van deskundigen in natuurlijke taal.

Bouw een systeem met meerdere agents in Databricks-apps als u aangepaste routeringslogica of indelingsgedrag nodig hebt dat Agent Supervisor niet ondersteunt.

De orchestratorsjabloon voor meerdere agents klonen

De orchestratorsjabloon met meerdere agents biedt de scaffolding voor projectstructuur- en indelingslogica met behulp van de OpenAI Agents SDK. Het bevat ook vaardigheidsbestanden die AI-coderingsassistenten leren hoe ze de orchestrator kunnen ontwikkelen.

Kloon de sjabloon en ga naar de map:

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

Subagents configureren

Elke back-end die de orchestrator kan aanroepen, wordt gedefinieerd als een subagent in de SUBAGENTS lijst in agent_server/agent.py.

Verwijder opmerkingen en configureer de items die u nodig hebt. Werk de beschrijving bij om de subagent gedetailleerder te beschrijven. De kwaliteit van de beschrijving is rechtstreeks gerelateerd aan hoe goed de orchestrator aanvragen naar de juiste subagent kan routeren:

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

Elke vermelding wordt automatisch een hulpprogramma dat de orchestrator kan aanroepen. U moet ten minste één subagent inschakelen.

In de volgende tabel wordt elk subagenttype beschreven:

De orchestrator aanpassen

De orchestratoragent wordt gemaakt in de create_orchestrator_agent() functie. Werk de instructies bij om uw specifieke hulpprogramma's te beschrijven en wanneer u elk hulpprogramma wilt gebruiken:

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

Resources en machtigingen configureren

Specificeer de resources die uw orchestrator nodig heeft in databricks.yml. Voor elk subagenttype is een eigen resourcevermelding vereist:

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'

Werk de tijdelijke aanduidingswaarden in databricks.yml bij zodat ze overeenkomen met de subagents die u hebt geconfigureerd in agent_server/agent.py.

Verleen de orchestrator toegang tot een Databricks-doeltoepassing.

Als uw orchestrator een Databricks-subagent-app aanroept, moet u de service-principal-machtiging CAN_USE van de orchestrator-app handmatig verlenen voor de doel-app. Deze machtiging kan niet worden gedeclareerd als een bundelresource en moet worden toegepast na de implementatie.

1. Zoek de client-ID van de service-principal van de orchestrator-applicatie:

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

2. Geef toestemming aan de service-principal CAN_USE van de orchestrator-app op de doel-app:

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

Lokaal testen

Stel uw lokale omgeving in en start de agent:

uv run quickstart
uv run start-app

Het quickstart script configureert Azure Databricks-verificatie en maakt een MLflow-experiment voor tracering. Na de installatie start-app start u de agentserver en een chatgebruikersinterface op http://localhost:8000.

Uitrollen naar Databricks Apps

Implementeer de orchestrator gebruikmakend van Declaratieve Automation Bundels:

1. Valideer de bundelconfiguratie:

   databricks bundle validate
   

2. Implementeer de bundel in uw werkruimte:

   databricks bundle deploy
   

3. Start de app:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Volgende stappen 

Nadat u uw orchestrator hebt geïmplementeerd, verkent u de volgende resources:

• Een AI-agent ontwerpen en implementeren in Databricks-apps
• Verificatie voor AI-agents
• Fouten opsporen in een geïmplementeerde AI-agent