feat(appkit): modify tools api

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

Author: hubertzub-db

apps/dev-playground/server/agent-tools.ts

@@ -1,37 +1,44 @@
-import { tool } from "@langchain/core/tools";
-import { z } from "zod";
+import type { FunctionTool } from "@databricks/appkit";
 
-export const weatherTool = tool(
-  async ({ location }) => {
+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`;
   },
-  {
-    name: "get_weather",
-    description: "Get the current weather for a location",
-    schema: 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 })}`;
+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",
+      },
+    },
   },
-  {
-    name: "get_current_time",
-    description: "Get the current date and time in a timezone",
-    schema: z.object({
-      timezone: z
-        .string()
-        .optional()
-        .describe("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 };

docs/docs/api/appkit/Interface.FunctionTool.md

@@ -0,0 +1,63 @@
+# Interface: FunctionTool
+
+## Properties
+
+### description?
+
+```ts
+optional description: string | null;
+```
+
+***
+
+### execute()
+
+```ts
+execute: (args: Record<string, unknown>) => string | Promise<string>;
+```
+
+Handler invoked when the model calls this tool.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `args` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+`string` \| `Promise`\<`string`\>
+
+***
+
+### name
+
+```ts
+name: string;
+```
+
+***
+
+### parameters?
+
+```ts
+optional parameters: Record<string, unknown> | null;
+```
+
+JSON Schema object describing the tool's parameters.
+
+***
+
+### strict?
+
+```ts
+optional strict: boolean | null;
+```
+
+***
+
+### type
+
+```ts
+type: "function";
+```

docs/docs/api/appkit/Interface.IAgentConfig.md

@@ -1,8 +1,6 @@
 # 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.addCapabilities()` (see [agent](Variable.agent.md) Plugin API).
+Base configuration interface for AppKit plugins
 
 ## Extends
 
@@ -27,7 +25,7 @@ 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?
 
@@ -39,7 +37,7 @@ optional host: string;
 
 [`BasePluginConfig`](Interface.BasePluginConfig.md).[`host`](Interface.BasePluginConfig.md#host)
 
----
+***
 
 ### maxTokens?
 
@@ -49,17 +47,17 @@ 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.addCapabilities({ mcpServers: [...] })`.
+MCP servers for Databricks tool integration. Ignored when `agentInstance` is provided.
 
----
+***
 
 ### model?
 
@@ -71,7 +69,7 @@ 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?
 
@@ -83,7 +81,7 @@ optional name: string;
 
 [`BasePluginConfig`](Interface.BasePluginConfig.md).[`name`](Interface.BasePluginConfig.md#name)
 
----
+***
 
 ### systemPrompt?
 
@@ -93,7 +91,7 @@ optional systemPrompt: string;
 
 System prompt injected at the start of every conversation
 
----
+***
 
 ### telemetry?
 
@@ -105,7 +103,7 @@ optional telemetry: TelemetryOptions;
 
 [`BasePluginConfig`](Interface.BasePluginConfig.md).[`telemetry`](Interface.BasePluginConfig.md#telemetry)
 
----
+***
 
 ### temperature?
 
@@ -115,17 +113,19 @@ optional temperature: number;
 
 Sampling temperature (0.0-1.0, default 0.1). Ignored when `agentInstance` is provided.
 
----
+***
 
 ### tools?
 
 ```ts
-optional tools: StructuredTool<ToolInputSchemaBase, any, any, any>[];
+optional tools: AgentTool[];
 ```
 
-Additional LangChain tools to register alongside MCP tools. Ignored when `agentInstance` is provided. You can add more at runtime with `appkit.agent.addCapabilities({ tools: [...] })`.
+Tools to register with the agent. Accepts OpenResponses-aligned FunctionTool
+objects or LangChain StructuredToolInterface instances.
+Ignored when `agentInstance` is provided.
 
----
+***
 
 ### useResponsesApi?
 

docs/docs/api/appkit/TypeAlias.AgentTool.md

@@ -0,0 +1,10 @@
+# Type Alias: AgentTool
+
+```ts
+type AgentTool = FunctionTool | StructuredToolInterface;
+```
+
+A tool that can be registered with the agent plugin.
+
+- `FunctionTool` (preferred): OpenResponses-aligned plain object with JSON Schema parameters.
+- `StructuredToolInterface`: LangChain tool for advanced use cases.

docs/docs/api/appkit/Variable.agent.md

@@ -1,21 +1,5 @@
 # Variable: agent
 
 ```ts
-const agent: ToPlugin<typeof AgentPlugin, IAgentConfig, "agent">;
+const agent: ToPlugin<typeof AgentPlugin, IAgentConfig, string>;
 ```
-
-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. |
-| `addCapabilities({ tools?, mcpServers? })` | Batch-add tools and/or MCP servers with a **single** agent rebuild. **Only when not using `agentInstance`.** |
-| `addTools(tools)` | Add LangChain tools after app creation. Rebuilds the agent. Convenience wrapper around `addCapabilities`. **Only when not using `agentInstance`.** |
-| `addMcpServers(servers)` | Add MCP servers after app creation. Rebuilds the agent and MCP client. Convenience wrapper around `addCapabilities`. **Only when not using `agentInstance`.** |
-
-When the plugin is configured with `model` and optional `tools` / `mcpServers` (i.e. without `agentInstance`), prefer `addCapabilities` to register both tools and MCP servers in one call instead of sequential `addTools` + `addMcpServers` (which would rebuild the agent twice).

docs/docs/api/appkit/index.md

@@ -34,6 +34,7 @@ plugin architecture, and React integration.
 | [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 |
+| [FunctionTool](Interface.FunctionTool.md) | - |
 | [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. |
@@ -54,6 +55,7 @@ plugin architecture, and React integration.
 
 | Type Alias | Description |
 | ------ | ------ |
+| [AgentTool](TypeAlias.AgentTool.md) | A tool that can be registered with the agent plugin. |
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
 | [PluginData](TypeAlias.PluginData.md) | - |
@@ -65,7 +67,7 @@ plugin architecture, and React integration.
 
 | Variable | Description |
 | ------ | ------ |
-| [agent](Variable.agent.md) | Agent plugin factory; runtime API includes invoke, stream, addCapabilities, addTools, addMcpServers. |
+| [agent](Variable.agent.md) | - |
 | [sql](Variable.sql.md) | SQL helper namespace |
 
 ## Functions

docs/docs/api/appkit/typedoc-sidebar.ts

@@ -102,6 +102,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.DatabaseCredential",
           label: "DatabaseCredential"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.FunctionTool",
+          label: "FunctionTool"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.GenerateDatabaseCredentialRequest",
@@ -183,6 +188,11 @@ const typedocSidebar: SidebarsConfig = {
       type: "category",
       label: "Type Aliases",
       items: [
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.AgentTool",
+          label: "AgentTool"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ConfigSchema",

packages/appkit/src/index.ts

@@ -51,6 +51,8 @@ export { Plugin, type ToPlugin, toPlugin } from "./plugin";
 export { agent, analytics, files, genie, lakebase, server } from "./plugins";
 export type {
   AgentInterface,
+  AgentTool,
+  FunctionTool,
   IAgentConfig,
   InvokeParams,
   ResponseStreamEvent,