diff --git a/apps/dev-playground/server/agent-tools.ts b/apps/dev-playground/server/agent-tools.ts
new file mode 100644
index 00000000..e2a1d5ff
--- /dev/null
+++ b/apps/dev-playground/server/agent-tools.ts
@@ -0,0 +1,52 @@
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { toJSONSchema } from "zod/v4/core";
+
+/**
+ * Workaround: @databricks/langchainjs@0.1.0 calls `schema.toJSONSchema()`
+ * as a method, but zod v4 only exposes it as a standalone function.
+ * Patch the schema so ChatDatabricks can convert it.
+ */
+function patchZodSchema
(schema: T): T {
+ (schema as any).toJSONSchema = () => toJSONSchema(schema);
+ return schema;
+}
+
+export const weatherTool = tool(
+ async ({ location }) => {
+ const conditions = ["sunny", "partly cloudy", "rainy", "windy"];
+ const condition = conditions[Math.floor(Math.random() * conditions.length)];
+ const temp = Math.floor(Math.random() * 30) + 50;
+ return `Weather in ${location}: ${condition}, ${temp}°F`;
+ },
+ {
+ name: "get_weather",
+ description: "Get the current weather for a location",
+ schema: patchZodSchema(
+ z.object({
+ location: z.string().describe("City name, e.g. 'San Francisco'"),
+ }),
+ ),
+ },
+);
+
+export const timeTool = tool(
+ async ({ timezone }) => {
+ const tz = timezone ?? "UTC";
+ return `Current time in ${tz}: ${new Date().toLocaleString("en-US", { timeZone: tz })}`;
+ },
+ {
+ name: "get_current_time",
+ description: "Get the current date and time in a timezone",
+ schema: patchZodSchema(
+ z.object({
+ timezone: z
+ .string()
+ .optional()
+ .describe("IANA timezone, e.g. 'America/New_York'. Defaults to UTC"),
+ }),
+ ),
+ },
+);
+
+export const demoTools = [weatherTool, timeTool];
diff --git a/apps/dev-playground/server/index.ts b/apps/dev-playground/server/index.ts
index d54781ea..2fedf02b 100644
--- a/apps/dev-playground/server/index.ts
+++ b/apps/dev-playground/server/index.ts
@@ -1,6 +1,7 @@
import "reflect-metadata";
-import { analytics, createApp, genie, server } from "@databricks/appkit";
+import { agent, analytics, createApp, genie, server } from "@databricks/appkit";
import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { demoTools } from "./agent-tools";
import { lakebaseExamples } from "./lakebase-examples-plugin";
import { reconnect } from "./reconnect-plugin";
import { telemetryExamples } from "./telemetry-example-plugin";
@@ -25,11 +26,25 @@ createApp({
spaces: { demo: process.env.DATABRICKS_GENIE_SPACE_ID ?? "placeholder" },
}),
lakebaseExamples(),
+ agent({
+ model: process.env.DATABRICKS_MODEL || "databricks-claude-sonnet-4-5",
+ systemPrompt:
+ "You are a helpful assistant. Use tools when appropriate — for example, use get_weather for weather questions, and get_current_time for time queries.",
+ }),
],
...(process.env.APPKIT_E2E_TEST && { client: createMockClient() }),
-}).then((appkit) => {
+}).then(async (appkit) => {
+ // Add tools (and optionally MCP servers) after app creation
+ await appkit.agent.addTools(demoTools);
+
appkit.server
.extend((app) => {
+ // Rewrite to use standard Databricks Apps convention: /invocations at root
+ app.post("/invocations", (req, res) => {
+ req.url = "/api/agent";
+ app(req, res);
+ });
+
app.get("/sp", (_req, res) => {
appkit.analytics
.query("SELECT * FROM samples.nyctaxi.trips;")
diff --git a/docs/docs/api/appkit/Interface.AgentInterface.md b/docs/docs/api/appkit/Interface.AgentInterface.md
new file mode 100644
index 00000000..0736fe32
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.AgentInterface.md
@@ -0,0 +1,43 @@
+# Interface: AgentInterface
+
+Contract that agent implementations must fulfil.
+
+The plugin calls `invoke()` for non-streaming requests and `stream()` for
+SSE streaming. Implementations are responsible for translating their SDK's
+output into Responses API types.
+
+## Methods
+
+### invoke()
+
+```ts
+invoke(params: InvokeParams): Promise;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`Promise`\<`ResponseOutputItem`[]\>
+
+***
+
+### stream()
+
+```ts
+stream(params: InvokeParams): AsyncGenerator;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`AsyncGenerator`\<[`ResponseStreamEvent`](TypeAlias.ResponseStreamEvent.md)\>
diff --git a/docs/docs/api/appkit/Interface.BasePluginConfig.md b/docs/docs/api/appkit/Interface.BasePluginConfig.md
index a7faffc6..1cf97ca0 100644
--- a/docs/docs/api/appkit/Interface.BasePluginConfig.md
+++ b/docs/docs/api/appkit/Interface.BasePluginConfig.md
@@ -2,6 +2,10 @@
Base configuration interface for AppKit plugins
+## Extended by
+
+- [`IAgentConfig`](Interface.IAgentConfig.md)
+
## Indexable
```ts
diff --git a/docs/docs/api/appkit/Interface.IAgentConfig.md b/docs/docs/api/appkit/Interface.IAgentConfig.md
new file mode 100644
index 00000000..2f288c04
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.IAgentConfig.md
@@ -0,0 +1,138 @@
+# Interface: IAgentConfig
+
+Base configuration interface for AppKit plugins.
+
+When you do **not** set `agentInstance`, the agent is built from `model`, `tools`, and `mcpServers`. You can then add more tools or MCP servers after app creation via `appkit.agent.addTools()` and `appkit.agent.addMcpServers()` (see [agent](Variable.agent.md) Plugin API).
+
+## Extends
+
+- [`BasePluginConfig`](Interface.BasePluginConfig.md)
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+### agentInstance?
+
+```ts
+optional agentInstance: AgentInterface;
+```
+
+Pre-built agent implementing AgentInterface.
+When provided the plugin skips internal LangGraph setup and delegates
+directly to this instance. Use this to bring your own agent
+implementation or a different LangChain variant.
+
+---
+
+### host?
+
+```ts
+optional host: string;
+```
+
+#### Inherited from
+
+[`BasePluginConfig`](Interface.BasePluginConfig.md).[`host`](Interface.BasePluginConfig.md#host)
+
+---
+
+### maxTokens?
+
+```ts
+optional maxTokens: number;
+```
+
+Max tokens to generate (default 2000). Ignored when `agentInstance` is provided.
+
+---
+
+### mcpServers?
+
+```ts
+optional mcpServers: DatabricksMCPServer[];
+```
+
+MCP servers for Databricks tool integration. Ignored when `agentInstance` is provided. You can add more at runtime with `appkit.agent.addMcpServers()`.
+
+---
+
+### model?
+
+```ts
+optional model: string;
+```
+
+Databricks model serving endpoint name (e.g. "databricks-claude-sonnet-4-5").
+Falls back to DATABRICKS_MODEL env var.
+Ignored when `agentInstance` is provided.
+
+---
+
+### name?
+
+```ts
+optional name: string;
+```
+
+#### Inherited from
+
+[`BasePluginConfig`](Interface.BasePluginConfig.md).[`name`](Interface.BasePluginConfig.md#name)
+
+---
+
+### systemPrompt?
+
+```ts
+optional systemPrompt: string;
+```
+
+System prompt injected at the start of every conversation
+
+---
+
+### telemetry?
+
+```ts
+optional telemetry: TelemetryOptions;
+```
+
+#### Inherited from
+
+[`BasePluginConfig`](Interface.BasePluginConfig.md).[`telemetry`](Interface.BasePluginConfig.md#telemetry)
+
+---
+
+### temperature?
+
+```ts
+optional temperature: number;
+```
+
+Sampling temperature (0.0-1.0, default 0.1). Ignored when `agentInstance` is provided.
+
+---
+
+### tools?
+
+```ts
+optional tools: StructuredTool[];
+```
+
+Additional LangChain tools to register alongside MCP tools. Ignored when `agentInstance` is provided. You can add more at runtime with `appkit.agent.addTools()`.
+
+---
+
+### useResponsesApi?
+
+```ts
+optional useResponsesApi: boolean;
+```
+
+Whether ChatDatabricks calls the upstream model using the Responses API
+instead of the Chat Completions API. Default: false.
+Ignored when `agentInstance` is provided.
diff --git a/docs/docs/api/appkit/Interface.InvokeParams.md b/docs/docs/api/appkit/Interface.InvokeParams.md
new file mode 100644
index 00000000..f4f360ea
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.InvokeParams.md
@@ -0,0 +1,38 @@
+# Interface: InvokeParams
+
+Agent interface types for the AppKit Agent Plugin.
+
+These types define the contract between the plugin framework and agent
+implementations. They mirror the OpenAI Responses API SSE format without
+requiring the `openai` package as a dependency.
+
+## Properties
+
+### chat\_history?
+
+```ts
+optional chat_history: {
+ content: string;
+ role: string;
+}[];
+```
+
+#### content
+
+```ts
+content: string;
+```
+
+#### role
+
+```ts
+role: string;
+```
+
+***
+
+### input
+
+```ts
+input: string;
+```
diff --git a/docs/docs/api/appkit/Interface.StandardAgent.md b/docs/docs/api/appkit/Interface.StandardAgent.md
new file mode 100644
index 00000000..c1d483e1
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.StandardAgent.md
@@ -0,0 +1,53 @@
+# Interface: StandardAgent
+
+## Implements
+
+- [`AgentInterface`](Interface.AgentInterface.md)
+
+## Methods
+
+### invoke()
+
+```ts
+invoke(params: InvokeParams): Promise;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`Promise`\<`ResponseOutputItem`[]\>
+
+#### Implementation of
+
+```ts
+AgentInterface.invoke
+```
+
+***
+
+### stream()
+
+```ts
+stream(params: InvokeParams): AsyncGenerator;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`AsyncGenerator`\<[`ResponseStreamEvent`](TypeAlias.ResponseStreamEvent.md)\>
+
+#### Implementation of
+
+```ts
+AgentInterface.stream
+```
diff --git a/docs/docs/api/appkit/TypeAlias.ResponseStreamEvent.md b/docs/docs/api/appkit/TypeAlias.ResponseStreamEvent.md
new file mode 100644
index 00000000..4a4fb290
--- /dev/null
+++ b/docs/docs/api/appkit/TypeAlias.ResponseStreamEvent.md
@@ -0,0 +1,11 @@
+# Type Alias: ResponseStreamEvent
+
+```ts
+type ResponseStreamEvent =
+ | ResponseOutputItemAddedEvent
+ | ResponseOutputItemDoneEvent
+ | ResponseTextDeltaEvent
+ | ResponseCompletedEvent
+ | ResponseErrorEvent
+ | ResponseFailedEvent;
+```
diff --git a/docs/docs/api/appkit/Variable.agent.md b/docs/docs/api/appkit/Variable.agent.md
new file mode 100644
index 00000000..0a499cf4
--- /dev/null
+++ b/docs/docs/api/appkit/Variable.agent.md
@@ -0,0 +1,20 @@
+# Variable: agent
+
+```ts
+const agent: ToPlugin;
+```
+
+Plugin factory for the AppKit agent (LangChain/LangGraph). Use in `createApp({ plugins: [agent({ ... })] })`. Configuration: [`IAgentConfig`](Interface.IAgentConfig.md).
+
+## Plugin API (runtime)
+
+After `const appkit = await createApp({ plugins: [..., agent(config)] })`, `appkit.agent` exposes:
+
+| Method | Description |
+| ------ | ------ |
+| `invoke(messages)` | Run the agent (non-streaming). Returns the assistant reply text. |
+| `stream(messages)` | Run the agent with streaming. Yields [`ResponseStreamEvent`](TypeAlias.ResponseStreamEvent.md)s. |
+| `addTools(tools)` | Add LangChain tools after app creation. Rebuilds the agent. **Only when not using `agentInstance`.** |
+| `addMcpServers(servers)` | Add MCP servers after app creation. Rebuilds the agent and MCP client. **Only when not using `agentInstance`.** |
+
+When the plugin is configured with `model` and optional `tools` / `mcpServers` (i.e. without `agentInstance`), you can call `appkit.agent.addTools([...])` and `appkit.agent.addMcpServers([...])` in the `.then()` of `createApp()` to register additional tools or MCP servers at runtime.
diff --git a/docs/docs/api/appkit/index.md b/docs/docs/api/appkit/index.md
index 4ad80820..5356bda8 100644
--- a/docs/docs/api/appkit/index.md
+++ b/docs/docs/api/appkit/index.md
@@ -30,10 +30,13 @@ plugin architecture, and React integration.
| Interface | Description |
| ------ | ------ |
+| [AgentInterface](Interface.AgentInterface.md) | Contract that agent implementations must fulfil. |
| [BasePluginConfig](Interface.BasePluginConfig.md) | Base configuration interface for AppKit plugins |
| [CacheConfig](Interface.CacheConfig.md) | Configuration for caching |
| [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
| [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
+| [IAgentConfig](Interface.IAgentConfig.md) | Base configuration interface for AppKit plugins |
+| [InvokeParams](Interface.InvokeParams.md) | Agent interface types for the AppKit Agent Plugin. |
| [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
| [LakebasePoolConfig](Interface.LakebasePoolConfig.md) | Configuration for creating a Lakebase connection pool |
| [PluginManifest](Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. |
@@ -42,6 +45,7 @@ plugin architecture, and React integration.
| [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
| [ResourceFieldEntry](Interface.ResourceFieldEntry.md) | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key). |
| [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). |
+| [StandardAgent](Interface.StandardAgent.md) | - |
| [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Configuration for streaming execution with default and user-scoped settings |
| [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
| [ValidationResult](Interface.ValidationResult.md) | Result of validating all registered resources against the environment. |
@@ -54,12 +58,14 @@ plugin architecture, and React integration.
| [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
| [PluginData](TypeAlias.PluginData.md) | - |
| [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
+| [ResponseStreamEvent](TypeAlias.ResponseStreamEvent.md) | - |
| [ToPlugin](TypeAlias.ToPlugin.md) | - |
## Variables
| Variable | Description |
| ------ | ------ |
+| [agent](Variable.agent.md) | Agent plugin factory; runtime API includes invoke, stream, addTools, addMcpServers. |
| [sql](Variable.sql.md) | SQL helper namespace |
## Functions
diff --git a/docs/docs/api/appkit/typedoc-sidebar.ts b/docs/docs/api/appkit/typedoc-sidebar.ts
index 2f17b1d2..d4718669 100644
--- a/docs/docs/api/appkit/typedoc-sidebar.ts
+++ b/docs/docs/api/appkit/typedoc-sidebar.ts
@@ -82,6 +82,11 @@ const typedocSidebar: SidebarsConfig = {
type: "category",
label: "Interfaces",
items: [
+ {
+ type: "doc",
+ id: "api/appkit/Interface.AgentInterface",
+ label: "AgentInterface"
+ },
{
type: "doc",
id: "api/appkit/Interface.BasePluginConfig",
@@ -102,6 +107,16 @@ const typedocSidebar: SidebarsConfig = {
id: "api/appkit/Interface.GenerateDatabaseCredentialRequest",
label: "GenerateDatabaseCredentialRequest"
},
+ {
+ type: "doc",
+ id: "api/appkit/Interface.IAgentConfig",
+ label: "IAgentConfig"
+ },
+ {
+ type: "doc",
+ id: "api/appkit/Interface.InvokeParams",
+ label: "InvokeParams"
+ },
{
type: "doc",
id: "api/appkit/Interface.ITelemetry",
@@ -142,6 +157,11 @@ const typedocSidebar: SidebarsConfig = {
id: "api/appkit/Interface.ResourceRequirement",
label: "ResourceRequirement"
},
+ {
+ type: "doc",
+ id: "api/appkit/Interface.StandardAgent",
+ label: "StandardAgent"
+ },
{
type: "doc",
id: "api/appkit/Interface.StreamExecutionSettings",
@@ -183,6 +203,11 @@ const typedocSidebar: SidebarsConfig = {
id: "api/appkit/TypeAlias.ResourcePermission",
label: "ResourcePermission"
},
+ {
+ type: "doc",
+ id: "api/appkit/TypeAlias.ResponseStreamEvent",
+ label: "ResponseStreamEvent"
+ },
{
type: "doc",
id: "api/appkit/TypeAlias.ToPlugin",
@@ -194,6 +219,11 @@ const typedocSidebar: SidebarsConfig = {
type: "category",
label: "Variables",
items: [
+ {
+ type: "doc",
+ id: "api/appkit/Variable.agent",
+ label: "agent"
+ },
{
type: "doc",
id: "api/appkit/Variable.sql",
diff --git a/packages/appkit-ui/src/react/agent-chat/agent-chat-message.tsx b/packages/appkit-ui/src/react/agent-chat/agent-chat-message.tsx
new file mode 100644
index 00000000..a8b3df1f
--- /dev/null
+++ b/packages/appkit-ui/src/react/agent-chat/agent-chat-message.tsx
@@ -0,0 +1,45 @@
+import { AgentChatPart } from "./agent-chat-part";
+import type { ChatMessage } from "./types";
+
+export interface AgentChatMessageProps {
+ message: ChatMessage;
+ isLast?: boolean;
+ isStreaming?: boolean;
+}
+
+/** Renders a single chat message bubble (user or assistant with parts). */
+export function AgentChatMessage({
+ message,
+ isLast = false,
+ isStreaming = false,
+}: AgentChatMessageProps) {
+ if (message.role === "user") {
+ return (
+
+
+ You
+
+
+ {message.content}
+
+
+
+ Agent
+
+
+ {message.parts.map((part, j) => (
+
+ ))}
+
+
+ {part.content}
+ {showCursor && |}
+
+ );
+ }
+
+ if (part.type === "function_call") {
+ return (
+
+
+ Tool: {part.name}
+
+
+ {tryFormatJson(part.arguments)}
+
+
+
+ Result
+
+
+ {tryFormatJson(part.output)}
+
+
+
+
+ {displayMessages.length === 0 && (
+
{emptyMessage}
+ )}
+ {displayMessages.map((msg, i) => (
+
+ ))}
+
+