@botonic/plugin-ai-agents 0.42.4 → 0.43.0-alpha.1

package/src/agent-builder.ts

@@ -1,10 +1,29 @@
-import { ResolvedPlugins } from '@botonic/core'
-import { Agent, InputGuardrail, ModelSettings } from '@openai/agents'
+import { CampaignV2, ContactInfo, ResolvedPlugins } from '@botonic/core'
+import {
+  Agent,
+  AgentOutputType,
+  InputGuardrail,
+  ModelSettings,
+} from '@openai/agents'
 
+import { OPENAI_MODEL, OPENAI_PROVIDER } from './constants'
 import { createInputGuardrail } from './guardrails'
 import { OutputSchema } from './structured-output'
 import { mandatoryTools, retrieveKnowledge } from './tools'
-import { AIAgent, ContactInfo, GuardrailRule, Tool } from './types'
+import { AIAgent, Context, GuardrailRule, Tool } from './types'
+
+interface AIAgentBuilderOptions<
+  TPlugins extends ResolvedPlugins = ResolvedPlugins,
+  TExtraData = any,
+> {
+  name: string
+  instructions: string
+  tools: Tool<TPlugins, TExtraData>[]
+  campaignContext?: CampaignV2
+  contactInfo: ContactInfo[]
+  inputGuardrailRules: GuardrailRule[]
+  sourceIds: string[]
+}
 
 export class AIAgentBuilder<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
@@ -15,33 +34,47 @@ export class AIAgentBuilder<
   private tools: Tool<TPlugins, TExtraData>[]
   private inputGuardrails: InputGuardrail[]
 
-  constructor(
-    name: string,
-    instructions: string,
-    tools: Tool<TPlugins, TExtraData>[],
-    contactInfo: ContactInfo,
-    inputGuardrailRules: GuardrailRule[],
-    sourceIds: string[]
-  ) {
-    this.name = name
-    this.instructions = this.addExtraInstructions(instructions, contactInfo)
-    this.tools = this.addHubtypeTools(tools, sourceIds)
+  constructor(options: AIAgentBuilderOptions<TPlugins, TExtraData>) {
+    this.name = options.name
+    this.instructions = this.addExtraInstructions(
+      options.instructions,
+      options.contactInfo,
+      options.campaignContext
+    )
+    this.tools = this.addHubtypeTools(options.tools, options.sourceIds)
     this.inputGuardrails = []
-    if (inputGuardrailRules.length > 0) {
-      const inputGuardrail = createInputGuardrail(inputGuardrailRules)
+    if (options.inputGuardrailRules.length > 0) {
+      const inputGuardrail = createInputGuardrail(options.inputGuardrailRules)
       this.inputGuardrails.push(inputGuardrail)
     }
   }
 
   build(): AIAgent<TPlugins, TExtraData> {
-    const modelSettings: ModelSettings = {}
+    const modelSettings: ModelSettings = {} as ModelSettings
+    if (OPENAI_PROVIDER === 'openai') {
+      // @ts-expect-error - reasoning.effort is valid but we need to update openai and typescript dependencies
+      modelSettings.reasoning = { effort: 'none' }
+      modelSettings.text = { verbosity: 'medium' }
+    }
 
-    if (this.tools.includes(retrieveKnowledge)) {
+    if (this.tools.includes(retrieveKnowledge) && OPENAI_PROVIDER === 'azure') {
       modelSettings.toolChoice = retrieveKnowledge.name
     }
 
-    return new Agent({
+    // When using standard OpenAI API, we need to specify the model
+    // Azure OpenAI uses deployment name instead
+    const model = OPENAI_PROVIDER === 'openai' ? OPENAI_MODEL : undefined
+
+    // TODO: Improve type safety - replace AgentOutputType<any> with AgentOutputType<typeof OutputSchema>
+    // Currently using explicit type parameters to avoid type inference issues where Agent constructor
+    // infers ZodObject instead of AgentOutputType<typeof OutputSchema>. The explicit type parameters
+    // ensure compatibility with AIAgent type definition. Future improvements:
+    // 1. Update @openai/agents package to properly infer AgentOutputType from outputType parameter
+    // 2. Replace AgentOutputType<any> with AgentOutputType<typeof OutputSchema> once type system allows
+    // 3. Consider updating AIAgent type definition if @openai/agents types change significantly
+    return new Agent<Context<TPlugins, TExtraData>, AgentOutputType<any>>({
       name: this.name,
+      model,
       instructions: this.instructions,
       tools: this.tools,
       outputType: OutputSchema,
@@ -53,20 +86,34 @@ export class AIAgentBuilder<
 
   private addExtraInstructions(
     initialInstructions: string,
-    contactInfo: ContactInfo
+    contactInfo: ContactInfo[],
+    campaignContext?: CampaignV2
   ): string {
-    const instructions = `<instructions>\n${initialInstructions}\n</instructions>`
+    const instructions = `<instructions>\n${initialInstructions.trim()}\n</instructions>`
     const metadataInstructions = this.getMetadataInstructions()
     const contactInfoInstructions = this.getContactInfoInstructions(contactInfo)
+    const campaignInstructions = this.getCampaignInstructions(campaignContext)
     const outputInstructions = this.getOutputInstructions()
-    return `${instructions}\n\n${metadataInstructions}\n\n${contactInfoInstructions}\n\n${outputInstructions}`
+    return `${instructions}\n\n${metadataInstructions}\n\n${contactInfoInstructions}\n\n${campaignInstructions}\n\n${outputInstructions}`
   }
 
-  private getContactInfoInstructions(contactInfo: ContactInfo): string {
-    const structuredContactInfo = Object.entries(contactInfo)
-      .map(([key, value]) => `${key}: ${value}`)
+  private getContactInfoInstructions(contactInfo: ContactInfo[]): string {
+    const structuredContactInfo = contactInfo
+      .map(
+        info =>
+          ` <contact_info>
+              <name>${info.name}</name>
+              <value>${info.value}</value>
+              <type>${info.type}</type>
+              ${
+                info.description
+                  ? `<description>${info.description}</description>`
+                  : ''
+              }
+            </contact_info>`
+      )
       .join('\n')
-    return `<contact_info>\n${structuredContactInfo}\n</contact_info>`
+    return `<contact_info_fields>\n${structuredContactInfo}</contact_info_fields>`
   }
 
   private getMetadataInstructions(): string {
@@ -74,6 +121,13 @@ export class AIAgentBuilder<
     return `<metadata>\n${metadata}\n</metadata>`
   }
 
+  private getCampaignInstructions(campaignContext?: CampaignV2): string {
+    if (!campaignContext || !campaignContext.agent_context) {
+      return ''
+    }
+    return `<campaign_context>\n${campaignContext.agent_context}\n</campaign_context>`
+  }
+
   private getOutputInstructions(): string {
     const example = {
       messages: [

package/src/constants.ts

@@ -1,6 +1,13 @@
 export const HUBTYPE_API_URL =
   process.env.HUBTYPE_API_URL || 'https://api.hubtype.com'
 
+// OpenAI Provider Configuration
+export const OPENAI_API_KEY = process.env.OPENAI_API_KEY // pragma: allowlist secret
+export const OPENAI_MODEL = process.env.OPENAI_MODEL || 'gpt-4.1-mini'
+export const OPENAI_PROVIDER: 'openai' | 'azure' =
+  (process.env.OPENAI_PROVIDER as 'openai' | 'azure') || 'azure'
+
+// Azure OpenAI Configuration
 export const AZURE_OPENAI_API_KEY = process.env.AZURE_OPENAI_API_KEY // pragma: allowlist secret
 export const AZURE_OPENAI_API_BASE = process.env.AZURE_OPENAI_API_BASE
 export const AZURE_OPENAI_API_DEPLOYMENT_NAME =

package/src/guardrails/input.ts

@@ -22,7 +22,7 @@ export function createInputGuardrail(rules: GuardrailRule[]): InputGuardrail {
     execute: async ({ input, context }) => {
       const lastMessage = input[input.length - 1] as UserMessageItem
       const result = await run(agent, [lastMessage], { context })
-      const finalOutput = result.finalOutput
+      const finalOutput = result.finalOutput as Record<string, boolean>
       if (finalOutput === undefined) {
         throw new Error('Guardrail agent failed to produce output')
       }

package/src/hubtype-api-client.ts

@@ -17,6 +17,71 @@ interface HubtypeUserMessage {
 
 type HubtypeMessage = HubtypeAssistantMessage | HubtypeUserMessage
 
+// V2 API Types
+interface HubtypeToolCall {
+  id: string
+  type: 'function'
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+interface HubtypeUserMessageV2 {
+  role: 'user'
+  content: string | null
+}
+
+interface HubtypeAssistantMessageV2 {
+  role: 'assistant'
+  content: string | null
+  tool_calls?: HubtypeToolCall[] | null
+}
+
+interface HubtypeToolMessageV2 {
+  role: 'tool'
+  content: string | null
+  tool_call_id: string
+}
+
+interface HubtypeSystemMessageV2 {
+  role: 'system'
+  content: string | null
+}
+
+type HubtypeMessageV2 =
+  | HubtypeUserMessageV2
+  | HubtypeAssistantMessageV2
+  | HubtypeToolMessageV2
+  | HubtypeSystemMessageV2
+
+interface MessageHistoryResponseV2 {
+  messages: HubtypeMessageV2[]
+  conversation_id: string | null
+  truncated: boolean
+}
+
+export interface GetMessagesV2Options {
+  maxMessages?: number
+  includeToolCalls?: boolean
+  maxFullToolResults?: number
+  debugMode?: boolean
+}
+
+export interface GetMessagesV2Result {
+  messages: AgenticInputMessage[]
+  conversationId: string | null
+  truncated: boolean
+}
+
+interface MessageHistoryV2Params {
+  last_message_id: string
+  max_messages?: number
+  include_tool_calls?: boolean
+  max_full_tool_results?: number
+  debug_mode?: boolean
+}
+
 export class HubtypeApiClient {
   private readonly authToken: string
 
@@ -92,6 +157,117 @@ export class HubtypeApiClient {
     }
   }
 
+  async getMessagesV2(
+    request: BotContext,
+    options: GetMessagesV2Options = {}
+  ): Promise<GetMessagesV2Result> {
+    const url = `${HUBTYPE_API_URL}/external/v2/ai/agent/message_history/`
+    const headers = {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${this.authToken}`,
+    }
+    const params: MessageHistoryV2Params = {
+      last_message_id: request.input.message_id,
+      ...(options.maxMessages !== undefined && {
+        max_messages: options.maxMessages,
+      }),
+      ...(options.includeToolCalls !== undefined && {
+        include_tool_calls: options.includeToolCalls,
+      }),
+      ...(options.maxFullToolResults !== undefined && {
+        max_full_tool_results: options.maxFullToolResults,
+      }),
+      ...(options.debugMode !== undefined && {
+        debug_mode: options.debugMode,
+      }),
+    }
+
+    try {
+      const response = await axios.get<MessageHistoryResponseV2>(url, {
+        headers,
+        params,
+      })
+      const { messages, conversation_id, truncated } = response.data
+      const formattedMessages = messages
+        .map(message => this.formatMessageV2(message))
+        .filter((message): message is AgenticInputMessage => message !== null)
+      return {
+        messages: formattedMessages,
+        conversationId: conversation_id,
+        truncated,
+      }
+    } catch (error) {
+      console.error(error)
+      throw new Error('Failed to get messages from Hubtype V2 API')
+    }
+  }
+
+  private formatMessageV2(
+    message: HubtypeMessageV2
+  ): AgenticInputMessage | null {
+    switch (message.role) {
+      case 'user':
+        return {
+          role: 'user',
+          content: message.content ?? '',
+        }
+      case 'assistant': {
+        const assistantMessage = message as HubtypeAssistantMessageV2
+        // If assistant message has tool_calls, include them for context
+        // Using double assertion as the OpenAI API supports this format,
+        // but the agents SDK types are more restrictive
+        if (
+          assistantMessage.tool_calls &&
+          assistantMessage.tool_calls.length > 0
+        ) {
+          return {
+            role: 'assistant',
+            content: assistantMessage.content ?? '',
+            tool_calls: assistantMessage.tool_calls.map(tc => ({
+              id: tc.id,
+              type: tc.type,
+              function: {
+                name: tc.function.name,
+                arguments: tc.function.arguments,
+              },
+            })),
+          } as unknown as AgenticInputMessage
+        }
+        // Regular assistant message without tool_calls
+        return {
+          role: 'assistant',
+          content: [
+            {
+              type: 'output_text',
+              text: assistantMessage.content ?? '',
+            },
+          ],
+          status: 'completed',
+        }
+      }
+      case 'tool': {
+        // Tool messages provide context about previous tool executions
+        // Using double assertion as the OpenAI API supports this format,
+        // but the agents SDK types are more restrictive
+        const toolMessage = message as HubtypeToolMessageV2
+        return {
+          role: 'tool',
+          tool_call_id: toolMessage.tool_call_id,
+          content: toolMessage.content ?? '',
+        } as unknown as AgenticInputMessage
+      }
+      case 'system':
+        return {
+          role: 'system',
+          content: message.content ?? '',
+        }
+      default:
+        throw new Error(
+          `Invalid message role: ${(message as HubtypeMessageV2).role}`
+        )
+    }
+  }
+
   private formatMessage(message: HubtypeMessage): AgenticInputMessage {
     if (message.role === 'user') {
       return {

package/src/index.ts

@@ -11,6 +11,8 @@ import {
   Context,
   CustomTool,
   InferenceResponse,
+  MemoryOptions,
+  MessageHistoryApiVersion,
   PluginAiAgentOptions,
   Tool,
 } from './types'
@@ -21,12 +23,24 @@ export default class BotonicPluginAiAgents<
 > implements Plugin
 {
   private readonly authToken?: string
+  private readonly messageHistoryApiVersion: MessageHistoryApiVersion
+  private readonly memory: MemoryOptions
   public toolDefinitions: CustomTool<TPlugins, TExtraData>[] = []
 
   constructor(options?: PluginAiAgentOptions<TPlugins, TExtraData>) {
     setUpOpenAI(options?.maxRetries, options?.timeout)
+
+    if (options?.messageHistoryApiVersion === 'v1' && options?.memory) {
+      throw new Error(
+        'Cannot use memory when messageHistoryApiVersion is "v1". ' +
+          'Either set messageHistoryApiVersion to "v2" or remove memory.'
+      )
+    }
+
     this.authToken = options?.authToken
     this.toolDefinitions = options?.customTools || []
+    this.messageHistoryApiVersion = options?.messageHistoryApiVersion ?? 'v2'
+    this.memory = options?.memory ?? {}
   }
 
   pre(): void {
@@ -46,14 +60,15 @@ export default class BotonicPluginAiAgents<
       const tools = this.buildTools(
         aiAgentArgs.activeTools?.map(tool => tool.name) || []
       )
-      const agent = new AIAgentBuilder<TPlugins, TExtraData>(
-        aiAgentArgs.name,
-        aiAgentArgs.instructions,
-        tools,
-        request.session.user.contact_info || {},
-        aiAgentArgs.inputGuardrailRules || [],
-        aiAgentArgs.sourceIds || []
-      ).build()
+      const agent = new AIAgentBuilder<TPlugins, TExtraData>({
+        name: aiAgentArgs.name,
+        instructions: aiAgentArgs.instructions,
+        tools: tools,
+        contactInfo: request.session.user.contact_info || [],
+        inputGuardrailRules: aiAgentArgs.inputGuardrailRules || [],
+        sourceIds: aiAgentArgs.sourceIds || [],
+        campaignContext: request.input.context?.campaign_v2,
+      }).build()
 
       const messages = await this.getMessages(
         request,
@@ -93,12 +108,24 @@ export default class BotonicPluginAiAgents<
     authToken: string,
     memoryLength: number
   ): Promise<AgenticInputMessage[]> {
-    if (isProd) {
-      const hubtypeClient = new HubtypeApiClient(authToken)
+    const hubtypeClient = new HubtypeApiClient(authToken)
+
+    if (!isProd) {
+      return await hubtypeClient.getLocalMessages(memoryLength)
+    }
+
+    if (this.messageHistoryApiVersion === 'v1') {
       return await hubtypeClient.getMessages(request, memoryLength)
     }
-    const hubtypeClient = new HubtypeApiClient(authToken)
-    return await hubtypeClient.getLocalMessages(memoryLength)
+
+    // Default to V2
+    const result = await hubtypeClient.getMessagesV2(request, {
+      maxMessages: this.memory.maxMessages ?? memoryLength,
+      includeToolCalls: this.memory.includeToolCalls ?? true,
+      maxFullToolResults: this.memory.maxFullToolResults ?? 1,
+      debugMode: this.memory.debugMode ?? false,
+    })
+    return result.messages
   }
 
   private buildTools(activeToolNames: string[]): Tool<TPlugins, TExtraData>[] {

package/src/openai.ts

@@ -3,7 +3,7 @@ import {
   setOpenAIAPI,
   setTracingDisabled,
 } from '@openai/agents'
-import { AzureOpenAI } from 'openai'
+import OpenAI, { AzureOpenAI } from 'openai'
 
 import {
   AZURE_OPENAI_API_BASE,
@@ -11,21 +11,37 @@ import {
   AZURE_OPENAI_API_KEY,
   AZURE_OPENAI_API_VERSION,
   isProd,
+  OPENAI_API_KEY,
+  OPENAI_PROVIDER,
 } from './constants'
 
 export function setUpOpenAI(maxRetries?: number, timeout?: number) {
-  setAzureOpenAIClient(maxRetries, timeout)
+  if (OPENAI_PROVIDER === 'azure') {
+    setAzureOpenAIClient(maxRetries, timeout)
+  } else {
+    setOpenAIClient(maxRetries, timeout)
+  }
   setOpenAIAPI('chat_completions')
   setTracingDisabled(true)
 }
 
+function setOpenAIClient(maxRetries?: number, timeout?: number) {
+  const client = new OpenAI({
+    apiKey: OPENAI_API_KEY,
+    timeout: timeout || 16000, // 16 seconds
+    maxRetries: maxRetries || 2,
+    dangerouslyAllowBrowser: !isProd,
+  })
+  setDefaultOpenAIClient(client)
+}
+
 function setAzureOpenAIClient(maxRetries?: number, timeout?: number) {
   const client = new AzureOpenAI({
     apiKey: AZURE_OPENAI_API_KEY,
     apiVersion: AZURE_OPENAI_API_VERSION,
     deployment: AZURE_OPENAI_API_DEPLOYMENT_NAME,
     baseURL: AZURE_OPENAI_API_BASE,
-    timeout: timeout || 8000, // 8 seconds
+    timeout: timeout || 16000, // 16 seconds
     maxRetries: maxRetries || 2,
     dangerouslyAllowBrowser: !isProd,
   })

package/src/runner.ts

@@ -1,4 +1,4 @@
-import { ResolvedPlugins, ToolExecution } from '@botonic/core'
+import { OutputMessage, ResolvedPlugins, ToolExecution } from '@botonic/core'
 import {
   InputGuardrailTripwireTriggered,
   Runner,
@@ -14,6 +14,15 @@ import {
   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
+interface AIAgentRunnerResult {
+  finalOutput?: {
+    messages?: OutputMessage[]
+  }
+  newItems?: RunToolCallItem[]
+}
+
 export class AIAgentRunner<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
   TExtraData = any,
@@ -32,7 +41,11 @@ export class AIAgentRunner<
       const runner = new Runner({
         modelSettings: { temperature: 0 },
       })
-      const result = await runner.run(this.agent, messages, { context })
+      // Type assertion to bypass strict type checking - the actual return type from runner.run()
+      // doesn't perfectly match our interface, but the properties we access are compatible
+      const result = (await runner.run(this.agent, messages, {
+        context,
+      })) as AIAgentRunnerResult
 
       const outputMessages = result.finalOutput?.messages || []
       const hasExit =

package/src/tools/retrieve-knowledge.ts

@@ -4,7 +4,7 @@ import { z } from 'zod'
 import { HubtypeApiClient } from '../hubtype-api-client'
 import { Context } from '../types'
 
-export const retrieveKnowledge = tool<any, Context, any>({
+export const retrieveKnowledge = tool({
   name: 'retrieve_knowledge',
   description:
     'Consult the knowledge base for information before answering. Use this tool to make sure the information you provide is faithful.',
@@ -12,10 +12,11 @@ export const retrieveKnowledge = tool<any, Context, any>({
     query: z.string().describe('The query to search the knowledge base for'),
   }),
   execute: async (
-    { query }: { query: string },
+    input: { query: string },
     runContext?: RunContext<Context>
   ): Promise<string[]> => {
     const context = runContext?.context
+    const query = input.query
     if (!context) {
       throw new Error('Context is required')
     }

package/src/types.ts

@@ -10,6 +10,7 @@ import {
 import {
   Agent,
   AgentInputItem,
+  AgentOutputType,
   RunContext as OpenAIRunContext,
   Tool as OpenAITool,
 } from '@openai/agents'
@@ -55,16 +56,25 @@ export interface Chunk {
   text: string
 }
 
-export type ContactInfo = Record<string, string>
-
 export type Tool<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
   TExtraData = any,
 > = OpenAITool<Context<TPlugins, TExtraData>>
+
 export type AIAgent<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
   TExtraData = any,
-> = Agent<Context<TPlugins, TExtraData>, typeof OutputSchema>
+> = Agent<Context<TPlugins, TExtraData>, AgentOutputType<typeof OutputSchema>>
+
+export type MessageHistoryApiVersion = 'v1' | 'v2'
+
+export interface MemoryOptions {
+  maxMessages?: number
+  includeToolCalls?: boolean
+  maxFullToolResults?: number
+  debugMode?: boolean
+}
+
 export interface PluginAiAgentOptions<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
   TExtraData = any,
@@ -73,6 +83,10 @@ export interface PluginAiAgentOptions<
   customTools?: CustomTool<TPlugins, TExtraData>[]
   maxRetries?: number
   timeout?: number
+  /** API version for message history endpoint. Defaults to 'v2'. */
+  messageHistoryApiVersion?: MessageHistoryApiVersion
+  /** Options for V2 message history API. Only used when messageHistoryApiVersion is 'v2'. */
+  memory?: MemoryOptions
 }
 
 export type AgenticInputMessage = AgentInputItem