Connect agents to structured data

AI agents often need to query or manipulate structured data to answer questions, update records, or create data pipelines.

Databricks provides multiple approaches for connecting agents to structured data in Unity Catalog tables and external data stores. Use pre-configured MCP servers for immediate access to Genie spaces and SQL warehouses, or build custom tools for specialized workflows.

This page shows how to:

• Query data in Unity Catalog tables

• Use Genie in advanced multi-agent systems

• Use UC functions to run deterministic, repeatable queries

Query data in Unity Catalog tables

If your agent needs to query data in Unity Catalog tables, Databricks recommends using Genie spaces. A Genie space is a collection of up to 25 Unity Catalog tables that Genie can keep in context and query using natural language. Agents can access the Genie space using a pre-configured MCP URL.

To connect to a Genie space:

1. Create a Genie space with the tables you want to query and share the space with the users, or service principals, that must access it. See Set up and manage a Genie space.
2. Create an agent and connect it to the pre-configured managed MCP URL for the space: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}.

Add a Genie space tool to your agent

The following examples show how to connect your agent to a Genie space MCP server. Replace <genie-space-id> with the ID of your Genie space.

OpenAI Agents SDK (Apps)

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)

Grant the app access to the Genie space in databricks.yml:

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

LangGraph (Apps)

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)

Grant the app access to the Genie space in databricks.yml:

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

Model Serving

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

To deploy the agent, see Deploy an agent for generative AI applications (Model Serving). For details on logging agents with MCP resources, see Use Databricks managed MCP servers.

Genie multi-agent system

For advanced, multi-agent systems, you can also use Genie as an agent rather than integrating it using MCP. When you call Genie as an agent, you can deterministically pass in existing conversation context to Genie.

For a code-first approach, see Use Genie in multi-agent systems (Model Serving). For a UI-first approach, see Use Supervisor Agent to create a coordinated multi-agent system.

Query data using Unity Catalog SQL function tool

Create a structured retrieval tool using Unity Catalog SQL functions when the query is known ahead of time and the agent provides the parameters.

The following example creates a Unity Catalog function called lookup_customer_info, which allows an AI agent to retrieve structured data from a hypothetical customer_data table.

Run the following code in a SQL editor.

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;

After you create a Unity Catalog tool, add it to your agent. See Create a Unity Catalog function tool.