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 d'IA et déployez-le à l'aide de Databricks Apps. Databricks Apps vous donne 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'un contrôle de version basé sur Git ou d'un développement IDE local.

astuce

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

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

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

Exigences​

Activez Databricks Apps dans votre workspace. Consultez Configurer votre Workspace et environnement de développement Databricks Apps.

Étape 1. Clonez le Template d'application d'agent​

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

Ce tutoriel utilise le template agent-openai-agents-sdk, qui comprend :

  • Un agent créé à l'aide d'OpenAI Agent SDK
  • 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 à l'aide de MLflow

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

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

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

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

  3. Créer une nouvelle experimentation MLflow avec le nom openai-agents-template et finaliser la configuration pour installer le template.

  4. Une fois l'application créée, 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 le personnaliser :

  1. Copier 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 agent​

Le agent Template démontre 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 de l'agent sur l'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 en tant que son frontend. Cette interface utilisateur de chat est intégrée au même déploiement Databricks Apps et est servie avec votre agent, donc aucune configuration supplémentaire n'est requise.

Vous pouvez personnaliser l'interface utilisateur de 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 des utilisateurs, consultez Créer et partager 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 le traçage et l'observabilité intégrés. L'AgentServer fournit l'/responses endpoint pour interroger votre agent et gère automatiquement le routage des requêtes, la journalisation et la gestion des erreurs.

Icône de parenthèses carrées. 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 Databricks AI pour des capacités robustes de journalisation, de traçage, d'évaluation, de déploiement et de monitoring.

RéponsesAgent permet d'envelopper facilement les agents existants pour la compatibilité Databricks.

Pour apprendre à créer un ResponsesAgent, consultez les exemples dans la documentation MLflow - RéponsesAgent pour Model Serving.

ResponsesAgent offre les avantages suivants :

  • Capacités d'agent avancées

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

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

    • Créez des agents à l’aide de n’importe quel framework : enveloppez tout agent existant à l’aide de l’interface ResponsesAgent pour bénéficier d’une compatibilité prête à l’emploi avec AI Playground, Agent Evaluation et le monitoring des agents.
    • Interfaces d'édition typées : rédigez du code d'agent à l'aide de classes Python typées, en bénéficiant de l'autocomplétion des IDE et notebooks.
    • Traçage automatique : MLflow agrège automatiquement les réponses diffusées en continu en traces pour une évaluation et un affichage plus faciles.
    • Compatible avec le schéma OpenAI Responses : Voir OpenAI : réponses vs ChatCompletion.

Icône de robot. SDK OpenAI Agents

Le Template utilise le SDK OpenAI Agents comme framework d'agents pour la gestion des conversations et l'orchestration des outils. Vous pouvez créer des agents en utilisant 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 de Databricks pour donner aux agents l'accès aux outils et aux sources de données. Voir Model Context Protocol (MCP) sur Databricks.

Créer des agents à l’aide d’assistants de codage IA​

Databricks recommande d'utiliser des assistants de codage 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 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​

Donnez à votre agent des capacités comme l'interrogation de bases de données, la recherche de documents ou l'appel d'APIs externes en le connectant à des serveurs MCP. Le Template d'agent inclut 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 aux outils pour connaître les types d'outils pris en charge et les 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 utilitaires.

Utilisez le décorateur @function_tool de l'SDK OpenAI :

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. Gérer l'utilisation des LLM par vos agents sur Databricks Apps avec Unity AI Gateway​

Acheminez les appels LLM de votre agent via la passerelle IA Unity (Bêta) 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 le coût par application, échanger des modèles et inspecter ou rejouer le trafic sans modifier le code de l’agent ni faire tourner les identifiants du fournisseur.

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs de Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Aperçus . Voir Gérer les prévisualisations Databricks.

  1. Activez Unity AI Gateway sur votre Workspace. La Passerelle d'IA Unity est sur inscription pendant la version bêta. Un administrateur de compte doit l'activer depuis la page Prévisualisations de la console de compte avant que vous puissiez créer ou query des endpoints de passerelle. Consultez la gestion des prévisualisations Databricks.

  2. Dirigez votre agent vers un Endpoint Unity AI Gateway. Dans votre code d’agent, transmettez le nom de l’Endpoint Unity AI Gateway en tant qu’argument model et définissez use_ai_gateway=True sur le client Databricks LLM. 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 les surfaces API supplémentaires (OpenAI Responses API, Anthropic Messages API, Google Gemini) et les exemples REST, consultez Interroger les services de modèles.

Sujets de création avancés​

Réponses en 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 de finalisation :

  1. Émettre des événements delta : Envoyez plusieurs événements output_text.delta avec le même item_id pour stream des fragments de texte en temps réel.
  2. Terminer par l'événement d'achèvement : envoyez un événement response.output_item.done final 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 vers le client. L'événement final terminé 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 de l'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 signaler 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 de source de récupération qui ne devraient pas être inclus dans l'historique de discussion 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 framework ci-dessus.

L'application d'examen Agent Evaluation ne prend pas en charge l'affichage des traces pour les agents avec des champs de saisie supplémentaires.

Fournir custom_inputs dans l'AI Playground et l'application d'évaluation

Si votre agent accepte des entrées supplémentaires en utilisant le 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 d'examen d'agent, 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 custom_inputs dans l&#39;AI Playground.

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

Configurez votre environnement local :

  1. Installez uv (gestionnaire de packages Python), nvm (gestionnaire de versions Node) et l'interface de ligne de commande Databricks :

  2. Changer le répertoire pour 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, allez à http://localhost:8000 pour ouvrir l'interface utilisateur de chat intégrée et start une discussion avec l'agent.

Étape 6. Configurer l'authentification​

Votre agent a besoin d'authentification pour accéder aux ressources Databricks. Databricks Apps offre deux méthodes d'authentification : l'autorisation d'application (Service Principal) et l'autorisation utilisateur (pour le compte 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 des Declarative Automation Bundles. Les templates d'agent sont livrés avec un databricks.yml, de sorte que ce chemin est le default lorsque vous start à partir d'un template.

Pour la référence complète, y compris 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 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 App authorization.

Étape 7. Évaluez l’agent​

Le Template comprend le code d'évaluation d'agent. Pour plus d’informations, consultez agent_server/evaluate_agent.py. É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 vers Databricks. Les Templates d'agent utilisent des 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 d'avoir le CLI Databricks installé et configuré.

remarque

Si vous avez créé votre application via l'interface utilisateur de 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 pour 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 (MLflow Experimentation, 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 only upload files et configure les ressources. bundle run est requis pour start ou redémarrer 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 rapide curl avec un jeton OAuth. Les jetons d'accès personnels (PAT) ne sont pas pris en charge pour 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érez un jeton OAuth à l'aide de Databricks CLI :

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

Utilisez le jeton pour interroger 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 telles que l’AI Playground supposent que votre agent dispose de l’un des ensembles de signatures de modèles pris en charge.

Si vous suivez l'approche recommandée pour la création d'agents à l'aide de l'interface ResponsesAgent, MLflow déduira 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. Voir Mettre en production votre agent Databricks Apps pour la séquence recommandée : CI/CD, tests de charge, puis passerelle d'IA Unity.

Sur cette page