Ligue agentes a dados estruturados

Os agentes de IA frequentemente precisam de consultar ou manipular dados estruturados para responder a perguntas, atualizar registos ou criar pipelines de dados.

O Databricks fornece múltiplas abordagens para ligar agentes a dados estruturados em tabelas do Unity Catalog e armazenamentos externos de dados. Use servidores MCP pré-configurados para acesso imediato a espaços Genie e armazéns SQL, ou construa ferramentas personalizadas para fluxos de trabalho especializados.

Esta página mostra como:

• Consultar dados nas tabelas do Unity Catalog

• Usar o Genie em sistemas multiagente avançados

• Use funções UC para executar consultas determinísticas e repetíveis

Consultar dados nas tabelas do Unity Catalog

Se o seu agente precisar de consultar dados em tabelas do Catálogo Unity, o Databricks recomenda usar espaços Genie. Um espaço Genie é uma coleção de até 25 tabelas do Catálogo Unity que o Genie pode manter em contexto e consultar usando linguagem natural. Os agentes podem aceder ao espaço Genie usando uma URL MCP pré-configurada.

Para se conectar a um espaço Genie:

1. Cria um espaço Genie com as tabelas que queres consultar e partilha o espaço com os utilizadores, ou principais de serviço, que têm de o aceder. Veja Configurar e gerir um espaço Genie.
2. Crie um agente e ligue-o ao URL MCP pré-configurado e gerido para o espaço: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}.

Adicione uma ferramenta de espaço Genie ao seu agente

Os exemplos seguintes mostram como ligar o seu agente a um servidor MCP espacial Genie. Substitui <genie-space-id> pelo ID do teu espaço Genie.

SDK de Agentes OpenAI (Aplicações)

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)

Conceda à aplicação acesso ao espaço Genie em databricks.yml:

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

LangGraph (Aplicações)

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)

Conceda à aplicação acesso ao espaço Genie em databricks.yml:

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

Serviço de Modelos

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(),
)

Para implementar o agente, veja Implementar um agente para aplicações de IA generativa (Model Serving). Para detalhes sobre agentes de registo com recursos MCP, veja Utilizar servidores MCP geridos pela Databricks.

Sistema multiagente Genie

Para sistemas avançados e multi-agente, também podes usar o Genie como agente em vez de o integrar através do MCP. Quando chamas o Génio como agente, podes passar de forma determinística o contexto da conversa existente para o Génio.

Para uma abordagem centrada no código, veja Use Genie em sistemas multi-agente (Model Serving). Para uma abordagem centrada na interface, consulte Usar Agente Supervisor para criar um sistema multiagente coordenado.

Consultar dados usando a ferramenta de função SQL do Unity Catalog

Crie uma ferramenta de recuperação estruturada usando funções SQL do Unity Catalog quando a consulta for conhecida antecipadamente e o agente fornecer os parâmetros.

O exemplo seguinte cria uma função Unity Catalog chamada lookup_customer_info, que permite a um agente de IA recuperar dados estruturados de uma tabela hipotética customer_data .

Execute o código a seguir em um 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;

Depois de criar uma ferramenta de catálogo Unity, adicione-a ao seu agente. Consulte a ferramenta de criação de funções do Catálogo Unity.