@botonic/plugin-ai-agents 0.43.0-alpha.0 → 0.43.0-beta.0

package/src/agent-builder.ts

@@ -1,29 +1,10 @@
-import { CampaignV2, ResolvedPlugins } from '@botonic/core'
-import {
-  Agent,
-  AgentOutputType,
-  InputGuardrail,
-  ModelSettings,
-} from '@openai/agents'
+import { ResolvedPlugins } from '@botonic/core'
+import { Agent, 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, 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[]
-}
+import { AIAgent, ContactInfo, GuardrailRule, Tool } from './types'
 
 export class AIAgentBuilder<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
@@ -34,47 +15,33 @@ export class AIAgentBuilder<
   private tools: Tool<TPlugins, TExtraData>[]
   private inputGuardrails: InputGuardrail[]
 
-  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)
+  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)
     this.inputGuardrails = []
-    if (options.inputGuardrailRules.length > 0) {
-      const inputGuardrail = createInputGuardrail(options.inputGuardrailRules)
+    if (inputGuardrailRules.length > 0) {
+      const inputGuardrail = createInputGuardrail(inputGuardrailRules)
       this.inputGuardrails.push(inputGuardrail)
     }
   }
 
   build(): AIAgent<TPlugins, TExtraData> {
-    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' }
-    }
+    const modelSettings: ModelSettings = {}
 
-    if (this.tools.includes(retrieveKnowledge) && OPENAI_PROVIDER === 'azure') {
+    if (this.tools.includes(retrieveKnowledge)) {
       modelSettings.toolChoice = retrieveKnowledge.name
     }
 
-    // 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>>({
+    return new Agent({
       name: this.name,
-      model,
       instructions: this.instructions,
       tools: this.tools,
       outputType: OutputSchema,
@@ -86,15 +53,13 @@ export class AIAgentBuilder<
 
   private addExtraInstructions(
     initialInstructions: string,
-    contactInfo: ContactInfo,
-    campaignContext?: CampaignV2
+    contactInfo: ContactInfo
   ): string {
-    const instructions = `<instructions>\n${initialInstructions.trim()}\n</instructions>`
+    const instructions = `<instructions>\n${initialInstructions}\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${campaignInstructions}\n\n${outputInstructions}`
+    return `${instructions}\n\n${metadataInstructions}\n\n${contactInfoInstructions}\n\n${outputInstructions}`
   }
 
   private getContactInfoInstructions(contactInfo: ContactInfo): string {
@@ -109,13 +74,6 @@ 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,13 +1,6 @@
 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 as Record<string, boolean>
+      const finalOutput = result.finalOutput
       if (finalOutput === undefined) {
         throw new Error('Guardrail agent failed to produce output')
       }

package/src/hubtype-api-client.ts

@@ -17,6 +17,63 @@ 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
+}
+
 export class HubtypeApiClient {
   private readonly authToken: string
 
@@ -92,6 +149,118 @@ 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: Record<string, string | number | boolean> = {
+      last_message_id: request.input.message_id,
+    }
+
+    if (options.maxMessages !== undefined) {
+      params.max_messages = options.maxMessages
+    }
+    if (options.includeToolCalls !== undefined) {
+      params.include_tool_calls = options.includeToolCalls
+    }
+    if (options.maxFullToolResults !== undefined) {
+      params.max_full_tool_results = options.maxFullToolResults
+    }
+    if (options.debugMode !== undefined) {
+      params.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,15 +60,14 @@ export default class BotonicPluginAiAgents<
       const tools = this.buildTools(
         aiAgentArgs.activeTools?.map(tool => tool.name) || []
       )
-      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 agent = new AIAgentBuilder<TPlugins, TExtraData>(
+        aiAgentArgs.name,
+        aiAgentArgs.instructions,
+        tools,
+        request.session.user.contact_info || {},
+        aiAgentArgs.inputGuardrailRules || [],
+        aiAgentArgs.sourceIds || []
+      ).build()
 
       const messages = await this.getMessages(
         request,
@@ -94,12 +107,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 OpenAI, { AzureOpenAI } from 'openai'
+import { AzureOpenAI } from 'openai'
 
 import {
   AZURE_OPENAI_API_BASE,
@@ -11,37 +11,21 @@ import {
   AZURE_OPENAI_API_KEY,
   AZURE_OPENAI_API_VERSION,
   isProd,
-  OPENAI_API_KEY,
-  OPENAI_PROVIDER,
 } from './constants'
 
 export function setUpOpenAI(maxRetries?: number, timeout?: number) {
-  if (OPENAI_PROVIDER === 'azure') {
-    setAzureOpenAIClient(maxRetries, timeout)
-  } else {
-    setOpenAIClient(maxRetries, timeout)
-  }
+  setAzureOpenAIClient(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 || 16000, // 16 seconds
+    timeout: timeout || 8000, // 8 seconds
     maxRetries: maxRetries || 2,
     dangerouslyAllowBrowser: !isProd,
   })

package/src/runner.ts

@@ -1,4 +1,4 @@
-import { OutputMessage, ResolvedPlugins, ToolExecution } from '@botonic/core'
+import { ResolvedPlugins, ToolExecution } from '@botonic/core'
 import {
   InputGuardrailTripwireTriggered,
   Runner,
@@ -14,15 +14,6 @@ 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,
@@ -37,15 +28,15 @@ export class AIAgentRunner<
     messages: AgenticInputMessage[],
     context: Context<TPlugins, TExtraData>
   ): Promise<RunResult> {
+    console.log(
+      'Running agent with messages',
+      JSON.stringify(messages, null, 2)
+    )
     try {
       const runner = new Runner({
         modelSettings: { temperature: 0 },
       })
-      // 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 result = await runner.run(this.agent, messages, { context })
 
       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({
+export const retrieveKnowledge = tool<any, Context, any>({
   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,11 +12,10 @@ export const retrieveKnowledge = tool({
     query: z.string().describe('The query to search the knowledge base for'),
   }),
   execute: async (
-    input: { query: string },
+    { query }: { 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,7 +10,6 @@ import {
 import {
   Agent,
   AgentInputItem,
-  AgentOutputType,
   RunContext as OpenAIRunContext,
   Tool as OpenAITool,
 } from '@openai/agents'
@@ -65,7 +64,16 @@ export type Tool<
 export type AIAgent<
   TPlugins extends ResolvedPlugins = ResolvedPlugins,
   TExtraData = any,
-> = Agent<Context<TPlugins, TExtraData>, AgentOutputType<typeof OutputSchema>>
+> = Agent<Context<TPlugins, TExtraData>, 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,
@@ -74,6 +82,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