@minded-ai/mindedjs 1.0.103-beta-1 → 1.0.103-beta-4

package/docs/low-code-editor/nodes.md

@@ -322,6 +322,33 @@ nodes:
   prompt: 'Help the customer with anything they need'
 ```
 
+## Browser Task Nodes
+
+Browser task nodes allow your agent to interact with web pages using AI-powered automation.
+
+### Basic Browser Task
+
+```yaml
+- type: browserTask
+  name: search_products
+  displayName: Search Products
+  prompt: 'Go to amazon.com and search for wireless headphones under $100'
+```
+
+### Browser Task with Custom Model
+
+You can specify which AI model to use for browser automation:
+
+```yaml
+- type: browserTask
+  name: complex_task
+  displayName: Complex Web Task
+  prompt: 'Navigate to the support page and fill out the contact form'
+  model: 'gpt-4o'        # Options: gpt-4o (default), gpt-4-turbo, claude-3-opus, etc.
+```
+
+The browser task will execute the prompt using the browser-use CLI tool, which provides AI-powered browser automation capabilities.
+
 ## Next Steps
 
 * [**Edges**](edges.md) - Connect nodes with intelligent routing

package/docs/low-code-editor/tools.md

@@ -247,6 +247,38 @@ const paymentTool: Tool<typeof paymentSchema, Memory> = {
   },
 };
 
+## Flow Control with goto
+
+Tools can control the flow by returning a `goto` property in their state update. This allows tools to programmatically move the conversation to a specific node.
+
+### Basic goto Usage
+
+```ts
+const moveToAnotherRepresentativeTool: Tool<typeof schema, Memory> = {
+  name: 'moveToAnotherRepresentative',
+  description: 'Transfer the conversation to another representative or department',
+  input: schema,
+  execute: async ({ input, state }) => {
+    logger.info({
+      message: 'Moving conversation to another representative',
+      sessionId: state.sessionId,
+      department: input.department,
+      reason: input.reason,
+      priority: input.priority,
+    });
+
+    return {
+      state: {
+        goto: 'share-new-representative',
+        memory: {
+          orderId: 'share-new-representative',
+        },
+      },
+    };
+  },
+};
+```
+
 ## Best Practices
 
 1. **Clear Descriptions**: Write descriptions that help the LLM understand when to use the tool

package/docs/platform/parallel-llm.md

@@ -0,0 +1,242 @@
+# Parallel LLM Requests
+
+Parallel LLM requests can significantly reduce latency by sending multiple identical requests and using the fastest response. This feature can reduce response times by 30-50% in scenarios with variable network conditions.
+
+## Quick Start
+
+The easiest way to enable parallel requests is through your `minded.json` configuration:
+
+```json
+{
+  "flows": ["./src/flows"],
+  "tools": ["./src/tools"],
+  "agent": "./src/agent.ts",
+  "llm": {
+    "name": "MindedChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true
+    }
+  }
+}
+```
+
+Your agent will automatically use parallel requests for all LLM calls:
+
+```typescript
+import { Agent } from '@minded-ai/mindedjs';
+import memorySchema from './agentMemorySchema';
+import config from '../minded.json';
+import tools from './tools';
+
+const agent = new Agent({
+  memorySchema,
+  config, // Parallel configuration is automatically applied
+  tools,
+});
+```
+
+## Configuration Options
+
+### MindedChatOpenAI (Recommended)
+
+For agents running on the Minded platform, use `MindedChatOpenAI` with parallel configuration:
+
+```json
+{
+  "llm": {
+    "name": "MindedChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true,
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+### AzureChatOpenAI
+
+For Azure OpenAI deployments:
+
+```json
+{
+  "llm": {
+    "name": "AzureChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true,
+      "azureOpenAIApiVersion": "2024-02-01"
+    }
+  }
+}
+```
+
+Required environment variables:
+
+```env
+AZURE_OPENAI_API_KEY=your_azure_key
+AZURE_OPENAI_API_INSTANCE_NAME=your_instance_name
+AZURE_OPENAI_API_DEPLOYMENT_NAME=your_deployment_name
+```
+
+### ChatOpenAI
+
+For standard OpenAI API:
+
+```json
+{
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true,
+      "openAIApiKey": "${OPENAI_API_KEY}"
+    }
+  }
+}
+```
+
+## Configuration Parameters
+
+| Parameter             | Type    | Default | Description                                   |
+| --------------------- | ------- | ------- | --------------------------------------------- |
+| `numParallelRequests` | number  | 1       | Number of parallel requests (2-5 recommended) |
+| `logTimings`          | boolean | false   | Enable detailed timing logs                   |
+
+## Performance Notes
+
+- **Optimal Range**: 2-3 parallel requests usually provide the best latency/cost balance
+- **Cost Impact**: You pay for all parallel requests made
+- **Best Use Cases**: Variable network conditions, consistency requirements
+- **Latency Reduction**: Typically 30-50% faster response times
+
+## Monitoring Performance
+
+When `logTimings: true` is enabled, you'll see detailed performance logs:
+
+```
+[Model] Fastest request completed { requestTime: 1.234, numParallelRequests: 3 }
+[Model] Time saved using parallel requests {
+  fastestRequestTime: 1.234,
+  secondFastestRequestTime: 1.567,
+  allFinishTime: 2.345,
+  timeSaved: 1.111,
+  timeSavedFromSecond: 0.333
+}
+```
+
+## Advanced Usage
+
+### Dynamic Configuration
+
+You can adjust parallel requests based on environment:
+
+```json
+{
+  "llm": {
+    "name": "MindedChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": "${NODE_ENV === 'production' ? 3 : 1}",
+      "logTimings": "${NODE_ENV === 'development'}"
+    }
+  }
+}
+```
+
+### Manual Instantiation with createParallelWrapper
+
+For advanced use cases where you need direct control over the LLM instance, you can manually apply parallel wrapping:
+
+```typescript
+import { createParallelWrapper } from '@minded-ai/mindedjs';
+import { ChatOpenAI, AzureChatOpenAI } from '@langchain/openai';
+
+// Manual wrapping for ChatOpenAI
+const parallelOpenAI = createParallelWrapper(
+  new ChatOpenAI({
+    openAIApiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4o',
+    temperature: 0.7,
+  }),
+  {
+    numParallelRequests: 3,
+    logTimings: true,
+  },
+);
+
+// Manual wrapping for AzureChatOpenAI
+const parallelAzure = createParallelWrapper(
+  new AzureChatOpenAI({
+    azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,
+    azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_INSTANCE!,
+    azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_DEPLOYMENT!,
+    azureOpenAIApiVersion: '2024-02-01',
+  }),
+  {
+    numParallelRequests: 2,
+    logTimings: false,
+  },
+);
+
+// Use directly with Agent (bypassing configuration)
+const agent = new Agent({
+  memorySchema,
+  config: {
+    flows: ['./flows'],
+    tools: [],
+    llm: parallelOpenAI as any, // Direct LLM instance
+  },
+  tools: [],
+});
+```
+
+**Note**: The configuration-based approach is recommended for most use cases as it's simpler and more maintainable. Use manual instantiation only when you need specific control over LLM creation or are integrating with existing LangChain workflows.
+
+## How It Works
+
+### MindedChatOpenAI (Backend Processing)
+
+- Parallel requests are handled on the Minded platform backend
+- Multiple requests sent to Azure OpenAI from the backend
+- Fastest response returned to your agent
+- Optimal for production deployments
+
+### Other LLM Providers (Client-Side Processing)
+
+- Parallel requests handled in your application
+- Multiple requests sent directly to the LLM provider
+- Good for development and custom deployments
+
+## Best Practices
+
+1. **Start Small**: Begin with 2-3 parallel requests
+2. **Monitor Costs**: Each parallel request counts toward your usage
+3. **Enable Logging**: Use `logTimings: true` during development to measure improvements
+4. **Environment-Specific**: Use fewer parallel requests in development
+5. **Configuration Over Code**: Prefer `minded.json` configuration over manual instantiation
+
+## Troubleshooting
+
+### No Performance Improvement
+
+- Check network latency variability
+- Ensure `numParallelRequests > 1`
+- Verify timing logs are showing multiple requests
+
+### Increased Costs
+
+- Reduce `numParallelRequests`
+- Consider cost vs. latency trade-offs
+- Monitor usage patterns
+
+### Rate Limiting
+
+- Lower `numParallelRequests`
+- Implement backoff strategies
+- Contact provider about rate limits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "1.0.103-beta-1",
+  "version": "1.0.103-beta-4",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,7 @@
     "order-refund": "cd examples/orderRefundAgent && nodemon --watch '**/*.ts' --exec 'ts-node' orderRefundAgent.ts",
     "zendesk": "cd examples/zendesk && nodemon --watch '**/*.ts' --exec 'ts-node' zendeskAgent.ts",
     "example-voice": "cd examples/voice && nodemon --watch '**/*.ts' --exec 'ts-node' voiceAgent.ts",
+    "example-browser": "cd examples/browserUsingAgent && nodemon --watch '**/*.ts' --exec 'ts-node' browserUsingAgent.ts",
     "lint": "eslint .",
     "lintFix": "eslint --fix .",
     "generateApiDocs": "typedoc src --out docs/api-reference ./src"

package/src/agent.ts

@@ -304,9 +304,17 @@ export class Agent {
 
     // Add edge from start to first node if no triggers exist
     const hasTrigger = nodes.some((node) => node.type === NodeType.TRIGGER && node.triggerType !== TriggerType.MANUAL);
-    if (!hasTrigger && nodes.length > 0) {
-      this.startingNodeId = nodes[0].name;
-      graph.addEdge('__start__', nodes[0].name as any);
+    if (!hasTrigger) {
+      // Find the Main flow
+      const mainFlow = this.flows.find((flow) => flow.name === 'Main flow');
+      if (mainFlow && mainFlow.nodes.length > 0) {
+        this.startingNodeId = mainFlow.nodes[0].name;
+        graph.addEdge('__start__', mainFlow.nodes[0].name as any);
+      } else if (nodes.length > 0) {
+        // Fallback to first node if Main flow not found
+        this.startingNodeId = nodes[0].name;
+        graph.addEdge('__start__', nodes[0].name as any);
+      }
     } else {
       nodes.forEach((node) => {
         if (node.type === NodeType.TRIGGER && node.triggerType !== TriggerType.MANUAL) {
@@ -348,6 +356,7 @@ export class Agent {
       sessionId: state.sessionId || uuidv4(), // Preserve existing sessionId or generate new one
       sessionType: state.sessionType || SessionType.TEXT,
       overrideStartFromNodeId: null,
+      goto: null,
     };
 
     // Emit INIT event with the initial state
@@ -421,7 +430,7 @@ export class Agent {
       // Try to acquire lock atomically (unless bypassing session check)
       if (!bypassSessionCheck && !(await this.interruptSessionManager.lock(sessionId))) {
         // Could not acquire lock, session is being processed - enqueue the message
-        logger.info({ message: 'Enqueuing message', sessionId, triggerBody, triggerName, appName });
+        logger.info({ msg: 'Enqueuing message', sessionId, triggerBody, triggerName, appName });
         await this.interruptSessionManager.enqueueMessage(sessionId, {
           triggerBody,
           triggerName,
@@ -458,7 +467,7 @@ export class Agent {
           const handlerResult = results.find((r) => r !== undefined);
           if (handlerResult) {
             if (!handlerResult.isQualified) {
-              logger.info({ message: `Trigger ${triggerName} was disqualified` });
+              logger.info({ message: '[Trigger] Disqualified', triggerName, triggerBody, sessionId });
               await this.interruptSessionManager.release(sessionId);
               return;
             }
@@ -469,7 +478,7 @@ export class Agent {
         }
       }
 
-      logger.info({ message: 'Invoking trigger', triggerName, sessionId, triggerBody });
+      logger.info({ msg: '[Trigger] Received', triggerName, triggerBody, sessionId });
       const langraphConfig = this.getLangraphConfig(sessionId || uuidv4());
       const state = await this.compiledGraph.getState(langraphConfig);
       const suffixes = Object.values(internalNodesSuffix);
@@ -478,7 +487,10 @@ export class Agent {
           ? state.values.overrideStartFromNodeId
             ? state.values.overrideStartFromNodeId
             : state.next[0]
-          : this.startingNodeId!;
+          : this.startingNodeId;
+      if (!nodeToBeInvoked) {
+        throw new Error('No node to be invoked');
+      }
       nodeToBeInvoked = nodeToBeInvoked.replace(new RegExp(suffixes.join('|'), 'g'), '');
       const historyStep = this.createTriggerHistoryStep(
         state.values.history,
@@ -543,23 +555,22 @@ export class Agent {
           langraphConfig,
         );
       }
-
-      const nextMessage = await this.interruptSessionManager.dequeue(sessionId);
-      if (nextMessage) {
-        // Dequeue the first message and process it recursively
-        // Recursively process the next message with bypass flag
-        const invokeParams: AgentInvokeParams = {
-          triggerBody: nextMessage.triggerBody,
-          triggerName: nextMessage.triggerName,
-          sessionId: sessionId,
-          bypassSessionCheck: true,
-        };
-        if (nextMessage.appName) {
-          invokeParams.appName = nextMessage.appName;
-        }
-        logger.info({ message: 'Invoking next message in the queue', invokeParams });
-        return await this.invoke(invokeParams);
-      }
+      // const nextMessage = await this.interruptSessionManager.dequeue(sessionId);
+      // if (nextMessage) {
+      //   // Dequeue the first message and process it recursively
+      //   // Recursively process the next message with bypass flag
+      //   const invokeParams: AgentInvokeParams = {
+      //     triggerBody: nextMessage.triggerBody,
+      //     triggerName: nextMessage.triggerName,
+      //     sessionId: sessionId,
+      //     bypassSessionCheck: true,
+      //   };
+      //   if (nextMessage.appName) {
+      //     invokeParams.appName = nextMessage.appName;
+      //   }
+      //   logger.info({ msg: 'Invoking next message in the queue', invokeParams });
+      //   return await this.invoke(invokeParams);
+      // }
 
       // Release the session lock
       await this.interruptSessionManager.release(sessionId);
@@ -567,7 +578,7 @@ export class Agent {
       return res;
     } catch (error: any) {
       logger.error({
-        message: 'Invoke error',
+        msg: '[Trigger] Error',
         errorMessage: error.message,
         stack: error.stack,
         sessionId,
@@ -805,7 +816,7 @@ export class Agent {
     // Skip secret loading in local development
     const { runLocally } = getConfig();
     if (runLocally) {
-      logger.info({ message: 'Running locally - skipping secret loading' });
+      logger.debug({ msg: '[Agent] Secrets loaded from local .env file' });
       return {};
     }
     if (!mindedConnection.isConnected()) {
@@ -832,10 +843,10 @@ export class Agent {
       const secrets = response.secrets || {};
 
       // Load secrets into process.env
-      logger.debug(`Loading ${Object.keys(secrets).length} secrets into environment variables`);
       Object.entries(secrets).forEach(([key, value]) => {
         process.env[key] = value;
       });
+      logger.debug(`[Agent] Loaded ${Object.keys(secrets).length} secrets from platform`);
 
       // Cache the secrets for future requests
       this.secretsCache = secrets;
@@ -851,7 +862,7 @@ export class Agent {
   }
 
   private setupVoice(): void {
-    logger.info({ message: 'Setting up voice' });
+    logger.info('[Voice] Setting up voice');
     if (!mindedConnection.isConnected()) {
       throw new Error('Minded connection is required');
     }
@@ -874,7 +885,7 @@ export class Agent {
           voiceSession.sendAudio(audioMessage.audioData);
         } else {
           logger.trace({
-            message: 'Audio received; voice session not found for sessionId',
+            message: '[Voice] Audio received; voice session not found for sessionId',
             sessionId: audioMessage.sessionId,
             activeSessions: Array.from(this.voiceSessions.keys()),
           });
@@ -884,13 +895,13 @@ export class Agent {
       // Hangup / end session handler
       connection.on(mindedConnectionSocketMessageType.DASHBOARD_VOICE_SESSION_END, (message) => {
         const hangup = message as BaseVoiceMessage;
-        logger.debug({ message: 'Dashboard eneded voice session', sessionId: hangup.sessionId });
+        logger.debug({ msg: '[Voice] Dashboard eneded voice session', sessionId: hangup.sessionId });
         const voiceSession = this.voiceSessions.get(hangup.sessionId);
         if (voiceSession) {
           voiceSession.hangup();
         } else {
           logger.trace({
-            message: 'Session ended; voice session not found for sessionId',
+            message: '[Voice] Session ended; voice session not found for sessionId',
             sessionId: hangup.sessionId,
             activeSessions: this.voiceSessions.keys(),
           });
@@ -917,7 +928,8 @@ export class Agent {
       voiceId: voiceTrigger.voiceId,
     });
     await voiceSession.init();
-    logger.debug({ message: 'Voice session initialized', sessionId: params.sessionId });
+    logger.debug({ msg: '[Voice] Voice session initialized', sessionId: params.sessionId });
+
     this.voiceSessions.set(params.sessionId, voiceSession);
 
     // Emit voice session start event
@@ -945,7 +957,7 @@ export class Agent {
    To be used by the Lambda wrapper to restore checkpoints
   */
   public async restoreCheckpoint(sessionId: string, checkpointId: string): Promise<void> {
-    logger.info({ message: 'Restoring checkpoint', sessionId, checkpointId });
+    logger.info({ msg: '[Agent]Restoring checkpoint', sessionId, checkpointId });
     const langraphConfig = this.getLangraphConfig(sessionId, checkpointId);
     await this.compiledGraph.invoke(
       new Command({