@databricks/appkit-ui 0.31.0 → 0.33.0

package/docs/api/appkit/Class.Plugin.md

@@ -139,6 +139,15 @@ protected config: TConfig;
 
 ***
 
+### context?[​](#context "Direct link to context?")
+
+```ts
+protected optional context: PluginContext;
+
+```
+
+***
+
 ### devFileReader[​](#devfilereader "Direct link to devFileReader")
 
 ```ts
@@ -255,6 +264,39 @@ AuthenticationError if user token is not available in request headers (productio
 
 ***
 
+### attachContext()[​](#attachcontext "Direct link to attachContext()")
+
+```ts
+attachContext(deps: {
+  context?: unknown;
+  telemetryConfig?: TelemetryOptions;
+}): void;
+
+```
+
+Binds runtime dependencies (telemetry provider, cache, plugin context) to this plugin. Called by `AppKit._createApp` after construction and before `setup()`. Idempotent: safe to call if the constructor already bound them eagerly. Kept separate so factories can eagerly construct plugin instances without running this before `TelemetryManager.initialize()` / `CacheManager.getInstance()` have run.
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter               | Type                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| `deps`                  | { `context?`: `unknown`; `telemetryConfig?`: `TelemetryOptions`; } |
+| `deps.context?`         | `unknown`                                                          |
+| `deps.telemetryConfig?` | `TelemetryOptions`                                                 |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`void`
+
+#### Implementation of[​](#implementation-of-2 "Direct link to Implementation of")
+
+```ts
+BasePlugin.attachContext
+
+```
+
+***
+
 ### clientConfig()[​](#clientconfig "Direct link to clientConfig()")
 
 ```ts
@@ -272,7 +314,7 @@ Values must be JSON-serializable plain data (no functions, Dates, classes, Maps,
 
 On the client, read the config with the `usePluginClientConfig` hook (React) or the `getPluginClientConfig` function (vanilla JS), both from `@databricks/appkit-ui`.
 
-#### Returns[​](#returns-3 "Direct link to Returns")
+#### Returns[​](#returns-4 "Direct link to Returns")
 
 `Record`<`string`, `unknown`>
 
@@ -304,7 +346,7 @@ const config = getPluginClientConfig<MyPluginConfig>("myPlugin");
 
 ```
 
-#### Implementation of[​](#implementation-of-2 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-3 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.clientConfig
@@ -338,7 +380,7 @@ Errors are never thrown — the method is production-safe.
 | -------------- |
 | `T`            |
 
-#### Parameters[​](#parameters-2 "Direct link to Parameters")
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
 
 | Parameter  | Type                                         |
 | ---------- | -------------------------------------------- |
@@ -346,7 +388,7 @@ Errors are never thrown — the method is production-safe.
 | `options`  | `PluginExecutionSettings`                    |
 | `userKey?` | `string`                                     |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-5 "Direct link to Returns")
 
 `Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`T`>>
 
@@ -369,7 +411,7 @@ userKey?: string): Promise<void>;
 | -------------- |
 | `T`            |
 
-#### Parameters[​](#parameters-3 "Direct link to Parameters")
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
 
 | Parameter  | Type                                                                                      |
 | ---------- | ----------------------------------------------------------------------------------------- |
@@ -378,7 +420,7 @@ userKey?: string): Promise<void>;
 | `options`  | [`StreamExecutionSettings`](./docs/api/appkit/Interface.StreamExecutionSettings.md) |
 | `userKey?` | `string`                                                                                  |
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-6 "Direct link to Returns")
 
 `Promise`<`void`>
 
@@ -395,7 +437,7 @@ Returns the public exports for this plugin. Override this to define a custom pub
 
 The returned object becomes the plugin's public API on the AppKit instance (e.g. `appkit.myPlugin.method()`). AppKit automatically binds method context and adds `asUser(req)` for user-scoped execution.
 
-#### Returns[​](#returns-6 "Direct link to Returns")
+#### Returns[​](#returns-7 "Direct link to Returns")
 
 `unknown`
 
@@ -416,7 +458,7 @@ appkit.myPlugin.getData();
 
 ```
 
-#### Implementation of[​](#implementation-of-3 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-4 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.exports
@@ -432,11 +474,11 @@ getEndpoints(): PluginEndpointMap;
 
 ```
 
-#### Returns[​](#returns-7 "Direct link to Returns")
+#### Returns[​](#returns-8 "Direct link to Returns")
 
 `PluginEndpointMap`
 
-#### Implementation of[​](#implementation-of-4 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-5 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.getEndpoints
@@ -452,11 +494,11 @@ getSkipBodyParsingPaths(): ReadonlySet<string>;
 
 ```
 
-#### Returns[​](#returns-8 "Direct link to Returns")
+#### Returns[​](#returns-9 "Direct link to Returns")
 
 `ReadonlySet`<`string`>
 
-#### Implementation of[​](#implementation-of-5 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-6 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.getSkipBodyParsingPaths
@@ -472,17 +514,17 @@ injectRoutes(_: Router): void;
 
 ```
 
-#### Parameters[​](#parameters-4 "Direct link to Parameters")
+#### Parameters[​](#parameters-5 "Direct link to Parameters")
 
 | Parameter | Type     |
 | --------- | -------- |
 | `_`       | `Router` |
 
-#### Returns[​](#returns-9 "Direct link to Returns")
+#### Returns[​](#returns-10 "Direct link to Returns")
 
 `void`
 
-#### Implementation of[​](#implementation-of-6 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-7 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.injectRoutes
@@ -498,14 +540,14 @@ protected registerEndpoint(name: string, path: string): void;
 
 ```
 
-#### Parameters[​](#parameters-5 "Direct link to Parameters")
+#### Parameters[​](#parameters-6 "Direct link to Parameters")
 
 | Parameter | Type     |
 | --------- | -------- |
 | `name`    | `string` |
 | `path`    | `string` |
 
-#### Returns[​](#returns-10 "Direct link to Returns")
+#### Returns[​](#returns-11 "Direct link to Returns")
 
 `void`
 
@@ -522,13 +564,13 @@ Resolve the effective user ID from a request.
 
 Returns the `x-forwarded-user` header when present. In development mode (`NODE_ENV=development`) falls back to the current context user ID so that callers outside an active `runInUserContext` scope still get a consistent value.
 
-#### Parameters[​](#parameters-6 "Direct link to Parameters")
+#### Parameters[​](#parameters-7 "Direct link to Parameters")
 
 | Parameter | Type      |
 | --------- | --------- |
 | `req`     | `Request` |
 
-#### Returns[​](#returns-11 "Direct link to Returns")
+#### Returns[​](#returns-12 "Direct link to Returns")
 
 `string`
 
@@ -551,14 +593,14 @@ protected route<_TResponse>(router: Router, config: RouteConfig): void;
 | -------------- |
 | `_TResponse`   |
 
-#### Parameters[​](#parameters-7 "Direct link to Parameters")
+#### Parameters[​](#parameters-8 "Direct link to Parameters")
 
 | Parameter | Type          |
 | --------- | ------------- |
 | `router`  | `Router`      |
 | `config`  | `RouteConfig` |
 
-#### Returns[​](#returns-12 "Direct link to Returns")
+#### Returns[​](#returns-13 "Direct link to Returns")
 
 `void`
 
@@ -571,11 +613,11 @@ setup(): Promise<void>;
 
 ```
 
-#### Returns[​](#returns-13 "Direct link to Returns")
+#### Returns[​](#returns-14 "Direct link to Returns")
 
 `Promise`<`void`>
 
-#### Implementation of[​](#implementation-of-7 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-8 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.setup

package/docs/api/appkit/Function.agentIdFromMarkdownPath.md

@@ -0,0 +1,18 @@
+# Function: agentIdFromMarkdownPath()
+
+```ts
+function agentIdFromMarkdownPath(filePath: string): string;
+
+```
+
+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).
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `filePath` | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string`

package/docs/api/appkit/Function.createAgent.md

@@ -0,0 +1,33 @@
+# Function: createAgent()
+
+```ts
+function createAgent(def: AgentDefinition): AgentDefinition;
+
+```
+
+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.
+
+The returned value is a plain `AgentDefinition` — no adapter construction, no side effects. Register it with `agents({ agents: { name: def } })` or run it standalone via `runAgent(def, input)`.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `def`     | [`AgentDefinition`](./docs/api/appkit/Interface.AgentDefinition.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`AgentDefinition`](./docs/api/appkit/Interface.AgentDefinition.md)
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+const support = createAgent({
+  instructions: "You help customers.",
+  model: "databricks-claude-sonnet-4-5",
+  tools: {
+    get_weather: tool({ ... }),
+  },
+});
+
+```

package/docs/api/appkit/Function.createApp.md

@@ -4,6 +4,7 @@
 function createApp<T>(config: {
   cache?: CacheConfig;
   client?: WorkspaceClient;
+  disableInternalTelemetry?: boolean;
   onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
   plugins?: T;
   telemetry?: TelemetryConfig;
@@ -23,14 +24,15 @@ Initializes telemetry, cache, and service context, then registers plugins in pha
 
 ## Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter                | Type                                                                                                                                                                                                                                                                                                     |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `config`                 | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `onPluginsReady?`: (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } |
-| `config.cache?`          | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                        |
-| `config.client?`         | `WorkspaceClient`                                                                                                                                                                                                                                                                                        |
-| `config.onPluginsReady?` | (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                              |
-| `config.plugins?`        | `T`                                                                                                                                                                                                                                                                                                      |
-| `config.telemetry?`      | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                |
+| Parameter                          | Type                                                                                                                                                                                                                                                                                                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `config`                           | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `disableInternalTelemetry?`: `boolean`; `onPluginsReady?`: (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } |
+| `config.cache?`                    | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                                                                |
+| `config.client?`                   | `WorkspaceClient`                                                                                                                                                                                                                                                                                                                                |
+| `config.disableInternalTelemetry?` | `boolean`                                                                                                                                                                                                                                                                                                                                        |
+| `config.onPluginsReady?`           | (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                                                                      |
+| `config.plugins?`                  | `T`                                                                                                                                                                                                                                                                                                                                              |
+| `config.telemetry?`                | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                                                        |
 
 ## Returns[​](#returns "Direct link to Returns")
 

package/docs/api/appkit/Function.defineTool.md

@@ -0,0 +1,26 @@
+# Function: defineTool()
+
+```ts
+function defineTool<S>(config: ToolEntry<S>): ToolEntry<S>;
+
+```
+
+Defines a single tool entry for a plugin's internal registry.
+
+The generic `S` flows from `schema` through to the `handler` callback so `args` is fully typed from the Zod schema. Names are assigned by the registry key, so they are not repeated inside the entry.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                                                                           |
+| ---------------------------------------------------------------------------------------- |
+| `S` *extends* `ZodType`<`unknown`, `unknown`, `$ZodTypeInternals`<`unknown`, `unknown`>> |
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `config`  | [`ToolEntry`](./docs/api/appkit/Interface.ToolEntry.md)<`S`> |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`ToolEntry`](./docs/api/appkit/Interface.ToolEntry.md)<`S`>

package/docs/api/appkit/Function.executeFromRegistry.md

@@ -0,0 +1,25 @@
+# Function: executeFromRegistry()
+
+```ts
+function executeFromRegistry(
+   registry: ToolRegistry, 
+   name: string, 
+   args: unknown, 
+signal?: AbortSignal): Promise<unknown>;
+
+```
+
+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.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                                                                |
+| ---------- | ------------------------------------------------------------------- |
+| `registry` | [`ToolRegistry`](./docs/api/appkit/TypeAlias.ToolRegistry.md) |
+| `name`     | `string`                                                            |
+| `args`     | `unknown`                                                           |
+| `signal?`  | `AbortSignal`                                                       |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`unknown`>

package/docs/api/appkit/Function.functionToolToDefinition.md

@@ -0,0 +1,16 @@
+# Function: functionToolToDefinition()
+
+```ts
+function functionToolToDefinition(tool: FunctionTool): AgentToolDefinition;
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                |
+| --------- | ------------------------------------------------------------------- |
+| `tool`    | [`FunctionTool`](./docs/api/appkit/Interface.FunctionTool.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`AgentToolDefinition`](./docs/api/appkit/Interface.AgentToolDefinition.md)

package/docs/api/appkit/Function.isFunctionTool.md

@@ -0,0 +1,16 @@
+# Function: isFunctionTool()
+
+```ts
+function isFunctionTool(value: unknown): value is FunctionTool;
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`value is FunctionTool`

package/docs/api/appkit/Function.isHostedTool.md

@@ -0,0 +1,16 @@
+# Function: isHostedTool()
+
+```ts
+function isHostedTool(value: unknown): value is HostedTool;
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`value is HostedTool`

package/docs/api/appkit/Function.isToolkitEntry.md

@@ -0,0 +1,18 @@
+# Function: isToolkitEntry()
+
+```ts
+function isToolkitEntry(value: unknown): value is ToolkitEntry;
+
+```
+
+Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`value is ToolkitEntry`

package/docs/api/appkit/Function.loadAgentFromFile.md

@@ -0,0 +1,21 @@
+# Function: loadAgentFromFile()
+
+```ts
+function loadAgentFromFile(filePath: string, ctx: LoadContext): Promise<AgentDefinition>;
+
+```
+
+Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library.
+
+Rejects non-empty `agents:` frontmatter because single-file loads have no siblings to resolve sub-agent references against — callers must use [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md) when markdown agents delegate to one another.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type          |
+| ---------- | ------------- |
+| `filePath` | `string`      |
+| `ctx`      | `LoadContext` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`AgentDefinition`](./docs/api/appkit/Interface.AgentDefinition.md)>

package/docs/api/appkit/Function.loadAgentsFromDir.md

@@ -0,0 +1,26 @@
+# Function: loadAgentsFromDir()
+
+```ts
+function loadAgentsFromDir(dir: string, ctx: LoadContext): Promise<LoadResult>;
+
+```
+
+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.
+
+Legacy top-level `*.md` files are rejected with an error — migrate each to `<id>/agent.md` under a sibling folder named for the agent id.
+
+Runs in two passes so sub-agent references in frontmatter (`agents: [...]`) can be resolved regardless of directory iteration order:
+
+1. Build every agent's definition from its own `agent.md`.
+2. Walk `agents:` references and wire `def.agents = { child: childDef }` by looking them up in the complete map. Dangling names and self-references fail loudly; mutual delegation is allowed and bounded at runtime by `limits.maxSubAgentDepth`.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `dir`     | `string`      |
+| `ctx`     | `LoadContext` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`LoadResult`>

package/docs/api/appkit/Function.mcpServer.md

@@ -0,0 +1,28 @@
+# Function: mcpServer()
+
+```ts
+function mcpServer(name: string, url: string): CustomMcpServerTool;
+
+```
+
+Factory for declaring a custom MCP server tool.
+
+Replaces the verbose `{ type: "custom_mcp_server", custom_mcp_server: { app_name, app_url } }` wrapper with a concise positional call.
+
+Example:
+
+```ts
+mcpServer("my-app", "https://my-app.databricksapps.com/mcp")
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `name`    | `string` |
+| `url`     | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`CustomMcpServerTool`

package/docs/api/appkit/Function.parseTextToolCalls.md

@@ -0,0 +1,26 @@
+# Function: parseTextToolCalls()
+
+```ts
+function parseTextToolCalls(text: string): {
+  args: unknown;
+  name: string;
+}[];
+
+```
+
+Parses text-based tool calls from model output.
+
+Handles two formats:
+
+1. Llama native: `[{"name": "tool_name", "parameters": {"arg": "val"}}]`
+2. Python-style: `[tool_name(arg1='val1', arg2='val2')]`
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `text`    | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+{ `args`: `unknown`; `name`: `string`; }\[]

package/docs/api/appkit/Function.resolveHostedTools.md

@@ -0,0 +1,16 @@
+# Function: resolveHostedTools()
+
+```ts
+function resolveHostedTools(tools: HostedTool[]): McpEndpointConfig[];
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `tools`   | [`HostedTool`](./docs/api/appkit/TypeAlias.HostedTool.md)\[] |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`McpEndpointConfig`\[]

package/docs/api/appkit/Function.runAgent.md

@@ -0,0 +1,26 @@
+# Function: runAgent()
+
+```ts
+function runAgent(def: AgentDefinition, input: RunAgentInput): Promise<RunAgentResult>;
+
+```
+
+Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion.
+
+Limitations vs. running through the agents() plugin:
+
+* **No OBO and no approval gate** — there is no HTTP request, so plugin tools run as the service principal. The agents-plugin approval gate that prompts for human confirmation on `effect: "write" | "update" | "destructive"` tools is also absent. LLM-controlled tool arguments flow straight through to the SP. Treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts) — not as an exposed user-facing surface.
+* **Hosted tools (MCP) are not supported** — they require a live MCP client that only exists inside the agents plugin's lifecycle. `runAgent` rejects them at index-build time with a clear error.
+* **Sub-agents** (`agents: { ... }` on the def) are executed as nested `runAgent` calls with no shared thread state. Plugin instances ARE shared across the recursion (same cache as the parent).
+* **Plugin tools** (used inside the function form via `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via `RunAgentInput`. Each plugin in that array is constructed once, `attachContext({})` and `await setup()` are called eagerly, and the resulting instance is shared across the top-level run and all sub-agent recursions. Plugins whose `setup()` requires runtime that only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`, `PluginContext`) throw at standalone-init time with a clear "use createApp instead" message — not mid-stream.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `def`     | [`AgentDefinition`](./docs/api/appkit/Interface.AgentDefinition.md) |
+| `input`   | [`RunAgentInput`](./docs/api/appkit/Interface.RunAgentInput.md)     |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`RunAgentResult`](./docs/api/appkit/Interface.RunAgentResult.md)>

package/docs/api/appkit/Function.tool.md

@@ -0,0 +1,28 @@
+# Function: tool()
+
+```ts
+function tool<S>(config: ToolConfig<S>): FunctionTool;
+
+```
+
+Factory for defining function tools with Zod schemas.
+
+* Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.
+* Infers the `execute` argument type from the schema.
+* Validates tool call arguments at runtime. On validation failure, returns a formatted error string to the LLM instead of throwing, so the model can self-correct on its next turn.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                                                                           |
+| ---------------------------------------------------------------------------------------- |
+| `S` *extends* `ZodType`<`unknown`, `unknown`, `$ZodTypeInternals`<`unknown`, `unknown`>> |
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `config`  | [`ToolConfig`](./docs/api/appkit/Interface.ToolConfig.md)<`S`> |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`FunctionTool`](./docs/api/appkit/Interface.FunctionTool.md)

package/docs/api/appkit/Function.toolsFromRegistry.md

@@ -0,0 +1,20 @@
+# Function: toolsFromRegistry()
+
+```ts
+function toolsFromRegistry(registry: ToolRegistry): AgentToolDefinition[];
+
+```
+
+Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema.
+
+Tool names come from registry keys (supports dotted names like `uploads.list` for dynamic plugins).
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                                                                |
+| ---------- | ------------------------------------------------------------------- |
+| `registry` | [`ToolRegistry`](./docs/api/appkit/TypeAlias.ToolRegistry.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`AgentToolDefinition`](./docs/api/appkit/Interface.AgentToolDefinition.md)\[]