@databricks/appkit 0.48.0 → 0.50.0

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.",
+    }),
+  }),
+});
+
+```