Créez un système multi-agents sur Databricks Apps
Au lieu de construire un seul agent qui fait tout, un orchestrateur multi-agents achemine les requêtes vers des sous-agents spécialisés à partir d'un seul point d'entrée.
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 de plusieurs sources.
L'orchestrateur traite chaque sous-agent comme un outil et utilise ses instructions pour acheminer les requêtes vers le bon. L'orchestrateur prend en charge les types de sous-agents suivants :
- **Agents Databricks Apps** : Autres agents déployés en tant qu'applications Databricks Apps, appelés via l'API de réponses.
- Agents Genie : interrogation de données en langage naturel via le serveur MCP Databricks intégré.
- Endpoints de service : assistants de connaissances, agents ou modèles sur Model Serving qui prennent en charge l'API des réponses.
Exigences
- La CLI de Databricks est installée et authentifiée. Les appels d'application à application nécessitent OAuth. Consultez Installer ou mettre à jour la CLI Databricks.
- Python 3.11 ou version(s) ultérieure(s).
- Le gestionnaire de packages
uv. Voir l'installation uv. - Les Databricks Apps sont activées dans votre Workspace. Consultez Configurer votre Workspace et environnement de développement Databricks Apps.
- Au moins un sous-agent à orchestrer : un Genie Agent, une autre application Databricks, un assistant de connaissances ou un endpoint de service.
Essayez d'abord Agent Supervisor
Avant de créer un orchestrateur personnalisé, envisagez d'utiliser l'agent superviseur pour créer un système multi-agents coordonné. Il crée et gère le système multi-agents pour vous via une interface utilisateur. Vous pouvez connecter des agents Genie, des Endpoints d'agent, des fonctions Unity Catalog, des serveurs MCP et des agents personnalisés, puis améliorer la qualité de la coordination au fil du temps en utilisant les commentaires en langage naturel d'experts en la matière.
Créez un système multi-agents sur Databricks Apps si vous avez besoin d'une logique de routage personnalisée ou d'un comportement d'orchestration que le Superviseur d'agent ne prend pas en charge.
Clonez le template d'orchestrateur multi-agents
Le template d'orchestrateur multi-agent fournit le cadre pour la structure du projet et la logique d'orchestration à l'aide du SDK OpenAI Agents. Il comprend également des fichiers de compétences qui enseignent aux assistants de code IA comment développer l'orchestrateur.
Cloner le template et accédez au dossier :
git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk-multiagent
Configurer les sous-agents
Chaque backend que l'orchestrateur peut appeler est défini comme un sous-agent dans la liste SUBAGENTS de agent_server/agent.py.
Décommentez et configurez les entrées dont vous avez besoin. Modifiez la description pour décrire le sous-agent plus en détail. La qualité de la description est directement liée à la capacité de l'orchestrateur à acheminer les requêtes vers le bon sous-agent :
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."
),
},
]
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 :
Type | Comment il se connecte | Exigences |
|---|---|---|
| Réponses API via | Authentification OAuth, |
| Serveur MCP Databricks intégré | ID de Genie Agent, |
| API de réponses via le nom de l'endpoint | L'Endpoint doit avoir le type de tâche Agent (Réponses) sur l'interface utilisateur de Model Serving. Inclut les assistants de connaissances, les agents et les modèles. |
Personnaliser l'orchestrateur
L'agent d'orchestration est créé dans la fonction create_orchestrator_agent(). 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,
)
Plus les instructions de l'orchestrateur sont spécifiques, plus il achemine les requêtes avec précision. Décrivez l'objectif de chaque outil et les types de questions qu'il traite.
Configurez les ressources et les autorisations.
Déclarez les ressources dont votre orchestrateur a besoin dans databricks.yml. Chaque type de sous-agent nécessite sa propre entrée de ressource :
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'
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.
Accordez à l'orchestrateur l'accès à une application Databricks cible
Si votre orchestrateur appelle une application Databricks sous-agent, vous devez accorder manuellement l'autorisation CAN_USE du Service Principal de l'application orchestrateur sur l'application cible. Cette autorisation ne peut pas être déclarée comme ressource de bundle et doit être appliquée après le déploiement.
Le champ service_principal_name dans la requête d'autorisations doit être l'ID client (UUID) du Service Principal, et non le nom d'affichage. L'utilisation du nom d'affichage réussit en silence, mais n'accorde pas l'autorisation. La commande databricks apps get renvoie cette valeur en tant que service_principal_client_id.
-
Recherchez l’ID client du Service Principal de l’application d’orchestration :
Bashdatabricks apps get <YOUR-ORCHESTRATOR-APP-NAME> --output json | jq -r '.service_principal_client_id' -
Accorder au Service Principal de l’application d’orchestration l’autorisation
CAN_USEsur l’application cible :Bashdatabricks 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 start l’agent :
uv run quickstart
uv run start-app
Le script quickstart configure l'authentification Databricks et crée une expérience MLflow pour le traçage. Après la configuration, start-app lance le serveur d'agent et une interface utilisateur de chat à l'adresse http://localhost:8000.
Déployer sur Databricks Apps
Déployez l'orchestrateur à l'aide de Declarative Automation Bundles:
-
Validez la configuration du bundle :
Bashdatabricks bundle validate -
Déployez le bundle dans votre Workspace :
Bashdatabricks bundle deploy -
start l’application :
Bashdatabricks bundle run agent_openai_agents_sdk_multiagent
bundle deploy upload files but doesn't start l’application. Exécutez bundle run pour start l’application.
Ressources supplémentaires
Après le déploiement de votre orchestrateur, explorez les ressources suivantes :