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.

`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.

`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/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/appkit.plugins.json` — adds the `agent` plugin entry so
`npx @databricks/appkit init --features agent` scaffolds the plugin
correctly.

- 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>

Documents the new `mcp` configuration block and the rules it enforces:
same-origin-only by default, explicit `trustedHosts` for external MCP
servers, plaintext `http://` refused outside localhost-in-dev, and
DNS-level blocking of private / link-local IP ranges (covers cloud
metadata services). See PR #302 for the policy implementation and
PR #304 for the `AgentsPluginConfig.mcp` wiring.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

- `docs/docs/plugins/agents.md`: new "SQL agent tools" subsection
  covering `analytics.query` readOnly enforcement, `lakebase.query`
  opt-in via `exposeAsAgentTool`, and the approval flow. New
  "Human-in-the-loop approval for destructive tools" subsection
  documents the config, SSE event shape, and `POST /chat/approve`
  contract.

- `apps/agent-app`: approval-card component rendered inline in the
  chat stream whenever an `appkit.approval_pending` event arrives.
  Destructive badge + Approve/Deny buttons POST to
  `/api/agent/approve` with the carried `streamId`/`approvalId`.

- `apps/dev-playground/client`: matching approval-card on the agent
  route, using the existing appkit-ui `Button` component and
  Tailwind utility classes.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Updates `docs/docs/plugins/agents.md` to document the new
two-key auto-inherit model introduced in PR #302 (per-tool
`autoInheritable` flag) and PR #304 (safe-by-default
`autoInheritTools: { file: false, code: false }`). Adds an
"Auto-inherit posture" subsection explaining that the developer
must opt into `autoInheritTools` AND the plugin author must mark
each tool `autoInheritable: true` for a tool to spread without
explicit wiring.

Includes a table documenting the `autoInheritable` marking on each
core plugin tool, plus an example of the setup-time audit log so
operators can see exactly what's inherited vs. skipped.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

- **Reference app no longer ships hardcoded dogfood URLs.** The three
  `https://e2-dogfood.staging.cloud.databricks.com/...` and
  `https://mario-mcp-hello-*.staging.aws.databricksapps.com/...` MCP
  URLs in `apps/agent-app/server.ts` are replaced with optional
  env-driven `VECTOR_SEARCH_MCP_URL` / `CUSTOM_MCP_URL` config. When
  set, their hostnames are auto-added to `agents({ mcp: { trustedHosts
  } })`. `.env.example` uses placeholder values the reader can replace
  instead of another team's workspace.

- **`appkit.agent` → `appkit.agents` in the reference app.** The
  prior `appkit.agent as { list, getDefault }` cast papered over the
  plugin-name mismatch fixed in PR #304. The runtime key now matches
  the docs, the manifest, and the factory name; the cast is gone.

- **Auto-inherit opt-in added to the reference config.** Since the
  defaults flipped to `{ file: false, code: false }` (PR #304, S-3),
  the reference now explicitly enables `autoInheritTools: { file:
  true }` so the markdown agents that ship alongside the code-defined
  one still pick up the analytics / files read-only tools. This is the
  pattern a real deployment should follow — opt in deliberately.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

- `apps/dev-playground/config/agents/autocomplete.md` sets
  `ephemeral: true`. Each debounced autocomplete keystroke no longer
  leaves an orphan thread in `InMemoryThreadStore` — the server now
  deletes the thread in the stream's `finally` (PR #304). Closes R1
  from the MVP re-review.
- `docs/docs/plugins/agents.md` documents the new `ephemeral`
  frontmatter key alongside the other AgentDefinition knobs.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Documents the MVP resource caps landed in PR #304: the static
request-body caps (enforced by the Zod schemas) and the three
configurable runtime limits (`maxConcurrentStreamsPerUser`,
`maxToolCalls`, `maxSubAgentDepth`). Includes the config-block
shape in the main reference and a new "Resource limits" subsection
under the Configuration section explaining the intent and per-user
semantics of each cap.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: MarioCadenas

apps/agent-app/.env.example

@@ -0,0 +1,16 @@
+# Databricks workspace (auto-injected by platform on deploy)
+DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
+
+# Agent LLM endpoint (Model Serving endpoint name)
+DATABRICKS_AGENT_ENDPOINT=databricks-claude-sonnet-4-5
+
+# Analytics plugin — SQL warehouse ID
+DATABRICKS_WAREHOUSE_ID=your-warehouse-id
+
+# Files plugin — Volume path (catalog.schema.volume)
+DATABRICKS_VOLUME_FILES=/Volumes/your-catalog/your-schema/your-volume
+
+# Optional: Custom MCP servers the agent can call. When set, the hostname
+# is automatically added to agents({ mcp: { trustedHosts } }).
+# VECTOR_SEARCH_MCP_URL=https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema>/<index>
+# CUSTOM_MCP_URL=https://<your-mcp-server>/mcp

apps/agent-app/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.env

apps/agent-app/app.yaml

@@ -0,0 +1,8 @@
+command: ['node', '--import', 'tsx', 'server.ts']
+env:
+  - name: DATABRICKS_WAREHOUSE_ID
+    valueFrom: sql-warehouse
+  - name: DATABRICKS_AGENT_ENDPOINT
+    valueFrom: serving-endpoint
+  - name: DATABRICKS_VOLUME_FILES
+    valueFrom: volume

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

@@ -0,0 +1,23 @@
+---
+endpoint: databricks-claude-sonnet-4-5
+default: true
+toolkits:
+  - files: [files.list, files.upload, files.delete]
+agents:
+  - support
+  - researcher
+---
+
+You are a front-desk dispatcher running on Databricks.
+
+Delegate requests to the right specialist:
+
+- `agent-support` — data analysis (SQL via analytics), file browsing, and general questions.
+- `agent-researcher` — research and knowledge lookups that benefit from MCP-hosted tools (vector search, custom endpoints).
+
+Only use your own tools (`files.upload`, `files.delete`, `files.list`) for
+file-management actions the user explicitly asks for. Destructive ones
+(`upload`, `delete`) will prompt the user for approval before running.
+
+Keep your own responses short — mostly routing decisions plus a brief summary
+of what the specialist returned.

apps/agent-app/config/agents/support.md

@@ -0,0 +1,17 @@
+---
+endpoint: databricks-claude-sonnet-4-5
+toolkits:
+  - analytics
+  - files
+tools:
+  - get_weather
+  # Optional MCP servers — uncomment the ones whose env vars are set in
+  # .env (VECTOR_SEARCH_MCP_URL, CUSTOM_MCP_URL). `server.ts` only
+  # registers each as ambient when its URL is configured, so leaving a
+  # reference here while the env var is unset will fail at startup.
+  # - mcp.vector-search
+  # - mcp.custom
+---
+
+You help customers with data analysis, file browsing, and general questions.
+Use the available tools as needed and summarize results concisely.

apps/agent-app/databricks.yml

@@ -0,0 +1,50 @@
+bundle:
+  name: appkit-agent-app
+
+variables:
+  sql_warehouse_id:
+    description: SQL Warehouse ID for analytics queries
+  serving_endpoint_name:
+    description: Model Serving endpoint name for the agent LLM
+  volume_full_name:
+    description: "UC Volume full name (e.g. catalog.schema.volume_name)"
+
+resources:
+  apps:
+    agent_app:
+      name: "appkit-agent-app"
+      description: "AppKit agent with auto-discovered tools from analytics, files, and genie plugins"
+      source_code_path: ./
+
+      user_api_scopes:
+        - sql
+        - files.files
+        - dashboards.genie
+
+      resources:
+        - name: sql-warehouse
+          sql_warehouse:
+            id: ${var.sql_warehouse_id}
+            permission: CAN_USE
+
+        - name: serving-endpoint
+          serving_endpoint:
+            name: ${var.serving_endpoint_name}
+            permission: CAN_QUERY
+
+        - name: volume
+          uc_securable:
+            securable_type: VOLUME
+            securable_full_name: ${var.volume_full_name}
+            permission: WRITE_VOLUME
+
+targets:
+  dogfood:
+    default: true
+    workspace:
+      host: https://e2-dogfood.staging.cloud.databricks.com
+
+    variables:
+      sql_warehouse_id: dd43ee29fedd958d
+      serving_endpoint_name: databricks-claude-sonnet-4-5
+      volume_full_name: main.mario.mario-vol

apps/agent-app/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AppKit Agent</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/agent-app/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agent-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "NODE_ENV=development tsx watch server.ts",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@databricks/appkit": "workspace:*",
+    "@databricks/appkit-ui": "workspace:*",
+    "@databricks/sdk-experimental": "^0.16.0",
+    "dotenv": "^16.6.1",
+    "lucide-react": "^0.511.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "marked": "^15.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.1.17",
+    "@types/node": "24.10.1",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "5.1.1",
+    "autoprefixer": "10.4.21",
+    "postcss": "8.5.6",
+    "tailwindcss": "4.1.17",
+    "tailwindcss-animate": "1.0.7",
+    "tw-animate-css": "1.4.0",
+    "tsx": "4.20.6",
+    "typescript": "5.9.3",
+    "vite": "npm:rolldown-vite@7.1.14"
+  },
+  "overrides": {
+    "vite": "npm:rolldown-vite@7.1.14"
+  }
+}

apps/agent-app/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+    autoprefixer: {},
+  },
+};

apps/agent-app/server.ts

@@ -0,0 +1,100 @@
+import {
+  agents,
+  analytics,
+  createAgent,
+  createApp,
+  files,
+  mcpServer,
+  server,
+  tool,
+} from "@databricks/appkit";
+import { z } from "zod";
+
+const port = Number(process.env.DATABRICKS_APP_PORT) || 8003;
+
+// Ambient function tool. Referenced from `config/agents/support.md` under
+// `tools: [get_weather]`. Markdown frontmatter looks up this name against
+// the `tools:` record passed to `agents({ tools: { get_weather } })` below.
+const get_weather = tool({
+  name: "get_weather",
+  description: "Get the current weather for a city",
+  schema: z.object({
+    city: z.string().describe("City name"),
+  }),
+  execute: async ({ city }) => `The weather in ${city} is sunny, 22°C`,
+});
+
+// MCP servers are conditional on runtime env vars — something markdown
+// frontmatter can't express. This is the motivating case for defining
+// the `researcher` agent in code below: it wires whatever MCP tools are
+// configured at boot, and is always callable (with a graceful fallback
+// when nothing is wired).
+//
+// Any MCP URL configured here must also be allowlisted via
+// `agents({ mcp: { trustedHosts: [...] } })` before outbound calls will
+// be allowed by the zero-trust host policy.
+const customMcpServers: Record<string, ReturnType<typeof mcpServer>> = {};
+if (process.env.VECTOR_SEARCH_MCP_URL) {
+  customMcpServers["mcp.vector-search"] = mcpServer(
+    "vector-search",
+    process.env.VECTOR_SEARCH_MCP_URL,
+  );
+}
+if (process.env.CUSTOM_MCP_URL) {
+  customMcpServers["mcp.custom"] = mcpServer(
+    "custom",
+    process.env.CUSTOM_MCP_URL,
+  );
+}
+
+// Code-defined research specialist. `assistant.md` references this by name
+// under `agents: [researcher]`; the agents plugin resolves that reference
+// against both markdown siblings and code-defined agents, with code winning
+// on collision. Defined in code so its MCP toolset can flex on env vars.
+const researcher = createAgent({
+  instructions:
+    "You are a research specialist. When MCP tools are available " +
+    "(vector search, custom endpoints), prefer them for knowledge lookups. " +
+    "If no MCP tools are configured, say so briefly and answer from general " +
+    "knowledge. Always include your source or note when you're answering " +
+    "without search.",
+  tools: {
+    get_weather,
+    ...customMcpServers,
+  },
+});
+
+const trustedMcpHosts = [
+  process.env.VECTOR_SEARCH_MCP_URL,
+  process.env.CUSTOM_MCP_URL,
+]
+  .filter((u): u is string => typeof u === "string" && u.length > 0)
+  .map((u) => new URL(u).hostname);
+
+const appkit = await createApp({
+  plugins: [
+    server({ port }),
+    analytics(),
+    files(),
+    agents({
+      // Code-defined agents merged with markdown agents; code wins on name
+      // collision. Markdown `agents: [...]` frontmatter can reference either.
+      agents: { researcher },
+      // Ambient tool library for markdown agents referencing names under
+      // their `tools:` frontmatter.
+      tools: { get_weather, ...customMcpServers },
+      // Enables auto-inherit of read-only plugin tools (analytics/files) into
+      // markdown agents that declare no explicit `toolkits:` / `tools:`. Both
+      // assistant.md and support.md are explicit, so this is a no-op today,
+      // but kept as a knob markdown authors can rely on.
+      autoInheritTools: { file: true },
+      mcp: { trustedHosts: trustedMcpHosts },
+    }),
+  ],
+});
+
+console.log(
+  `Agent app running on port ${port}. ` +
+    `Agents: ${appkit.agents.list().join(", ") || "(none)"}. ` +
+    `Default: ${appkit.agents.getDefault() ?? "(none)"}.`,
+);