Connettere gli agenti ai dati strutturati

Scegli uno strumento basato sui dati di cui il tuo agente ha bisogno e su chi scrive la query:

Consulta i dati con Genie One

Azure Databricks consiglia il Genie One MCP per gli agenti che rispondono a domande aziendali in tutto lo spazio di lavoro in linguaggio naturale. Utilizza Genie Ontology per interpretare i termini aziendali e interroga i dati del tuo spazio di lavoro utilizzando i permessi del chiamante.

Segui la procedura in Usa strumenti MCP in un agente Python e imposta server_url sull'URL MCP di Genie One:

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

Sostituisci <workspace-hostname> con il nome host del tuo spazio di lavoro. Poi fai una domanda al tuo agente sui tuoi dati, come "Quali sono stati i 10 clienti principali per ricavi dello scorso trimestre?"

Per Claude Code o Codex, installa Databricks AI Tools e usa la skill di scoperta dati, che interroga Genie One tramite la Databricks CLI.

Interroga uno specifico agente Genie da Python

Usa AI Bridge per esporre uno specifico Genie Agent come strumento nel tuo agente Python. AI Bridge gestisce richieste, sondaggi e risultati delle query tramite l'API Genie.

Per Claude Code o Codex, installa Databricks AI Tools per utilizzare l'abilità Genie Agents tramite Databricks CLI.

Prima di iniziare

1. Usa Python 3.12. Per lo sviluppo locale, accedi con la CLI di Databricks, usando il DEFAULT profilo così i client Python possono trovare le tue credenziali.
2. Scegli un Genie Agent a cui la tua identità possa accedere, con i permessi di magazzino e dati richiesti. Copia il suo ID di spazio da Impostazioni e sostituisci <genie-agent-id> con quell'ID.
3. Sostituisci <model-endpoint> con un endpoint modello Azure Databricks che supporti la chiamata di strumenti e per cui hai il permesso di fare query.
4. Esegui il comando di installazione del tuo framework in un terminale. In un notebook, usa %pip e riavvia Python dopo l'installazione. Esegui esempi con await in un notebook che supporti il supporto di primo livello per await.

Avvia il tuo agente

Entrambi gli esempi permettono al modello di chiamare ask_genie e utilizzare il risultato nella sua risposta. Il Genie client da databricks-ai-bridge può anche essere incapsulato come strumento di funzione Python in altri framework. La scheda SDK degli Agenti OpenAI mostra questo client senza dipendenza da LangChain.

LangGraph

Questo esempio avvolge l'helper di AI Bridge come uno strumento 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)

OpenAI Agents SDK

Questo esempio utilizza il client AI Bridge Genie client e il decorator dell'SDK function_tool degli agenti OpenAI. Il modello gira su 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)

Controlla l'output o le tracce dell'agente per confermare che chiami ask_genie e utilizzi il risultato. Questi esempi avviano una nuova conversazione Genie per ogni chiamata di strumento. Per mantenere il contesto, salva l'ID della conversazione restituito per la conversazione di ogni utente e passalo nella chiamata successiva:

• GenieAgent: leggi response["conversation_id"] e includi "conversation_id" accanto "messages" nel dizionario di input successivo.
• Genie: leggi response.conversation_id e passalo come conversation_id a ask_question().

Per le opzioni client e i dettagli sull'implementazione, consulta il repository AI Bridge, inclusi l'helper GenieAgent e il Genie client.

Quando ospiti il tuo agente sulle app Databricks, aggiungi l'agente Genie come risorsa app con permesso Può eseguire. Il service principal dell'app ha anche bisogno di accedere all'endpoint del modello e al warehouse e ai dati sottostanti.

Esegui SQL con il Databricks SQL MCP

Usa il Databricks SQL MCP quando il tuo agente deve scrivere ed eseguire SQL sulle tabelle del tuo Unity Catalog.

Per utilizzare system.ai.dbsql, system.ai.sandbox o system.ai.web_search, un amministratore dell'account deve abilitare la beta di Unity Gateway dalla pagina Anteprime della console dell'account. Vedi Gestisci anteprime dell'account.

Segui Usa gli strumenti MCP in un agente Python e imposta server_url su:

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

Sostituisci <workspace-hostname> con il nome host del tuo spazio di lavoro. Chiedi all'agente di eseguire SELECT 1 AS result e confermare che chiama lo strumento e restituisca 1.

Per gli agenti di codifica, usa la guida all'impostazione del tuo agente. Per la selezione del warehouse e le opzioni specifiche per SQL, consulta il riferimento Databricks SQL MCP.

Esegui una query predefinita con una funzione Unity Catalog

Creare uno strumento di recupero strutturato usando le funzioni SQL del catalogo unity quando la query è nota in anticipo e l'agente fornisce i parametri.

Il seguente esempio crea una funzione Unity Catalog chiamata lookup_customer_info. Presuppone che tu abbia una customer_data tabella con customer_name, customer_id, e customer_email colonne.

Rivedi i requisiti e le autorizzazioni della funzione. Sostituisci my_catalog.my_schema con un catalogo e uno schema dove puoi creare funzioni e adatta i nomi delle tabelle e delle colonne ai tuoi dati. Esegui il seguente codice in un editor 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;

Prova la funzione con un nome cliente dalla tua tabella:

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

Poi usa Unity Catalog AI per aggiungere la funzione al tuo agente. Quella guida include esempi di LangGraph, OpenAI, Anthropic e LlamaIndex.

Usa Genie in un sistema multi-agente

Per coordinare gli Agenti Genie con altri agenti e strumenti, vedi Supervisor Agent. Per le integrazioni esistenti di Model Servecing, vedi Usa Genie nei sistemi multi-agente.

Consulta un agente Genie usando MCP

Per connettersi a uno specifico Genie Agent tramite MCP, consulta il riferimento Genie Agent MCP per il suo URL e i requisiti. Per interrogare un Genie Agent da Python senza MCP, usa gli esempi di strumenti AI Bridge.