Conectar agentes a dados estruturados

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

O Databricks fornece várias abordagens para conectar agentes a dados estruturados em tabelas do Catálogo do Unity e armazenamentos de dados externos. Use servidores MCP pré-configurados para acesso imediato a espaços do Genie e sql warehouses ou crie ferramentas personalizadas para fluxos de trabalho especializados.

Esta página mostra como:

• Consultar dados em tabelas do Catálogo do Unity

• Usar o Genie em sistemas avançados de vários agentes

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

Consultar dados em tabelas do Catálogo do Unity

Se o agente precisar consultar dados em tabelas do Unity Catalog, a Databricks recomenda o uso de Genie spaces. Um espaço do 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 do Genie usando uma URL do MCP pré-configurada.

Para se conectar a um espaço do Genie:

1. Crie um espaço do Genie com as tabelas que você deseja consultar e compartilhe o espaço com os usuários ou entidades de serviço que devem acessá-lo. Veja Configurar e gerenciar um espaço do Genie.
2. Crie um agente e conecte-o à URL mcp gerenciada previamente configurada para o espaço: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}.

Adicionar uma ferramenta de espaço do Genie ao seu agente

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

SDK de Agentes do OpenAI (Aplicativos)

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 do 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 (Aplicativos)

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 do 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 Modelo

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 Implantar um agente para aplicativos de IA generativos (Model Serving). Para obter detalhes sobre agentes de log com recursos mcp, consulte Usar servidores MCP gerenciados pelo Databricks.

Sistema multi-agente do Genie

Para sistemas avançados de vários agentes, você também pode usar o Genie como um agente em vez de integrá-lo usando o MCP. Quando você chama Genie como um agente, você pode passar deterministicamente o contexto de conversa existente para o Genie.

Para obter uma abordagem de primeiro código, consulte Usar o Genie em sistemas multi-agentes (Model Serving). Para obter uma abordagem inicial da interface do usuário, consulte Usar o Supervisor Agent para criar um sistema de vários agentes coordenado.

Consultar dados usando a ferramenta de função SQL do Catálogo do Unity

Crie uma ferramenta de recuperação estruturada utilizando as funções SQL do Catálogo Unity quando a consulta já é conhecida e o agente fornece os parâmetros.

O exemplo a seguir cria uma função de Catálogo do Unity chamada lookup_customer_info, que permite que um agente de IA recupere dados estruturados de uma tabela hipotética customer_data .

Execute o código a seguir em um editor do 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 do Catálogo do Unity, adicione-a ao agente. Consulte Criar uma ferramenta de função no Unity Catalog.