Condividi tramite

Connettere gli agenti ai dati strutturati

Gli agenti di intelligenza artificiale spesso devono eseguire query o modificare dati strutturati per rispondere a domande, aggiornare i record o creare pipeline di dati.

Databricks offre diversi approcci per la connessione degli agenti ai dati strutturati nelle tabelle di Unity Catalog e negli archivi dati esterni. Usare server MCP preconfigurato per l'accesso immediato agli spazi Genie e ai warehouse SQL oppure creare strumenti personalizzati per flussi di lavoro specializzati.

Questa pagina illustra come:

Eseguire query sui dati nelle tabelle di Unity Catalog

Se l'agente deve eseguire query sui dati nelle tabelle di Unity Catalog, Databricks consiglia di usare spazi Genie. Uno spazio Genie è una raccolta di un massimo di 25 tabelle del catalogo Unity che Genie può mantenere nel contesto ed eseguire query usando il linguaggio naturale. Gli agenti possono accedere allo spazio Genie usando un URL MCP preconfigurato.

Per connettersi a uno spazio Genie:

  1. Creare uno spazio Genie con le tabelle su cui eseguire query e condividere lo spazio con gli utenti o le entità servizio che devono accedervi. Vedere Configurare e gestire uno spazio Genie.
  2. Creare un agente e connetterlo all'URL MCP gestito preconfigurato per lo spazio: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}.

Annotazioni

Il server MCP gestito per Genie richiama Genie come strumento MCP, il che significa che la cronologia non viene passata quando si richiamano le API Genie.

Aggiungere uno strumento spaziale Genie all'agente

Gli esempi seguenti illustrano come connettere l'agente a un server MCP dello spazio Genie. Sostituire <genie-space-id> con l'ID dello spazio Genie.

OpenAI Agents SDK (App)

from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()
host = workspace_client.config.host

async with McpServer(
    url=f"{host}/api/2.0/mcp/genie/<genie-space-id>",
    name="genie-space",
    workspace_client=workspace_client,
) as genie_server:
    agent = Agent(
        name="Data analyst agent",
        instructions="You are a data analyst. Use the Genie tool to query structured data and answer questions.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[genie_server],
    )
    result = await Runner.run(agent, "What were the top 10 customers by revenue last quarter?")
    print(result.final_output)

Concedere all'app l'accesso allo spazio Genie in databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

LangGraph (App)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="genie-space",
        url=f"{host}/api/2.0/mcp/genie/<genie-space-id>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "What were the top 10 customers by revenue last quarter?"}]}
    )
    print(result["messages"][-1].content)

Concedere all'app l'accesso allo spazio Genie in databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

Gestione dei modelli

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

# Connect to the Genie space MCP server
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/genie/<genie-space-id>",
    workspace_client=workspace_client,
)

# List available tools from the Genie space
tools = mcp_client.list_tools()

# Log the agent with the required resources for deployment
mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Per distribuire l'agente, vedere Distribuire un agente per le applicazioni di intelligenza artificiale generative (Model Serving). Per informazioni dettagliate sulla registrazione degli agenti con risorse MCP, vedere Usare server MCP gestiti di Databricks.

Sistema multi-agente Genie

Importante

Questa funzionalità è in Anteprima Pubblica.

Per i sistemi avanzati multi-agente, è anche possibile usare Genie come agente anziché integrarlo tramite MCP. Quando si invoca Genie come agente, è possibile passare in modo deterministico il contesto di conversazione esistente a Genie.

Per un approccio code-first, vedere Utilizzare Genie nei sistemi multi-agente (Model Serving). Per un approccio basato su interfaccia utente, vedere Usare l'agente supervisore per creare un sistema multi-agente coordinato.

Eseguire query sui dati usando lo strumento per funzioni SQL del Catalogo Unity

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.

L'esempio seguente crea una funzione di Catalogo Unity denominata lookup_customer_info, che consente a un agente di intelligenza artificiale di recuperare dati strutturati da una tabella ipotetica customer_data .

Eseguire il codice seguente in un editor SQL.

CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name 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 main.default.customer_data
  WHERE customer_name = customer_name
  LIMIT 1;

Dopo aver creato uno strumento di Unity Catalog, puoi aggiungerlo al tuo agente. Vedere Creare uno strumento per le funzioni del catalogo Unity.

  • Last updated on