Aller au contenu principal
Dernière mise à jour le

Connectez les agents aux données structurées

Choisissez un outil en fonction des données dont votre agent a besoin et de la personne qui rédige la query :

Votre agent doit

Utilisation

Répondez aux questions métiers dans tout le Workspace

Genie One MCP

query un Genie Agent sélectionné à partir de Python

Outils de passerelle IA

Écrire et exécuter du SQL

Databricks SQL MCP

Exécuter une query prédéfinie avec des parameters

Outils de fonction Unity Catalog

Votre agent doit

Utilisation

Répondez aux questions métiers dans tout le Workspace

Genie One MCP

query un Genie Agent sélectionné à partir de Python

Outils de passerelle IA

Écrire et exécuter du SQL

Databricks SQL MCP

Exécuter une query prédéfinie avec des parameters

Outils de fonction Unity Catalog

Query des données avec Genie One​

Databricks recommande Genie One MCP pour les agents qui répondent aux questions métier dans tout le workspace en langage naturel. Il utilise l'ontologie Genie pour interpréter les termes métier et effectue une query sur les données de votre workspace à l'aide des autorisations de l'appelant.

Suivez Utiliser les outils MCP dans un agent Python et définissez server_url sur l'URL MCP Genie One :

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp

Remplacez <workspace-hostname> par le hostname de votre workspace. Posez ensuite une question à votre agent sur vos données, par exemple "Quels ont été les 10 principaux clients en termes de chiffre d'affaires au dernier trimestre ?"

Pour Claude Code ou Codex, installez Databricks AI Tools et utilisez la compétence de découverte des données, qui interroge Genie One via la Databricks CLI.

Effectuer une query sur un Genie Agent spécifique à partir de Python​

Utilisez AI Bridge pour exposer un Genie Agent spécifique en tant qu'outil dans votre agent Python. AI Bridge gère les requêtes, le sondage et les résultats de query via l'API Genie.

Pour Claude Code ou Codex, installez Databricks AI Tools pour utiliser la compétence Genie Agents via Databricks CLI.

Avant de start​

  1. Utilisez Python 3.12. Pour le développement local, connectez-vous avec la CLI Databricks, en utilisant le profil DEFAULT afin que les clients Python puissent trouver vos informations d'identification.
  2. Choisissez un Genie Agent auquel votre identité peut accéder, doté des permissions de warehouse et de données requises. Copiez l'ID de son espace à partir de Settings et remplacez <genie-agent-id> par cet ID.
  3. Remplacez <model-endpoint> par un Endpoint de modèle Databricks qui prend en charge l'appel d'outils et que vous êtes autorisé à query.
  4. Exécutez la commande d'installation de votre framework dans un terminal. Dans un notebook, utilisez %pip et redémarrez Python après l'installation. Exécutez des exemples avec await dans un notebook qui prend en charge await de niveau supérieur.

Exécutez votre agent​

Ces deux exemples permettent au modèle d’appeler ask_genie et d’utiliser le résultat dans sa réponse. Le client Genie de databricks-ai-bridge peut également être encapsulé en tant qu’outil de fonction Python dans d’autres frameworks. L’tab OpenAI Agents SDK affiche ce client sans dépendance LangChain.

Cet exemple enveloppe l'assistantGenieAgent d'AI Bridge en tant qu'outil LangChain.

Bash
pip install --upgrade databricks-langchain langgraph
Python
from databricks_langchain import ChatDatabricks
from databricks_langchain.genie import GenieAgent
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

genie = GenieAgent(genie_space_id="<genie-agent-id>")


@tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    response = genie.invoke({
        "messages": [{"role": "user", "content": question}]
    })
    return response["messages"][-1].content


agent = create_react_agent(
    ChatDatabricks(endpoint="<model-endpoint>"),
    tools=[ask_genie],
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Use Genie to find total sales last month.",
    }]
})
print(result["messages"][-1].content)

Vérifiez la sortie ou les traces de l'agent pour confirmer qu'il appelle ask_genie et utilise le résultat. Ces exemples start une nouvelle conversation Genie pour chaque appel d'outil. Pour conserver le contexte, enregistrez l'identifiant de conversation renvoyé pour chaque conversation d'utilisateur et transmettez-le lors du prochain appel :

  • GenieAgent: lisez response["conversation_id"] et incluez "conversation_id" avec "messages" dans le dictionnaire d’entrées suivant.
  • Genie: lire response.conversation_id et le transmettre en tant que conversation_id à ask_question().

Pour connaître les options client et les détails d'implémentation, consultez le repository AI Bridge, incluant le helperGenieAgent et le clientGenie.

Lors de l’hébergement de votre agent sur Databricks Apps, ajoutez le Genie Agent en tant que ressource d’application avec l’autorisation Can run . Le service principal de l’application a également besoin d’accéder à l’endpoint du modèle ainsi qu’au warehouse et aux données sous-jacents.

Exécuter du code SQL avec le MCP Databricks SQL​

Utilisez Databricks SQL MCP lorsque votre agent doit écrire et exécuter du SQL sur vos tables Unity Catalog.

Pour utiliser system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, un administrateur de compte doit activer la version bêta de Unity Gateway depuis la page Previews de la console du compte. Consultez Gérer les aperçus du compte.

Suivez Use MCP tools in a Python agent et définissez server_url sur :

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

Remplacez <workspace-hostname> par le hostname de votre workspace. Demandez à l’agent d’exécuter SELECT 1 AS result et confirmez qu’il appelle l’outil et renvoie 1.

Pour les agents de codage, utilisez le guide de configuration de votre agent. Pour la sélection du warehouse et les options spécifiques à SQL, consultez la référence Databricks SQL MCP.

Exécutez une query prédéfinie avec une fonction Unity Catalog​

Créez un outil de récupération structuré en utilisant les fonctions SQL de Unity Catalog lorsque la query est connue à l'avance et que l'agent fournit les parameters.

L’exemple suivant crée une fonction Unity Catalog nommée lookup_customer_info. Il suppose que vous disposez d’une table customer_data dotée des colonnes customer_name, customer_id et customer_email.

Examinez les exigences et autorisations relatives aux fonctions. Remplacez my_catalog.my_schema par un catalogue et un schéma dans lesquels vous pouvez créer des fonctions, puis adaptez les noms des tables et des colonnes à vos données. Exécutez le code suivant dans un éditeur SQL :

SQL
CREATE FUNCTION my_catalog.my_schema.lookup_customer_info(
  customer_name_input STRING COMMENT 'Name of the customer whose info to look up'
)
RETURNS STRING
COMMENT 'Returns metadata about a particular customer, given the customer''s name, including the customer''s email and ID. The
customer ID can be used for other queries.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM my_catalog.my_schema.customer_data
  WHERE customer_name = customer_name_input
  LIMIT 1;

Testez la fonction avec un nom de client de votre table :

SQL
SELECT my_catalog.my_schema.lookup_customer_info('Example Customer');

Utilisez ensuite Unity Catalog AI pour ajouter la fonction à votre agent. Ce guide inclut des exemples pour LangGraph, OpenAI, Anthropic et LlamaIndex.

Effectuer une query sur un Genie Agent à l’aide de MCP​

Pour vous connecter à un Genie Agent spécifique via MCP, consultez la référence MCP de Genie Agent pour connaître son URL et ses exigences. Pour effectuer une query sur un Genie Agent à partir de Python sans MCP, utilisez les exemples d’outils AI Bridge.

Sur cette page