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. |
| DatabaseValidationError | Deliberate validation failure raised by a database mutation hook. Generated routes answer 422 and echo only the issues naming a public column; every other failure raised inside a hook stays an opaque server error. |
| 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. |
| MlflowClient | A thin client over the Databricks workspace REST API, owning the host + bearer token so callers (eval-run creation, assessment writes, the judge's serving endpoint) don't each re-derive URLs or re-attach auth. The host is normalized once at construction. |
| 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 | - |
| AssertionHandle | Chainable handle returned by every assertion to control its severity. Mirrors eve: assertions are gates by default; .soft() demotes to a tracked metric; .atLeast(n) is a soft, score-thresholded assertion. |
| AssertionResult | A single recorded assertion outcome. |
| Assessment | A Feedback assessment in the MLflow REST proto-JSON shape. |
| 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. |
| CustomJudgeSpec | A custom LLM-judge definition: a prompt template and choice→score mapping. |
| DatabaseCredential | Database credentials with OAuth token for Postgres connection |
| DatabaseRegistry | CANONICAL augmentation target. Empty by default; the generated database.d.ts augments it via declare module "@databricks/appkit" { interface DatabaseRegistry { ... } }. |
| DatabaseValidationIssue | One rejected field; path names public columns, never their values. |
| DatabricksAuth | Resolved Databricks host + bearer token for the eval runner's REST calls. |
| DatasetRow | One row of a managed evaluation dataset. inputs are the kwargs passed to the agent for the turn; expectations (when present) is the row's ground truth / guidelines. Mirrors the {inputs, expectations} shape of mlflow.genai datasets and of the Unity Catalog table backing a managed eval dataset. |
| DiscoveredEval | An eval file found under server/agents/<agent>/evals/. |
| DiscoveredEvalConfig | A per-agent evals.config.ts found under server/agents/<agent>/evals/. |
| DriveResult | What a driver returns for a single t.send. |
| EndpointConfig | - |
| EntityMutationHooks | Mutation lifecycle for one entity. A before hook may return a replacement payload, which is revalidated against the trusted schema before it is persisted. Every hook, the mutation, and any write a hook issues through ctx.app.database share one transaction, so a rejection anywhere rolls all of them back. Throw DatabaseValidationError to answer a generated route with 422; any other failure stays an opaque server error. |
| EvalDefinition | A single eval, default-exported from a *.eval.ts file. |
| EvalDriver | Abstraction over how the agent is driven. The HTTP driver posts to a running app's agents endpoint; future drivers (in-process) implement the same shape. |
| EvalResult | The outcome of running one eval. |
| EvalRunSummary | - |
| EvalSummary | - |
| EvalWebServer | Auto-start config for the app under test, à la Playwright's webServer. When set in a root evals.config.ts, the CLI boots the app before running evals and tears it down after — so you don't have to start the server by hand. |
| 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. |
| HookApp | The only capability a hook receives: entities bound to its transaction. |
| HookContext | Which entity is being mutated, and the surface a hook may write through. |
| 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). |
| HttpDriverOptions | - |
| 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 | - |
| JudgeConfig | - |
| JudgeScore | A normalized judge result. score is 0..1. |
| 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). |
| MatchResult | Result of a deterministic matcher run against a value. |
| 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). |
| PostResult | Structured result for a best-effort POST that must not throw. |
| PromptContext | Context passed to baseSystemPrompt callbacks. |
| ReadEvalDatasetOptions | - |
| ReadSerializerContext | Which entity and generated operation produced the row being shaped. |
| RegisteredAgent | - |
| ReportOutcome | - |
| 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 | - |
| ResolveDatabricksAuthOptions | - |
| 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 | - |
| RunEvalOptions | - |
| RunEvalsOptions | - |
| Schema | One finalized schema. TTableName keeps the declared names in the type, so configuration that addresses a table by name is checked against the schema it was written for. Code that accepts any schema uses the default. |
| 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 |
| TestContext | The t context passed to an eval's test function. |
| 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. |
| DatabaseApiConfig | Full generated CRUD for every declared table by default. Set false to disable all generated routes, or use an object to restrict tables and writes. Keyed routes require a public primary key; upsert stays programmatic. Route names must start with a letter, contain only letters, digits, _, or -, be at most 64 characters, and be unique ignoring case. Invalid names fail setup; exclude internal tables with api.tables or use api: false. |
| DatabaseApiWriteOperation | Generated HTTP write operations. |
| DatabaseApiWritesConfig | All writes by default; false keeps reads only, and an object narrows writes. |
| DatabaseExports | Typed database API published by the plugin. |
| EntityHooks | Response shaping and mutation lifecycle declared for one table. |
| EvalProgress | - |
| 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 |
| IDatabaseConfig | Configuration for one schema-bound DatabasePlugin instance. |
| JobsExport | Public API shape of the jobs plugin. Callable to select a job by key. |
| Matcher | A deterministic matcher: inspects a string value and returns a result. |
| 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. |
| ReadSerializer | Shape one already private-safe row before it reaches the wire. A Promise is not assignable to the return type, so an async callback fails to compile: serializers run inside the response path and must not add latency there. |
| 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. |
| Severity | Whether an assertion fails the eval (gate) or is tracked only (soft). |
| 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. |
| TransactionClient | Entity and SQL capabilities bound to one transaction. |
Variables
| Variable | Description |
|---|---|
| agents | Plugin factory for the agents plugin. Discovers agents from server/agents/<id>/agent.{ts,md} by default (markdown still in config/agents/ is read as a deprecated fallback), resolves toolkits/tools from registered plugins, exposes the 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. |
| bigid | - |
| bigint | - |
| boolean | - |
| buildAssessments | - |
| configureJudge | Configure the judge once. Sets the OpenAI-compatible client env autoevals reads and the default judge model. No-op-safe: on failure, judging stays disabled and isJudgeConfigured returns false. |
| createAgent | Pure factory for agent definitions: cycle-detects the sub-agent graph and returns the same object, stamped with a non-enumerable AGENT_BRAND so discovery recognizes it. Safe at module top-level; no adapter is built. Don't Object.freeze the definition before passing it in — the brand is written onto the argument. |
| createApp | Bootstraps AppKit with the provided configuration. |
| createHttpDriver | Drives an agent by POSTing to a running app's chat endpoint and parsing the SSE response. Keeps the thread id across sends so multi-turn evals share a conversation. Agent/stream errors surface as succeeded: false rather than throwing, so t.succeeded() can assert on them. |
| 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. |
| database | Create the database plugin. Omit configuration to load config/database/schema.ts, or supply a typed schema override. |
| defineEval | Define an agent eval. Default-export the result from a server/agents/<id>/evals/*.eval.ts file. |
| defineEvalConfig | Define per-directory eval config. Default-export from evals.config.ts. |
| defineManifest | Validates a raw manifest (typically a manifest.json import) against the canonical Zod schema and returns it as a strict PluginManifest. |
| defineSchema | Compile one declared schema. The returned type keeps the table names the builder returned, so api.tables and hooks can name only real tables. |
| defineTool | Defines a single tool entry for a plugin's internal registry. |
| discoverEvalConfigs | Discover the per-agent evals.config.ts (from defineEvalConfig) at <rootDir>/server/agents/<agent>/evals/evals.config.ts. Config is per-agent: each agent's config applies only to that agent's evals. Agents without a config file are omitted. Returns a stable, sorted list. |
| discoverEvalFiles | Discover evals under <rootDir>/server/agents/<agent>/evals/ — co-located with each agent's agent.{md,ts} (same folder-per-agent layout the agents plugin discovers). The agent id is the folder name; the eval id is the file path relative to that evals dir with .eval.ts stripped. Sorted + stable. |
| enumColumn | - |
| equals | Passes when the value equals expected exactly. |
| evalGlyph | Status glyph for a single eval result. |
| 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. |
| findRootEvalConfig | Path to the root evals.config.ts (from defineEvalConfig) at <rootDir>/evals.config.ts, or undefined when absent. The root config holds run-wide settings (baseUrl, webServer); it's distinct from the per-agent configs found by discoverEvalConfigs. |
| findServerFile | Find the server entry file by checking candidate paths in order. |
| fk | Declare foreign-key to another column. |
| formatEvalDetail | Indented detail lines for a failing eval (error + failing assertions). |
| formatEvalHeadline | The one-line header for a single eval result (no failure detail). |
| formatEvalResults | Render all results as a human-readable console report (non-streaming). |
| formatResultsJson | Render results as a machine-readable JSON report (2-space indented): { summary: EvalSummary, results: EvalResult[] }. Faithful to the types — every field present on a result round-trips. |
| formatResultsJUnit | Render results as JUnit XML for standard CI test reporters: a single <testsuite name="appkit-agent-evals"> with one <testcase> per result. Failures carry a <failure> (error or failing-gate summary); skips a <skipped>. All attribute/text values are XML-escaped. |
| formatSummaryLine | The final PASS/FAIL summary line. |
| 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 |
| id | - |
| includes | Passes when the value contains substring. |
| integer | - |
| isFunctionTool | - |
| isHostedTool | - |
| isJudgeConfigured | - |
| 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. |
| jsonb | - |
| 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. |
| loadRootEvalConfig | Load the root evals.config.ts under rootDir (the project root), or return undefined when there is none. This is the run-wide config carrying baseUrl/webServer; the CLI reads it to resolve options and manage the app-under-test lifecycle before calling runEvalsInDir. |
| matches | Passes when the value matches pattern. |
| mcpServer | Factory for declaring a custom MCP server tool. |
| normalizeHost | Ensure the host has a scheme (Databricks env often lacks https://). |
| parseTextToolCalls | Parses text-based tool calls from model output. |
| readEvalDataset | Read a Databricks managed evaluation dataset (a Unity Catalog table with inputs/expectations columns) into rows, over the public SQL Statement Execution API. Reuses SQLWarehouseConnector for submit/poll/transform — its result transform already JSON-parses string columns into objects, so inputs/expectations come back as records whether the table stores them as JSON strings or structs. |
| reportToMlflow | Write one pass/fail assessment per eval result to the Databricks MLflow REST API. Never throws — failures are collected so the run still reports. |
| resolveDatabricksAuth | - |
| resolveHostedTools | - |
| resolveWorkspaceClient | Construct a Databricks WorkspaceClient for the eval runner — the object the SDK-backed connectors (e.g. SQLWarehouseConnector) take. An explicit host+token builds a PAT client; otherwise the profile (or ambient config) is used and the SDK resolves credentials, minting OAuth as needed. Returns undefined if construction throws (missing/invalid config). |
| runAgent | Standalone agent execution without createApp. Resolves the adapter, binds inline tools, and drives the adapter's run() loop to completion. |
| runEval | Run a single eval against a driver. Never throws for assertion or agent failures — those become a non-passing EvalResult. Only a malformed eval definition surfaces as result.error. |
| runEvalsInDir | Discover, load, and run every eval under each agent's evals/ dir, driving the agents on a running app. Never throws for an individual eval — load/run failures become non-passing EvalResults. |
| runWithRetries | Run attempt up to 1 + retries times, stopping as soon as it returns a result that is neither a thrown error / per-eval timeout (error) nor a transport/agent turn failure (infraFailure). Assertion failures set neither, so a failed-but-completed eval is returned on the first try and never retried. Returns the last result when every attempt failed on infra. |
| summarize | - |
| text | - |
| timestamp | - |
| 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. |
| userTurns | Extract every user-message content, in order, from an MLflow {"messages":[{"role":"user","content":"..."}]} input. A dataset row can carry a full multi-turn conversation; replaying these against one thread (one t.send per returned string) lets the agent see the accumulating history. |
| uuid | - |
| varchar | - |