@botonic/plugin-ai-agents 0.37.0 → 0.37.1

package/README.md

@@ -2,13 +2,155 @@
 
 ## env variables
 
-You need this env variables when deploy a bot that use this plugin
+- It is necessary to add the following variables to an `.env` file:
+  - `AZURE_OPENAI_API_KEY`
+  - `AZURE_OPENAI_API_BASE`
+  - `AZURE_OPENAI_API_DEPLOYMENT_NAME`
+  - `AZURE_OPENAI_API_VERSION`
+- Add these env variables to build using rspack, for target NODE and DEV.
 
-.env
+```ts
+...
+import { config } from 'dotenv'
+config()
+...
+  const plugins = [
+    new rspack.EnvironmentPlugin({
+      NODE_ENV: process.env.NODE_ENV,
+      HUBTYPE_API_URL: process.env.HUBTYPE_API_URL || HUBTYPE_DEFAULTS.API_URL,
+      BOTONIC_TARGET: BotonicTarget.NODE,
+      WEBCHAT_PUSHER_KEY:
+        process.env.WEBCHAT_PUSHER_KEY || HUBTYPE_DEFAULTS.WEBCHAT_PUSHER_KEY,
+      ENVIRONMENT: process.env.ENVIRONMENT,
+      AZURE_OPENAI_API_KEY: isNodeOrDev
+        ? process.env.AZURE_OPENAI_API_KEY
+        : undefined,
+      AZURE_OPENAI_API_DEPLOYMENT_NAME: isNodeOrDev
+        ? process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME
+        : undefined,
+      AZURE_OPENAI_API_VERSION: isNodeOrDev
+        ? process.env.AZURE_OPENAI_API_VERSION
+        : undefined,
+      AZURE_OPENAI_API_BASE: isNodeOrDev
+        ? process.env.AZURE_OPENAI_API_BASE
+        : undefined,
+    }),
+    new rspack.ProgressPlugin(),
+  ]
+```
+
+## Custom Tools
+
+- It is possible to add tools from the bot code. To do this:
+- Add the `zod` dependency.
+- Create and export the definition of the tools in a file, for example: `src/server/tools.ts`.
 
+```ts
+import { CustomTool } from '@botonic/plugin-ai-agents'
+import axios from 'axios'
+import z from 'zod'
+
+export const customTools: CustomTool[] = [
+  {
+    name: 'get_current_weather',
+    description: 'Get current weather for a city',
+    schema: z.object({
+      cityName: z.string(),
+    }),
+    func: async (input: { cityName: string }) => {
+      const baseURL = 'http://api.weatherapi.com/v1'
+      const response = await axios.get(`${baseURL}/forecast.json`, {
+        params: {
+          key: 'WEATHER_API_TOKEN',
+          q: input.cityName,
+        },
+      })
+      const data = response.data
+      console.log('get_current_weather', { data })
+      return data
+    },
+  },
+  ...
+]
 ```
-AZURE_OPENAI_API_KEY='FAKE_API_KEY' // pragma: allowlist secret
-AZURE_OPENAI_API_BASE='FAKE_API_URL_BASE'
-AZURE_OPENAI_API_DEPLOYMENT_NAME='gpt-4o-mini_p1'
-AZURE_OPENAI_API_VERSION='2024-12-01-preview'
+
+- Add these tools to:
+- Update the `BotonicPluginFlowBuilderOptions`, as we did with the knowledge base, and add the `customTools`.
+
+src/server/config.ts
+
+```ts
+import { PluginAiAgentOptions } from '@botonic/plugin-ai-agents'
+import { customTools } from './tools'
+
+...
+function getFlowBuilderConfig(
+  env: ENVIRONMENT
+): BotonicPluginFlowBuilderOptions<BotPlugins, UserData> {
+  return {
+...
+    getAiAgentResponse: async (
+      request: BotRequest,
+      aiAgentArgs: {
+        name: string
+        instructions: string
+      }
+    ) => {
+      const aiAgentPlugin = request.plugins.aiAgents
+      return await aiAgentPlugin.getInference(request, aiAgentArgs)
+    },
+...
+}
+
+function getAiAgentsConfig(): PluginAiAgentOptions {
+  return {
+    authToken: 'AUTH_TOKEN', // Used locally
+    customTools: customTools,
+  }
+}
+...
+
+interface Config {
+  // Use any for infer type for TPlugins and TExtraData
+  // to avoid type errors with circular dependencies
+  flowBuilder: BotonicPluginFlowBuilderOptions<any, any>
+  aiAgents: PluginAiAgentOptions
+  knowledgeBases: PluginKnowledgeBaseOptions
+}
+
+export const CONFIG: Record<ENVIRONMENT, Config> = {
+  [ENVIRONMENT.LOCAL]: {
+    flowBuilder: getFlowBuilderConfig(ENVIRONMENT.LOCAL),
+    aiAgents: getAiAgentsConfig(),
+    knowledgeBases: getKnowledgeBasesConfig(),
+  },
+  ...
+}
+```
+
+## Share customTools with flow builder frontend
+
+- Create new `src/bot-config.ts` file and add customTools. This file is used so that every time a bot is deployed, the Flow Builder frontend can know which tools are in the deployed bot and enable or disable tools for each AI Agent node.
+
+src/bot-config.ts
+
+```ts
+import { BotConfigJSON } from '@botonic/core'
+
+import { customTools } from './server/tools'
+
+const aiAgentTools =
+  customTools?.map(customTool => ({
+    name: customTool.name,
+    description: customTool.description,
+  })) || []
+
+/**
+ * This is the configuration is shared with flow-builder-frontend.
+ */
+export const botConfig: BotConfigJSON = {
+  tools: aiAgentTools,
+  payloads: [],
+  webviews: [],
+}
 ```

package/lib/cjs/types.d.ts

@@ -1,14 +1,15 @@
-import { Agent, AgentInputItem, RunContext, Tool as OpenAITool } from '@openai/agents';
+import { Agent, AgentInputItem, Tool as OpenAITool, RunContext as OpenAIRunContext } from '@openai/agents';
 import { ZodSchema } from 'zod';
 import { OutputMessage, OutputSchema } from './structured-output';
 export interface Context {
     authToken: string;
 }
+export type RunContext = OpenAIRunContext<Context>;
 export interface CustomTool {
     name: string;
     description: string;
     schema: ZodSchema;
-    func: (input?: any, runContext?: RunContext<Context>) => Promise<any>;
+    func: (input?: any, runContext?: RunContext) => Promise<any>;
 }
 export type Tool = OpenAITool<Context>;
 export type AIAgent = Agent<Context, typeof OutputSchema>;

package/lib/esm/types.d.ts

@@ -1,14 +1,15 @@
-import { Agent, AgentInputItem, RunContext, Tool as OpenAITool } from '@openai/agents';
+import { Agent, AgentInputItem, Tool as OpenAITool, RunContext as OpenAIRunContext } from '@openai/agents';
 import { ZodSchema } from 'zod';
 import { OutputMessage, OutputSchema } from './structured-output';
 export interface Context {
     authToken: string;
 }
+export type RunContext = OpenAIRunContext<Context>;
 export interface CustomTool {
     name: string;
     description: string;
     schema: ZodSchema;
-    func: (input?: any, runContext?: RunContext<Context>) => Promise<any>;
+    func: (input?: any, runContext?: RunContext) => Promise<any>;
 }
 export type Tool = OpenAITool<Context>;
 export type AIAgent = Agent<Context, typeof OutputSchema>;

package/package.json

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

package/src/types.ts

@@ -1,8 +1,8 @@
 import {
   Agent,
   AgentInputItem,
-  RunContext,
   Tool as OpenAITool,
+  RunContext as OpenAIRunContext,
 } from '@openai/agents'
 import { ZodSchema } from 'zod'
 
@@ -12,11 +12,13 @@ export interface Context {
   authToken: string
 }
 
+export type RunContext = OpenAIRunContext<Context>
+
 export interface CustomTool {
   name: string
   description: string
   schema: ZodSchema
-  func: (input?: any, runContext?: RunContext<Context>) => Promise<any>
+  func: (input?: any, runContext?: RunContext) => Promise<any>
 }
 
 export type Tool = OpenAITool<Context>