plugin-flow-builder: use an ai agent from flow builder #BLT-1644 (#3022)

## Description

- Add node of type AiAgent
- Add Ai Agents flow
- Infer getAiAgentResponse by plugin constructor from bot plugins
- Use getAiAgentResponse to create text messages from ai agent

## Context

In bot you should pass the getAiAgentResponse to flow builder, the same
way as getKnowledgeBaseResponse:

src/server/config.ts
```typescript
...

function getFlowBuilderConfig(
  env: ENVIRONMENT
): BotonicPluginFlowBuilderOptions<BotPlugins, UserData> {
  return {
    getAccessToken: () => '82ff9243e97ad293705424e358866b', // Used locally,
    trackEvent: async (request: BotRequest, eventName, args) => {
      await trackEvent(request, eventName, args)
    },
    getAiAgentResponse: async (
      request: BotRequest,
      aiAgentArgs: {
        name: string
        instructions: string
      }
    ) => {
      const aiAgentPlugin = request.plugins.aiAgent
      return await aiAgentPlugin.getInference(request, aiAgentArgs)
    },
    getKnowledgeBaseResponse: async (
 ...
  }
}
```

## Testing

Add a test to check basic usage of AiAgent node

Author: Iru89

package-lock.json

@@ -1,6 +1,6 @@
 {
-  "name": "botonic-plugin-ai-agents",
-  "version": "0.36.0",
+  "name": "@botonic/plugin-ai-agents",
+  "version": "0.36.0-alpha.0",
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
   "description": "Use AI Agents to generate your contents",

packages/botonic-plugin-ai-agents/package.json

@@ -10,10 +10,12 @@ All notable changes to Botonic will be documented in this file.
     Click to see more.
   </summary>
 
-## [0.35.x] - 2025-mm-dd
+## [0.36.x] - 2025-mm-dd
 
 ### Added
 
+- [PR-3022](https://github.com/hubtype/botonic/pull/3022): Add an ai agent from flow builder.
+
 ### Changed
 
 ### Fixed

packages/botonic-plugin-flow-builder/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "@botonic/plugin-flow-builder",
-  "version": "0.35.2",
+  "version": "0.36.0-alpha.0",
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
   "description": "Use Flow Builder to show your contents",

packages/botonic-plugin-flow-builder/package.json

@@ -0,0 +1,52 @@
+import { FlowContent } from '../content-fields'
+import { FlowAiAgent } from '../content-fields/flow-ai-agent'
+import { AiAgentResponse } from '../types'
+import { FlowBuilderContext } from './index'
+
+export async function getContentsByAiAgent({
+  cmsApi,
+  flowBuilderPlugin,
+  request,
+}: FlowBuilderContext): Promise<FlowContent[]> {
+  const startNodeAiAgentFlow = cmsApi.getStartNodeAiAgentFlow()
+  if (!startNodeAiAgentFlow) {
+    return []
+  }
+
+  const contents =
+    await flowBuilderPlugin.getContentsByNode(startNodeAiAgentFlow)
+  const aiAgentContent = contents.find(
+    content => content instanceof FlowAiAgent
+  ) as FlowAiAgent
+
+  if (!aiAgentContent) {
+    return []
+  }
+
+  const aiAgentResponse = await flowBuilderPlugin.getAiAgentResponse?.(
+    request,
+    {
+      name: aiAgentContent.name,
+      instructions: aiAgentContent.instructions,
+    }
+  )
+
+  if (!aiAgentResponse) {
+    return []
+  }
+
+  return updateContentsWithAiAgentResponse(contents, aiAgentResponse)
+}
+
+function updateContentsWithAiAgentResponse(
+  contents: FlowContent[],
+  aiAgentResponse: AiAgentResponse
+): FlowContent[] {
+  return contents.map(content => {
+    if (content instanceof FlowAiAgent) {
+      content.text = aiAgentResponse.message.content
+    }
+
+    return content
+  })
+}

packages/botonic-plugin-flow-builder/src/action/ai-agent.ts

@@ -9,6 +9,7 @@ import { getFlowBuilderPlugin } from '../helpers'
 import BotonicPluginFlowBuilder from '../index'
 import { trackFlowContent } from '../tracking'
 import { inputHasTextData } from '../utils'
+import { getContentsByAiAgent } from './ai-agent'
 import { getContentsByFallback } from './fallback'
 import { getContentsByFirstInteraction } from './first-interaction'
 import { getContentsByKnowledgeBase } from './knowledge-bases'
@@ -106,6 +107,10 @@ async function getContents(
   }
 
   if (inputHasTextData(request.input)) {
+    const aiAgentContents = await getContentsByAiAgent(context)
+    if (aiAgentContents.length > 0) {
+      return aiAgentContents
+    }
     const knowledgeBaseContents = await getContentsByKnowledgeBase(context)
     if (knowledgeBaseContents.length > 0) {
       return knowledgeBaseContents

packages/botonic-plugin-flow-builder/src/action/index.tsx

@@ -1,7 +1,12 @@
 import { Input, PluginPreRequest } from '@botonic/core'
 import axios from 'axios'
 
-import { KNOWLEDGE_BASE_FLOW_NAME, SEPARATOR, UUID_REGEXP } from './constants'
+import {
+  AI_AGENTS_FLOW_NAME,
+  KNOWLEDGE_BASE_FLOW_NAME,
+  SEPARATOR,
+  UUID_REGEXP,
+} from './constants'
 import {
   HtBotActionNode,
   HtFallbackNode,
@@ -202,6 +207,18 @@ export class FlowBuilderApi {
     return this.getNodeById<HtNodeWithContent>(knowledgeBaseFlow.start_node_id)
   }
 
+  getStartNodeAiAgentFlow(): HtNodeWithContent | undefined {
+    const aiAgentFlow = this.flow.flows.find(
+      flow => flow.name === AI_AGENTS_FLOW_NAME
+    )
+
+    if (!aiAgentFlow) {
+      return undefined
+    }
+
+    return this.getNodeById<HtNodeWithContent>(aiAgentFlow.start_node_id)
+  }
+
   isKnowledgeBaseEnabled(): boolean {
     return this.flow.is_knowledge_base_active || false
   }

packages/botonic-plugin-flow-builder/src/api.ts

@@ -10,4 +10,5 @@ export const UUID_REGEXP =
 
 export const MAIN_FLOW_NAME = 'Main'
 export const KNOWLEDGE_BASE_FLOW_NAME = 'Knowledge base'
+export const AI_AGENTS_FLOW_NAME = 'AI agents'
 export const FALLBACK_FLOW_NAME = 'Fallback'

packages/botonic-plugin-flow-builder/src/constants.ts

@@ -0,0 +1,23 @@
+import { Text } from '@botonic/react'
+
+import { ContentFieldsBase } from './content-fields-base'
+import { HtAiAgentNode } from './hubtype-fields/ai-agent'
+
+export class FlowAiAgent extends ContentFieldsBase {
+  public code: string = ''
+  public name: string = ''
+  public instructions: string = ''
+  public text: string = ''
+
+  static fromHubtypeCMS(component: HtAiAgentNode): FlowAiAgent {
+    const newAiAgent = new FlowAiAgent(component.id)
+    newAiAgent.name = component.content.name
+    newAiAgent.instructions = component.content.instructions
+
+    return newAiAgent
+  }
+
+  toBotonic(id: string): JSX.Element {
+    return <Text key={id}>{this.text}</Text>
+  }
+}

packages/botonic-plugin-flow-builder/src/content-fields/flow-ai-agent.tsx

@@ -0,0 +1,10 @@
+import { HtBaseNode } from './common'
+import { HtNodeWithContentType } from './node-types'
+
+export interface HtAiAgentNode extends HtBaseNode {
+  type: HtNodeWithContentType.AI_AGENT
+  content: {
+    name: string
+    instructions: string
+  }
+}

packages/botonic-plugin-flow-builder/src/content-fields/hubtype-fields/ai-agent.ts

@@ -12,6 +12,7 @@ export enum HtNodeWithContentType {
   WHATSAPP_CTA_URL_BUTTON = 'whatsapp-cta-url-button',
   KNOWLEDGE_BASE = 'knowledge-base',
   BOT_ACTION = 'bot-action',
+  AI_AGENT = 'ai-agent',
 }
 
 export enum HtNodeWithoutContentType {

packages/botonic-plugin-flow-builder/src/content-fields/hubtype-fields/node-types.ts

@@ -1,3 +1,4 @@
+import { HtAiAgentNode } from './ai-agent'
 import { HtBotActionNode } from './bot-action'
 import { HtCarouselNode } from './carousel'
 import { HtFallbackNode } from './fallback'
@@ -29,6 +30,7 @@ export type HtNodeWithContent =
   | HtSmartIntentNode
   | HtKnowledgeBaseNode
   | HtBotActionNode
+  | HtAiAgentNode
 
 export type HtNodeWithoutContent = HtUrlNode | HtPayloadNode | HtGoToFlow
 

packages/botonic-plugin-flow-builder/src/content-fields/hubtype-fields/nodes.ts

@@ -1,3 +1,4 @@
+import { FlowAiAgent } from './flow-ai-agent'
 import { FlowBotAction } from './flow-bot-action'
 import { FlowCarousel } from './flow-carousel'
 import { FlowHandoff } from './flow-handoff'
@@ -10,21 +11,21 @@ import { FlowText } from './flow-text'
 import { FlowVideo } from './flow-video'
 import { FlowWhatsappCtaUrlButtonNode } from './flow-whatsapp-cta-url-button'
 import { FlowWhatsappButtonList } from './whatsapp-button-list/flow-whatsapp-button-list'
-
 export { ContentFieldsBase } from './content-fields-base'
 export { FlowButton } from './flow-button'
 export { FlowElement } from './flow-element'
 export {
+  FlowAiAgent,
   FlowBotAction,
   FlowCarousel,
+  FlowHandoff,
   FlowImage,
   FlowKnowledgeBase,
   FlowText,
   FlowVideo,
   FlowWhatsappButtonList,
+  FlowWhatsappCtaUrlButtonNode,
 }
-export { FlowHandoff } from './flow-handoff'
-export { FlowWhatsappCtaUrlButtonNode } from './flow-whatsapp-cta-url-button'
 
 export type FlowContent =
   | FlowCarousel
@@ -36,5 +37,6 @@ export type FlowContent =
   | FlowHandoff
   | FlowKnowledgeBase
   | FlowBotAction
+  | FlowAiAgent
 
 export { DISABLED_MEMORY_LENGTH }

packages/botonic-plugin-flow-builder/src/content-fields/index.ts

@@ -14,6 +14,7 @@ import {
   SOURCE_INFO_SEPARATOR,
 } from './constants'
 import {
+  FlowAiAgent,
   FlowBotAction,
   FlowCarousel,
   FlowContent,
@@ -37,6 +38,7 @@ import {
 } from './content-fields/hubtype-fields'
 import { DEFAULT_FUNCTIONS } from './functions'
 import {
+  AiAgentFunction,
   BotonicPluginFlowBuilderOptions,
   FlowBuilderJSONVersion,
   InShadowingConfig,
@@ -58,6 +60,7 @@ export default class BotonicPluginFlowBuilder implements Plugin {
   public getAccessToken: (session: Session) => string
   public trackEvent?: TrackEventFunction
   public getKnowledgeBaseResponse?: KnowledgeBaseFunction
+  public getAiAgentResponse?: AiAgentFunction
   public smartIntentsConfig: SmartIntentsInferenceConfig
   public inShadowing: InShadowingConfig
 
@@ -72,6 +75,7 @@ export default class BotonicPluginFlowBuilder implements Plugin {
     this.getAccessToken = resolveGetAccessToken(options.getAccessToken)
     this.trackEvent = options.trackEvent
     this.getKnowledgeBaseResponse = options.getKnowledgeBaseResponse
+    this.getAiAgentResponse = options.getAiAgentResponse
     this.smartIntentsConfig = {
       ...options?.smartIntentsConfig,
       useLatest: this.jsonVersion === FlowBuilderJSONVersion.LATEST,
@@ -230,6 +234,9 @@ export default class BotonicPluginFlowBuilder implements Plugin {
       case HtNodeWithContentType.KNOWLEDGE_BASE:
         return FlowKnowledgeBase.fromHubtypeCMS(hubtypeContent)
 
+      case HtNodeWithContentType.AI_AGENT:
+        return FlowAiAgent.fromHubtypeCMS(hubtypeContent)
+
       case HtNodeWithContentType.BOT_ACTION:
         return FlowBotAction.fromHubtypeCMS(hubtypeContent, locale, this.cmsApi)
 

packages/botonic-plugin-flow-builder/src/index.ts

@@ -24,6 +24,7 @@ export interface BotonicPluginFlowBuilderOptions<
   getAccessToken: () => string
   trackEvent?: TrackEventFunction<TPlugins, TExtraData>
   getKnowledgeBaseResponse?: KnowledgeBaseFunction<TPlugins, TExtraData>
+  getAiAgentResponse?: AiAgentFunction<TPlugins, TExtraData>
   smartIntentsConfig?: { numSmartIntentsToUse: number }
   inShadowing?: Partial<InShadowingConfig>
 }
@@ -48,6 +49,19 @@ export type KnowledgeBaseFunction<
   memoryLength: number
 ) => Promise<KnowledgeBaseResponse>
 
+export type AiAgentFunction<
+  TPlugins extends ResolvedPlugins = ResolvedPlugins,
+  TExtraData = any,
+> = (
+  request: BotContext<TPlugins, TExtraData>,
+  aiAgentArgs: AiAgentArgs
+) => Promise<AiAgentResponse>
+
+export interface AiAgentArgs {
+  name: string
+  instructions: string
+}
+
 export interface FlowBuilderApiOptions {
   url: string
   flowUrl: string
@@ -74,6 +88,10 @@ export interface KnowledgeBaseResponse {
   answer: string
 }
 
+export interface AiAgentResponse {
+  message: { role: string; content: string }
+}
+
 export interface SmartIntentResponse {
   data: {
     smart_intent_title: string

packages/botonic-plugin-flow-builder/src/types.ts

@@ -0,0 +1,9 @@
+interface MockAiAgentOptions {
+  message: { role: string; content: string }
+}
+
+export function mockAiAgentResponse({ message }: MockAiAgentOptions) {
+  return jest.fn(() => {
+    return Promise.resolve({ message })
+  })
+}