Déboguer un agent de code personnalisé

Cette page explique comment déboguer les problèmes courants avec les agents de code personnalisés déployés sur Databricks.

Accéder à :

• Bonnes pratiques
• Développement local
• Problèmes de configuration
• Problèmes de déploiement
• Erreurs Runtime
• Erreurs d'authentification
• Mémoire et stockage

La plupart des sections de debugging de cette page s'appliquent aux agents déployés sur Databricks Apps. Cependant, vous pouvez également trouver des informations de débogage pour les agents déployés sur Model Serving (hérité) à l'aide des sélecteurs de tab.

Créer des agents en utilisant les bonnes pratiques

Utilisez les bonnes pratiques suivantes lors de la création d’agents :

• Activer le traçage MLflow : Suivez les bonnes pratiques dans Créer un agent d’IA et le déployer sur Databricks Apps. Activez la journalisation automatique de trace MLflow pour faciliter le débogage de vos agents.

• Documentez clairement les outils : des descriptions claires des outils et des parameter garantissent que votre agent comprend vos outils et les utilise de manière appropriée. Voir Améliorer l'appel d'outil avec une documentation claire.

• Ajoutez des délais d'attente et des limites de jetons aux appels LLM : ajoutez des délais d'attente et des limites de jetons aux appels LLM dans votre code pour éviter les retards causés par des étapes longues.

  • Si votre agent utilise le client OpenAI pour query un Endpoint de service de LLM Databricks, définissez des délais d'expiration personnalisés pour les appels d'Endpoint de service, selon les besoins.

• **Valider la configuration avant le déploiement** : exécutez databricks bundle validate avant de déployer pour détecter rapidement les problèmes de configuration YAML. Cela permet d'identifier les références de Ressources incompatibles, les autorisations non valides et les erreurs de syntaxe.

• Testez d'abord en local : utilisez le développement local pour détecter les problèmes avant le déploiement. start votre serveur d'agent localement, testez avec des requêtes d'exemple, et vérifiez que les traces MLflow apparaissent correctement avant de déployer sur Databricks Apps.

Déboguer les problèmes de développement locaux

Testez votre agent localement pour identifier les problèmes avant le déploiement.

Avant d'exécuter votre agent localement, vérifiez que votre environnement est correctement configuré :

1. Vérifiez la version de Databricks CLI : exécutez databricks -v pour vérifier que vous disposez de la version 0.283.0 ou ultérieure.

2. Vérifiez les profils CLI : Exécutez databricks auth profiles pour voir les profils d'authentification configurés.

3. Valider la configuration de l'environnement : Vérifiez que votre fichier .env contient les variables requises, en particulier MLFLOW_TRACKING_URI, qui doit utiliser le format databricks://PROFILE_NAME pour inclure votre profil CLI.

Erreurs courantes de développement local

Erreur	Cause	Solutions
The provided MLFLOW_EXPERIMENT_ID does not exist	Format d’URI de suivi incorrect ou expérimentation a été supprimée	Vérifiez que MLFLOW_TRACKING_URI utilise le format databricks://PROFILE_NAME avec le nom de votre profil CLI.
Module not found	Dépendances non installées	Exécuter uv sync pour installer les dépendances
Port already in use	Un autre processus utilisant le port	Utilisez l'indicateur --port pour spécifier un port différent (par exemple, uv run start-app --port 8001).
Erreurs d'authentification lors de l'exécution en local	L'environnement n'est pas configuré.	Exécutez le script de démarrage rapide ou configurez manuellement le fichier .env avec votre profil CLI

Erreur	Cause	Solutions
The provided MLFLOW_EXPERIMENT_ID does not exist	Format d’URI de suivi incorrect ou expérimentation a été supprimée	Vérifiez que MLFLOW_TRACKING_URI utilise le format databricks://PROFILE_NAME avec le nom de votre profil CLI.
Module not found	Dépendances non installées	Exécuter uv sync pour installer les dépendances
Port already in use	Un autre processus utilisant le port	Utilisez l'indicateur --port pour spécifier un port différent (par exemple, uv run start-app --port 8001).
Erreurs d'authentification lors de l'exécution en local	L'environnement n'est pas configuré.	Exécutez le script de démarrage rapide ou configurez manuellement le fichier .env avec votre profil CLI

Testez l'agent localement

Pour tester votre agent avant le déploiement :

1. Start le serveur d'agents localement :

   Bash

   uv run start-app

2. Dans un autre terminal, envoyez une requête de test :

   Bash

   curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": [{"role": "user", "content": "hello"}]}'

3. Affichez les traces MLflow dans l'interface utilisateur de Databricks pour vérifier que votre agent enregistre correctement les traces.

Débogage des problèmes de configuration

Les erreurs de configuration dans databricks.yml et app.yaml sont des sources courantes d'échecs de déploiement.

Validez la configuration des Declarative Automation Bundles

Validez la configuration des Declarative Automation Bundles avant de déployer l'application :

Bash

databricks bundle validate

Cette commande vérifie votre configuration pour :

• Erreurs de syntaxe YAML
• Champs obligatoires manquants
• Références de Ressources non valides
• Problèmes de configuration des autorisations

Incohérences de configuration courantes

Point de configuration	Règle	Comment déboguer
valueFrom références dans app.yaml	Doit correspondre exactement à une ressource name dans databricks.yml	Recherchez la chaîne exacte dans les deux fichiers pour vérifier qu'ils correspondent.
Nom de l’application	Doit start par le préfixe agent- (par exemple, agent-data-analyst).	Vérifiez le champ name sous resources.apps dans databricks.yml
Genie Agent ID	Doit être la chaîne hexadécimale de 32 caractères provenant de l'URL Genie	Extraire du chemin de l'URL : https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Référence de la fonction Unity Catalog	Doit utiliser le format catalog.schema.function_name	Vérifiez que la fonction existe en utilisant databricks unity-catalog functions list
Référence de l'instance Lakebase	Doit utiliser value (et non valueFrom) dans le fichier app.yaml.	Le nom de l'instance est une chaîne de caractères littérale, et non une référence de ressource.

Point de configuration	Règle	Comment déboguer
valueFrom références dans app.yaml	Doit correspondre exactement à une ressource name dans databricks.yml	Recherchez la chaîne exacte dans les deux fichiers pour vérifier qu'ils correspondent.
Nom de l’application	Doit start par le préfixe agent- (par exemple, agent-data-analyst).	Vérifiez le champ name sous resources.apps dans databricks.yml
Genie Agent ID	Doit être la chaîne hexadécimale de 32 caractères provenant de l'URL Genie	Extraire du chemin de l'URL : https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Référence de la fonction Unity Catalog	Doit utiliser le format catalog.schema.function_name	Vérifiez que la fonction existe en utilisant databricks unity-catalog functions list
Référence de l'instance Lakebase	Doit utiliser value (et non valueFrom) dans le fichier app.yaml.	Le nom de l'instance est une chaîne de caractères littérale, et non une référence de ressource.

Déboguer les problèmes de déploiement

Agents deployed to Apps

L'application existe déjà.

L'application existe déjà

Si vous voyez Error: failed to create app - An app with the same name already exists, vous avez deux options :

Option 1 : Lier à une application existante (recommandée)

Bash

# Get existing app configuration
databricks apps get <app-name> --output json

# Sync the configuration to your databricks.yml, then bind
databricks bundle deployment bind <bundle-name> <app-name> --auto-approve

# Deploy
databricks bundle deploy
databricks bundle run <bundle-name>

Option 2 : Supprimer et recréer

Bash

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>

L'application ne se met pas à jour après le déploiement

L'application ne se met pas à jour après le déploiement.

databricks bundle deploy upload uniquement les fichiers dans le Workspace. Vous devez également exécuter databricks bundle run <bundle-name> pour redémarrer l'application avec le nouveau code.

Déployez toujours en utilisant les deux commandes :

Bash

databricks bundle deploy && databricks bundle run <bundle-name>

Afficher l’état du déploiement et les logs

Afficher l'état du déploiement et les logs

Pour vérifier l'état de déploiement de votre application :

Bash

databricks apps get <app-name>

Pour consulter les logs de l'application en temps réel :

Bash

databricks apps logs <app-name> --follow

Agents on Model Serving (legacy)

Si vous avez déployé votre agent à l'aide de agents.deploy() vers un Endpoint de Model Serving, consultez le guide de debugging pour le Model Serving pour les problèmes spécifiques au déploiement.

Pour déboguer les problèmes d'exécution tels que les requêtes lentes ou défaillantes, consultez Déboguer les erreurs d'exécution.

Déboguer les erreurs d'exécution

Agents deployed to Apps

Utilisez les logs d'application et les tests de requête pour identifier les problèmes de votre agent déployé.

Analyse des logs d'application

Afficher les logs en temps réel de votre application déployée :

Bash

databricks apps logs <app-name> --follow

Recherchez :

• Traces de pile indiquant des erreurs de code
• Messages d'autorisation refusée pour les Ressources.
• Erreurs de connexion aux services externes
• Messages de délai d’expiration

Erreurs d'exécution courantes

Erreur	Cause	Solutions
Redirection 302 lors de l'interrogation de l'application	Utilisation d'un jeton d'accès personnel au lieu d'OAuth	Obtenez un jeton OAuth avec databricks auth token
L'agent n'utilise pas les outils disponibles	Outils non renvoyés par le client MCP	Vérifiez que l'URL du serveur MCP est correcte et que la Ressource dispose des autorisations appropriées dans databricks.yml
La réponse en streaming s’interrompt en cours de réponse	Délai d'expiration de la connexion	Augmentez la variable d'environnement CHAT_PROXY_TIMEOUT_SECONDS dans app.yaml
L'agent renvoie « Mémoire non disponible »	Manquant user_id dans la requête	Transmettez custom_inputs.user_id dans la charge utile de la requête
Réponses vides ou erronées malgré le statut 200	Une erreur s'est produite dans la réponse Stream.	Vérifiez le contenu réel du Stream et les logs d'application, pas seulement le code d'état HTTP.

Erreur	Cause	Solutions
Redirection 302 lors de l'interrogation de l'application	Utilisation d'un jeton d'accès personnel au lieu d'OAuth	Obtenez un jeton OAuth avec databricks auth token
L'agent n'utilise pas les outils disponibles	Outils non renvoyés par le client MCP	Vérifiez que l'URL du serveur MCP est correcte et que la Ressource dispose des autorisations appropriées dans databricks.yml
La réponse en streaming s’interrompt en cours de réponse	Délai d'expiration de la connexion	Augmentez la variable d'environnement CHAT_PROXY_TIMEOUT_SECONDS dans app.yaml
L'agent renvoie « Mémoire non disponible »	Manquant user_id dans la requête	Transmettez custom_inputs.user_id dans la charge utile de la requête
Réponses vides ou erronées malgré le statut 200	Une erreur s'est produite dans la réponse Stream.	Vérifiez le contenu réel du Stream et les logs d'application, pas seulement le code d'état HTTP.

Agents on Model Serving (legacy)

Utilisez les tables d'inférence et les traces MLflow pour identifier les problèmes avec les agents déployés sur les Endpoint de Model Serving.

Identifier les requêtes problématiques

Si vous avez activé la journalisation automatique des traces MLflow lors de la création de votre agent, les traces sont automatiquement enregistrées dans les tables d'inférence. Utilisez ces traces pour identifier les composants d'agent lents ou défaillants.

1. Dans votre workspace, accédez à l'onglet Serving et sélectionnez le nom de votre déploiement.

2. Dans la section **Tables d'inférences**, recherchez le nom entièrement qualifié de la table d'inférence. Par exemple : my-catalog.my-schema.my-table.

3. Exécutez les éléments suivants dans un Notebook Databricks :

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table

4. Inspectez la colonne **Réponse** pour obtenir des informations détaillées sur la trace.

5. Filtrez sur request_time, databricks_request_id ou status_code pour affiner les résultats.

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   WHERE status_code != 200

Analyser les problèmes de cause fondamentale

Après avoir identifié les requêtes échouées ou lentes, utilisez la fonction mlflow.models.validate_serving_input. API pour invoquer votre agent suite à la requête d'entrée échouée. Visualisez la trace résultante et effectuez une analyse des causes profondes sur la réponse échouée.

Pour une boucle de développement plus rapide, mettez à jour directement le code de votre agent et itérez en invoquant votre agent par rapport à l'exemple d'entrée ayant échoué.

Déboguer les erreurs d'authentification

Agents deployed to Apps

Authentification par jeton OAuth requise

Authentification par jeton OAuth requise

Vous devez utiliser un jeton OAuth Databricks pour query les agents déployés sur les applications. L’utilisation d’un jeton d’accès personnel (PAT) entraîne une erreur de redirection 302.

Pour obtenir un jeton OAuth :

Bash

databricks auth token

Utilisez le jeton dans les demandes à votre application déployée :

Bash

TOKEN=$(databricks auth token | jq -r '.access_token')
curl -X POST <app-url>/invocations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'

Erreurs d'autorisation de ressource

Erreurs d'autorisation des ressources

Si votre agent ne peut pas accéder aux ressources du workspace, vérifiez que la ressource est correctement configurée dans databricks.yml. Chaque type de ressource nécessite des autorisations spécifiques :

Error	Cause	Solution
Permission denied on Genie Agent	Missing genie_space resource	Add a genie_space resource with permission: 'CAN_RUN'
AI Search index not accessible	Missing uc_securable resource for the index	Add a uc_securable resource with securable_type: 'TABLE' and permission: 'SELECT'
Unity Catalog function execution denied	Missing uc_securable resource for the function	Add a uc_securable resource with securable_type: 'FUNCTION' and permission: 'EXECUTE'
Serving endpoint access denied	Missing serving_endpoint resource	Add a serving_endpoint resource with permission: 'CAN_QUERY'
SQL warehouse access denied	Missing sql_warehouse resource	Add a sql_warehouse resource with permission: 'CAN_USE'

Error	Cause	Solution
Permission denied on Genie Agent	Missing genie_space resource	Add a genie_space resource with permission: 'CAN_RUN'
AI Search index not accessible	Missing uc_securable resource for the index	Add a uc_securable resource with securable_type: 'TABLE' and permission: 'SELECT'
Unity Catalog function execution denied	Missing uc_securable resource for the function	Add a uc_securable resource with securable_type: 'FUNCTION' and permission: 'EXECUTE'
Serving endpoint access denied	Missing serving_endpoint resource	Add a serving_endpoint resource with permission: 'CAN_QUERY'
SQL warehouse access denied	Missing sql_warehouse resource	Add a sql_warehouse resource with permission: 'CAN_USE'

Exemple de configuration des ressources dans databricks.yml:

YAML

resources:
  apps:
    my_agent:
      name: 'agent-my-app'
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '01234567890abcdef01234567890abcd'
            permission: 'CAN_RUN'
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: 'catalog.schema.index_name'
            securable_type: 'TABLE'
            permission: 'SELECT'

Autorisations de serveur MCP personnalisées

Autorisations de serveur MCP personnalisées

Si votre agent se connecte à un serveur MCP personnalisé s'exécutant en tant qu'application Databricks, vous devez accorder manuellement les autorisations, car les applications ne sont pas encore prises en charge en tant que dépendances de ressources dans databricks.yml.

Bash

# Get your agent app's service principal
AGENT_SP=$(databricks apps get <agent-app-name> --output json | jq -r '.service_principal_name')

# Grant permission on the MCP server app
databricks apps update-permissions <mcp-server-app-name> \
  --json "{\"access_control_list\": [{\"service_principal_name\": \"$AGENT_SP\", \"permission_level\": \"CAN_USE\"}]}"

Agents on Model Serving (legacy)

Si votre agent déployé rencontre des erreurs d'authentification lors de l'accès à des Ressources telles que les index de recherche IA ou les endpoints LLM, vérifiez qu'il a été connecté avec les Ressources nécessaires pour la transmission automatique de l'authentification. Consultez la transmission automatique de l'authentification.

Pour examiner les Ressources journalisées, exécutez ce qui suit dans un Notebook :

Python

%pip install -U mlflow[databricks]==2.20.2
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

Pour rajouter des ressources manquantes ou incorrectes, log l'agent et déployez-le à nouveau.

Si vous utilisez l'authentification manuelle pour les ressources, vérifiez que les variables d'environnement sont correctement définies. Les paramètres manuels remplacent les configurations d'authentification automatiques. Consultez Authentification manuelle.

Débogage des problèmes de mémoire et de stockage

Pour les agents utilisant Lakebase pour le stockage en mémoire, les problèmes suivants sont courants :

Erreur	Cause	Solutions
relation 'store' does not exist	Tables mémoire non initialisées	Exécutez await store.setup() localement avant le déploiement pour créer les tables requises.
Unable to resolve :re[LKB] instance	Nom d’instance incorrect ou configuration incorrecte	Vérifiez que LAKEBASE_INSTANCE_NAME utilise value (et non valueFrom) dans app.yaml et correspond au instance_name dans databricks.yml
permission denied for table store	Autorisations Lakebase manquantes	Ajoutez une database Ressource dans databricks.yml avec permission: 'CAN_CONNECT_AND_CREATE'
La mémoire ne persiste pas entre les conversations	Différents user_id par requête	Assurez-vous de transmettre un user_id cohérent dans custom_inputs pour chaque utilisateur

Erreur	Cause	Solutions
relation 'store' does not exist	Tables mémoire non initialisées	Exécutez await store.setup() localement avant le déploiement pour créer les tables requises.
Unable to resolve :re[LKB] instance	Nom d’instance incorrect ou configuration incorrecte	Vérifiez que LAKEBASE_INSTANCE_NAME utilise value (et non valueFrom) dans app.yaml et correspond au instance_name dans databricks.yml
permission denied for table store	Autorisations Lakebase manquantes	Ajoutez une database Ressource dans databricks.yml avec permission: 'CAN_CONNECT_AND_CREATE'
La mémoire ne persiste pas entre les conversations	Différents user_id par requête	Assurez-vous de transmettre un user_id cohérent dans custom_inputs pour chaque utilisateur

Exemple de configuration des Ressources Lakebase :

YAML

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

Avant de déployer un agent avec mémoire, initialisez les tables localement :

Python

import asyncio
from databricks_langchain import AsyncDatabricksStore

async def setup_memory():
    async with AsyncDatabricksStore(
        instance_name='your-lakebase-instance',
        embedding_endpoint='databricks-gte-large-en',
        embedding_dims=1024,
    ) as store:
        await store.setup()

asyncio.run(setup_memory())