@databricks/appkit 0.47.1 → 0.49.0

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

@@ -22,8 +22,175 @@ type ResolvedToolEntry =
   agentName: string;
   def: AgentToolDefinition;
   source: "subagent";
+}
+  | {
+  def: AgentToolDefinition;
+  source: "hosted-supervisor";
+  spec: SupervisorTool;
 };
 
 ```
 
 Internal tool-index entry after a tool record has been resolved to a dispatchable form.
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+```ts
+{
+  def: AgentToolDefinition;
+  localName: string;
+  pluginName: string;
+  source: "toolkit";
+}
+
+```
+
+### 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;
+
+```
+
+### source[​](#source "Direct link to source")
+
+```ts
+source: "toolkit";
+
+```
+
+```ts
+{
+  def: AgentToolDefinition;
+  functionTool: FunctionTool;
+  source: "function";
+}
+
+```
+
+### def[​](#def-1 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### functionTool[​](#functiontool "Direct link to functionTool")
+
+```ts
+functionTool: FunctionTool;
+
+```
+
+### source[​](#source-1 "Direct link to source")
+
+```ts
+source: "function";
+
+```
+
+```ts
+{
+  def: AgentToolDefinition;
+  mcpToolName: string;
+  source: "mcp";
+}
+
+```
+
+### def[​](#def-2 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### mcpToolName[​](#mcptoolname "Direct link to mcpToolName")
+
+```ts
+mcpToolName: string;
+
+```
+
+### source[​](#source-2 "Direct link to source")
+
+```ts
+source: "mcp";
+
+```
+
+```ts
+{
+  agentName: string;
+  def: AgentToolDefinition;
+  source: "subagent";
+}
+
+```
+
+### agentName[​](#agentname "Direct link to agentName")
+
+```ts
+agentName: string;
+
+```
+
+### def[​](#def-3 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### source[​](#source-3 "Direct link to source")
+
+```ts
+source: "subagent";
+
+```
+
+```ts
+{
+  def: AgentToolDefinition;
+  source: "hosted-supervisor";
+  spec: SupervisorTool;
+}
+
+```
+
+### def[​](#def-4 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### source[​](#source-4 "Direct link to source")
+
+```ts
+source: "hosted-supervisor";
+
+```
+
+Adapter-side hosted tool (executed by the model-host, not by the Node process). Today: Supervisor API hosted tools (Genie spaces, UC functions, etc.). The `spec` is opaque to the agents plugin — it routes the entry into `AgentInput.extensions` for the adapter that declared the matching `acceptsExtensions` key. `def` is a synthetic placeholder kept so the index has a uniform shape; it is intentionally NOT included in the `tools` array passed to `adapter.run()` (those entries are not callable functions).
+
+### spec[​](#spec "Direct link to spec")
+
+```ts
+spec: SupervisorTool;
+
+```

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

@@ -0,0 +1,45 @@
+# Type Alias: SupervisorTool
+
+```ts
+type SupervisorTool = 
+  | {
+  genie_space: {
+     description: string;
+     id: string;
+  };
+  type: "genie_space";
+}
+  | {
+  type: "uc_function";
+  uc_function: {
+     description: string;
+     name: string;
+  };
+}
+  | {
+  knowledge_assistant: {
+     description: string;
+     knowledge_assistant_id: string;
+  };
+  type: "knowledge_assistant";
+}
+  | {
+  app: {
+     description: string;
+     name: string;
+  };
+  type: "app";
+}
+  | {
+  type: "uc_connection";
+  uc_connection: {
+     description: string;
+     name: string;
+  };
+};
+
+```
+
+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.
+
+This is an adapter-internal wire type. Application code authors tools via the [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md) factories, which return tagged [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md) records — the agents plugin then unwraps the `.spec` when routing through [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions).

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

@@ -0,0 +1,8 @@
+# Variable: SUPERVISOR\_EXTENSION\_KEY
+
+```ts
+const SUPERVISOR_EXTENSION_KEY: "databricks.supervisor";
+
+```
+
+Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads.

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

@@ -0,0 +1,176 @@
+# Variable: supervisorTools
+
+```ts
+const supervisorTools: {
+  app: (__namedParameters: {
+     description: string;
+     name: string;
+  }) => HostedSupervisorTool;
+  genieSpace: (__namedParameters: {
+     description: string;
+     id: string;
+  }) => HostedSupervisorTool;
+  knowledgeAssistant: (__namedParameters: {
+     description: string;
+     knowledgeAssistantId: string;
+  }) => HostedSupervisorTool;
+  ucConnection: (__namedParameters: {
+     description: string;
+     name: string;
+  }) => HostedSupervisorTool;
+  ucFunction: (__namedParameters: {
+     description: string;
+     name: string;
+  }) => HostedSupervisorTool;
+};
+
+```
+
+Concise factories for declaring Supervisor API tools.
+
+Each factory accepts a single named-options object: routing-critical strings (`id`, `name`, `description`) get labels at the call site so "we swapped the args and didn't notice for two weeks" bugs are impossible.
+
+`description` is required: SA's protobuf validation rejects `null`/`""`, AND the LLM running on SA reads this string to decide when to route to the tool. Two genie spaces both labelled "Genie space" give the model nothing to discriminate on, so callers always own the routing hint.
+
+⚠ The `description` is read by the LLM at routing time — it is a prompt-injection sink. Do **not** derive it from untrusted input (user messages, request bodies, external systems). Treat it as application configuration. (CWE-1427)
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+### app()[​](#app "Direct link to app()")
+
+```ts
+app: (__namedParameters: {
+  description: string;
+  name: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter                       | Type                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `name`: `string`; } |
+| `__namedParameters.description` | `string`                                       |
+| `__namedParameters.name`        | `string`                                       |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### genieSpace()[​](#geniespace "Direct link to genieSpace()")
+
+```ts
+genieSpace: (__namedParameters: {
+  description: string;
+  id: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter                       | Type                                         |
+| ------------------------------- | -------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `id`: `string`; } |
+| `__namedParameters.description` | `string`                                     |
+| `__namedParameters.id`          | `string`                                     |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### knowledgeAssistant()[​](#knowledgeassistant "Direct link to knowledgeAssistant()")
+
+```ts
+knowledgeAssistant: (__namedParameters: {
+  description: string;
+  knowledgeAssistantId: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter                                | Type                                                           |
+| ---------------------------------------- | -------------------------------------------------------------- |
+| `__namedParameters`                      | { `description`: `string`; `knowledgeAssistantId`: `string`; } |
+| `__namedParameters.description`          | `string`                                                       |
+| `__namedParameters.knowledgeAssistantId` | `string`                                                       |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### ucConnection()[​](#ucconnection "Direct link to ucConnection()")
+
+```ts
+ucConnection: (__namedParameters: {
+  description: string;
+  name: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter                       | Type                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `name`: `string`; } |
+| `__namedParameters.description` | `string`                                       |
+| `__namedParameters.name`        | `string`                                       |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### ucFunction()[​](#ucfunction "Direct link to ucFunction()")
+
+```ts
+ucFunction: (__namedParameters: {
+  description: string;
+  name: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter                       | Type                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `name`: `string`; } |
+| `__namedParameters.description` | `string`                                       |
+| `__namedParameters.name`        | `string`                                       |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+import { createAgent } from "@databricks/appkit";
+import {
+  agents,
+  DatabricksAdapter,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+const assistant = createAgent({
+  instructions: "You are a helpful assistant.",
+  model: DatabricksAdapter.fromSupervisorApi({
+    model: "databricks-claude-sonnet-4",
+  }),
+  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.",
+    }),
+  }),
+});
+
+```