Conectar agentes a dados estruturados

Os agentes AI frequentemente precisam consultar ou manipular dados estruturados para responder a perguntas, atualizar registros ou criar fluxos de dados.

O Databricks oferece diversas abordagens para conectar agentes a dados estruturados em tabelas do Unity Catalog e em armazenamentos de dados externos. Utilize servidores MCP pré-configurados para acesso imediato aos Genie spaces e ao banco de dados SQL , ou crie ferramentas personalizadas para fluxos de trabalho especializados.

Esta página mostra como:

• Consultar dados nas tabelas Unity Catalog

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

Consultar dados nas tabelas Unity Catalog

Se o seu agente precisar consultar dados em tabelas Unity Catalog , Databricks recomenda o uso Genie spaces. Um espaço Genie é uma coleção de até 25 tabelas do Unity Catalog que o Genie pode manter em contexto e consultar usando linguagem natural. Os agentes podem acessar o espaço Genie usando um URL MCP pré-configurado.

Para se conectar a um espaço Genie:

1. Crie um espaço Genie com as tabelas que deseja consultar e compartilhe o espaço com os usuários ou a entidade de serviço que precisam acessá-lo. Consulte Configurar e gerenciar um espaço Genie.
2. Crie um agente e conecte-o ao URL MCP pré-configurado para o espaço: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}.

nota

O servidor MCP de gerenciamento para Genie invoca Genie como uma ferramenta MCP, o que significa que o histórico não é passado ao invocar APIs Genie .

Adicione uma ferramenta Genie Space ao seu agente.

Os exemplos a seguir mostram como conectar seu agente a um servidor Genie Space MCP. Substitua <genie-space-id> pelo ID do seu espaço Genie.

OpenAI Agents SDK (Apps)

Python

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 ao aplicativo acesso ao espaço Genie em databricks.yml:

YAML

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

LangGraph (Apps)

Python

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 ao aplicativo acesso ao espaço Genie em databricks.yml:

YAML

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

Model Serving

Python

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 implantar o agente, consulte implantado um agente para aplicações generativas AI (servindo modelo). Para obter detalhes sobre agentes de registro com recursos MCP, consulte Usar Databricks para gerenciar servidores MCP.

Consultar uso de dados Unity Catalog SQL ferramenta de função

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 a seguir cria uma função Unity Catalog chamada lookup_customer_info, que permite que um agente AI recupere dados estruturados de uma tabela hipotética customer_data .

Execute o código a seguir em um editor SQL.

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;

Após criar uma ferramenta Unity Catalog , adicione-a ao seu agente. Consulte a ferramenta Criar um Unity Catalog.