What you will be able to do
- Choose between the Genie MCP server, Genie as an agent, the Databricks SQL MCP server and Unity Catalog functions for structured retrieval
- Configure Supervisor Agent with a Genie Agent subagent and the end-user permissions it needs
- Define a Genie subagent in a custom Databricks Apps orchestrator and declare its CAN_RUN resource
1.Choosing how a multi-agent system reaches structured data
A multi-agent system sends each request to the specialist that suits it best. A common combination is a RAG agent over unstructured documents alongside a Genie agent over structured data, so users get answers from both kinds of source. The design decision is how the structured-data specialist gets connected.
| Option | When to choose it | Key property |
|---|---|---|
| Genie One MCP server | Natural-language analytics across your workspace; the documented starting point for analytics use cases | Genie resolves business terms through Genie Ontology, your governed semantic layer |
| Genie Agent MCP server (/api/2.0/mcp/genie/{genie_space_id}) | Natural-language questions over a curated set of Unity Catalog tables in one Genie Agent | Read-only; no conversation history passed |
| Genie as an agent (Public Preview) | Advanced multi-agent systems that need context across turns | Conversation context passed deterministically |
| Databricks SQL MCP server (/api/2.0/mcp/sql) | Running a specific query you already wrote, such as validating syntax or authoring a pipeline | Exposes SQL execution as a tool against a SQL warehouse, governed by Unity Catalog permissions |
| Unity Catalog SQL function | The query is known ahead of time and the agent only supplies parameters | Deterministic, repeatable queries |
The difference between Genie and the SQL MCP server is who supplies the SQL. With Genie, the agent sends a plain-language question and Genie writes and runs the SQL, using your governed semantic layer. With the Databricks SQL MCP server, the agent works at the SQL level through a SQL warehouse, which suits developer queries and data engineering. For analytics, the docs say to start with Genie One.
Genie as an agent is the alternative to the MCP integration for advanced multi-agent systems. Because the MCP server invokes Genie as a tool, history is not passed. Calling Genie as an agent lets you pass in existing conversation context deterministically. There are two documented routes. The code-first route is the "Use Genie in multi-agent systems (Model Serving)" guide. The UI-first route is Supervisor Agent. The two sections below cover Supervisor Agent and the other code route, a custom orchestrator on Databricks Apps.
If you call Genie from your own application, the Genie API's Chat mode APIs support stateful conversations, where users can ask follow-up questions and explore data over time. Agent mode APIs send prompts in Agent mode and stream the reasoning and SQL results. Management APIs handle creating, configuring and deploying Genie Agents across workspaces. The Databricks SDKs can call these APIs as well. The runtime endpoints and request and response formats are documented in the Genie API reference, which this lesson does not reproduce.
Checkpoint 1 of 5· Match them up
Match each requirement to the structured-data integration it points to.
Tap a term, then the definition that fits it.
Genie handles natural-language questions. Unity Catalog functions cover known queries with parameters. Genie-as-agent passes context. The SQL MCP server runs SQL you supply.
“Create a structured retrieval tool using Unity Catalog SQL functions when the query is known ahead of time and the agent provides the parameters.”Source: docs.databricks.com
Checkpoint 2 of 5· Exam question
A developer is writing a custom Python agent that does not use Agent Bricks and needs to programmatically ask a brand-new question against a Genie space with `space_id=abc123` for the very first time in a session. Which API call should the agent issue first to obtain a conversation ID and message ID?
Correct answer: A — `POST /api/2.0/genie/spaces/abc123/start-conversation`, sending the question text in the request body to begin the thread.
- A. This is correct because the start-conversation endpoint on a Genie space is the documented call for beginning a new conversation thread; it returns the conversation ID and message ID needed for any follow-up calls.
- B. This is incorrect because the messages endpoint requires an existing `conversation_id` in its path and is used to continue a conversation that has already been started, not to create the first one.
- C. This is incorrect because that endpoint is a GET request used to poll the status of a previously created message, not to submit a new natural-language question.
- D. This is incorrect because the SQL Statement Execution API runs literal SQL text; it has no natural-language understanding and does not interact with Genie space conversation state.
2.Supervisor Agent: UI-first orchestration with Genie subagents
Supervisor Agent builds a multi-agent supervisor system for you. It coordinates Genie Agents alongside agent endpoints, Unity Catalog functions, MCP servers and custom agents, and handles task delegation and result synthesis. Subject matter experts can improve its coordination over time by giving feedback in natural language. The result is an endpoint you can query in Playground or build a Databricks Apps chat application on.
You must provide at least one subagent. The workspace needs serverless compute, Unity Catalog, Model Serving access, and a serverless usage policy with a nonzero budget.
The requirement most often missed is permissions. The supervisor has built-in access controls, so each end user reaches only the subagents and data they already have access to. For a Genie Agent subagent, the end user needs access to the Genie Agent and to its underlying Unity Catalog objects. Compare the other subagent types: a Knowledge Assistant or model serving endpoint needs CAN QUERY, and a Unity Catalog function needs EXECUTE.
Checkpoint 3 of 5· Check yourself
A supervisor endpoint includes a Genie Agent subagent. Some end users get unhelpful answers whenever a question routes to Genie. What is the most likely cause?
End users need explicit access to each subagent. For a Genie Agent that means the agent itself and its Unity Catalog objects, and without that access the supervisor cannot return a useful response from it.
“Without explicit access, the supervisor cannot return helpful responses from a subagent.”Source: docs.databricks.com
Sources5
3.Custom orchestrator on Databricks Apps with a Genie subagent
Build your own orchestrator only when you need custom routing or orchestration behavior that Supervisor Agent does not support. The Databricks template (agent-openai-agents-sdk-multiagent) uses the OpenAI Agents SDK. It treats each subagent as a tool and routes using the subagent's instructions. Genie subagents connect through the built-in Databricks MCP server. Other Databricks Apps agents and serving endpoints connect through the Responses API.
The docs state that the managed Genie MCP server does not pass conversation history, and they point to Genie as an agent when you need history. They do not say how the template's genie subagent type treats history, so confirm that behavior before you depend on multi-turn context.
SUBAGENTS = [
{
"name": "genie",
"type": "genie",
"space_id": "<YOUR-GENIE-SPACE-ID>",
"description": (
"Query a Genie Agent for structured data analysis. "
"Use this for questions about data, metrics, and tables."
),
},Each entry becomes a tool automatically. Routing accuracy depends on two pieces of text: the description of each subagent and the orchestrator's instructions. Name the dataset and topic Genie covers, and tell the orchestrator to ask for clarification when it is unsure. Then declare the Genie resource in databricks.yml so the app's service principal can query the space:
Checkpoint 4 of 5· Fill the gap
Which permission lets the orchestrator app submit questions to the Genie Agent?
resources:
- name: 'genie_space'
genie_space:
name: 'Genie Agent'
space_id: '<YOUR-GENIE-SPACE-ID>'
permission: ' ? 'Genie subagents need CAN_RUN on the space. CAN_QUERY is for serving endpoints, and CAN_USE is for subagent Databricks apps.
Source: docs.databricks.comFor a Genie Agent app resource, the levels are Can view (read configuration), Can run (submit queries and receive responses), Can edit and Can manage. Access covers only the selected agent, so every additional Genie Agent has to be added as its own resource. CAN_RUN is still not enough on its own: the app's service principal also needs permissions on the data Genie queries, typically USE CATALOG, USE SCHEMA and SELECT.
Checkpoint 5 of 5· Exam question
An agent has already sent a message to a Genie space and received a `message_id`. It now needs to obtain the tabular result of the query Genie generated so it can pass the rows back to the orchestrating agent. What is the correct sequence to follow?
Correct answer: A — Poll `GET .../messages/{message_id}` until the status is conclusive (such as completed), then call `GET .../messages/{message_id}/query-result/{attachment_id}` to fetch the rows.
- A. This is correct because message processing is asynchronous: the agent must poll the message endpoint until a conclusive status is reached before the generated SQL's results become retrievable via the query-result endpoint keyed by attachment ID.
- B. This is incorrect because SQL generation and execution take time and are not guaranteed to finish synchronously; fetching the query result before processing completes will not reliably return the finished rows.
- C. This is incorrect because deleting a conversation removes it rather than finalizing it, and starting a brand-new conversation discards the in-progress question instead of retrieving its results.
- D. This is incorrect because repeatedly calling start-conversation creates a new conversation thread each time rather than checking the status of the message that was already submitted.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Granting the orchestrator app CAN_RUN on the Genie Agent is all it needs to return data.Why is that wrong?
The app's service principal also needs permissions on the underlying data sources, typically USE CATALOG, USE SCHEMA and SELECT on the relevant tables.
Covered in Custom orchestrator on Databricks Apps with a Genie subagent
2.Once a Genie Agent is added to Supervisor Agent, every end user of the supervisor endpoint can get answers from it.Why is that wrong?
The supervisor enforces built-in access controls. Each end user needs access to the Genie Agent and its underlying Unity Catalog objects.
Covered in Supervisor Agent: UI-first orchestration with Genie subagents
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“For example, you can combine a RAG agent that queries unstructured documents with a Genie agent that queries structured data”
↩︎ Choosing how a multi-agent system reaches structured data“Build a multi-agent system on Databricks Apps if you need custom routing logic or orchestration behavior that Agent Supervisor doesn't support.”
↩︎ Custom orchestrator on Databricks Apps with a Genie subagent“Genie Agents: Natural language data querying through the built-in Databricks MCP server.”
↩︎ Custom orchestrator on Databricks Apps with a Genie subagent“Description quality is directly related to how well the orchestrator can route requests to the correct subagent”
↩︎ Custom orchestrator on Databricks Apps with a Genie subagent - 2.
“For a code-first approach, see Use Genie in multi-agent systems (Model Serving). For a UI-first approach, see Use Supervisor Agent”
↩︎ Choosing how a multi-agent system reaches structured data“The managed MCP server for Genie invokes Genie as an MCP tool, which means history isn't passed when invoking Genie APIs.”
↩︎ Choosing how a multi-agent system reaches structured data“When you call Genie as an agent, you can deterministically pass in existing conversation context to Genie.”
↩︎ Prediction“Create a structured retrieval tool using Unity Catalog SQL functions when the query is known ahead of time and the agent provides the parameters.”
↩︎ Checkpoint - 3.
“For analytics use cases, start with the Genie One MCP server.”
↩︎ Choosing how a multi-agent system reaches structured data“Use the Databricks SQL MCP server when you need to run a specific query you already wrote”
↩︎ Choosing how a multi-agent system reaches structured data - 4.
“Chat mode APIs: Enable natural language data querying in applications, chatbots, and agent frameworks.”
↩︎ Choosing how a multi-agent system reaches structured data - 5.
“coordinates Genie Agents, agent endpoints, Unity Catalog functions, MCP servers, and custom agents to work together”
↩︎ Supervisor Agent: UI-first orchestration with Genie subagents“Access to the Genie Agent and its underlying Unity Catalog objects.”
↩︎ Supervisor Agent: UI-first orchestration with Genie subagents“The supervisor has built-in access controls, so that its end users only access the subagents and data they have access to.”
↩︎ Exam trap 2“Without explicit access, the supervisor cannot return helpful responses from a subagent.”
↩︎ Checkpoint - 6.
“To preserve history across turns, use Genie in a multi-agent system.”
↩︎ Custom orchestrator on Databricks Apps with a Genie subagent - 7.
“Can run: Grants the app permission to submit queries to the Genie Agent and receive responses.”
↩︎ Custom orchestrator on Databricks Apps with a Genie subagent“Access is scoped to the selected agent only.”
↩︎ Custom orchestrator on Databricks Apps with a Genie subagent“The app's service principal also needs appropriate permissions on the underlying data sources that the Genie Agent queries.”
↩︎ Exam trap 1