Connecter des agents à des 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 requête :

Interroger les données avec Genie One

Azure Databricks recommande le Genie One MCP pour les agents qui répondent à des questions métier dans tout l’espace de travail en langage naturel. Il utilise Genie Ontology pour interpréter les termes métier et interroge les données de votre espace de travail en utilisant les permissions de l’appelant.

Suivez Utilisez des outils MCP dans un agent Python et définissez server_url à l’URL MCP de Genie One :

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

Remplacez <workspace-hostname> par le nom d’hôte de votre espace de travail. Posez ensuite une question à votre agent sur vos données, par exemple : « Quels étaient les 10 principaux clients par chiffre d’affaires le trimestre dernier ? »

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

Interroger un agent Genie spécifique à partir de Python

Utilisez AI Bridge pour exposer un agent Genie spécifique comme outil dans votre agent Python. AI Bridge gère les requêtes, le polling et les résultats de requêtes via l’API Genie.

Pour Claude Code ou Codex, installez Databricks AI Tools afin d’utiliser la skill Genie Agents via le CLI Databricks.

Avant de commencer

1. Utilisez Python 3.12. Pour le développement local, connectez-vous avec Databricks CLI, en utilisant le profil DEFAULT pour que les clients Python puissent trouver vos identifiants.
2. Choisissez un agent Genie auquel votre identité peut accéder, avec les permissions d’entrepôt et de données requises. Copiez son identifiant d’espace depuis les Paramètres et remplacez <genie-agent-id> par cet ID.
3. Remplacez <model-endpoint> par un point de terminaison de modèle Azure Databricks qui prend en charge l’appel d’outils et que vous êtes autorisé à interroger.
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 carnet qui prend en charge l’instruction await de niveau supérieur.

Faites tourner votre agent

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

LangGraph

Cet exemple enveloppe le GenieAgenthelper d’AI Bridge comme un outil LangChain.

pip install --upgrade databricks-langchain langgraph

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)

Kit de développement logiciel (SDK) Des agents OpenAI

Cet exemple utilise le client AI Bridge Genie et le décorateur du function_tool SDK OpenAI Agents. Le modèle fonctionne sur Azure Databricks.

pip install --upgrade databricks-ai-bridge databricks-openai openai-agents

from agents import Agent, Runner, function_tool
from agents import set_default_openai_api, set_default_openai_client
from agents.tracing import set_trace_processors
from databricks_ai_bridge.genie import Genie
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI())
set_default_openai_api("chat_completions")
set_trace_processors([])
genie = Genie(space_id="<genie-agent-id>", return_pandas=False)


@function_tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    return genie.ask_question(question).result


agent = Agent(
    name="Data analyst",
    instructions="Use ask_genie to answer questions about business data.",
    model="<model-endpoint>",
    tools=[ask_genie],
)
result = await Runner.run(agent, "What were total sales last month?")
print(result.final_output)

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

• GenieAgent: lire response["conversation_id"] et inclure "conversation_id" aux côtés de "messages" dans le dictionnaire d’entrée suivant.
• Genie: lire response.conversation_id et le transmettre en tant que conversation_id à ask_question().

Pour les options client et les détails de l’implémentation, voir le AI Bridge repository, incluant l’utilitaireGenieAgent et le Genie client.

Lorsque vous hébergez votre agent sur Databricks Apps, ajoutez l’agent Genie comme ressource d’application avec la permission Peut exécuter . Le principal de service de l’application a également besoin d’accéder au point de terminaison du modèle ainsi qu’à l’entrepôt et aux données sous-jacents.

Exécuter SQL avec le Databricks SQL MCP

Utilisez le 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 Unity Gateway depuis la page Previews de la console de compte. Voir Gérer les aperçus du compte.

Suivez Utilisez des outils MCP dans un agent Python et réglez server_url sur :

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

Remplacez <workspace-hostname> par le nom d’hôte de votre espace de travail. Demandez à l’agent d’exécuter SELECT 1 AS result et vérifiez 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 de l’entrepôt SQL et les options spécifiques à SQL, consultez la référence SQL MCP de Databricks.

Exécutez une requête prédéfinie avec une fonction Unity Catalog

Créez un outil de récupération structurée à l’aide des fonctions SQL du catalogue Unity lorsque la requête est connue à l’avance et que l’agent fournit les paramètres.

L’exemple suivant crée une fonction du catalogue Unity appelée lookup_customer_info. Il suppose que vous avez un customer_data tableau avec les colonnes customer_name, customer_id et customer_email.

Examinez les exigences et autorisations liées à la fonction. Remplacez my_catalog.my_schema par un catalogue et un schéma où vous pouvez créer des fonctions, et adaptez les noms des tables et des colonnes à vos données. Exécutez le code suivant dans un éditeur 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 client de votre tableau :

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

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

Utiliser Genie dans un système multi-agents

Pour coordonner Genie Agents avec d’autres agents et outils, voir Supervisor Agent. Pour les intégrations existantes de Model Servecing, voir Utiliser Genie dans les systèmes multi-agents.

Interroger un agent Genie à l’aide de MCP

Pour se connecter à un Agent Genie spécifique via MCP, consultez la référence MCP de l’Agent Genie pour son URL et ses exigences. Pour interroger un agent Genie depuis Python sans MCP, utilisez les exemples d’outils AI Bridge.