@databricks/appkit-ui 0.32.0 → 0.33.0

package/docs/api/appkit/Function.loadAgentFromFile.md

@@ -0,0 +1,21 @@
+# Function: loadAgentFromFile()
+
+```ts
+function loadAgentFromFile(filePath: string, ctx: LoadContext): Promise<AgentDefinition>;
+
+```
+
+Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library.
+
+Rejects non-empty `agents:` frontmatter because single-file loads have no siblings to resolve sub-agent references against — callers must use [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md) when markdown agents delegate to one another.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type          |
+| ---------- | ------------- |
+| `filePath` | `string`      |
+| `ctx`      | `LoadContext` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`AgentDefinition`](./docs/api/appkit/Interface.AgentDefinition.md)>

package/docs/api/appkit/Function.loadAgentsFromDir.md

@@ -0,0 +1,26 @@
+# Function: loadAgentsFromDir()
+
+```ts
+function loadAgentsFromDir(dir: string, ctx: LoadContext): Promise<LoadResult>;
+
+```
+
+Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist.
+
+Legacy top-level `*.md` files are rejected with an error — migrate each to `<id>/agent.md` under a sibling folder named for the agent id.
+
+Runs in two passes so sub-agent references in frontmatter (`agents: [...]`) can be resolved regardless of directory iteration order:
+
+1. Build every agent's definition from its own `agent.md`.
+2. Walk `agents:` references and wire `def.agents = { child: childDef }` by looking them up in the complete map. Dangling names and self-references fail loudly; mutual delegation is allowed and bounded at runtime by `limits.maxSubAgentDepth`.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `dir`     | `string`      |
+| `ctx`     | `LoadContext` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`LoadResult`>

package/docs/api/appkit/Function.mcpServer.md

@@ -0,0 +1,28 @@
+# Function: mcpServer()
+
+```ts
+function mcpServer(name: string, url: string): CustomMcpServerTool;
+
+```
+
+Factory for declaring a custom MCP server tool.
+
+Replaces the verbose `{ type: "custom_mcp_server", custom_mcp_server: { app_name, app_url } }` wrapper with a concise positional call.
+
+Example:
+
+```ts
+mcpServer("my-app", "https://my-app.databricksapps.com/mcp")
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `name`    | `string` |
+| `url`     | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`CustomMcpServerTool`

package/docs/api/appkit/Function.parseTextToolCalls.md

@@ -0,0 +1,26 @@
+# Function: parseTextToolCalls()
+
+```ts
+function parseTextToolCalls(text: string): {
+  args: unknown;
+  name: string;
+}[];
+
+```
+
+Parses text-based tool calls from model output.
+
+Handles two formats:
+
+1. Llama native: `[{"name": "tool_name", "parameters": {"arg": "val"}}]`
+2. Python-style: `[tool_name(arg1='val1', arg2='val2')]`
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `text`    | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+{ `args`: `unknown`; `name`: `string`; }\[]

package/docs/api/appkit/Function.resolveHostedTools.md

@@ -0,0 +1,16 @@
+# Function: resolveHostedTools()
+
+```ts
+function resolveHostedTools(tools: HostedTool[]): McpEndpointConfig[];
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `tools`   | [`HostedTool`](./docs/api/appkit/TypeAlias.HostedTool.md)\[] |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`McpEndpointConfig`\[]

package/docs/api/appkit/Function.runAgent.md

@@ -0,0 +1,26 @@
+# Function: runAgent()
+
+```ts
+function runAgent(def: AgentDefinition, input: RunAgentInput): Promise<RunAgentResult>;
+
+```
+
+Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion.
+
+Limitations vs. running through the agents() plugin:
+
+* **No OBO and no approval gate** — there is no HTTP request, so plugin tools run as the service principal. The agents-plugin approval gate that prompts for human confirmation on `effect: "write" | "update" | "destructive"` tools is also absent. LLM-controlled tool arguments flow straight through to the SP. Treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts) — not as an exposed user-facing surface.
+* **Hosted tools (MCP) are not supported** — they require a live MCP client that only exists inside the agents plugin's lifecycle. `runAgent` rejects them at index-build time with a clear error.
+* **Sub-agents** (`agents: { ... }` on the def) are executed as nested `runAgent` calls with no shared thread state. Plugin instances ARE shared across the recursion (same cache as the parent).
+* **Plugin tools** (used inside the function form via `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via `RunAgentInput`. Each plugin in that array is constructed once, `attachContext({})` and `await setup()` are called eagerly, and the resulting instance is shared across the top-level run and all sub-agent recursions. Plugins whose `setup()` requires runtime that only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`, `PluginContext`) throw at standalone-init time with a clear "use createApp instead" message — not mid-stream.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `def`     | [`AgentDefinition`](./docs/api/appkit/Interface.AgentDefinition.md) |
+| `input`   | [`RunAgentInput`](./docs/api/appkit/Interface.RunAgentInput.md)     |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`RunAgentResult`](./docs/api/appkit/Interface.RunAgentResult.md)>

package/docs/api/appkit/Function.tool.md

@@ -0,0 +1,28 @@
+# Function: tool()
+
+```ts
+function tool<S>(config: ToolConfig<S>): FunctionTool;
+
+```
+
+Factory for defining function tools with Zod schemas.
+
+* Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.
+* Infers the `execute` argument type from the schema.
+* Validates tool call arguments at runtime. On validation failure, returns a formatted error string to the LLM instead of throwing, so the model can self-correct on its next turn.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                                                                           |
+| ---------------------------------------------------------------------------------------- |
+| `S` *extends* `ZodType`<`unknown`, `unknown`, `$ZodTypeInternals`<`unknown`, `unknown`>> |
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `config`  | [`ToolConfig`](./docs/api/appkit/Interface.ToolConfig.md)<`S`> |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`FunctionTool`](./docs/api/appkit/Interface.FunctionTool.md)

package/docs/api/appkit/Function.toolsFromRegistry.md

@@ -0,0 +1,20 @@
+# Function: toolsFromRegistry()
+
+```ts
+function toolsFromRegistry(registry: ToolRegistry): AgentToolDefinition[];
+
+```
+
+Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema.
+
+Tool names come from registry keys (supports dotted names like `uploads.list` for dynamic plugins).
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                                                                |
+| ---------- | ------------------------------------------------------------------- |
+| `registry` | [`ToolRegistry`](./docs/api/appkit/TypeAlias.ToolRegistry.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`AgentToolDefinition`](./docs/api/appkit/Interface.AgentToolDefinition.md)\[]

package/docs/api/appkit/Interface.AgentAdapter.md

@@ -0,0 +1,21 @@
+# Interface: AgentAdapter
+
+## Methods[​](#methods "Direct link to Methods")
+
+### run()[​](#run "Direct link to run()")
+
+```ts
+run(input: AgentInput, context: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `input`   | [`AgentInput`](./docs/api/appkit/Interface.AgentInput.md)           |
+| `context` | [`AgentRunContext`](./docs/api/appkit/Interface.AgentRunContext.md) |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`AsyncGenerator`<[`AgentEvent`](./docs/api/appkit/TypeAlias.AgentEvent.md), `void`, `unknown`>

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -0,0 +1,112 @@
+# Interface: AgentDefinition
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agents?[​](#agents "Direct link to agents?")
+
+```ts
+optional agents: Record<string, AgentDefinition>;
+
+```
+
+Sub-agents, exposed as `agent-<key>` tools on this agent.
+
+***
+
+### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
+
+```ts
+optional baseSystemPrompt: BaseSystemPromptOption;
+
+```
+
+Override the plugin's baseSystemPrompt for this agent only.
+
+***
+
+### ephemeral?[​](#ephemeral "Direct link to ephemeral?")
+
+```ts
+optional ephemeral: boolean;
+
+```
+
+When true, the thread used for a chat request against this agent is deleted from `ThreadStore` after the stream completes (success or failure). Use for stateless one-shot agents — e.g. autocomplete, where each request is independent and retaining history would both poison future calls and accumulate unbounded state in the default `InMemoryThreadStore`. Defaults to `false`.
+
+***
+
+### instructions[​](#instructions "Direct link to instructions")
+
+```ts
+instructions: string;
+
+```
+
+System prompt body. For markdown-loaded agents this is the file body.
+
+***
+
+### maxSteps?[​](#maxsteps "Direct link to maxSteps?")
+
+```ts
+optional maxSteps: number;
+
+```
+
+***
+
+### maxTokens?[​](#maxtokens "Direct link to maxTokens?")
+
+```ts
+optional maxTokens: number;
+
+```
+
+***
+
+### model?[​](#model "Direct link to model?")
+
+```ts
+optional model: 
+  | string
+  | AgentAdapter
+| Promise<AgentAdapter>;
+
+```
+
+Model adapter (or endpoint-name string sugar for `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional — falls back to the plugin's `defaultModel`.
+
+***
+
+### name?[​](#name "Direct link to name?")
+
+```ts
+optional name: string;
+
+```
+
+Stable identifier for the agent. **Optional and informational** — when the definition is registered via `agents: { foo: def }` (code) or lives at `config/agents/<id>/agent.md` (markdown), the **registry key always wins** and `name` is ignored. The agent will be reachable as `foo` (or `<id>`) regardless of what this field contains.
+
+Set `name` when:
+
+* Running standalone via `runAgent({ agent: def })`, where there is no enclosing key. The runtime uses it for the agent's slot in error messages and OTel spans.
+* Building a definition that may be passed to either form and you want a consistent fallback label.
+
+Setting `name` to a value that differs from the registry key is harmless but confusing — prefer keeping them aligned or omitting `name` entirely.
+
+***
+
+### tools?[​](#tools "Direct link to tools?")
+
+```ts
+optional tools: 
+  | AgentTools
+  | AgentToolsFn;
+
+```
+
+Per-agent tool record. Key is the LLM-visible tool-call name.
+
+Accepts either a plain record (for agents that only use inline tools) or a function `(plugins) => Record<string, AgentTool>` that receives the typed [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map and returns a tool record (for agents that pull tools from registered plugins).
+
+The function is invoked once at agent setup; the result is cached. Don't put per-request logic in there.

package/docs/api/appkit/Interface.AgentInput.md

@@ -0,0 +1,37 @@
+# Interface: AgentInput
+
+## Properties[​](#properties "Direct link to Properties")
+
+### messages[​](#messages "Direct link to messages")
+
+```ts
+messages: Message[];
+
+```
+
+***
+
+### signal?[​](#signal "Direct link to signal?")
+
+```ts
+optional signal: AbortSignal;
+
+```
+
+***
+
+### threadId[​](#threadid "Direct link to threadId")
+
+```ts
+threadId: string;
+
+```
+
+***
+
+### tools[​](#tools "Direct link to tools")
+
+```ts
+tools: AgentToolDefinition[];
+
+```

package/docs/api/appkit/Interface.AgentRunContext.md

@@ -0,0 +1,32 @@
+# Interface: AgentRunContext
+
+## Properties[​](#properties "Direct link to Properties")
+
+### executeTool()[​](#executetool "Direct link to executeTool()")
+
+```ts
+executeTool: (name: string, args: unknown) => Promise<unknown>;
+
+```
+
+Tool implementations should sanitize failure text — errors become `tool_result.error` and can flow back into the LLM transcript.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type      |
+| --------- | --------- |
+| `name`    | `string`  |
+| `args`    | `unknown` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`unknown`>
+
+***
+
+### signal?[​](#signal "Direct link to signal?")
+
+```ts
+optional signal: AbortSignal;
+
+```

package/docs/api/appkit/Interface.AgentToolDefinition.md

@@ -0,0 +1,37 @@
+# Interface: AgentToolDefinition
+
+## Properties[​](#properties "Direct link to Properties")
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+***
+
+### description[​](#description "Direct link to description")
+
+```ts
+description: string;
+
+```
+
+***
+
+### name[​](#name "Direct link to name")
+
+```ts
+name: string;
+
+```
+
+***
+
+### parameters[​](#parameters "Direct link to parameters")
+
+```ts
+parameters: JSONSchema7;
+
+```

package/docs/api/appkit/Interface.AgentsPluginConfig.md

@@ -0,0 +1,241 @@
+# Interface: AgentsPluginConfig
+
+Base configuration interface for AppKit plugins
+
+## Extends[​](#extends "Direct link to Extends")
+
+* [`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md)
+
+## Indexable[​](#indexable "Direct link to Indexable")
+
+```ts
+[key: string]: unknown
+
+```
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agents?[​](#agents "Direct link to agents?")
+
+```ts
+optional agents: Record<string, AgentDefinition>;
+
+```
+
+Code-defined agents, merged with file-loaded ones (code wins on key collision).
+
+***
+
+### approval?[​](#approval "Direct link to approval?")
+
+```ts
+optional approval: {
+  requireForDestructive?: boolean;
+  timeoutMs?: number;
+};
+
+```
+
+Human-in-the-loop approval gate for mutating tool calls. When enabled (the default), the agents plugin emits an `appkit.approval_pending` SSE event before executing any tool whose annotation flags it as mutating — `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean — and waits for a `POST /chat/approve` decision from the same user who initiated the stream. A missing decision after `timeoutMs` auto-denies the call.
+
+#### requireForDestructive?[​](#requirefordestructive "Direct link to requireForDestructive?")
+
+```ts
+optional requireForDestructive: boolean;
+
+```
+
+Require human approval for tools that mutate state. Triggered by `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean. Default: `true`.
+
+#### timeoutMs?[​](#timeoutms "Direct link to timeoutMs?")
+
+```ts
+optional timeoutMs: number;
+
+```
+
+Milliseconds to wait before auto-denying. Default: 60\_000.
+
+***
+
+### autoInheritTools?[​](#autoinherittools "Direct link to autoInheritTools?")
+
+```ts
+optional autoInheritTools: 
+  | boolean
+  | AutoInheritToolsConfig;
+
+```
+
+Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand.
+
+***
+
+### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
+
+```ts
+optional baseSystemPrompt: BaseSystemPromptOption;
+
+```
+
+Customize or disable the AppKit base system prompt.
+
+***
+
+### defaultAgent?[​](#defaultagent "Direct link to defaultAgent?")
+
+```ts
+optional defaultAgent: string;
+
+```
+
+Agent used when clients don't specify one. Defaults to the first-registered agent or the file with `default: true` frontmatter.
+
+***
+
+### defaultModel?[​](#defaultmodel "Direct link to defaultModel?")
+
+```ts
+optional defaultModel: 
+  | string
+  | AgentAdapter
+| Promise<AgentAdapter>;
+
+```
+
+Default model for agents that don't specify their own (in code or frontmatter).
+
+***
+
+### dir?[​](#dir "Direct link to dir?")
+
+```ts
+optional dir: string | false;
+
+```
+
+Directory of agent packages (`<id>/agent.md` each). Default `./config/agents`. Set to `false` to disable.
+
+***
+
+### host?[​](#host "Direct link to host?")
+
+```ts
+optional host: string;
+
+```
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+[`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md).[`host`](./docs/api/appkit/Interface.BasePluginConfig.md#host)
+
+***
+
+### limits?[​](#limits "Direct link to limits?")
+
+```ts
+optional limits: {
+  maxConcurrentStreamsPerUser?: number;
+  maxSubAgentDepth?: number;
+  maxToolCalls?: number;
+  toolCallTimeoutMs?: number;
+};
+
+```
+
+Runtime resource limits applied during agent execution. Defaults are tuned to protect a single-instance deployment from a misbehaving user or a runaway prompt injection; tighten or relax as appropriate for the deployment's scale and trust model. Request-body caps (chat message size, invocations input size / length) are enforced statically by the Zod schemas and are not configurable here.
+
+#### maxConcurrentStreamsPerUser?[​](#maxconcurrentstreamsperuser "Direct link to maxConcurrentStreamsPerUser?")
+
+```ts
+optional maxConcurrentStreamsPerUser: number;
+
+```
+
+Max concurrent chat streams a single user may have open. Subsequent `POST /chat` requests from that user while at-limit are rejected with HTTP 429. Default: `5`.
+
+#### maxSubAgentDepth?[​](#maxsubagentdepth "Direct link to maxSubAgentDepth?")
+
+```ts
+optional maxSubAgentDepth: number;
+
+```
+
+Max sub-agent recursion depth. Protects against a prompt-injected agent that delegates to a sub-agent which in turn delegates back to itself (directly or transitively). Default: `3`.
+
+#### maxToolCalls?[​](#maxtoolcalls "Direct link to maxToolCalls?")
+
+```ts
+optional maxToolCalls: number;
+
+```
+
+Max tool invocations per agent run (across the full tool-call graph, including sub-agent invocations). A run that exceeds the budget is aborted with a terminal error event. Default: `50`.
+
+#### toolCallTimeoutMs?[​](#toolcalltimeoutms "Direct link to toolCallTimeoutMs?")
+
+```ts
+optional toolCallTimeoutMs: number;
+
+```
+
+Per-call timeout for tools dispatched through `PluginContext` (toolkit-routed tools — analytics SQL warehouse queries, Genie messages, Lakebase queries). Independent of `maxToolCalls`: the budget caps how many tools fire per run, this caps how long any single tool call may run. The signal handed to plugin tool implementations combines this timeout with the parent stream's abort signal via `AbortSignal.any`. Function and MCP tools have their own timeouts in their respective adapters and ignore this setting. Default: `300_000` (5 minutes) — generous enough for cold SQL Warehouse round-trips and long Genie conversations.
+
+***
+
+### mcp?[​](#mcp "Direct link to mcp?")
+
+```ts
+optional mcp: McpHostPolicyConfig;
+
+```
+
+MCP server host policy. By default only same-origin Databricks workspace URLs may be used as MCP endpoints; custom hosts must be explicitly allowlisted here. Workspace credentials (SP / OBO) are never forwarded to non-workspace hosts.
+
+***
+
+### name?[​](#name "Direct link to name?")
+
+```ts
+optional name: string;
+
+```
+
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+[`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md).[`name`](./docs/api/appkit/Interface.BasePluginConfig.md#name)
+
+***
+
+### telemetry?[​](#telemetry "Direct link to telemetry?")
+
+```ts
+optional telemetry: TelemetryOptions;
+
+```
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+[`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md).[`telemetry`](./docs/api/appkit/Interface.BasePluginConfig.md#telemetry)
+
+***
+
+### threadStore?[​](#threadstore "Direct link to threadStore?")
+
+```ts
+optional threadStore: ThreadStore;
+
+```
+
+Persistent thread store. Default: in-memory.
+
+***
+
+### tools?[​](#tools "Direct link to tools?")
+
+```ts
+optional tools: Record<string, AgentTool>;
+
+```
+
+Ambient tool library. Keys may be referenced by markdown frontmatter via `tools: [key1, key2]`.