@databricks/appkit-ui 0.32.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/llms.txt

@@ -43,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:
@@ -59,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.
@@ -74,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.
@@ -88,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.
@@ -102,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.32.0",
+  "version": "0.33.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",