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 one or more volumes, 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.

Overview

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?

To blend a local CSV or Excel file into a single conversation instead of analyzing files stored in volumes, see Upload a file to a Genie Agent.

How it works

When a user asks a question that requires context from a volume, the Genie Agent retrieves the files that are most relevant to the question, parses them, and adds their content to the agent's context. The agent then reasons over that content together with any structured data to generate an answer with citations.

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

Before you attach volumes, confirm that you meet the requirements in this section.

General requirements

The following requirements apply to the agent and its users:

  • Unity Catalog enabled in your workspace.
  • AI Gateway (Beta) enabled.
  • Agent mode available in your region. See Regional availability.
  • A well-prepared Genie Agent with clear instructions and table metadata. See Curate an effective Genie Agent.
  • One or more Unity Catalog volumes that contain relevant files.
  • Both the Workspace access and Databricks SQL access entitlements for every user of the agent. Users can use the rest of Genie without Workspace access, but this feature requires both. See Manage entitlements.
  • At least READ VOLUME permission on the attached volumes for every user of the agent.

Volume requirements

The following limits apply to the volumes and files you attach:

  • You can attach a maximum of 10 volumes to a Genie Agent.
  • Each volume can contain up to 500 total files. TXT and MD files do not count toward this limit. Questions directed toward volumes with more than 500 files will return an error.
  • Files must be one of the following types: PDF, JPG, JPEG, PNG, TIFF, TIF, DOC, DOCX, PPT, or PPTX. The Genie Agent ignores unsupported file types.
  • The Genie Agent ignores files larger than 10 MB and continues to answer questions using the other supported files in the volume.

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.

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.

Scope your questions to a small number of files. During the Beta, a Genie Agent can retrieve context from up to 5 files per question. To get an accurate answer, ask questions that a small, relevant set of files can answer.

Works well Doesn't work well
"What were the key findings from the Q1 and Q2 financial reports?" "Summarize the customer insights across all 500 files in this volume."
"Compare the pricing details in these two contracts." "Find every mention of customer churn across all win/loss reports."

Limitations

The following limitations apply during the Beta:

  • This feature is not available on AWS GovCloud.
  • Consumer-only, Databricks SQL-only, and account-only users cannot use this feature. Every user of the agent must have both the Workspace access and Databricks SQL access entitlements.
  • A Genie Agent can retrieve context from up to 5 files per question.
  • The Genie Agent cannot analyze external files, such as files in Google Drive or SharePoint.
  • Web-search tools are not available.

Frequently asked questions

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

How is this feature billed?

When a user asks a question, the Genie Agent first retrieves and processes the relevant files. This generates Foundation Model Serving costs (pay-per-token), billed under the Serverless Real-time Inference SKU. See Foundation Model Serving pricing. The agent then reasons over the retrieved content, which is billed as part of standard Genie usage. See Genie pricing.

When should I use this feature instead of a Multi-Agent Supervisor?

Attach volumes to a Genie Agent when you want an agent to answer questions across structured and unstructured data within a specific domain. Build a custom supervisor agent only when you need fine-grained control over agent behavior, such as model selection, chunking strategy, or orchestrating multiple sub-agents.

When should I use this feature instead of Genie One?

Attach volumes to a Genie Agent when you want to build a specialized agent that answers questions in a specific domain. 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.

Can I analyze files in volumes through the API?

Yes. You can analyze files in volumes through the Agent mode APIs. See Agent mode APIs in Genie Agents.

Additional resources

See the following resources for related information:

  • Last updated on