@adminforth/agent 1.23.0 → 1.24.1

package/README.md

@@ -0,0 +1,31 @@
+# AdminForth Agent Plugin
+
+<img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /> <img src="https://woodpecker.devforth.io/api/badges/3848/status.svg" alt="Build Status" /> <a href="https://www.npmjs.com/package/@adminforth/agent"><img src="https://img.shields.io/npm/dm/@adminforth/agent" alt="npm downloads" /></a> <a href="https://www.npmjs.com/package/@adminforth/agent"><img src="https://img.shields.io/npm/v/@adminforth/agent" alt="npm version" /></a>
+
+[![Ask AI](https://tluma.ai/badge)](https://tluma.ai/ask-ai/devforth/adminforth)
+
+Adds a native AI agent to your AdminForth application.
+
+## Features
+
+- Connect AdminForth with native AI agent workflows.
+- Expose API-based tools to agent-driven tasks.
+- Extend back-office operations with custom agent actions.
+- Keep agent capabilities close to your admin logic.
+
+## Documentation
+
+Full setup and configuration guide:
+
+[AdminForth Agent Documentation](https://adminforth.dev/docs/tutorial/Plugins/agent/)
+
+## About AdminForth
+
+AdminForth is an open-source, agent-first admin framework for building robust admin panels and back-office applications faster.
+
+## Related links
+
+- [AdminForth website](https://adminforth.dev)
+- [npm package](https://www.npmjs.com/package/@adminforth/agent)
+- [More AdminForth plugins](https://adminforth.dev/docs/tutorial/ListOfPlugins/)
+- [Built by DevForth](https://devforth.io)

package/agent/middleware/apiBasedTools.ts

@@ -1,7 +1,10 @@
 import { ToolMessage } from "@langchain/core/messages";
 import { createMiddleware } from "langchain";
-import { logger } from "adminforth";
-import { type ApiBasedTool } from "../../apiBasedTools.js";
+import { logger, type AdminUser, type IAdminForth } from "adminforth";
+import {
+  formatApiBasedToolCall,
+  type ApiBasedTool,
+} from "../../apiBasedTools.js";
 import {
   createToolCallTracker,
   type ToolCallEventSink,
@@ -46,6 +49,7 @@ function getEnabledApiToolNames(messages: unknown[]) {
 
 export function createApiBasedToolsMiddleware(
   apiBasedTools: Record<string, ApiBasedTool>,
+  adminforth: IAdminForth,
 ) {
   const alwaysAvailableApiToolNames = new Set<string>(ALWAYS_AVAILABLE_API_TOOL_NAMES);
   const dynamicTools = Object.fromEntries(
@@ -71,14 +75,33 @@ export function createApiBasedToolsMiddleware(
     async wrapToolCall(request, handler) {
       const startedAt = Date.now();
       const toolInput = JSON.stringify(request.toolCall.args ?? {});
-      const { emitToolCallEvent } = request.runtime.context as {
+      const { adminUser, emitToolCallEvent, userTimeZone } = request.runtime.context as {
+        adminUser: AdminUser;
         emitToolCallEvent: ToolCallEventSink;
+        userTimeZone: string;
       };
+      const toolArgs = (request.toolCall.args ?? {}) as Record<string, unknown>;
+      let toolInfo: string | undefined;
+
+      if (request.toolCall.name === "fetch_skill") {
+        toolInfo = `Load ${(toolArgs.skillName as string).split("_").join(" ")} skill`;
+      } else if (request.toolCall.name === "fetch_tool_schema") {
+        toolInfo = `Load ${(toolArgs.toolName as string).split("_").join(" ")} tool `;
+      } else {
+        toolInfo = await formatApiBasedToolCall({
+          adminforth,
+          adminUser,
+          inputs: toolArgs,
+          toolName: request.toolCall.name,
+          userTimeZone,
+        });
+      }
       const toolCallTracker = createToolCallTracker({
         emit: emitToolCallEvent,
         toolCallId: request.toolCall.id,
         toolName: request.toolCall.name,
-        input: (request.toolCall.args ?? {}) as Record<string, unknown>,
+        toolInfo,
+        input: toolArgs,
         startedAt,
       });
       toolCallTracker.start();

package/agent/middleware/sequenceDebug.ts

@@ -122,11 +122,32 @@ function finalizeSequenceDebug(sequence: PendingSequenceDebug): SequenceDebug {
 }
 
 type OpenAiResponsesDebugModel = {
-  model: string;
+  getName?: () => string;
+  model?: string;
   zdrEnabled?: boolean;
-  invocationParams: (options?: Record<string, unknown>) => Record<string, unknown>;
+  _defaultConfig?: {
+    modelProvider?: string;
+  };
+  invocationParams?: (options?: Record<string, unknown>) => Record<string, unknown>;
 };
 
+function getDebugModelName(model: OpenAiResponsesDebugModel) {
+  return typeof model.getName === "function" ? model.getName() : undefined;
+}
+
+function supportsOpenAiResponseDebug(
+  model: OpenAiResponsesDebugModel,
+): model is OpenAiResponsesDebugModel & {
+  model: string;
+  invocationParams: (options?: Record<string, unknown>) => Record<string, unknown>;
+} {
+  return (
+    getDebugModelName(model) === "ChatOpenAI" &&
+    typeof model.model === "string" &&
+    typeof model.invocationParams === "function"
+  );
+}
+
 function stringifyPromptForDebug(params: {
   model: OpenAiResponsesDebugModel;
   systemMessage: { text: string };
@@ -137,6 +158,22 @@ function stringifyPromptForDebug(params: {
 }) {
   const { model, systemMessage, messages, tools, toolChoice, modelSettings } = params;
 
+  if (!supportsOpenAiResponseDebug(model)) {
+    return YAML.stringify({
+      model: {
+        name: getDebugModelName(model) ?? null,
+        provider: model._defaultConfig?.modelProvider ?? null,
+        configuredModel:
+          typeof model.model === "string" ? model.model : null,
+      },
+      systemMessage,
+      messages,
+      ...(tools.length > 0 ? { tools } : {}),
+      ...(toolChoice !== undefined ? { toolChoice } : {}),
+      ...(modelSettings ? { modelSettings } : {}),
+    });
+  }
+
   return YAML.stringify({
     input: convertMessagesToResponsesInput({
       messages: [

package/agent/simpleAgent.ts

@@ -1,10 +1,19 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { createAgent, summarizationMiddleware } from "langchain";
-import { logger, type AdminUser, type CompletionAdapter } from "adminforth";
+import {
+  MODEL_PROVIDER_CONFIG,
+  getChatModelByClassName,
+} from "langchain/chat_models/universal";
+import {
+  logger,
+  type AdminUser,
+  type CompletionAdapter,
+  type IAdminForth,
+} from "adminforth";
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
 import {type BaseCheckpointSaver, type Messages } from "@langchain/langgraph";
 import type { LLMResult } from "@langchain/core/outputs";
 import { z } from "zod";
-import { ChatOpenAI } from "@langchain/openai";
 import { createAgentTools } from "./tools/index.js";
 import { createApiBasedToolsMiddleware } from "./middleware/apiBasedTools.js";
 import {
@@ -23,9 +32,24 @@ export const contextSchema = z.object({
   emitToolCallEvent: z.custom<ToolCallEventSink>(),
 });
 
-type OpenAIBackedCompletionAdapter = CompletionAdapter & {
+export type AgentModelProvider = "openai" | "anthropic" | "google-genai";
+export type AgentChatModel = BaseChatModel<any, any>;
+
+type ProviderBackedCompletionAdapter = CompletionAdapter & {
+  constructor?: {
+    name?: string;
+  };
   options?: {
     openAiApiKey?: string;
+    openAIApiKey?: string;
+    anthropicApiKey?: string;
+    geminiApiKey?: string;
+    googleApiKey?: string;
+    googleGenAiApiKey?: string;
+    googleGenerativeAiApiKey?: string;
+    apiKey?: string;
+    provider?: string;
+    modelProvider?: string;
     model?: string;
     baseURL?: string;
     baseUrl?: string;
@@ -34,7 +58,9 @@ type OpenAIBackedCompletionAdapter = CompletionAdapter & {
   };
 };
 
-type OpenAiReasoningConfig = Record<string, unknown>;
+type AgentChatModelConstructor = new (
+  fields?: Record<string, unknown>,
+) => AgentChatModel;
 
 type LlmOutputTokenUsage = {
   promptTokens?: unknown;
@@ -51,6 +77,233 @@ type PendingLlmRun = {
   firstTokenAt?: number;
 };
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function normalizeProvider(value: unknown): AgentModelProvider | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const normalized = value.toLowerCase().replace(/[_\s]+/g, "-");
+
+  if (["openai", "open-ai"].includes(normalized)) {
+    return "openai";
+  }
+
+  if (["anthropic", "claude"].includes(normalized)) {
+    return "anthropic";
+  }
+
+  if (
+    [
+      "google",
+      "gemini",
+      "google-genai",
+      "google-gemini",
+      "google-generative-ai",
+      "google-generativeai",
+    ].includes(normalized)
+  ) {
+    return "google-genai";
+  }
+
+  return undefined;
+}
+
+function detectProviderFromConstructorName(
+  constructorName: string | undefined,
+): AgentModelProvider | undefined {
+  const normalized = constructorName?.toLowerCase();
+
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (normalized.includes("openai")) {
+    return "openai";
+  }
+
+  if (normalized.includes("anthropic") || normalized.includes("claude")) {
+    return "anthropic";
+  }
+
+  if (normalized.includes("gemini") || normalized.includes("google")) {
+    return "google-genai";
+  }
+
+  return undefined;
+}
+
+function detectProviderFromModelName(
+  model: string | undefined,
+): AgentModelProvider | undefined {
+  const normalized = model?.toLowerCase();
+
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (normalized.startsWith("claude")) {
+    return "anthropic";
+  }
+
+  if (normalized.startsWith("gemini")) {
+    return "google-genai";
+  }
+
+  if (/^(gpt|o[1-9]|chatgpt)/.test(normalized)) {
+    return "openai";
+  }
+
+  return undefined;
+}
+
+function detectAgentModelProvider(
+  adapter: ProviderBackedCompletionAdapter,
+): AgentModelProvider {
+  const options = adapter.options ?? {};
+
+  return (
+    normalizeProvider(options.modelProvider) ??
+    normalizeProvider(options.provider) ??
+    detectProviderFromConstructorName(adapter.constructor?.name) ??
+    (options.openAiApiKey || options.openAIApiKey
+      ? "openai"
+      : undefined) ??
+    (options.anthropicApiKey ? "anthropic" : undefined) ??
+    (options.geminiApiKey ||
+    options.googleApiKey ||
+    options.googleGenAiApiKey ||
+    options.googleGenerativeAiApiKey
+      ? "google-genai"
+      : undefined) ??
+    detectProviderFromModelName(options.model) ??
+    (() => {
+      throw new Error(
+        "Could not infer completion adapter provider. Set options.modelProvider to openai, anthropic, or google-genai.",
+      );
+    })()
+  );
+}
+
+function getProviderApiKey(
+  provider: AgentModelProvider,
+  options: ProviderBackedCompletionAdapter["options"],
+) {
+  switch (provider) {
+    case "openai":
+      return options?.openAiApiKey ?? options?.openAIApiKey ?? options?.apiKey;
+    case "anthropic":
+      return options?.anthropicApiKey ?? options?.apiKey;
+    case "google-genai":
+      return (
+        options?.geminiApiKey ??
+        options?.googleApiKey ??
+        options?.googleGenAiApiKey ??
+        options?.googleGenerativeAiApiKey ??
+        options?.apiKey
+      );
+  }
+}
+
+function getProviderModel(
+  provider: AgentModelProvider,
+  options: ProviderBackedCompletionAdapter["options"],
+) {
+  if (options?.model) {
+    return options.model;
+  }
+
+  if (provider === "openai") {
+    return "gpt-5-nano";
+  }
+
+  if (provider === "google-genai") {
+    return "gemini-3-flash-preview";
+  }
+
+  throw new Error(
+    `CompletionAdapter for provider ${provider} must expose options.model`,
+  );
+}
+
+function buildChatModelConfig(params: {
+  provider: AgentModelProvider;
+  options: ProviderBackedCompletionAdapter["options"];
+  maxTokens: number;
+}) {
+  const { provider, options, maxTokens } = params;
+  const apiKey = getProviderApiKey(provider, options);
+
+  if (!apiKey) {
+    const optionName =
+      provider === "openai"
+        ? "options.openAiApiKey"
+        : provider === "anthropic"
+          ? "options.anthropicApiKey"
+          : "options.geminiApiKey";
+
+    throw new Error(
+      `CompletionAdapter must expose ${optionName} for ${provider} agent mode`,
+    );
+  }
+
+  const model = getProviderModel(provider, options);
+  const baseURL = options?.baseURL ?? options?.baseUrl;
+  const extraRequestBodyParameters = {
+    ...(options?.extraRequestBodyParameters ?? {}),
+  };
+
+  if (provider === "openai" && isRecord(extraRequestBodyParameters.reasoning)) {
+    extraRequestBodyParameters.reasoning = {
+      ...extraRequestBodyParameters.reasoning,
+      summary: "auto",
+    };
+  }
+
+  const config: Record<string, unknown> = {
+    model,
+    apiKey,
+    maxTokens,
+    streaming: true,
+    ...extraRequestBodyParameters,
+  };
+
+  if (typeof options?.timeoutMs === "number") {
+    config.timeout = options.timeoutMs;
+  }
+
+  if (baseURL) {
+    config.baseURL = baseURL;
+    config.baseUrl = baseURL;
+    config.configuration = {
+      baseURL,
+    };
+  }
+
+  if (provider === "openai") {
+    config.openAIApiKey = apiKey;
+    config.useResponsesApi = true;
+    config.outputVersion = "v1";
+    config.promptCacheKey = `adminforth-agent:${model}:system-v1:tools-v1`;
+    config.promptCacheRetention = "in_memory";
+  }
+
+  if (provider === "anthropic") {
+    config.anthropicApiKey = apiKey;
+  }
+
+  if (provider === "google-genai") {
+    config.geminiApiKey = apiKey;
+    config.googleApiKey = apiKey;
+    config.maxOutputTokens = maxTokens;
+  }
+
+  return { model, config };
+}
+
 function getFiniteNumber(value: unknown) {
   return typeof value === "number" && Number.isFinite(value)
     ? value
@@ -162,63 +415,39 @@ function createAgentLlmMetricsLogger() {
   return new AgentLlmMetricsLogger();
 }
 
-export function createAgentChatModel(params: {
+export async function createAgentChatModel(params: {
   adapter: CompletionAdapter;
   maxTokens: number;
 }) {
-  const adapter = params.adapter as OpenAIBackedCompletionAdapter;
+  const adapter = params.adapter as ProviderBackedCompletionAdapter;
   const options = adapter.options ?? {};
-
-  if (!options.openAiApiKey) {
-    throw new Error(
-      "CompletionAdapter must expose options.openAiApiKey for ChatOpenAI",
-    );
-  }
-
-  const model = options.model ?? "gpt-5-nano";
-  const baseURL = options.baseURL ?? options.baseUrl;
-  const reasoning = options.extraRequestBodyParameters
-    ?.reasoning as OpenAiReasoningConfig | undefined;
-  const reasoningConfig = reasoning
-    ? {
-        ...reasoning,
-        summary: "auto",
-      }
-    : undefined;
-
-  // @ts-ignore
-  return new ChatOpenAI({
-    apiKey: options.openAiApiKey,
-    model,
+  const provider = detectAgentModelProvider(adapter);
+  const { config } = buildChatModelConfig({
+    provider,
+    options,
     maxTokens: params.maxTokens,
-    useResponsesApi: true,
-    outputVersion: "v1",
-    streaming: true,
-
-    promptCacheKey: `adminforth-agent:${model}:system-v1:tools-v1`,
-    promptCacheRetention: "in_memory", 
-
-    ...(reasoningConfig ? { reasoning: reasoningConfig } : {}),
-    ...(typeof options.timeoutMs === "number"
-      ? { timeout: options.timeoutMs }
-      : {}),
-    ...(baseURL
-      ? {
-          configuration: {
-            baseURL,
-          },
-        }
-      : {}),
   });
+  const className = MODEL_PROVIDER_CONFIG[provider].className;
+  const ChatModelClass = await getChatModelByClassName(
+    className,
+    provider,
+  ) as AgentChatModelConstructor;
+
+  return {
+    model: new ChatModelClass(config),
+    provider,
+  };
 }
 
 export async function callAgent(params: {
   name: string;
-  model: ChatOpenAI;
-  summaryModel: ChatOpenAI;
+  model: AgentChatModel;
+  summaryModel: AgentChatModel;
+  modelProvider: AgentModelProvider;
   checkpointer?: BaseCheckpointSaver;
   messages: Messages;
   adminUser: AdminUser;
+  adminforth: IAdminForth;
   apiBasedTools: Record<string, ApiBasedTool>;
   customComponentsDir: string;
   sessionId: string;
@@ -231,9 +460,11 @@ export async function callAgent(params: {
     name,
     model,
     summaryModel,
+    modelProvider,
     checkpointer,
     messages,
     adminUser,
+    adminforth,
     apiBasedTools,
     customComponentsDir,
     sessionId,
@@ -244,16 +475,16 @@ export async function callAgent(params: {
   } = params;
 
   const tools = await createAgentTools(customComponentsDir, apiBasedTools);
-  const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(apiBasedTools);
-  const openAiResponsesContinuationMiddleware =
-    createOpenAiResponsesContinuationMiddleware();
+  const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(apiBasedTools, adminforth);
   const sequenceDebugMiddleware = createSequenceDebugMiddleware(
     sequenceDebugSink,
   );
 
   const middleware = [
     apiBasedToolsMiddleware,
-    openAiResponsesContinuationMiddleware,
+    ...(modelProvider === "openai"
+      ? [createOpenAiResponsesContinuationMiddleware()]
+      : []),
     sequenceDebugMiddleware,
     summarizationMiddleware({
       model: summaryModel,

package/agent/toolCallEvents.ts

@@ -6,6 +6,7 @@ export type ToolCallEvent =
   | {
       toolCallId: string;
       toolName: string;
+      toolInfo?: string;
       phase: "start";
       input: string;
     }
@@ -64,6 +65,7 @@ export function createToolCallTracker(params: {
   emit: ToolCallEventSink;
   toolCallId?: string;
   toolName: string;
+  toolInfo?: string;
   input?: Record<string, unknown>;
   startedAt?: number;
 }) {
@@ -75,6 +77,7 @@ export function createToolCallTracker(params: {
       params.emit({
         toolCallId,
         toolName: params.toolName,
+        toolInfo: params.toolInfo,
         phase: "start",
         input: YAML.stringify(params.input ?? {}),
       });