Construire un système multi-agent sur Databricks Apps
Au lieu de créer un seul agent qui fait tout, un orchestrateur multi-agents 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 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 Responses.
- Genie Agents : Interrogation de données en langage naturel via le serveur MCP Databricks intégré.
- Endpoint de service : Assistants de connaissances, agents ou modèles sur Model Serving qui prennent en charge l'API Réponses.
Exigences
- La CLI 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 ultérieure.
- Le gestionnaire de packages
uv. Consultez l'installation uv. - Databricks Apps activées dans votre Workspace. Consultez Configurez votre Workspace Databricks Apps et votre environnement de développement.
- Au moins un sous-agent à orchestrer : un Genie Agent, une autre Databricks App, un assistant de connaissances ou un endpoint de service.
Essayez d'abord Agent Supervisor
Avant de créer un orchestrateur personnalisé, veuillez considérer l’utilisation d’un agent superviseur pour créer un système multi-agent coordonné. Il conçoit et gère pour vous le système multi-agents via une interface utilisateur. Vous pouvez connecter des agents Genie, des Endpoint 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.
Développez 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 l'Agent Supervisor ne prend pas en charge.
Clonez le template d'orchestrateur multi-agents
Le template d'orchestrateur multi-agents fournit la structure de projet et la logique d'orchestration à l'aide de l'OpenAI Agents SDK. Il comprend également des fichiers de compétences qui enseignent aux assistants de codage d'IA comment développer l'orchestrateur.
Clonez 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. Mettez à jour 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 sous-agent correct :
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 de l'API via | Authentification OAuth, autorisation |
| Serveur MCP Databricks intégré | Genie Agent ID, |
| API de réponses via le nom d'endpoint | L'Endpoint doit avoir le type de tâche Agent (Réponses) sur l'interface utilisateur de service. Comprend 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'entre 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.
Configurer 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.
Accorder à l'orchestrateur l'accès à une application Databricks cible
Si votre orchestrateur appelle une application Databricks de sous-agent, vous devez accorder manuellement au Service Principal de l'application orchestratrice l'autorisation CAN_USE sur l'application cible. Cette autorisation ne peut pas être déclarée comme une ressource de bundle et doit être appliquée après le déploiement.
Le champ service_principal_name dans la demande 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 silencieusement mais n'accorde pas l'autorisation. La commande databricks apps get renvoie cette valeur sous la forme de service_principal_client_id.
-
Recherchez l'ID client du service principal de l'application orchestrateur :
Bashdatabricks apps get <YOUR-ORCHESTRATOR-APP-NAME> --output json | jq -r '.service_principal_client_id' -
Accordez l'autorisation
CAN_USEau Service Principal de l'application orchestratrice sur l'application cible :Bashdatabricks apps update-permissions <TARGET-APP-NAME> \
--json '{"access_control_list": [{"service_principal_name": "<SP-CLIENT-ID>", "permission_level": "CAN_USE"}]}'
Testez 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érimentation MLflow pour le traçage. Après la configuration, start-app lance le serveur d'agent et une interface utilisateur de chat à http://localhost:8000.
Déployer sur Databricks Apps
Déployer l’orchestrateur à l’aide de Declarative Automation Bundles:
-
Validez la configuration du bundle :
Bashdatabricks bundle validate -
Déployez le bundle sur votre workspace :
Bashdatabricks bundle deploy -
start l’application :
Bashdatabricks bundle run agent_openai_agents_sdk_multiagent
bundle deploy uploads les fichiers mais ne start pas l’application. Exécutez bundle run pour start l'application.
Ressources supplémentaires
Après avoir déployé votre orchestrateur, explorez les Ressources suivantes :