@databricks/appkit-ui 0.31.0 → 0.33.0

package/docs/plugins/agents.md

@@ -0,0 +1,441 @@
+# Agents
+
+Beta plugin
+
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
+
+The `agents` plugin turns a Databricks AppKit app into an AI-agent host. It loads agent definitions from markdown on disk (one folder per agent: `config/agents/<id>/agent.md`), from TypeScript (`createAgent(def)`), or both, and exposes them at `POST /invocations` alongside routes for chat, thread management, and cancellation.
+
+This page covers the full lifecycle. For the hand-written primitives (`tool()`, `mcpServer()`), see [tools](./docs/plugins/server.md).
+
+## Requirements[​](#requirements "Direct link to Requirements")
+
+Streaming-capable serving endpoints only
+
+The agents plugin drives the LLM over Server-Sent Events. Foundation Model APIs (Claude, Llama, GPT, etc.) and other chat-style endpoints support streaming and work out of the box. Custom model endpoints that return a single JSON response (e.g. typical `sklearn` or MLflow `pyfunc` deployments) do **not** stream — pointing an agent at one will fail with "Response body is null — streaming not supported" on the first turn. If you list a serving endpoint in `apps init`, pick one whose model implements the chat-completions streaming protocol; the agents plugin reads its name from `DATABRICKS_SERVING_ENDPOINT_NAME` whenever an agent doesn't pin `model:` itself.
+
+For the non-streaming path against a custom endpoint, use the `serving` plugin's `/invoke` route with `useServingInvoke` instead.
+
+## Install[​](#install "Direct link to Install")
+
+`agents` is a regular plugin. Add it to `plugins[]` alongside `server()` and any ToolProvider plugins whose tools you want agents to reach.
+
+```ts
+import { agents, analytics, createApp, files, server } from "@databricks/appkit";
+import { agents } from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [server(), analytics(), files(), agents()],
+});
+
+```
+
+That alone gives you a live HTTP server with `POST /invocations` wired to a markdown-driven agent.
+
+## Level 1: drop a markdown agent package[​](#level-1-drop-a-markdown-agent-package "Direct link to Level 1: drop a markdown agent package")
+
+Each agent lives in its own directory with a fixed entry file `agent.md`. A reserved top-level folder named `skills` is ignored until per-agent skills ship (you can add other asset folders beside `agent.md` under each agent id).
+
+```text
+my-app/
+  server.ts
+  config/agents/
+    assistant/
+      agent.md
+
+```
+
+```md
+---
+endpoint: databricks-claude-sonnet-4-5
+default: true
+---
+
+You are a helpful data assistant running on Databricks.
+
+Use the available tools to query data, browse files, and help users.
+
+```
+
+On startup the plugin:
+
+1. Discovers `./config/agents/assistant/agent.md` and registers agent id `assistant`.
+2. Parses the YAML frontmatter and markdown body as the agent's `instructions`.
+3. Resolves the adapter from `endpoint` (or falls back to `DATABRICKS_AGENT_ENDPOINT`).
+4. Mounts the agent at the default name (`assistant`).
+
+The agent starts with **no tools**. Tools are opt-in — declare them in frontmatter (Level 2 below) or opt into auto-inherit explicitly with `agents({ autoInheritTools: { file: true } })`. See "Auto-inherit posture" further down for what that costs and why it's off by default.
+
+Requests land at `POST /invocations` with an OpenAI Responses-compatible body. Every tool call runs through `asUser(req)` so SQL executes as the requesting user, file access respects Unity Catalog ACLs, and telemetry spans are created automatically.
+
+## Level 2: scope tools in frontmatter[​](#level-2-scope-tools-in-frontmatter "Direct link to Level 2: scope tools in frontmatter")
+
+```md
+---
+endpoint: databricks-claude-sonnet-4-5
+tools:
+  - plugin:analytics                              # all analytics.* tools
+  - plugin:files: [uploads.read, uploads.list]    # only these files tools
+  - plugin:genie: { except: [getConversation] }   # everything but getConversation
+  - get_weather                                   # ambient tool declared in code
+default: true
+---
+
+You are a read-only data analyst.
+
+```
+
+The unified `tools:` list mixes plugin references and ambient tools, mirroring the TS function form `tools(plugins) => ({ ...plugins.analytics.toolkit(), ...plugins.files.toolkit({ only: [...] }), get_weather: tool({...}) })`. Each entry is one of:
+
+* **`plugin:<name>`** — pull every tool from the named plugin.
+* **`plugin:<name>: [tool1, tool2]`** — only the listed tools (sugar for `{ only: [...] }`).
+* **`plugin:<name>: { ...ToolkitOptions }`** — full `prefix` / `only` / `except` / `rename` options.
+* **`<key>`** (no prefix) — ambient tool name resolved against the `agents({ tools: { ... } })` config.
+
+When any `tools:` is declared the auto-inherit default is turned off — the agent sees exactly the listed tools.
+
+## Level 3: code-defined agents[​](#level-3-code-defined-agents "Direct link to Level 3: code-defined agents")
+
+```ts
+import { analytics, createApp, files, server } from "@databricks/appkit";
+import { agents, createAgent, tool } from "@databricks/appkit/beta";
+import { z } from "zod";
+
+const support = createAgent({
+  instructions: "You help customers with data and files.",
+  model: "databricks-claude-sonnet-4-5",                      // string sugar
+  tools(plugins) {
+    return {
+      ...plugins.analytics.toolkit(),                          // all analytics tools
+      ...plugins.files.toolkit({ only: ["uploads.read"] }),    // filtered subset
+      get_weather: tool({
+        description: "Weather",
+        schema: z.object({ city: z.string() }),
+        execute: async ({ city }) => `Sunny in ${city}`,
+      }),
+    };
+  },
+});
+
+await createApp({
+  plugins: [server(), analytics(), files(), agents({ agents: { support } })],
+});
+
+```
+
+Code-defined agents start with no tools by default. The function form `tools(plugins) => Record<string, AgentTool>` is the primary way to pull in plugin tools: each plugin registered in `createApp({ plugins: [...] })` shows up on the `plugins` parameter, and you call `.toolkit(opts?)` on it to get a spread-friendly record. The runtime invokes the function once at agent setup and caches the result — every plugin is mentioned exactly once (in `createApp`), with no held variables or marker imports.
+
+Inline `tool({...})` calls live in the same record. `name` is optional — the agents plugin overrides it with the record key (`get_weather` above).
+
+The asymmetry (file: auto-inherit, code: strict) matches the personas: prompt authors want zero ceremony, engineers want no surprises.
+
+### Scoping tools in code[​](#scoping-tools-in-code "Direct link to Scoping tools in code")
+
+`plugins.<name>.toolkit(opts?)` accepts the same `ToolkitOptions` as markdown frontmatter:
+
+| Option   | Example                      | Meaning                          |
+| -------- | ---------------------------- | -------------------------------- |
+| `only`   | `{ only: ["query"] }`        | Allowlist of local tool names    |
+| `except` | `{ except: ["legacy"] }`     | Denylist of local tool names     |
+| `prefix` | `{ prefix: "" }`             | Drop the `${pluginName}.` prefix |
+| `rename` | `{ rename: { query: "q" } }` | Remap specific local names       |
+
+For plugins that don't expose a `.toolkit()` method (e.g., third-party `ToolProvider` plugins authored with plain `toPlugin`), the runtime falls back to walking `getAgentTools()` and synthesizing namespaced keys (`${pluginName}.${localName}`). The fallback respects `only` / `except` / `rename` / `prefix` the same way.
+
+If a referenced plugin is not registered in `createApp({ plugins })`, the agents plugin throws at setup with an `Available: …` listing so you can fix the wiring before the first request.
+
+## Level 4: sub-agents[​](#level-4-sub-agents "Direct link to Level 4: sub-agents")
+
+```ts
+const researcher = createAgent({
+  instructions: "Research the question. Return concise bullets.",
+  model: "databricks-claude-sonnet-4-5",
+  tools: { search: tool({ /* ... */ }) },
+});
+
+const writer = createAgent({
+  instructions: "Draft prose from notes.",
+  model: "databricks-claude-sonnet-4-5",
+});
+
+const supervisor = createAgent({
+  instructions: "Coordinate researcher and writer.",
+  model: "databricks-claude-sonnet-4-5",
+  agents: { researcher, writer },  // exposed as agent-researcher, agent-writer
+});
+
+await createApp({
+  plugins: [
+    server(),
+    agents({ agents: { supervisor, researcher, writer } }),
+  ],
+});
+
+```
+
+Each key in `agents: {...}` on an `AgentDefinition` becomes an `agent-<key>` tool on the parent. When invoked, the agents plugin runs the child's adapter with a fresh message list (no shared thread state) and returns the aggregated text. Cycles are rejected at load time.
+
+## Level 5: standalone (no `createApp`)[​](#level-5-standalone-no-createapp "Direct link to level-5-standalone-no-createapp")
+
+```ts
+import { createAgent, runAgent, tool } from "@databricks/appkit";
+import { z } from "zod";
+
+const classifier = createAgent({
+  instructions: "Classify tickets: billing | bug | feature.",
+  model: "databricks-claude-sonnet-4-5",
+  tools: {
+    lookup_account: tool({ /* ... */ }),
+  },
+});
+
+for (const ticket of tickets) {
+  const result = await runAgent(classifier, {
+    messages: [{ role: "user", content: ticket.body }],
+  });
+  await persistClassification(ticket.id, result.text);
+}
+
+```
+
+`runAgent` drives the adapter without `createApp` or HTTP. Inline `tool()` calls work standalone as shown above. To use plugin tools in standalone mode, pass the plugin factories through `RunAgentInput.plugins` and reach into them via the `tools(plugins)` function form:
+
+```ts
+import { analytics } from "@databricks/appkit";
+import { createAgent, runAgent } from "@databricks/appkit/beta";
+
+const classifier = createAgent({
+  instructions: "Classify tickets. Use analytics.query for historical data.",
+  model: "databricks-claude-sonnet-4-5",
+  tools(plugins) {
+    return { ...plugins.analytics.toolkit() };
+  },
+});
+
+const result = await runAgent(classifier, {
+  messages: "is ticket 42 a duplicate?",
+  plugins: [analytics()],
+});
+
+```
+
+`runAgent` eagerly constructs each plugin in `RunAgentInput.plugins`, runs the standard `attachContext({})` + `await setup()` lifecycle, and shares the instances across the top-level run and every sub-agent dispatch. Plugins whose `setup()` requires `createApp`-only runtime (e.g. `WorkspaceClient`, `ServiceContext`) throw at standalone-init with a clear "use createApp instead" message rather than mid-stream.
+
+Hosted tools (MCP) are still `agents()`-only since they require the live MCP client. Plugin tool dispatch in standalone mode runs as the service principal (no OBO) and **bypasses the agents-plugin approval gate** — treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts), not as an exposed user-facing surface.
+
+## Configuration reference[​](#configuration-reference "Direct link to Configuration reference")
+
+```ts
+agents({
+  dir?: string | false,         // "./config/agents" default; false disables
+  agents?: Record<string, AgentDefinition>,
+  defaultAgent?: string,
+  defaultModel?: AgentAdapter | Promise<AgentAdapter> | string,
+  tools?: Record<string, AgentTool>,
+  autoInheritTools?: boolean | { file?: boolean, code?: boolean },
+  threadStore?: ThreadStore,    // default in-memory
+  baseSystemPrompt?: false | string | (ctx: PromptContext) => string,
+  mcp?: {
+    trustedHosts?: string[],    // extra hostnames allowed for custom MCP URLs
+    allowLocalhost?: boolean,   // default: NODE_ENV !== "production"
+  },
+  approval?: {
+    requireForDestructive?: boolean,  // default: true
+    timeoutMs?: number,               // default: 60_000
+  },
+  limits?: {
+    maxConcurrentStreamsPerUser?: number, // default: 5
+    maxToolCalls?: number,                // default: 50
+    maxSubAgentDepth?: number,            // default: 3
+  },
+})
+
+```
+
+`autoInheritTools` defaults to `{ file: false, code: false }` — no tools spread into any agent unless the developer explicitly opts in. When opted in, only tools whose plugin author marked `autoInheritable: true` are spread; destructive or state-mutating tools are always skipped from the auto-inherit path even when opt-in is enabled. Boolean shorthand (`autoInheritTools: true`) applies to both origins. See "Auto-inherit posture" below.
+
+### MCP host policy[​](#mcp-host-policy "Direct link to MCP host policy")
+
+AppKit applies a zero-trust policy to every MCP URL used as a hosted tool. By default only **same-origin Databricks workspace URLs** (matching the resolved `DATABRICKS_HOST`) may be reached. Every other host must be explicitly allowlisted via `mcp.trustedHosts`, and workspace credentials (service-principal and on-behalf-of user tokens) are **never** forwarded to those hosts.
+
+```ts
+agents({
+  agents: {
+    support: createAgent({
+      instructions: "…",
+      tools: {
+        "mcp.internal": mcpServer("internal", "https://mcp.corp.internal/mcp"),
+      },
+    }),
+  },
+  mcp: {
+    trustedHosts: ["mcp.corp.internal"],
+  },
+});
+
+```
+
+The policy enforces four rules at MCP `connect()` time, before any byte is sent:
+
+1. Only `http` and `https` URLs are accepted.
+2. Plaintext `http://` is rejected for everything except `localhost` when `allowLocalhost` is true (default in development, off in production).
+3. The destination hostname must match the workspace host, equal `localhost` (if permitted), or appear in `trustedHosts`.
+4. The resolved DNS address must not fall in loopback, RFC1918, CGNAT (100.64.0.0/10), link-local (169.254.0.0/16 — covers cloud metadata services), ULA, or multicast ranges.
+
+`Authorization` headers carrying workspace credentials are scoped to same-origin workspace URLs. A `mcpServer(name, url)` pointing at a trusted external host must authenticate itself (for example, a custom token baked into `url`).
+
+### Auto-inherit posture[​](#auto-inherit-posture "Direct link to Auto-inherit posture")
+
+AppKit treats auto-inherit as a two-key operation: the developer must opt into `autoInheritTools`, AND the plugin author must mark each tool `autoInheritable: true`. Both are required for a tool to spread into an agent's index without explicit wiring.
+
+```ts
+// Opt-in at the agents plugin level (pick one):
+agents({ autoInheritTools: true });                   // both origins
+agents({ autoInheritTools: { file: true } });         // markdown agents only
+agents({ autoInheritTools: { file: true, code: true } });
+
+// Per-tool, inside a plugin:
+defineTool({
+  description: "safe read",
+  schema: z.object({ ... }),
+  annotations: { effect: "read", requiresUserContext: true },
+  autoInheritable: true, // explicit consent that this tool may auto-spread
+  execute: (args, signal) => ...,
+});
+
+```
+
+The AppKit core plugins ship with the following `autoInheritable` markings:
+
+| Tool                                                            | `autoInheritable` | Rationale                                                                           |
+| --------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
+| `analytics.query`                                               | yes               | OBO-scoped, read-only SQL enforced at runtime via the classifier                    |
+| `files.list` / `files.read` / `files.exists` / `files.metadata` | yes               | OBO-scoped read operations                                                          |
+| `files.upload` / `files.delete`                                 | no                | Mutating — wire explicitly                                                          |
+| `genie.getConversation`                                         | yes               | Read-only history                                                                   |
+| `genie.sendMessage`                                             | no                | State-mutating Genie conversation                                                   |
+| `lakebase.query`                                                | no                | Already gated by `exposeAsAgentTool`; auto-inherit stays closed as defense-in-depth |
+
+Third-party `ToolProvider` plugins that don't expose a `toolkit()` method are also skipped from the auto-inherit path — their tools must be wired via `tools:` explicitly. At setup the agents plugin logs what each agent inherited and what was skipped so the posture is visible:
+
+```text
+[agents] [agent support] auto-inherited 2 tool(s): analytics.query, files.uploads.read
+[agents] [agent support] auto-inherit skipped 3 tool(s) not marked autoInheritable: files(2), genie(1). Wire them explicitly via `tools:` if needed.
+
+```
+
+### SQL agent tools[​](#sql-agent-tools "Direct link to SQL agent tools")
+
+Two built-in agent tools can execute SQL on behalf of the LLM: `analytics.query` (against the Databricks SQL warehouse) and the opt-in `lakebase.query` (against a Lakebase Postgres database). Both have distinct safety postures because they run with different privileges.
+
+**`analytics.query`** runs under the caller's OBO token (the end user's Databricks credentials). Its `readOnly: true` annotation is enforced at execution time — statements are tokenized and only `SELECT`, `WITH`, `SHOW`, `EXPLAIN`, `DESCRIBE`, and `DESC` are accepted. Writes, DDL, and stacked statements are rejected before the request reaches the warehouse:
+
+```ts
+// accepted
+analytics.query({ query: "SELECT * FROM main.sales.orders WHERE created_at > current_date() - 7" })
+
+// rejected at the plugin, never reaches the warehouse
+analytics.query({ query: "UPDATE main.sales.orders SET status = 'cancelled'" })
+analytics.query({ query: "SELECT 1; DROP TABLE main.sales.orders" })
+
+```
+
+**`lakebase.query`** is **not registered as an agent tool by default**. Enabling it is an explicit decision because the Lakebase pool is bound to the application's service principal: an agent with access to this tool can execute SQL as the SP regardless of which end user initiated the request. Opt in with an acknowledgement flag:
+
+```ts
+lakebase({
+  exposeAsAgentTool: {
+    iUnderstandRunsAsServicePrincipal: true,
+    readOnly: true, // default
+  },
+});
+
+```
+
+With `readOnly: true` (default), the same SQL classifier as `analytics.query` applies, and the accepted statement is additionally wrapped in `BEGIN READ ONLY; … ROLLBACK;` so the Postgres server rejects any write that slips past the classifier (e.g., a `SELECT` over a side-effecting function). The tool annotation is `{ effect: "read" }`.
+
+With `readOnly: false`, the tool accepts arbitrary SQL and is annotated `{ effect: "destructive" }`. The `destructive` effect triggers the human-in-the-loop approval gate (below) on every invocation.
+
+### Human-in-the-loop approval for mutating tools[​](#human-in-the-loop-approval-for-mutating-tools "Direct link to Human-in-the-loop approval for mutating tools")
+
+Any tool annotated with a mutating effect — `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean — requires explicit user approval before execution. Secure by default: set `approval.requireForDestructive: false` only for fully autonomous back-office agents running in single-user contexts.
+
+Flow:
+
+1. Before running the tool, the agents plugin emits an `appkit.approval_pending` SSE event carrying the pending call's `approval_id`, `stream_id`, `tool_name`, `args`, and `annotations`.
+
+2. The chat client renders an approval prompt (see the reference app's approval card).
+
+3. The same user who initiated the stream posts the decision to `POST /api/agent/approve`:
+
+   ```http
+   POST /api/agent/approve
+   Content-Type: application/json
+   X-Forwarded-User: <end-user id>
+   X-Forwarded-Access-Token: <OBO token>
+
+   { "streamId": "...", "approvalId": "...", "decision": "approve" | "deny" }
+
+   ```
+
+4. If approved, the tool executes normally and the stream continues. If denied, the adapter receives the string `"Tool execution denied by user approval gate (tool: <name>)."` as the tool output and the LLM can apologise / replan. If no decision arrives within `approval.timeoutMs` (default 60 s), the gate auto-denies.
+
+The route enforces that the decider is the stream owner: an approve from a different `x-forwarded-user` returns `403`. Cancelling the stream via `POST /api/agent/cancel` denies every pending approval on that stream.
+
+### Resource limits[​](#resource-limits "Direct link to Resource limits")
+
+The plugin enforces a handful of caps to protect a single-instance deployment from runaway prompts, misbehaving clients, or prompt-injected delegation cycles. Some are static (enforced by the request schema) and some are configurable via `agents({ limits: { ... } })`.
+
+**Static caps** (applied at `POST /chat` and `POST /invocations` request parsing):
+
+| Field                                | Cap               | Why                                                                           |
+| ------------------------------------ | ----------------- | ----------------------------------------------------------------------------- |
+| `chat.message`                       | 64 000 characters | \~16k tokens; larger bodies are almost certainly abuse.                       |
+| `invocations.input` string           | 64 000 characters | Same reasoning.                                                               |
+| `invocations.input` array            | 100 items         | Prevents a single request seeding hundreds of messages into the thread store. |
+| `invocations.input[].content` string | 64 000 characters | Per-seeded-message cap.                                                       |
+| `invocations.input[].content` array  | 100 items         | Per-seeded-message cap.                                                       |
+
+**Configurable caps** (defaults shown):
+
+```ts
+agents({
+  limits: {
+    maxConcurrentStreamsPerUser: 5,  // HTTP 429 + Retry-After when exceeded
+    maxToolCalls: 50,                // aborts the run if the budget is exhausted
+    maxSubAgentDepth: 3,             // rejects sub-agent recursion beyond this
+  },
+});
+
+```
+
+The `maxToolCalls` budget is shared across the top-level adapter and every sub-agent it delegates to, so a prompt-injected fan-out cannot escape by going deeper. `maxConcurrentStreamsPerUser` is per-user, not global — one user hitting their limit does not affect others.
+
+## Runtime API[​](#runtime-api "Direct link to Runtime API")
+
+After `createApp`, the plugin exposes:
+
+```ts
+appkit.agents.list();               // => ["support", "researcher", ...]
+appkit.agents.get("support");       // => RegisteredAgent | null
+appkit.agents.getDefault();         // => "support"
+appkit.agents.register(name, def);  // dynamic registration
+appkit.agents.reload();             // re-scan the directory
+appkit.agents.getThreads(userId);   // list user's threads
+
+```
+
+## Frontmatter schema[​](#frontmatter-schema "Direct link to Frontmatter schema")
+
+| Key                | Type            | Notes                                                                                                                                                                                                                                                                                           |
+| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `endpoint`         | string          | Model serving endpoint name. Shortcut for `model`.                                                                                                                                                                                                                                              |
+| `model`            | string          | Same as `endpoint`; either works.                                                                                                                                                                                                                                                               |
+| `tools`            | array           | Unified tool list. Entries are `plugin:<name>` / `plugin:<name>: [t1, t2]` / `plugin:<name>: { only, except, rename, prefix }` for plugin tools, or a bare `<key>` resolved against `agents({ tools: {...} })` for ambient tools. See "Level 2: scope tools in frontmatter" above for examples. |
+| `default`          | boolean         | First agent id (sorted order) with `default: true` becomes the default agent.                                                                                                                                                                                                                   |
+| `maxSteps`         | number          | Adapter max-step hint.                                                                                                                                                                                                                                                                          |
+| `maxTokens`        | number          | Adapter max-token hint.                                                                                                                                                                                                                                                                         |
+| `baseSystemPrompt` | false \| string | Per-agent override. `false` disables the AppKit base prompt.                                                                                                                                                                                                                                    |
+| `ephemeral`        | boolean         | If `true`, the thread created for a chat request against this agent is deleted from `ThreadStore` after the stream finishes. Use for stateless one-shot agents (e.g. autocomplete) so history does not accumulate or contaminate future calls. Defaults to `false`.                             |
+
+Unknown keys are logged and ignored. Invalid YAML and missing plugin/tool references throw at boot.

package/docs/privacy.md

@@ -0,0 +1,41 @@
+# Privacy
+
+AppKit sends a small amount of anonymized usage telemetry to Databricks so the team can understand how the SDK is used and prioritize improvements. This page documents exactly what is sent, when, and how to turn it off.
+
+## What we collect[​](#what-we-collect "Direct link to What we collect")
+
+Every event is a single record with three top-level fields:
+
+| Field            | Type   | Source                                               |
+| ---------------- | ------ | ---------------------------------------------------- |
+| `event_name`     | enum   | One of `APP_STARTUP`, `HEARTBEAT`, `REQUEST_METRICS` |
+| `app_id`         | string | The app's OAuth client UUID (`DATABRICKS_CLIENT_ID`) |
+| `appkit_version` | string | The AppKit SDK version                               |
+
+Each event also carries one of three event-specific bodies:
+
+* **`APP_STARTUP`** — emitted once when `createApp` finishes booting. Empty body.
+
+* **`HEARTBEAT`** — emitted every five minutes from a running app. Empty body.
+
+* **`REQUEST_METRICS`** — emitted once per minute, one record per HTTP endpoint that received traffic in the window. Each record contains:
+
+  <!-- -->
+
+  * `endpoint` — the route template (e.g. `GET /api/genie/:space_id/messages`), never the raw request URL or any user-provided values.
+  * `request_count`
+  * `request_latency_ms_avg`
+  * `response_count_http4xx`
+  * `response_count_http5xx`
+
+## How to opt out[​](#how-to-opt-out "Direct link to How to opt out")
+
+Set any one of the following:
+
+```sh
+DISABLE_APPKIT_INTERNAL_TELEMETRY=true
+DO_NOT_TRACK=1
+
+```
+
+Either fully disables the reporter — no events are emitted and no network calls are made.

package/llms.txt

@@ -29,6 +29,7 @@ npx @databricks/appkit docs <query>
 - [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with Agent Skills, and remote tunneling to deployed backends.
 - [FAQ](./docs/faq.md): Integrations
 - [Plugins](./docs/plugins.md): Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming.
+- [Privacy](./docs/privacy.md): AppKit sends a small amount of anonymized usage telemetry to Databricks
 
 ## Development
 
@@ -42,6 +43,7 @@ npx @databricks/appkit docs <query>
 
 ## Plugins
 
+- [Agents](./docs/plugins/agents.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
 - [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
@@ -58,11 +60,13 @@ npx @databricks/appkit docs <query>
 
 ## appkit API reference [collapsed]
 
-- [@databricks/appkit](./docs/api/appkit.md): Core library for building Databricks applications with type-safe SQL queries,
+- [@databricks/appkit](./docs/api/appkit.md): Documentation merge entry for Typedoc — combines the stable @databricks/appkit
 - [Abstract Class: AppKitError](./docs/api/appkit/Class.AppKitError.md): Base error class for all AppKit errors.
+- [Class: AppKitMcpClient](./docs/api/appkit/Class.AppKitMcpClient.md): Lightweight MCP client for Databricks-hosted MCP servers.
 - [Class: AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md): Error thrown when authentication fails.
 - [Class: ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md): Error thrown when configuration is missing or invalid.
 - [Class: ConnectionError](./docs/api/appkit/Class.ConnectionError.md): Error thrown when a connection or network operation fails.
+- [Class: DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md): Adapter that talks directly to Databricks Model Serving /invocations endpoint.
 - [Class: ExecutionError](./docs/api/appkit/Class.ExecutionError.md): Error thrown when an operation execution fails.
 - [Class: InitializationError](./docs/api/appkit/Class.InitializationError.md): Error thrown when a service or component is not properly initialized.
 - [Abstract Class: Plugin<TConfig>](./docs/api/appkit/Class.Plugin.md): Base abstract class for creating AppKit plugins.
@@ -73,12 +77,17 @@ npx @databricks/appkit docs <query>
 - [Class: ValidationError](./docs/api/appkit/Class.ValidationError.md): Error thrown when input validation fails.
 - [Enumeration: RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md): Permission set for Unity Catalog table access
 - [Enumeration: ResourceType](./docs/api/appkit/Enumeration.ResourceType.md): Resource types from schema $defs.resourceType.enum
+- [Function: agentIdFromMarkdownPath()](./docs/api/appkit/Function.agentIdFromMarkdownPath.md): Derives the logical agent id from a markdown path. When the file is named
 - [Function: appKitServingTypesPlugin()](./docs/api/appkit/Function.appKitServingTypesPlugin.md): Vite plugin to generate TypeScript types for AppKit serving endpoints.
 - [Function: appKitTypesPlugin()](./docs/api/appkit/Function.appKitTypesPlugin.md): Vite plugin to generate types for AppKit queries.
+- [Function: createAgent()](./docs/api/appkit/Function.createAgent.md): Pure factory for agent definitions. Returns the passed-in definition after
 - [Function: createApp()](./docs/api/appkit/Function.createApp.md): Bootstraps AppKit with the provided configuration.
 - [Function: createLakebasePool()](./docs/api/appkit/Function.createLakebasePool.md): Create a Lakebase pool with appkit's logger integration.
+- [Function: defineTool()](./docs/api/appkit/Function.defineTool.md): Defines a single tool entry for a plugin's internal registry.
+- [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
 - [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
 - [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
+- [Function: functionToolToDefinition()](./docs/api/appkit/Function.functionToolToDefinition.md): Parameters
 - [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
 - [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
 - [Function: getLakebaseOrmConfig()](./docs/api/appkit/Function.getLakebaseOrmConfig.md): Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
@@ -87,13 +96,32 @@ npx @databricks/appkit docs <query>
 - [Function: getResourceRequirements()](./docs/api/appkit/Function.getResourceRequirements.md): Gets the resource requirements from a plugin's manifest.
 - [Function: getUsernameWithApiLookup()](./docs/api/appkit/Function.getUsernameWithApiLookup.md): Resolves the PostgreSQL username for a Lakebase connection.
 - [Function: getWorkspaceClient()](./docs/api/appkit/Function.getWorkspaceClient.md): Get workspace client from config or SDK default auth chain
+- [Function: isFunctionTool()](./docs/api/appkit/Function.isFunctionTool.md): Parameters
+- [Function: isHostedTool()](./docs/api/appkit/Function.isHostedTool.md): Parameters
 - [Function: isSQLTypeMarker()](./docs/api/appkit/Function.isSQLTypeMarker.md): Type guard to check if a value is a SQL type marker
+- [Function: isToolkitEntry()](./docs/api/appkit/Function.isToolkitEntry.md): Type guard for ToolkitEntry — used by the agents plugin to differentiate
+- [Function: loadAgentFromFile()](./docs/api/appkit/Function.loadAgentFromFile.md): Loads a single markdown agent file and resolves its frontmatter against
+- [Function: loadAgentsFromDir()](./docs/api/appkit/Function.loadAgentsFromDir.md): Scans a directory for one subdirectory per agent, each containing
+- [Function: mcpServer()](./docs/api/appkit/Function.mcpServer.md): Factory for declaring a custom MCP server tool.
+- [Function: parseTextToolCalls()](./docs/api/appkit/Function.parseTextToolCalls.md): Parses text-based tool calls from model output.
+- [Function: resolveHostedTools()](./docs/api/appkit/Function.resolveHostedTools.md): Parameters
+- [Function: runAgent()](./docs/api/appkit/Function.runAgent.md): Standalone agent execution without createApp. Resolves the adapter, binds
+- [Function: tool()](./docs/api/appkit/Function.tool.md): Factory for defining function tools with Zod schemas.
+- [Function: toolsFromRegistry()](./docs/api/appkit/Function.toolsFromRegistry.md): Produces the AgentToolDefinition[] a ToolProvider exposes to the LLM,
+- [Interface: AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md): Methods
+- [Interface: AgentDefinition](./docs/api/appkit/Interface.AgentDefinition.md): Properties
+- [Interface: AgentInput](./docs/api/appkit/Interface.AgentInput.md): Properties
+- [Interface: AgentRunContext](./docs/api/appkit/Interface.AgentRunContext.md): Properties
+- [Interface: AgentsPluginConfig](./docs/api/appkit/Interface.AgentsPluginConfig.md): Base configuration interface for AppKit plugins
+- [Interface: AgentToolDefinition](./docs/api/appkit/Interface.AgentToolDefinition.md): Properties
+- [Interface: AutoInheritToolsConfig](./docs/api/appkit/Interface.AutoInheritToolsConfig.md): Auto-inherit configuration. When enabled for a given agent origin, agents
 - [Interface: BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md): Base configuration interface for AppKit plugins
 - [Interface: CacheConfig](./docs/api/appkit/Interface.CacheConfig.md): Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
 - [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
 - [Interface: EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md): Properties
 - [Interface: FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md): Minimal user identity passed to the policy function.
 - [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
+- [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
@@ -101,28 +129,53 @@ npx @databricks/appkit docs <query>
 - [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
 - [Interface: JobsConnectorConfig](./docs/api/appkit/Interface.JobsConnectorConfig.md): Properties
 - [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
+- [Interface: McpConnectAllResult](./docs/api/appkit/Interface.McpConnectAllResult.md): Per-endpoint outcome of AppKitMcpClient.connectAll. Callers (the
+- [Interface: Message](./docs/api/appkit/Interface.Message.md): Properties
 - [Interface: PluginManifest<TName>](./docs/api/appkit/Interface.PluginManifest.md): Plugin manifest that declares metadata and resource requirements.
+- [Interface: PluginToolkitProvider](./docs/api/appkit/Interface.PluginToolkitProvider.md): Minimum shape every entry in the Plugins map must expose. Core
+- [Interface: PromptContext](./docs/api/appkit/Interface.PromptContext.md): Context passed to baseSystemPrompt callbacks.
+- [Interface: RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md): Properties
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
 - [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
 - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
 - [Interface: ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md): Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instancename, databasename or scope, key).
 - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
+- [Interface: RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md): Properties
+- [Interface: RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md): Properties
 - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
 - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
 - [Interface: TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md): OpenTelemetry configuration for AppKit applications
+- [Interface: Thread](./docs/api/appkit/Interface.Thread.md): Properties
+- [Interface: ThreadStore](./docs/api/appkit/Interface.ThreadStore.md): Methods
+- [Interface: ToolAnnotations](./docs/api/appkit/Interface.ToolAnnotations.md): Properties
+- [Interface: ToolConfig<S>](./docs/api/appkit/Interface.ToolConfig.md): Type Parameters
+- [Interface: ToolEntry<S>](./docs/api/appkit/Interface.ToolEntry.md): Single-tool entry for a plugin's internal tool registry.
+- [Interface: ToolkitEntry](./docs/api/appkit/Interface.ToolkitEntry.md): A tool reference produced by a plugin's .toolkit() call. The agents plugin
+- [Interface: ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md): Properties
+- [Interface: ToolProvider](./docs/api/appkit/Interface.ToolProvider.md): Methods
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
+- [Type Alias: AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md): Type Declaration
+- [Type Alias: AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md): Any tool an agent can invoke: inline function tools (tool()), hosted MCP
+- [Type Alias: AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md): Per-agent tool record. String keys map to inline tools, toolkit entries,
+- [Type Alias: AgentToolsFn()](./docs/api/appkit/TypeAlias.AgentToolsFn.md): Function form of AgentDefinition.tools. Receives the typed
+- [Type Alias: BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md)
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
 - [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
 - [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
 - [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on
+- [Type Alias: HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md)
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
 - [Type Alias: JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md): Job handle returned by appkit.jobs("etl").
 - [Type Alias: JobsExport()](./docs/api/appkit/TypeAlias.JobsExport.md): Public API shape of the jobs plugin.
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
+- [Type Alias: Plugins](./docs/api/appkit/TypeAlias.Plugins.md): Plugin map passed to the function form of AgentDefinition.tools.
+- [Type Alias: ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md): Internal tool-index entry after a tool record has been resolved to a dispatchable form.
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
+- [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
+- [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
 - [Variable: WRITE_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md): Actions that mutate data.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",