Agent Bricks

---
name: agent-bricks
description: "Create and manage Databricks Agent Bricks: Knowledge Assistants (KA) for document Q&A, Genie Spaces for SQL exploration, and Multi-Agent Supervisors (MAS) for multi-agent orchestration. Use when building conversational AI applications on Databricks."
---

# Agent Bricks

Create and manage Databricks Agent Bricks - pre-built AI components for building conversational applications.

## Overview

Agent Bricks are three types of pre-built AI tiles in Databricks:

| Brick | Purpose | Data Source |
|-------|---------|-------------|
| **Knowledge Assistant (KA)** | Document-based Q&A using RAG | PDF/text files in Volumes |
| **Genie Space** | Natural language to SQL | Unity Catalog tables |
| **Multi-Agent Supervisor (MAS)** | Multi-agent orchestration | Model serving endpoints |

## Prerequisites

Before creating Agent Bricks, ensure you have the required data:

### For Knowledge Assistants
- **Documents in a Volume**: PDF, text, or other files stored in a Unity Catalog volume
- Generate synthetic documents using the `unstructured-pdf-generation` skill if needed

### For Genie Spaces
- **Tables in Unity Catalog**: Bronze/silver/gold tables with the data to explore
- Generate raw data using the `synthetic-data-generation` skill
- Create tables using the `spark-declarative-pipelines` skill

### For Multi-Agent Supervisors
- **Model Serving Endpoints**: Deployed agent endpoints to orchestrate
- These could be custom agents, fine-tuned models, or other deployed services

## MCP Tools

### Knowledge Assistant Tools

**create_or_update_ka** - Create or update a Knowledge Assistant
- `name`: Name for the KA
- `volume_path`: Path to documents (e.g., `/Volumes/catalog/schema/volume/folder`)
- `description`: (optional) What the KA does
- `instructions`: (optional) How the KA should answer
- `tile_id`: (optional) Existing tile_id to update
- `add_examples_from_volume`: (optional, default: true) Auto-add examples from JSON files

**get_ka** - Get Knowledge Assistant details
- `tile_id`: The KA tile ID

**delete_ka** - Delete a Knowledge Assistant
- `tile_id`: The KA tile ID to delete

### Genie Space Tools

**IMPORTANT**: Before creating a Genie Space, you MUST first inspect the table schemas using `get_table_details` to understand the data. This allows you to:

- Select the most relevant tables for the use case
- Write sample questions that reference actual column names and data patterns
- Create a description that accurately explains the data model

**Genie Space Creation Workflow**:

1. Call `get_table_details(catalog, schema)` to fetch table schemas
2. Analyze the columns, data types, and relationships
3. Select tables appropriate for the user's use case (prefer silver/gold over bronze)
4. Generate 5-10 sample questions based on actual columns and business context
5. Write a description explaining what users can explore
6. Call `create_or_update_genie` with the prepared content

**create_or_update_genie** - Create or update a Genie Space for SQL exploration

- `display_name`: Display name for the space
- `table_identifiers`: List of tables (e.g., `["catalog.schema.table1", "catalog.schema.table2"]`)
- `warehouse_id`: (optional) SQL warehouse ID (auto-detects if not provided)
- `description`: (optional) What the space does - explain the data model and relationships
- `sample_questions`: (optional) List of sample questions that reference actual columns
- `space_id`: (optional) Existing space_id to update

**get_genie** - Get Genie Space details

- `space_id`: The Genie space ID

**delete_genie** - Delete a Genie Space

- `space_id`: The Genie space ID to delete

### Multi-Agent Supervisor Tools

**create_or_update_mas** - Create or update a Multi-Agent Supervisor
- `name`: Name for the MAS
- `agents`: List of agent configurations:
  - `name`: Agent name
  - `endpoint_name`: Model serving endpoint name
  - `description`: What this agent handles (used for routing)
- `description`: (optional) What the MAS does
- `instructions`: (optional) Routing instructions
- `tile_id`: (optional) Existing tile_id to update
- `examples`: (optional) List of example questions with `question` and `guideline` fields

**get_mas** - Get Multi-Agent Supervisor details
- `tile_id`: The MAS tile ID

**delete_mas** - Delete a Multi-Agent Supervisor
- `tile_id`: The MAS tile ID to delete

## Typical Workflow

### 1. Generate Source Data

Before creating Agent Bricks, generate the required source data:

**For KA (document Q&A)**:
```
1. Use `unstructured-pdf-generation` skill to generate PDFs
2. PDFs are saved to a Volume with companion JSON files (question/guideline pairs)
```

**For Genie (SQL exploration)**:
```
1. Use `synthetic-data-generation` skill to create raw parquet data
2. Use `spark-declarative-pipelines` skill to create bronze/silver/gold tables
```

### 2. Create the Agent Brick

Use the appropriate `create_or_update_*` tool with your data sources.

### 3. Wait for Provisioning

Newly created KA and MAS tiles need time to provision. The endpoint status will progress:
- `PROVISIONING` - Being created (can take 2-5 minutes)
- `ONLINE` - Ready to use
- `OFFLINE` - Not running

### 4. Add Examples (Automatic)

For KA, if `add_examples_from_volume=true`, examples are automatically extracted from JSON files in the volume and added once the endpoint is `ONLINE`.

## Best Practices

1. **Use meaningful names**: Names are sanitized automatically (spaces become underscores)
2. **Provide descriptions**: Helps users understand what the brick does
3. **Add instructions**: Guide the AI's behavior and tone
4. **Include sample questions**: Shows users how to interact with the brick
5. **Use the workflow**: Generate data first, then create the brick

## See Also

- `1-knowledge-assistants.md` - Detailed KA patterns and examples
- `2-genie-spaces.md` - Detailed Genie patterns and examples
- `3-multi-agent-supervisors.md` - Detailed MAS patterns and examples