databricks-agent-bricks

Files (3)

• 1-knowledge-assistants.md
• 2-supervisor-agents.md
• SKILL.md

SKILL.md (first lines)

# 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 |
| **Supervisor Agent (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 `databricks-unstructured-pdf-generation` skill if needed

### For Genie Spaces
- **See the `databricks-genie` skill** for comprehensive Genie Space guidance
- Tables in Unity Catalog with the data to explore
- Generate raw data using the `databricks-synthetic-data-gen` skill
- Create tables using the `databricks-spark-declarative-pipelines` skill

### For Supervisor Agents
- **Model Serving Endpoints**: Deployed agent endpoints (KA endpoints, custom agents, fine-tuned models)
- **Genie Spaces**: Existing Genie spaces can be used directly as agents for SQL-based queries
- Mix and match endpoint-based and Genie-based agents in the same Supervisor Agent

### For Unity Catalog Functions
- **Existing UC Function**: Function already registered in Unity Catalog
- Agent service principal has `EXECUTE` privilege on the function

### For External MCP Servers
- **Existing UC HTTP Connection**: Connection configured with `is_mcp_connection: 'true'`
- Agent service principal has `USE CONNECTION` privilege on the connection

## MCP Tools

### Knowledge Assistant Tool

**manage_ka** - Manage Knowledge Assistants (KA)
- `action`: "create_or_update", "get", "find_by_name", or "delete"
- `name`: Name for the KA (for create_or_update, find_by_name)
- `volume_path`: Path to documents (e.g., `/Volumes/catalog/schema/volume/folder`) (for create_or_update)
- `description`: (optional) What the KA does (for create_or_update)
- `instructions`: (optional) How the KA should answer (for create_or_update)
- `tile_id`: The KA tile ID (for get, delete, or update via create_or_update)
- `add_examples_from_volume`: (optional, default: true) Auto-add examples from JSON files (for create_or_update)

Actions:
- **create_or_update**: Requires `name`, `volume_path`. Optionally pass `tile_id` to update.
- **get**: Requires `tile_id`. Returns tile_id, name, description, endpoint_status, knowledge_sources, examples_count.
- **find_by_name**: Requires `name` (exact match). Returns found, tile_id, name, endpoint_name, endpoint_status. Use this to look up an existing KA when you know the name but not the tile_id.
- **delete**: Requires `tile_id`.

### Genie Space Tools

**For comprehensive Genie guidance, use the `databricks-genie` skill.**

Use `manage_genie` with actions:
- `create_or_update` - Create or update a Genie Space
- `get` - Get Genie Space details
- `list` - List all Genie Spaces
- `delete` - Delete a Genie Space
- `export` / `import` - For migration

See `databricks-genie` skill for:
- Table inspection workflow
- Sample question best practices
- Curation (instructions, certified queries)

**IMPORTANT**: There is NO system table for Genie spaces (e.g., `system.ai.genie_spaces` does not exist). Use `manage_genie(action="list")` to find spaces.

### Supervisor Agent Tool

**manage_mas** - Manage Supervisor Agents (MAS)
- `action`: "create_or_update", "get", "find_by_name", or "delete"
- `name`: Name for the Supervisor Agent (for create_or_update, find_by_name)
- `agents`: List of agent configurations (for create_or_update), each with:
  - `name`: Agent identifier (required)
  - `description`: What this agent handles - critical for routing (required)
  - `ka_tile_id`: Knowledge Assistant tile ID (use for document Q&A agents - recommended for KAs)
  - `genie_space_id`: Genie space ID (use for SQL-based data agents)
  - `endpoint_name`: Model serving endpoint name (for custom agents)
  - `uc_function_name`: Unity Catalog function name in format `catalog.schema.function_name`
  - `connection_name`: Unity Catalog connection name (for external MCP servers)
  - Note: Provide exactly one of: `ka_tile_id`, `genie_space_id`, `endpoint_name`, `uc_function_name`, or `connection_name`
- `description`: (optional) What the Supervisor Agent does (for create_or_update)
- `instructions`: (optional) Routing instructions for the supervisor (for create_or_update)
- `tile_id`: The Supervisor Agent tile ID (for get, delete, or update via create_or_update)
- `examples`: (optional) List of example questions with `question` and `guideline` fields (for create_or_update)

Actions:
- **create_or_update**: Requires `name`, `agents`. Optionally pass `tile_id` to update.
- **get**: Requires `tile_id`. Returns tile_id, name, description, endpoint_status, agents, examples_count.
- **find_by_name**: Requires `name` (exact match). Returns found, tile_id, name, endpoint_status, agents_count. Use this to look up an existing Supervisor Agent when you know the name but not the tile_id.
- **delete**: Requires `tile_id`.

## Typical Workflow

### 1. Generate Source Data

Before creating Agent Bricks, generate the required source data:

**For KA (document Q&A)**:
```
1. Use `databricks-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 `databricks-synthetic-data-gen` skill to create raw parquet data
2. Use `databricks-spark-declarative-pipelines` skill to create bronze/silver/gold tables

From ThomazRossito/data-agents, MIT.

More from ThomazRossito/data-agents