Analyze files in volumes with a Genie Agent

A Genie Agent can analyze the unstructured files stored in Unity Catalog volumes, such as PDFs, Word documents, slide decks, and images. An agent author attaches volumes to the agent, and business users ask questions about their content alongside the agent's structured data in a single conversation.

Important

This feature is in Beta. To use it, a workspace admin must turn on Analyze Files in Volumes with Genie Agents from the Previews page. See Manage Azure Databricks previews.

Note

Genie Agents were formerly known as Genie Spaces.

What you can ask a Genie Agent about your files

By attaching volumes to an agent, business users can combine data from documents such as support tickets, sales call logs, and policy files with data from the agent's structured tables. Users can then answer questions such as:

  • Which support issues are taking the longest to resolve, and what are customers saying in escalation requests?
  • Why are late-stage sales opportunities stalling, and what objections appear most often in sales call logs?
  • Which regions are underperforming, and what internal escalation policies apply?

When to use file analysis in a Genie Agent

Attach volumes to a Genie Agent when you want a specialized agent for a specific domain. Choose a different approach when your needs are broader:

  • Use Genie One as a unified entry point for all questions about your structured data. Genie One can call a Genie Agent to answer questions about files.
  • Build a custom Multi-Agent Supervisor only when you need fine-grained control over agent behavior, such as model selection, chunking strategy, or orchestrating multiple sub-agents.
  • Use file upload to blend a local CSV or Excel file into a single conversation instead of analyzing files stored in volumes.

How a Genie Agent analyzes files

When a user asks a question that requires context from a volume, the Genie Agent retrieves the file content that is most relevant to the question and adds it to the agent's context. The agent then reasons over that content together with any structured data to generate an answer with citations. These citations can point to the specific page of the source file (Beta).

File analysis runs only in Agent mode, which uses multi-step reasoning to retrieve and analyze the relevant files. See Agent mode.

The Genie Agent always uses the permissions of the user who asks the question. A user who does not have at least READ VOLUME permission on an attached volume receives an error. Users can ask questions across a specific volume, multiple volumes, and structured data in the same conversation.

Requirements

The following requirements apply to the agent and its users:

Attach volumes to a Genie Agent

Before you begin, review the Requirements.

To attach volumes to a Genie Agent:

  1. Open the Genie Agent that you want to add files to.
  2. Open the Sources tab, then click Add.
  3. Select one or more volumes. The Genie Agent processes the entire volume. You cannot attach a subset of the folders or files in a volume.
  4. Add a clear description in the Description field. See Optimize your agent for file questions.

When you attach a volume, Azure Databricks automatically enables content search.

How content search works

Content search parses and indexes your files so the Genie Agent can reason over a larger set of files, draw on specific passages across many files, and answer questions with lower latency. For file and volume limits, see Limitations.

Content search stays in sync with your volume automatically. When you add, change, or remove files, Azure Databricks updates the index to reflect your changes, so the Genie Agent reasons over current content without any manual step.

Optimize your agent for file questions

After you attach your volumes, follow these recommendations to help the Genie Agent use their content:

  • Add a clear description: Describe what content the volume contains, how it is organized, and how the agent should use it. The agent uses this description to retrieve relevant files.
  • Avoid duplicate content: Attaching multiple volumes that contain overlapping information makes it harder for the agent to retrieve relevant documents. The same applies to individual files within a volume.
  • Avoid irrelevant files: Include only files that are relevant to the agent's domain. Irrelevant files can confuse the agent.
  • Use clear file names: Use descriptive file names so the agent can distinguish between files.

Ask questions about files

To ask questions about files in a Genie Agent:

  1. Open a Genie Agent that has volumes attached.
  2. Turn on Agent mode in the chat box. You must use Agent mode to answer questions about files.
  3. Enter a question and send your prompt. Agent mode retrieves context from the relevant volume, and then generates an answer after the analysis is complete.

Content search supported regions

Content search is available in the regions listed in this section.

In some regions, content search runs only if an account admin enables cross-Geo processing, which allows Azure Databricks to process your files outside your workspace Geo. See Enable cross-Geo processing.

Regions that don't require cross-Geo processing

Content search runs in your workspace region for the following regions:

  • Australia East
  • Central US
  • East US
  • East US 2
  • France Central
  • Germany West Central
  • Japan East
  • North Central US
  • North Europe
  • South Central US
  • West Europe
  • West US
  • West US 2

Regions that require cross-Geo processing

For the following regions, an account admin must enable cross-Geo processing before content search runs:

  • Brazil South
  • Canada Central
  • Central India
  • East Asia
  • Southeast Asia
  • UK South

Limitations

The following limitations apply:

  • Only Unity Catalog managed volumes support content search. External volumes and My Files volumes aren't supported. See Store files in My Files.
  • Each workspace can have up to 250 volumes attached to Genie Agents.
  • Each indexed volume can contain up to 10,000 files.
  • Content search skips files larger than 100 MB and files with more than 500 pages.
  • Content search supports PDF, JPG, JPEG, PNG, TIFF, TIF, DOC, DOCX, PPT, PPTX, MD, or TXT files. It skips all other file types.

Frequently asked questions

The following questions cover common topics for analyzing files in volumes.

How is this feature billed?

Azure Databricks charges for the following:

  • Preparing files: When Azure Databricks enables content search or syncs a volume, it parses your files with the ai_parse_document AI function, which is billed under AI Functions pricing.
  • Answering questions: The agent's reasoning over your files is billed as part of standard Genie usage. See Genie pricing.

Can I analyze files in volumes through the API?

Yes. You can analyze files in volumes through the Agent mode APIs. See the Agent mode API reference.

Additional resources

See the following resources for related information:

  • Last updated on