Skip to content

Commit 4a441d2

Browse files
MarioCadenasMarioCadenas
committed
feat(appkit): reference agent-app, dev-playground chat UI, docs, and template
Final layer of the agents feature stack. Everything needed to exercise, demonstrate, and learn the feature. ### Reference application: agent-app `apps/agent-app/` — a standalone app purpose-built around the agents feature. Ships with: - `server.ts` — full example of code-defined agents via `fromPlugin`: ```ts const support = createAgent({ instructions: "…", tools: { ...fromPlugin(analytics), ...fromPlugin(files), get_weather, "mcp.vector-search": mcpServer("vector-search", "https://…"), }, }); await createApp({ plugins: [server({ port }), analytics(), files(), agents({ agents: { support } })], }); ``` - `config/agents/assistant.md` — markdown-driven agent alongside the code-defined one, showing the asymmetric auto-inherit default. - Vite + React 19 + TailwindCSS frontend with a chat UI. - Databricks deployment config (`databricks.yml`, `app.yaml`) and deploy scripts. ### dev-playground chat UI + demo agent `apps/dev-playground/client/src/routes/agent.route.tsx` — chat UI with inline autocomplete (hits the `autocomplete` markdown agent) and a full threaded conversation panel (hits the default agent). `apps/dev-playground/server/index.ts` — adds a code-defined `helper` agent using `fromPlugin(analytics)` alongside the markdown-driven `autocomplete` agent in `config/agents/`. Exercises the mixed-style setup (markdown + code) against the same plugin list. `apps/dev-playground/config/agents/*.md` — both agents defined with valid YAML frontmatter. ### Docs `docs/docs/plugins/agents.md` — progressive five-level guide: 1. Drop a markdown file → it just works. 2. Scope tools via `toolkits:` / `tools:` frontmatter. 3. Code-defined agents with `fromPlugin()`. 4. Sub-agents. 5. Standalone `runAgent()` (no `createApp` or HTTP). Plus a configuration reference, runtime API reference, and frontmatter schema table. `docs/docs/api/appkit/` — regenerated typedoc for the new public surface (fromPlugin, runAgent, AgentDefinition, AgentsPluginConfig, ToolkitEntry, ToolkitOptions, all adapter types, and the agents plugin factory). ### Template `template/appkit.plugins.json` — adds the `agent` plugin entry so `npx @databricks/appkit init --features agent` scaffolds the plugin correctly. ### Test plan - Full appkit vitest suite: 1311 tests passing - Typecheck clean across all 8 workspace projects - `pnpm docs:build` clean (no broken links) - `pnpm --filter=@databricks/appkit build:package` clean, publint clean Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
1 parent 29e3534 commit 4a441d2

67 files changed

Lines changed: 3673 additions & 59 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/agent-app/.env.example‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Databricks workspace (auto-injected by platform on deploy)
2+
DATABRICKS_HOST=https://e2-dogfood.staging.cloud.databricks.com
3+
4+
# Agent LLM endpoint
5+
DATABRICKS_AGENT_ENDPOINT=databricks-claude-sonnet-4-5
6+
7+
# Analytics plugin — SQL warehouse ID
8+
DATABRICKS_WAREHOUSE_ID=dd43ee29fedd958d
9+
10+
# Files plugin — Volume path
11+
DATABRICKS_VOLUME_FILES=/Volumes/main/mario/mario-vol

‎apps/agent-app/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
dist
3+
.env

‎apps/agent-app/app.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
command: ['node', '--import', 'tsx', 'server.ts']
2+
env:
3+
- name: DATABRICKS_WAREHOUSE_ID
4+
valueFrom: sql-warehouse
5+
- name: DATABRICKS_AGENT_ENDPOINT
6+
valueFrom: serving-endpoint
7+
- name: DATABRICKS_VOLUME_FILES
8+
valueFrom: volume

‎apps/agent-app/config/agents/assistant.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
endpoint: databricks-claude-sonnet-4-5
3+
default: true
4+
---
5+
6+
You are a helpful data assistant running on Databricks.
7+
8+
Use the available tools to query data, browse files, and help users with their analysis.
9+
10+
When using `analytics.query`, write Databricks SQL. When results are large, summarize the key findings rather than dumping raw data.
11+
12+
You also have access to additional tools from MCP servers — use them when relevant.

‎apps/agent-app/databricks.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
bundle:
2+
name: appkit-agent-app
3+
4+
variables:
5+
sql_warehouse_id:
6+
description: SQL Warehouse ID for analytics queries
7+
serving_endpoint_name:
8+
description: Model Serving endpoint name for the agent LLM
9+
volume_full_name:
10+
description: "UC Volume full name (e.g. catalog.schema.volume_name)"
11+
12+
resources:
13+
apps:
14+
agent_app:
15+
name: "appkit-agent-app"
16+
description: "AppKit agent with auto-discovered tools from analytics, files, and genie plugins"
17+
source_code_path: ./
18+
19+
user_api_scopes:
20+
- sql
21+
- files.files
22+
- dashboards.genie
23+
24+
resources:
25+
- name: sql-warehouse
26+
sql_warehouse:
27+
id: ${var.sql_warehouse_id}
28+
permission: CAN_USE
29+
30+
- name: serving-endpoint
31+
serving_endpoint:
32+
name: ${var.serving_endpoint_name}
33+
permission: CAN_QUERY
34+
35+
- name: volume
36+
uc_securable:
37+
securable_type: VOLUME
38+
securable_full_name: ${var.volume_full_name}
39+
permission: WRITE_VOLUME
40+
41+
targets:
42+
dogfood:
43+
default: true
44+
workspace:
45+
host: https://e2-dogfood.staging.cloud.databricks.com
46+
47+
variables:
48+
sql_warehouse_id: dd43ee29fedd958d
49+
serving_endpoint_name: databricks-claude-sonnet-4-5
50+
volume_full_name: main.mario.mario-vol

‎apps/agent-app/index.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>AppKit Agent</title>
7+
</head>
8+
<body>
9+
<div id="root"></div>
10+
<script type="module" src="/src/main.tsx"></script>
11+
</body>
12+
</html>

‎apps/agent-app/package.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"name": "agent-app",
3+
"private": true,
4+
"version": "0.0.0",
5+
"type": "module",
6+
"scripts": {
7+
"dev": "NODE_ENV=development tsx watch server.ts",
8+
"build": "tsc -b && vite build",
9+
"preview": "vite preview"
10+
},
11+
"dependencies": {
12+
"@databricks/appkit": "workspace:*",
13+
"@databricks/appkit-ui": "workspace:*",
14+
"@databricks/sdk-experimental": "^0.16.0",
15+
"dotenv": "^16.6.1",
16+
"lucide-react": "^0.511.0",
17+
"react": "19.2.0",
18+
"react-dom": "19.2.0",
19+
"marked": "^15.0.0",
20+
"zod": "^4.0.0"
21+
},
22+
"devDependencies": {
23+
"@tailwindcss/postcss": "4.1.17",
24+
"@types/node": "24.10.1",
25+
"@types/react": "19.2.7",
26+
"@types/react-dom": "19.2.3",
27+
"@vitejs/plugin-react": "5.1.1",
28+
"autoprefixer": "10.4.21",
29+
"postcss": "8.5.6",
30+
"tailwindcss": "4.1.17",
31+
"tailwindcss-animate": "1.0.7",
32+
"tw-animate-css": "1.4.0",
33+
"tsx": "4.20.6",
34+
"typescript": "5.9.3",
35+
"vite": "npm:rolldown-vite@7.1.14"
36+
},
37+
"overrides": {
38+
"vite": "npm:rolldown-vite@7.1.14"
39+
}
40+
}

‎apps/agent-app/postcss.config.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
export default {
2+
plugins: {
3+
"@tailwindcss/postcss": {},
4+
autoprefixer: {},
5+
},
6+
};

‎apps/agent-app/server.ts‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
import {
2+
agents,
3+
analytics,
4+
createAgent,
5+
createApp,
6+
files,
7+
fromPlugin,
8+
mcpServer,
9+
server,
10+
tool,
11+
} from "@databricks/appkit";
12+
import { z } from "zod";
13+
14+
const port = Number(process.env.DATABRICKS_APP_PORT) || 8003;
15+
16+
// Shared tool available to any agent that declares `tools: [get_weather]` in
17+
// its markdown frontmatter.
18+
const get_weather = tool({
19+
name: "get_weather",
20+
description: "Get the current weather for a city",
21+
schema: z.object({
22+
city: z.string().describe("City name"),
23+
}),
24+
execute: async ({ city }) => `The weather in ${city} is sunny, 22°C`,
25+
});
26+
27+
// Code-defined agent. Overrides config/agents/support.md if a file with that
28+
// name exists. Tools here are explicit; defaults are strict (no auto-inherit
29+
// for code-defined agents), so we pull analytics + files in via fromPlugin.
30+
const support = createAgent({
31+
instructions:
32+
"You help customers with data analysis, file browsing, and general questions. " +
33+
"Use the available tools as needed and summarize results concisely.",
34+
tools: {
35+
...fromPlugin(analytics),
36+
...fromPlugin(files),
37+
get_weather,
38+
"mcp.vector-search": mcpServer(
39+
"vector-search",
40+
"https://e2-dogfood.staging.cloud.databricks.com/api/2.0/mcp/vector-search/main/default",
41+
),
42+
"mcp.uc-greet": mcpServer(
43+
"uc-greet",
44+
"https://e2-dogfood.staging.cloud.databricks.com/api/2.0/mcp/functions/main/mario/greet",
45+
),
46+
"mcp.mario-hello": mcpServer(
47+
"mario-mcp-hello",
48+
"https://mario-mcp-hello-6051921418418893.staging.aws.databricksapps.com/mcp",
49+
),
50+
},
51+
});
52+
53+
const appkit = await createApp({
54+
plugins: [
55+
server({ port }),
56+
analytics(),
57+
files(),
58+
agents({
59+
// Ambient tool library referenced by markdown frontmatter `tools: [...]`.
60+
tools: { get_weather },
61+
// Code-defined agents are merged with markdown agents; code wins on key
62+
// collision. Markdown agents still auto-inherit analytics+files tools
63+
// unless their frontmatter says otherwise.
64+
agents: { support },
65+
}),
66+
],
67+
});
68+
69+
const registry = appkit.agent as {
70+
list: () => string[];
71+
getDefault: () => string | null;
72+
};
73+
console.log(
74+
`Agent app running on port ${port}. Agents: ${registry.list().join(", ")}. Default: ${registry.getDefault() ?? "(none)"}.`,
75+
);

0 commit comments

Comments
 (0)