@databricks/appkit-ui 0.32.0 → 0.34.0

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

@@ -0,0 +1,157 @@
+# Class: AppKitMcpClient
+
+Lightweight MCP client for Databricks-hosted MCP servers.
+
+Uses raw fetch() with JSON-RPC 2.0 over HTTP — no @modelcontextprotocol/sdk or LangChain dependency. Supports the Streamable HTTP transport only (POST with JSON-RPC request, single JSON-RPC response). Implements exactly four methods: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`. No prompts/resources/completion/sampling.
+
+All outbound URLs are gated by an McpHostPolicy: unallowlisted hosts are rejected before the first byte is sent, and workspace credentials are only forwarded to the same-origin workspace. See `mcp-host-policy.ts`.
+
+Rationale for hand-rolling JSON-RPC instead of `@modelcontextprotocol/sdk`: see the file-level comment at the top of this module.
+
+## Constructors[​](#constructors "Direct link to Constructors")
+
+### Constructor[​](#constructor "Direct link to Constructor")
+
+```ts
+new AppKitMcpClient(
+   workspaceHost: string, 
+   authenticate: () => Promise<Record<string, string>>, 
+   policy: McpHostPolicy, 
+   options: {
+  dnsLookup?: DnsLookup;
+  fetchImpl?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}): AppKitMcpClient;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter            | Type                                                                                                                                     |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `workspaceHost`      | `string`                                                                                                                                 |
+| `authenticate`       | () => `Promise`<`Record`<`string`, `string`>>                                                                                            |
+| `policy`             | `McpHostPolicy`                                                                                                                          |
+| `options`            | { `dnsLookup?`: `DnsLookup`; `fetchImpl?`: (`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`<`Response`>; } |
+| `options.dnsLookup?` | `DnsLookup`                                                                                                                              |
+| `options.fetchImpl?` | (`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`<`Response`>                                               |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`AppKitMcpClient`
+
+## Methods[​](#methods "Direct link to Methods")
+
+### callTool()[​](#calltool "Direct link to callTool()")
+
+```ts
+callTool(
+   qualifiedName: string, 
+   args: unknown, 
+   authHeaders?: Record<string, string>, 
+callerSignal?: AbortSignal): Promise<string>;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter       | Type                         |
+| --------------- | ---------------------------- |
+| `qualifiedName` | `string`                     |
+| `args`          | `unknown`                    |
+| `authHeaders?`  | `Record`<`string`, `string`> |
+| `callerSignal?` | `AbortSignal`                |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`Promise`<`string`>
+
+***
+
+### canForwardWorkspaceAuth()[​](#canforwardworkspaceauth "Direct link to canForwardWorkspaceAuth()")
+
+```ts
+canForwardWorkspaceAuth(serverName: string): boolean;
+
+```
+
+Whether the named MCP server may receive workspace-scoped auth headers (e.g., an OBO bearer token from an end-user request). Callers should gate auth-forwarding decisions on this to prevent credential exfiltration to non-workspace hosts.
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `serverName` | `string` |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`boolean`
+
+***
+
+### close()[​](#close "Direct link to close()")
+
+```ts
+close(): Promise<void>;
+
+```
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`Promise`<`void`>
+
+***
+
+### connect()[​](#connect "Direct link to connect()")
+
+```ts
+connect(endpoint: McpEndpointConfig): Promise<void>;
+
+```
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter  | Type                |
+| ---------- | ------------------- |
+| `endpoint` | `McpEndpointConfig` |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`Promise`<`void`>
+
+***
+
+### connectAll()[​](#connectall "Direct link to connectAll()")
+
+```ts
+connectAll(endpoints: McpEndpointConfig[]): Promise<McpConnectAllResult>;
+
+```
+
+Connects every endpoint in parallel and returns a structured summary so callers can distinguish "all connected" from "some failed".
+
+Returning the result instead of throwing is deliberate: one misconfigured MCP server should not take down the entire agents plugin at boot, and the agents plugin uses the summary to warn at startup with the failed-endpoint names. Errors are also logged here so a caller that ignores the return still gets per-endpoint diagnostics.
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter   | Type                   |
+| ----------- | ---------------------- |
+| `endpoints` | `McpEndpointConfig`\[] |
+
+#### Returns[​](#returns-5 "Direct link to Returns")
+
+`Promise`<[`McpConnectAllResult`](./docs/api/appkit/Interface.McpConnectAllResult.md)>
+
+`connected` lists the endpoint names that initialised successfully; `failed` carries `{ name, error }` for the rest.
+
+***
+
+### getAllToolDefinitions()[​](#getalltooldefinitions "Direct link to getAllToolDefinitions()")
+
+```ts
+getAllToolDefinitions(): AgentToolDefinition[];
+
+```
+
+#### Returns[​](#returns-6 "Direct link to Returns")
+
+[`AgentToolDefinition`](./docs/api/appkit/Interface.AgentToolDefinition.md)\[]

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

@@ -0,0 +1,151 @@
+# Class: DatabricksAdapter
+
+Adapter that talks directly to Databricks Model Serving `/invocations` endpoint.
+
+No dependency on the Vercel AI SDK or LangChain. Uses raw `fetch()` to POST OpenAI-compatible payloads and parses the SSE stream itself. Calls `authenticate()` per-request so tokens are always fresh.
+
+Handles both structured `tool_calls` responses and text-based tool call fallback parsing for models that output tool calls as text.
+
+## Examples[​](#examples "Direct link to Examples")
+
+```ts
+import { createApp, createAgent, agents } from "@databricks/appkit";
+import { DatabricksAdapter } from "@databricks/appkit/beta";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+
+const adapter = DatabricksAdapter.fromServingEndpoint({
+  workspaceClient: new WorkspaceClient({}),
+  endpointName: "my-endpoint",
+});
+
+await createApp({
+  plugins: [
+    agents({
+      agents: {
+        assistant: createAgent({
+          instructions: "You are a helpful assistant.",
+          model: adapter,
+        }),
+      },
+    }),
+  ],
+});
+
+```
+
+```ts
+const adapter = new DatabricksAdapter({
+  endpointUrl: "https://host/serving-endpoints/my-endpoint/invocations",
+  authenticate: async () => ({ Authorization: `Bearer ${token}` }),
+});
+
+```
+
+## Implements[​](#implements "Direct link to Implements")
+
+* [`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md)
+
+## Constructors[​](#constructors "Direct link to Constructors")
+
+### Constructor[​](#constructor "Direct link to Constructor")
+
+```ts
+new DatabricksAdapter(options: DatabricksAdapterOptions): DatabricksAdapter;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                       |
+| --------- | -------------------------- |
+| `options` | `DatabricksAdapterOptions` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`DatabricksAdapter`
+
+## Methods[​](#methods "Direct link to Methods")
+
+### run()[​](#run "Direct link to run()")
+
+```ts
+run(input: AgentInput, context: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown>;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `input`   | [`AgentInput`](./docs/api/appkit/Interface.AgentInput.md)           |
+| `context` | [`AgentRunContext`](./docs/api/appkit/Interface.AgentRunContext.md) |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`AsyncGenerator`<[`AgentEvent`](./docs/api/appkit/TypeAlias.AgentEvent.md), `void`, `unknown`>
+
+#### Implementation of[​](#implementation-of "Direct link to Implementation of")
+
+[`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md).[`run`](./docs/api/appkit/Interface.AgentAdapter.md#run)
+
+***
+
+### fromModelServing()[​](#frommodelserving "Direct link to fromModelServing()")
+
+```ts
+static fromModelServing(endpointName?: string, options?: ModelServingOptions): Promise<DatabricksAdapter>;
+
+```
+
+Creates a DatabricksAdapter from a Model Serving endpoint name. Auto-creates a WorkspaceClient internally. Reads the endpoint name from the argument or the `DATABRICKS_SERVING_ENDPOINT_NAME` env var.
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter       | Type                  |
+| --------------- | --------------------- |
+| `endpointName?` | `string`              |
+| `options?`      | `ModelServingOptions` |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`Promise`<`DatabricksAdapter`>
+
+#### Example[​](#example "Direct link to Example")
+
+```ts
+// Reads endpoint from DATABRICKS_SERVING_ENDPOINT_NAME env var
+const adapter = await DatabricksAdapter.fromModelServing();
+
+// Explicit endpoint
+const adapter = await DatabricksAdapter.fromModelServing("my-endpoint");
+
+// With options
+const adapter = await DatabricksAdapter.fromModelServing("my-endpoint", {
+  maxSteps: 5,
+  maxTokens: 2048,
+});
+
+```
+
+***
+
+### fromServingEndpoint()[​](#fromservingendpoint "Direct link to fromServingEndpoint()")
+
+```ts
+static fromServingEndpoint(options: ServingEndpointOptions): Promise<DatabricksAdapter>;
+
+```
+
+Creates a DatabricksAdapter for a Databricks Model Serving endpoint.
+
+Routes through the shared `connectors/serving/stream` helper, which delegates to the SDK's `apiClient.request({ raw: true })`. That gives the adapter centralised URL encoding + authentication with the rest of the serving surface — no bespoke `fetch()` + `authenticate()` plumbing.
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter | Type                     |
+| --------- | ------------------------ |
+| `options` | `ServingEndpointOptions` |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`Promise`<`DatabricksAdapter`>

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.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)