Aller au contenu principal
Dernière mise à jour le

Créez un agent IA et déployez-le sur Databricks Apps

Créez un agent IA et déployez-le à l'aide de Databricks Apps. Databricks Apps vous offre un contrôle total sur le code de l'agent, la configuration du serveur et le workflow de déploiement. Cette approche est idéale lorsque vous avez besoin d'un comportement de serveur personnalisé, d'une gestion de version basée sur Git ou d'un développement local IDE.

astuce

Si votre agent utilise uniquement les outils hébergés par Databricks et n'a pas besoin de logique personnalisée entre les appels d'outils, vous pouvez utiliser l'API Supervisor (bêta) pour laisser Databricks gérer la boucle d'agent pour vous.

Aperçu de l'interface utilisateur de discussion d'agent

Chaque Template d'agent conversationnel comprend une interface utilisateur de chat intégré (illustrée ci-dessus) sans configuration supplémentaire requise. L’interface utilisateur de chat prend en charge les réponses de streaming, le rendu markdown, l’authentification Databricks et l’historique de chat persistant facultatif.

Exigences​

Activez les Databricks Apps dans votre Workspace. Consultez Configurez votre Workspace Databricks Apps et votre environnement de développement.

Étape 1. Cloner le template d'application d'agent​

Commencez par utiliser un template d'agent pré-construit du repository de templates d'applications Databricks.

Ce tutoriel utilise le Template agent-openai-agents-sdk, qui inclut :

  • Un agent créé à l'aide du SDK d'agent OpenAI
  • Code de démarrage pour une application d'agent avec une API REST conversationnelle et une interface utilisateur de chat interactive.
  • Code pour évaluer l'agent avec MLflow

Choisissez l’un des chemins suivants pour configurer le Template :

Installez le Template d'application à l'aide de l'interface utilisateur de Workspace. Ceci installe l'application et la déploie sur une ressource de compute dans votre Workspace. Vous pouvez ensuite synchroniser les fichiers de l'application avec votre environnement local pour un développement ultérieur.

  1. Dans votre workspace Databricks, cliquez sur + Nouveau > Application .

  2. Cliquez sur **Agents** > **Agent personnalisé (OpenAI SDK)**.

  3. Créez une nouvelle Expérimentation MLflow avec le nom openai-agents-template et complétez le reste de la configuration pour installer le Template.

  4. Après avoir créé l'application, cliquez sur l'URL de l'application pour ouvrir l'interface utilisateur de discussion.

Après avoir créé l’application, download le code source sur votre machine locale pour la personnaliser :

  1. Copiez la première commande sous Synchroniser les fichiers

    Synchroniser les fichiers Databricks Apps

  2. Dans un terminal local, exécutez la commande copiée.

Étape 2. Comprendre l'application de l'agent​

Le Template d'agent présente une architecture prête pour la production avec ces composants clés. Ouvrez les sections suivantes pour plus de détails sur chaque composant :

Diagramme simple d'agent sur application

Ouvrez les sections suivantes pour plus de détails sur chaque composant :

Icône de Chat Interface utilisateur de chat intégrée

Le Template d'agent récupère et exécute automatiquement le Template d'application de chat comme interface utilisateur. Cette interface utilisateur de chat est incluse dans le même déploiement Databricks Apps et servie aux côtés de votre agent, il n'y a donc pas de configuration supplémentaire requise.

Vous pouvez personnaliser l'interface utilisateur du chat directement dans votre projet. Pour plus de détails sur les fonctionnalités de l'application de chat, y compris comment activer l'historique de chat persistant et la collecte des retours utilisateur, consultez Créez et partagez une interface utilisateur de chat avec Databricks Apps.

Icône de puce. MLflow AgentServer

Un serveur FastAPI asynchrone qui gère les requêtes d'agent avec traçage et observabilité intégrés. L'AgentServer fournit l'endpoint /responses pour interroger votre agent et gère automatiquement l'acheminement des requêtes, la journalisation et la gestion des erreurs.

Icône de crochets carré. interfaceResponsesAgent

Databricks recommande MLflow ResponsesAgent pour créer des agents. ResponsesAgent vous permet de créer des agents avec n’importe quel framework tiers, puis de l’intégrer aux fonctionnalités de Databricks AI pour des capacités de journalisation, de traçabilité, d’évaluation, de déploiement et de monitoring robustes.

ResponsesAgent enveloppe facilement les agents existants pour la compatibilité Databricks.

Pour savoir comment créer un ResponsesAgent, consultez les exemples dans la documentation MLflow - ResponsesAgent pour Model Serving.

ResponsesAgent offre les avantages suivants :

  • Capacités d'agent avancées

    • Prise en charge multi-agents
    • Sortie en streaming : diffusez la sortie par petits fragments.
    • Historique complet des messages d'appels d'outils : renvoie plusieurs messages, y compris les messages d'appels d'outils intermédiaires, pour une qualité et une gestion de conversation améliorées.
    • Prise en charge de la confirmation de l'appel d'outil
    • Support des outils à exécution longue

  • Développement, déploiement et monitoring rationalisés

    • Créer des agents à l'aide de n'importe quel framework : Encapsulez tout agent existant à l'aide de l'interface ResponsesAgent pour obtenir une compatibilité prête à l'emploi avec AI Playground, Agent Evaluation et le Monitoring d'Agent.
    • Interfaces de création typées : Écrivez du code d'agent en utilisant des classes Python typées, en bénéficiant de la complétion automatique de l'IDE et des Notebooks.
    • Traçage automatique : MLflow agrège automatiquement les réponses Stream dans des traces pour faciliter l'évaluation et l'affichage.
    • Compatible avec le schéma Responses d'OpenAI : voir OpenAI : Réponses vs. ChatCompletion.

Icône de robot. SDK OpenAI Agents

Le Template utilise le SDK OpenAI Agents comme framework d'agent pour la gestion des conversations et l'orchestration d'outils. Vous pouvez créer des agents à l'aide de n'importe quel framework. La clé est d'envelopper votre agent avec l'interface MLflow ResponsesAgent.

Icône Mcp. Serveurs MCP (Model Context Protocol)

Le Template se connecte aux serveurs MCP Databricks pour donner aux agents l'accès aux outils et aux sources de données. Consultez Model Context Protocol (MCP) sur Databricks.

Créez des agents à l'aide d'assistants de code IA​

Databricks recommande d'utiliser des assistants de codage basés sur l'IA tels que Claude, Cursor et Copilot pour créer des agents. Utilisez les compétences d'agent fournies, dans /.claude/skills, et le fichier AGENTS.md pour aider les assistants d'IA à comprendre la structure du projet, les outils disponibles et les bonnes pratiques. Les agents peuvent lire automatiquement ces fichiers pour développer et déployer les Databricks Apps.

Étape 3. Ajoutez des outils à votre agent​

Conférez à votre agent des fonctionnalités telles que l’interrogation de bases de données, la recherche de documents ou l’appel d’APIs externes en le connectant aux serveurs MCP. Le Template d’agent comprend une connexion de serveur MCP par default. Pour ajouter d’autres outils, configurez des serveurs MCP supplémentaires dans le code de votre agent et accordez les autorisations requises dans databricks.yml.

Consultez Connecter des agents à des outils pour connaître les types d'outils pris en charge et des exemples de code.

Définir des outils de fonction Python locaux​

Pour les opérations qui ne nécessitent pas de sources de données externes ou d'APIs, définissez les outils directement dans le code de votre agent. Ces outils s'exécutent dans le même processus que votre agent et sont utiles pour les transformations de données, les calculs ou les opérations d'infrastructures publiques.

Utilisez le décorateur @function_tool du SDK OpenAI Agents :

Python
from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

Les outils de fonction locaux ne nécessitent pas d'octrois de ressources dans databricks.yml car ils s'exécutent au sein du processus de l'agent.

Étape 4. Gouvernez l'utilisation des LLM de vos agents sur Databricks Apps avec Unity AI Gateway​

Acheminez les appels LLM de votre agent via Unity AI Gateway (Beta) afin que chaque requête soit régie par les mêmes contrôles, quel que soit le fournisseur qui y répond. Avec la passerelle dans le chemin de la requête, vous pouvez centraliser les autorisations, attribuer les coûts par application, échanger les modèles, et inspecter ou rejouer le trafic sans modifier le code de l'agent ou faire pivoter les informations d'identification du fournisseur.

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs du Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Previews . Consultez Gérer les aperçus Databricks.

  1. Activez Unity AI Gateway sur votre Workspace. Unity AI Gateway est disponible sur inscription pendant la phase Bêta. Un administrateur de compte doit l'activer depuis la page **Aperçus** de la console de compte avant que vous ne puissiez créer ou query des Endpoint de passerelle. Voir Gérer les aperçus Databricks.

  2. Pointez votre agent vers un Endpoint de passerelle Unity AI. Dans le code de votre agent, passez le nom de l'Endpoint Unity AI Gateway comme argument model et définissez use_ai_gateway=True sur le client LLM Databricks. Le client achemine le trafic via la passerelle et gère automatiquement l'authentification.

Python
from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)

Pour d'autres surfaces d'API (OpenAI Responses API, Anthropic Messages API, Google Gemini) et des exemples REST, consultez Requêter les services de modèle.

Sujets de création avancés​

Réponses de streaming

Réponses en streaming​

Le streaming permet aux agents d'envoyer des réponses par blocs en temps réel au lieu d'attendre la réponse complète. Pour implémenter le streaming avec ResponsesAgent, émettez une série d'événements delta suivie d'un événement d'achèvement final :

  1. Émettre des événements delta : Envoyez plusieurs Stream avec le output_text.delta même item_id pour diffuser des blocs de texte en temps réel.
  2. Terminer avec l'événement terminé : Envoyez un événement final response.output_item.done avec le même item_id que les événements delta contenant le texte de sortie final complet.

Chaque événement delta Stream un segment de texte au client. L’événement « done » final contient le texte de réponse complet et signale à Databricks de faire ce qui suit :

  • Tracez la sortie de votre agent avec le traçage MLflow
  • Agréger les réponses Stream dans les tables d'inférence Unity AI Gateway
  • Afficher le résultat complet dans l’interface utilisateur d’AI Playground

Propagation des erreurs de streaming

Databricks propage toutes les erreurs rencontrées lors du streaming avec le dernier jeton sous databricks_output.error. Il appartient au client appelant de gérer et de faire remonter correctement cette erreur.

Bash
{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Entrées et sorties personnalisées

Entrées et sorties personnalisées​

Certains scénarios peuvent nécessiter des entrées d'agent supplémentaires, telles que client_type et session_id, ou des sorties comme des liens vers la source de récupération qui ne devraient pas être inclus dans l'historique de chat pour les interactions futures.

Pour ces scénarios, MLflow ResponsesAgent prend en charge en mode natif les champs custom_inputs et custom_outputs. Vous pouvez accéder aux entrées personnalisées via request.custom_inputs dans les exemples de frameworks ci-dessus.

L'application de révision Agent Evaluation ne prend pas en charge le rendu des traces pour les agents avec des champs de saisie supplémentaires.

Fournissez custom_inputs dans l'AI Playground et examinez l'application.

Si votre agent accepte des entrées supplémentaires à l'aide du champ custom_inputs, vous pouvez fournir manuellement ces entrées à la fois dans l'AI Playground et dans l'application de révision.

  1. Dans l'AI Playground ou l'application Agent Review, sélectionnez l'icône d'engrenage Icône d&#39;engrenage..

  2. Activer custom_inputs .

  3. Fournissez un objet JSON qui correspond au schéma d'entrée défini de votre agent.

    Fournissez des entrées personnalisées dans l&#39;AI Playground.

Étape 5. Exécuter l'application agent localement​

Configurez votre environnement local :

  1. Installez uv (gestionnaire de packages Python), nvm (gestionnaire de versions Node), et la CLI Databricks :

  2. Changez de répertoire vers le dossier agent-openai-agents-sdk.

  3. Exécutez les scripts de démarrage rapide fournis pour installer les dépendances, configurer votre environnement et start l'application.

    Bash
    uv run quickstart
    uv run start-app

Dans un navigateur, rendez-vous sur http://localhost:8000 pour ouvrir l'interface utilisateur de chat intégrée et start à discuter avec l'agent.

Étape 6. Configurer l'authentification​

Votre agent a besoin d'une authentification pour accéder aux Ressources Databricks. Databricks Apps fournit deux méthodes d'authentification : autorisation d'application (Service Principal) et autorisation utilisateur (au nom de l'utilisateur). Vous pouvez configurer l'un ou l'autre via l'interface utilisateur du Workspace ou de manière déclarative dans databricks.yml avec les Declarative Automation Bundles. Les Template d'agent sont livrés avec un databricks.yml, ce chemin est donc le default lorsque vous start depuis un Template.

Pour la référence complète, incluant tous les types de ressources pris en charge, les valeurs d'autorisation et une présentation de bout en bout databricks.yml, consultez Authentification pour les agents d'IA.

L'autorisation d'application utilise un Service Principal que Databricks crée automatiquement pour votre application. Tous les utilisateurs partagent les mêmes autorisations.

Déclarez chaque Ressource que l'agent utilise sous resources.apps.<app>.resources dans databricks.yml. Déployez le bundle pour accorder au service principal les autorisations déclarées :

YAML
resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'
Bash
databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Pour la liste complète des types de ressources, consultez Autorisation de l'application.

Étape 7. Évaluer l'agent​

Le Template inclut le code d'évaluation d'agent. Voir agent_server/evaluate_agent.py pour plus d'informations. Évaluez la pertinence et la sécurité des réponses de votre agent en exécutant ce qui suit dans un terminal :

Bash
uv run agent-evaluate

Étape 8. Déployez l'agent vers Databricks Apps​

Après avoir configuré l'authentification, déployez votre agent sur Databricks. Les templates d'agent utilisent les Databricks Asset Bundles (DABs) pour le déploiement. Le fichier databricks.yml dans le Template définit la configuration de l'application et les permissions des Ressources. Assurez-vous que le Databricks CLI est installé et configuré.

remarque

Si vous avez créé votre application via l'interface utilisateur du Workspace à l'étape 1, exécutez databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve avant de déployer pour lier l'application existante à votre bundle. Sinon, databricks bundle deploy échoue avec « Une application portant le même nom existe déjà ».

  1. Validez la configuration du bundle afin de détecter les erreurs avant le déploiement :

    Bash
    databricks bundle validate

  2. Déployez le bundle. Ceci upload votre code et configure les Ressources (Expérimentation MLflow, Endpoint de service, etc.) définies dans databricks.yml:

    Bash
    databricks bundle deploy

  3. Start ou redémarrez l’application :

    Bash
    databricks bundle run agent_openai_agents_sdk
remarque

bundle deploy ne fait qu'upload les fichiers et configure les Ressources. bundle run est nécessaire pour start ou restart l'application avec le nouveau code.

Pour les futures mises à jour, exécutez databricks bundle deploy, puis databricks bundle run agent_openai_agents_sdk pour redéployer.

Étape 9. Query l'agent déployé​

L'exemple suivant utilise une requête curl rapide avec un jeton OAuth. Les jetons d'accès personnels (PAT) ne sont pas pris en charge pour les Databricks Apps.

Pour la liste complète des méthodes de query, y compris le client Databricks OpenAI et l'API REST, consultez Interroger un agent déployé sur Databricks.

Générer un jeton OAuth à l’aide de l’interface CLI Databricks :

Bash
databricks auth login --host <https://host.databricks.com>
databricks auth token

Utilisez le token pour query l'agent :

Bash
curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Comprendre les signatures de modèle pour garantir la compatibilité avec les fonctionnalités Databricks​

Databricks utilise les Signatures de modèle MLflow pour définir le schéma d'entrée et de sortie des agents. Les fonctionnalités du produit comme l'AI Playground supposent que votre agent dispose d'un ensemble de signatures de modèle prises en charge.

Si vous suivez l'approche recommandée pour la création d'agents à l'aide de l'interface ResponsesAgent, MLflow inférera automatiquement une signature pour votre agent qui est compatible avec les fonctionnalités produit de Databricks.

Limitations​

Étapes suivantes​

Une fois que votre agent fonctionne en développement, mettez-le en production. Consultez Produire votre agent Databricks Apps pour connaître la séquence recommandée : CI/CD, tests de charge, puis Unity AI Gateway.

Sur cette page