@botonic/plugin-ai-agents 0.48.1 → 0.49.0-alpha.1

package/src/bot-config-tools.ts

@@ -1,5 +1,5 @@
 import type { ToolConfigJSON } from '@botonic/core'
-import { zodToJsonSchema } from 'zod-to-json-schema'
+import { z } from 'zod'
 
 import type { CustomTool } from './types'
 
@@ -13,9 +13,8 @@ export function getToolsForBotConfig(
   return customTools.map(tool => ({
     name: tool.name,
     description: tool.description,
-    // Cast to avoid TS "Type instantiation is excessively deep" with zodToJsonSchema + ZodSchema
-    schema: zodToJsonSchema(tool.schema as never, {
-      $refStrategy: 'none',
+    schema: z.toJSONSchema(tool.schema, {
+      target: 'draft-07',
     }) as ToolConfigJSON['schema'],
   }))
 }

package/src/debug-logger.ts

@@ -1,4 +1,8 @@
-import type { AiAgentArgs, ToolExecution } from '@botonic/core'
+import {
+  type AiAgentArgs,
+  AiAgentType,
+  type ToolExecution,
+} from '@botonic/core'
 import type { ModelSettings } from '@openai/agents'
 import { OPENAI_PROVIDER } from './constants'
 import type { AgenticInputMessage, MemoryOptions, RunResult } from './types'
@@ -66,9 +70,11 @@ class EnabledDebugLogger implements DebugLogger {
     console.log(`${PREFIX} === AI Agent Debug Info ===`)
     console.log(`${PREFIX} Agent Name: ${aiAgentArgs.name}`)
     console.log(`${PREFIX} Active Tools: ${JSON.stringify(toolNames)}`)
-    console.log(
-      `${PREFIX} Source IDs: ${JSON.stringify(aiAgentArgs.sourceIds || [])}`
-    )
+    if (aiAgentArgs.type === AiAgentType.Specialist) {
+      console.log(
+        `${PREFIX} Source IDs: ${JSON.stringify(aiAgentArgs.sourceIds || [])}`
+      )
+    }
     console.log(`${PREFIX} Message History Count: ${messages.length}`)
     console.log(
       `${PREFIX} Input Guardrail Rules: ${aiAgentArgs.inputGuardrailRules?.length || 0}`

package/src/guardrails/input.ts

@@ -19,20 +19,34 @@ export interface GuardrailTrackingContext {
   inferenceId: string
 }
 
-export function createInputGuardrail(
+export async function createInputGuardrails(
   rules: GuardrailRule[],
   llmConfig: LLMConfig,
   trackingContext: GuardrailTrackingContext
-): InputGuardrail {
+): Promise<InputGuardrail[]> {
+  if (rules.length === 0) {
+    return []
+  }
+
+  return [await buildInputGuardrail(rules, llmConfig, trackingContext)]
+}
+
+async function buildInputGuardrail(
+  rules: GuardrailRule[],
+  llmConfig: LLMConfig,
+  trackingContext: GuardrailTrackingContext
+): Promise<InputGuardrail> {
   const outputType = z.object(
     Object.fromEntries(
       rules.map(rule => [rule.name, z.boolean().describe(rule.description)])
     )
   )
+  const modelSettings = createInputGuardrailModelSettings(llmConfig)
 
   const agent = new Agent({
     name: 'InputGuardrail',
-    model: llmConfig.modelName,
+    model: await llmConfig.getModel(),
+    modelSettings,
     instructions:
       'Check if the user triggers some of the following guardrails.',
     outputType,
@@ -42,11 +56,7 @@ export function createInputGuardrail(
     name: 'InputGuardrail',
     execute: async ({ input, context }) => {
       const lastMessage = input[input.length - 1] as UserMessageItem
-      const modelProvider = llmConfig.modelProvider
-      const modelSettings = createInputGuardrailModelSettings(llmConfig)
       const runner = new Runner({
-        modelSettings,
-        modelProvider,
         tracingDisabled: true,
       })
       const startTime = Date.now()
@@ -80,10 +90,17 @@ export function createInputGuardrail(
 function createInputGuardrailModelSettings(
   llmConfig: LLMConfig
 ): ModelSettings {
-  return {
+  const modelSettings: ModelSettings = {
     ...llmConfig.modelSettings,
     toolChoice: undefined,
   }
+  if (llmConfig.modelSettings.reasoning) {
+    modelSettings.reasoning = { ...llmConfig.modelSettings.reasoning }
+  }
+  if (llmConfig.modelSettings.text) {
+    modelSettings.text = { ...llmConfig.modelSettings.text }
+  }
+  return modelSettings
 }
 
 async function sendGuardrailLlmRunTracking(
@@ -114,7 +131,7 @@ async function sendGuardrailLlmRunTracking(
     product_name: TrackProductName.AI_AGENT,
     deployment_name: llmConfig.modelName,
     model_name:
-      (response.providerData?.['model'] as string | undefined) ??
+      (response.providerData?.model as string | undefined) ??
       llmConfig.modelName,
     feature: TrackFeature.AI_AGENT_GUARDRAIL,
     api_version: apiVersion,

package/src/index.ts

@@ -1,13 +1,17 @@
-import type {
-  AiAgentArgs,
-  BotContext,
-  HubtypeAssistantMessage,
-  Plugin,
-  ResolvedPlugins,
+import {
+  type AIAgentRouterArgs,
+  type AiAgentArgs,
+  type AiAgentSpecialistArgs,
+  AiAgentType,
+  type BotContext,
+  type HubtypeAssistantMessage,
+  type Plugin,
+  type ResolvedPlugins,
 } from '@botonic/core'
-import { setTracingDisabled, tool } from '@openai/agents'
+import { handoff, setTracingDisabled, tool } from '@openai/agents'
 import { v7 as uuidv7 } from 'uuid'
-import { AIAgentBuilder } from './agent-builder'
+import type { ZodObject } from 'zod'
+import { RouterAgent, SpecialistAgent } from './agents'
 import {
   DEFAULT_MAX_RETRIES,
   DEFAULT_TIMEOUT_16_SECONDS,
@@ -16,7 +20,7 @@ import {
 } from './constants'
 import { createDebugLogger, type DebugLogger } from './debug-logger'
 import { LLMConfig } from './llm-config'
-import { AIAgentRunner } from './runner'
+import { RouterRunner, WorkerRunner } from './runners'
 import { HubtypeApiClient } from './services/hubtype-api-client'
 import type {
   AgenticInputMessage,
@@ -77,84 +81,33 @@ export default class BotonicPluginAiAgents<
     botContext: BotContext<TPlugins, TExtraData>,
     aiAgentArgs: AiAgentArgs
   ): Promise<InferenceResponse> {
-    try {
-      const authToken = isProd
-        ? botContext.session._access_token
-        : this.authToken
-      if (!authToken) {
-        throw new Error('Auth token is required')
-      }
-
-      const inferenceId = uuidv7()
-
-      // Create client for OpenAI/Azure OpenAI
-      const llmConfig = new LLMConfig(
-        this.maxRetries,
-        this.timeout,
-        aiAgentArgs.model,
-        aiAgentArgs.verbosity
-      )
+    const authToken = isProd ? botContext.session._access_token : this.authToken
+    if (!authToken) {
+      throw new Error('Auth token is required')
+    }
 
-      // Build tools
-      const tools = this.buildTools(
-        aiAgentArgs.activeTools?.map(tool => tool.name) || []
-      )
+    const inferenceId = uuidv7()
 
-      // Build agent
-      const agent = new AIAgentBuilder<TPlugins, TExtraData>({
-        name: aiAgentArgs.name,
-        instructions: aiAgentArgs.instructions,
-        tools: tools,
-        contactInfo: botContext.session.user.contact_info || [],
-        inputGuardrailRules: aiAgentArgs.inputGuardrailRules || [],
-        sourceIds: aiAgentArgs.sourceIds || [],
-        outputMessagesSchemas: aiAgentArgs.outputMessagesSchemas || [],
-        campaignsContext: botContext.input.context?.campaigns_v2,
-        logger: this.logger,
-        llmConfig,
-        guardrailTrackingContext: {
-          botId: botContext.session.bot.id,
-          isTest: botContext.session.is_test_integration,
+    try {
+      if (aiAgentArgs.type === AiAgentType.Specialist) {
+        return await this.executeWorkerAIAgent(
+          botContext,
+          aiAgentArgs,
           authToken,
-          inferenceId,
-        },
-      }).build()
-
-      // Get messages
-      const messages = await this.getMessages(
-        botContext,
-        authToken,
-        aiAgentArgs.previousHubtypeMessages || []
-      )
-
-      // Build context
-      const context: Context<TPlugins, TExtraData> = {
-        authToken,
-        sourceIds: aiAgentArgs.sourceIds || [],
-        knowledgeUsed: {
-          query: '',
-          sourceIds: [],
-          chunksIds: [],
-          chunkTexts: [],
-        },
-        request: botContext,
+          inferenceId
+        )
       }
 
-      // Log agent debug info
-      this.logger.logAgentDebugInfo(
-        aiAgentArgs,
-        tools.map(t => t.name),
-        messages
-      )
+      if (aiAgentArgs.type === AiAgentType.Router) {
+        return await this.executeRouterAIAgent(
+          botContext,
+          aiAgentArgs,
+          authToken,
+          inferenceId
+        )
+      }
 
-      // Run agent
-      const runner = new AIAgentRunner<TPlugins, TExtraData>(
-        agent,
-        llmConfig,
-        inferenceId,
-        this.logger
-      )
-      return await runner.run(messages, context)
+      throw new Error('Invalid agent type')
     } catch (error) {
       console.error('error plugin returns undefined', error)
       return {
@@ -165,10 +118,188 @@ export default class BotonicPluginAiAgents<
         error: true,
         inputGuardrailsTriggered: [],
         outputGuardrailsTriggered: [],
+        startingAgentName: '',
+        lastAgentName: '',
+        availableSpecialists: [],
+        isTransferredToSpecialist: false,
       }
     }
   }
 
+  private async executeWorkerAIAgent(
+    botContext: BotContext<TPlugins, TExtraData>,
+    aiAgentArgs: AiAgentSpecialistArgs,
+    authToken: string,
+    inferenceId: string
+  ) {
+    const llmConfig = new LLMConfig(
+      this.maxRetries,
+      this.timeout,
+      aiAgentArgs.model,
+      aiAgentArgs.verbosity
+    )
+
+    // Get LLM config, tools and agent
+    const { tools, agent } = await this.getAIAgentWorkerAndTools(
+      botContext,
+      aiAgentArgs,
+      aiAgentArgs.outputMessagesSchemas || [],
+      authToken,
+      inferenceId,
+      llmConfig
+    )
+
+    // Get messages
+    const messages = await this.getMessages(
+      botContext,
+      authToken,
+      aiAgentArgs.previousHubtypeMessages || []
+    )
+
+    // Build context
+    const context: Context<TPlugins, TExtraData> = {
+      authToken,
+      knowledgeUsed: {
+        query: '',
+        sourceIds: [],
+        chunksIds: [],
+        chunkTexts: [],
+      },
+      request: botContext,
+    }
+
+    // Log agent debug info
+    this.logger.logAgentDebugInfo(
+      aiAgentArgs,
+      tools.map(t => t.name),
+      messages
+    )
+
+    // Run agent
+    const runner = new WorkerRunner<TPlugins, TExtraData>(
+      agent,
+      llmConfig,
+      inferenceId,
+      this.logger
+    )
+    return await runner.run(messages, context)
+  }
+
+  private async executeRouterAIAgent(
+    botContext: BotContext<TPlugins, TExtraData>,
+    aiAgentArgs: AIAgentRouterArgs,
+    authToken: string,
+    inferenceId: string
+  ) {
+    const { specialists, name, instructions } = aiAgentArgs
+
+    const llmConfig = new LLMConfig(
+      this.maxRetries,
+      this.timeout,
+      aiAgentArgs.model,
+      aiAgentArgs.verbosity
+    )
+
+    const specialistsAgents = await Promise.all(
+      specialists.map(async specialistData => {
+        const { agent } = await this.getAIAgentWorkerAndTools(
+          botContext,
+          specialistData,
+          aiAgentArgs.outputMessagesSchemas || [],
+          authToken,
+          inferenceId,
+          llmConfig
+        )
+        return handoff(agent, {
+          toolNameOverride: specialistData.name,
+          toolDescriptionOverride: specialistData.description,
+        })
+      })
+    )
+
+    const router = await RouterAgent.create<TPlugins, TExtraData>({
+      name,
+      instructions,
+      llmConfig,
+      handoffs: specialistsAgents,
+      inputGuardrailRules: aiAgentArgs.inputGuardrailRules || [],
+      outputMessagesSchemas: aiAgentArgs.outputMessagesSchemas || [],
+      guardrailTrackingContext: {
+        botId: botContext.session.bot.id,
+        isTest: botContext.session.is_test_integration,
+        authToken,
+        inferenceId,
+      },
+    })
+
+    // Get messages
+    const messages = await this.getMessages(
+      botContext,
+      authToken,
+      aiAgentArgs.previousHubtypeMessages || []
+    )
+
+    // Build context
+    const context: Context<TPlugins, TExtraData> = {
+      authToken,
+      knowledgeUsed: {
+        query: '',
+        sourceIds: [],
+        chunksIds: [],
+        chunkTexts: [],
+      },
+      request: botContext,
+    }
+
+    // Run agent
+    const routerAgent = router.getAgent()
+    const runner = new RouterRunner<TPlugins, TExtraData>(
+      routerAgent,
+      llmConfig,
+      inferenceId,
+      this.logger
+    )
+
+    return await runner.run(messages, context)
+  }
+
+  private async getAIAgentWorkerAndTools(
+    botContext: BotContext,
+    aiAgentArgs: AiAgentArgs,
+    outputMessagesSchemas: ZodObject<any>[],
+    authToken: string,
+    inferenceId: string,
+    llmConfig: LLMConfig
+  ) {
+    // Build tools
+    const tools = this.buildTools(aiAgentArgs)
+
+    // Build agent
+    const sourceIds =
+      aiAgentArgs.type === AiAgentType.Specialist ? aiAgentArgs.sourceIds : []
+    const worker = await SpecialistAgent.create<TPlugins, TExtraData>({
+      name: aiAgentArgs.name,
+      instructions: aiAgentArgs.instructions,
+      tools: tools,
+      contactInfo: botContext.session.user.contact_info || [],
+      inputGuardrailRules: aiAgentArgs.inputGuardrailRules || [],
+      sourceIds,
+      outputMessagesSchemas: outputMessagesSchemas || [],
+      campaignsContext: botContext.input.context?.campaigns_v2,
+      logger: this.logger,
+      llmConfig,
+      guardrailTrackingContext: {
+        botId: botContext.session.bot.id,
+        isTest: botContext.session.is_test_integration,
+        authToken,
+        inferenceId,
+      },
+    })
+    const workerAgent = worker.getAgent()
+
+    return { agent: workerAgent, tools }
+  }
+
   private async getMessages(
     botContext: BotContext,
     authToken: string,
@@ -192,7 +323,10 @@ export default class BotonicPluginAiAgents<
     return result.messages
   }
 
-  private buildTools(activeToolNames: string[]): Tool<TPlugins, TExtraData>[] {
+  private buildTools(aiAgentArgs: AiAgentArgs): Tool<TPlugins, TExtraData>[] {
+    const activeTools =
+      aiAgentArgs.type === AiAgentType.Router ? [] : aiAgentArgs.activeTools
+    const activeToolNames = activeTools.map(tool => tool.name)
     const availableTools = this.toolDefinitions.filter(tool =>
       activeToolNames.includes(tool.name)
     )

package/src/llm-config.ts

@@ -1,5 +1,6 @@
 import type { VerbosityLevel } from '@botonic/core'
 import {
+  type Model,
   type ModelProvider,
   type ModelSettings,
   OpenAIProvider,
@@ -35,6 +36,10 @@ export class LLMConfig {
     this.modelSettings = this.getModelSettings(modelName, verbosity)
   }
 
+  async getModel(): Promise<Model> {
+    return await this.modelProvider.getModel(this.modelName)
+  }
+
   private getModelProvider(): ModelProvider {
     const client = this.getClient()
     return new OpenAIProvider({

package/src/runners/base-runner.ts

@@ -0,0 +1,190 @@
+import type {
+  OutputMessage,
+  ResolvedPlugins,
+  ToolExecution,
+} from '@botonic/core'
+import { InputGuardrailTripwireTriggered, Runner } from '@openai/agents'
+
+import { isProd } from '../constants'
+import type { DebugLogger } from '../debug-logger'
+import { getApiVersion, type LLMConfig } from '../llm-config'
+import { HubtypeApiClient } from '../services/hubtype-api-client'
+import { TrackFeature, TrackProductName } from '../services/types'
+import type {
+  AgenticInputMessage,
+  AgenticOutputMessage,
+  AIAgent,
+  Context,
+  ResultRawResponse,
+  RunResult,
+} from '../types'
+
+// Minimal interface matching the properties we actually use from Runner.run() result.
+// This bypasses strict type checking while maintaining type safety for accessed properties.
+export interface RunnerResult {
+  finalOutput?: {
+    messages?: OutputMessage[]
+  }
+  rawResponses?: ResultRawResponse[]
+  newItems?: unknown[]
+  lastAgent?: { name?: string }
+  // biome-ignore lint/suspicious/noExplicitAny: state is a complex internal type
+  state?: any
+}
+
+export abstract class BaseRunner<
+  TPlugins extends ResolvedPlugins = ResolvedPlugins,
+  TExtraData = unknown,
+> {
+  protected agent: AIAgent<TPlugins, TExtraData>
+  protected llmConfig: LLMConfig
+  protected inferenceId: string
+  protected logger: DebugLogger
+
+  constructor(
+    agent: AIAgent<TPlugins, TExtraData>,
+    llmConfig: LLMConfig,
+    inferenceId: string,
+    logger: DebugLogger
+  ) {
+    this.agent = agent
+    this.llmConfig = llmConfig
+    this.inferenceId = inferenceId
+    this.logger = logger
+  }
+
+  async run(
+    messages: AgenticInputMessage[],
+    context: Context<TPlugins, TExtraData>
+  ): Promise<RunResult> {
+    const startTime = Date.now()
+
+    this.logger.logRunnerStart(
+      this.llmConfig.modelName,
+      this.llmConfig.modelSettings
+    )
+
+    try {
+      const runner = new Runner({
+        tracingDisabled: true,
+      })
+      const result = (await runner.run(this.agent, messages, {
+        context,
+      })) as RunnerResult
+      const endTime = Date.now()
+
+      await this.sendLlmRunTracking(result, context, startTime, endTime)
+
+      const runResult = this.buildRunResult(result, context, messages.length)
+
+      this.logger.logRunResult(runResult, startTime)
+
+      return runResult
+    } catch (error) {
+      if (error instanceof InputGuardrailTripwireTriggered) {
+        const runResult: RunResult = {
+          startingAgentName: '',
+          lastAgentName: '',
+          availableSpecialists: [],
+          isTransferredToSpecialist: false,
+          messages: [],
+          memoryLength: 0,
+          toolsExecuted: [],
+          exit: true,
+          error: false,
+          inputGuardrailsTriggered: error.result.output.outputInfo,
+          outputGuardrailsTriggered: [],
+        }
+
+        this.logger.logGuardrailTriggered()
+        this.logger.logRunResult(runResult, startTime)
+
+        return runResult
+      }
+
+      this.logger.logRunnerError(startTime, error)
+
+      throw error
+    }
+  }
+
+  protected getToolsExecuted(
+    _result: RunnerResult,
+    _context: Context<TPlugins, TExtraData>
+  ): ToolExecution[] {
+    return []
+  }
+
+  protected buildRunResult(
+    result: RunnerResult,
+    context: Context<TPlugins, TExtraData>,
+    memoryLength: number
+  ): RunResult {
+    const outputMessages = result.finalOutput?.messages || []
+    const hasExit =
+      outputMessages.length === 0 ||
+      outputMessages.some(message => message.type === 'exit')
+
+    return {
+      startingAgentName: '',
+      lastAgentName: '',
+      availableSpecialists: [],
+      isTransferredToSpecialist: false,
+      messages: hasExit
+        ? []
+        : (outputMessages.filter(
+            message => message.type !== 'exit'
+          ) as AgenticOutputMessage[]),
+      toolsExecuted: this.getToolsExecuted(result, context),
+      exit: hasExit,
+      memoryLength,
+      error: false,
+      inputGuardrailsTriggered: [],
+      outputGuardrailsTriggered: [],
+    }
+  }
+
+  private async sendLlmRunTracking(
+    result: RunnerResult,
+    context: Context<TPlugins, TExtraData>,
+    startTime: number,
+    endTime: number
+  ): Promise<void> {
+    if (!isProd) {
+      return
+    }
+    const rawResponses = result.rawResponses ?? []
+    if (rawResponses.length === 0) {
+      return
+    }
+    const botId = context.request.session.bot.id
+    const isTest = context.request.session.is_test_integration
+    const totalDuration = endTime - startTime
+    const durationPerCall = Math.round(totalDuration / rawResponses.length)
+    const temperature =
+      (this.llmConfig.modelSettings.temperature as number | undefined) ?? 0
+    const apiVersion = getApiVersion()
+
+    const llmRuns = rawResponses.map(response => ({
+      inference_id: this.inferenceId,
+      is_test: isTest,
+      product_name: TrackProductName.AI_AGENT,
+      deployment_name: this.llmConfig.modelName,
+      model_name:
+        (response.providerData?.model as string | undefined) ??
+        this.llmConfig.modelName,
+      feature: TrackFeature.AI_AGENT_RUN,
+      api_version: apiVersion,
+      num_prompt_tokens: response.usage.inputTokens,
+      num_completion_tokens: response.usage.outputTokens,
+      duration_in_milliseconds: durationPerCall,
+      temperature,
+      error: null,
+    }))
+
+    const client = new HubtypeApiClient(context.authToken)
+    await client.trackLlmRuns(botId, {
+      llm_runs: llmRuns,
+    })
+  }
+}

package/src/runners/index.ts

@@ -0,0 +1,2 @@
+export { RouterRunner } from './router-runner'
+export { SpecialistRunner as WorkerRunner } from './specialist-runner'