databricks-agent-bricks

Create Agent Bricks: Knowledge Assistants (KA) for document Q&A and Supervisor Agents for multi-agent orchestration (MAS).

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.databricks/aitools/skills/databricks-agent-bricks/SKILL.md

Agent Bricks

Name: databricks-agent-bricks
Rating: 65.60000000000001 (1 reviews)
Author: databricks

Agent Bricks are pre-built AI tiles in Databricks that provide conversational interfaces. This skill covers Knowledge Assistants and Supervisor Agents.

Brick	Purpose	This Skill
Knowledge Assistant (KA)	Document Q&A using RAG on PDFs/text in Volumes	✓
Supervisor Agent	Orchestrates multiple agents (KA, endpoints, UC functions, MCP)	✓

Knowledge Assistant

# Find volumes
databricks volumes list CATALOG SCHEMA
databricks experimental aitools tools query --warehouse WH "LIST '/Volumes/catalog/schema/volume/'"

# Create KA
databricks knowledge-assistants create-knowledge-assistant "Name" "Description"

# Add knowledge source. With --json, pass ONLY the PARENT as a positional arg
# and put display_name / description / source_type / the source body (files|index|file_table)
# inside the JSON. Mixing positional DISPLAY_NAME/DESCRIPTION/SOURCE_TYPE with --json errors.
databricks knowledge-assistants create-knowledge-source \
  "knowledge-assistants/{ka_id}" \
  --json '{
    "display_name": "Docs",
    "description": "Documentation files",
    "source_type": "files",
    "files": {"path": "/Volumes/catalog/schema/volume/"}
  }'

# Sync and check status
databricks knowledge-assistants sync-knowledge-sources "knowledge-assistants/{ka_id}"
databricks knowledge-assistants get-knowledge-assistant "knowledge-assistants/{ka_id}"

# List/manage
databricks knowledge-assistants list-knowledge-assistants
databricks knowledge-assistants delete-knowledge-assistant "knowledge-assistants/{ka_id}"

Source types: files (Volume path) or index (Vector Search: index.index_name, index.text_col, index.doc_uri_col)

Status: CREATING (2-5 min) → ONLINE → OFFLINE

Supervisor Agent

Native CLI: databricks supervisor-agents (Beta, requires CLI ≥ 0.299.2). Resource paths look like supervisor-agents/{id} — every command takes either that full path or a PARENT of that shape. list-supervisor-agents and list-examples/list-tools return bare JSON arrays.

# Create the supervisor agent (display name positional, description/instructions as flags)
databricks supervisor-agents create-supervisor-agent "My Supervisor" \
    --description "Routes queries to specialized agents" \
    --instructions "Route data questions to analyst, document questions to docs_agent."
# → returns {name: "supervisor-agents/<uuid>", endpoint_name: "mas-<short>-endpoint", ...}

# List / get / find by name
databricks supervisor-agents list-supervisor-agents
databricks supervisor-agents get-supervisor-agent supervisor-agents/<id>
databricks supervisor-agents list-supervisor-agents | jq '.[] | select(.display_name == "My Supervisor")'

# Update — UPDATE_MASK + new DISPLAY_NAME are positional; description/instructions optional flags
databricks supervisor-agents update-supervisor-agent supervisor-agents/<id> \
    "display_name,description,instructions" "My Supervisor (v2)" \
    --description "..." --instructions "..."

# Delete
databricks supervisor-agents delete-supervisor-agent supervisor-agents/<id>

Tools (the agents the supervisor routes to)

Each tool wires the supervisor to a downstream resource. tool_type lives in --json (the CLI rejects it as a positional when --json is used). Each type has a type-specific block (genie_space, knowledge_assistant, etc.) whose identifier field differs by type — see the table below.

# Attach a Genie space — find its space_id with `databricks genie list-spaces`
databricks supervisor-agents create-tool supervisor-agents/<id> analyst --json '{
    "tool_type": "genie_space",
    "description": "SQL analytics on the analytics warehouse",
    "genie_space": {"id": "<genie_space_id>"}
}'

# Attach a Knowledge Assistant — find ka_id with `databricks knowledge-assistants list-knowledge-assistants`
databricks supervisor-agents create-tool supervisor-agents/<id> docs_agent --json '{
    "tool_type": "knowledge_assistant",
    "description": "Answers from product documentation",
    "knowledge_assistant": {"knowledge_assistant_id": "<ka_id>"}
}'

# List / get / delete tools
databricks supervisor-agents list-tools supervisor-agents/<id>
databricks supervisor-agents get-tool supervisor-agents/<id>/tools/<tool_id>
databricks supervisor-agents delete-tool supervisor-agents/<id>/tools/<tool_id>

Tool types (tool_type value → type-specific block):

`tool_type`	Block	Use for
`genie_space`	`{"id": "<space_id>"}`	Natural language → SQL via Genie
`knowledge_assistant`	`{"knowledge_assistant_id": "<ka_id>"}`	Document Q&A via a KA
`uc_function`	`{"name": "catalog.schema.func"}`	UC SQL/Python function
`uc_connection`	`{"name": "<connection_name>"}`	External MCP server via UC HTTP Connection
`volume`	`{"name": "<full_volume_name>"}`	UC Volume browsing
`app`	`{"name": "<app_name>"}`	Databricks App
Other types (`serving_endpoint`, `lakeview_dashboard`, `supervisor_agent`, `uc_table`, `vector_search_index`, `catalog`, `schema`, `web_search`)	Block name and field shape vary	Run `databricks supervisor-agents create-tool --help` and probe — these were not verified end-to-end here.

Examples (training the supervisor)

Examples must use --json — the positional GUIDELINES arg doesn't accept any encoding because guidelines is a repeated string.

databricks supervisor-agents create-example supervisor-agents/<id> --json '{
    "question": "What were Q4 revenue numbers?",
    "guidelines": ["Route to analyst Genie space", "Always group by region"]
}'

databricks supervisor-agents list-examples supervisor-agents/<id>
databricks supervisor-agents get-example supervisor-agents/<id>/examples/<ex_id>
databricks supervisor-agents delete-example supervisor-agents/<id>/examples/<ex_id>

Endpoint readiness: after create-supervisor-agent, the serving endpoint takes up to ~10 minutes to come online before it can answer queries. get-supervisor-agent returns the endpoint name immediately, but querying it is gated on the endpoint's own readiness — check via databricks serving-endpoints get <endpoint_name>.

Reference

Topic	File
KA source types, index, troubleshooting	references/1-knowledge-assistants.md
UC functions, MCP servers, examples	references/2-supervisor-agents.md

Repository: databricks/devhub
Path: .databricks/aitools/skills/databricks-agent-bricks/SKILL.md
Commit: ade58e4

Last updated: 5 days ago
First committed: 2 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.