feat(appkit): tracing integration for agent plugin

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,32 @@ 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 AI agent powered by the AppKit Agent Plugin.
+                Features{" "}
+                <a
+                  href="https://www.openresponses.org/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                >
+                  OpenResponses
+                </a>
+                -compatible 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,44 @@
+import type { FunctionTool } from "@databricks/appkit";
+
+export const weatherTool: FunctionTool = {
+  type: "function",
+  name: "get_weather",
+  description: "Get the current weather for a location",
+  parameters: {
+    type: "object",
+    properties: {
+      location: {
+        type: "string",
+        description: "City name, e.g. 'San Francisco'",
+      },
+    },
+    required: ["location"],
+  },
+  execute: 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`;
+  },
+};
+
+export const timeTool: FunctionTool = {
+  type: "function",
+  name: "get_current_time",
+  description: "Get the current date and time in a timezone",
+  parameters: {
+    type: "object",
+    properties: {
+      timezone: {
+        type: "string",
+        description: "IANA timezone, e.g. 'America/New_York'. Defaults to UTC",
+      },
+    },
+  },
+  execute: async ({ timezone }) => {
+    const tz = (timezone as string) ?? "UTC";
+    return `Current time in ${tz}: ${new Date().toLocaleString("en-US", { timeZone: tz })}`;
+  },
+};
+
+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,26 @@ 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.",
+      tools: [demoTools.weatherTool],
+    }),
   ],
   ...(process.env.APPKIT_E2E_TEST && { client: createMockClient() }),
-}).then((appkit) => {
+}).then(async (appkit) => {
+  // Add tools after app creation
+  await appkit.agent.addTools([demoTools.timeTool]);
+
   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/Class.StandardAgent.md

@@ -0,0 +1,74 @@
+# Class: StandardAgent
+
+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.
+
+## Implements
+
+- [`AgentInterface`](Interface.AgentInterface.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new StandardAgent(agent: LangGraphAgent, systemPrompt: string): StandardAgent;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `agent` | `LangGraphAgent` |
+| `systemPrompt` | `string` |
+
+#### Returns
+
+`StandardAgent`
+
+## Methods
+
+### invoke()
+
+```ts
+invoke(params: InvokeParams): Promise<ResponseOutputItem[]>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`Promise`\<[`ResponseOutputItem`](TypeAlias.ResponseOutputItem.md)[]\>
+
+#### Implementation of
+
+[`AgentInterface`](Interface.AgentInterface.md).[`invoke`](Interface.AgentInterface.md#invoke)
+
+***
+
+### stream()
+
+```ts
+stream(params: InvokeParams): AsyncGenerator<ResponseStreamEvent>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `params` | [`InvokeParams`](Interface.InvokeParams.md) |
+
+#### Returns
+
+`AsyncGenerator`\<[`ResponseStreamEvent`](TypeAlias.ResponseStreamEvent.md)\>
+
+#### Implementation of
+
+[`AgentInterface`](Interface.AgentInterface.md).[`stream`](Interface.AgentInterface.md#stream)

docs/docs/api/appkit/Function.createInvokeHandler.md

@@ -0,0 +1,18 @@
+# Function: createInvokeHandler()
+
+```ts
+function createInvokeHandler(getAgent: () => AgentInterface): RequestHandler;
+```
+
+Create an Express handler that invokes the agent via the AgentInterface
+and streams/returns the response in Responses API format.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `getAgent` | () => [`AgentInterface`](Interface.AgentInterface.md) |
+
+## Returns
+
+`RequestHandler`

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

@@ -0,0 +1,15 @@
+# Function: isFunctionTool()
+
+```ts
+function isFunctionTool(t: unknown): t is FunctionTool;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `t` | `unknown` |
+
+## Returns
+
+`t is FunctionTool`