feat(appkit): add AgentPlugin for LangChain/LangGraph agents

Signed-off-by: Hubert Zub <hubert.zub@databricks.com>

Author: hubertzub-db

apps/dev-playground/.env.dist

@@ -9,6 +9,7 @@ OTEL_SERVICE_NAME='dev-playground'
 DATABRICKS_VOLUME_PLAYGROUND=
 DATABRICKS_VOLUME_OTHER=
 DATABRICKS_GENIE_SPACE_ID=
+DATABRICKS_MODEL=
 LAKEBASE_ENDPOINT='' # Run: databricks postgres list-endpoints projects/{project-id}/branches/{branch-id} — use the `name` field from the output
 PGHOST=
 PGUSER=

apps/dev-playground/client/src/routeTree.gen.ts

@@ -20,6 +20,7 @@ import { Route as DataVisualizationRouteRouteImport } from './routes/data-visual
 import { Route as ChartInferenceRouteRouteImport } from './routes/chart-inference.route'
 import { Route as ArrowAnalyticsRouteRouteImport } from './routes/arrow-analytics.route'
 import { Route as AnalyticsRouteRouteImport } from './routes/analytics.route'
+import { Route as AgentRouteRouteImport } from './routes/agent.route'
 import { Route as IndexRouteImport } from './routes/index'
 
 const TypeSafetyRouteRoute = TypeSafetyRouteRouteImport.update({
@@ -77,6 +78,11 @@ const AnalyticsRouteRoute = AnalyticsRouteRouteImport.update({
   path: '/analytics',
   getParentRoute: () => rootRouteImport,
 } as any)
+const AgentRouteRoute = AgentRouteRouteImport.update({
+  id: '/agent',
+  path: '/agent',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -85,6 +91,7 @@ const IndexRoute = IndexRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/agent': typeof AgentRouteRoute
   '/analytics': typeof AnalyticsRouteRoute
   '/arrow-analytics': typeof ArrowAnalyticsRouteRoute
   '/chart-inference': typeof ChartInferenceRouteRoute
@@ -99,6 +106,7 @@ export interface FileRoutesByFullPath {
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/agent': typeof AgentRouteRoute
   '/analytics': typeof AnalyticsRouteRoute
   '/arrow-analytics': typeof ArrowAnalyticsRouteRoute
   '/chart-inference': typeof ChartInferenceRouteRoute
@@ -114,6 +122,7 @@ export interface FileRoutesByTo {
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/agent': typeof AgentRouteRoute
   '/analytics': typeof AnalyticsRouteRoute
   '/arrow-analytics': typeof ArrowAnalyticsRouteRoute
   '/chart-inference': typeof ChartInferenceRouteRoute
@@ -130,6 +139,7 @@ export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
+    | '/agent'
     | '/analytics'
     | '/arrow-analytics'
     | '/chart-inference'
@@ -144,6 +154,7 @@ export interface FileRouteTypes {
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
+    | '/agent'
     | '/analytics'
     | '/arrow-analytics'
     | '/chart-inference'
@@ -158,6 +169,7 @@ export interface FileRouteTypes {
   id:
     | '__root__'
     | '/'
+    | '/agent'
     | '/analytics'
     | '/arrow-analytics'
     | '/chart-inference'
@@ -173,6 +185,7 @@ export interface FileRouteTypes {
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  AgentRouteRoute: typeof AgentRouteRoute
   AnalyticsRouteRoute: typeof AnalyticsRouteRoute
   ArrowAnalyticsRouteRoute: typeof ArrowAnalyticsRouteRoute
   ChartInferenceRouteRoute: typeof ChartInferenceRouteRoute
@@ -265,6 +278,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AnalyticsRouteRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/agent': {
+      id: '/agent'
+      path: '/agent'
+      fullPath: '/agent'
+      preLoaderRoute: typeof AgentRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -277,6 +297,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  AgentRouteRoute: AgentRouteRoute,
   AnalyticsRouteRoute: AnalyticsRouteRoute,
   ArrowAnalyticsRouteRoute: ArrowAnalyticsRouteRoute,
   ChartInferenceRouteRoute: ChartInferenceRouteRoute,

apps/dev-playground/client/src/routes/__root.tsx

@@ -104,6 +104,14 @@ function RootComponent() {
                     Files
                   </Button>
                 </Link>
+                <Link to="/agent" className="no-underline">
+                  <Button
+                    variant="ghost"
+                    className="text-foreground hover:text-secondary-foreground"
+                  >
+                    Agent
+                  </Button>
+                </Link>
                 <ThemeSelector />
               </div>
             </nav>

apps/dev-playground/client/src/routes/agent.route.tsx

@@ -0,0 +1,31 @@
+import { AgentChat } from "@databricks/appkit-ui/react";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/agent")({
+  component: AgentChatRoute,
+});
+
+function AgentChatRoute() {
+  return (
+    <div className="min-h-screen bg-background">
+      <main className="max-w-2xl mx-auto px-6 py-12 flex flex-col h-[calc(100vh-6rem)]">
+        <div className="mb-6">
+          <h1 className="text-3xl font-bold tracking-tight text-foreground">
+            Agent Chat
+          </h1>
+          <p className="text-muted-foreground mt-1">
+            Chat with the agent via <code>POST /invocations</code> (Responses
+            API SSE stream).
+          </p>
+        </div>
+
+        <AgentChat
+          invokeUrl="/invocations"
+          placeholder="Type a message..."
+          emptyMessage="Send a message to start."
+          className="flex-1 min-h-0"
+        />
+      </main>
+    </div>
+  );
+}

apps/dev-playground/client/src/routes/index.tsx

@@ -218,6 +218,25 @@ function IndexRoute() {
               </Button>
             </div>
           </Card>
+
+          <Card className="p-6 hover:shadow-lg transition-shadow cursor-pointer">
+            <div className="flex flex-col h-full">
+              <h3 className="text-2xl font-semibold text-foreground mb-3">
+                Agent Chat
+              </h3>
+              <p className="text-muted-foreground mb-6 flex-grow">
+                Chat with a LangChain/LangGraph AI agent powered by the AppKit
+                Agent Plugin. Features Responses API SSE streaming and tool call
+                rendering.
+              </p>
+              <Button
+                onClick={() => navigate({ to: "/agent" })}
+                className="w-full"
+              >
+                Try Agent Chat
+              </Button>
+            </div>
+          </Card>
         </div>
 
         <div className="text-center pt-12 border-t border-border">

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<T extends z.ZodType>(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];

apps/dev-playground/server/index.ts

@@ -1,6 +1,14 @@
 import "reflect-metadata";
-import { analytics, createApp, files, genie, server } from "@databricks/appkit";
+import {
+  agent,
+  analytics,
+  createApp,
+  files,
+  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";
@@ -26,11 +34,25 @@ createApp({
     }),
     lakebaseExamples(),
     files(),
+    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;")

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<ResponseOutputItem[]>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`Promise`\<`ResponseOutputItem`[]\>
+
+***
+
+### stream()
+
+```ts
+stream(params: InvokeParams): AsyncGenerator<ResponseStreamEvent>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`AsyncGenerator`\<[`ResponseStreamEvent`](TypeAlias.ResponseStreamEvent.md)\>

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