Créer un système multi-agent sur Databricks Apps

Au lieu de créer un agent qui effectue tout, un orchestrateur multi-agent achemine les requêtes vers des sous-agents spécialisés à partir d’un point d’entrée unique.

Par exemple, vous pouvez combiner un agent RAG qui interroge des documents non structurés avec un agent Genie qui interroge des données structurées, afin que les utilisateurs obtiennent des réponses à partir de plusieurs sources.

L’orchestrateur traite chaque sous-agent comme un outil et utilise ses instructions pour diriger les demandes vers le bon. L’orchestrateur prend en charge les types de sous-éléments suivants :

• Agents Databricks Apps : d’autres agents déployés en tant qu’applications Databricks, appelés via l’API Réponses.
• Genie Spaces : interrogation de données en langage naturel via le serveur mcP intégré Azure Databricks.
• Points de terminaison de service : Assistants de connaissances, agents ou modèles sur Model Serving qui prennent en charge l’API Réponses.

Exigences

• L’interface CLI Databricks installée et authentifiée. Les appels d’application à application nécessitent OAuth. Consultez Installer ou mettre à jour l’interface CLI Databricks.
• Python 3.11 ou version ultérieure.
• Gestionnaire de paquet uv. Voir l’installation uv.
• Databricks Apps activées dans votre espace de travail. Consultez Configurer votre espace de travail Databricks Apps et votre environnement de développement.
• Au moins un sous-agent à orchestrer : un espace Genie, une autre application Databricks, un assistant intelligent ou un point de terminaison de service.

Essayez d'abord le gestionnaire d'agent

Avant de créer un orchestrateur personnalisé, envisagez d’utiliser l’agent superviseur pour créer un système multi-agent coordonné. Il génère et gère le système multi-agent pour vous via une interface utilisateur. Vous pouvez connecter Genie Spaces, les points de terminaison d’agent, les fonctions du catalogue Unity, les serveurs MCP et les agents personnalisés, et améliorer la qualité de la coordination au fil du temps à l’aide de commentaires en langage naturel provenant d’experts en la matière.

Créez un système multi-agent sur Databricks Apps si vous avez besoin d’une logique de routage personnalisée ou d’un comportement d’orchestration que le superviseur de l’agent ne prend pas en charge.

Cloner le modèle d’orchestrateur multi-agent

Le modèle d’orchestrateur multi-agent fournit la structure de projet et la logique d’orchestration à l’aide du Kit de développement logiciel (SDK) Des agents OpenAI. Il inclut également des fichiers de compétences qui enseignent aux assistants de codage IA comment développer l’orchestrateur.

Clonez le modèle et accédez au dossier :

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

Configurer des sous-agents

Chaque back-end que l’orchestrateur peut appeler est défini en tant que sous-agent dans la SUBAGENTS liste dans agent_server/agent.py.

Supprimez les commentaires et configurez les entrées dont vous avez besoin. Mettez à jour la description pour décrire le sous-composant plus en détail. La qualité de la description est directement liée à la façon dont l’orchestrateur peut acheminer les demandes vers le sous-agent correct.

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

Chaque entrée devient automatiquement un outil que l’orchestrateur peut appeler. Vous devez activer au moins un sous-agent.

Le tableau suivant décrit chaque type de sous-agent :

Personnaliser l’orchestrateur

L’agent d’orchestrateur est créé dans la create_orchestrator_agent() fonction. Mettez à jour les instructions pour décrire vos outils spécifiques et quand utiliser chacun d’eux :

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

Configurer des ressources et des autorisations

Déclarez les ressources dont votre orchestrateur a besoin dans databricks.yml. Chaque type de sous-agent requiert sa propre entrée de ressource :

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'

Mettez à jour les valeurs d’espace réservé dans databricks.yml pour qu’elles correspondent aux sous-agents que vous avez configurés dans agent_server/agent.py.

Accorder à l’orchestrateur l’accès à une application Databricks cible

Si votre orchestrateur appelle une application Databricks subagente, vous devez accorder manuellement l’autorisation du principal CAN_USE de service de l’application orchestrator sur l’application cible. Cette autorisation ne peut pas être déclarée en tant que ressource groupée et doit être appliquée après le déploiement.

1. Recherchez l’ID client du principal de service de l’application orchestrator :

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

2. Accordez au principal du service de l'application orchestrator l'autorisation sur l'application cible :

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

Tester localement

Configurez votre environnement local et démarrez l’agent :

uv run quickstart
uv run start-app

Le quickstart script configure l’authentification Azure Databricks et crée une expérience MLflow pour le suivi. Après l’installation, start-app lance le serveur d’agent et une interface utilisateur de conversation à l’adresse http://localhost:8000.

Déployer sur Databricks Apps

Déployez l’orchestrateur à l’aide des bundles d’automatisation déclaratifs :

1. Validez la configuration de l’offre groupée :

   databricks bundle validate
   

2. Déployez l’offre groupée sur votre espace de travail :

   databricks bundle deploy
   

3. Démarrez l’application :

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Étapes suivantes

Après avoir déployé votre orchestrateur, explorez les ressources suivantes :

• Créer un agent IA et le déployer sur Databricks Apps
• Authentification pour les agents IA
• Déboguer un agent IA déployé