Skip to main content

Integrating with Agents

This page covers the integration mechanisms for calling Databricks agents from connected partner products. Three integration surfaces are available, each serving a different partner need:

SurfacePurposeWhen to use
Genie OneWorkspace-wide natural-language analyticsBroad Q&A across all customer data — ask anything
Genie AgentsDomain-specific AI experts — partner-created or customer-createdFixed, branded, single-domain experience with deterministic accuracy
Agent Bricks custom agentsPartner-built custom agentsCustom logic, tools, or workflows specific to the partner's product
Genie Attribution

All integrations that surface Genie results must display a "Powered by Genie" attribution label and include a citation linking to the source Genie Agent. See Genie Attribution.

Genie One​

Genie One is the workspace-wide, ontology-grounded AI coworker. Users ask questions in natural language; Genie One resolves business terms and metrics against the Unity Catalog semantic graph, generates SQL, and returns answers — all within the calling user's security boundaries. Under the hood, Genie One can orchestrate across domain-specific Genie Agents or write queries directly using Genie Ontology, but from the partner's perspective it is one surface: ask a question, get a governed answer.

There is no direct ontology graph or metadata API. Partners do not query the ontology directly — Genie One resolves business terms, metrics, and table relationships as part of answering. If you have been looking for an ontology API, Genie One is the integration path.

Use cases​

  • Embedded analytics — partner product calls Genie One behind the scenes, Unity Catalog enforces end-user identity
  • Conversational BI — business analysts get ontology-aware answers without leaving the partner application

Integration mechanisms​

MechanismProtocolDescriptionBest for
Genie One MCPMCPRecommended default. Standard MCP integration — ask a question, poll for completion, fetch the result. Most MCP clients get plain text responses.Partners with MCP-capable clients or agent frameworks
Genie One MCP for MCP Apps clientsMCP + MCP AppsSame integration, but clients supporting the MCP Apps specification get richer inline rendering — charts, citations, and live progress instead of text-only.Partners with MCP clients that support the MCP Apps specification
Responses API ★REST / SSEStreaming alternative without MCP — OpenResponses-compatible profile. Coming soon; not yet generally available.Partners planning native streaming integrations

Ontology​

The Genie Ontology captures business meaning in Unity Catalog. Partners interact with it through two verbs:

  • Enrich (write): work directly in Unity Catalog — Metric Views (GA), Pages (Beta), Domains (PuPr). These are the only partner-actionable write surfaces.
  • Consume (read): there is no direct ontology API. Genie One resolves business terms and metrics against the ontology under the hood when answering a question.

Genie One vs. Genie Agent​

Default to Genie One for broad, ask-anything analytics — it routes to the right curated agent automatically. Target a specific Genie Agent when the partner needs a fixed, branded, single-domain experience where deterministic accuracy outweighs workspace-wide breadth.

API details​

Genie One MCP:

  • Endpoint: https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp
  • OAuth scope: ai-gateway
  • Tools: genie_ask, genie_poll_response, genie_get_query_result, genie_cancel_response, view_ask
  • Flow: genie_ask starts a response → poll with genie_poll_response → use genie_get_query_result for full (non-truncated) results

Documentation: Genie One MCP server | Managed MCP servers | Connect MCPs to AI assistants and coding agents

Genie Agents​

A Genie Agent is a curated, domain-specific AI expert — scoped to a set of Unity Catalog tables or metric views (up to 30), with domain-specific instructions, a knowledge store, example SQL queries, and benchmarks. Each Genie Agent runs as a compound AI system with multi-step planning, schema verification, and self-correction loops.

Partners can both create Genie Agents and call them. Use the Management API (POST / GET / PATCH /api/2.0/genie/spaces) to provision custom Genie Agents tailored to your product or customer use cases — for example, onboarding templates that spin up a ready-made domain expert the moment a customer connects. Partners can also integrate with existing customer-created Genie Agents through the calling mechanisms below.

Use cases​

  • Domain-specific analytics — a dedicated "Sales Analytics" or "Fleet Operations" agent embedded in the partner product
  • Embedded domain agent — streaming the agent's reasoning trace into a partner chatbot or application

Integration mechanisms​

MechanismProtocolDescriptionBest for
Agent Mode API (recommended)REST / SSEStreams the response with structured output items: reasoning, function_call/output, message. Multi-step reasoning built in.Partner chatbots, alerts, and embedded apps that need real-time streaming
Conversation APIREST (polling)Start a conversation, poll until complete, fetch result. Supports full non-truncated result download.Backend integrations, scheduled reports, no real-time requirement
Genie Agent MCPMCPSame MCP pattern as Genie One, scoped to a single agent instead of the whole workspace.MCP-native platforms needing a dedicated domain agent

API details​

Agent Mode API:

  • Endpoint: POST /api/2.0/genie/agents/{agent_id}/responses
  • Streaming: Server-Sent Events with structured output items — reasoning, function_call / function_call_output, message (with table chunks)
  • Conversations: pass conversation_id to continue a thread; omit to start new

Conversation API:

  • Endpoint: POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
  • Result download: POST .../attachments/{attachment_id}/downloads for full non-truncated results via short-lived presigned URLs

Genie Agent MCP:

  • Endpoint: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}
  • OAuth scope: genie
  • Same MCP tools and flow as Genie One MCP, but scoped to this one agent

Documentation: Create and manage a Genie Agent | Genie Agents concepts | Use the Genie Agents API | Agent Mode API reference | Genie Conversation API reference | Genie Space API reference

Agent Bricks custom agents​

Partners can both create Agent Bricks custom agents and call existing ones. Build and deploy custom agents using the Agent Platform, or integrate with agents already running in a customer's workspace. Connected partners call Agent Bricks agents through the OpenAI-compatible API — using the Databricks OpenAI Client (recommended) or direct REST calls. Agent Bricks agents are deployed to Databricks Apps and queried via the standard Responses or Chat Completions interface.

For building and configuring custom agents, see the Agent Platform page.

Documentation: Query an agent deployed on Databricks | Agent Bricks

What's next​