Skip to content

Commit 10baa35

Browse files
jamesbroadheadjamesbroadhead
committed
experimental: sync from a-d-k experimental @ f9b404b
Re-sync from databricks-solutions/ai-dev-kit:experimental (now at f9b404b after PR #533 merged). Two upstream commits since the original import touched skill content shipped here: - 0ebc38b "Surface silent failures in installer + dashboard skill" — databricks-aibi-dashboards/SKILL.md (CLI flag JSON-vs-flag form clarification). - f9b404b "Replace mas_manager.py with native supervisor-agents CLI" — databricks-agent-bricks/SKILL.md + 2-supervisor-agents.md updated to the new supervisor-agents CLI group (Beta, CLI 0.299.2+); the 667-line mas_manager.py shim removed. The fork branch's installer-side fixes (5d2e6ac/39c349c/dd2257c) are a-d-k tooling and don't touch databricks-skills/, so nothing to pull from there. Manifest regenerated. Co-authored-by: Isaac
1 parent 0ff1b23 commit 10baa35

5 files changed

Lines changed: 121 additions & 733 deletions

File tree

‎experimental/databricks-agent-bricks/2-supervisor-agents.md‎

Lines changed: 34 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Supervisor Agents - Details
22

3-
For commands, see [SKILL.md](SKILL.md). `<SKILL_ROOT>` in examples = the directory containing SKILL.md.
3+
For commands, see [SKILL.md](SKILL.md). All operations use the native `databricks supervisor-agents` CLI (Beta, requires CLI ≥ 0.299.2).
44

55
## Unity Catalog Functions
66

@@ -10,9 +10,13 @@ Call registered UC functions from the Supervisor Agent.
1010
- UC Function exists (`CREATE FUNCTION` or Python UDF)
1111
- Grant execute: `GRANT EXECUTE ON FUNCTION catalog.schema.func TO \`<agent_sp>\`;`
1212

13-
**Config:**
14-
```json
15-
{"name": "enricher", "uc_function_name": "catalog.schema.enrich_data", "description": "Enriches customer records"}
13+
**Attach as a tool:**
14+
```bash
15+
databricks supervisor-agents create-tool supervisor-agents/<id> enricher --json '{
16+
"tool_type": "uc_function",
17+
"description": "Enriches customer records",
18+
"uc_function": {"name": "catalog.schema.enrich_data"}
19+
}'
1620
```
1721

1822
## External MCP Servers
@@ -39,9 +43,13 @@ OPTIONS (
3943
GRANT USE CONNECTION ON my_mcp TO `<agent_sp>`;
4044
```
4145

42-
**3. Config:**
43-
```json
44-
{"name": "operations", "connection_name": "my_mcp", "description": "Execute operations: approve invoices, trigger workflows"}
46+
**3. Attach as a tool:**
47+
```bash
48+
databricks supervisor-agents create-tool supervisor-agents/<id> operations --json '{
49+
"tool_type": "uc_connection",
50+
"description": "Execute operations: approve invoices, trigger workflows",
51+
"uc_connection": {"name": "my_mcp"}
52+
}'
4553
```
4654

4755
**Test connection:**
@@ -61,20 +69,27 @@ The `description` field drives routing. Be specific:
6169

6270
## Adding Examples
6371

64-
Examples help evaluation and routing optimization. **The MAS endpoint must be ONLINE.** Right after `create_mas` (or a big `update_mas`), the endpoint is `NOT_READY` and takes **up to ~10 minutes** to come ONLINE. Pass `--wait` to block until then:
72+
Examples help evaluation and routing optimization. **The serving endpoint must be ONLINE.** Right after `create-supervisor-agent` (or a structural `update-supervisor-agent`), the endpoint takes **up to ~10 minutes** to come ONLINE. Examples can be added before that — they're stored on the agent definition — but querying the endpoint to evaluate routing requires readiness.
6573

6674
```bash
67-
# Fails fast if endpoint isn't ONLINE yet
68-
python <SKILL_ROOT>/scripts/mas_manager.py add_examples TILE_ID '[
69-
{"question": "I need my invoice for March", "guideline": "Route to billing_agent"},
70-
{"question": "API returns 500 error", "guideline": "Route to tech_agent"}
71-
]'
72-
73-
# --wait blocks until endpoint is ONLINE (default timeout 15 min) then adds.
74-
# The process must stay alive for the whole wait — there is no background queue.
75-
python <SKILL_ROOT>/scripts/mas_manager.py add_examples TILE_ID '[...]' --wait
76-
77-
python <SKILL_ROOT>/scripts/mas_manager.py list_examples TILE_ID
75+
# Add an example (guidelines is a repeated string — must use --json)
76+
databricks supervisor-agents create-example supervisor-agents/<id> --json '{
77+
"question": "I need my invoice for March",
78+
"guidelines": ["Route to billing_agent"]
79+
}'
80+
81+
databricks supervisor-agents create-example supervisor-agents/<id> --json '{
82+
"question": "API returns 500 error",
83+
"guidelines": ["Route to tech_agent"]
84+
}'
85+
86+
# List / inspect / remove
87+
databricks supervisor-agents list-examples supervisor-agents/<id>
88+
databricks supervisor-agents get-example supervisor-agents/<id>/examples/<ex_id>
89+
databricks supervisor-agents delete-example supervisor-agents/<id>/examples/<ex_id>
90+
91+
# Check endpoint readiness before querying
92+
databricks serving-endpoints get <endpoint_name>
7893
```
7994

8095
## Troubleshooting

‎experimental/databricks-agent-bricks/SKILL.md‎

Lines changed: 68 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -54,48 +54,82 @@ databricks knowledge-assistants delete-knowledge-assistant "knowledge-assistants
5454

5555
## Supervisor Agent
5656

57-
**No CLI** — use `mas_manager.py` from this skill's `scripts/` folder. All `<SKILL_ROOT>/...` paths below are relative to the directory containing this SKILL.md (resolve to the absolute path in your install location).
57+
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.
5858

5959
```bash
60-
# Create MAS
61-
python <SKILL_ROOT>/scripts/mas_manager.py create_mas "My Supervisor" '{
62-
"description": "Routes queries to specialized agents",
63-
"instructions": "Route data questions to analyst, document questions to docs_agent.",
64-
"agents": [
65-
{"name": "analyst", "genie_space_id": "01abc...", "description": "SQL analytics"},
66-
{"name": "docs_agent", "ka_tile_id": "dab408a2-...", "description": "Answers from documents"}
67-
]
60+
# Create the supervisor agent (display name positional, description/instructions as flags)
61+
databricks supervisor-agents create-supervisor-agent "My Supervisor" \
62+
--description "Routes queries to specialized agents" \
63+
--instructions "Route data questions to analyst, document questions to docs_agent."
64+
# → returns {name: "supervisor-agents/<uuid>", endpoint_name: "mas-<short>-endpoint", ...}
65+
66+
# List / get / find by name
67+
databricks supervisor-agents list-supervisor-agents
68+
databricks supervisor-agents get-supervisor-agent supervisor-agents/<id>
69+
databricks supervisor-agents list-supervisor-agents | jq '.[] | select(.display_name == "My Supervisor")'
70+
71+
# Update — UPDATE_MASK + new DISPLAY_NAME are positional; description/instructions optional flags
72+
databricks supervisor-agents update-supervisor-agent supervisor-agents/<id> \
73+
"display_name,description,instructions" "My Supervisor (v2)" \
74+
--description "..." --instructions "..."
75+
76+
# Delete
77+
databricks supervisor-agents delete-supervisor-agent supervisor-agents/<id>
78+
```
79+
80+
### Tools (the agents the supervisor routes to)
81+
82+
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.
83+
84+
```bash
85+
# Attach a Genie space — find its space_id with `databricks genie list-spaces`
86+
databricks supervisor-agents create-tool supervisor-agents/<id> analyst --json '{
87+
"tool_type": "genie_space",
88+
"description": "SQL analytics on the analytics warehouse",
89+
"genie_space": {"id": "<genie_space_id>"}
90+
}'
91+
92+
# Attach a Knowledge Assistant — find ka_id with `databricks knowledge-assistants list-knowledge-assistants`
93+
databricks supervisor-agents create-tool supervisor-agents/<id> docs_agent --json '{
94+
"tool_type": "knowledge_assistant",
95+
"description": "Answers from product documentation",
96+
"knowledge_assistant": {"knowledge_assistant_id": "<ka_id>"}
6897
}'
6998

70-
# Check status and manage. list_mas enumerates every MAS you can access
71-
# and returns {tile_id, name, endpoint_status, agents_count} — use it to
72-
# find a tile_id / see which MAS are ONLINE before operations.
73-
python <SKILL_ROOT>/scripts/mas_manager.py list_mas
74-
python <SKILL_ROOT>/scripts/mas_manager.py get_mas TILE_ID
75-
python <SKILL_ROOT>/scripts/mas_manager.py update_mas TILE_ID '{"agents": [...]}'
76-
python <SKILL_ROOT>/scripts/mas_manager.py delete_mas TILE_ID
77-
78-
# Add examples — requires endpoint_status=ONLINE. After create_mas the MAS is
79-
# NOT_READY and takes up to ~10 min to reach ONLINE. Without --wait, this
80-
# fails fast if not ONLINE yet. With --wait, it blocks until ONLINE then adds.
81-
python <SKILL_ROOT>/scripts/mas_manager.py add_examples TILE_ID '[{"question": "...", "guideline": "..."}]' [--wait]
82-
83-
# Find IDs
84-
databricks knowledge-assistants list-knowledge-assistants --output json | jq '.[].id'
85-
databricks genie list-spaces --output json | jq '.[].space_id'
99+
# List / get / delete tools
100+
databricks supervisor-agents list-tools supervisor-agents/<id>
101+
databricks supervisor-agents get-tool supervisor-agents/<id>/tools/<tool_id>
102+
databricks supervisor-agents delete-tool supervisor-agents/<id>/tools/<tool_id>
86103
```
87104

88-
**Agent types** (use exactly ONE per agent):
105+
**Tool types** (`tool_type` value → type-specific block):
89106

90-
| Field | Type |
91-
|-------|------|
92-
| `ka_tile_id` | Knowledge Assistant |
93-
| `genie_space_id` | Genie Space |
94-
| `endpoint_name` | Model serving endpoint |
95-
| `uc_function_name` | UC function (`catalog.schema.func`) |
96-
| `connection_name` | MCP server (UC HTTP Connection) |
107+
| `tool_type` | Block | Use for |
108+
|---|---|---|
109+
| `genie_space` | `{"id": "<space_id>"}` | Natural language → SQL via Genie |
110+
| `knowledge_assistant` | `{"knowledge_assistant_id": "<ka_id>"}` | Document Q&A via a KA |
111+
| `uc_function` | `{"name": "catalog.schema.func"}` | UC SQL/Python function |
112+
| `uc_connection` | `{"name": "<connection_name>"}` | External MCP server via UC HTTP Connection |
113+
| `volume` | `{"name": "<full_volume_name>"}` | UC Volume browsing |
114+
| `app` | `{"name": "<app_name>"}` | Databricks App |
115+
| 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. |
116+
117+
### Examples (training the supervisor)
118+
119+
Examples must use `--json` — the positional `GUIDELINES` arg doesn't accept any encoding because guidelines is a `repeated string`.
120+
121+
```bash
122+
databricks supervisor-agents create-example supervisor-agents/<id> --json '{
123+
"question": "What were Q4 revenue numbers?",
124+
"guidelines": ["Route to analyst Genie space", "Always group by region"]
125+
}'
126+
127+
databricks supervisor-agents list-examples supervisor-agents/<id>
128+
databricks supervisor-agents get-example supervisor-agents/<id>/examples/<ex_id>
129+
databricks supervisor-agents delete-example supervisor-agents/<id>/examples/<ex_id>
130+
```
97131

98-
**Status:** `NOT_READY` (up to ~10 min after create/big update) → `ONLINE` → `OFFLINE`
132+
**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>`.
99133

100134
---
101135

0 commit comments

Comments
 (0)