What you will be able to do
- Explain what a Genie Agent (formerly Genie Space) is and which Genie API families exist
- List the prerequisites and curation practices that make a Genie Agent return reliable results to an agent
- Connect an agent to a Genie Agent through the managed Genie MCP server URL
- State the limitations of the Genie MCP server (read-only, no conversation history)
Key concept
Genie Agent as a natural-language data tool — A Genie Agent is a curated set of Unity Catalog tables plus instructions and example SQL. Another agent can send it a plain-language question, and Genie writes and runs the SQL and returns the result, so the calling agent never has to write SQL itself.
1.Genie Agents and the Genie API families
Older exam material and blog posts say Genie Spaces. The current documentation calls the same thing a Genie Agent. The rename did not change the configuration: identifiers such as space_id and the genie_space resource type still use the old word. A Genie Agent is a domain-specific chat interface. Data analysts curate it with datasets registered in Unity Catalog, example SQL queries, SQL expressions for business semantics, and text instructions written in the organization's own terms. Users ask questions and get back SQL queries, result tables and visualizations.
For a multi-agent system, what matters is that you can call a Genie Agent from code. The Genie API (the "conversational API" in the exam guide) has three families of capabilities, and each one does a different job.
| API family | What it does | Typical use |
|---|---|---|
| Chat mode APIs | Natural-language data querying with stateful conversations, follow-up questions and history | Chatbots, applications and agent frameworks that retrieve data |
| Agent mode APIs | Send prompts in Agent mode, stream the reasoning and SQL results, and receive final reports with citations | Programmatic deep-analysis requests |
| Management APIs | Create, configure and deploy Genie Agents across workspaces | CI/CD pipelines, version control, automated agent management |
You can call these APIs directly over REST or through the Databricks SDKs. When an agent needs to retrieve data and handle follow-up questions, the Chat mode APIs are the relevant family, because they keep conversation state between turns.
The managed MCP server is a different route from calling the Chat mode APIs yourself. The MCP server invokes Genie as a tool, so it does not pass conversation history to the Genie API. For advanced multi-agent systems, the docs say you can instead use Genie as an agent rather than through MCP, and then you can deterministically pass in existing conversation context to Genie.
Checkpoint 1 of 3· Check yourself
A team wants its customer-facing chatbot to answer data questions and handle follow-ups such as "now break that down by region." Which Genie API family fits?
Chat mode APIs are the family built for stateful natural-language querying with follow-up questions. Management APIs handle deployment and CI/CD.
“These APIs support stateful conversations created in Chat mode where users can ask follow-up questions and explore data naturally over time.”Source: docs.databricks.com
2.Prerequisites and a well-curated Genie Agent
No. The documentation is direct about this: the Genie Agent supplies the context Genie uses to interpret a question, so a badly curated agent gives wrong answers even when the integration is correct. Before you wire Genie into a multi-agent system, check two things.
Access prerequisites. The caller needs a workspace with the Databricks SQL entitlement and at least CAN USE on a SQL pro or serverless SQL warehouse. In production, use OAuth for users (U2M) when a person with a browser is present. Otherwise use a service principal (OAuth M2M), and that service principal must have permissions on the data and the warehouses. To call an existing agent you also need its space ID. You can get it from the List Genie Agents API or copy it from the agent's Settings tab.
Curation practices. A well-structured Genie Agent: - uses well-annotated data, because Genie relies on table metadata and column comments in Unity Catalog - is tested with the questions you expect end users to ask - includes company-specific context (instructions, example SQL, functions), with at least five tested example SQL queries - has at least five benchmark questions to measure accuracy
Genie turns the question into SQL using the table metadata and column comments. Poorly described columns give Genie less to work with, and the orchestrating agent cannot correct SQL it never sees.
Checkpoint 2 of 3· Check yourself
A background agent with no browser session must call the Genie API in production. Which authentication approach do the docs recommend?
When browser-based authentication is not possible, the docs say to use a service principal, and it must have access to the required data and warehouses.
“In situations where browser-based authentication is not possible, use a service principal to authenticate with the API.”Source: docs.databricks.com
Sources1
3.Connecting an agent through the Genie Agent MCP server
The simplest way to give an agent access to a Genie Agent is the Genie Agent MCP server. Databricks hosts and manages it, and Unity Catalog permissions are enforced on every request. Databricks recommends Genie Agents when an agent needs to query Unity Catalog tables. Each server is scoped to one Genie Agent, which holds up to 25 tables in context, instead of your whole workspace. The URL pattern is https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id} and the OAuth scope is genie. Usage is billed at serverless SQL compute pricing.
Do not confuse it with the Genie One MCP server, which is a separate managed server for natural-language analytics across your workspace (OAuth scope ai-gateway). For analytics use cases the docs say to start with Genie One, because Genie resolves business terms through your governed semantic layer. Choose the Genie Agent MCP server when you want to scope the agent to one curated Genie Agent.
Setup takes three steps. Create the Genie Agent. Share it with the users or service principals that need it. Point your agent at the MCP URL. With the OpenAI Agents SDK, the Genie server is passed in mcp_servers:
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)LangGraph uses the same URL through DatabricksMultiServerMCPClient. For Model Serving, you list tools with DatabricksMCPClient and log the agent with resources=mcp_client.get_databricks_resources() so that deployment gets the Genie permissions. On Databricks Apps, you grant the app CAN_RUN on the space in databricks.yml, as shown here:
resources:
apps:
my_agent_app:
resources:
- name: 'my_genie_space'
genie_space:
space_id: '<genie-space-id>'
permission: 'CAN_RUN'Checkpoint 3 of 3· Fill the gap
Complete the managed MCP URL so this LangGraph agent gets a Genie Agent as a tool.
mcp_client = DatabricksMultiServerMCPClient([
DatabricksMCPServer(
name="genie-space",
url=f"{host}/api/2.0/mcp/ ? /<genie-space-id>",
workspace_client=workspace_client,
),
])The Genie Agent managed MCP server lives at /api/2.0/mcp/genie/{genie_space_id}. The sql path is the Databricks SQL MCP server, which runs SQL directly and does not use Genie.
Source: docs.databricks.comThe server has two limits you need to know. It is read-only: it queries data and never writes to your tables. It also passes no conversation history. The Chat mode API is stateful, but the MCP server calls Genie as a stateless tool. If you need history preserved across turns, the docs point you to Genie in a multi-agent system.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Because the Genie Chat mode API is stateful, an agent that connects through the Genie Agent MCP server automatically gets follow-up context.Why is that wrong?
The managed MCP server calls Genie as a tool and does not pass history. To preserve history, use Genie in a multi-agent system.
Covered in Connecting an agent through the Genie Agent MCP server
2.If the Genie API integration is implemented correctly, the agent will get correct data answers.Why is that wrong?
Answer quality depends on how well the Genie Agent is curated: annotated tables, tested example SQL and benchmarks. An untested agent can return wrong results through a correct integration.
Covered in Prerequisites and a well-curated Genie Agent
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Genie Agents were formerly known as Genie Spaces.”
↩︎ Genie Agents and the Genie API families“Chat mode APIs: Enable natural language data querying in applications, chatbots, and agent frameworks.”
↩︎ Genie Agents and the Genie API families“Use these APIs for CI/CD pipelines, version control, and automated agent management.”
↩︎ Genie Agents and the Genie API families“At least CAN USE privileges on a SQL pro or serverless SQL warehouse.”
↩︎ Prerequisites and a well-curated Genie Agent“Genie relies on table metadata and column comments.”
↩︎ Prerequisites and a well-curated Genie Agent“Aim for at least five tested example SQL queries.”
↩︎ Prerequisites and a well-curated Genie Agent“you can find the space ID using the List Genie Agents API”
↩︎ Prerequisites and a well-curated Genie Agent“If the agent is incomplete or untested, users might still receive incorrect results even with a correct API integration.”
↩︎ Exam trap 2“These APIs support stateful conversations created in Chat mode where users can ask follow-up questions and explore data naturally over time.”
↩︎ Checkpoint“In situations where browser-based authentication is not possible, use a service principal to authenticate with the API.”
↩︎ Checkpoint - 2.https://docs.databricks.com/aws/en/genie-agentsOfficial docs
“Data analysts curate each agent with datasets registered to Unity Catalog, example SQL queries, SQL expressions for business semantics, and text instructions”
↩︎ Genie Agents and the Genie API families - 3.
“When you call Genie as an agent, you can deterministically pass in existing conversation context to Genie.”
↩︎ Genie Agents and the Genie API families“If your agent needs to query data in Unity Catalog tables, Databricks recommends using Genie Agents.”
↩︎ Connecting an agent through the Genie Agent MCP server - 4.
“A Genie Agent is a collection of up to 25 Unity Catalog tables that Genie keeps in context”
↩︎ Connecting an agent through the Genie Agent MCP server“Read-only. The Genie Agent MCP server queries data; it doesn't write to your tables.”
↩︎ Connecting an agent through the Genie Agent MCP server“lets an agent query a single Genie Agent with natural language, without writing SQL”
↩︎ Key concept“To preserve history across turns, use Genie in a multi-agent system.”
↩︎ Exam trap 1 - 5.
“Genie Agents use serverless SQL compute pricing.”
↩︎ Connecting an agent through the Genie Agent MCP server“For analytics use cases, start with the Genie One MCP server.”
↩︎ Connecting an agent through the Genie Agent MCP server