Managing Genie Agents as code: can you version-control and promote them?

A developer recently asked on the Databricks Community forum whether the Databricks VS Code extension can edit Genie Agents (formerly Genie Spaces). Their pain was specific: the browser UI makes maintenance slow, there is no copy and paste between agents, example SQL and sources have no text representation, and sources can’t be re-ordered. What they really wanted was to fork an agent, test changes, and merge them back later.

That is a software-delivery question, and it matters more as soon as a second person starts editing an agent. A Genie Agent holds your instructions, example queries and data sources. That is production logic. If it lives only in a browser tab, nobody can review a change, roll one back, or say who altered the revenue instructions last Tuesday.

Here is how we would handle it.

Short answer: there is no Genie editor in VS Code, but there is a code path

The replies in the thread agree on the first point: the VS Code extension has no Genie editor. One Databricks reply also said they knew of no published roadmap for one, and suggested raising feature requests through the account team or the Ideas portal.

The path that does exist is Declarative Automation Bundles (the newer name for Databricks Asset Bundles). The bundle resources documentation lists genie_spaces as a resource type that lets you define a Genie Agent in a bundle. The details that matter, from the docs:

• It was added in Databricks CLI version 1.3.0.
• It is supported only with the direct deployment engine, so older bundles need engine: direct in databricks.yml.
• warehouse_id is required, and the agent’s content lives in a *.geniespace.json file referenced through file_path (or inline as serialized_space).
• permissions can be declared on the resource, and parent_path sets the workspace folder.

The CLI also has a generator, databricks bundle generate genie-space. Point it at an existing agent with --existing-id and it writes two things: a YAML resource file, and the .geniespace.json file holding the serialized agent. The docs also describe a loop for UI edits: run it again with --resource <key> to refresh the JSON from the workspace, and add --watch --force to keep the files in sync while someone works in the UI.

The documentation pages we read don’t attach a Preview or Beta label to this resource. The surface is new, though, so check the release status for your CLI version and cloud before you build a delivery process on it.

A workflow that works

This is the setup we would put in place for a team with more than one agent author.

1. Treat the UI as a sandbox, not the source of truth. Authors can experiment in the browser, because that is where the quick feedback is. The agent that users see in production is the one deployed from the repo.
2. Export once, then commit. Generate the bundle files from the existing agent and commit both the YAML and the JSON. From then on, changes arrive as pull requests, and the diff shows exactly which instruction or example query changed.
3. Fork to test. For an experiment, clone the agent from its menu in the UI, as the thread suggests, change it there, and when the change is worth keeping, regenerate the JSON and open a pull request. Don’t merge by hand-editing a large JSON blob if you can avoid it.
4. Run the benchmarks before the merge. A code review tells you what changed. It doesn’t tell you whether accuracy got worse. Genie’s benchmark feature stores test questions with reference SQL and scores a run, and the docs allow up to 500 benchmark questions per agent. Make “benchmark score did not drop” a merge condition. The score is only as good as your question set, so keep growing it from real user questions.
5. Parameterize per environment. The same agent usually points at a different catalog and warehouse in dev, test and production. Use bundle targets and variables for the warehouse and catalog, so the agent definition stays the same across environments.
6. Declare permissions in the bundle. The resource takes a permissions block, so who can run or edit the agent is reviewed in the same pull request as everything else.

What the thread also taught us

Don’t make the agent carry what Unity Catalog can carry. A Databricks reply recommended keeping table and column comments in Unity Catalog, so agents inherit them and you copy less between agents. We agree. Descriptions, primary and foreign keys, and metric views for your key measures belong in the governed data layer. The agent file then stays small: instructions, a few example question and SQL pairs, and the data sources. A smaller agent is easier to review, and it fits the documented guidance of five or fewer tables, with a hard limit of 50 tables, views or metric views per agent.

Keep instructions and example SQL in plain files. The workaround the Databricks reply offered, before bundles enter the picture, was to keep instructions and example question and SQL pairs in a repo as Markdown or SQL files. It’s a reasonable fallback if you can’t adopt bundles yet, and it gives you review history immediately.

Source order is not worth fighting over. The same reply said there is no UI option to re-sequence sources and that order probably doesn’t affect answer quality. Generated JSON sorts tables alphabetically, according to one practitioner. Don’t spend review time on it.

Limits to plan around

• Browser edits and repo edits can drift. If one person changes the live agent in the UI and the next deployment overwrites it, someone loses work. Pick the direction of truth. We recommend the repo, with the --watch option reserved for the short period when someone is authoring in the UI.
• Older engines and older bundles. Genie resources need the direct engine. If your existing bundles use the other engine, switching it is a project of its own, so test it on a non-critical bundle first.
• It is a new area. A different community thread from earlier in 2026 still said Genie wasn’t supported in bundles. That has changed in the current docs, which is a good reminder to re-check what the docs say now rather than trusting any forum answer, including this one, for long.
• Code review doesn’t replace measurement. A clean diff can still make answers worse. Benchmarks and sampled production conversations are what catch that.

Summary

• There is no Genie editor in the VS Code extension, so manage agents through bundles instead.
• The genie_spaces bundle resource needs CLI 1.3.0 or newer and the direct deployment engine.
• Use databricks bundle generate genie-space to export an existing agent into YAML plus a .geniespace.json file.
• Make the repo the source of truth, use the UI as a sandbox, and gate merges on benchmark results.
• Put descriptions, keys and measures in Unity Catalog and metric views so the agent file stays small.
• Parameterize warehouse and catalog per environment, and declare permissions in the bundle.

If you want help setting up a review-and-promotion process for your Genie Agents, Zephico offers a Genie readiness review, a pilot sprint, and rollout and governance support. We are a Databricks Consulting Partner. Details are on our Databricks Genie page.