appkit
@databricks/appkit
Documentation merge entry for Typedoc — combines the stable @databricks/appkit
surface with @databricks/appkit/beta. Not meant for application imports.
Enumerations
| Enumeration | Description |
|---|---|
| RequestedClaimsPermissionSet | Permission set for Unity Catalog table access |
| ResourceType | Resource types from resourceTypeSchema.options |
Classes
| Class | Description |
|---|---|
| AppKitError | Base error class for all AppKit errors. Provides a consistent structure for error handling across the framework. |
| AppKitMcpClient | Lightweight MCP client for Databricks-hosted MCP servers. |
| AuthenticationError | Error thrown when authentication fails. Use for missing tokens, invalid credentials, or authorization failures. |
| ConfigurationError | Error thrown when configuration is missing or invalid. Use for missing environment variables, invalid settings, or setup issues. |
| ConnectionError | Error thrown when a connection or network operation fails. Use for database pool errors, API failures, timeouts, etc. |
| DatabricksAdapter | Adapter that talks directly to Databricks Model Serving /invocations endpoint. |
| ExecutionError | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states. |
| InitializationError | Error thrown when a service or component is not properly initialized. Use when accessing services before they are ready. |
| Plugin | Base abstract class for creating AppKit plugins. |
| PolicyDeniedError | Thrown when a policy denies an action. |
| ResourceRegistry | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only. |
| ServerError | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc. |
| SupervisorApiAdapter | Adapter that calls the Databricks AI Gateway Responses API (/ai-gateway/mlflow/v1/responses). |
| TunnelError | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc. |
| ValidationError | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches. |
Interfaces
| Interface | Description |
|---|---|
| AgentAdapter | - |
| AgentDefinition | - |
| AgentInput | - |
| AgentRunContext | - |
| AgentsPluginConfig | Base configuration interface for AppKit plugins |
| AgentToolDefinition | - |
| AutoInheritToolsConfig | 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 | Base configuration interface for AppKit plugins |
| CacheConfig | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
| DatabaseCredential | Database credentials with OAuth token for Postgres connection |
| EndpointConfig | - |
| FilePolicyUser | Minimal user identity passed to the policy function. |
| FileResource | Describes the file or directory being acted upon. |
| FunctionTool | - |
| GenerateDatabaseCredentialRequest | Request parameters for generating database OAuth credentials |
| GenerationParams | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates. |
| HostedSupervisorTool | Tagged record returned by every supervisorTools factory. The __kind discriminator lets the agents plugin (and standalone runAgent) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use type: "genie-space" hyphenated, vs SA's type: "genie_space" underscored). |
| IAiSearchConfig | Base configuration interface for AppKit plugins |
| IJobsConfig | Configuration for the Jobs plugin. |
| IndexConfig | - |
| ITelemetry | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
| JobAPI | User-facing API for a single configured job. |
| JobConfig | Per-job configuration options. |
| JobsConnectorConfig | - |
| LakebasePool | Subset of pg.Pool exposed by the Lakebase plugin. |
| LakebasePoolConfig | Configuration for creating a Lakebase connection pool |
| LakebasePoolManager | Manages multiple Lakebase connection pools keyed by an identifier (e.g. userId). |
| McpConnectAllResult | Per-endpoint outcome of AppKitMcpClient.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 | - |
| PluginManifest | 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 | Minimum shape every entry in the Plugins 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 | Context passed to baseSystemPrompt callbacks. |
| RegisteredAgent | - |
| RequestedClaims | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables |
| RequestedResource | Resource to request permissions for in Unity Catalog |
| RerankerConfig | - |
| ResourceEntry | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
| ResourceRequirement | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). |
| RunAgentInput | - |
| RunAgentResult | - |
| SearchRequest | - |
| SearchResponse | - |
| SearchResult | - |
| ServingEndpointEntry | Shape of a single registry entry. |
| ServingEndpointRegistry | 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 | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. |
| SupervisorApiAdapterOptions | - |
| SupervisorExtension | Shape of the value at AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]. The agents plugin / runAgent build this from the tool index; advanced callers invoking adapter.run(...) directly populate it themselves. |
| TelemetryConfig | OpenTelemetry configuration for AppKit applications |
| Thread | - |
| ThreadStore | - |
| ToolAnnotations | - |
| ToolConfig | - |
| ToolEntry | Single-tool entry for a plugin's internal tool registry. |
| 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. |
| ToolkitOptions | - |
| ToolProvider | - |
| ValidationResult | Result of validating all registered resources against the environment. |
| WorkspaceClient | AppKit's workspace client facade. Mirrors the multi-client shape of the modular Databricks SDK: each service is its own accessor, so services can be migrated one at a time behind this stable interface. |
| WorkspaceClientLike | Structural shape of a Databricks SDK client used by fromSupervisorApi. Only what we need: apiClient.request for streaming and config.ensureResolved to materialise the host/credentials. |
| WorkspaceClientOptions | Options used to construct the wrapper. Mirrors the subset of the old SDK's Config + ClientOptions that AppKit relies on today; we deliberately do NOT re-expose every old-SDK config knob. |
Type Aliases
| Type Alias | Description |
|---|---|
| AgentEvent | - |
| AgentTool | Any tool an agent can invoke: inline function tools (tool()), hosted MCP tools (mcpServer() / raw hosted), toolkit references from plugins (analytics().toolkit()), or adapter-hosted Supervisor-API tools (supervisorTools.*). |
| AgentTools | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc. |
| AgentToolsFn | Function form of AgentDefinition.tools. Receives the typed Plugins 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 | - |
| ConfigSchema | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
| ExecutionResult | Discriminated union for plugin execution results. |
| FileAction | Every action the files plugin can perform. |
| FilePolicy | A policy function that decides whether user may perform action on resource. Return true to allow, false to deny. |
| HostedTool | - |
| IAppRouter | Express router type for plugin route registration |
| JobsExport | Public API shape of the jobs plugin. Callable to select a job by key. |
| PluginData | Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp(). |
| Plugins | Plugin map passed to the function form of AgentDefinition.tools. Each entry exposes a .toolkit(opts?) method that returns a record of ToolkitEntry markers ready to be spread into a tool record. |
| ResolvedToolEntry | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
| ResourceFieldEntry | - |
| ResourcePermission | Union of all possible permission levels across all resource types. |
| SearchFilters | - |
| ServingFactory | Factory function returned by AppKit.serving. |
| SupervisorTool | Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body. |
| ToolRegistry | - |
| ToPlugin | Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple. |
Variables
| Variable | Description |
|---|---|
| agents | 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). |
| aiSearch | - |
| READ_ACTIONS | Actions that only read data. |
| sql | SQL helper namespace |
| SUPERVISOR_EXTENSION_KEY | Namespace key under which the adapter reads its hosted-tool payload from AgentInput.extensions. Exported so the agents plugin and standalone runAgent (the producers) can write under the same key the adapter reads. |
| supervisorTools | Concise factories for declaring Supervisor API tools. |
| WRITE_ACTIONS | Actions that mutate data. |
Functions
| Function | Description |
|---|---|
| agentIdFromMarkdownPath | 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 | 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 | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood. |
| createAgent | 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 | Bootstraps AppKit with the provided configuration. |
| createLakebasePool | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry. |
| createLakebasePoolManager | Create a pool manager that maintains per-key Lakebase connection pools. |
| createWorkspaceClient | Construct an AppKit workspace client. |
| defineTool | Defines a single tool entry for a plugin's internal registry. |
| executeFromRegistry | 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 | 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 | Find the server entry file by checking candidate paths in order. |
| fromSupervisorApi | Creates an AgentAdapter backed by the Databricks AI Gateway Responses API (/ai-gateway/mlflow/v1/responses). |
| functionToolToDefinition | - |
| generateDatabaseCredential | Generate OAuth credentials for Postgres database connection using the proper Postgres API. |
| getExecutionContext | Get the current execution context. |
| getLakebaseOrmConfig | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly. |
| getLakebasePgConfig | Get Lakebase connection configuration for PostgreSQL clients. |
| getPluginManifest | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission. |
| getResourceRequirements | Gets the resource requirements from a plugin's manifest. |
| getUsernameWithApiLookup | Resolves the PostgreSQL username for a Lakebase connection. |
| getWorkspaceClient | Get workspace client from config or SDK default auth chain |
| isFunctionTool | - |
| isHostedTool | - |
| isSQLTypeMarker | Type guard to check if a value is a SQL type marker |
| isSupervisorTool | Type guard for HostedSupervisorTool. Used by the agents plugin (buildToolIndex) and standalone runAgent (classifyTool) to route supervisor-hosted tools to the extensions payload rather than the adapter's tools array. |
| isToolkitEntry | Type guard for ToolkitEntry — used by the agents plugin to differentiate toolkit references from inline tools in a mixed tools record. |
| loadAgentFromFile | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library. |
| loadAgentsFromDir | 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 | Factory for declaring a custom MCP server tool. |
| parseTextToolCalls | Parses text-based tool calls from model output. |
| resolveHostedTools | - |
| runAgent | Standalone agent execution without createApp. Resolves the adapter, binds inline tools, and drives the adapter's run() loop to completion. |
| tool | Factory for defining function tools with Zod schemas. |
| toolsFromRegistry | Produces the AgentToolDefinition[] a ToolProvider exposes to the LLM, deriving parameters JSON Schema from each entry's Zod schema. |