databricks-genie-agents
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDatabricks Genie Agents
Databricks Genie Agents
Create, manage, and query Genie Agents (formerly Genie Spaces) - natural language interfaces for SQL-based data exploration.
创建、管理和查询Genie Agents(原名为Genie Spaces)——基于SQL的数据探索自然语言接口。
Overview
概述
Genie Agents allow users to ask natural language questions about structured data in Unity Catalog. The system translates questions into SQL queries, executes them on a SQL warehouse, and presents results conversationally.
A Genie Agent is a curated agent scoped to specific data — its tables, sample questions, and instructions are authored for a particular business area. This is distinct from Genie One / the general "ask Genie" data-discovery path (see the skill), which answers questions across your data without a curated, per-scope agent.
databricks-data-discoveryGenie Agents允许用户向Unity Catalog中的结构化数据提出自然语言问题。系统会将问题转换为SQL查询,在SQL warehouse上执行,并以对话形式呈现结果。
Genie Agent是针对特定数据精心策划的代理——其关联的表、示例问题和说明都是为特定业务领域编写的。这与Genie One/通用的“询问Genie”数据探索路径(请查看技能)不同,后者无需特定范围的精心策划代理即可跨所有数据回答问题。
databricks-data-discoveryCreating a Genie Agent
创建Genie Agent
Step 1: Understand the Data
步骤1:了解数据
Before creating a Genie Agent, explore the available tables to:
- Select relevant tables — typically gold layer (aggregated KPIs) and sometimes silver layer (cleaned facts) or metric views
- Understand the story — what business questions can this data answer? What insights can users discover?
- Design meaningful sample questions — questions should reflect real use cases and lead to actionable insights in the data
Use as the default — one call returns columns, types, sample rows, null counts, and row count. If you only know the schema, list tables first with .
discover-schemaquery "SHOW TABLES IN ..."databricks experimental aitools tools discover-schema catalog.schema.gold_sales catalog.schema.gold_customersFor Genie, knowing column distribution shapes the sample questions and text instructions. If you don't already know the data, probe cardinality, ranges, and top categorical values with aggregate SQL through so your sample questions reflect what's actually in the data. Both commands auto-pick the default warehouse; set or pass to override.
databricks experimental aitools tools query --warehouse <WH> "..."DATABRICKS_WAREHOUSE_ID--warehouse <ID>Fan out independent probes with (returns a statement_id immediately) + (blocks until terminal: ):
databricks experimental aitools tools statement submit... getSUCCEEDED|FAILED|CANCELED|CLOSEDbash
SIDS=()
for q in "$@"; do
SIDS+=( "$(databricks experimental aitools tools statement submit --warehouse "$WH" "$q" | jq -r .statement_id)" )
done
for s in "${SIDS[@]}"; do databricks experimental aitools tools statement get "$s"; done创建Genie Agent之前,请先探索可用的表,以:
- 选择相关表——通常是黄金层(聚合KPI),有时也包括白银层(清洗后的事实表)或指标视图
- 理解业务场景——这些数据可以回答哪些业务问题?用户可以发现哪些洞察?
- 设计有意义的示例问题——问题应反映实际用例,并能引导从数据中获取可执行的洞察
默认使用命令——一次调用即可返回列、类型、示例行、空值计数和行数。如果仅了解架构,请先使用列出表。
discover-schemaquery "SHOW TABLES IN ..."databricks experimental aitools tools discover-schema catalog.schema.gold_sales catalog.schema.gold_customers对于Genie而言,了解列分布情况有助于设计示例问题和文本说明。如果尚未了解数据,请通过执行聚合SQL来探查基数、范围和分类值的Top数据,这样示例问题就能反映数据的实际情况。这两个命令都会自动选择默认仓库;可设置或传递来覆盖默认设置。
databricks experimental aitools tools query --warehouse <WH> "..."DATABRICKS_WAREHOUSE_ID--warehouse <ID>使用(立即返回statement_id)+ (阻塞直到状态变为)来并行执行多个独立探查:
databricks experimental aitools tools statement submit... getSUCCEEDED|FAILED|CANCELED|CLOSEDbash
SIDS=()
for q in "$@"; do
SIDS+=( "$(databricks experimental aitools tools statement submit --warehouse "$WH" "$q" | jq -r .statement_id)" )
done
for s in "${SIDS[@]}"; do databricks experimental aitools tools statement get "$s"; doneUse status
for non-blocking peek; cancel
to terminate.
statuscancel使用status
进行非阻塞式查看;使用cancel
终止任务。
statuscancelundefinedundefinedStep 2: Create the Genie Agent
步骤2:创建Genie Agent
Define your Genie Agent in a local JSON file (e.g., ) for version control and easy iteration. See "serialized_space Format" below for the full structure.
genie_agent.jsonbash
undefined在本地JSON文件(例如)中定义Genie Agent,以便进行版本控制和迭代。请查看下方的“serialized_space 格式”了解完整结构。
genie_agent.jsonbash
undefinedList all Genie Agents
列出所有Genie Agent
databricks genie list-spaces
databricks genie list-spaces
Create a Genie Agent from a local file
从本地文件创建Genie Agent
IMPORTANT: sample_questions require a 32-char hex "id" and "question" must be an array
重要提示:sample_questions需要32位十六进制的"id",且"question"必须是数组
IMPORTANT: parent_path must ALREADY EXIST — create it first, or create fails with
重要提示:parent_path必须已存在——请先创建该路径,否则创建会失败并提示
"Tree node with path ... does not exist":
"Tree node with path ... does not exist":
databricks workspace mkdirs /Workspace/Users/you@company.com/genie_spaces
databricks genie create-space --json "{
"warehouse_id": "WAREHOUSE_ID",
"title": "Sales Analytics",
"description": "Explore sales data",
"parent_path": "/Workspace/Users/you@company.com/genie_spaces",
"serialized_space": $(cat genie_agent.json | jq -c '.' | jq -Rs '.')
}"
databricks workspace mkdirs /Workspace/Users/you@company.com/genie_spaces
databricks genie create-space --json "{
"warehouse_id": "WAREHOUSE_ID",
"title": "Sales Analytics",
"description": "Explore sales data",
"parent_path": "/Workspace/Users/you@company.com/genie_spaces",
"serialized_space": $(cat genie_agent.json | jq -c '.' | jq -Rs '.')
}"
Get agent details (with full config)
获取代理详情(包含完整配置)
databricks genie get-space SPACE_ID --include-serialized-space
databricks genie get-space SPACE_ID --include-serialized-space
Tag the Genie Agent for resource tracking — use any tag the user indicated for their
为Genie Agent添加标签以进行资源跟踪——使用用户为项目指定的任意标签;否则默认使用ai_generated_source=databricks-agent-skills
。
ai_generated_source=databricks-agent-skillsproject; otherwise default to ai_generated_source=databricks-agent-skills
.
ai_generated_source=databricks-agent-skills(Beta版CLI接口——如果命令失败可忽略。)
(Beta CLI surface — ignore if the command fails.)
—
databricks workspace-entity-tag-assignments create-tag-assignment
geniespaces SPACE_ID ai_generated_source --tag-value databricks-agent-skills || true
geniespaces SPACE_ID ai_generated_source --tag-value databricks-agent-skills || true
databricks workspace-entity-tag-assignments create-tag-assignment
geniespaces SPACE_ID ai_generated_source --tag-value databricks-agent-skills || true
geniespaces SPACE_ID ai_generated_source --tag-value databricks-agent-skills || true
Delete a Genie Agent
删除Genie Agent
databricks genie trash-space SPACE_ID
undefineddatabricks genie trash-space SPACE_ID
undefinedStep 3: Test and Iterate
步骤3:测试与迭代
Use the Conversation API (section below) to ask questions and verify answers. If answers are inaccurate or incomplete, improve the agent — see "Improving a Genie Agent" below.
使用下方的Conversation API提问并验证答案。如果答案不准确或不完整,请优化代理——请查看下方的“优化Genie Agent”部分。
Export & Import
导出与导入
Convention: always holds the parsed agent object (not a JSON-string-encoded blob), so it's readable and editable. At each use site we stringify it with — same pattern as Step 2 Create and "Improving a Genie Agent" below. on export strips the outer quoting so the file is already a parsed object.
genie_agent.jsonjq -c '.' | jq -Rs '.'jq -r '.serialized_space | fromjson'bash
undefined约定: 始终保存解析后的代理对象(不是JSON字符串编码的 blob),以便于阅读和编辑。在每个使用场景中,我们使用将其字符串化——与步骤2的创建操作和下方的“优化Genie Agent”操作模式相同。导出时使用可以去除外层引号,使文件直接成为解析后的对象。
genie_agent.jsonjq -c '.' | jq -Rs '.'jq -r '.serialized_space | fromjson'bash
undefinedExport: extract serialized_space AND unwrap it to a parsed object on disk
导出:提取serialized_space并将其转换为解析后的对象保存到磁盘
databricks genie get-space SPACE_ID --include-serialized-space -o json
| jq '.serialized_space | fromjson' > genie_agent.json
| jq '.serialized_space | fromjson' > genie_agent.json
databricks genie get-space SPACE_ID --include-serialized-space -o json
| jq '.serialized_space | fromjson' > genie_agent.json
| jq '.serialized_space | fromjson' > genie_agent.json
Import: same stringify pattern as Step 2 (Create)
导入:使用与步骤2(创建)相同的字符串化模式
databricks genie create-space --json "{
"warehouse_id": "WAREHOUSE_ID",
"title": "Sales Analytics",
"description": "Migrated agent",
"parent_path": "/Workspace/Users/you@company.com/genie_spaces",
"serialized_space": $(cat genie_agent.json | jq -c '.' | jq -Rs '.')
}"
undefineddatabricks genie create-space --json "{
"warehouse_id": "WAREHOUSE_ID",
"title": "Sales Analytics",
"description": "Migrated agent",
"parent_path": "/Workspace/Users/you@company.com/genie_spaces",
"serialized_space": $(cat genie_agent.json | jq -c '.' | jq -Rs '.')
}"
undefinedImproving a Genie Agent
优化Genie Agent
Recommendation-first: when asked to optimize, tune, or fix an Agent (or its queries/tables), start by diagnosing and presenting a recommended change — do not run mutating actions (, , , liquid clustering, warehouse changes) until the user approves. Diagnose with read-only queries only.
update-spaceALTEROPTIMIZEWrong filter values (Genie filters on a value that returns nothing — e.g. asking for when the column stores a different code or casing): fix with prompt matching / synonyms mapping the user's term to the actual categorical value, not a hardcoded text instruction.
cancelledWhen Genie answers are inaccurate or incomplete, improve the agent by updating questions, SQL examples, or instructions:
bash
undefined优先推荐: 当要求优化、调整或修复代理(或其查询/表)时,请先诊断并提出建议的更改——在用户批准之前,不要执行变更操作(、、、液态聚类、仓库更改)。仅使用只读查询进行诊断。
update-spaceALTEROPTIMIZE过滤值错误(Genie过滤的值返回空结果——例如查询但列中存储的是其他代码或大小写不同的值):使用提示匹配/同义词映射将用户术语转换为实际的分类值,而非硬编码文本说明。
cancelled当Genie的答案不准确或不完整时,可以通过更新问题、SQL示例或说明来优化代理:
bash
undefined1. Edit your local genie_agent.json (add questions, fix SQL examples, improve instructions)
1. 编辑本地的genie_agent.json(添加问题、修复SQL示例、优化说明)
2. Push updates back to the agent
2. 将更新推送到代理
databricks genie update-space SPACE_ID --json "{"serialized_space": $(cat genie_agent.json | jq -c '.' | jq -Rs '.')}"
undefineddatabricks genie update-space SPACE_ID --json "{"serialized_space": $(cat genie_agent.json | jq -c '.' | jq -Rs '.')}"
undefinedserialized_space Format
serialized_space 格式
The field is a JSON string containing the full space configuration.
serialized_spaceserialized_spaceField Format Requirements
字段格式要求
IMPORTANT: All items in , , and require a unique field.
sample_questionsexample_question_sqlstext_instructionsid| Field | Format |
|---|---|
| |
| |
| |
- ID format: 32-character lowercase hex, unique across all three lists combined (a duplicate between e.g. and
text_instructionsis rejected).example_question_sqls - Text fields are arrays: ,
question, andsqlare arrays of strings, not plain strings.content - Sort order matters: must be sorted by
data_sources.tables, and each table'sidentifiermust be sorted bycolumn_configs;column_nameandexample_question_sqlsmust be sorted bytext_instructions. (idis silently re-sorted server-side.)sample_questions - accepts at most one item — the API rejects more than one (
text_instructions). Merge all guidance (persona, table guide, investigation flow, answer style) into a single entry.text_instructions must contain at most one item - Simple ID scheme that satisfies both rules: prefix per list + monotonic counter, total 32 hex chars — ,
1…0001for1…0002;sample_questions,2…0001for2…0002;example_question_sqlsfor3…0001. Authoring order = sort order, no collisions.text_instructions - is a top-level key of
benchmarks(alongsideserialized_space/version/config/data_sources), not nested underinstructions. Each item takes a unique 32-char hexinstructions.id
重要提示: 、和中的所有条目都需要唯一的字段。
sample_questionsexample_question_sqlstext_instructionsid| 字段 | 格式 |
|---|---|
| |
| |
| |
- ID格式: 32位小写十六进制字符串,在所有三个列表中必须唯一(例如和
text_instructions之间重复会被拒绝)。example_question_sqls - 文本字段为数组: 、
question和sql是字符串数组,而非普通字符串。content - 排序顺序重要: 必须按
data_sources.tables排序,每个表的identifier必须按column_configs排序;column_name和example_question_sqls必须按text_instructions排序。(id会在服务器端自动重新排序。)sample_questions - 最多接受一个条目——API会拒绝多个条目(提示
text_instructions)。将所有指导内容(角色、表指南、调查流程、回答风格)合并到一个条目中。text_instructions must contain at most one item - 满足两个规则的简单ID方案: 每个列表加前缀+单调计数器,总长度32位十六进制字符——使用
sample_questions、1…0001;1…0002使用example_question_sqls、2…0001;2…0002使用text_instructions。编写顺序=排序顺序,不会冲突。3…0001 - 是
benchmarks的顶级键(与serialized_space/version/config/data_sources同级),而非嵌套在instructions下。每个条目需要唯一的32位十六进制instructions。id
Text Instructions
文本说明
text_instructions- Where to find information — which tables contain which metrics
- How to answer specific questions — when a user asks X, use table Y with filter Z
- Business context — definitions, thresholds, and domain knowledge
Well-crafted instructions significantly improve answer accuracy.
text_instructions- 信息位置——哪些表包含哪些指标
- 特定问题的回答方式——当用户询问X时,使用表Y和过滤器Z
- 业务上下文——定义、阈值和领域知识
精心编写的说明能显著提高答案的准确性。
Example
示例
Top-level keys are , , , . Every item in , , and needs a unique 32-char hex and all text fields are arrays:
versionconfigdata_sourcesinstructionssample_questionsexample_question_sqlstext_instructionsidjson
{
"version": 2,
"config": {
"sample_questions": [
{"id": "10000000000000000000000000000001", "question": ["What is our current on-time performance?"]}
]
},
"data_sources": {
"tables": [
{"identifier": "catalog.ops.gold_otp_summary"}
]
},
"instructions": {
"example_question_sqls": [
{
"id": "20000000000000000000000000000001",
"question": ["What is our on-time performance?"],
"sql": ["SELECT flight_date, ROUND(SUM(on_time_count) * 100.0 / SUM(total_flights), 1) AS otp_pct\n", "FROM catalog.ops.gold_otp_summary\n", "WHERE flight_date >= date_sub(current_date(), 7)\n", "GROUP BY flight_date ORDER BY flight_date"]
}
],
"text_instructions": [
{
"id": "30000000000000000000000000000001",
"content": [
"On-time performance (OTP) questions: Use gold_otp_summary table. OTP target is 85%.\n",
"Delay analysis questions: Use gold_delay_analysis table. Filter by delay_code for specific delay types.\n",
"When asked about 'this week' or 'recent': Use flight_date >= date_sub(current_date(), 7).\n",
"When comparing aircraft: Join with gold_aircraft_reliability on tail_number."
]
}
]
}
}顶级键包括、、、。、和中的每个条目都需要唯一的32位十六进制,且所有文本字段都是数组:
versionconfigdata_sourcesinstructionssample_questionsexample_question_sqlstext_instructionsidjson
{
"version": 2,
"config": {
"sample_questions": [
{"id": "10000000000000000000000000000001", "question": ["What is our current on-time performance?"]}
]
},
"data_sources": {
"tables": [
{"identifier": "catalog.ops.gold_otp_summary"}
]
},
"instructions": {
"example_question_sqls": [
{
"id": "20000000000000000000000000000001",
"question": ["What is our on-time performance?"],
"sql": ["SELECT flight_date, ROUND(SUM(on_time_count) * 100.0 / SUM(total_flights), 1) AS otp_pct\n", "FROM catalog.ops.gold_otp_summary\n", "WHERE flight_date >= date_sub(current_date(), 7)\n", "GROUP BY flight_date ORDER BY flight_date"]
}
],
"text_instructions": [
{
"id": "30000000000000000000000000000001",
"content": [
"On-time performance (OTP) questions: Use gold_otp_summary table. OTP target is 85%.\n",
"Delay analysis questions: Use gold_delay_analysis table. Filter by delay_code for specific delay types.\n",
"When asked about 'this week' or 'recent': Use flight_date >= date_sub(current_date(), 7).\n",
"When comparing aircraft: Join with gold_aircraft_reliability on tail_number."
]
}
]
}
}Cross-Workspace Migration
跨工作区迁移
When migrating between workspaces, catalog names often differ. Export the agent, remap with , then import:
sedbash
python3 -c "import sys; p=sys.argv[1]; open(p,'w').write(open(p).read().replace('source_catalog','target_catalog'))" genie_agent.jsonUse to target different workspaces.
DATABRICKS_CONFIG_PROFILE=profile_name在工作区之间迁移时,目录名称通常不同。导出代理后,使用重新映射,然后导入:
sedbash
python3 -c "import sys; p=sys.argv[1]; open(p,'w').write(open(p).read().replace('source_catalog','target_catalog'))" genie_agent.json使用指定不同的工作区。
DATABRICKS_CONFIG_PROFILE=profile_nameConversation API
Conversation API
Scope: use this to query one specific Genie Agent — typically to validate an Agent after creating or editing it, or to lean on its curated business logic and certified queries. For general natural-language data questions or finding data across your workspace, don't use this — route to the databricks-data-discovery skill (Genie One) instead.
Ask questions of a specific Agent via three CLI primitives: , (follow-ups), and (state + SQL + text). on / returns immediately with ; poll until is , , or . Intermediate states you'll see: , , , .
start-conversationcreate-messageget-message--no-waitstart-conversationcreate-message{conversation_id, message_id}get-message.statusCOMPLETEDFAILEDCANCELLEDSUBMITTEDFILTERING_CONTEXTASKING_AIEXECUTING_QUERYbash
undefined适用范围: 用于查询特定的Genie Agent——通常在创建或编辑代理后进行验证,或借助其精心策划的业务逻辑和认证查询。 若要查询通用自然语言数据问题或在工作区内查找数据,请不要使用此API——转而使用**databricks-data-discovery** 技能(Genie One)。
通过三个CLI原语向特定Agent提问:、(跟进提问)和(状态+SQL+文本)。在/中使用会立即返回;轮询直到变为、或。你会看到的中间状态包括:、、、。
start-conversationcreate-messageget-messagestart-conversationcreate-message--no-wait{conversation_id, message_id}get-message.statusCOMPLETEDFAILEDCANCELLEDSUBMITTEDFILTERING_CONTEXTASKING_AIEXECUTING_QUERYbash
undefinedStart a new conversation (async — get IDs back immediately)
启动新对话(异步——立即返回ID)
databricks genie start-conversation --no-wait SPACE_ID "What were total sales last month?"
databricks genie start-conversation --no-wait SPACE_ID "What were total sales last month?"
→ {"conversation_id": "...", "message_id": "..."}
→ {"conversation_id": "...", "message_id": "..."}
Poll state
轮询状态
databricks genie get-message SPACE_ID CONV_ID MSG_ID | jq '{status, error}'
databricks genie get-message SPACE_ID CONV_ID MSG_ID | jq '{status, error}'
When COMPLETED, pull the generated SQL and any text reply
当状态为COMPLETED时,获取生成的SQL和文本回复
databricks genie get-message SPACE_ID CONV_ID MSG_ID
| jq '.attachments[] | {sql: .query.query, description: .query.description, text: .text.content}'
| jq '.attachments[] | {sql: .query.query, description: .query.description, text: .text.content}'
databricks genie get-message SPACE_ID CONV_ID MSG_ID
| jq '.attachments[] | {sql: .query.query, description: .query.description, text: .text.content}'
| jq '.attachments[] | {sql: .query.query, description: .query.description, text: .text.content}'
Fetch the query result rows (columns + data_array)
获取查询结果行(列+data_array)
databricks genie get-message-attachment-query-result SPACE_ID CONV_ID MSG_ID ATTACHMENT_ID
| jq '{columns: .statement_response.manifest.schema.columns | map({name, type: .type_name}), rows: .statement_response.result.data_array}'
| jq '{columns: .statement_response.manifest.schema.columns | map({name, type: .type_name}), rows: .statement_response.result.data_array}'
databricks genie get-message-attachment-query-result SPACE_ID CONV_ID MSG_ID ATTACHMENT_ID
| jq '{columns: .statement_response.manifest.schema.columns | map({name, type: .type_name}), rows: .statement_response.result.data_array}'
| jq '{columns: .statement_response.manifest.schema.columns | map({name, type: .type_name}), rows: .statement_response.result.data_array}'
Follow-up in the same conversation (Genie remembers context)
在同一对话中跟进提问(Genie会记住上下文)
databricks genie create-message --no-wait SPACE_ID CONV_ID "Break that down by region"
Start a new conversation for unrelated topics. Use `create-message` (same `CONV_ID`) only for follow-ups on the same topic.
On `FAILED`, `get-message` populates `.error.error` with the underlying error string (e.g. `[INSUFFICIENT_PERMISSIONS] ...`) and `.error.type` (e.g. `SQL_EXECUTION_EXCEPTION`). Attachments may still include `suggested_questions` even when the primary query failed.databricks genie create-message --no-wait SPACE_ID CONV_ID "Break that down by region"
针对不相关主题请启动新对话。仅在同一主题的跟进提问时使用`create-message`(相同的`CONV_ID`)。
当状态为`FAILED`时,`get-message`会在`.error.error`中填充底层错误字符串(例如`[INSUFFICIENT_PERMISSIONS] ...`),并在`.error.type`中填充错误类型(例如`SQL_EXECUTION_EXCEPTION`)。即使主查询失败,附件中仍可能包含`suggested_questions`。Troubleshooting
故障排除
| Issue | Solution |
|---|---|
| Add 32-char hex UUID |
| Use |
| No warehouse available | Create a SQL warehouse or provide |
Empty | Requires CAN EDIT permission on the agent |
| Tables not found after migration | Remap catalog name in |
| Slow answers / query timeouts | Size up the warehouse attached to the agent; simplify or pre-aggregate tall source tables |
| Wrong or empty answers | Add |
| 问题 | 解决方案 |
|---|---|
| 为每个示例问题添加32位十六进制UUID |
| 使用 |
| 无可用仓库 | 创建SQL warehouse或提供 |
导出时 | 需要拥有代理的CAN EDIT权限 |
| 迁移后找不到表 | 导入前在 |
| 回答缓慢/查询超时 | 扩大代理关联的仓库规模;简化或预聚合数据量较大的源表 |
| 答案错误或为空 | 添加 |
Related Skills
相关技能
- databricks-data-discovery - General natural-language data exploration / "ask Genie" (Genie One) across your data; use it when you are not targeting a specific curated Genie Agent
- databricks-synthetic-data-gen - Generate data for Genie tables
- databricks-pipelines - Build bronze/silver/gold tables
- databricks-data-discovery - 通用自然语言数据探索/“询问Genie”(Genie One),可跨所有数据查询;当不针对特定精心策划的Genie Agent时使用此技能
- databricks-synthetic-data-gen - 为Genie表生成数据
- databricks-pipelines - 构建青铜/白银/黄金层表