@databricks/appkit 0.48.0 → 0.50.0

package/docs/plugins/agents.md

@@ -16,12 +16,14 @@ The agents plugin drives the LLM over Server-Sent Events. Foundation Model APIs
 
 For the non-streaming path against a custom endpoint, use the `serving` plugin's `/invoke` route with `useServingInvoke` instead.
 
+Or skip serving-endpoint setup entirely with the managed [Supervisor API adapter](#managed-agents-the-supervisor-api-adapter) (beta).
+
 ## Install[​](#install "Direct link to Install")
 
 `agents` is a regular plugin. Add it to `plugins[]` alongside `server()` and any ToolProvider plugins whose tools you want agents to reach.
 
 ```ts
-import { agents, analytics, createApp, files, server } from "@databricks/appkit";
+import { analytics, createApp, files, server } from "@databricks/appkit";
 import { agents } from "@databricks/appkit/beta";
 
 await createApp({
@@ -182,7 +184,7 @@ Each key in `agents: {...}` on an `AgentDefinition` becomes an `agent-<key>` too
 ## Level 5: standalone (no `createApp`)[​](#level-5-standalone-no-createapp "Direct link to level-5-standalone-no-createapp")
 
 ```ts
-import { createAgent, runAgent, tool } from "@databricks/appkit";
+import { createAgent, runAgent, tool } from "@databricks/appkit/beta";
 import { z } from "zod";
 
 const classifier = createAgent({
@@ -225,7 +227,135 @@ const result = await runAgent(classifier, {
 
 `runAgent` eagerly constructs each plugin in `RunAgentInput.plugins`, runs the standard `attachContext({})` + `await setup()` lifecycle, and shares the instances across the top-level run and every sub-agent dispatch. Plugins whose `setup()` requires `createApp`-only runtime (e.g. `WorkspaceClient`, `ServiceContext`) throw at standalone-init with a clear "use createApp instead" message rather than mid-stream.
 
-Hosted tools (MCP) are still `agents()`-only since they require the live MCP client. Plugin tool dispatch in standalone mode runs as the service principal (no OBO) and **bypasses the agents-plugin approval gate** — treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts), not as an exposed user-facing surface.
+MCP hosted tools (`mcpServer(...)`) still require `agents()` (they need a live MCP client). Supervisor-API hosted tools (`supervisorTools.*`), by contrast, **work in standalone `runAgent`** — the adapter has everything it needs to execute them server-side. This makes batch-eval / CI use of supervisor agents possible without `createApp`. Plugin tool dispatch in standalone mode runs as the service principal (no OBO) and **bypasses the agents-plugin approval gate** — treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts), not as an exposed user-facing surface.
+
+## Managed agents: the Supervisor API adapter[​](#managed-agents-the-supervisor-api-adapter "Direct link to Managed agents: the Supervisor API adapter")
+
+`DatabricksAdapter.fromSupervisorApi` (beta) is the zero-config way to run an agent: instead of provisioning and pointing at a model-serving endpoint, you run the agentic loop in the Databricks workspace by targeting the AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`), which runs the LLM — and any hosted tools — as a managed service on Databricks. No `DATABRICKS_SERVING_ENDPOINT_NAME`, no stream-capability check, no JS tool plumbing for the common cases.
+
+The minimal agent is one extra line versus a markdown agent:
+
+```ts
+import { createApp } from "@databricks/appkit";
+import { agents, createAgent, DatabricksAdapter } from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [
+    agents({
+      agents: {
+        assistant: createAgent({
+          instructions: "You are a helpful assistant.",
+          model: DatabricksAdapter.fromSupervisorApi({
+            model: "databricks-claude-sonnet-4-5",
+          }),
+        }),
+      },
+    }),
+  ],
+});
+
+```
+
+`createAgent({ model })` already accepts adapters and adapter promises in addition to the model-name string used in earlier examples, so you can drop the factory result straight in. The factory resolves credentials through the SDK chain (`DATABRICKS_HOST`, OAuth, PAT, …); pass `workspaceClient` to reuse an existing client.
+
+### Hosted tools[​](#hosted-tools "Direct link to Hosted tools")
+
+Expose Genie spaces, Unity Catalog functions/connections, Knowledge Assistants, or other AppKit apps to the model by declaring them as agent tools — same place every other tool is declared. Execution stays server-side; you write no tool code:
+
+```ts
+import {
+  createAgent,
+  DatabricksAdapter,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+const assistant = createAgent({
+  instructions: "You are a helpful data assistant.",
+  model: DatabricksAdapter.fromSupervisorApi({
+    model: "databricks-claude-sonnet-4-5",
+  }),
+  tools: () => ({
+    nyc: supervisorTools.genieSpace({
+      id: "01ABCDEF12345678",
+      description: "NYC taxi trip records and zones",
+    }),
+    add: supervisorTools.ucFunction({
+      name: "main.default.add",
+      description: "Adds two integers and returns the sum.",
+    }),
+  }),
+});
+
+```
+
+Each `supervisorTools.*` factory takes a single named-options object — routing-critical strings get labels at the call site, so positional-argument swap bugs are impossible.
+
+`description` is **required and non-empty** — the LLM uses it to route between tools, so two Genie spaces both labelled "Genie space" will be indistinguishable.
+
+Hosted-tool descriptions are trusted application configuration (CWE-1427)
+
+A hosted tool's `description` is read by the LLM to decide when to route to that tool. **Do not derive it from untrusted input** — user messages, request bodies, freeform fields from external systems, or any value an attacker could influence. Treat `description` (and `id`/`name`) as application-controlled, alongside the agent's `instructions`. Allowing a user-controlled string here is a prompt-injection sink: a hostile description can convince the model to route to (or away from) a tool for any future request handled by the agent.
+
+The same caution applies to MCP `description`s and to any other field the model reads at routing time.
+
+| Factory                                                                     | Tool kind              | Identifier      |
+| --------------------------------------------------------------------------- | ---------------------- | --------------- |
+| `supervisorTools.genieSpace({ id, description })`                           | Genie space            | space id        |
+| `supervisorTools.ucFunction({ name, description })`                         | Unity Catalog function | three-part name |
+| `supervisorTools.knowledgeAssistant({ knowledgeAssistantId, description })` | Knowledge Assistant    | assistant id    |
+| `supervisorTools.app({ name, description })`                                | Databricks App         | app name        |
+| `supervisorTools.ucConnection({ name, description })`                       | UC connection          | connection name |
+
+### Declaring hosted tools in markdown agents[​](#declaring-hosted-tools-in-markdown-agents "Direct link to Declaring hosted tools in markdown agents")
+
+Hosted-supervisor tools also work in markdown-driven agents: declare the tool in code (under `agents({ tools: { ... } })`) and reference its key in frontmatter:
+
+```ts
+// server.ts
+agents({
+  agents: { /* ... */ },
+  tools: {
+    nyc_taxi: supervisorTools.genieSpace({
+      id: "01ABCDEF12345678",
+      description: "NYC taxi trip records and zones",
+    }),
+  },
+});
+
+```
+
+```md
+---
+endpoint: databricks-claude-sonnet-4-5
+tools:
+  - nyc_taxi
+---
+
+You answer questions about NYC taxi data using the Genie space.
+
+```
+
+No new frontmatter syntax — the ambient-tool lookup in `tools:` already resolves bare keys against `agents({ tools })`, and the tagged-record shape of `supervisorTools.*` lets the plugin classify them automatically.
+
+### What does *not* apply to Supervisor-API agents[​](#what-does-not-apply-to-supervisor-api-agents "Direct link to what-does-not-apply-to-supervisor-api-agents")
+
+The managed runtime owns its own tool execution, so the adapter intentionally **ignores function tools and sub-agents from the agents-plugin tool index**. For any agent whose `model:` is a Supervisor adapter:
+
+* Only `supervisorTools.*` entries reach the model. Function tools (`tool({...})`), MCP hosted tools (`mcpServer(...)`), and local sub-agents (`agents: { ... }`) declared alongside a supervisor adapter will trigger a registration-time warning and **will not be exposed to the model**. The capability check fires from `consumesInputTools: false` on the adapter.
+* The **human-in-the-loop approval gate** does not fire (tool calls never enter the Node process; `effect: "destructive"` annotations are irrelevant for hosted tools).
+* `limits.maxToolCalls` is not enforced (the managed runtime accounts for its own calls).
+* Per-call **OBO** does not apply to hosted tools; they run with the credentials the managed runtime uses for the target resource.
+
+### Cross-adapter sub-agent composition[​](#cross-adapter-sub-agent-composition "Direct link to Cross-adapter sub-agent composition")
+
+Supervisor and chat-completions adapters can both appear in the same `agents({ agents: { ... } })` map, but composition only goes one direction:
+
+* **Chat-completions parent → supervisor sub-agent** works natively. The parent dispatches via `agent-{key}` as a regular function tool; the child's adapter runs entirely on the AI Gateway.
+* **Supervisor parent → function-tool / local sub-agent children** is not yet wired. The capability check warns at registration; those tools will not reach the supervisor model. Future work will lift this restriction by routing SA's `response.function_call` events through `context.executeTool`.
+
+Recovery path for non-streaming tool turns
+
+Some hosted tool kinds return their final assistant text without incremental `output_text.delta` events. The adapter has a recovery path that pulls the text out of `response.completed.output[]` so the turn is not silently empty. Set `DEBUG=appkit:agents:supervisor-api` to log the per-turn event-type histogram if you want to verify which path a turn took.
 
 ## Configuration reference[​](#configuration-reference "Direct link to Configuration reference")
 
@@ -370,10 +500,10 @@ Flow:
 
 2. The chat client renders an approval prompt (see the reference app's approval card).
 
-3. The same user who initiated the stream posts the decision to `POST /api/agent/approve`:
+3. The same user who initiated the stream posts the decision to `POST /api/agents/approve`:
 
    ```http
-   POST /api/agent/approve
+   POST /api/agents/approve
    Content-Type: application/json
    X-Forwarded-User: <end-user id>
    X-Forwarded-Access-Token: <OBO token>
@@ -384,7 +514,7 @@ Flow:
 
 4. If approved, the tool executes normally and the stream continues. If denied, the adapter receives the string `"Tool execution denied by user approval gate (tool: <name>)."` as the tool output and the LLM can apologise / replan. If no decision arrives within `approval.timeoutMs` (default 60 s), the gate auto-denies.
 
-The route enforces that the decider is the stream owner: an approve from a different `x-forwarded-user` returns `403`. Cancelling the stream via `POST /api/agent/cancel` denies every pending approval on that stream.
+The route enforces that the decider is the stream owner: an approve from a different `x-forwarded-user` returns `403`. Cancelling the stream via `POST /api/agents/cancel` denies every pending approval on that stream.
 
 ### Resource limits[​](#resource-limits "Direct link to Resource limits")
 

package/llms.txt

@@ -74,6 +74,7 @@ npx @databricks/appkit docs <query>
 - [Class: PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md): Thrown when a policy denies an action.
 - [Class: ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md): Central registry for tracking plugin resource requirements.
 - [Class: ServerError](./docs/api/appkit/Class.ServerError.md): Error thrown when server lifecycle operations fail.
+- [Class: SupervisorApiAdapter](./docs/api/appkit/Class.SupervisorApiAdapter.md): Adapter that calls the Databricks AI Gateway Responses API
 - [Class: TunnelError](./docs/api/appkit/Class.TunnelError.md): Error thrown when remote tunnel operations fail.
 - [Class: ValidationError](./docs/api/appkit/Class.ValidationError.md): Error thrown when input validation fails.
 - [Enumeration: RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md): Permission set for Unity Catalog table access
@@ -89,6 +90,7 @@ npx @databricks/appkit docs <query>
 - [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
 - [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
 - [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
+- [Function: fromSupervisorApi()](./docs/api/appkit/Function.fromSupervisorApi.md): Creates an AgentAdapter backed by the Databricks AI Gateway
 - [Function: functionToolToDefinition()](./docs/api/appkit/Function.functionToolToDefinition.md): Parameters
 - [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
 - [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
@@ -101,6 +103,7 @@ npx @databricks/appkit docs <query>
 - [Function: isFunctionTool()](./docs/api/appkit/Function.isFunctionTool.md): Parameters
 - [Function: isHostedTool()](./docs/api/appkit/Function.isHostedTool.md): Parameters
 - [Function: isSQLTypeMarker()](./docs/api/appkit/Function.isSQLTypeMarker.md): Type guard to check if a value is a SQL type marker
+- [Function: isSupervisorTool()](./docs/api/appkit/Function.isSupervisorTool.md): Type guard for HostedSupervisorTool. Used by the agents plugin
 - [Function: isToolkitEntry()](./docs/api/appkit/Function.isToolkitEntry.md): Type guard for ToolkitEntry — used by the agents plugin to differentiate
 - [Function: loadAgentFromFile()](./docs/api/appkit/Function.loadAgentFromFile.md): Loads a single markdown agent file and resolves its frontmatter against
 - [Function: loadAgentsFromDir()](./docs/api/appkit/Function.loadAgentsFromDir.md): Scans a directory for one subdirectory per agent, each containing
@@ -110,7 +113,7 @@ npx @databricks/appkit docs <query>
 - [Function: runAgent()](./docs/api/appkit/Function.runAgent.md): Standalone agent execution without createApp. Resolves the adapter, binds
 - [Function: tool()](./docs/api/appkit/Function.tool.md): Factory for defining function tools with Zod schemas.
 - [Function: toolsFromRegistry()](./docs/api/appkit/Function.toolsFromRegistry.md): Produces the AgentToolDefinition[] a ToolProvider exposes to the LLM,
-- [Interface: AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md): Methods
+- [Interface: AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md): Properties
 - [Interface: AgentDefinition](./docs/api/appkit/Interface.AgentDefinition.md): Properties
 - [Interface: AgentInput](./docs/api/appkit/Interface.AgentInput.md): Properties
 - [Interface: AgentRunContext](./docs/api/appkit/Interface.AgentRunContext.md): Properties
@@ -126,6 +129,7 @@ npx @databricks/appkit docs <query>
 - [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
+- [Interface: HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md): Tagged record returned by every supervisorTools factory. The
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
@@ -149,6 +153,8 @@ npx @databricks/appkit docs <query>
 - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
 - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
+- [Interface: SupervisorApiAdapterOptions](./docs/api/appkit/Interface.SupervisorApiAdapterOptions.md): Properties
+- [Interface: SupervisorExtension](./docs/api/appkit/Interface.SupervisorExtension.md): Shape of the value at AgentInput.extensions[SUPERVISOREXTENSIONKEY].
 - [Interface: TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md): OpenTelemetry configuration for AppKit applications
 - [Interface: Thread](./docs/api/appkit/Interface.Thread.md): Properties
 - [Interface: ThreadStore](./docs/api/appkit/Interface.ThreadStore.md): Methods
@@ -159,6 +165,7 @@ npx @databricks/appkit docs <query>
 - [Interface: ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md): Properties
 - [Interface: ToolProvider](./docs/api/appkit/Interface.ToolProvider.md): Methods
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
+- [Interface: WorkspaceClientLike](./docs/api/appkit/Interface.WorkspaceClientLike.md): Structural shape of a Databricks SDK client used by fromSupervisorApi.
 - [Type Alias: AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md): Type Declaration
 - [Type Alias: AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md): Any tool an agent can invoke: inline function tools (tool()), hosted MCP
 - [Type Alias: AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md): Per-agent tool record. String keys map to inline tools, toolkit entries,
@@ -178,11 +185,14 @@ npx @databricks/appkit docs <query>
 - [Type Alias: ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
+- [Type Alias: SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md): Tools supported by the Databricks AI Gateway Responses API. The shapes match
 - [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
 - [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
+- [Variable: SUPERVISOR_EXTENSION_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md): Namespace key under which the adapter reads its hosted-tool payload
+- [Variable: supervisorTools](./docs/api/appkit/Variable.supervisorTools.md): Concise factories for declaring Supervisor API tools.
 - [Variable: WRITE_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md): Actions that mutate data.
 
 ## appkit-ui API reference [collapsed]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {