@databricks/appkit 0.32.0 → 0.33.0

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)

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)\[]

package/docs/api/appkit/Interface.AgentAdapter.md

@@ -0,0 +1,21 @@
+# Interface: AgentAdapter
+
+## Methods[​](#methods "Direct link to Methods")
+
+### run()[​](#run "Direct link to run()")
+
+```ts
+run(input: AgentInput, context: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `input`   | [`AgentInput`](./docs/api/appkit/Interface.AgentInput.md)           |
+| `context` | [`AgentRunContext`](./docs/api/appkit/Interface.AgentRunContext.md) |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`AsyncGenerator`<[`AgentEvent`](./docs/api/appkit/TypeAlias.AgentEvent.md), `void`, `unknown`>

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -0,0 +1,112 @@
+# Interface: AgentDefinition
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agents?[​](#agents "Direct link to agents?")
+
+```ts
+optional agents: Record<string, AgentDefinition>;
+
+```
+
+Sub-agents, exposed as `agent-<key>` tools on this agent.
+
+***
+
+### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
+
+```ts
+optional baseSystemPrompt: BaseSystemPromptOption;
+
+```
+
+Override the plugin's baseSystemPrompt for this agent only.
+
+***
+
+### ephemeral?[​](#ephemeral "Direct link to ephemeral?")
+
+```ts
+optional ephemeral: boolean;
+
+```
+
+When true, the thread used for a chat request against this agent is deleted from `ThreadStore` after the stream completes (success or failure). Use for stateless one-shot agents — e.g. autocomplete, where each request is independent and retaining history would both poison future calls and accumulate unbounded state in the default `InMemoryThreadStore`. Defaults to `false`.
+
+***
+
+### instructions[​](#instructions "Direct link to instructions")
+
+```ts
+instructions: string;
+
+```
+
+System prompt body. For markdown-loaded agents this is the file body.
+
+***
+
+### maxSteps?[​](#maxsteps "Direct link to maxSteps?")
+
+```ts
+optional maxSteps: number;
+
+```
+
+***
+
+### maxTokens?[​](#maxtokens "Direct link to maxTokens?")
+
+```ts
+optional maxTokens: number;
+
+```
+
+***
+
+### model?[​](#model "Direct link to model?")
+
+```ts
+optional model: 
+  | string
+  | AgentAdapter
+| Promise<AgentAdapter>;
+
+```
+
+Model adapter (or endpoint-name string sugar for `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional — falls back to the plugin's `defaultModel`.
+
+***
+
+### name?[​](#name "Direct link to name?")
+
+```ts
+optional name: string;
+
+```
+
+Stable identifier for the agent. **Optional and informational** — when the definition is registered via `agents: { foo: def }` (code) or lives at `config/agents/<id>/agent.md` (markdown), the **registry key always wins** and `name` is ignored. The agent will be reachable as `foo` (or `<id>`) regardless of what this field contains.
+
+Set `name` when:
+
+* Running standalone via `runAgent({ agent: def })`, where there is no enclosing key. The runtime uses it for the agent's slot in error messages and OTel spans.
+* Building a definition that may be passed to either form and you want a consistent fallback label.
+
+Setting `name` to a value that differs from the registry key is harmless but confusing — prefer keeping them aligned or omitting `name` entirely.
+
+***
+
+### tools?[​](#tools "Direct link to tools?")
+
+```ts
+optional tools: 
+  | AgentTools
+  | AgentToolsFn;
+
+```
+
+Per-agent tool record. Key is the LLM-visible tool-call name.
+
+Accepts either a plain record (for agents that only use inline tools) or a function `(plugins) => Record<string, AgentTool>` that receives the typed [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map and returns a tool record (for agents that pull tools from registered plugins).
+
+The function is invoked once at agent setup; the result is cached. Don't put per-request logic in there.