Connect agents to structured data

Choose a tool based on the data your agent needs and who writes the query:

Your agent needs to	Use
Answer business questions across the workspace	Genie One MCP
Query one curated Genie Agent from Python	AI Bridge tools
Write and run SQL	Databricks SQL MCP
Run a predefined query with parameters	Unity Catalog function tools

Your agent needs to	Use
Answer business questions across the workspace	Genie One MCP
Query one curated Genie Agent from Python	AI Bridge tools
Write and run SQL	Databricks SQL MCP
Run a predefined query with parameters	Unity Catalog function tools

Query data with Genie One

Databricks recommends the Genie One MCP for agents that answer business questions across the workspace in natural language. It uses Genie Ontology to interpret business terms and queries your workspace data using the caller's permissions.

Follow Use MCP tools in a Python agent and set server_url to the Genie One MCP URL:

Text

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp

Replace <workspace-hostname> with your workspace hostname. Then ask your agent a question about your data, such as "What were the top 10 customers by revenue last quarter?"

For Claude Code or Codex, install Databricks AI Tools and use the data discovery skill, which queries Genie One through the Databricks CLI.

Query a specific Genie Agent from Python

Use AI Bridge to expose a specific Genie Agent as a tool in your Python agent. AI Bridge handles requests, polling, and query results through the Genie API.

For Claude Code or Codex, install Databricks AI Tools to use the Genie Agents skill through the Databricks CLI.

Before you start

1. Use Python 3.12. For local development, sign in with the Databricks CLI, using the DEFAULT profile so the Python clients can find your credentials.
2. Choose a Genie Agent that your identity can access, with the required warehouse and data permissions. Copy its space ID from Settings and replace <genie-agent-id> with that ID.
3. Replace <model-endpoint> with a Databricks model endpoint that supports tool calling and that you have permission to query.
4. Run the installation command for your framework in a terminal. In a notebook, use %pip and restart Python after installation. Run examples with await in a notebook that supports top-level await.

Run your agent

Both examples let the model call ask_genie and use the result in its answer. The Genie client from databricks-ai-bridge can also be wrapped as a Python function tool in other frameworks. The OpenAI Agents SDK tab shows this client without a LangChain dependency.

LangGraph

This example wraps AI Bridge's GenieAgent helper as a LangChain tool.

Bash

pip install --upgrade databricks-langchain langgraph

Python

from databricks_langchain import ChatDatabricks
from databricks_langchain.genie import GenieAgent
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

genie = GenieAgent(genie_space_id="<genie-agent-id>")


@tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    response = genie.invoke({
        "messages": [{"role": "user", "content": question}]
    })
    return response["messages"][-1].content


agent = create_react_agent(
    ChatDatabricks(endpoint="<model-endpoint>"),
    tools=[ask_genie],
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Use Genie to find total sales last month.",
    }]
})
print(result["messages"][-1].content)

OpenAI Agents SDK

This example uses the AI Bridge Genie client and the OpenAI Agents SDK's function_tool decorator. The model runs on Databricks.

Bash

pip install --upgrade databricks-ai-bridge databricks-openai openai-agents

Python

from agents import Agent, Runner, function_tool
from agents import set_default_openai_api, set_default_openai_client
from agents.tracing import set_trace_processors
from databricks_ai_bridge.genie import Genie
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI())
set_default_openai_api("chat_completions")
set_trace_processors([])
genie = Genie(space_id="<genie-agent-id>", return_pandas=False)


@function_tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    return genie.ask_question(question).result


agent = Agent(
    name="Data analyst",
    instructions="Use ask_genie to answer questions about business data.",
    model="<model-endpoint>",
    tools=[ask_genie],
)
result = await Runner.run(agent, "What were total sales last month?")
print(result.final_output)

Check the agent's output or traces to confirm it calls ask_genie and uses the result. These examples start a new Genie conversation for each tool call. To retain context, save the returned conversation ID for each user's conversation and pass it on the next call:

• GenieAgent: read response["conversation_id"] and include "conversation_id" alongside "messages" in the next input dictionary.
• Genie: read response.conversation_id and pass it as conversation_id to ask_question().

For client options and implementation details, see the AI Bridge repository, including the GenieAgent helper and the Genie client.

When hosting your agent on Databricks Apps, add the Genie Agent as an app resource with Can run permission. The app's service principal also needs access to the model endpoint and the underlying warehouse and data.

Run SQL with the Databricks SQL MCP

Use the Databricks SQL MCP when your agent needs to write and run SQL against your Unity Catalog tables.

To use system.ai.dbsql, system.ai.sandbox, or system.ai.web_search, an account admin must enable the Unity Gateway beta from the account console Previews page. See Manage account previews.

Follow Use MCP tools in a Python agent and set server_url to:

Text

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

Replace <workspace-hostname> with your workspace hostname. Ask the agent to run SELECT 1 AS result and confirm that it calls the tool and returns 1.

For coding agents, use your agent's setup guide. For warehouse selection and SQL-specific options, see the Databricks SQL MCP reference.

Run a predefined query with a Unity Catalog function

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. It assumes you have a customer_data table with customer_name, customer_id, and customer_email columns.

Review the function requirements and permissions. Replace my_catalog.my_schema with a catalog and schema where you can create functions, and adapt the table and column names to your data. Run the following code in a SQL editor:

SQL

CREATE FUNCTION my_catalog.my_schema.lookup_customer_info(
  customer_name_input 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 my_catalog.my_schema.customer_data
  WHERE customer_name = customer_name_input
  LIMIT 1;

Test the function with a customer name from your table:

SQL

SELECT my_catalog.my_schema.lookup_customer_info('Example Customer');

Then use Unity Catalog AI to add the function to your agent. That guide includes LangGraph, OpenAI, Anthropic, and LlamaIndex examples.

Use Genie in a multi-agent system

To coordinate Genie Agents with other agents and tools, see Supervisor Agent. For existing Model Serving integrations, see Use Genie in multi-agent systems.

Query a Genie Agent using MCP (legacy)

For an existing MCP integration with a specific Genie Agent, see the legacy Genie Agent MCP reference for its URL and requirements. For new Python agents, use the AI Bridge tool examples.