@databricks/appkit-ui 0.32.0 → 0.33.0

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

@@ -0,0 +1,73 @@
+# Interface: ToolEntry\<S>
+
+Single-tool entry for a plugin's internal tool registry.
+
+Plugins collect these into a `Record<string, ToolEntry>` keyed by the tool's public name and dispatch via `executeFromRegistry`.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter            | Default type |
+| ------------------------- | ------------ |
+| `S` *extends* `z.ZodType` | `z.ZodType`  |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+***
+
+### autoInheritable?[​](#autoinheritable "Direct link to autoInheritable?")
+
+```ts
+optional autoInheritable: boolean;
+
+```
+
+Whether this tool is eligible for auto-inheritance into markdown or code-defined agents that enable `autoInheritTools`. Defaults to `false` (safe-by-default) — plugin authors must explicitly opt a tool in if they consider it safe enough to appear in every agent's tool record without an explicit `tools:` declaration. Destructive or privilege-sensitive tools should leave this unset so that they only reach agents that wire them explicitly (via `tools:` object/function form, markdown `plugin:NAME` entries in the unified `tools:` list, or `plugins.<name>.toolkit({ only: [...] })`).
+
+***
+
+### description[​](#description "Direct link to description")
+
+```ts
+description: string;
+
+```
+
+***
+
+### execute()[​](#execute "Direct link to execute()")
+
+```ts
+execute: (args: output<S>, signal?: AbortSignal) => unknown;
+
+```
+
+Callback the agents plugin invokes after Zod validation succeeds.
+
+Named `execute` to match the public `tool({ execute })` form — both the agent-author surface and the plugin-author surface now spell their callback the same way. `args` is the inferred Zod output (so `T extends z.ZodType` flows through and `args` is fully typed). `signal` is the per-run AbortSignal: forward it to any awaited I/O so cancellation actually unwinds the call (analytics and lakebase both do this).
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `args`    | `output`<`S`> |
+| `signal?` | `AbortSignal` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`unknown`
+
+***
+
+### schema[​](#schema "Direct link to schema")
+
+```ts
+schema: S;
+
+```

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

@@ -0,0 +1,38 @@
+# Interface: ToolProvider
+
+## Methods[​](#methods "Direct link to Methods")
+
+### executeAgentTool()[​](#executeagenttool "Direct link to executeAgentTool()")
+
+```ts
+executeAgentTool(
+   name: string, 
+   args: unknown, 
+signal?: AbortSignal): Promise<unknown>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `name`    | `string`      |
+| `args`    | `unknown`     |
+| `signal?` | `AbortSignal` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`unknown`>
+
+***
+
+### getAgentTools()[​](#getagenttools "Direct link to getAgentTools()")
+
+```ts
+getAgentTools(): AgentToolDefinition[];
+
+```
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+[`AgentToolDefinition`](./docs/api/appkit/Interface.AgentToolDefinition.md)\[]

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

@@ -0,0 +1,59 @@
+# Interface: ToolkitEntry
+
+A tool reference produced by a plugin's `.toolkit()` call. The agents plugin recognizes the `__toolkitRef` brand and dispatches tool invocations through `PluginContext.executeTool(req, pluginName, localName, ...)`, preserving OBO (asUser) and telemetry spans.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### \_\_toolkitRef[​](#__toolkitref "Direct link to __toolkitRef")
+
+```ts
+readonly __toolkitRef: true;
+
+```
+
+***
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+***
+
+### autoInheritable?[​](#autoinheritable "Direct link to autoInheritable?")
+
+```ts
+optional autoInheritable: boolean;
+
+```
+
+Whether this tool is eligible for `autoInheritTools` spreading. Mirrors [ToolEntry.autoInheritable](./docs/api/appkit/Interface.ToolEntry.md#autoinheritable) from the source registry so the agents plugin can filter auto-inherited tools without re-walking the provider's internal registry.
+
+***
+
+### def[​](#def "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+***
+
+### localName[​](#localname "Direct link to localName")
+
+```ts
+localName: string;
+
+```
+
+***
+
+### pluginName[​](#pluginname "Direct link to pluginName")
+
+```ts
+pluginName: string;
+
+```

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

@@ -0,0 +1,45 @@
+# Interface: ToolkitOptions
+
+## Properties[​](#properties "Direct link to Properties")
+
+### except?[​](#except "Direct link to except?")
+
+```ts
+optional except: string[];
+
+```
+
+Exclude tools whose local name matches one of these.
+
+***
+
+### only?[​](#only "Direct link to only?")
+
+```ts
+optional only: string[];
+
+```
+
+Only include tools whose local name matches one of these.
+
+***
+
+### prefix?[​](#prefix "Direct link to prefix?")
+
+```ts
+optional prefix: string;
+
+```
+
+Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`.
+
+***
+
+### rename?[​](#rename "Direct link to rename?")
+
+```ts
+optional rename: Record<string, string>;
+
+```
+
+Remap specific local names to different keys (applied after prefix).

package/docs/api/appkit/TypeAlias.AgentEvent.md

@@ -0,0 +1,299 @@
+# Type Alias: AgentEvent
+
+```ts
+type AgentEvent = 
+  | {
+  content: string;
+  type: "message_delta";
+}
+  | {
+  content: string;
+  type: "message";
+}
+  | {
+  args: unknown;
+  callId: string;
+  name: string;
+  type: "tool_call";
+}
+  | {
+  callId: string;
+  error?: string;
+  result: unknown;
+  type: "tool_result";
+}
+  | {
+  content: string;
+  type: "thinking";
+}
+  | {
+  error?: string;
+  status: "running" | "waiting" | "complete" | "error";
+  type: "status";
+}
+  | {
+  data: Record<string, unknown>;
+  type: "metadata";
+}
+  | {
+  annotations?: ToolAnnotations;
+  approvalId: string;
+  args: unknown;
+  streamId: string;
+  toolName: string;
+  type: "approval_pending";
+};
+
+```
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+```ts
+{
+  content: string;
+  type: "message_delta";
+}
+
+```
+
+### content[​](#content "Direct link to content")
+
+```ts
+content: string;
+
+```
+
+### type[​](#type "Direct link to type")
+
+```ts
+type: "message_delta";
+
+```
+
+```ts
+{
+  content: string;
+  type: "message";
+}
+
+```
+
+### content[​](#content-1 "Direct link to content")
+
+```ts
+content: string;
+
+```
+
+### type[​](#type-1 "Direct link to type")
+
+```ts
+type: "message";
+
+```
+
+```ts
+{
+  args: unknown;
+  callId: string;
+  name: string;
+  type: "tool_call";
+}
+
+```
+
+### args[​](#args "Direct link to args")
+
+```ts
+args: unknown;
+
+```
+
+### callId[​](#callid "Direct link to callId")
+
+```ts
+callId: string;
+
+```
+
+### name[​](#name "Direct link to name")
+
+```ts
+name: string;
+
+```
+
+### type[​](#type-2 "Direct link to type")
+
+```ts
+type: "tool_call";
+
+```
+
+```ts
+{
+  callId: string;
+  error?: string;
+  result: unknown;
+  type: "tool_result";
+}
+
+```
+
+### callId[​](#callid-1 "Direct link to callId")
+
+```ts
+callId: string;
+
+```
+
+### error?[​](#error "Direct link to error?")
+
+```ts
+optional error: string;
+
+```
+
+### result[​](#result "Direct link to result")
+
+```ts
+result: unknown;
+
+```
+
+### type[​](#type-3 "Direct link to type")
+
+```ts
+type: "tool_result";
+
+```
+
+```ts
+{
+  content: string;
+  type: "thinking";
+}
+
+```
+
+### content[​](#content-2 "Direct link to content")
+
+```ts
+content: string;
+
+```
+
+### type[​](#type-4 "Direct link to type")
+
+```ts
+type: "thinking";
+
+```
+
+```ts
+{
+  error?: string;
+  status: "running" | "waiting" | "complete" | "error";
+  type: "status";
+}
+
+```
+
+### error?[​](#error-1 "Direct link to error?")
+
+```ts
+optional error: string;
+
+```
+
+### status[​](#status "Direct link to status")
+
+```ts
+status: "running" | "waiting" | "complete" | "error";
+
+```
+
+### type[​](#type-5 "Direct link to type")
+
+```ts
+type: "status";
+
+```
+
+```ts
+{
+  data: Record<string, unknown>;
+  type: "metadata";
+}
+
+```
+
+### data[​](#data "Direct link to data")
+
+```ts
+data: Record<string, unknown>;
+
+```
+
+### type[​](#type-6 "Direct link to type")
+
+```ts
+type: "metadata";
+
+```
+
+```ts
+{
+  annotations?: ToolAnnotations;
+  approvalId: string;
+  args: unknown;
+  streamId: string;
+  toolName: string;
+  type: "approval_pending";
+}
+
+```
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+### approvalId[​](#approvalid "Direct link to approvalId")
+
+```ts
+approvalId: string;
+
+```
+
+### args[​](#args-1 "Direct link to args")
+
+```ts
+args: unknown;
+
+```
+
+### streamId[​](#streamid "Direct link to streamId")
+
+```ts
+streamId: string;
+
+```
+
+### toolName[​](#toolname "Direct link to toolName")
+
+```ts
+toolName: string;
+
+```
+
+### type[​](#type-7 "Direct link to type")
+
+```ts
+type: "approval_pending";
+
+```
+
+Emitted by the agents plugin (not adapters) when a mutating tool call is awaiting human approval — fires for tools annotated with `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean. Clients should render an approval prompt and POST to `/chat/approve` with the matching `approvalId` and a `decision` of `approve` or `deny`.

package/docs/api/appkit/TypeAlias.AgentTool.md

@@ -0,0 +1,11 @@
+# Type Alias: AgentTool
+
+```ts
+type AgentTool = 
+  | FunctionTool
+  | HostedTool
+  | ToolkitEntry;
+
+```
+
+Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), or toolkit references from plugins (`analytics().toolkit()`).

package/docs/api/appkit/TypeAlias.AgentTools.md

@@ -0,0 +1,8 @@
+# Type Alias: AgentTools
+
+```ts
+type AgentTools = Record<string, AgentTool>;
+
+```
+
+Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc.

package/docs/api/appkit/TypeAlias.AgentToolsFn.md

@@ -0,0 +1,20 @@
+# Type Alias: AgentToolsFn()
+
+```ts
+type AgentToolsFn = (plugins: Plugins) => AgentTools;
+
+```
+
+Function form of `AgentDefinition.tools`. Receives the typed [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map and returns a tool record. Invoked exactly once at setup (or once per `runAgent` call in standalone mode); the result is cached as the agent's resolved tool record.
+
+Use the function form when an agent needs tools from registered plugins. The bare object form is fine when an agent only uses inline tools.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                      |
+| --------- | --------------------------------------------------------- |
+| `plugins` | [`Plugins`](./docs/api/appkit/TypeAlias.Plugins.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`AgentTools`](./docs/api/appkit/TypeAlias.AgentTools.md)

package/docs/api/appkit/TypeAlias.BaseSystemPromptOption.md

@@ -0,0 +1,9 @@
+# Type Alias: BaseSystemPromptOption
+
+```ts
+type BaseSystemPromptOption = 
+  | false
+  | string
+  | (ctx: PromptContext) => string;
+
+```

package/docs/api/appkit/TypeAlias.HostedTool.md

@@ -0,0 +1,10 @@
+# Type Alias: HostedTool
+
+```ts
+type HostedTool = 
+  | GenieTool
+  | VectorSearchIndexTool
+  | CustomMcpServerTool
+  | ExternalMcpServerTool;
+
+```

package/docs/api/appkit/TypeAlias.Plugins.md

@@ -0,0 +1,26 @@
+# Type Alias: Plugins
+
+```ts
+type Plugins = Record<string, PluginToolkitProvider>;
+
+```
+
+Plugin map passed to the function form of [AgentDefinition.tools](./docs/api/appkit/Interface.AgentDefinition.md#tools). Each entry exposes a `.toolkit(opts?)` method that returns a record of [ToolkitEntry](./docs/api/appkit/Interface.ToolkitEntry.md) markers ready to be spread into a tool record.
+
+AppKit does not statically know which plugins the surrounding `createApp` will register, so this is a plain string-keyed record. Refer to plugins by the name used in `createApp({ plugins: [...] })`; unknown names resolve to `undefined` at runtime.
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+const support = createAgent({
+  instructions: "...",
+  tools(plugins) {
+    return {
+      get_weather: tool({ ... }),
+      ...plugins.analytics.toolkit(),
+      ...plugins.files.toolkit({ only: ["uploads.read"] }),
+    };
+  },
+});
+
+```

package/docs/api/appkit/TypeAlias.ResolvedToolEntry.md

@@ -0,0 +1,29 @@
+# Type Alias: ResolvedToolEntry
+
+```ts
+type ResolvedToolEntry = 
+  | {
+  def: AgentToolDefinition;
+  localName: string;
+  pluginName: string;
+  source: "toolkit";
+}
+  | {
+  def: AgentToolDefinition;
+  functionTool: FunctionTool;
+  source: "function";
+}
+  | {
+  def: AgentToolDefinition;
+  mcpToolName: string;
+  source: "mcp";
+}
+  | {
+  agentName: string;
+  def: AgentToolDefinition;
+  source: "subagent";
+};
+
+```
+
+Internal tool-index entry after a tool record has been resolved to a dispatchable form.

package/docs/api/appkit/TypeAlias.ToolRegistry.md

@@ -0,0 +1,6 @@
+# Type Alias: ToolRegistry
+
+```ts
+type ToolRegistry = Record<string, ToolEntry>;
+
+```

package/docs/api/appkit/Variable.agents.md

@@ -0,0 +1,19 @@
+# Variable: agents
+
+```ts
+const agents: ToPlugin<typeof AgentsPlugin, AgentsPluginConfig, string>;
+
+```
+
+Plugin factory for the agents plugin. Reads `config/agents/*.md` by default, resolves toolkits/tools from registered plugins, exposes `appkit.agents.*` runtime API and mounts `/invocations`.
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+import { agents, analytics, createApp, server } from "@databricks/appkit";
+
+await createApp({
+  plugins: [server(), analytics(), agents()],
+});
+
+```