# @databricks/appkit Documentation merge entry for Typedoc — combines the stable `@databricks/appkit` surface with `@databricks/appkit/beta`. Not meant for application imports. ## Enumerations[​](#enumerations "Direct link to Enumerations") | Enumeration | Description | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md) | Permission set for Unity Catalog table access | | [ResourceType](./docs/api/appkit/Enumeration.ResourceType.md) | Resource types from resourceTypeSchema.options | ## Classes[​](#classes "Direct link to Classes") | Class | Description | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [AppKitError](./docs/api/appkit/Class.AppKitError.md) | Base error class for all AppKit errors. Provides a consistent structure for error handling across the framework. | | [AppKitMcpClient](./docs/api/appkit/Class.AppKitMcpClient.md) | Lightweight MCP client for Databricks-hosted MCP servers. | | [AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md) | Error thrown when authentication fails. Use for missing tokens, invalid credentials, or authorization failures. | | [ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md) | Error thrown when configuration is missing or invalid. Use for missing environment variables, invalid settings, or setup issues. | | [ConnectionError](./docs/api/appkit/Class.ConnectionError.md) | Error thrown when a connection or network operation fails. Use for database pool errors, API failures, timeouts, etc. | | [DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md) | Adapter that talks directly to Databricks Model Serving `/invocations` endpoint. | | [ExecutionError](./docs/api/appkit/Class.ExecutionError.md) | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states. | | [InitializationError](./docs/api/appkit/Class.InitializationError.md) | Error thrown when a service or component is not properly initialized. Use when accessing services before they are ready. | | [Plugin](./docs/api/appkit/Class.Plugin.md) | Base abstract class for creating AppKit plugins. | | [PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md) | Thrown when a policy denies an action. | | [ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md) | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only. | | [ServerError](./docs/api/appkit/Class.ServerError.md) | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc. | | [TunnelError](./docs/api/appkit/Class.TunnelError.md) | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc. | | [ValidationError](./docs/api/appkit/Class.ValidationError.md) | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches. | ## Interfaces[​](#interfaces "Direct link to Interfaces") | Interface | Description | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) | - | | [AgentDefinition](./docs/api/appkit/Interface.AgentDefinition.md) | - | | [AgentInput](./docs/api/appkit/Interface.AgentInput.md) | - | | [AgentRunContext](./docs/api/appkit/Interface.AgentRunContext.md) | - | | [AgentsPluginConfig](./docs/api/appkit/Interface.AgentsPluginConfig.md) | Base configuration interface for AppKit plugins | | [AgentToolDefinition](./docs/api/appkit/Interface.AgentToolDefinition.md) | - | | [AutoInheritToolsConfig](./docs/api/appkit/Interface.AutoInheritToolsConfig.md) | Auto-inherit configuration. When enabled for a given agent origin, agents with no explicit `tools:` declaration receive every registered ToolProvider plugin tool whose author marked `autoInheritable: true`. Tools without that flag — destructive, state-mutating, or privilege-sensitive — never spread automatically and must be wired via `tools:` (object or function form in code, `plugin:NAME` entries in markdown frontmatter). | | [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md) | Base configuration interface for AppKit plugins | | [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. | | [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection | | [EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md) | - | | [FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md) | Minimal user identity passed to the policy function. | | [FileResource](./docs/api/appkit/Interface.FileResource.md) | Describes the file or directory being acted upon. | | [FunctionTool](./docs/api/appkit/Interface.FunctionTool.md) | - | | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials | | [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md) | Configuration for the Jobs plugin. | | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. | | [JobAPI](./docs/api/appkit/Interface.JobAPI.md) | User-facing API for a single configured job. | | [JobConfig](./docs/api/appkit/Interface.JobConfig.md) | Per-job configuration options. | | [JobsConnectorConfig](./docs/api/appkit/Interface.JobsConnectorConfig.md) | - | | [LakebasePool](./docs/api/appkit/Interface.LakebasePool.md) | Subset of `pg.Pool` exposed by the Lakebase plugin. | | [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md) | Configuration for creating a Lakebase connection pool | | [LakebasePoolManager](./docs/api/appkit/Interface.LakebasePoolManager.md) | Manages multiple Lakebase connection pools keyed by an identifier (e.g. userId). | | [McpConnectAllResult](./docs/api/appkit/Interface.McpConnectAllResult.md) | Per-endpoint outcome of [AppKitMcpClient.connectAll](./docs/api/appkit/Class.AppKitMcpClient.md#connectall). Callers (the agents plugin in particular) use the split to warn at startup when some MCP servers are unreachable without aborting boot for the rest. | | [Message](./docs/api/appkit/Interface.Message.md) | - | | [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types. | | [PluginToolkitProvider](./docs/api/appkit/Interface.PluginToolkitProvider.md) | Minimum shape every entry in the [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map must expose. Core plugins (analytics, files, genie, lakebase) implement this directly via their `.toolkit()` method. The agents plugin and standalone `runAgent` synthesize this shape for any registered plugin that doesn't implement `.toolkit()` directly (falling back to `getAgentTools()` walking). | | [PromptContext](./docs/api/appkit/Interface.PromptContext.md) | Context passed to `baseSystemPrompt` callbacks. | | [RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md) | - | | [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md) | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables | | [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md) | Resource to request permissions for in Unity Catalog | | [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. | | [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). | | [RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md) | - | | [RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md) | - | | [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md) | Shape of a single registry entry. | | [ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md) | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint. | | [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. | | [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications | | [Thread](./docs/api/appkit/Interface.Thread.md) | - | | [ThreadStore](./docs/api/appkit/Interface.ThreadStore.md) | - | | [ToolAnnotations](./docs/api/appkit/Interface.ToolAnnotations.md) | - | | [ToolConfig](./docs/api/appkit/Interface.ToolConfig.md) | - | | [ToolEntry](./docs/api/appkit/Interface.ToolEntry.md) | Single-tool entry for a plugin's internal tool registry. | | [ToolkitEntry](./docs/api/appkit/Interface.ToolkitEntry.md) | 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. | | [ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md) | - | | [ToolProvider](./docs/api/appkit/Interface.ToolProvider.md) | - | | [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md) | Result of validating all registered resources against the environment. | ## Type Aliases[​](#type-aliases "Direct link to Type Aliases") | Type Alias | Description | | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md) | - | | [AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md) | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), or toolkit references from plugins (`analytics().toolkit()`). | | [AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md) | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc. | | [AgentToolsFn](./docs/api/appkit/TypeAlias.AgentToolsFn.md) | 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. | | [BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md) | - | | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. | | [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md) | Discriminated union for plugin execution results. | | [FileAction](./docs/api/appkit/TypeAlias.FileAction.md) | Every action the files plugin can perform. | | [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md) | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. | | [HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md) | - | | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md) | Express router type for plugin route registration | | [JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md) | Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`. | | [JobsExport](./docs/api/appkit/TypeAlias.JobsExport.md) | Public API shape of the jobs plugin. Callable to select a job by key. | | [PluginData](./docs/api/appkit/TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. | | [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) | 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. | | [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. | | [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md) | - | | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. | | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. | | [ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md) | - | | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. | ## Variables[​](#variables "Direct link to Variables") | Variable | Description | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [agents](./docs/api/appkit/Variable.agents.md) | 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 `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). | | [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md) | Actions that only read data. | | [sql](./docs/api/appkit/Variable.sql.md) | SQL helper namespace | | [WRITE\_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md) | Actions that mutate data. | ## Functions[​](#functions "Direct link to Functions") | Function | Description | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [agentIdFromMarkdownPath](./docs/api/appkit/Function.agentIdFromMarkdownPath.md) | Derives the logical agent id from a markdown path. When the file is named `agent.md`, the id is the parent directory name (folder-based layout); otherwise the id is the file stem (e.g. legacy single-file paths). | | [appKitServingTypesPlugin](./docs/api/appkit/Function.appKitServingTypesPlugin.md) | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation. | | [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md) | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood. | | [createAgent](./docs/api/appkit/Function.createAgent.md) | Pure factory for agent definitions. Returns the passed-in definition after cycle-detecting the sub-agent graph. Accepts the full `AgentDefinition` shape and is safe to call at module top-level. | | [createApp](./docs/api/appkit/Function.createApp.md) | Bootstraps AppKit with the provided configuration. | | [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md) | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry. | | [createLakebasePoolManager](./docs/api/appkit/Function.createLakebasePoolManager.md) | Create a pool manager that maintains per-key Lakebase connection pools. | | [defineTool](./docs/api/appkit/Function.defineTool.md) | Defines a single tool entry for a plugin's internal registry. | | [executeFromRegistry](./docs/api/appkit/Function.executeFromRegistry.md) | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn. | | [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md) | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings. | | [findServerFile](./docs/api/appkit/Function.findServerFile.md) | Find the server entry file by checking candidate paths in order. | | [functionToolToDefinition](./docs/api/appkit/Function.functionToolToDefinition.md) | - | | [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API. | | [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md) | Get the current execution context. | | [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md) | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly. | | [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md) | Get Lakebase connection configuration for PostgreSQL clients. | | [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md) | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission. | | [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md) | Gets the resource requirements from a plugin's manifest. | | [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md) | Resolves the PostgreSQL username for a Lakebase connection. | | [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md) | Get workspace client from config or SDK default auth chain | | [isFunctionTool](./docs/api/appkit/Function.isFunctionTool.md) | - | | [isHostedTool](./docs/api/appkit/Function.isHostedTool.md) | - | | [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md) | Type guard to check if a value is a SQL type marker | | [isToolkitEntry](./docs/api/appkit/Function.isToolkitEntry.md) | Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record. | | [loadAgentFromFile](./docs/api/appkit/Function.loadAgentFromFile.md) | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library. | | [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md) | 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. | | [mcpServer](./docs/api/appkit/Function.mcpServer.md) | Factory for declaring a custom MCP server tool. | | [parseTextToolCalls](./docs/api/appkit/Function.parseTextToolCalls.md) | Parses text-based tool calls from model output. | | [resolveHostedTools](./docs/api/appkit/Function.resolveHostedTools.md) | - | | [runAgent](./docs/api/appkit/Function.runAgent.md) | Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion. | | [tool](./docs/api/appkit/Function.tool.md) | Factory for defining function tools with Zod schemas. | | [toolsFromRegistry](./docs/api/appkit/Function.toolsFromRegistry.md) | Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema. |